rungent核心概念
入口
你的用户和他们的 Agent 通过 rungent 进入你产品的地方。面板、⌘K、MCP、带你品牌的 CLI、skill.md 和 llms.txt 都来自同一份目录,都以用户身份操作,每次写操作前都会先问。
| 入口 | 谁在用 | 提供什么 | 写操作如何确认 |
|---|---|---|---|
| 面板 | 你的用户,在页面旁边 | 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 搜索#
⌘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编辑此页