@h-ai/cli 0.1.0-alpha.46 → 0.1.0-alpha.48

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.46",
+  "version": "0.1.0-alpha.48",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -34,7 +34,7 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.46"
+    "@h-ai/core": "0.1.0-alpha.48"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/apps/api/apps/{{projectName}}-service/config/_serv.yml.hbs

@@ -2,6 +2,10 @@
 # {{projectName}} API Service - Serv / HTTP 入口配置
 # =============================================================================
 
+server:
+  host: 127.0.0.1
+  port: 3000
+
 http:
   apiPrefix: /api/v1
   openapi:

package/templates/apps/api/apps/{{projectName}}-service/src/index.ts.hbs

@@ -1,3 +1,4 @@
+import type { ServConfig } from '@h-ai/serv'
 import process from 'node:process'
 import { core } from '@h-ai/core'
 import { serv } from '@h-ai/serv'
@@ -9,7 +10,11 @@ const logger = core.logger.child({ app: '{{api.servicePackageName}}', scope: 'en
 async function main(): Promise<void> {
   await initApp()
 
+  // host/port 来自 config/_serv.yml 的 server（HOST/PORT 环境变量高于配置文件）。
+  const { server } = core.config.getOrThrow<ServConfig>('serv')
   serv.listen({{api.serviceAppFactoryName}}(), {
+    host: server.host,
+    port: server.port,
     onListening: info => logger.info('API service listening', { address: info.address, port: info.port }),
     onClose: closeApp,
   })

package/templates/apps/api/apps/{{projectName}}-service/src/server/procedures/app-procedures.ts.hbs

@@ -1,7 +1,5 @@
 import type { ServContext } from '@h-ai/serv'
-{{#if features.iam}}import type { AppEchoInput, AppEchoOutputData, AppInfoOutputData } from '{{api.contractPackageName}}'
-{{else}}import type { AppEchoOutputData, AppInfoOutputData } from '{{api.contractPackageName}}'
-{{/if}}
+import type { AppEchoOutputData, AppInfoOutputData } from '{{api.contractPackageName}}'
 import { ok } from '@h-ai/core'
 import { serv } from '@h-ai/serv'
 import { appContract } from '{{api.contractPackageName}}'
@@ -15,12 +13,12 @@ export interface AppProcedureDeps {
   readonly startedAt: number
 }
 
-const p = serv.implement(appContract).$context<ServContext>()
-
 /** 创建应用自有 procedures。 */
 export function createAppProcedures(deps: AppProcedureDeps) {
-  return p.router({
-    info: p.info.handler(() => {
+  return serv
+    .implement(appContract)
+    .context<ServContext>()
+    .route('info', () => {
       const data: AppInfoOutputData = {
         name: deps.info.name,
         version: deps.info.version,
@@ -28,22 +26,28 @@ export function createAppProcedures(deps: AppProcedureDeps) {
         uptimeMs: Math.max(0, Date.now() - deps.startedAt),
       }
       return ok(data)
-    }),
-    echo: {{#if features.iam}}p.echo.handler(serv.requireAuth<AppEchoInput, AppEchoOutputData>(({ input, context }) => {
+    })
+{{#if features.iam}}
+    .route('echo')
+    .auth()
+    .handle(({ input, context }) => {
       const data: AppEchoOutputData = {
         message: input.message,
-        userId: context.session!.userId,
+        userId: context.session.userId,
         requestId: context.requestId,
         timestamp: new Date().toISOString(),
       }
-      return Promise.resolve(ok(data))
-    })){{else}}p.echo.handler(({ input, context }) => {
+      return ok(data)
+    })
+{{else}}
+    .route('echo', ({ input, context }) => {
       const data: AppEchoOutputData = {
         message: input.message,
         requestId: context.requestId,
         timestamp: new Date().toISOString(),
       }
       return ok(data)
-    }){{/if}},
-  })
+    })
+{{/if}}
+    .build()
 }

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_serv.yml.hbs

@@ -5,6 +5,10 @@
 # 业务接口路径直接写在对应 *-contract.ts；公共 HTTP 传输配置以本文件为准。
 # =============================================================================
 
+server:
+  host: 127.0.0.1
+  port: 3000
+
 http:
   apiPrefix: /api/v1
   openapi:

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/index.ts.hbs

@@ -1,18 +1,18 @@
-import process from 'node:process'
+import type { ServConfigInput } from '@h-ai/serv'
 import { core } from '@h-ai/core'
-import { serv } from '@h-ai/serv'
+import { serv, ServConfigSchema } from '@h-ai/serv'
 import { createServerApp } from './app-server.js'
 
 // 加载 config/ 下的 _core.yml / _serv.yml 等配置文件（约定优于配置）
 core.init({ configDir: './config', logging: { level: 'info' } })
 
+// host/port 来自 config/_serv.yml 的 server（HOST/PORT 环境变量高于配置文件）。
+const { server } = ServConfigSchema.parse(core.config.get<ServConfigInput>('serv') ?? {})
 const app = createServerApp()
-const port = process.env.PORT ? Number(process.env.PORT) : 3000
-const host = process.env.HOST ?? '127.0.0.1'
 const listenApp = app as Parameters<typeof serv.listen>[0]
 
 serv.listen(listenApp, {
-  port,
-  host,
-  onListening: info => core.logger.info('{{fullstack.servPackageName}} listening', { host, port: info.port }),
+  host: server.host,
+  port: server.port,
+  onListening: info => core.logger.info('{{fullstack.servPackageName}} listening', { host: server.host, port: info.port }),
 })

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/procedures/app-procedures.ts.hbs

@@ -11,21 +11,21 @@ export interface CreateAppProceduresOptions {
   readonly frontends: readonly AppFrontendTarget[]
 }
 
-const p = serv.implement(appContract).$context<ServContext>()
-
 /** app 领域 procedures：把共享 contract 绑定到真实业务处理函数。 */
 export function createAppProcedures(options: CreateAppProceduresOptions) {
-  return p.router({
-    info: p.info.handler(() => ok(createAppInfo(options))),
-    echo: p.echo.handler(({ input, context }) => {
+  return serv
+    .implement(appContract)
+    .context<ServContext>()
+    .route('info', () => ok(createAppInfo(options)))
+    .route('echo', ({ input, context }) => {
       const data: AppEchoOutputData = {
         message: input.message,
         echoedAt: new Date().toISOString(),
         requestId: context.requestId,
       }
       return ok(data)
-    }),
-  })
+    })
+    .build()
 }
 
 function createAppInfo(options: CreateAppProceduresOptions): AppInfoOutputData {
@@ -35,4 +35,4 @@ function createAppInfo(options: CreateAppProceduresOptions): AppInfoOutputData {
     startedAt: options.startedAt,
     frontends: [...options.frontends],
   }
-}
+}

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.46",
+  "version": "0.1.0-alpha.48",
   "private": true,
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",
   "keywords": ["hai", {{#unless isSvelteOnlyApp}}"sveltekit", {{/unless}}"svelte5", "{{appType}}"],

package/templates/skills/hai-ai/SKILL.md

@@ -126,7 +126,7 @@ memory:
 | Context 并发 | `createManager({ concurrency: 'reject' \| 'queue' })` | 默认单活动生成防消息乱序；活动生成期间新 chat 返回 `CONTEXT_BUSY`（reject）或排队（queue） |
 | Context 重置 | `await manager.reset({ preserveSystemPrompt?, cancelActiveTurn?, waitForMemoryTasks? })` | 异步：终止活动生成、清空消息/摘要/轮次，默认保留系统提示词 |
 | 语音识别 | `ai.audio.transcribe` / `transcribeStream` | 完整音频返回 `HaiResult`；持续音频输入用 `AudioInputStream` 流式返回临时文本 |
-| 语音合成 | `ai.audio.synthesize` / `synthesizeStream` | `text` 可为字符串或 `AsyncIterable<string>`（可接 LLM 文本流边生成边合成） |
+| 语音合成 | `ai.audio.synthesize` / `synthesizeStream` | `text` 可为字符串或 `AsyncIterable<string>`（可接 LLM 文本流边生成边合成）；完整结果可用 `serializePlayableAudio` 转为浏览器播放负载 |
 | 图片生成 | `ai.image.generate({ prompt, size?, model?, referenceImages? })` | 可选参考图使用字节 + MIME；Provider 协议和临时 URL 下载由模块内部处理 |
 | A2A | `ai.a2a.registerExecutor/handleRequest` | 延迟初始化 SDK handler |
 
@@ -317,6 +317,20 @@ for await (const event of ai.audio.synthesizeStream({ text: { id: 'seg-1', text:
 }
 ```
 
+需要通过 API 返回浏览器可播放的 Base64 音频时，调用 `serializePlayableAudio(result.data)`；该函数会将 `pcm16` 封装为 WAV，并透传 WAV/MP3，`opus` 不支持该转换。
+
+```ts
+import { serializePlayableAudio } from '@h-ai/ai'
+
+const synthesized = await ai.audio.synthesize({ text: '欢迎参加访谈。' })
+if (!synthesized.success)
+  return synthesized
+
+const playable = serializePlayableAudio(synthesized.data)
+if (!playable.success)
+  return playable
+```
+
 - 流式方法是 `AsyncIterable`，迭代期间的连接/协议/上游错误会终止迭代（抛出），不返回 `HaiResult`。
 - `segment_started` 携带服务端解析 Provider 后的真实输出参数（`format` / `sampleRate?` / `channels?`）；播放器据此解码，不按请求参数猜测格式。
 - 平台不支持的输入方式（如 OpenAI/MiMo 的持续音频输入）会抛 `AUDIO_UNSUPPORTED_INPUT`，不伪装成实时。

package/templates/skills/hai-ai/reference.md

@@ -178,6 +178,7 @@ const result = await ai.rag.query('核心架构是什么？', {
 | `getCapabilities({ operation, model? })` | `HaiResult<AudioModelCapabilities>` | 按模型与操作查询 `transcribe` / `synthesize` 能力分支，并拒绝操作不匹配模型 |
 
 - 音频类型：`AudioContent { data: Uint8Array, format: 'pcm16'|'wav'|'mp3'|'opus', sampleRate?, channels? }`；`pcm16` 等裸音频必须传 `sampleRate`。
+- 播放负载：`serializePlayableAudio(audio)` 返回 `HaiResult<PlayableAudio>`；`PlayableAudio` 为 `{ audioBase64, format: 'wav'|'mp3', mimeType }`。该函数将 `pcm16` 封装为 WAV，透传 WAV/MP3；`opus` 不支持转换。
 - 请求可选：识别 `contextHints?: string[]`（热词/提示）；合成 `instruction?: string`（自然语言风格指令）；均支持 `signal: AbortSignal`。
 - 模型配置：`audio.models: [{ id, provider: 'openai'|'mimo'|'qwen'|'doubao', model, operations, apiKey?, baseUrl?, appKey?, accessKey?, resourceId?, workspaceId? }]`；`operations` 必须明确为识别、合成或两者。确认 LLM 与语音模型共用凭据时，可设置 `audio.inheritLlmApiKey: true`，默认关闭。
 - 凭据优先级：模型条目 `apiKey` → 显式启用继承后的 LLM `apiKey` → `HAI_AI_AUDIO_<PROVIDER>_API_KEY` 或 `OPENAI_API_KEY` / `MIMO_API_KEY` / `DASHSCOPE_API_KEY` / `VOLC_API_KEY`（豆包旧版控制台额外 `VOLC_APP_KEY` / `VOLC_ACCESS_KEY`）。可选密钥中的 YAML `null`、空字符串和纯空白字符串都会规范化为未配置。

package/templates/skills/hai-build/SKILL.md

@@ -225,7 +225,7 @@ logging:
 | 身份认证/授权         | `hai-iam`        | iam.init, 登录, 注册, RBAC, Token, Bearer         |
 | AI/LLM/MCP            | `hai-ai`         | ai.init, LLM, MCP, Agent, 工具调用                |
 | 公共 API 契约         | `hai-api-contract` | apiContract.create, contract, schema, oRPC, HaiResult |
-| API Service 运行时    | `hai-serv`       | serv.createApp, Hono, procedures, OpenAPI, docs, requireAuth |
+| API Service 运行时    | `hai-serv`       | serv.createApp, Hono, procedures, OpenAPI, docs, route guard |
 | SvelteKit 集成        | `hai-kit`        | kit.createHandle, guard, middleware, validate, response |
 | UI 组件               | `hai-ui`         | 表单, 按钮, 表格, Modal, Toast, 移动端组件        |
 | typed API 客户端      | `hai-api-client` | apiClient.init, typed client, Bearer, 401 refresh, custom fetch |

package/templates/skills/hai-kit/SKILL.md

@@ -131,6 +131,10 @@ transport 默认保护同源 `/api/*` endpoint 与 SvelteKit `__data.json` 页
 同时驱动 `hooks.server.ts` 与浏览器端 `kit.client.installBrowserTransport()`：
 
 ```yml
+server:
+  host: 127.0.0.1
+  port: 3000
+
 transport:
   keyExchangePath: /api/_hai/key-exchange
   requireEncryption: true
@@ -150,7 +154,8 @@ import rawKitConfig from '../config/_kit.yml?raw'
 export const appKitConfig = resolveKitConfig(parse(rawKitConfig) ?? {})
 ```
 
-`_kit.yml` 只放公开的 transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
+`resolveKitConfig()` 同时解析 `server`（host/port）与 `transport`；host/port 优先级为 `HOST` / `PORT` 环境变量 > `_kit.yml` 的 `server` > 默认 `127.0.0.1:3000`（与 `@h-ai/serv` 同构）。
+`_kit.yml` 只放公开的 server/transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
 
 ## 核心 API
 

package/templates/skills/hai-serv/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-serv
-description: 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象；当需求涉及创建 API 服务、装配 procedure、挂载 OpenAPI 文档、配置健康检查、添加认证/权限 pipeline 包装器或切换 Node/Fetch 运行时适配器时使用。
+description: 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象；当需求涉及创建 API 服务、装配 procedure、挂载 OpenAPI 文档、配置健康检查、声明 route 认证授权或切换 Node/Fetch 运行时适配器时使用。
 ---
 
 # hai-serv
@@ -9,7 +9,7 @@ description: 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象；当需求涉及创建 API 服务、装配 procedure、挂载 OpenAPI 文档、配置健康检查、添加认证/权限 pipeline 包装器或切换 Node/Fetch 运行时适配器时使用。 |
+| 能力 | 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象；当需求涉及创建 API 服务、装配 procedure、挂载 OpenAPI 文档、配置健康检查、声明 route 认证授权或切换 Node/Fetch 运行时适配器时使用。 |
 | 适用场景 | 当任务与 `hai-serv` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
 | 输入 | 模块配置、类型化业务参数、依赖初始化状态和目标运行环境 |
 | 输出 | 符合模块公共 API 的实现或示例；业务结果使用 HaiResult，并同步必要测试与文档 |
@@ -31,14 +31,14 @@ description: 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象
 
 - 将 `@h-ai/api-contract` contract 装配成最小 HTTP App 抽象
 - 配置 `/health`、`/ready`、`/openapi.json`、`/docs` 等系统端点
-- 在 procedure 中添加认证（`requireAuth`）或权限（`requirePermission`）检查
+- 在 procedure route 上添加 `.auth()`、`.permission()` 或 `.role()` guard
 - 切换 Node.js (`@hono/node-server`) 或 Fetch Runtime（Cloudflare Workers / Deno）部署
 - 自定义 `ServContext`（注入 session、tenant 等请求级数据）
 - 生成 OpenAPI 3.1 文档供外部工具消费
 - 通过 `config/_serv.yml` 管理 API 前缀、OpenAPI、docs、health、rpc 等 HTTP 挂载配置
 - 通过 `serv.createRuntimeSecurityPolicy(...)` 对生产 CORS Origin、原生 WebView Origin、Secure Cookie 与 API 文档暴露执行 fail-closed 策略
 - 启用传输加密：`serv.createApp({ transport: { crypto } })`
-- 高级场景通过 `createApp({ middlewares })` 自定义 HTTP middleware，或通过共享类型自定义 procedure wrapper
+- 高级场景通过 `createApp({ middlewares })` 自定义 HTTP middleware，通过 `createContext` 注入请求级业务字段
 - 公开只读文件通过 `serv.storageAssets(...)` 统一处理安全 key、MIME 白名单、GET/HEAD、ETag 与缓存头
 - 为 Audio WebSocket 配置一次性 ticket 校验、IAM/模型/配额授权与并发释放钩子
 
@@ -86,8 +86,11 @@ const app = serv.createApp({
   },
 })
 
-// Node.js 启动（自动读取 PORT / HOST 环境变量；onClose 自动监听 SIGINT/SIGTERM）
+// Node.js 启动（host/port 来自 _serv.yml 的 server；HOST/PORT 环境变量高于配置文件；onClose 自动监听 SIGINT/SIGTERM）
+const { server } = core.config.getOrThrow<ServConfig>('serv')
 serv.listen(app, {
+  host: server.host,
+  port: server.port,
   onListening: info => logger.info('API service listening', { port: info.port }),
   onClose: closeApp, // 业务模块关闭函数（ai/storage/iam/reldb 等反向释放）
 })
@@ -179,16 +182,19 @@ import { ok } from '@h-ai/core'
 import { serv } from '@h-ai/serv'
 
 export function createAppProcedures(deps: { name: string; version: string }) {
-  const p = serv.implement(appContract).$context<ServContext>()
-  return p.router({
-    // 公开 procedure：handler 直接返回 HaiResult
-    info: p.info.handler(() => ok({ name: deps.name, version: deps.version })),
-    // 鉴权 procedure：用 serv.requireAuth 包一层，未登录时短路返回 ApiUnauthorized
-    echo: p.echo.handler(serv.requireAuth(({ input, context }) => ok({
+  return serv
+    .implement(appContract)
+    .context<ServContext>()
+    // 公开 procedure：route 名只出现一次，handler 直接返回 HaiResult。
+    .route('info', () => ok({ name: deps.name, version: deps.version }))
+    // 鉴权 procedure：guard 通过后 context.session 自动收窄为非空。
+    .route('echo')
+    .auth()
+    .handle(({ input, context }) => ok({
       message: input.message,
-      userId: context.session!.userId,
-    }))),
-  })
+      userId: context.session.userId,
+    }))
+    .build()
 }
 ```
 
@@ -215,7 +221,7 @@ const app = serv.createApp({ contract, procedures, http, iam })
 注意要点：
 
 - **无 input 的 POST 过程**：默认不发送 body；transport 加密层会自动跳过空 body 请求，客户端可直接 `client.app.info()`。
-- **`serv.requireAuth` 仅可在过程内调用**：必须在 `context` 中有 `session`；公开过程不要包装它。
+- **认证授权写在 route 链上**：公开过程使用 `.route(path, handler)`；需要认证时使用 `.route(path).auth().handle(handler)`。
 - **客户端导入相同 contract**：把服务端与客户端共享的 contract 独立成 package（如 `@h-ai/api-service-contract`），禁止从 app 源码目录跨应用 import。
 
 ### 5. Fetch Runtime（Cloudflare Workers / Deno / Bun）
@@ -262,6 +268,10 @@ const app = serv.createApp({
 
 ```yaml
 # config/_serv.yml
+server:
+  host: 127.0.0.1
+  port: 3000
+
 http:
   apiPrefix: /api/v1
   openapi:
@@ -320,8 +330,14 @@ import { serv } from '@h-ai/serv'
 // 等价于 oc.route(...)，但不让应用感知 @orpc/contract
 const route = apiContract.route({ method: 'POST', path: '/x', operationId: 'x', tags: ['x'] })
 
-// 等价于 implement(contract)
-const p = serv.implement(appContract).$context<ServContext>()
+const procedures = serv
+  .implement(appContract)
+  .context<ServContext>()
+  .route('info', infoHandler)
+  .route('echo')
+  .auth()
+  .handle(echoHandler)
+  .build()
 ```
 
 ### 传输加密
@@ -379,16 +395,17 @@ await apiClient.init({
 3. `iam.session.verifyToken`（推荐：传入 `iam` 后自动启用）
 4. 默认 `parseRequestContext`：仅解析请求元数据，`session` 为 `undefined`
 
-> ⚠️ `verifyToken` 会在每次请求调用（不缓存）；verifyToken 失败或抛错统一收敛为 `session=undefined`，由 `requireAuth` 统一返回 401。
+> ⚠️ `verifyToken` 会在每次请求调用（不缓存）；verifyToken 失败或抛错统一收敛为 `session=undefined`，由 route 的 `.auth()` / `.permission()` / `.role()` 统一返回 401。
 
-### Procedure 包装器（所有导出为 `serv.xxx` 扁平 API）
+### 链式 procedure guard
 
-| 函数 | 说明 |
+| 链式调用 | 说明 |
 | --- | --- |
-| `serv.mapHaiError(handler)` | 捕获未处理异常，转换为 `HaiResult` |
-| `serv.requireAuth(handler)` | 验证 session（`context.session` 非空，即 token 已通过 `verifyToken` 校验） |
-| `serv.requirePermission(permission, handler)` | 验证权限码，支持通配符 `serv.WILDCARD_PERMISSION`（`'*'`） |
-| `serv.requireRole(role, handler)` | 验证角色，支持通配符 `serv.WILDCARD_ROLE`（`'*'`） |
+| `.route(path, handler)` | 注册公开 procedure；path/input/output 从 contract 推导 |
+| `.route(path).auth().handle(handler)` | 要求 session；通过后 `context.session` 自动收窄 |
+| `.permission(permission)` | 隐含认证并检查权限，支持 `serv.WILDCARD_PERMISSION` |
+| `.role(role)` | 隐含认证并检查角色，支持 `serv.WILDCARD_ROLE` |
+| `.build()` | contract 全部 procedures 实现后构建 router |
 | `serv.validateInputOrFail(zodSchema, input, locale)` | 在 procedure 内执行 Zod 二次校验，失败时返回本地化 `HaiResult` + `ValidationFormError[]` |
 | `serv.resolveRequestLocale(headers)` | 从 `x-hai-locale` / `Accept-Language` 解析并规范化 locale |
 | `serv.m(key, { locale, params })` | 读取 serv 自身 i18n 消息（请求级本地化） |
@@ -396,26 +413,29 @@ await apiClient.init({
 ```typescript
 import { serv } from '@h-ai/serv'
 
-// 组合包装（从外到内：error → auth → permission/role → handler）
-const handler = serv.mapHaiError(
-  serv.requireAuth(
-    serv.requirePermission('user.write', actualHandler)
-  )
-)
-
-// 角色检查示例
-const adminOnly = serv.requireAuth(
-  serv.requireRole('admin', actualHandler)
-)
+const procedures = serv
+  .implement(appContract)
+  .context<ServContext>()
+  .route('info', infoHandler)
+  .route('users.update')
+  .permission('user.write')
+  .role('admin')
+  .handle(updateUserHandler)
+  .build()
 ```
 
-### 高级：自定义 pipeline（HTTP middleware + context + procedure wrapper）
+- `.permission()` / `.role()` 隐含 `.auth()`；未登录返回 401，授权不足返回 403。
+- 同一路由声明多个 permission/role 时必须全部满足。
+- handler 的未处理异常由 router 统一转换成 INTERNAL_ERROR HaiResult。
+- 重复/未知路径会被拒绝；遗漏 contract procedure 时 `.build()` 在类型上不可用，运行时也会校验。
+
+### 高级：自定义 pipeline（HTTP middleware + context + route guard）
 
 `@h-ai/serv` 的 pipeline 分三层：
 
 1. **HTTP middleware 层**：通过 `serv.createApp({ middlewares })` 注入 HTTP middleware
 2. **context 层**：通过 `verifyToken` / `createContext` / `serv.buildAuthContextFactory()` 自定义请求上下文
-3. **procedure wrapper 层**：通过 `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 自定义业务包装器
+3. **route guard 层**：通过 `.auth()` / `.permission()` / `.role()` 声明认证授权
 
 #### HTTP middleware
 
@@ -501,44 +521,25 @@ const app = serv.createApp({
 - 在默认认证上下文之上追加字段：`buildAuthContextFactory(...) + createContext`
 - 完全接管上下文构造：`createContext`
 
-#### Procedure wrapper
+#### Route guard
 
-适用于已进入 procedure 后的审计、租户约束、业务 guard：
+认证、权限与角色约束直接写在目标 route 上，不嵌套高阶 handler：
 
 ```typescript
-import type { ServGuardedProcedureWrapper, ServProcedureWrapper } from '@h-ai/serv'
-import { err, HaiCommonError } from '@h-ai/core'
-import { serv } from '@h-ai/serv'
-
-const withAudit: ServProcedureWrapper = handler => async (options) => {
-  options.context.logger.info('procedure.start', { requestId: options.context.requestId })
-  return await handler(options)
-}
-
-const requireTenant: ServGuardedProcedureWrapper<string> = (tenantId, handler) => async (options) => {
-  if (options.context.request.headers.get('x-tenant-id') !== tenantId) {
-    return err(
-      HaiCommonError.FORBIDDEN,
-      serv.m('serv_errorForbidden', { locale: options.context.locale }),
-    )
-  }
-  return await handler(options)
-}
-
-const createWidget = serv.mapHaiError(
-  serv.requireAuth(
-    withAudit(
-      requireTenant('tenant-a', async ({ input }) => widgetService.create(input)),
-    ),
-  ),
-)
+const procedures = serv
+  .implement(widgetContract)
+  .context<ServContext>()
+  .route('widgets.list', ({ input }) => widgetService.list(input))
+  .route('widgets.create')
+  .permission('widgets.write')
+  .handle(({ input, context }) =>
+    widgetService.create(context.session.userId, input))
+  .build()
 ```
 
-说明：
-
-- `ServMiddleware` / `ServMiddlewareMount` / `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 等共享类型由根入口 `@h-ai/serv` 对外暴露
-- `src/pipelines/*` 是模块内部默认实现目录，不作为公开子路径 API 文档承诺
-- 常规场景优先继续用 `serv.requireAuth / requirePermission / requireRole / mapHaiError`
+HTTP 审计、限流、CORS、租户头校验等跨 route 能力继续放在
+`createApp({ middlewares })`；请求级业务字段通过 `createContext` 注入。
+不要为认证授权重新嵌套多层高阶 handler。
 
 ### 正常业务请求中的错误与 i18n
 
@@ -549,22 +550,24 @@ const createWidget = serv.mapHaiError(
 3. **业务/领域错误**：不要 throw 预期失败；直接返回 `err(...)`，并在**创建错误消息的那一层**用对应模块的 i18n getter 按 `context.locale` 出消息。
 
 ```typescript
-import { err, HaiCommonError } from '@h-ai/core'
 import { z } from 'zod'
 import { serv } from '@h-ai/serv'
 
 const Schema = z.object({ title: z.string().min(1) })
 
-const handler = serv.mapHaiError(async ({ input, context }) => {
-  const validated = serv.validateInputOrFail(Schema, input, context.locale)
-  if (!validated.success)
-    return validated
-
-  if (!context.session)
-    return err(HaiCommonError.UNAUTHORIZED, serv.m('serv_errorUnauthorized', { locale: context.locale }))
-
-  return widgetService.create(validated.data)
-})
+const procedures = serv
+  .implement(widgetContract)
+  .context<ServContext>()
+  .route('widgets.create')
+  .auth()
+  .handle(({ input, context }) => {
+    const validated = serv.validateInputOrFail(Schema, input, context.locale)
+    if (!validated.success)
+      return validated
+
+    return widgetService.create(context.session.userId, validated.data)
+  })
+  .build()
 ```
 
 > 如果错误来自下游模块（如 `iam` / `storage`）并且该模块已经返回 `HaiResult`，serv 默认**透传**它的 `error.message`。由于 `HaiError` 目前不携带 `messageKey/params`，serv 边界不能对任意下游错误再做通用重翻译；要做请求级 i18n，必须在创建该错误的模块/feature 里就拿到 locale。
@@ -639,20 +642,17 @@ import type { ServContext } from '@h-ai/serv'
 import { serv } from '@h-ai/serv'
 import { myContract } from './my-contract.js'
 
-const { requireAuth, requirePermission } = serv
-
 export function createMyProcedures() {
-  return {
-    widget: {
-      list: requireAuth(async ({ input, context }) => {
-        // input 类型来自 contract 定义
-        return ok(await widgetService.list(input))
-      }),
-      create: requirePermission('widget:write', async ({ input }) => {
-        return ok(await widgetService.create(input))
-      }),
-    },
-  }
+  return serv
+    .implement(myContract)
+    .context<ServContext>()
+    .route('widget.list')
+    .auth()
+    .handle(({ input }) => widgetService.list(input))
+    .route('widget.create')
+    .permission('widget:write')
+    .handle(({ input }) => widgetService.create(input))
+    .build()
 }
 ```
 
@@ -681,13 +681,13 @@ const app = serv.createApp({
 
 ## 错误码
 
-procedure 包装器内置以下错误：
+route 实现器内置以下错误：
 
 | 错误码 | 触发条件 |
 | --- | --- |
-| `HaiCommonError.UNAUTHORIZED` | `requireAuth`：`context.session` 为空（无 token 或 token 校验失败） |
-| `HaiCommonError.FORBIDDEN` | `requirePermission`：无对应权限 |
-| `HaiCommonError.INTERNAL_ERROR` | `mapHaiError`：procedure 抛出未处理异常 |
+| `HaiCommonError.UNAUTHORIZED` | `.auth()`：`context.session` 为空（无 token 或 token 校验失败） |
+| `HaiCommonError.FORBIDDEN` | `.permission()` / `.role()`：无对应权限或角色 |
+| `HaiCommonError.INTERNAL_ERROR` | route handler 抛出未处理异常 |
 
 ---