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

package/templates/shared/public-base-path.mjs

@@ -8,12 +8,25 @@ const basePathMessage = core.i18n.createMessageGetter({
   'ja-JP': { invalid: 'PUBLIC_BASE_PATHは空、または/で始まるサイト内ディレクトリーです。外部URL、末尾の/、クエリー、フラグメント、パス逸脱は使えません。' },
 })
 
-/** @param {string} [value] - 无末尾斜杠的公开目录；空字符串表示域名根目录。 */
+/**
+ * @param {string} [value] - 无末尾斜杠的公开目录；空字符串表示域名根目录。
+ * @returns {'' | `/${string}`} 经校验的站内挂载目录，可直接用于 SvelteKit paths.base。
+ */
 export function resolvePublicBasePath(value = process.env.PUBLIC_BASE_PATH ?? '') {
   if (value && (!/^\/[\w.-]+(?:\/[\w.-]+)*$/.test(value) || value.split('/').some(segment => segment === '.' || segment === '..'))) {
-    const language = [process.env.HAI_CORE_DEFAULTLOCALE, process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG].find(item => item?.trim())?.split(/[_.-]/)[0]?.toLowerCase()
-    const locale = language === 'en' || language === 'c' || language === 'posix' ? 'en-US' : language === 'ja' ? 'ja-JP' : 'zh-CN'
+    const language = [
+      process.env.HAI_CORE_DEFAULTLOCALE,
+      process.env.LC_ALL,
+      process.env.LC_MESSAGES,
+      process.env.LANG,
+    ].find(item => item?.trim())?.split(/[_.-]/)[0]?.toLowerCase()
+    const locale = language === 'en' || language === 'c' || language === 'posix'
+      ? 'en-US'
+      : language === 'ja'
+        ? 'ja-JP'
+        : 'zh-CN'
     throw new Error(basePathMessage('invalid', { locale }))
   }
-  return value
+  // 已排除不以 / 开头的非空字符串；正则校验无法自动收窄 TypeScript 字符串类型。
+  return /** @type {'' | `/${string}`} */ (value)
 }

package/templates/shared/run-e2e.mjs

@@ -12,12 +12,16 @@ 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 = [[]]
+const groups = [
+  { args: [], name: undefined },
+]
 for (const argument of process.argv.slice(2)) {
   if (argument === '--next')
-    groups.push([])
+    groups.push({ args: [], name: undefined })
+  else if (argument.startsWith('--e2e-group='))
+    groups.at(-1).name = argument.slice('--e2e-group='.length)
   else
-    groups.at(-1).push(argument)
+    groups.at(-1).args.push(argument)
 }
 let child
 let interrupted = false
@@ -37,7 +41,12 @@ function stop() {
   if (process.platform === 'win32' && child?.pid && child.exitCode === null) {
     // Windows 的 kill 不传递 SIGTERM；同时结束本次 Playwright 创建的浏览器与服务进程。
     stopping = new Promise((resolve) => {
-      const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
+      const killer = spawn('taskkill', [
+        '/pid',
+        String(child.pid),
+        '/t',
+        '/f',
+      ], { windowsHide: true, stdio: 'ignore' })
       killer.once('error', () => {
         child?.kill()
         resolve()
@@ -56,31 +65,49 @@ try {
   const evidenceParent = resolve(process.env.HAI_AUTH_EVIDENCE_DIR || join(cwd, 'test-results'))
   mkdirSync(evidenceParent, { recursive: true })
   const runRoot = mkdtempSync(join(evidenceParent, 'run-'))
-  for (const [index, args] of groups.entries()) {
+  for (const [index, { args, name }] of groups.entries()) {
     const groupRoot = join(runRoot, `group-${index + 1}`)
     const groupDataRoot = join(dataRoot, `group-${index + 1}`)
     mkdirSync(groupDataRoot)
     const hasOutput = args.some(argument => argument === '--output' || argument.startsWith('--output='))
-    const outputArgs = hasOutput ? [] : ['--output', join(groupRoot, 'results')]
+    const outputArgs = hasOutput
+      ? []
+      : [
+          '--output',
+          join(groupRoot, 'results'),
+        ]
     const html = process.env.PLAYWRIGHT_HTML_OUTPUT_DIR || process.env.PLAYWRIGHT_HTML_REPORT
     const code = await new Promise((resolve, reject) => {
-      child = spawn(process.execPath, [cli, 'test', ...args, ...outputArgs], {
+      child = spawn(process.execPath, [
+        cli,
+        'test',
+        ...args,
+        ...outputArgs,
+      ], {
         cwd,
         windowsHide: true,
         stdio: 'inherit',
         env: {
           ...process.env,
-          ...(!html ? { PLAYWRIGHT_HTML_OUTPUT_DIR: join(groupRoot, 'html') } : {}),
+          ...(!html
+            ? {
+                PLAYWRIGHT_HTML_OUTPUT_DIR: join(groupRoot, 'html'),
+              }
+            : {}),
           HAI_AUTH_EVIDENCE_DIR: process.env.HAI_AUTH_EVIDENCE_DIR || join(groupRoot, 'evidence'),
           HAI_E2E_DATA_ROOT: groupDataRoot,
+          HAI_E2E_GROUP: name,
         },
       })
       child.once('error', reject)
       child.once('exit', resolve)
     })
     // 配置组互相独立，普通失败继续收集；保留首个失败码，中断才停止后续组。
-    if (code !== 0)
-      process.exitCode ||= typeof code === 'number' && code !== 0 ? code : 1
+    if (code !== 0) {
+      process.exitCode ||= typeof code === 'number' && code !== 0
+        ? code
+        : 1
+    }
     if (interrupted) {
       process.exitCode ||= 1
       break
@@ -93,10 +120,17 @@ finally {
   await stopping
   // Playwright 退出后服务进程已关闭，此时删除 SQLite / storage，避免 Windows 文件锁。
   try {
-    rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+    rmSync(dataRoot, {
+      recursive: true,
+      force: true,
+      maxRetries: 3,
+      retryDelay: 100,
+    })
   }
   catch (error) {
-    process.stderr.write(`E2E data cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.stderr.write(`E2E data cleanup failed: ${error instanceof Error
+      ? error.message
+      : String(error)}\n`)
     // 清理错误不能把原始失败（如 exit 7）覆盖成另一状态，也不能让成功变为假成功。
     if (!process.exitCode)
       process.exitCode = 1

package/templates/shared/run-node.mjs

@@ -0,0 +1,56 @@
+/** 所有模板共用环境来源规则启动 Node，让 NODE_OPTIONS 在子进程启动前生效。 */
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { resolve } from 'node:path'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+const [mode, environmentDirectory, entry, ...arguments_] = process.argv.slice(2)
+if (!mode || !environmentDirectory || !entry)
+  throw new Error('Usage: node run-node.mjs <mode> <env-directory> <entry> [arguments]')
+
+// 从实际应用解析公开 Core 入口，脚本可以放在 workspace 根目录。
+const require = createRequire(resolve('package.json'))
+const { core } = await import(pathToFileURL(require.resolve('@h-ai/core')).href)
+const loaded = core.config.loadEnvFiles({
+  mode,
+  envDir: resolve(environmentDirectory),
+})
+if (!loaded.success)
+  throw new Error(loaded.error.message)
+
+const child = spawn(process.execPath, [
+  resolve(entry),
+  ...arguments_,
+], {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    ...loaded.data,
+  },
+  stdio: 'inherit',
+  windowsHide: true,
+})
+function interrupt() {
+  child.kill('SIGINT')
+}
+function terminate() {
+  child.kill('SIGTERM')
+}
+process.on('SIGINT', interrupt)
+process.on('SIGTERM', terminate)
+try {
+  const result = await new Promise((resolve, reject) => {
+    child.once('error', reject)
+    child.once('close', (code, signal) => resolve({ code, signal }))
+  })
+  process.exitCode = result.code ?? (result.signal === 'SIGINT'
+    ? 130
+    : 143)
+}
+finally {
+  process.off('SIGINT', interrupt)
+  process.off('SIGTERM', terminate)
+  if (child.exitCode === null && child.signalCode === null)
+    child.kill('SIGTERM')
+}

package/templates/shared/run-tauri.mjs

@@ -0,0 +1,74 @@
+/** Tauri JSON 保留平台配置；名称通过 CLI 覆盖，不向源码写入环境值。 */
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { resolve } from 'node:path'
+import process from 'node:process'
+import { resolveNativeName } from './native-name.mjs'
+
+const [environmentDirectory, coreFile, ...args] = process.argv.slice(2)
+if (!environmentDirectory || !coreFile)
+  throw new Error('Expected environment directory and Core YAML path before Tauri arguments')
+const require = createRequire(resolve('package.json'))
+const separator = args.indexOf('--')
+const toolArgs = separator < 0
+  ? args
+  : args.slice(0, separator)
+const command = toolArgs.find(argument => !argument.startsWith('-'))
+if (['dev', 'build', 'bundle'].includes(command) && !toolArgs.some(argument => ['--help', '-h', '--version', '-V'].includes(argument))) {
+  const envDir = resolve(environmentDirectory)
+  const name = resolveNativeName(envDir, resolve(envDir, coreFile), command === 'dev'
+    ? 'dev'
+    : 'prod')
+  const config = JSON.parse(readFileSync(resolve('src-tauri/tauri.conf.json'), 'utf8'))
+  const platform = process.platform === 'win32'
+    ? 'windows'
+    : process.platform === 'darwin'
+      ? 'macos'
+      : 'linux'
+  const platformFile = resolve(`src-tauri/tauri.${platform}.conf.json`)
+  const patch = existsSync(platformFile)
+    ? JSON.parse(readFileSync(platformFile, 'utf8'))
+    : {}
+  // 与 Tauri 的 JSON Merge Patch 一致：平台数组整体替换，null 删除对应设置。
+  const app = patch.app === null
+    ? undefined
+    : {
+        ...config.app,
+        ...patch.app,
+      }
+  const main = app?.windows?.findIndex(window => (window.label ?? 'main') === 'main') ?? -1
+  const windows = app?.windows?.map((window, index) => index === (main < 0
+    ? 0
+    : main)
+    ? { ...window, title: name }
+    : window)
+  const overlay = {
+    productName: name,
+    ...(windows
+      ? {
+          app: { windows },
+        }
+      : {}),
+  }
+  // 名称是默认覆盖；调用方后续显式 --config 仍可覆盖它，保留 Tauri 原有优先级。
+  args.splice(args.indexOf(command) + 1, 0, '--config', JSON.stringify(overlay))
+}
+const child = spawn(process.execPath, [
+  require.resolve('@tauri-apps/cli/tauri.js'),
+  ...args,
+], { stdio: 'inherit', windowsHide: true })
+const interrupt = () => child.kill('SIGINT')
+const terminate = () => child.kill('SIGTERM')
+process.on('SIGINT', interrupt)
+process.on('SIGTERM', terminate)
+try {
+  process.exitCode = await new Promise((resolveExit, reject) => {
+    child.once('error', reject)
+    child.once('close', code => resolveExit(code ?? 1))
+  })
+}
+finally {
+  process.off('SIGINT', interrupt)
+  process.off('SIGTERM', terminate)
+}

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

@@ -32,7 +32,9 @@ export function publicRuntimeConfig(config: PublicRuntimeConfig): Plugin {
           version: metadata.version,
           env: metadata.env,
           defaultLocale: metadata.defaultLocale,
-          logging: metadata.logging ? { level: metadata.logging.level, format: metadata.logging.format } : undefined,
+          logging: metadata.logging
+            ? { level: metadata.logging.level, format: metadata.logging.format }
+            : undefined,
         }
       : undefined,
   }
@@ -45,11 +47,15 @@ export function publicRuntimeConfig(config: PublicRuntimeConfig): Plugin {
   return {
     name: 'hai-public-runtime-config',
     configureServer(server) {
-      const base = server.config.base.startsWith('/') ? server.config.base : '/'
+      const base = server.config.base.startsWith('/')
+        ? server.config.base
+        : '/'
       server.middlewares.use(`${base}runtime-config.js`, respond)
     },
     configurePreviewServer(server) {
-      const base = server.config.base.startsWith('/') ? server.config.base : '/'
+      const base = server.config.base.startsWith('/')
+        ? server.config.base
+        : '/'
       server.middlewares.use(`${base}runtime-config.js`, respond)
     },
   }

package/templates/skills/AGENTS.md

@@ -1,85 +1,22 @@
 # AGENTS.md
 
-> 通用 AI 编程助手入口。优先阅读 `README.md`、现有测试与 `.agents/skills/`；本文件同时作为 `hai add` / AI 支持回填时的 generic fallback。
-
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+> 通用 AI 编程助手入口；hai add / AI 支持回填未能确定工程类型时使用。实际布局以当前 README、package.json 和目录为准。
 
 ## 行为契约
 
-涉及框架数据结构、配置、核心流程或模块边界的新增、修改、删除，先读 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md)，说明实际影响并等待用户决定。已有具体确认不重复要求；普通应用私有实现按当前业务授权执行。确认后的变更成套更新文档、配置、网站内容源、注释、模板与调用方。
-
-需求/设计文档审查或从文档生成代码时，读取 [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 清单与任务记录，比较已验收与目标文档 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 树。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
-
-- 直接影响：修改 / 新建 / 删除哪些文件；哪些脚本、类型、配置或路由会变。
-- 间接影响：哪些测试、README、i18n、示例、共享类型、依赖方需要同步更新。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 项目概述
 
-本项目由 hai-framework CLI 生成。单应用工程通常在 `src/` 下开发；多包工程会同时包含 `packages/*` 与 `apps/*`。实际结构以当前项目目录为准。
-
-如项目使用 SvelteKit，`+server.ts` 只能导出 HTTP handler 与 SvelteKit 允许的配置项；辅助函数放到 `src/lib/**`。
-
-## 工作流程
-
-开发、审查、测试和排错先读[沟通与同步维护](.agents/skills/hai-app-create/collaboration.md)：结论优先，区分发现与待验证、计划与完成；按实际影响检查使用文档、配置示例、截图、测试、CLI 模板和调用方。每批说明解决什么、使用变化、验证及剩余问题。
-
-1. 先搜索现有实现、引用点、测试和 README。
-2. 小步修改，优先保持目录结构、公开 API 和脚本稳定。
-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 注释一节。
-
-## 质量门禁
-
-AI 先分析差异、调用方和受影响流程，默认只选择相关 test/E2E 与必要门禁，用户明确要求时才全量。核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集所选检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加相关 E2E，未运行项说明原因。
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
+本项目由 hai-framework CLI 生成，单应用通常位于 src/，多包工程位于 apps/ 与 packages/。不要按目录名猜测运行端或强行转换架构。
 
 ## 完成条件
 
-- typecheck / lint / build / test / test:e2e 状态明确；整轮收集后集中修复，最终必需门禁对最终代码有效通过，未执行或阻塞明确原因，不能宣称完成。
-- README、i18n、测试、代码注释与实现保持一致。
-- 最终回复说明执行过的门禁、已同步的文档 / 依赖方，以及未完成项。
-
-## Skills 路由
-
-- `.agents/skills/hai-build/SKILL.md`：架构、构建和质量门禁。
-- `.agents/skills/hai-app-create/SKILL.md`：应用骨架、路由、页面与 API 模板。
-- `.agents/skills/hai-app-review/SKILL.md`：应用代码审查。
-- `.agents/skills/hai-app-tests/SKILL.md`：Vitest / Playwright 测试策略。
-- 具体模块按需读取对应 `hai-*` Skill。
-
-前端项目已交付对应技能时，先按 hai-ui-design 确定任务、布局、状态与组件映射，使用 hai-ui 实现，再由 hai-ui-review 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。

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

@@ -2,35 +2,17 @@
 
 > 管理后台项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`src/lib/server/` 与 `messages/*` 工作。
 
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
 
 ## 行为契约
 
-涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
-
-需求/设计文档审查或从文档生成代码时，读取 [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 清单与任务记录，比较已验收与目标文档 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 树。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
-
-- 直接影响：哪些 `+page.svelte`、`+layout.svelte`、`+page.server.ts`、`+server.ts`、service、messages、README、测试会变。
-- 间接影响：哪些角色权限、导航入口、共享组件、表单流程和依赖模块需要同步。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 项目定位
 
@@ -40,50 +22,12 @@
 
 - 页面组件、layout、load 只负责渲染、权限态拼装和请求编排；业务逻辑放在 `src/lib/server/services` 或模块 API。
 - 认证授权使用 `@h-ai/iam` / `@h-ai/kit`；Web token 优先 httpOnly cookie。
-- 所有用户可见文本走 `$lib/paraglide/messages.js`，同步 `messages/zh-CN.json`、`messages/en-US.json`、`messages/ja-JP.json`。
+- 所有用户可见文本走 `#lib/paraglide/messages.js`，同步 `messages/zh-CN.json`、`messages/en-US.json`、`messages/ja-JP.json`。
 - API 边界必须做 Zod 校验，HaiResult 错误用 kit response 转换。
 - `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/server/**`。
 - 本样板默认不使用 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
 
-## 工作流程
-
-1. 先搜索现有路由、service、共享组件、messages 和测试。
-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，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
 
 ## 完成条件
 
-- 修改页面、API、认证流程时同步测试、README 和 i18n。
-- 修改公共模块用法或共享组件时，全局检索并同步依赖方。
-- 最终回复说明门禁状态、已更新页面 / API / 文档与未完成项。
-
-## 优先 Skills
-
-- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
-- `hai-kit`、`hai-ui`、`hai-iam`、`hai-reldb`、`hai-cache`、`hai-crypto`
-- 其它 `hai-*` 模块按需读取
-
-前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。

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

@@ -2,35 +2,17 @@
 
 > API 服务项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`apps/*-contract/src/**`、`apps/*-serv/src/**` 与测试工作。
 
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
 
 ## 行为契约
 
-涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
-
-需求/设计文档审查或从文档生成代码时，读取 [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 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-普通新增、修改、修复任务开始前，先读 [应用开发 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 树。
-
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
-
-- 直接影响：哪些 `apps/*-contract`、`apps/*-serv`、config、README、测试会变。
-- 间接影响：哪些 typed client、部署脚本、环境变量说明和断言需要同步。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 项目定位
 
@@ -44,40 +26,7 @@
 - 纯 API 需求不生成用户页面或引入 UI 专属依赖；需求增加前端时，按实际架构补充应用及其文案和验证。
 - 配置和密钥来自 `apps/*-serv/config/` 与环境变量，禁止硬编码。
 
-## 工作流程
-
-1. 先搜索现有 contract、procedures、init、config 和测试。
-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，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
 
 ## 完成条件
 
-- 修改 contract、procedure、配置或环境变量说明后，同步测试、README 和调用方。
-- 最终回复说明门禁状态、已更新 contract / service / 配置 / 文档与未完成项。
-
-## 优先 Skills
-
-- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
-- `hai-serv`、`hai-api-contract`、`hai-api-client`
-- `hai-core`、`hai-reldb`、`hai-cache`、`hai-iam`、`hai-crypto`
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。