# 工作原理

rungent 由哪些部分组成、运行时跑在哪里、一次请求经过哪些步骤、界面说的是什么协议，以及这些文档使用的术语。

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

## 你要安装什么

rungent 是一个运行时，用 TypeScript 写成，只依赖 Web 标准 API。它以一个 npm 包 `rungent` 发布，入口按你的技术栈需要导入：

| 导入 | 是什么 |
|---|---|
| `rungent` | 运行时：`createRungent` 和各种存储 |
| `rungent/react` | 面板、⌘K 命令面板、确认卡、表单、模型设置 |
| `rungent/client` | HTTP API 的类型化客户端，把事件归约成一个对话线程 |
| `rungent/delegation` | 签名密钥，以及你的 API 要做的断言检查 |
| `rungent/knowledge` | 把你的文档变成可引用的搜索来源 |
| `rungent/sql/postgres`、`/sql/sqlite`、`/sql/d1` | 存储和知识用的数据库驱动 |
| `rungent/node` | 适配 Node `(req, res)` 的 `nodeHandler`，以及 `rungent serve` 背后的服务 |
| `rungent/cli` | 作为库的 CLI，用来做品牌 CLI |
| `rungent/protocol`、`/catalog`、`/search`、`/documents` | 契约的类型和辅助函数，供你自己的工具使用 |

这个包只有一个命令 `rungent`：它是每个 rungent 宿主的 CLI，也是编写工具（`check`、`keys`、`brand`），还有 `rungent serve`。另有两样不在 npm 上：运行 `rungent serve` 的 Docker 镜像 `ghcr.io/rungent/rungent-server`，以及 PyPI 上的 Python kit `rungent`（导入名 `rungent`）。

## 运行时跑在哪里

<ol class="planes">
<li><b>内嵌</b><ul class="main"><li>你的 JavaScript API<small>Hono、Express、Workers、Node</small></li><li>rungent 在同一进程<small>一个 fetch 处理函数</small></li></ul></li>
<li><b>在你的 API 旁边</b><ul class="bar"><li>你的 API<small>Python、Go、Java 等</small></li><li>旁边运行 rungent serve<small>由代理转发 /rungent 和 /mcp</small></li></ul></li>
<li><b>两种方式都</b><ul><li>同源<small>用户的 Cookie 直接可用</small></li><li>同一份契约<small>输入 OpenAPI，输出断言</small></li></ul></li>
</ol>

两种形态都在你自己的域名下提供同样的路径：助手用的 `/rungent/v0/*`、`/mcp`、`/skill.md`、`/llms.txt` 和 `/.well-known/rungent-keys.json`。你的 Web 应用以同源请求访问它们，所以用户现有的登录会话就是凭据。[JavaScript](javascript.md) 内嵌 rungent；[Python 与其他技术栈](python.md)在你的 API 旁边运行它。

## 一次请求，一步一步

用户发出一条消息后，rungent 依次执行这些步骤。每一步都写在代码里，而不是提示词里。

<ol class="steps">
<li><b>目录</b>rungent 用用户的凭据读取你的 OpenAPI，只保留带 x-rungent 且该用户可见的操作。</li>
<li><b>预检索</b>如果你把文档交给了 rungent，它先按用户的话检索一遍。</li>
<li><b>路由</b>创建或修改的请求直接送到对应的操作。</li>
<li><b>表单</b>操作的表单打开并预填；在你的应用里，就是页面自己的表单。</li>
<li><b>解析</b>用户写的名称（「train-01」）通过你的列表操作换成 ID。</li>
<li><b>确认</b>写操作显示一张写明对象和变更的卡片；确认绑定到这组确切的参数。</li>
<li class="host"><b>调用</b>rungent 带着用户凭据和签名断言调用你的 API，由你授权。</li>
<li><b>流式</b>文字、工具活动和结果以事件流回界面，断线后可以续上。</li>
</ol>

提问走短路径：Agent 用你的读操作和搜索查找信息，然后带引用作答。除非你另行设置，读操作从不需要确认。

## 以用户身份调用

rungent 在你的产品里没有账号。每次调用都带着用户自己的凭据，所以你的权限检查原样生效；还带着一个 `Rungent-Assertion`：一份签名令牌，写明用户、操作、确切的请求和确认。你的 API 用 rungent 的公钥校验它。详见[以用户身份调用](acting-as-the-user.md)。

## 协议

助手通过 HTTP 和 server-sent events 说 [AG-UI](https://docs.ag-ui.com)。rungent 在上面加了一层小小的约定：每个事件带一个序号，客户端重连时正好拿到错过的那些；另有四种暂停，每种都由用户来答复：

| 暂停 | 何时 | 用户如何答复 |
|---|---|---|
| 确认 | 写操作之前 | 确认或拒绝 |
| 表单 | 带表单的操作之前 | 操作的完整参数 |
| 提问 | Agent 问是哪个对象或哪个动作 | 一个选项 |
| 任务 | 你的 API 稍后执行这项工作 | 无需答复；由你的 API 回报结果 |

任何 AG-UI 客户端都能驱动 rungent，React 面板只是其中之一。见 [HTTP API](http-api.md#events)。

## rungent 有什么不同

Agent 框架（LangGraph、Mastra、Vercel AI SDK）给你一个循环，工具、身份和界面都留给你自己做。OpenAPI 生成器（Stainless、Speakeasy）给开发者生成 SDK 和 MCP 服务，用开发者自己的密钥调用你的 API。rungent 从你已有的 API 出发，在你的产品里为当前登录用户运行 Agent，用你的表单，并在代码里强制确认。它也能和它们配合：一个耗时很长的 LangGraph 工作流，可以做成一个以[延后任务](http-api.md#deferred-tasks)作答的操作。

## 这些文档使用的术语

| 词 | 含义 |
|---|---|
| 宿主 | 你的产品，即 rungent 调用其 API 的那个服务 |
| 目录 | 你的 OpenAPI 中带 `x-rungent` 的操作，按某个用户可见的范围 |
| 操作 | 目录中的一个 HTTP 端点；对 Agent、MCP 和 CLI 来说是一个工具 |
| 效果 | 操作做什么：读取、创建、修改、删除，或对外动作 |
| 写操作 | 效果不是 `read` 的任何操作 |
| 入口 | 操作出现的地方：助手、MCP、CLI |
| 身份 | 说明某个凭据属于谁的那一个操作 |
| 断言 | rungent 代表用户发出的每次调用上的签名令牌 |
| 表单 | 操作运行前向用户收集的输入 |
| 路由 | 把修改请求送到对应表单的那一步 |
| 中断 | 一次运行中等待用户的暂停：确认、表单、提问或任务 |
| 面板 | 你页面旁的助手面板，来自 `rungent/react` |
