跳转到内容

快速开始:Workers 上的 Hono

本快速开始把 aidy 内嵌到 Cloudflare Workers 上的 Hono 应用中。运行时和你的 API 跑在同一个 Worker 里:它通过进程内的 app.fetch 访问你的路由,把会话存进 D1,并在你自己的域名下提供 agent、MCP 和生成的文档。

贯穿全文的例子是位于 https://console.example.com 的云控制台,其中有一个 stop_vm 操作。

终端窗口
npm install @aidy-dev/core @aidy-dev/sql @aidy-dev/spec @hono/zod-openapi
npm install @aidy-dev/client @aidy-dev/react
npm install -g @aidy-dev/cli

这里只用 CLI 生成一次 aidy 的签名密钥。

使用 @hono/zod-openapi 时,在每个允许 aidy 调用的路由上加一个 x-aidy 对象。没有注解的路由对 aidy 不可见。@hono/zod-openapi 会把这个键原样复制到生成的 OpenAPI 操作中。

src/api.ts
import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
import type { AssertionClaims } from '@aidy-dev/spec/delegation';
export type Env = {
DB: D1Database;
AIDY_SIGNING_KEY: string; // 私钥 JWK,作为 secret
AIDY_PUBLIC_JWK: string; // 公钥 JWK,作为 var
AIDY_SECRET: string;
OPENAI_API_KEY: string;
};
type Vars = { user: { id: string; orgId: string; name: string }; aidy?: AssertionClaims };
export const app = new OpenAPIHono<{ Bindings: Env; Variables: Vars }>();
app.use('/api/*', authenticate); // 你现有的 session 或 bearer 鉴权,设置 c.var.user
const Vm = z.object({ id: z.string(), name: z.string(), status: z.enum(['running', 'stopped']) });
app.openapi(
aidyRoute({
method: 'get',
path: '/api/vm/{vm_id}',
summary: 'Get a server',
request: { params: z.object({ vm_id: z.string() }) },
responses: { 200: { description: 'The VM', content: { 'application/json': { schema: Vm } } } },
'x-aidy': { name: 'get_vm', description: 'Get a cloud server (VM) by id.' },
}),
async (c) => c.json(await getVm(c.var.user, c.req.valid('param').vm_id), 200),
);
app.openapi(
aidyRoute({
method: 'post',
path: '/api/vm/{vm_id}/stop',
summary: 'Stop server',
request: {
params: z.object({ vm_id: z.string() }),
body: { content: { 'application/json': { schema: z.object({ forced: z.boolean().default(false) }) } } },
},
responses: { 200: { description: 'Stopped', content: { 'application/json': { schema: Vm } } } },
'x-aidy': {
name: 'stop_vm',
title: 'Stop server',
description: 'Stop a running cloud server (VM).',
effect: 'update',
open: '/console/instance/{vm_id}',
confirmation: {
title: 'Stop server {resource_name}?',
fields: [{ key: 'forced', label: 'Force', values: { true: 'Yes', false: 'No' } }],
lookup: { path: '/api/vm/{vm_id}', labelPath: 'name' },
},
},
}),
async (c) => c.json(await stopVm(c.var.user, c.req.valid('param').vm_id, c.req.valid('json')), 200),
);

POST 的默认效果是 create。停止服务器是修改已有资源,所以给 stop_vm 设置 effect: 'update'。除 read 之外的效果都算写操作,默认需要审批;见操作与效果。

aidy 需要恰好一个 role: identity 操作来判断凭据属于谁,并可以联邦检索任意多个 role: search 操作。

const Identity = z.object({ subject: z.string(), tenant: z.string().optional(), name: z.string().optional() });
app.openapi(
aidyRoute({
method: 'get',
path: '/api/me',
responses: { 200: { description: 'Me', content: { 'application/json': { schema: Identity } } } },
'x-aidy': { name: 'whoami', role: 'identity' },
}),
(c) => c.json({ subject: c.var.user.id, tenant: c.var.user.orgId, name: c.var.user.name }, 200),
);
app.openapi(
aidyRoute({
method: 'get',
path: '/api/vms/search',
request: { query: z.object({ q: z.string(), limit: z.coerce.number().max(50).default(10) }) },
responses: { 200: { description: 'Hits', content: { 'application/json': { schema: z.object({ hits: z.array(z.any()) }) } } } },
'x-aidy': { name: 'search_vms', role: 'search' },
}),
async (c) => {
const { q, limit } = c.req.valid('query');
const vms = await findVms(c.var.user, q, limit);
return c.json({ hits: vms.map((vm) => ({ type: 'vm', id: vm.id, title: vm.name, url: `/console/instance/${vm.id}` })) }, 200);
},
);
app.doc31('/openapi.json', { openapi: '3.1.0', info: { title: 'Console', version: '1' } });

见身份和搜索与知识。

aidy 的每次调用都带着用户的凭据和一个 Aidy-Assertion。你的 API 照常鉴权凭据,并校验断言。aidyRoute 给每个带注解的路由挂一个中间件,完成委托中检查的两部分:verifyAssertion(签名、有效期、audience、方法、URL、请求体、防重放)和 checkCall(subject、tenant、操作、审批)。

aidy 的各个包都不提供 aidyRoute;它是你在 @aidy-dev/spec/delegation 之上自己写的几行代码:

src/aidy-route.ts
import { createRoute, type RouteConfig } from '@hono/zod-openapi';
import { checkCall, importPublicKeys, verifyAssertion } from '@aidy-dev/spec/delegation';
import { createMiddleware } from 'hono/factory';
type XAidy = { name: string; effect?: string; approval?: 'never' | 'always' } & Record<string, unknown>;
const seen = new Map<string, number>(); // jti → exp,每个 isolate 一份
export function aidyRoute<R extends RouteConfig & { 'x-aidy': XAidy }>(route: R) {
const meta = route['x-aidy'];
const effect = meta.effect ?? (route.method === 'get' ? 'read' : 'write');
const approval = meta.approval ?? (effect === 'read' ? 'never' : 'always');
const verify = createMiddleware(async (c, next) => {
const token = c.req.header('aidy-assertion');
if (!token) return next(); // 来自你 UI 的普通请求
try {
const claims = await verifyAssertion(token, {
keys: await importPublicKeys([JSON.parse(c.env.AIDY_PUBLIC_JWK)]),
audience: 'https://console.example.com',
request: { method: c.req.method, url: c.req.url, body: new Uint8Array(await c.req.arrayBuffer()) },
remember: (jti, exp) => {
if (seen.has(jti)) return false;
seen.set(jti, exp);
return true;
},
});
const user = c.get('user');
checkCall(claims, { subject: user.id, tenant: user.orgId, op: meta.name, approval });
c.set('aidy', claims); // 审计:actor = aidy,claims.rid,claims.apr
} catch {
return c.json({ error: 'aidy_assertion_invalid' }, 401);
}
return next();
});
return createRoute({ ...route, middleware: [verify] });
}
终端窗口
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwk

该命令打印公钥 JWK,并把私钥 JWK 写入一个权限为 0600 的新文件。它从不打印私钥。

终端窗口
npx wrangler secret put AIDY_SIGNING_KEY < aidy-2026-11.private.jwk
openssl rand -base64 32 | npx wrangler secret put AIDY_SECRET
npx wrangler secret put OPENAI_API_KEY
rm aidy-2026-11.private.jwk

把打印出的公钥 JWK 写进 wrangler.jsonc,作为 var AIDY_PUBLIC_JWK。AIDY_SECRET 用来加密管理员在设置中保存的模型 API key。

终端窗口
npx wrangler d1 create console-aidy
wrangler.jsonc
{
"name": "console",
"main": "src/index.ts",
"compatibility_date": "2026-11-01",
"d1_databases": [{ "binding": "DB", "database_name": "console-aidy", "database_id": "<id>" }],
"vars": { "AIDY_PUBLIC_JWK": "{\"kty\":\"OKP\",\"crv\":\"Ed25519\",\"x\":\"…\",\"kid\":\"aidy-2026-11\"}" }
}

aidy 在第一次请求时,或在你调用 aidy.migrate() 时,创建自己的 aidy_* 表。

src/index.ts
import { createAidy, SqlStore, type Aidy } from '@aidy-dev/core';
import { importSigningKey } from '@aidy-dev/spec/delegation';
import { d1Driver } from '@aidy-dev/sql/d1';
import type { Context } from 'hono';
import { app, type Env } from './api';
let aidy: Promise<Aidy> | undefined;
function aidyFor(env: Env): Promise<Aidy> {
aidy ??= (async () => {
const signingKey = await importSigningKey(JSON.parse(env.AIDY_SIGNING_KEY));
return createAidy({
url: 'https://console.example.com',
host: {
origin: 'https://console.example.com',
openapi: '/openapi.json',
fetch: (request) => app.fetch(request, env), // 进程内调用,不走网络
},
signingKey,
secret: env.AIDY_SECRET,
store: new SqlStore(d1Driver(env.DB)),
models: { chain: [{ id: 'main', provider: 'openai', model: 'gpt-4.1-mini', apiKey: env.OPENAI_API_KEY }] },
});
})();
return aidy;
}
const serve = async (c: Context<{ Bindings: Env }>) => (await aidyFor(c.env)).fetch(c.req.raw, c.executionCtx);
app.all('/aidy/v0/*', serve);
app.all('/mcp', serve);
app.get('/skill.md', serve);
app.get('/llms.txt', serve);
app.get('/.well-known/aidy-keys.json', serve);
export default app;

importSigningKey 把私钥 JWK 导入为可导出(extractable)的密钥,这样 aidy 才能在 /.well-known/aidy-keys.json 公开其公钥部分;它还会去掉 workerd 拒绝的成员(Node 导出的 alg、key_ops、ext)。createAidy 返回 { fetch(request, ctx?), migrate(), close() };传入 c.executionCtx 后,运行可以借助 waitUntil 在响应结束后继续。createAidy 在第一次请求之前不做任何 I/O,所以每个 isolate 构建一次的开销很小。要把 aidy 挂在 /assistant 这样的前缀下,设置 basePath。模型选择和回退见模型。

部署,然后检查生成的文档:

终端窗口
npx wrangler deploy
curl -H "Authorization: Bearer $TOKEN" https://console.example.com/skill.md
web/Shell.tsx
import { createClient } from '@aidy-dev/client';
import { AidyDock, AidyProvider, SearchPalette } from '@aidy-dev/react';
import '@aidy-dev/react/styles.css';
import type { ReactNode } from 'react';
import { useNavigate } from 'react-router';
const client = createClient(); // same origin; the client adds /aidy/v0
export function Shell({ children }: { children: ReactNode }) {
const navigate = useNavigate();
return (
<AidyProvider client={client} locale="zh-CN" onOpen={(path) => navigate(path)}>
{children}
<AidyDock />
<SearchPalette />
</AidyProvider>
);
}

aidy 把请求的 Authorization 和 Cookie 头当作用户凭据,所以同源的 cookie 会话无需改动即可使用。使用 bearer token 时,在 createClient 中加上:

const client = createClient({
headers: () => ({ Authorization: `Bearer ${getToken()}` }),
});

⌘J 打开或关闭侧边栏。让它“停掉 gpu-train-01”:它会查到这台服务器,显示标题为“Stop server gpu-train-01?”的审批卡片,只有你批准后才执行。成功后,onOpen 会收到 /console/instance/vm-42。