# JavaScript

把 rungent 嵌入 JavaScript API，再把面板放进你的 Web 应用。本页讲 createRungent 的参数、如何挂载到 Hono、Express 和 Cloudflare Workers、该用哪种存储，以及面板中真正要关心的几个 prop。

嵌入式的 rungent 就是你应用里的一个 Web 标准 `fetch` 处理函数。不管用什么框架，接入都是这样：

```ts
import { createRungent } from 'rungent';

const rungent = createRungent({ url, host, signingKey, secret, store, models });

// 把这些路径交给 rungent.fetch(request)：
// /rungent/v0/*  /mcp  /skill.md  /llms.txt  /.well-known/rungent-keys.json
```

`createRungent` 返回 `{ fetch(request, ctx?), migrate(), close() }`。在第一个请求到来之前它不做任何 I/O；第一个请求会创建 rungent 的表。`migrate()` 可以提前建表，`close()` 会等正在进行的运行结束。rungent 不带任何框架适配器：下面这几行就是全部。[快速开始](quickstart.md)完整走了一遍 Hono 宿主。

## createRungent 的参数

| 选项 | 是什么 |
|---|---|
| `url` | **必填。** rungent 对外提供服务的公开 URL，如 `https://console.example.com`。作为 `iss` 签进每一份断言。 |
| `host.origin` | **必填。** 你产品的公开 origin：断言的 `aud`，也是 `htu` 的开头。 |
| `host.openapi` | **必填。** 你的 OpenAPI 3.1 文档的路径或 URL，用每个用户的凭据获取。 |
| `host.fetch` | 你应用自己的 `fetch`（Hono 的 `app.fetch`），这样 rungent 在进程内调用你的 API。默认是全局 `fetch`。 |
| `host.baseUrl` | rungent 通过网络访问你 API 的地址（`http://127.0.0.1:3000`）。默认是 `host.origin`。 |
| `signingKey` | **必填。** rungent 的 Ed25519 密钥，由 `importSigningKey` 导入。见[密钥与轮换](acting-as-the-user.md#keys-and-rotation)。 |
| `secret` | **必填。** 32 字节或更长，用来加密管理员保存的模型 API key。传一个列表就能轮换：第一个用于加密，每一个都能解密。 |
| `store` | **必填。** 对话、确认和设置存放的地方。见[选择存储](#choose-a-store)。 |
| `models` | **必填。** `{ chain }`，默认的模型链。见[选择模型](deploy.md#choose-models)。 |
| `name` | 助手的名字。默认 `Assistant`。 |
| `instructions` | 加进系统提示词的产品事实：一个字符串，或一个以用户身份为参数的函数。 |
| `product` | `{ name, summary? }`，未登录的调用方读不到你的 OpenAPI 时，用于 `/skill.md` 和 `/llms.txt`。 |
| `basePath` | 把所有路由放到一个前缀下。见[在前缀下提供 rungent](#serve-rungent-under-a-prefix)。 |
| `sources` | 更多搜索来源，比如你的文档。见[搜索与知识](search.md#index-docs-from-code)。 |
| `hostKeys` | 你的 API 签 `Rungent-Host-Assertion` 所用的公钥。见 [HTTP API](http-api.md#host-assertions)。 |
| `skill` | `{ name?, guide?, cli? }`，用于 `/skill.md`。见[入口](surfaces.md#skill-md-and-llms-txt)。 |
| `limits` | `{ maxSteps, contextTokens, runTimeoutSeconds }`。默认 16、128 000 和 600。 |
| `mcp` | `{ authorizationServers?, instructions? }`。见[入口](surfaces.md#sign-in-with-oauth)。 |

## 挂载到 Hono

把应用的 `fetch` 交给 rungent，再挂上这些路径。rungent 的调用不会离开进程，每一个都以发往 `host.origin` 的请求到达你的路由。

```ts
const rungent = createRungent({
  url: 'https://console.example.com',
  host: { origin: 'https://console.example.com', openapi: '/api/openapi.json', fetch: app.fetch },
  // signingKey、secret、store、models …
});

for (const path of ['/rungent/v0/*', '/mcp', '/skill.md', '/llms.txt', '/.well-known/rungent-keys.json']) {
  app.all(path, (c) => rungent.fetch(c.req.raw));
}
```

浏览器标记为 `Sec-Fetch-Site: cross-site` 的修改类请求会被 rungent 拒绝；在 `/rungent/v0` 下，不是 `application/json` 的请求体也会被拒绝。这样别的网站就无法借用户的 cookie 会话操作 rungent。

## 挂载到 Express

`rungent/node` 里的 `nodeHandler(rungent)` 把 rungent 适配成 Node 的 `(req, res)`。要把它注册在所有 body parser 之前：rungent 自己读取原始请求体。

```ts
import express from 'express';
import { createRungent } from 'rungent';
import { nodeHandler } from 'rungent/node';

const app = express();
const rungent = createRungent({
  url: 'https://console.example.com',
  host: { origin: 'https://console.example.com', baseUrl: 'http://127.0.0.1:3000', openapi: '/api/openapi.json' },
  // signingKey、secret、store、models …
});

app.all(['/rungent/v0/*splat', '/mcp', '/skill.md', '/llms.txt', '/.well-known/rungent-keys.json'], nodeHandler(rungent));
app.use(express.json({ verify: (req, _res, buf) => { (req as { rawBody?: Buffer }).rawBody = buf; } }));
// … 你的路由
app.listen(3000);
```

这些路径模式是 Express 5 的语法。Express 没有进程内的 `fetch`，所以 rungent 通过回环地址 `host.baseUrl` 调用你的 API。校验断言时，要用公开 origin 重建 URL（`https://console.example.com${req.originalUrl}`），并对 `rawBody`（收到的原始字节）求哈希。关闭时，`await rungent.close()` 让正在进行的运行跑完。

## 挂载到 Cloudflare Workers

绑定随每个请求一起到来，所以在每个 isolate 的第一个请求上构建一次 rungent，并传入执行上下文：这样响应关闭后，运行还能借 `waitUntil` 继续。

```ts
import { createRungent, SqlStore, type Rungent } from 'rungent';
import { importSigningKey } from 'rungent/delegation';
import { d1Driver } from 'rungent/sql/d1';

let rungent: Promise<Rungent> | undefined;

const rungentFor = (env: Env) =>
  (rungent ??= importSigningKey(JSON.parse(env.RUNGENT_SIGNING_KEY)).then((signingKey) =>
    createRungent({
      url: 'https://console.example.com',
      host: { origin: 'https://console.example.com', openapi: '/api/openapi.json', fetch: (request) => app.fetch(request, env) },
      signingKey,
      secret: env.RUNGENT_SECRET,
      store: new SqlStore(d1Driver(env.DB)),
      models: { chain: [{ id: 'main', provider: 'openai', model: 'gpt-4.1-mini', apiKey: env.OPENAI_API_KEY }] },
    }),
  ));

for (const path of ['/rungent/v0/*', '/mcp', '/skill.md', '/llms.txt', '/.well-known/rungent-keys.json']) {
  app.all(path, async (c) => (await rungentFor(c.env)).fetch(c.req.raw, c.executionCtx));
}
```

把 `RUNGENT_SIGNING_KEY` 和 `RUNGENT_SECRET` 存为 Worker secret（`wrangler secret put`）。`waitUntil` 仍然受请求时长限制，而且每个 isolate 都有自己的 MCP 会话。生产环境里，把每个用户路由到一个 Durable Object，由它用同样的方式构建 rungent 实例并调用 `rungent.fetch(request, this.ctx)`：运行在流式输出时，这个对象会一直运行，同一用户的请求也都汇集到一处。

## 选择存储

| 存储 | 适用于 |
|---|---|
| `new SqlStore(postgresDriver(url))`，驱动来自 `rungent/sql/postgres` | 生产环境，以及多个进程共用一个数据库。需要 `postgres` 包。 |
| `new SqlStore(sqliteDriver('rungent.sqlite'))`，来自 `rungent/sql/sqlite` | Node 上的单个进程，使用内置的 `node:sqlite`。 |
| `new SqlStore(d1Driver(env.DB))`，来自 `rungent/sql/d1` | Cloudflare Workers。在一个地方运行 `migrate()`，比如部署步骤里。 |
| `new MemoryStore()` | 开发和测试：重启后什么都不记得。 |

`SqlStore` 和 `MemoryStore` 来自 `rungent`。rungent 使用自己的 `rungent_*` 表，在第一个请求时创建或升级它们；请给它单独的数据库或 schema。`postgresDriver` 也可以接收一个现成的 `postgres` 客户端。

开发时，`rungent/delegation` 里的 `generateKeyPair('dev')` 在内存里生成一个密钥（`signingKey: (await generateKeyPair('dev')).signing`）。生产环境用 `importSigningKey(JSON.parse(process.env.RUNGENT_SIGNING_KEY!))` 加载生成好的私钥 JWK。

## 在前缀下提供 rungent

要在 `/assistant` 下提供 rungent，设置 `basePath: '/assistant'` 和 `url: 'https://console.example.com/assistant'`。所有路由都移到这个前缀下，一句 `app.all('/assistant/*', …)` 就能挂载；Web 客户端也要带上前缀：`createClient({ baseUrl: '/assistant' })`。

## 加上面板

面板只挂载一次：放在 Web 应用的根布局里，包住页面渲染的区域。这样用户在页面之间切换时，面板和其中的对话都保持不动。

```tsx
// web/RootLayout.tsx
import { createClient } from 'rungent/client';
import { RungentDock, RungentProvider, SearchPalette } from 'rungent/react';
import 'rungent/react/styles.css';

const client = createClient();

export function RootLayout({ children }: { children: React.ReactNode }) {
  const navigate = useNavigate();
  return (
    <RungentProvider
      client={client}
      locale={i18n.language}
      onOpen={navigate}
      forms={{ create_vm: CreateVm }}
      suggestions={() => ['Which servers are running?', 'Create a server']}
      context={() => [{ description: 'The page the user is on', value: location.pathname }]}
    >
      <Header />
      <RungentDock>{children}</RungentDock>
      <SearchPalette />
    </RungentProvider>
  );
}
```

这些组件需要 React 19。`createClient()` 与页面自身的 origin 通信，靠浏览器的 cookie 识别用户。如果你的应用持有访问令牌，就在每个请求上带上它：``createClient({ headers: async () => ({ Authorization: `Bearer ${await getToken()}` }) })``；`baseUrl` 可以指向另一个 origin 或一个前缀。

### 要关心的 prop

| `RungentProvider` prop | 是什么 |
|---|---|
| `client` | 上面创建的客户端。 |
| `forms` | 你页面自己的表单组件，按操作名对应。见[表单与确认](forms-and-approvals.md#show-your-page-s-own-form)。 |
| `onOpen` | `(path) => void`：你的路由器，用于助手打开的页面和回答里的链接。只接受同源路径；不传时，rungent 直接设置 `window.location`。 |
| `locale` | rungent 自身文案的语言：`zh-CN` 有自己的文案，其他任何语言标签都显示英文。按你应用的语言设置来选。`strings` 可以按 key 覆盖任意文案（`{ assistant: 'Copilot' }`）。 |
| `theme` | `'light'`、`'dark'` 或 `'system'`（默认）。 |
| `context` | `() => {description, value}[]`，每次运行开始时调用：告诉助手用户正在看什么，这样「停掉这台」指的就是屏幕上那台服务器。 |
| `suggestions` | `() => string[]`：空对话里给出的建议问题，比如按页面不同而不同。 |
| `upload` | `(file) => Promise<{url, mimeType, name}>`：保存用户附加的文件。不传时，输入框不提供附件。 |

`RungentDock` 接受 `open`/`onOpenChange` 来受控，`onLayoutChange`（收到 `'closed'`、`'panel'` 或 `'expanded'`，比如用来折叠你的导航），以及在你的产品有自己的按钮时用 `launcher={false}`。`useDock().ask(text)` 打开面板，开始一段以这条消息开头的新对话。页面有固定顶栏时，把 `--rungent-dock-top` 设为顶栏高度。在布局不归你管的页面上，渲染不带子元素的 `<RungentDock />`：面板会固定在窗口边缘。

### ⌘K 与样式

`SearchPalette` 按 ⌘K 打开；手机没有 ⌘K，可以在搜索按钮上调用 `useSearchPalette().open()`。所有颜色和尺寸都是 `.rungent-root` 上的 CSS 变量：

```css
.rungent-root {
  --rungent-accent: #0f766e;
  --rungent-accent-fg: #ffffff;
  --rungent-radius: 6px;
  --rungent-font: Inter, system-ui, sans-serif;
}
.rungent-root[data-rungent-theme='dark'] { --rungent-accent: #2dd4bf; }
```

组件的样式会自己设好所依赖的属性，所以 Tailwind preflight 这类 CSS reset 不会改变它们。如果要自己做对话界面，`useThread`、`useThreads`、`useSearch`、`useCatalog`、`RungentThread`、`ApprovalCard` 和 `RungentForm` 也都已导出；它们背后的事件见 [HTTP API](http-api.md#events)。

## 接下来

- [部署](deploy.md#choose-models)：模型链，以及修改它的管理页面。
- [测试](testing.md)：针对你的部署检查每一个入口。
