Pi Durable 调研总结

By 陈成 · Published October 27, 2026

Pi Durable 是什么,崩溃恢复怎么做?OpenCode 2、Claude Code、qodercli 各自怎么处理崩溃,qodercli 引入它有什么收益?

2026-10-27 整理。来源:X 书签(4 条)及其评论、X 搜索、Reddit 搜索、官方博客、GitHub README、相关项目页面。

一句话

Pi Durable(@earendil-works/pi-durable)是 Earendil(Pi coding agent 背后的团队,Mario Zechner / @badlogicgames)在 2026-10-01 随 Pi 1.0 一起发布的实验性持久化 agent harness。它把对话、模型调用、工具调用和应用状态都先提交到存储,然后才对外展示;进程挂了,换个进程打开同一个存储就能从断点继续。

它不替代 Pi coding agent,而是一个用来做 agentic 应用的框架,coding agent 只是其中一种。

用 Mario 自己在 Reddit 上的 tl;dr:agent 崩了,你想恢复它,包括所有工具调用和后台任务?agent 要跑在 serverless 上?pi-durable 解决的就是这些。

为什么要做

Pi coding agent Pi Durable
运行位置 你的(远程)机器,终端里 任何有 JS runtime 的地方:Node、Bun、浏览器、Cloudflare Durable Object、手机
使用者 一个人驱动 多人、多端同时看和 steer
进程挂了 人看一眼,让它继续 自动从最后一个 checkpoint 恢复
对话长度 受上下文限制,手动 compact 后台 compaction,不打断对话
定位 稳定,1.0 后不再大改 实验性,API 随时变

Reddit 上有一种解读:Pi 越来越“集中”(一切在用户电脑上,电脑关了 agent 就停),Pi Durable 越来越“解耦”(状态、执行、客户端分离,追求 always-on)。社区也有人认为 Pi Durable 是 Pi 未来架构的替代者,Pi 1.0 冻结了老架构,正是因为新架构必然带来破坏性变更。

核心概念

flowchart LR
    subgraph Harness["Harness(一个存储 + 运行机器)"]
        direction TB
        Reg["Registry<br/>已安装的 Extensions"]
        Conv["Conversation<br/>transcript(Entry 序列)"]
        Doc["Document<br/>类型化 JSON 状态"]
        Task["Task<br/>带 checkpoint 的状态机"]
    end
    Storage[("Storage<br/>Memory / SQLite / JSONL<br/>IndexedDB / CF Durable Object")]
    Env["Execution Env<br/>本机 / 远程 VM / 沙箱"]
    Clients["客户端<br/>TUI / Web / 手机 / Slack"]
    Models["pi-ai<br/>模型提供方"]

    Harness -- "原子 commit,先存后显示" --> Storage
    Task -- 工具在这里执行 --> Env
    Task --> Models
    Clients -- "watch / submit / steer" --> Harness

一次输入被回答的过程:

sequenceDiagram
    participant C as Client
    participant H as Harness
    participant S as Storage
    participant M as Model
    participant T as Tool

    C->>H: submit(input, requestId)
    H->>S: commit pi.user
    H->>S: commit pi.generation task
    H->>M: 请求
    M-->>H: assistant(含 tool calls)
    H->>S: commit pi.assistant + pi.tool tasks(先记录意图)
    H->>T: execute()
    Note over T: 进程在这里崩了?<br/>replay: "safe" → 重跑<br/>否则 → 告诉模型 interrupted
    T-->>H: result
    H->>S: commit pi.tool-result
    H->>M: 下一轮
    M-->>H: 最终回答
    H->>S: commit pi.assistant → submission done

崩溃恢复是怎么做的

这是 Pi Durable 的核心,也是社区讨论最多的部分。

  1. 工具调用先记录意图再执行。 进程死在工具调用中间时,只有声明了 replay: "safe" 的工具(比如只读搜索)会在重启后重跑。其他工具(比如 deploy、退款)会以 interrupted 错误返回给模型,附上已提交的输出,由模型决定要不要先检查状态。
  2. 被打断的模型请求会重发,部分回答留在 transcript 里,标记为 aborted。
  3. requestId 让提交 exactly-once:客户端崩溃后用同一个 requestId 重试,拿回的是原来那个 submission,不会问两遍。
  4. Code Mode 的脚本也能恢复:模型写的 JS 在 QuickJS 沙箱里确定性执行(虚拟时钟、固定种子随机数、UTC),每次工具调用结果先写 journal。重启后重新运行脚本,按顺序喂回 journal 里的结果,已完成的调用不会再执行。
  5. 防崩溃死循环:同一个 task 被崩溃打断次数达到 restartLimit(默认 5)后会被 park,等人工 retryTask()。
  6. 睡眠可持久化:task 可以 sleepUntil,睡眠状态写入存储,不占进程;在 Cloudflare DO 这类可能被驱逐的环境,通过 onWake + alarm 唤醒。
stateDiagram-v2
    [*] --> pending
    pending --> running: 调度
    running --> waiting: 等子任务
    running --> sleeping: sleepUntil
    sleeping --> pending: 时间到 / alarm
    waiting --> running: 子任务完成
    running --> completing: 结果已定,等所属工作结束
    completing --> terminal
    running --> terminal: completed / failed / aborted
    running --> pending: 进程崩溃,重启后
    pending --> parked: 崩溃次数 ≥ restartLimit
    parked --> pending: retryTask()

社区提醒(重要):Pi Durable 保证的是“不会盲目重放不安全的工具调用”,不是外部副作用的 exactly-once。

其他能力

存储后端

后端 说明
Memory 不持久化
SQLite (Node) 单文件,WAL。只把工作集放内存,适合长期运行
JSONL (Node) 追加写文件,全量历史也在内存里,长跑不推荐
IndexedDB v1.4.0 新增,浏览器本地。同一时间只能一个 owner,官方建议用 Web Locks;需要长期保留时调用 navigator.storage.persist();关掉浏览器后任务不会继续跑
Cloudflare Durable Object 用 DO 自带的 SQLite,commit 即 DO 存储事务

同一个存储同一时间只能被一个进程持有,没有跨进程锁,其他客户端通过这个进程 attach。存储接口很小,有一致性测试套件,可以自己在 KV 或 Postgres 上实现。

生态与玩法(按热度和代表性)

mindmap
  root((Pi Durable))
    云端托管
      Cloudflare agents SDK v0.26 跑在 Durable Object
      Vercel durable-harness 支持 Pi 等多种 harness
      Rivet Actors 每实例约 1.3MB
      Deno celld 示例
    终端与移动
      Pi Pocket 手机优先 Web App
      Mario 在手机上跑 harness 做 pim
      PiDurableKit iOS JavaScriptCore
      Obsidian 内嵌
    个人 agent
      elvis 的 My Pi 类 Dots 主动式助手
      llufnam 的 pi os
      Sawyer Hood 号召自己做 Grok Bot
    多 agent 编排
      Daniel Griesser 的 Ultimate 自扩展 harness
      Pi Pocket agent teams
    基础设施
      pi-durable-agent 和 pi-durable-disk
      Terrarium microVM
    学习资料
      Superlinear 播客
      Caleb 的技术手册 PDF
      Alejandro AO 30 分钟教程

书签里的 4 条:

  1. Superlinear:用 Pi Durable + Cloudflare Durable Objects 可以做的 4 件事(播客 + 长推)

    • 高风险工作流的 durable agent:不盲目重放不安全调用。
    • 团队共享 agent:一个 DO 持有 agent 状态,多个客户端连同一个 session,消息排队或 steer,更新广播给所有人。
    • 到处运行:Mario 做了一个 Android app,harness 和状态在手机本地,只有模型调用走远程。
    • 在 agent 状态之上做新工具(他们最看好的一点):任务、checkpoint、被打断的操作都是结构化数据,不用叫醒 agent 就能可视化。可以做调试面板、工具调用可靠性指标、多人协作面板。原话:“durable execution state 成了一个可以在上面搭工具的新原语,而不只是用来做崩溃恢复。”
    • 评论里 @catmanyau 提醒:说“随处可运行”要小心,工具权限和副作用仍然要在工具实际执行的地方强制。
  2. Pi Pocket(@lovelylogicss / fingerthief):基于 Pi Durable 的手机优先、多人协作 Web App。手机审批、运行中重启不丢、多人、agent teams、PiP(帮你管其他 session 并盯 GitHub 的助手)、扩展系统、主题。跑在自己机器或手机(Termux)上,不需要云 VM。作者在 Reddit 上说,用它可以“合上笔记本,带去别处再打开,自动安全地接着跑”。

  3. VerySmallWoods:IndexedDbStorage:Pi Durable 加了浏览器存储适配器,可以做浏览器里的研究助手、可恢复的多步骤工作流。评论认为这适合纯客户端优先的 agent 应用。

  4. Vercel durable-harness:Vercel 推出的 durable-harness,让 Pi、OpenCode、Codex、Claude Code 等现有 harness 在 Vercel 上持久运行(24 万浏览)。它的思路和 Pi Durable 一样:模型和工具调用前先记录意图,完成后记录结果,用队列消息兜底,函数死了由新函数读日志接着跑;replay: 'safe' 的工具会重跑,其他的告诉模型“可能已执行”。区别在于它从外部给已有 harness 加持久化,底层用 Workflow SDK 的 World(Vercel / Postgres / MongoDB / Redis / Turso)。评论里有人指出真正的创新是“计算层变成了临时的,可以跨机器恢复”;也有人问长跑 agent 如何限制失控的花费,以及“副作用已发生但没来得及记录”的情况怎么处理。

其他值得看的:

和 OpenCode 2 对比

OpenCode 2(anomalyco/opencode v2.1.3)也有崩溃恢复,但粒度是整个 turn,不是每个 task。以下基于源码 packages/core/src/session/execution.ts 和 session/execution/restart.ts。

OpenCode 2 怎么做

和 Pi Durable 的区别

Pi Durable OpenCode 2
恢复单位 每个 task(模型调用、工具调用、compaction)各自 checkpoint 整个 turn,靠提示模型“接着做”来恢复
崩溃时正在跑的工具调用 执行前先记录意图;replay: "safe" 的重跑,其他以 interrupted 返回给模型 不按工具记录,也没有 replay 标注。未完成的调用不会重跑,新的 step 取代残留的半成品记录,由模型自己判断哪些做过了
Code Mode 崩溃后 QuickJS 确定性执行 + journal,重跑脚本时已完成的调用不再执行 没有 journal,解释器也不保证确定性,中断的 execute 直接丢失
持久睡眠 / 定时 sleepUntil + onWake alarm 没找到
投递语义 不盲目重放不安全的工具 源码自己写明 “Recovery is at-least-once … not repeated external side effects after a crash”
崩溃次数上限 5 次,之后 park,等人工 retryTask() 10 次,之后 turn 直接失败

结论:OpenCode 2 做到的是“会话挺过崩溃”:输入、transcript、进行中标记都持久化,turn 能自动恢复。Pi Durable 更进一步,给每次工具调用做 checkpoint。OpenCode 2 等于把“哪些已经做过”交给模型去看 transcript 判断,所以对外写操作更需要自己带幂等键,因为工具执行前没有任何意图记录。

qodercli 现状与引入 Pi Durable 的收益

基于 ~/Projects/qodercli(develop,bfd9380805)源码。

1. qodercli 现在怎么处理崩溃

一句话:transcript 能挺过崩溃,执行不能。进程挂了,会话停在原地,要人用 --resume / --continue 手动接回,没有自动恢复。

Pi Durable OpenCode 2 Claude Code 2.1.306 qodercli
存储 可插拔(SQLite / JSONL / IndexedDB / DO…),原子 commit SQLite / DO storage,事件 + 投影同事务 JSONL 追加,100ms 批量,修补半行;云端会话另写服务端 JSONL 追加,100ms 批量,无 fsync
崩溃后谁来恢复 新进程打开存储,自动接着跑 启动扫描 claim,自动续跑 人或宿主 --resume,之后自动判定并续跑中断的 turn 人手动 --resume
中断的工具调用 先记意图;safe 重跑,其余告诉模型 interrupted 不重跑,提示模型别重复 不重跑,补一条“结果未知、先检查再重试”的合成 tool_result 从上下文里删掉,模型不知情
子 agent / 后台任务 子对话归 task 所有,一起恢复 后台子 agent 作为子 session 续跑 孤儿后台任务通知模型,部分 agent 标为可恢复 标成 interrupted,不续跑
脚本级 journal Code Mode 全量 journal,确定性重放 无 无 Workflow 有前缀缓存,需显式 resumeFromRunId
崩溃死循环保护 restartLimit 5 10 次 没找到计数;靠中断时长上限(默认 6 小时)挡掉太旧的 turn 不需要(没有自动恢复)

对照:Claude Code 2.1.306 怎么处理崩溃

基于 ~/Projects/claude-code-versions/versions/2.1.306-unbundled/extracted 的打包产物(已压缩混淆,以下按字符串和调用关系推断,函数名不可读,结论以行为为准)。

一句话:和 qodercli 一样是“JSONL transcript + resume”,但 resume 这一步做得很细:它会判断崩溃时是否有 turn 没做完,给中断的工具调用补上明确的“结果未知”,然后自动续跑。没有 claim、task checkpoint、意图日志这些 durable 机制。

对 qodercli 的启示:上面“建议的落地顺序”第 1 步,基本可以照 Claude Code 的做法:不删未完成的 tool_use,补一条带“结果未知、先检查”的合成 tool_result;再加“turn 是否被打断”的分类和自动续跑提示。这两步不需要动存储,收益却最直接。

2. 如果给 qodercli 实现 Pi Durable,能得到什么

直接收益

  1. SDK / daemon / Remote Control 场景下进程挂了能自动接着跑。 这是最大的一条。现在一个 daemon 进程挂掉,所有会话停住,宿主只能重开再让用户手动 resume;引入 task + checkpoint 后,宿主重新拉起进程,进行中的 turn、后台子 agent 都能从最后一个 checkpoint 继续,SDK 侧的 running 任务也能拿到真实终态。
  2. 中断的工具调用对模型可见。 先记意图再执行,崩溃后模型拿到的是“Bash: npm publish 被中断,已输出 …”,而不是这次调用凭空消失。对 deploy、git push、发消息这类工具,这是正确性问题:模型现在可能在不知情的情况下把它再跑一遍。
  3. 后台子 agent 能续跑,不再只是标成 interrupted。 子 agent 本身就是一个由工具 task 拥有的对话,可以按同一套机制恢复。长时间的 Workflow、多 agent 编排受益最大。
  4. Workflow 从“手动前缀缓存”变成“自动 journal 恢复”。 现有 WorkflowJournal 的 started/result 记录、链式 key 的思路和 Pi Code Mode 的 journal 是一回事,往下补到工具调用粒度并接上自动恢复就行,这部分改动相对小。
  5. /loop、ScheduleWakeup 能真正持久。 现在的唤醒挂在进程上,进程没了就没了;有了持久睡眠(sleepUntil + 唤醒),定时任务可以挺过重启,甚至在进程不在时由宿主唤醒。
  6. 多端 attach。 所有 UI 状态都是已提交状态时,TUI、IDE 插件、Remote Control 可以同时看、晚加入、断线重连,watch() 直接对应现有的 SDK 消息流。

代价和风险

建议的落地顺序(从便宜到贵)

  1. resume 时不删未完成的 tool_use,改为补一条合成 tool_result(“执行被中断,可能已部分完成”)。改动小,立刻修掉“模型不知情”的问题。
  2. 加 turn 级的持久标记 + 启动扫描 + 次数上限,做到 OpenCode 2 的水平,先覆盖 daemon / SDK。
  3. 后台子 agent 从“标 interrupted”改成按子会话续跑。
  4. 工具调用先记意图、加 replay 标注;Workflow journal 下沉到工具调用粒度并自动恢复。
  5. 最后再考虑持久睡眠和多端 attach。

社区争议

1. 文档太难懂(r/PiCodingAgent,137 赞 58 评论)

2. 和 Pi 扩展不兼容

3. 是否能上生产

4. 迁移建议(r/AI_Agents)

我的判断

参考链接

X 书签

官方

相关项目与文章

OpenCode 2(v2.1.3 源码)

qodercli(本地源码,~/Projects/qodercli)

Claude Code 2.1.306(本地解包产物,~/Projects/claude-code-versions/versions/2.1.306-unbundled/extracted)

X 讨论

Reddit

Read this report as Markdown · Cite it (BibTeX)