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

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

@@ -13,6 +13,23 @@ http:
     readyPath: /ready
   rpc: false
 
+cors:
+  origin: '*'
+  nativeOrigins: 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/_core.yml.hbs

@@ -3,12 +3,12 @@
 # =============================================================================
 #
 # 后端服务的应用级配置，由 core.config 在启动时加载。
-# 敏感信息请通过环境变量注入。
+# 每个叶子项都可由约定式 HAI 环境变量覆盖，敏感值不要写入文件。
 # =============================================================================
 
 name: {{fullstack.servPackageName}}
 version: 0.1.0
-env: ${HAI_ENV:development}
-debug: ${HAI_DEBUG:false}
+env: development
+debug: false
 
 defaultLocale: {{fullstack.i18n.baseLocale}}

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:*}
+  origin: '*'
+  nativeOrigins: 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.44",
   "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

@@ -65,9 +65,9 @@ await ai.close()
 
 ```yaml
 llm:
-  apiKey: ${HAI_AI_LLM_API_KEY:}
-  baseUrl: ${HAI_AI_LLM_BASE_URL:https://api.openai.com/v1}
-  model: ${HAI_AI_LLM_MODEL:gpt-4o-mini}
+  apiKey: ''
+  baseUrl: https://api.openai.com/v1
+  model: gpt-4o-mini
   api: chat # chat（默认）| responses | anthropic——底层协议，对使用方透明
   timeout: 60000
   tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
@@ -97,6 +97,9 @@ memory:
   # allowEphemeralFallback: true # 仅明确接受重启丢失数据时开启
 ```
 
+约定环境变量优先于 YAML，例如 `HAI_AI_LLM_APIKEY`、
+`HAI_AI_LLM_BASEURL`、`HAI_AI_LLM_MODEL`。
+
 `ai.config` 是脱敏快照；`apiKey`、`privateKey`、URL 内嵌凭证会被隐藏。
 
 ## 常用 API
@@ -279,11 +282,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 +337,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` 不把未完成的部分音频当作成功返回。