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 中列出的每个参数,只要它的值是非空字符串:
- aidy 以用户身份调用
op。列表通过page_size查询参数分页时,请求 100 条。 - 找出条目:响应体本身是数组时就用它,否则取第一个包含
key字段的对象数组,比如{"items": [...]}。 - 如果某条目的
key等于该值,说明它已经是 id,保持不变。 - 否则把该值与每个条目的
name、display_name、displayName或title比较,忽略大小写和首尾空白。 - 恰好一个匹配时,把值替换为该条目的
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
Section titled “unresolved_reference”没有条目匹配或有多个匹配时,调用以 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)." }}这个错误作为工具结果返回给模型,不会以错误的形式展示给用户。
在流程中的位置
Section titled “在流程中的位置”resolve 在校验和宿主表单之后、confirmation 查询和审批之前执行:
validate → form → resolve → confirmation lookup → approval → execute因此审批绑定的是解析后的 id。用户批准的是“Stop server gpu-train-01?”,而 argsHash 覆盖的是 {"vm_id": "vm-42", ...}。即使这个名字之后指向了另一台服务器,也改变不了已批准的内容。
resolve 引用的操作不存在或不是 read 时,目录校验失败。见目录。