Pi 源码学习文档集（index）

仓库：https://github.com/earendil-works/pi — TypeScript monorepo 的 AI agent 工具集本目录是一套逐包深入的源码学习文档。配合仓库自带的 docs/（尤其是 packages/coding-agent/docs/how-pi-works.md）一起读效果最佳。

架构速记

依赖方向（自底向上）：

pi-ai  ──►  pi-agent-core  ──►  pi-durable  ──►  pi-coding-agent
                │                  │
                └──── chord ◄──────┘   (chord 是横向底座：服务/RPC + 复制状态 + delta + facet/bundle)

pi-coding-agent 再把 tui / mcp / protocol / env / client / server / codemode / evals / telemetry 组装成最终产品。

文档导航

文档	包	内容
01-pi-ai.md	`pi-ai`	统一多 provider LLM API；`transform-messages.ts` 跨 provider 归一化
02-pi-agent-core.md	`pi-agent-core`	`Agent` 类 + `agent-loop` 双层循环 + 事件流 + 工具执行
03-pi-durable.md	`pi-durable`	Session 内核 / Harness / 文档观察与回放 / 任务调度
04-chord.md	`chord`	应用组合运行时：复制状态 / 服务RPC / 不可变 delta / facet / bundle
05-pi-coding-agent.md	`pi-coding-agent`	CLI 入口 / `core/` 编排 / `modes/`（交互·print·json·rpc）/ 扩展
06-peripheral.md	9 个外围包	tui / mcp / protocol / env / client / server / codemode / evals / telemetry
07-extensions.md	扩展机制	extensions / skills / prompt-templates / themes / packages

三条自测主线（验证是否读懂）

请求链路：从 pi（CLI 入口）到"模型返回一段文本"经过哪些包/函数？
工具落地：一条 tool call 如何被记录进 session 树？compaction 时原 entry 去哪了？
可扩展性：用户装的一个 Pi 扩展包，在 loader 眼里是什么？如何注册工具/命令/UI？

动手环境

bash

git clone https://github.com/earendil-works/pi
cd pi
npm install --ignore-scripts      # 不跑 lifecycle scripts（供应链硬化要求）
npm run build:offline             # 用已有模型数据离线构建
./test.sh                         # 跑非 e2e 测试（无 API key 也能跑大部分）
./pi-test.sh                      # 从源码跑 pi

仓库强约束（见 AGENTS.md）：改代码后必须 npm run check；models.generated.ts 只能由脚本生成；禁止 git add -A / git reset --hard 等破坏性操作。

文档说明

本集文档基于仓库 main 分支的源码结构编写，关键结论均对照 src/ 下真实文件（已抓取 pi-ai / pi-agent-core / pi-durable / chord / coding-agent 的核心文件核对）。
外围包（第 06 篇）按"文件树 + 类型名"推断职责，深读时请以仓库实际源码为准。

Pi 源码学习文档集（index） ​

架构速记 ​

文档导航 ​

推荐阅读顺序（最小可理解路径） ​

三条自测主线（验证是否读懂） ​

动手环境 ​

文档说明 ​

Pi 源码学习文档集（index）

架构速记

文档导航

推荐阅读顺序（最小可理解路径）

三条自测主线（验证是否读懂）

动手环境

文档说明