读真实开源项目的方法论

:::info 学习目标 完成本篇后你能够：按四步法独立读懂一个大型开源项目；用”主干道追踪法”找到任何功能的实现位置；形成自己的源码阅读笔记模板。 前置：第 1~11 篇完成。预计时长：45 分钟（阅读方法论本身）。 :::

读源码不是逐行读完（dsh 2500 个文件，逐行读完需要数月），而是带着问题沿主干道走，路过的地方只记路标不进店。以 dsh 为例演示。

第一步：读地图（30 分钟）

不读代码，只读”关于代码的文字”：

1. README.md——项目自述：是什么、怎么跑、亮点；
2. docs/ 与目录级 README——dsh 的 packages/README.zh.md 是一张完整的包地图（50 个包按能力分组，每组指明职责）；
3. AGENTS.md / CLAUDE.md——写给 AI 的仓库说明，往往是最高效的人类导读；
4. 跑起来——docker compose up 或 pnpm dev，先用再读。

产出：一张手绘的分层图（不用精确，错了后面会修正）。

第二步：找到主干道（1 小时）

每个系统都有一条”一次请求/一次任务”的主干道。找法：

• 从入口顺藤摸瓜：CLI 的 main/bin → 路由 → 核心调度。dsh 的入口是 apps/cli/src/bin.ts；
• 从日志反查：跑起来后看日志输出的关键字，回源码 grep——日志语句永远离主干道不远；
• 从测试反查：核心逻辑必有测试，测试文件就是”这个函数怎么用”的说明书（dsh 的 *.spec.ts）。

dsh 的主干道结论（第 7 篇验证过）：bin.ts → runProfile → boot() → agent-loop（turn/step 循环）→ tools 执行。

四步法全景

第三步：沿主干道精读（数天~数周）

第三步：沿主干道精读（数天~数周）

只精读主干道上的文件，每读一个文件回答三个问题并记进笔记：

## agent.ts（2026-09-06 读）
1. 它做什么：turn/step 循环，驱动模型与工具
2. 它依赖谁：session（写日志）、systemPrompt（组装）、tools（执行）、llm（流式）
3. 它被谁调：ThreadManager / CodexThread；事件从 agent/* 发出
4. 我的问题：pre-step 的 reject 之后 pending input 去哪了？→ 已在 296 行找到答案

三个问题的答案就是你笔记的骨架——第 7~11 篇的每篇都是这么写出来的。

第四步：动手验证（持续）

• 改一行看效果：改日志文案、改默认值，重跑验证理解；
• 写个小工具：照第 14 篇的流程给项目加功能——写不出来就说明还没读懂；
• 给别人讲：写博客或组内分享（本专栏就是这个方法的产物）。

常见的错误读法

1. 从第一个文件逐行读到最后一行——2500 个文件会读半年，且读完即忘；
2. 只读不跑——没有可运行的实例，所有理解都是猜测；
3. 每个被引用的类型都点进去——引用深度是无限的，只展开你正在追的那条线；
4. 不记笔记——两周后全部还给源码。

本篇产出

选一个你感兴趣的开源项目（不一定是 dsh），完成第一步和第二步：产出分层手绘图 + 主干道文件清单（不超过 10 个文件）。这份清单就是你下阶段精读的计划表。