内置工具
八个内置的 Pi 工具、defaultTools 实际选的是什么、工具结果如何到达转录记录,以及何时加上 codemode。
Pi 在工作时显示每一次工具调用和结果。这是关于可见度的一个承诺,不是关于限制的承诺:它不会在每次工具调用之前询问,并且这些工具以这个进程的操作系统权限运行。
你能控制的是集合。settings.md 把 defaultTools 默认为 read、bash、edit 和 write。每一次运行都从那个列表起步,除非你改它。
这八个
cli.md 列出内置工具及其用途:
| 工具 | 用途 |
|---|---|
read |
读取文本文件与受支持的图片 |
bash |
运行 shell 命令 |
powershell |
在 Windows 上运行 PowerShell 命令 |
edit |
对已有文件施加精确的文本替换 |
write |
创建或覆盖一个文件 |
grep |
搜索文件内容 |
find |
用 glob 模式查找路径 |
ls |
列出目录内容 |
还有两个来自内置扩展,并且默认关闭:codemode,它运行调用其他工具的 JavaScript,以及 tool_search,它搜索那些没有声明给模型的工具。settings.md 指出,当一个服务器需要它们时 MCP 扩展会把它们打开——对带 codemode 暴露方式(exposure)的服务器开 codemode,对带 deferred 暴露方式的服务器开 tool_search。
flowchart TD
DEF["defaultTools 设置<br/>先是用户,然后项目叠加其上"] --> SYN["语法决定操作:<br/>裸名 = 替换,+ = 添加,- = 移除"]
SYN --> BUILT["内置工具<br/>read bash edit write(Windows 上还有 powershell)"]
SYN --> EXT["扩展与自定义工具<br/>由扩展注册"]
SYN --> MCP["MCP 工具<br/>保留,除非某个条目以 mcp__ 开头"]
CLI["--tools / --exclude-tools<br/>一次调用"] -.->|"覆盖设置"| OUT
BUILT --> OUT["活动工具集合<br/>= 声明给模型的那些"]
EXT --> OUT
MCP --> OUT
SEL["defaultTools: [#quot;+codemode#quot;]"] --> SYN
三列输入,一个操作,一个结果。虚线箭头是让这件事变混乱的两样东西:命令行旗标把设置替换为只供一次调用使用(包括在 /reload 上),而一个裸名是替换而不是添加——所以 defaultTools: ["read"] 是一个单工具智能体,不是一个双工具的。
默认列表如何组成
defaultTools 比它看着更微妙。裸名替换默认值;+name 添加;-name 移除。而这个合并是不对称的——项目设置叠加在用户设置之上:
- 一个只含
+name和-name条目的项目列表会改变用户的选择。 - 一个含裸名的项目列表会替换它。
- 在一个列表内部,裸名构成选择,然后
+name和-name按顺序应用。
所以项目设置文件里的 ["+grep", "+find", "+ls"] 在用户已有的东西之上添加三个搜索工具。["read", "powershell", "edit", "write"] 则彻底替换选择。
有四个内置扩展在 extensions 中命名为 builtin:mcp、builtin:llama.cpp、builtin:codemode 和 builtin:tool-search。它们默认加载;-builtin:mcp 禁用一个。
一次性覆盖
--tools 替换整个选择,所以把你想要的每个工具都点名。这是唯一一处 +name 和 -name 会被拒绝的地方:
# --no-mcp is here because 1.0.4 keeps MCP tools; see the table below.
pi --tools read,grep,find,ls --no-mcp --print "Review this project"
pi --tools read,bash,edit,write,codemode
在你抄下第一行之前:这种收窄只针对内置、扩展和自定义工具。在 1.0.4 上 --tools 不移除 MCP 工具,所以如果智能体目录里配置了 MCP 服务器,模型仍然拥有它们,而 --no-mcp 才是让"只读和搜索"成真的东西。第 32 章在要紧的那条命令处有同样的限定。
另外三个旗标,按严重程度递增:-xt/--exclude-tools 在所有其他选择选项之后禁用列出的名字;-nbt/--no-builtin-tools 保留扩展与自定义工具;-nt/--no-tools 以一切禁用起步。
从 1.0.4 起,一个条目可以是一个模式,而 --tools 不再触及 MCP 工具。 --tools 和 --exclude-tools 都接受名字或模式,其中 * 匹配任意字符,并且匹配是锚定的,所以 mcp__radius__* 就是那个服务器的工具,别的都不是。这两个旗标把 MCP 与其他一切分开处理:
| 旗标 | 内置、扩展与自定义工具 | MCP 工具 |
|---|---|---|
--tools |
被列表替换 | 保留,除非某个条目以 mcp__ 开头 |
--exclude-tools |
被列表禁用 | 被列表禁用,MCP 包括在内 |
--no-tools |
全部禁用 | 全部禁用 |
所以在一个有 MCP 服务器的会话里,pi --tools read,grep,find,ls 不再意味着"模型只能碰到这四个"。它意味着模型能碰到那四个以及白名单保留的每一个 MCP 工具——以其暴露方式给出的无论什么可达范围,而对于默认的 codemode 暴露方式,这包括一个由模型自己写的脚本。一个没有任何条目命名或匹配的 MCP 工具,无论其暴露方式如何,都从不直接声明给模型。点名某一个服务器的工具,就是你拿走其他服务器的方式:
pi --tools read,bash,codemode,'mcp__radius__*'
MCP 资源工具——list_mcp_resources、list_mcp_resource_templates 和 read_mcp_resource——在这条规则下算作 MCP 工具。要把它们全部去掉,用 --exclude-tools 'mcp__*',或者用 --no-mcp 为这次运行关掉 MCP,它不连接任何服务器,不留任何 MCP 工具,也不留 /mcp。
有两个区分值得记住。模式是命令行特性:设置文件里的 defaultTools 接受裸名和 +name/-name 修饰符,而那里一个含 * 的名字是一个匹配不到任何工具的名字。而 --no-mcp 为一次运行禁用内置 MCP 支持;它不影响替换它的扩展。第 21 章有一张按暴露方式逐项列出的表,讲"保留"是什么意思,包括文档没有明说的那一种情形——一个白名单没有点名的 direct 暴露方式工具保持注册,但既不被声明也不可调用。
reload 陷阱
/reload 启用那些新添加到 defaultTools 里的工具。它不禁用从其中被移除的工具,也不重新启用你关掉的、未变更的工具。--tools、--no-tools 和 --no-builtin-tools 为一次调用覆盖设置,包括在 reload 上。
如果你禁用一个工具,而在编辑 settings.json 之后它仍然禁用着,那是有文档记载的行为,不是一个 bug。重启 Pi。
一个工具结果长什么样
message-types.md 定义了 ToolResultMessage:
interface ToolResultMessage<TDetails = JsonValue> {
role: "toolResult";
toolCallId: string;
toolName: string;
content: (TextContent | ImageContent)[];
details?: TDetails;
usage?: Usage;
nestedCalls?: NestedToolCalls;
isError: boolean;
timestamp: number;
}
有三样东西要带进那些扩展章。details 是工具专属的结构化数据。可选的 usage 报告由该工具执行的嵌套模型工作——它计入全会话统计,但不属于主模型调用的用量。而 isError 是一个普通字段。
返回不是失败
extensions.md 把这条规则说得毫不客气:从 execute() 抛出以产生一个失败的工具结果,而返回一个对象并不把它标为错误。
这也覆盖那些内置工具。codemode.md 说一次 bash 调用会解析成一个结构化值,“对于非零退出码也一样”:
const r = await tools.bash({ command: "npm test" });
if (r.exit_code !== 0) text(`tests failed: ${r.output}`);
非零退出是数据。抛出是失败。把两者混为一谈,会让模型把一次红色的测试运行当成坏掉的工具,去重试工具而不是修代码。
codemode 改变一轮的形状
codemode 是一个注册了接受原始 JavaScript 的工具的内置扩展。脚本作为 QuickJS 沙箱中一个异步函数的主体运行,所以顶层 await 和 return 能用。它没有 Node API、文件系统、网络或计时器;它只通过工具和 models 触及外部世界。
只有脚本的输出到达模型。这正是全部的要点所在:
// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}
const results = await Promise.allSettled([
tools.bash({ command: "npm test -- --run tests/auth" }),
tools.bash({ command: "npm test -- --run tests/billing" }),
tools.bash({ command: "npm run lint" }),
]);
for (const [i, r] of results.entries()) {
text(r.status === "fulfilled" ? `job ${i}: exit ${r.value.exit_code}` : `job ${i} failed: ${r.reason}`);
}
三次工具调用,一条模型可见的消息。沙箱有 256 MB 的内存限制;过滤和聚合,而不是累积。
它也有一个输出上限,而从 1.0.1 起,超过它是一个失败而不是一次意外。当一次脚本的输出超过 16777216 个文本与 base64 图片数据字符,或 100000 次对 text()、image() 和 console 的调用时,脚本失败。这两者以前都容易被触及到足以把 Pi 跑爆内存,所以它们现在是强制上限。
教训就是上面那个 max_output_tokens 选项已经暗示的那一个:脚本是计算多次调用的摘要的地方,不是转发它们的地方。如果完整输出重要,有文档记载的建议是用一个工具把它写进文件并返回路径。
自从 1.0.3 起,图片通向那条建议已经有了一条更短的路:image() 也把每张图片存到一个临时文件,并在结果中说出路径,所以后面一轮可以复制或移动它,而脚本什么都不用写。到 1.0.4,这件事有了一个正在进来的同伴——对图片调用 tools.read() 会解析成一个图片块,由 image() 显示,而不是解析成脚本无法渲染的文本。
在 codemode 活动期间,codemode.mode 决定其他工具如何呈现。用 on(默认)时,已声明的工具保持声明,它们的描述说明如何从脚本中调用它们。用 only 时,它们对模型隐藏,转而列在 codemode 的描述里。
声明工具不是激活工具
出自 extensions.md:活动集合——通过 pi.getActiveTools() 读、通过 pi.setActiveTools() 写——就是声明给模型的那组工具。pi.getAllTools() 报告每一个已注册的工具,连同它的 exposure、namespace 和 annotations。有两个列表,而它们不是同一个列表。
错误:“我注册了这个工具,所以模型能看见它。”
正确:“我注册了这个工具,所以它存在。模型能不能看见它是一个独立的问题,有一个独立的答案。”
文档对于两者在哪里不同是精确的:注册一个 direct 或 model-only 工具会激活它,而其他暴露方式不会在注册时激活。codemode 和 deferred 是让人吃惊的那两个,这就是内置扩展把它们以非活动状态交付的原因。第 17 章讲透全部五种暴露方式。
宁可选搜索,不要猜
这是我们的建议,不是 Pi 的:在其他任何东西之前,先加上搜索工具。
{
"defaultTools": ["+grep", "+find", "+ls"]
}
根据我们的经验,一个没有它们的模型会转而伸手去拿 bash,用 cat 或 ls 接进 shell 逻辑,这要花掉一次完整的进程启动,并让输出经过 shell 而不是经过一个结构化结果。如果你看到这种事发生,这三条条目就是修复。
运行了什么
defaultTools 规则是通过 Pi 自己的 SettingsManager、在真实的 settings.json 文件上、在 examples/ch07-settings/ 中运行的。没有任何东西重新实现那个合并。在用户列表为 read, bash 的情况下:
- 一个只含
+grep、+find、+ls的项目列表给出read, bash, grep, find, ls; - 一个含裸名的项目列表,
read, powershell,替换选择; - 在一个列表内部,裸名构成选择,然后
+和-按顺序应用:read, bash, -bash, +grep给出read, grep; - 一个只含
-bash的项目列表从用户的选择中移除bash。
一次性旗标是在第 32 章的测试中对着随附的二进制文件运行的:在 --tools read,grep,find,ls 下,一个索要 bash 的模型得到一个失败的工具结果,而那条命令从未运行,而默认工具集确实运行了它。-nt、-nbt 和 -xt 变体以及 reload 陷阱没有运行。
下一章
defaultTools 是一个设置,而它以本章只是暗示过的方式与其他设置组合:一个含裸名的项目文件替换用户的列表,一个只含 + 和 - 条目的则修订它。那种不对称不是一件奇谈,它是支配 Pi 中每一个设置的那条规则,所以下一章在任何一个设置被针对某个具体工具写下来之前,先画出整个配置表面以及各层之间的优先级。
第 7 章:设置,以及配置从哪里来。