17 · 源码地图、研究证据与边界¶
17.1 研究基线¶
官方 v1.0.0 commit a13d35a742c6ef8462812a28fbe1d8c8b7431c32，1848 个 Git tracked files。完整清单保存每个文件的路径、字节数、文本行数和 SHA-256。生成清单不等于对每个文件进行语义审核。
下载：版本证据、全部文件 JSON 清单、CSV 清单、main 与 1.0 差异、公开符号定位。
17.2 核心阅读顺序¶
ai/types 与 utils/transcript
→ agent/types
→ agent/agent.ts
→ agent/agent-loop.ts
→ coding-agent/core/sdk.ts
→ coding-agent/core/agent-session.ts 主干
→ session-manager 与 compaction
→ tools 与 resource-loader
→ extensions/mcp、codemode
→ TUI、RPC
→ durable、Chord、protocol（实验方向）
先看输入输出类型，再追执行顺序。搜索函数名只是定位；需要看前后条件、调用者和消费者，才能理解不变量。
17.3 28 个核心文件的完整逐行原文¶
这些页面包含固定版本全部原文，支持跳到行号与 #L123 链接。文件收录只是阅读辅助；右侧说明实际讲解覆盖。原作者许可保存在 MIT LICENSE。
| 文件 | 行数 | 原文 | 讲解覆盖 |
|---|---|---|---|
packages/ai/src/types.ts |
1168 | 逐行原文 | 04：消息与provider compat契约；非全部模型类型审计 |
packages/ai/src/api/anthropic-messages.ts |
1646 | 逐行原文 | 04/20：中途工具声明适配与版本差异；非全部provider分支审计 |
packages/coding-agent/src/core/compaction/compaction.ts |
1119 | 逐行原文 | 07：usage估算、合法切点、split turn与摘要失败 |
packages/coding-agent/src/core/settings-manager.ts |
1533 | 逐行原文 | 08/14：inMemory的项目trust默认与设置；非全部迁移审计 |
packages/coding-agent/src/core/nested-tool-calls.ts |
261 | 逐行原文 | 09：嵌套授权、父调用归属和结果包装 |
packages/coding-agent/src/core/extensions/types.ts |
2245 | 逐行原文 | 08：事件边界与mutable input；非全部公开类型逐句分析 |
packages/mcp/src/oauth/flow.ts |
437 | 逐行原文 | 09：issuer条件、scope与授权流程；未真实认证E2E |
packages/coding-agent/src/modes/rpc/rpc-mode.ts |
819 | 逐行原文 | 10：JSONL响应disposition、事件和错误边界 |
packages/agent/src/agent.ts |
613 | 逐行原文 | 05：状态、队列、取消和事件屏障 |
packages/agent/src/agent-loop.ts |
940 | 逐行原文 | 05：完整主循环和工具执行管线 |
packages/agent/src/types.ts |
529 | 逐行原文 | 04–05：公开契约与边界 |
packages/ai/src/index.ts |
48 | 逐行原文 | 04：入口职责与导出 |
packages/ai/src/utils/transcript.ts |
234 | 逐行原文 | 04：system 与工具声明重放 |
packages/ai/src/models.ts |
1256 | 逐行原文 | 04：Models 和 Provider 契约；未逐分支审核所有模型操作 |
packages/coding-agent/src/core/sdk.ts |
462 | 逐行原文 | 06：SDK 组装工厂 |
packages/coding-agent/src/core/agent-session.ts |
4348 | 逐行原文 | 06：请求、事件、恢复主干；非全文件逐行审计 |
packages/coding-agent/src/core/session-manager.ts |
2013 | 逐行原文 | 07：树、投影和追加存储；非所有格式迁移路径审计 |
packages/coding-agent/src/core/system-prompt.ts |
216 | 逐行原文 | 08：prompt sections 和 diff |
packages/coding-agent/src/core/resource-loader.ts |
1275 | 逐行原文 | 08：资源发现、reload、信任主干；非所有 package 解析分支审计 |
packages/coding-agent/src/core/tools/read.ts |
203 | 逐行原文 | 08：分页、截断、图片和取消 |
packages/coding-agent/src/core/tools/edit.ts |
220 | 逐行原文 | 08：批量替换、行尾和队列 |
packages/coding-agent/src/core/tools/file-mutation-queue.ts |
61 | 逐行原文 | 08：同文件排序 |
packages/coding-agent/src/core/tools/bash.ts |
442 | 逐行原文 | 08：工具包装、输出、操作适配主干 |
packages/codemode/src/runtime/host.ts |
361 | 逐行原文 | 09：worker 和能力边界；非全 VM 实现审计 |
packages/mcp/src/client.ts |
615 | 逐行原文 | 09：独立 MCP client 契约；非所有协议分支审计 |
packages/tui/src/tui.ts |
1493 | 逐行原文 | 10：Component 和共享 UI 抽象；非全终端行为审计 |
packages/protocol/src/framing.ts |
151 | 逐行原文 | 10：帧契约浏览；非全部 CBOR 编解码审计 |
packages/durable/src/harness/tool.ts |
488 | 逐行原文 | 11：工具意图与 replay 恢复路径 |
17.4 Monorepo package 地图¶
下表从各 package.json 自动读取，列的是 dependencies 中内部运行时依赖，不包含 devDependencies 或全部外部依赖。实验状态以 package 文档声明为准，不能只看版本号。
| npm 名称 | 目录 | 版本 | 内部运行时依赖 |
|---|---|---|---|
@earendil-works/pi-agent-core |
agent |
1.0.0 | @earendil-works/pi-ai |
@earendil-works/pi-ai |
ai |
1.0.0 | @earendil-works/pi-telemetry |
@earendil-works/chord |
chord |
1.0.0 | 无 Pi 运行时依赖 |
@earendil-works/pi-client |
client |
1.0.0 | @earendil-works/chord, @earendil-works/pi-protocol |
@earendil-works/pi-codemode |
codemode |
1.0.0 | 无 Pi 运行时依赖 |
@earendil-works/pi-coding-agent |
coding-agent |
1.0.0 | @earendil-works/chord, @earendil-works/pi-agent-core, @earendil-works/pi-ai, @earendil-works/pi-codemode, @earendil-works/pi-mcp, @earendil-works/pi-tui |
@earendil-works/pi-durable |
durable |
1.0.0 | @earendil-works/chord, @earendil-works/pi-ai |
@earendil-works/pi-evals |
evals |
1.0.0 | 无 Pi 运行时依赖 |
@earendil-works/pi-mcp |
mcp |
1.0.0 | 无 Pi 运行时依赖 |
@earendil-works/pi-protocol |
protocol |
1.0.0 | @earendil-works/chord |
@earendil-works/pi-server |
server |
1.0.0 | @earendil-works/chord, @earendil-works/pi-protocol |
@earendil-works/pi-telemetry |
telemetry |
1.0.0 | 无 Pi 运行时依赖 |
@earendil-works/pi-tui |
tui |
1.0.0 | 无 Pi 运行时依赖 |
17.5 本课程重点核对的不变量¶
| 不变量 | 证据 | 验证方式 |
|---|---|---|
| 完整消息后才执行工具 | agent-loop + Agent awaited emit | 代码精读与离线事件 |
| 参数校验失败不执行工具 | prepareToolCall | 契约测试 |
| parallel 结果历史保持源顺序 | executeToolCallsParallel | 契约测试 |
| sequential 工具影响整个批次 | executeToolCalls | 契约测试 |
| SDK canonical history 来自 SessionManager | prepareRequest projection | SDK + Faux 测试 |
| 分支不删除原始历史 | SessionManager append / branch | 文件恢复测试 |
| 低层 agent_end 后仍可能恢复 | AgentSession post-run | 代码精读，非真实 provider 重试压测 |
| project trust 不等于沙箱 | security + resource loader | 文档和源码核对 |
| Code Mode 调用不回滚外部副作用 | VM host 与 extension contract | 代码/文档核对 |
| Durable 重放依赖安全策略 | ToolTask phases | 意图与恢复分支精读 |
17.6 哪些没有完成整仓库逐行审核¶
没有宣称已逐行审查所有 provider adapters、OAuth 全路径、native TUI、图片处理、所有历史版本迁移、CBOR、Chord bundler、Durable 全调度器、完整测试套件和依赖源码。
对这些内容，课程采用公开接口、文档、代表实现和使用边界研究。选定核心主干做了按连续逻辑段的详细解释；大型 AgentSession 文件讲解主要请求与状态路径，没有把它的每个分支都称为已测试。
你要求「最好逐行研究」，本交付把核心执行链逐段精读、逐行浏览原文、文件证据与测试结合，而不以机械复述 1848 个文件代替理解。这个边界比虚假的「整仓库每行都懂了」更方便继续深入。
17.7 三条值得进一步研究的路径¶
模型协议路径：Models.prepareRequest → provider stream → provider payload transform → assistant stream normalization。结合你的实际 provider，研究工具声明和跨模型历史转换。
扩展执行路径：resource-loader → extension runtime/runner → AgentSession hook → nested calls。增加插件冲突、reload 与恢复案例。
持久任务路径：Harness → Task scheduler → transaction → ToolTask checkpoint → storage。重点测试进程崩溃、外部动作未知状态和任务迁移。
17.8 自己逐行读时的笔记模板¶
每行都应归到契约、状态、控制或副作用中的一个方面。真正有价值的逐行研究是理解这些联系，而不是给每行写「声明变量」「返回结果」。