Pi Agent 源码级教程
F05

扩展(上)—— 三步落位,一次拦截

2,405 字 · 含 31 行代码 · 约 19 分钟

从这一章开始动手写代码。目标是两条:让扩展真的被加载, 以及在工具执行前把它拦下来——后者是「权限控制」在 Pi 里唯一可行的入口。

M07 讲过扩展机制的内部实现(加载器状态机、四十一个钩子怎么分发)。 这一章只讲使用视角:文件放哪、改完怎么生效、写坏了怎么救回来。

三个问题:

  1. 一个 .ts 文件放在三个不同的位置,加载行为有什么区别?
  2. 改完扩展,要重启 Pi 吗?
  3. tool_call 里返回值有 block 和 reason,还有第三个字段是干什么的?
text
   写代码            落位                 生效             验证   ─────            ─────                ─────            ─────   foo.ts  ──>  ~/.pi/agent/extensions/  ──> 自动发现  ──> console.log           ──>  .pi/extensions/         ──> 需项目信任           ──>  pi -e ./foo.ts          ──> 显式加载                                                        └─ /reload 热重载

一、三步落位:-e、全局目录、项目目录

同一个文件,三种放法,行为完全不同。

1.1 -e:只这次算数

powershell
pi -e ./tmp-pif/hello.ts -p "say ok" --no-tools

-e 是 --extension,可以重复多次(--help 里写了 "can be used multiple times")。 它不缓存、不改配置,进程退出就没了。调试时首选这种方式: 路径写错立刻报错,且不污染你的全局目录。

路径不存在时报错原文(本机实跑):

text
Error: Failed to load extension "...\tmp-pif\probe.ts":Extension path does not exist: ...\tmp-pif\probe.tsHint: Start without extensions using "pi -ne".

最后那行 pi -ne 是逃生舱。扩展写坏了导致 Pi 起不来时, 加上 -ne(--no-extensions)绕过全部扩展启动一次,进去把文件删掉。 注意 --help 里的措辞很细:显式 -e 的路径仍然会加载, -ne 关的是「发现」和内置扩展,不是「你亲手指定的那个」。

另外 -e 支持 builtin:<name>,用来单独打开一个内置扩展, 比如 -e builtin:codemode。

1.2 全局目录:放进去就生效

把文件丢进 <agent-dir>/extensions/(默认 ~/.pi/agent/extensions/), 下一次启动自动加载。本机实测的输出:

text
ok[hello] reason=startup

第一行是模型回答,第二行是扩展在 session_start 里打的日志。 删掉文件再跑,第二行就没了。

不需要写进 settings.json。目录扫描就够了。

1.3 项目目录:要过信任闸门

.pi/extensions/ 里的扩展会随项目加载——但只在项目被信任时。 F01 讲的信任闸门在这里生效。同一个仓库,换台机器第一次打开, .pi/ 里的扩展不会加载,直到你按了信任。

1.4 目录扫描的规则:只下一层

discoverExtensionsInDir(extensions/loader.ts:790-880)认三种形态:

形态 例子 认不认
目录里直接的 .ts / .js extensions/foo.ts 认
子目录带 index.ts extensions/bar/index.ts 认
子目录带 package.json 且声明 pi extensions/baz/ 认
子目录再套子目录 extensions/baz/lib/x.ts 不认

源码注释写得很干脆:No recursion beyond one level。 所以别指望按分类建目录树,Pi 只看一层。

一个文件要被认成扩展,形式是 export default function (pi) {...}。 没有默认导出、或者默认导出不是函数,这个文件会被静默跳过。


二、/reload:改完不用重启

改扩展、改设置、改 AGENTS.md,绝大多数情况下在交互模式里敲 /reload 就够。它做的事是:重新发现资源、重建会话状态、 重跑 session_start(reason 是 "reload")。

那条 reason 字段值得单独说。session_start 事件的 reason 有五种(types.ts:774-781):

reason 什么时候
startup 进程启动
reload /reload
new 新会话
resume 恢复旧会话
fork 从某个节点分叉

如果你的扩展在 session_start 里做了初始化,必须对 reload 幂等。 最常见的事故是「每 reload 一次就多注册一份工具」—— 注册两次同名工具会报错,然后整个扩展挂掉。

正确的写法是不在 session_start 里注册任何东西, 只在工厂函数顶层注册一次;session_start 里只做「重建内存状态」。


三、钩子全景:四十一个,常用的十几个

ExtensionAPI 上的 on() 一共 41 个重载(types.ts:1621-1688)。 全列一遍没有意义,按用途分四类,每类挑最常用的:

类别 钩子 你会用来干什么
会话 session_start session_tree session_shutdown 初始化状态、重建状态、收尾
轮次 before_agent_start turn_start turn_end agent_end 改系统提示词、计时、记账
模型 context before_provider_request message_end 裁剪上下文、改请求体、改回复
工具 tool_call tool_result tool_execution_start 拦截、改写结果、打日志
用户 input user_bash 改输入、接管 ! 命令

tool_call 是这一章的主角,tool_result 和 input 在 F06 收尾时再说。

3.1 拦截:tool_call 的三个返回值

ToolCallEventResult(types.ts:1474-1483)只有三个可选字段:

ts
// types.ts:1474-1483(注释已摘成下面三段说明)block?: boolean;reason?: string;terminate?: boolean;

源码的注释比字段本身更有信息量,按三条摘:

block——Block tool execution. To modify arguments, mutate event.input in place instead. 改参数不走返回值,直接改 event.input。

terminate——Hint that the agent should stop after the current tool batch when this call is blocked. Early termination only happens when every finalized tool result in the batch sets this to true.

block: true 拒绝执行。返回给模型的是一个错误结果, 它知道「被拒绝了」以及 reason 里写的理由,可以换个方式重试。

reason 只是给人(和模型)看的说明。不写也能 block, 但模型会收到一个没有解释的失败,通常会原地重试同一个调用。

terminate: true 是容易被忽略的那个。注释写得很精确: 「只有当这一批里每一个最终工具结果都把它设成 true 时, 早停才真的发生」。这是个「与」条件,不是「或」。 你想让 agent 立刻停下,光返回 terminate 不够—— 同批其它调用没有一起表态,agent 还是会继续跑。

想改参数怎么办? 看第一条注释:mutate event.input in place。 不是返回值里放个新 input,是就地把 event.input 改掉。 而且 types.ts:1270-1275 补了一句关键的:

Later tool_call handlers see earlier mutations. No re-validation is performed after mutation.

改完不再校验。你把 read 的 path 改成一个数字,也没人拦你。 这是扩展能造成麻烦的地方,也是它能做「参数规范化」的地方。


四、一个能用的拦截器:permission-gate

仓库自带这个例子(examples/extensions/permission-gate.ts,35 行), 这是最短的可运行拦截器。它的骨架就四步:

ts
const dangerousPatterns = [	/\brm\s+(-rf?|--recursive)/i,	/\bsudo\b/i,	/\b(chmod|chown)\b.*777/i,];

下一步是 pi.on("tool_call", ...),里面按顺序做四件事:

  1. if (event.toolName !== "bash") return undefined;
  2. 取 event.input.command,过一遍 dangerousPatterns.some(...)
  3. 命中则先看 ctx.hasUI:假就 return { block: true, reason: ... }
  4. 真就 await ctx.ui.select(...),用户选了 "Yes" 才放行

完整文件可以在仓库里直接打开看,也可以拷到 <agent-dir>/extensions/ 直接用。下面只标出四个设计点。

先判 toolName 再取 event.input。 不判就去摸 event.input.command, 在 read 调用上拿到的是 undefined,正则不报错,但你就失去了这个钩子。

ctx.hasUI 决定降级策略。 没有 UI 时不能问人, 选择是「直接 block」。-p 和 CI 跑的时候走这条路—— 这就是为什么权限扩展在非交互模式下默认是「更严」而不是「更松」。

返回值 undefined 表示放行。 不是 { block: false }。 两者的差别在实践中不明显,但写 undefined 更清楚:什么都没说。

正则写宽一点,只拦最危险的。 \brm\s+(-rf?|--recursive) 只拦递归删除, 不拦 rm a.txt。拦截器太激进会让 agent 每两步就被打断, 最后你只能关掉它——那才是真正的不安全。

4.1 这个模型的门槛在哪

它匹配的是命令文本。bash -c "rm -rf /" 能拦到, python -c "import shutil; shutil.rmtree('/')" 拦不到; base64 解码后再执行更拦不到。

这不是缺陷,是这类方案的固有边界。真要隔离,得靠容器—— F10 会讲三条隔离线的取舍。


五、三种错误策略:写给会崩的扩展

扩展是会抛异常的。Pi 对着三种情况有三种态度, M07 讲过实现,这里只记结论:

错误发生在 Pi 的态度
扩展加载时(工厂函数抛错) 记为加载失败,其它扩展继续,Pi 正常启动
事件处理器抛错 记日志,该事件的其余处理器照常跑
返回值不合法 当作「没说」处理

第一行是最重要的:一个扩展写坏不会让 Pi 起不来。 所以你调试时不需要每次都 -ne,正常启动,去看看有没有报错就行。

真正会挡住启动的是「路径不存在」这类加载期错误—— F01 实验 3 演示过,它会直接打一行 Error: Failed to load extension。


六、自己动手验证

实验 1:三步落位的差别。

先在 tmp-pif/hello.ts 建:

ts
export default function (pi) {	pi.on("session_start", (event) => {		console.log("[hello] reason=" + event.reason);	});}

三种跑法,观察第二行输出:

powershell
pi -e ./tmp-pif/hello.ts -p "say ok" --no-tools
powershell
Copy-Item ./tmp-pif/hello.ts "$env:USERPROFILE\.pi\agent\extensions\zz.ts"pi -p "say ok" --no-tools
powershell
pi -ne -p "say ok" --no-tools

第三条应该没有 [hello]——这就是 -ne 的作用。 实验完记得删掉那个 zz.ts,否则它会影响你后面所有实验。

实验 2:看 reload 的 reason。

把上面的 hello.ts 改成也打印 reason,然后进交互模式敲 /reload。 你会看到 reason=reload。这一条决定了你的初始化逻辑要不要防重入。

实验 3:亲手拦一次。

把 permission-gate.ts 拷到全局扩展目录,然后让 Pi 干点危险事。 非交互模式下最直观:

powershell
pi -p "run: rm -rf /tmp/nonexistent-dir" 

期望:模型调 bash,扩展返回 Dangerous command blocked (no UI for confirmation), 模型收到错误后改用别的说法或者告诉你它被拦了。

改一处试试

把 permission-gate 的正则改宽一点,比如加上 /\bdel\s+/i(Windows 的删除命令)。 然后重复实验 3。你会立刻发现一个问题:这个正则对 bash 工具生效, 但 Windows 上实际用的是 powershell 工具——event.toolName !== "bash" 那行直接把它挡在门外了。

这正是本章想让你带走的一点:拦截器的覆盖面, 取决于你判了哪些 toolName。要拦 PowerShell,得再写一个分支。


七、工程暗坑

坑一:在 session_start 里注册工具。 reload 一次注册一次,第二次报重名,扩展整体失效。 注册放工厂顶层,session_start 只重建状态。

坑二:改了 event.input 之后以为会被校验。 不会。类型上是 Record<string, unknown>,运行时也不复查。 改参数要自己保证合法。

坑三:terminate 单独返回不管用。 必须是同一批所有最终工具结果都为 true。想让 agent 停, 更可靠的做法是把 reason 写清楚,让模型自己决定不继续。

坑四:以为 -ne 把所有扩展都关了。 显式 -e 的路径仍然加载。这个设计是对的——否则你没法在 「怀疑某个自动发现的扩展有问题」时,只保留自己那个调试扩展。

坑五:.pi/extensions/ 里写了代码,但没生效也不报错。 先查信任。没信任时整个 .pi/ 被跳过,包括扩展、技能、提示词, 而且不会提示你。见 F01 那节的五级判定。


八、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/extensions/types.ts 2,329 on() 41 个重载、ToolCallEventResult
packages/coding-agent/src/core/extensions/loader.ts 881 discoverExtensionsInDir 三种形态
packages/coding-agent/src/core/extensions/runner.ts 1,566 事件分发与错误策略
packages/coding-agent/examples/extensions/permission-gate.ts 35 拦截器的最小样本
packages/coding-agent/examples/extensions/todo.ts 305 F06 的主体样本

九、下一章

会拦了,下一步是「自己造一个工具」。F06 拆 registerTool 的全部参数, 用 todo.ts 走一遍状态存哪、怎么在分叉之后自动恢复, 以及 TUI 里怎么给自己的工具画一块专门的显示区。