@h-ai/cli 0.1.0-alpha.19 → 0.1.0-alpha.21

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.21",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -34,7 +34,7 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.19"
+    "@h-ai/core": "0.1.0-alpha.21"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -52,6 +52,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run",
+    "test:e2e": "pnpm test:scaffold-gates",
     "test:scaffold-gates": "pnpm build && node tests/run-scaffold-gates.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

package/templates/README.md

@@ -9,13 +9,13 @@ templates/
 ├── base/                    # 所有应用类型共用的骨架文件
 │   ├── package.json.hbs     # 动态：按 features 注入依赖
 │   ├── vite.config.ts.hbs   # 动态：按 hasI18n / hasUi 注入插件
-│   ├── tsconfig.json
-│   ├── svelte.config.js
-│   ├── .gitignore
+│   ├── 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         # 动态：i18n 时输出 %lang% 占位符
-│       ├── app.d.ts
+│       ├── app.html.hbs         # 动态：SvelteKit 应用输出 app shell
+│       ├── app.d.ts.hbs         # 动态：SvelteKit 应用输出 App namespace
 │       ├── app.css
 │       ├── hooks.server.ts.hbs  # 动态：按 features / hasI18n 组装 handle 序列
 │       └── lib/server/
@@ -33,6 +33,10 @@ templates/
 │   │   └── 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/            # 多前端目标，按用户选择条件生成
@@ -52,17 +56,20 @@ templates/
 │   └── project.inlang/
 │       └── settings.json    # Paraglide 项目配置
 │
-└── skills/                  # AI Skill 单一来源模板（分发到 .agents/skills/）
+└── skills/                  # AI Skill 与各 appType 桥接指引
+    └── bridges/             # admin / api / website / h5 / mobile-app / fullstack 专属 AGENTS/Copilot/Claude
 ```
 
 ## AI Skill 模板（Single Source of Truth）
 
 `templates/skills/` 是 CLI 生成共享 AI 上下文时的单一来源，同时用于 `hai create` 与 `hai add`。
 
-- 每个 Skill 目录会复制到 `.agents/skills/<skill>/`
-- `copilot-instructions.md` 会复制到 `.github/copilot-instructions.md`，并引导 Copilot/其他助手读取 `.agents/skills/`
-- `AGENTS.md`、`CLAUDE.md`、`opencode.json` 会复制到项目根目录
-- `opencode.json` 使用 OpenCode 的 `instructions` 与 `skills.paths` 配置，将项目级指令与 Skill 目录显式指向 `AGENTS.md` 和 `.agents/skills/`
+- `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`）
+- `bridges/<appType>/copilot-instructions.md` 会复制到 `.github/copilot-instructions.md`；没有专属文件时回退到通用桥接文件
+- `bridges/<appType>/AGENTS.md`、`bridges/<appType>/CLAUDE.md` 会复制到项目根目录，确保不同样板工程使用自己的 AI 指引
+- `opencode.json` 会复制到项目根目录
+- `templates/skills/AGENTS.md`、`CLAUDE.md`、`copilot-instructions.md` 与 `opencode.json` 不是多余副本：它们是 generic fallback，主要服务于缺少 appType 上下文时的桥接复制与 `hai add` 回填 AI 支持
+- `opencode.json` 使用 OpenCode 的 `instructions` 配置复用 `.github/copilot-instructions.md`；`.agents/skills/` 由 OpenCode 原生发现，不再写入过期的 `skills.paths`
 - `CLAUDE.md` 作为 Claude Code 的原生项目指引入口，并通过 `@AGENTS.md` 复用共享规范；`.agents/skills/` 仍是共享参考目录，而非 Claude Code 的原生 project skills 目录
 - `hai add` 只补齐缺失的 AI 支持文件，不覆盖用户已自定义的桥接文件，也不会自动删除遗留的 `.github/skills/`
 
@@ -77,23 +84,27 @@ templates/
 
 所有 `.hbs` 文件可使用以下变量：
 
-| 变量                   | 类型      | 说明                                         |
-| ---------------------- | --------- | -------------------------------------------- |
-| `{{projectName}}`      | `string`  | 项目名称（如 `my-app`）                      |
-| `{{appType}}`          | `string`  | 应用类型：`admin` / `website` / `h5` / `api` |
-| `{{hasUi}}`            | `boolean` | 是否包含 UI（非 `api` 类型为 `true`）        |
-| `{{hasI18n}}`          | `boolean` | 是否启用 i18n（非 `api` 类型为 `true`）      |
-| `{{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                          |
-
-`fullstack.*` 包含包名、前端选择、依赖版本和 `contractExportName`，用于渲染 contract / serv / 多端 UI 的模板。
+| 变量                   | 类型      | 说明                                      |
+| ---------------------- | --------- | ----------------------------------------- |
+| `{{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`。
+
+`fullstack.*` 包含包名、前端选择、依赖版本、`contractExportName` 和原生壳 `nativeAppIdSegment`，用于渲染 contract / serv / 多端 UI / Capacitor / Tauri 模板。
 
 ### 常用条件写法
 
@@ -116,8 +127,8 @@ import { iam } from '@h-ai/iam'
 模板引擎执行 6 个步骤：
 
 1. **复制 `base/` 静态文件** → 项目根
-2. **复制 `apps/{appType}/` 路由** → 项目根（`messages/` 仅 `hasI18n` 时复制）
-3. **叠加 feature 静态路由** → `src/routes/`
+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/` 目录存在**

package/templates/apps/admin/messages/en-US.json

@@ -8,10 +8,15 @@
   "nav_admin": "Enter Admin",
   "page_home_title": "Admin Console",
   "page_home_subtitle": "Built with hai Agent Framework",
+  "page_home_badge": "Powered by hai",
   "page_dashboard_title": "Dashboard",
+  "page_dashboard_subtitle": "Overview of system operations",
   "page_dashboard_total_users": "Total Users",
   "page_dashboard_today_active": "Today Active",
+  "page_dashboard_revenue": "Monthly Revenue",
+  "page_dashboard_orders": "Pending Orders",
   "page_settings_title": "System Settings",
+  "page_settings_subtitle": "Manage system configuration",
   "page_settings_basic": "Basic Configuration",
   "page_settings_desc": "Manage system settings here.",
   "auth_login_title": "Login",

package/templates/apps/admin/messages/zh-CN.json

@@ -8,10 +8,15 @@
   "nav_admin": "进入后台",
   "page_home_title": "管理后台",
   "page_home_subtitle": "基于 hai Agent Framework 构建",
+  "page_home_badge": "由 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": "登录",

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

@@ -1,21 +1,21 @@
 {{!-- 管理后台根布局 --}}
-<script lang="ts">
+<script lang='ts'>
   /**
    * 管理后台根布局
    */
   import type { Snippet } from 'svelte'
-  import '../app.css'
 {{#if hasI18n}}
   import { browser } from '$app/environment'
-  import { setGlobalLocale } from '@h-ai/ui'
   import { getLocale } from '$lib/paraglide/runtime.js'
+  import { setGlobalLocale } from '@h-ai/ui'
 {{/if}}
+  import '../app.css'
 
   interface Props {
     children: Snippet
   }
 
-  let { children }: Props = $props()
+  const { children }: Props = $props()
 {{#if hasI18n}}
 
   if (browser) {
@@ -25,6 +25,6 @@
 {{/if}}
 </script>
 
-<div class="min-h-screen bg-base-200">
+<div class='min-h-screen bg-base-200'>
   {@render children()}
 </div>

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

@@ -1,11 +1,13 @@
 {{!-- 管理后台首页 --}}
-<script lang="ts">
+<script lang='ts'>
   /**
    * 管理后台首页 — 入口导航
    */
+  import { resolve } from '$app/paths'
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
 {{/if}}
+  import { Badge, Card } from '@h-ai/ui'
 </script>
 
 <svelte:head>
@@ -16,20 +18,38 @@
 {{/if}}
 </svelte:head>
 
-<main class="min-h-screen flex items-center justify-center">
-  <div class="text-center">
+<main class='min-h-screen flex items-center justify-center p-6'>
+  <Card shadow='lg' padding='xl' class='w-full max-w-xl bg-base-100 text-center'>
 {{#if hasI18n}}
-    <h1 class="text-4xl font-bold mb-4">{m.app_title()}</h1>
-    <p class="text-gray-600 mb-8">{m.page_home_subtitle()}</p>
-    <div class="flex gap-4 justify-center">
-      <a href="/admin" class="btn btn-primary">{m.nav_admin()}</a>
+    <div class='flex justify-center'>
+      <Badge variant='primary'>
+        <span class='icon-[tabler--sparkles] size-4'></span>
+        {m.page_home_badge()}
+      </Badge>
+    </div>
+    <h1 class='mt-4 text-4xl font-black tracking-tight'>{m.app_title()}</h1>
+    <p class='mt-3 text-base-content/60'>{m.page_home_subtitle()}</p>
+    <div class='mt-8 flex flex-wrap gap-3 justify-center'>
+      <a href={resolve('/admin', {})} class='btn btn-primary'>
+        <span class='icon-[tabler--layout-dashboard] size-5'></span>
+        {m.nav_admin()}
+      </a>
     </div>
 {{else}}
-    <h1 class="text-4xl font-bold mb-4">管理后台</h1>
-    <p class="text-gray-600 mb-8">基于 hai Agent Framework 构建</p>
-    <div class="flex gap-4 justify-center">
-      <a href="/admin" class="btn btn-primary">进入后台</a>
+    <div class='flex justify-center'>
+      <Badge variant='primary'>
+        <span class='icon-[tabler--sparkles] size-4'></span>
+        由 hai 驱动
+      </Badge>
+    </div>
+    <h1 class='mt-4 text-4xl font-black tracking-tight'>管理后台</h1>
+    <p class='mt-3 text-base-content/60'>基于 hai Agent Framework 构建</p>
+    <div class='mt-8 flex flex-wrap gap-3 justify-center'>
+      <a href={resolve('/admin', {})} class='btn btn-primary'>
+        <span class='icon-[tabler--layout-dashboard] size-5'></span>
+        进入后台
+      </a>
     </div>
 {{/if}}
-  </div>
+  </Card>
 </main>

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

@@ -1,9 +1,11 @@
 {{!-- 后台管理布局（侧边栏 + 内容区） --}}
-<script lang="ts">
+<script lang='ts'>
   /**
    * 后台管理布局（侧边栏 + 内容区）
    */
   import type { Snippet } from 'svelte'
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
 {{/if}}
@@ -12,33 +14,48 @@
     children: Snippet
   }
 
-  let { children }: Props = $props()
+  const { children }: Props = $props()
+
+  const navItems = $derived([
+{{#if hasI18n}}
+    { path: '/admin', label: m.nav_dashboard(), icon: 'icon-[tabler--layout-dashboard]' },
+    { path: '/admin/settings', label: m.nav_settings(), icon: 'icon-[tabler--settings]' },
+{{else}}
+    { path: '/admin', label: '仪表盘', icon: 'icon-[tabler--layout-dashboard]' },
+    { path: '/admin/settings', label: '设置', icon: 'icon-[tabler--settings]' },
+{{/if}}
+  ] as const)
 </script>
 
-<div class="drawer 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 drawer-button lg:hidden mb-4">
-      ☰
+<div class='drawer 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'>
+      <span class='icon-[tabler--menu-2] size-5'></span>
     </label>
     {@render children()}
   </div>
-  <div class="drawer-side">
-    <label for="admin-drawer" class="drawer-overlay"></label>
-    <nav class="menu p-4 w-64 min-h-full bg-base-100 text-base-content">
+  <div class='drawer-side'>
+    <label for='admin-drawer' class='drawer-overlay' aria-label='close sidebar'></label>
+    <nav class='menu p-4 w-64 min-h-full gap-1 bg-base-100 text-base-content border-r border-base-300/60'>
+      <div class='flex items-center gap-2 px-2 mb-6 text-xl font-bold'>
+        <span class='icon-[tabler--cube] size-6 text-primary'></span>
 {{#if hasI18n}}
-      <div class="text-xl font-bold mb-6 px-2">{m.app_title()}</div>
-      <ul>
-        <li><a href="/admin">{m.nav_dashboard()}</a></li>
-        <li><a href="/admin/settings">{m.nav_settings()}</a></li>
-      </ul>
+        {m.app_title()}
 {{else}}
-      <div class="text-xl font-bold mb-6 px-2">管理后台</div>
-      <ul>
-        <li><a href="/admin">仪表盘</a></li>
-        <li><a href="/admin/settings">设置</a></li>
-      </ul>
+        管理后台
 {{/if}}
+      </div>
+      <ul class='gap-1'>
+        {#each navItems as item (item.path)}
+          <li>
+            <a href={resolve(item.path, {})} class:menu-active={page.url.pathname === item.path}>
+              <span class='{item.icon} size-5'></span>
+              {item.label}
+            </a>
+          </li>
+        {/each}
+      </ul>
     </nav>
   </div>
 </div>

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

@@ -1,10 +1,27 @@
 {{!-- 仪表盘页面 --}}
-<script lang="ts">
+<script lang='ts'>
   /**
    * 仪表盘页面
    */
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
+{{/if}}
+  import { Card, PageHeader } from '@h-ai/ui'
+{{#if hasI18n}}
+
+  const stats = $derived([
+    { label: m.page_dashboard_total_users(), value: '0', icon: 'icon-[tabler--users]', accent: 'text-primary' },
+    { label: m.page_dashboard_today_active(), value: '0', icon: 'icon-[tabler--activity]', accent: 'text-success' },
+    { label: m.page_dashboard_revenue(), value: '¥0', icon: 'icon-[tabler--coin]', accent: 'text-warning' },
+    { label: m.page_dashboard_orders(), value: '0', icon: 'icon-[tabler--shopping-cart]', accent: 'text-info' },
+  ])
+{{else}}
+  const stats = [
+    { label: '总用户', value: '0', icon: 'icon-[tabler--users]', accent: 'text-primary' },
+    { label: '今日活跃', value: '0', icon: 'icon-[tabler--activity]', accent: 'text-success' },
+    { label: '本月营收', value: '¥0', icon: 'icon-[tabler--coin]', accent: 'text-warning' },
+    { label: '待处理订单', value: '0', icon: 'icon-[tabler--shopping-cart]', accent: 'text-info' },
+  ]
 {{/if}}
 </script>
 
@@ -17,29 +34,21 @@
 </svelte:head>
 
 {{#if hasI18n}}
-<h1 class="text-2xl font-bold mb-6">{m.page_dashboard_title()}</h1>
-
-<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
-  <div class="stat bg-base-100 rounded-box shadow">
-    <div class="stat-title">{m.page_dashboard_total_users()}</div>
-    <div class="stat-value">0</div>
-  </div>
-  <div class="stat bg-base-100 rounded-box shadow">
-    <div class="stat-title">{m.page_dashboard_today_active()}</div>
-    <div class="stat-value">0</div>
-  </div>
-</div>
+<PageHeader title={m.page_dashboard_title()} description={m.page_dashboard_subtitle()} />
 {{else}}
-<h1 class="text-2xl font-bold mb-6">仪表盘</h1>
+<PageHeader title='仪表盘' description='系统运营数据总览' />
+{{/if}}
 
-<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
-  <div class="stat bg-base-100 rounded-box shadow">
-    <div class="stat-title">总用户</div>
-    <div class="stat-value">0</div>
-  </div>
-  <div class="stat bg-base-100 rounded-box shadow">
-    <div class="stat-title">今日活跃</div>
-    <div class="stat-value">0</div>
-  </div>
+<div class='grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-4 gap-4'>
+  {#each stats as stat (stat.label)}
+    <Card shadow='sm' class='bg-base-100'>
+      <div class='flex items-center justify-between'>
+        <div>
+          <div class='text-sm text-base-content/55'>{stat.label}</div>
+          <div class='mt-1 text-3xl font-bold tracking-tight'>{stat.value}</div>
+        </div>
+        <span class='{stat.icon} {stat.accent} size-9'></span>
+      </div>
+    </Card>
+  {/each}
 </div>
-{{/if}}

package/templates/apps/admin/src/routes/admin/settings/+page.svelte.hbs

@@ -1,11 +1,12 @@
 {{!-- 设置页面 --}}
-<script lang="ts">
+<script lang='ts'>
   /**
    * 设置页面
    */
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
 {{/if}}
+  import { Card, PageHeader } from '@h-ai/ui'
 </script>
 
 <svelte:head>
@@ -17,21 +18,23 @@
 </svelte:head>
 
 {{#if hasI18n}}
-<h1 class="text-2xl font-bold mb-6">{m.page_settings_title()}</h1>
+<PageHeader title={m.page_settings_title()} description={m.page_settings_subtitle()} />
 
-<div class="card bg-base-100 shadow">
-  <div class="card-body">
-    <h2 class="card-title">{m.page_settings_basic()}</h2>
-    <p>{m.page_settings_desc()}</p>
+<Card shadow='sm' class='bg-base-100'>
+  <div class='flex items-center gap-2'>
+    <span class='icon-[tabler--adjustments] size-5 text-primary'></span>
+    <h2 class='text-base font-semibold'>{m.page_settings_basic()}</h2>
   </div>
-</div>
+  <p class='mt-2 text-sm text-base-content/60'>{m.page_settings_desc()}</p>
+</Card>
 {{else}}
-<h1 class="text-2xl font-bold mb-6">系统设置</h1>
+<PageHeader title='系统设置' description='管理系统配置项' />
 
-<div class="card bg-base-100 shadow">
-  <div class="card-body">
-    <h2 class="card-title">基本配置</h2>
-    <p>在此管理系统设置。</p>
+<Card shadow='sm' class='bg-base-100'>
+  <div class='flex items-center gap-2'>
+    <span class='icon-[tabler--adjustments] size-5 text-primary'></span>
+    <h2 class='text-base font-semibold'>基本配置</h2>
   </div>
-</div>
+  <p class='mt-2 text-sm text-base-content/60'>在此管理系统设置。</p>
+</Card>
 {{/if}}

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

@@ -0,0 +1,16 @@
+# {{api.contractPackageName}}
+
+{{projectName}} API service 的共享 contract 包。
+
+## 包含内容
+
+- `app-contract.ts`：应用级路由定义
+- `app-schemas.ts`：输入输出 Zod schema
+- `{{projectName}}-contract.ts`：工程级 contract 聚合入口
+
+## 常用命令
+
+```bash
+pnpm --filter {{api.contractPackageName}} build
+pnpm --filter {{api.contractPackageName}} test
+```

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

@@ -0,0 +1,38 @@
+{
+  "name": "{{api.contractPackageName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist .turbo"
+  },
+  "dependencies": {
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+    "zod": "{{api.packageSpecifiers.zod}}"
+  },
+  "devDependencies": {
+    "@types/node": "{{api.packageSpecifiers.nodeTypes}}",
+    "rimraf": "{{api.packageSpecifiers.rimraf}}",
+    "tsup": "{{api.packageSpecifiers.tsup}}",
+    "typescript": "{{api.packageSpecifiers.typescript}}",
+    "vitest": "{{api.packageSpecifiers.vitest}}"
+  }
+}

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

@@ -0,0 +1,27 @@
+import { apiContract } from '@h-ai/api-contract'
+import { AppEchoInputSchema, AppEchoOutputSchema, AppInfoOutputSchema } from './app-schemas.js'
+
+/** 应用自有 app contract。 */
+export const appContract = {
+  info: apiContract
+    .route({
+      method: 'POST',
+      path: '/app/info',
+      operationId: 'app.info',
+      summary: 'Get service info',
+      tags: ['app'],
+    })
+    .output(AppInfoOutputSchema),
+  echo: apiContract
+    .route({
+      method: 'POST',
+      path: '/app/echo',
+      operationId: 'app.echo',
+      summary: '{{#if features.iam}}Echo a message (auth required){{else}}Echo a message{{/if}}',
+      tags: ['app'],
+    })
+    .input(AppEchoInputSchema)
+    .output(AppEchoOutputSchema),
+}
+
+export type AppContract = typeof appContract

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

@@ -0,0 +1,33 @@
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+/** 服务元信息响应数据。 */
+export const AppInfoOutputDataSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  uptimeMs: z.number().int().nonnegative(),
+  transportEnabled: z.boolean(),
+})
+
+/** app.info 标准 HaiResult 输出。 */
+export const AppInfoOutputSchema = apiContract.haiResultSchema(AppInfoOutputDataSchema)
+
+/** 输入：单条文本消息（演示用，限制最大长度防止误用）。 */
+export const AppEchoInputSchema = z.object({
+  message: z.string().min(1).max(2000),
+})
+
+/** 输出：原样回显 + 调用者快照。 */
+export const AppEchoOutputDataSchema = z.object({
+  message: z.string(),
+  requestId: z.string(),
+  timestamp: z.string(),
+  userId: z.string().optional(),
+})
+
+/** app.echo 标准 HaiResult 输出。 */
+export const AppEchoOutputSchema = apiContract.haiResultSchema(AppEchoOutputDataSchema)
+
+export type AppInfoOutputData = z.infer<typeof AppInfoOutputDataSchema>
+export type AppEchoInput = z.infer<typeof AppEchoInputSchema>
+export type AppEchoOutputData = z.infer<typeof AppEchoOutputDataSchema>

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

@@ -0,0 +1,3 @@
+export * from './app-contract.js'
+export * from './app-schemas.js'
+export * from './{{projectName}}-contract.js'

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

@@ -0,0 +1,12 @@
+import { apiContract } from '@h-ai/api-contract'
+import { appContract } from './app-contract.js'
+
+/** 工程级应用 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,
+})
+
+export type ApiWorkspaceContract = typeof {{api.contractExportName}}

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

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { AppEchoInputSchema, {{api.contractExportName}} } from '../src/index.js'
+
+describe('{{api.contractPackageName}}', () => {
+  it('includes generated contract routes', () => {
+    expect({{api.contractExportName}}.app.info).toBeDefined()
+    expect({{api.contractExportName}}.app.echo).toBeDefined()
+{{#if features.iam}}    expect({{api.contractExportName}}.iam.auth.login).toBeDefined()
+{{/if}}{{#if features.storage}}    expect({{api.contractExportName}}.storage.presignedUrls.createUpload).toBeDefined()
+{{/if}}{{#if features.ai}}    expect({{api.contractExportName}}.ai.chats.createCompletion).toBeDefined()
+{{/if}}  })
+
+  it('validates app.echo input length', () => {
+    expect(AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
+    expect(AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
+    expect(AppEchoInputSchema.safeParse({ message: 'x'.repeat(2001) }).success).toBe(false)
+  })
+})