@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.68

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

@@ -21,7 +21,14 @@ async function main(): Promise<void> {
   })
 }
 
-main().catch((error: unknown) => {
+main().catch(async (error: unknown) => {
   core.logger.error('API service failed to start', { error })
   process.exitCode = 1
+  try {
+    // 包括初始化后的 app/transport 创建失败，均须释放已建立的连接。
+    await closeApp()
+  }
+  catch (cleanupError) {
+    core.logger.error('API service startup cleanup failed', { error: cleanupError })
+  }
 })

package/templates/apps/api/apps/{{projectName}}-service/src/lib/server/init.ts.hbs

@@ -21,23 +21,47 @@
 
 let initialized = false
 let initPromise: Promise<void> | null = null
+/** 记录启动/关闭后未确认释放的资源，使失败清理可以重试。 */
+let cleanupPending = false
+let closePromise: Promise<void> | null = null
 {{#if features.crypto}}let cryptoInitialized = false
 {{/if}}
 
+/**
+ * 合并并发启动；任一步失败先逆序清理，未释放的资源会在下次启动前重试。
+ * @throws Error | AggregateError - 启动失败，或启动与资源清理同时失败。
+ * @example
+ * await initApp()
+ */
 export async function initApp(): Promise<void> {
+  if (closePromise)
+    await closePromise
   if (initialized)
     return
   if (initPromise)
     return initPromise
+  if (cleanupPending) {
+    await closeApp()
+    return await initApp()
+  }
 
-  initPromise = doInit()
-  try {
-    await initPromise
+  cleanupPending = true
+  initPromise = doInit().then(() => {
     initialized = true
-  }
-  finally {
+    cleanupPending = false
+  }).catch(async (error: unknown) => {
+    // 私有清理不等待 initPromise，避免启动失败时等待自身。
+    try {
+      await cleanupModules()
+    }
+    catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Application startup and cleanup failed')
+    }
+    throw error
+  }).finally(() => {
     initPromise = null
-  }
+  })
+  return await initPromise
 }
 
 async function doInit(): Promise<void> {
@@ -160,16 +184,38 @@ async function doInit(): Promise<void> {
   core.logger.info('API service initialized')
 }
 
+/**
+ * 等待启动并关闭所有模块；失败时保留重试入口。
+ * @throws AggregateError - 任一资源未确认释放。
+ * @example
+ * await closeApp()
+ */
 export async function closeApp(): Promise<void> {
-  if (!initialized && !initPromise)
+  closePromise ??= doCloseApp().finally(() => {
+    closePromise = null
+  })
+  return await closePromise
+}
+
+/** 等待启动结束后逐一释放；HaiResult 失败与异常都会聚合报告并保留重试入口。 */
+async function doCloseApp(): Promise<void> {
+  if (!initialized && !initPromise && !cleanupPending)
     return
 
+  if (initPromise)
+    await initPromise.catch(() => undefined)
+  await cleanupModules()
+}
+
+/** 不等待启动屏障，供启动失败与显式关闭共用的逆序清理。 */
+async function cleanupModules(): Promise<void> {
+  const failures: unknown[] = []
   const closers: Array<readonly [string, () => unknown]> = [
 {{#if features.ai}}    ['ai', () => ai.close()],
 {{/if}}{{#if features.storage}}    ['storage', () => storage.close()],
 {{/if}}{{#if features.iam}}    ['iam', () => iam.close()],
-{{/if}}{{#if features.reach}}    ['reach', () => reach.close()],
 {{/if}}{{#if features.vecdb}}    ['vecdb', () => vecdb.close()],
+{{/if}}{{#if features.reach}}    ['reach', () => reach.close()],
 {{/if}}{{#if features.cache}}    ['cache', () => cache.close()],
 {{/if}}{{#if features.db}}    ['reldb', () => reldb.close()],
 {{/if}}  ]
@@ -180,14 +226,25 @@ export async function closeApp(): Promise<void> {
 
   for (const [name, close] of closers) {
     try {
-      await close()
+      const result = await close()
+      if (result && typeof result === 'object' && 'success' in result && result.success === false) {
+        failures.push('error' in result ? result.error : new Error('Module close failed'))
+        core.logger.warn(`Module close failed: ${name}`)
+        continue
+      }
+{{#if features.crypto}}      if (name === 'crypto')
+        cryptoInitialized = false
+{{/if}}
     }
     catch (error) {
+      failures.push(error)
       core.logger.warn(`Module close failed: ${name}`, { error })
     }
   }
 
   initialized = false
-{{#if features.crypto}}  cryptoInitialized = false
-{{/if}}  core.logger.info('API service closed')
+  cleanupPending = failures.length > 0
+  if (cleanupPending)
+    throw new AggregateError(failures, 'Application resource cleanup failed; retry closeApp()')
+  core.logger.info('API service closed')
 }

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

@@ -7,12 +7,20 @@ import type { AppProcedureDeps } from './app-procedures.js'
 import { storage } from '@h-ai/storage'
 {{/if}}import { createAppProcedures } from './app-procedures.js'
 
+// @hai-generator:procedures:imports
+
 /** 创建应用级 procedures 聚合。 */
 export function {{api.serviceProceduresFactoryName}}(deps: { app: AppProcedureDeps }) {
   return {
+    // @hai-generator:procedures:entries
 {{#if features.iam}}    iam: createIamProcedures({ iam }),
-{{/if}}{{#if features.storage}}    storage: createStorageProcedures({ storage }),
-{{/if}}{{#if features.ai}}    ai: createAiProcedures({ ai }),
+{{/if}}{{#if features.storage}}    storage: createStorageProcedures({
+      storage,
+      authorize: ({ context, keys }) => keys.every(key =>
+        key.startsWith(`users/${encodeURIComponent(context.session.userId)}/`)),
+    }),
+{{/if}}{{#if features.ai}}    // AI 默认绑定可信 session.userId，跨主体访问需另行提供 authorizeObject 策略。
+    ai: createAiProcedures({ ai }),
 {{/if}}    app: createAppProcedures(deps.app),
   }
 }

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

@@ -19,7 +19,7 @@ test.beforeAll(async () => {
     auth: { storage: apiClient.tokenStorage.memory() },
 {{/if}}
 {{#if features.crypto}}
-    transport: process.env.HAI_SERV_TRANSPORT === 'false' ? undefined : { crypto },
+    transport: { crypto },
 {{/if}}
   })
   expect(result.success).toBe(true)
@@ -46,7 +46,7 @@ test('service app.info endpoint returns HaiResult', async () => {
     return
   expect(body.data.name).toBe(process.env.HAI_CORE_NAME ?? '{{projectName}} API Service')
   expect(body.data.version).toBe(process.env.HAI_CORE_VERSION ?? '0.1.0')
-  expect(body.data.env).toBe(process.env.HAI_CORE_ENV ?? 'development')
+  expect(body.data.env).toBe('test')
   expect(typeof body.data.transportEnabled).toBe('boolean')
 })
 {{#if features.iam}}

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

@@ -1 +1 @@
-{ "images": [{ "name": "app", "target": "runtime", "containerPort": 3000 }] }
+{ "images": [{ "name": "app", "dockerfile": "images/app.Dockerfile", "containerPort": 3000 }] }

package/templates/apps/api/images/app.Dockerfile.hbs

@@ -0,0 +1,35 @@
+FROM node:24.22.1-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR=
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+ENV CI=true
+ENV ONNXRUNTIME_NODE_INSTALL_CUDA=skip
+WORKDIR /workspace
+
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
+COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
+RUN pnpm compile
+RUN --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds if [ -d node_modules/better-sqlite3 ]; then cd node_modules/better-sqlite3; for attempt in 1 2 3; do node -e "require('node:child_process').execFileSync(process.execPath,[require.resolve('prebuild-install/bin.js'),'--verbose'],{stdio:'inherit'})" && break; [ "$attempt" = 3 ] && exit 1; sleep 3; done; fi
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds pnpm pm deploy --filter {{api.servicePackageName}} --prod /prod/app
+
+FROM node:24.22.1-bookworm-slim AS runtime-base
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+WORKDIR /app
+
+COPY --from=build --chown=node:node /prod/app ./
+RUN mkdir -p /app/data && chown node:node /app/data
+
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "dist/index.js"]

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

@@ -13,9 +13,11 @@
     "start:prod": "pnpm --filter {{api.servicePackageName}} start:prod",
     "dev:test": "pnpm --filter {{api.servicePackageName}} dev:test",
     "dev:prod": "pnpm --filter {{api.servicePackageName}} dev:prod",
-    "compile": "pnpm --filter {{api.contractPackageName}} build && pnpm -r --if-present build",
+    "compile": "pnpm -r --if-present build",
     "build": "hai build",
+{{#if features.deploy}}
     "deploy": "hai deploy apps/{{projectName}}-service",
+{{/if}}
     "check": "pnpm typecheck",
     "typecheck": "pnpm --filter {{api.contractPackageName}} build && pnpm -r --if-present typecheck",
     "lint": "eslint *.js *.ts e2e && pnpm -r --if-present lint",
@@ -30,6 +32,9 @@
     "{{api.contractPackageName}}": "workspace:*"
   },
   "devDependencies": {
+{{#if features.deploy}}
+    "@h-ai/deploy": "{{haiPackageSpecifier}}",
+{{/if}}
     "@h-ai/cli": "{{haiPackageSpecifier}}",
     "@h-ai/api-client": "{{haiPackageSpecifier}}",
 {{#if features.crypto}}

package/templates/apps/api/playwright.config.ts.hbs

@@ -1,5 +1,6 @@
 import process from 'node:process'
 import { defineConfig } from '@playwright/test'
+import { createE2eNotificationEnv, createE2eServerEnv, createE2eTransportRing } from './scripts/e2e-env.js'
 
 const defaultBaseURL = 'http://127.0.0.1:3000'
 const baseURL = process.env.BASE_URL || defaultBaseURL
@@ -33,25 +34,32 @@ function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string
 export default defineConfig({
   testDir: './e2e',
   globalSetup: './e2e/capture-evidence.ts',
-  fullyParallel: false,
+  fullyParallel: true,
   forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: 1,
+  retries: 0,
+  workers: 2,
   reporter: 'list',
   timeout: 30_000,
   use: {
     baseURL,
     channel: 'chrome',
-    trace: 'on-first-retry',
+    trace: 'retain-on-failure',
     screenshot: 'only-on-failure',
   },
   webServer: [{
     name: '{{api.servicePackageName}}',
-    command: 'pnpm --filter {{api.servicePackageName}} start',
-    env: {
+    command: 'pnpm --filter {{api.servicePackageName}} exec node dist/index.js',
+    env: createE2eServerEnv({
+      ...createE2eNotificationEnv(),
+      HAI_CORE_ENV: 'test',
+      HAI_DB: JSON.stringify({ type: 'sqlite', database: `${process.env.HAI_E2E_DATA_ROOT}/api.db` }),
+      HAI_CACHE: JSON.stringify({ type: 'memory' }),
+      HAI_STORAGE: JSON.stringify({ type: 'local', root: `${process.env.HAI_E2E_DATA_ROOT}/uploads` }),
+      HAI_VECDB: JSON.stringify({ type: 'lancedb', path: `${process.env.HAI_E2E_DATA_ROOT}/vecdb` }),
+      HAI_CRYPTO_TRANSPORT_SERVERKEYRING: createE2eTransportRing(),
       HOST: serviceHost,
       PORT: servicePort,
-    },
+    }),
     url: `${baseURL}/health`,
     reuseExistingServer: false,
     timeout: 120_000,

package/templates/apps/fullstack/.dockerignore.hbs

@@ -1,18 +1,23 @@
-.git
+**/.git
+**/node_modules
+**/.pnpm-store
+**/.cache
+**/.svelte-kit
+**/.turbo
+**/build
+**/dist
+**/coverage
+**/playwright-report
+**/test-results
+**/src-tauri/target
+**/hash-core/target
+tmp
 **/*.tar
-Dockerfile
 .github
 .agents
 .claude
 .codex
 .opencode
-.turbo
-**/build
-**/dist
-**/node_modules
-node_modules
-playwright-report
-test-results
 **/data
 *.log
 # 仅保留公共基础 .env；分环境配置、私有覆盖及已有交付包不进入构建上下文。

package/templates/apps/fullstack/.gitignore.hbs

@@ -29,3 +29,10 @@ playwright-report/
 # 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
 .env.local
 .env.*.local
+
+# 构建器生成的安装输入快照
+**/images/dependencies/
+
+# 项目本地缓存
+**/.pnpm-store/
+**/.cache/

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

@@ -2,9 +2,19 @@
 {{#if fullstack.frontends.app}}
 # {{projectName}}-app
 
+## 简介
+
 App/H5 前端工程，复用 shared 的响应式 mini 后台，使用 Svelte 5 + Vite + Capacitor，可输出 Web 预览并同步 Android / iOS 原生工程。
 
-## i18n 与 shared 协同
+## 核心功能清单
+
+- 响应式 H5 页面与 Capacitor Android/iOS 原生壳。
+- 共享管理界面、个人设置和接口客户端。
+- 原生使用安全 TokenStorage，浏览器预览使用 Cookie 刷新。
+
+## 使用入门
+
+### i18n 与 shared 协同
 
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
@@ -13,7 +23,7 @@ App/H5 前端工程，复用 shared 的响应式 mini 后台，使用 Svelte 5 +
 
 自定义建议：移动端独有引导、运营位、按钮文案放在本目录 `messages/`；跨端通用组件放到 shared。
 
-## 编译、打包与部署
+### 编译、打包与部署
 
 ```bash
 # 开发预览，默认端口 {{fullstack.ports.app}}
@@ -31,15 +41,23 @@ pnpm --filter {{projectName}}-app cap:build:android:release
 pnpm --filter {{projectName}}-app cap:build:ios
 ```
 
-部署前确认 `PUBLIC_API_BASE` 在 `.env` 中指向可访问的后端服务。Android 模拟器访问宿主机通常使用 `http://10.0.2.2:3000`。
+本地开发通过根 `.env` 的 `PUBLIC_API_BASE` 配置代理。原生打包前，在本端 `public/runtime-config.js` 中设置 `globalThis.__HAI_PUBLIC_CONFIG__ = { apiBase: 'https://api.example.com/api/v1' }`，再编译并同步原生工程；这里只能放公开地址，不能放密钥。Android 模拟器访问宿主机通常使用 `http://10.0.2.2:3000/api/v1`。
 
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
-LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器预览通过后，原生壳仍需在对应系统或设备单独验收。
+
+## 许可证
+
+Apache-2.0
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/index.html.hbs

@@ -6,6 +6,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
     <meta name="theme-color" content="#2563eb" />
+    <script src="/runtime-config.js"></script>
     <title>{{html fullstack.appName}}</title>
     <link
       rel="icon"

package/templates/apps/fullstack/apps/{{projectName}}-app/messages/ja-JP.json.hbs

@@ -0,0 +1,7 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "page_title": "{name}"
+}
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/public/runtime-config.js.hbs

@@ -0,0 +1,4 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+globalThis.__HAI_PUBLIC_CONFIG__ = {}
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/src/App.svelte.hbs

@@ -3,6 +3,7 @@
 <script lang="ts">
   import type { ManagementApiOptions } from '{{fullstack.sharedPackageName}}'
   import { capacitor, createCapacitorTokenStorage } from '@h-ai/capacitor'
+  import { core } from '@h-ai/core'
   import { Alert } from '@h-ai/ui/components/compounds/index'
   import { Button, Spinner } from '@h-ai/ui/components/primitives/index'
   import { onMount } from 'svelte'
@@ -29,7 +30,12 @@
   }
   onMount(() => {
     void initialize()
-    return () => void capacitor.close()
+    return () => {
+      void capacitor.close().then((closed) => {
+        if (!closed.success)
+          core.logger.warn('Native listener cleanup failed; retry on next initialization')
+      })
+    }
   })
 </script>
 

package/templates/apps/fullstack/apps/{{projectName}}-app/vite.config.ts.hbs

@@ -12,7 +12,7 @@ import { defineConfig } from 'vitest/config'
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode, command }) => {
-  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
+  const envResult = command === 'build' || process.env.HAI_E2E === '1' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data
@@ -51,7 +51,7 @@ export default defineConfig(({ mode, command }) => {
     },
     envPrefix: ['VITE_', 'PUBLIC_'],
     ssr: {
-      noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
+      noExternal: ['@h-ai/ui', /{{fullstack.sharedPackageName}}/],
     },
     test: {
       environment: 'node',

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

@@ -2,9 +2,19 @@
 {{#if fullstack.frontends.desktop}}
 # {{projectName}}-desktop
 
+## 简介
+
 桌面端工程，参考 `apps/desktop-app` 使用 Tauri v2 + Svelte 5 + Vite，前端通过共享 contract 调用 `{{fullstack.servPackageName}}`。
 
-## i18n 与 shared 协同
+## 核心功能清单
+
+- Tauri v2 桌面壳与共享管理界面。
+- 运行时配置 API 地址，无需按环境重复打包。
+- 原生令牌仅存内存，重启后重新登录。
+
+## 使用入门
+
+### i18n 与 shared 协同
 
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
@@ -14,7 +24,7 @@
 
 自定义建议：桌面端菜单、状态、快捷操作文案放在本目录 `messages/`；跨端通用能力放到 shared。
 
-## 编译、打包与部署
+### 编译、打包与部署
 
 ```bash
 # 仅前端开发，默认端口 {{fullstack.ports.desktop}}
@@ -32,13 +42,21 @@ pnpm build --target desktop --platform windows --arch x64
 
 打包前需要安装 Rust 工具链和 Tauri 平台依赖。构建不读取 .env.prod/.env.local；启动已安装程序前设置进程 PUBLIC_API_BASE（HTTP(S)，不含凭据、查询和片段）。Rust 会在页面加载前注入公开地址，仅将该 Origin 加入 CSP；不需要为 test/prod 重打安装包。缺省连接 http://localhost:3000/api/v1。
 
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
-LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器预览通过后，原生壳仍需在对应系统或设备单独验收。
+
+## 许可证
+
+Apache-2.0
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-desktop/messages/ja-JP.json.hbs

@@ -0,0 +1,7 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.desktop}}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "page_title": "{name}"
+}
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-desktop/vite.config.ts.hbs

@@ -13,7 +13,7 @@ const host = process.env.TAURI_DEV_HOST
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode, command }) => {
-  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
+  const envResult = command === 'build' || process.env.HAI_E2E === '1' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data

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

@@ -2,14 +2,24 @@
 {{#if fullstack.hasMiniapp}}
 # {{projectName}}-miniapp
 
-小程序端当前为预留占位，不参与 workspace 构建、单元测试或 E2E，但已预置 inlang 标准目录：
+## 简介
 
-- `project.inlang/settings.json`：小程序端 locale 配置
-- `messages/zh-CN.json`、`messages/en-US.json`：小程序端自有文案
+小程序预留目录，目前没有可运行的小程序应用。
 
-消息格式插件复用 workspace 已安装的依赖，从根目录 `node_modules` 加载；生成后先在 workspace 根目录安装依赖，无需从 CDN 加载插件。
+## 核心功能清单
 
-后续实现时建议复用 `packages/{{fullstack.contractPackageName}}` 中的 Schema 与路径常量，保持接口真相源一致。
+- 已提供 `project.inlang/settings.json` 与中英文 `messages/`。
+- 可复用 `packages/{{fullstack.contractPackageName}}` 的接口类型。
 
-协同边界：跨端通用文案/组件放 `packages/{{fullstack.sharedPackageName}}`，小程序独有页面文案放本目录 `messages/`。
+## 使用入门
+
+选定小程序框架后再实现页面、请求适配和认证。小程序文案放本目录 `messages/`，跨端通用内容放 `packages/{{fullstack.sharedPackageName}}`；消息格式插件使用工程根已安装的依赖。
+
+## 开发测试
+
+本目录不参与 workspace 构建、单元测试或 E2E。接入实际框架后增加对应命令，并在目标平台验证登录、请求、导航与发布包。
+
+## 许可证
+
+Apache-2.0
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-miniapp/messages/ja-JP.json.hbs

@@ -0,0 +1,12 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.hasMiniapp}}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "mini_title": "{{projectName}} ミニアプリ",
+  "mini_status": "予約済みのプレースホルダー",
+  "mini_description": "ミニアプリの対象では、まだビルド可能なパッケージは生成しません。標準のinlang project.inlangとmessagesを用意しているため、後でミニアプリ用フレームワークに組み込めます。",
+  "mini_shared_contract": "packages/{{fullstack.contractPackageName}}のスキーマとルート定数を再利用してください。",
+  "mini_own_messages": "ミニアプリ固有の文案はapps/{{projectName}}-miniapp/messagesに配置します。",
+  "mini_customize": "端末間の言語切り替えを揃えるため、言語一覧をsharedと一致させてください。"
+}
+{{/if}}

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

@@ -2,9 +2,19 @@
 {{#if fullstack.frontends.web}}
 # {{projectName}}-web
 
+## 简介
+
 响应式 mini 后台 Web 前端，通过 `packages/{{fullstack.sharedPackageName}}` 调用后端 API，并通过 `@h-ai/ui` 组件搭建页面。
 
-## i18n 与 shared 协同
+## 核心功能清单
+
+- 浏览器访问共享管理界面与个人设置。
+- 与 API 共用接口类型、登录状态、主题和语言。
+- 可单独构建 Web 镜像并增量更新。
+
+## 使用入门
+
+### i18n 与 shared 协同
 
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
@@ -12,7 +22,7 @@
 
 自定义建议：Web 独有文案放在本目录 `messages/`；跨端通用文案或组件放到 shared。
 
-## 编译、打包与部署
+### 编译、打包与部署
 
 ```bash
 # 开发预览，默认端口 {{fullstack.ports.web}}
@@ -22,15 +32,23 @@ pnpm --filter {{projectName}}-web dev
 pnpm --filter {{projectName}}-web build
 ```
 
-从工程根运行 `pnpm build --target docker` 构建并导出镜像。启用 deploy 功能后，运行根命令 `pnpm deploy --env test`，一次发布 API/Web；网络不通时用 `pnpm deploy --env prod --bundle-only`，按输出说明手工搬运 tar。部署不重新构建。
+从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
 
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
-LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器预览通过后，原生壳仍需在对应系统或设备单独验收。
+
+## 许可证
+
+Apache-2.0
 {{/if}}