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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.66",
+  "version": "0.1.0-alpha.68",
   "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.68",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,12 +41,13 @@
     "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/api-client": "0.1.0-alpha.68",
+    "@h-ai/cache": "0.1.0-alpha.68",
+    "@h-ai/crypto": "0.1.0-alpha.68",
+    "@h-ai/deploy": "0.1.0-alpha.68",
+    "@h-ai/reach": "0.1.0-alpha.68",
+    "@h-ai/reldb": "0.1.0-alpha.68",
+    "@h-ai/storage": "0.1.0-alpha.68",
     "@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/messages/ja-JP.json

@@ -0,0 +1,38 @@
+{
+  "app_title": "管理コンソール",
+  "app_description": "hai Agent Frameworkで構築した管理コンソール",
+  "meta_description": "管理コンソール — 企業管理システム",
+  "nav_home": "ホーム",
+  "nav_dashboard": "ダッシュボード",
+  "nav_settings": "設定",
+  "nav_admin": "管理画面へ",
+  "page_home_title": "管理コンソール",
+  "page_home_subtitle": "hai Agent Frameworkで構築",
+  "page_home_badge": "Powered by hai",
+  "page_dashboard_title": "ダッシュボード",
+  "page_dashboard_subtitle": "システム稼働状況の概要",
+  "page_dashboard_total_users": "総ユーザー数",
+  "page_dashboard_today_active": "本日のアクティブユーザー",
+  "page_dashboard_revenue": "月間売上",
+  "page_dashboard_orders": "未処理の注文",
+  "page_settings_title": "システム設定",
+  "page_settings_subtitle": "システム設定を管理",
+  "page_settings_basic": "基本設定",
+  "page_settings_desc": "ここでシステムの設定を管理します。",
+  "auth_login_title": "ログイン",
+  "auth_login_submit": "ログイン",
+  "auth_login_loading": "ログイン中...",
+  "auth_login_failed": "ログインに失敗しました",
+  "auth_login_to_register": "アカウントをお持ちでない方は新規登録",
+  "auth_register_title": "登録",
+  "auth_register_submit": "登録",
+  "auth_register_loading": "登録中...",
+  "auth_register_failed": "登録に失敗しました",
+  "auth_register_to_login": "既にアカウントをお持ちの方はログイン",
+  "auth_label_username": "ユーザー名",
+  "auth_label_email": "メールアドレス",
+  "auth_label_password": "パスワード",
+  "auth_label_confirm_password": "パスワードの確認",
+  "auth_error_network": "ネットワークエラー",
+  "auth_error_password_mismatch": "パスワードが一致しません"
+}

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

@@ -9,8 +9,8 @@
 {{/if}}
   import { page } from '$app/state'
 {{#if hasI18n}}
-  import { getLocale } from '$lib/paraglide/runtime.js'
-  import { setGlobalLocale } from '@h-ai/ui'
+  import { getLocale, setLocale } from '$lib/paraglide/runtime.js'
+  import { LanguageSwitch, setGlobalLocale } from '@h-ai/ui'
 {{/if}}
   import '../app.css'
 
@@ -21,6 +21,11 @@
   const { children }: Props = $props()
 {{#if hasI18n}}
 
+  function handleLanguageChange(language: string) {
+    setGlobalLocale(language)
+    setLocale(language as Parameters<typeof setLocale>[0])
+  }
+
   if (browser) {
     const paraglideLocale = getLocale()
     setGlobalLocale(paraglideLocale)
@@ -32,8 +37,13 @@
   <title>{page.data.appConfig.name}</title>
 </svelte:head>
 
-<div class='min-h-screen flex flex-col bg-base-200'>
-  <header class='navbar border-b border-base-300 bg-base-100 px-6'><span class='text-lg font-semibold'>{page.data.appConfig.name}</span></header>
-  <div class='flex-1'>{@render children()}</div>
-  <footer class='border-t border-base-300 bg-base-100 p-3 text-center text-xs text-base-content/60'>{page.data.appConfig.name} · {page.data.appConfig.version} · {page.data.appConfig.env}</footer>
+<div class='h-dvh flex flex-col overflow-hidden bg-base-200'>
+  <header class='navbar shrink-0 border-b border-base-300 bg-base-100 px-6'>
+    <span class='flex-1 text-lg font-semibold'>{page.data.appConfig.name}</span>
+{{#if hasI18n}}
+    <LanguageSwitch currentLanguage={getLocale()} onchange={handleLanguageChange} />
+{{/if}}
+  </header>
+  <div class='flex min-h-0 flex-1 flex-col overflow-auto'>{@render children()}</div>
+  <footer class='shrink-0 border-t border-base-300 bg-base-100 p-3 text-center text-xs text-base-content/60'>{page.data.appConfig.name} · {page.data.appConfig.version} · {page.data.appConfig.env}</footer>
 </div>

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

@@ -27,10 +27,10 @@
   ] as const)
 </script>
 
-<div class='drawer lg:drawer-open'>
+<div class='drawer min-h-0 flex-1 lg:drawer-open'>
   <input id='admin-drawer' type='checkbox' class='drawer-toggle' />
-  <div class='drawer-content p-6'>
-    <label for='admin-drawer' class='btn btn-ghost btn-sm drawer-button lg:hidden mb-4'>
+  <div class='drawer-content flex min-h-0 min-w-0 flex-col overflow-auto p-4 sm:p-6'>
+    <label for='admin-drawer' class='btn btn-ghost btn-sm drawer-button shrink-0 self-start lg:hidden mb-4'>
       <span class='icon-[tabler--menu-2] size-5'></span>
     </label>
     {@render children()}

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}}-contract/src/index.ts.hbs

@@ -1,3 +1,5 @@
 export * from './app-contract.js'
 export * from './app-schemas.js'
 export * from './{{projectName}}-contract.js'
+
+// @hai-generator:contracts:exports

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

@@ -1,12 +1,15 @@
 import { apiContract } from '@h-ai/api-contract'
 import { appContract } from './app-contract.js'
 
+// @hai-generator:contracts:imports
+
 /** 工程级应用 contract。 */
 export const {{api.contractExportName}} = apiContract.create({
 {{#if features.iam}}  iam: apiContract.iam,
 {{/if}}{{#if features.storage}}  storage: apiContract.storage,
 {{/if}}{{#if features.ai}}  ai: apiContract.ai,
-{{/if}}  app: appContract,
+{{/if}}  // @hai-generator:contracts:entries
+  app: appContract,
 })
 
 export type ApiWorkspaceContract = typeof {{api.contractExportName}}

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

@@ -1,21 +1,35 @@
 # {{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。
 
-## 关键目录
+
+### 关键目录
+
+{{#if features.crypto}}启用 transport 时，`serverKeyRing` 与客户端 `keyStore` 都必须显式提供。CLI 在本服务被忽略的 `.env.local` 中一次性生成独立开发 ring，变量为 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`；运行时不生成密钥。部署使用 Secret Manager 向所有节点分发相同受管 ring，配合共享数据库 registry。公钥/版本参与协商，私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发新旧版本再切 activeKeyId，过渡期后撤销旧 ID；无需会话粘性。
+{{#unless features.db}}本模板未选择 db，registry 仅在 development/test 显式使用内存；production/staging 会拒绝启动 transport。选择 db 并配置共享数据库后再部署，或显式关闭 transport。
+{{/unless}}{{/if}}
 
 - `config/`：service 配置
 - `src/app.ts`：HTTP App 装配
@@ -23,13 +37,24 @@ 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。
+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`。
 {{/if}}
+
+## 开发测试
+
+```sh
+pnpm --filter {{api.servicePackageName}} typecheck
+pnpm --filter {{api.servicePackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

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

@@ -5,7 +5,6 @@
 name: {{projectName}} API Service
 version: 0.1.0
 env: ${HAI_CORE_ENV:development}
-debug: ${HAI_CORE_DEBUG:false}
 
 logging:
   level: info
@@ -16,12 +15,3 @@ logging:
     - secret
 
 defaultLocale: {{defaultLocale}}
-supportedLocales:
-{{#if_eq defaultLocale 'en-US'}}  - en-US
-  - zh-CN
-{{else}}  - zh-CN
-  - en-US
-{{/if_eq}}
-
-features:
-  apiAccess: true

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

@@ -27,11 +27,13 @@ cors:
     - Content-Type
 {{#if features.crypto}}    - X-Client-Id
     - X-Encrypted
+    - X-Hai-Transport
 {{/if}}    - X-Hai-Locale
     - X-Request-Id
     - X-Requested-With
   exposedHeaders:
 {{#if features.crypto}}    - X-Encrypted
+    - X-Hai-Transport
 {{/if}}    - X-Request-Id
 
 {{#if features.crypto}}transport:
@@ -42,6 +44,5 @@ cors:
     - /openapi.json
     - /docs
     - /_hai/scalar.js
-  maxClients: 10000
 {{else}}transport: false
 {{/if}}

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/apps/{{projectName}}-service/src/app.ts.hbs

@@ -1,9 +1,12 @@
 import type { CoreConfig } from '@h-ai/core'
-import type { ServConfig } from '@h-ai/serv'
+import type { ServConfig{{#if features.crypto}}, ServTransportConfig{{/if}} } from '@h-ai/serv'
+{{#if features.crypto}}import process from 'node:process'
+{{/if}}
 import { core } from '@h-ai/core'
-{{#if features.crypto}}import { crypto } from '@h-ai/crypto'
+{{#if features.crypto}}import { {{#if features.db}}createReldbTransportKeyStore{{else}}createInMemoryKeyStore{{/if}}, crypto, parseTransportServerKeyRing } from '@h-ai/crypto'
 {{/if}}{{#if features.iam}}import { iam } from '@h-ai/iam'
-{{/if}}import { serv } from '@h-ai/serv'
+{{/if}}{{#if features.crypto}}{{#if features.db}}import { reldb } from '@h-ai/reldb'
+{{/if}}{{/if}}import { serv } from '@h-ai/serv'
 import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
 import { {{api.serviceProceduresFactoryName}} } from './server/procedures/index.js'
 
@@ -24,14 +27,24 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
     nativeOrigins: servConfig.cors.nativeOrigins,
   })
 {{#if features.crypto}}  const transportMode = _options.transport ?? 'config'
-  const transport = transportMode === 'disabled' || servConfig.transport === false
-    ? undefined
-    : {
-        crypto,
-        keyExchangePath: servConfig.transport.keyExchangePath,
-        excludePaths: [...servConfig.transport.excludePaths],
-        maxClients: servConfig.transport.maxClients,
-      }
+  let transport: ServTransportConfig | undefined
+  if (transportMode !== 'disabled' && servConfig.transport !== false) {
+{{#unless features.db}}    if (coreConfig.env !== 'development' && coreConfig.env !== 'test')
+      throw new Error('Production transport requires a shared registry; enable the db feature and configure a shared database')
+{{/unless}}
+    const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+    if (!ring.success)
+      throw new Error(ring.error.message)
+    transport = {
+      crypto,
+      serverKeyRing: ring.data,
+{{#if features.db}}      keyStore: createReldbTransportKeyStore({ reldb, ttlSeconds: 3600 }),
+{{else}}      keyStore: createInMemoryKeyStore(), // 无 db 的模板仅在 development/test 使用内存 registry。
+{{/if}}
+      keyExchangePath: servConfig.transport.keyExchangePath,
+      excludePaths: [...servConfig.transport.excludePaths],
+    }
+  }
 {{else}}  const transport = undefined
 {{/if}}
 {{#if features.iam}}