awesome-agentic-ai-zh 项目记忆解读：Agent 协作规范、模型选型标准与练习工程约定

教程文档AI Agent人工智能大模型【免费下载链接】awesome-agentic-ai-zhA trilingual (繁中 / English / 简中) learning roadmap for agentic AI: from LLM basics to multi-agent systems, with 240 curated resources and hands-on examples. 中文 AI agent 學習地圖。项目地址https://gitcode.com/gh_mirrors/aw/awesome-agentic-ai-zh点击查看免费下载本文以仓库根目录的 CLAUDE.md 为骨架系统拆解这个「AI Agent 学习路线图」仓库如何为 AI 协作 AgentClaude、Codex、Gemini 等沉淀一套可执行的工程契约从仓库定位、Ollama 与 Anthropic 的规范模型清单到双路径练习框架、文件约定、三语镜像与委托协作规则。读完本文你可以快速理解该仓库的贡献边界与质量标准也能把同样的「项目记忆」模式复用到自己的 Agent 驱动型开源项目中。一、CLAUDE.md 是什么面向协作 Agent 的「项目记忆」在 AI Agent 深度参与开源开发的今天仓库需要一个「先读文件」让任何进入仓库的 Agent 在触碰练习代码或模型推荐之前先理解全局约束。CLAUDE.md 正是这样一份「standing instructions」——它开篇就写明任何在本仓库工作的 AI AgentClaude、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 用一张表格固化了「何时收、何时推」的边界决策场景规则新增 stage 级练习文件夹允许但必须包含「路线图节点 双路径 SDK 演示 一行点睛结论」starter 以 70–150 行为宜starter 超过约 150 行推回若膨胀到章节级改为加 提示框指向 Hello-Agents 等深度资料给 README 加第 5 个 extension收益递减README 保持紧凑约 200 行以内额外深度放 提示框新增资源库/论文/工具/框架只在有明确教学角色、现行文档、已验证许可或官方来源、且在该章节有足够真实采用度时添加第三方 GitHub 仓库评审时须 ≥1,000 stars官方供应商文档、标准、模型卡与不可替代的权威来源豁免。策展本身是首要价值在本仓库新增章节级教程推回正确做法是「1 页摘要 简单说明性案例 指向权威来源」三语镜像优先级先冻结繁体中文再在同一 public-content PR 中发布匹配的英文与简体中文镜像部分镜像会阻塞发布2.2 仓库内的既有落地证据这条定位不是纸面口号。CLAUDE.md 记录查核日 2026-09-13Stage 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 本机模型清单与正确 tagCLAUDE.md 最容易被误用、也最值得深挖的部分是规范模型清单。它明确要求每个练习必须给出「本机免费路径 云端可选路径」且任何模型推荐列表都必须包含本机 LLM禁止只列云端模型。3.1 Ollama 规范模型表依 CLAUDE.md 记录查核日 2026-08-30Model tag使用场景备注gemma4:e4bStage 1 2纯对话、提示工程有效 4B 参数当时官方 Ollama tag 页显示 9.6 GB 下载。:e4b这个 tag 很关键——不是gemma3n:e4b不是gemma3:4b不是gemma4:latestgemma4:e2b更小的 Stage 12 备选官方 tag 页当时显示 7.2 GB 下载实际内存需求随运行时与硬件变化不能承诺每台 4 GB 机器都能跑qwen2.5:3bStage 3–6工具使用 / agent / ReAct1.9 GB可靠的工具调用支持OpenAI function-calling 格式当前 function-calling 练习的默认模型qwen3.5:4bStage 7辩论 / eval / 可观测性 / 流式 / 部署机制官方 tag 3.4 GB这些练习不依赖 function calling此行使不替代Stage 3–6 的工具调用默认值llama3.2:3bqwen2.5:3b的工具调用替代2.0 GB能力相近mistral-nemo:12b更高质量的本机兜底7.1 GB更接近云端质量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 记录值需以官方定价为准模型用途价格锚点CLAUDE.md 记录claude-fable-5-1最高等级 Claude1M 上下文、128K 最大输出适合长时间 agentic 工作$10 输入 / $50 输出$0.25 cache readclaude-mythos-5-1与 Fable 5.1 同模型仅限通过审核的网络安全与生命科学用户$10 输入 / $50 输出$0.25 cache readclaude-haiku-4-5最便宜的云端选项所有练习可用$1 输入 / $5 输出claude-sonnet-5-5新工作的生产默认改既有 tool-calling 示例前先读迁移指南$2 输入 / $10 输出claude-opus-5-5大多数工作负载的 Opus 级默认eval 仍不达标时改用 Fable 5.1$4 输入 / $20 输出$0.20 cache read3.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 rulesClaude 是文档定位中的规范/生产参考Ollama 是练习默认——因为成本学生不应在学习期间被 API 费用挡在门外每个练习必须同时交付两条路径Path AOllama主要可运行练习练习标题、结果、第一个动作保持可见仅当 Path A 是唯一即时动作且渲染内容短时用details markdown1 open否则用闭合的details markdown1折叠代码与排错内容Path BAnthropicdetails markdown1可选云端质量对比。每个练习必须显式写明预算——单次运行成本 整个 stage 总成本任何模型推荐列表都必须出现本机 LLM。4.1 落地示例Stage 3 练习 1 的完整双路径examples/stage-3/01-function-calling/README.md 是这条规则的完整标本Path A 命令本机API 费$0ollama pull qwen2.5:3b cd examples/stage-3/01-function-calling python -m pip install -r requirements.txt ollama serve python starter.pyPath B 命令需要 API keycd 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 完整演示了「模型只提出请求程序才真正执行」的最小回路定义工具 schemaget_weathercity必填、unit枚举为celsius、additionalProperties: Falserun_once()发出第一次请求要求恰好一个tool call多于一个直接抛错把 assistant 消息含 tool_calls追加进 messages调用execute_tool()校验并执行工具——它把模型产出的参数当作不可信输入处理把 tool result 以role: tooltool_call_id回填发起第二次请求得到最终回答。工具执行端的防护逻辑execute_tool尤其值得学习名称不在 allowlist 返回tool_not_allowedJSON 解析失败返回invalid_arguments字段集合必须严格等于{city, unit}多出的字段如admin同样被拒——这正是练习 README「你正在保護什麼」一节列出的四项防护Allowlist / 參數驗證 / 結果配對 / 錯誤標記。4.3 Anthropic 路径的差异点starter_anthropic.py 展示同一契约在 Anthropic SDK 下的形态工具声明用input_schema解析响应用tool_use块结果回填用type: tool_resulttool_use_id失败时额外加is_error: true让模型知道这不是正常结果——这是与 OpenAI 兼容格式的主要 API 差异。五、练习文件工程约定可运行、可测试、可自我验证CLAUDE.md 为每个练习文件夹定义了固定文件契约文件职责starter.pyOllama / OpenAI 兼容默认实现Path Astarter_anthropic.pyAnthropic SDK 版本Path Btest.py基于 mock 的测试OpenAI-compat 响应形状test_anthropic.py基于 mock 的测试content-block 形状requirements.txt同时钉住openai与anthropicREADME.md三语切换器 怎麼跑兩條 path 各 path 预算 walkthrough 常见坑两份约束细节也值得复制到其他仓库每个 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(encodingutf-8, errorsreplace)这保证在繁体中文 Windows 控制台cp950下运行练习不会因编码问题输出乱码——一个看似琐碎、却在教学中高频踩坑的细节。5.1 依赖的精确钉版examples/stage-3/01-function-calling/requirements.txt 展示了「钉版但不过度」的平衡openai3.5,4 anthropic1.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.pyLangGraph Ollama同仓库 Stage 4 练习 1模型仍默认qwen2.5:3b通过ChatOpenAI(base_urlhttp://localhost:11434/v1, api_keyollama)连接本机tool声明离线搜索工具用StateGraph组装agent → tools → agent的条件回路tool_node同样校验工具名与参数集合。文件头同样写明$0预算、python test.py验证方式结尾同样用 assert 自检——说明文件契约是跨 stage、跨框架的一致约定而不是某个练习的一次性写法。六、三语镜像规则先冻结繁体中文再出镜像仓库的定位是三语繁中 / English / 简中CLAUDE.md 为此定下翻译纪律zh-TW 为规范语言不带语言后缀的.mdzh-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陈述仓库维护状态组件状态要点公开课程Stage 0–8、Stage 7.5、A1–A3、五条角色路径、walkthrough、Capstone、Glossary 与核心资源页均有繁中/简中/英文三语路由读者路径已上架页面保留目标、加粗核心术语、必读、评分项目/资源、练习产出与完成检查setup、长代码、替代方案与排错可折叠示例模型支持的练习文件夹保留免费/本机 Ollama 路径、可选 Anthropic 路径、预算指引与离线行为测试除非练习刻意不依赖模型Stage 5章节含五个累积练习 5.1–5.8 参考入口tool-calling tutor 为可安装的 meta-exampleStage 6读者路径、进阶 RAG/Memory 页、隔离集合、chunk-overlap 防护、持久记忆与离线行为测试齐全不声称在线模型输出质量Stage 7主线顺序为 Eval → Observability → Approval/Recovery → DeployMulti-Agent 保持可选六个示例文件夹覆盖生产机制自动检查2026-09-13 时 58 个scripts/test_*.py模块收集 1,145 个测试该数字是带日期的观察值CI 与pytest --collect-only才是当前事实来源合并门Required / pr-gate是稳定必需检查绿色的机器 gate 不能替代维护者人工 review注意这里的表述纪律值得所有项目学习测试数量标注了「dated observation」并明确「CI 与 pytest --collect-only 才是当前事实来源」——这是仓库对自己「数据会过期」的诚实声明也解释了为什么相关测试脚本如 scripts/test_reader_ux.py、scripts/test_repository_freshness.py 等会被反复执行来刷新状态。九、给 Agent 与维护者的实践清单把 CLAUDE.md 的规则抽象为一套可复用的「项目记忆」模板核心是五件事先写定位再写规则用「我们是什么 / 我们不是什么 / 何时推回」三句话划定贡献边界配一张决策表钉死模型事实规范模型 tag、用途、价格锚点、日期与验证方式ollama list并记录曾经用错的 tag 防止复发统一工程契约双路径、文件命名、自我验证 assert、编码重配置、离线测试——每个练习都长一个样子机器可检查把人类约定 gate 化翻译纪律、链接校验、镜像同步、locale 检查全部脚本化见 scripts/ 与对应test_*.py让 CI 承担记忆诚实标注时效任何计数、价格、模型能力都带查核日期过期数据让位于当前 CI 与官方来源。对任何准备让 Claude、Codex 或 Gemini 深度参与维护的仓库而言CLAUDE.md 这份「项目记忆」本身就是一份值得对照的范本它不是写给人类看的冗长文档而是机器可消费、规则可执行、事实可验证的协作契约。赞分享教程文档AI Agent人工智能大模型【免费下载链接】awesome-agentic-ai-zhA trilingual (繁中 / English / 简中) learning roadmap for agentic AI: from LLM basics to multi-agent systems, with 240 curated resources and hands-on examples. 中文 AI agent 學習地圖。项目地址https://gitcode.com/gh_mirrors/aw/awesome-agentic-ai-zh点击查看免费下载相关推荐awesome-agentic-ai-zh 贡献指南策展标准、Entry Schema 与三语协作规范awesome agentic ai zh 贡献指南策展标准、Entry Schema 与三语协作规范 awesome agentic ai zh 是一份三语教程文档AI Agent人工智能大模型如何快速掌握MCP协议标准化进程Awesome-MCP-ZH最新规范解读如何快速掌握MCP协议标准化进程Awesome MCP ZH最新规范解读 MCPMessage Communication Protocol协议作为跨平台文档知识库自动化构建docker-alpine-java镜像generate_dockerfiles.sh脚本完全指南自动化构建docker alpine java镜像generate_dockerfiles.sh脚本完全指南 在容器化部署的时代高效构建轻量级Java环境至上一篇如何用ExplorerPatcher免费恢复Windows 10经典界面终极兼容性解决方案指南下一篇自然语言处理gh_mirrors/co/cosmos中的文本分析算法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考