# 概览

rungent 是一个开源框架，让产品从已有的 HTTP API 出发变成 Agent 原生。一份标注好的目录，就能给出产品内 Agent、MCP、CLI、skill、给 Agent 读的文档、全局搜索和带引用的回答，而且都以当前登录用户的身份工作。

## 痛点

一个产品想让 Agent 用起来，最后往往要把同一件事做七遍：

| 入口 | 谁在用 | 通常怎么做 |
|---|---|---|
| 产品内的 Agent | 你的用户 | 一个聊天组件，自带一套工具清单 |
| MCP 服务 | Claude Code、Cursor、Codex | 第二套工具清单，常常挂在服务账号上 |
| CLI | 开发者和他们的 Agent | API 的第三份拷贝 |
| Skill | 编码 Agent | 手写的说明文件，写完就开始过时 |
| 给 Agent 读的文档 | 任何 Agent | `llms.txt`，如果有人记得维护 |
| 全局搜索 | 所有人 | 另建一套资源索引 |
| 基于文档的回答（RAG） | 所有人 | 另一条管线，另配一个模型 |

每一份拷贝都会和 API 渐行渐远；每一份对权限都有自己的理解，往往比用户本人的权限还大。写操作绕过了页面上的表单，于是 Agent 问的字段和页面不一样；同一个请求，这次弹表单，下次变成一问一答。

## rungent 是什么

**rungent 把一份目录（你的 OpenAPI，在允许 Agent 使用的操作上加 `x-rungent`）变成全部七种入口，并且每一种都以当前登录用户的身份运行。**

每个入口都遵守三条规则：

- **一份目录。** Agent、MCP 工具、CLI 命令、skill 和搜索都从你的操作生成，所以说法永远一致。
- **一个身份。** rungent 用用户自己的凭据加一份签名断言调用你的 API。它没有自己的权限，你的权限说了算。
- **一条变更路径。** 想改点什么，就打开你页面自己的表单，再弹一张绑定了确切参数的确认卡，然后才调用。不会变成聊天式盘问。

rungent 是一个 npm 包 `rungent`，外加一个给非 JavaScript 技术栈用的服务镜像和一个 Python kit。它能跑在 Node、Bun、Deno 和 Cloudflare Workers 上。

## 一句话开始

发给你的编码 Agent：

```text
从 https://rungent.acahti.dev/skills/rungent/SKILL.md 安装 rungent skill，然后用它把这个产品接入 rungent。
```

这个 skill 教会 Agent 完整的接入：标注操作、加身份操作、校验 rungent 的断言、挂载 rungent 和面板、把文档加为知识、再测试一遍。你只需要审一个 PR。想自己动手的话，[快速开始](quickstart.md)展示了它写了什么。

上线之后，你的产品会提供自己的 `skill.md`，你的用户把这句话发给*他们的* Agent：

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

## 两侧，一份目录

rungent 面向两类人，目录是他们相遇的地方。

*rungent：构建侧写一份目录，使用侧从它得到每一种入口*

- **构建侧**是你和你的编码 Agent。你们读 [rungent skill](quickstart.md) 和这些文档，写的只有：标注、一个身份操作、一个中间件、一个 React 组件。
- **使用侧**是你的用户和他们的 Agent。他们不读这些文档，他们看到的是你的产品：页面旁的助手、⌘K，以及产品提供的 `skill.md`、`/mcp` 和 CLI。他们能做的一切都在你的目录里，并且只限于他们有权做的。

## 架构

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

rungent 位于各个入口和你的 API 之间。它用每个用户的凭据读取目录，运行 Agent 循环，让每次变更都走表单和确认，以 AG-UI 事件流式传输对话，并对你的资源和文档做联邦搜索。决定权留在你的产品里：身份、权限、表单和产品事实。详见[工作原理](how-it-works.md)。

## 概念

| 词 | 含义 | 页面 |
|---|---|---|
| 目录 | 标了 `x-rungent` 的 OpenAPI 操作，按某个用户可见的范围 | [目录](catalog.md) |
| 身份 | 这是谁的请求；每次调用都以这个用户的身份进行 | [以用户身份调用](acting-as-the-user.md) |
| 变更路径 | 路由 → 你的表单 → 确认 → 调用 | [表单与确认](forms-and-approvals.md) |
| 知识 | 你的文档和资源，可搜索、可引用 | [搜索与知识](search.md) |
| 入口 | 面板、⌘K、MCP、CLI、`skill.md`、`llms.txt` | [入口](surfaces.md) |

## 接下来

<ul class="tiles">
<li><a href="quickstart.md"><b>快速开始</b><span>一句话接入，以及它在一个 JavaScript API 里写了什么。</span></a></li>
<li><a href="how-it-works.md"><b>工作原理</b><span>运行时、一次请求的每一步，以及协议。</span></a></li>
<li><a href="playground.md"><b>演练场</b><span>一个沙箱云控制台，由本站自己的 rungent 驱动。</span></a></li>
<li><a href="x-rungent.md"><b>参考</b><span>每个 x-rungent 键、HTTP API 和 CLI。</span></a></li>
</ul>

> **版本 0。** 协议是 `rungent/0`，HTTP API 在 `/rungent/v0` 下；小版本仍可能有破坏性变更，[更新日志](changelog.md)列出了每一处。
