@h-ai/cli 0.1.0-alpha.42 → 0.1.0-alpha.43

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.42",
+  "version": "0.1.0-alpha.43",
   "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.42"
+    "@h-ai/core": "0.1.0-alpha.43"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/apps/api/apps/{{projectName}}-contract/README.md.hbs

@@ -4,10 +4,12 @@
 
 ## 包含内容
 
-- `app-contract.ts`：应用级路由定义
-- `app-schemas.ts`：输入输出 Zod schema
+- `app-contract.ts`：应用级接口定义，业务 path 与一次性输出 Schema 就近内联
+- `app-schemas.ts`：跨接口、跨层复用的输入/数据 Zod Schema
 - `{{projectName}}-contract.ts`：工程级 contract 聚合入口
 
+API 前缀、健康检查与跨端 Header 等传输配置位于 service 的 `config/_serv.yml`。
+
 ## 常用命令
 
 ```bash

package/templates/apps/api/apps/{{projectName}}-contract/src/app-contract.ts.hbs

@@ -1,5 +1,5 @@
 import { apiContract } from '@h-ai/api-contract'
-import { AppEchoInputSchema, AppEchoOutputSchema, AppInfoOutputSchema } from './app-schemas.js'
+import { AppEchoInputSchema, AppEchoOutputDataSchema, AppInfoOutputDataSchema } from './app-schemas.js'
 
 /** 应用自有 app contract。 */
 export const appContract = {
@@ -11,7 +11,7 @@ export const appContract = {
       summary: 'Get service info',
       tags: ['app'],
     })
-    .output(AppInfoOutputSchema),
+    .output(apiContract.haiResultSchema(AppInfoOutputDataSchema)),
   echo: apiContract
     .route({
       method: 'POST',
@@ -21,7 +21,7 @@ export const appContract = {
       tags: ['app'],
     })
     .input(AppEchoInputSchema)
-    .output(AppEchoOutputSchema),
+    .output(apiContract.haiResultSchema(AppEchoOutputDataSchema)),
 }
 
 export type AppContract = typeof appContract

package/templates/apps/api/apps/{{projectName}}-contract/src/app-schemas.ts.hbs

@@ -1,4 +1,3 @@
-import { apiContract } from '@h-ai/api-contract'
 import { z } from 'zod'
 
 /** 服务元信息响应数据。 */
@@ -9,9 +8,6 @@ export const AppInfoOutputDataSchema = z.object({
   transportEnabled: z.boolean(),
 })
 
-/** app.info 标准 HaiResult 输出。 */
-export const AppInfoOutputSchema = apiContract.haiResultSchema(AppInfoOutputDataSchema)
-
 /** 输入：单条文本消息（演示用，限制最大长度防止误用）。 */
 export const AppEchoInputSchema = z.object({
   message: z.string().min(1).max(2000),
@@ -25,9 +21,6 @@ export const AppEchoOutputDataSchema = z.object({
   userId: z.string().optional(),
 })
 
-/** app.echo 标准 HaiResult 输出。 */
-export const AppEchoOutputSchema = apiContract.haiResultSchema(AppEchoOutputDataSchema)
-
 export type AppInfoOutputData = z.infer<typeof AppInfoOutputDataSchema>
 export type AppEchoInput = z.infer<typeof AppEchoInputSchema>
 export type AppEchoOutputData = z.infer<typeof AppEchoOutputDataSchema>

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

@@ -13,6 +13,23 @@ http:
     readyPath: /ready
   rpc: false
 
+cors:
+  origin: ${HAI_CORS_ORIGIN:*}
+  nativeOrigins: ${HAI_NATIVE_ORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+{{#if features.iam}}  credentials: true
+{{else}}  credentials: false
+{{/if}}  allowedHeaders:
+    - Authorization
+    - Content-Type
+{{#if features.crypto}}    - X-Client-Id
+    - X-Encrypted
+{{/if}}    - X-Hai-Locale
+    - X-Request-Id
+    - X-Requested-With
+  exposedHeaders:
+{{#if features.crypto}}    - X-Encrypted
+{{/if}}    - X-Request-Id
+
 {{#if features.crypto}}transport:
   keyExchangePath: /_hai/key-exchange
   excludePaths:
@@ -23,4 +40,4 @@ http:
     - /_hai/scalar.js
   maxClients: 10000
 {{else}}transport: false
-{{/if}}
+{{/if}}

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

@@ -1,6 +1,6 @@
 import type { ServConfig } from '@h-ai/serv'
 import { core } from '@h-ai/core'
-{{#if features.crypto}}import { crypto, TRANSPORT_PROTOCOL } from '@h-ai/crypto'
+{{#if features.crypto}}import { crypto } from '@h-ai/crypto'
 {{/if}}{{#if features.iam}}import { iam } from '@h-ai/iam'
 {{/if}}import { serv } from '@h-ai/serv'
 import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
@@ -14,26 +14,18 @@ interface CreateApiServiceAppOptions {
   refreshCookie?: 'enabled' | 'disabled'
 }
 
-const LOOPBACK_ORIGIN_RE = /^https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/
-const WEBVIEW_ORIGINS = new Set([
-  'capacitor://localhost',
-  'http://localhost',
-  'https://tauri.localhost',
-  'tauri://localhost',
-])
-const DEFAULT_CORS_ALLOWED_HEADERS = [
-  'Authorization',
-  'Content-Type',
-{{#if features.crypto}}  TRANSPORT_PROTOCOL.CLIENT_ID_HEADER,
-  TRANSPORT_PROTOCOL.ENCRYPTED_HEADER,
-{{/if}}  'X-Hai-Locale',
-  'X-Request-Id',
-  'X-Requested-With',
-]
-
+interface AppCoreConfig {
+  readonly env?: string
+}
 /** 创建 API Service HTTP 应用。 */
 export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptions = {}) {
   const servConfig = core.config.getOrThrow<ServConfig>('serv')
+  const coreConfig = core.config.get<AppCoreConfig>('core')
+  const security = serv.createRuntimeSecurityPolicy({
+    environment: coreConfig?.env,
+    corsOrigin: servConfig.cors.origin,
+    nativeOrigins: servConfig.cors.nativeOrigins,
+  })
 {{#if features.crypto}}  const transportMode = _options.transport ?? 'config'
   const transport = transportMode === 'disabled' || servConfig.transport === false
     ? undefined
@@ -46,7 +38,7 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
 {{else}}  const transport = undefined
 {{/if}}
 {{#if features.iam}}
-  const refreshCookie = _options.refreshCookie === 'disabled' ? undefined : {}
+  const refreshCookie = _options.refreshCookie === 'disabled' ? undefined : { secure: security.secureRefreshCookie }
 {{/if}}
 
   const appOptions: Parameters<typeof serv.createApp>[0] = {
@@ -61,17 +53,21 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
         startedAt,
       },
     }),
-    http: servConfig.http,
+    http: {
+      ...servConfig.http,
+      openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
+      docs: security.exposeApiDocs ? servConfig.http.docs : false,
+    },
 {{#if features.iam}}
     iam,
 {{/if}}
     middlewares: [
       {
         middleware: serv.cors({
-          origin: origin => resolveCorsOrigin(origin) !== null,
-{{#if features.iam}}          credentials: true,
-{{/if}}          allowedHeaders: DEFAULT_CORS_ALLOWED_HEADERS,{{#if features.crypto}}
-          exposedHeaders: [TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, 'X-Request-Id'],{{/if}}
+          origin: security.allowOrigin,
+          credentials: servConfig.cors.credentials,
+          allowedHeaders: [...servConfig.cors.allowedHeaders],
+          exposedHeaders: [...servConfig.cors.exposedHeaders],
         }),
       },
     ],
@@ -86,13 +82,3 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
 
   return serv.createApp(appOptions)
 }
-
-function resolveCorsOrigin(origin: string | undefined): string | null {
-  if (!origin)
-    return null
-  if (WEBVIEW_ORIGINS.has(origin))
-    return origin
-  if (LOOPBACK_ORIGIN_RE.test(origin))
-    return origin
-  return null
-}

package/templates/apps/api/apps/{{projectName}}-service/tests/service.test.ts.hbs

@@ -1,3 +1,4 @@
+import type { ServConfig } from '@h-ai/serv'
 import type { AddressInfo } from 'node:net'
 import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -20,6 +21,7 @@ let tempRoot = ''
 let baseUrl = ''
 let client: ReturnType<typeof apiClient.create<typeof {{api.contractExportName}}>>
 let server: ReturnType<typeof serv.listen>
+let servConfig: ServConfig
 {{#if features.storage}}let storageRoot = ''
 {{/if}}{{#if features.vecdb}}let vecdbRoot = ''
 {{/if}}
@@ -45,6 +47,7 @@ beforeAll(async () => {
     configDir: './config',
     logging: { level: 'warn' },
   })
+  servConfig = core.config.getOrThrow<ServConfig>('serv')
 {{#if features.db}}
 
   const dbResult = await reldb.init({ type: 'sqlite', database: ':memory:' })
@@ -93,7 +96,7 @@ beforeAll(async () => {
 
   client = apiClient.create({{api.contractExportName}})
   const initResult = await client.init({
-    baseUrl: `${baseUrl}/api/v1`,
+    baseUrl: `${baseUrl}${servConfig.http.apiPrefix}`,
     auth: { storage: apiClient.tokenStorage.memory() },
   })
   if (!initResult.success)
@@ -114,7 +117,9 @@ afterAll(async () => {
 
 describe('{{api.servicePackageName}}', () => {
   it('returns health status', async () => {
-    const response = await fetch(`${baseUrl}/health`)
+    if (servConfig.http.health === false)
+      throw new Error('service test requires health endpoint')
+    const response = await fetch(`${baseUrl}${servConfig.http.health.path}`)
 
     expect(response.status).toBe(200)
     await expect(response.json()).resolves.toEqual({ status: 'ok' })

package/templates/apps/api/e2e/api-service.spec.ts.hbs

@@ -1,4 +1,8 @@
 import { expect, test } from '@playwright/test'
+import { apiContract } from '@h-ai/api-contract'
+import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
+
+const API_PREFIX = '/api/v1'
 
 test('service health endpoint returns ok', async ({ request }) => {
   const response = await request.get('/health')
@@ -8,7 +12,7 @@ test('service health endpoint returns ok', async ({ request }) => {
 })
 
 test('service app.info endpoint returns HaiResult', async ({ request }) => {
-  const response = await request.post('/api/v1/app/info')
+  const response = await request.post(`${API_PREFIX}${apiContract.pathOf({{api.contractExportName}}.app.info)}`)
   const body = await response.json()
 
   expect(response.status()).toBe(200)

package/templates/apps/api/package.json.hbs

@@ -15,6 +15,10 @@
     "test:e2e": "pnpm build && playwright test",
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
   },
+  "dependencies": {
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+    "{{api.contractPackageName}}": "workspace:*"
+  },
   "devDependencies": {
     "@antfu/eslint-config": "{{api.packageSpecifiers.antfuEslintConfig}}",
     "@playwright/test": "{{api.packageSpecifiers.playwright}}",

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -1,17 +1,19 @@
 import { expect, test } from '@playwright/test'
-import { APP_API_ROUTES } from '{{fullstack.contractPackageName}}'
+import { apiContract } from '@h-ai/api-contract'
+import { {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
 
 const DEFAULT_SERVICE_BASE_URL = 'http://127.0.0.1:3000'
 const apiBaseUrl = process.env.SERVICE_BASE_URL || DEFAULT_SERVICE_BASE_URL
+const apiPrefix = '/api/v1'
 
 test('service health endpoint is ready', async ({ request }) => {
-  const response = await request.get(apiBaseUrl + APP_API_ROUTES.health)
+  const response = await request.get(`${apiBaseUrl}/health`)
   expect(response.ok()).toBe(true)
   await expect(response).toBeOK()
 })
 
 test('service echo endpoint returns HaiResult', async ({ request }) => {
-  const response = await request.post(apiBaseUrl + APP_API_ROUTES.echo, {
+  const response = await request.post(`${apiBaseUrl}${apiPrefix}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, {
     data: { message: 'hello e2e' },
   })
   expect(response.ok()).toBe(true)

package/templates/apps/fullstack/package.json.hbs

@@ -20,6 +20,7 @@
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
   },
   "dependencies": {
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
     "{{fullstack.contractPackageName}}": "workspace:*",
     "{{fullstack.sharedPackageName}}": "workspace:*"
   },

package/templates/apps/fullstack/packages/{{projectName}}-contract/README.md.hbs

@@ -1,14 +1,16 @@
 # {{fullstack.contractPackageName}}
 
-共享 API 契约包，包含前后端共用的路径常量、Zod Schema、`apiContract.route()` 路由定义与工程级 contract。
+共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。
 
 ## 骨架说明
 
-- `src/app-routes.ts`：HTTP 路径常量，供 service、frontend 与 E2E 复用。
-- `src/app-schemas.ts`：输入输出 Schema 与类型。
-- `src/app-contract.ts`：app 领域 contract 路由定义。
+- `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
+- `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
 - `src/{{projectName}}-contract.ts`：工程级 contract，供 `@h-ai/serv` 与 `@h-ai/api-client` 共用。
 
+只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时才保留私有常量。
+API 前缀、健康检查与跨端 Header 等传输配置位于 serv 包的 `config/_serv.yml`。
+
 ## 开发
 
 - `pnpm --filter {{fullstack.contractPackageName}} typecheck`

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/app-contract.ts.hbs

@@ -1,21 +1,20 @@
 import { apiContract } from '@h-ai/api-contract'
-import { APP_CONTRACT_ROUTES } from './app-routes.js'
-import { AppEchoInputSchema, AppEchoOutputSchema, AppInfoOutputSchema } from './app-schemas.js'
+import { AppEchoInputSchema, AppEchoOutputDataSchema, AppInfoOutputDataSchema } from './app-schemas.js'
 
 /** app 领域 API contract：路径、方法、输入输出 Schema 的单一来源。 */
 export const appContract = {
   info: apiContract.route({
     method: 'POST',
-    path: APP_CONTRACT_ROUTES.info,
+    path: '/app/info',
     operationId: 'app.info',
     tags: ['app'],
     summary: 'Get application runtime information',
-  }).output(AppInfoOutputSchema),
+  }).output(apiContract.haiResultSchema(AppInfoOutputDataSchema)),
   echo: apiContract.route({
     method: 'POST',
-    path: APP_CONTRACT_ROUTES.echo,
+    path: '/app/echo',
     operationId: 'app.echo',
     tags: ['app'],
     summary: 'Echo a message through the generated service route',
-  }).input(AppEchoInputSchema).output(AppEchoOutputSchema),
-}
+  }).input(AppEchoInputSchema).output(apiContract.haiResultSchema(AppEchoOutputDataSchema)),
+}

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/app-schemas.ts.hbs

@@ -1,4 +1,4 @@
-import { apiContract } from '@h-ai/api-contract'
+import type { HaiResult } from '@h-ai/core'
 import { z } from 'zod'
 
 export const AppFrontendTargetSchema = z.enum(['web', 'app', 'miniapp', 'desktop'])
@@ -23,12 +23,9 @@ export const AppEchoOutputDataSchema = z.object({
   requestId: z.string(),
 })
 
-export const AppInfoOutputSchema = apiContract.haiResultSchema(AppInfoOutputDataSchema)
-export const AppEchoOutputSchema = apiContract.haiResultSchema(AppEchoOutputDataSchema)
-
 export type AppFrontendTarget = z.infer<typeof AppFrontendTargetSchema>
 export type AppInfoOutputData = z.infer<typeof AppInfoOutputDataSchema>
-export type AppInfoOutput = z.infer<typeof AppInfoOutputSchema>
+export type AppInfoOutput = HaiResult<AppInfoOutputData>
 export type AppEchoInput = z.infer<typeof AppEchoInputSchema>
 export type AppEchoOutputData = z.infer<typeof AppEchoOutputDataSchema>
-export type AppEchoOutput = z.infer<typeof AppEchoOutputSchema>
+export type AppEchoOutput = HaiResult<AppEchoOutputData>

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

@@ -1,4 +1,3 @@
 export * from './app-contract.js'
-export * from './app-routes.js'
 export * from './app-schemas.js'
 export * from './{{projectName}}-contract.js'

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

@@ -1,9 +1,12 @@
 import { apiContract } from '@h-ai/api-contract'
 import { appContract } from './app-contract.js'
 
+/** 当前工程启用的前端目标。 */
+export const ENABLED_FRONTENDS = {{{fullstack.selectedFrontendsJson}}} as const
+
 /** 工程级 API contract，前端 typed client 与后端 service 共用。 */
 export const {{fullstack.contractExportName}} = apiContract.create({
   app: appContract,
 })
 
-export type FullstackContract = typeof {{fullstack.contractExportName}}
+export type FullstackContract = typeof {{fullstack.contractExportName}}

package/templates/apps/fullstack/packages/{{projectName}}-contract/tests/contract.test.ts.hbs

@@ -1,10 +1,9 @@
+import { apiContract } from '@h-ai/api-contract'
 import { describe, expect, it } from 'vitest'
 import {
-  APP_API_ROUTES,
   appContract,
   AppEchoInputSchema,
   AppInfoOutputDataSchema,
-  AppInfoOutputSchema,
   ENABLED_FRONTENDS,
   {{fullstack.contractExportName}},
 } from '../src/index.js'
@@ -13,7 +12,7 @@ describe('{{fullstack.contractPackageName}}', () => {
   it('defines app contract routes', () => {
     expect({{fullstack.contractExportName}}.app).toBeDefined()
     expect(appContract.info).toBeDefined()
-    expect(APP_API_ROUTES.info).toBe('/api/v1/app/info')
+    expect(apiContract.pathOf(appContract.info)).toBe('/app/info')
   })
 
   it('validates app info payload', () => {
@@ -31,18 +30,4 @@ describe('{{fullstack.contractPackageName}}', () => {
     expect(AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
     expect(AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
   })
-
-  it('validates HaiResult app info response', () => {
-    const result = AppInfoOutputSchema.safeParse({
-      success: true,
-      data: {
-        name: '{{fullstack.servPackageName}}',
-        version: '0.1.0',
-        startedAt: '2026-01-01T00:00:00.000Z',
-        frontends: [...ENABLED_FRONTENDS],
-      },
-    })
-
-    expect(result.success).toBe(true)
-  })
 })

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

@@ -2,12 +2,30 @@
 # {{fullstack.servPackageName}} - Serv / HTTP 入口配置
 # =============================================================================
 #
-# HTTP 路由路径（apiPrefix / health / openapi / docs）由共享 contract
-# 统一定义，作为前后端唯一事实来源，因此不在此重复声明。
-# 本文件仅声明服务端运行时设置。
+# 业务接口路径直接写在对应 *-contract.ts；公共 HTTP 传输配置以本文件为准。
 # =============================================================================
 
-# CORS 允许的来源。
-# 开发环境放开为 *，生产环境应收敛为前端域名（如 https://app.example.com）。
+http:
+  apiPrefix: /api/v1
+  openapi:
+    path: /openapi.json
+  docs:
+    path: /docs
+  health:
+    path: /health
+    readyPath: /ready
+  rpc: false
+
 cors:
   origin: ${HAI_CORS_ORIGIN:*}
+  nativeOrigins: ${HAI_NATIVE_ORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+  credentials: false
+  allowedHeaders:
+    - Authorization
+    - Content-Type
+    - X-Request-Id
+    - X-Requested-With
+  exposedHeaders:
+    - X-Request-Id
+
+transport: false

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

@@ -1,6 +1,7 @@
+import type { ServConfigInput } from '@h-ai/serv'
 import { core } from '@h-ai/core'
-import { serv } from '@h-ai/serv'
-import { APP_HTTP_ROUTES, ENABLED_FRONTENDS, {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
+import { serv, ServConfigSchema } from '@h-ai/serv'
+import { ENABLED_FRONTENDS, {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
 import { createServerProcedures } from './server/procedures/index.js'
 
 const STARTED_AT = new Date().toISOString()
@@ -9,11 +10,7 @@ const STARTED_AT = new Date().toISOString()
 interface AppCoreConfig {
   name?: string
   version?: string
-}
-
-/** `_serv.yml` 中的服务端运行时设置。 */
-interface AppServConfig {
-  cors?: { origin?: string }
+  env?: string
 }
 
 /** 应用侧最小 HTTP App 抽象；不把底层 Hono 类型暴露给项目代码。 */
@@ -27,10 +24,14 @@ export function createServerApp(): ServerApp {
   // 配置来自 config/_core.yml 与 config/_serv.yml。
   // 单元测试可不初始化 core，此时回退到内置默认值。
   const coreConfig = core.config.get<AppCoreConfig>('core')
-  const servConfig = core.config.get<AppServConfig>('serv')
+  const servConfig = ServConfigSchema.parse(core.config.get<ServConfigInput>('serv') ?? {})
   const appName = coreConfig?.name ?? '{{fullstack.servPackageName}}'
   const appVersion = coreConfig?.version ?? '0.1.0'
-  const corsOrigin = servConfig?.cors?.origin ?? '*'
+  const security = serv.createRuntimeSecurityPolicy({
+    environment: coreConfig?.env,
+    corsOrigin: servConfig.cors.origin,
+    nativeOrigins: servConfig.cors.nativeOrigins,
+  })
 
   return serv.createApp({
     contract: {{fullstack.contractExportName}},
@@ -43,19 +44,16 @@ export function createServerApp(): ServerApp {
       },
     }),
     http: {
-      apiPrefix: APP_HTTP_ROUTES.apiPrefix,
-      health: {
-        path: APP_HTTP_ROUTES.health,
-        readyPath: APP_HTTP_ROUTES.ready,
-      },
-      openapi: { path: APP_HTTP_ROUTES.openapi },
-      docs: { path: APP_HTTP_ROUTES.docs },
-      rpc: false,
+      ...servConfig.http,
+      openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
+      docs: security.exposeApiDocs ? servConfig.http.docs : false,
     },
     middlewares: [{
       middleware: serv.cors({
-        origin: corsOrigin,
-        allowedHeaders: ['Authorization', 'Content-Type', 'X-Requested-With'],
+        origin: security.allowOrigin,
+        credentials: servConfig.cors.credentials,
+        allowedHeaders: [...servConfig.cors.allowedHeaders],
+        exposedHeaders: [...servConfig.cors.exposedHeaders],
       }),
     }],
   })

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

@@ -1,11 +1,14 @@
-import { APP_API_ROUTES } from '{{fullstack.contractPackageName}}'
+import { apiContract } from '@h-ai/api-contract'
+import { {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
 import { describe, expect, it } from 'vitest'
 import { createServerApp } from '../src/app-server.js'
 
+const API_PREFIX = '/api/v1'
+
 describe('{{fullstack.servPackageName}}', () => {
   it('returns health status', async () => {
     const app = createServerApp()
-    const response = await app.request(APP_API_ROUTES.health)
+    const response = await app.request('/health')
 
     expect(response.status).toBe(200)
     await expect(response.json()).resolves.toEqual({ status: 'ok' })
@@ -13,7 +16,7 @@ describe('{{fullstack.servPackageName}}', () => {
 
   it('returns app info as HaiResult', async () => {
     const app = createServerApp()
-    const response = await app.request(APP_API_ROUTES.info, { method: 'POST' })
+    const response = await app.request(`${API_PREFIX}${apiContract.pathOf({{fullstack.contractExportName}}.app.info)}`, { method: 'POST' })
     const body = await response.json()
 
     expect(response.status).toBe(200)
@@ -23,7 +26,7 @@ describe('{{fullstack.servPackageName}}', () => {
 
   it('validates echo input', async () => {
     const app = createServerApp()
-    const response = await app.request(APP_API_ROUTES.echo, {
+    const response = await app.request(`${API_PREFIX}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ message: '' }),
@@ -34,7 +37,7 @@ describe('{{fullstack.servPackageName}}', () => {
 
   it('returns echo result as HaiResult', async () => {
     const app = createServerApp()
-    const response = await app.request(APP_API_ROUTES.echo, {
+    const response = await app.request(`${API_PREFIX}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ message: 'hello unit' }),

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/api/api-client.ts.hbs

@@ -1,6 +1,6 @@
 import type { AppInfoOutputData } from '{{fullstack.contractPackageName}}'
 import { apiClient } from '@h-ai/api-client'
-import { APP_HTTP_ROUTES, {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
+import { {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
 
 export type AppInfo = AppInfoOutputData
 
@@ -43,9 +43,9 @@ function resolveDefaultApiOrigin(): string {
 
 function normalizeApiBaseUrl(value: string): string {
   const trimmed = trimTrailingSlash(value)
-  return trimmed.endsWith(APP_HTTP_ROUTES.apiPrefix)
+  return trimmed.endsWith('/api/v1')
     ? trimmed
-    : `${trimmed}${APP_HTTP_ROUTES.apiPrefix}`
+    : `${trimmed}/api/v1`
 }
 
 function trimTrailingSlash(value: string): string {

package/templates/apps/mobile-app/src/lib/api.ts.hbs

@@ -33,7 +33,6 @@ export async function initApi(): Promise<void> {
     baseUrl: resolveApiBase(),
     auth: {
       storage: await createTokenStorage(),
-      refreshPath: '/auth/refresh',
     },
   })
 
@@ -51,4 +50,4 @@ export async function closeApi(): Promise<void> {
   initialized = false
 }
 
-export { apiClient }
+export { apiClient }

package/templates/base/e2e/app.spec.ts.hbs

@@ -2,6 +2,9 @@ import { expect, test } from '@playwright/test'
 
 /** 首页从真实浏览器页面发起，覆盖基础渲染链路。 */
 test('home page renders from browser', async ({ page }) => {
+  const pageErrors: string[] = []
+  page.on('pageerror', error => pageErrors.push(error.message))
   await page.goto('/')
+  await expect(pageErrors).toEqual([])
   await expect(page.locator('main, section').first()).toBeVisible()
-})
+})

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.42",
+  "version": "0.1.0-alpha.43",
   "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

@@ -279,11 +279,13 @@ for await (const ev of m.chatStream('展开讲讲', { signal: controller.signal
 
 ## 语音（Audio）
 
-`ai.audio` 提供 ASR/TTS，Provider（OpenAI / MiMo / Qwen / 豆包）作为内部实现，凭据未配置时回退平台环境变量。调用方只表达「音频还是文本、完整还是流式」，不感知 WebSocket / SSE / 厂商事件。
+`ai.audio` 提供 ASR/TTS，Provider（OpenAI / MiMo / Qwen / 豆包）作为内部实现，凭据未配置时回退平台环境变量。调用方只表达「音频还是文本、完整还是流式」，不感知 WebSocket / SSE / 厂商事件。LLM 与语音模型确认共用凭据时，可显式设置 `inheritLlmApiKey: true`；该选项默认关闭，避免跨供应商误用密钥。
 
 ```yaml
 # ai.init 配置片段
 audio:
+  # 仅当语音服务与 LLM 确认共用同一密钥时启用
+  inheritLlmApiKey: true
   models:
     - { id: asr, provider: qwen, model: qwen3-asr-flash-realtime, operations: [transcribe] }
     - { id: tts, provider: qwen, model: qwen3-tts-flash-realtime, operations: [synthesize] }
@@ -332,6 +334,8 @@ image:
   generateModel: free
 ```
 
+LLM、Audio、Image 的可选密钥统一使用 `OptionalSecretSchema`：配置中的 YAML `null`、空字符串和纯空白字符串均表示未配置。语音密钥优先级为模型条目 → 启用继承后的 LLM 密钥 → 平台环境变量，业务启动代码不应再遍历配置修补 `apiKey`。
+
 ```ts
 const image = await ai.image.generate({
   prompt: '水墨风格的未来城市，清晨薄雾',

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

@@ -179,8 +179,8 @@ const result = await ai.rag.query('核心架构是什么？', {
 
 - 音频类型：`AudioContent { data: Uint8Array, format: 'pcm16'|'wav'|'mp3'|'opus', sampleRate?, channels? }`；`pcm16` 等裸音频必须传 `sampleRate`。
 - 请求可选：识别 `contextHints?: string[]`（热词/提示）；合成 `instruction?: string`（自然语言风格指令）；均支持 `signal: AbortSignal`。
-- 模型配置：`audio.models: [{ id, provider: 'openai'|'mimo'|'qwen'|'doubao', model, operations, apiKey?, baseUrl?, appKey?, accessKey?, resourceId?, workspaceId? }]`；`operations` 必须明确为识别、合成或两者。
-- 凭据环境变量回退：`HAI_AI_AUDIO_<PROVIDER>_API_KEY` 或 `OPENAI_API_KEY` / `MIMO_API_KEY` / `DASHSCOPE_API_KEY` / `VOLC_API_KEY`（豆包旧版控制台额外 `VOLC_APP_KEY` / `VOLC_ACCESS_KEY`）。
+- 模型配置：`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`、空字符串和纯空白字符串都会规范化为未配置。
 - 资源上限：`audio.maxAudioBytes`（默 10 MiB）、`audio.maxStreamDurationMs`（默 5 分钟）；所有请求支持 `signal: AbortSignal` 打断。
 - Provider 为内部实现，不从根入口导出；不支持的输入方式招 `AUDIO_UNSUPPORTED_INPUT`，不伪装实时。取消 → `AUDIO_CANCELLED`，超时 → `AUDIO_TIMEOUT`，连接失败或 `end` 前异常断连 → `AUDIO_CONNECTION_FAILED`。浏览器客户端（`@h-ai/ai/client`）严格区分正常结束 / 取消 / 异常断连：取消招 `AUDIO_CANCELLED`、`end` 前断连招 `AUDIO_CONNECTION_FAILED`、服务端 error 帧保留其领域错误码，`synthesize` 不把未完成的部分音频当作成功返回。
 

package/templates/skills/hai-api-contract/SKILL.md

@@ -80,7 +80,7 @@ const WidgetCreateInputSchema = z.object({
   description: z.string().optional(),
 })
 
-// 输出 Schema（统一包装为 HaiResult<T>）
+// 同一 contract 内两个接口复用，因此保留为文件私有常量，不从 schemas 导出。
 const WidgetOutputSchema = apiContract.haiResultSchema(z.object({
   id: z.string(),
   name: z.string(),
@@ -196,16 +196,27 @@ myContract.ai.chats.createCompletion  // POST /ai/chats/completion
 import { apiContract } from '@h-ai/api-contract'
 import { z } from 'zod'
 
-const OutputSchema = apiContract.haiResultSchema(z.object({
-  id: z.string(),
-  name: z.string(),
-}))
+const getWidget = apiContract
+  .route({ method: 'GET', path: '/widgets/{id}' })
+  .output(apiContract.haiResultSchema(z.object({
+    id: z.string(),
+    name: z.string(),
+  })))
 
 // 等价于:
 // { success: true, data: { id: string, name: string } }
 // | { success: false, error: HaiError }
 ```
 
+### `apiContract.pathOf(procedure)` — 读取业务路径
+
+```typescript
+const refreshPath = apiContract.pathOf(apiContract.iam.auth.refresh)
+// '/auth/refresh'
+```
+
+middleware、client 与 E2E 需要业务路径时从 contract 元数据读取，不维护第二份 route 常量。服务端挂载时再与 `_serv.yml` 的 `http.apiPrefix` 拼接。
+
 ### 公共 Schema 工具
 
 | 访问路径 | 说明 |
@@ -224,6 +235,11 @@ const OutputSchema = apiContract.haiResultSchema(z.object({
 ### 必须遵循
 
 - **输出必须包装为 `apiContract.haiResultSchema`** — 客户端依赖 `success` 判断成功/失败
+- **业务 path 直接写在对应 `*-contract.ts`** — 禁止新增 `*-routes.ts` 或业务路径常量
+- **一次性 `*OutputSchema` 直接内联** — 不在 schemas 文件声明或导出
+- **同一 contract 内重复使用的输出可设私有常量** — 不得为复用扩大公共导出
+- **公共 HTTP 传输配置以配置文件为准** — API 前缀、健康检查、OpenAPI/docs、密钥协商路径与跨端 Header 放在 service 的 `_serv.yml`，不放 contract 包
+- **schemas 只保留真实复用结构** — 至少被多个接口或 contract/procedure 等不同层共同消费
 - **`operationId` 全局唯一** — 格式为 `domain.resource.action`，如 `iam.auth.login`
 - **`tags` 至少包含领域名** — 供 OpenAPI 文档分组
 - **输入 Schema 用 Zod v4** — 与 `@orpc/zod/zod4` 的 `ZodToJsonSchemaConverter` 配套
@@ -234,6 +250,16 @@ const OutputSchema = apiContract.haiResultSchema(z.object({
 - ❌ Contract 文件中 `import` 任何业务模块（`@h-ai/iam`、`@h-ai/storage` 等）
 - ❌ 在 contract 中使用 `z.any()` 或 `z.unknown()` 作为输出类型
 - ❌ 重复定义已存在的领域 contract
+- ❌ 导出只被单个 contract 接口使用的 `*OutputSchema`
+- ❌ 用独立 `*-routes.ts` 维护业务接口路径
+
+### 文件职责
+
+| 文件 | 只负责 |
+| --- | --- |
+| `*-contract.ts` | 业务接口 path、method、输入与输出边界 |
+| `*-schemas.ts` | 跨接口或跨层复用的输入、实体、数据结构 |
+| service `config/_serv.yml` | API 前缀、基础设施端点、跨端 Header 与加密 transport 配置 |
 
 ---
 
@@ -266,9 +292,9 @@ const getWidget = apiContract
 ### 无输入的端点
 
 ```typescript
-const healthContract = apiContract
-  .route({ method: 'GET', path: '/health', operationId: 'health.check', tags: ['system'] })
-  .output(apiContract.haiResultSchema(z.object({ status: z.string() })))
+const versionContract = apiContract
+  .route({ method: 'GET', path: '/system/version', operationId: 'system.version', tags: ['system'] })
+  .output(apiContract.haiResultSchema(z.object({ version: z.string() })))
 ```
 
 ---

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

@@ -69,7 +69,6 @@ await apiClient.init({
   baseUrl: import.meta.env.PUBLIC_API_BASE,
   auth: {
     storage: createCapacitorTokenStorage(),
-    refreshPath: '/api/v1/auth/refresh',
   },
 })
 ```
@@ -289,7 +288,6 @@ export async function initApi() {
     baseUrl: `${import.meta.env.PUBLIC_API_BASE}/api/v1`,
     auth: {
       storage: createCapacitorTokenStorage(),
-      refreshPath: '/auth/refresh',
     },
   })
 }

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

@@ -136,6 +136,7 @@ unwatch()
 - `${VAR}` — 读取 `process.env.VAR`；缺失则返回 `HaiConfigError.CONFIG_ENV_VAR_MISSING` 错误
 - `${VAR:default}` — 读取 `process.env.VAR`；缺失则使用默认值
 - **类型还原**：整个值恰好是单个变量表达式时，结果还原为原生类型（number / boolean 等）；混合文本始终为字符串
+- **空值语义**：`${VAR:}` 或值为空字符串的 `${VAR}` 保持为 `''`，不会被 YAML 解析为 `null`；是否把空字符串视为未配置由模块 Schema 明确定义
 
 ```yaml
 # config/_core.yml

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

@@ -36,6 +36,7 @@ description: 使用 @h-ai/serv 将 oRPC contract 挂载为最小 HTTP App 抽象
 - 自定义 `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
 - 为 Audio WebSocket 配置一次性 ticket 校验、IAM/模型/配额授权与并发释放钩子
@@ -91,6 +92,40 @@ serv.listen(app, {
 })
 ```
 
+生产部署先从 `_core.yml.env` 与 `_serv.yml.cors` 创建安全策略；不要在业务应用重复实现 Origin 解析：
+
+```typescript
+const security = serv.createRuntimeSecurityPolicy({
+  environment: coreConfig.env,
+  corsOrigin: servConfig.cors.origin,
+  nativeOrigins: servConfig.cors.nativeOrigins,
+})
+
+const app = serv.createApp({
+  contract,
+  procedures,
+  http: {
+    ...servConfig.http,
+    openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
+    docs: security.exposeApiDocs ? servConfig.http.docs : false,
+  },
+  refreshCookie: { secure: security.secureRefreshCookie },
+  middlewares: [{
+    middleware: serv.cors({
+      origin: security.allowOrigin,
+      credentials: servConfig.cors.credentials,
+      allowedHeaders: [...servConfig.cors.allowedHeaders],
+      exposedHeaders: [...servConfig.cors.exposedHeaders],
+    }),
+  }],
+})
+```
+
+- 生产环境 `cors.origin` 禁止为空或 `*`，启动时 fail-fast。
+- 普通 Web Origin 仅接受 HTTP(S)；原生 Origin 通过 `cors.nativeOrigins` 显式允许 HTTP(S)、Capacitor 或 Tauri。
+- Origin 按完整规范化值精确匹配，不使用前缀/后缀匹配。
+- 生产环境自动要求 Secure refresh cookie，并把 OpenAPI/docs 作为安全上限关闭。
+
 ### 2.1 Audio WebSocket 安全接入
 
 ```typescript

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/app-routes.ts.hbs

@@ -1,27 +0,0 @@
-/** HTTP 与业务 API 路径常量，前端、服务端与 E2E 共用。 */
-export const APP_HTTP_ROUTES = {
-  apiPrefix: '/api/v1',
-  health: '/health',
-  ready: '/ready',
-  openapi: '/openapi.json',
-  docs: '/docs',
-} as const
-
-/** app 领域 contract 内部路径，最终会挂载到 APP_HTTP_ROUTES.apiPrefix 下。 */
-export const APP_CONTRACT_ROUTES = {
-  info: '/app/info',
-  echo: '/app/echo',
-} as const
-
-/** 已拼接 apiPrefix 的实际 HTTP 路径，便于测试和非 typed client 场景使用。 */
-export const APP_API_ROUTES = {
-  health: APP_HTTP_ROUTES.health,
-  ready: APP_HTTP_ROUTES.ready,
-  openapi: APP_HTTP_ROUTES.openapi,
-  docs: APP_HTTP_ROUTES.docs,
-  info: `${APP_HTTP_ROUTES.apiPrefix}${APP_CONTRACT_ROUTES.info}`,
-  echo: `${APP_HTTP_ROUTES.apiPrefix}${APP_CONTRACT_ROUTES.echo}`,
-} as const
-
-/** 当前工程启用的前端目标。 */
-export const ENABLED_FRONTENDS = {{{fullstack.selectedFrontendsJson}}} as const