AI 智能体的工具契约

工具是以函数形式呈现的权限边界。JSON 校验只能证明参数形状正确，不能证明动作符合意图、获得授权、可安全重试或确实完成。

契约维度

维度	必须回答的问题
选择	何时用它而不是别的工具？
输入	字段、范围、enum 和路径规则是什么？
权限	哪个身份执行，可读写什么？
副作用	只读、可逆、外部可见还是破坏性？
并发	读写之间状态变化怎么办？
幂等	同一请求重试会不会重复？
结果	如何证明完整、部分、拒绝或未知完成？
审批	哪些参数/副作用组合需人工？
可观测性	保留哪些脱敏字段、ID、耗时和产物？

契约例子

name: replace_text
purpose: 在一个仓库文件中替换唯一精确文本块
input:
  path: 仓库相对路径，禁止 traversal
  old_text: 非空且必须恰好匹配一次
  new_text: string
preconditions:
  - path 位于批准写入范围
  - 工作树版本与读取时一致
effects: 可逆本地写入
idempotency: 成功后不可在不重读的情况下重试
result:
  status: succeeded | conflict | no-match | multiple-matches | denied
  changed_file: path 或 null
approval: 超出任务范围时必需

它给循环一个可区分失败；笼统的 edit failed 只会诱发盲重试。

结果信封

{
  "request_id": "req-123",
  "status": "partial",
  "completed": 8,
  "failed": 2,
  "retry_safe": false,
  "artifact": "results/batch-123.json",
  "errors": [{"code": "permission-denied", "item": "..."}]
}

单项成功不能变成批次成功。“结果未知”也不同于失败，因为重复外部动作可能造成副本。

设计规则

少量正交工具优于重叠别名；拆开读、可逆写和破坏动作；尽量用 enum/范围/明确路径代替自由 shell；模型外校验路径与授权；大数据写入产物，只返回带来源摘要；可变状态使用版本/并发检查；审批绑定副作用和参数；测试畸形、恶意、过期、重复与部分成功调用。

注入与不可信结果

网页、issue、文档和工具元数据可能含有试图驱动模型的指令，它们仍是数据。Harness 应标出来源，不让返回文本获得执行权限，避免秘密进入上下文，并在下一动作前重新过策略。类型化响应减少歧义，但不能净化语义。

小模型取舍

紧凑模型常更可靠地调用浅 schema，但删减 schema 可能删掉安全信息。必须用精确模板和量化测有效调用率与任务成功。不要为了适配模型静默削弱权限；改用更简单工具、约束适配器或更强模型。