第 5 课：四大内置工具

pi 为你做的一切都源自一小套模型可以调用的工具。理解它们，是有效驾驭 pi、明白它能做什么（以及不能做什么）的关键。

四大工具

默认情况下，pi 只给模型四个工具：

工具	作用	说明
read	读取文件内容	文本和图片；发送给模型
write	创建或覆盖文件	整体重写——适合新文件
edit	精确修补	定向文本替换，一次调用可多处修改
bash	运行 shell 命令	你 shell 的全部能力

另外三个只读工具可通过 CLI 选项启用：grep、find、ls。

模型如何使用它们

观察一次会话，你会看到一种固定模式：

1. 探索 — ls、find 或 read 了解布局
2. 诊断 — bash 跑测试，grep 找用法
3. 行动 — edit 做外科手术式的修改，write 建新文件
4. 验证 — bash 再次运行检查

工具以你的权限在你的工作目录中运行。没有权限弹窗——pi 的设计是"被信任或被沙箱化"（容器、tmux 等），而不是被反复盘问。

控制工具

你可以从 CLI 控制工具的可用性：

pi --tools read,grep,find,ls -p "Review the code"   # 只读模式
pi --exclude-tools ask_question                      # 禁用某个工具
pi --no-tools                                        # 禁用所有工具
pi --no-builtin-tools                                # 只保留扩展/自定义工具

--tools 是白名单；--exclude-tools 移除特定工具。只读审查会话非常适合代码审计。

你也可以在对话中引导："只看，别改任何东西"或"不要运行破坏性命令"作为指令效果出奇地好。但想要真正的保证，请用上面的标志或在容器中运行 pi。

为什么用 edit 而不是 write？

write 会替换整个文件；edit 只精确修补指定文本。修改已有文件时，edit 更温和——token 更少、误伤无关部分的风险更低，而且模型可以在一次调用中做多处精确修改。这就是你会看到 pi 修改已有代码时大多用 edit 的原因。

bash 工具——自带上下文

模型运行的每条命令都会通过环境变量获得会话元数据：

变量	含义
PI_SESSION_ID	当前会话 ID
PI_SESSION_FILE	会话 JSONL 文件的绝对路径
PI_PROVIDER / PI_MODEL	当前提供商和模型
PI_REASONING_LEVEL	当前生效的推理等级

在 pi 内运行的脚本可以检测到自己身处 pi 并据此行事（例如，只在代理会话中才提交）。

你的那部分权力

你在编辑器里拥有同样的能力：

• !command — 运行 shell 命令，输出发给模型
• !!command — 静默运行（输出不进上下文）
• @file — 直接附加文件，而不是让模型去读

这些是你"参与"的工具：快速运行 !git diff 让模型看到确切的改动，或者用 Ctrl+V 粘贴截图给它看 UI bug。

实践中的安全

因为 bash 以完整权限运行，好习惯是 git 优先：

git init / git checkout -b feature

这样 pi 可以自由探索，而你在提交前可以审查 diff。有些人会添加一个在每次工具调用前自动提交的技能或扩展——这在扩展课里会讲到。

---

作业： 用 pi --tools read,grep,find,ls 开启一个会话并要求代码审查——确认它拒绝修改任何东西。然后开一个普通会话，让 pi 修复一个 lint 错误，观察它如何组合 bash（跑 lint）→ read（看错误）→ edit（修复）→ bash（再检查）。