最佳实践与反模式

本章把前面章节的工程经验浓缩为可执行的检查清单，并列出常见反模式及其危害。

Schema 设计

检查清单

• [ ] 工具名称唯一且语义清晰：使用小写 + 下划线，例如 search_orders 而不是 func1。
• [ ] 描述优先于命名：description 应说明工具用途、适用场景、返回内容。不要只重复名称。
• [ ] 必填字段明确：用 required 列出所有必填参数，避免模型遗漏关键输入。
• [ ] 类型约束具体：尽量使用 string、number、boolean、array 等具体类型，少用 {} 或 anyOf。
• [ ] 枚举值列出选项：如果参数只有固定取值，使用 enum。
• [ ] 添加示例：在 description 或 examples 中给出参数示例，降低模型理解成本。
• [ ] 字段说明完整：每个参数都写 description，说明格式、单位、取值范围。
• [ ] 控制 schema 大小：避免嵌套过深、字段过多。大型 schema 既消耗 token，也降低遵循率。
• [ ] 启用严格模式（如果可用）：OpenAI strict mode 能显著提升参数格式正确率。
• [ ] 版本化 schema：破坏性变更走大版本，description 中标注 deprecation。

反模式

• “万能工具”：一个工具接收大量可选参数，试图覆盖所有场景。模型容易选错、填错参数。
• 描述含糊：描述只有“获取信息”，模型无法判断与其他工具的区别。
• 过度使用 additionalProperties: true：允许任意额外字段会降低可校验性。
• 把内部字段名暴露给模型：使用业务语义名称，而不是数据库列名。

执行治理

检查清单

• [ ] 超时必设：每个工具调用都有连接超时与整体超时。
• [ ] 重试策略区分错误类型：只对可重试错误（5xx、超时）重试，4xx 不重试。
• [ ] 重试次数有上限：避免无限重试压垮下游。
• [ ] 指数退避 + 抖动：防止重试风暴。
• [ ] 熔断器保护连续失败：连续失败达到阈值后快速失败，并暴露状态指标。
• [ ] 降级路径：主路径失败时返回缓存、兜底结果或友好提示。
• [ ] 并发控制：独立调用并行，依赖调用串行；设置最大并发数。
• [ ] 幂等性设计：写操作工具应支持幂等键（idempotency key）。

反模式

• 无超时：下游卡住时整个 Agent 挂起。
• 对所有错误都重试：对 400 Bad Request 反复重试只会浪费资源。
• 裸奔执行：直接把模型参数拼进 shell 或 SQL，存在注入风险。
• 忽略部分批量失败：并行调用中部分失败时静默丢弃，导致结果不完整。

校验与沙箱

检查清单

• [ ] 多层校验：语法校验 → JSON Schema 校验 → 语义校验 → 权限校验。
• [ ] 参数级授权：不仅校验“能不能调工具”，还要校验“能不能以该参数调”。
• [ ] 敏感操作 HITL：删除、扣款、发送外部消息等操作需要人工确认。
• [ ] 沙箱执行：外部代码或网络调用在受限容器/网络中运行。
• [ ] Secrets 不泄露：API Key、数据库密码由 Runtime 注入，不进入模型上下文。
• [ ] 输出脱敏：错误信息不暴露堆栈、内部 IP、数据库结构。

反模式

• 只校验类型不校验语义：例如 user_id 是字符串但无权访问该用户。
• 把 secrets 当工具参数：让模型自己填 API Key。
• 在模型上下文中返回原始错误堆栈：既泄露信息，又浪费 token。

可观测性

检查清单

• [ ] 全链路 Trace：从模型调用到工具执行每个阶段都有 span。
• [ ] 核心指标可监控：延迟、成功率、schema 违规率、工具选择错误率、重试率、降级率、token 成本。
• [ ] 结构化日志：参数、结果、错误分类清晰，便于检索。
• [ ] 敏感字段脱敏：日志中不记录密码、token、PII。
• [ ] 定期评估工具选择准确率：用人工标注或 LLM Judge 抽检。

反模式

• 只打成功日志：失败时没有 trace，无法定位。
• 日志满天飞：不加区分地记录所有内容，既贵又难检索。
• 没有指标基线：无法判断“今天工具调用变慢了”是否正常。

大规模工具集

检查清单

• [ ] 渐进披露：工具元数据（名称 + 一句话描述）常驻可索引，完整 schema 按需加载。
• [ ] 每轮注入受限：实际进 Prompt 的候选工具控制在 5~10 个，经检索/规则筛选产生。
• [ ] 检索质量有评测：对工具召回统计 Recall@K，避免“该招的没招进来”。
• [ ] 索引异步更新：工具增删改后索引异步重建，不阻塞请求路径。
• [ ] 热门组合缓存：高频任务的工具组合预编排，降低检索与推理开销。

反模式

• 全量注入：几百个工具的 schema 全塞进 Prompt，token 爆炸且选择准确率骤降。
• 检索与权限脱节：检索层召回当前用户无权使用的工具，权限校验又太晚。
• 元数据写成小作文：一句话能讲清的工具描述写成长文档，索引与注入成本双高。

工具供应链安全

检查清单

• [ ] 第三方工具描述视为不可信输入：发现时审查并去指令化，防止工具投毒。
• [ ] 哈希存证 + 变更告警：首次审批记录工具定义哈希，运行时变更即拒绝或重新审批（防 rug pull）。
• [ ] 静态扫描：接入 mcp-scan 等工具审计 MCP Server 与工具描述。
• [ ] 最小权限：第三方工具默认沙箱 + 高审批级别；破坏性操作强制 HITL。
• [ ] 网络出站白名单：MCP Server / 工具进程限制出站网络，防数据外泄。

反模式

• 审批一次永久信任：工具描述更新后不重新校验，等于把权限交给第三方 Server。
• 把工具描述当系统提示：描述中出现“忽略之前的指令”类内容时无检测机制。
• 沙箱裸奔：代码执行/浏览器工具无网络隔离、无资源限额。

模型交互

检查清单

• [ ] 错误信息可行动：返回给模型的错误应说明“哪里错了、如何修正”。
• [ ] 长任务压缩工具历史：对过旧的 tool_result 做摘要或外置到 Memory，避免上下文膨胀（平台侧即 context compaction）。
• [ ] 限制每轮工具数量：工具过多时选择准确率下降，可通过命名空间或检索动态筛选。
• [ ] 明确终止条件：设置 max-turns、max-tool-calls、no-progress 检测。
• [ ] 结果反馈完整：工具结果包括成功/失败、关键数据、错误说明，便于模型继续推理。

反模式

• 静默吞掉工具错误：模型以为调用成功，基于错误信息继续生成。
• 盲目重试：收到超时直接重放写操作，造成重复扣款/下单；应先验证外部状态（verify-before-retry）。
• 把工具当 Prompt 用：本可以用简单 prompt 解决，却注册一个无意义工具。
• 不控制循环深度：模型在两个工具之间来回调用，永远无法收敛。

一句话总结

好 Tool Use = 清晰的 schema + 坚固的校验 + 隔离的执行 + 完整的观测 + 明确的终止。