跳转到内容

目录

目录(catalog)是 aidy 可以调用的操作集合。它就是你的 OpenAPI 3.1 文档:带有 x-aidy 对象的操作进入目录,没有的则对 aidy 不可见。

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

aidy 用用户的凭据从 host.openapi 拉取文档,因此宿主可以给不同用户展示不同的目录。GET /aidy/v0/catalog 列出当前调用者可见的操作。

name 是唯一的必填键。它匹配 ^[a-z][a-z0-9_]{0,63}$,在目录中唯一,并在各处使用:

位置 写法
agent 工具和 MCP 工具 stop_vm
CLI 命令 stop-vm,或 cli.command 中的词(vm stop)
断言 claim op stop_vm

title 用于审批卡片、活动记录和 CLI 帮助,默认取 OpenAPI 的 summary,再退回 name。description 给模型看:写明资源及其常见同义词(“cloud server (VM)”),默认取 summary。

其他键各有专页说明:

键 页面
effect、approval、surfaces、redact、repeatable、timeoutSeconds、open、cli 操作与效果
confirmation 审批
form 表单
resolve Resolve
next 链式调用
role 身份、搜索与知识、表单

完整列表见 x-aidy 参考。

aidy 把每个带注解的操作规范化为一个输入 schema。模型、MCP 客户端和 CLI 看到的是同一个 schema。

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

对于请求体为 {"forced": boolean} 的 POST /api/vm/{vm_id}/stop,派生出的输入是:

{
"type": "object",
"properties": {
"vm_id": { "type": "string" },
"forced": { "type": "boolean", "default": false }
},
"required": ["vm_id"]
}

aidy 调用该操作时,再把参数拆回路径、查询串和请求体。调用前,参数会先做类型转换(JSON 字符串转为对象或数组,数字字符串转为数字),再按这个 schema 校验。不合法的参数以 invalid_arguments 返回给模型,不会到达你的 API。

aidy 加载目录时会做校验。未知的 x-aidy 键会被拒绝,以下情况也会失败:

  • 名字重复;
  • form、resolve 或 next 引用了不存在的操作,或引用了角色、效果不对的操作;
  • 角色操作的方法或形态不对;
  • confirmation 的 lookup.path 不是由目录中的 GET 操作提供;
  • open 或 lookup.path 不是以单个 / 开头。

部署前先检查文档:

终端窗口
aidy check --openapi openapi.json

aidy check 打印目录中的所有问题,有任何问题就以 1 退出。加上 --routes 时,它还接受一份 UI 发出的 METHOD /path 请求列表(每行一个),凡是没有目录操作提供的路由都会报错,除非该行标注了 # browser-only: <原因>。这样可以保证 agent 能做到 UI 能做的事。

GET /api/vm/{vm_id}
POST /api/vm/{vm_id}/stop
GET /api/vm/{vm_id}/console # browser-only: interactive terminal