Frontier Now
搜索

智能体框架#代码智能体#运行时

durable-harness：编程 Agent 崩溃恢复，会话从日志续跑

durable-harness 是一套编程 Agent 崩溃恢复方案：会话存进事件日志，崩溃后接着跑，适合用 Pi、OpenCode 或 fx 的团队。

作者
Frontier Now 编辑部
发布

项目资料

GitHub Ecosystem
仓库地址github.com/vercel-labs/durable-harness
许可证
Apache-2.0
主语言
TypeScript
星标
90
核查时间
2026-10-21

以上快照资料以核查当日为准，可能随版本或运营策略变化。

durable-harness 的生成封面卡（不是仓库截图）：会话写入事件日志，崩溃后从日志续跑

编程 Agent 崩溃恢复的第一步，是搞清楚未完成的回合存在哪里：Vercel 的文档写道，多数 harness 把正在进行的回合放在运行它的进程内存里，进程一死，回合也跟着消失。durable-harness 是 vercel-labs 组织开源的项目（Apache-2.0），它让 Pi、OpenCode、fx、Claude Code 和 Codex 变成能从崩溃中恢复的编程 Agent，运行在 Workflow SDK 的 World 上。每个会话是一次 workflow run，对话、正在进行的回合，以及每次模型调用和工具调用，都写进这次运行的事件日志，所以进程崩溃后，另一台机器可以从日志接着跑。微信公众号「AI工程化」在 10 月 21 日介绍过它。

核心功能

durable-harness 的核心，是让会话在崩溃后接着跑，同时不让不能重复的工具执行两次。

  • 崩溃后从日志续跑：每个回合在 Vercel Queues 里对应一条消息。函数挂掉后，新函数读取日志，从断点继续；日志里已有结果的调用直接读回，不再执行。
  • 按工具设定重放规则：工具标成 safe 或 never。safe 的工具（比如只读查询）崩溃后可以重跑：Pi 会重跑，Claude Code、Codex 和 OpenCode 则告诉模型它可以安全地重复调用。never 的工具（比如退款或发邮件）从不执行第二次，模型只会被告知这次调用「可能执行过，也可能没有」，它可以先查再决定。
  • 哪些 harness 要 Sandbox：Pi、OpenCode 和 fx 跑在你自己的函数里。Claude Code 和 Codex 只能跑在每个会话自己的 Vercel Sandbox 里，自托管也一样，文档给的理由是它们是为单个用户设计、状态存在磁盘上的命令行工具。
  • 三种文件位置：virtual() 把文件存进会话日志，跟着会话走；virtual({ durable: false }) 放在内存里，每个回合结束就清空；sandbox() 把命令交给会话自己的 Vercel Sandbox，文件放在 Drive 上。
  • 可替换的存储：World 是 Workflow SDK 的存储和队列接口。本地开发默认写进 .workflow-data 目录，部署到 Vercel 时会话出现在 Agent Runs 里，自托管可以换成 Postgres World。
  • Documents：类型化的 JSON 状态，比如待办清单，和会话一起存在日志里，单个文档不超过 64 KB。
harnessREADME 里的包名运行位置
Pidurable-harness/pi-durable（推荐）或 durable-harness/pi你的函数，文件在虚拟工作区或 Sandbox
OpenCodedurable-harness/opencode你的函数，文件在虚拟工作区或 Sandbox
fxdurable-harness/fx，agent 来自 libfx你的函数，文件在虚拟工作区或 Sandbox
Claude Codedurable-harness/claude-code仅 Vercel Sandbox（实验性）
Codexdurable-harness/codex仅 Vercel Sandbox（实验性）

包名取自 README，运行位置取自 Vercel 文档的 harness 选择表。

典型使用场景

durable-harness 最适合的情况是：回合已经做了实际工作，进程却在中途死掉。

  • 给客服 Agent 配退款工具的团队：退款工具标成 never。文档举过一个例子：函数在写回复时挂掉，新函数只重跑被打断的模型调用，客户只被退款一次。
  • 在网页里放编程 Agent 的产品团队：回合可以超过单个函数的最长运行时间，断开的客户端重连后，会接着看到仍在运行的回合。
  • 想把会话存进自己数据库的团队：用 Postgres World，需要 @workflow/world-postgres 5.0.4 或更新版本、Node.js 22 或更高版本，并设置 WORKFLOW_TARGET_WORLD 和 WORKFLOW_POSTGRES_URL。部署在 Vercel 之外时，模型调用还要 AI_GATEWAY_API_KEY。

快速上手

README 的例子是 Pi 加 Next.js，先装依赖：

npm install durable-harness @earendil-works/pi-durable @earendil-works/chord @earendil-works/pi-ai just-bash

接着加三个文件：lib/agent.ts 用 Harness.open 打开 Pi 的 durable Harness；app/api/chat/route.ts 导出 chatRoute；next.config.ts 用 withDurableHarness 包住配置。本地开发不需要额外配置。README 没有给出运行后的界面或输出，authorize 只留了一行注释；文档说，生产环境里没有 authorize 的聊天路由会对每个请求返回 401。

小结

durable-harness 适合已经在用 Pi、OpenCode 或 fx、又希望长回合能扛住崩溃的团队，尤其是愿意用 Next.js 和 Vercel 部署，或能自己维护 Postgres 的团队。它不适合两类人：一是需要稳定 API 的生产系统，README 写明它实验性、版本是 0.0.x，npm 上最新是 0.0.1-beta.6；二是想在自己服务器上跑 Claude Code 或 Codex、却不接 Vercel Sandbox 的人，因为文档说这两者只能跑在 Sandbox 里。

限制也要先知道。Sandbox 默认允许所有出站流量，network: 'deny-all' 可以关掉；它默认最长运行 4 小时，模型花费默认没有上限，要用 sandbox({ budget }) 设置。Pi（durable-harness/pi）和 OpenCode 的回合先在聊天请求里跑 60 秒，交接时还在运行的命令会被停下、不会重跑，开头的长安装或构建可能因此被切断，文档把它列为 Vercel Queues 当前的限制。虚拟工作区约 500 个文件，没有网络，也没有 node、python 这类真实二进制。文档还说，Postgres World 只是参考实现，不认证路由、不加密数据。

许可证是 Apache-2.0，主要语言是 TypeScript。仓库 2026-10-16 才创建，截至 2026-10-21 有 90 颗星、6 个未关闭的 issue 或 PR，最近一次推送在 2026-10-19。想找同时调度多个编程 Agent 的界面，可以看 Paseo；durable-harness 管的是单个会话崩溃后能否接着跑。

我们读了 README、LICENSE、仓库元数据、npm 包信息和 Vercel 官方文档，没有安装或运行它。README 里没有性能数据、界面截图、运行输出和价格，这篇文章也就不包含这些内容。