# 入口

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

*rungent 位于人们使用的入口与产品 API 之间*

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

每个入口都[以用户身份](acting-as-the-user.md)调用你的 API，也只显示这个用户目录里有的东西。本页讲最终用户这一侧；面板在开发者那一侧怎么接，见 [JavaScript](javascript.md#add-the-dock)。

## 哪些操作出现在哪里

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

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

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

## 面板

![在云控制台旁打开、给出建议问题的面板](/images/welcome.png "空对话里显示产品自己的建议问题。控制台往旁边让出位置，没有任何内容被遮挡。")

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

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

## ⌘K 搜索

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

## 给编码 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 指南。

```bash
# 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
```

```jsonc
// 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 变了。部署了多个副本时，要把一个会话路由到同一个副本（[部署](deploy.md#run-several-replicas)）。 |
| OAuth 登录一直不开始 | 把 `/.well-known/oauth-protected-resource/mcp` 和 `/mcp` 一起路由到 rungent。 |

## 带你名字的 CLI

```bash
acme login https://console.example.com
acme vm stop gpu-train-01
```

```text
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 就是你的命令：

```bash
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 参考](cli-reference.md)。

`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](https://llmstxt.org) 格式索引。两者都按请求者自己的目录生成。不带凭据请求时，它们列出你的 OpenAPI 对匿名用户可见的内容；如果你的 API 要求登录，就只写如何连接。

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

```ts
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 说一句话：

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

## 接下来

[JavaScript](javascript.md) 讲如何在你的应用里挂载 rungent 和面板。
