企业官网建设流程全解析

• 教程
• 文档
• AI Agent
• 人工智能
• 大模型

本文以仓库根目录的 CLAUDE.md 为骨架，系统拆解这个「AI Agent 学习路线图」仓库如何为 AI 协作 Agent（Claude、Codex、Gemini 等）沉淀一套可执行的工程契约：从仓库定位、Ollama 与 Anthropic 的规范模型清单，到双路径练习框架、文件约定、三语镜像与委托协作规则。读完本文，你可以快速理解该仓库的贡献边界与质量标准，也能把同样的「项目记忆」模式复用到自己的 Agent 驱动型开源项目中。

一、CLAUDE.md 是什么：面向协作 Agent 的「项目记忆」

在 AI Agent 深度参与开源开发的今天，仓库需要一个「先读文件」，让任何进入仓库的 Agent 在触碰练习代码或模型推荐之前，先理解全局约束。CLAUDE.md 正是这样一份「standing instructions」——它开篇就写明：任何在本仓库工作的 AI Agent（Claude、Codex、Gemini）都应先读本文件，再动手修改练习或模型推荐。

这份文件解决的是一类真实问题：多个 Agent、多个轮次协作同一仓库时，容易出现「新增了不符合定位的章节级教程」「用了过时的模型 tag」「只做了单一路径的练习」等系统性偏差。把规则固化进一个机器可读、可引用的记忆文件，比口头约定更可靠，也让人类维护者与 Agent 执行者共享同一份「契约」。

二、仓库定位：学习路线图 + 精炼资源 + 小型示例，不重写百科全书

CLAUDE.md 给仓库定下唯一角色：

learning roadmap + curated resources + simple illustrative cases（学习路线图 + 精选资源 + 简单说明性案例）

并明确「我们不是什么」：Datawhale Hello-Agents 是章级、中文繁体深度的教程（16 项生产能力、章节格式），本仓库不与它竞争，而是路由到它。这句「route → depth, not reinvent」（路由到深度，而非重新发明）是全仓库最重要的一句话。

2.1 贡献决策表：新增内容之前先对照

CLAUDE.md 用一张表格固化了「何时收、何时推」的边界：

2.2 仓库内的既有落地证据

这条定位不是纸面口号。CLAUDE.md 记录（查核日 2026-09-13）：Stage 3 / 4 / 6 / 7 的练习 README 都包含可见的学习资源与返回 Stage 的回路；主 README 与两个语言镜像都在 purpose 附近陈述路线图定位；而 tracks/cli/ 刻意保持 outline-only——因为 CLI 练习是 bash/markdown/config，不是 Python SDK，套不进「双路径」框架，这种「不强行套框架」本身就是正确判断。

在 README.md 中同样可以看到定位声明：「這裡的角色是學習路線圖 + 精選資源 + 可直接執行的小練習。需要完整章節時，我們會帶你去官方文件、Datawhale Hello-Agents 或對應的 Cookbook，不重寫另一套百科全書。」两处文档互为印证，说明这是一条被反复维护、Agent 必须遵守的硬边界。

三、模型选型规范：Ollama 本机模型清单与正确 tag

CLAUDE.md 最容易被误用、也最值得深挖的部分，是规范模型清单。它明确要求：每个练习必须给出「本机免费路径 + 云端可选路径」，且任何模型推荐列表都必须包含本机 LLM，禁止只列云端模型。

3.1 Ollama 规范模型表（依 CLAUDE.md 记录，查核日 2026-08-30）

3.2 为什么 tag 必须精确：一次真实的翻车记录

CLAUDE.md 特别记录了一组「曾经用错的 tag」，并说明已通过rename_gemma.py批量修复了 13 个文件：

• ❌gemma3:4b—— 旧命名，2026-05-12 被替换
• ❌gemma3n:e4b—— 错误家族，2026-05-12 被替换
• ✅gemma4:e4b—— 正确（依用户 Ollama 安装截图确认）

这条记录的价值在于：模型 tag 是 Agent 最容易「凭记忆编造」的内容。仓库给出的纪律是——不确定时，让用户运行ollama list核对，绝不猜测。这与 stages/01-llm-basics.md 中「找不到模型：先用ollama list，再以ollama pull gemma4:e4b安裝；不要自行猜測 tag」的指引完全一致。

3.3 Anthropic 规范模型与价格锚点

云端路径同样有规范清单（价格按每 1M tokens 计，为 CLAUDE.md 记录值，需以官方定价为准）：

3.4 模型规范在练习代码中的落地

打开 examples/stage-3/01-function-calling/starter.py，可以看到模型不是硬编码，而是通过环境变量注入：

MODEL = os.environ.get("MODEL", "qwen2.5:3b")

默认值正是规范表中的qwen2.5:3b，允许用户用MODEL=...覆盖。Anthropic 路径 starter_anthropic.py 则固定为具体版本号claude-haiku-4-5-20251001，练习 README 解释原因：「程式預設使用固定版本……避免模型 alias 日後移動時，教學結果悄悄改變」——这是对「模型 tag/版本必须钉死」这一 Agent 纪律的直接代码化。

四、双路径（Dual-Path）框架规则：每个练习必须两条路

CLAUDE.md 定义了三层不可违反的 framing rules：

1. Claude 是文档定位中的规范/生产参考；
2. Ollama 是练习默认——因为成本，学生不应在学习期间被 API 费用挡在门外；
3. 每个练习必须同时交付两条路径：
   • Path A（Ollama，主要可运行练习）：练习标题、结果、第一个动作保持可见；仅当 Path A 是唯一即时动作且渲染内容短时用<details markdown="1" open>，否则用闭合的<details markdown="1">折叠代码与排错内容；
   • Path B（Anthropic，<details markdown="1">，可选云端质量对比）。
4. 每个练习必须显式写明预算——单次运行成本 + 整个 stage 总成本；
5. 任何模型推荐列表都必须出现本机 LLM。

4.1 落地示例：Stage 3 练习 1 的完整双路径

examples/stage-3/01-function-calling/README.md 是这条规则的完整标本：

• Path A 命令（本机，API 费$0）：

ollama pull qwen2.5:3b cd examples/stage-3/01-function-calling python -m pip install -r requirements.txt ollama serve python starter.py

• Path B 命令（需要 API key）：

cd examples/stage-3/01-function-calling python -m pip install -r requirements.txt $env:ANTHROPIC_API_KEY = "你的-key" python starter_anthropic.py

• 预算显式化：README 要求正式运行前保留$0.05上限，并给出计算公式——輸入 token × $1 / 1,000,000 + 輸出 token × $5 / 1,000,000，同时提醒 Tool Use 还会加入系统提示 token、不要把没有 token 假设的小数写成保证价格（价格查核日2026-08-27）。
• 离线自检：python test.py与python test_anthropic.py使用假的模型响应，不连 Ollama、不调用 Anthropic API，应看到两次all pass。

4.2 Path A 的核心实现：一个最小工具调用回路

starter.py 完整演示了「模型只提出请求，程序才真正执行」的最小回路：

1. 定义工具 schema（get_weather，city必填、unit枚举为celsius、additionalProperties: False）；
2. run_once()发出第一次请求，要求恰好一个tool call（多于一个直接抛错）；
3. 把 assistant 消息（含 tool_calls）追加进 messages；
4. 调用execute_tool()校验并执行工具——它把模型产出的参数当作不可信输入处理；
5. 把 tool result 以role: "tool"+tool_call_id回填；
6. 发起第二次请求，得到最终回答。

工具执行端的防护逻辑（execute_tool）尤其值得学习：名称不在 allowlist 返回tool_not_allowed；JSON 解析失败返回invalid_arguments；字段集合必须严格等于{"city", "unit"}，多出的字段（如admin）同样被拒——这正是练习 README「你正在保護什麼」一节列出的四项防护（Allowlist / 參數驗證 / 結果配對 / 錯誤標記）。

4.3 Anthropic 路径的差异点

starter_anthropic.py 展示同一契约在 Anthropic SDK 下的形态：工具声明用input_schema；解析响应用tool_use块；结果回填用type: "tool_result"+tool_use_id；失败时额外加is_error: true让模型知道这不是正常结果——这是与 OpenAI 兼容格式的主要 API 差异。

五、练习文件工程约定：可运行、可测试、可自我验证

CLAUDE.md 为每个练习文件夹定义了固定文件契约：

两份约束细节也值得复制到其他仓库：

• 每个 starter 以# === 自我驗證 ===块结尾，内含 2+ 个assert语句。例如starter.py结尾断言工具名、tool_result["ok"]、消息里存在role == "tool"的回填记录；starter_anthropic.py则断言tool_use_id存在。
• 每个 Python 文件头部做 Windows cp950 UTF-8 重配置：

import sys if hasattr(sys.stdout, "reconfigure"): sys.stdout.reconfigure(encoding="utf-8", errors="replace")

这保证在繁体中文 Windows 控制台（cp950）下运行练习不会因编码问题输出乱码——一个看似琐碎、却在教学中高频踩坑的细节。

5.1 依赖的精确钉版

examples/stage-3/01-function-calling/requirements.txt 展示了「钉版但不过度」的平衡：

openai>=3.5,<4 anthropic>=1.1,<2 # Only starter_anthropic.py needs this package.

两个 SDK 同时出现在一个 requirements 里，保证双路径都能安装；范围约束（而非精确 pin）兼顾兼容与演进。

5.2 离线测试如何验证「防护」而非「结果」

examples/stage-3/01-function-calling/test.py 用MagicMock与SimpleNamespace伪造模型响应，四个测试分别覆盖：合法调用完成完整往返（并校验回填的tool_call_id）、坏 JSON 永不执行工具、多余/错误字段被拒、未知工具名被拒。这套「不花钱、不联网、可回归」的测试设计，是练习教学质量的关键保障——学员在本地就能确认自己的实现确实在执行防护逻辑。

5.3 从单一调用到图工作流：约定的进阶形态

同一套工程约定在更复杂的练习中延续。例如 examples/stage-4/01-same-agent-two-frameworks/starter.py（LangGraph + Ollama，同仓库 Stage 4 练习 1）：模型仍默认qwen2.5:3b，通过ChatOpenAI(base_url="http://localhost:11434/v1", api_key="ollama")连接本机；@tool声明离线搜索工具；用StateGraph组装agent → tools → agent的条件回路；tool_node同样校验工具名与参数集合。文件头同样写明$0预算、python test.py验证方式，结尾同样用 assert 自检——说明文件契约是跨 stage、跨框架的一致约定，而不是某个练习的一次性写法。

六、三语镜像规则：先冻结繁体中文，再出镜像

仓库的定位是三语（繁中 / English / 简中），CLAUDE.md 为此定下翻译纪律：

• zh-TW 为规范语言（不带语言后缀的.md），zh-Hans 与 en 为镜像；
• 翻译前先冻结繁体中文的含义——有边界的翻译 Agent 只有在文件范围、URL、数字、标题与安全边界全部确定之后，才可以产出 en + zh-Hans；
• 机械转换只是第一遍；必须跑 Hans、mirror、anchor、locale-link 四道 gate，再做人类可读的语义对比。

从仓库结构可以印证这条规则的执行：stages/、examples/、branches/、tracks/、resources/下的文档几乎都是.md（繁中规范）+.en.md+.zh-Hans.md三件套，且每个练习 README 顶部都有三语切换器（如 examples/stage-3/01-function-calling/README.md 开头的繁中/简中/English 链接）。仓库 scripts/ 下还配套了check-hans-chars.py、sync-language-switchers.py等脚本，以及test_locale_links.py、test_zh_hans_localize.py等测试，将「三语一致性」从人工约定升级为机器 gate。

七、Codex 委托协作规则：主 Agent 与执行 Agent 的边界

对于多人/多 Agent 协作，CLAUDE.md 定义了委托模式：

• 主 Agent 拥有范围、架构、治理、最终集成、Git 与用户沟通；
• 被委托的执行者获得有边界的文件所有权、验收命令、返回契约与停止条件，不得回退并发工作；
• 由独立 reviewer 阅读最终稳定暂存区的 diff；任何后续编辑都会使该 review 指纹失效；
• Agent 边界不构成提交边界——只暂存明确的路径、跑完必需的 gate，提交被验收的整体结果。

这套规则解决的是多 Agent 并行时的典型事故：执行者越界改文件、review 了又改导致审查失明、按 Agent 而非按功能提交导致半成品入库。

八、课程契约与自动检查：可观测的维护状态

CLAUDE.md 末尾用一张「current curriculum contract」表（查核日 2026-09-13）陈述仓库维护状态：

注意这里的表述纪律值得所有项目学习：测试数量标注了「dated observation」，并明确「CI 与 pytest --collect-only 才是当前事实来源」——这是仓库对自己「数据会过期」的诚实声明，也解释了为什么相关测试脚本（如 scripts/test_reader_ux.py、scripts/test_repository_freshness.py 等）会被反复执行来刷新状态。

九、给 Agent 与维护者的实践清单

把 CLAUDE.md 的规则抽象为一套可复用的「项目记忆」模板，核心是五件事：

1. 先写定位，再写规则：用「我们是什么 / 我们不是什么 / 何时推回」三句话划定贡献边界，配一张决策表；
2. 钉死模型事实：规范模型 tag、用途、价格锚点、日期与验证方式（ollama list），并记录曾经用错的 tag 防止复发；
3. 统一工程契约：双路径、文件命名、自我验证 assert、编码重配置、离线测试——每个练习都长一个样子，机器可检查；
4. 把人类约定 gate 化：翻译纪律、链接校验、镜像同步、locale 检查全部脚本化（见 scripts/ 与对应test_*.py），让 CI 承担记忆；
5. 诚实标注时效：任何计数、价格、模型能力都带查核日期，过期数据让位于当前 CI 与官方来源。

对任何准备让 Claude、Codex 或 Gemini 深度参与维护的仓库而言，CLAUDE.md 这份「项目记忆」本身就是一份值得对照的范本：它不是写给人类看的冗长文档，而是机器可消费、规则可执行、事实可验证的协作契约。

• 教程
• 文档
• AI Agent
• 人工智能
• 大模型