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

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.64",
+  "version": "0.1.0-alpha.66",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",
@@ -21,33 +21,37 @@
     "paraglide:compile": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
 {{/if}}
     "dev": "vite dev",
-    "build": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vite build",
+    "dev:test": "vite dev --mode test",
+    "dev:prod": "vite dev --mode prod",
+    "compile": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vite build",
+    "build": "hai build",
+    "deploy": "hai deploy",
+{{#unless isSvelteOnlyApp}}
+    "start": "node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local build/index.js",
+    "start:test": "node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local build/index.js",
+    "start:prod": "pnpm start",
+{{/unless}}
     "preview": "vite preview",
-    "check": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}{{#if isSvelteOnlyApp}}svelte-check --tsconfig ./tsconfig.json{{else}}svelte-kit sync && svelte-check --tsconfig ./tsconfig.json{{/if}}",
+    "check": "pnpm typecheck",
     "typecheck": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}{{#if isSvelteOnlyApp}}svelte-check --tsconfig ./tsconfig.json{{else}}svelte-kit sync && svelte-check --tsconfig ./tsconfig.json{{/if}}",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vitest run",
     "test:watch": "vitest",
-    "test:e2e": "playwright test",
-    "clean": "{{#if isSvelteOnlyApp}}rimraf dist build android ios .turbo src/lib/paraglide{{else}}rimraf .svelte-kit build .turbo{{/if}}",
-    "docker:build": "docker build --target runtime -t {{projectName}}:latest .",
-{{#unless isSvelteOnlyApp}}
-    "docker:build:data": "docker build --target runtime-with-data --build-context embedded-data=./data -t {{projectName}}:latest .",
-{{/unless}}
-    "podman:build": "podman build --format docker --jobs=1 --target runtime -t {{projectName}}:latest ."{{#unless isSvelteOnlyApp}},
-    "podman:build:data": "podman build --format docker --jobs=1 --target runtime-with-data --build-context embedded-data=./data -t {{projectName}}:latest ."{{/unless}}{{#if isCapacitorApp}},
+    "test:e2e": "node scripts/run-e2e.mjs",
+    "clean": "{{#if isSvelteOnlyApp}}rimraf dist build android ios .turbo src/lib/paraglide{{else}}rimraf .svelte-kit build .turbo{{/if}}"{{#if isCapacitorApp}},
     "cap:add:android": "cap add android",
     "cap:add:ios": "cap add ios",
-    "cap:sync": "pnpm build && cap sync",
-    "cap:sync:android": "pnpm build && cap sync android",
-    "cap:sync:ios": "pnpm build && cap sync ios",
+    "cap:sync": "pnpm compile && cap sync",
+    "cap:sync:android": "pnpm compile && cap sync android",
+    "cap:sync:ios": "pnpm compile && cap sync ios",
     "cap:android": "cap open android",
     "cap:ios": "cap open ios",
     "cap:run:android": "cap run android",
     "cap:run:ios": "cap run ios",
-    "cap:build:android:debug": "pnpm build && cap sync android && cd android && gradlew.bat assembleDebug",
-    "cap:build:android:release": "pnpm build && cap sync android && cap build android --androidreleasetype APK",
-    "cap:build:ios": "pnpm build && cap sync ios && cap build ios"{{/if}}
+    "cap:build:android:debug": "pnpm compile && cap sync android && cd android && gradlew.bat assembleDebug",
+    "cap:build:android:release": "pnpm compile && cap sync android && cap build android --androidreleasetype APK",
+    "cap:build:ios": "pnpm compile && cap sync ios && cap build ios"{{/if}}
   },
   "dependencies": {
   {{#if isSvelteOnlyApp}}
@@ -79,6 +83,10 @@
 {{/if}}
   },
   "devDependencies": {
+    "@h-ai/cli": "{{haiPackageSpecifier}}",
+{{#if isSvelteOnlyApp}}
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+{{/if}}
     "@antfu/eslint-config": "{{versions.antfuEslintConfig}}",
     "@playwright/test": "{{versions.playwright}}",
 {{#if isCapacitorApp}}

package/templates/base/svelte.config.js.hbs

@@ -56,6 +56,8 @@ const config = {
     runes: true,
   },
   kit: {
+    // 环境文件由 Vite 的 core loader 统一加载；Kit 不再二次读取根目录私有配置。
+    env: { dir: './.svelte-kit' },
 {{#if isCapacitorApp}}
     adapter: adapter({
       pages: 'build',

package/templates/base/tests/scaffold.test.ts.hbs

@@ -3,6 +3,9 @@ import type { CoreConfig } from '@h-ai/core'
 {{/unless}}
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
+{{#unless isSvelteOnlyApp}}
+import process from 'node:process'
+{{/unless}}
 import { fileURLToPath } from 'node:url'
 {{#unless isSvelteOnlyApp}}
 import { core } from '@h-ai/core'
@@ -43,9 +46,12 @@ describe('generated scaffold', () => {
 {{#unless isCapacitorApp}}
 
   it('ships an application config loaded at startup', async () => {
-    const coreConfig = await readFile(join(rootDir, 'config/_core.yml'), 'utf-8')
-    expect(coreConfig).toContain('name: {{projectName}}')
-    expect(coreConfig).toContain('defaultLocale: {{defaultLocale}}')
+    const result = core.config.load<CoreConfig>('core', join(rootDir, 'config/_core.yml'))
+    expect(result.success).toBe(true)
+    if (!result.success)
+      return
+    expect(result.data.name).toBe(process.env.HAI_CORE_NAME ?? '{{projectName}}')
+    expect(result.data.defaultLocale).toBe(process.env.HAI_CORE_DEFAULTLOCALE ?? '{{defaultLocale}}')
   })
 {{/unless}}
 {{#unless isSvelteOnlyApp}}

package/templates/base/vite.config.ts.hbs

@@ -6,9 +6,7 @@ import type { CoreConfig } from '@h-ai/core'
 {{/if}}
 import path from 'node:path'
 import process from 'node:process'
-{{#if isSvelteOnlyApp}}
 import { core } from '@h-ai/core'
-{{/if}}
 {{#if hasUi}}
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 {{/if}}
@@ -23,10 +21,16 @@ import { sveltekit } from '@sveltejs/kit/vite'
 {{#if hasUi}}
 import tailwindcss from '@tailwindcss/vite'
 {{/if}}
-import { defineConfig, loadEnv } from 'vite'
+import { defineConfig } from 'vite'
+{{#if isSvelteOnlyApp}}
+import { publicRuntimeConfig } from './scripts/vite-runtime-config.js'
+{{/if}}
 
-export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, process.cwd(), '')
+export default defineConfig(({ mode, command }) => {
+  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir: process.cwd() })
+  if (!envResult.success)
+    throw new Error(envResult.error.message)
+  const env = envResult.data
   Object.assign(process.env, env)
 {{#if isSvelteOnlyApp}}
   // 浏览器无法读取 YAML；构建时通过 core 解析，仅注入明确可公开的字段。
@@ -42,12 +46,14 @@ export default defineConfig(({ mode }) => {
 {{/if}}
 
   return {
+    envDir: false,
     envPrefix: ['VITE_', 'PUBLIC_'],
 {{#if isSvelteOnlyApp}}
     define: { __APP_CORE_CONFIG__: JSON.stringify(appConfig) },
 {{/if}}
     plugins: [
   {{#if isSvelteOnlyApp}}
+      publicRuntimeConfig({ apiBase: process.env.PUBLIC_API_BASE, core: appConfig }),
       svelte(),
   {{else}}
       sveltekit(),

package/templates/shared/.gitattributes

@@ -0,0 +1,5 @@
+# Windows 构建机交付 Linux 启动脚本时必须保留 LF，避免 /bin/sh 解释器失效。
+*.sh text eol=lf
+*.sh.hbs text eol=lf
+*.envsh text eol=lf
+*.envsh.hbs text eol=lf

package/templates/shared/container-runtime-config.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+set -eu
+
+# 只编码公开白名单；Base64 不会把环境值中的引号或换行解释为 JavaScript。
+encode() { printf '%s' "$1" | base64 | tr -d '\n'; }
+mkdir -p /tmp/hai-runtime-config
+cat > /tmp/hai-runtime-config/runtime-config.js <<EOF
+{
+  const decode = value => new TextDecoder().decode(Uint8Array.from(atob(value), character => character.charCodeAt(0)));
+  const nonempty = object => Object.fromEntries(Object.entries(object).filter(([, value]) => value !== ''));
+  const core = nonempty({
+    name: decode('$(encode "${HAI_CORE_NAME:-}")'),
+    version: decode('$(encode "${HAI_CORE_VERSION:-}")'),
+    env: decode('$(encode "${HAI_CORE_ENV:-}")'),
+    defaultLocale: decode('$(encode "${HAI_CORE_DEFAULTLOCALE:-}")')
+  });
+  const logging = nonempty({
+    level: decode('$(encode "${HAI_CORE_LOGGING_LEVEL:-}")'),
+    format: decode('$(encode "${HAI_CORE_LOGGING_FORMAT:-}")')
+  });
+  if (Object.keys(logging).length) core.logging = logging;
+  const config = nonempty({
+    apiBase: decode('$(encode "${PUBLIC_API_BASE:-}")'),
+    apiTransport: decode('$(encode "${PUBLIC_API_TRANSPORT:-}")'),
+    apiKeyExchangePath: decode('$(encode "${PUBLIC_API_KEY_EXCHANGE_PATH:-}")')
+  });
+  if (Object.keys(core).length) config.core = core;
+  globalThis.__HAI_PUBLIC_CONFIG__ = { ...globalThis.__HAI_PUBLIC_CONFIG__, ...config };
+}
+EOF

package/templates/shared/hash-router.svelte.ts

@@ -0,0 +1,83 @@
+import { SvelteMap, SvelteURL } from 'svelte/reactivity'
+
+/**
+ * 页面目录驱动的 hash 导航；仅管理 URL，不包含业务权限或页面加载逻辑。
+ * @example
+ * ```ts
+ * const pages = import.meta.glob('../pages/*.svelte')
+ * const router = new HashRouter(Object.keys(pages), '/home')
+ * const stop = router.start(() => void loadCurrentPage())
+ * router.navigate('/reports/weekly?period=month')
+ * stop()
+ * ```
+ */
+export class HashRouter {
+  /** 当前页面路径，例如 `/reports/weekly`。 */
+  path = $state('')
+  /** 当前页面查询串，例如 `?period=month`。 */
+  search = $state('')
+  private readonly files = new SvelteMap<string, string>()
+
+  private readonly fallback: string
+
+  /**
+   * 建立页面文件到 URL 的映射，新增页面无需维护路由表。
+   * @param pageFiles - import.meta.glob 返回的文件名
+   * @param fallback - 空路径和未知页面的回退路径
+   * @example new HashRouter(Object.keys(import.meta.glob('../pages/*.svelte')), '/home')
+   */
+  constructor(pageFiles: string[], fallback: string) {
+    this.fallback = fallback
+    for (const file of pageFiles) {
+      const route = file.replace(/^.*\/pages/, '').replace(/\.svelte$/, '').replace(/\/index$/, '') || '/'
+      this.files.set(route, file)
+    }
+    if (!this.files.has(fallback))
+      throw new Error('Hash router fallback page is missing')
+    this.path = fallback
+  }
+
+  /** 当前路径对应的页面文件；可用于索引 import.meta.glob 的惰性加载器。 */
+  get file(): string {
+    return this.files.get(this.path) ?? this.files.get(this.fallback)!
+  }
+
+  /**
+   * 恢复地址栏状态并监听链接、前进与后退；卸载时调用返回的清理函数。
+   * @param onChange - URL 导航完成后的业务通知
+   * @returns 移除事件监听器的函数
+   * @example const stop = router.start(() => void store.navigate(router.path.slice(1)))
+   */
+  start(onChange: () => void = () => {}): () => void {
+    const synchronize = () => {
+      this.navigate(location.hash.slice(1), true)
+      onChange()
+    }
+    synchronize()
+    window.addEventListener('hashchange', synchronize)
+    return () => {
+      window.removeEventListener('hashchange', synchronize)
+    }
+  }
+
+  /**
+   * 导航到页面；未知路径回退，查询串随 hash 保留并可在刷新后恢复。
+   * @param target - 以 `/` 开头的本地页面路径和查询串
+   * @param replace - 是否替换当前历史项
+   * @example router.navigate('/settings?section=profile')
+   */
+  navigate(target: string, replace = false): void {
+    const local = target.startsWith('/') && !target.startsWith('//') && !target.includes('\\')
+    const url = new SvelteURL(local ? target : this.fallback, 'https://hash.invalid')
+    const known = this.files.has(url.pathname)
+    this.path = known ? url.pathname : this.fallback
+    this.search = known ? url.search : ''
+    const hash = `#${this.path}${this.search}`
+    if (location.hash !== hash) {
+      if (replace)
+        history.replaceState(history.state, '', hash)
+      else
+        history.pushState(history.state, '', hash)
+    }
+  }
+}

package/templates/shared/run-e2e.mjs

@@ -0,0 +1,65 @@
+/** 运行浏览器验收，并在报告写完后清理本次输出；失败和中断同样清理。 */
+import { spawn } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import process from 'node:process'
+
+const cwd = process.cwd()
+const require = createRequire(resolve(cwd, 'package.json'))
+const cli = require.resolve('@playwright/test/cli')
+const dataParent = resolve(process.env.HAI_E2E_DATA_ROOT || tmpdir())
+mkdirSync(dataParent, { recursive: true })
+const dataRoot = mkdtempSync(join(dataParent, 'hai-browser-e2e-'))
+const groups = [[]]
+for (const argument of process.argv.slice(2)) {
+  if (argument === '--next')
+    groups.push([])
+  else
+    groups.at(-1).push(argument)
+}
+let child
+let interrupted = false
+function stop() {
+  if (interrupted)
+    return
+  interrupted = true
+  if (process.platform === 'win32' && child?.pid && child.exitCode === null) {
+    // Windows 的 kill 不传递 SIGTERM；同时结束本次 Playwright 创建的浏览器与服务进程。
+    spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
+      .once('error', () => child?.kill())
+  }
+  else {
+    child?.kill()
+  }
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+try {
+  for (const args of groups) {
+    const code = await new Promise((resolve, reject) => {
+      child = spawn(process.execPath, [cli, 'test', ...args], {
+        cwd,
+        windowsHide: true,
+        stdio: 'inherit',
+        env: { ...process.env, HAI_AUTH_EVIDENCE_DIR: join(cwd, 'test-results/evidence'), HAI_E2E_DATA_ROOT: dataRoot },
+      })
+      child.once('error', reject)
+      child.once('exit', resolve)
+    })
+    if (code !== 0 || interrupted) {
+      process.exitCode = typeof code === 'number' && code !== 0 ? code : 1
+      break
+    }
+  }
+}
+finally {
+  process.removeListener('SIGINT', stop)
+  process.removeListener('SIGTERM', stop)
+  // 固定为当前测试工程中的标准输出目录，禁止删除调用方任意指定的路径。
+  for (const name of ['test-results', 'playwright-report'])
+    rmSync(join(cwd, name), { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  // Playwright 退出后服务进程已关闭，此时删除 SQLite / storage，避免 Windows 文件锁。
+  rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+}

package/templates/shared/vite-runtime-config.ts

@@ -0,0 +1,54 @@
+/** Vite 开发与预览的公开运行配置；同一份静态构建可连接不同环境的 API。 */
+import type { CoreConfig } from '@h-ai/core'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Plugin } from 'vite'
+
+/** 只允许浏览器可见的地址、开关和品牌字段，禁止传入 process.env 或完整服务配置。 */
+export interface PublicRuntimeConfig {
+  /** 包含 API 前缀的公开地址，例如 https://example.test/api/v1。 */
+  apiBase?: string
+  /** 客户端传输开关，与服务端一致。 */
+  apiTransport?: string
+  /** 公开密钥交换端点。 */
+  apiKeyExchangePath?: string
+  /** 客户端公开元数据；不含密钥或连接参数。 */
+  core?: Pick<CoreConfig, 'name' | 'version' | 'env' | 'defaultLocale'> & { logging?: Pick<NonNullable<CoreConfig['logging']>, 'level' | 'format'> }
+}
+
+/**
+ * 在加载应用前提供无缓存的公开配置；构建只复制空的占位文件。
+ * @example `plugins: [publicRuntimeConfig({ apiBase: process.env.PUBLIC_API_BASE })]`
+ */
+export function publicRuntimeConfig(config: PublicRuntimeConfig): Plugin {
+  const metadata = config.core
+  // 明确投影字段，JavaScript 调用方即使误传完整配置也不能公开连接参数或密钥。
+  const publicConfig: PublicRuntimeConfig = {
+    apiBase: config.apiBase,
+    apiTransport: config.apiTransport,
+    apiKeyExchangePath: config.apiKeyExchangePath,
+    core: metadata
+      ? {
+          name: metadata.name,
+          version: metadata.version,
+          env: metadata.env,
+          defaultLocale: metadata.defaultLocale,
+          logging: metadata.logging ? { level: metadata.logging.level, format: metadata.logging.format } : undefined,
+        }
+      : undefined,
+  }
+  const body = `globalThis.__HAI_PUBLIC_CONFIG__ = { ...globalThis.__HAI_PUBLIC_CONFIG__, ...${JSON.stringify(publicConfig)} };\n`
+  const respond = (_request: IncomingMessage, response: ServerResponse): void => {
+    response.setHeader('Content-Type', 'application/javascript; charset=utf-8')
+    response.setHeader('Cache-Control', 'no-store')
+    response.end(body)
+  }
+  return {
+    name: 'hai-public-runtime-config',
+    configureServer(server) {
+      server.middlewares.use('/runtime-config.js', respond)
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use('/runtime-config.js', respond)
+    },
+  }
+}

package/templates/skills/AGENTS.md

@@ -2,13 +2,20 @@
 
 > 通用 AI 编程助手入口。优先阅读 `README.md`、现有测试与 `.agents/skills/`；本文件同时作为 `hai add` / AI 支持回填时的 generic fallback。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
+- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
+- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
+- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+
 ## 行为契约
 
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
 
-根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
 
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
@@ -36,6 +43,13 @@
 3. 改动公共类型、配置、模板或共享逻辑时，同步更新所有调用方与文档。
 4. 每次改动后按影响范围运行质量门禁并记录结果。
 
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
+- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
+- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
+- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
+
 ## 质量门禁
 
 先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。

package/templates/skills/bridges/admin/AGENTS.md

@@ -2,13 +2,20 @@
 
 > 管理后台项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`src/lib/server/` 与 `messages/*` 工作。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
+- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
+- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
+- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+
 ## 行为契约
 
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
 
-根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
 
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
@@ -42,6 +49,15 @@
 2. 变更权限、登录、会话、导航或 CRUD 页面时，优先扩展现有 service / component，而不是临时散落逻辑。
 3. 修改页面、API、认证流程后，同步测试、README 和 i18n。
 
+页面统一继承根布局的 header/footer；新增页面沿用 SvelteKit 自动文件路由，刷新定位及服务端 load/鉴权保持一致。
+
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
+- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
+- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
+- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
+
 ## 质量门禁
 
 先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。

package/templates/skills/bridges/api/AGENTS.md

@@ -2,13 +2,20 @@
 
 > API 服务项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`apps/*-contract/src/**`、`apps/*-service/src/**` 与测试工作。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
+- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
+- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
+- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+
 ## 行为契约
 
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
 
-根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
 
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
@@ -30,9 +37,9 @@
 ## 架构边界
 
 - API 输入输出必须由 `apps/*-contract/src/**` 中的 Zod schema 与 contract 定义统一约束。
-- Service 通过 `@h-ai/serv` + `@h-ai/api-contract` 装配 HTTP App；不要退回到 SvelteKit API routes 架构。
+- 当前 Service 通过 `@h-ai/serv` + `@h-ai/api-contract` 装配 HTTP App；保留此架构时不混入 SvelteKit API routes，需求要求迁移时同步入口、contract、调用方与脚本。
 - Typed client / contract / service 三者保持同一份路径与类型定义，不要复制粘贴接口。
-- 不生成用户页面；不要引入 UI 专属依赖或页面文案。
+- 纯 API 需求不生成用户页面或引入 UI 专属依赖；需求增加前端时，按实际架构补充应用及其文案和验证。
 - 配置和密钥来自 `apps/*-service/config/` 与环境变量，禁止硬编码。
 
 ## 工作流程
@@ -41,6 +48,13 @@
 2. 修改 contract、响应格式、安全策略或配置时，同步 README、typed client 调用方与测试。
 3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
 
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
+- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
+- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
+- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
+
 ## 质量门禁
 
 先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。

package/templates/skills/bridges/fullstack/AGENTS.md.hbs

@@ -2,13 +2,20 @@
 
 Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 package/app；模块用法按需读取 `.agents/skills/*/SKILL.md` 及其引用。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
+- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
+- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
+- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+
 ## 行为契约
 
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
 
-根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
 
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
@@ -21,7 +28,11 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 - 修改前检索实现、调用方、测试和文档，优先复用现有 contract、procedure、共享组件与脚本。
 - 跨包变更先明确受影响的 contract、serv、shared、前端及交付流程，再同步调用方；不必输出固定问卷。
 
-## 架构边界
+## 初始架构
+
+- 页面统一继承公共 header/footer；新增 SPA 页面放 `packages/{{projectName}}-shared/src/lib/pages/**/*.svelte`，由 `HashRouter` 自动发现。菜单只维护业务入口，不维护路由表。
+
+以下为生成时的目录和分层；需求调整架构时同步相关包、脚本与说明，按调整后的实际结构工作。
 
 | 路径 | 职责 |
 | --- | --- |
@@ -33,20 +44,33 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 | `apps/{{projectName}}-desktop` | Svelte 5 + Vite + Tauri v2 桌面端，按选择生成 |
 | `apps/{{projectName}}-miniapp` | 选择 miniapp 时生成的预留说明与文案，当前不是可运行应用 |
 
-- 前端负责 UI 与请求编排；后端业务放 serv，共享能力放 shared。本样板默认不用 `@h-ai/kit`，不要混入 SvelteKit load / route 结构。
+- 前端负责 UI 与请求编排；后端业务放 serv，共享能力放 shared。保留当前 Vite SPA 架构时，不混入 SvelteKit load / route 结构；需要迁移时成套调整。
 - 用户文本按 shared 跨端文案与各 app 专属文案分工，同步现有 locale。
 - 本样板默认启用 IAM、reldb、cache、audit、storage 和 crypto，复用现有初始化与关闭顺序；新增模块前先检查依赖、配置与公开契约。
 - 应用名称、版本、环境、日志与 locale 配置通过 core 统一获取；浏览器显示来自服务端 `app.info`，不另写硬编码副本或将私有配置注入客户端。
 
-## 管理与安全边界
+## 初始管理业务
+
+这些是可运行示例的默认行为，按实际需求选择保留、修改或移除；不是 hai-framework 对所有应用的要求。
+
+- 初始使用 `admin` / `user` 两种角色：管理员进入用户、角色和审计管理，普通用户进入个人设置。角色代码、数量、权限粒度及可访问页面由业务需求决定；更换模型时同步服务端授权、资源范围与各端入口。
+- 初始角色页维护说明并显示人数，用户页分配角色；示例防止管理员自删除、自禁用、自降级及移除最后管理员。是否采用这些流程和保护由需求确定，保留的业务不变量需覆盖并发管理请求。
+- 默认头像接受 PNG/JPEG/WebP，最大 512 KiB；普通用户更新自己的头像，管理员可替用户更新。格式、限额和操作主体可调整，contract、客户端和服务端保持一致；仍需验证文件内容及资源访问权限，storage key 由服务端生成。
+- 默认用户与审计列表使用页码分页：`page >= 1`、`pageSize` 为 1–100、每页 20 条。分页方式、筛选和上限可按需求调整，同步 schema、procedure、store 和测试。
+- 默认将语言与主题偏好保存到当前用户 metadata，审计采用操作字段和资源标识。偏好来源、审计字段、保留期及失败策略按需求确定，敏感数据按实际用途脱敏。
+
+## 当前传输与安全契约
+
+- JSON 业务请求与响应经 typed api-client 和 serv 的 crypto transport 加解密，包含登录与刷新；健康/就绪检查和公开头像二进制资源使用既有例外。新增 API 沿用当前管道；需求调整传输方案时同步客户端、服务端及测试，不能静默绕过仍生效的安全契约。
+- Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端装配 `createCapacitorTokenStorage`，浏览器预览沿用 Cookie；Desktop 原生端使用内存 TokenStorage，重启后重新登录。原生 body 刷新通道同时验证 `X-HAI-Token-Transport: body`、端对应的 `x-request-client` 与受信完整 Origin，刷新请求沿用这些头。调整会话方案时保持凭据保护和通道校验；敏感 token 不写 localStorage 或普通配置文件。
+- 服务端依据实际权限模型验证每个受保护操作，个人操作绑定当前会话，代他人操作验证对应权限；不能只靠隐藏导航保护资源。SQL 动态值参数化，日志与审计不泄露密码、token 或密钥。
+
+## 代码注释与示例
 
-- `admin` / `user` 是固定角色代码。管理员进入用户、角色和审计管理；普通用户只进入个人设置。服务端为每个管理操作验证角色，个人资料、密码和头像按当前会话绑定用户，不能只靠导航隐藏保护权限。
-- 角色管理更新说明并显示人数，用户管理负责角色分配；保留当前管理员的自删除、自禁用、自降级及最后管理员保护，并验证并发管理请求。
-- JSON 业务请求与响应统一经 typed api-client 和 serv 的 crypto transport 加解密，包含登录与刷新；健康/就绪检查和公开头像二进制资源遵循已有例外，不能为新增业务 API 绕过传输加密。
-- Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端装配 `createCapacitorTokenStorage`，浏览器预览沿用 Cookie；Desktop 原生端使用内存 TokenStorage，重启后重新登录。原生 body 刷新通道同时验证 `X-HAI-Token-Transport: body`、端对应的 `x-request-client` 与受信完整 Origin，刷新请求沿用这些头。敏感 token 不写 localStorage，不擅自将其持久化到普通配置文件。
-- 头像接受 PNG/JPEG/WebP，最大 512 KiB；contract、客户端与服务端校验保持一致。服务端验证实际图片数据并生成 storage key；普通用户仅更新自己的头像，管理员可替用户更新。
-- 用户与审计查询按 contract 分页，`page >= 1`、`pageSize` 为 1–100；页面默认每页 20 条。新增筛选同步 schema、procedure、store 和测试，SQL 值参数化。
-- 语言与主题偏好保存到当前用户 metadata，客户端只应用已支持的值。审计仅记录操作字段和资源标识，不记录密码、token、头像内容或联系信息。
+- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
+- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
+- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
+- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
 
 ## 质量门禁