Pi Agent 源码级教程
M11

持久运行时 —— 把 Agent Loop 拆成状态机

10,301 字 · 含 368 行代码 · 约 48 分钟

你让它读了七个文件、改了三个,第八个文件刚读到一半。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:

text
@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 只有九行,值得看一眼:

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):

ts
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)有六个字段:

ts
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):

ts
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):

ts
export type TaskOwnership =	| { readonly kind: "conversation" }	| { readonly kind: "task"; readonly taskId: TaskId };
  • 会话拥有:顶层任务。一个 run 的 pi.generation 就是这样。
  • 任务拥有:子任务。一次工具调用 pi.tool 被它所在那轮 generation 拥有。

所有权不是装饰字段,它决定三件事:

  1. 谁等谁。waitForTask 只能等自己拥有的任务(types.ts:306-310)。
  2. 取消怎么传播。父任务取消,意图会传给下面的普通子任务(§5.6)。
  3. 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:

text
outcome 已定 ──> completing ──子任务全部终态──> terminal

types.ts:691-696 的注释写得很直白:

ts
/** 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 有一条校验:

ts
/** * 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):

ts
// 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

ts
// 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)做的事,用大白话说:

  1. 如果一个任务被"放弃重启"标记过,先给它打 abort 标记,这一轮就返回(下次再看)。
  2. 扫出这一轮所有可跑的候选。
  3. 对每个候选:检查重启次数上限、解析定义、必要时迁移、把状态写回 running。
  4. 全部写操作放进同一个 commitInternal。

第 3 步里那段"重启上限"值得抄一眼(:1932-1944):

ts
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)回答:

ts
#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)的处理干脆利落:

ts
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)很短:

ts
#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):

ts
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 里那些。

用一张图说清三条边:

text
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)只有一个写方法:

ts
commit(	batches: readonly (readonly StorageWrite[])[],	receive: (index: number, seq: Seq) => void,	context: Context,): Promise<CommitResult>;

签名里装了四件事(:1330-1340 的注释):

  1. 一个 batch 是一次原子提交,带自己的 seq,还要对照前一个 batch 留下的状态检查。
  2. 拒绝就停:某个 batch 被 durable 自己的校验拒了,前面的已经持久,它和后面的都没有。
  3. receive 是落盘回执,不是发布。它在全部落盘之后、下一个 commit 开始之前同步调用; Session 的对外发布在更后面。
  4. 结果是未知的就 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):

ts
// 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):

ts
// 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 把它拆成两步,中间隔着一次持久化:

ts
// 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 结束,要么结束,要么换一个任务接着干:

ts
// 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):

ts
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):

ts
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:

ts
// 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:上下文快满了,prepare phase 里提前压。generation 建这个子任务, 然后置 waiting 等它。
  • overflow:请求直接失败了、错误里说上下文超了,才压。此时 generation 已经在 request 或 poll 之后,压完重走一轮 prepare。

检查点里记的是"等的是哪个压缩任务"(compacted?: TaskId<CompactionResult>), 不是"压没压过"。所以进程死了重启,generation 还是知道该等谁——那个任务也在磁盘上, 会自己接着跑。

pi.live 里还有一份给人看的视图(live.ts:70-80):

ts
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 在"边界"上看一眼收件箱:

ts
// 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":

ts
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 的嵌套调用是同步的一次函数调用,栈一退就没了;这里是一个有主人的任务,可以和调用者 一起死、一起重启。

再看检查点,只有两条分支:

ts
// 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 那个洞补上了

ts
// 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):

ts
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。

ts
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 里的全过程:

text
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:看任务状态机在磁盘上长什么样

bash
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/ 下新建一个任务定义:

ts
const Stuck = defineTask({	name: "test.stuck",	version: 1,	initial: () => ({ phase: "spin" }),	phases: {		// 只读不写,什么都不提交		spin: async () => {},	},	abort: async () => {},});

把它注册进去、建一个、等一秒。判据:任务终态是 faulted, 错误文本含 returned without durable progress。

实验 3:确认 durable 真的不依赖 agent

bash
cd packages/durablegrep -r "pi-agent-core" package.json src/ | wc -lgrep -r "pi-ai" package.json | wc -l
powershell
cd 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:跑一遍存储一致性套件

bash
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:看取消怎么级联

bash
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,把表写放到表读前面:

ts
await runtime.commit(async (tx) => {	await tx.appendEntry(UserEntry, runtime.conversationId, { model: [] });	await tx.latestHeadMarker(runtime.conversationId); // 写之后才读	return undefined;}, context);

判据:抛 ReadAfterWrite。把两行对调就不抛了。

这个实验的价值不在验证一个错误,而在明白 prepareBoundary 为什么长成那个形状: 它必须在回调第一行就把队列和 head 读出来,因为边界的判断依赖"写之前的世界", 而一旦开始写,那个世界就不可再问。


五句话

如果只记五句:

  1. 进度在磁盘上,不在调用栈上。 进程死了,恢复的是任务,不是循环。
  2. 六个状态,completing 必须有。 它同时是"等子任务"和"不许再招人"。
  3. 不可逆操作先提交意图,再执行。 崩在中间,留下的是"我打算做什么"。
  4. replay: "unsafe" 是好默认值。 不确定能不能重来,就假定不能。
  5. 循环被 handOver 替代。 第二轮的起点是另一个任务,不是下一次迭代。

本章小结

  1. durable 分三层:状态机(task)/ 调度器 / generation 交接。
  2. 六个状态、五种结局;completing 必须单独存在。
  3. 调度器没有 while:预留、决策、记账、唤醒。
  4. generation 用 handOver 取代循环:换代码,不换状态。
  5. 不可逆操作先提交意图,再执行。

概念回顾

术语 一句话 在哪
状态机 task = 状态 + 阶段 + 检查点 §四
调度器 没有循环的循环:预留 / 决策 / 记账 / 唤醒 §五
generation 用 handOver 取代 while §六
持久意图 pi.tool 先提交"要跑什么"再跑 §七
不产生进展即失败 jsonEqual 把空转变成可上报的 faulted §十三

练习

练习 1(读):§四 说 completing 必须单独存在。 如果把它并回 running,崩在哪一步会分不清"跑完了没"? → 回 §4.3、§4.4 的 finish 与 drain 两步。

练习 2(改):把 tool.ts:195-198 的"先提交意图、再执行"两步对调。 预期:崩溃后出现"执行了但没记录",重放会重复执行;回滚:调回原顺序。

常见误区

  1. 你会以为 状态机是给 while 加存档点;实际是 进度本来就不该放在栈上; 证据 §六。
  2. 你会以为 调度器是轮询循环;实际是 预留加唤醒,没有 while; 证据 §五。
  3. 你会以为 四种后端要四套语义;实际是 一套语义四种实现;证据 §九。

读完自检

三条,能不能不看稿说出来?

自检 一句话答案 不会就去
一个 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) 引用的那份规格书