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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.66",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.66",
+    "@h-ai/core": "0.1.0-alpha.67",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,12 +41,12 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.66",
-    "@h-ai/crypto": "0.1.0-alpha.66",
-    "@h-ai/deploy": "0.1.0-alpha.66",
-    "@h-ai/reach": "0.1.0-alpha.66",
-    "@h-ai/reldb": "0.1.0-alpha.66",
-    "@h-ai/storage": "0.1.0-alpha.66",
+    "@h-ai/cache": "0.1.0-alpha.67",
+    "@h-ai/crypto": "0.1.0-alpha.67",
+    "@h-ai/deploy": "0.1.0-alpha.67",
+    "@h-ai/reach": "0.1.0-alpha.67",
+    "@h-ai/reldb": "0.1.0-alpha.67",
+    "@h-ai/storage": "0.1.0-alpha.67",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/README.md

@@ -1,163 +1,66 @@
-# CLI Templates
+# CLI 项目模板
 
-此目录包含 `hai create` 命令使用的项目模板文件。
+## 简介
 
-## 目录结构
+这里保存 `hai create` 生成应用时使用的源码、配置和 AI 指引。维护模板后，需要生成真实项目验证，不能只检查模板文件本身。
 
-```
-templates/
-├── base/                    # 所有应用类型共用的骨架文件
-│   ├── package.json.hbs     # 动态：按 features 注入依赖
-│   ├── vite.config.ts.hbs   # 动态：按 hasI18n / hasUi 注入插件
-│   ├── tsconfig.json.hbs    # 动态：SvelteKit / 纯 Svelte 5 分支
-│   ├── svelte.config.js.hbs # 动态：SvelteKit / 纯 Svelte 5 分支
-│   ├── .gitignore.hbs      # 动态：纯 Svelte 5 应用不输出 .svelte-kit
-│   ├── playwright.config.ts
-│   └── src/
-│       ├── app.html.hbs         # 动态：SvelteKit 应用输出 app shell
-│       ├── app.d.ts.hbs         # 动态：SvelteKit 应用输出 App namespace
-│       ├── app.css
-│       ├── hooks.server.ts.hbs  # 动态：按 features / hasI18n 组装 handle 序列
-│       └── lib/server/
-│           └── init.ts.hbs      # 动态：按 features 注入模块初始化
-│
-├── apps/                    # 应用类型专属路由与页面
-│   ├── admin/               # 管理后台
-│   │   ├── messages/        # i18n 消息文件（zh-CN / en-US）
-│   │   └── src/routes/      # +page / +layout .svelte.hbs
-│   ├── website/             # 企业官网
-│   │   ├── messages/
-│   │   └── src/routes/
-│   ├── h5/                  # H5 移动端
-│   │   ├── messages/
-│   │   └── src/routes/
-│   ├── api/                 # 纯 API 服务（无 UI / 无 i18n）
-│   │   └── src/routes/
-│   ├── mobile-app/          # Svelte 5 + Vite + Capacitor 移动应用
-│   │   ├── index.html.hbs
-│   │   ├── messages/
-│   │   └── src/App.svelte.hbs
-│   └── fullstack/           # 前后端分离多包工程（contract / serv / web / app / desktop / miniapp 占位）
-│       ├── packages/        # 共享 contract 与后端 serv 包
-│       ├── apps/            # 多前端目标，按用户选择条件生成
-│       └── e2e/             # 服务端 + 页面级 Playwright 流程
-│
-├── features/                # 可选 feature 路由（叠加到 src/routes/）
-│   ├── iam/
-│   │   ├── routes-shared/   # 所有应用类型共用（API 端点）
-│   │   ├── routes-admin/    # admin 专属（登录/注册页 .hbs）
-│   │   └── routes-h5/       # h5 专属（登录/注册页 .hbs）
-│   ├── storage/
-│   │   └── routes/          # 上传 API
-│   └── ai/
-│       └── routes/          # 聊天流 API
-│
-├── i18n/                    # i18n 脚手架（hasI18n 时复制到项目根）
-│   └── project.inlang/
-│       └── settings.json    # Paraglide 项目配置
-│
-└── skills/                  # AI Skill 与各 appType 桥接指引
-    └── bridges/             # admin / api / website / h5 / mobile-app / fullstack 专属 AGENTS
-```
+## 核心功能清单
 
-## AI Skill 模板（Single Source of Truth）
-
-`templates/skills/` 是 CLI 生成共享 AI 上下文时的单一来源，同时用于 `hai create` 与 `hai add`。
-
-- `hai create` 会把 `templates/skills/` 下所有 `hai-*` Skill 目录复制到 `.agents/skills/<skill>/`，再按 appType 排除互斥项（例如 fullstack 不复制 `hai-kit`；admin / website / h5 不复制 `hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`；mobile-app 不复制 `hai-core`、`hai-kit`、`hai-serv`、`hai-api-contract`）
-- 通用 `copilot-instructions.md` 复制到 `.github/copilot-instructions.md`，只引用项目根 `AGENTS.md`，不另维护 appType 专属规则
-- `bridges/<appType>/AGENTS.md` 会复制到项目根目录，确保不同样板工程使用自己的 AI 指引；通用 `CLAUDE.md` 仅包含 `@AGENTS.md`
-- `opencode.json` 会复制到项目根目录
-- `templates/skills/AGENTS.md` 是缺少 appType 上下文时的通用规则；`CLAUDE.md`、`copilot-instructions.md` 与 `opencode.json` 是各工具的轻量入口，用于创建项目和回填 AI 支持
-- Codex 原生读取根 `AGENTS.md` 并发现 `.agents/skills/`，支持 `$hai-app-create` 等显式调用和按任务自动选择；无需 `.codex/skills` 或工具专属配置。依据：[Codex skills](https://learn.chatgpt.com/docs/build-skills)、[AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
-- `opencode.json` 使用 OpenCode 的 `instructions` 配置直接引用 `AGENTS.md`；`.agents/skills/` 由 OpenCode 原生发现，不再写入过期的 `skills.paths`
-- `CLAUDE.md` 通过 `@AGENTS.md` 复用共享规范，Claude Code 按其中的任务导航读取 `.agents/skills/` 正文与参考。CLI 不生成 `.claude/` 技能副本；此模式不提供 Claude 原生技能自动发现或 `/skill` 命令。依据：[Claude Code 项目指引](https://code.claude.com/docs/en/memory)、[原生 skills](https://code.claude.com/docs/en/skills)
-- `hai add` / `hai init` 只补齐缺失的 AI 支持文件，不覆盖用户已自定义的桥接文件，也不会自动删除遗留的 `.github/skills/` 或 `.claude/`
-
-## 文件类型说明
-
-| 类型                                       | 处理方式                                     |
-| ------------------------------------------ | -------------------------------------------- |
-| 普通文件（`.ts` / `.svelte` / `.json` 等） | 直接复制，内容不变                           |
-| `.hbs` 文件                                | 经 Handlebars 渲染后输出（去掉 `.hbs` 后缀） |
-
-## 渲染上下文（TemplateContext）
-
-所有 `.hbs` 文件可使用以下变量：
-
-| 变量                   | 类型      | 说明                                      |
-| ---------------------- | --------- | ----------------------------------------- |
-| `{{projectName}}`      | `string`  | 项目名称（如 `my-app`）                   |
-| `{{appType}}`          | `string`  | 应用类型                                  |
-| `{{hasUi}}`            | `boolean` | 是否包含 UI（非 `api` 类型为 `true`）     |
-| `{{hasI18n}}`          | `boolean` | 是否启用 i18n（非 `api` 类型为 `true`）   |
-| `{{isSvelteOnlyApp}}`  | `boolean` | 是否为不依赖 SvelteKit 的纯 Svelte 5 应用 |
-| `{{isCapacitorApp}}`   | `boolean` | 是否为 Capacitor 移动应用                 |
-| `{{defaultLocale}}`    | `string`  | 默认语言，如 `zh-CN`                      |
-| `{{packageManager}}`   | `string`  | 包管理器：`pnpm` / `npm` / `yarn`         |
-| `{{fullstack.*}}`      | `object`  | fullstack 类型专用上下文                  |
-| `{{features.iam}}`     | `boolean` | 是否选中 iam feature                      |
-| `{{features.db}}`      | `boolean` | 是否选中 db feature                       |
-| `{{features.cache}}`   | `boolean` | 是否选中 cache feature                    |
-| `{{features.crypto}}`  | `boolean` | 是否选中 crypto feature                   |
-| `{{features.storage}}` | `boolean` | 是否选中 storage feature                  |
-| `{{features.ai}}`      | `boolean` | 是否选中 ai feature                       |
-
-`appType` 支持 `admin` / `website` / `h5` / `api` / `mobile-app` / `fullstack`。
-
-H5 业务页面复用 `@h-ai/ui` 的 `BottomNav` 和移动端壳样式，桌面预览保持居中限宽，认证路由独立显示。
-
-`fullstack.*` 包含包名、前端选择、依赖版本、`contractExportName` 和原生壳 `nativeAppIdSegment`，用于渲染 contract / serv / 多端 UI / Capacitor / Tauri 模板。
-
-`moduleConfigs` 保留创建时指定的模块值。Fullstack 的模块 YAML 用 `{{{moduleConfig 'db' true}}}` 等 helper 复用 `cli-config-templates.ts`；可选模块传 `features.ai` 等开关，未选择时整份注释。创建流程保留已渲染的配置，不再用精简内容覆盖；core、serv、Reach 保留应用专用默认值及完整的可选字段。新增 Schema 字段同步此生成器和相应模板。
-
-所有根 `.gitignore`（base / api / fullstack）保留 `**/data/`，包括 `.gitkeep` 在内的运行数据不跟踪。Fullstack 服务端 config 始终含 core、serv、db、cache、iam、storage、audit、reach、ai、vecdb、payment、scheduler、deploy 共 13 份 YAML；不为无配置入口的 crypto/datapipe 生成 YAML。未启用块的后续接入步骤见 [CLI 配置说明](../README.md#应用配置与显示)。
-
-### 常用条件写法
-
-```handlebars
-{{!-- 按 feature 条件注入内容 --}}
-{{#if features.iam}}
-import { iam } from '@h-ai/iam'
-{{/if}}
-
-{{!-- 按 i18n 条件切换内容 --}}
-{{#if hasI18n}}
-  <title>{m.page_title()}</title>
-{{else}}
-  <title>首页</title>
-{{/if}}
-```
+- `admin`、`website`、`h5`：SvelteKit 应用。
+- `api`：共享 contract 与 API service 的 workspace。
+- `mobile-app`：Svelte + Vite + Capacitor 应用。
+- `fullstack`：contract、API、共享界面，以及按需选择的 Web/App/Desktop；miniapp 仅预留说明。
+- 后台工作区随窗口扩展；手机壳支持宽屏，表格在内部滚动，文章与认证表单保留阅读宽度。
+- 默认部署工具、独立镜像 Dockerfile、环境示例和可复制的 AI 技能。
+
+## 使用入门
+
+### 文件如何组合
 
-## 生成流程
+| 目录           | 用途                                                                |
+| -------------- | ------------------------------------------------------------------- |
+| `base/`        | 普通应用共用的配置、脚本和入口                                      |
+| `apps/<类型>/` | 应用专属页面、workspace、原生壳与配置；API/fullstack 维护自己的骨架 |
+| `features/`    | 按所选模块叠加的路由和页面                                          |
+| `i18n/`        | Paraglide 工程配置                                                  |
+| `skills/`      | 完整的技能目录与各类型 AI 入口                                      |
 
-模板引擎执行 6 个步骤：
+普通文件直接复制，`.hbs` 经 Handlebars 渲染并去掉后缀。`cli-template-engine.ts` 决定适用目录与条件；`cli-create.ts` 完成配置、镜像定义和根 README 等生成工作。修改前先查实际调用路径，API/fullstack 不套用 SvelteKit 文件路由。
 
-1. **复制 `base/` 静态文件** → 项目根
-2. **复制 `apps/{appType}/` 专属文件** → 项目根（`messages/` 仅 `hasI18n` 时复制）
-3. **叠加 feature 静态路由** → `src/routes/`（纯 Svelte 5 应用跳过 SvelteKit 路由）
-4. **渲染所有 `.hbs` 文件** — `base/` + `apps/{appType}/` 输出到项目根；`features/*/routes*/` 输出到 `src/routes/`
-5. **复制 `i18n/` 脚手架** → 项目根（仅 `hasI18n` 时）
-6. **确保 `static/` 目录存在**
+### 配置与构建
 
-## 新增模板
+模板通过 `projectName`、`appType`、`features`、`hasUi`、`hasI18n`、`versions` 以及 `api`/`fullstack` 上下文渲染，完整字段见 [cli-types.ts](../src/cli-types.ts)。模块 YAML 使用 `moduleConfig` helper，与 [配置生成器](../src/commands/cli-config-templates.ts) 共用字段和默认值。
 
-### 新增应用页面
+部署默认启用，`--no-deploy` 可关闭；SDK 是开发依赖。每个镜像使用 `images/` 中独立 Dockerfile，Web 资源放 `images/web/`。`hai.build.json` 直接选择文件；依赖输入由构建器生成到 `images/dependencies/`。所有根 `.gitignore` 均忽略 `**/images/dependencies/`、运行数据和私有环境文件。
 
-在 `apps/{appType}/src/routes/` 下创建 `.svelte` 或 `.svelte.hbs` 文件。若含用户可见文本，使用 `.hbs` 并加 `{{#if hasI18n}}` 条件，同时在对应的 `apps/{appType}/messages/` 里补充 i18n key。
+Fullstack 服务端保留各模块的配置示例，未使用模块保持注释。安装依赖、校验和初始化、接入业务后才启用对应配置。修改公开 Schema 时同步配置生成器、环境变量说明、调用方与技能。
 
-### 新增 feature 路由
+### AI 指引
 
-在 `features/{featureId}/routes-shared/`（API 路由）或 `features/{featureId}/routes-{appType}/`（UI 页面）下创建文件，然后在 `cli-template-engine.ts` 的 `FEATURE_ROUTE_DIRS` / `FEATURE_APP_ROUTE_DIRS` 中注册该目录。
+`skills/hai-*` 的完整目录复制到生成应用 `.agents/skills/`，按应用架构排除不适用项。`bridges/<类型>/AGENTS.md` 提供根入口；Claude/Copilot/OpenCode 配置只引用共享规则。新增参考文件必须随 skill 一起复制，不能链接回框架私有路径。
 
-## 配置驱动认证页面
+`hai add` / `hai init` 补齐缺失文件，保留应用已有的自定义内容。框架升级时按目标发布版本比较并合并，不直接覆盖应用规则。
 
-协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+### 页面与文案
 
-选用 IAM 的 admin/h5/website 模板提供 AuthPanel 和标准认证路由；mobile-app 与 fullstack Web/App/Desktop 使用 API 客户端共享动作。修改服务端 config/_iam.yml 即可控制登录方式、注册、重置、协议和品牌，无需改表单。配置 Reach 模板和真实发送 Provider 后启用 OTP/重置。分布式部署使用共享数据库与 Redis。
+用户可见文本加入对应 messages。认证复用 AuthPanel 与服务端公开 IAM 配置；表单复用 Form/FormLayout/FormField。业务规则由应用需求决定，模板默认角色、流程和限额可调整，修改时同步授权、界面、测试和文档。
+
+## 开发测试
+
+维护模板时保留 `shared/.gitattributes`，让生成工程的 `.dockerignore`、Dockerfile 和 POSIX 脚本统一使用 LF，保持跨平台输入一致并确保 Linux 脚本可运行。在仓库根执行：
+
+```sh
+pnpm --filter @h-ai/cli typecheck
+pnpm --filter @h-ai/cli lint
+pnpm --filter @h-ai/cli build
+pnpm --filter @h-ai/cli test
+pnpm check:skills
+pnpm --filter @h-ai/cli test:scaffold-gates
+pnpm --filter @h-ai/cli test:deploy-gates
+```
 
-LDAP/Reach 是可选 peer；IAM 不强制启用 Reach。默认 LDAP 客户端由应用选择安装 ldapts。自定义通知回调、协议弹窗、表单 snippet 用法随 hai-iam/hai-ui skills 完整复制到生成项目，不能要求应用读取本仓库私有路径。
+脚手架门禁会生成项目并执行安装、类型检查、lint、构建、测试和浏览器流程。部署门禁另需可用 Podman/Docker，验证镜像构建、隔离服务器上的 SSH/人工部署与部分更新。原生安装包和真实第三方服务需要各自的验收环境。
 
-## 表单布局
+## 许可证
 
-新增/编辑复用 `@h-ai/ui` 的 Form/FormLayout/FormField：可选一列或双列、标签独立成行或与控件同行，多行文本与多选自动跨列，窄容器自动收为一列。CRUD 使用 `form` 配置，字段可用 `colSpan` 覆盖。错误显示在字段附近并随 UI 语言更新。website 联系页采用 FormLayout + FormField；fullstack 共享用户编辑页采用双列同行标签，个人资料与密码页复用 UI 场景组件。没有数据表单的模板保留现有骨架，新增表单按 hai-ui skill 接入。
+Apache-2.0

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

@@ -29,7 +29,7 @@
 
 <div class='drawer lg:drawer-open'>
   <input id='admin-drawer' type='checkbox' class='drawer-toggle' />
-  <div class='drawer-content p-6'>
+  <div class='drawer-content min-w-0 p-4 sm:p-6'>
     <label for='admin-drawer' class='btn btn-ghost btn-sm drawer-button lg:hidden mb-4'>
       <span class='icon-[tabler--menu-2] size-5'></span>
     </label>

package/templates/apps/api/.dockerignore.hbs

@@ -1,16 +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
 .github
 .agents
 .claude
 .codex
 .opencode
-.turbo
-build
-dist
-node_modules
-playwright-report
-test-results
 **/data
 *.log
 # 仅保留公共基础 .env；分环境配置、私有覆盖及已有交付包不进入构建上下文。

package/templates/apps/api/.gitignore.hbs

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

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

@@ -1,8 +1,18 @@
 # {{api.contractPackageName}}
 
+## 简介
+
 {{projectName}} API service 的共享 contract 包。
 
-## 包含内容
+## 核心功能清单
+
+- 共享接口路径、输入输出 Schema 和类型。
+- 客户端与服务端使用同一份 contract。
+- 不包含服务端业务实现，也不加载私有配置。
+
+## 使用入门
+
+### 包含内容
 
 - `app-contract.ts`：应用级接口定义，业务 path 与一次性输出 Schema 就近内联
 - `app-schemas.ts`：跨接口、跨层复用的输入/数据 Zod Schema
@@ -10,9 +20,20 @@
 
 API 前缀、健康检查与跨端 Header 等传输配置位于 service 的 `config/_serv.yml`。
 
-## 常用命令
+### 常用命令
 
 ```bash
 pnpm --filter {{api.contractPackageName}} build
 pnpm --filter {{api.contractPackageName}} test
 ```
+
+## 开发测试
+
+```sh
+pnpm --filter {{api.contractPackageName}} typecheck
+pnpm --filter {{api.contractPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

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

@@ -1,21 +1,31 @@
 # {{api.servicePackageName}}
 
+## 简介
+
 {{projectName}} API service 包，负责模块初始化、procedure 装配与 HTTP 入口。
 
-## 常用命令
+## 核心功能清单
+
+- 初始化所选框架模块，装配共享接口并提供 HTTP 服务。
+- 配置、健康检查和应用 procedures 各有明确入口。
+- 从工程根构建镜像，支持自动发布与离线包。
+
+## 使用入门
+
+### 常用命令
 
 ```bash
 pnpm --filter {{api.servicePackageName}} dev
 pnpm --filter {{api.servicePackageName}} test
 ```
 
-## 容器运行
+### 容器运行
+
 
-从工程根运行 `pnpm build --target docker` 构建并导出镜像，再运行 `pnpm deploy --env test`。deploy 只消费已构建镜像；含 Web 时一并发布 API/Web。网络不通用 `pnpm deploy --env prod --bundle-only`，按输出说明手工搬运 tar。
 - 配置默认打包自本目录 `config/`，可在运行时只读挂载到 `/app/config`，敏感值通过环境变量注入。
-从工程根运行 `pnpm build --target docker` 构建并导出镜像，再运行 `pnpm deploy --env test`。deploy 只消费已构建镜像；含 Web 时一并发布 API/Web。网络不通用 `pnpm deploy --env prod --bundle-only`，按输出说明手工搬运 tar。
 
-## 关键目录
+
+### 关键目录
 
 - `config/`：service 配置
 - `src/app.ts`：HTTP App 装配
@@ -23,9 +33,9 @@ pnpm --filter {{api.servicePackageName}} test
 - `src/server/procedures/`：应用级 procedures
 
 {{#if features.iam}}
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。客户端可通过安全公开配置和框架认证动作接入 `AuthPanel`。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。客户端可通过安全公开配置和框架认证动作接入 `AuthPanel`。单实例可使用 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。
 
@@ -33,3 +43,14 @@ LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IA
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}
+
+## 开发测试
+
+```sh
+pnpm --filter {{api.servicePackageName}} typecheck
+pnpm --filter {{api.servicePackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

package/templates/apps/api/apps/{{projectName}}-service/package.json.hbs

@@ -43,8 +43,7 @@
     "@h-ai/audit": "{{haiPackageSpecifier}}"{{/if}}{{#if features.cache}},
     "@h-ai/cache": "{{haiPackageSpecifier}}"{{/if}}{{#if features.crypto}},
     "@h-ai/crypto": "{{haiPackageSpecifier}}"{{/if}}{{#if features.datapipe}},
-    "@h-ai/datapipe": "{{haiPackageSpecifier}}"{{/if}}{{#if features.deploy}},
-    "@h-ai/deploy": "{{haiPackageSpecifier}}"{{/if}}{{#if features.iam}},
+    "@h-ai/datapipe": "{{haiPackageSpecifier}}"{{/if}}{{#if features.iam}},
     "@h-ai/iam": "{{haiPackageSpecifier}}"{{/if}}{{#if features.payment}},
     "@h-ai/payment": "{{haiPackageSpecifier}}"{{/if}}{{#if features.reach}},
     "@h-ai/reach": "{{haiPackageSpecifier}}"{{/if}}{{#if features.db}},

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

@@ -15,7 +15,9 @@
     "dev:prod": "pnpm --filter {{api.servicePackageName}} dev:prod",
     "compile": "pnpm --filter {{api.contractPackageName}} build && 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/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。
 
 协议支持配置中的 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/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/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',