工具开关 —— 八个内置,两个模组,五档暴露
F02 解决「能不能调用模型」,这一章解决「模型能动手做多少事」。
这是 Pi 最容易被低估的一块:工具集不只是「开几个开关」,
它会改写系统提示词。你关掉 grep,模型收到的规则里就多一句
「用 bash 去 find」;你打开 codemode,模型的工具描述里就多一整套调用说明。
三个问题:
- 默认到底开了几个工具?
pi --list-models列不出来的工具去哪了? --tools read,grep和--tools +codemode,-write有什么区别?- 为什么有的工具明明注册了,模型却看不见?
注册一个工具(registerTool)之后,要问两个相互独立的问题:
- 模型看得见它吗? 看它在不在 active 集合里(
exposure决定它会不会自动进去)。 - 别的工具能调它吗? 只看
exposure,和 active 无关。
五档 exposure 把这两个问题拆成了四个组合:
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)实跑的结果:
<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 |
在「没有声明给模型」的工具里搜,把命中的声明给下一次调用 |
打开方式有两种,长期和临时:
{ "defaultTools": ["+codemode"] }pi --tools +codemode4.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 的注释是这本书里最清楚的一段,联合类型本身很短:
// 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:看默认工具集真的只有四个。
$env:PI_OFFLINE="1"; pi --mode json -p "x" | Out-File -Encoding utf8 t.jsonl然后用 node 取出来(避免被 PowerShell 的编码绕晕)。把下面三行存成
tools.mjs,比写成一行好调试:
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);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 排在最后。
pi --tools read,grep -xt grep -p "hi"如果 -xt 不是最后执行,grep 就会留在集合里。想更直接一点,
用 --mode json 看 sections.tools 里没有 grep。
改一处试试
在自己的 ~/.pi/agent/settings.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 那种「先只给名字,用时才展开」的惰性加载。