← Pi Agents

扩展状态与持久化

一个扩展把状态放在哪里,才能让它在重载、恢复和分叉之后活下来,以及为什么答案几乎总是一条会话条目,而不是一个模块变量。

你的 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 条目躺在文件里和你的重建状态里,而转录记录什么都不显示。给这个守卫一个界面,是下一个挂接点,而它的规则结果比看上去更严格。