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:
@@ -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})。
|
||||
|
||||
Reference in New Issue
Block a user