从一个扩展里注册一个工具和一个命令
加载一个注册了模型可调用工具和斜杠命令的 TypeScript 扩展,并看着这个工具跑过 Pi 真实的流水线。
扩展(extension)是一个默认导出接收 ExtensionAPI 的 TypeScript 模块。注册一个工具会让它变为活动并向模型声明,而注册一个命令会在内置命令旁边添加一个 / 命令。这个页面同时加载最小的命令扩展和这个一贯示例的 review_scope 工具;唯一的替换是模型,一个重放脚本的 faux provider。
运行它
Pi 1.0.4 用 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 --extension ./hello.ts 加载它,然后运行 /hello。
这个一贯示例是一个工具而不是一个命令。review_scope 用 defineTool 和 Type 声明,并用 pi.registerTool 注册。它的 base 参数是 Type.Optional(Type.String(...)),所以一次不带参数的调用是有效的,并默认使用工作树;传入 { base: "main" } 会指定 git diff --name-only main。
| 用什么注册 | 它添加什么 | 它如何出现 |
|---|---|---|
pi.registerCommand("hello", …) |
一个 /hello 命令 |
与内置命令并列 |
pi.registerTool(reviewScopeTool) |
一个模型可调用的工具 | 活动并向模型声明 |
预期结果
这是已观察:first-extension.test.ts 把每个扩展加载进一个带有脚本化 faux provider 的真实 AgentSession,并断言下面这些。
| 扩展 | 步骤 | 结果 |
|---|---|---|
| command | getRegisteredCommands() |
包含 hello,与内置命令并列 |
| tool | getActiveToolNames() |
包含 review_scope——一个 direct 工具在注册时激活 |
| tool | model calls review_scope with { base: "main" } |
isError: false;文本点明 git diff --name-only main;details 是 { base: "main", diffCmd: "git diff --name-only main" } |
| tool | model calls review_scope with {} |
isError: false;文本点明 git status --short |
机制与局限
有文档记载: 导出的 ExtensionAPI 类型定义了默认工厂函数契约、pi.registerCommand、pi.registerTool 和 defineTool。一个 direct 工具(默认的 exposure)在注册时被激活并向模型声明,而一个工具结果携带面向模型的 content 外加一个 details 字段。
已观察: first-extension.test.ts 通过真实运行时——真实的扩展加载器、真实的内置工具、一个内存中的会话——运行这个扩展,并断言一个已注册的工具是活动的、一次脚本化的调用产生一个 toolResult、其 content 和 details 与 execute() 所返回的相符,以及这个命令被注册了。它还钉住了一个缺陷:base 最初被声明为必需的 Type.String(...),而它的描述称它可选,所以一次不带参数的调用会不符合 schema。它现在是 Type.Optional(Type.String(...)),并有一个针对空调用的测试。参数描述和参数 schema 是两个陈述,而只有 schema 会被检查。
局限: 注册一个工具让它存在并被声明;它不是运行的许可,而模型仍然可能忽略它(第 17 章)。.pi/extensions/ 下的一个项目扩展在项目被信任之前完全不会加载(第 8 章),所以在那之前,一个技能会在没有这个工具的情况下触发。这个测试使用一个 faux 模型,所以它展示的是模型周围的代码,而不是一个真实模型会选择 review_scope。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.