面向架构师 / 贡献者 / 二开工程师的 Pi Agent 深度文档。自底向上，关键路径级源码引用（file:line 格式），Mermaid 图示，中文为主。
Pi 是一个自扩展的 coding agent 工具集，由 earendil-works/pi-mono monorepo 下的四个核心 npm 包组成：
| 包 | npm 名 | 定位 |
|---|---|---|
pi-ai |
@earendil-works/pi-ai |
统一多供应商 LLM API：Provider/Model/Api 三层抽象，auth 解析链，流式事件协议 |
pi-agent-core |
@earendil-works/pi-agent-core |
状态化 agent runtime：agentLoop 状态机，tool 执行模型，session JSONL 持久化，compaction |
pi-tui |
@earendil-works/pi-tui |
自研终端 UI 框架：Component 组件树，differential rendering，自研多行编辑器，键绑定系统 |
pi-coding-agent |
@earendil-works/pi-coding-agent |
CLI 产品入口：interactive/print/json/rpc 四种模式，ExtensionAPI 扩展体系，信任模型 |
注意：
pi-tui是独立自研框架，不依赖 React/Ink 等第三方 UI 库。
| # | 章节 | 内容 |
|---|---|---|
| 01 | 全景与分层 | Monorepo 布局、四包依赖图、典型请求数据流、术语表 |
| 02 | pi-ai 深入 | Provider/Model/Api 三层抽象、auth 解析链、流式事件协议、tool call 部分 JSON 解析 |
| 03 | pi-agent-core 深入 | AgentMessage 类型边界、agentLoop 状态机、事件流、tool 执行（parallel/sequential）、steering vs follow-up |
| 04 | pi-tui 深入 | Component 接口、自研 Editor（grapheme 光标、kill/yank）、差分渲染（16ms 节流）、键绑定（Kitty/XTerm/legacy） |
| 05 | pi-coding-agent 深入 | CLI 启动链、四种运行模式、ExtensionAPI 全表、settings 加载与优先级、信任模型 |
| 06 | 端到端时序 | 一次 prompt("修个 bug") 的完整 Mermaid 时序图 |
| 07 | 扩展点手册 | 5 种最小骨架（tool / provider / extension / skill / package）+ 4 种加载方式 |
| 08 | 学习路线 | 3 条路径：5 天速通 / 2 周深读 / 1 月贡献者 |
| — | Demo 实践 | 6 个可运行示例：pi-hello-tool、pi-hello-provider、pi-hello-extension、pi-hello-skill、pi-hello-package、pi-rpc-client |