面向要用 pi 构建企业级 agent 的开发者。27 章正文加 4 个附录：前 12 章讲 pi-ai、pi-agent-core、pi-coding-agent，第 13 到 19 章讲 pi-durable，第 20 到 24 章讲 ExecutionEnv 与 Cloudflare 部署，第 25 到 27 章按源码执行顺序拆关键机制。
- 依据：
github.com/earendil-works/pi源码，逐文件对照v1.4.0（2026-10-27 的main，commit973b74c） - 包版本：
@earendil-works/pi-ai、pi-agent-core、pi-coding-agent、pi-durable、pi-env均为1.4.0 - 运行时：Node.js >= 22.19；
pi-durable标注为 experimental，小版本之间 API 可能变，升级前先读CHANGELOG.md - 示例主线：一个「运维助手 opsbot」，从单文件 agent 长到带持久化、远程执行环境、Cloudflare 部署的完整系统
pi 是什么。 一个刻意做小的 agent harness。内核只有模型调用、工具执行、事件流和状态管理，其余能力靠扩展拼：pi-agent-core 是运行时，pi-coding-agent 是官方基于它做的编码 CLI，pi-durable 把 agent 循环改写成「提交即持久」的任务系统。三者共用 pi-ai 的模型层。
它跟常见框架的差别。 大多数框架把 agent 写成一个循环，持久化、沙箱、审批是外挂。pi 的选择相反：pi-agent-core 只给你循环和钩子，不替你决定存储、权限和部署；要持久化就换 pi-durable，它的每条消息、每次工具调用都先落盘再可见；要隔离就把 ExecutionEnv 换成远程或容器实现。代价是你要自己组装，好处是每一层都能替换。
学它的顺序。 先建立 AgentMessage → LLM Message、turn、事件屏障这三个概念（第 4、6 章），再学工具和上下文（第 5、6 章），然后进 pi-durable 的 commit / task / phase（第 13～16 章）。跳过心智模型直接抄 durable 代码，会在「工具为什么重跑了」「进程被驱逐后任务停在哪」这类问题上卡很久。
| 章节 | 讲什么 | 读完能做 |
|---|---|---|
| 01 认识 pi | 包结构、设计取舍、与 LangGraph / Agents SDK / Temporal 的对比 | 判断你的场景该用哪一层 |
| 02 第一个 agent | createModels、Agent、事件订阅、第一个工具 |
跑起一个能调用工具的 agent |
| 03 模型层 pi-ai | provider、模型目录、流式事件、thinking、用量与成本、重试 | 接任意兼容端点并正确计费 |
| 章节 | 讲什么 | 读完能做 |
|---|---|---|
| 04 循环与事件 | turn 的边界、事件时序、agent_end 与 idle 的区别 |
用事件驱动 UI 和审计 |
| 05 工具系统 | AgentTool 全字段、schema 校验、并行/顺序、beforeToolCall / afterToolCall、terminate |
写出可审计、可中断的工具 |
| 06 上下文与系统提示 | AgentMessage 与 LLM 消息的边界、convertToLlm、transformContext、系统消息增量 |
控制 token 和行为漂移 |
| 07 控制流 | steering、follow-up、abort、continue、prepareRequest、finishTurn |
做可打断、可续跑的前端 |
| 08 生产实践 | 重试、缓存、identity、多模型路由、faux provider 测试、审计 | 把 demo 变成能上线的服务 |
| 章节 | 讲什么 | 读完能做 |
|---|---|---|
| 09 CLI 与四种接口 | TUI、print、JSON、RPC、会话参数、模型选择 | 把 pi 接进脚本和 CI |
| 10 会话、分支与压缩 | JSONL 树、/tree、/fork、compaction 阈值与边界 |
设计可回溯的会话存储 |
| 11 扩展系统 | ExtensionAPI、事件表、工具、命令、状态、UI、生命周期 |
用扩展改造 pi 而不 fork |
| 12 Skills、MCP、Codemode 与 SDK | 按需加载的技能、MCP 暴露策略、QuickJS 脚本、进程内嵌入 | 把 pi 变成企业内的编码助手 |
| 章节 | 讲什么 | 读完能做 |
|---|---|---|
| 13 为什么需要 durable | 进程会死、审批会等、部署会滚；commit / task / phase 三个概念 | 判断哪些状态必须落盘 |
| 14 第一个 durable agent | Harness.open、submit / wait、commit、存储后端 |
跑起可恢复的会话 |
| 15 恢复与幂等 | resume、requestId、crash loop、restartLimit、readOnly |
正确处理重启和重复提交 |
| 16 任务系统 | defineTask、phase、checkpoint、sleep、waiting、子任务、abort、task graph |
写自定义持久任务 |
| 17 durable 工具与扩展 | defineTool、replay、嵌套调用、callers、deferred、hooks、热替换 |
控制副作用的重复执行 |
| 18 上下文、压缩与成本 | sections、configure、compaction 策略、usage |
让长会话可控 |
| 19 观察与子代理 | watch、watchEvents、ownership、前台/后台子代理 |
做实时 UI 和多 agent 协作 |
| 章节 | 讲什么 | 读完能做 |
|---|---|---|
| 20 ExecutionEnv 接口 | FileSystem / Shell、Result、错误码、reader、watcher、listFiles |
实现自己的执行环境 |
| 21 Node 与远程执行 | NodeExecutionEnv 的进程组与 spill、pi-env 守护进程与协议 |
把工具放到另一台机器跑 |
| 22 无文件系统环境 | Workers 没有 fs 时怎么办：远程 env、容器 env、受限 env | 在 serverless 上选对环境 |
| 23 Cloudflare 架构与部署 | Worker + Durable Object + SQLite + alarm + onWake |
部署一个可休眠的 agent |
| 24 Cloudflare 运维 | 驱逐、恢复、CPU/内存限制、多租户、成本、排错 | 上线并守住 |
| 章节 | 从一个问题出发 | 讲清楚什么 |
|---|---|---|
| 25 源码：agent core | 工具明明并行跑了，为什么结果顺序不乱 | declareToolChanges、streamAssistantResponse、parallel preflight、terminate、length 截断 |
| 26 源码：durable | 进程在工具执行到一半被杀，恢复后为什么有时重跑、有时不跑 | commit/adopt、scheduler 的 reserve/phase/decide、replay 规则、压缩任务 |
| 27 源码：coding agent | 一行 /compact 到底改了哪些状态 |
AgentSession、SessionManager、extension runner、compaction |
- A 术语与速查：概念对照、包与入口、常见错误码
- B API 与事件速查：Agent 事件、durable 任务状态、Cloudflare 绑定
- C Cloudflare 上线检查表：逐条勾选，含排错表
- D 企业落地最佳实践：选层、成本、副作用、审批、多租户、迁移与反模式
第一遍：01 → 08。 这八章是地基。第 4 章的 turn、第 6 章的两种消息、第 7 章的队列，后面每一章都在复用。
第二遍：按目标跳。 做编码助手看 09～12；做企业后端看 13～19；要部署看 20～24；要改源码看 25～27。
动手建议。 建一个空目录，第 2 章的代码直接跑；第 14 章换成 durable 时保留同一个工具定义，能直观看到两层运行时的差别。
- 代码块标题里的路径相对项目根目录；源码引用标了文件路径，行号对应
v1.4.0。 - 命令默认在项目根目录执行，Node 用 22.19 以上。
- 流程图用 Mermaid，GitHub、VS Code、Obsidian 可直接渲染。
- 「注意事项」标记的是源码或文档里能验证的行为，不是猜测。
- 涉及删除、对外发消息、花钱的例子一律标了审批或幂等要求。pi 默认不信任模型，这个前提贯穿全书。