docs: 调整附录与第二章排版,补充模块/包说明

- AGENTS.md: 新增 Codex 代理说明文件
- .gitignore: 屏蔽第三方工具目录 (.prism/, .claudeprism/, .agents/)
- preamble: 启用 xcolor dvipsnames 选项,新增 GREEN 颜色与 \greenheading 命令
- ch02-framework: 修正智能体段落引号格式
- ap01-programming: 补充 Python 模块与包的对比说明(esp_engine 示例)
- ap02-vibe-coding: 应用 \greenheading 标题样式,强调 commit 作为审核检查点
- 移除 2026_DesignAI.code-workspace(放弃 workspace 持久化方案)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-06-14 11:31:25 +08:00
parent 979b5128dc
commit c85bbd3c55
8 changed files with 174 additions and 14 deletions
@@ -494,6 +494,47 @@ train\_model(100, optimizer="SGD", lr=0.1)
导入模块
Python 通过\textbf{模块}module)和\textbf{}package)组织代码复用:一个 \texttt{.py} 文件就是一个模块,含有 \texttt{\_\_init\_\_.py} 的文件夹就是一个包,使用 \texttt{from 包.包.模块 import 函数/类} 的语法导入。
以本书生态安全格局项目中的 \texttt{esp\_engine/} 为例:
\begin{verbatim}
esp_engine/
├── data_manager.py ← 模块(1个文件,7个函数)
├── io/ ← 包(文件夹,2个模块)
│ ├── __init__.py
│ ├── raster_io.py ← 7个函数
│ └── vector_io.py ← 5个函数
├── steps/ ← 包(文件夹,10个模块)
│ ├── __init__.py
│ ├── reclassify.py
│ ├── cost_distance.py
│ └── ...8个文件)
└── workflows/ ← 包(文件夹,6个模块)
├── __init__.py
├── suitability.py
└── ...5个文件)
\end{verbatim}
何时用模块、何时用包?原则很简单——看体量(表\ref{tab:module-vs-package})。
\begin{table}[htbp]
\centering
\caption{模块与包的选择原则}
\label{tab:module-vs-package}
\begin{tabular}{@{} l l l @{}}
\toprule
\textbf{情况} & \textbf{做法} & \textbf{项目中的例子} \\
\midrule
功能集中,一个文件装得下 & 模块(单个 .py & data\_manager.py:7个函数全是数据预处理 \\[3pt]
功能分多个领域,各有独立逻辑 & 包(文件夹+子模块) & steps/:10个文件,每个是一种 GIS 操作 \\[3pt]
拿捏不准 & 先做模块,膨胀了再拆 &\\
\bottomrule
\end{tabular}
\end{table}
一句话:\textbf{模块是``够用就好的最小单位'',包是``需要分家时的组织方式''}
\emph{\# 导入标准库}
\textbf{import} os