深入讲解工具
一个工具声明一个名字、一段描述、一个 schema 和一个 execute();本章讲暴露方式、注解、结构化输出、terminate 和嵌套调用。
第 15 章的 review-scope 工具告诉模型该运行哪条命令。那是一个形状像建议的工具。本章把它变成一个形状像工具的工具:它执行、它返回结构化数据、它声明自己的风险,而且它知道自己是否对模型可见。
五种暴露方式
exposure 控制模型如何够到一个工具。“可调用"意味着可以通过 ctx.executeTool() 从其他工具调用它——这正是 codemode 脚本所做的事。
| 暴露方式 | 是否向模型声明 | 是否可从 ctx.tools 调用 |
|---|---|---|
direct(默认) |
活动期间 | 活动期间 |
model-only |
活动期间 | 从不 |
codemode |
仅在显式激活时 | 只要已注册 |
deferred |
仅在显式激活时 | 只要已注册,但不被 codemode 列出 |
hidden |
从不 | 从不 |
这五行坐在一条更短的流水线——存在、活动、已声明、被调用——之上,而把这几步中的任何两步并成一步,是最常见的工具 bug:
flowchart TD
A["registerTool"] --> B["这个工具存在"]
B --> C{"exposure"}
C -->|direct, model-only| D["注册时即激活"]
C -->|codemode, deferred, hidden| E["已注册但不活动"]
E --> F["pi.setActiveTools 名字"]
F --> D
D --> G["活动集就是模型看到的东西"]
G --> H["模型发出一个工具调用"]
H --> I["tool_call 处理器可以阻止或改写它"]
I --> J["execute 运行"]
J --> K["content 与 details,或 structuredContent"]
注册一个
direct或model-only工具会激活它;其他暴露方式不会在注册时被激活。
活动集就是向模型声明的那组工具,所以激活与声明是一步而不是两步。并且一个工具无法被注销:要撤回一个,用 exposure: "hidden" 重新注册它。
错误:"我注册了它,所以模型可以调用它。"
正确:"注册让一个工具存在。暴露方式决定它是否向模型声明、是否可从 ctx.executeTool 调用、两者皆是、或两者皆非。激活是把它放进已声明集的那个动作。"
为这个守卫选择一种暴露方式
评审守卫想从同一份代码里得到几样不同的东西:
run_checks——模型应当直接调用它。direct。collect_diff——对其他工具有用,但不值一行声明。codemode。dangerous_commands——一张其他代码查阅的查找表;任何东西都不会调用它。deferred。
import { Type } from "@earendil-works/pi-ai";
import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
export const runChecks = defineTool({
name: "run_checks",
label: "Run Checks",
description:
"Run this repository's own type check and unit tests and return the results. " +
"Use before reviewing a diff or claiming a change is verified.",
annotations: { readOnlyHint: true, openWorldHint: false },
exposure: "direct",
parameters: Type.Object({
skipTests: Type.Optional(Type.Boolean({ description: "Run only the type check.", default: false })),
}),
async execute(_id, params, _signal) {
const steps = params.skipTests ? ["pnpm typecheck"] : ["pnpm typecheck", "pnpm test:unit"];
const results = await Promise.all(steps.map((command) => runCommand(command)));
return {
content: [{ type: "text", text: results.map((r) => r.output.slice(0, 1000)).join("\n") }],
details: { steps, results: results.map((r) => ({ exit_code: r.exit_code })) },
};
},
});
export default function (pi: ExtensionAPI) {
pi.registerTool(runChecks);
}
runCommand 由你自己提供。下面是一个把非零退出当数据返回的实现,它与第 6 章为内置 bash 工具给出的规则相同:
import { exec } from "node:child_process";
import { promisify } from "node:util";
const execAsync = promisify(exec);
export async function runCommand(command: string): Promise<{ output: string; exit_code: number }> {
try {
const { stdout, stderr } = await execAsync(command, { maxBuffer: 1024 * 1024 });
return { output: stdout + stderr, exit_code: 0 };
} catch (err: any) {
// exec rejects on a non-zero exit. That is a result, not a tool failure.
return { output: `${err.stdout ?? ""}${err.stderr ?? ""}`, exit_code: err.code ?? 1 };
}
}
承载本章的是这两行:exposure: "direct" 和 annotations: { readOnlyHint: true, openWorldHint: false }——后者正是让第 16 章的守卫无需为每次调用都提问、就能对这个工具做出推理的东西。
注解是提示,不是事实
readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint 与 MCP 工具注解含义相同。extensions.md 对默认值讲得很明确:缺失的提示取 MCP 默认值,所以一个工具不是只读的,并且可能是破坏性的、可能抵达一个开放世界。这些提示没有被验证,但一个许可扩展可以用它们来决定确认哪些调用。
下面是文档展示的那个许可扩展:
pi.on("tool_call", async (event, ctx) => {
const hints = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
const needsApproval =
hints?.destructiveHint === true ||
(!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
return { block: true, reason: `${event.toolName} was not approved` };
}
});
仔细读这个默认值:完全没有任何注解时,needsApproval 为 true。一个从不声明自己提示的工具,会被进程里每一个许可扩展当作危险的。在准确的地方声明 readOnlyHint: true 不是文档——它是你如何免于被提问而被调用的方式。
返回数据而不是文本
extensions.md 精确地划出了这条线:
当结果是数据时,声明
outputSchema并返回一个匹配的structuredContent。模型仍然收到content;而诸如 codemode 脚本这样的程序化调用方收到的是structuredContent而不是文本。
所以一个工具可以同时回答两类受众。content 是给模型的散文;structuredContent 是给脚本的一个值。
import { Type } from "@earendil-works/pi-ai";
export const failingTests = defineTool({
name: "failing_tests",
label: "Failing Tests",
description: "List the currently failing unit tests, grouped by file. Use when deciding what to fix.",
parameters: Type.Object({}),
outputSchema: Type.Object({
files: Type.Array(
Type.Object({ path: Type.String(), failed: Type.Integer(), names: Type.Array(Type.String()) }),
),
}),
async execute() {
const files = [
{ path: "src/auth/refresh.ts", failed: 2, names: ["refreshes expired token", "retries once"] },
];
return {
content: [{ type: "text", text: `${files.length} file(s) with failing tests.` }],
structuredContent: { files },
details: { count: files.length },
};
},
});
然后是失败情形,那是人们会搞错的那个:
要报告一个仍然携带数据的失败,请返回带
isError: true的结果,而不是抛出:模型看到一个错误,而脚本仍然收到structuredContent。
没有数据时抛出。有数据并且有错误时,返回 isError: true。
截断是一份契约
extensions.md 指示:截断面向模型的大型结果,并告诉模型去哪里读完整的输出。
bash 立下了先例——它的 output 最多容纳 1 MiB,更长的输出会在一个省略标记周围保留开头和结尾的 512 KiB,而 full_output_path 保存其余部分。你的工具应当照做,并在 content 里点明那个文件名,这样模型需要时就能读它。
terminate 与顺序执行
extensions.md:只有当智能体应当在该批次中每一个已完成的工具都同意终止时,跳过它的自动后续,才返回 terminate: true。
“该批次中每一个已完成的工具"这句话在起着真实的作用。三个并行调用中的一个 terminate: true 什么也不做。
当工具共享可变的内存状态时,使用顺序执行。会修改文件的工具应当用 withFileMutationQueue() 包住完整的读—改—写操作。
嵌套调用
一个工具可以用 ctx.executeTool(name, args, { signal, onUpdate }) 运行其他工具。有文档记载的后果,每一条都要紧:
- 嵌套调用像模型发出的调用一样,经过参数验证以及
tool_call和tool_result处理器。你第 16 章的守卫看得见它们。 - 它们发出
tool_execution_start、tool_execution_update和tool_execution_end,全都携带parentToolCallId,而toolCallId由 Pi 指派为<parent id>/<n>。 - 这些 id 从不在转录记录中作为工具调用或工具结果出现。
- 嵌套调用不添加转录记录条目;它们的结果只抵达调用方工具。
- 会话在调用方工具的结果消息上保留一份有界的记录,形式是
nestedCalls——名字、参数、状态、时长、错误,从不是结果。每次调用超过 8 KiB 或每个工具结果超过 32 KiB 的参数会被省略,最多保留 256 次调用,而complete: false标记一份丢失了任何东西的记录。 - 嵌套结果(在每一个深度上)的
usage,会被加到调用方工具结果的usage上。
最后一点与 message-types.md 配对,后者说一个工具结果的可选 usage 报告嵌套的模型工作,并贡献给全会话统计。你的工具只报告自己的 usage;它的子级的 usage 被叠加上去。
export const reviewDiff = defineTool({
name: "review_diff",
label: "Review Diff",
description: "Run the project's checks and list failing tests for the changed files, then summarise both.",
parameters: Type.Object({}),
// ctx is the fifth argument: an ExtensionToolContext, which is the extension
// context plus executeTool().
async execute(_id, _params, signal, onUpdate, ctx) {
const checks = await ctx.executeTool("run_checks", {}, { signal, onUpdate });
const tests = await ctx.executeTool("failing_tests", {}, { signal, onUpdate });
// executeTool() never rejects for a tool failure. It resolves to an outcome,
// { toolCall, result, isError }, and the tool's own content and
// structuredContent are on outcome.result.
const checksText = checks.result.content.find((c) => c.type === "text")?.text ?? "none";
return {
content: [
{ type: "text", text: `checks${checks.isError ? " (failed)" : ""}: ${checksText}` },
{ type: "text", text: `tests: ${tests.result.structuredContent ? JSON.stringify(tests.result.structuredContent) : "none"}` },
],
details: { nested: ["run_checks", "failing_tests"] },
};
},
});
因为嵌套调用会经过 tool_call,所以像这样的一个编排器会继承你的守卫。这是一个特性:守卫适用于模型从未看见的代码路径。
动态激活
extensions.md 给出了这个模式:先注册每一个工具,让可选的工具保持不活动,并用一个加载器工具通过 pi.setActiveTools() 选出想要的活动工具。名字必须已经注册;未知的名字被忽略。
pi.on("tool_call", async (event) => {
if (event.toolName !== "review_diff") return;
const current = pi.getActiveTools();
if (!current.includes("failing_tests")) {
pi.setActiveTools([...current, "failing_tests"]);
}
});
Pi 在转录记录的第一条系统消息里记下初始提示词和工具集,然后在下一次模型请求之前追加工具和提示词的变化。无法表示这个转换的 provider 会收到一个完整的转录记录检查点,这可能让缓存的前缀失效——这是频繁切换的其中一个真实代价。
命名空间
namespace: { name, description, instructions } 像 MCP 服务器那样把相关工具分组。codemode 工具在一个标题下列出一个命名空间,附上它的 description。instructions 保存更长的使用指引;它不被列出,而 codemode 脚本用 describeNamespace(name) 读它。
评审守卫的那些工具是一个很好的命名空间候选。它的 description 变成 codemode 列出的标题,而它的 instructions 可以容纳一段描述放不下的指引——这里是"在报告一个 diff 之前调用 review_diff。它运行项目自己的检查;不要换成你自己的命令。”
画一次调用:渲染器是一件独立的事
上面这一切决定模型是否被允许看见一个工具,以及一个守卫是否放行一次调用。这两者都不决定这次调用一旦发生之后看起来是什么样,而在 Pi 那里,那是三个真正独立的机制。
一个工具用两个可选属性声明自己的画法:renderCall 和 renderResult。它们在交互式转录记录和 HTML 导出中渲染这次调用。这是工具作者自己的事,而对大多数工具来说没有什么可做的。
pi.registerToolRenderer((toolName, next) => renderers) 走出了那一步。它按名字为对任何工具的调用选择渲染器——包括那些在这个会话里尚未注册的工具。有文档记载的情形是被恢复的会话里的一个 MCP 工具,在它的服务器重新连接之前:没有已注册的工具对象可问,而在 1.0.1 之前,这次调用根本没有画法。
pi.registerToolRenderer((toolName, next) => {
if (toolName.startsWith("mcp__")) {
return { renderCall: () => new Text("call an MCP server", 0, 0) };
}
return next();
});
要紧的细节是 next()。它返回剩下的那些解析器会用的东西——按扩展加载顺序排的其他渲染器,然后是已注册工具自己的那个。所以返回 next() ?? mine 只是填空,而返回 undefined 是推迟,而不是压制。一条渲染器链是一架回退的梯子,不是一个覆盖层。
为什么这属于一章讲工具的书、而不属于 UI 那一章:渲染是按工具的,并随工具一起走,而一个全局主题或一个键位属于呈现层。一个随包发布工具的包,同时发布这个工具看起来的样子,而完全不必依赖 TUI。这与第 31 章在更大尺度上利用的是同一个分离——一项能力不应当因为终端消失而不再是能力。
有三件事值得分开,因为它们很容易被混为一谈:
| 机制 | 决定什么 |
|---|---|
exposure |
模型是否被告知这个工具存在 |
annotations |
一个守卫对这次调用的风险推断出什么 |
renderCall / registerToolRenderer |
这次调用一旦发生之后如何被画出 |
三者中没有哪一个蕴含另外两个中的任何一个。一个工具可以完全可见却以默认形状画自己,或者对模型隐藏、却仍然为一个正在读导出的会话的人渲染。
一个关于版本的说明,因为这一节的版本敏感性是本章其余部分所没有的:pi.registerToolRenderer() 出现在 1.0.1。在 1.0.0 上,画一个工具调用的唯一方式是这个工具自身的 renderCall 和 renderResult 属性,而这需要拥有这个工具。
你该重读的那份清单
extensions.md 用一些值得打开的引用结束工具这一节:hello.ts、todo.ts、dynamic-tools.ts 和 truncated-tool.ts,全都在 examples/extensions/ 下。dynamic-tools.ts 在会话初始化之后注册工具,并在运行时从一个命令里添加更多;truncated-tool.ts 展示截断契约。从与你挂接点匹配的那个开始。
运行了什么
examples/ch17-tools/ 通过一个真实的会话编译并运行本章的每一个工具和钩子。光是编译就在本章的早期草稿里发现了三个缺陷,而测试随后确立了这些行为:
- 在
review_diff里,ctx不在作用域中,而它的结果被从错误的对象上读取。两者都在上面修好了。 skipTests曾是一个必需的布尔值,尽管这个工具本应可以在不带参数的情况下调用。它现在是可选的。- 渲染器的例子曾返回一个普通对象。
registerToolRenderer需要一个pi-tuiComponent,所以{ custom: "…" }编译不过。它现在返回一个Text。
测试展示了什么:
- 一条非零退出的命令会作为数据回来:
isError为false,而退出码在details里; review_diff通过ctx.executeTool()运行另外两个工具,并从outcome.result读它们的structuredContent;- 嵌套调用会经过
tool_call:一个侦察扩展依次看到review_diff、run_checks、failing_tests,所以一个守卫适用于模型从未看见的代码路径; - 在许可扩展下,一个带
readOnlyHint: true和openWorldHint: false的工具不会被问及,而一个没有提示的工具在没有 UI 时会被阻止; - 一个
deferred工具在注册时不活动,在加载器工具调用setActiveTools()时变为活动,并且在两种情形下都可从另一个工具调用。
验证
/reload
提问:"list the failing tests"
预期:模型调用 failing_tests 并报告一个结构化的答案。
提问:"run git push --force"
预期:第 16 章的守卫会在 bash 工具运行之前提问。
第二个检查要紧:它确认嵌套路径与这个守卫仍然能组合。
暴露方式和注解决定模型能否看见一个工具、以及一个守卫是否放它通过。两者都不告诉模型这个工具就是这里的正确答案——那个住在提示词里,而一段描述本身不会把它放进去。第 18 章讲那些真正能做到这一点的层面。