第十章：工具是一份带权限和结果的执行契约

10.1 工具描述只解决可发现性的一部分

模型需要知道工具名称、用途与参数结构。宿主则还需要执行实现、权限分类、取消方式、结果格式和可能的副作用。把这些内容只写成一句“读取文件”，不足以支撑恢复、测试和调度。

Codex 的 ToolRouter 同时保存模型可见规格和执行注册表，说明“公布给模型什么”与“能执行什么”需要对应。Pi 的读取工具定义也提供了从声明继续追踪执行的具体入口。Codex · router.rs L83–97 Pi · read.ts L84–98

以读取工具为例，参数必须是对象，路径必须是字符串，多余字段怎样处理也要明确。本书实验使用严格字段集合，不把未知字段悄悄丢弃。真实系统可采用 JSON Schema 等工具，但仍应核对校验后传给执行函数的是哪一份参数。

参数校验不能代替权限检查。{"path":"../secret"} 在结构上完全有效，却可能越过工作区。反过来，路径在工作区内，也不意味着某次写入已经被授权。类型、范围、授权与运行时隔离是不同检查。

工具找不到文件，可以返回可恢复的错误结果；未知工具可以返回 invalid；策略拒绝返回 denied；程序内部不可恢复异常则可能终止本轮。用一项布尔 success 覆盖所有情况，会让模型和恢复器缺少下一步依据。

本书实验保留 ok、invalid、denied、error、conflict 与 unknown。conflict 表示基于旧状态的写入前置条件不成立，正确路径是重新读取，而不是自动放宽校验。unknown 则要求外部核查，不能让模型猜测其副作用。

一个比“覆盖文件”更可解释的接口是：目标路径、预期旧内容哈希、新内容。宿主先核对文件是否仍与模型读取时相同，再写入。这样可以减少基于过期上下文覆盖用户改动的风险。

但要精确描述保证：普通“读取哈希 → 比较 → 写入”之间仍可能被其他进程修改，它不是原子 compare-and-swap。本书实验用这项限制解释并发边界；真正需要强保证时，应结合锁、操作系统原语、版本化存储或事务设计，而不能给教学检查冠上事务承诺。

输出应包含足以支持下一步的信息，但不应无上限占满上下文。大结果可以外置，返回预览、内容哈希和定位符。消费者需要知道它看到的是完整值还是截断值，验证程序也应能够访问完整证据。

练习：某工具返回 HTTP 200，但业务响应写着“任务未完成”，应记录 ok 吗？传输成功与目标成功应分开表达。宿主可以记录请求成功，同时将业务结果标为未完成，不能让模型只凭状态码宣告整个任务成功。