← Pi Agents

内置工具

八个内置的 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 章:设置,以及配置从哪里来。