# 目录

你的 OpenAPI 文档，在允许 Agent 使用的操作上加上 x-rungent，就是目录。本页讲什么是操作、效果意味着什么、名称怎样变成 ID、两次调用怎样串起来，以及上线前怎样把这些全部检查一遍。

一个云控制台本来就有 OpenAPI 3.1 文档。给其中三个端点各加一个 `x-rungent` 对象，就得到一份目录：

```json
"/api/vms": {
  "get": {
    "x-rungent": { "name": "list_vms", "description": "List the user's cloud servers (VMs)." }
  },
  "post": {
    "x-rungent": { "name": "create_vm", "description": "Create a cloud server (VM).", "form": "vm_form" }
  }
},
"/api/vms/{vm_id}/stop": {
  "post": {
    "x-rungent": {
      "name": "stop_vm",
      "description": "Stop a running cloud server (VM).",
      "effect": "update",
      "resolve": { "vm_id": { "op": "list_vms" } },
      "confirmation": { "title": "Stop server {vm_id}?" }
    }
  }
}
```

没有 `x-rungent` 的操作对 rungent 不可见。助手、MCP、CLI、`skill.md` 和搜索读的都是同一份标注，所以每个操作只需描述一次。所有键见 [x-rungent](x-rungent.md)。

## 什么是操作

操作就是某个路径上带 `x-rungent` 的某个 HTTP 方法。它是 Agent 的一个工具、MCP 客户端的一个工具，也是 CLI 的一条命令。唯一必填的键是 `name`：小写字母、数字和 `_`，最长 64 个字符，在目录中唯一。

| 用在哪里 | 写法 |
|---|---|
| Agent 的工具、MCP 工具、断言的 `op` | `stop_vm` |
| CLI 命令 | `stop-vm`，或 `cli.command` 里写的词（`vm stop`） |

`description` 是模型选工具时读的：写清资源，以及用户对它的叫法（「cloud server (VM)」）。`title` 用在确认卡、活动行和 CLI 帮助里。两者都默认取 OpenAPI 的 `summary`。

## 效果、确认与入口

`effect` 说明一次调用做什么，其余所有默认值都由它决定。除非你另行指定，rungent 按 HTTP 方法推断：

| `effect` | 含义 | 默认对应 | `approval` | `surfaces` |
|---|---|---|---|---|
| `read` | 不做任何改动 | `GET`、`HEAD` | `never` | `agent`、`mcp`、`cli` |
| `create` | 创建资源 | `POST` | `always` | `agent`、`cli` |
| `update` | 修改已有资源 | `PUT`、`PATCH` | `always` | `agent`、`cli` |
| `delete` | 删除资源 | `DELETE` | `always` | `agent`、`cli` |
| `external` | 对外动作：发邮件、刷卡扣款 | 无 | `always` | `agent`、`cli` |

方法表达不清时就写明 `effect`：停服务器是一个修改已有服务器的 `POST`，所以 `stop_vm` 是 `update`。`GET` 必须保持为 `read`。

- **`approval`** 取 `never` 或 `always`，由运行时根据目录决定，从不由提示词决定。一个仍然需要确认的读操作，比如导出全部客户，就设 `"approval": "always"`。见[表单与确认](forms-and-approvals.md)。
- **`surfaces`** 列出操作出现在哪些入口。MCP 默认只读；在写操作上列出 `mcp`，就会把它提供给能请用户确认的 MCP 客户端。见[入口](surfaces.md)。

## 特殊角色的操作

有些操作不是工具，而是给 rungent 自己应答的。它们带 `role`，不出现在任何入口，也从不提供给模型：

| `role` | 形式 | 页面 |
|---|---|---|
| `identity` | `GET`，无参数；每份目录恰好一个 | [以用户身份调用](acting-as-the-user.md#who-the-user-is) |
| `search` | `GET`，带必填的查询参数 `q` | [搜索与知识](search.md#add-a-search-source) |
| `form` | 应答表单的 `POST`；rungent 把它当作读操作 | [表单与确认](forms-and-approvals.md#declare-the-form) |

## 每个用户看到自己的目录

rungent 用当前登录用户自己的凭据获取你的 OpenAPI 文档，读到的内容按凭据缓存 5 分钟。你的服务器可以略去某个用户无权调用的操作，那么任何入口都不会向这个用户提供它们。`GET /rungent/v0/catalog` 列出调用者看到的内容。隐藏操作只是一种礼貌：你的 API 仍要对收到的每次调用做授权。

## 输入结构

rungent 把每个操作变成一个扁平的输入结构，模型、MCP 客户端和 CLI 看到的都是它：

- 路径参数和查询参数成为顶层属性；路径参数必填。
- JSON 请求体如果是带 `properties` 的对象，就展开成顶层属性；其他请求体变成一个 `body` 属性。
- 指向 `#/components/schemas` 的 `$ref` 保留为 `$defs` 引用，所以递归结构依然有效。

对于 `POST /api/vms/{vm_id}/stop`，请求体为 `{"forced": boolean}`，输入就是 `{vm_id, forced}`，其中 `vm_id` 必填。调用你的 API 时，rungent 再把参数拆回路径、查询和请求体。

每次调用前，rungent 先转换参数类型（数字字符串转成数字，JSON 字符串转成对象），再做校验。不合规的参数永远到不了你的 API：模型收到 `invalid_arguments`，其中按路径列出每个问题（`vm_id: required`），然后修正自己的调用。带表单的操作则改为打开表单。

## 把名称换成 ID

用户写「stop gpu-train-01」，你的路由要的是 `vm-42`。`resolve` 把一个参数映射到列出候选项的读操作 `{op, key?}`，其中 `key` 是条目里存放 ID 的字段（默认 `id`）。对每个列出的、值为字符串的参数，rungent：

1. 以用户身份调用 `op`；如果它接受查询参数 `page_size`，就请求 100 条；
2. 从应答中取出条目：应答本身就是数组，或者是第一个由带 `key` 的对象组成的嵌套数组（`{"items": [...]}`）；
3. 如果某个条目的 `key` 等于这个值，就保留原值，因为它已经是 ID；
4. 否则不区分大小写，拿它和每个条目的 `name`、`display_name`、`displayName` 或 `title` 比较，用唯一匹配项的 `key` 替换它。

没有匹配或匹配到多个，调用就以 `unresolved_reference` 失败，并列出最多十个候选项，模型可以从中选一个，或者去问用户。名称在确认卡之前解析，所以确认绑定的是 `vm-42`，卡片等待期间即使有人改名，也改变不了实际执行的内容。确认卡上的 [lookup](forms-and-approvals.md#write-the-card) 会把名称写回卡片。

`resolve` 适合一次列表调用就能完整返回的集合：服务器、项目、成员。更大的集合，模型通过[搜索](search.md)或带过滤的列表找到 ID。

## 把两次调用当一次运行

有些动作需要两次调用：先准备一份草稿，检查配额并报价，再提交它。第一个操作上的 `next` 指明第二个操作，rungent 在第一次成功后、模型写任何内容之前立即运行它：

```json
"x-rungent": {
  "name": "prepare_vm_draft",
  "approval": "never",
  "next": {
    "op": "commit_vm_draft",
    "arguments": { "draft_id": "id", "revision": "revision" },
    "when": { "status": "prepared" }
  }
}
```

草稿应答 `{"id": "d-7", "revision": 3, "status": "prepared", …}`，于是 rungent 用 `{"draft_id": "d-7", "revision": 3}` 调用 `commit_vm_draft`。如果草稿应答 `"status": "needs_quota"`，`when` 不满足：链条停下，由模型解释结果。`argumentsFrom` 则把结果中的一个对象整个作为下一次调用的输入（[x-rungent](x-rungent.md#chains)）。

下一次调用和其他调用一样，要经过校验、解析和它自己的确认，所以链条从不跳过确认卡。每个操作在一条链中最多运行一次，所以环路会自行终止。

## 调用之后会发生什么

- `open` 指明成功后要展示的产品页面，用参数和结果填充（`/console/instance/{vm_id}`）。面板把它交给你的路由器。
- `redact` 列出模型和 MCP 客户端永远看不到的结果字段（`ip`）。名称像密钥的字段（`password`、`token`、`api_key`、`cookie` 等）总会被移除。
- `timeoutSeconds` 限定调用时长：默认 120 秒，最多 3600 秒。
- 在一次运行中，用相同参数重复的写操作直接以第一次的结果作答。如果重复正是目的（「再加一块 GPU」），就设 `repeatable: true`。
- 需要的时间超过一次请求的操作，应答 `202 {"rungentTask": "<id>"}`，运行会一直等到你的 API [完成这项任务](http-api.md#deferred-tasks)。

## 检查目录

rungent 读取目录时会校验它，有错误就拒绝。部署前先检查文档：

```bash
npx rungent check --openapi http://localhost:3000/api/openapi.json --routes routes.txt
```

它打印每一个问题，只要有问题就以 1 退出；规则见 [x-rungent](x-rungent.md#validation-rules)。`--routes` 接收你的界面发出的请求，每行一个 `METHOD /path`，没有操作承接的行都会报失败，除非该行以 `# browser-only: <reason>` 结尾。这样能保证你的界面能做的事，Agent 也能做。

## 接下来

[以用户身份调用](acting-as-the-user.md)讲 rungent 怎样以用户自己的权限调用这些操作。
