← Pi Agents

事件与扩展生命周期

Pi 按注册顺序把具名事件分派给处理器;这里讲一次运行的生命周期、每个事件可以返回什么,以及一个建立在 tool_call 上的强制推送守卫。

评审守卫可以建议运行这些检查。它拦不住模型在解决一个冲突时决定去运行的那次 git push --force。

只有一个 tool_call 处理器能做到这件事,因为 tool_call 在调用运行之前触发。要把这件事做对,需要知道生命周期,因为处理器按注册顺序运行,而一个返回值只对声明了要接受返回值的事件有意义。

事件如何分派

extensions.md 陈述了三条规则:

  • 处理器按扩展的加载与注册顺序运行。
  • pi.on() 返回一个函数,它取消那次注册;这些改动不会影响一次已经正在进行的分派。
  • 有些事件只作通知;另一些会转换数据、替换结果或取消一次操作。

然后是那条能防住大多数错误的话:

使用每个事件声明的结果类型,而不要假设每一个返回值都有效果。

处理器按流顺序被 await,所以一个慢的处理器会拖慢流的消费。处理器的错误会被报告,而不改变 provider 响应——下面会提到一个例外。

一次运行的形状

extensions.md 这样描述它:一次运行从 input 和 before_agent_start 开始,穿过模型、消息和工具事件,到达 agent_end。自动重试、恢复、压缩或排队的工作可能在此之后继续。

最后那句才是要紧的。agent_end 不是终点。

    sequenceDiagram
  participant U as 你
  participant P as Pi
  participant H as 处理器
  U->>P: 提交一条提示词
  P->>H: input
  P->>H: before_agent_start
  P->>H: agent_start
  loop 每轮一次
    P->>H: turn_start
    P->>H: message_start, message_update, message_end
    P->>H: tool_call,在工具运行之前
    H-->>P: 阻止,或一份打过补丁的输入
    P->>H: tool_result
    P->>H: turn_end
  end
  P->>H: agent_end
  P->>H: agent_before_settle
  H-->>P: 条目,以及 continue true
  P->>H: agent_settled
  Note over H: continue true 换来再一次请求
  

那里的每一支箭头都有文档记载。被刻意略去的是 Pi 没有为之定位的一切:provider_stream_event、session_before_compact、user_bash 和 cache_warming_decision 在这次运行中没有被说明的位置,所以它们留在图之外,改而在下面的表格里出现。

有两支边界结束这个序列:

  • agent_before_settle 是最后一个可行动的边界:它可以追加条目,并请求一次继续。
  • agent_settled 是终局性的,且仅作通知;当一个集成需要知道 Pi 不会自动继续时,使用它。

与 turn_end 并列,agent_before_settle 是一个可行动的边界。它的处理器可以串起提议的 custom、custom_message、context_edit 或 compaction 条目,并为下一次模型请求返回 continue: true。要守住条件,因为一次无条件的继续可能形成循环。

错误:"agent_end 意味着智能体已经完成了。"
正确:"agent_end 结束的是一次低层运行。agent_before_settle 是最后一个仍然能添加工作的边界,而 agent_settled 是一个通知:不会再有事情自己发生。"

那些改变行为的事件

与其罗列每一个事件名,下面是那些扩展作者会去抓的事件:

事件 形状 它能做什么
project_trust cwd、mode、hasUI、ui、trusted 返回 { trusted: "yes" | "no" | "undecided" };第一个做出决定的拥有它
session_start reason(startup、reload、new、resume、fork) 获取会话作用域的资源
session_shutdown reason、targetSessionFile? 幂等地释放它们
input text、images?、source、streamingBehavior? 继续、转换文本,或自行处理它
before_agent_start prompt、images?、systemPrompt、systemPromptOptions 注入一条消息或替换提示词
tool_call toolName、input、toolCallId 修改 event.input,或 { block: true, reason }
tool_result result 替换 content、details、structuredContent、isError、usage
message_end message 替换已定稿的消息,保留它的角色
turn_end turnIndex、message、toolResults 追加条目,返回 continue: true
agent_before_settle 边界状态 同样的事,作为最后的机会
session_before_compact preparation、reason、willRetry、signal 取消,或提供你自己的摘要
user_bash command、excludeFromContext、cwd 自行处理这条命令

这个守卫

回到强制推送。下面是整个扩展:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

const BLOCKED = [
	/\bgit\s+push\b[^\n]*(--force|-f)\b/,
	/\bgit\s+reset\s+--hard\b/,
	/\bgit\s+clean\b[^\n]*-[a-z]*f/,
];

export default function (pi: ExtensionAPI) {
	pi.on("tool_call", async (event, ctx) => {
		if (event.toolName !== "bash" && event.toolName !== "powershell") return;

		const raw = JSON.stringify(event.input);
		const hit = BLOCKED.find((re) => re.test(raw));
		if (!hit) return;

		if (!ctx.hasUI) {
			// No way to ask. Refuse rather than allow silently.
			return { block: true, reason: `Guard blocked: ${hit.source}` };
		}

		const ok = await ctx.ui.confirm(
			"This command rewrites history or destroys work. Allow?",
			raw.slice(0, 200),
		);
		if (ok) return;

		return { block: true, reason: "Blocked by review-guard extension" };
	});
}

有四点值得点名。

event.input 是被就地修改,而不是被替换——ToolCallEventResult 说要通过修改 event.input 来改变参数,而结果类型只携带 block、reason 和 terminate。

ctx.hasUI 守住了这个对话框。extensions.md 说,对交互式和 RPC 客户端都支持的交互用 ctx.hasUI,对只限于终端的行为用 ctx.mode === "tui"。一次 print 模式的运行没有 UI,而那里诚实的行为是拒绝。

这些正则对着整个序列化后的输入匹配,因此能抓住埋在一条更长命令里的强制推送。这是一件钝器;一个工具调用屏蔽清单是一个启发式,而诚实的说法是它提高了一次事故的代价,而不是防范一个铁了心的人。

一个不带 reason 的 block: true 没给模型任何可用的东西。永远要提供一个。

错误的失败方式不同

extensions.md 区分了两条错误路径,而这种不对称是要紧的:

  • 一个 tool_call 处理器的失败会作为一种故障保护而阻止该工具。
  • 一次工具执行的失败会变成给模型的一个错误结果。

所以一个每次调用都抛出的守卫扩展会拦住每一次调用。这是安全的,而它同时也是一次全面停机。要在处理器内部捕获。

并发规则

来自 extensions.md 的三条约束会改变你写处理器的方式:

  1. 来自一条助手消息的工具调用可能并行运行。当另一个工具事件运行时,不要假设存在一个兄弟调用或兄弟结果。
  2. 对由活动一轮拥有的嵌套工作,用 ctx.signal;命令和空闲的会话事件通常没有操作信号。
  3. 一个返回 undefined 的 user_bash 处理器会把命令传给下一个处理器,如果没有处理器处理它,就交给本地执行。返回 operations 或 result 会停止传播。一个处理器的失败会阻止该命令,而不是继续下传。

第 1 点是那个会绊住人的。一个假设自己按顺序看到调用的守卫,会在一条助手消息同时发出两个工具调用时出现竞态。要让处理器彼此独立。

两个你不该改写它们的事件

provider_stream_event 在 Pi 归一化每一个已解析的 provider 流事件之前为它触发。extensions.md 说要把它当作只读,因为修改可能影响归一化,并且它仅作通知且不被持久化。它是一个调试面,不是一个控制面。

cache_warming_decision 可以用 { action: "warm" } 或 { action: "stop" } 覆盖一次空闲的提示词缓存刷新,而最后一个返回某个动作的处理器胜出。注意这条规则:最后者胜,不是最先者。在叠两个都回答它的扩展之前,值得知道这一点。

一个扩展,几个钩子

一个现实的守卫会注册一个命令、一个事件和一些 UI:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
	let blockedThisRun = 0;

	pi.registerCommand("guard-status", {
		description: "Show how many calls review-guard has blocked this run",
		handler: async (_args, ctx) => {
			ctx.ui.notify(`review-guard blocked ${blockedThisRun} call(s)`, "info");
		},
	});

	pi.on("session_start", async () => {
		blockedThisRun = 0;
	});

	pi.on("tool_call", async (event, ctx) => {
		if (event.toolName !== "bash") return;
		const raw = JSON.stringify(event.input);
		if (!/\bgit\s+push\b[^\n]*(--force|-f)\b/.test(raw)) return;

		const ok = ctx.hasUI
			? await ctx.ui.confirm("Allow a force push?", raw.slice(0, 200))
			: false;

		if (ok) return;
		blockedThisRun += 1;
		return { block: true, reason: "Blocked by review-guard: force push requires --force-with-lease" };
	});
}

两个顺序上的细节。计数器在 session_start 里重置,而不是在工厂函数里——一个在工厂函数里初始化的模块级变量会存活到重新加载为止,而 session_start 每个会话只触发一次,那正是你想要的粒度。并且,因为处理器按加载与注册顺序运行,如果另一个扩展也守卫 bash,那么先加载的那个先看到这次调用。

清理

extensions.md 要求三件事:即使在正常操作已经尝试过清理之后,也要在 session_shutdown 里释放资源;保持清理幂等,因为取消、重新加载、替换会话和进程退出汇聚到同一条路径上;并且用 ctx.shutdown() 请求一次有序的进程关闭。

我们的守卫不持有任何资源,所以没有东西要释放。这是一个正当的结果,而且它值得作为目标。

运行了什么

examples/ch16-events/ 把两个守卫加载进一个真实的会话,并驱动一个会请求 bash 的脚本化模型。这些命令包含 touch ran.flag,所以"它被拦住了吗?“是一个存在或不存在的文件,而不是一次推断:

  • 在没有人可问的情况下,强制推送守卫拒绝,结果是一个模型能读懂的错误,而 ran.flag 永远不会被创建;
  • 一条普通命令会原样通过,并且真的运行;
  • git reset --hard 被同一个守卫拒绝;
  • 多钩子版本以 --force-with-lease 这个理由拒绝;
  • 一个会抛出的 tool_call 处理器会作为一种故障保护而阻止该工具,同样地,不出现任何文件。

最后一个是有文档记载的故障保护,已观察。它也是要在守卫内部捕获错误的原因:一个每次调用都抛出的守卫是一次全面停机,而不是一扇开着的门。

要验证什么

/reload
提问:"push my branch forcefully"
预期:守卫会提问,而阻止会报告一个理由。

然后测试那条无 UI 的路径,它是最可能出错的那条:

pi -ne --print "run git push --force origin main"

由于 -ne 会禁用扩展,这条命令不会被守卫——这正是测试两条路径的意义所在。去掉 -ne 来检查你自己的守卫的 print 模式分支。

这个守卫拦截发生了的调用。它对从未发生的调用什么都没说,因为一个模型看不见的工具不会产生可供拦截的 tool_call 事件。第 17 章把它拆开:注册实际上保证了什么、暴露方式又增加了什么,以及一个工具在一个许可扩展不经询问就放它通过之前必须声明什么。