Tool 契约设计

Tool 是能力契约，不是随手暴露的函数

一份生产契约同时服务四类读者：模型用名称与描述判断是否调用；Runtime 用 Schema、风险和策略元数据执行；调用方依赖稳定结果与错误；平台依赖 Owner、版本、SLO 和审计字段治理。直接把内部 REST API 自动转换为 Tool，往往会暴露模型不该决定的租户、权限、内部令牌和低层资源标识。

契约应围绕用户意图而不是内部接口颗粒度设计。例如“创建退款申请”比“更新订单表字段”更能承载权限、不变量和审计。一个 Tool 最好只有一个清晰能力边界；把查询、批准和执行揉在一起，会使只读探索意外升级为副作用。

名称与描述决定模型如何区分能力

名称使用稳定、具体的动词与资源，如 orders_get_status；描述先说何时使用，再说何时不要使用、必要前置和可观察副作用。近义 Tool 若无法从描述稳定区分，应合并、加确定性路由或要求澄清，而不是继续堆提示词。

参数 Schema 应减少歧义而非复刻内部 API

用类型压缩动作空间。优先使用 enum、范围、格式和可判别联合类型，避免接受“大 JSON”再让执行器猜动作。可选字段要有真实默认语义；不能把“缺省”同时解释为不修改、自动推断和清空。

让单位、时间和标识可判定。金额必须声明币种与最小单位，时间使用带时区的标准格式，ID 指明来源和生命周期。自然语言地址、显示名和数据库主键不是同一种标识。示例可以辅助模型，但不能代替约束。

模型只提交业务引用。租户、用户、访问令牌、审批人和服务端时间由可信上下文注入，不开放为模型参数。对大对象传稳定 Artifact ID 并在执行端重新读取，避免过期内容和 Context 复制。

Schema 之后还有业务校验。执行前必须再次校验资源存在性、所属租户、当前状态、权限和额度。模型看到订单号且格式合法，不意味着它拥有该订单，也不意味着订单仍允许退款。

结果既要供模型理解，也要防止 Context 爆炸

结果分为机器可判定状态、模型可读摘要和可选 Artifact。稳定字段用于后续逻辑，摘要说明“发生了什么、下一步能做什么”，大列表和原始文档存外部并给出分页/截断信息。来源、生成时间和数据新鲜度会直接影响后续决策，应进入结果契约。

type ToolResult<T> =
  | { ok: true; data: T; summary: string; artifactId?: string; observedAt: string }
  | { ok: false; error: ToolError; correlationId: string }

结果写入模型 Context 前再执行最小披露：删除令牌、内部拓扑、无关个人数据与堆栈。不要把“模型可能需要”当无限返回的理由。

错误必须支持下一步决策

按恢复动作分类。至少区分输入不可用、权限/策略拒绝、业务冲突、暂时故障和结果未知。HTTP 500 可能来自确定的业务适配错误，HTTP 超时也可能已经成功；仅按状态码决定重试会制造重复副作用。

稳定字段优先于自然语言。错误包含稳定 code、retryable、safeMessage、可选 retryAfter 与 correlationId。诊断细节进入受保护日志，不回注模型。错误码必须有 Owner 和兼容策略。

只反馈可行动信息。告诉模型需要补哪个字段、是否允许重新读取状态、是否必须转人工；不要回传 SQL、堆栈或策略内部规则。模型不得凭错误文案自行把“未知”改写为“失败”。

副作用是契约的一部分

契约显式声明只读、可逆写入、不可逆动作，幂等能力、所需审批、预览能力和执行后验证接口。高风险动作采用 prepare/commit：先返回变更摘要、影响范围和确认令牌，审批后由 Runtime 提交；确认令牌绑定参数、身份、策略版本和有效期，不能作为通用放行票。

Tool 演进要保护模型和消费者

新增可选字段通常比重命名、改变单位或收紧 enum 更容易兼容，但模型选择行为仍可能变化。破坏性变更采用新版本身份、双版本观察窗口、调用方迁移和明确下线门槛；不要只靠 Prompt 通知模型“以后换个写法”。

测试分四层：Schema 正反例；业务/权限/副作用契约；模型是否在有干扰项时选对并生成正确参数；历史 Trace 回放和新旧版本兼容。上线指标至少包含选中率、参数拒绝率、业务冲突、未知结果和旧版本残余调用。