GitHub 趋势 · 第 61 期

45,943 star 的《深入理解 AI Agent》：正文是 Markdown 源码，PDF 是构建产物

#GitHub趋势#AIAgent#开源书籍

先说判断：这不是一个软件项目，是一本书。但它发布的方式完全是软件工程的——正文是 Markdown 源文件，PDF 与 EPUB 是构建产物，依赖被一份 1.25 MB 的锁文件钉死，109 个配套实验按章拆成十个 extra。

对想系统学 Agent 工程的中文读者，这是目前最值得 clone 的一份材料；但如果你想要的是装个库就能用的东西，它给不了。

想系统学 Agent，缺的从来不是结论

你手上通常是三类东西：零散的博客、几篇被转烂的综述、一堆跑不起来的 demo。真正的缺口是一份从原理讲到工程、并且把实验怎么跑起来也交代清楚的材料——大部分教程到该运行的时候就停住了。

这个仓库补的正是这一块：不给结论清单，给 10 章正文加 109 个能自己跑的实验。

它是什么

仓库 bojieli/ai-agent-book 是一本中文技术书的开源主仓库，作者李博杰（GitHub 账号 bojieli，个人账号）。书名《深入理解 AI Agent：设计原理与工程实践》，全书围绕一个公式展开：Agent = LLM + 上下文 + 工具。

GitHub API 实测：45,943 star、5,138 fork、未关闭 issue 22 条、watcher 168 个。Trending 页同期快照是 45,951 star，比 API 多 8 个——小项目上这种偏差很常见，两个数我都列出来。它这轮出现在 Python 日榜，单日 +301。

仓库的顶层结构长这样（按 contents 接口实测整理）：

ai-agent-book/
├── book/                    中文正文源码：introduction.md、chapter1~10.md、afterword.md
├── book-en/ book-es/ book-ar/ book-he/ book-hu/ book-id/
│   book-ja/ book-ko/ book-ptbr/ book-ru/ book-ta/ book-tr/
│   book-vi/ book-zhtw/      14 个翻译书稿目录
├── chapter1/ ~ chapter10/   各章配套实验（每章 README 是权威实验清单）
├── agentbook/               跨实验共用的 provider 与依赖管线
├── docs/                    实验台账、目录约定、站点 i18n 说明
├── cursor-chats/            写作过程的对话记录
├── extras/ scripts/ slides/ tests/ assets/ overrides/
├── pyproject.toml           ch1 ~ ch10 共十个 extra
├── uv.lock                  1,312,108 字节
├── mkdocs.yml               在线版配置（15,091 字节）
└── README.md                40,363 字节（另有 10 个翻译版）

十章，109 个实验

章	主题	实验
1	AI Agent 入门	4
2	上下文工程	10
3	用户记忆和知识库	12
4	工具	5
5	Coding Agent 与通用 Agent	16
6	交互：观察与动作空间的扩展	14
7	Agent 的评估	14
8	模型后训练	19
9	Agent 的持续进化	9
10	多 Agent 协作	6

这一列加起来是 4+10+12+5+16+14+14+19+9+6 = 109，和 README 头条写的「109 个配套实验」对得上。第六章是 2.0 版重组出来的新章——把原来第四章的异步交互和第九章的多模态 Agent 合并为「交互：观察与动作空间的扩展」，后面的评估、后训练、持续进化各往后挪了一章。

章的主题密度也不平均：第 5 章讲 Coding Agent 与通用 Agent，把代码称作能创造新工具的工具；第 8 章讲模型后训练，把预训练 / SFT / RL 三阶段拆开讲，实验数最多（19 个）；第 7 章把评估做成可比较信号，第 9 章讲怎么从运行轨迹里拿学习信号。

书稿是源码：四件证据

▪正文就是源文件。book/ 下 10 个 chapterN.md 合计 993,015 字节；最长的是第八章 136,660 字节，最短的是第九章 59,225 字节。再加引言 19,439 与后记 10,495，正文源码合计 1,022,949 字节。
▪成品是编译出来的。中文 PDF 靠 book/build_pdf.sh 生成，前置要装 pandoc、xelatex 和 ElegantBook 文档类；配图以 SVG 存在 book/images/，排版控制在 book/preamble.tex，交叉引用与实验框交给三个 Lua 过滤器（crossref.lua 2,940 字节 / experiment_box.lua 1,677 字节 / epub_external_links.lua 1,467 字节）。EPUB 走另一条链路，有独立的构建脚本与样式表。
▪依赖是钉死的。仓库根目录躺着一份 uv.lock，1,312,108 字节；109 个实验按章拆成 ch1 到 ch10 十个 extra，装哪章装哪个。对一份教学材料来说，这一步决定了半年后别人 clone 下来还能不能跑出同样的结果。
▪在线版是同一次构建的全部语言。官方在 docs/STATIC_SITE_I18N.md 里写明了一个限制：Material for MkDocs 一次构建只接受一个 theme.language，所以页面外壳统一用中文生成，再在浏览器里按语言切换。导航词条来自 extras/site-nav-i18n.json，脚本 scripts/site_i18n.py 负责校验并在构建时生成 site-i18n.generated.js——文件里明确写着 never edit that generated file。审计不过就拒绝构建，其中一条失败条件很实在：非 CJK 语言的自定义目录里残留中文文本。

怎么把它跑起来

README 给的主路径是 uv 加锁安装，逐字抄在下面（把 ch1 换成 ch2 ~ ch10 即可）：

# 推荐：使用提交到仓库的 uv.lock，获得可复现的章节环境
uv sync --locked --extra ch1

# 未安装 uv 时：使用 pip 从 pyproject.toml 重新解析
python -m pip install -e ".[ch1]"

装完在仓库根目录跑实验：

uv run python chapter1/context/main.py

想自己编译 PDF，则需要先装 pandoc、xelatex、ElegantBook 文档类与相关字体，然后：

cd book && bash build_pdf.sh

跑测试的路径在 docs/EXPERIMENT_CONVENTIONS.md 里，顺手把 dev extra 一起装上：

uv sync --locked --python 3.12 --extra chN --extra dev
python -m pytest tests

写作过程也在仓库里

上面都是它做得好的部分。接下来是它真正少见的地方：仓库根目录有一个 cursor-chats/，里面是 Cursor 会话的导出文件，文件名就是时间戳加上当时给 AI 的指令全文。我抓到的清单里就有 54 个（接口返回被截断，实际不止），最小的 868 字节，最大的 98,584 字节。

挑三条文件名念一下，你会明白这个目录的分量：

▪20250517_193545_帮我仔细审阅一下这本书的标题和内容，标题有什么改进建议？内容呢？.md
▪20250517_235702_写一段本书简介，突出书的亮点.md
▪20250912_215724_文章中现在存在大量重复。这是一本学术著作，因此需要去除所有的重复，保证结构严谨、逻辑清晰。.md

这三条摆在一起，一本书的构思、宣传语、返工去重三个阶段就都在里面了。目录里还有让 AI 读 arXiv 论文做对比、比对 vLLM 与 Ollama 的 prompt 模板、以及在终端里跑 python main.py 的会话记录。

README 里没有介绍它，docs/ 下也没有。它更像是 Cursor 的会话导出被一起提交了进来——我不替作者解释动机。但抛开动机，这个目录本身就是一份罕见的一手材料：一本书和 AI 往返几十轮的痕迹，没有被清理掉。

我的判断

适合谁：想系统学 Agent 工程、并且愿意动手跑实验的人；要给团队或课程找一份中文教材的人（Apache-2.0 允许商用与改写，这一点后面还要说一句）；习惯先看懂机制再去跑代码的人。

不适合谁：想要一个能直接装进项目里的框架的人——这是书加实验集合，不是软件产品；只想找一份速查清单的人；磁盘紧张的人，理由在文末最后一个数字。

上手前有四件事值得先知道：

▪章节 extra 是排他同步的。README 的原话是「uv sync 每次都会精确同步当前选择」——装第二章时，第一章的依赖会被移出环境。想同时保留必须合并成一条命令，README 给的写法是 uv sync --locked --extra ch2 --extra vllm。
▪clone 不等于能跑。第 6、7、8、10 章的部分实验依赖外部仓库，README 明说那 22 个仓库加 1 个辅助 cookbook「不作为本书源码内置依赖（出于体积与版权）」，要自己按附录脚本 clone 到指定目录。脚本也不是普通 clone：每一行都用 checkout --detach 钉到固定 commit，再用 test 校验 HEAD，例如 git -C chapter6/browser-use checkout --detach ec9277c5001f2cb78ee419c927775a3cfc227ff8。浏览器、CUDA、FFmpeg、Ollama、Playwright 这些系统依赖还得另外装。
▪「克隆或安装源码不代表实验完成」——这是 README 的原话。真状态在 docs/EXPERIMENT_STATUS.md（21,279 字节）：那份台账列了 43 行，其中 32 行 Complete、11 行 Incomplete。未完成的原因基本不是代码——Google Calendar 与 Notion 缺授权凭证、Unipile 探测返回 401、Gemini Robotics-ER 认证失败、没有本地 ManiSkill 环境与 PPO checkpoint 等等。台账还定义了一个状态叫 Reader exercise，但整张表里一行都没用上。
▪版本口径要注意。README 说「项目统一支持 Python 3.11–3.13」，同一段又写「第 8 章部分内置第三方组件需要 Python 3.12+」；而约定文件里的安装示例统一用 --python 3.12。要跑第 8 章，别停在 3.11。

还有两个小坑，都属于看着不起眼、遇上了很烦的那一类。一是多语言入口基本是墓碑：根目录 10 个翻译版 README 里有 8 个只有 95 到 201 字节——README.en.md 实测全文是 This file has moved 加一行新路径，README.ja.md 是「このファイルは移動しました」加一行新路径；docs/ 下还有一组同构文件，LEARNING.md 连同 7 个语言版本合计 1,158 字节。真正的翻译正文在各 book-语言/ 目录和每章 chapterN/README.语言.md（2,369 到 7,249 字节）里。二是唯一一个 Release 的 tag 名就叫 latest，标注是 rolling，prerelease 为 true，发布于 2026-07-21，挂着 30 个附件（15 种语言 × PDF 与 EPUB，合计约 216 MB，最大的是韩语 PDF 12,784,257 字节）。README 说的「固定版本见 Releases」，实际是名字固定、内容滚动。

最后一个数字：仓库本身 794,108 KB，也就是约 775 MB——比它一次发布出来的全部成品（约 216 MB）还大三倍多。clone 之前心里有个数。

仓库：github.com/bojieli/ai-agent-book（bojieli/ai-agent-book）

star：API 实测 45,943 · Trending 页快照 45,951（2026-09-12，Python 日榜单日 +301）· fork 5,138 · 未关闭 issue 22 · watcher 168

版本：默认分支 main · 仓库创建于 2025-09-09 · 最近推送 2026-09-12 · Releases 仅 1 个（tag latest，prerelease，2026-07-21）

选题依据：全语言日 / 周 / 月三榜剔除历史已写项目后无新面孔，改用分语言日榜；该仓库不在历史已写清单里，也不在往期线索池中。

数据来源：GitHub Trending 官方页面 + GitHub REST API，抓取时间 2026-09-12 14:43（GMT+8）。正文中的字节数、条目数均为接口实测；README 的「109 个配套实验」经逐章相加核对。

本文只陈述抓取到的公开事实，不构成对项目质量的保证，也不构成法律意见。

你更想先看哪一块——上下文工程，还是 Agent 的评估？评论区说一声，我按票数决定下一期从哪一章挑一个实验顺着讲。

下期预告：上一期答应的那个主题族（把模型塞到小设备与边缘上），到今天三榜上仍然凑不够成员，继续欠着。下期如果出现高动量新面孔，就回单项目精读；仍然零候选，就换个主题族做横向合集。