6.1 架构总览

这是最顶层的一层：@pi/coding-agent —— 一个真正可用的交互式编码 Agent CLI。它把前面所有包"缝合"起来，并加上产品级能力：会话持久化、内置工具、扩展系统、上下文压缩、模型管理、认证、TUI 界面。

它依赖了谁

coding-agent 是唯一一个"什么都依赖"的包：

coding-agent
 ├─ @pi/ai            （直接 import compat 入口，拿默认 streamSimple）
 ├─ @pi/agent-core    （Agent 运行时）
 ├─ @pi/tui           （交互界面）
 ├─ @pi/server        （远程会话服务端）
 ├─ @pi/client        （远程会话客户端）
 └─ @pi/protocol      （远程协议）

从 main() 到 Agent

入口链路（packages/coding-agent/src/main.ts）：

main()
 ├─ 解析 CLI 参数（parseArgs）
 ├─ 决定运行模式：print / interactive / rpc / json
 └─ 各模式内部调用 SDK 的 createAgentSession()

createAgentSession()（core/sdk.ts:169）是"装配工厂"，它一次性完成：

1. 解析 cwd、agentDir（配置目录 ~/.pi/agent）。
2. 创建 ModelRuntime（基于 @pi/ai 的 Models，管理模型目录 + 认证）。
3. 创建 SessionManager / SettingsManager / ResourceLoader。
4. 解析要用的模型（从会话恢复，或找默认）。
5. 构造 Agent（来自 @pi/agent-core），注入 streamFn、事件回掉、队列模式。
6. 创建 AgentSession（对 Agent 的产品化封装）。

AgentSession：产品化封装

AgentSession（core/agent-session.ts）在 Agent 之上加的职责：

能力	说明
会话持久化	把 transcript 存到磁盘，可恢复（见 6.2）
工具激活管理	按 tools / excludeTools 启停工具
事件总线	把 AgentEvent 转成会话级事件（供 UI/扩展）
上下文压缩	transcript 过长时自动压缩（compaction）
认证视图	模型可用性、登录状态

运行模式（modes）

modes/ 提供四种消费方式，share 同一个 SDK：

模式	说明
print	单次提问，结果打到 stdout（pi -p "…"）
interactive	全屏 TUI（@pi/tui）
rpc	通过 RPC 协议驱动（自动化/IDE 集成）
json	结构化 JSON 事件输出（pi --json）

关键：同一套 AgentSession，四种模式都能驱动。这正是"无状态内核 + 多种 UI"的分层红利。

三级装配递进

从低到高，装配层次是：

Agent（@pi/agent-core）         —— 无状态循环，只发事件
   ↑
AgentSession（coding-agent）    —— 产品化：持久化、工具、事件总线
   ↑
Modemode（print/interactive/…） —— 与用户交互

每一层只依赖下一层，不越级。

源码目录速查

packages/coding-agent/src/
├── main.ts           入口：参数解析 + 模式分发
├── cli/              参数解析、帮助、模型列举
├── core/             核心：sdk、session、tools、compaction、extensions…
├── extensions/       内置扩展
├── modes/            四种运行模式 + TUI 组件
└── config.ts / migrations.ts  配置与迁移

小结

• coding-agent 依赖所有下层包，是聚合根。
• main() → createAgentSession() → Agent + AgentSession。
• 四种运行模式共享同一 SDK。
• 分层红利：换 UI 不改内核，换模型不改循环。

真实源码位置

• 入口：packages/coding-agent/src/main.ts
• SDK 工厂：packages/coding-agent/src/core/sdk.ts:169
• 模式：packages/coding-agent/src/modes/

下一步：6.2 会话状态管理。