pi 是我现在用的终端 coding agent：读文件、跑命令、改代码、管会话。拿它当 agent 工程的研究对象，因为它满足几个条件：TypeScript 写的；代码是分层的库，不是一整块 CLI；扩展机制（extensions / skills / subagents）做得完整，有二次开发的入口。
以下目录信息核对于 0.85.x 的仓库。
项目地址
- 源码：github.com/earendil-works/pi（monorepo）
- npm 包：@earendil-works/pi-coding-agent，pi 命令来自 packages/coding-agent
- 文档在 packages/coding-agent/docs/，本地 npm 目录里也有一份，30 篇上下：extensions、SDK、自定义 provider、session 格式、安全模型都有
仓库顶层
| 目录/文件 | 作用 |
|---|---|
| packages/ | monorepo 工作区，全部源码，11 个包（见下表） |
| scripts/ | 构建与发布自动化：二进制打包、版本同步、release、模型目录生成等 30 余个脚本 |
| .github/ | CI 工作流 |
| .pi/ | pi 开发 pi 自己用的配置，读它能学到这套工具的实践配置写法 |
| AGENTS.md / CONTRIBUTING.md / SECURITY.md | 贡献规范、安全策略，动手改代码前过一遍 |
| tsconfig / biome.json / vitest. | TypeScript monorepo 工具链 |
packages/ 里的 11 个包
| 包 | 职责 |
|---|---|
| agent | 通用 agent 库：agent loop（对话循环）、状态管理、传输抽象都在这 |
| ai | 统一 LLM API：provider 集合、自动鉴权、token 与成本跟踪、会话中途换模型。只收录支持 tool calling 的模型 |
| coding-agent | pi CLI 本体：read/bash/edit/write 工具、会话管理，docs 和 examples 也在这个包里 |
| tui | 终端 UI 库，差分渲染，不依赖 agent 逻辑，可以单独拿来用 |
| client | 远程会话客户端，framed CBOR 字节流 |
| protocol | 远程会话的 CBOR 协议定义，client 和 server 共用 |
| server | 实验性 server 包，把 agent 跑成服务端 |
| session-backends | 会话存储后端，目前就一个 sqlite-node |
| chord | 应用组合运行时：services、复制状态、RPC、插件 |
| evals | 行为评测：真实 AgentSession 适配 vitest-evals，隔离目录里跑端到端检查 |
| telemetry | 供应商中立的遥测契约与 schema 工具 |
分层关系
从下往上看：tui 管渲染，ai 管模型调用，两个互不依赖。agent 站在 ai 上跑对话循环。coding-agent 把 agent、tui、内置工具组装成 CLI。protocol/client/server/session-backends 把这套东西搬到远程。evals 和 telemetry 是横向的质量工具。定位问题时从哪进：工具行为去 coding-agent，循环逻辑去 agent，模型接入去 ai，界面毛病去 tui。
阅读顺序（计划）
- agent/src/agent-loop.ts，看一次对话循环怎么走、工具怎么被调度
- ai 包：streaming、provider 抽象、成本核算
- coding-agent/src：内置工具的判定与实现，扩展点在哪
- extensions：对照 docs/extensions.md 和 examples/extensions/ 里的实例
- session 格式：docs/session-format.md
下一步
（待填：clone 仓库跑通开发环境，docs/development.md 有说明。第一个改造目标：给某个内置工具加个行为开关，验证对扩展机制的理解。）