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" } } }}Schema
Section titled “Schema”下表在构建时由 spec/schemas/x-aidy.schema.json 生成,始终与契约一致。
| 字段 | 类型 | 约束 | 必填 |
|---|---|---|---|
name | string | pattern ^[a-z][a-z0-9_]{0,63}$ | 是 |
title | string | ≤ 80 chars | |
description | string | ≤ 500 chars | |
effect | "read" | "create" | "update" | "delete" | "external" | ||
approval | "never" | "always" | ||
role | "identity" | "search" | "form" | ||
surfaces | "agent" | "mcp" | "cli"[] | ||
confirmation | object | ||
confirmation.title | string | ≤ 200 chars | 是 |
confirmation.target | string | ≤ 200 chars | |
confirmation.fields | object[] | ||
confirmation.fields[].key | string | 是 | |
confirmation.fields[].label | string | 是 | |
confirmation.fields[].values | map<string, string> | ||
confirmation.lookup | object | ||
confirmation.lookup.path | string | pattern ^\/(?!\/) | 是 |
confirmation.lookup.labelPath | string | 是 | |
confirmation.risk | "low" | "medium" | "high" | ||
confirmation.costHint | string | ≤ 200 chars | |
form | string | pattern ^[a-z][a-z0-9_]{0,63}$ | |
resolve | map<string, object> | ||
resolve.<name>.op | string | pattern ^[a-z][a-z0-9_]{0,63}$ | 是 |
resolve.<name>.key | string | ||
next | object | ||
next.op | string | pattern ^[a-z][a-z0-9_]{0,63}$ | 是 |
next.arguments | map<string, string> | ||
next.argumentsFrom | string | ||
next.when | map<string, any> | ||
open | string | pattern ^\/(?!\/) | |
redact | string[] | ||
repeatable | boolean | ||
timeoutSeconds | number | > 0, ≤ 3600 | |
cli | object | ||
cli.command | string | pattern ^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$ | 是 |
cli.args | string[] |
由 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 中的 _ 换成 -,没有位置参数。 |
Confirmation
Section titled “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."}模板支持 {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。 |
接收目标调用的参数,返回一个 表单。从不提供给模型。 |
Identity
Section titled “Identity”{ "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 参考。