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