跳转到内容

审批

写操作要等用户确认。这个决定由运行时代码根据目录做出,审批绑定到用户所见确切参数的哈希。恢复运行时不能改动参数,已批准的调用最多执行一次。

当操作的 approval 为 always 时需要审批,这是除 read 之外所有效果的默认值(见操作与效果)。模型无法绕过:提示词、工具描述和模型输出都不参与这个决定。宿主还会再检查一遍,因为 approval: always 操作的断言必须带有审批 id apr(见委托)。

对于写操作,aidy 按顺序执行以下步骤,任何一步失败即停止:

  1. 校验参数是否符合操作的输入 schema。
  2. 表单:操作指定了 form 时,向用户收集输入(见表单)。
  3. Resolve:把名字解析成 id(见 Resolve)。
  4. 查询卡片要显示的资源名(confirmation.lookup)。
  5. 请求审批:运行以 aidy:approval 中断结束。
  6. 用户批准后执行。

在第 6 步之前,没有任何写请求会到达你的 API。查询失败会在审批前中止调用,什么都不会执行。

在第 5 步,aidy 冻结已校验的参数并计算:

argsHash = base64url(SHA-256(JCS(arguments)))

JCS 即 JSON Canonicalization Scheme,RFC 8785:键排序、无空白、数字使用最短形式,所以每种实现都得到相同的字节。aidy 把审批连同冻结参数和哈希一起持久化,并把两者放进中断:

{
"id": "int_…",
"reason": "aidy:approval",
"message": "Stop server gpu-train-01?",
"toolCallId": "call_…",
"expiresAt": "2026-11-19T08:15:00Z",
"responseSchema": {
"type": "object",
"properties": { "approved": { "type": "boolean" } },
"required": ["approved"]
},
"metadata": {
"aidy": {
"op": "stop_vm",
"arguments": { "vm_id": "vm-42", "forced": false },
"argsHash": "q2…",
"impact": {
"title": "Stop server gpu-train-01?",
"target": "gpu-train-01",
"effect": "update",
"risk": "medium",
"costHint": null,
"changes": ["Force: No"]
}
}
}
}

客户端在下一次运行的 resume[] 中作答,并回传它展示过的哈希:

{
"interruptId": "int_…",
"status": "resolved",
"payload": { "approved": true },
"metadata": { "aidy": { "argsHash": "q2…" } }
}
  • 回传的 argsHash 必须与存储的一致;不一致则什么都不执行。
  • aidy 执行的是冻结的参数,恢复时无法替换参数。
  • 每个审批最多执行一次,即使两个 worker 竞争也是如此:审批通过对状态的 compare-and-set 被消费。
  • approved: false 或 status: "cancelled" 都不会执行写操作。用户如果直接发送新消息,需要同时为每个未关闭的中断发送 cancelled。
  • 审批在 15 分钟后过期(expiresAt)。

确认过的写操作总会执行完并被记录:运行的生命周期长于它的 HTTP 响应,只有 POST /aidy/v0/runs/{id}/cancel 能停止它。

Python kit 和 @aidy-dev/spec 为宿主和测试提供同样的哈希函数:

from aidy import args_hash
args_hash({"vm_id": "vm-42", "forced": False})

confirmation 决定卡片的样子。模板支持 {argument} 占位符和 {resource_name}:

"confirmation": {
"title": "Stop server {resource_name}?",
"target": "{resource_name}",
"fields": [{ "key": "forced", "label": "Force", "values": { "true": "Yes", "false": "No" } }],
"lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" },
"risk": "medium",
"costHint": "Billing continues for disks."
}
键 含义
title 必填。卡片上的问题。
target 被操作的资源。有 lookup 时默认为 {resource_name}。
fields 要展示的参数,带标签和可选的显示值。每个字段成为 impact.changes 中的一行(Force: No)。
lookup 在展示卡片前以用户身份发起的带鉴权 GET。响应中 labelPath 处的值成为 {resource_name}。
risk low、medium 或 high。
costHint 关于费用的简短说明。

lookup 路径必须由目录中的某个 GET 操作提供,因为 aidy 的每次调用都要标明所调用的操作。有了 lookup,即使模型只传了 vm-42,卡片也能显示“Stop server gpu-train-01?”。

metadata.aidy.impact 是卡片展示的内容:title、target、effect、risk、costHint 和 changes,由 confirmation 和冻结参数渲染而成。@aidy-dev/react 的 ApprovalCard 负责渲染。MCP 客户端在 elicitation 提示中看到相同的标题、目标和变更,CLI 则把它们打印在终端上。