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
@@ -5,7 +5,7 @@ Code、Markdown/Obsidian、Git/GitHub等核心工具的使用方法。
\section{Vibe Coding的概念与工具}
\subsection{什么是Vibe Coding}
\subsection{\greenheading{什么是Vibe Coding}}
传统编程遵循``明确需求 → 设计算法 → 编写代码''的线性流程,而 Vibe Coding 则转变为``\textbf{模糊想法 → AI辅助 → 迭代完善}''。这是一种以AI为核心的编程新模式:开发者用自然语言描述意图,AI生成代码,再通过迭代对话逐步完善。对于编程经验较少的设计专业读者而言,这种模式大幅降低了技术门槛——不需要记住语法细节,只需要清楚地表达”想要什么”。
@@ -47,6 +47,8 @@ Vibe Coding 的基本流程是:\textbf{描述意图}→AI生成代码→运行
EPCC 的核心理念是\textbf{先理解、再规划、后动手、常存档}——这与传统的"边写边想"形成对比,特别适合设计专业读者在 AI 辅助下管理复杂项目。
值得强调的是,Commit 阶段并非简单的``保存'',而是\textbf{人工审核的检查点}。每一次 commit 都意味着开发者已经阅读、理解并确认了 AI 生成的代码——只有审核无误的内容才应当提交。因此,在 Vibe Coding 中不宜一次性让 AI 生成大量代码,而应将任务拆分为小步骤,每一步都以一次成功的 commit 为目标。从这个意义上说,Vibe Coding 的过程就是\textbf{不断 commit 的过程}:生成一小段代码 → 审核确认 → commit → 进入下一轮。这种``小步快跑''的节奏既保证了代码质量,也帮助开发者在每次 commit 中逐步积累对项目的理解。
\subsection{工具生态}
当前 AI 编程工具已形成多种产品形态,各有侧重(表\ref{tab:ai-tools})。