@h-ai/cli 0.1.0-alpha.12 → 0.1.0-alpha.15

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

@@ -0,0 +1,658 @@
+---
+name: hai-serv
+description: 使用 @h-ai/serv 将 oRPC contract 挂载为 Hono HTTP API Service；当需求涉及创建 API 服务、装配 procedure、挂载 OpenAPI 文档、配置健康检查、添加认证/权限 pipeline 包装器或切换 Node/Fetch 运行时适配器时使用。
+---
+
+# hai-serv
+
+> `@h-ai/serv` 是 hai-framework 的 API Service 运行时，基于 Hono + oRPC 将 `@h-ai/api-contract` 的领域 contract 挂载成跨端可访问的 HTTP API。
+
+---
+
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js / Fetch Runtime）。** 浏览器端通过 `@h-ai/api-client` 调用由本模块暴露的 HTTP API。
+
+---
+
+## 适用场景
+
+- 将 `@h-ai/api-contract` contract 装配成 Hono HTTP app
+- 配置 `/health`、`/ready`、`/openapi.json`、`/docs` 等系统端点
+- 在 procedure 中添加认证（`requireAuth`）或权限（`requirePermission`）检查
+- 切换 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.createApp({ transport: { crypto } })`
+- 高级场景通过 `createApp({ middlewares })` 自定义 HTTP middleware，或通过共享类型自定义 procedure wrapper
+
+---
+
+## 使用步骤
+
+### 1. 安装依赖
+
+```typescript
+// @h-ai/serv 依赖 @h-ai/api-contract 提供 contract 定义
+// 业务 procedure 依赖对应领域模块（iam/storage/ai）
+```
+
+### 2. 创建并启动 app
+
+```typescript
+import { ai } from '@h-ai/ai'
+import { apiContract } from '@h-ai/api-contract'
+import { iam } from '@h-ai/iam'
+import { serv } from '@h-ai/serv'
+import { createAiProcedures } from '@h-ai/serv/features/ai'
+import { createIamProcedures } from '@h-ai/serv/features/iam'
+import { createStorageProcedures } from '@h-ai/serv/features/storage'
+import { storage } from '@h-ai/storage'
+
+const contract = apiContract.create({ iam: apiContract.iam, storage: apiContract.storage, ai: apiContract.ai })
+
+// 装配 procedures（每个 feature 对应 contract 中的一个领域）
+const procedures = {
+  iam: createIamProcedures({ iam }),
+  storage: createStorageProcedures({ storage }),
+  ai: createAiProcedures({ ai }),
+}
+
+// 创建 Hono app
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: {
+    apiPrefix: '/api/v1',
+    openapi: { path: '/openapi.json' },
+    docs: { path: '/docs' },
+    health: { path: '/health', readyPath: '/ready' },
+  },
+})
+
+// Node.js 启动（自动读取 PORT / HOST 环境变量；onClose 自动监听 SIGINT/SIGTERM）
+serv.listen(app, {
+  onListening: info => logger.info('API service listening', { port: info.port }),
+  onClose: closeApp, // 业务模块关闭函数（ai/storage/iam/reldb 等反向释放）
+})
+```
+
+### 3. 扩展应用自有 contract + procedures
+
+`apiContract.create({...})` 接受任意 key——除了框架提供的 `iam/storage/ai`，应用可以挂入自己的领域 contract，
+客户端通过 `client.<key>.<procedure>(...)` 调用，类型完全推导自同一份 contract。
+
+```typescript
+// apps/api-service-contract/src/app-contract.ts
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+const InfoOutput = apiContract.haiResultSchema(z.object({ name: z.string(), version: z.string() }))
+const EchoInput = z.object({ message: z.string().min(1).max(2000) })
+const EchoOutput = apiContract.haiResultSchema(z.object({ message: z.string(), userId: z.string() }))
+
+export const appContract = {
+  info: apiContract.route({ method: 'POST', path: '/app/info', operationId: 'app.info', tags: ['app'] })
+    .output(InfoOutput),
+  echo: apiContract.route({ method: 'POST', path: '/app/echo', operationId: 'app.echo', tags: ['app'] })
+    .input(EchoInput).output(EchoOutput),
+}
+```
+
+```typescript
+// src/server/procedures/app-procedures.ts
+import type { ServContext } from '@h-ai/serv'
+import { appContract } from '@h-ai/api-service-contract'
+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({
+      message: input.message,
+      userId: context.session!.userId,
+    }))),
+  })
+}
+```
+
+把自有 contract / procedures 与框架的 iam/storage/ai 平铺合并：
+
+```typescript
+const contract = apiContract.create({
+  iam: apiContract.iam,
+  storage: apiContract.storage,
+  ai: apiContract.ai,
+  app: appContract, // ← 自有契约
+})
+
+const procedures = {
+  iam: createIamProcedures({ iam }),
+  storage: createStorageProcedures({ storage }),
+  ai: createAiProcedures({ ai }),
+  app: createAppProcedures({ name: 'demo', version: '1.0.0' }),
+}
+
+const app = serv.createApp({ contract, procedures, http, iam })
+```
+
+注意要点：
+
+- **无 input 的 POST 过程**：默认不发送 body；transport 加密层会自动跳过空 body 请求，客户端可直接 `client.app.info()`。
+- **`serv.requireAuth` 仅可在过程内调用**：必须在 `context` 中有 `session`；公开过程不要包装它。
+- **客户端导入相同 contract**：把服务端与客户端共享的 contract 独立成 package（如 `@h-ai/api-service-contract`），禁止从 app 源码目录跨应用 import。
+
+### 5. Fetch Runtime（Cloudflare Workers / Deno / Bun）
+
+```typescript
+import { serv } from '@h-ai/serv'
+
+// toFetch 返回标准 Fetch handler
+const handler = serv.toFetch(app)
+
+export default { fetch: handler }
+```
+
+### 6. 通过 `config/_serv.yml` 管理 HTTP 配置
+
+`@h-ai/serv` 不自己扫描 YAML；推荐由 `@h-ai/core` 统一加载，再用 `ServConfigSchema` 校验：
+
+```typescript
+import { core } from '@h-ai/core'
+import { serv, ServConfigSchema } from '@h-ai/serv'
+
+core.init({ configDir: './config' })
+
+const validation = core.config.validate('serv', ServConfigSchema)
+if (!validation.success)
+  throw new Error(validation.error.message)
+
+const servConfig = core.config.getOrThrow<import('@h-ai/serv').ServConfig>('serv')
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: servConfig.http,
+  transport: servConfig.transport === false
+    ? undefined
+    : {
+        crypto,
+        keyExchangePath: servConfig.transport.keyExchangePath,
+        excludePaths: [...servConfig.transport.excludePaths],
+        maxClients: servConfig.transport.maxClients,
+      },
+})
+```
+
+```yaml
+# config/_serv.yml
+http:
+  apiPrefix: /api/v1
+  openapi:
+    path: /openapi.json
+  docs:
+    path: /docs
+  health:
+    path: /health
+    readyPath: /ready
+  rpc: false
+
+transport:
+  keyExchangePath: /_hai/key-exchange
+  excludePaths:
+    - /health
+    - /ready
+    - /openapi.json
+    - /docs
+    - /_hai/scalar.js
+  maxClients: 10000
+```
+
+---
+
+## 核心 API
+
+### `serv.createApp(options)` — 创建 Hono app
+
+```typescript
+import type { CreateServAppOptions } from '@h-ai/serv'
+
+const app = serv.createApp({
+  contract,       // AnyContractRouter — 通过 apiContract.create() 组合的 contract
+  procedures,     // Router<AnyContractRouter, ServContext> — procedure 实现
+  http?,          // ServHttpConfigInput — HTTP 端点配置（见下方配置节）
+  middlewares?,   // readonly ServMiddlewareMount[] — 自定义 Hono middleware（日志/CORS/限流/租户头校验）
+  iam?,           // ServIam — 顶层 IAM 句柄，同时驱动 access token 校验与 refresh cookie【推荐】
+  refreshCookie?, // RefreshCookieConfig — httpOnly refresh cookie 刷新路径（见下方 cookie 节）
+  transport?,     // { crypto, keyExchangePath?, excludePaths?, maxClients? } — 统一传输加密
+  verifyToken?,   // (token) => Promise<HaiResult<ServSession>> — 逃脱口：不使用 iam 时提供自定义校验
+  createContext?, // CreateServContext — 高级：完全接管上下文构造（设置后 serv 不再自动填充 session）
+})
+```
+
+### `apiContract.route` / `serv.implement` — contract 与运行时分层
+
+应用代码不要直接 `import { oc } from '@orpc/contract'` 或 `import { implement } from '@orpc/server'`。
+contract 路由统一用 `@h-ai/api-contract` 定义，procedure 运行时统一用 `@h-ai/serv` 实现：
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+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>()
+```
+
+### 传输加密
+
+serv 不暴露本地传输加密工厂；内部统一调用 `crypto.transport.createServer()`。客户端用 `@h-ai/api-client` 的 `transport` 配置自动协商。
+
+```typescript
+import { crypto } from '@h-ai/crypto'
+import { serv } from '@h-ai/serv'
+
+await crypto.init()
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: { apiPrefix: '/api/v1' },
+  transport: {
+    crypto,
+    // keyExchangePath 默认 '/_hai/key-exchange'
+    // maxClients: 10000,
+  },
+})
+```
+
+客户端：
+
+```typescript
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  transport: { crypto },
+})
+```
+
+若服务端通过 `config/_serv.yml` 自定义了 `transport.keyExchangePath`，客户端也必须传入同一路径：
+
+```typescript
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  transport: {
+    crypto,
+    keyExchangePath: '/custom/key-exchange',
+  },
+})
+```
+
+> 不要导入或暴露子目录内部 transport 工厂；公共装配点只有 `serv.createApp({ transport: { crypto } })`。
+
+**上下文工厂优先级**（`context.session` 填充来源）：
+
+1. 显式 `createContext`（高级场景：多租户、额外字段）
+2. `verifyToken`（逃脱口：使用非 @h-ai/iam 的认证服务）
+3. `iam.session.verifyToken`（推荐：传入 `iam` 后自动启用）
+4. 默认 `parseRequestContext`：仅解析请求元数据，`session` 为 `undefined`
+
+> ⚠️ `verifyToken` 会在每次请求调用（不缓存）；verifyToken 失败或抛错统一收敛为 `session=undefined`，由 `requireAuth` 统一返回 401。
+
+### Procedure 包装器（所有导出为 `serv.xxx` 扁平 API）
+
+| 函数 | 说明 |
+| --- | --- |
+| `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`（`'*'`） |
+| `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 消息（请求级本地化） |
+
+```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)
+)
+```
+
+### 高级：自定义 pipeline（HTTP middleware + context + procedure wrapper）
+
+`@h-ai/serv` 的 pipeline 分三层：
+
+1. **HTTP middleware 层**：通过 `serv.createApp({ middlewares })` 注入 Hono middleware
+2. **context 层**：通过 `verifyToken` / `createContext` / `serv.buildAuthContextFactory()` 自定义请求上下文
+3. **procedure wrapper 层**：通过 `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 自定义业务包装器
+
+#### HTTP middleware
+
+适用于请求日志、trace、限流、CORS、租户头校验等 **HTTP 层** 横切逻辑：
+
+```typescript
+import type { ServMiddleware } from '@h-ai/serv'
+
+const requestMetrics: ServMiddleware = async (c, next) => {
+  const startedAt = Date.now()
+  await next()
+  c.header('x-response-time-ms', String(Date.now() - startedAt))
+}
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: { apiPrefix: '/api/v1' },
+  middlewares: [
+    { middleware: requestMetrics },
+    {
+      path: '/api/v1/*',
+      middleware: async (c, next) => {
+        if (!c.req.header('x-tenant-id'))
+          return c.text('Missing x-tenant-id', 400)
+        await next()
+      },
+    },
+  ],
+})
+```
+
+执行顺序固定为：`securityHeaders` → `transport`（若启用）→ `middlewares` → health/refresh-cookie/OpenAPI/RPC/docs/oRPC routes。
+
+#### Context pipeline
+
+如果想复用“Bearer token → session”这段逻辑，再追加租户/工作区等字段，优先：
+
+```typescript
+const baseContext = serv.buildAuthContextFactory(token => iam.session.verifyToken(token))
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  createContext: async ({ request }) => {
+    const context = await baseContext({ request })
+    return {
+      ...context,
+      tenantId: request.headers.get('x-tenant-id') ?? null,
+    }
+  },
+})
+```
+
+选择建议：
+
+- 只换 token 校验实现：`verifyToken`
+- 在默认认证上下文之上追加字段：`buildAuthContextFactory(...) + createContext`
+- 完全接管上下文构造：`createContext`
+
+#### Procedure wrapper
+
+适用于已进入 procedure 后的审计、租户约束、业务 guard：
+
+```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)),
+    ),
+  ),
+)
+```
+
+说明：
+
+- `ServMiddleware` / `ServMiddlewareMount` / `ServProcedureWrapper` / `ServGuardedProcedureWrapper` 等共享类型由根入口 `@h-ai/serv` 对外暴露
+- `src/pipelines/*` 是模块内部默认实现目录，不作为公开子路径 API 文档承诺
+- 常规场景优先继续用 `serv.requireAuth / requirePermission / requireRole / mapHaiError`
+
+### 正常业务请求中的错误与 i18n
+
+按三层处理：
+
+1. **oRPC contract 输入校验**：进入 handler 前自动发生；`serv.createApp()` 会把默认英文 Zod 错误改写为本地化 `errors[]`。
+2. **handler 内二次校验**：对跨字段规则、数据库回读对象等适合 Zod 表达的场景，使用 `serv.validateInputOrFail(zodSchema, input, context.locale)`；简单业务规则直接 `err(...)` 即可。
+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)
+})
+```
+
+> 如果错误来自下游模块（如 `iam` / `storage`）并且该模块已经返回 `HaiResult`，serv 默认**透传**它的 `error.message`。由于 `HaiError` 目前不携带 `messageKey/params`，serv 边界不能对任意下游错误再做通用重翻译；要做请求级 i18n，必须在创建该错误的模块/feature 里就拿到 locale。
+
+### `serv.parseRequestContext` — 默认 Context 解析器
+
+从 HTTP 请求头自动解析：
+
+| 字段 | 来源 |
+| --- | --- |
+| `accessToken` | `Authorization: Bearer <token>` |
+| `requestId` | `x-request-id` 或自动生成 UUID |
+| `ip` | `x-forwarded-for` / `x-real-ip` |
+| `locale` | `accept-language` |
+| `userAgent` | `user-agent` |
+
+### `serv.generateSpec(contract, options)` — 生成 OpenAPI 文档
+
+```typescript
+const spec = await serv.generateSpec(contract, {
+  title: 'My API',
+  version: '1.0.0',
+  apiPrefix: '/api/v1',
+  description: '接口说明',
+})
+// spec 为 OpenAPI 3.1 Document 对象
+```
+
+---
+
+## HTTP 配置（`ServHttpConfigInput`）
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `apiPrefix` | `'/api/v1'` | oRPC OpenAPI handler 挂载前缀 |
+| `health` | `{ path: '/health', readyPath: '/ready' }` | 健康与就绪检查端点 |
+| `openapi` | `false` | OpenAPI JSON endpoint，显式开启 |
+| `docs` | `false` | Scalar 文档页，显式开启；启用后自动挂载 `/_hai/scalar.js` 本地脚本路由 |
+| `rpc` | `false` | 内部 RPC endpoint，显式开启；`loopback` / `private-network` 基于真实连接 IP，网关场景用 `gateway-only` |
+| `transport` | `undefined` | 顶层配置；启用后默认挂载 `{apiPrefix}/_hai/key-exchange` |
+
+```typescript
+http: {
+  apiPrefix: '/api/v1',
+  openapi: { path: '/openapi.json' },
+  docs: { path: '/docs' },
+  health: { path: '/health', readyPath: '/ready' },
+  rpc: false, // 关闭内部 RPC
+}
+```
+
+---
+
+## Feature Procedures（默认实现）
+
+`@h-ai/serv` 内置了三个 feature 模块，开箱即用：
+
+| 导入路径 | 工厂函数 | 所需依赖 |
+| --- | --- | --- |
+| `@h-ai/serv/features/iam` | `createIamProcedures({ iam })` | `@h-ai/iam` |
+| `@h-ai/serv/features/storage` | `createStorageProcedures({ storage })` | `@h-ai/storage` |
+| `@h-ai/serv/features/ai` | `createAiProcedures({ ai })` | `@h-ai/ai` |
+
+---
+
+## 常见模式
+
+### 自定义领域 procedure
+
+```typescript
+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))
+      }),
+    },
+  }
+}
+```
+
+### 自定义 contract 组合
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { widgetContract } from './widget-contract.js'
+
+export const myAppContract = apiContract.create({
+  iam: apiContract.iam,
+  widget: widgetContract,
+})
+
+const app = serv.createApp({
+  contract: myAppContract,
+  procedures: {
+    iam: createIamProcedures({ iam }),
+    widget: createMyProcedures(),
+  },
+  http: { apiPrefix: '/api/v1' },
+})
+```
+
+---
+
+## 错误码
+
+procedure 包装器内置以下错误：
+
+| 错误码 | 触发条件 |
+| --- | --- |
+| `HaiCommonError.UNAUTHORIZED` | `requireAuth`：`context.session` 为空（无 token 或 token 校验失败） |
+| `HaiCommonError.FORBIDDEN` | `requirePermission`：无对应权限 |
+| `HaiCommonError.INTERNAL_ERROR` | `mapHaiError`：procedure 抛出未处理异常 |
+
+---
+
+## httpOnly Cookie 认证
+
+将 refresh token 存储在 `HttpOnly` cookie 中，避免 XSS 风险（浏览器 JS 无法读取）。
+
+先区分两个 token：
+
+- `accessToken`：短期凭证，客户端放在内存，通过 `Authorization: Bearer <token>` 发送；
+  `serv.parseRequestContext()` / `extractBearerToken()` 解析、`buildAuthContextFactory()` 校验的就是它。
+- `refreshToken`：长期凭证，启用 `refreshCookie` 后只保存在 httpOnly cookie；
+  它不会走 `Authorization`，也不会被 `extractBearerToken()` 读取，只会在 `/auth/refresh` 被服务端取出。
+
+### 适用场景
+
+- 浏览器端（Web / H5）使用 `@h-ai/api-client` 的 `apiClient.tokenStorage.httpOnlyCookie()`
+- 对 refresh token 有更高安全要求，不希望存储在 localStorage
+
+### 工作流程
+
+1. 浏览器 POST `/auth/login` → serv 拦截 oRPC 成功响应 → `Set-Cookie: hai_refresh_token=...;HttpOnly;SameSite=Strict`，并从 JSON 响应体擦除 `refreshToken`
+2. Access token 由客户端存内存（不持久化）
+3. Access token 过期 → 客户端 POST `/auth/refresh`（浏览器自动携带 cookie）
+4. serv 读取 cookie → 调用 `iam.session.refresh` → 返回新 access token + 更新 cookie（响应体不暴露 refresh token）
+5. POST `/auth/logout` → serv 清除 cookie（`Max-Age=0`）
+
+若同时启用 `transport: { crypto }`，`/auth/refresh` 也必须走加密链路；cookie-only 刷新请求允许空 body，服务端不要把 `Request.body === null` 误判为需要解密的请求体。
+
+### 配置
+
+```typescript
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: { apiPrefix: '/api/v1' },
+  iam,                                  // 顶层句柄：同时驱动 verifyToken 与 refresh
+  refreshCookie: {
+    // cookieName?: string              默认 'hai_refresh_token'
+    // maxAge?: number                  默认 30 * 24 * 3600（30 天）
+    // secure?: boolean                 默认 NODE_ENV=production 时开启
+    // onRefresh?: (token) => ...       可选：覆盖默认的 iam.session.refresh
+  },
+  // ✅ 顶层 iam 同时为 access token 校验提供默认实现，无需再传 verifyToken
+})
+```
+
+> **逃脱口**：不使用 `@h-ai/iam` 时，可显式传入顶层 `verifyToken: token => myAuthService.verify(token)`。
+
+### Cookie 规格
+
+| 属性 | 值 |
+| --- | --- |
+| Name | `hai_refresh_token`（可配置） |
+| Path | `{apiPrefix}/auth/refresh`（最小范围） |
+| HttpOnly | ✓ |
+| SameSite | `Strict` |
+| Secure | 生产自动开启，`secure: false` 可在 HTTP 开发环境关闭 |
+| Max-Age | 30 天（可配置） |
+
+---
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/serv test
+pnpm --filter @h-ai/serv typecheck
+pnpm --filter @h-ai/serv lint
+```