你的第一个扩展
扩展(extension)是一个默认导出接收 ExtensionAPI 的 TypeScript 模块;这里给出能工作的最小工具、它如何被加载,以及工厂函数的生命周期规则。
评审守卫可以请模型去运行 scripts/run-checks.sh。它无法提供一个新的操作、拦住一条危险的命令,或者显示一行状态。这些需要代码,而 quickstart.md 毫不含糊:可执行的工具、命令或事件处理器,就意味着一个扩展。
本章构建的是能做一件技能做不到的事的最小的扩展。
扩展是什么
extensions.md:扩展是被加载进 Pi 进程的 TypeScript 模块,它们的工厂函数会注册工具、命令、快捷键、provider、事件处理器、渲染器和终端 UI。
把第一句再读一遍,因为它回答了安全问题:一个扩展运行在 Pi 进程内部,带着同样的操作系统权限,并且它可以检查提示词、工具调用、文件、凭据和会话历史。只从你信任的来源加载扩展。
错误:"一个里面带脚本的技能就是一个扩展。"
正确:"技能是模型阅读的指令,加上一组它可能运行的文件。扩展是 Pi 加载并调用的 TypeScript。当你需要 registerTool、registerCommand 或 pi.on 的那一刻,你已经跨过了信任边界。"
契约
一个扩展导出一个默认工厂函数,它接收 ExtensionAPI。Pi 使用 jiti,所以本地的 TypeScript 扩展不需要单独的编译步骤。
下面是最小的命令扩展,来自文档:
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function (pi: ExtensionAPI) {
pi.registerCommand("hello", {
description: "Show a greeting",
handler: async (name, ctx) => {
ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
},
});
}
启动 Pi 并运行 /hello。在开发过程中,可以直接加载一个文件而不安装它:
pi --extension ./hello.ts
这个一条命令的循环,就是先用 TypeScript 写扩展、而不是先去构建并安装一个包的理由。
这个一贯示例:一个工具
extensions.md 描述了一个自定义工具是什么:一个名字、一段面向模型的描述、一个 TypeBox 参数 schema,以及一个 execute() 函数。它的结果需要面向模型的 content 和一个 details 字段。
下面是评审守卫的第一个工具,它使用 defineTool 和 Type,与随附的 examples/extensions/hello.ts 完全一样:
import { Type } from "@earendil-works/pi-ai";
import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
const reviewScopeTool = defineTool({
name: "review_scope",
label: "Review Scope",
description:
"List the files changed in this repository and the checks this project defines. " +
"Use before reviewing a diff so findings cover the files that actually changed.",
parameters: Type.Object({
base: Type.Optional(
Type.String({
description: "Optional git ref to compare against. Defaults to the working tree.",
}),
),
}),
async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
const base = params.base?.trim() || "";
const diffCmd = base ? `git diff --name-only ${base}` : "git status --short";
return {
content: [
{ type: "text", text: `Run \`${diffCmd}\` and report the changed files.` },
],
// details is for rendering or state reconstruction; keep it small.
details: { base: base || null, diffCmd },
};
},
});
export default function (pi: ExtensionAPI) {
pi.registerTool(reviewScopeTool);
}
把它保存为 .pi/extensions/review-scope.ts,然后运行 /reload。
重要的五个字段
| 字段 | 用途 |
|---|---|
name |
模型用什么名字调用它 |
label |
它在终端里如何渲染 |
description |
模型读它来决定是否调用 |
parameters |
参数的 TypeBox schema |
execute() |
实现 |
描述不是文档。它是模型选择这个工具而不是 bash 的唯一依据。“List the files changed in this repository and the checks this project defines. Use before reviewing a diff” 既告诉模型这个工具做什么,也告诉模型什么时候用。
content 与 details
结果携带两类信息:content 给模型,details 给渲染或状态重建。当没有结构化的东西要保留时,用 details: undefined。
上面的例子在 content 上故意做得很薄——它告诉模型该运行什么,而不是替它运行。对第一个扩展来说,这是诚实的:一个每次调用都要去执行外部命令的工具,相比 bash 什么也挣不到。第 17 章会用真正的执行、outputSchema 和嵌套调用来替换它。
带进那一章的一条纪律:从 execute() 抛出会产生一个失败的工具结果,而返回一个对象不会把它标记为错误。一个做不了这件事的工具应当在文本里说明,或者抛出,而不是返回一个读起来像成功的对象。
把它放在哪
extensions.md:把扩展放在你的用户或项目扩展目录里。Pi 会加载直接的 TypeScript 或 JavaScript 文件,以及含有 index.ts 或 index.js 入口点的子目录。
小扩展用单个文件,多文件的实现用目录。把 npm 依赖放在附近的 package.json 里。
对这个一贯示例来说:
.pi/
├── extensions/
│ └── review-scope.ts # 一个文件,一个工具
├── skills/
│ └── review-guard/
└── prompts/
└── review.md
.pi/extensions/ 需要项目信任,如第 8 章所确立。在你授予它之前,这个工具不存在,而第 13 章的技能会在没有它的情况下触发——在审查输出时值得记住这一点。
选择一个挂接点
extensions.md 给出了这张表,它是关于一个扩展能做什么的最快的地图:
| 能力 | 主要 API |
|---|---|
| 观察或修改生命周期行为 | pi.on() |
| 添加一个模型可调用的操作 | pi.registerTool() |
添加一个 / 命令 |
pi.registerCommand() |
| 添加快捷键或 CLI 标志 | pi.registerShortcut() 或 pi.registerFlag() |
| 发送用户消息或自定义消息 | pi.sendUserMessage() 或 pi.sendMessage() |
| 持久化非上下文的会话数据 | pi.appendEntry() |
| 改变活动工具、模型或思考级别 | pi 上的会话控制方法 |
| 添加一个模型 provider | pi.registerProvider() |
| 添加一个 MCP 服务器 | pi.registerMcpServer() |
| 把每个请求路由到一个模型 | pi.registerVirtualModel() |
| 添加终端渲染 | 渲染器注册和 ctx.ui |
| 与另一个扩展通信 | pi.events |
flowchart TD
LOAD["发现"] --> TRUST{"项目扩展?"}
TRUST -->|"是,但尚未被信任"| SKIP["完全不会被加载"]
TRUST -->|"否,或已授予信任"| FAC["工厂函数运行<br/>可以是异步的;Pi 会等待"]
FAC --> REG["你注册的东西<br/>工具、命令、处理器、provider"]
REG --> START["session_start<br/>在这里启动进程、套接字、计时器"]
START --> RUN["会话运行"]
RUN --> SHUT["session_shutdown<br/>幂等的清理"]
REL["/reload"] -.->|"替换运行时"| FAC
CANCEL["取消、替换会话、退出"] -.->|"全部汇聚到这里"| SHUT
工厂函数那个方框是任何东西都不能被启动、而一切都可以被注册的地方——这个区分就是规则 2 的全部,而来自 session_start 的那支箭头就是补救。虚线的 REL 箭头是下面的规则 4:一次重新加载会构建一个新的运行时,所以旧运行时捕获的任何东西都过期了。进入 session_shutdown 的三支虚线箭头,是规则 3 要求幂等性的原因。
工厂函数的生命周期规则
这是导致真实 bug 的部分,而 extensions.md 陈述了三条约束:
- 工厂函数可以是同步的或异步的。在启动继续之前,Pi 会等待一个异步的工厂函数,使它能获取配置或注册启动期间需要的 provider。
- 不要在工厂函数里启动进程、套接字、监视器或计时器,因为某些调用会在不启动会话的情况下加载扩展。从
session_start、或从需要这些资源的命令或工具那里启动长生命周期的资源。 - 用一个幂等的
session_shutdown处理器关闭会话作用域的资源。
幂等之所以要紧,是因为 extensions.md 解释了原因:取消、重新加载、替换会话和进程退出,可能汇聚到同一条清理路径上。
一个只做注册的工厂函数——像我们的这个——不做别的事,就同时满足了这三条。
重新加载会让状态失效
extensions.md 毫不含糊:重新加载会替换扩展运行时,所以 await ctx.reload() 之后的代码不得复用来自旧运行时的状态。只有个人的和显式的命令行扩展,才能参与在项目扩展加载之前运行的 project_trust 事件。
各种模式并不一致
扩展会在交互式、RPC、JSON 和 print 模式下加载。交互式模式提供完整的终端 UI。RPC 可以通过 RPC Extension UI 协议转发受支持的对话框和通知,但不能转发自定义的终端组件;JSON 和 print 模式完全没有 UI。
用 ctx.mode === "tui" 来限定只对终端成立的行为,用 ctx.hasUI 处理交互式与 RPC 客户端都支持的交互。让工具和事件的行为独立于渲染,这样非交互模式仍然可用。
我们的 review-scope.ts 完全没有 UI,这意味着它在四种模式下都能工作。这是一个值得刻意去选择的属性。
运行了什么
本章的这些扩展是 examples/ch15-first-extension/ 里的文件。它们用 TypeScript 编译器针对锁定的 1.0.4 声明编译,然后被加载进一个来自 pi-coding-agent 的真实 AgentSession:真实的扩展运行时、真实的内置工具、一个内存中的会话。唯一的替换是模型,它是 pi-ai 的 faux provider,重放一段脚本。测试骨架里没有任何东西重新实现一条 Pi 规则。第 16 到 21 章使用同一个测试骨架,而第 20 和 21 章还替换了界面,以及在 MCP 的情形下替换了连接的远端。
这里的测试确立了什么:
- 注册一个
direct工具会让它变为活动,而一次脚本化的工具调用会跑过 Pi 自己的流水线,并产生一个带有代码所返回的content和details的工具结果; - 这个命令被注册在内置命令旁边。
它们也发现了本章第一稿里的一个缺陷。base 被声明为 Type.String(...),而它的描述说的是可选,所以一个照着描述去做、因而省略它的模型,会发出不符合 schema 的参数。它现在是 Type.Optional(Type.String(...)),并且有一个测试用不带参数的方式调用这个工具。一个参数的描述和一个参数的 schema 是两个陈述,而只有 schema 会被检查。
接下来的三步
这个扩展注册了某个东西,然后就停在那里。仍然缺三样东西,而每一样的缺失各有不同的原因:
- 16 加入事件,因为一个只是存在的工具无法介入。
tool_call是唯一一个在工具运行之前触发的钩子,而它就是拦住强制推送的东西。 - 17 把这个工具讲具体,因为注册它和模型看见它是两个不同的事实,而两者都不是许可。
- 18 改变模型所知的内容,因为一个模型不知道的工具,就是模型会用
bash绕开的工具。
从 .pi/extensions/review-scope.ts 开始,然后 /reload,然后让 Pi 使用这个工具。