# x-rungent

x-rungent OpenAPI 扩展的每个键：类型、默认值和作用，以及目录必须通过的校验规则。

OpenAPI 3.1 文档里的一个操作，带上 `x-rungent` 对象就进入目录。没有它的操作对 rungent 不可见；对象里出现未知的键，校验就会失败。这些键合起来是什么意思，见[目录](catalog.md)。

```json
"post": {
  "summary": "Stop server",
  "x-rungent": {
    "name": "stop_vm",
    "description": "Stop a running cloud server (VM).",
    "effect": "update",
    "resolve": { "vm_id": { "op": "list_vms" } },
    "open": "/console/instance/{vm_id}",
    "confirmation": {
      "title": "Stop server {resource_name}?",
      "lookup": { "path": "/api/vms/{vm_id}", "labelPath": "name" },
      "risk": "medium"
    },
    "cli": { "command": "vm stop", "args": ["vm_id"] }
  }
}
```

## 全部键

| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
| `name` | `^[a-z][a-z0-9_]{0,63}$` | 必填 | 稳定的名字，在目录内唯一：它是模型和 MCP 看到的工具名，把 `_` 换成 `-` 就是 CLI 命令，也是断言里的 `op`。 |
| `title` | 字符串，1–80 | OpenAPI 的 `summary`，没有则用 `name` | 给人看的标签：确认卡、活动记录、CLI 帮助。 |
| `description` | 字符串，1–500 | OpenAPI 的 `summary`，没有则用 `title` | 模型据此选择操作。写明资源及其同义词（"cloud server (VM)"）。 |
| `effect` | `read` `create` `update` `delete` `external` | 角色操作为 `read`；其余按方法推断：`GET`/`HEAD` `read`，`POST` `create`，`PUT`/`PATCH` `update`，`DELETE` `delete` | 调用做什么。`external` 会触及产品之外（邮件、支付）。`GET` 和 `HEAD` 必须是 `read`。 |
| `approval` | `never` `always` | `read` 为 `never`，其余为 `always` | 每次调用是否要用户确认。见[表单与确认](forms-and-approvals.md)。 |
| `role` | `identity` `search` `form` | 无 | 把它变成特殊操作；见[角色](#roles)。 |
| `surfaces` | `agent` `mcp` `cli` 组成的数组 | `read`：三个都有；写操作：`agent`、`cli`；角色操作：无 | 出现在哪些入口。CLI 也能看到 `mcp` 操作。`mcp` 上的写操作，只对能确认它的客户端执行。 |
| `confirmation` | 对象 | 由 `title` 和参数生成的卡片 | 确认卡；见[确认卡](#confirmation)。 |
| `form` | 操作名 | 无 | 一个 `role: form` 操作，为本操作提供表单；之后本操作的输入只来自这个表单。 |
| `resolve` | `{argument: {op, key?}}` | 无 | 让用户说出事物的名字，而不必给出 id：`op` 是列出候选项的读操作，`key` 是 id 字段（默认 `id`）。见[把名字变成 id](catalog.md#turn-names-into-ids)。 |
| `next` | 对象 | 无 | 成功后、模型开口前的一次后续调用；见[链式调用](#chains)。 |
| `open` | 以单个 `/` 开头的路径模板 | 无 | 成功后要展示的页面，用参数和结果填充。以 `rungent.ui.open` 事件发出。 |
| `redact` | 字段名数组 | `[]` | 在模型或 MCP 客户端看到之前，从结果和参数中（任意层级）删除的字段。类似密钥的键（`password`、`token`、`api_key`、`authorization`、`cookie` 等）总会被删除。 |
| `repeatable` | 布尔值 | `false` | 允许一次运行中有相同的成功写操作。为 `false` 时，第二次相同的写操作直接用第一次的结果作答（`deduplicated: true`）。 |
| `timeoutSeconds` | 数字，> 0 且 ≤ 3600 | `120`；`role: search` 为 `2` | rungent 等你的 API 多久。搜索操作最多只能设 `10`。 |
| `cli` | `{command, args?}` | `name` 把 `_` 换成 `-`，没有位置参数 | CLI 里的写法：`command` 是用空格分隔的小写单词（`vm stop`），`args` 是按顺序作为位置参数的输入。 |

## 确认卡

| 键 | 类型 | 含义 |
|---|---|---|
| `title` | 字符串，1–200，必填 | 卡片标题。 |
| `target` | 字符串，1–200 | 被操作的对象，醒目显示。默认：查到的名字。 |
| `fields` | `[{key, label, values?}]` | 在卡片上以 `label: value` 列出的参数；`values` 把原始值映射成文字。 |
| `lookup` | `{path, labelPath}` | 出卡片前以用户身份发起的一次 `GET`；其响应中 `labelPath`（点分路径）处的值成为 `{resource_name}`。 |
| `risk` | `low` `medium` `high` | 显示在卡片上。 |
| `costHint` | 字符串，1–200 | 一行成本说明。 |

`title`、`target` 和 `lookup.path` 都是模板：`{argument}` 取某个输入的值，`{resource_name}` 取查询到的名字。`lookup.path` 必须由目录中的某个 `GET` 操作提供；查询失败时，调用会在出卡片之前停止。

## 链式调用

```json
"next": { "op": "commit_vm_draft", "arguments": { "draft_id": "id", "revision": "revision" }, "when": { "status": "prepared" } }
```

| 键 | 类型 | 含义 |
|---|---|---|
| `op` | 操作名，必填 | 接下来调用的操作；不能是角色操作。 |
| `arguments` | `{argument: path}` | 下一次调用的每个参数，取自本次调用结果的点分路径。缺值时链条停止。 |
| `argumentsFrom` | 路径 | 结果中的一个路径，其对象整个作为下一次调用的输入。`arguments` 可以在此基础上添加，但不能覆盖。 |
| `when` | `{path: value}` | 结果中的每个路径都必须等于对应的值，否则链条停止。 |

下一次调用会自己走一遍解析、确认卡和确认。

## 角色

| 角色 | 必须满足的形态 | rungent 用它做什么 |
|---|---|---|
| `identity` | `GET`，没有输入。每个目录恰好一个。 | 得知一个凭据属于谁：`{subject, tenant?, name?, locale?, scopes?}`。见[以用户身份调用](acting-as-the-user.md#who-the-user-is)。 |
| `search` | `GET`，必填查询参数 `q`，可选 `limit`，`timeoutSeconds` ≤ 10。 | ⌘K、`search` 工具和 MCP 搜索的一个来源：`{hits: [...]}`。见[搜索与知识](search.md#add-a-search-source)。 |
| `form` | `POST`，`approval: never`。 | 为一个操作的参数返回通用表单：`{prompt, questions}`。见[表单与确认](forms-and-approvals.md#declare-the-form)。 |

角色操作都是读操作，不出现在任何入口，也从不提供给模型。

## 校验规则

`rungent check` 一次报告所有问题，用 `METHOD /path` 或操作名标明位置。出现以下情况，目录就不通过：

- 文档不是 OpenAPI 3.1；
- `x-rungent` 对象有未知的键、缺少 `name`，或某个值的类型或长度不对；
- 两个操作的 `name` 相同；
- `role: identity` 操作不是恰好一个；
- `GET` 或 `HEAD` 操作，或角色操作，effect 不是 `read`；
- 角色操作列了 surfaces，或不符合上面它所属角色的形态；
- 请求体不是 `application/json`，有必填的 header 或 cookie 参数，或 `$ref` 指向 `#/components/schemas` 之外或指向不存在的东西；
- 同一个输入名出现两次（比如既是路径参数又是请求体字段）；
- `form` 指向的操作不是 `role: form`；
- `resolve` 的键不是输入，或它的 `op` 不是无角色的读操作；
- `next.op` 不是目录中的操作，或是角色操作；
- `cli.args` 中有一项不是输入；
- 确认卡中除 `{resource_name}` 外的占位符不是输入；
- 确认卡有 `lookup`，但 `title` 里没有 `{resource_name}`；
- `lookup.path` 不由目录中的 `GET` 操作提供；
- `open` 或 `lookup.path` 不是以单个 `/` 开头。

每个操作得到的输入 schema 见[目录](catalog.md#the-input-schema)。
