rungent v0.5.1
EN中文

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编辑此页