P280 · 工具调用

把需要管控的动作定义成明确工具

Promote opaque actions to typed control points

需要单独授权、显示、审计或调度的动作,应提供有类型约束的工具接口。

编辑审核

以下示例与示意结果由本站编写,用于说明方法,不是模型实测结果。

使用场景

发票助手能调用通用 Shell,但发送发票前必须展示确切发票与收件人。教学任务是把 INV-17 发给 billing@example.test;宿主已有针对该组合的审批规则。需要明确识别发送动作才能应用这条规则。

具体做法

  1. 找出需要独立授权、展示或审计的副作用,定义动作接口;教学接口为 send_invoice(invoice_id, recipient)。
  2. 宿主校验发票存在、收件人有效和审批绑定的具体组合,在发送前显示该组合。审批不足时返回未执行状态。
  3. 将批准对象与实际发送载荷绑定,防止检查后换收件人;记录动作、参数、审批依据和发送结果。
  4. 若通用Shell仍可绕过发送门禁,还需在执行环境或服务端约束同一副作用。

反例

将INV-17发给billing@example.test,把发送命令放到Shell工具里;按普通命令执行,不需让宿主知道这是发送发票。

改进写法

将INV-17发给billing@example.test时调用send_invoice,传递发票身份和确切收件人。宿主先展示并验证这组参数的已有审批,再发送相同载荷;检查失败返回未发送。记录可复核的发送结果,不能以工具调用已生成作为发送成功。

为什么这样改

明确动作与参数给宿主一个稳定检查点,不必从任意命令字符串推断业务意图。相同接口还便于专门显示和审计;类型约束只帮助表达,不负责授予权限。

如何验证

教学测试中,批准INV-17与指定收件人的组合后发送一次;将收件人换为other@example.test应拒绝且发送次数为零。模拟服务返回失败,应显示失败而不是成功。核对审计中的参数与实际请求一致。

适用边界

类型化接口不能自动防止绕过、载荷变化或重复发送;还需宿主和服务约束及必要的幂等处理。理解Shell副作用的宿主也可强制门禁,不能把来源中的绝对表述当成事实。这一方法关注动作控制点,不是让每个简单命令都成为专用工具。

原文与版本

如何收录这些方法