#源码地图:packages/coding-agent

打开 packages/coding-agent/src 的第一印象是文件多(约 180 个),但结构其实只有三层:入口 → 核心 → 模式。这张地图帮你建立全局,再给出一条被验证过的阅读顺序。

#顶层结构

src/
├── main.ts              # 入口:参数 → 装配 → 进入某种运行模式(~860 行)
├── cli.ts               # bin 入口,仅转发 main.ts
├── cli/                 # 启动期辅助:参数解析、项目信任交互、会话选择器、首启 UI
├── core/                # 与 UI 无关的一切(重点区)
├── modes/               # 四种运行模式:interactive / print / rpc
├── extensions/          # 内置扩展(随包发布的 extensions)
└── utils/               # 工具函数:路径、图片、剪贴板、语法高亮……

main.ts 开头的注释自己说得很清楚:"This file handles CLI argument parsing and translates them into createAgentSession() options. The SDK does the heavy lifting."——入口只做装配,产品能力全在 core/,而 core/ 又通过 core/sdk.ts 对外导出(上一篇实战篇第 08 章用的就是它)。

#启动链路(main.ts)

main() 的执行序列(简化):

1. SettingsManager.create(cwd, agentDir, { projectTrusted: false }) —— bootstrap 设置(不信任项目);
2. takeOverStdout() —— 接管输出(output-guard.ts);
3. runMigrations(cwd) —— 配置/认证数据迁移(migrations.ts);
4. 解析参数(cli/args.ts)→ resolveCliModel(...) 解析 --model 等;
5. 项目信任决策(cli/project-trust.ts + core/trust-manager.ts);
6. createAgentSessionRuntime(createRuntime, { cwd, agentDir, sessionManager }) —— 总装(见下);
7. 按模式分派:runRpcMode(runtime) / runPrintMode(runtime) / new InteractiveMode(runtime, ...)。

#core/ 分组导览

#modes/:同一个 AgentSession 的四种消费方式

• interactive/interactive-mode.ts + components/(约 40 个组件):TUI。值得先看的组件:assistant-message.ts(流式渲染)、tool-execution.ts(工具调用块)、footer.ts(token/成本/上下文用量)、tree-selector.ts(/tree 的树导航)、model-selector.ts。
• print-mode.ts:-p 模式,收集事件、打印最终文本。
• rpc/:--mode rpc,stdin/stdout 的 LF 分隔 JSONL 协议(类型在 rpc-types.ts,帧处理在 jsonl.ts),供非 Node 进程集成。
• --mode json 没有单独目录:它是 print 模式把每个事件序列化成 JSON 行的变体。

#推荐阅读顺序

1. packages/agent/src/agent-loop.ts(约 800 行)——loop 本体,整个系统的心脏,对照设计思想:agent loop读。
2. core/tools/ 里的 read.ts → write.ts → edit.ts → bash.ts——看真实工具如何处理截断、diff、串行化,对照工具实现精读。
3. core/system-prompt.ts(约 160 行)——最短却最能体现 pi 气质的文件。
4. core/session-manager.ts——JSONL 树的全部操作,对照会话与运行时。
5. core/sdk.ts → core/agent-session.ts——看"门面"和"总装"如何分层。
6. 最后按兴趣进 modes/——交互模式组件最多,但都是"事件的消费者",有了前面的底子全是顺水推舟。