Pi Agent 源码级教程
F03

工具开关 —— 八个内置,两个模组,五档暴露

2,496 字 · 含 32 行代码 · 约 16 分钟

F02 解决「能不能调用模型」,这一章解决「模型能动手做多少事」。

这是 Pi 最容易被低估的一块:工具集不只是「开几个开关」, 它会改写系统提示词。你关掉 grep,模型收到的规则里就多一句 「用 bash 去 find」;你打开 codemode,模型的工具描述里就多一整套调用说明。

三个问题:

  1. 默认到底开了几个工具?pi --list-models 列不出来的工具去哪了?
  2. --tools read,grep 和 --tools +codemode,-write 有什么区别?
  3. 为什么有的工具明明注册了,模型却看不见?

注册一个工具(registerTool)之后,要问两个相互独立的问题:

  • 模型看得见它吗? 看它在不在 active 集合里(exposure 决定它会不会自动进去)。
  • 别的工具能调它吗? 只看 exposure,和 active 无关。

五档 exposure 把这两个问题拆成了四个组合:

text
   exposure     自动激活   模型看得见   工具能调   ---------------------------------------------   direct       是         看得见       能调   model-only   是         看得见       不能调   codemode     否         看不见 *     一直能调   deferred     否         看不见 *     一直能调   hidden       否         从来看不见   不能调

<sub>* codemode / deferred 只在被显式激活(或 tool_search 搜中)之后 才进声明名单。两者唯一区别是「要不要写进 codemode 工具的说明书」。</sub>

把四行分成两对记:看得见 ≠ 能调(model-only), 能调 ≠ 看得见(codemode / deferred)。把它们当成一根轴的人, 写扩展时会在「我明明注册了,模型为什么不用」上卡很久。


一、默认工具集:四个,不是八个

pi --help 的第一行是 pi - AI coding assistant with read, bash, edit, write tools。 allToolNames(tools/index.ts:96-105)列了八个:

工具 干什么 默认开
read 读文件与图片 是
bash 跑 shell 命令 是
edit 精确文本替换 是
write 新建或覆盖文件 是
powershell 在 Windows 上跑 PowerShell 否
grep 搜文件内容 否
find glob 找路径 否
ls 列目录 否

「八个内置、默认四个」不是文档编的,是代码里两个常量决定的: DEFAULT_TOOL_NAMES(settings-manager.ts:85)只写了四个, 而 allToolNames 是「所有可能存在」的集合。

所以「用 grep 搜一下」在默认配置下根本不会发生——模型没有这个工具, 它只能用 bash 去跑 rg 或 findstr。

1.1 怎么确认自己机器上到底开了什么

别看文档,看系统提示词。--mode json 的第一条 message_end 里, system 消息带一个 sections 对象,键是 preamble / tools / rules / docs / cwd(system-prompt.ts:150-160)。 sections.tools 就是模型看到的那份工具清单。

本机(v1.4.0,装了 pi-web-access)实跑的结果:

text
<tools>- read: Read file contents- bash: Execute bash commands (ls, grep, find, etc.)- edit: Make precise file edits ...- write: Create or overwrite files- web_search: Use for web research questions. ...- source_check: Gather structured source evidence ...- fetch_content: Use to fetch URL content, direct images, ...- get_search_content: Use after web_search, source_check, or fetch_content ...</tools>

前四个是内置四件套,后四个来自已安装的包。grep find ls powershell 一个都没出现——和上面那张表一致。

这条输出还揭示了一件事:工具集是「内置 + 扩展」拼起来的, 你在 defaultTools 里写什么都管不到扩展注册的工具(除非用 -nt 全关)。


二、工具集影响系统提示词,不只是「能不能调」

buildRules(system-prompt.ts:88-125)里有一段很说明问题。 三个 addRule 对应三种配置(:108-116):

你开了什么 写进提示词的那句
bash + PowerShell,且无 grep/find/ls Use bash or PowerShell for file operations …
只有 PowerShell Use PowerShell for file operations …
只有 bash Use bash for file operations like ls, rg, find

外层条件 (hasBash || hasPowerShell) && !hasGrep && !hasFind && !hasLs 是整段的开关。默认四件套正好落进最后一个分支,所以默认系统提示词里有 「Use bash for file operations like ls, rg, find」这一条。

一旦你加上 grep,!hasGrep 变成假,这条规则就消失了—— 模型不再被要求「用 bash 干搜索」,因为它有了专门的工具。

这就是「工具集改写提示词」的具体样子:不是加一行说明, 是替换掉一段行为指导。所以改工具集之后,值得重跑一次 --mode json 看一眼 sections.rules,确认模型拿到的指令符合你的预期。

另外 :150 有个细节:hiddenTools 里的工具会被从 「声明给模型」的列表里滤掉(declaredTools),但仍留在 selectedTools 里 参与规则计算。这是扩展做「工具存在但模型看不见」的手段,F06 会用到。


三、--tools 的三种写法

cli.md:119-128 把规则说得很密,拆成三类:

写法 语义 例子
纯普通名 整套替换成这个白名单 --tools read,grep
纯 +/- 在默认集上加减 --tools +codemode,-write
混着写 非法,直接报错 --tools read,+grep

支持 * 通配,但只在「纯普通名」里有效:--tools 'read,gre*' 能展开, --tools '+code*' 会报错,因为 +/- 只收精确名。 这个校验函数是 getToolListError(settings-manager.ts:97-104), 它查的正是这两件事:模组里有没有普通名、模组里有没有 *。

四个开关的分工也容易混:

开关 长写法 做什么
-t --tools 白名单或加减,见上表
-xt --exclude-tools 最后执行的黑名单,连 MCP 工具一起管
-nbt --no-builtin-tools 关掉内置,保留扩展和自定义工具
-nt --no-tools 全关,连 MCP 一起

-xt 的「最后执行」很关键(cli.md:121-122):它排在所有选择选项之后, 所以 --tools read,grep -xt grep 的净结果是只剩 read。 用它来「临时禁掉某个工具」比改白名单安全——白名单一写, 你以后新加的工具默认就不在里面了。

-nbt 是这组里最少人用的,也是最有用的一档:想保留扩展工具、 又不想要内置的文件写能力时,它正好卡在中间。


四、codemode 与 tool_search:两个内置扩展

这两个不是内置工具,是内置扩展提供的工具,默认关闭。 cli.md:151-156 把它们单列了一张表:

内置扩展 干什么
codemode 跑一段 JS 去调别的工具,能 Promise.allSettled 并行;只有脚本的返回值进模型
tool_search 在「没有声明给模型」的工具里搜,把命中的声明给下一次调用

打开方式有两种,长期和临时:

json
{ "defaultTools": ["+codemode"] }
powershell
pi --tools +codemode

4.1 codemode 值不值得开

值得,理由不是「能并行」这么简单。cli.md:174 列了它的真实用处:

  • 并行跑多个工具调用,只要最终结果;
  • 在结果进模型之前先过滤——读十个文件,脚本里摘出三行, 模型看到的就只有三行,而不是十个文件的全文;
  • 调分类模型(models.classify)和图像模型(models.generateImages)。

第二条才是它省 token 的本质。read 一个 2000 行的文件,全文进上下文; 换成 codemode 里读、在脚本里 slice 出你要的段落,只回传那一小段。 细节和脚本 API 在 F07,这里只要记住:codemode 的开关在工具层,不在模型层。

4.2 tool_search 解决的是「工具太多」

MCP 接上三台服务器,工具可能上百个。全部声明给模型, 系统提示词会膨胀到几万 token,而且里面 95% 用不上。

tool_search 的做法是:那些工具先不声明(deferred 暴露), 模型觉得需要时调 tool_search 搜一下,命中的下一轮才声明。 cli.md:182 还补了一句重要的实现细节:加载过的工具会记进会话, 所以在这个分支上它们会一直保持声明,不用反复搜。


五、五档 exposure:扩展才碰得到的旋钮

普通用户改不到这一层,但理解了它,你才能看懂 MCP 那套行为。 types.ts:521-536 的注释是这本书里最清楚的一段,联合类型本身很短:

ts
// types.ts:536export type ToolExposure =	| "direct" | "model-only" | "codemode"	| "deferred" | "hidden";

五档的含义,逐个拆:

档 声明给模型 能被 executeTool 调 何时生效
direct 激活时声明 是 注册即激活
model-only 激活时声明 否 注册即激活
codemode 只有显式激活才声明 是(一直可调) 注册后即「可调不可见」
deferred 同 codemode,但不进 codemode 的工具清单 是 同上,只能靠 tool_search 找
hidden 从不 否 注册了也够不着

model-only 的存在很反直觉:「声明给模型,但什么也调不了」。 它的用途在注释里写了——orchestrating 或 interactive 类工具, 比如一个「问用户要输入」的工具,模型该知道有它,但不该被别的工具链式调用。

codemode 和 deferred 的唯一区别是要不要出现在 codemode 工具的说明书里。 MCP 工具默认走这个区间,因为一个 MCP 服务器可能有几十个工具, 全列进 codemode 的描述等于又把提示词撑爆了。


六、自己动手验证

实验 1:看默认工具集真的只有四个。

powershell
$env:PI_OFFLINE="1"; pi --mode json -p "x" | Out-File -Encoding utf8 t.jsonl

然后用 node 取出来(避免被 PowerShell 的编码绕晕)。把下面三行存成 tools.mjs,比写成一行好调试:

js
const L = require("fs").readFileSync("t.jsonl", "utf8")  .split(/\r?\n/).filter(Boolean).map(JSON.parse);const s = L.find((e) =>  e.type === "message_end" && e.message.role === "system");console.log(s.message.sections.tools);
powershell
node tools.mjs

在干净环境(pi -ne)里应该只有前四行。

实验 2:加上 grep,看规则段变了。

分别跑 pi --mode json -p "x" 和 pi --tools read,bash,edit,write,grep -p "x", 对比 sections.rules。第一份应该有 Use bash for file operations like ls, rg, find,第二份没有。 这一条是本章最值得亲手做一遍的实验——它把「工具集影响提示词」从说法变成事实。

实验 3:-xt 排在最后。

powershell
pi --tools read,grep -xt grep -p "hi"

如果 -xt 不是最后执行,grep 就会留在集合里。想更直接一点, 用 --mode json 看 sections.tools 里没有 grep。

改一处试试

在自己的 ~/.pi/agent/settings.json 里写:

json
"defaultTools": ["+codemode"]

然后跑实验 1 的命令。sections.tools 里会多出 codemode, 并且它的描述会列出「可以调哪些工具」——因为 codemode 会把当前 所有 codemode / deferred 档的工具列进自己的说明。 这也是为什么它一开,提示词就明显变长。


七、工程暗坑

坑一:-nbt 和 -nt 差一个字母,结果差很远。 -nbt 只关内置,扩展工具还活着;-nt 全关。做只读审查时, 用 -nbt 保留了 web_search 这类扩展工具,用 -nt 连它也一起没了。

坑二:白名单会让你以后新加的工具「默认不在」。 --tools read,grep 是整套替换,以后包更新带进来一个新工具, 它不在白名单里,就不生效。要长期用某个组合,写 defaultTools 而不是每次命令行传。

坑三:+name 加进来的工具,不等于「能被模型直接调」。 +codemode 加的是 codemode 这个工具本身。你到底能不能并行读十个文件, 取决于脚本里能不能调到 read——那是 exposure 和 active 的事。 F07 会把这条链路走完。

坑四:关掉 grep 不会让搜索变慢,但会让搜索变笨。 模型只能用 bash 拼 rg,命令写错就得重试一轮。 如果任务以搜索为主,直接开 grep find ls 更划算—— 它们的输出本来就是截断过的,比 bash 原文更省 token。

坑五:MCP 工具不受 --tools 的白名单约束。 cli.md:132 说得很清楚:--tools 只选「声明给模型的工具」, MCP 工具的够得着程度由 exposure 决定。想让 --tools 管到 MCP, 条目必须写成 mcp__ 开头(如 'mcp__radius__*')。 真要把它们关掉,用 -xt 'mcp__*' 或 --no-mcp。


八、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/tools/index.ts 225 allToolNames 八件套、四件套工厂
packages/coding-agent/src/core/settings-manager.ts 1,457 DEFAULT_TOOL_NAMES、getToolListError、applyToolModifiers
packages/coding-agent/src/core/system-prompt.ts 229 buildRules 里工具集如何改写规则
packages/coding-agent/src/core/extensions/types.ts 2,329 ToolExposure 五档与 hiddenTools
packages/coding-agent/docs/cli.md 343 --tools 全表与 MCP 例外

九、下一章

工具定了,下一个问题更根本:模型怎么知道你是谁、这个项目是什么规矩。 F04 拆四层指令:AGENTS.md 的探索链、SYSTEM.md 的整段替换、 APPEND_SYSTEM.md 的追加、以及 SKILL.md 那种「先只给名字,用时才展开」的惰性加载。