从 Pi Durable 看 Harness 的演进

在常见的 Harness 架构里（比如 pi coding agent），记忆、脑子、手都被塞进同一个 Node.js 进程，而且强依赖一台 VM。

Pi Durable 改变了这个设计。

这篇文章从 Durable 出发，拆一拆 Harness 的演进：Durable 解决了什么，Durable 之外 pi 还有哪些变化，最后试着设计一套能 scale up 的 long-time Harness 架构，以及它对我们业务的影响。

先把 Harness 拆开

Harness 是一个复杂的概念，很多地方直接把它定义为「模型之外的一切」。这个定义很粗糙，是一句废话。

在 Pi 这个场景，我们来进一步拆分：

• 持久化系统：agent 运行必须依赖的持久化文件，包括 transcript、skill 等

• agent loop：一个 Node.js 进程

• execution environment：Filesystem + shell（bash tool）

这三个组件可以类比为 Harness 的记忆、脑子、手。

在常见的 Harness 架构中（pi coding agent），这三部分都被耦合在一个 Node.js 进程内，且对 VM 是强依赖。Durable 改变了这个设计，带来了很多改变。

Why durable？

持久化系统与 OS Filesystem 解耦

在 Durable 中，Pi 把持久化系统从 Node 中拆出去，transcript（sessionLog）以 SQLite 的方式存储。这解决了两个问题：

• 持久化系统，也就是启动、恢复 session 需要的前置依赖，都与 Filesystem 解耦。这直接减少了启动 Agent 的一个前置要求：「带有 FS 的 VM」。 agent 可以跑在更多的云服务上，大幅降低开销

• 解决了之前 session.jsonl 的内存随单一会话的累计不断膨胀的问题

执行环境与操作系统解耦

在 agent 中，shell tool 是必备的，agent 能通过 shell 完成相当大一部分的工作内容。但是代价是什么？依赖一个完整的操作系统环境。

Durable 对依赖 FS 和 bash 的 tool 做了特殊处理，同时提供了一个 env package，为执行环境的隔离提供了基本的套件：

• agent loop 完全不依赖 FS 和 shell，可以部署在更丰富的计算节点上，比如 serverless

• 可以做到一个 loop 在多套环境中切换，且 pi 的套件已经做好了各种边缘情况处理，不会出现幻觉等问题

对业务的影响： 在 personal agent 中，有相当一部分任务通过不依赖执行环境的 tool 和 MCP 配置就可以完成。比如相当一部分调研任务，只需要 web search 和 RAG MCP 等配合即可。

假设有 70% 的场景是这种模式，我们就可以只用一个 Node 进程承接用户需求，极大节省硬件资源。

无损状态恢复

Durable 重新设计了 Harness 内的状态模型：严格幂等、写入优先。 它提供了 doc API，允许开发者将拓展状态写入 transcript，作为持久化状态。

• 所有状态存储外置，且能无损恢复，使我们的计算节点调度策略更加灵活

• 像 subagent、HITL 这种涉及关键状态的场景，有了更灵活、容错率更大的处理方式，能无损故障恢复

Out of durable

Durable 作为一个独立的 package 发布，原本 pi coding agent 的包依然保留。在 Durable 之外，pi 本身也经历了一个大版本的变更，发生了很多变化，而这些变化在 Durable 和 pi coding agent 中是通用的。

MCP Support

在新版本的 pi 中，MCP 得到了 pi 官方的原生支持，这与后面介绍的 codemode 有很大关联。

• 可以去掉我们原有的第三方 MCP 方案

• 作者对 MCP server 的实现提出了几点建议，值得我们学习：结构化返回 稳定的数据结构：不能因为实际返回的数据类型、数量不同，就返回不同的数据结构 MCP 不支持大型二进制数据，这限制了很多有意思的实现

codemode

模型可以在 pi 中写一段受信任的 JS（QuickJS 引擎）来调用工具。

为什么 codemode 有效？现在的 LLM 经过大量训练后非常擅长使用 bash，能通过脚本的方式高效实现一系列操作。但有些能力是 bash 做不到的，比如 read image、Linear MCP 操作。

模型完全有可能需要批量调度工具来完成一次任务。在原有架构中，agent 每个 turn 只能调用几个 tool，然后等待返回，再开启下一个 turn。无论从时间角度还是 cache read 角度（每个 turn 都会在 context 尾部 append 一批 tool return），这都是比较糟糕的模式。

引入 codemode 后，以 Linear 任务为例：假如我让模型总结这个月的 ticket 完成情况，模型会先做一轮试探性的调用，了解 API 和 return schema，然后直接写好一大段 JS，并发调度 tool，在几个 turn 内完成任务。

• codemode 可以节省上下文，适合我们的 RAG MCP 和后续引入的更加复杂的 MCP

• 整体上也是更高效的一种方式

• codemode 已在 pi coding agent 中支持，Durable 还没完全支持

server & client & protocol

Durable 跑通之后，下一个问题是：Harness 跑在哪、谁来看。server & client & protocol 就是把「跑」和「看」拆开：worker 是 loop & execution env，配合 server 能解决很多问题。

• **protocol 只是信封，不干活：**packages/[email protected] CBOR + 4 字节长度 组帧，hello{version=8, serverId} 握手 路由 {serverId/sessionId/attachmentId} payload 全是不透明的 strict-JSON，语义丢给 chord 限 16MiB，无鉴权、无兼容保证

• **server/client 才是干活的：**packages/server + packages/[email protected] unix transport，默认 ~/.pi/server server 管 Session 目录 + worker 生命周期，attach/detach 下发 live 路由，durable 会话 stays local to worker coding-agent/rpc-entry 是打进 dist/bundle 的编程入口

对我们业务的影响： 多人多端。server 常驻承接长会话 + sqlite 恢复，client 按需 attach 看同一份 viewState，presentation 可以是我们实现的任意 client。

计算和展示分离后，调度更像 web 服务，而不是和 VM 绑死。 这也允许我们做更多产品上的尝试，比如共享 session、public session。

试着设计一套能 scale up 的 long-time Harness 架构

这套架构有以下特点：

• 持久化部分是独立的 database

• 一个 bot 的默认启动条件是一个单独的 agent loop，即一个 Node.js 进程。这个进程理论上可以灵活调度、销毁、恢复

• bot 默认没有 fs 和 shell 工具。 这也符合我们之前的业务设计：主 loop 只承载较轻量的任务。单 loop + MCP 仍然可以完成非常多的工作（预期至少承接 50% 以上的任务）

• fs + shell 和 subagent 绑定，承载中大型任务，用完销毁。infra 层面考虑准备一批空白的、资源分配低的 sandbox 实例供灵活调度。subagent 的 transcripts 可以持久化，其他内容均不需要持久化

• 主 loop 原有的持久化需求，由 artifact MCP + truth fs 承接。 memory 状态也外置，是单独的服务

这套架构的目标是：在产品体验不变的情况下，硬件资源消耗低一个数量级。正常的 VM 架构，以大部分公司的硬件资源，显然是无法承载的。