Pi Durable 的定位与设计初衷
Pi 团队在发布 Pi 1.0 版本的同时，推出了一款名为 Pi Durable 的实验性 npm 包。官方将其定义为一种 “durable agent harness”（持久化 Agent 容器），旨在构建各种类型的 Agent 应用，其中自然包含 Coding Agent。这个框架的核心定位是解决传统 AI Agent 在进程崩溃、网络中断或长时间运行后状态丢失的问题。它提供了一套完整的机制，包括模型调用工具、执行环境以及会话状态的持久化存储。
“它是 Pi 团队和 Pi 1.0 同一天发布的一个实验性的 npm 包，官方对它的定位是一个 durable agent harness。”
Pi Durable 与 Pi 1.0（终端 Coding Agent）的关系并非替代，而是互补。Pi 1.0 专注于单人在终端内的交互体验，而 Pi Durable 则是一个更通用的底层框架。它允许开发者在任何地方运行 Agent，从不同界面接入，支持无限长的会话，并能应对内外部严重故障。官方强调，Pi Durable 与 Pi 共享代码（如模型接入库 pi-ai），并遵循极简和可定制的原则。单独将其打包，是为了在不干扰 Pi 核心功能的前提下，试验新的设计并在验证后整合回主项目。
八大接口与核心机制解析
Pi Durable 提供了八组主要接口，构成了其功能基石。第一组负责打开和恢复存储。开发者可以指定 SQLite 文件等存储介质，Agent 的会话记录和任务进度写入其中。进程重启后，通过同一份存储即可恢复未完成的任务。
“一份存储加上运行一段或多段大模型会话所需的那套机制，它还提供模型要调用的工具以及工具运行的执行环境。”
第二组接口管理会话生命周期，支持创建新会话或从任意记录分叉出新会话。第三组处理提交与等待逻辑，包括输入排队、插话转向或直接拒绝忙状态下的新消息。第四组允许为每段会话单独配置模型思考强度、工具指令和工作目录。第五组用于扩展 Agent 能力，通过注册表（registry）定义新工具、System Prompt 段落及执行钩子。
第六组接口用于持久化应用状态。开发者可以定义带检查点（checkpoint）的自定义长任务，并将业务状态与会话一起保存。第七组提供实时状态订阅，将变化推送到终端、网页或其他客户端。第八组选择存储类型及执行环境。Pi Durable 内置了读/写/编辑文件及执行命令四个工具，使其能直接作为 Coding Agent 运行。存储后端支持 SQLite、JSONL、目录甚至内存，且核心实现不依赖 Node API，可适配 Bun 或 Cloudflare Durable Objects。
原子提交与崩溃恢复机制
Pi Durable 的核心对象是 Harness，其贯穿全局的规则是所有变化都通过原子提交写入存储。在提交完成前，任何中间状态都不会展示给用户。
“所有变化都通过同一条原子提交写进存储，提交完成之前不展示任何东西。”
存储中包含两类数据：一是会话记录（transcript），包含用户消息、模型回答和工具结果，写入后不可修改；二是任务（Task），如 pi.generation 和 pi.tool。任务是持久化的状态机，每一步都保存为检查点（checkpoint）。以一次包含两个工具调用的问答为例：用户消息写入后，启动 generation 任务请求模型；模型决定调用两个工具，回答作为模型消息写入记录；随后生成两个 tool 任务执行具体操作；结果写回后，generation 进入下一轮直至最终回答。
崩溃恢复依赖于 “Effect Sandwich”（效果三明治）模式：先写计划到存储，再执行操作，最后将结果写入并推进检查点。若进程在“执行中”阶段崩溃，重启后会寻找未完成的任务从最后检查点继续。关键在于工具的重放（Replay）属性。开发者可声明工具为 safe，表示其幂等且可安全重放（如只读操作）；未声明的工具在崩溃后不会自动重执行，而是向模型返回中断错误，由模型决定后续步骤。
实验验证：断点续传与工具重放
博主通过模拟模型进行了第一个实验，以复现崩溃恢复过程。实验中定义了两个工具：fetch_report（模拟读取报告，声明为 replay: safe）和 send_email（发送邮件，未声明重放）。模型在同一轮中并行调用它们。当执行到第 7 步时，博主通过 kill -9 强制杀死进程。
重启后使用相同的 requestId 重新打开会话，Harness 返回了编号为 7 的原有提交，而非创建新提交。实验结果呈现三点特征：
1. 不重复执行：客户端重试时，Agent 不会将同一件事做两遍。
2. 安全工具重放：fetch_report 从第一步重新运行至第 12 步，因为声明了 safe。
3. 中断工具处理：send_email 未重新执行，结果是一条包含崩溃前已提交输出的中断错误。
“能从断点继续不等于每个操作都只会执行一次。Pi Durable 保证每一步都有记录，崩溃后都能从记录继续。”
最终模型收到的反馈是“报告已拿到，邮件被中断”，并据此生成回答。这证明了 Pi Durable 并不自动保证幂等性，而是将判断权交给工具开发者。通过 memo 机制（记录某操作已执行），可进一步避免如重复发送邮件等副作用。
高级功能：分叉、收件箱与多人协作
基于原子提交和持久化状态，Pi Durable 实现了多种高级功能。
分叉（Fork）：解决同一段对话向两个方向继续的场景。会话可从任意条目分叉出新会话，新会话继承分叉点前的历史，之后独立运行。官方示例为 Slack Agent：频道主对话与下方的 Thread 即为分叉关系。文档（Document）作为带类型的 JSON，可与会话记录在原子提交中一起修改。开发者可声明文档分叉时是沿用父会话当前值，还是取分叉那一刻的值。博主实验显示，在分支中修改笔记不影响父会话中的副本。
收件箱（Inbox）：处理 Agent 忙碌时的新消息。默认策略是追加任务，排队等待当前轮次结束；插话转向（Steer）允许新消息在当前工具调用后直接介入，调整执行方向；拒绝则直接报错。此外支持仅写入会话记录而不触发模型的“静默写入”，用于记录如打开文件等事件。
多人协作：多个客户端可连接同一会话。由于界面仅渲染已提交状态，后加入的客户端可直接获取当前完整视图并接收后续 WebSocket 推送的小量操作数据。这避免了历史重放，适合实时协作场景。
Subagent 与运行时代码替换
Pi Durable 中并没有显式的“Subagent”概念，子会话本质上是由工具创建并归属该工具调用的普通会话。工具可以创建子会话，为其更换模型、添加指令并提交任务。由于子会话也是普通会话，它天然具备崩溃恢复和费用统计能力。
“Subagent 就是一个由工具创建并归这个工具调用所有的会话。”
子会话可放入后台运行，前台按 Esc 不会中止后台任务。中止父级工具时，系统会从下往上撤销操作。博主演示了基于 Pi Durable 的度假规划 Agent。该 Agent 使用 research 工具启动 Subagent，并行搜索天气、博物馆和火车信息。在 DeepSeek Flash 模型驱动下，主 Agent 将调研交给 Subagent 后，立即询问用户偏好（周末、节奏、预算），体现了非阻塞特性。
当进程在搜索中途被杀死时，重启后任务面板仅显示剩余的火车搜索。由于天气和博物馆结果在崩溃前已写入存储，重启后未重新执行；火车搜索完成后生成报告送回主会话。最终行程单整合了三项结果，总费用约 0.002 美元。值得注意的是，Demo 界面代码无需处理崩溃逻辑，恢复完全由 Harness 完成。
此外，Pi Durable 支持运行时替换代码。对话中仅保存扩展名字而非代码，注册表可在 Agent 运行时更新。已开始的调用使用旧代码，下一次调用则自动切换为新版本。系统提示词也会根据当前启用的扩展重新拼装，变化部分作为条目写入记录以节省 Token。
上手指南与生态集成
使用 Pi Durable 需安装三个包：pi-durable、模型接入库 pi-ai 以及状态订阅工具 chord。构建最小可用程序仅需三步：
1. 准备模型和注册表：创建模型集合，设置 Provider，加载工具。
2. 打开 Harness：传入存储（如 SQLite）、模型注册表和执行环境。
3. 交互与恢复：获取根会话，提交输入并等待结果。进程重启后使用相同 requestId 打开同一存储，即可继续未完成任务。
官方仓库提供两个 Demo：终端 Coding Agent 和度假规划 Agent。它们复用 Pi 的登录信息，会话存储在本地 SQLite 中。加上 --continue 参数即可继续最近会话。
“Pi Durable 做的事情可以用一句话概括：Agent 状态全部放在存储里，进程只负责从存储里读出进度接着往下执行。”
生态方面，Pi Durable 与 Cloudflare 的集成尤为值得关注。尽管名字相似，但 Pi Durable 是 npm 包，Cloudflare Durable Objects (DO) 是运行时。10月2日发布的 Cloudflare Agents SDK Beta 提供了 PiHarness，可将 Pi Durable 跑在 DO 中。当对象被回收时，通过定时唤醒机制重新拉起并从检查点继续执行。
结论
Pi Durable 通过“先写存储、再执行、后展示”的原子提交机制，从根本上解决了 Agent 的状态持久化问题。它不仅仅是一个崩溃恢复工具，更通过分叉、收件箱、Subagent 和运行时热更新等特性，赋予了 Agent 长生命周期和高并发协作能力。对于需要长时间运行、多人协同或复杂工作流编排的 Agent 应用，Pi Durable 提供了一个代码量适中（约1500行）、示例完整且易于扩展的底层框架。其核心价值在于将 Agent 的状态从易失性的进程内存中解放出来，使其能够像传统数据库事务一样可靠地运行在任意环境中。