---
name: source-reading
description: 带 AI 精读大型开源仓库，产出每句话都能回溯到源码具体行的书稿、课程或技术文档。核心是零幻觉：每一处引用逐字节核实、行号实读、静默删行由脚本抓出。覆盖锁版本锚点、写逐章大纲、八段结构写章节、编成带封面封底的 HTML 书、机器校验、并行子 Agent 生产六件事。当用户要读懂一个陌生的大型仓库、精读某个开源项目源码、把源码整理成一本书、整理成课程或系列文章、做源码解读、写架构分析、或者要派多个 Agent 并行写技术内容时使用。触发词：精读源码、读源码、源码解读、源码分析、拆解这个项目、这个仓库怎么读、把源码写成课、把源码写成书、写源码精读、架构分析、code walkthrough、带我读代码。
---

# 源码精读

把陌生的大型仓库读成可交付的内容。**唯一不可妥协的要求：每一个技术论断都可回溯到源码的具体行。**

AI 读码时幻觉几乎必然发生：根据文件名推测实现、根据常见模式补全细节、把注释当成代码行为陈述。掺进去一次，整份产出的可信度就是零，因为读者无法分辨哪句是真的。下面所有规则都是为了守住这一条。

## 第一步：先定规模，别过度应用

问清产出形态再动手。四阶段全流程很重，小任务不需要。

| 用户要什么 | 走哪些 |
|---|---|
| 读懂某个模块、回答一个机制问题 | 只用零幻觉引用纪律，不建大纲不做课页 |
| 一篇架构分析、一份技术文档 | 阶段一 + 阶段三 |
| 一门课、一个系列、多篇连载 | 四阶段全走，并建校验器 |

不确定就问：产出是给自己看还是给别人看，要不要交互演示，篇数大概多少。

## 零幻觉铁律

动笔前必须做到，每条都是作废级：

1. **每一处引用、每一个行号、每一个类型名与函数名，动笔前用读文件工具实读核实。** 禁止凭印象、禁止根据文件名推测、禁止照抄大纲里的候选行号
2. **代码块与源文件逐字节一致。** 保留原始缩进、属性宏、注释、空行。禁止转译、禁止美化、禁止写「示意代码」
3. 中间跳过内容必须显式写省略标记（含 `...` 的整行注释）。**静默删行会被校验器抓成 FABRICATION**
4. 找不到某个机制的实现，写明 `未找到对应实现，检索关键词为 X、Y、Z`。不许编一个看起来合理的
5. 由推断得出的结论显式标注为推断
6. 引用注释时说明这是注释，不要当成代码行为陈述
7. 数字（行数、文件数、变体个数）必须统计过，统一用 `splitlines()` 口径
8. 引用符号链接时引真实文件，并注明链接关系

引用格式，三部分必填，路径相对仓库根：

````
```153:160:core/src/session/turn.rs
pub(crate) async fn run_turn(
    sess: Arc<Session>,
    ...
) -> CodexResult<Option<String>> {
```
````

## 四阶段工作流

每一层的输入是上一层的输出，不要跳级。跳级的后果很具体：没有版本锚点，写到第十章时第一章的行号全部失效，且无法判断是当初写错还是后来改了。

```
- [ ] 阶段一 语料准备：锁版本、备对比语料、建检索脚本
- [ ] 阶段二 大纲：立一个真问题 + 逐章源码锚点
- [ ] 阶段三 章节书稿：八段结构，每处论断带行号
- [ ] 阶段四 成书：编成带封面封底的 HTML 书
- [ ] 贯穿 机器校验（批量生产之前就要建好）
```

### 阶段一：语料准备

```bash
git -C <repo> tag course-anchor-$(date +%Y%m%d)
git -C <repo> rev-parse --short HEAD
```

把 tag 与 commit 写进所有下游文档的文件头。然后做三件事：

1. **备至少一个同类项目做对照。** 只读一个仓库读不出设计决策，会把作者的选择当成唯一解。对比语料也要锁版本
2. **建 ripgrep 检索脚本，不要建向量库。** 查阅场景是关键词匹配，`rg` 毫秒级、零依赖
3. **找「为什么」的一手材料**，按优先级：仓库根的评审红线文件（`AGENTS.md`、`CONTRIBUTING.md`、`.cursor/rules/`）→ 模块级 README → 模块头注释 → 测试文件 → 官方博客。指向外链的空壳文档要识别出来跳过

评审红线文件优先级最高：每条禁令背后通常都是一次真实事故，这是「为什么不那样做」的唯一一手来源。

### 阶段二：大纲

用 `templates/00-outline-template.md`。三件事按顺序：

1. **先立一个真问题**，把整门内容收束到一句话。这句话决定哪些内容进、哪些不进。缺了它，大纲会退化成源码目录的中文翻译
2. **写清读者带走什么**，具体到能直接用。「学会 Agent 架构」不算，「一份该不该做沙箱、做到哪一层的决策树」才算
3. **逐章写锚点**：核心问题、源码入口（文件加候选行号）、要分析的设计决策、对比对象、演示方向

已核实的行号标 ✓。**✓ 的含义是曾经核实过，不是现在还对。** 写作时即使看到 ✓ 也要重读，因为真正要引用的可能是相邻的行。

演示方向要在大纲阶段就逐章分配，句式统一。不提前分配，多个写作 Agent 会做出雷同的演示。

### 阶段三：章节书稿

填 `templates/01-chapter-spec-template.md` 里的占位符，填完的那一份就是唯一写作标准。八段顺序固定：

| 段 | 要求 |
|---|---|
| 场景还原 | 从具体会翻车的情形开局，不从概念定义开局 |
| 逐行精读 | 篇幅主体，一段代码一段话交替推进 |
| 设计决策分析 | 回答为什么，给出「不这样做会出什么事」 |
| 边界条件剖析 | ≥ 2 个「如果…会怎样」，答案落到确切分支和行号 |
| 横向对比 | ≥ 1 组，两侧都给路径行号，说清各自代价 |
| 演示设计 | 分步 + 每步字幕文案 + 逻辑轨迹面板 |
| 可迁移结论 | 哪些值得抄、最小成本形态、哪些是过度设计 |
| 思考题 | ≥ 3 道，含 1 道动手验证 |

两段最容易被敷衍，也最能拉开深度：**边界条件**不许答「取决于配置」，必须落到源码里某个 `if` 的某一行；**横向对比**不许写成功能清单对照，要说清另一侧为什么可以没有、或用什么别的东西补上了。

### 阶段四：成书

把章节 markdown 编成一本带封面、目录、正文、封底的 HTML 书：

```bash
pip install markdown
cp book/book.config.example.json book.config.json    # 填书名、作者、被读仓库与版本锚点
python3 book/build_book.py
```

封面放阶段二立的那句话与版本锚点，封底放逐章引用数、图数、字数。读者判断一份源码解读值不值得信，看的就是这两样敢不敢摊开。

**带省略的引用块，省略之后的行号构建器不排**，只从两头数，中间留空。跳过了多少行只有源文件知道，编一个看起来合理的行号比不给更糟。

用法与输入格式见 `book/README.md`。校对用 `python3 book/shot_book.py dist`。

产出形态是课程站交互课页时走 `templates/02-page-spec-template.md`，与成书并行不冲突。课页上默认零代码，能在一页上贴的代码量远小于理解所需；演示必须有分步动画、每步一句人话字幕、逻辑轨迹面板。写「做个动画演示这个流程」等于没写。

## 文风

**能写成正则的进禁忌，不能的进表达偏好。** 无法自动检查的硬性规则等于没有规则。

禁忌交付前必须清零，跑：

```bash
python3 templates/style_scan.py path/to/chapters/
```

扫描器剥掉代码块、行内代码和「」直接引用后再判，避免源码字符被误报。只扫面向读者的正文，大纲和规范这类内部工作文档不在约束范围内。

**不要用同义替换绕过正则**，比如把「而不是」换成「而非」。禁的是靠否定制造对比这件事，不是那三个字。

完整清单在 `templates/01-chapter-spec-template.md` 第 4 节。

## 机器校验

**投入产出比最高的一件事，必须在批量生产之前建好。** 人工复核十万字的行号不现实。

至少校验三件：

1. **代码块与源文件逐字节比对**。以内容为准、行号为辅：按省略标记切成连续段，每段要在源文件里找到完全连续的匹配。拼不上判 FABRICATION，行号错了自动校正
2. **文风禁忌扫描**
3. **引用密度下限**。防一种隐蔽作弊：删掉报错的引用让校验变绿

第三条来自真实事故：某章初稿 56 处引用带若干报错，交付时只剩 22 处、全部通过。**校验器只报「现有引用是否正确」，不报「该有的引用是否还在」，这个缺口必须补。**

另外单独写一个脚本查「被引用文件是否存在」「行号是否越界」，逐字节比对验证不了路径写对没有。

校验器会误报，误报会让人开始忽略它的输出，那等于没有校验。每修一个误报都记下判据。

## 并行生产

规范里每一处含糊都会变成 N 份不同的理解。派活时必须给全四样：

1. 填好的写作规范（一个文件，不要口头补充）
2. 那一章的大纲条目
3. 全部语料的绝对路径。**先确认路径真实存在再说**，凭印象说「某个语料不在本地」会让子 Agent 绕开它
4. 校验命令，以及「必须全绿才算交付」

子 Agent 的四种典型偏差，规范里要提前堵：删引用让校验变绿、滥用省略标记凑字数、把检查糊弄过去、误报上游文档写错（实际命中率约两成）。

要求上报文档错误时带证据，格式固定：**被质疑的原话 → 源码文件与行号 → 那几行的原文 → 为什么对不上**。

并行中陆续收到的上游文档问题不要边收边改，开一个 `PENDING_FIXES.md` 累积，全部回来后统一核实统一修。

## 参考资料

- 方法论完整版，含每条规则的来由：[METHODOLOGY.md](METHODOLOGY.md)
- 29 条踩坑清单，全部来自真实事故，卡住时来查：[PITFALLS.md](PITFALLS.md)
- 大纲模板：[templates/00-outline-template.md](templates/00-outline-template.md)
- 章节写作规范模板：[templates/01-chapter-spec-template.md](templates/01-chapter-spec-template.md)
- 课页规范模板：[templates/02-page-spec-template.md](templates/02-page-spec-template.md)
- 成书构建器用法与输入格式：[book/README.md](book/README.md)
- 文风扫描器：[templates/style_scan.py](templates/style_scan.py)
- 真实成品，同一章从大纲到课页的纵向切片：[example/README.md](example/README.md)