跳转到内容

x-aidy

宿主发布一份 OpenAPI 3.1 文档。带有 x-aidy 对象的操作会加入 aidy 目录;没有它的操作对 aidy 不可见。未知键一律拒绝。目录背后的设计见 目录 和 操作。

"post": {
"operationId": "stopVm",
"x-aidy": {
"name": "stop_vm",
"title": "Stop server",
"description": "Stop a running cloud server (VM).",
"open": "/console/instance/{vm_id}",
"confirmation": {
"title": "Stop server {resource_name}?",
"lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" }
}
}
}

下表在构建时由 spec/schemas/x-aidy.schema.json 生成,始终与契约一致。

字段类型约束必填
namestringpattern ^[a-z][a-z0-9_]{0,63}$是
titlestring≤ 80 chars
descriptionstring≤ 500 chars
effect"read" | "create" | "update" | "delete" | "external"
approval"never" | "always"
role"identity" | "search" | "form"
surfaces"agent" | "mcp" | "cli"[]
confirmationobject
confirmation.titlestring≤ 200 chars是
confirmation.targetstring≤ 200 chars
confirmation.fieldsobject[]
confirmation.fields[].keystring是
confirmation.fields[].labelstring是
confirmation.fields[].valuesmap<string, string>
confirmation.lookupobject
confirmation.lookup.pathstringpattern ^\/(?!\/)是
confirmation.lookup.labelPathstring是
confirmation.risk"low" | "medium" | "high"
confirmation.costHintstring≤ 200 chars
formstringpattern ^[a-z][a-z0-9_]{0,63}$
resolvemap<string, object>
resolve.<name>.opstringpattern ^[a-z][a-z0-9_]{0,63}$是
resolve.<name>.keystring
nextobject
next.opstringpattern ^[a-z][a-z0-9_]{0,63}$是
next.argumentsmap<string, string>
next.argumentsFromstring
next.whenmap<string, any>
openstringpattern ^\/(?!\/)
redactstring[]
repeatableboolean
timeoutSecondsnumber> 0, ≤ 3600
cliobject
cli.commandstringpattern ^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$是
cli.argsstring[]

由 spec/schemas/x-aidy.schema.json 在构建时生成;其余键一律拒绝.

键 类型 含义
name ^[a-z][a-z0-9_]{0,63}$ 必填。 稳定的工具名,在目录内唯一。同时是 MCP 工具名和 CLI 命令(stop_vm → stop-vm)。
title 字符串,≤ 80 给人看的标签,用于审批卡片、活动记录和 CLI 帮助。默认取 OpenAPI 的 summary,其次是 name。
description 字符串,≤ 500 给模型看的描述。写明资源及其常见同义词。默认取 OpenAPI 的 summary。
effect read create update delete external 调用的作用。默认按方法推断:GET/HEAD 为 read,POST 为 create,PUT/PATCH 为 update,DELETE 为 delete。external 表示会触达产品之外(邮件、支付)。
approval never always 每次调用是否需要用户确认。read 默认 never,其余默认 always。
role identity search form 特殊操作,见 角色。
surfaces agent mcp cli 组成的数组 操作出现在哪些面。默认:read 三处都有;其他作用为 agent、cli。为写操作列出 mcp,它只会暴露给支持确认的 MCP 客户端。角色操作没有 surfaces。
confirmation 对象 审批卡片,见 Confirmation。
form 操作名 一个 role: form 操作,在审批或执行前提供输入表单。
resolve {argument: {op, key?}} 名称或 id 查找:审批前,如果某个字符串参数不是 op 所列条目的 key(默认 id),就按条目名称匹配。唯一匹配时替换它;没有匹配或多个匹配时,调用以 unresolved_reference 失败。
next 对象 成功后、模型回复前执行的后续调用,见 链式调用。
open 路径模板 成功后展示的产品页面,由参数和结果填充({vm_id})。必须以 / 开头。
redact 字段名数组 在模型或 MCP 客户端看到之前从结果中删除的字段(例如 ip)。
repeatable 布尔值 允许在一次运行中重复执行相同的成功写操作。默认 false:相同的写操作直接返回第一次的结果。
timeoutSeconds 数字,≤ 3600 调用超时。默认 120;role: search 操作默认 2,最大 10(更大的值是目录错误)。
cli {command, args?} CLI 写法:command 是空格分隔的单词(vm stop),args 是按顺序的位置参数。默认:name 中的 _ 换成 -,没有位置参数。
{
"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."
}

模板支持 {argument} 占位符和 {resource_name}。设置 lookup 后,aidy 会在展示审批前以用户身份发起一次带认证的 GET,从响应中读取 labelPath 作为 {resource_name}。lookup 路径必须由目录中的某个 GET 操作提供,因为 aidy 发起的每次调用都要写明所调用的操作(见 委托)。lookup 失败时,调用在审批前中止,不会执行任何操作。

键 约束 含义
title 必填,≤ 200 卡片标题。
target ≤ 200 被操作的对象,醒目展示。
fields [{key, label, values?}] 卡片上展示的参数;values 把原始值映射为标签。
lookup {path, labelPath} 提供 {resource_name} 的认证 GET。
risk low medium high 显示在卡片上。
costHint ≤ 200 一行费用提示。

详见 审批。

"next": {
"op": "commit_vm_draft",
"arguments": { "draft_id": "id", "revision": "revision" },
"when": { "status": "prepared" }
}

arguments 把下一次调用的参数映射到本次结果中的路径。argumentsFrom 指定结果中的一个路径,其对象作为下一次调用的完整输入(预先准备好的配置);此时 arguments 只能补充路径参数,不能覆盖它。when 必须与结果匹配,否则链在此停止。下一个操作自身的审批规则照常生效。详见 链式调用。

角色 形态 用途
identity GET,无参数,read。每个目录恰好一个。 返回调用所用凭据对应的 Identity。
search GET,必填查询参数 q,可选 limit,read,timeoutSeconds ≤ 10。 一个搜索来源,见 搜索。
form POST,read,approval: never。 接收目标调用的参数,返回一个 表单。从不提供给模型。
{
"subject": "u_123",
"tenant": "t_9",
"name": "Ada Lovelace",
"locale": "zh-CN",
"scopes": ["aidy:admin"]
}

subject 必填,其余可选。拥有 aidy:admin 的用户可以修改 aidy 设置(模型链)。会话归属于 (subject, tenant)。详见 身份。

aidy 把每个带标注的操作规范化为一个输入 schema,模型、MCP 和 CLI 看到的都是它:

  • 路径参数和查询参数成为顶层属性。
  • 对象类型的请求体展开为顶层属性。其他类型的请求体成为一个 body 属性。
  • 同一个名字出现两次(例如路径参数和请求体字段同名)属于目录错误。
  • 指向 #/components/schemas 的 $ref 保留为 $defs 引用,因此递归 schema 依然有效。

出现以下情况时目录校验失败:

  • 名字重复;
  • form、resolve 或 next 引用的操作不存在,或其角色、作用不对;
  • 角色操作的方法或形态不对;
  • confirmation 的 lookup.path 没有对应的 GET 操作;
  • open 或 lookup.path 不是以单个 / 开头。

运行 aidy check --openapi openapi.json 列出全部问题,见 CLI 参考。