rungent构建
JavaScript
把 rungent 嵌入 JavaScript API,再把面板放进你的 Web 应用。本页讲 createRungent 的参数、如何挂载到 Hono、Express 和 Cloudflare Workers、该用哪种存储,以及面板中真正要关心的几个 prop。
嵌入式的 rungent 就是你应用里的一个 Web 标准 fetch 处理函数。不管用什么框架,接入都是这样:
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 不带任何框架适配器:下面这几行就是全部。快速开始完整走了一遍 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 导入。见密钥与轮换。 |
secret |
必填。 32 字节或更长,用来加密管理员保存的模型 API key。传一个列表就能轮换:第一个用于加密,每一个都能解密。 |
store |
必填。 对话、确认和设置存放的地方。见选择存储。 |
models |
必填。 { chain },默认的模型链。见选择模型。 |
name |
助手的名字。默认 Assistant。 |
instructions |
加进系统提示词的产品事实:一个字符串,或一个以用户身份为参数的函数。 |
product |
{ name, summary? },未登录的调用方读不到你的 OpenAPI 时,用于 /skill.md 和 /llms.txt。 |
basePath |
把所有路由放到一个前缀下。见在前缀下提供 rungent。 |
sources |
更多搜索来源,比如你的文档。见搜索与知识。 |
hostKeys |
你的 API 签 Rungent-Host-Assertion 所用的公钥。见 HTTP API。 |
skill |
{ name?, guide?, cli? },用于 /skill.md。见入口。 |
limits |
{ maxSteps, contextTokens, runTimeoutSeconds }。默认 16、128 000 和 600。 |
mcp |
{ authorizationServers?, instructions? }。见入口。 |
挂载到 Hono#
把应用的 fetch 交给 rungent,再挂上这些路径。rungent 的调用不会离开进程,每一个都以发往 host.origin 的请求到达你的路由。
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 自己读取原始请求体。
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 继续。
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 应用的根布局里,包住页面渲染的区域。这样用户在页面之间切换时,面板和其中的对话都保持不动。
// 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 |
你页面自己的表单组件,按操作名对应。见表单与确认。 |
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 变量:
.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。
接下来#
供 Agent 读取: javascript.md编辑此页