操作与效果
每个目录操作都声明它做什么(effect)、用户是否需要确认(approval),以及出现在哪里(surfaces)。aidy 根据 HTTP 方法推导出合理的默认值,所以大多数操作只需要 name 和 description。
effect |
含义 | 默认对应 |
|---|---|---|
read |
读取数据,不做修改。 | GET、HEAD |
create |
创建资源。 | POST |
update |
修改已有资源。 | PUT、PATCH |
delete |
删除资源。 | DELETE |
external |
触达产品之外:发邮件、扣款。 | 无 |
当 HTTP 方法不能说明调用做了什么时,就显式设置 effect。POST /api/vm/{vm_id}/stop 修改的是已有服务器,属于 update;用 POST 实现的搜索接口属于 read。
{ "name": "stop_vm", "effect": "update" }除 read 之外的效果都是写操作。效果还决定 MCP 工具注解(readOnlyHint、destructiveHint、idempotentHint)以及审批卡片上的 effect 字段。
approval |
含义 |
|---|---|
never |
立即执行。read 的默认值。 |
always |
每次调用都由用户确认。所有写操作的默认值。 |
只有这两种取值,任何提示词都无法改变它:是否审批由运行时代码根据目录决定。需要确认的 read(比如导出完整客户名单)可以设置 approval: "always"。见审批。
surfaces 列出操作出现在哪里:agent、mcp、cli。
| 效果 | 默认入口 |
|---|---|
read |
agent、mcp、cli |
| 任意写操作 | agent、cli |
因此 MCP 服务器默认只读。在写操作上列出 mcp 会把它暴露给 MCP 客户端,此后每次调用都要求客户端通过 MCP elicitation 确认;不支持 elicitation 的客户端能看到该工具,但调用会被拒绝并附上说明。aidy CLI 同样通过 MCP 连接,但它还能看到 cli 入口上的操作,并在终端上请求确认。
角色操作(identity、search、form)没有入口,也从不作为工具提供给模型。搜索通过内置的 search 工具到达模型。
结果:open 和 redact
Section titled “结果:open 和 redact”open 是调用成功后展示的产品页面。它是一个路径模板,用参数和结果填充,必须以 / 开头:
{ "name": "stop_vm", "open": "/console/instance/{vm_id}" }成功后,运行会发出 CUSTOM 事件 aidy.ui.open,内容为 {"path": "/console/instance/vm-42"},@aidy-dev/react 会把这个路径交给你的路由。
redact 列出在模型或 MCP 客户端看到之前要从结果中删除的字段,任意深度都生效:
{ "name": "get_vm", "redact": ["ip", "root_password_hint"] }名字像机密的字段(password、token、api_key、authorization、cookie 等)总会被删除,无论在结果中还是在事件展示的参数中。
aidy 在代码中对同一次运行内的每个调用施加以下保护:
| 情形 | 结果 |
|---|---|
| 模型用相同参数重复一个写操作 | 直接返回第一次的结果,不再审批、不再调用。工具结果带 deduplicated: true。需要允许相同写操作时(比如“再加一块 GPU”)设置 repeatable: true。 |
| 模型重复一个已成功的读操作 | 以 repeated_call 拒绝;模型必须根据已有结果回答。 |
| 模型重试一个已批准但失败的写操作 | 以 already_attempted 拒绝;模型必须告诉用户失败原因。 |
| 参数不符合输入 schema | 返回 invalid_arguments;不会到达你的 API。 |
| 模型一次调用多个工具,其中一个暂停等待用户 | 其余调用返回 not_executed,可在用户回答后再次调用。 |
timeoutSeconds 限制每次调用的时长,默认 120 秒,最多 3600 秒。超时的调用以 timeout 失败。宿主返回错误时为 http_{status}(例如 http_403),并附上宿主的错误信息,以及放在 detail 中的错误响应体(已脱敏,最多 4 KB),让模型能根据结构化字段修正调用。
这些错误码返回给模型,由模型用自己的话向用户解释结果。
耗时超过一次请求的操作可以返回 202 和 {"aidyTask": "<id>"}。运行会以 aidy:task 中断暂停,直到宿主通过 POST /aidy/v0/tasks/{taskId} 完成任务,该请求需用 Aidy-Host-Assertion 签名。见 AG-UI profile。
CLI 写法
Section titled “CLI 写法”cli 设置命令词和位置参数:
{ "name": "stop_vm", "cli": { "command": "vm stop", "args": ["vm_id"] } }aidy vm stop vm-42 --forced不设置时,命令是把名字中的 _ 换成 -(stop-vm),所有参数都是 flag。见 CLI 指南。