从「Agent 是什么」
到「我能自己造」

前置：装一个 AI 编程工具

在你自己的电脑上装好 Claude Code 或 Codex CLI。花 1–2 天在日常任务中使用它——不是为了学原理，而是为了建立"我告诉电脑干什么，它就能干"的体验直觉。这个直觉是后面所有理论学习的基础。

你需要先理解的三个概念

不需要知道怎么实现，只需要知道它们是干什么的。每个概念 5 分钟：

1. API（程序之间打电话） 比喻：你去餐厅——你（客户端）看菜单、点菜（发送请求）、厨房（服务器）做好后端出来（返回响应）。你不需要知道厨房怎么做菜，你只需要知道怎么点。

在 Agent 的世界里：Agent 通过 API 把"用户说了什么 + 有什么工具可用 + 之前聊了什么"一起发给模型，模型通过 API 返回"我说了什么 + 我要用什么工具"。

2. 终端（Terminal）——跟电脑用文字对话 比喻：GUI（图形界面）是你用手指指点点告诉电脑干什么。Terminal 是你打字告诉电脑干什么。很多开发工具只活在 Terminal 里——因为打字比点鼠标快得多，而且可以写成脚本自动跑。

3. Git——代码的时光机 三件事：git commit（拍照——把当前状态存下来）、git log（看相册——看之前都拍过什么照）、git diff（对比两张照片——这次改了哪几行）。理解这三件事就够了。

然后进入阶段一

推荐阅读顺序

第 1 步：《Claude-Code-工作原理科普-深入版.md》第 1–7 章（2–3 小时）

为什么先读这个：这是全项目最核心的一份文档。它用一个具体的 Agent（Claude Code）把"启动→输入分流→上下文组装→主循环→工具系统"讲透了。先从一个项目吃透骨架，再去看别的——如果一上来就看十三家的对比，你会被差异淹没，不知道哪些是"所有 Agent 的共同骨架"、哪些是"这一个项目的特殊选择"。

读的时候注意：第 6 章（Agent 主循环）是最重要的一章。如果你只能读一章，读第 6 章。它讲的就是"模型说话→软件动手→把结果喂回模型→直到模型不再要工具"这个核心循环。

第 2 步：打开 Claude Code 学习站 v1（learn/claude-v1/）（1–2 小时）

为什么：第 1 步读的是文字，这一步是交互式的。三个 LAB 对应三个核心概念： - LAB 01 Prompt 旅程模拟器：看一个用户请求是怎么被一步步组装成发给模型的消息的 - LAB 02 Agent 主循环可视化：看模型→工具→模型这个循环是怎么转的 - LAB 03 权限闸门演示：看什么操作会被拦住、什么会被放行

不做这三个 LAB，你对 Agent 的理解停在"纸面上"。做了之后你会对"循环"有直观的感受。

第 3 步：《从零构建AI编程助手-开发全流程教程.md》第 1–8 章（1 小时）

为什么：前面两步是"看别人造的"，这一步是"看别人怎么造的"。从一个想法（"我想造一个 AI 编程助手"）出发，一步步从零到有。你不需要真的写代码（那是阶段三的事），但你需要理解造一个 Agent 需要哪些零件、零件之间怎么配合。

第 4 步：回来读《深入版》第 8–14 章（1–2 小时）

为什么：第 1 步读的是骨架，这一步读的是血肉——40+ 个工具怎么分类、60+ 个命令怎么设计、插件/技能/MCP 怎么接入、effort 档位和模型切换怎么实现、上下文压缩怎么做、子 Agent 怎么派。

概念关系图

flowchart TD
    U["用户输入"] --> R["输入分流：这是命令还是对话？"]
    R --> A["上下文组装：拼系统提示词+项目说明+历史"]
    A --> L["Agent 主循环 ★ 核心"]
    L --> M["模型 API"]
    M --> L
    L --> T["工具系统：读写文件/执行命令/搜索"]
    T --> P["权限闸门：这个操作安全吗？"]
    P --> L
    L --> O["输出：完成任务或需要用户决策"]

常见误区

❌ "Agent 就是 ChatGPT 加了个终端界面"——不对。ChatGPT 只能说话，Agent 能动手（改文件、跑命令、上网查）。这需要一整套工具系统、权限系统、错误处理。

❌ "Agent 主循环就是 while True"——技术上是的，但能跑和能跑好之间差了 100 个边界条件（用户中途插话怎么办？工具执行失败怎么办？上下文超了怎么办？模型陷入死循环怎么办？）。看懂了第 6 章你对这句话会有全新的理解。

❌ "权限系统就是弹个窗问 y/n"——这是最朴素的理解。真正的权限系统涉及：规则沉淀（上次允许的下次自动放）、命令 AST 解析（不能靠字符串匹配）、来源追踪（子 Agent 的结果不能当作用户的确认）、模式切换（Plan 模式根本不注册写工具）。

验收检查

阶段一完成后，你应该能：

• [ ] 画出 Agent 主循环的流程图（不需要画得很好看，但逻辑要对）
• [ ] 说出 "Agent" 和 "Chatbot" 的两个本质区别
• [ ] 解释"模型说要调 read_file('/foo')"之后，到"文件内容回喂给模型"之间发生了什么
• [ ] 说出至少三种权限路线的名字和核心理念
• [ ] 向一个不懂技术的朋友解释清楚"Agent 是什么"

推荐阅读顺序

第 1 步：《项目分析/横向对比与总结评价.md》第 1–2 章（1 小时）

为什么先读这个：把十三家项目摊在同一张桌子上——速览总表 + 十个维度逐项对比。全局印象先建立起来。这张表很长建议横屏看——每一列都是一个完整项目的"体检报告"。

读的时候注意： - 第二章每个维度（架构形态、主循环、工具系统、权限、压缩、记忆、子Agent、扩展、模型认证、缓存）都有一张对比表 + 一段"各家的想法"分析。表格回答"是什么"，分析回答"为什么" - 特别注意"架构形态"这张图——看懂单体/服务器/消息总线三种形态的差异，是理解后续一切的基础

第 2 步：挑 3 个架构差异最大的项目来读（每个 1 小时）

推荐组合（这三家代表了三种根本不同的产品定位）：

1. CodeWhale：Rust 单二进制 + 结构安全 + 错题本文化。代表"把安全做进编译器"的路线
2. nanobot：Python 轻量 + 显式状态机 + MessageBus + Dream 反思。代表"核心保持小、能力从边缘长"的路线
3. goose：一切皆 MCP + 引擎即服务器 + ACP 协议。代表"Agent 是本地基础设施"的路线

读的时候做一件事：拿一张纸，画三个圈——分别标上 CodeWhale、nanobot、goose。在每个项目里遇到"它解决某个问题的方式"时，在圈里写下来。比如： - 权限怎么做的？CodeWhale→结构安全（Plan 不注册写工具），nanobot→沙箱派（bwrap），goose→GooseMode 四模式 - 架构怎么做的？CodeWhale→双二进制消息管道，nanobot→MessageBus 双队列，goose→引擎即服务器

做完这张图，你对"同一个问题有多少种解法"会有直观的感受。

第 3 步：《Agent工程模式目录.md》全文（1–2 小时）

为什么：前两步看的是"这个项目做了什么"，这一步看的是"跨项目的模式"——同一个工程问题，不同项目给出了什么不同的答案。

读法：不一定要按顺序。先读你感兴趣的章节（比如你现在最头疼"缓存怎么搞"，直接翻到第一章）。每章的结构是一致的——先讲"这个问题到底难在哪"，再讲"各家怎么解"，最后讲"你该怎么做"。

第 4 步：架构图库（架构图库.html）（30–45 分钟）

为什么：读了很多文字之后，看图能帮你把抽象概念"空间化"。每张图上来先写清两件事——"回答什么问题"和"承重墙论点是什么"。点图可全屏放大。

常见误区

❌ "工具越多越好"——完全不对。hermes 有 74 个工具，goose 有 0 个内置工具。数量跟能力没有关系。关键在于：新增一个核心工具的边际成本是多少（每个工具的 schema 每次请求都要发）。

❌ "锁定一家模型就是技术保守"——不对。Claude Code 锁 Anthropic 是因为它的商业逻辑是"让你多用 Claude"，不是因为它做不了多 provider。锁定的红利是能做多 provider 架构做不了的深度优化（缓存计费头里应外合、签名 thinking、ToolSearch）。

❌ "开源的就是比闭源的更自由"——不完全对。开源有开源的税（适配税、最小公分母妥协），闭源有闭源的红利（第一方优化）。选什么取决于你最在乎什么。

验收检查

• [ ] 能说出三种权限路线（弹窗派/结构安全派/沙箱派）的区别和各自适合什么场景
• [ ] 能解释 hermes-agent 的"先落盘再动手"为什么是铁律
• [ ] 能说出 prompt cache 的五板斧（静态前置/易变外移/工具稳定/压缩慎重/遥测可见）
• [ ] 看到一个 Agent 项目时，能先问自己"它的产品定位是什么？"再判断它的技术选择是否自洽

四条构建路线——选最适合你的

怎么用这些教程

1. 不要跳步。教程是按"撞墙→补零件"的顺序设计的。如果你跳过"给大脑"直接看"给刹车"，你会发现刹车不知道装在哪
2. 每步做完都对照验收断言。每条路线附录里都有"做完第 N 步你应该看到 XXX"的断言。不要跳过——它们就是你的 CI
3. 遇到困惑翻回阶段二的对应分析。教程里的"为什么这么做"往往在那份分析里展开了

动手之前的心理准备

• 你写的第一版大概率跑不起来或者跑不好——这是正常的。教程里的"翻车点"列表就是为这个准备的
• 同一个功能（比如"权限闸门"），你可以在版本 1 用黑名单+弹窗（半小时），版本 2 加规则沉淀（半天），版本 3 加 provenance 降级（几天）。不要试图在版本 1 就把所有东西做完美
• 造 Agent 最大的陷阱不是"技术太难"，而是"过度设计"——在还没验证用户确实需要之前，花了两周做精密的上下文压缩。先用最简单的方案跑起来，再根据实际痛点迭代

验收检查

• [ ] 你的 Agent 能完成一个端到端的任务（不是 demo，是真实任务）
• [ ] 你的 Agent 在遇到危险操作时会拦住（不是事后发现执行了 rm -rf）
• [ ] 你能解释你代码里的 3 个关键决策——"为什么选这种做法而不是那种"

推荐阅读顺序

第 1 步：MiMo Code 第 20 章逐层差分 + LAB 05 归属核对台（2–3 小时）

这是全项目最有教育意义的一份分析——不是"MiMo 做了什么"，而是"在 opencode 的基础上，小米改了哪些、为什么改、哪些其实是上游已有的"。这份分析里有 15 条能力，逐条标注：🟢 首创 / 🟡 继承扩张 / 🔵 上游已有，并附两边的真实字节数。学会这套方法，以后你自己看任何 fork 都能用。

第 2 步：Open Design 解析站（2–3 小时）

全系列最反直觉的样本——一行主循环不写，驱动 25 个 CLI。重点看三个 LAB：适配器解剖台（理解"数据代替代码"）、提示词分层装配器（理解缓存分区）、反 AI 味 linter（理解"审美质量的程序化"）。

第 3 步：MiroFish 解析站（2–3 小时）

全系列唯一的非编程 Agent——群体仿真。重点不是学它的代码，是拓宽"Agent 能用来做什么"的想象力。注意它的 LAB 01 里有一个真实的静默数据破坏缺陷——中文类型名在 _to_pascal_case 函数里全部坍塌成 Unknown，全程不报错。这个缺陷是运行实验台时发现的，不是读代码读出来的。"跑起来"和"读代码"的差异就在这里。

第 4 步：OpenAI Codex 解析站（2–3 小时）

重点看 LAB 01（审批×沙箱正交表——理解两道正交防线怎么配合）、LAB 02（AGENTS.md 字节预算——理解"先到先得"的链式预算怎么饿死深层目录）、LAB 03（run_turn 停机协议——理解"为什么压缩后必须继续"）。

第 5 步：《架构图绘制规范》+ 两轮审阅勘误（1 小时）

学会画架构图——不是画目录树，是"先想清楚要回答什么问题、承重墙论点是什么、图上每个框每条线都为支撑那一个论点存在"。这套方法帮你自己把复杂系统想清楚。

验收检查

• [ ] 能在任何两个 fork/上下游项目之间，写出 10 条以上的差异化分析（不是"这个有那个没有"，是"这个改了什么、为什么改、改的代价是什么"）
• [ ] 能画出你读过的任何一个项目的架构图（不是目录树，是"回答一个具体问题"的图——比如"权限闸门是怎么挡住一条 shell 命令的"）
• [ ] 在讨论"选什么权限路线/架构形态/模型策略"时，有清晰的判断框架（不是"我觉得这个好"，而是"在你的场景下，选 X 因为 Y，但代价是 Z"）