第 3 节 · 本站原创中文课程 · 建议 25 分钟
工具定义、真实执行与模型消息
本节保留 Pi 1.0.0 的引用与学习记录。阅读 Pi 1.1.0 对应章节
学完能做：分开工具声明和执行，实现一个可解释的只读工具。
模型看到声明，程序承担副作用
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 自带同样的权限系统。
这是本站独立编写的讲解与示例，并非官方课程逐字翻译。理解之后，请完成下面的练习、自测和笔记。
参考来源：Pi v1.0.0 官方源码与文档