快速开始: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-openapinpm install @aidy-dev/client @aidy-dev/reactnpm install -g @aidy-dev/cli这里只用 CLI 生成一次 aidy 的签名密钥。
2. 给路由加注解
Section titled “2. 给路由加注解”使用 @hono/zod-openapi 时,在每个允许 aidy 调用的路由上加一个 x-aidy 对象。没有注解的路由对 aidy 不可见。@hono/zod-openapi 会把这个键原样复制到生成的 OpenAPI 操作中。
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 之外的效果都算写操作,默认需要审批;见操作与效果。
3. 添加身份和搜索
Section titled “3. 添加身份和搜索”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' } });4. 校验断言
Section titled “4. 校验断言”aidy 的每次调用都带着用户的凭据和一个 Aidy-Assertion。你的 API 照常鉴权凭据,并校验断言。aidyRoute 给每个带注解的路由挂一个中间件,完成委托中检查的两部分:verifyAssertion(签名、有效期、audience、方法、URL、请求体、防重放)和 checkCall(subject、tenant、操作、审批)。
aidy 的各个包都不提供 aidyRoute;它是你在 @aidy-dev/spec/delegation 之上自己写的几行代码:
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] });}5. 生成密钥和 secret
Section titled “5. 生成密钥和 secret”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.jwkopenssl rand -base64 32 | npx wrangler secret put AIDY_SECRETnpx wrangler secret put OPENAI_API_KEYrm aidy-2026-11.private.jwk把打印出的公钥 JWK 写进 wrangler.jsonc,作为 var AIDY_PUBLIC_JWK。AIDY_SECRET 用来加密管理员在设置中保存的模型 API key。
6. 创建 D1 存储
Section titled “6. 创建 D1 存储”npx wrangler d1 create console-aidy{ "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_* 表。
7. 挂载 aidy
Section titled “7. 挂载 aidy”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 deploycurl -H "Authorization: Bearer $TOKEN" https://console.example.com/skill.md8. 加上侧边栏
Section titled “8. 加上侧边栏”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。