rungent v0.5.1
EN中文

rungent核心概念

入口

你的用户和他们的 Agent 通过 rungent 进入你产品的地方。面板、⌘K、MCP、带你品牌的 CLI、skill.md 和 llms.txt 都来自同一份目录,都以用户身份操作,每次写操作前都会先问。

人和 Agent 在这里工作产品内助手页面旁的助手面板⌘K 搜索资源与文档MCP 客户端Claude Code、Cursor 等CLI你的品牌命令skill.md · llms.txt给任何 Agentrungent一份目录你的 OpenAPI,按用户可见路由 → 表单 → 确认每次变更同一条路径Agent 循环模型链、重试、上限会话与流式AG-UI 事件,可续传搜索与知识联邦检索,带引用你的产品HTTP APIOpenAPI 3.1 + x-rungent身份当前登录的是谁权限由你的规则决定页面表单与业务页面同一张表单文档回答引用它们用户自己的会话用户凭据+ 签名断言结果,你的报错每次调用都以当前登录用户的身份执行,rungent 没有自己的权限。人和 Agent 在这里工作产品内助手页面旁的助手面板⌘K 搜索资源与文档MCP 客户端Claude Code、Cursor 等CLI你的品牌命令skill.md · llms.txt给任何 Agent用户自己的会话rungent一份目录你的 OpenAPI,按用户可见路由 → 表单 → 确认每次变更同一条路径Agent 循环模型链、重试、上限会话与流式AG-UI 事件,可续传搜索与知识联邦检索,带引用用户凭据+ 签名断言你的产品HTTP APIOpenAPI 3.1 + x-rungent身份当前登录的是谁权限由你的规则决定页面表单与业务页面同一张表单文档回答引用它们

每次调用都以当前登录用户的身份执行,rungent 没有自己的权限。

入口 谁在用 提供什么 写操作如何确认
面板 你的用户,在页面旁边 agent 上的操作、搜索、表单 一张确认卡
⌘K 搜索面板 你的用户 覆盖所有来源的搜索 无需确认
MCP(/mcp) Claude Code、Cursor、Codex 及其他 Agent mcp 上的操作、搜索 MCP elicitation
CLI 在终端里的人和 Agent cli 或 mcp 上的操作、搜索 [y/N],或 --yes
skill.md、llms.txt 正在摸索如何接入的 Agent 如何连接,以及有哪些操作 不发起调用

每个入口都以用户身份调用你的 API,也只显示这个用户目录里有的东西。本页讲最终用户这一侧;面板在开发者那一侧怎么接,见 JavaScript。

哪些操作出现在哪里#

操作的 surfaces 列出提供它的入口。读操作默认三个入口都有;写操作默认是 agent 和 cli。所以 MCP 一开始是只读的,写操作经由 CLI 到达终端,而 CLI 每次都会先问。要改变它,就设置这个列表:

{ "name": "stop_vm", "effect": "update", "surfaces": ["agent", "mcp", "cli"] }

有角色的操作不出现在任何入口;搜索则通过内置的 search 工具到达每个入口。

面板#

在云控制台旁打开、给出建议问题的面板
空对话里显示产品自己的建议问题。控制台往旁边让出位置,没有任何内容被遮挡。

面板在页面旁边打开,从页面那里分走空间,而不是盖在页面上,所以助手刚改过的服务器列表始终看得见。⌘J(Ctrl+J)打开或关闭它。用户可以拖动它的边缘,在 360 到 640 像素之间调整宽度;在手机上它占满屏幕,展开后会在回答旁边列出历史对话。

空对话会显示你提供的建议问题。文字带着光标流式出现,查询显示为简短的行(「Looked up 2 things」),表单、确认和提问都出现在对话里。一个圆环显示上下文用了多少。用户正在看的内容随每条消息一起发送,open 指定的页面通过你的路由打开。

⌘K(Ctrl+K)打开覆盖所有搜索来源的搜索面板,按类别分组。方向键移动,回车打开结果,最后一行把搜索词作为问题交给面板。

给编码 Agent 用的 MCP#

每个 rungent 宿主都在 <host>/mcp 上以 streamable HTTP 提供 MCP。客户端用一个你的 API 认作用户本人的 token 登录(个人访问令牌、API key 或 OAuth access token),然后得到 mcp 上每个操作对应的一个工具,外加 search。rungent 在每次调用时转发这个 token,从不保存它。每个工具都带有根据效果生成的提示(readOnlyHint、destructiveHint、idempotentHint);除非你设置了 mcp.instructions,客户端收到的指令就是你的 skill 指南。

# Claude Code
claude mcp add --transport http console https://console.example.com/mcp \
  --header "Authorization: Bearer $CONSOLE_TOKEN"

# Codex
codex mcp add console --url https://console.example.com/mcp --bearer-token-env-var CONSOLE_TOKEN
// Cursor:.cursor/mcp.json
{ "mcpServers": { "console": { "url": "https://console.example.com/mcp",
  "headers": { "Authorization": "Bearer ${env:CONSOLE_TOKEN}" } } } }

其他客户端也是这三项设置:streamable HTTP、URL 和 Authorization 头。只支持 stdio 的客户端通过 mcp-remote 这类桥接工具接入。

给用户发 token 最简单的办法,是在产品里做一个页面,让他们为自己的 Agent 创建 token,和其他 API token 一样可以限定范围、可以吊销。

用 OAuth 登录#

支持 MCP 授权的客户端可以通过你的 OAuth 服务让用户登录,不用粘贴 token。用 mcp: { authorizationServers: ['https://auth.example.com'] } 指定它(用 rungent serve 时是 RUNGENT_MCP_AUTHORIZATION_SERVERS)。rungent 随后提供 /.well-known/oauth-protected-resource/mcp,对 /mcp 的请求如果没有有效 token,会返回 401,并带一个指向那里的 WWW-Authenticate 头。客户端完成登录后带着 access token 重试。token 由你的服务签发、由你的 API 检查;rungent 只负责转发。

MCP 出问题时#

你看到的 原因和处理
连接时 401 没有 token,或者你的身份操作拒绝了它。检查客户端启动的环境里是否设置了这个变量。
工具里缺少某个写操作 写操作只有列在 surfaces 里才会出现在 mcp 上,而且只对有权使用它的用户出现。
not_executed,“cannot ask for (elicitation)” 客户端无法显示确认。换一个能显示的客户端,或者用面板、CLI。
404 session_not_found 会话已经没了:空闲了 10 分钟、rungent 重启了,或者 token 变了。部署了多个副本时,要把一个会话路由到同一个副本(部署)。
OAuth 登录一直不开始 把 /.well-known/oauth-protected-resource/mcp 和 /mcp 一起路由到 rungent。

带你名字的 CLI#

acme login https://console.example.com
acme vm stop gpu-train-01
Stop server gpu-train-01? [y/N] y
{ "id": "vm-42", "name": "gpu-train-01", "status": "stopped" }

这个 CLI 没有为你的产品专门写的命令:它连到 <host>/mcp,列出已登录用户能用的操作,把每个操作变成一条命令。新增一个操作,下次运行时就多一条命令,不用重新发布。输出是 JSON,所以 Agent 写脚本调用它和人手敲一样方便;acme search "gpu" 搜索你的产品和文档。

rungent brand 会生成一个小 npm 包,它的 bin 就是你的命令:

npx rungent brand --name acme --host https://console.example.com -o acme-cli --npm-name @acme/cli
cd acme-cli && npm publish --access public

它读取 ACME_HOST 和 ACME_TOKEN(或者你用 --env-host 和 --env-token 指定的变量),自己保存登录信息,并依赖 rungent,所以 rungent 发新版本时,它只是一次普通的依赖更新。如果产品由客户自己部署,就不要传 --host。所有参数见 CLI 参考。

x-rungent.cli 决定命令的形状:{"command": "vm stop", "args": ["vm_id"]} 把 acme stop-vm --vm-id vm-42 变成 acme vm stop vm-42;再在 vm_id 上加 resolve,acme vm stop gpu-train-01 也能用。

skill.md 和 llms.txt#

rungent 提供 /skill.md,一个 Agent 加载后就能使用你产品的 skill(如何连接、安全规则、按领域列出的每个操作),以及 /llms.txt,即同样内容的 llms.txt 格式索引。两者都按请求者自己的目录生成。不带凭据请求时,它们列出你的 OpenAPI 对匿名用户可见的内容;如果你的 API 要求登录,就只写如何连接。

在 createRungent 里用 skill.cli 告诉 Agent 该装哪个 CLI:

createRungent({
  // ...
  skill: { cli: { command: 'acme', package: '@acme/cli' }, guide: '…a hand-written guide placed first…' },
});

install 可以代替 package,写一行自由格式的安装说明。用 rungent serve 时,设置 RUNGENT_CLI_COMMAND,再加上 RUNGENT_CLI_PACKAGE 或 RUNGENT_CLI_INSTALL。都不设时,文档里写的是 rungent 提供的 rungent。rungent docs 把同样的文档写成文件,放进你的文档站。

上线之后,用户只需要对他们的 Agent 说一句话:

安装 https://console.example.com/skill.md 上的 skill,用它帮我管理服务器。

接下来#

JavaScript 讲如何在你的应用里挂载 rungent 和面板。

供 Agent 读取: surfaces.md编辑此页