@h-ai/cli 1.0.0-beta.2 → 1.0.0-beta.21

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.21",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,36 +30,40 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.12.1"
   },
   "dependencies": {
-    "@h-ai/core": "1.0.0-beta.2",
-    "cac": "^7.0.1",
+    "@h-ai/core": "1.0.0-beta.21",
+    "cac": "^7.1.0",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
     "fs-extra": "^11.4.1",
     "handlebars": "^4.7.10",
-    "ora": "^9.4.1",
+    "ora": "^10.0.0",
     "prompts": "^2.4.2",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/api-client": "1.0.0-beta.2",
-    "@h-ai/cache": "1.0.0-beta.2",
-    "@h-ai/crypto": "1.0.0-beta.2",
-    "@h-ai/deploy": "1.0.0-beta.2",
-    "@h-ai/feedback": "1.0.0-beta.2",
-    "@h-ai/iam": "1.0.0-beta.2",
-    "@h-ai/reach": "1.0.0-beta.2",
-    "@h-ai/reldb": "1.0.0-beta.2",
-    "@h-ai/storage": "1.0.0-beta.2",
+    "@h-ai/api-client": "1.0.0-beta.21",
+    "@h-ai/cache": "1.0.0-beta.21",
+    "@h-ai/crypto": "1.0.0-beta.21",
+    "@h-ai/deploy": "1.0.0-beta.21",
+    "@h-ai/feedback": "1.0.0-beta.21",
+    "@h-ai/iam": "1.0.0-beta.21",
+    "@h-ai/kit": "1.0.0-beta.21",
+    "@h-ai/payment": "1.0.0-beta.21",
+    "@h-ai/reach": "1.0.0-beta.21",
+    "@h-ai/reldb": "1.0.0-beta.21",
+    "@h-ai/storage": "1.0.0-beta.21",
+    "@h-ai/vecdb": "1.0.0-beta.21",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "@types/prompts": "^2.4.9",
     "altcha": "^3.5.0",
     "fast-string-width": "^3.0.2",
-    "rimraf": "^6.1.3",
-    "testcontainers": "^12.2.0",
-    "tsup": "^8.5.1",
+    "rimraf": "^6.1.4",
+    "testcontainers": "^12.2.1",
+    "tsup": "^9.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.1.0",
+    "zod": "^4.6.7"
   },
   "scripts": {
     "build": "tsup",

package/templates/README.md

@@ -1,55 +1,70 @@
 # CLI 项目模板
 
-## 简介
+本目录供 `hai create/add/init` 组合应用源码、配置、脚本和AI指引；维护者在这里修改生成源，接入应用使用生成后的工程。模板不承担应用自身的业务授权和数据恢复。
 
-这里保存 `hai create` 生成应用时使用的源码、配置和 AI 指引。维护模板后，需要生成真实项目验证，不能只检查模板文件本身。
+## 快速开始
 
-## 核心功能清单
+在框架根构建CLI，再生成独立工程检查模板效果：
 
-- `admin`、`website`、`h5`：SvelteKit 应用。
-- `api`：共享 contract 与 API service 的 workspace。
-- `mobile-app`：Svelte + Vite + Capacitor 应用。
-- `fullstack`：contract、API、共享界面，以及按需选择的 Web/App/Desktop；miniapp 仅预留说明。
-- 后台工作区随窗口扩展；手机壳支持宽屏，表格在内部滚动，文章与认证表单保留阅读宽度。
-- 默认部署工具、独立镜像 Dockerfile、环境示例和可复制的 AI 技能。
+```sh
+pnpm --filter @h-ai/cli build
+node packages/cli/dist/index.js create ../template-probe --type website --defaults --no-install --no-git
+```
 
-## 使用入门
+输入模板种类与工程名，输出新目录中的源码、README、配置、Dockerfile及适用技能。随后在该工程安装并验证；仅检查 `.hbs` 语法不能证明生成结果能运行。
+
+## 功能
 
 ### 文件如何组合
 
-| 目录           | 用途                                                                |
-| -------------- | ------------------------------------------------------------------- |
-| `base/`        | 普通应用共用的配置、脚本和入口                                      |
-| `apps/<类型>/` | 应用专属页面、workspace、原生壳与配置；API/fullstack 维护自己的骨架 |
-| `features/`    | 按所选模块叠加的路由和页面                                          |
-| `i18n/`        | Paraglide 工程配置                                                  |
-| `skills/`      | 完整的技能目录与各类型 AI 入口                                      |
+| 目录                | 场景、输入与输出                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------- |
+| base/               | 普通应用共享基础；输入渲染上下文，输出配置、脚本和入口                                |
+| apps/               | 按admin/website/h5/api/mobile-app/fullstack选择骨架；API/fullstack有独立workspace结构 |
+| features/           | 叠加实际模块所需路由与页面；不把Serv套成SvelteKit文件路由                             |
+| i18n/               | 生成Paraglide工程与应用消息；默认中英日文                                             |
+| shared/             | 原生显示名、Tauri入口及跨模板文件约定，避免各模板复制不同规则                         |
+| skills/ 与 bridges/ | 输出完整 `.agents/skills/` 及根AGENTS入口，工具配置只桥接共享规则                     |
+
+普通文件复制，`.hbs` 由Handlebars渲染并去后缀。`cli-template-engine.ts` 选择目录/条件，`cli-create.ts` 编排配置、镜像与README生成。例如website输出Core/Kit/UI展示站，fullstack输出contract、Serv、共享UI及所选Web/App/Desktop；miniapp仅为预留说明。
+
+### 生成上下文与配置
+
+上下文含 `projectName/appType/features/hasUi/hasI18n/versions` 和 `api/fullstack` 形状，定义见[CLI类型](../src/cli-types.ts)。模块YAML使用 `moduleConfig` helper，字段和默认值由[配置生成器](../src/commands/cli-config-templates.ts)共同维护。
+
+输入启用模块后，输出对应依赖、有效配置及公共环境默认；未使用模块保留注释示例。新功能仍须接入校验、初始化、关闭和业务路由，不能仅取消YAML注释。`hai add/init` 补缺失项并保留自定义文件。
+
+### 构建、原生名称与部署
+
+部署工具默认是开发依赖，`--no-deploy` 可省略。`hai.json.build.images` 指向images内独立Dockerfile，Web资源在images/web。构建器生成images/dependencies，根gitignore忽略该缓存、运行数据和私有环境。
+
+Dockerfile使用全局HAI_NODE_IMAGE/HAI_NGINX_IMAGE及构建阶段HAI_NPM_REGISTRY接收下载设置，代理只用于构建，不进入运行镜像。pnpm下载采用追加日志，Windows转发保留警告、错误和统一换行。[下载源契约](skills/hai-build/reference.md#下载源与代理)
 
-普通文件直接复制，`.hbs` 经 Handlebars 渲染并去掉后缀。`cli-template-engine.ts` 决定适用目录与条件；`cli-create.ts` 完成配置、镜像定义和根 README 等生成工作。修改前先查实际调用路径，API/fullstack 不套用 SvelteKit 文件路由。
+产物使用工程标识，批次名为 `build-<工程>-<目标>-YYYYMMDD-HHmmss-<随机串>-<版本>`，latest保存相对批次名。输入一个Core展示名后，Capacitor的appName和Tauri产品/主窗口名使用该值；Fullstack读取Serv的Core，独立mobile读取自身Core。只投影名称，不下发完整配置。辅助窗口及后续显式Tauri配置保持自身优先级。[名称与构建](../../../docs/usage/getting-started/build.md#原生应用名称)
 
-### 配置与构建
+### 服务端边界与页面
 
-模板通过 `projectName`、`appType`、`features`、`hasUi`、`hasI18n`、`versions` 以及 `api`/`fullstack` 上下文渲染，完整字段见 [cli-types.ts](../src/cli-types.ts)。模块 YAML 使用 `moduleConfig` helper，与 [配置生成器](../src/commands/cli-config-templates.ts) 共用字段和默认值。
+SvelteKit服务端固定加载Kit配置，根load只投影公开transport。选择crypto后，hooks从私有环境装配密钥环和registry；共享DB用于共享registry，内存仅开发/测试。纯客户端不生成服务端私钥。输入冲突路径策略或缺少required加密依赖时，创建宿主应失败。
 
-部署默认启用，`--no-deploy` 可关闭；SDK 是开发依赖。每个镜像使用 `images/` 中独立 Dockerfile，Web 资源放 `images/web/`。`hai.json` 的 `build.images` 选择文件，`deploy` 保存项目级部署参数；依赖输入由构建器生成到 `images/dependencies/`。所有根 `.gitignore` 均忽略 `**/images/dependencies/`、运行数据和私有环境文件。
+页面文字走应用messages，认证复用AuthPanel及公开IAM配置，表单使用Form/FormLayout/FormField。输入无效表单时保留草稿、显示安全Toast和可访问错误关联；默认角色、流程和限额由业务决定，并在服务端授权。宽屏工作区可扩展，窄屏表格内部滚动，阅读内容保留合适宽度。
 
-Fullstack 服务端保留各模块的配置示例，未使用模块保持注释。安装依赖、校验和初始化、接入业务后才启用对应配置。修改公开 Schema 时同步配置生成器、环境变量说明、调用方与技能。
+### AI指引
 
-SvelteKit 的 `kit-config.ts` 在服务端读取并固定 `_kit.yml`，根 load 只投影公开 transport；选择 crypto 后，hooks 装配环境密钥环和 registry，布局安装浏览器传输。db 提供共享 registry，无 db 仅限开发/测试。路径规则可配置 IP、时段与 required/disabled 加密，规则冲突须在装配时失败。调整时同步三种 SSR 布局、服务端入口、私钥生成边界和实际生成工程的根/子目录门禁；纯客户端工程不生成服务端私钥。
+复制skill完整目录及其相对参考文件，并按应用架构排除不适用能力；引用不得回到框架私有目录。输入website或fullstack两种架构时，输出应各自形成可独立使用的引用闭包。Claude/Copilot/OpenCode仅引用AGENTS和共享规范，不复制长正文。调整公共契约时同步实现、配置、示例、调用方与skills。
 
-### AI 指引
+## 配置
 
-`skills/hai-*` 的完整目录复制到生成应用 `.agents/skills/`，按应用架构排除不适用项。`bridges/<类型>/AGENTS.md` 提供根入口；Claude/Copilot/OpenCode 配置只引用共享规则。新增参考文件必须随 skill 一起复制，不能链接回框架私有路径。
+模板参数在生成阶段消费，生成应用通过自身 `config/`、环境与宿主参数配置运行。环境公共值与私有秘密分开，版本固定到CLI对应框架发布；pnpm补丁注册必须连同实际patch文件复制。[应用配置手册](../../../docs/usage/configuration/README.md)
 
-`hai add` / `hai init` 补齐缺失文件，保留应用已有的自定义内容。框架升级时按目标发布版本比较并合并，不直接覆盖应用规则。
+维护 `shared/.gitattributes`，使Dockerfile、dockerignore和POSIX脚本输出LF。原生工程名、API公开地址、网站basepath与服务器私密配置职责独立，不将完整服务端配置投影到浏览器或原生打包工具。
 
-### 页面与文案
+## 错误处理
 
-用户可见文本加入对应 messages。认证复用 AuthPanel 与服务端公开 IAM 配置；表单复用 Form/FormLayout/FormField。业务规则由应用需求决定，模板默认角色、流程和限额可调整，修改时同步授权、界面、测试和文档。
+模板渲染失败应指出文件/步骤并停止，不以部分产物当成功。生成后的校验或构建失败回到所属模板修复，不能只手工修一份测试工程。私钥、凭据和完整用户数据不进入错误正文。缺失依赖、非法路径、引用不完整和不支持的架构组合要明确拒绝。
 
 ## 开发测试
 
-维护模板时保留 `shared/.gitattributes`，让生成工程的 `.dockerignore`、Dockerfile 和 POSIX 脚本统一使用 LF，保持跨平台输入一致并确保 Linux 脚本可运行。在仓库根执行：
+在仓库根按实际影响选择：
 
 ```sh
 pnpm --filter @h-ai/cli typecheck
@@ -61,7 +76,7 @@ pnpm --filter @h-ai/cli test:scaffold-gates
 pnpm --filter @h-ai/cli test:deploy-gates
 ```
 
-脚手架门禁会生成项目并执行安装、类型检查、lint、构建、测试和浏览器流程。部署门禁另需可用 Podman/Docker，验证镜像构建、隔离服务器上的 SSH/人工部署与部分更新。原生安装包和真实第三方服务需要各自的验收环境。
+脚手架门禁真实安装、类型/lint、构建、测试和浏览器流程；部署门禁需可用Podman/Docker，并验证实际镜像、SSH/手工适用及部分更新。原生设备和第三方线上服务另需对应环境。仅文案改动不代表重跑过所有运行场景。
 
 ## 许可证
 

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

@@ -4,18 +4,15 @@
    * 管理后台根布局
    */
   import type { Snippet } from 'svelte'
-  import { browser } from '$app/environment'
+  import { browser } from '$app/env'
 {{#if features.iam}}
-  import { base } from '$app/paths'
+  import { resolve } from '$app/paths'
 {{else}}
 {{#if features.crypto}}
-  import { base } from '$app/paths'
+  import { resolve } from '$app/paths'
 {{/if}}
 {{/if}}
   import { page } from '$app/state'
-{{#if hasI18n}}
-  import { getLocale, setLocale } from '$lib/paraglide/runtime.js'
-{{/if}}
 {{#if features.crypto}}
   import { crypto } from '@h-ai/crypto'
   import { kit } from '@h-ai/kit'
@@ -31,6 +28,9 @@
 {{/if}}
 {{#if features.crypto}}
   import { untrack } from 'svelte'
+{{/if}}
+{{#if hasI18n}}
+  import { getLocale, setLocale } from '#lib/paraglide/runtime.js'
 {{/if}}
   import '../app.css'
 
@@ -40,10 +40,16 @@
 
   const { children }: Props = $props()
 {{#if features.crypto}}
-  if (browser)
-    kit.client.installBrowserTransport(untrack(() => page.data.kitConfig), { crypto, basePath: base })
+  if (browser) {
+    kit.client.installBrowserTransport(untrack(() => page.data.kitConfig), {
+      crypto,
+      basePath: resolve('/').replace(/\/$/, ''),
+    })
+  }
 {{/if}}
-  const initialTheme = browser ? getSavedTheme() : 'light'
+  const initialTheme = browser
+    ? getSavedTheme()
+    : 'light'
   let currentTheme = $state(initialTheme)
   if (browser)
     applyTheme(initialTheme, false)
@@ -52,7 +58,7 @@
     applyTheme(theme)
   }
 {{#if features.iam}}
-  const authActions = kit.client.createAuthActions({ basePath: `${base}/api/auth` })
+  const authActions = kit.client.createAuthActions({ basePath: `${resolve('/').replace(/\/$/, '')}/api/auth` })
   $effect(() => authActions.bindPageExit({ enabled: page.data.iamPublicConfig?.session.endOnPageHide }))
 {{/if}}
 {{#if hasI18n}}

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

@@ -5,10 +5,10 @@
    */
   import { resolve } from '$app/paths'
   import { page } from '$app/state'
+  import { Badge, Card } from '@h-ai/ui'
 {{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
+  import * as m from '#lib/paraglide/messages.js'
 {{/if}}
-  import { Badge, Card } from '@h-ai/ui'
 </script>
 
 <svelte:head>
@@ -31,7 +31,7 @@
     <h1 class='mt-4 text-4xl font-black tracking-tight'>{page.data.appConfig.name}</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'>
+      <a href={resolve('admin')} class='btn btn-primary'>
         <span class='icon-[tabler--layout-dashboard] size-5'></span>
         {m.nav_admin()}
       </a>
@@ -46,7 +46,7 @@
     <h1 class='mt-4 text-4xl font-black tracking-tight'>{page.data.appConfig.name}</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'>
+      <a href={resolve('admin')} class='btn btn-primary'>
         <span class='icon-[tabler--layout-dashboard] size-5'></span>
         进入后台
       </a>

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

@@ -6,10 +6,10 @@
   import type { Snippet } from 'svelte'
   import { resolve } from '$app/paths'
   import { page } from '$app/state'
+  import { WorkspaceLayout } from '@h-ai/ui'
 {{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
+  import * as m from '#lib/paraglide/messages.js'
 {{/if}}
-  import { WorkspaceLayout } from '@h-ai/ui'
 
   interface Props {
     children: Snippet
@@ -31,11 +31,19 @@
 
   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]' },
+    {
+      path: resolve('admin'),
+      label: m.nav_dashboard(),
+      icon: 'icon-[tabler--layout-dashboard]',
+    },
+    {
+      path: resolve('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]' },
+    { path: resolve('admin'), label: '仪表盘', icon: 'icon-[tabler--layout-dashboard]' },
+    { path: resolve('admin/settings'), label: '设置', icon: 'icon-[tabler--settings]' },
 {{/if}}
   ] as const)
 </script>
@@ -64,10 +72,12 @@
       <ul class='gap-1'>
         {#each navItems as item (item.path)}
           <li>
-            <a href={resolve(item.path, {})} class:menu-active={page.url.pathname === resolve(item.path, {})} onclick={closeDrawer}>
+            <!-- eslint-disable svelte/no-navigation-without-resolve -- 菜单字段已由 resolve 生成完整挂载地址；规则无法追踪派生/筛选后的集合，不能二次添加前缀。 -->
+            <a href={item.path} class:menu-active={page.url.pathname === item.path} onclick={closeDrawer}>
               <span class='{item.icon} size-5'></span>
               {item.label}
             </a>
+            <!-- eslint-enable svelte/no-navigation-without-resolve -->
           </li>
         {/each}
       </ul>

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

@@ -3,17 +3,37 @@
   /**
    * 仪表盘页面
    */
+  import { Card, PageHeader } from '@h-ai/ui'
 {{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
+  import * as m from '#lib/paraglide/messages.js'
 {{/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' },
+    {
+      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 = [

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

@@ -3,10 +3,10 @@
   /**
    * 设置页面
    */
+  import { Card, PageHeader } from '@h-ai/ui'
 {{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
+  import * as m from '#lib/paraglide/messages.js'
 {{/if}}
-  import { Card, PageHeader } from '@h-ai/ui'
 </script>
 
 <svelte:head>

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

@@ -23,3 +23,13 @@ tmp
 # 仅保留公共基础 .env；分环境配置、私有覆盖及已有交付包不进入构建上下文。
 **/.env.*
 **/.hai
+# 部署证书和测试材料不进入镜像构建上下文。
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/tests
+**/e2e
+**/*.test.*
+**/*.spec.*
+docs

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

@@ -14,6 +14,14 @@
 
 ### 包含内容
 
+输入输出约定由Schema共享，客户端先检查 `success` 再取 `data`：
+
+| 功能 | 输入示例 | 成功输出与边界 |
+| --- | --- | --- |
+| app.info | 无业务参数 | name/version/env/defaultLocale/uptimeMs/transportEnabled；只返回公开元信息 |
+| app.echo | `{ message: 'hello' }`，1–2000字符 | 同一message及requestId/timestamp，可含userId；演示回显，不写业务数据 |
+| 工程contract | 聚合应用与已启用模块契约 | Serv与typed client使用同一输入/输出类型；声明不替代服务端授权 |
+
 - `app-contract.ts`：应用级接口定义，业务 path 与一次性输出 Schema 就近内联
 - `app-schemas.ts`：跨接口、跨层复用的输入/数据 Zod Schema
 - `{{projectName}}-contract.ts`：工程级 contract 聚合入口

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

@@ -4,7 +4,12 @@ import { z } from 'zod'
 export const AppInfoOutputDataSchema = z.object({
   name: z.string(),
   version: z.string(),
-  env: z.enum(['development', 'production', 'test', 'staging']),
+  env: z.enum([
+    'development',
+    'production',
+    'test',
+    'staging',
+  ]),
   defaultLocale: z.string(),
   uptimeMs: z.number().int().nonnegative(),
   transportEnabled: z.boolean(),

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

@@ -5,11 +5,19 @@ 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}}{{#if features.feedback}}  feedback: apiContract.feedback,
-{{/if}}  // @hai-generator:contracts:entries
+{{#if features.iam}}
+  iam: apiContract.iam,
+{{/if}}
+{{#if features.storage}}
+  storage: apiContract.storage,
+{{/if}}
+{{#if features.ai}}
+  ai: apiContract.ai,
+{{/if}}
+{{#if features.feedback}}
+  feedback: apiContract.feedback,
+{{/if}}
+  // @hai-generator:contracts:entries
   app: appContract,
 })
 

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

@@ -5,14 +5,22 @@ 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}}  })
+{{#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)
+    expect(AppEchoInputSchema.safeParse({
+      message: 'x'.repeat(2001),
+    }).success).toBe(false)
   })
 })

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

@@ -6,6 +6,8 @@ export default defineConfig({
   target: 'node22',
   sourcemap: true,
   clean: true,
-  dts: { compilerOptions: { ignoreDeprecations: '6.0' } },
+  dts: {
+    compilerOptions: { ignoreDeprecations: '6.0' },
+  },
   external: ['@h-ai/api-contract', 'zod'],
 })

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

@@ -19,15 +19,19 @@ pnpm --filter {{api.servPackageName}} dev
 pnpm --filter {{api.servPackageName}} test
 ```
 
+启动读取本服务配置并校验依赖。默认健康入口 `GET /health` 返回可达状态，`POST /api/v1/app/info` 返回公开服务信息；路径按 `_serv.yml` 调整。`app.echo` 输入 `{ message: 'hello' }`，成功输出相同message、请求编号和时间；按已装配客户端/传输协议调用，不把curl明文当启用加密后的通用调用方式。启用的认证/反馈/存储等模块按根目录及对应skill接入。
+
 ### 容器运行
 
 
-- 配置默认打包自本目录 `config/`，可在运行时只读挂载到 `/app/config`，敏感值通过环境变量注入。
+- YAML配置默认打包自本目录 `config/`，镜像内位于 `/app/config`；SDK部署的私有 `.env.runtime` 另通过 `/run/hai/config` 只读挂载并在启动时读取。修改普通运行配置后重启，端口/网关/挂载变化需重新部署。
+{{#if features.iam}}- 受控内网或 VPN 的生产 HTTP 入口可设置 `HAI_SERV_REFRESH_COOKIE_SECURE=false` 和实际 `HAI_SERV_CORS_ORIGIN`，重新部署后端后重新登录。刷新凭据会经 HTTP 明文传输。
+{{/if}}
 
 
 ### 关键目录
 
-{{#if features.crypto}}启用 transport 时，`serverKeyRing` 与客户端 `keyStore` 都必须显式提供。CLI 在本服务 `.env.dev/.env.test/.env.prod` 中分别生成独立 ring，提交环境文件后克隆用户可共享，变量为 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`；运行时不生成密钥。部署直接复用所选环境文件的 ring，或由 Secret Manager 向所有节点分发相同受管 ring，配合共享数据库 registry。公钥/版本参与协商，私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发新旧版本再切 activeKeyId，过渡期后撤销旧 ID；无需会话粘性。
+{{#if features.crypto}}启用 transport 时，`serverKeyRing` 与客户端 `keyStore` 都必须显式提供。CLI 在本服务 `.env.dev.local/.env.test.local/.env.prod.local` 中分别生成独立 ring，私有文件不提交 Git，克隆后通过受保护配置或 Secret Manager 分发，变量为 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`；运行时不生成密钥。部署直接复用所选环境文件的 ring，或由 Secret Manager 向所有节点分发相同受管 ring，配合共享数据库 registry。公钥/版本参与协商，私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发新旧版本再切 activeKeyId，过渡期后撤销旧 ID；无需会话粘性。
 {{#unless features.db}}本模板未选择 db，registry 仅在 development/test 显式使用内存；production/staging 会拒绝启动 transport。选择 db 并配置共享数据库后再部署，或显式关闭 transport。
 {{/unless}}{{/if}}
 

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

@@ -7,19 +7,33 @@ server:
   port: 3000
 
 http:
+  # auto 仅在受管私有 Compose 代理中采用容器网段；普通宿主忽略转发头。
+  trustedProxies: auto
+  access: false
+  # 独立文件与下方内联规则二选一，用所选配置块替换 access: false。
+  # access:
+  #   file: ./config/security/request-access.yml
+  # access:
+  #   global:
+  #     timezone: UTC # 可用 HAI_SERV_HTTP_ACCESS_GLOBAL_TIMEZONE=Asia/Shanghai
+  #     allowIps: []
+  #     denyIps: []
+  #     windows: []
+  #   rules: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json
+  # HAI_SERV_HTTP_DOCS=false 关闭文档；开启时再配置 path/requireAuth。
   docs:
     path: /docs
+    # requireAuth: true
   health:
     path: /health
     readyPath: /ready
-  rpc: false
 
 cors:
   origin: ${HAI_SERV_CORS_ORIGIN:*}
-  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://localhost,http://tauri.localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
 {{#if features.iam}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:true}
 {{else}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:false}
 {{/if}}  allowedHeaders:
@@ -43,6 +57,14 @@ cors:
 {{else}}
   maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:1048576}
 {{/if}}
+  # 传输时钟窗口，单位秒；允许领先 0～300 秒，请求有效期 1～600 秒。
+  maxFutureSkewSeconds: ${HAI_SERV_TRANSPORT_MAXFUTURESKEWSECONDS:30}
+  maxRequestAgeSeconds: ${HAI_SERV_TRANSPORT_MAXREQUESTAGESECONDS:300}
+  # HAI_SERV_TRANSPORT_ROUTEPLAINTEXTBYTES 可填 JSON 路径映射。
+  routePlaintextBytes: {}
+  # 单条路径需要更大请求体时填写字节数，* 只匹配一段路径。
+  # routePlaintextBytes:
+  #   /api/v1/uploads/*: 8388608
   keyExchangePath: /_hai/key-exchange
   excludePaths:
     - /health

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

@@ -28,11 +28,11 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo",
-    "dev": "pnpm build && node --env-file=.env --env-file=.env.dev --env-file-if-exists=.env.local dist/index.js",
-    "start": "node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local dist/index.js",
-    "dev:test": "pnpm build && node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local dist/index.js",
+    "dev": "pnpm build && node ../../scripts/run-node.mjs dev . dist/index.js",
+    "start": "node ../../scripts/run-node.mjs prod . dist/index.js",
+    "dev:test": "pnpm build && node ../../scripts/run-node.mjs test . dist/index.js",
     "dev:prod": "pnpm build && pnpm start",
-    "start:test": "node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local dist/index.js",
+    "start:test": "node ../../scripts/run-node.mjs test . dist/index.js",
     "start:prod": "pnpm start"
   },
   "dependencies": {