源码篇阅读索引：值得逐行读的文件
小A读完源码篇，想在 pi-mono 里自己挑文件精读。他随手点开一个目录，几千个文件，不知道从哪下手，又回头找老Z。
“别全读，也别乱读。”老Z说，“读源码最大的坑，是把所有文件一视同仁。有的文件是入口，读它能看懂一条主路径；有的只是适配细节，扫一眼知道它解决什么问题就够了；generated models、第三方依赖、各类 README 根本不该逐行读，读了也记不住。这个附录就是照这个思路编的：每条路径给一张表，表后跟着一段‘怎么读、别怎么读’的解说。‘建议先看什么’那栏告诉你入口，解说告诉你容易在哪误解。读错方向的成本，往往比读得慢的成本高，时间有限时，先读解说再读表，比反过来省事。”
本附录服务 Part II，供完成一轮章节阅读、想深入某条调用链时查阅。路径与符号均按上游 pi 标签 v1.0.0（提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32）核对，只收那些“读懂了它就读懂一条主干”的文件，不做全仓库覆盖。
“还有一句要紧的，”老Z说，“这份索引对应的是 v1.0.0 这个快照。你 checkout 的是别的版本，路径可能还在，行号可能漂移，接口可能改名，索引的价值建立在基线一致上。从 0.83.0 到 1.0.0，整个 harness 目录就搬了家。所以先在上游克隆里跑 git rev-parse HEAD 确认基线，或者直接读本书仓库的 pi/ 快照，再拿索引对号入座；基线不对，一切‘建议先看什么’都只能当参考，不能当坐标。”
阅读优先级怎么排
老Z给了小A三条排序原则：
- 先入口，后细节：从
index.ts的导出表和某个create*/run*函数进，先看清主路径再钻分支。- 先契约，后实现：读一个模块前先读它的
types.ts或接口定义；实现细节只有在你怀疑某个 bug 时才需要。- 先状态，后逻辑：一个类有哪些成员、谁在何时改它们，比“这个 if 写得巧不巧”重要十倍。
小A：“三条原则里，哪条最容易被违反？”
“第二条。”老Z说，“很多人一进模块就扑向实现函数，对着 if 和 for 逐行读，读完了也说不出这个模块对外保证什么，因为他们跳过了 types.ts。接口是承诺，实现是兑现。不先看承诺就去看兑现，你看到的是一堆‘碰巧这么写’的代码，看不出哪些写法是为了满足契约才有的。”
“再补一条经验。”老Z接着说，“读到某个成员变量被赋值时，顺手记下‘谁在哪儿给它赋的值’。状态是‘谁在何时改’拼起来的，一个 currentSession 字段，找不到所有赋值点，你就永远不知道会话是何时被替换的。这条听着朴素，排障时最省时间。”
小A按这三条筛了一遍。值得逐行读的文件，按“读了能打通哪条主路径”分组如下。
模型请求这条路径
| 路径与符号 | 对应主题 | 建议先看什么 | 边界 |
|---|---|---|---|
packages/ai/src/models.ts:ModelsImpl、createProvider | 源码篇第2章 目录与户口——pi-ai | applyAuth 如何合并认证、streamSimple 如何委派 Provider | 不逐个 Provider 展开 |
packages/ai/src/api/lazy.ts:lazyStream | 源码篇第3章 先开票，后办事——pi-ai | 初始化延迟与错误入口的职责切分 | lazyStream 只管时序，不代表具体厂商事件格式 |
packages/ai/src/auth/resolve.ts:resolveProviderAuth | 模型认证 | 凭据来源链与失败传播 | 不审计凭据后端的安全存储 |
老Z特别提醒：models.ts 是整个 pi-ai 包的“门面”。它不是最长的文件，但 ModelsImpl 把 Provider 映射、模型查找、认证合并和流入口委派都集中在这里，读懂 streamSimple 的十几行，就等于读懂了 pi-ai 对外暴露的全部主路径。至于各 Provider 的适配细节（anthropic、openai-responses、openai-completions、google 等），走查时挑一个最深读即可，其余对比着看差异。
“读 streamSimple 时，最容易误读的是以为它包办了认证。”老Z说，“认证合并发生在 applyAuth，streamSimple 只是把认证结果和 Provider 选择一起接到流上。它是装配点，不是逻辑实现，想找认证或解析错误的根因，要往 applyAuth 和 resolveProviderAuth 里钻，别在装配点打转。Provider 查找先于认证合并，查找失败不应归为认证错误。”
“那 lazyStream 应该就是个惰性优化。”
“这个词只对了一半。”老Z说，“它的职责是把流创建延迟到订阅时，并统一错误入口：既是性能设计，也是错误处理设计，错误在订阅前统一变成可观察的流错误，而不是散落在创建阶段。读 lazyStream，别只看它晚了一步，要看它把失败统一成了什么形状。”
“resolveProviderAuth 是不是也容易读岔？”
“容易。有人以为它审计凭据安全，其实它做的是凭据解析与合并：按配置链路找出该用哪套凭据，再把失败往上抛。凭据的安全存储是另一层的事，不归它管。边界那栏写的‘不审计凭据后端的安全存储’，就是提醒你别越界读。”小A把这三条误读标在了表格旁边。
循环与会话这条路径
| 路径与符号 | 对应主题 | 建议先看什么 | 边界 |
|---|---|---|---|
packages/agent/src/agent.ts:Agent、subscribe | 源码篇第4章 双层循环——pi-agent-core | transcript、监听器、消息队列与中止控制器的状态契约 | 事件不是持久化 |
packages/agent/src/agent-loop.ts:runAgentLoop、runToolCall | 循环 | stop reason 的判定、工具结果的回收、finishTurn 等回合插口 | 不要从嵌套循环推断业务轮次 |
packages/coding-agent/src/core/agent-session.ts:AgentSession | 源码篇第5章 调度台——pi-coding-agent | 构造函数里的 subscribe 和 _install* 插口 | 很长，按插口跳读 |
packages/coding-agent/src/core/session-manager.ts:SessionManager | 会话 | header version 3、entry 类型、_persist 的懒创建与同步追加 | JSONL 不只保存对话消息 |
packages/coding-agent/src/core/agent-session-runtime.ts:fork | 会话 fork | at/before 边界与 createBranchedSession | 不创建 Git worktree |
packages/coding-agent/src/core/compaction/compaction.ts:compact、getSummarizationFailure | 压缩 | 摘要的 error／length 失败判定 | 摘要不是无损恢复 |
packages/coding-agent/src/core/skills.ts:loadSkillsFromDir、formatSkillsForPrompt | Skills | 发现规则、diagnostics、只列 name 和 description | 文本说明不是权限约束 |
“这一组最容易踩的坑在这儿。”老Z指着 agent-loop.ts 和 agent-session.ts 说，“runAgentLoop 是无状态的循环，AgentSession 才是有状态的装配层。很多人把 loop 当成总控函数，以为读懂它就懂了会话。方向反了：loop 不知道会话写到哪，不知道何时压缩，也不知道哪些 skill 可用。v1.0.0 把这条界线画得更清楚了，会话相关代码干脆不在 agent 包里。两层分开读，才不会把装配决策误当核心机制。”
“我懂了，”小A抢着说，“subscribe 就是事件日志，漏掉的回放一遍就行。”
“这一步猜偏了。subscribe 看起来像事件中心，但事件不是持久化，监听器拿到的是一次性的可观察事实，不是可以回放的日志。要回放得靠 JSONL，不是靠 subscribe。”
“那 session-manager.ts 呢？”
“存对话只是它的一部分。header version 3、entry 类型之外，里面存的还有配置变化、用量、压缩记录、上下文编辑和导航信息。把 JSONL 当成‘消息存档’来读，会漏掉大半信息。还要注意读取时坏行会被跳过，不报错。”
“compaction.ts 的误读藏得深。”老Z接着说，“很多人以为压缩是无损整理，其实它是可能失败的独立请求：摘要请求出错或被 token 上限截断，压缩就失败，不完整的摘要不会写进会话。把它当静默截断来读，你就不会去处理失败分支，而失败分支恰恰是本书故障手册里的一章。读 compaction，带着‘它会失败’的预期去读。”
“skills.ts 的边界在另一个方向。”老Z说，“文本说明不是权限约束，skill 是通过文本影响模型的指令包，模型可以不遵守；它甚至只把 name 和 description 放进提示词，正文要模型自己用 read 去读。读 skills.ts 时，别把它当成安全机制。”
产品与终端这条路径
| 路径与符号 | 对应主题 | 建议先看什么 | 边界 |
|---|---|---|---|
packages/tui/src/tui-main-screen.ts | 源码篇第6章 调度台与工位——pi-tui | 主屏差分更新、旧帧 previousLines、宽度检查 | 需结合 terminal 层阅读 |
packages/coding-agent/src/main.ts、cli.ts | 源码篇第7章 户口本上的住址——pi-coding-agent | 入口、参数解析、模式选择、cwd 解析 | 非单一总控函数 |
packages/coding-agent/src/core/agent-session-services.ts | 产品服务装配 | 资源、模型运行时、Provider 注册的先后 | 服务先于会话 |
packages/coding-agent/src/core/tools/file-mutation-queue.ts:withFileMutationQueue | 工具并发 | 同路径写入序列化、finally 释放 | 不处理所有外部资源 |
小A看着 main.ts 的早退分支出神：“这一堆 if (... return; 是干嘛的？”
“它们都是不会启动会话的命令：包管理、配置、--version、导出、help、模型列表。”老Z说，“别把所有 return 解读为调用失败，真正建会话的逻辑在它们之后。读 main() 的诀窍是，先跳过所有早退，直接找到 createSessionManager() 那一行，那才是产品主路径的真正起点。”
小A盯着两个文件又看了一会儿：“这两个文件这么长，会话逻辑不会都收在这儿吧？”
“这一步就踩进这一组的误读里了。”老Z说，“它们看起来像总控，其实是入口和参数解析，不是会话的核心逻辑；agent-session-services.ts 装配的是长期服务，agent-session.ts 装配的是一次会话，两层名字相近的‘装配’别混成一个概念。读 coding-agent 这一包，时刻记住边界栏那句‘非单一总控函数’。主路径散在多个文件里，不集中在哪个大函数上。”
“file-mutation-queue.ts 还有一处要当心。”老Z主动补了一句，“有人以为它保证所有写入安全，其实 withFileMutationQueue 只把同一路径的写入串行化，finally 保证释放；不同路径不管，网络请求不管，其他外部资源也不管。文件写入的串行化，别放大成一切的并发安全。”
协议、服务端与评测这条路径
| 路径与符号 | 对应主题 | 建议先看什么 | 边界 |
|---|---|---|---|
packages/protocol/src/protocol.ts | 源码篇第9章 发货与报关——pi-protocol | 信封联合类型、additionalProperties: false、PROTOCOL_VERSION | schema 不替代授权；业务内容是 Unknown |
packages/protocol/src/codec.ts:ValidatedMessageDecoder | protocol | frame → CBOR → validation 的串接 | decoder 失败后不能继续用 |
packages/protocol/src/framing.ts:FrameDecoder | protocol | 4 字节大端长度前缀、不完整尾帧、EOF 半帧 | 上限需按配置核对 |
packages/server/src/server.ts:Server | 源码篇第10章 黑板与便签——pi-server+pi-client | 握手阶段、handleRequest 的路由与错误码 | 不证明自动重连 |
packages/server/src/session-router.ts:SessionRouter | 会话附着 | 一连接一附着、attachmentId、断线释放 | 非分布式事务保证 |
packages/evals/src/harness.ts:runPiCodingAgent | 源码篇第11章 每次考试换新考场——pi-evals | 临时目录 mkdtemp、环境隔离、artifact 收集、cleanup | 真实模型非确定性 |
“protocol 这三个文件，建议倒着读。”老Z说，“先 protocol.ts 看清协议接受什么对象，再 codec.ts 看对象怎么变字节，最后 framing.ts 看字节怎么切 frame。这是协议可靠性的三个层次，顺序反了，容易把 framing 的边界误当成 schema 的约束。”
“这一组还有个误读要单独说：把 schema 当成授权。”老Z说，“protocol.ts 里的 additionalProperties: false 是形状约束，不是权限约束：它保证消息结构符合协议，不保证谁有资格发这条消息。”
“codec.ts 呢？decoder 失败了，跳过去用下一条就是。”
“错在‘可以继续用’。ValidatedMessageDecoder 串接了 frame → CBOR → validation 三层，是有状态的，一旦某一层失败，这个状态就不可信，必须新建。读 codec 时，把失败后的恢复路径当成正文读，别当成角落里的异常处理。”
“上限源码里写了，照着用就行。”小A指着 framing.ts 说。
“不一定，它可能是可配的。FrameDecoder 处理 4 字节大端长度前缀、不完整尾帧和 EOF 半帧，但长度上限要按配置核对。读的时候顺手查一下上限从哪来，别假设源码里的值就是唯一答案。”
“服务端和评测这组也有两处边界。”老Z说，“server.ts 处理握手、请求路由和断线清理，但它不证明自动重连；session-router.ts 的 SessionRouter 管附着和释放，但它不是分布式事务保证，断线后在途请求是否执行仍然未知。两个边界都是‘看着像、其实不是’，读的时候对照边界栏，别让名字替你下结论。evals/src/harness.ts 则要注意真实模型的非确定性：它建临时目录、收集 artifact、跑 cleanup，但真实模型的结果不能当确定性证明，这是评测的底色，不是 bug。”
不值得逐行读的部分
小A问：“那哪些文件不用读？”
老Z列了三类：
- generated models：TypeBox 生成的类型代码，机器产物，读它不如读 schema 定义。
- 模型清单与配置：
package.json、tsconfig.json、各类 lock 文件，扫一眼知道版本和依赖即可。- 第三方依赖：
node_modules里的东西不是 pi-mono 的设计，要研究就去看它自己的仓库。
“三类不读，理由各不相同。”老Z说，“generated models 是机器写的，别当人写的读，它的形状从 schema 来，读 schema 更省力；配置清单是状态不是逻辑，它告诉你依赖了谁，不告诉你系统怎么运转；第三方依赖是别人的边界，进 node_modules 之前先问一句：这行代码是 pi-mono 的决策，还是 upstream 的行为？答不上来就别读了。分清‘谁做的决定’，比分清‘代码在哪’更重要。”
“清单之外还有一类：测试文件。”老Z接着说，“测试是最被低估的说明书，它把‘这个模块应该怎样表现’写得比任何文档都具体。读实现遇到困惑时，先翻对应测试，测试的名字就是行为契约，测试的断言就是边界。‘它为什么这么写’的疑问，答案常常在测试里，不在文档里。”
“既然测试是说明书，”小A问，“那我该按什么顺序把测试和实现对着读？”
“一条约定：实现看不懂时，先读测试；测试读懂了，再回头读实现。”老Z说，“测试给你的是可观察行为，输入这个，应该得到那个；实现给你的是内部机制，它是怎么做到的。先知道该表现成什么样，再看怎么做到的。顺序反了，你会拿实现细节去猜行为，十个有九个猜错。”
“动手改之前呢？”
“先跑对应的那组测试，别凭阅读结果直接判断行为。”老Z说，“阅读告诉你‘它应该这样’，测试告诉你‘它确实这样’，两者之间隔着你没注意到的副作用和配置。阅读建立的是假设：你读出‘这个函数接受空数组时返回空’，这是假设，跑测试确认了，才变成知识。跳过测试直接改，改坏了也分不清是自己错还是读错了。”
阅读路线建议
如果时间有限，老Z推荐一条主线：models.ts → agent-loop.ts → agent-session.ts → main.ts。这四个文件串起来就是“一次完整请求”的全貌，从模型请求出发，经过循环，被装配层组织，最后从命令行入口装配进来。读完这条主线，再按兴趣分支钻 protocol、tui 或 evals。
“为什么按这个顺序？”小A问。
“它是按数据流排的，不是按代码量排的。”老Z说，“请求从模型层生成，进循环层跑，被装配层组织，最后从入口层进入。顺着数据流读，每一层的输出就是下一层的输入，认知是连续的。倒着读，从入口到模型，也能通，但你会先看到‘被谁调用’再看‘怎么实现’，容易在入口的装配噪音里迷路。顺着数据流，是四条路径里最省力的读法。”
“那四个文件里，先读透哪一个？”
“agent-session.ts。”老Z说，“它是最‘交叉’的一个，Agent、模型、工具、提示、会话写入、压缩、扩展都在这里接线。读透它，你对其他三个文件的疑问会少一半，因为它把它们之间的关系摆在了明面上。它读起来最‘绕’，但它是把这四条路径缝起来的那根线。”
“主线读完，还有一条补线。”老Z说，“session-manager.ts 和 compaction.ts 值得单独读，它们决定会话的持久化和上下文的管理，是‘一次完整请求’之外、但决定长会话质量的两个文件。主线回答一次请求怎么跑，这两个文件回答跑了很多次之后，状态怎么存、怎么裁。短会话看主线，长会话看这两个。说到底，源码阅读要建立的是一张可验证的地图：下次遇到 bug 或想扩展时，知道该往哪个文件看。”
小A把这条主线画在索引第一页：模型 → 循环 → 装配 → 入口，旁边批了一行小字：“先读数据流，再读细节”。