@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

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

@@ -0,0 +1,20 @@
+import { apiContract } from '@h-ai/api-contract'
+import { AppEchoInputSchema, AppEchoOutputDataSchema, AppInfoOutputDataSchema } from './app-schemas.js'
+
+/** app 领域 API contract：路径、方法、输入输出 Schema 的单一来源。 */
+export const appContract = {
+  info: apiContract.route({
+    method: 'POST',
+    path: '/app/info',
+    operationId: 'app.info',
+    tags: ['app'],
+    summary: 'Get application runtime information',
+  }).output(apiContract.haiResultSchema(AppInfoOutputDataSchema)),
+  echo: apiContract.route({
+    method: 'POST',
+    path: '/app/echo',
+    operationId: 'app.echo',
+    tags: ['app'],
+    summary: 'Echo a message through the generated service route',
+  }).input(AppEchoInputSchema).output(apiContract.haiResultSchema(AppEchoOutputDataSchema)),
+}

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

@@ -0,0 +1,35 @@
+import type { HaiResult } from '@h-ai/core'
+import { z } from 'zod'
+
+export const AppFrontendTargetSchema = z.enum(['web', 'app', 'miniapp', 'desktop'])
+
+/** 服务信息响应数据。 */
+export const AppInfoOutputDataSchema = z.object({
+  notice: z.string().max(200),
+  name: z.string(),
+  version: z.string(),
+  env: z.string(),
+  defaultLocale: z.string(),
+  supportedLocales: z.array(z.string()),
+  startedAt: z.string().datetime(),
+  frontends: z.array(AppFrontendTargetSchema),
+})
+
+/** Echo 请求体。 */
+export const AppEchoInputSchema = z.object({
+  message: z.string().min(1).max(200),
+})
+
+/** Echo 响应数据。 */
+export const AppEchoOutputDataSchema = z.object({
+  message: z.string(),
+  echoedAt: z.string().datetime(),
+  requestId: z.string(),
+})
+
+export type AppFrontendTarget = z.infer<typeof AppFrontendTargetSchema>
+export type AppInfoOutputData = z.infer<typeof AppInfoOutputDataSchema>
+export type AppInfoOutput = HaiResult<AppInfoOutputData>
+export type AppEchoInput = z.infer<typeof AppEchoInputSchema>
+export type AppEchoOutputData = z.infer<typeof AppEchoOutputDataSchema>
+export type AppEchoOutput = HaiResult<AppEchoOutputData>

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

@@ -0,0 +1,7 @@
+export * from './app-contract.js'
+export * from './app-schemas.js'
+export * from './admin-contract.js'
+export * from './admin-schemas.js'
+export * from './{{fullstack.contractPackageName}}.js'
+
+// @hai-generator:contracts:exports

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

@@ -0,0 +1,23 @@
+import { apiContract } from '@h-ai/api-contract'
+import { adminContract, authContract, profileContract } from './admin-contract.js'
+import { appContract } from './app-contract.js'
+
+// @hai-generator:contracts:imports
+
+/** 当前工程启用的前端目标。 */
+export const ENABLED_FRONTENDS = {{{fullstack.selectedFrontendsJson}}} as const
+export const SUPPORTED_LOCALES = [{{#each fullstack.i18n.locales}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}] as const
+
+/** 工程级 API contract，前端 typed client 与后端 service 共用。 */
+export const {{fullstack.contractExportName}} = apiContract.create({
+  // @hai-generator:contracts:entries
+  app: appContract,
+  iam: { auth: authContract },
+  admin: adminContract,
+  profile: profileContract,
+{{#if features.feedback}}
+  feedback: apiContract.feedback,
+{{/if}}
+})
+
+export type FullstackContract = typeof {{fullstack.contractExportName}}

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

@@ -0,0 +1,31 @@
+import { apiContract } from '@h-ai/api-contract'
+import { describe, expect, it } from 'vitest'
+import * as contracts from '../src/index.js'
+
+describe('{{fullstack.contractPackageName}}', () => {
+  it('defines app contract routes', () => {
+    expect(contracts.{{fullstack.contractExportName}}.app).toBeDefined()
+    expect(contracts.appContract.info).toBeDefined()
+    expect(apiContract.pathOf(contracts.appContract.info)).toBe('/app/info')
+  })
+
+  it('validates app info payload', () => {
+    const result = contracts.AppInfoOutputDataSchema.safeParse({
+      name: '{{fullstack.servPackageName}}',
+      version: '0.1.0',
+      env: 'test',
+      defaultLocale: 'zh-CN',
+      supportedLocales: ['zh-CN', 'en-US'],
+      startedAt: '2026-01-01T00:00:00.000Z',
+      frontends: [...contracts.ENABLED_FRONTENDS],
+      notice: '',
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('validates echo input boundaries', () => {
+    expect(contracts.AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
+    expect(contracts.AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
+  })
+})

package/templates/apps/fullstack/packages/{{projectName}}-contract/tsconfig.json.hbs

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: { compilerOptions: { ignoreDeprecations: '6.0' } },
+  sourcemap: true,
+  clean: true,
+})

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

@@ -0,0 +1,84 @@
+# {{fullstack.servPackageName}}
+
+## 简介
+
+后端 API Service，基于 `@h-ai/serv` 将共享 contract 装配为最小 HTTP App 抽象，不在应用代码中直接暴露 Hono。
+
+## 核心功能清单
+
+- HTTP 服务、健康检查和共享 contract 的 procedure 实现。
+- 用户、角色、审计与个人设置的示例业务。
+- 模块配置、加密传输与服务端权限校验。
+
+## 使用入门
+
+### 默认功能与配置
+
+以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
+
+- `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
+- `config/_serv.yml`：服务端运行时设置（CORS 来源等）。
+- `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml` / `_reach.yml`：管理及开发通知配置，初始化前使用模块公开 Schema 验证。Reach 默认控制台 Provider，生产按注释替换为 SMTP/短信/API。
+- `config/_ai.yml` / `_vecdb.yml` / `_payment.yml` / `_scheduler.yml`：保留未启用模块的完整注释示例；配置文件存在不代表模块已接入。先在本 workspace 安装对应依赖，再在 `src/server/runtime.ts` 按公开 Schema 校验、初始化并反序关闭，接入实际业务后按需取消注释。整份注释先去掉一层外层注释，可选字段继续按需开启。
+- `src/index.ts`：进程入口，先 `core.init({ configDir: './config' })`，再初始化 reldb → cache → crypto → storage → reach（有配置时）→ audit → iam → scheduler（有任务时）；启动失败及退出反序释放。
+- 选择 AI 时自动安装 reldb/vecdb/AI，并在 reldb/cache 之后初始化 vecdb、在其余依赖之后初始化 AI；关闭时先释放 AI，最后释放 vecdb/关系库，关闭失败会返回错误并保留重试义务。生产环境必须使用共享后端，根 `.env.prod` 默认连接 Compose `db/cache/storage/vecdb`，凭据和真实 Reach Provider JSON 私有注入。
+- `src/app-server.ts`：服务装配入口，挂载健康检查、OpenAPI、docs 与 procedures；应用名称 / 版本与 CORS 来源均取自上述配置。
+- `src/server/procedures/app-procedures.ts`：app 领域 procedures，对应 contract 中的 `app.info` / `app.echo` 路由。
+- `src/server/procedures/admin-procedures.ts`：认证、管理员用户/角色/审计管理和个人设置，使用 `.auth()` / `.permission(...)` 守卫。每个请求读取用户最新启用状态、角色和权限。
+- 标准认证 procedures 复用 `@h-ai/serv/features/iam`，注册、登录方式、重置与协议由 `_iam.yml` 控制；登录、退出、修改密码追加业务审计。HTTP App 类型复用公开 `ServHttpApp`。
+- `src/server/admin-service.ts`：角色分配、头像上传和审计编排，全部底层操作复用 hai 模块。初始使用 admin、audit_admin、config_admin、business_operator 和 user 五种角色，四类职责及基础成员权限由 security-roles.ts 配置；锁内重新鉴权，默认禁止管理员自删、自禁用、自降级，并补偿用户更新失败后的角色变更。业务规则可按需求替换，保留的不变量需验证并发与失败路径。
+- `tests/app-server.test.ts`：真实加密 HTTP 测试，覆盖 Cookie/受信原生刷新、RBAC、旧会话权限、并发管理操作、补偿、头像安全、偏好、审计及会话失效。
+
+CLI 已在根目录 `.env.dev/.env.test/.env.prod` 为每个环境的 admin、audit_admin、config_admin、business_operator 分别生成独立随机强密码，对应 `HAI_ADMIN_DEFAULT_PASSWORD`、`HAI_AUDIT_ADMIN_PASSWORD`、`HAI_CONFIG_ADMIN_PASSWORD`、`HAI_BUSINESS_OPERATOR_PASSWORD`。已有账号不改密或重新分配职责；未配置密码的独立职责账号不创建；`dev`/`start` 自动读取，首次登录使用用户名 `admin` 和该密码。仅在没有用户时创建管理员，不重设已有用户密码。密码不符合 `_iam.yml` 策略时，启动日志显示具体原因及错误码。环境文件随项目提交供克隆后共享；私有文件或进程变量可覆盖，`.env.example` 不含真实密码。所有业务 JSON 请求和响应强制加密；健康检查和随机路径的只读头像图片可直接访问。头像支持 PNG/JPEG/WebP，最大 512 KiB，校验内容特征和大小后由服务端生成 key，不能指定任意文件路径。
+
+默认 SQLite + 本地 storage + memory cache 仅适合本地开发与显式测试，管理写入仅支持单写实例：进程内保护无过期时间，共享 cache 锁定期续租，丢失锁或释放失败会记录错误。多实例读取可使用共享数据库、Redis cache 和 S3 storage，但管理写请求必须统一路由到同一写实例；仅更换 Redis 不提供任意多写副本的最后管理员原子保证。传输在所有节点共享受管版本化密钥环与 registry，不依赖会话粘性；重启加载原 ring，轮换先分发新旧版本再切 activeKeyId。Web 使用 HttpOnly refresh Cookie + 内存 access token；仅同时满足客户端标识、body 通道头与受信原生 Origin 的 App/Desktop 请求返回 refresh token body。
+
+业务公告配置与审计在同一事务提交，失败回滚。其他已经提交的管理修改，其补充审计记录采用最大努力策略：写入失败输出包含操作及资源的结构化错误日志，业务仍返回原操作结果，避免将已经完成的变更误报为失败；应用启动时 audit 初始化失败则停止启动。
+
+### 开发
+
+所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，初始管理员密码和传输密钥环按环境生成到 `.env.dev/.env.test/.env.prod`；其他私有值或覆盖值保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
+
+CLI 同时在根 `.env.dev/.env.test/.env.prod` 分别生成独立的 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`，结构为 `{activeKeyId,keys:{id:{publicKey,privateKey}}}`，运行时不隐式生成。同一环境所有节点从环境文件加载相同 ring，也可由 Secret Manager 统一覆盖，客户端 registry 复用共享 reldb。私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发含新旧版本的 ring，再切 activeKeyId 并滚动重建；过渡期后删除旧 ID，旧客户端 destroy 后重协商。没有 sticky session 依赖。
+
+自动生成的 `.env` 包含已启用模块的环境参数；YAML 显式引用相同变量并保留本地回退。使用 `start:test` / `start:prod` 加载对应环境覆盖。
+
+- `pnpm --filter {{fullstack.servPackageName}} dev`
+- `pnpm --filter {{fullstack.servPackageName}} test`
+
+### 容器运行
+
+从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
+
+- 服务镜像直接由 `@h-ai/serv` 对外监听，配置挂载点为 `/app/config`，数据目录为 `/app/data`，不包含额外转发进程。
+- Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
+- YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
+
+### IAM 认证配置
+
+服务端 `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；回调第三参数 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，由安全渲染器在弹窗显示。
+
+增强安全按 _iam.yml/_audit.yml 启用，包含账号生命周期、密码期限/复杂度、ALTCHA、失败窗口锁定、一次性邀请、首次改密、用途绑定再认证、时段/IP、闲置/绝对期限和并发会话策略。页面离开撤销默认关闭且只最佳努力。审计查询支持分类、结果、等级、排序及最近7天统计；私有备份返回 key/数量/SHA-256 回执，失败复用编号，不通过头像资源路由公开。自动备份与轻量告警复用 Scheduler/Reach；归档不是数据库原子快照，恢复在独立环境进行。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 反馈现场与交付检查
+
+feedback.init(config, { collectEvidence }) 支持等待业务 text/data 与文本/ZIP/GZIP 附件；_feedback.yml 提供业务采集超时和 Webhook URL/签名密钥/请求超时。密钥仅放服务端私有环境。Webhook 持久重试，详情展示状态并允许管理员重试。
+
+反馈的 console/disabled/reach 独立选择；SDK getView/ratio/saveDraft 与 createFeedbackReview 统一预览、标注、保存及轮询。退出身份清理草稿和观察器。宿主生命周期由 core.module.createRuntime 处理，框架表升级前备份停旧写入并运行各模块 dryRun 预检。
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.servPackageName}} typecheck
+pnpm --filter {{fullstack.servPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_ai.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'ai' features.ai}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_audit.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'audit' true}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_cache.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'cache' true}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_core.yml.hbs

@@ -0,0 +1,22 @@
+# =============================================================================
+# {{fullstack.servPackageName}} - 应用配置
+# =============================================================================
+#
+# 后端服务的应用级配置，由 core.config 在启动时加载。
+# 每个叶子项都可由约定式 HAI 环境变量覆盖，敏感值不要写入文件。
+# =============================================================================
+
+{{yaml 'name' fullstack.appName}}
+version: 0.1.0
+env: development
+
+defaultLocale: {{fullstack.i18n.baseLocale}}
+logging:
+  level: info
+  format: pretty
+  # context:
+  #   service: api
+  redact:
+    - password
+    - token
+    - secret

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_db.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'db' true}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_feedback.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'feedback' features.feedback}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_iam.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'iam' true}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_payment.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'payment' features.payment}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_reach.yml.hbs

@@ -0,0 +1,60 @@
+# 开发触达示例；生产环境改为 SMTP、短信或 API Provider。
+providers:
+  - name: email
+    type: console
+  - name: sms
+    type: console
+  # SMTP 替换 email 控制台 Provider；同名 Provider 只保留一个。
+  # - name: email
+  #   type: smtp
+  #   host: ${HAI_REACH_PROVIDERS_0_HOST:smtp.example.com}
+  #   port: ${HAI_REACH_PROVIDERS_0_PORT:465}
+  #   secure: true
+  #   user: ${HAI_REACH_PROVIDERS_0_USER:}
+  #   pass: ${HAI_REACH_PROVIDERS_0_PASS:}
+  #   from: ${HAI_REACH_PROVIDERS_0_FROM:noreply@example.com}
+  # 阿里云短信替换 sms 控制台 Provider。
+  # - name: sms
+  #   type: aliyun-sms
+  #   accessKeyId: ${HAI_REACH_PROVIDERS_0_ACCESSKEYID}
+  #   accessKeySecret: ${HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET}
+  #   signName: MyApp
+  #   endpoint: dysmsapi.aliyuncs.com
+  # 自有发送服务：按需将 template.provider 改为 custom。
+  # - name: custom
+  #   type: api
+  #   url: https://notify.example.com/send
+  #   method: POST # POST | PUT
+  #   headers:
+  #     Authorization: '${HAI_REACH_PROVIDERS_0_HEADERS_AUTHORIZATION}'
+  #   timeout: 10000
+  #   idempotent: ${HAI_REACH_PROVIDERS_0_IDEMPOTENT:false} # 仅接收端具备原子持久去重时启用；默认在途不明结果转 unknown
+templates:
+  - name: otp_email
+    provider: email
+    subject: Verification code
+    body: 'Your verification code is {code}.'
+  - name: otp_sms
+    provider: sms
+    body: 'Your verification code is {code}.'
+  - name: password_reset
+    provider: email
+    subject: Password reset
+    body: 'Reset your password: {resetUrl}. Expires at {expiresAt}.'
+  - name: password_reset_sms
+    provider: sms
+    body: 'Reset your password: {resetUrl}. Expires at {expiresAt}.'
+
+# 免打扰可选；验证码应避免 delay，以免延迟到失效后投递。
+# dnd:
+#   enabled: false
+#   strategy: discard # discard | delay
+#   start: '22:00'
+#   end: '08:00'
+
+# 延迟队列策略随每条消息保存；最多领取 5 次，指数退避 1 分钟至 1 小时。
+# 超限 dead 只经可信服务端人工恢复；unknown 不允许自动重发。
+queue:
+  maxAttempts: ${HAI_REACH_QUEUE_MAXATTEMPTS:5}
+  retryDelayMs: ${HAI_REACH_QUEUE_RETRYDELAYMS:60000}
+  maxRetryDelayMs: ${HAI_REACH_QUEUE_MAXRETRYDELAYMS:3600000}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_scheduler.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'scheduler' features.scheduler}}}

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

@@ -0,0 +1,64 @@
+# =============================================================================
+# {{fullstack.servPackageName}} - Serv / HTTP 入口配置
+# =============================================================================
+#
+# 业务接口路径直接写在对应 *-contract.ts；公共 HTTP 传输配置以本文件为准。
+# =============================================================================
+
+server:
+  host: 127.0.0.1
+  port: 3000
+
+http:
+  # auto 仅在受管私有 Compose 代理中采用容器网段；普通宿主忽略转发头。
+  # 自建代理填写明确 IP/CIDR；[] 显式忽略转发头。
+  trustedProxies: auto
+  access: false
+  # access:
+  #   file: ./config/security/request-access.yml
+  apiPrefix: /api/v1
+  openapi:
+    path: /openapi.json
+  docs:
+    path: /docs
+    # requireAuth: true
+  health:
+    path: /health
+    readyPath: /ready
+  rpc: false
+  # 内部 RPC 可选；启用时用对象替换 false，gateway-only 必须配置网关密钥。
+  # rpc:
+  #   prefix: /api/rpc
+  #   access: gateway-only # loopback | private-network | gateway-only
+  #   gatewayHeader: X-Gateway-Key
+  #   gatewaySecret: ${HAI_SERV_HTTP_RPC_GATEWAYSECRET}
+
+cors:
+  origin: ${HAI_SERV_CORS_ORIGIN:*}
+  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://localhost,http://tauri.localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+  credentials: ${HAI_SERV_CORS_CREDENTIALS:true}
+  allowedHeaders:
+    - Authorization
+    - Content-Type
+    - X-Request-Id
+    - X-Requested-With
+    - X-Request-Client
+    - X-Hai-Terminal
+    - X-HAI-Token-Transport
+    - X-Client-Id
+    - X-Encrypted
+    - X-Hai-Transport
+  exposedHeaders:
+    - X-Request-Id
+    - X-Encrypted
+    - X-Hai-Transport
+
+transport:
+  # 双向业务明文 UTF-8 字节；默认 {{#if features.feedback}}auto（按反馈预算推导）{{else}}1 MiB{{/if}}，范围 1 KiB～64 MiB，密文容量自动推导。
+{{#if features.feedback}}
+  maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:auto}
+{{else}}
+  maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:1048576}
+{{/if}}
+  keyExchangePath: /_hai/key-exchange
+  # excludePaths: [/health, /ready]

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_storage.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'storage' true}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_vecdb.yml.hbs

@@ -0,0 +1 @@
+{{{moduleConfig 'vecdb' features.vecdb}}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/data/.gitkeep.hbs

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,62 @@
+{
+  "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
+  "name": "{{fullstack.servPackageName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "config",
+    "data",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "check": "pnpm typecheck",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "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: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:prod": "pnpm start"
+  },
+  "dependencies": {
+    "pino-pretty": "{{fullstack.packageSpecifiers.pinoPretty}}",
+{{#if features.ai}}
+    "@h-ai/ai": "{{haiPackageSpecifier}}",
+{{/if}}
+    "@h-ai/audit": "{{haiPackageSpecifier}}",
+    "@h-ai/cache": "{{haiPackageSpecifier}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+    "@h-ai/crypto": "{{haiPackageSpecifier}}",
+{{#if features.feedback}}
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+    "@h-ai/feedback": "{{haiPackageSpecifier}}",
+{{/if}}
+    "@h-ai/iam": "{{haiPackageSpecifier}}",
+    "@h-ai/reach": "{{haiPackageSpecifier}}",
+    "@h-ai/reldb": "{{haiPackageSpecifier}}",
+    "@h-ai/scheduler": "{{haiPackageSpecifier}}",
+    "@h-ai/serv": "{{haiPackageSpecifier}}",
+    "@h-ai/storage": "{{haiPackageSpecifier}}",
+{{#if features.vecdb}}
+    "@h-ai/vecdb": "{{haiPackageSpecifier}}",
+{{/if}}
+    "zod": "{{fullstack.packageSpecifiers.zod}}",
+    "{{fullstack.contractPackageName}}": "workspace:*"
+  }
+}

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/app-server.ts.hbs

@@ -0,0 +1,115 @@
+import type { CoreConfig } from '@h-ai/core'
+import type { {{#if features.feedback}}CreateServContext, {{/if}}ServHttpApp } from '@h-ai/serv'
+import process from 'node:process'
+{{#if features.feedback}}import { resolveFeedbackBudget } from '@h-ai/api-contract/feedback'
+{{/if}}import { core } from '@h-ai/core'
+import { createReldbTransportKeyStore, crypto, parseTransportServerKeyRing } from '@h-ai/crypto'
+{{#if features.feedback}}
+import { FeedbackConfigSchema } from '@h-ai/feedback'
+{{/if}}
+import { iam } from '@h-ai/iam'
+import { reldb } from '@h-ai/reldb'
+import { serv, ServConfigSchema } from '@h-ai/serv'
+import { storage } from '@h-ai/storage'
+import * as contracts from '{{fullstack.contractPackageName}}'
+import { createServerProcedures } from './server/procedures/index.js'
+
+const STARTED_AT = new Date().toISOString()
+
+/** 创建后端 HTTP App；与 @h-ai/serv 的 createApp 返回语义保持一致。 */
+export function createServerApp(): ServHttpApp {
+  const coreConfig = core.config.getOrThrow<CoreConfig>('core')
+  const servConfig = ServConfigSchema.parse(core.config.getOrThrow('serv'))
+  if (servConfig.transport === false)
+    throw new Error('Fullstack management requires transport encryption; configure scoped access.rules[].encryption: disabled for plaintext external endpoints')
+  const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+  if (!ring.success)
+    throw new Error(`HAI_CRYPTO_TRANSPORT_SERVERKEYRING: ${ring.error.message} (${ring.error.code})`)
+{{#if features.feedback}}  // 可选反馈故障重试期间仍使用配置预算，避免缓存默认容量。
+  const feedbackSettings = FeedbackConfigSchema.safeParse(core.config.get('feedback'))
+  const feedbackBudget = resolveFeedbackBudget(feedbackSettings.success ? feedbackSettings.data : {})
+{{/if}}  const security = serv.createRuntimeSecurityPolicy({
+    environment: coreConfig.env,
+    corsOrigin: servConfig.cors.origin,
+    nativeOrigins: servConfig.cors.nativeOrigins,
+  })
+  const publicPaths = [
+    `${servConfig.http.apiPrefix}/assets`,
+    ...(servConfig.http.health ? [servConfig.http.health.path, servConfig.http.health.readyPath].filter((path): path is `/${string}` => Boolean(path)) : []),
+    ...(servConfig.http.openapi && security.exposeApiDocs ? [servConfig.http.openapi.path] : []),
+    ...(servConfig.http.docs && security.exposeApiDocs ? [servConfig.http.docs.path] : []),
+  ]
+{{#if features.feedback}}
+  // 普通业务日志与反馈使用同一可信应用范围；身份仍由 IAM 验证。
+  const authenticatedContext = serv.buildAuthContextFactory(token => iam.auth.verifyToken(token))
+  const createContext: CreateServContext = async input => ({
+    ...await authenticatedContext(input),
+    scopeId: '{{projectName}}',
+  })
+{{/if}}
+
+  return serv.createApp({
+    contract: contracts.{{fullstack.contractExportName}},
+    procedures: createServerProcedures({
+      app: {
+        name: coreConfig.name,
+        version: coreConfig.version,
+        env: coreConfig.env,
+        defaultLocale: coreConfig.defaultLocale,
+        supportedLocales: contracts.SUPPORTED_LOCALES,
+        startedAt: STARTED_AT,
+        frontends: [...contracts.ENABLED_FRONTENDS],
+      },
+    }),
+    iam,
+{{#if features.feedback}}
+    createContext,
+{{/if}}
+    refreshCookie: {
+      secure: security.secureRefreshCookie,
+      nativeTokenTransport: { isRequest: request => request.headers.get('x-hai-token-transport') === 'body'
+        && ['{{projectName}}-app', '{{projectName}}-desktop'].includes(request.headers.get('x-request-client') ?? '')
+        && security.isNativeOrigin(request.headers.get('origin') ?? '') },
+    },
+    // 管理业务默认强制双向加密；各节点复用受管服务端密钥环与共享 reldb 客户端 registry。
+    transport: {
+      ...servConfig.transport,
+{{#if features.feedback}}
+      routePlaintextBytes: {
+        [`${servConfig.http.apiPrefix}/feedback/reports`]: feedbackBudget.maxTransportBytes,
+        [`${servConfig.http.apiPrefix}/feedback/reports/*/evidence`]: feedbackBudget.maxTransportBytes,
+        [`${servConfig.http.apiPrefix}/feedback/reports/*/attachments/*`]: feedbackBudget.maxTransportBytes,
+        [`${servConfig.http.apiPrefix}/feedback/reports/*/exports/*`]: feedbackBudget.maxTransportBytes,
+        ...servConfig.transport.routePlaintextBytes,
+      },
+{{/if}}
+      excludePaths: [...new Set([...publicPaths, ...servConfig.transport.excludePaths])],
+      crypto,
+      serverKeyRing: ring.data,
+      keyStore: createReldbTransportKeyStore({ reldb, ttlSeconds: 3600 }),
+    },
+    http: {
+      ...servConfig.http,
+      openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
+      docs: security.exposeApiDocs ? servConfig.http.docs : false,
+    },
+    middlewares: [{
+      middleware: serv.cors({
+        origin: security.allowOrigin,
+        credentials: servConfig.cors.credentials,
+        allowedHeaders: [...new Set([...servConfig.cors.allowedHeaders, 'X-Client-Id', 'X-Encrypted', 'X-Hai-Transport', 'X-Request-Client', 'X-HAI-Token-Transport', 'X-Hai-Reauthentication', 'X-Hai-Terminal'])],
+        exposedHeaders: [...new Set([...servConfig.cors.exposedHeaders, 'X-Encrypted', 'X-Hai-Transport'])],
+      }),
+    }, {
+      path: `${servConfig.http.apiPrefix}/assets/*`,
+      middleware: serv.storageAssets({
+        storage,
+        pathPrefix: `${servConfig.http.apiPrefix}/assets/`,
+        keyPattern: /^avatars\/[\w-]+\/[\w-]+\.(png|jpg|webp)$/,
+        allowedContentTypes: ['image/png', 'image/jpeg', 'image/webp'],
+        cacheControl: 'public, max-age=31536000, immutable',
+        crossOriginResourcePolicy: 'cross-origin',
+      }),
+    }],
+  })
+}

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/build-metadata.ts.hbs

@@ -0,0 +1,7 @@
+{{! @skipIfEmpty }}
+{{#if features.feedback}}
+/** 当前应用编译时烘焙的产物身份；运行时配置不能覆盖。 */
+declare const __HAI_BUILD_METADATA__: { appVersion: string, buildId: string, commit: string }
+
+export const buildMetadata = __HAI_BUILD_METADATA__
+{{/if}}

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/index.ts.hbs

@@ -0,0 +1,40 @@
+import type { CoreConfig } from '@h-ai/core'
+import type { ServConfigInput } from '@h-ai/serv'
+import process from 'node:process'
+import { core } from '@h-ai/core'
+import { serv, ServConfigSchema } from '@h-ai/serv'
+import { createServerApp } from './app-server.js'
+import { closeModules, initializeModules } from './server/runtime.js'
+
+async function startServer(): Promise<void> {
+  // 加载配置后按依赖顺序初始化；日志设置沿用 _core.yml。
+  core.init({ configDir: './config' })
+  await initializeModules()
+  try {
+    // HOST/PORT 环境变量优先于 config/_serv.yml。
+    const { server } = ServConfigSchema.parse(core.config.getOrThrow<ServConfigInput>('serv'))
+    const app = createServerApp()
+    await new Promise<void>((resolve, reject) => {
+      const listener = serv.listen(app, {
+        host: server.host,
+        port: server.port,
+        onListening: (info) => {
+          core.logger.info('Application listening', { name: core.config.getOrThrow<CoreConfig>('core').name, host: server.host, port: info.port })
+          resolve()
+        },
+        onClose: closeModules,
+      })
+      listener.server.once('error', reject)
+      listener.server.once('listening', () => listener.server.off('error', reject))
+    })
+  }
+  catch (error) {
+    await closeModules()
+    throw error
+  }
+}
+
+void startServer().catch((error: unknown) => {
+  core.logger.fatal('Application startup failed', { error })
+  process.exitCode = 1
+})