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
- Harness:一个打开的存储,加上运行 agent 的机器。所有变更走一条原子 commit 线,没提交的东西不会显示。
- Conversation:一份 transcript,可以新建、fork。每个对话单独存自己的 agent 配置(模型、thinking level、扩展、工具、工作目录)。
- Entry:不可变的记录,例如
pi.user、pi.assistant、pi.tool-result、pi.reset,也可以是你自定义的类型。 - Commit:原子写入,追加 entry、改 document、建 task,要么全成功要么全不写。
- Document:和 transcript 存在一起的类型化 JSON,比如 todo list、计划、沙箱信息。和 transcript 在同一个 commit 里改,所以应用状态不会和 transcript 对不上。
- Task:每一步都存 checkpoint 的持久状态机。模型调用(
pi.generation)、工具调用(pi.tool)、compaction 都是 task。 - Extension:工具、system prompt section、hook、wrapper、task 的打包。对话只存扩展名,不存代码,所以可以热替换。
一次输入被回答的过程:
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 的核心,也是社区讨论最多的部分。
- 工具调用先记录意图再执行。 进程死在工具调用中间时,只有声明了
replay: "safe"的工具(比如只读搜索)会在重启后重跑。其他工具(比如 deploy、退款)会以interrupted错误返回给模型,附上已提交的输出,由模型决定要不要先检查状态。 - 被打断的模型请求会重发,部分回答留在 transcript 里,标记为 aborted。
requestId让提交 exactly-once:客户端崩溃后用同一个 requestId 重试,拿回的是原来那个 submission,不会问两遍。- Code Mode 的脚本也能恢复:模型写的 JS 在 QuickJS 沙箱里确定性执行(虚拟时钟、固定种子随机数、UTC),每次工具调用结果先写 journal。重启后重新运行脚本,按顺序喂回 journal 里的结果,已完成的调用不会再执行。
- 防崩溃死循环:同一个 task 被崩溃打断次数达到
restartLimit(默认 5)后会被 park,等人工retryTask()。 - 睡眠可持久化: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。
- Superlinear 的推文里拿“退款”举例,评论里 @deeponailabs 指出:退款接口仍然需要幂等键。Superlinear 也承认这一点。
- Reddit r/LLMDevs 上有人担心
replay: "safe"是会过时的人工标注:有人重构工具加了写操作却忘了改标记,崩溃恢复就会重复执行副作用。 - r/AI_Agents 的讨论结论:durable runtime 买到的是“状态挺过重启、可以睡几天、可回放历史”,买不到“外部副作用 exactly-once”。每个对外写操作仍要自己带幂等键,最小验证是“在业务写入提交后、step 标记完成前杀掉 worker,第二次运行不能产生第二条记录”。
其他能力
- 多对话并发 + fork:一个 harness 并发跑任意多个对话。比如 Slack 频道是一个对话,某个 thread 是从某条消息 fork 出来的子对话,两者互不阻塞,还可以给 thread 配不同的工具(能搜索、不能部署)。
- Busy 时的输入:
steer(插到当前工具轮次之后)、follow-up(当前 run 结束后开始,默认行为)、reject、write(只写记录不触发模型)。 - 子 agent:没有内置,但几行代码就能写,子 agent 本身就是一个由工具调用 task 拥有的对话,同样可以崩溃恢复。
- 所有权树:task 和对话组成一棵所有权树,abort 自底向上,每个 task 先清理自己的副作用。示例里用“多张卡分账付款,一张被拒其余自动退款”来演示。
- 后台 compaction:接近上下文上限时后台做摘要,在下一个 turn 边界放入,对话不停。旧消息永远留在存储里,可以配合
search_history工具做“自我交接再回查”。 - 热更新:registry 运行中可替换扩展。正在执行的工具调用用旧代码跑完,下一次用新代码。
- 多人协作:UI 需要的一切都是已提交状态,任意客户端都可以 attach、晚加入、断线重连、steer。
watch()给出每次 commit 的精确操作,适合走 socket。 - 执行环境与 harness 分离:harness 可以跑在一台机器上,工具在另一台执行。有人把 harness 放在宿主机,把
pi-env暴露在 microVM 里作为安全的编码环境。 - 体量:不含测试约 15,000 行,GPT 约 15 万 token、Claude 约 25 万 token。官方的说法是“让你的 agent 能读懂它”。
存储后端
| 后端 | 说明 |
|---|---|
| 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 条:
-
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 提醒:说“随处可运行”要小心,工具权限和副作用仍然要在工具实际执行的地方强制。
-
Pi Pocket(@lovelylogicss / fingerthief):基于 Pi Durable 的手机优先、多人协作 Web App。手机审批、运行中重启不丢、多人、agent teams、PiP(帮你管其他 session 并盯 GitHub 的助手)、扩展系统、主题。跑在自己机器或手机(Termux)上,不需要云 VM。作者在 Reddit 上说,用它可以“合上笔记本,带去别处再打开,自动安全地接着跑”。
-
VerySmallWoods:IndexedDbStorage:Pi Durable 加了浏览器存储适配器,可以做浏览器里的研究助手、可恢复的多步骤工作流。评论认为这适合纯客户端优先的 agent 应用。
-
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 如何限制失控的花费,以及“副作用已发生但没来得及记录”的情况怎么处理。
其他值得看的:
- Cloudflare(Matt Carey):
npm i agentsv0.26.0 正式支持 Pi 跑在 Durable Object 上,用的是 Pi 的 harness loop 而不是 Cloudflare 自己的 Think。评论里有人总结:“一个进程持有一个存储,正好对应一个 DO;执行环境是独立接口,沙箱容器死了不会带走对话。” Ryan Dahl 回复 Deno 的 celld 也有 Pi 示例。 - elvis(@omarsar0):用 Pi Durable 很快做出一个类似 OpenAI Dots 的主动式个人 agent。功能包括定时任务、等待审批、每个 Space 一个 Linux 桌面供它操作、记忆存在 durable document 里跨 Space 共享,进程杀掉后能接着跑。
- Daniel Griesser 的 Ultimate:基于 Pi Durable 的自扩展 harness。coordinator 带 worker / reviewer / scout 子 agent,每个功能一个 worktree,lander agent 负责跑测试、解冲突、合并。运行中热重载自己的核心。agent 之间可以留“note”(不触发 turn 的消息)。所有对话、子 agent 的每个动作都有记录,可以让它回头分析失败的工具调用。他说之前觉得别的 durability 层太复杂、耦合太深,Pi Durable 在复杂度和 API 之间取得了平衡。
- 小墨同学(中文社区):发布一周后的社区玩法:PiDurableKit(Swift 封装,跑在 JavaScriptCore,iOS App 可直接接入)、Rivet Actors 升级到 pi-durable(每实例约 1.3MB 内存、毫秒级启动、空闲自动休眠)、核心整个跑在浏览器里(外层 Kotlin 托管执行环境做成 WebView 应用)、号召自己做 Grok Bot、durable codemode(当时 Mario 说可能会做,现在 README 里已有可跨重启恢复的 Code Mode)。评论里 @LilTea_eth 的质疑值得注意:“1.3MB/实例只能证明启动成本低,不能证明长期任务可控”,建议拿真实任务连续跑 compaction、跨客户端接管、长时间空闲,看 checkpoint 会不会膨胀、旧状态会不会覆盖新状态。
和 OpenCode 2 对比
OpenCode 2(anomalyco/opencode v2.1.3)也有崩溃恢复,但粒度是整个 turn,不是每个 task。以下基于源码 packages/core/src/session/execution.ts 和 session/execution/restart.ts。
OpenCode 2 怎么做
- turn 级的持久标记(claim):turn 开始时,在写“started”事件的同一个 SQLite 事务里给 session 打上“进行中”标记(
time_suspended)。只有终态事件(完成、失败、用户中断)会清掉它;正常关机故意保留。所以崩溃、SIGKILL、被驱逐、正常重启,留下的痕迹都一样。源码注释原话:recovery "is a property of the database, never of a shutdown hook"。 - 启动时扫描恢复:
SessionRestart.resumeSuspendedSessions找出所有带标记的 session,插入一条合成消息 “The server restarted while you were working. Continue from where you left off without repeating completed work.”,然后重新跑 agent 循环。managed server 启动时自动调用,嵌入方可以自己调。 - 防崩溃死循环:持久化的
resume_attempts计数在每次恢复前先 +1,超过 10 次(DEFAULT_MAX_ATTEMPTS)就把这个 turn 标成失败,“interrupted repeatedly and will not be resumed automatically”。没有 parked 状态,也没有retryTask()这样的人工重试入口。 - 后台任务:重启时还在跑的后台 shell 报告为 “Command cancelled because the server restarted”;后台子 agent 本身是子 session,按同样方式恢复。
- 其他持久化能力:持久收件箱 + 客户端指定消息 id(幂等提交,相当于 Pi 的
requestId)、带序号可续读的事件日志、重启不断的持久终端、在 workerd 上用 DO storage。
和 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 手动接回,没有自动恢复。
- transcript 是追加写的 JSONL(
packages/core/src/services/transcript/append-channel.ts):每个 transcript 文件有一个有序追加队列,默认攒 100ms 或 1MB 写一次(O_APPEND),写失败会回滚到上一个边界,不会留下半行。没有 fsync,所以进程崩溃时最多丢最后约 100ms 的缓冲;机器断电时丢多少取决于 OS 页缓存。 - resume 时直接丢掉没有结果的工具调用(
transcript/resume-projector.ts的filterUnresolvedToolUses):assistant 消息里有tool_use但没有对应tool_result的块会被删掉。模型看不到“我当时正在调这个工具”,也不知道它可能已经执行过一半。这和 Pi 的“以interrupted返回给模型、附上已提交输出”正好相反,也比 OpenCode 2 的“提示模型重启过、别重复”信息更少。 - 没有“进行中 turn”的持久标记:transcript 里看不出崩溃时是否有 turn 在跑,所以也没有启动时的扫描、自动续跑、崩溃次数上限。
- 后台子 agent 有状态文件,但只做对账(
agents/agent-task-runtime.ts):每个后台 agent 任务写一个task-<id>.json。reconcileAgentTaskRecords发现记录还是running但所属执行已不存在时,把它改成interrupted(“The process that owned this subagent task is no longer running.”),不会续跑。 - Workflow 有 journal,是最接近 Pi Durable 的部分(
workflows/workflow-journal.ts):每次agent()调用记录started/event/result,key 由前一个 key 加本次调用的 prompt/options 哈希链式算出。用resumeFromRunId重跑时,前缀上没改过的调用直接返回缓存结果,第一个没命中的调用之后全部重新执行。但它要模型或用户显式重新调用 Workflow 工具,不是崩溃后自动恢复;粒度是子 agent,不是工具调用。 - 退出路径有收尾,但只覆盖正常退出:
cli/src/utils/cleanup.ts处理 SIGINT / SIGHUP / SIGTERM / TTY 断开,thread-manager/thread-session/turn/backgroundWindDown.ts在会话关闭前等后台任务、发出task_notification{status:'stopped'}。SIGKILL、OOM、宿主被杀时这些都不会跑,SDK 侧看到的后台任务会一直停在 running。 - daemon 模式下也是单进程:
threadManager+threadSession是“单进程多会话管理器”(thread-manager/AGENTS.md),SDK / ACP / Remote Control 只是协议胶水。一个进程挂了,它上面所有会话一起停。
| 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 机制。
-
transcript 写入:和 qodercli 几乎一样,JSONL 追加,
FLUSH_INTERVAL_MS = 100批量刷盘(transcript writer 类,chunk-0etknh8v.js)。多了tornTailToSeal,下次打开时修补崩溃留下的半行。fsync 只在原子写文件的工具函数里出现(chunk-6y37dffm.js),transcript 追加路径没看到。云端会话(CLAUDE_CODE_REMOTE)还会把事件写到服务端(remoteIngressUrl),worker 挂了由新 worker 接手。 -
判定“turn 是否被打断”:resume 时从 transcript 末尾往回分类,结果是
none(正常结束、用户主动停止、API 报错终止、达到 max turns 等)、interrupted_turn或interrupted_prompt(用户输入后还没开始回答)。正常关机时会在最后一条 user 消息上打interruptedByShutdown标记,用来区分“关机打断”和“崩溃”。 -
中断的工具调用补合成结果,不删除:有
tool_use没有tool_result的调用,会补一条is_error的 tool_result(toolDenialKind: "interrupted"),内容是:[Tool call interrupted: the session ended before this call's result was recorded, so its outcome is unknown. Check whether it took effect before relying on it or running it again.]
如果会话是从另一个会话复制过来的,用另一句:结果“不在这份副本里”,调用可能已完成、还在跑、或根本没跑。这正是 qodercli 缺的那一步,也比 OpenCode 2 的提示更具体:它针对每个调用告诉模型“先检查再重试”。
-
自动续跑:判定为
interrupted_turn时追加一条 meta 消息 “Continue from where you left off.”(可用CLAUDE_CODE_RESUME_PROMPT改),交互式 resume(repl_restore)和-p模式(print)都有这条路径的埋点。interrupted_prompt则重新提交那条用户输入。是否不经用户确认直接续跑由CLAUDE_CODE_RESUME_INTERRUPTED_TURN(或宿主传入的同名选项)控制,默认行为从混淆代码里没法完全确认;CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS限制多旧的中断还值得续(默认 6 小时,flag 可调到 1 分钟至 30 天)。 -
挂起的权限弹窗:云端 worker 重启时,上一个 worker 留下的权限 / 对话框请求会被取消(
resumeStalePromptCancel),属于这次中断 turn 的那个请求可以被新 worker 接管(“adopted”),不用重新问用户。 -
后台任务:会话里记着运行中的后台任务;重启后它们成了孤儿,会以通知的形式告诉模型(
orphaned_background_tasks_pending_notification),部分后台 agent 记为resumable_orphaned_agents。远程执行的命令在宿主重启后会告诉模型“结果未知,可能已部分或全部执行,先检查再重复”。 -
没有的东西:没有“进行中 turn”的持久 claim,所以不会在启动时自动扫描所有会话;没有崩溃次数上限;工具执行前不记意图,没有
replay标注,也没有 journal 重放。它依赖模型读合成 tool_result 自己判断,所以本质上和 OpenCode 2 同一档(turn 级、at-least-once),只是交给模型的信息更完整。
对 qodercli 的启示:上面“建议的落地顺序”第 1 步,基本可以照 Claude Code 的做法:不删未完成的 tool_use,补一条带“结果未知、先检查”的合成 tool_result;再加“turn 是否被打断”的分类和自动续跑提示。这两步不需要动存储,收益却最直接。
2. 如果给 qodercli 实现 Pi Durable,能得到什么
直接收益
- SDK / daemon / Remote Control 场景下进程挂了能自动接着跑。 这是最大的一条。现在一个 daemon 进程挂掉,所有会话停住,宿主只能重开再让用户手动 resume;引入 task + checkpoint 后,宿主重新拉起进程,进行中的 turn、后台子 agent 都能从最后一个 checkpoint 继续,SDK 侧的 running 任务也能拿到真实终态。
- 中断的工具调用对模型可见。 先记意图再执行,崩溃后模型拿到的是“
Bash: npm publish被中断,已输出 …”,而不是这次调用凭空消失。对 deploy、git push、发消息这类工具,这是正确性问题:模型现在可能在不知情的情况下把它再跑一遍。 - 后台子 agent 能续跑,不再只是标成 interrupted。 子 agent 本身就是一个由工具 task 拥有的对话,可以按同一套机制恢复。长时间的 Workflow、多 agent 编排受益最大。
- Workflow 从“手动前缀缓存”变成“自动 journal 恢复”。 现有
WorkflowJournal的 started/result 记录、链式 key 的思路和 Pi Code Mode 的 journal 是一回事,往下补到工具调用粒度并接上自动恢复就行,这部分改动相对小。 /loop、ScheduleWakeup能真正持久。 现在的唤醒挂在进程上,进程没了就没了;有了持久睡眠(sleepUntil+ 唤醒),定时任务可以挺过重启,甚至在进程不在时由宿主唤醒。- 多端 attach。 所有 UI 状态都是已提交状态时,TUI、IDE 插件、Remote Control 可以同时看、晚加入、断线重连,
watch()直接对应现有的 SDK 消息流。
代价和风险
- 改动面大。 qodercli 的 agent loop、工具调度(
streaming-tool-executor、tool-execution-lifecycle)、transcript、后台任务各有一套生命周期,要统一成“task 状态机 + 原子 commit”,基本是重写执行内核,不是加一层。 - 存储要升级。 现在的 JSONL 批量追加没有事务、也不 fsync,撑不住“先 commit 后显示”。要么换 SQLite,要么给 JSONL 加 commit 边界和 fsync,并接受写延迟。
- 每个工具要标
replay。 shell、edit、MCP 调用大多不安全,标错(尤其是重构后忘了改)就会在恢复时重复执行副作用。外部副作用的幂等仍然要工具自己负责。 - API 不稳定。 Pi Durable 官方标为 experimental,直接依赖它就要跟着升级;更现实的做法是借鉴它的模型自己实现。
- 对单人终端用户收益有限。 本地 TUI 崩了,用户本来就在旁边,
--resume已经够用。收益集中在 SDK、daemon、Remote Control、长时间 Workflow 这些“没人盯着”的场景。
建议的落地顺序(从便宜到贵)
- resume 时不删未完成的
tool_use,改为补一条合成tool_result(“执行被中断,可能已部分完成”)。改动小,立刻修掉“模型不知情”的问题。 - 加 turn 级的持久标记 + 启动扫描 + 次数上限,做到 OpenCode 2 的水平,先覆盖 daemon / SDK。
- 后台子 agent 从“标 interrupted”改成按子会话续跑。
- 工具调用先记意图、加
replay标注;Workflow journal 下沉到工具调用粒度并自动恢复。 - 最后再考虑持久睡眠和多端 attach。
社区争议
1. 文档太难懂(r/PiCodingAgent,137 赞 58 评论)
- 楼主:大家都在猜这到底是什么。不就是状态放在和客户端分离的服务器上的有状态 agent 吗?
- 高赞评论:描述太复杂,得让 AI 解释;“读起来太 AI 了”。
- Mario 回应:README 是给 agent 读的(agent 写、人工后处理),博客是他手写的;持久化本身有一定复杂度,不知道怎么写得更短。
- 一位重度 Pi 用户读完博客仍然“clear as mud”,不知道它适合谁、做什么。
- 有人讽刺“不就是 request with retry”,Mario 和其他人反驳:重试和持久化是正交的,可以持久化而不重试,也可以重试而不持久化。
- 比较到位的解释:每次 LLM 调用和工具调用都写入数据库日志(意图、调用、结果),崩溃后回放日志恢复,复用已记录的输出而不是重新调用,你自己标注哪些工具是幂等的。这里的 “durable” 指的是 durable invocations。
2. 和 Pi 扩展不兼容
- Pi Durable 的扩展 API 和 Pi 不同,现有 Pi 扩展不能直接用,也没有 skills。有人觉得移植自己的扩展是最大的门槛。
- 也有人指出 Pi Durable 主要面向嵌入式应用:如果要把它放进产品里,需要托管、扩容、冗余、可恢复,它才真正有意义。对单人编码来说,一台 24/7 服务器 +
pi resume基本够用。
3. 是否能上生产
- 官方明确是 experimental,API 随时变。
- 有人说“官方说不是生产就绪,别用”;也有人反问“没人用怎么变稳定”。
- 已在用的人(Pi Pocket 作者、pi os 作者)反馈持久化部分很稳。
4. 迁移建议(r/AI_Agents)
- Python 架构的 B2B SaaS 要不要迁到 Pi Durable?回复的共识是:先把 SQLite 换成 Postgres,把关键业务写入做幂等;只有当工作流真的需要等很久(人工审批、外部回调、其他 agent)时,再引入 durable runtime。
我的判断
- 适合:要嵌入产品的 agent(多租户、托管、多端)、长时间运行或需要定时/睡眠的个人助手、多人协作 agent、跑在受限环境(浏览器、手机、DO)里的 agent,以及想在 agent 执行状态之上做观测和调试工具的场景。
- 不太需要:单人在终端里用 Pi 写代码、已有稳定 24/7 机器。Pi 1.0 本身就够了。
- 要自己负责的:外部副作用的幂等性、
replay: "safe"标注的正确性、工具执行侧的权限控制、长跑的成本上限、API 不稳定带来的升级成本。 - 趋势:Pi Durable、Vercel durable-harness、Cloudflare agents、Rivet 在同一个月扎堆出现,大家都在把“intent → result 日志 + 可恢复 task”变成 agent harness 的标配。Pi Durable 的不同在于体量小、可读、从里到外都可插拔。OpenCode 2 走的是更轻的路线:turn 级标记 + 重启后让模型接着做,没有工具级的意图日志。
参考链接
X 书签
- Superlinear:4 things worth building with Pi Durable + Cloudflare DO — https://x.com/superlinear_fm/status/2113258339974926415
- Pi Pocket 新版展示 — https://x.com/lovelylogicss/status/2114469016773566785
- VerySmallWoods:IndexedDbStorage — https://x.com/verysmallwoods/status/2113060652658954502
- Vercel:Introducing durable-harness — https://x.com/vercel/status/2112653833382027729
官方
- 博客:Pi Durable(Earendil,2026-10-01)— https://earendil.com/posts/pi-durable/
- Pi 1.0 发布 — https://earendil.com/posts/pi-1-0/
- README — https://github.com/earendil-works/pi/blob/main/packages/durable/README.md
- 规范 spec.md — https://github.com/earendil-works/pi/blob/main/packages/durable/docs/spec.md
- 示例 — https://github.com/earendil-works/pi/tree/main/packages/durable/test/examples
- Release v1.4.0 — https://github.com/earendil-works/pi/releases/tag/v1.4.0
相关项目与文章
- Vercel 博客:Making every harness durable — https://vercel.com/blog/making-every-harness-durable
- vercel-labs/durable-harness — https://github.com/vercel-labs/durable-harness
- Pi Pocket — https://github.com/TannerMidd/pi-pocket
- Daniel Griesser:Ultimate — https://danielgriesser.com/posts/ultimate/
- disler/durable-pi — https://github.com/disler/durable-pi
- disler/pi-durable-news-agent — https://github.com/disler/pi-durable-news-agent
- Terrarium pi_durable 示例 — https://github.com/terrarium-sh/terrarium_examples/tree/main/official/pi_durable
- Superlinear 播客(YouTube)— https://youtube.com/watch?v=BB84EzZjF3U
OpenCode 2(v2.1.3 源码)
- turn 级 claim 与终态释放 — https://github.com/anomalyco/opencode/blob/v2.1.3/packages/core/src/session/execution.ts
- 重启恢复与
resume_attempts上限 — https://github.com/anomalyco/opencode/blob/v2.1.3/packages/core/src/session/execution/restart.ts - claim / release / countResume — https://github.com/anomalyco/opencode/blob/v2.1.3/packages/core/src/session/store.ts
- 工具中断处理 — https://github.com/anomalyco/opencode/blob/v2.1.3/packages/core/src/session/runner/step.ts
qodercli(本地源码,~/Projects/qodercli)
- transcript 追加队列:
packages/core/src/services/transcript/append-channel.ts - resume 时过滤未完成工具调用:
packages/core/src/services/transcript/resume-projector.ts - 后台 agent 任务记录与对账:
packages/core/src/agents/agent-task-runtime.ts - Workflow journal:
packages/core/src/workflows/workflow-journal.ts、workflow-tool.ts - 退出收尾:
packages/cli/src/utils/cleanup.ts、packages/cli/src/thread-manager/thread-session/turn/backgroundWindDown.ts
Claude Code 2.1.306(本地解包产物,~/Projects/claude-code-versions/versions/2.1.306-unbundled/extracted)
- transcript writer、turn 中断判定、自动续跑:
chunk-0etknh8v.js(搜FLUSH_INTERVAL_MS、interrupted_turn、Continue from where you left off) - 合成 tool_result 文案:
chunk-rgk39qss.js(搜Tool call interrupted) - 云端 worker 恢复、挂起权限请求、孤儿后台任务:
chunk-26csean4.js(搜resumeStalePromptCancel、running_background_tasks)
X 讨论
- Matt Carey:Pi on Durable Objects(agents v0.26.0)— https://x.com/mattzcarey/status/2106082034611572811
- elvis:My Pi 个人 agent — https://x.com/omarsar0/status/2107232293366505651
- Caleb:Pi Durable 技术手册 — https://x.com/calebfahlgren/status/2107199330926899652
- Alejandro AO:教程视频 — https://x.com/_alejandroao/status/2112466641464267203
- Luis Catacora:What is Pi Durable? — https://x.com/lucataco/status/2106953813907091579
- Mario 推荐上面这个解释 — https://x.com/badlogicgames/status/2107025576771072277
- 小墨同学:一周社区玩法 — https://x.com/xiaomovps/status/2108370725623181408
- 小墨同学:从入门到精通(长文)— https://x.com/xiaomovps/status/2109089837097853220
- Rui Carmo:pi-durable in Obsidian — https://x.com/rcarmo/status/2107819123724161205
- Miguel Ríos:pi-durable-agent — https://x.com/MiguelriosEN/status/2113727904882233641
- Daniel Griesser — https://x.com/DanielGri/status/2113544750972194852
- Why did you have to make Pi Durable's description so confusing? — https://www.reddit.com/r/PiCodingAgent/comments/1x9zmbo/
- Has anyone experimented with Pi Durable? — https://www.reddit.com/r/PiCodingAgent/comments/1x9dd2m/
- Is migrating my existing Python agent architecture to Pi-Durable a good idea? — https://www.reddit.com/r/AI_Agents/comments/1x8jtfl/
- Pi Durable: an experimental harness for long-running agents — https://www.reddit.com/r/LLMDevs/comments/1wyx4ec/
- Pi Pocket: use Pi from your phone or any browser — https://www.reddit.com/r/PiCodingAgent/comments/1wyl7f7/
- Introducing Terrarium — https://www.reddit.com/r/PiCodingAgent/comments/1xf8pea/
- I've been using Pi Durable a ton — https://www.reddit.com/r/PiCodingAgent/comments/1x7n1f4/