跳转到内容

操作与效果

每个目录操作都声明它做什么(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 是调用成功后展示的产品页面。它是一个路径模板,用参数和结果填充,必须以 / 开头:

{ "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 设置命令词和位置参数:

{ "name": "stop_vm", "cli": { "command": "vm stop", "args": ["vm_id"] } }
终端窗口
aidy vm stop vm-42 --forced

不设置时,命令是把名字中的 _ 换成 -(stop-vm),所有参数都是 flag。见 CLI 指南。