扩展状态与持久化
一个扩展把状态放在哪里,才能让它在重载、恢复和分叉之后活下来,以及为什么答案几乎总是一条会话条目,而不是一个模块变量。
你的 guard 扩展会阻止对 .env 和 .git/ 的写入。周一它还能用。周二你运行 /reload,而 /guard status 里的那个被阻止计数读出来是零。周三你从磁盘恢复那个会话,它读出来又是零。
没有任何东西坏掉。那个计数从未被存在任何能活过一个进程的地方。它住在一个被工厂闭包捕获的模块级 let 里,而工厂每次加载都会再跑一遍。修复办法不是"把它存到磁盘上某个合理的位置"。修复办法是理解:Pi 已经交给你的扩展一个持久的、知晓分支的、可以安放状态的地方——会话文件。
状态可以住在哪里
Pi 的 extensions.md 给了你一张短表,而它值得被当作一个决策来读,而不是一张清单。状态如何参与对话,决定了它该去哪儿:
| 状态 | 存储 |
|---|---|
| 跟随活动分支的工具状态 | 工具结果的 details |
| 被排除在模型上下文之外的持久数据 | pi.appendEntry() |
| 被存储并发送给模型的自定义内容 | pi.sendMessage() |
| 位于单个会话之外的数据 | 外部存储 |
有文档记载。那张表就在源文档里,不是推断出来的。
同样那四行,按真正把它们区分开来的那些属性展开:
| 属性 | 工具结果的 details |
pi.appendEntry() |
pi.sendMessage() |
外部存储 |
|---|---|---|---|---|
| 写入为 | 一个工具结果上的一个 details 字段 |
一条 custom 条目,属于这个会话 |
一条 custom_message 条目,属于这个会话 |
你写入的任何东西 |
| 在模型上下文里? | 否——content 是面向模型的那一半 |
否 | 是,被转换成一条用户消息 | 只有在你发送它之后 |
| 相对于分支? | 是 | 是——条目住在树里 | 是——条目住在树里 | 否 |
| 能在重载与恢复之后活下来? | 是 | 是 | 是 | 是 |
| 负载由谁拥有 | 你的工具 | 你,以 customType 为键 |
你,以 customType 为键 |
你 |
| 最佳用途 | 一次工具调用产出的状态 | 模型绝不能读的持久事实 | 模型必须读、但用户没有键入的内容 | 任何跨会话的东西 |
有两个格子是从上下文里读出来的,而不是被平白陈述的。message-types.md 把一个工具结果的 details 只称为"tool-specific";extensions.md 划下了这条线——“它的结果需要面向模型的 content,以及一个用于渲染或状态重建的 details 字段。” 而没有任何东西把外部存储送给模型:它只有在你注入它时才到达,而这又是 pi.sendMessage() 那一列。
错误:“我的工具返回了一个结果对象,所以它成功了。”
正确:返回一个对象就是成功路径。
extensions.md:“从execute()抛出,以产生一个失败的工具结果。返回一个对象并不会把它标记为错误。” 当一次失败仍然必须向脚本携带数据时,改为返回带isError: true的结果。
追加一条持久条目
pi.appendEntry(customType, data) 写入一条 custom 会话条目。会话格式文档把它称为 CustomEntry,而它的形状很小:
{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
有两个事实要紧,且两者都有文档记载。条目住在树里,所以它和其他一切一样有一个 id 和一个 parentId。而它不参与 LLM 上下文:session-format.md 谈到 CustomEntry 时说,它"不参与 LLM 上下文"。
第二个事实正是优先选它而不是 pi.sendMessage() 的理由。你的守卫那个被阻止计数,不是模型需要去推理的东西。把它放进上下文会花掉 token,更糟的是,会招来模型去谈论它。
下面是这个守卫长出一条持久日志的过程。它记录一次阻止,然后把它渲染出来。
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
interface GuardBlock {
tool: string;
reason: string;
at: number;
}
const PROTECTED = [".env", ".git/", "node_modules/"];
export default function (pi: ExtensionAPI) {
// In-memory mirror, rebuilt from the session on every load.
let blocks: GuardBlock[] = [];
pi.on("tool_call", async (event, ctx) => {
if (event.toolName !== "write" && event.toolName !== "edit") return undefined;
const path = String(event.input.path ?? "");
const hit = PROTECTED.find((p) => path.includes(p));
if (!hit) return undefined;
const entry: GuardBlock = {
tool: event.toolName,
reason: `path matches ${hit}`,
at: Date.now(),
};
blocks = [...blocks, entry];
// Durable, branch-aware, and invisible to the model.
pi.appendEntry<GuardBlock>("guard.block", entry);
if (ctx.hasUI) ctx.ui.notify(`Blocked ${event.toolName} on ${path}`, "warning");
return { block: true, reason: `Path "${path}" is protected` };
});
pi.registerCommand("guard-blocks", {
description: "List blocked tool calls recorded in this session",
handler: async (_args, ctx) => {
ctx.ui.notify(
blocks.length === 0 ? "No blocked calls in this session" : blocks.map((b) => b.reason).join("; "),
"info",
);
},
});
}
appendEntry 在数据类型上是泛型的,所以同一个 GuardBlock interface 既描述内存中的镜像,也描述持久化的条目。这值得去做:它让重建变成一个过滤,而不是一次翻译。
flowchart TD
E["guard.block 条目<br/>已持久化,每一个分支"] --> G["session_start 时的 getBranch()"]
G --> M["模块变量<br/>活动历史的状态"]
M --> R["运行期间读取<br/>快,但重启后就没了"]
F[".pi/ 下的一个文件"] -.->|"能活下来,但不是相对于分支"| M
T["一个工具结果"] -.->|"相对于分支,但要花掉一次请求"| M
M -.->|"永远到不了模型那里"| N["provider 请求"]
只有第一条路径在实线上。两个虚线输入是下面那张表里的替代方案,而那个虚线输出是让本章的做法变得便宜的那个属性:用户从没问过的簿记,留在模型的上下文之外。
可以放置状态的四个地方
本章的每一个选项都在持久性与分支敏感性之间做交易,而这个交易用一张表来看比用散文来看更容易。
| 能在一次重启后活下来 | 相对于分支 | 到达模型 | 代价 | |
|---|---|---|---|---|
| 模块变量 | 否 | 否 | 否 | 免费,而在分叉上是错的 |
appendEntry + getBranch() |
是 | 是 | 否 | 文件里每个事件一个条目 |
.pi/ 下的一个文件 |
是 | 否 | 否 | 跨分支共享;分叉时需要重写 |
| 一个工具结果 | 是 | 是 | 是 | 花掉一次请求往返 |
第三行是诱人的那一行,而第二行才是一个守卫工作状态的正确选择,因为相对于分支意味着被放弃的那条路径上的阻止不算数。一个文件给不了你这个,除非加上额外的机制,而把它放进一个工具结果,则意味着为你已经掌握了的簿记花掉一次模型请求。
这也是第 26 章的那个投影,应用于状态而不是消息:什么被持久化、什么是活动的、什么被发送,是三个分开的问题,而 getBranch() 只回答中间那个。
加载时重建
模块变量是一个缓存,不是存储。extensions.md 精确地告诉你如何把它重新填满:
在
session_start期间从ctx.sessionManager.getBranch()重建对分支敏感的状态。不要从每一个文件条目重建它,因为被放弃的分支代表着替代的历史。
有文档记载,而第二句才是要紧的那一句。getBranch() 返回活动分支。扫描文件里的每一个条目,会给你每一条替代历史的并集,而那正是如果用户放弃了另一条路径你所会拥有的状态。
const rebuild = (ctx: ExtensionContext) => {
const next: GuardBlock[] = [];
for (const entry of ctx.sessionManager.getBranch()) {
if (entry.type === "custom" && entry.customType === "guard.block") {
next.push(entry.data as GuardBlock);
}
}
blocks = next;
};
pi.on("session_start", async (_e, ctx) => rebuild(ctx));
pi.on("session_tree", async (_e, ctx) => rebuild(ctx));
session_start 覆盖一个全新会话或一个被恢复的会话;session_tree 覆盖同一个会话内部的导航。examples/extensions/ 里的 todo 示例两个都注册了,而只要你的状态跟随分支,那个配对就是该照抄的模式。
用 customType 给你的条目做键
customType 是你再次找到自己条目的方式。挑一个带命名空间的字符串,并且绝不为一个不同的负载形状复用它。会话格式文档指出,Pi 自己把虚拟模型路由器状态存为一条 customType 为 pi.virtual-model-state 的 custom 条目,这是一个关于"不属于你的东西该如何命名"的有用信号。
注意什么不是一条 custom 条目:custom_message。会话版本 3 把 hookMessage 角色改名为 custom,以统一扩展,而这两个条目类型现在正是在上下文这个问题上有所区别。CustomEntry(custom)是没有模型可见性的持久状态。CustomMessageEntry(custom_message)是"由扩展注入、确实参与 LLM 上下文的消息"。第 26 章会把这一对拆开来讲。
那条会咬状态代码的生命周期规则
extensions.md 警告:“不要在工厂里启动进程、套接字、观察器或定时器,因为有些调用会在不启动会话的情况下加载扩展。” 它还警告说,重载会"替换扩展运行时,所以 await ctx.reload() 之后的代码绝不能复用旧运行时的状态。"
两个警告说的是同一个错误:把工厂的闭包当作持久的东西。你的工厂在重载后会再跑一遍,在恢复后也会再跑一遍。任何你想让它比运行时活得更久的东西,都必须落在磁盘上,而会话文件已经在那儿了。
你手动做的持久化
有时候状态确实属于会话之外。守卫可能还需要一个跨会话的审计文件,因为"上周这个仓库触发了这个守卫多少次"不是一个分支问题。那就是上面那张表的最后一列:外部存储。用 node:fs,并从 session_shutdown 里写它——那里正是你被告知要释放资源的地方——并保持它幂等,因为取消、重载、会话替换和进程退出,全都汇聚到同一条路径上。
如果你发现自己在写一个外部文件,来记住这段对话已经确立了的某个东西,停手。Pi 有一棵树干这个。
自己验证
pi --extension ./guard.ts
在会话里:让智能体编辑 .env,看着它被阻止,然后运行 /guard-blocks。用 /reload 重载,再跑一次。计数活了下来。现在打开 /tree,导航回到那次阻止之前,再跑一次。计数下降了,因为那次阻止位于你已不在其上的一条分支上。那个行为就是选用条目而不是文件的全部论据。
运行了什么
examples/ch19-state/guard-blocks.ts 是这个守卫组装成一个完整文件后的样子,因为本章的两个片段共享了一些页面没有展示的变量。四个测试带着一个录制型 UI 绑定,把它跑过一个真实的会话:
- 一次受保护的写入被阻止,用户收到一条
warning通知,并且会话里存在一个custom条目,带着那次阻止的数据; - 那个条目永远到不了 provider:后面一次请求里既没有
guard.block,也没有那段理由文本; /guard-blocks把状态读回来;- 状态跟随分支:导航回到那次阻止之前再运行这条命令,报告的是
No blocked calls in this session。
最后一个结果就是选用条目而不是文件的全部论据,它是被观察到的,而不是被断言的。
本章没有解决的问题
它没有告诉你如何让一条 custom 条目在转录记录中可见。渲染一条是 pi.registerEntryRenderer(customType, renderer),有文档记载,但那只在交互模式下可用,并且属于下一章的 UI 工作。
下一章:斜杠命令与自定义 UI。你目前存储的任何东西,人眼都还看不见——一条 custom 条目躺在文件里和你的重建状态里,而转录记录什么都不显示。给这个守卫一个界面,是下一个挂接点,而它的规则结果比看上去更严格。