rungent参考
x-rungent
x-rungent OpenAPI 扩展的每个键:类型、默认值和作用,以及目录必须通过的校验规则。
OpenAPI 3.1 文档里的一个操作,带上 x-rungent 对象就进入目录。没有它的操作对 rungent 不可见;对象里出现未知的键,校验就会失败。这些键合起来是什么意思,见目录。
"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 |
每次调用是否要用户确认。见表单与确认。 |
role |
identity search form |
无 | 把它变成特殊操作;见角色。 |
surfaces |
agent mcp cli 组成的数组 |
read:三个都有;写操作:agent、cli;角色操作:无 |
出现在哪些入口。CLI 也能看到 mcp 操作。mcp 上的写操作,只对能确认它的客户端执行。 |
confirmation |
对象 | 由 title 和参数生成的卡片 |
确认卡;见确认卡。 |
form |
操作名 | 无 | 一个 role: form 操作,为本操作提供表单;之后本操作的输入只来自这个表单。 |
resolve |
{argument: {op, key?}} |
无 | 让用户说出事物的名字,而不必给出 id:op 是列出候选项的读操作,key 是 id 字段(默认 id)。见把名字变成 id。 |
next |
对象 | 无 | 成功后、模型开口前的一次后续调用;见链式调用。 |
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 操作提供;查询失败时,调用会在出卡片之前停止。
链式调用#
"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?}。见以用户身份调用。 |
search |
GET,必填查询参数 q,可选 limit,timeoutSeconds ≤ 10。 |
⌘K、search 工具和 MCP 搜索的一个来源:{hits: [...]}。见搜索与知识。 |
form |
POST,approval: never。 |
为一个操作的参数返回通用表单:{prompt, questions}。见表单与确认。 |
角色操作都是读操作,不出现在任何入口,也从不提供给模型。
校验规则#
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 见目录。
供 Agent 读取: x-rungent.md编辑此页