第 11 章 Chapter Outline：Tool Use 与工具协议

本文件是正文写作蓝图。MCP 当前 Tools 草案、OpenAI Function Calling、Anthropic 工具定义与 JSON Schema 的陈述均只在各自协议、产品或规范语境中使用。工具契约（Tool Contract）、调用请求（Invocation Request）、调用记录（Invocation Record）、结果信封（Result Envelope）、调用关联标识（Call Correlation ID）和效果不确定性（Effect Uncertainty）均为本书工程模型；它们不是任何厂商的 API、授权策略、日志后端或执行保证。正文、示例实现和 Fact Check 当天必须重新核验 REF-036 至 REF-039。

章节契约

读者完成后的能力： 能把“模型建议调用”“参数形状合格”“请求获准执行”“工具返回结果”“外部效果已观察”和“任务验收通过”分成不同判断；能为一个工具设计稳定描述、输入/输出形状、调用关联、错误表示和未知效果出口；能指出何时必须交给环境/权限、人类批准、结果验证或恢复机制，而不把一个 Schema、成功文本或模型自述当成充分证据。

前置知识： 已完成第 8 章，理解 Skill 描述和可复用能力不是单次调用契约；已完成第 10 章，理解 Workflow Contract、State Record、检查点和状态迁移不能替代工具请求或外部观察。读者应能阅读 JSON 对象、简单序列图、表格、错误分类和测试断言。

章节边界： 本章定义工具接口的可审查模型，不实现 MCP、SDK、路由器、浏览器、文件系统、网络 API、数据库、凭证、实际权限、批准 UI、审计系统、重试运行时或真实外部副作用。第 12 章负责环境、Sandbox、凭证和授权；第 14 章负责人工批准；第 15 章定义观察质量；第 17 章定义结果验收；第 18 章深入重试、恢复和补偿；第 24 章把工具协议扩展到 MCP 集成；第 25 章把浏览器操作做成真实端到端验证。本章不把上述能力预写为已存在的工具字段。

小节蓝图

1. 模型提出动作，不等于系统已经行动

• 读者问题： 为什么模型生成一段“调用工具”的结构化文本后，系统仍不能直接声称已经读取、写入、发布或完成任务？
• 叙述任务： 以原创场景开场：Agent 提议用“修改书稿元数据”工具把状态改为完成，但调用对象只含名称和参数。依次拆开六个时刻：模型候选、参数解析、策略/批准检查、应用执行、结果回传、外部效果观察与任务验证。定义本书中的工具调用（Tool Invocation）为一次可关联交互，不等于外部效果或验收结论。
• 证据边界： REF-037 只支持 OpenAI 产品中“提供工具、接收调用、在应用侧执行、回传结果”的多步流程；REF-036 只支持当前 MCP Tools 草案的发现与调用实例。本书的六阶段区分、案例和证据规则不归因给任一来源。
• 计划工件： “候选 / 请求 / 执行 / 结果 / 观察 / 验收”对照表，分别说明谁产生它、能证明什么、不能证明什么、需要哪个关联标识。
• 验证： 给出“模型已输出 JSON”“工具返回 200”“回读发现目标未变”“评估通过”四类观察，读者能指出其中哪一项仍缺授权、效果或验收证据。
• 过渡： 先把时刻拆开，才能定义模型和人类看到的工具描述究竟应提供哪些约束。

2. 工具描述（Tool Descriptor）：描述能力，不授予能力

• 读者问题： 一个好工具定义应告诉模型和审查者什么，又为什么不能把名称、描述或“只读”提示当作可信安全声明？
• 叙述任务： 定义本书 Tool Descriptor 的最小字段：稳定名称和版本、用途、非用途、输入/输出形状、结果限制、效果类别、失败边界和文档来源。说明名称与描述帮助选择，Schema 描述数据形状，效果分类帮助风险路由；三者均不授予权限。对比含糊的 update 与明确的 document_update_metadata_preview，但不为任何厂商制定命名规则。
• 证据边界： REF-036 只支持 MCP 草案中的名称、说明、输入/输出 Schema，以及工具注解只是提示、不能作为不受信任服务器的可靠行为依据。REF-038 只支持 Anthropic 客户端工具中的名称、说明、input_schema 和输入样例。字段集合、案例名称、风险分类和审查规则均为本书模型。
• 计划工件： Tool Descriptor 模板和“描述 / Schema / 权限 / 批准 / 观察 / 验收”职责矩阵；矩阵必须突出“提示不是授权”。
• 验证： 读者能为一个文档查询工具写出用途和非用途；能拒绝仅凭 readOnlyHint、自然语言描述或成功历史就允许写入的设计。
• 过渡： 描述的是可见能力面；下一节说明如何把候选参数变成可执行的、受检查的请求。

3. 从 Schema 到调用请求（Invocation Request）：形状检查之后仍有门

• 读者问题： 参数通过 JSON Schema 或 SDK 的严格模式后，为什么仍可能不能执行？
• 叙述任务： 区分解析、形状校验、语义校验、目标确认、环境/权限检查和批准检查。定义本书 Invocation Request 的字段：调用关联标识、工具及版本、已解析参数、输入来源摘要、风险类别、环境引用、策略/批准快照引用和预期观察。强调 Schema 不知道目标资源是否存在、参数是否过时、权限是否有效或副作用是否可接受。
• 证据边界： REF-039 只支持 JSON Schema 的 Core 与 Validation 定位；REF-037 只支持该产品提醒应用在执行前校验模型生成参数；REF-038 的 Schema 与样例只适用于该产品。语义/权限/批准分层、请求字段和判定顺序均为本书模型。
• 计划工件： 请求准入门（admission gate）表：未知工具、结构不合格、语义冲突、只读、写入缺批准、环境不匹配和允许执行等路径；每条写明需要的证据与不可推出的结论。
• 验证： 读者能说明 {"path":"../draft.md"} 符合字符串类型却仍可能被拒绝的原因；能把“写入缺批准”交给第 14 章，而不是在 Schema 中伪造批准结果。
• 过渡： 请求获准执行后，最重要的是让每份结果、错误和后续观察能回到正确的那一次调用。

4. 调用关联与结果信封（Result Envelope）：让结果能被追溯，而非只被朗读

• 读者问题： 多个工具请求、异步返回或接力执行时，为什么不能只把“工具说成功了”拼回上下文？
• 叙述任务： 定义调用关联标识的目的：把一个 Invocation Request、路由决定、执行观察、工具结果、回读和后续验证候选连起来。定义本书 Result Envelope：关联标识、结果分类、原始/规范化输出、错误对象或限制、观察时间、效果状态、下一步候选和未验证范围。强调调用记录用于追溯，但不等同于第 10 章完整 State Record，也不等同于第 17 章验收证据。
• 证据边界： REF-037 只支持 OpenAI Function Calling 示例中 call_id 与函数结果的关联；REF-036 只支持 MCP 当前草案中工具结果内容、structuredContent/错误层次的限定结构。关联字段名称、结果分类、记录格式与教学对象都是本书模型。
• 计划工件： 请求—结果—观察—验证的关联图，以及 Result Envelope 模板。图中明确区分工具返回的 succeeded 与验证器给出的接受结论。
• 验证： 面对两个同名工具调用和一个延迟结果，读者能要求关联标识；面对只有文本“修改成功”，读者能指出其缺请求、目标、观察和验收关联。
• 过渡： 关联解决“它属于哪一次调用”；下一节解决“错误、超时和未知效果各自意味着什么”。

5. 错误、超时与效果不确定性：不要用一次重试掩盖未知

• 读者问题： 工具报错、协议报错、被策略拒绝、超时、取消和“可能已经写入”分别应传达什么？
• 叙述任务： 建立本书的结果分类：rejected 表示在执行前被策略或批准门拒绝；failed 表示获得了可关联的失败观察；timed_out 与 cancelled 只记录交互终止；effect_unknown 表示已有证据无法判定外部效果是否发生；succeeded 仅表示某次工具交互返回了成功类结果。说明协议级异常与工具内部错误需要保留不同诊断路径；任何分类都不自动推导可安全重试。
• 证据边界： REF-036 只支持 MCP 当前草案区分工具结果中的 isError 与找不到工具、服务不支持等协议级错误的做法。REF-037、REF-038 仅支持各自产品的调用/定义语境。错误分类、未知效果规则、停止条件和恢复动作属于本书模型；不外推为固定 HTTP、SDK 或 MCP 错误码。
• 计划工件： 错误层次与恢复入口表，列出可见输入、可保留证据、允许动作、禁止结论和应移交章节。表必须将“效果未知”与“确认失败”分开。
• 验证： 读者能为“请求超时且没有回读”“工具返回结构错误”“批准过期”“外部系统明确拒绝”选择不同的记录和下一步；不会把 timeout 当作失败事实或把 retry 当作副作用安全证明。
• 过渡： 分类本身不产生安全执行；下一节把工具的效果类型与后续权限、批准和观察责任连接起来。

6. 副作用与证据边界：接口安全不是一句“仅限只读”

• 读者问题： 为什么把工具标为只读、可逆或幂等仍不足以决定它是否可运行？
• 叙述任务： 使用本书效果类别：纯计算、受限读取、可逆写入、不可逆写入和开放世界操作。对每类提出“调用前需要什么、调用后要观察什么、哪些未知必须停止”的问题，不建立真实权限矩阵。解释效果类别用于让风险在协议中可见，不替代第 12 章的实际环境和最小权限，也不替代第 14 章的人类责任判定。
• 证据边界： REF-036 的 readOnlyHint、destructiveHint、idempotentHint 与 openWorldHint 位于 MCP 2025-11-25 Schema Reference；它们只是给客户端的提示，且该版本化 Schema 明确其并非来自不受信任服务器的可靠行为证明。本书效果类别、证据门槛和案例路由均为工程扩展。
• 计划工件： “效果类别 / 调用前证据 / 调用后观察 / 不可推导内容 / 移交章节”矩阵，包含第 12、14、15、17、18 章的责任列。
• 验证： 读者能解释为什么一项自称“只读”的远程查询仍可能因数据范围、凭证或提示不可信而不能自动执行；能解释为什么“可逆”不等于不需要验证。
• 过渡： 有了可见的效果边界，最后用一个教学案例把预览、执行、回读和验证串成闭环。

7. 完整工程案例：为书稿元数据变更设计预览、执行与回读协议

• 读者问题： 怎样把一个看似简单的“修改文件”请求设计为可审查交互，而不是把模型输出直接写入仓库？
• 叙述任务： 构造原创教学案例：虚构 document_update_metadata 工具先生成预览，再由环境/批准门决定能否执行，最后回传带关联标识的结果并发起回读观察。演练四条路径：参数形状不合格、写入缺批准、工具返回但回读冲突、超时导致效果未知。案例刻意不操作本仓库、不创建真实文件、不调用 Git、网络、模型或工具。
• 证据边界： Tool Contract、案例对象、状态分类、预览语义、回读判断和预期输出均为本书教学模型。REF-036 至 REF-039 不支持真实文件写入、MCP/SDK 行为、权限、回读可靠性或审计结论。
• 计划图示： chapter-11-tool-invocation-sequence.mmd 将展示 Agent candidate → admission gate → tool adapter → target → Result Envelope → observation → evaluator，并以分支明确拒绝、失败、超时和效果未知。图不得画成真实文件写入、批准已完成或任务已验收。
• 计划示例： 11-tool-use-and-tool-protocols.example-plan.md 将定义纯内存函数，例如 assessToolInvocation：输入 Tool Contract、Invocation Request 与注入的环境/批准摘要；输出只表示允许、拒绝、需要批准或效果未知的教学判断。示例不得调用 MCP、SDK、网络、文件、Git、浏览器、数据库、凭证或真实权限系统。
• 验证： 计划测试至少覆盖：未知工具、参数形状不合格、只读请求允许、写入缺批准、关联标识冲突、超时后的效果未知和“工具成功但未经验证”。所有断言只能证明教学函数契约。
• 过渡： 第 12 章将把抽象的准入门落到环境、Sandbox、凭证和实际权限；第 24、25 章再把协议应用到 MCP 和浏览器等具体集成。

不在本章展开的内容

• MCP 的版本协商、远程服务器接入、认证、发现缓存和多服务器治理属于第 24 章；本章只建立单次工具交互的契约边界。
• 凭证、文件系统、网络、进程、生产环境和 Sandbox 的实际隔离属于第 12 章。
• 人类何时承担批准责任、如何呈现确认和如何记录责任归属属于第 14 章。
• 页面快照、元素定位、点击、等待与真实 UI 证据属于第 25 章；本章不会把接口返回代替浏览器端到端验证。
• 结果是否达到业务目标属于第 17 章；超时、重试、补偿和恢复策略属于第 18 章。

章节工件状态

1. 已完成：Research Brief 与候选资料。REF-036 至 REF-039 的允许陈述、外推禁区与写作日复核要求已登记。
2. 已完成：Chapter Outline。逐节定义读者问题、叙述任务、证据边界、计划工件、验证和相邻章节责任。
3. 已完成：First Draft 与 Technical Review。正文保留原创教学案例、本书模型和未实施边界；审查记录位于 .memory/reviews/2026-07-16-chapter-11-technical-review.md。
4. 已完成：Example Plan 与 Example Implementation。assessToolInvocation 的模块缺失红灯、7 项 Node 内置测试与演示均有真实记录，且只处理注入对象。
5. 已完成：Mermaid 图源与 Diagram Review。图源、SVG/PNG 导出、图文一致性比较与视觉审查记录位于 .memory/reviews/2026-07-16-chapter-11-diagram-review.md；图只表达本书模型。
6. 已完成：Fact Check。REF-036 至 REF-039 的允许陈述、外推禁区、动态复核条件和教学工件边界记录于 11-tool-use-and-tool-protocols.fact-check.md。
7. 已完成：Language Editing。术语、主语、段落节奏和图示替代描述已收束，未改变来源、示例接口或 Mermaid 语义；记录位于 .memory/reviews/2026-07-16-chapter-11-language-edit.md。
8. 未开始：Final Review。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] 覆盖候选、描述、Schema、调用请求、关联、结果信封、错误层次、效果不确定性和副作用边界。
• [x] 明确 MCP、OpenAI、Anthropic 与 JSON Schema 的限定陈述，不把草案、产品字段或规范写成跨系统保证。
• [x] 明确第 8、10、12、14、15、17、18、24、25 章的责任边界，不提前实现 Tool、权限、批准、观察、验证、重试或集成运行时。
• [x] 图示、示例、测试和案例均保持为计划，不表示真实工具执行、外部效果、授权或验收事实。