Example

看 Pi 把哪些工具声明给模型

追踪 defaultTools 与一次性的 --tools 覆盖如何决定活动集合,以及 1.0.4 那个 MCP 例外住在哪里。

Pi 向模型声明一个活动工具集合;那个集合就是模型可以索要的东西。 三样输入组成它:内置工具、由扩展注册的工具,以及 MCP 工具。 defaultTools 修订用户的选择,--tools 为一次调用替换它,而同一套 语法在这两个地方意思不同。

默认选择及其两种修订

settings.md 把 defaultTools 默认为 read、bash、edit 和 write。 在一个设置列表内,裸名替换选择,+name 添加,-name 移除,按顺序:

defaultTools 列表 含义
["read","bash","edit","write"] 默认值,未改变
["+grep","+find","+ls"] 在默认值之上添加三个搜索工具
["read","powershell"] 一个双工具智能体:裸列表替换
["-bash"] 默认值减去 Bash
["+codemode"] 添加那个默认关闭的 codemode 内置扩展工具

codemode 和 tool_search 来自内置扩展,并且默认关闭;当一个带那种 暴露方式的 MCP 服务器需要它们时,它们打开。项目设置文件叠加在用户文件 之上(第 7 章详细掌管那个合并)。

一次性覆盖是另一套语法

在命令行上,--tools 替换整个选择,而 +name / -name 在那里会被 拒绝:

pi --tools read,grep,find,ls --no-mcp --print "Review this project"
pi --tools read,bash,edit,write,codemode

覆盖持续那次调用(包括跨 /reload)。

1.0.4 例外

--tools 收窄内置、扩展和自定义工具——但不收窄 MCP 工具。在 1.0.4 上, 如果配置了服务器,即使 --tools 没有点名它们,MCP 工具仍然保留,所以需要 --no-mcp 才能移除它们。命令行上没有办法说"除这些以外的所有工具"。

机制与局限

有文档记载:settings.md 描述默认值和裸名/+/− 规则;默认关闭的内置扩展 记录在 extensions.md 中。**已观察:**第 7 章的测试通过真实的 SettingsManager 断言 defaultTools 的修订对替换语义;headless.test.ts 展示 --tools 收窄一个 智能体——一个索要 Bash 的模型得到一个失败的结果,而什么也不运行; tool-allowlist.test.ts 演练 disabledBuiltinExtensions 和 mcp__ 命名。MCP 例外 在章中被记录为 1.0.4 的行为,所以它是对版本敏感的。

声明一个工具使它可用;它不让模型使用它,也不让一次使用获得授权——工具以 Pi 进程的操作系统权限运行。这个示例展示的是被声明的集合如何组成,不是一个真实 模型拿它做什么。

读这一章 以及 examples 目录 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.