---
title: "Pi Durable"
author: "陈成"
author_url: "https://research.sorrycc.dev/@sorrycc"
question: "Pi Durable 是什么，崩溃恢复怎么做？OpenCode 2、Claude Code、qodercli 各自怎么处理崩溃，qodercli 引入它有什么收益？"
url: "https://research.sorrycc.dev/@sorrycc/pi-durable"
emoji: "🔁"
published: 2026-10-27T14:58:23Z
updated: 2026-10-27T14:58:22Z
version: 2
cite: "https://research.sorrycc.dev/@sorrycc/pi-durable.bib"
---

# Pi Durable 调研总结

By [陈成](https://research.sorrycc.dev/@sorrycc) · 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 冻结了老架构，正是因为新架构必然带来破坏性变更。

## 核心概念

```mermaid
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 的打包。对话只存扩展名，不存代码，所以可以热替换。

一次输入被回答的过程：

```mermaid
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 唤醒。

```mermaid
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 上实现。

## 生态与玩法（按热度和代表性）

```mermaid
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 如何限制失控的花费，以及“副作用已发生但没来得及记录”的情况怎么处理。

**其他值得看的：**

- **Cloudflare（Matt Carey）**：`npm i agents` v0.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，能得到什么

**直接收益**

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 消息流。

**代价和风险**

- **改动面大。** 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 这些“没人盯着”的场景。

**建议的落地顺序**（从便宜到贵）

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 评论）

- 楼主：大家都在猜这到底是什么。不就是状态放在和客户端分离的服务器上的有状态 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

**Reddit**
- 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/
