前华为 2012 实验室的人离职去写 AI Agent 教科书，把 88 个实验全部开源

上周有个读者在后台问我，说现在想系统学 AI Agent，到底该看什么。我给他列了一串资料，论文、博客、官方文档，越列越长，列到最后自己都觉得这事儿不太对劲。

说真的，AI Agent 这个领域有个很奇怪的现象。论文一天能冒出来几十篇，框架一周能火好几个，但真要找一本从上下文工程讲到多 Agent 协作、从评估方法讲到模型后训练的系统性教材，你会发现几乎没有。要么是某家公司的产品手册，要么是某个 KOL 的入门合集，碎片化严重。

然后我翻到了这个仓库，bojieli/ai-agent-book。前华为 2012 实验室的李博杰写的《深入理解 AI Agent，设计原理与工程实践》，整本书开源，配 88 个可跑的实验。5000 多 Star，Apache 2.0 协议，昨天还在 commit。

这本书真正有意思的地方不是「又有人开源了一本书」，而是它把一本技术书做成了一个可执行的工程项目。我花了一天时间把它从头到尾拆了一遍，越看越觉得这里面的工程思路值得单独拎出来讲。

一句话定位

这是一本围绕 Agent = LLM + 上下文 + 工具 这个核心公式展开的工程教材，10 章正文配 88 个按章节组织的实验项目，从强化学习对比 LLM 的样本效率，一直讲到语音狼人杀的多 Agent 信息隔离。

你想想看，这个公式本身不新鲜，市面上讲 Agent 的文章十篇有九篇会提。但这本书的差异在于，它把这个公式拆成了三个可独立工程化的支柱，然后给每个支柱都配了一整套能跑的实验。

• 模型这一层，第 7 章讲 SFT、RL、RLHF 三阶段后训练
• 上下文这一层，第 2、3 章讲 KV Cache 友好设计、上下文压缩、RAG
• 工具这一层，第 4、5 章讲 MCP 协议、Coding Agent、代码即工具

三章一组，把「公式」落成了「工程」。这种结构化的拆解，比那种「Agent 就是 LLM 调一堆工具」的笼统说法要有用得多。

全书的工程骨架

先看仓库的目录结构，这是理解整本书设计哲学的第一把钥匙。

ai-agent-book/
├── book/              # 中文原版正文 + PDF
│   ├── chapter1.md ~ chapter10.md
│   ├── introduction.md
│   ├── afterword.md
│   ├── gen_*_figs.py  # 配图全由脚本生成
│   ├── preamble.tex   # LaTeX 排版
│   └── build_pdf.sh   # 一键编译
├── book-en/           # 社区贡献的英文版
├── book-ta/           # 泰米尔语版
├── chapter1/ ~ chapter10/  # 配套实验代码
└── EXPERIMENT_TRIAGE.md    # 实验缺口处置计划（重点）

几个细节值得注意。

第一，所有配图都是代码生成的。book/gen_ch1_figs.py 到 gen_ch9_figs.py，每一章的图都由对应脚本画出来，存到 book/images/。这意味着配图不是用画图工具拖出来的死图，而是可复现、可改的代码产物。你如果觉得某张图画得不对，可以直接改脚本重新生成。这个细节看着小，但它是技术书「工程化」的一个标志。

第二，整本书用 pandoc + xelatex + ElegantBook 文档类编译，build_pdf.sh 一条命令出 PDF。中文、英文、泰米尔语三个版本共用一套编译流程。你想想看，这不是一个人在写书，这是一个人在维护一个文档工程项目。

第三，也是最关键的，88 个实验项目按章节组织，chapterN/项目名/ 的结构，和正文十章一一对应。这不是那种「书里提到的代码放在一个 repo 里」，而是每章的每个实验都有独立目录、独立 README、独立可运行入口。

核心公式怎么落到代码里

公式讲完了，看代码。这本书最硬核的地方，是它真的把「上下文」「工具」「模型」这三件事各自拆出了非平凡的实现。我挑三个有代表性的实验讲讲。

Coding Agent，17 个工具的纯 Python 实现

第 5 章的 chapter5/coding-agent/ 是一个生产级 Coding Agent，作者明确说要对标 Claude Code 这类工具。它有意思的地方在于全部工具用纯 Python 实现，不依赖命令行。

看 chapter5/coding-agent/tools/ 目录，你能看到 17 个工具的实现，bash_tool.py、edit_tool.py、grep_tool.py、glob_tool.py、multi_edit_tool.py、notebook_edit_tool.py、task_tool.py、todo_write_tool.py、web_fetch_tool.py、web_search_tool.py、write_tool.py 等等。

其中最值得讲的是 grep_tool.py。作者没用 ripgrep，而是用纯 Python 正则重写了一个完全兼容 ripgrep 功能的版本。README 里的解释是「特别适合 Mac 用户」，因为 Mac 默认没装 rg。这个设计决策背后其实是一个工程判断，工具链的依赖越少，部署门槛越低，可移植性越强。

agent.py 里的 CodingAgent 类支持 anthropic、openai、openrouter 三个 provider，流式响应，持久化 shell 会话，自动 Lint 检测。系统提示词里还有时间戳、工具调用计数、TODO 列表管理这些「状态栏元信息」。你如果用过 Claude Code，会对这套设计很熟悉，这本书是把它从黑盒里拆出来给你看。

异步 Agent，inbox 队列的三协程模型

第 4 章的 chapter4/async-agent/ 是另一个亮点，它实现了一个叫 Flux 的异步 Agent 框架。我直接看 runtime.py 的开头注释，作者自己把架构说得很清楚。

三个协程全部基于 asyncio 单线程协作。

• inbox 队列，所有进来的事件先入队，包括用户输入、打断信号、异步完成通知
• _dispatcher 协程，从 inbox 取事件，判定紧急度，分流到立即处理、排队、打断三路
• _worker 协程，从 work 队列取事件批次，追加到轨迹，跑一轮 LLM

最巧妙的设计是打断机制。每一轮 LLM 调用作为一个可取消的子任务 turn_task，用户喊「取消」时直接 cancel() 掉它，同时取消所有后台异步工具。这套设计回答了一个很实际的问题，Agent 跑到一半用户改主意了，怎么优雅地停下来。很多框架根本不考虑这个。

工具层面，run_terminal_command 是异步的，调用后立即返回一个 task_id 占位符，命令在后台跑。任务完成后，结果作为一条新的系统事件注入对话。这个设计把「长时间运行的工具」和「对话流」解耦了，Agent 不会被一个慢工具卡死。

自我进化，从工具使用者到工具创造者

第 8 章是这本书的精华之一。chapter8/self-evolving-tools/ 复现了 Alita 的「最小预定义，最大自我进化」思想。

Agent 启动时不预置任何领域工具，只有五个通用元工具，web_search、read_webpage、code_interpreter、create_tool、search_tools。遇到不会做的任务，它自己上网找开源库、读文档、在沙箱测试、把可行方案封装成新工具存入工具库。

这里有个很关键的设计，幻觉控制。作者在 README 里反复强调，所有数字与结论必须来自真实的搜索结果、文档或代码执行输出。create_tool 封装工具前要先过两道守卫，语法编译检查 + 用 test_args 真跑一次 run()，通过才注册入库。这个细节很重要，因为它直接回答了「Agent 自己造工具会不会造出个不能用的一堆」这个质疑。

第 8 章还有个对照实验，active-tool-discovery/。它对比「全量注入 120+ 工具 schema」和「主动按需发现」两种范式。后者只在 system 里保留少量基础工具加一个 discover_tools 元工具，用嵌入相似度从工具库检索 3-5 个最相关的专用工具。结论是既省 token 又避免模型在超长工具列表下错选、滥用通用工具。这个实验的价值在于，它用数据回答了「工具越多越好吗」这个常见误区。

评估和后训练，被多数教程跳过的两章

坦白讲，市面上的 Agent 教程有个共同问题，重构建轻评估。大家都在讲怎么搭 Agent，很少有人讲怎么量化 Agent 到底行不行。这本书的第 6 章专门解决这个问题。

第 6 章一口气覆盖了 Terminal-Bench、SWE-bench、GAIA、OSWorld、tau2-bench 这些主流评估基准。每个基准都有对应的 chapter6/ 目录，告诉你这个基准测什么、怎么跑、结果怎么读。

更有意思的是 chapter6/agent-cost-analysis/。它对一个典型的多轮 Agent 任务做全链路成本拆解，用自建的轻量 tracing 记录每次 LLM 调用的输入、输出、缓存 token、时延与成本，聚合出「哪一步最贵」，再用 A/B 对比量化 KV-cache 友好设计加上下文压缩带来的真实节省。这个实验直接回答了一个老板最爱问的问题，「这个 Agent 一次调用要花多少钱，能不能便宜点」。

第 7 章讲模型后训练，预训练、SFT、RL 三阶段全景。chapter7/AdaptThink/ 让推理模型学会根据问题难度自适应选择推理模式，在大幅降低推理成本（45-69%）的同时提升准确率。chapter7/retool/ 用多轮对话和代码沙箱提升数学推理能力，在 AIME 2024 上训练。这两个实验都不是玩具，是基于 DeepSeek-R1-Distill-Qwen 和 Qwen2.5-32B-Instruct 做的真实训练。

第 9 章和第 10 章是拓展篇。第 9 章把感知从文本扩展到语音、GUI 和物理世界，讲语音三范式（级联、端到端全模态、全双工）。第 10 章讲多 Agent 协作，其中 chapter10/book-translation/ 用管理者模式把长文档翻译拆给术语表、翻译、审校四个专职 Agent，Manager 只保存任务和文件索引，完整译文全部落盘，上下文基本恒定。这个设计直接解决了「长任务把 Agent 上下文撑爆」的经典问题。

作者自己列的实验缺口表

这本书最让我意外的，不是它的内容有多全，而是作者自己把「哪些实验还没补齐」公开列了出来。这个文件叫 EXPERIMENT_TRIAGE.md，在仓库根目录，副标题是「实验代码缺口·处置计划（SHIP 优先）」。

我摘几条给你看。

实验 7-14 RLVP，作者自己的论文，书里用了自己的数字，但仓库里零代码。处置计划标注的是「最大缺口，书用作者自己论文数字却零代码，须放出训练/评估」。工作量标的是 L(GPU)，最难的那档。

实验 3-13 结构化知识提取（司法），现状是 stub，处置 SHIP，工作量 L。CAIL2018 抽取管道加因子重要性模型加对话 Agent，这是个完整的大工程。

实验 10-8 语音狼人杀，处置 SHIP，工作量 L。法官加信息权限控制加实时语音多 Agent，也是个硬骨头。

整张表把所有实验分了三档。SHIP（约 28 个）需要在仓库内新建可运行的参考实现。KEEP-EXT（8 个）是训练类实验，核心代码在外部 fork，仓库内补薄壳（钉住上游 commit 加 run.sh/config 加结果表），不重写。ALREADY（2 组）是代码其实已存在于仓库某处，只需修正指向。

作者还贴心地给了 build order，分了五个 Batch。Batch 1 是多 Agent 自包含项目（无外部依赖，教学价值高），建议先做。Batch 5 是训练类，最后做。这种「我自己知道哪里没做完，而且我告诉你优先级」的诚实姿态，在开源项目里相当少见。

这就是我想说的这本书最珍贵的东西，诚实的工程自觉。大多数技术书只会吹自己覆盖了多少内容，不会主动告诉你哪些还没覆盖完。这本书反过来，把缺口表放根目录，接受读者的审视。

三种语言，八个贡献者

看几个数字。

仓库 5094 Star，479 Fork。贡献者只有 8 个，bus factor 相当集中，基本是李博杰一个人扛。这个数字背后有个现实，这本书的可持续性高度依赖作者本人，一旦作者停更，后续维护会是个问题。

语言版本方面，中文是原版，英文和泰米尔语都是社区贡献的翻译，由 @nsdevaraj 完成。最近一周的 commit 基本都在做英文版和泰米尔语版的打磨，比如「switch text/math fonts to TeX Gyre Pagella」「Fix glued-text defects in Tamil and English editions」「Fix over-compressed table columns in all three editions」。看 commit message 能感觉到，作者对排版质量的要求很高，连「文字粘连」和「表格列过度压缩」这种细节都在修。

issue 区有个有意思的细节。14 个 issue 里，大部分是读者跑实验时遇到的 bug 报告，比如 issue #1 到 #5 都是 load_dotenv 没加载、消息格式转换丢信息、迭代完没退出循环这类具体的代码 bug。这说明读者真的在跑这些实验，不是光 Star 收藏。issue #8 是个典型的读者提问，「请问文章中的思考题有对应的解答吗」，作者关闭时回复了。这种活跃度对一个开源教材项目来说算健康。

什么人该读，怎么读

我的建议是分三类人。

如果你是 Agent 方向的工程师，直接看第 2、4、5 章。第 2 章的上下文工程（KV Cache 友好设计、上下文压缩）和第 4 章的工具（MCP 协议、异步 Agent）是最能直接用上的。第 5 章的 Coding Agent 实现可以作为你设计自己 Agent 的参考骨架。

如果你是研究者或者想深入，重点看第 6、7 章。第 6 章的评估方法论和第 7 章的后训练实验，是市面上少有的系统化整理。特别是 agent-cost-analysis 和 AdaptThink 这两个实验，值得复现一遍。

如果你是决策者或者技术选型，看第 1 章和第 10 章。第 1 章建立整体认知框架，第 10 章讲多 Agent 协作的适用边界，告诉你什么时候该用多 Agent、什么时候单 Agent 就够。

读法上有个建议。这本书不要从头读到尾，那是折磨。先读第 1 章建立框架，然后挑你最关心的那一章，把对应目录下的实验亲手跑一遍。README 里明确标了三种类型，✅ 可独立运行、📖 复现指南（依赖外部仓库）、🚧 设计文档（代码还在完善）。先从 ✅ 的开始，别一上来就去碰 📖 的训练类实验。

一个可带走的方法论

拆完这本书，我最大的收获不是某个具体的技术点，而是一个关于「技术知识工程化」的方法论。

我把它叫做 「公式-支柱-实验」三层结构。

第一层是一个核心公式，比如这本书的 Agent = LLM + 上下文 + 工具。公式要足够简洁，一句话能说清，但又要足够有解释力，能覆盖这个领域的主要问题。

第二层是把公式拆成几个可独立工程化的支柱。这本书拆成模型、上下文、工具三个支柱，每个支柱对应几章正文。支柱之间要正交，不能互相覆盖。

第三层是每个支柱配一组可运行的实验。实验不是示意图，是真代码，能跑，能改，能复现。而且实验要和正文严格对应，读者读完一章就能找到对应的实验上手。

这套结构不只适用于写书。你如果要做内训材料、做开源项目的文档、做技术选型报告，都可以套。核心思想是，把抽象概念拆成可工程化的支柱，再给每个支柱配上可验证的实例。读者不是来听你讲道理的，是来拿能用的东西的。

李博杰这本书做的，其实就是把 AI Agent 这个听起来很玄的领域，用这套三层结构拆成了一组可执行的任务。读者拿走的不是「我懂了 Agent 是什么」，而是「我能跑通这 88 个实验」。

这两者的差距，就是一本好技术书和一篇好博客的差距。