跳转到内容

Resolve

用户说“停掉 gpu-train-01”,而你的 API 接收的是 vm-42。resolve 负责衔接:在审批之前,aidy 在一个列表操作中查找字符串参数,把名字替换成对应的 id。

"/api/vm/{vm_id}/stop": {
"post": {
"x-aidy": {
"name": "stop_vm",
"effect": "update",
"resolve": { "vm_id": { "op": "list_vms" } }
}
}
},
"/api/vms": {
"get": {
"x-aidy": { "name": "list_vms", "description": "List the user's cloud servers (VMs)." }
}
}

resolve 把参数名映射到 {op, key?}:

键 含义
op 目录中列出候选项的 read 操作。
key 存放 id 的字段。默认 id。

对 resolve 中列出的每个参数,只要它的值是非空字符串:

  1. aidy 以用户身份调用 op。列表通过 page_size 查询参数分页时,请求 100 条。
  2. 找出条目:响应体本身是数组时就用它,否则取第一个包含 key 字段的对象数组,比如 {"items": [...]}。
  3. 如果某条目的 key 等于该值,说明它已经是 id,保持不变。
  4. 否则把该值与每个条目的 name、display_name、displayName 或 title 比较,忽略大小写和首尾空白。
  5. 恰好一个匹配时,把值替换为该条目的 key。

对于这个列表:

{
"items": [
{ "id": "vm-42", "name": "gpu-train-01" },
{ "id": "vm-43", "name": "gpu-train-02" }
]
}

{"vm_id": "gpu-train-01"} 变成 {"vm_id": "vm-42"},而 {"vm_id": "vm-42"} 保持不变。

没有条目匹配或有多个匹配时,调用以 unresolved_reference 失败,不会向该操作发送任何请求。错误信息最多列出十个候选项,模型可以据此询问用户或选出正确的一项:

{
"status": "failed",
"error": {
"code": "unresolved_reference",
"message": "\"gpu-train\" matches several items; say which one: gpu-train (vm-42), gpu-train (vm-51)."
}
}

这个错误作为工具结果返回给模型,不会以错误的形式展示给用户。

resolve 在校验和宿主表单之后、confirmation 查询和审批之前执行:

validate → form → resolve → confirmation lookup → approval → execute

因此审批绑定的是解析后的 id。用户批准的是“Stop server gpu-train-01?”,而 argsHash 覆盖的是 {"vm_id": "vm-42", ...}。即使这个名字之后指向了另一台服务器,也改变不了已批准的内容。

resolve 引用的操作不存在或不是 read 时,目录校验失败。见目录。