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

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。
 
 协议支持配置中的 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}}-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}}-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。
 
 协议支持配置中的 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}}-web/vite.config.ts.hbs

@@ -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/e2e/fullstack.spec.ts.hbs

@@ -61,7 +61,7 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
-test('hash routing restores direct links, refresh and browser history', async ({ page }) => {
+test('hash routing and responsive workspace preserve usable content width', async ({ page }, testInfo) => {
   await page.goto('/#/roles?source=direct')
   await login(page, 'admin', adminPassword)
   await expect(page.getByTestId('roles-page')).toBeVisible()
@@ -70,6 +70,16 @@ test('hash routing restores direct links, refresh and browser history', async ({
   await expect(page.getByTestId('roles-page')).toBeVisible()
   await expect(page.locator('header')).toBeVisible()
   await expect(page.locator('footer')).toBeVisible()
+  for (const width of [1440, 1920, 2560, 3840, 390]) {
+    await page.setViewportSize({ width, height: 960 })
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    const main = await page.locator('main').boundingBox()
+    const content = await page.getByTestId('roles-page').boundingBox()
+    expect(content!.width).toBeGreaterThan(main!.width - 80)
+    if (width === 1920)
+      await capture(page, '{{projectName}}-wide.png', testInfo.outputPath('wide-1920.png'))
+  }
+  await page.setViewportSize({ width: 1440, height: 960 })
   await page.getByTestId('nav-settings').click()
   await expect(page).toHaveURL(/#\/settings$/)
   await page.goBack()

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

@@ -1,7 +1,7 @@
 {
   "images": [
-    { "name": "app", "target": "runtime", "containerPort": 3000 }{{#if fullstack.frontends.web}},
-    { "name": "web", "target": "web", "containerPort": 8080 }{{/if}}
+    { "name": "app", "dockerfile": "images/app.Dockerfile", "containerPort": 3000 }{{#if fullstack.frontends.web}},
+    { "name": "web", "dockerfile": "images/web.Dockerfile", "containerPort": 8080 }{{/if}}
   ]{{#if fullstack.frontends.desktop}},
   "desktop": ["apps/{{projectName}}-desktop"]{{/if}}
 }

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

@@ -0,0 +1,36 @@
+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 --filter {{fullstack.servPackageName}}... --if-present build
+
+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 {{fullstack.servPackageName}} --prod /prod/service
+
+FROM node:24.22.1-bookworm-slim AS service
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+WORKDIR /app
+
+COPY --from=build --chown=node:node /prod/service ./
+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/fullstack/images/web.Dockerfile.hbs

@@ -0,0 +1,34 @@
+{{#if fullstack.frontends.web}}
+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
+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 --filter {{fullstack.sharedPackageName}} paraglide:compile && pnpm --filter {{projectName}}-web... --if-present build
+
+FROM nginxinc/nginx-unprivileged:1.29.8-alpine AS web
+
+ENV PUBLIC_API_BASE=
+ENV NGINX_ENVSUBST_FILTER=PUBLIC_API_BASE_BASE64
+ENV NGINX_ENVSUBST_OUTPUT_DIR=/tmp/hai-runtime-config
+
+RUN mkdir -p /tmp/hai-runtime-config
+COPY images/web/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --chmod=755 images/web/19-runtime-config.envsh /docker-entrypoint.d/19-runtime-config.envsh
+COPY images/web/runtime-config.js.template /etc/nginx/templates/runtime-config.js.template
+COPY --from=build /workspace/apps/{{projectName}}-web/dist /usr/share/nginx/html
+
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -Y off -q -O /dev/null http://127.0.0.1:8080/health || exit 1
+{{/if}}

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

@@ -17,7 +17,9 @@
     "dev:prod": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:prod",
     "compile": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present build",
     "build": "hai build",
+{{#if features.deploy}}
     "deploy": "hai deploy packages/{{projectName}}-serv",
+{{/if}}
     "check": "pnpm typecheck",
     "typecheck": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present typecheck",
     "lint": "eslint *.js *.ts e2e && pnpm -r --if-present lint",

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

@@ -1,8 +1,18 @@
 # {{fullstack.contractPackageName}}
 
+## 简介
+
 共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。业务 schema、角色、流程及限额是模板初始方案，按用户需求修改，并同步服务端授权、调用方、测试与说明；不要求需求沿用默认业务。
 
-## 骨架说明
+## 核心功能清单
+
+- 共享接口路径、输入输出 Schema 和类型。
+- 客户端与服务端使用同一份 contract。
+- 不包含服务端业务实现，也不加载私有配置。
+
+## 使用入门
+
+### 骨架说明
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
@@ -13,7 +23,18 @@
 API 前缀、健康检查与跨端 Header 等传输配置位于 serv 包的 `config/_serv.yml`。
 `SUPPORTED_LOCALES` 为生成时实际编译的语言列表；`app.info` 中名称、版本、环境、默认语言来自后端 core 配置。更新公开契约时同时更新 serv、shared typed API client、各端 UI 与测试。
 
-## 开发
+### 开发
 
 - `pnpm --filter {{fullstack.contractPackageName}} typecheck`
 - `pnpm --filter {{fullstack.contractPackageName}} test`
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.contractPackageName}} typecheck
+pnpm --filter {{fullstack.contractPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

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

@@ -1,8 +1,18 @@
 # {{fullstack.servPackageName}}
 
+## 简介
+
 后端 API Service，基于 `@h-ai/serv` 将共享 contract 装配为最小 HTTP App 抽象，不在应用代码中直接暴露 Hono。
 
-## 默认功能与配置
+## 核心功能清单
+
+- HTTP 服务、健康检查和共享 contract 的 procedure 实现。
+- 用户、角色、审计与个人设置的示例业务。
+- 模块配置、加密传输与服务端权限校验。
+
+## 使用入门
+
+### 默认功能与配置
 
 以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
 
@@ -24,7 +34,7 @@ CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项
 
 业务修改提交后的审计记录采用最大努力策略：写入失败输出包含操作及资源的结构化错误日志，业务仍返回原操作结果，避免将已经完成的变更误报为失败；应用启动时 audit 初始化失败则停止启动。
 
-## 开发
+### 开发
 
 所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，实际密钥保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
 
@@ -33,20 +43,31 @@ CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项
 - `pnpm --filter {{fullstack.servPackageName}} dev`
 - `pnpm --filter {{fullstack.servPackageName}} test`
 
-## 容器运行
+### 容器运行
 
-从工程根运行 `pnpm build --target docker` 构建并导出镜像。启用 deploy 功能后，运行根命令 `pnpm deploy --env test`；含 Web 镜像时一并发布 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。
 
 - 服务镜像直接由 `@h-ai/serv` 对外监听，配置挂载点为 `/app/config`，数据目录为 `/app/data`，不包含额外转发进程。
 - Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
 - YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
 
-## 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。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.servPackageName}} typecheck
+pnpm --filter {{fullstack.servPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

package/templates/apps/fullstack/packages/{{projectName}}-shared/.gitignore.hbs

@@ -1,3 +1,10 @@
 node_modules
 .turbo
 src/lib/paraglide
+
+# 构建器生成的安装输入快照
+**/images/dependencies/
+
+# 项目本地缓存
+**/.pnpm-store/
+**/.cache/

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

@@ -1,35 +1,48 @@
 # {{fullstack.sharedPackageName}}
 
+## Introduction
+
 Shared mini administration workspace for **{{projectName}}**. Web, Capacitor App and Tauri desktop use the same `AdminWorkspace`, responsive `AppShell`, typed API client and management store.
 
+## Core features
+
+- Shared management pages, forms, navigation and application state.
+- Typed encrypted API client and platform-specific token storage.
+- Themes, language preferences, onboarding and help.
+
+## Getting started
+
+### Behavior and configuration
+
 The behavior below describes the initial example. Roles, permissions, workflows, limits, preferences and audit policies can change with the user's requirements. Update conflicting implementation, tests and guidance together; preserve the applicable public API contracts and server security checks.
 
 - Administrators manage users, upload user avatars, assign the built-in administrator/user roles, edit role descriptions and query audit logs.
 - By default, ordinary users update their own profile, avatar, language, appearance and password. The server enforces the actual business permissions on every request.
+- The workspace uses the available window width. Tables scroll within their own area; settings panels form two columns on large screens and stack on phones.
 - `ManagementStore` owns API calls and business state; components render the state and forward user interactions.
 - Application name, version, environment and default locale come from the backend `app.info` contract, which reads `core` configuration. Do not duplicate these values in translations or frontend constants.
 - Requests, token refresh and JSON responses use the same `@h-ai/api-client` + `@h-ai/crypto` transport. Avatar uploads use encrypted JSON and validate PNG/JPEG/WebP content, with a 512 KiB limit.
 - Read metadata through the same initialized `managementApi.app.info()` client; inspect `success` before using `data`.
 
-All three Vite apps read the workspace root .env. Development and preview servers proxy /api to the local backend when no explicit API base is configured, so browser clients can use a single origin. In deployments, configure PUBLIC_API_BASE or the Web container runtime API origin for the actual service.
+Vite development and preview servers read the workspace root environment files and proxy /api to the backend. Builds do not load deployment environment files. Web containers receive their public API address at startup; native apps follow the platform configuration below.
 
 An origin-only API base uses `/api/v1`. For a custom service `http.apiPrefix`, include that path in `PUBLIC_API_BASE` or the runtime API base; the client preserves the configured path and restricts avatar URLs to its matching resource prefix.
 
-## Authentication and preferences
+### Authentication and preferences
 
 Web and browser previews keep access tokens in memory and refresh tokens in the server's httpOnly Cookie. Requests include credentials; reload restores the session through the encrypted refresh flow. Never store authentication tokens in localStorage.
 
-Capacitor native uses `createCapacitorTokenStorage()` and the trusted native token channel. Tauri native uses memory token storage and requires a new login after restarting the application. Native builds require a reachable `PUBLIC_API_BASE` in the workspace root `.env`; missing configuration produces a connection configuration error. Both send their frontend `clientName` and `X-HAI-Token-Transport: body`; the service verifies the allowed native origin before returning a refresh token in JSON.
+Capacitor native uses `createCapacitorTokenStorage()` and the trusted native token channel. Set its public API address in the App's `public/runtime-config.js` before compiling and syncing native assets. Tauri uses memory token storage and requires a new login after restart; set process `PUBLIC_API_BASE` before launching the installed application, and its Rust host injects the address. Both send `clientName` and `X-HAI-Token-Transport: body`; the service verifies the trusted native origin before returning a refresh token in JSON. Missing API configuration is an error, not a successful connection.
 
 Language and theme preferences are saved in IAM user metadata, restored after login and synchronized with the shared/host Paraglide runtimes and `core.i18n`. The small reactive theme store delegates DOM updates and safe appearance caching to `@h-ai/ui/theme` (`applyTheme` / `getSavedTheme`); the framework uses the `theme` localStorage key. Appearance selectors live in personal settings and save through the authenticated profile contract.
 
-## Onboarding and help
+### Onboarding and help
 
 AdminWorkspace mounts the shared `@h-ai/ui/guide` controller and GuideHost after authentication. AppShell includes a help button; first-use invitations offer start, later and dismiss. Web stores preferences in Cookies, while App/Desktop use localStorage, scoped by the current user and tour version. Help articles link to the overview and profile tours.
 
 Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
 
-## i18n and themes
+### i18n and themes
 
 Shared page copy belongs in `messages/{zh-CN,en-US}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
 
@@ -37,22 +50,30 @@ All frontend and shared projects load the installed message-format plugin from t
 
 The scaffold theme configuration determines the themes compiled into frontend CSS. Personal settings offer only those available themes. Customize the common layout in `src/lib/components/AppShell.svelte`, the management pages in adjacent components, and business behavior in `src/lib/stores/management-store.svelte.ts`.
 
-## Validation
+### Validation
 
 Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout. All selected Web/App/Desktop previews also exercise login, tours, help and profile navigation. Clean screenshots, reports, temporary projects, containers and helper processes in finally/teardown, including failure paths. These browser checks do not replace native-shell or miniapp device acceptance.
 
-## IAM configuration
+### IAM configuration
 
-The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. All service nodes must share the same database and Redis; memory cache is for a single process.
+The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. A single process can use memory cache. Multiple instances need shared database/cache, write routing and transport session affinity as described in the project README.
 
 Authentication defaults to a split layout. Set `ui.variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `logoUrl` and `illustrationUrl` to customize login and registration. Without a `brandTitle`, the displayed application name comes from `app.info` and follows `core` configuration.
 
 LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
 
-协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+Agreements accept Markdown text or a URL. Markdown takes precedence and opens in a safely rendered dialog.
 
 See `.agents/skills/hai-iam/reference.md` in the generated application for the complete contract.
 
-## Form layouts
+### Form layouts
+
+The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings fill the available width and use two columns on wide screens, with stacked labels and a single avatar editor. Narrow containers automatically stack cards, fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.
+
+## Development and testing
+
+Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Browser checks cover shared workflows; test native shells on their target platforms separately.
+
+## License
 
-The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings use a bounded page width, stacked labels and a single avatar editor. Narrow containers automatically stack fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.
+Apache-2.0

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AppShell.svelte.hbs

@@ -34,7 +34,7 @@
   {#if menuOpen}
     <BareButton class="fixed inset-0 z-30 bg-black/30 lg:hidden" ariaLabel={m.close_menu()} onclick={() => { menuOpen = false }} />
   {/if}
-  <aside class="fixed inset-y-0 left-0 z-40 flex w-60 flex-col border-r border-base-content/8 bg-base-100 transition-transform duration-200 lg:sticky lg:top-0 lg:h-dvh lg:translate-x-0 {menuOpen ? 'translate-x-0' : '-translate-x-full'}">
+  <aside class="fixed inset-y-0 left-0 z-40 flex w-60 shrink-0 flex-col border-r border-base-content/8 bg-base-100 transition-transform duration-200 lg:sticky lg:top-0 lg:h-dvh lg:translate-x-0 {menuOpen ? 'translate-x-0' : '-translate-x-full'}">
     <div class="flex h-16 items-center gap-3 border-b border-base-content/8 px-5">
       <span class="grid size-8 shrink-0 place-items-center rounded-lg bg-primary text-primary-content"><span class="icon-[tabler--hexagon-letter-h] size-5"></span></span>
       <span class="truncate text-sm font-semibold" data-testid="app-name">{store.info?.name}</span>
@@ -66,7 +66,7 @@
         <Button variant="ghost" size="sm" loading={store.saving} onclick={() => void store.logout()} data-testid="logout">{m.logout()}</Button>
       </div>
     </header>
-    <main class="mx-auto w-full max-w-7xl flex-1 p-4 pb-8 sm:p-6 lg:p-8" data-guide="admin-content">{@render children()}</main>
+    <main class="w-full min-w-0 flex-1 p-4 pb-8 sm:p-6 lg:p-8" data-guide="admin-content">{@render children()}</main>
     <footer class="border-t border-base-content/8 px-6 py-3 text-center text-xs text-base-content/35">{store.info?.name} · v{store.info?.version}</footer>
   </div>
 </div>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/settings.svelte.hbs

@@ -14,13 +14,13 @@
   const themeOptions = AVAILABLE_THEMES.map(theme => ({ value: theme, label: getThemeInfo(theme)?.name ?? theme }))
 </script>
 
-<section class='mx-auto w-full max-w-4xl space-y-6' data-testid='settings-page'>
-  <div>
+<section class='grid w-full min-w-0 gap-6 xl:grid-cols-2' data-testid='settings-page'>
+  <div class='xl:col-span-2'>
     <h1 class='text-xl font-semibold tracking-tight'>{m.settings_title()}</h1>
     <p class='mt-1 text-sm text-base-content/50'>{m.settings_description()}</p>
   </div>
   {#if store.user}
-    <Card title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
+    <Card class='xl:row-span-2' title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
       <div class='mb-5 flex flex-wrap items-center gap-3 border-b border-base-content/8 pb-4'>
         <p class='min-w-0 break-all text-sm text-base-content/55'>@{store.user.username}</p>
         <Badge size='sm' variant='ghost'>{store.isAdmin ? m.role_admin() : m.role_user()}</Badge>

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

@@ -75,11 +75,11 @@ describe('shared API transport', () => {
     expect(server.requests.at(-1)?.headers.get('x-request-client')).toBe('configured-client')
   })
 
-  it('uses the API origin injected at container startup', async () => {
+  it.each([false, true])('uses the injected API origin when native configuration is required: %s', async (requireApiBase) => {
     Object.assign(globalThis, { __HAI_PUBLIC_CONFIG__: { apiBase: 'https://runtime.example.com' } })
     const server = createServerFetch()
     try {
-      expect((await initializeManagementApi({ fetchFn: server.fetchFn })).success).toBe(true)
+      expect((await initializeManagementApi({ fetchFn: server.fetchFn, requireApiBase })).success).toBe(true)
       expect((await managementApi.app.info()).success).toBe(true)
       expect(server.requests.every(request => request.url.startsWith('https://runtime.example.com/api/v1/'))).toBe(true)
     }

package/templates/apps/h5/src/routes/+layout.svelte.hbs

@@ -61,14 +61,14 @@
 </svelte:head>
 
 <div class='hai-mobile-viewport'>
-  <div class='hai-mobile-shell max-w-lg'>
+  <div class='hai-mobile-shell min-w-0'>
     <AppBar title={page.data.appConfig.name} safeArea fixed={false} />
     <main class='hai-mobile-main'>{@render children()}</main>
     <footer class='border-t border-base-300 bg-base-100 p-2 text-center text-xs text-base-content/60'>
       {page.data.appConfig.name} · {page.data.appConfig.version} · {page.data.appConfig.env}
     </footer>
     {#if !isAuthPage}
-      <BottomNav items={navItems} active={activeNav} onchange={handleNavigation} centered maxWidth='lg' safeArea />
+      <BottomNav items={navItems} active={activeNav} onchange={handleNavigation} centered maxWidth='none' safeArea />
     {/if}
   </div>
 </div>

package/templates/apps/mobile-app/src/App.svelte.hbs

@@ -100,7 +100,7 @@
 </script>
 
 <div class='hai-mobile-viewport'>
-  <div class='hai-mobile-shell max-w-lg'>
+  <div class='hai-mobile-shell min-w-0'>
     <AppBar title={appConfig.name} safeArea fixed={false} class='bg-base-100/95 backdrop-blur border-base-content/8' />
     <main class='hai-mobile-main'>
       {#if booting}
@@ -129,7 +129,7 @@
 {{#if features.iam}}
     {#if authenticated && !booting && !bootError}
 {{/if}}
-      <BottomNav items={navItems} active={router.path.slice(1)} onchange={handleTabChange} safeArea centered maxWidth='lg' />
+      <BottomNav items={navItems} active={router.path.slice(1)} onchange={handleTabChange} safeArea centered maxWidth='none' />
 {{#if features.iam}}
     {/if}
 {{/if}}

package/templates/apps/mobile-app/src/lib/pages/home.svelte.hbs

@@ -12,8 +12,8 @@
   const { nativeRuntime, nativeTokenStorage }: Props = $props()
 </script>
 
-<section class='space-y-4 p-4 pb-6'>
-  <div class='bg-primary text-primary-content rounded-2xl p-5 shadow-sm'>
+<section class='grid gap-4 p-4 pb-6 lg:grid-cols-2'>
+  <div class='lg:col-span-2 bg-primary text-primary-content rounded-2xl p-5 shadow-sm'>
     <p class='text-sm opacity-75'>{m.hero_eyebrow()}</p>
     <h1 class='mt-1 text-2xl font-bold'>{m.hero_title()}</h1>
     <p class='mt-2 text-sm opacity-80'>{m.hero_subtitle()}</p>

package/templates/apps/website/src/routes/+layout.svelte.hbs

@@ -49,7 +49,7 @@
 </svelte:head>
 
 <div class='min-h-screen flex flex-col'>
-  <header class='navbar bg-base-100 shadow-sm'>
+  <header class='navbar flex-wrap bg-base-100 shadow-sm'>
     <div class='flex-1'>
 {{#if hasI18n}}
       <a href={resolve('/', {})} class='btn btn-ghost text-xl font-black tracking-tight'>{page.data.appConfig.name}</a>
@@ -57,8 +57,8 @@
       <a href={resolve('/', {})} class='btn btn-ghost text-xl font-black tracking-tight'>{page.data.appConfig.name}</a>
 {{/if}}
     </div>
-    <nav class='flex-none'>
-      <ul class='menu menu-horizontal px-1'>
+    <nav class='w-full flex-none sm:w-auto'>
+      <ul class='menu menu-horizontal flex-wrap px-1'>
         {#each navItems as item (item.path)}
           <li><a href={resolve(item.path, {})}>{item.label}</a></li>
         {/each}