持久运行时 —— 把 Agent Loop 拆成状态机
你让它读了七个文件、改了三个,第八个文件刚读到一半。AI 正在调工具。
然后进程没了。OOM、部署、Ctrl-C、笔记本合盖——哪一种都行,结果一样:
内存里那半个对话没了。用户重开,问的是同一句话,Agent 从头再来一遍,
前七个文件的读取白花,改过的三个文件不知道改到哪了。
M03 讲 runLoop 时,里面有两个 while:内层管模型与工具的锯齿,外层管续命。
当时有个前提一直没摆到台面上——进程还在跑。
packages/durable 的全部工作,是把这句话反过来:进程随时会消失,对话还得接着走。
33,728 行,harness/ 一个目录就占了 11,332 行。这不是会话存储包,
是一个完整的持久运行时。
它要解决的是同一种问题在每一步上的版本:
你没法让进程不死。你只能让每一步的进度都已经落在磁盘上, 死在哪一步都只丢那一步。
下面每一个设计——六个状态、completing、handOver、提交意图再执行——
都是在为这句话补一个漏洞。
零、读这章之前,你需要先知道一件事
三个类型层手法:Extract<A, B> = 从联合类型 A 里挑出能塞进 B 的那几支;
brand(打标记的类型)= 给 string 盖个看不见的章,让它和别的 string 不能互换;
never = 一个值都没有的类型,用来兜底"这里根本不该发生"。
没有它会怎样:把 Extract 当"过滤字符串"用,类型悄悄退化成 string,
编译不报错,直到运行时两个 id 串了才暴露。
本书哪里用到:§三 那 12 行最小片段;删掉它看错误信息怎么变。
一、三个包的分工
先把最容易搞混的关系钉死。
| 包 | 层 | 依赖 pi-agent-core |
循环在哪 |
|---|---|---|---|
agent |
无状态循环 | — | agent-loop.ts 的 runLoop |
durable |
有状态运行时 | 否 | 任务状态机,没有 while |
coding-agent |
CLI 宿主 | 是 | 调 agent 的 runLoop |
注意第二行的两个事实叠在一起:它有状态,但不依赖那个有状态的内核。 这不是遗漏,是整章要解释的那条替代路线。
1.1 两条互不相交的依赖线
看 coding-agent/package.json:44-45:依赖里有 pi-agent-core 和 pi-ai,
没有 pi-durable。
再看 durable/package.json 的 dependencies:
@earendil-works/chord 可持久化原语(JSON、delta、watch)@earendil-works/pi-ai 模型调用@earendil-works/pi-codemode 沙箱脚本@earendil-works/pi-schema schema 校验@earendil-works/pi-telemetry 追踪diff / photon 文本 diff / 图片解码没有 pi-agent-core。
这是 M10 那个"两代实现"的技术底:CLI 那一条线用 agent 的循环 + 自己写的
SessionManager;durable 这一条线两者都不用,它用 pi-ai 直接发请求,
自己把循环拆成了状态机。
1.2 为什么可以不用 runLoop
runLoop 的价值是"管理锯齿":模型给出 tool call,跑工具,把结果塞回去,再问一遍。
这件事在任何进程里都需要。
但"管理锯齿"有两种写法:
- 栈上的循环:
while的进度是局部变量,进程死了就没了。 - 状态机:每一步的进度是一次提交,进程死了从最后一步重来。
durable 选后者。所以它的循环不是一个函数,是一组phase 处理函数加一个调度器。
你在 generation.ts 里搜不到 while (hasMoreToolCalls),搜到的是 phase: "tools"。
二、目录地图
durable/src/ 一共 33,728 行,按目录切成十块:
| 目录 | 文件 | 行数 | 职责 |
|---|---|---|---|
harness/ |
24 | 11,332 | 运行时:调度器、四个内置任务、注册表、视图 |
storage/ |
19 | 5,769 | 四种后端 + 共享 SQL 层 |
session/ |
7 | 4,628 | 提交内核(M10 讲过) |
testing/ |
8 | 3,409 | 存储一致性测试套件 |
env/ |
5 | 2,319 | 执行环境抽象(文件、进程、监听) |
codemode/ |
5 | 1,710 | 沙箱脚本执行 |
tools/ |
11 | 1,596 | 内置工具实现 |
images/ |
6 | 396 | 图片解码与缩放 |
tool-search/ |
2 | 102 | 延迟工具加载 |
| 根层 | 10 | 2,467 | types / documents / entries / errors / search 等 |
harness/ 里最重的四个文件:scheduler.ts(3,159)、generation.ts(1,188)、
tool.ts(1,147)、types.ts(1,080)。后面几节基本围着它们转。
2.1 harness/ 的 24 个文件分成五组
只记住"最重的四个"不够用。真正读代码时要能在一次跳转内找到目标,所以按职责分:
| 组 | 代表文件 | 行数合计 |
|---|---|---|
| 调度内核 | scheduler.ts |
3,159 |
| 内置任务 | generation / tool / compaction |
2,836 |
| 状态与文档 | types / live / agent / inbox |
2,186 |
| 视图与投影 | view / context / task-graph / transcript |
1,567 |
| 定义与胶水 | harness / submissions / prompt / registry |
1,584 |
五行加起来 11,332,就是整个 harness/。两个细节:
- 状态与文档那组还有两个几十行的尾巴:
usage.ts(73) 和provider.ts(40), 各自只定义一个文档。它们行数少,但都是内置契约的一部分。 - 视图与投影那组是"读侧"。
context.ts拼模型输入,view.ts拼给人看的快照,task-graph.ts算父子关系。这一组全是纯读:不提交、不改状态,因此可以随时重算。
2.2 根层那四个不到 250 行的文件
大包容易让人只盯大头。durable 的四个小文件反而定义了整个包的形状:
| 文件 | 行 | 定义了什么 |
|---|---|---|
ids.ts |
12 | 带 brand 的数字 ID,避免 ConversationId 和 TaskId 混用 |
tasks.ts |
9 | defineTask,Task 就是 { definition } 一个字段 |
entries.ts |
35 | 六个内置 entry kind(M10 §8.1) |
documents.ts |
209 | defineDoc / defineDocFamily 的四个重载 |
tasks.ts 只有九行,值得看一眼:
// tasks.ts:4-9export function defineTask< I, S extends { phase: string }, R, H extends object = object,>(definition: TaskDefinition<I, S, R, H>): Task<I, S, R, H> { return { definition };}类型参数有三个硬约束:S 必须有 phase 字段,R 是结果类型,H 是钩子形状。
"必须有 phase"这一条,就是"任务即状态机"的类型级表达。
三、三个内核概念
entry、document、task。M10 讲了前两个,这里只补必要的差别,重点在第三个。
3.1 entry:不可变的历史
EntryRecord(types.ts:458-473)M10 拆过。这一章只需要记住一句话:
entry 只追加,永远不改。所以它是"发生过什么"的唯一权威。
3.2 document:可以被改写的状态
defineDoc(documents.ts:39-80)有四个重载,切的是三个维度:
| 维度 | 取值 | 含义 |
|---|---|---|
| 作用域 | session / 会话 / task |
谁拥有它,跟着谁销毁 |
| 历史 | latest / rewindable |
只留最新值,还是每个提交点都能回去 |
| 分叉 | asOf / current |
分叉时拷"那一刻的值"还是"现在的值" |
内置文档一共九个 kind(durable/src 下 8 个文件,codemode.ts 里有三个)。下面五个是最关键的,各自语义设置值得列一张表:
| 文档 | 定义在 | history | fork | 装什么 |
|---|---|---|---|---|
pi.agent |
agent.ts |
rewindable | asOf | 模型、思考等级、工具与扩展 |
pi.provider |
provider.ts |
latest | initial | provider 侧会话 id |
pi.live |
live.ts |
latest | initial | 正在跑的 generation 与工具 |
pi.inbox |
inbox.ts |
latest | initial | 排队中的提交 |
pi.usage |
usage.ts |
latest | initial | 累计花费 |
剩下四个:pi.tool.nested-call(tool.ts:118)、pi.codemode.run / .journal / .store(codemode.ts:126 / :152 / :165)——分别在后文的嵌套工具调用和 M13 的 codemode 里出场,到这里不影响理解。
注意 fork 那一列:只有 pi.agent 是 asOf。
provider 侧会话 id 分叉时必须换一个新的(README 里明说)——否则两个会话共用一个
provider 缓存,提示词缓存会互相干扰。pi.live 是"此刻在跑什么",新会话当然什么都不在跑。
只有 pi.agent 是 asOf,因为它存的是用户的选择:你从这个点分叉,
当然希望新会话继承你当时选的那个模型。
AgentDoc 是最讲究的一个(harness/agent.ts:44-52):
export const AgentDoc = defineDoc<AgentState>({ kind: "pi.agent", version: 1, scope: "conversation", history: "rewindable", fork: "asOf", initial: () => ({}), checkpointWhen: () => true,});四个字段各管一件事:
scope: "conversation":每个会话一份 agent 配置,不是全局。history: "rewindable":每次改动都留版本,所以能读到"上个月那一刻"。fork: "asOf":分叉时拷分叉点那一刻的配置,不是拷现在这个。checkpointWhen: () => true:任何改动都产生一个新版本,不合并。
checkpointWhen 是这套设计里最巧的一个钩子:它决定"这次改动要不要留一个可回读的快照"。
默认策略是按大小或时间算,而 agent 配置改一次就该记一次——所以直接返回 true。
3.3 task:第四种东西
entry 是"发生过什么",document 是"现在是什么",task 是**"接下来要做什么,做到哪了"**。
这是第一代完全没有的维度。M10 §7.2 说过:第一代的树里没有"这次调用成没成"这个概念,
所以只能在请求前补一个假的 No result provided。task 就是把那个缺口补上的类型。
TaskDefinition(types.ts:364-387)有六个字段:
export type TaskDefinition< I, S extends { phase: string }, R, H extends object,> = { readonly name: string; // 落到 TaskRecord.kind readonly version: number; // 落到 TaskRecord.version,用于迁移 initial(input: I): S; // 第一个检查点 readonly phases: { readonly [P in S["phase"]]: PhaseHandler< I, Extract<S, { phase: P }>, S, R, H>; }; abort(task, runtime, context): Promise<void>; migrate?(input, checkpoint, fromVersion): { input: I; checkpoint: S; }; readonly hooks?: H;};三件事值得单独说:
一、phases 是穷举映射。 S["phase"] 是一个字面量联合,phases 必须每个都实现。
加一个 phase 忘了写处理函数,编译期就报错。
二、每个 handler 拿到的是"窄化后的任务"。 Extract<S, { phase: P }> 把联合类型
收窄到当前 phase,于是 task.state.checkpoint 在 prepare 里就是 prepare 的形状,
不需要在每个 handler 开头写 if。
三、migrate 在预留时跑,不在启动时跑。 一个一年前的 task 要等真正轮到自己
被调度时才迁移,所以旧版本的迁移代码不会在新进程启动时集中爆掉。
3.4 TaskRuntime:handler 能碰到的全部
每个 phase handler 签名的第二个参数是 runtime(types.ts:261-361)。它是任务唯一的
"手"——除了它,handler 没有别的途径读写世界。按用途分四组:
| 组 | 方法 | 干什么 |
|---|---|---|
| 写 | commit(change, context, options?) |
唯一写入口,返回新状态或 undefined |
| 读 | entry / entries / context / getTask |
读已提交的 entry、上下文视图 |
| 编排 | waitForTask / abortOwned / sleepUntil / outcomes |
建关系和等结果 |
| 宿主 | agent / settings / models / env / hooks / report |
拿配置、跑钩子、报错 |
commit 的签名值得拄一遍(:290-297):
commit( change: (tx: Tx, current: RunningTask<I, S, R>) => NextTaskState<S, R> | undefined | Promise<NextTaskState<S, R> | undefined>, context: Context, options?: CommitOptions,): Promise<void>;三个要点:
- 回调里拿到的
current是提交那一刻的任务记录,不是 handler 开头的快照。 中间可能已经过了一轮变更线,重读一遍才对。 - 返回值是"下一个状态"。返回
undefined表示"状态不变,只写了别的"。 - 写操作全在
tx上。注释里有一条警告(:286-287):回调里只能用tx读, 用snapshot()/watchDoc()去读会排到自己持有的那条线上,永远不返回。 这是这套 API 最容易踩的一处死锁。
还有一个隐晦的约束:memo。两种签名——只读,或"没有就写、有就返回赢家"。
它是任务自己存的小值,随任务记录一起销毁,不占文档。
3.5 所有权:每个任务都得有个主人
TaskOptions.ownership 是必填字段(types.ts:406-407),注释写着
"a task always names its owner (spec §5.5)"。两种主人(:395):
export type TaskOwnership = | { readonly kind: "conversation" } | { readonly kind: "task"; readonly taskId: TaskId };- 会话拥有:顶层任务。一个 run 的
pi.generation就是这样。 - 任务拥有:子任务。一次工具调用
pi.tool被它所在那轮 generation 拥有。
所有权不是装饰字段,它决定三件事:
- 谁等谁。
waitForTask只能等自己拥有的任务(types.ts:306-310)。 - 取消怎么传播。父任务取消,意图会传给下面的普通子任务(§5.6)。
completing什么时候结束。父任务宣布结局后,要等所有普通子任务终态。
还有两个标记:
background: true:会话拥有的任务,但排除在普通空闲等待、会话取消、级联之外。 常驻的后台任务用它。abandonOnRestart: true:进程重启后就不该继续的任务。它会被打上abortReason: "restart"的标记走 abort 处理器,而不是变成orphaned。
这两个标记解决同一类问题:这个任务还要不要跟着宿主一起活。 第一代根本没有这个问题,因为它没有任务。
四、六种状态,五种结局
4.1 TaskState(types.ts:658-702)
| status | 有调用栈吗 | 什么时候离开 |
|---|---|---|
pending |
没有 | 被调度器预留 → running |
running |
有 | handler 提交新检查点 → 仍是 running;或提交等待/睡眠/结局 |
waiting |
没有 | on 里所有任务都终态 → pending |
sleeping |
没有 | 时钟到 until → pending |
completing |
没有 | 它拥有的普通子任务全部终态 → terminal |
terminal |
没有 | 永不再变 |
注意 pending 和 running 的检查点类型完全一样。运行时状态不进检查点——
这是整套设计的核心约定:检查点里只有"业务进度",没有"我现在跑到哪一行"。
4.2 TaskOutcome(types.ts:621-655)
五种结局,区分得很细:
| status | 谁写的 | 含义 |
|---|---|---|
completed |
任务自己 | 正常完成,带 result |
failed |
任务自己 | 预期内的失败,带 error |
aborted |
abort 处理器 | 被取消,走完了自己定义的清理 |
orphaned |
调度器 | 定义没了或迁移失败,这台机器上永远跑不了 |
faulted |
调度器 | 契约破了:未捕获异常,或这一轮没产生持久进展 |
orphaned 和 faulted 的区别很实用:前者是"缺东西",装上那个扩展就能继续;
后者是"代码有 bug",重试一万次也一样。诊断时先看这个字段。
4.3 completing 为什么必须存在
这是六个状态里最反直觉的一个。
任务宣布了自己的结局,但它手上还有子任务在跑。如果立刻置 terminal,
子任务结束后就没有父任务可挂结果了。所以中间插一个 completing:
outcome 已定 ──> completing ──子任务全部终态──> terminaltypes.ts:691-696 的注释写得很直白:
/** Outcome decided; becomes terminal once no ordinary owned work * below is live. Runs no more code. */"不再跑代码,但也不许收摊"——这一条正是第一代树结构做不出来的状态。 树里没有"父子任务的存活计数"这种东西。
4.4 为什么 finish 必须和 drain 分成两步
这是上面那条规则在代码里的直接后果,也是读 generation.ts 七个 phase 时最容易疑惑的地方:
afterRun 钩子跑完就该结束了,何必再有一个 drain。
session/transaction.ts:1062-1065 有一条校验:
/** * New owned work needs a live owner, judged on the owner's final * candidate: not `completing`, terminal, or abort-marked. A task * therefore cannot create owned work in the commit that finishes it * (spec §5.5). */async #validateOwners(): Promise<void> {一次提交里,不许"建子任务"和"自己终结"同时发生。 #validateOwners 在组装阶段
(commit 真正落盘之前)遍历这次提交里所有新写的主任务 id,主人的候选状态只要是
completing / terminal / abort-marked,直接抛错。
所以 afterRun 钩子要建任务时,finish 只能先做一次不终结的提交
(generation.ts:899-915 的 holdRun):
// generation.ts:914-915(Commit A:不终结,只换 phase)const summary: RunSummary = { ...end, first: run.first ?? end.answer };return { status: "running", checkpoint: { phase: "finish", run: summary } };running,不是 terminal。pi.live.run 也特意保留(delete live.generation
只清 generation 那一格),因为钩子建的任务还挂着这个 run。等 drain 里那些任务
全终态,才走 endAnsweredRun(:953-956 的注释直接写着 "Commit B")真正收尾。
这段代码把 §4.3 那句话变成了可执行的规则:
completing 不只是"等子任务结束"的状态,它还是一条"不许再招人"的边界。
两个 phase,就是这条边界在时间上的投影。
五、调度器:没有循环的循环
scheduler.ts 3,159 行,是全包最重的一块。抓四个函数就够理解它了。
5.1 一次 kick,一轮 drain
// scheduler.ts:1865-1888#kick(): void { this.#scheduleWake(); this.#dirty = true; if (this.#draining || !this.#enabled || this.#closing) return; this.#draining = true; // Never commit synchronously from a commit or registry listener. queueMicrotask(() => void this.#drain());}async #drain(): Promise<void> { try { while (this.#dirty && this.#enabled && !this.#closing) { this.#dirty = false; const reservations = await this.#reserve(); for (const reservation of reservations) this.#start(reservation); } } catch (error) { this.#failSession(error); } finally { this.#draining = false; if (this.#dirty) this.#kick(); }}这是 scheduler.ts 里唯一的调度循环——文件里另有五个 while,
都在向上走归属链或跑任务阶段,只有这一个管"这一轮有没有新活"。
三个细节:
queueMicrotask:注释写着"永远不要从提交回调或注册表监听器里同步提交"。 否则一次提交里套另一次提交,变更线会自己咬自己。finally里再kick一次:循环最后一轮检查之后到达的唤醒不能丢。#failSession:预留阶段抛错,整个 Session 判死(M10 §10.4)。调度器不做局部恢复。
5.2 #reserve:一次提交预留所有活
#reserve(:1894-1988)做的事,用大白话说:
- 如果一个任务被"放弃重启"标记过,先给它打 abort 标记,这一轮就返回(下次再看)。
- 扫出这一轮所有可跑的候选。
- 对每个候选:检查重启次数上限、解析定义、必要时迁移、把状态写回
running。 - 全部写操作放进同一个
commitInternal。
第 3 步里那段"重启上限"值得抄一眼(:1932-1944):
const cutOff = record.restarts !== undefined && record.restarts >= this.#restartLimit();if (cutOff && (mode === "abort" || !this.#limitsRestarts(record.kind))) { const message = mode === "abort" ? `Abort handler of task ${id} (${record.kind}) was cut off ` + `${record.restarts} times` : `Task ${id} (${record.kind}) was cut off ${record.restarts} times ` + "without progress"; await this.#terminate(tx, record, { status: "faulted", error: { message, detail: { reason: "restart_limit" } }, }); continue;}#restartLimit() 默认 5(harness/agent.ts:58)。
这是第一代完全没有的一道闸。 一个会让进程崩溃的 bug,如果没有这个计数器,
就是无限重启:启动 → 跑到同一处 → 崩 → 再启动。加上计数之后,
第五次直接判 faulted 并上报,用户看到的是"这个任务坏了",不是"这个软件坏了"。
5.3 #rules:六条决策规则
一次 phase 跑完,要不要继续?#rules(:2289-2303)回答:
#rules( current: ErasedRunningTask, previous: PhaseResult | undefined,): StepPlan { // 3. abort mark: end; a fresh abort invocation starts once the // ordinary owned work is gone. if (current.abortRequested) return END; if (!current.background && this.#belowCancelled(parentOf(current))) { return CASCADE; } if (previous === undefined) return CONTINUE; // 4. uncaught error. if (previous.failure !== undefined) { return { kind: "fault", error: previous.failure.error }; } // 6. no durable progress. if (jsonEqual(current.state.checkpoint, previous.checkpoint)) { const message = `Task ${current.kind} phase ${previous.checkpoint.phase} returned ` + "without durable progress"; return { kind: "fault", error: new Error(message) }; } return PROGRESS;}注释里给规则编了号,因为规则 1(状态已不是 running)和规则 2(Harness 在关闭)
在 #step 里先处理掉了。
最狠的是规则 6:handler 跑完,检查点跟进去时一模一样,判 faulted。
PhaseHandler 的类型注释(types.ts:238-241)写着:
每个 phase 处理器都必须通过
runtime.commit()提交一个变了的检查点或一个终态; 什么都没提交就返回,是"契约失败"。
这条规则把"我好像跑了但什么都没干"变成了一个显式错误。
在普通 while 循环里,这种 bug 表现为"卡住了";在这里,它是一个可上报的 faulted。
5.4 open():把 running 改回 pending
进程重启后,文件里那些 running 的任务是什么状态?答案是:不知道。
可能跑完了没来得及提交,也可能刚到一半。
open(:433-469)的处理干脆利落:
if (record.state.status === "running") { const restarts = (record.restarts ?? 0) + 1; const pending = withState(record, { status: "pending", checkpoint: record.state.checkpoint, }); tx.setTask({ ...pending, restarts } as AnyTaskRecord);}三件事一起发生:状态回 pending、检查点原样保留、restarts 加一。
"原样保留"是重点。上一轮跑到哪个 phase、那个 phase 的中间数据是什么,全在检查点里。 所以重跑不是从头来,是从最后一个已提交的阶段继续。
而 restarts 加一,就是 §5.2 那道闸的输入。这两个动作必须同时发生,
否则计数器就失去了"连续"的语义。
5.5 一次调用的完整生命周期
#start(:2172-2189)很短:
#start(reservation: Reservation): void { const invocation = reservation.invocation; void (async () => { try { if (invocation.mode === "run") await this.#run(reservation); else await this.#runAbort(reservation); } catch (error) { this.#report(error, { kind: "task_error", ... }, invocation.context); } finally { this.#end(invocation); invocation.record = undefined; invocation.finish(); this.#kick(); } })();}#run(:2192-2216)是一个 while (current !== undefined):跑一个 phase,
做一次决策,再跑下一个 phase——直到某个 phase 把状态改成 waiting / sleeping /
terminal,或者决策说结束。
也就是说,一次"调用"(invocation)里可以连续跑好几个 phase,只要它们都在同一轮 并且每次都有持久进展。中途进程死了,检查点停在哪,下次就从哪接。
5.6 取消怎么往下传
取消不是"给每个任务发一个 signal",而是一条从下往上确认的链。
#belowCancelled(:1702-1705)判一个任务头上有没有"取消意图"。
#planReservation 里(:2021-2024):
if (!record.abortRequested && !record.background && this.#belowCancelled(parentOf(record))) { cascade = true; continue;}命中就不跑这个 phase,而是把这一轮标成"有待处理的级联",然后安排一次 reconcile。
为什么不直接取消?因为 abort 是自下而上跑的(:2031-2032 的注释):
子任务先清理完,父任务才能收尾。直接给父任务打 abort 标记,父任务会在子任务
还活着的时候就开始清理。
The waiting rule is also inverted: #waitingOn(:2034-2040)里,被 abort 标记的任务
要等的是它所有活着的普通子任务,不是 state.on 里那些。
用一张图说清三条边:
abortTask(parent) | +-> parent.abortRequested = true (一次提交) | +-> parent 不再跑 phase,等 owned 全终态 | +-> child 被级联标记 -> child 跑 abort 处理器 -> terminal | +-> 全部终态 -> parent 跑 abort 处理器 -> aborted中间那一步是"标记",不是"命令"。标记落盘之后,即使进程在中间死掉,
重启后 open() 会重新推导级联标记(:465-467)。
取消意图本身也是持久的。
5.7 提交点:一次 commit 到底保证什么
前面反复出现"一次提交"。现在把它打开——这是 session/transaction.ts(1,293) 的全部职责,
也是"中断后可恢复"能成立的地基。
Storage 接口(types.ts:1329)只有一个写方法:
commit( batches: readonly (readonly StorageWrite[])[], receive: (index: number, seq: Seq) => void, context: Context,): Promise<CommitResult>;签名里装了四件事(:1330-1340 的注释):
- 一个 batch 是一次原子提交,带自己的
seq,还要对照前一个 batch 留下的状态检查。 - 拒绝就停:某个 batch 被
durable自己的校验拒了,前面的已经持久,它和后面的都没有。 receive是落盘回执,不是发布。它在全部落盘之后、下一个 commit 开始之前同步调用; Session 的对外发布在更后面。- 结果是未知的就 reject(连接断了、语句或提交失败);已发出的
receive仍然算数。
第 3 条区分了两件常被混为一谈的事:"写进存储"和"看到新值"。落盘成功但发布还没跑时 进程死掉,没问题——重启后从存储读就是新值。反过来,把发布当成落盘确认,就会丢数据。
Transaction implements Tx(transaction.ts:239)是接口上面那个对象。三条硬约束:
| 约束 | 出处 | 撞上了会怎样 |
|---|---|---|
| 表读必须在第一次表写之前 | :277 的 #written |
抛 ReadAfterWrite |
| 读一个被未发布写者占着的 key | :123 的 GatedStorage |
等待,直到那个写者发布 |
| 回调抛错 | :757 的 sealAfterFailure |
所有 prepared 变更作废,一个字节不落盘 |
第一条解释了 prepareBoundary 的注释为什么强调 "Table reads must precede the commit's
first table write"(inbox.ts:54-57):边界要读队列和最新 head,这两次读必须在任何写之前完成。
第三条是"一个 phase 要么全成要么全不成"的来源。检查点和这一轮的副作用(追加 entry、 建子任务)在同一个回调里,所以不可能出现"记了进度但没做"或"做了但没记"。
还有一层更省的东西:HeldDocument / holdable()(:796-852)。不是每次 commit 都必须落盘。
一个只改 latest 文档、且改的是已有会话文档的提交,可以只在内存里推进,把变更攒着;
等某个 commit 真要落盘时,takeHeld() 把攒的变更排在自己前面,一起写。
语义上已提交,物理上延后——不是"拖批",因为任何一个后来的落盘点都会把它们带上。
最后一步是 adopt(:904):落盘成功后按指针交换更新缓存,不重读存储。
所以一次提交的代价是"一次批量写 + 一次指针交换",而不是"写 + 全量重读"。
这一节和 §5.4 合起来,就是完整的恢复机制: 恢复的起点是最后一次落盘的 batch,而检查点保证那次 batch 里有一个完整可续的状态。
六、generation:把 while 换成 handOver
GenerationTask(generation.ts:162),name: "pi.generation",version: 2。
6.1 七个 phase
GenerationCheckpoint(:69-136)是一个七支联合:
| phase | 干什么 | 离开时去哪 |
|---|---|---|
prepare |
拼系统提示词、工具集,写 pi.system |
request |
request |
发一次模型请求 | tools / retry / poll / 终态 |
retry |
指数退避后重发 | request 或 poll |
poll |
拉一次延迟响应(provider 后台任务) | 同 request |
tools |
为 tool call 建子任务并等待 | finish 或再次 tools |
finish |
跑 afterRun 钩子,它们可能建任务 |
drain 或终态 |
drain |
等 afterRun 建的任务全部终态 |
终态 |
对比 M03 的 runLoop,一一对得上:
| M03 | M11 |
|---|---|
prepareRequest 钩子 |
prepare phase |
streamFn 一次请求 |
request phase |
| 重试逻辑 | retry phase + sleepUntil |
| 顺带产出的 partial | convertPartial(generation.ts:661) |
内层 while (hasMoreToolCalls) |
tools phase + waiting |
afterRun 钩子 |
finish phase |
外层 while (true) |
handOver 到新任务 |
prepare 里还有一件容易被忽略的事:它算出一个 cutoff(generation.ts:245-257):
// generation.ts:245-247let cutoff = (await tx.latestEntryId(conversationId))!;for (const entry of entries) { cutoff = (await tx.appendEntry( SystemEntry, conversationId, entry, )).id;}cutoff 是"这一轮请求能看到的最后一条 entry"。prepare 把系统提示词写成 pi.system entry,
cutoff 随之推进到这个新 entry。之后 request 拿上下文视图时(:283):
// generation.ts:283const view = await runtime.context(conversationId, context, { at: cutoff });{ at: cutoff } 是关键:视图按一个固定的 entry id 取,不是按"当前最新"。
于是请求发出后,即使队列里又落了一条 entry,这一轮的输入也不会变。
retry 和 poll 也带着同一个 cutoff(:298、:336)。一次请求重试三次,
三次发给 provider 的 messages 一模一样——否则重试就成了"换了个问题再问一遍",
计费和提示词缓存都会错位。
这和 §6.4 的"不重发、不重复付费"是同一个设计的两面: 请求的输入必须是一个可以被持久引用的事实,而不是一个随时会变的查询结果。
6.2 内层循环怎么没的
M03 的内层循环是这样的:模型给了 tool call,Promise.all 跑工具,
结果塞回 messages,再问一遍。
durable 把它拆成两步,中间隔着一次持久化:
// generation.ts:345-357await runtime.commit(async (tx): Promise<Next> => { const live = await tx.doc(LiveDoc, runtime.conversationId); const slot = live.tools?.find( (slot) => slot.callId === next && slot.taskId === undefined, ); const taskId = await createToolTask( tx, runtime, assistant, next, slot?.unoffered, ); if (slot !== undefined) slot.taskId = taskId; const checkpoint: GenerationCheckpoint = { phase: "tools", assistant, tools: [...tools, taskId], pending: rest, }; return { status: "waiting", checkpoint, on: [taskId], policy: "allSettled" };}, context);一次提交同时干了三件事:建工具任务、把任务 id 记进检查点、把 generation 置为 "等这一个任务"。
然后 generation 就放弃了调用栈——waiting 状态下它没有 invocation,不占内存。
工具任务跑完,调度器把它唤醒,它从 tools phase 继续,取出下一个待开始的调用。
串行工具轮就是这样实现的:pending 数组每轮少一个。
并行轮呢?pending 一次全建完,on 里是全部任务 id,还是 waiting。
所以"串行还是并行"在这套设计里不是两种控制流,是两种填 pending 的顺序。
6.3 外层循环怎么没的
M03 的外层 while (true) 管"续命":question(steering)、follow-up、finishTurn。
durable 里没有这个循环。一个 run 结束,要么结束,要么换一个任务接着干:
// generation.ts:1175-1187function createGeneration( tx: Tx, conversationId: ConversationId, telemetry: Pick<TaskCreationOptions, "submissionIds"> = {},): Promise<TaskId<GenerationResult>> { return tx.createTask(GenerationTask, {}, { ownership: { kind: "conversation" }, conversationId, ...telemetry, });}/** Hand run control from `from` to `to`; the run's inputs move with it. */export function handOver( live: Draft<LiveState>, from: TaskId, to: TaskId,): void { if (live.run?.taskId === from) live.run.taskId = to;}handOver 三行,但它就是"循环"的替代品。两个调用点:
:883:finishTurn式的续命——追加一条 user 消息,新建 generation,交棒。:1137:还有排队的输入——把输入推回run.inputs,新建 generation,交棒。
区别在哪?while 循环里,第二轮是第一轮的"下一次迭代",同一个函数调用栈。
handOver 里,第二轮是另一个任务,第一个任务已经 terminal。
这个差别带来一个直接好处:崩溃点可以精确到轮次。假设你问了五个问题,
第三个答案生成到一半进程死了。重启后要恢复的是"第三个 generation task",
不是"整个对话循环"。前两个任务已经是 terminal,一行代码都不用重跑。
6.4 中断分三种,不是一个 error
request phase 开头两行(:264-266):
if (cutOffTooOften(task, runtime)) return endCutOff(runtime, task, context);// The host stopped while this request was in flight:// a failed attempt, not a resend.if (task.restarts !== undefined) { return interrupted(runtime, task.state.checkpoint, context);}如果这个任务被重启过(restarts !== undefined),说明这次请求是在上一个进程里发出的,
结果无从得知。这时不能当"没发过"重发——provider 可能已经计费了。
interrupted 的处理是把它记成一次失败尝试,然后走正常的重试逻辑。
retry phase 里还有一段专门为延迟响应写的续命(:310-317):
if (poll !== undefined) { const pollAt = runtime.now(); live.generation = { attempt: attempt + 1, deferred: { pollAt } }; return { status: "running", checkpoint: { phase: "poll", attempt: attempt + 1, ...kept, ...poll, pollAt, }, };}检查点里的 poll.handle 是 provider 侧那个后台任务的句柄。进程死了再起来,
拿这个句柄去拉结果就行——不重发请求,不重复付费。
GenerationCheckpoint 里 retry 那一支的注释(:96-100)写得很清楚:
主机死的时候正在拉取的那个延迟响应:下一次尝试再拉一次,而不是重发一次请求, 这样 provider 那边的任务既不会丢,也不会付两次钱。
这就是"把状态显式建模"的具体收益。第一代把这类信息全丢了,
所以 M10 §7.2 只能补一个 No result provided。
6.5 压缩是一个被 generation 拥有的任务
M09 讲了压缩的触发条件。在这一层,它就是一个普通任务:
CompactionTask(compaction.ts:114),name: "pi.compaction",三个 phase:
// compaction.ts:57-60export type CompactionCheckpoint = | { phase: "select" } | ({ phase: "summarize" } & SummaryRequest) | ({ phase: "retry"; until: number } & SummaryRequest);select 选范围,summarize 发一次摘要请求,retry 退避重试。
跟 generation 骨架一模一样,只是短。
两种触发者(generation.ts:237 / :812):
- threshold:上下文快满了,
preparephase 里提前压。generation 建这个子任务, 然后置waiting等它。 - overflow:请求直接失败了、错误里说上下文超了,才压。此时 generation 已经在
request或poll之后,压完重走一轮prepare。
检查点里记的是"等的是哪个压缩任务"(compacted?: TaskId<CompactionResult>),
不是"压没压过"。所以进程死了重启,generation 还是知道该等谁——那个任务也在磁盘上,
会自己接着跑。
pi.live 里还有一份给人看的视图(live.ts:70-80):
export type CompactionStatus = { taskId: TaskId<CompactionResult>; trigger: CompactionReason; blocking: boolean; attempt: number; retry?: { at: number; error: string };};blocking 就是"有没有 run 在等它"。前台的压缩要显示进度,后台的不用。
6.6 一轮的输入从哪来
M03 里 steering 和 follow-up 是两个钩子。这里它们是队列里的两种模式:
pi.inbox 的每一项带 mode: "steer" | "followUp" | "write"(inbox.ts:8-16)。
一个 run 在"边界"上看一眼收件箱:
// inbox.ts:35-42export type Boundary = { readonly conversationId: ConversationId; readonly inbox: Draft<InboxState>; readonly steeringMode: QueueMode; readonly followUpMode: QueueMode; head: EntryId | undefined;};steeringMode / followUpMode 来自设置(agent.ts:80-81),默认都是
"one-at-a-time"——一次只放一条进去,剩下的留在队列里。
两种模式的差别,只在于在哪个边界取。
| 模式 | 取的时机 | 效果 |
|---|---|---|
steer |
一次 generation 结束、下一轮开始前 | 打断当前节奏,插一句 |
followUp |
整个 run 已经答完之后 | 当作新一轮的起点 |
所以在 durable 里,"打断"不是一个信号,是队列里一条比别的优先的记录。
withdrawQueuedInputs(harness.ts:253)在任务失败时把排队的提交撤回去,
让用户重新决定——这是第一代做不出来的,因为它的输入直接就是一行 entry。
七、tool:一次调用的持久意图
ToolTask(tool.ts:136),name: "pi.tool",version: 3。
7.1 两个 phase,两种 input
ToolTaskInput(tool.ts:67-83)分两支,切的是"这次调用有没有一条 entry":
export type ToolTaskInput = | { kind: "model"; assistant: EntryId; callId: string; unoffered?: true } | { kind: "nested"; parent: TaskId; parentCallId: string; key: string; call: ToolCall; progress?: false };model:只存两个指针——哪条 assistant entry、哪个callId。参数不复制, 用的时候回 entry 里读。于是 entry 是唯一权威,不会出现"任务里的参数和历史里的不一"。nested:调用内容call内联在 input 里。注释把理由写在脸上: "whose call the input carries because no entry holds it"——嵌套调用不写进 transcript, 没有别处可查。
unoffered?: true 也在这一层:它是一句"这个调用我根本没提供过",所以不必解析工具名,
直接结算成 tool_unavailable。
这一支就是 M03 里 executeTool 那个结构在持久层的对应物。但区别必须说清:
M03 的嵌套调用是同步的一次函数调用,栈一退就没了;这里是一个有主人的任务,可以和调用者
一起死、一起重启。
再看检查点,只有两条分支:
// tool.ts:85-88export type ToolTaskCheckpoint = | { phase: "call" } /** Durable intent: the final arguments and the replay policy * recorded before execution. */ | { phase: "execute"; arguments: JsonObject; replay: "safe" | "unsafe" };call 这个 phase 很长(:149-200),因为它把整个"准备工作"串在了一起:
读调用、解析工具、修参数、校验、跑 beforeTool 钩子、再校验、提交意图、执行。
注释解释了为什么不拆(:130-135):"all in one call handler so nothing separates
resolution from settlement"——解析和结算之间不能有缝。如果"解析出工具"和"开始执行"
分成两个 phase,中间那次崩溃就会留下一个"已经决定要用哪个工具、但还不知道参数"的半截状态。
7.2 一段三行,把 M10 那个洞补上了
// tool.ts:195-198await runtime.commit(() => { const intent = { phase: "execute", arguments: final, replay: tool.replay ?? "unsafe", } as const; return { status: "running", checkpoint: intent };}, context);await run(runtime, task.input, call, tool, final, context);先提交"我要用这些参数跑这个工具,重放策略是 safe/unsafe",然后才真正跑。
崩在 run 里面怎么办?进程重启,这个任务回到 pending,检查点是 execute。
execute phase 只做一件事(:202-227):
const { arguments: args, replay } = task.state.checkpoint;const call = await readCall(runtime, task.input, context);const tool = await resolveTool(runtime, task.input, call.name, context);if (replay === "safe" && tool?.replay === "safe") { // The rerun reports from scratch: clear what the interrupted // attempt published. await runtime.commit(async (tx) => { const slot = toolSlot( await tx.doc(LiveDoc, runtime.conversationId), runtime.taskId, ); if (slot !== undefined) { clearProgress(slot); slot.status = "running"; if ("parentTaskId" in slot) slot.arguments = args; } return undefined; }, context); return run(runtime, task.input, call, tool, args, context);}const message = `Tool ${call.name} was interrupted and may have partially run`;const ending = { status: "failed", message } as const;await settleFromSlot( runtime, task.input, call, { tool }, ending, "interrupted", message, context,);两条路,选择依据是两次策略都必须说 safe:检查点里记的(当时的判断)和注册表里
现在的(当前的定义)。任何一边是 unsafe,就不重跑,写一条 interrupted 的真实结果。
这就是"读文件可以重来、bash 不能瞎重来"在类型上的表达。
replay 由工具自己声明(tool.replay ?? "unsafe")。默认 unsafe 是个好默认值:
新写的工具不知道能不能重放,就假定不能。
7.3 工具里还能再调工具
NestedCallDoc(tool.ts:117-125)解决的是另一类问题:工具 A 在执行中想调工具 B。
export const NestedCallDoc = defineDocFamily<NestedCallState, null>({ kind: "pi.tool.nested-call", version: 1, scope: "task", family: true, initial: () => ({}), // The document retires with its task. checkpointWhen: () => false,});一行一个槽位:family: true + initial: () => ({}) 意味着每次嵌套调用是这一族里的
一个新成员,读的时候按 key 取。
注释里那句"the result retires with the caller"是关键:嵌套调用的结果不写进 transcript,
它挂在调用者的文档上。所以对话历史里看不到它,调用者结束它也一起没了。
ToolTaskResult 因此是 { kind: "nested" }——只有一个标记,没有内容。
7.4 并行还是串行,是一个设置
settings.toolExecution(agent.ts:79)默认 "parallel"。
两种模式在代码里只差填 pending 的速度:
- 并行:一次把这一轮所有调用建成任务,
pending立刻清空。 - 串行:
pending留着剩下的调用,每轮只建一个(generation.ts:342-357)。
一份检查点里 tools 是"已经建过的任务",pending 是"还没开始的调用"。
两个数组一起,就是这一轮的全部进度。
这也解释了 unoffered 那个标记的来由。version: 2 的迁移注释(generation.ts:166-168)
写得很具体:版本 1 会把"模型调了一个这轮没提供给它的工具"当成正常调用去解析名字;
版本 2 改成留一个 unoffered 标记,让它结算成 tool_unavailable。
为什么这需要版本号? 因为检查点是跨版本读的。一个 v1 进程读到 v2 的检查点,
不知道怎么处理 unoffered,所以 #fit 直接判它 blocked,宁可不跑。
八、和 M03 的对照
把两代放一张表里,边界就清楚了:
| 问题 | agent(M03) |
durable(M11) |
|---|---|---|
| 循环的载体 | 函数调用栈 | task 记录 |
| 进度存在哪 | 局部变量 | 检查点(每次提交) |
| 一次工具调用 | await 一个 Promise |
一个 pi.tool 任务 |
| 一轮对话的边界 | while 的一次迭代 |
一个 pi.generation 任务 |
| 崩溃恢复 | 没有这个概念 | open() 把 running 改回 pending |
| 并发 | Promise.all |
调度器 + waiting + 所有权 |
| 取消 | AbortSignal |
abort 标记 + abort 处理器 |
| 重试上限 | 调用方自己数 | restarts + restartLimit |
| 系统提示词 | 每次请求现拼 | prepare phase + pi.system entry |
| 谁在用 | coding-agent |
durable 之上的宿主 |
这张表的读法是:右列每一行,都是左列某一行从"内存里的事实"变成"存储里的事实"。
不是 durable 更聪明,是它把同样的东西记下来了。代价是每次状态变化都要一次提交,
收益是进程可以在任何一个逗号后面死掉。
但要说清一件事:这张表里有一半不是 agent 做不到,而是 agent 不该做。
AbortSignal 换成 abort 标记、Promise.all 换成调度器,这两条是"要不要"的选择。
runLoop 完全可以加一个 restartLimit 参数,把重试次数记在一个 Map 里。
真正做不到的是另外几条:崩溃恢复、跨轮次的进度、进程死时"可能已经发生"的那个事实。
分界线只有一条:这个信息需不需要活过进程。
- 不需要 → 留在内存里,循环就够了。
- 需要 → 它必须在某一次提交里落盘;一旦落盘,就要回答"谁在什么时候提交"—— 那已经是一个运行时了。
所以 coding-agent 选 agent 是合理的:它的会话是本地文件,用户关掉终端就是"结束",
没有"重启后接着跑"的承诺要兑现。durable 选了另一条,因为它要把这个承诺兑现。
选型的分歧不在能力,在承诺。
九、四种后端,一套语义
M10 讲了 JSONL 的 marker + sidecar。这里补全四个后端:
| 后端 | 文件 | 行数 | 定位 |
|---|---|---|---|
| JSONL | storage/jsonl/storage.ts |
908 | 本地、可读、全历史在内存 |
| SQLite | storage/sqlite/storage.ts |
1,050 | 长时间跑、不占内存 |
| IndexedDB | storage/indexeddb.ts |
1,273 | 浏览器 |
| Memory | storage/memory.ts |
893 | 测试与沙箱 |
前三个的实现方式差得很远,但对外暴露的是同一个 Storage 接口(types.ts:1329)。
9.1 一致性靠测试,不靠约定
testing/storage-conformance.ts 2,100 行,env-conformance.ts 634 行。
这两个文件是这套多后端设计的地基。
它们的用法是:每种后端实现完,跑同一套用例。用例断言的不是"SQL 长什么样",
而是"语义对不对"——分叉后能不能读到父会话的历史、延迟提交的窗口到点没有、
一篇文档的 latest 版本是不是真的只有一个。
这比写文档靠谱。 一份 3,000 行的契约文档会过期,2,100 行可执行的用例不会。
顺带一个观察:durable/docs/spec.md 有 362 KB。代码 33,728 行,规格书 36 万字节。
这个比例在开源项目里很少见——源码里那些 (spec §8.3)、(spec §5.5) 的注释,
指的就是这份文件。读不懂某段代码时,先去看它引用的 spec 章节。
9.2 SQLite 那 1,050 行里有什么
storage/sqlite/ 下除了 storage.ts 还有 schema.ts(64)、migrations.ts(139)、
database.ts(2)、node.ts(23)、cloudflare.ts(16)。
database.ts 只有两行——它是一个纯类型文件。真正干活的是 node.ts / cloudflare.ts
这两个薄适配层,一个接 node:sqlite,一个接 Durable Object 的 SQL。
上面还有一层 storage/store/(6 文件 / 1,329 行):commit.ts、documents.ts、
queries.ts、storage.ts、tables.ts。两个 SQL 后端共享这一层,
所以 SQLite 和 Durable Object 的语义天然一致——它们跑的是同一份 SQL。
十、完整链路
一次"用户输入 → 模型回答",在 durable 里的全过程:
submit(input) | +-> 一次提交:pi.user entry + submission 记录 + pi.inbox 更新 | (M10 §9:先 sidecar,再 marker) | +-> startRun -> tx.createTask(GenerationTask) | +-> [scheduler #kick] queueMicrotask(#drain) | | | +-> #reserve :一次提交预留所有可跑任务 | | -> 状态写回 running,restarts 不动 | +-> #start -> #run :循环跑 phase | +-> prepare :拼提示词 -> 需要时写 pi.system entry -> 提交 | -> checkpoint = { phase: "request", cutoff, model, ... } | +-> request :streamResponse(...) 真正发请求 | | | +-> 拿到 tool call -> 提交:建 n 个 pi.tool 任务 | | -> checkpoint = { phase: "tools", on: [...] } | | -> 状态 = waiting(放弃调用栈) | | | +-> 拿到最终答案 -> 提交:写 pi.assistant | -> checkpoint = { phase: "finish", run } | +-> [工具任务各自调度,见第七节] | -> 全部 terminal -> 唤醒 generation | +-> finish / drain :afterRun 钩子可能再建任务 -> 终态 completed { entryId } -> 需要续命则 handOver 到新 generation 任务对比 M10 §11.1 的那张图:第一代那条线的终点是"文件里多一行"; 这条线的终点是"一批任务到达终态"。
十一、工程暗坑
1. pending 和 running 的检查点类型一样,但不是一回事。
pending 表示没有调用栈,running 表示有人正持有它。靠检查点区分不了,
只能看状态字段。写恢复逻辑时不要拿检查点形状猜状态。
2. 规则 6 会咬人:phase 没产生持久进展就是 fault。
#rules(scheduler.ts:2297-2301)对比进出的检查点。你写一个只做副作用、
不提交的 handler,第一次跑就判 faulted。想"什么都不改就退出",
得显式返回一个 waiting 或 sleeping 状态。
3. checkpointWhen 返回 false 的文档不会留下版本。
NestedCallDoc 就是 checkpointWhen: () => false,因为它跟着任务一起销毁。
给这种文档写"回到上一版"的逻辑会拿到 undefined。
4. replay 两边都是 safe 才重跑。
tool.ts:208 是 replay === "safe" && tool?.replay === "safe"。
只在自己那一侧写 safe、工具声明的是 unsafe,照样不重跑——这是故意的,
因为它防的是"工具的实现换了,重跑不再安全"。
5. restarts 只在"没改变过状态"时累加。
open() 里回退 running → pending 时加一。如果任务在被切断前改了检查点,
它大概率已经离开 running,下一次不会再加。连续才是这个计数器的语义。
6. abandonOnRestart 的任务不会变 orphaned。
它会带 abortReason: "restart" 等自己的定义,好让 abort 处理器清理干净
(scheduler.ts:1947-1952)。这类任务的 abort 处理器必须能处理"从没开始过"的情况。
7. orchestration 里有两种等待,别混。
waitForTask 等的是"任务终态",是内存里的等待,调用结束就没;
state.waiting 是持久等待,进程重启后仍然等。前者用来读结果,后者用来编排。
8. 延迟提交同样影响任务状态。
runtime.commit(..., PROGRESS_COMMIT) 是 persistWithinMs 那一档(默认 1 秒)。
任务的决策提交(返回新状态的那些)是立即的,只有纯文档改动可以延迟。
把这两类提交搞混,会在崩溃后看到"工具槽位显示 running 但任务已经 terminal"。
9. readOnly: true 打开的 Harness 什么都不恢复。
open() 里 if (this.#readOnly) continue; 跳过回退逻辑,running 任务保持原样
(另一个进程还在跑它)。所以只读端看到的 running 是真的在跑,
不是"上次没跑完"。
10. GenerationTask 的 version 是 2,ToolTask 是 3。
版本号不是包版本,是"检查点结构版本"。改 GenerationCheckpoint 的字段就必须加版本,
否则老检查点会被当成新结构读(prepare 里有专门处理旧版本缺字段的分支)。
11. commit 回调里只能用 tx 读。
types.ts:286-287 明确警告:回调里调 snapshot() / watchDoc() / getTask()
会排到自己持有的那条变更线上,然后永远不返回。这不是慢,是死锁。
12. pi.inbox 只在队列空的时候留版本。
inbox.ts:28 是 checkpointWhen: (value) => value.items.length === 0。
所以"把收件箱回滚到上一版"这种操作拿不到非空的旧状态——它压根没存。
13. 同一个 commit 里,表读必须在表写之前。
transaction.ts:277 的 #written 一旦置位,后续表读直接抛 ReadAfterWrite。
所以凡是"先读一下再决定写什么"的 phase,读都得摆在开头(prepareBoundary 就是这个形状)。
这条限制不在文档里,在错误里——撞上一次就记住了。
十二、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。
六个实验,前三个不用装依赖。
实验 1:看任务状态机在磁盘上长什么样
cd packages/durablenode --conditions=source --experimental-strip-types \ test/examples/12-recovery.ts判据:输出里能看到任务从 pending 到 terminal 的迁移,以及重开后
running 被改回 pending 且 restarts 变了。
想看更完整的恢复场景,再跑 30-reload-and-restart.ts(中途重载扩展 + 模拟重启)。
实验 2:让一个 phase 不提交,看它被判 fault
去 packages/durable/test/ 下新建一个任务定义:
const Stuck = defineTask({ name: "test.stuck", version: 1, initial: () => ({ phase: "spin" }), phases: { // 只读不写,什么都不提交 spin: async () => {}, }, abort: async () => {},});把它注册进去、建一个、等一秒。判据:任务终态是 faulted,
错误文本含 returned without durable progress。
实验 3:确认 durable 真的不依赖 agent
cd packages/durablegrep -r "pi-agent-core" package.json src/ | wc -lgrep -r "pi-ai" package.json | wc -lcd packages/durable(Get-ChildItem package.json,src -Recurse -File | Select-String -Pattern 'pi-agent-core').Count(Select-String -Path package.json -Pattern 'pi-ai').Count判据:第一条 0,第二条 1。再反查 coding-agent/package.json 里两条都在。
实验 4:跑一遍存储一致性套件
cd packages/durablenpx vitest --run test/memory-storage.test.ts \ test/jsonl-storage.test.ts test/sqlite-storage.test.ts判据:三套用例全绿。它们用的是同一份 createStorageConformance()
(src/testing/storage-conformance.ts:129)——契约只有一份,实现有三份。
把 storage/memory.ts 里某处语义改坏,再跑,看是哪一条用例先红。
先红的那条就是这份契约里最容易被写错的一条。
实验 5:看取消怎么级联
cd packages/durablenode --conditions=source --experimental-strip-types \ test/examples/23-child-tasks.ts判据:子任务先到终态,父任务后到——中间那段就是 completing。
把 ownership 从 { kind: "task", taskId } 改成 { kind: "conversation" },
子任务就不再被级联取消,会自己跑完。所有权不只是记账,它是取消的拓扑。
实验 6:撞一次 ReadAfterWrite
拿任意一个 phase 的 handler,把表写放到表读前面:
await runtime.commit(async (tx) => { await tx.appendEntry(UserEntry, runtime.conversationId, { model: [] }); await tx.latestHeadMarker(runtime.conversationId); // 写之后才读 return undefined;}, context);判据:抛 ReadAfterWrite。把两行对调就不抛了。
这个实验的价值不在验证一个错误,而在明白 prepareBoundary 为什么长成那个形状:
它必须在回调第一行就把队列和 head 读出来,因为边界的判断依赖"写之前的世界",
而一旦开始写,那个世界就不可再问。
五句话
如果只记五句:
- 进度在磁盘上,不在调用栈上。 进程死了,恢复的是任务,不是循环。
- 六个状态,
completing必须有。 它同时是"等子任务"和"不许再招人"。 - 不可逆操作先提交意图,再执行。 崩在中间,留下的是"我打算做什么"。
replay: "unsafe"是好默认值。 不确定能不能重来,就假定不能。- 循环被
handOver替代。 第二轮的起点是另一个任务,不是下一次迭代。
本章小结
durable分三层:状态机(task)/ 调度器 / generation 交接。- 六个状态、五种结局;
completing必须单独存在。 - 调度器没有
while:预留、决策、记账、唤醒。 generation用handOver取代循环:换代码,不换状态。- 不可逆操作先提交意图,再执行。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 状态机 | task = 状态 + 阶段 + 检查点 | §四 |
| 调度器 | 没有循环的循环:预留 / 决策 / 记账 / 唤醒 | §五 |
| generation | 用 handOver 取代 while |
§六 |
| 持久意图 | pi.tool 先提交"要跑什么"再跑 |
§七 |
| 不产生进展即失败 | jsonEqual 把空转变成可上报的 faulted |
§十三 |
练习
练习 1(读):§四 说 completing 必须单独存在。
如果把它并回 running,崩在哪一步会分不清"跑完了没"?
→ 回 §4.3、§4.4 的 finish 与 drain 两步。
练习 2(改):把 tool.ts:195-198 的"先提交意图、再执行"两步对调。
预期:崩溃后出现"执行了但没记录",重放会重复执行;回滚:调回原顺序。
常见误区
- 你会以为 状态机是给
while加存档点;实际是 进度本来就不该放在栈上; 证据 §六。 - 你会以为 调度器是轮询循环;实际是 预留加唤醒,没有
while; 证据 §五。 - 你会以为 四种后端要四套语义;实际是 一套语义四种实现;证据 §九。
读完自检
三条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
一个 while 怎么变成状态机的? |
把进度从栈上搬到存储里,循环就不该是个函数 | §六 |
completing 这个状态为什么必须存在? |
因为 finish 和 drain 必须分两步,中间得有个名字 |
§4.3、§4.4 |
| 不可逆的操作该怎么写? | 先提交意图,再执行——崩溃后才知道"可能已经发生" | §7.2 |
十三、收束
13.1 三个可迁移的方法
一、把"进度"从栈上搬到存储里,循环就自然消失了。
不是"给循环加个存档点",是"循环本来就不该是一个函数"。
一个 while 的每次迭代如果都要持久化,那它就是一个状态机,
只是因为不需要崩溃恢复,被写成了循环的样子。
二、用"不产生进展即失败"兜住状态机的空转。
状态机最阴的 bug 是"什么都没发生,但也没报错"。
#rules 规则 6 用一个 jsonEqual 把这类 bug 变成可上报的 faulted。
这是状态机设计里性价比最高的一行代码。
三、不可逆的操作要先记意图,再执行。
tool.ts:195-198 那三行是整章最值得抄的一处:先提交"我要用什么参数跑什么工具",
再跑。这样崩溃之后,系统知道"有一件事可能已经发生了",
而不是"不知道发生过什么"——后者才是数据损坏的真正来源。
13.2 这章的边界
本章讲了 durable 的调度内核和三个内置任务。没讲的是:
codemode/(1,710 行):沙箱里跑模型写的脚本,留给 M13。env/(2,319 行):文件与进程的跨平台抽象,本章只当作黑盒。tools/(1,596 行):内置工具实现,M05 讲的是coding-agent的那一套,不是这一套。images/、tool-search/:与主线无关的两块。
13.3 下一站
M11 讲了"提交怎么被调度成任务"。M12 讲 chord——durable 依赖的那个包,
也是这些提交能在浏览器、Node、Cloudflare 三处跑同一份代码的原因。
chord 50,101 行(216 文件),是仓库里最大的包。M12 只细读它的 v1 根层——
那 25 个文件里就有 object.ts、connection.ts、host.ts、reload.ts。
下一章:M12 chord——50,101 行的热重载宿主,只细读 v1 根层。
本章源码索引
| 文件 | 行数 | 职责 |
|---|---|---|
durable/src/types.ts |
1,446 | TaskDefinition / TaskState / TaskRuntime / Tx / Storage 契约 |
durable/src/session/transaction.ts |
1,293 | 一次提交的原子边界:Tx 实现、ReadAfterWrite、延迟提交 |
durable/src/session/session.ts |
2,105 | Session 门面:提交线、缓存、发布 |
durable/src/harness/scheduler.ts |
3,159 | 预留、决策、记账、唤醒;唯一的调度循环 |
durable/src/harness/generation.ts |
1,188 | pi.generation 七阶段任务 + handOver |
durable/src/harness/tool.ts |
1,147 | pi.tool 两阶段任务 + 重放策略 + 嵌套调用 |
durable/src/harness/types.ts |
1,080 | AgentState / Agent / Submission / ToolExecutionResult |
durable/src/harness/harness.ts |
612 | Harness 门面:open / resume / create / fork |
durable/src/harness/compaction.ts |
501 | pi.compaction(select / summarize / retry) |
durable/src/harness/live.ts |
452 | pi.live 文档:工具槽位、压缩状态、run 进度 |
durable/src/harness/view.ts |
400 | 会话视图与窗口 |
durable/src/harness/context.ts |
383 | head 标记到上下文区间(M10 §8.2) |
durable/src/harness/agent.ts |
362 | AgentDoc 定义 + 默认策略常数 |
durable/src/harness/task-graph.ts |
313 | 任务图视图 |
durable/src/harness/submissions.ts |
318 | 提交的生命周期 |
durable/src/harness/registry.ts |
115 | 三个内置任务的注册表 |
durable/src/documents.ts |
209 | defineDoc / defineDocFamily 四个重载 |
durable/src/testing/storage-conformance.ts |
2,100 | 四种后端共用的一致性用例 |
durable/src/storage/sqlite/storage.ts |
1,050 | SQLite 后端 |
durable/src/storage/indexeddb.ts |
1,273 | IndexedDB 后端 |
durable/src/storage/memory.ts |
893 | 内存后端 |
durable/docs/spec.md |
362 KB | 源码注释里 (spec §x.y) 引用的那份规格书 |