Pi Coding Agent 的工具把模型提出的动作转换为文件读取、代码修改或命令执行。工具名表示一种能力，实际结果由执行环境、参数和当前文件状态共同决定。
本文按 2026 年 9 月 18 日可查的官方资料说明；命令、配置和默认行为应结合所安装版本核对。 下文讨论官方内置实现；扩展可以替换或增加工具。
常用工具的职责
| 工具 | 用途 | 应关注的结果 |
|---|---|---|
| read | 读取文本或支持的图片 | 是否读全、是否发生截断 |
| edit | 对已有文件做局部修改 | 是否匹配目标、实际差异是什么 |
| write | 创建文件或覆盖其完整内容 | 路径及写入内容是否正确 |
| bash | 执行 Shell 命令 | 输出、退出状态和外部影响 |
| grep、find、ls | 内容搜索、文件查找与目录浏览 | 查询范围及匹配结果 |
Pi 的默认编码工具围绕 read、edit、write、bash 组织，其他工具可按需要启用。工具选择参数见官方使用说明。
读取与修改如何区别
read 实现接受路径及可选的行偏移与数量。长文本会受输出限制，返回内容包含继续读取的提示。只看到前一段，不能据此声称检查过整个文件。
edit 实现面向局部编辑，并返回修改差异。write 实现会创建不存在的文件，或覆盖已有文件，并可创建父目录。选择这两种动作时，局部修改和完整重写的意图必须明确。
例如修复分页条件，通常先读取目标函数与测试，再做局部修改；不能因为要改一行，就假定模型已经掌握整份文件的其他内容。
命令运行在哪里
内置文件工具使用工作目录解析相对路径，Shell 工具也使用相应执行目录。在桌面终端、容器或远程主机启动 Pi，会得到不同的文件系统、程序安装和环境变量。
因此，命令找不到某个程序可能是执行环境问题；测试找不到配置可能是目录问题。此时应先检查环境与路径，不必立刻归因为模型不理解任务。
输出、超时与失败
bash 实现支持命令和可选超时，结果包含执行输出及失败信息。其工具参数没有默认超时；宿主环境可能另有约束。
错误输出可以成为下一轮判断的依据。相反，命令退出成功也不等于业务目标正确：测试脚本可能没有覆盖当前问题，文件写入也可能写错位置。用户应结合实际差异与验证结果理解完成状态。
工具限制的范围
工具白名单决定哪些工具可供模型调用，但工作目录本身不是文件系统隔离边界。仅去掉 write 也不能保证只读，因为 Shell 仍可能修改文件。应把工具组合与环境权限一起考虑，详见官方安全说明。