第 3 节 · 本站原创中文课程 · 建议 25 分钟
工具定义、真实执行与模型消息
学完能做：分开工具声明和执行，实现一个可解释的只读工具。
模型看到声明，程序承担副作用
core/tools/index.ts 的 ToolName 包含 read、bash、powershell、edit、write、grep、find、ls。createToolDefinition 与 createTool 分开：定义描述参数和能力，执行对象才访问文件或启动进程。Codemode 和 tool_search 由内建扩展注册，不在这个八项联合类型里。不能因为模型选择了 read，就说读取成功，也不能把名字带 read 的工具视为可信。
工具观察如何回到模型
pi-ai 的 Quick Start 定义工具 schema 和 Context，用 models.stream 取得流式事件，再通过 s.result() 获得最终消息。示例筛选 toolCall，执行后把 toolCallId、toolName、content、isError 等写成 toolResult 放回上下文。工具调用请求与工具执行结果是两种消息；缺少关联 ID 或结果，模型下一轮就无法可靠判断执行了什么。
先用假工具建立边界
学习时先实现读取预登记文档 ID 的工具，不接受任意文件路径。定义参数错误、NOT_FOUND、TIMEOUT 的处理，再在宿主执行端重复校验；schema 是沟通协议，不是最终访问控制。测试未知 ID、超长返回、取消和正文中的伪指令。这个练习是你的最小安全适配器，并非宣称 Pi 自带同样的权限系统。
增减默认工具不等于替换清单
1.1 的 pi --tools +codemode,-write 保留其他默认工具、添加 codemode 并移除 write；只用普通名称的列表则替换整个选择。两种写法不能混用，+/- 项只接受准确工具名，模式排除使用 --exclude-tools。禁用 write 仍可能留下 bash、edit 或 MCP 工具，因此它不是只读沙箱。用一个假工具集合模拟增减和替换，再检查最终可达能力。
这是本站独立编写的讲解与示例，并非官方课程逐字翻译。理解之后，请完成下面的练习、自测和笔记。
参考来源：Pi v1.1.0 官方源码与文档