审批
写操作要等用户确认。这个决定由运行时代码根据目录做出,审批绑定到用户所见确切参数的哈希。恢复运行时不能改动参数,已批准的调用最多执行一次。
策略写在代码里
Section titled “策略写在代码里”当操作的 approval 为 always 时需要审批,这是除 read 之外所有效果的默认值(见操作与效果)。模型无法绕过:提示词、工具描述和模型输出都不参与这个决定。宿主还会再检查一遍,因为 approval: always 操作的断言必须带有审批 id apr(见委托)。
卡片出现之前
Section titled “卡片出现之前”对于写操作,aidy 按顺序执行以下步骤,任何一步失败即停止:
- 校验参数是否符合操作的输入 schema。
- 表单:操作指定了
form时,向用户收集输入(见表单)。 - Resolve:把名字解析成 id(见 Resolve)。
- 查询卡片要显示的资源名(
confirmation.lookup)。 - 请求审批:运行以
aidy:approval中断结束。 - 用户批准后执行。
在第 6 步之前,没有任何写请求会到达你的 API。查询失败会在审批前中止调用,什么都不会执行。
冻结参数与 argsHash
Section titled “冻结参数与 argsHash”在第 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 则把它们打印在终端上。
- 委托:宿主检查的
aprclaim。 - AG-UI profile:中断与恢复。
- React 指南:
ApprovalCard。