返回课程首页

附录 A

源码地图

包、入口、阅读顺序与调用链索引。

源码基线：Pi v0.82.0 · commit 518855d

本附录回答三个问题：应该先看哪个包、每个包负责什么、遇到某类问题去哪里找。

1. Monorepo 顶层

packages/
├── ai/             Provider、Model、Message、Streaming
├── agent/          Agent Loop、Tool、Event、Harness
├── coding-agent/   Session、Skills、Extensions、SDK、RPC、Coding Tools
├── evals/          评估相关能力
├── server/         服务端组合能力
├── storage/        仓库内部存储相关实现
└── tui/            终端界面（本书不讲）

构建桌面 Agent 的主阅读顺序是：

pi-ai → pi-agent-core → pi-coding-agent → SDK/RPC 宿主

2. pi-ai

入口：

  • packages/ai/src/index.ts
  • packages/ai/src/types.ts
  • packages/ai/src/models.ts
  • packages/ai/src/compat.ts
  • packages/ai/src/images-api-registry.ts
  • packages/ai/src/auth/
  • packages/ai/src/providers/

适合查找：

问题 文件区域
Model/Message/Tool 类型 types.ts
Provider 注册与模型刷新 models.ts
文本 API 名称怎样映射到 Stream compat.ts
图片 API Registry images-api-registry.ts
OAuth/API Key 契约 auth/
厂商请求/响应转换 providers/

3. pi-agent-core

入口：

  • packages/agent/src/agent.ts
  • packages/agent/src/agent-loop.ts
  • packages/agent/src/types.ts
  • packages/agent/src/harness/

适合查找：

  • 为什么还会继续下一 Turn；
  • ToolCall 怎样校验和执行；
  • 并行 Tool Event 怎样发出；
  • Steering/Follow-up 怎样进入循环；
  • Abort 怎样传递；
  • Agent/Event/Tool Definition 的类型。

先读 types.ts，再读 agent-loop.ts，最后读 agent.ts 对外状态机。

4. pi-coding-agent 核心

packages/coding-agent/src/core/
├── agent-session.ts
├── agent-session-services.ts
├── agent-session-runtime.ts
├── session-manager.ts
├── resource-loader.ts
├── model-runtime.ts
├── provider-composer.ts
├── project-trust.ts
├── settings-manager.ts
├── extensions/
└── tools/
主题 入口
Prompt、Queue、Retry、Compaction agent-session.ts
组装 CWD-bound 依赖 agent-session-services.ts
New/Resume/Fork/Replacement agent-session-runtime.ts
JSONL、Branch、Entry session-manager.ts
Skills/Extensions/Prompt 发现 resource-loader.ts
Provider/Auth/Model Registry model-runtime.ts
Project Trust project-trust.ts
Extension Factory/Handler extensions/loader.ts、runner.ts
Built-in Tool/Operations tools/

5. SDK 与 RPC

SDK：

  • packages/coding-agent/src/core/sdk.ts
  • packages/coding-agent/docs/sdk.md

RPC：

  • packages/coding-agent/src/modes/rpc/rpc-types.ts
  • packages/coding-agent/src/modes/rpc/rpc-mode.ts
  • packages/coding-agent/src/modes/rpc/jsonl.ts
  • packages/coding-agent/src/modes/rpc/rpc-client.ts
  • packages/coding-agent/src/core/output-guard.ts
  • packages/coding-agent/docs/rpc.md

不要只读 rpc-client.ts 就假设它是完整桌面客户端；第 32 章解释了 UI Response、Parse Error 与 stdin Backpressure 的补强点。

6. Skills 阅读入口

  • packages/coding-agent/docs/skills.md
  • packages/coding-agent/src/core/resource-loader.ts
  • Skill Parser/Loader 相关源码
  • Prompt 中 Skill Formatter 相关源码

阅读链：

扫描目录
→ 解析 SKILL.md
→ 冲突/诊断
→ 摘要进入 System Prompt
→ 模型读取完整文件
→ Tool 执行

7. Extensions 阅读入口

  • packages/coding-agent/docs/extensions.md
  • core/extensions/types.ts
  • core/extensions/loader.ts
  • core/extensions/runner.ts
  • core/extensions/wrapper.ts
  • core/event-bus.ts

阅读链：

发现路径
→ Import Module
→ Factory 注册
→ Runtime Bind
→ Handler/Event
→ Tool/Provider/Resource
→ session_shutdown Cleanup

8. 测试入口

  • packages/coding-agent/test/suite/harness.ts
  • packages/coding-agent/test/suite/agent-session-prompt.test.ts
  • 各 Package 的 test/ 目录

内部 Harness 展示了怎样注入 Faux Provider、Inline Extension、Tools 与 Event Collector。应用 可以借鉴测试形状，但不要把仓库内部 Test Helper 当成稳定公共 SDK。

9. 按问题反向定位

现象 第一站 第二站
模型请求格式错 Provider 实现 ai/types.ts
Tool 没执行 agent-loop.ts Extension tool_call
UI 一直忙 agent-session.ts settled/queue/retry
Skill 找不到 resource-loader.ts Skill Diagnostics
Extension 没生效 loader runner/bindings
Session 恢复不对 session-manager.ts compaction/context
切 Session 后事件重复 runtime replacement 宿主订阅
RPC 消息错位 jsonl/rpc-mode 宿主 ID Map

10. 推荐的三遍阅读法

第一遍只看类型与公开文档；第二遍沿一次真实调用链；第三遍用测试验证边界。不要按文件名 字母顺序读完整个仓库。