# 按水平分级的阅读路线

> 这个项目现在有 60+ 份文档、30+ 个交互实验台、4 套从零构建教程。这一份是**学习地图**——不是目录，是告诉你"你现在在哪、下一步该往哪走、走到那之后应该能做什么"。
>
> **读者设定**：有基本编程概念（变量、函数、API、终端）但不需要有 Agent 开发经验。
>
> **怎么用**：先读"快速自测"找到自己的阶段，然后按推荐顺序推进。每个阶段读完后做验收检查——不是"我好像懂了"，是"我能做出来"。
>
> **和「官方课 / 论文」地图的关系**：这份路线排的是本站 **开源 Agent 源码分析**。若你还缺 LLM / Prompt / Agent 的官方课与论文底子，先看 [AI 学习路径完整清单](./AI学习路径完整清单.html)。

---

## 快速自测：你现在在哪

勾选你能做到的：

**阶段〇（完全零基础）**
- [ ] 我不知道 API 是什么
- [ ] 我没用过任何 AI 编程工具
- [ ] 我不知道终端（Terminal）怎么用
- → 如果勾了任何一项，从阶段〇开始

**阶段一（入门）**
- [ ] 我大概知道 AI Agent 是"能动手的 AI"
- [ ] 但我讲不清楚它从收到消息到执行工具的完整链路
- [ ] 我没读过任何 Agent 项目的源码
- → 从阶段一开始

**阶段二（进阶）**
- [ ] 我能画出 Agent 主循环的流程图
- [ ] 我知道 prompt cache 是什么以及为什么要优化它
- [ ] 但我没比较过不同项目的架构差异
- → 从阶段二开始

**阶段三（动手）**
- [ ] 我读过至少 2–3 份源码分析
- [ ] 我想自己造一个能用的 Agent
- [ ] 但我不确定从哪里开始写第一行代码
- → 从阶段三开始

**阶段四（深入）**
- [ ] 我造过至少一个能跑的 Agent
- [ ] 我想看懂 fork 差异、理解前沿工程实践
- → 从阶段四开始

---

## 阶段〇：打开大门（2–3 小时）

**目标**：建立对"AI 能帮人干什么"的直觉。这个阶段不需要写代码。

### 前置：装一个 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`（对比两张照片——这次改了哪几行）。理解这三件事就够了。

### 然后进入阶段一

---

## 阶段一：建立认知——Agent 到底是什么、怎么工作

**目标**：搞清楚一个 AI Agent 从收到用户消息到完成任务的完整链路。能跟别人讲清楚。

**预计时间**：6–8 小时

### 推荐阅读顺序

**第 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 怎么派。

### 概念关系图

```mermaid
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 是什么"

---

## 阶段二：打开视野——同一个问题，不同的答案

**目标**：理解 Agent 不是只有一种写法。同样的核心循环，不同的架构选择会导致完全不同的工程形态。开始在脑海中建立"选什么架构取决于要做什么产品"的判断框架。

**预计时间**：8–12 小时

### 推荐阅读顺序

**第 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 项目时，能先问自己"它的产品定位是什么？"再判断它的技术选择是否自洽

---

## 阶段三：动手构建——从零造一个能用的 Agent

**目标**：把阶段二的"知识"变成阶段三的"能力"。亲手写一个能跑、能干活、知道什么时候停的 Agent。

**预计时间**：每条路线 8–15 小时

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

| 路线 | 造什么 | 用什么语言 | 编程门槛 | 独特的收获 |
|---|---|---|---|---|
| **A** | AI 编程助手（MiniClaude） | TypeScript/Node.js | ★★☆ | 最接近你每天用的工具，每一步都有即时反馈 |
| **B** | 通用任务 Agent（Manus 式） | Python | ★★☆ | 跟着一个真实任务走——每撞一堵墙补一个零件，理解"Agent 为什么需要这个" |
| **C** | AI 同事（OpenWorker 式 · 无人值守） | Python | ★★★ | 最难但最有收获：接 Slack、定时跑、人不在时挂起等你 |
| **D** | AI 设计 Agent（Open Design 式 · 宿主） | TypeScript | ★★☆ | 最反直觉：你一行 Agent 主循环都不写——做的是"插座 + 剧本 + 闸门" |

### 怎么用这些教程

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

### 动手之前的心理准备

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

### 验收检查

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

---

## 阶段四：专线深潜——看懂前沿实践

**目标**：读懂 fork 差异、理解"宿主"形态、看懂非编程 Agent、学会画架构图。

**预计时间**：每项 2–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"）

---

## 给零基础的人：阶段〇前置补充

如果你在快速自测里勾了阶段〇：

1. **不需要先学编程语言**。阶段一的内容就是为了"不需要会写代码"设计的。读完之后你会自然地想学——那时候再学，因为你有了"为什么要学"的动力
2. **但你需要先理解三个概念**（见阶段〇的三概念解释）。如果你连"API 是什么"都不知道，阶段一的文档里会出现太多你不认识的名词
3. **装一个 AI 编程工具用几天**——不是为了学原理，是为了建立直觉。就像你先学会开车，再去学发动机原理

---

## 给有基础的人：快速定位

| 你缺什么 | 直接看 |
|---|---|
| 不熟悉某个具体项目 | 总目录 → 单项目分析卡 → 读"最独特设计"那章（通常在第 1 章末尾或最后一章） |
| 不确定权限该选哪条路线 | 《Agent工程模式目录》第三章 + 横向对比 §3.1"对决一" |
| 上下文压缩策略选不好 | 《Agent工程模式目录》第四章 + 横向对比 §2.5 + §3.2"对决二" |
| 想知道各家缓存怎么做的 | 《Agent工程模式目录》第一章 + 横向对比 §2.10 |
| 想看前沿实践（fork/宿主/仿真/Rust Agent） | 阶段四 |
| 想对比 Claude Code vs OpenCode vs Codex | 《Claude-Code-vs-OpenCode-vs-Codex-深度对比.md》 |

---

*如果你想在读完阶段四之后继续深入，参见《后续待剖析的开源项目推荐列表.md》。若还缺官方课 / 论文底子，参见 [AI 学习路径完整清单](./AI学习路径完整清单.html)。*