Source Reading

# 源码精读

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

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` 毫秒级、零依赖