第 17 章 · 工具系统与 CLI 全解
本章目标：搞清楚 pi 的 7 个内置工具各自能做什么，掌握用命令行参数精确控制工具可用性的方法，并把整份 CLI 参数表收进你的速查手册。
17.1 内置工具清单
pi 的内置工具一共 7 个（官方 CLI 参考原文：read, bash, edit, write, grep, find, ls）：
| 工具 | 职责 | 典型用途 |
|---|---|---|
read | 读文件 | 查看源码、配置 |
write | 写文件 | 创建新文件 |
edit | 精确编辑文件 | 改代码、改配置 |
bash | 执行 shell 命令 | 跑测试、git 操作、构建 |
grep | 内容搜索 | 在代码库中查找模式 |
find | 文件名查找 | 定位文件位置 |
ls | 列目录 | 浏览项目结构 |
注意两点设计哲学：没有内置的网页抓取/终端 UI 类花哨工具——需要就靠扩展或技能补；bash 是万能后门——即使禁掉其他工具，只要 bash 可用，模型理论上仍能间接完成读写，所以"只读审查"场景必须把 bash 一并排除。
17.2 用 Tool Options 控制工具可用性
CLI 提供四个层级的开关（括号内为缩写）：
bash
# 白名单模式：只允许这 4 个只读类工具 —— 官方推荐的"Read-only mode"
pi --tools read,grep,find,ls -p "Review the code"
pi -t read,grep,find,ls "..." # 等价缩写
# 黑名单模式：仅禁用某个工具（含内置、扩展与自定义工具）
pi --exclude-tools ask_question
pi -xt bash "重构这段代码" # 禁用 bash，逼模型用 read/write/edit
# 关闭全部内置工具，但保留扩展注册的自定义工具
pi --no-builtin-tools
# 全部工具关闭 —— 纯对话模式，模型只能用语言回答
pi --no-tools "解释一下 CAP 定理"选择策略：
- 代码审查 / 架构问答 →
-t read,grep,find,ls，杜绝任何写入； - 只想屏蔽某个危险动作 →
-xt bash或-xt write； - 让扩展全权接管工具集 →
--no-builtin-tools； - 纯文本任务 →
--no-tools最省心，也最安全。
工具白名单 ≠ 安全边界
官方 security 文档明确：这些选项是行为控制而非沙箱。真正的隔离要靠容器或微虚拟机（见第 19 章）。不要把 -t read,... 当成对抗恶意仓库的防线。
17.3 CLI 参数速查表
完整语法：pi [options] [@files...] [messages...]。以下按功能分组（与官方 README 的 CLI Reference 一致）：
运行模式
| 参数 | 说明 |
|---|---|
| （默认） | 交互式 TUI |
-p / --print | 输出响应后退出 |
--mode json | JSON Lines 事件流输出 |
--mode rpc | RPC 进程集成模式 |
--export <in> [out] | 把会话导出为 HTML |
模型相关
| 参数 | 说明 |
|---|---|
--provider <name> | 指定 provider（anthropic/openai/google 等） |
--model <pattern> | 模型模式或 ID，支持 provider/id[:thinking] |
--api-key <key> | 临时指定 API key（覆盖环境变量） |
--thinking <level> | 思考级别：off/minimal/low/medium/high/xhigh/max |
--models <patterns> | Ctrl+P 循环切换的模型列表 |
--list-models [search] | 列出可用模型 |
会话相关
| 参数 | 说明 |
|---|---|
-c / --continue | 继续最近一次会话 |
-r / --resume | 浏览并选择历史会话 |
--session <path|id> | 使用指定会话文件或 UUID 前缀 |
--fork <path|id> | 从既有会话分叉出新会话 |
--session-dir <dir> | 自定义会话存储目录 |
--no-session | 临时模式，不落盘 |
-n <name> | 启动时命名会话 |
资源加载
| 参数 | 说明 |
|---|---|
-e <source> | 加载扩展（路径/npm/git），可重复 |
--skill <path> | 加载技能，可重复 |
--prompt-template <path> | 加载提示词模板，可重复 |
--theme <path> | 加载主题，可重复 |
--no-extensions / --no-skills 等 | 关闭对应资源的自动发现 |
--no-context-files (-nc) | 不加载 AGENTS.md / CLAUDE.md |
系统提示词
bash
# 整体替换默认系统提示词（上下文文件和技能仍会追加）
pi --system-prompt "你是一个只回答 Go 问题的助手"
# 只做追加
pi --append-system-prompt "所有回答使用中文"17.4 组合实战示例
把上面的参数拼起来，就是各种标准工作姿势：
bash
# 1. 用便宜的小模型跑批量文档翻译（无人值守）
for f in docs/en/*.md; do
pi --model openai/gpt-4o-mini --no-session -p "把 @$f 翻译成中文，只输出译文" \
> "docs/zh/$(basename "$f")"
done
# 2. 高思考级别攻坚复杂 bug
pi --model sonnet:high "这个并发死锁只在周五出现，帮我排查"
# 3. 只读模式 + 禁止上下文文件，审计陌生仓库
cd /tmp/untrusted-repo
pi -t read,grep,find,ls --no-context-files -p "总结这个项目的入口和依赖"
# 4. 精确复现同事的调试现场：从会话 ID 分叉继续
pi --session 9f2c1a3b --fork17.5 本章小结
- 内置工具共 7 个：read/write/edit/bash/grep/find/ls，
bash是能力上限也是风险上限； - 四个控制层级：
--tools白名单 >--exclude-tools黑名单 >--no-builtin-tools>--no-tools； - 工具开关只是行为约束不是沙箱；
- 模型可用
provider/id:thinking简写一步到位； --system-prompt替换、--append-system-prompt追加。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. 官方推荐的"只读审查"命令是哪种写法？
2. --no-tools 与 --no-builtin-tools 的区别是？
3. 想从当前会话的历史中某个点另开一条探索线，应该用？
4. pi --model sonnet:high 中 ":high" 的含义是？
🛠️ 动手实践
- 分别用
--tools、--exclude-tools、--no-tools三种方式让 pi"只解释不修改"你的一个项目，对比三种方式的响应差异。 - 用
--list-models找出你可用的最便宜模型，写一个批量重命名 markdown 标题的脚本。 - 用
--fork复制一条旧会话，在新分支上尝试不同的重构方案，再用/tree回看两条线的分叉点。