源码篇第13章 先落盘,后可见——pi-durable ​

小A用印章把发光的任务卡先盖进厚账册,老Z在旁递上下一张;身后传送带上三枚齿轮任务依次排队,一枚被气泡封存,远处灯塔与三格存储架守望。

本章导读: 源码篇的收官加餐(书号 42,阅读位置在源码篇第12章之后)。读 packages/durable:session/session.ts 的原子提交线、harness/scheduler.ts 的任务检查点、harness/tool.ts 的重放规则、storage/ 的耐久阶梯。这一章回答源码篇第5章留在最后的问题——进程死在工具执行到一半,重启后谁来收尾。pi-durable 的 README 自称 Experimental:API 在版本间无通告变更;本章只描述 v1.0.0 快照的行为,不做接口稳定性承诺。

源码篇第5章读完,小A已经能说出 AgentSession 靠什么活过重启:每条消息同步追加进 JSONL,读取时跳过坏行。他把笔记本翻回那页的边界表,指着一行问老Z:"_persist 没有 fsync,坏行静默跳过——那如果进程正好死在工具执行到一半呢?会话文件里只有‘模型说要调这个工具’,没有结果。重启后谁来收尾?”

“源码篇第5章的答案是宽松的:读不懂的行跳过,中断的回合留在历史里等宿主处理。”老Z说,“pi-durable 走的是另一条路:任何一步先原子落盘再对外可见,重启后由任务检查点接着跑,或明确判定不能重跑。这一章把那条‘先落盘、后可见’的内核读一遍。”

本章依据上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32)、@earendil-works/pi-durable 1.0.0。包内规范文档自称 Pico5,发布包叫 pi-durable:docs/spec.md 是规范性契约,src/ 是它的实现。本章以 src/ 为已确认事实,spec 用于核对语义措辞。注意它的依赖只有 pi-ai、chord、diff 和 typebox——不依赖 pi-agent-core;coding-agent 只在被构建排除的 src/experimental/ 里使用它。它是与 Agent+循环+AgentSession 并列的另一种宿主内核,不是源码篇第5章那条链的换皮。

边界:Storage.commit() 只保证“已提交状态被 Session 发布”。断电耐久强度取决于 backend 配置;JSONL 默认 fsync 关闭,SQLite 使用 synchronous=NORMAL。

全景:对话是日志,运行是任务 ​

README 的 Quick Start 给了最小骨架:Harness.open(storage, { models, registry }, context) 打开一个存储上的 Session;root() 取根对话;submit({ type: "input", content }) 持久受理一个输入;submission.wait(context) 等它 answered。一次问答在存储里长这样:

text
submit(input) → pi.user 条目
  pi.generation 任务 → pi.assistant(工具调用)
    pi.tool 任务 × n → pi.tool-result × n   (归 generation 所有,它等齐再继续)
  pi.generation 任务 → pi.assistant(最终答案) → submission done

四个概念各司其职:Entry 是不可变转录记录;Commit 是原子写;Document 是存在转录旁边的类型化 JSON 状态(pi.agent、pi.live、pi.inbox、pi.usage);Task 是带检查点的持久状态机。核心规则写在 spec 开头:所有变更走同一条原子提交线;只有已提交的状态可被观察。 没有“先显示后补写”的通道。

比喻:台账与工位

源码篇第5章的 AgentSession 像收银员边收钱边往本子上记,本子写坏了跳过那行继续;pi-durable 像银行柜台:每笔业务先盖章进总账,章没盖完客人根本看不到结果。两种“活过重启”,一种宽容,一种较真。

一条提交线,和它的三种失败 ​

内核入口是 src/session/session.ts 的 #runCommit()。把它的分支逐段读出来:

ts
// 提交主流程:回调 → 结算出原子写批 → Storage.commit → 内存采纳 → 发布。(session.ts 节选思路)
result = await change(tx);                 // 回调抛错 → settleFailure(),草稿丢弃,什么都没发生
const writes = await tx.settleSuccess();
if (writes.length === 0) { tx.discard(); return result; }  // 空写批 = 未提交,不算持久化
seq = await this.#storage.commit(writes, withoutAbortSignal(context));
// 一旦存储受理,调用方取消不再中断结算
// 存储抛错:只有 StorageRejected(承诺未产生任何持久效果)不投毒;其余一律 #poison
documents = tx.adopt(seq);                 // 存储已提交而采纳失败 → 也投毒:内存落后于持久状态
this.#publish(seq, writes, documents, context);

配合 src/errors.ts,三类错误给出三种恢复答案:

错误 含义 正确恢复
ReadAfterWrite 事务在首个表写之后又去读表——确定性编程错误 把读取挪到写之前;这是代码缺陷不是运行时状况
StorageRejected 存储在任何持久效果前整批拒绝 同一 Session 可安全继续,无需重开
其他存储失败 结果不确定 Session 投毒,必须关闭重开:内存与持久状态已可能不一致

投毒是最能体现这套设计取向的一点:它宁可不干活,也不带着“不知道写没写进去”的状态继续。对照源码篇第5章的 SessionManager——那边坏行静默跳过、写入尽力而为;这边不确定即停机。两种哲学都在 Pi 的 1.0 快照里,读源码时要分清哪条承诺属于哪个运行时。

事务层还有一条使用侧约束:表读取必须发生在首次表写之前(先读齐再写),文档草稿在写批内可继续编辑,提交参数在 Storage.commit() settle 前被借用、之后归存储。这些都是 session/transaction.ts 与 spec §4 可核对的形状。

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。