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

package/templates/skills/hai-api-contract/reference.md

@@ -0,0 +1,278 @@
+# hai-api-contract 参考
+
+> `@h-ai/api-contract` 是 hai-framework 的公共 HTTP API 契约包，使用 oRPC contract + Zod v4 作为唯一接口真相源。本包只描述接口边界，不包含任何 procedure 实现。
+
+## 运行环境
+
+> ✅ **契约定义包，无服务端业务依赖；Zod/oRPC schema 构造仍有运行时代码。** 可在客户端、服务端、测试环境直接引用。
+
+## 适用场景
+
+- 定义新领域的 oRPC contract（输入/输出 Schema + HTTP 路由元数据）
+- 组合多个领域 contract 为应用级 contract
+- 向 `@h-ai/serv` 提供 contract（装配为 HTTP API）
+- 向 `@h-ai/api-client` 提供 contract（生成类型安全客户端）
+- 复用内置领域 contract（iam/storage/ai/payment）
+- 复用公共 Schema 工厂（`apiContract.haiResultSchema`、分页 Schema）
+
+## 使用步骤
+
+### 1. 组合应用级 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+// 按需组合，传 false/undefined 的领域不会出现在 contract 或 OpenAPI spec 中
+export const myContract = apiContract.create({
+  iam: apiContract.iam,
+  storage: apiContract.storage,
+  ai: apiContract.ai,
+  payment: false, // 禁用领域
+})
+
+// myContract.iam.auth.login
+// myContract.storage.presignedUrls.createUpload
+// myContract.ai.chats.createCompletion
+```
+
+### 2. 组合自定义 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+export const myContract = apiContract.create({
+  iam: apiContract.iam,
+  storage: apiContract.storage,
+  payment: false, // 禁用领域（不会出现在 contract 或 OpenAPI spec 中）
+})
+```
+
+### 3. 定义新领域 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+// 输入 Schema
+const WidgetCreateInputSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+})
+
+// 同一 contract 内两个接口复用，因此保留为文件私有常量，不从 schemas 导出。
+const WidgetOutputSchema = apiContract.haiResultSchema(z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: z.string(),
+}))
+
+// 领域 contract
+export const widgetContract = {
+  widget: {
+    create: apiContract
+      .route({
+        method: 'POST',
+        path: '/widgets',
+        operationId: 'widget.create',
+        summary: 'Create widget',
+        tags: ['widget'],
+      })
+      .input(WidgetCreateInputSchema)
+      .output(WidgetOutputSchema),
+
+    getById: apiContract
+      .route({
+        method: 'GET',
+        path: '/widgets/{id}',
+        operationId: 'widget.getById',
+        summary: 'Get widget by id',
+        tags: ['widget'],
+      })
+      .input(z.object({ id: z.string() }))
+      .output(WidgetOutputSchema),
+  },
+}
+```
+
+### 4. 将新 contract 挂入应用级 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { widgetContract } from './widget-contract.js'
+
+export const appContract = apiContract.create({
+  iam: apiContract.iam,
+  widget: widgetContract,
+})
+```
+
+### 5. 传给 `@h-ai/serv`（服务端）
+
+```typescript
+import { serv } from '@h-ai/serv'
+import { appContract } from './app-contract.js'
+import { createMyProcedures } from './procedures/widget.js'
+
+const app = serv.createApp({
+  contract: appContract,
+  procedures: {
+    iam: createIamProcedures({ iam }),
+    widget: createMyProcedures(),
+  },
+  http: { apiPrefix: '/api/v1' },
+})
+```
+
+## 核心 API
+
+### `apiContract.create(options)` — 组合领域 contract
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+const contract = apiContract.create({
+  iam: apiContract.iam,      // 启用：纳入 contract
+  storage: false,            // 禁用：不出现在 OpenAPI spec 中
+  custom: myContract,        // 自定义领域
+})
+// 类型自动收窄，被禁用的 key 不出现在 contract 类型中
+```
+
+### 内置领域 contract
+
+| 访问路径 | 领域 | 功能概述 |
+| --- | --- | --- |
+| `apiContract.iam` | IAM | auth（登录/登出/OTP/刷新/注册/改密码）、users、roles、permissions Admin CRUD |
+| `apiContract.storage` | Storage | presignedUrls（上传/下载/批量）、files（元数据查询/删除） |
+| `apiContract.ai` | AI | chats（completion/流式）、knowledge（上传/查询） |
+| `apiContract.payment` | Payment | orders、subscriptions |
+
+### 内置 contract 路径示例
+
+```typescript
+const myContract = apiContract.create({ iam: apiContract.iam, storage: apiContract.storage, ai: apiContract.ai })
+
+// IAM
+myContract.iam.auth.login        // POST /auth/login
+myContract.iam.auth.logout       // POST /auth/logout
+myContract.iam.users.list        // GET  /iam/users
+myContract.iam.roles.create      // POST /iam/roles
+
+// Storage
+myContract.storage.presignedUrls.createUpload   // POST /storage/presigned-urls/upload
+
+// AI
+myContract.ai.chats.createCompletion  // POST /ai/chats/completion
+```
+
+### `apiContract.haiResultSchema(dataSchema)` — 标准输出包装
+
+所有 HTTP 输出必须通过 `apiContract.haiResultSchema` 包装为 `HaiResult<T>`，与 `@h-ai/core` 的 `ok()/err()` 返回结构一致：
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+const getWidget = apiContract
+  .route({ method: 'GET', path: '/widgets/{id}' })
+  .output(apiContract.haiResultSchema(z.object({
+    id: z.string(),
+    name: z.string(),
+  })))
+
+// 等价于:
+// { success: true, data: { id: string, name: string } }
+// | { success: false, error: HaiError }
+```
+
+### `apiContract.pathOf(procedure)` — 读取业务路径
+
+```typescript
+const refreshPath = apiContract.pathOf(apiContract.iam.auth.refresh)
+// '/auth/refresh'
+```
+
+middleware、client 与 E2E 需要业务路径时从 contract 元数据读取，不维护第二份 route 常量。服务端挂载时再与 `_serv.yml` 的 `http.apiPrefix` 拼接。
+
+### 公共 Schema 工具
+
+| 访问路径 | 说明 |
+| --- | --- |
+| `apiContract.haiResultSchema(dataSchema)` | `HaiResult<T>` 输出包装 |
+| `apiContract.voidResultSchema` | `HaiResult<void>` 空结果包装 |
+| `apiContract.paginatedSchema(itemSchema)` | 分页列表输出 Schema |
+| `HaiErrorSchema` | HaiError 公共字段 Schema |
+| `PaginationQuerySchema` | 分页参数 Schema（可选 page/pageSize，pageSize 上限 100；默认值由服务端处理） |
+
+## Contract 定义规范
+
+### 必须遵循
+
+- **输出必须包装为 `apiContract.haiResultSchema`** — 客户端依赖 `success` 判断成功/失败
+- **业务 path 直接写在对应 `*-contract.ts`** — 禁止新增 `*-routes.ts` 或业务路径常量
+- **一次性 `*OutputSchema` 直接内联** — 不在 schemas 文件声明或导出
+- **同一 contract 内重复使用的输出可设私有常量** — 不得为复用扩大公共导出
+- **公共 HTTP 传输配置以配置文件为准** — API 前缀、健康检查、OpenAPI/docs、密钥协商路径与跨端 Header 放在 service 的 `_serv.yml`，不放 contract 包
+- **schemas 只保留真实复用结构** — 至少被多个接口或 contract/procedure 等不同层共同消费
+- **`operationId` 全局唯一** — 格式为 `domain.resource.action`，如 `iam.auth.login`
+- **`tags` 至少包含领域名** — 供 OpenAPI 文档分组
+- **输入 Schema 用 Zod v4** — 与 `@orpc/zod/zod4` 的 `ZodToJsonSchemaConverter` 配套
+- **Contract 不含业务逻辑** — 只有 Schema + 路由元数据，没有 `async function`
+
+### 禁止
+
+- ❌ Contract 文件中 `import` 任何业务模块（`@h-ai/iam`、`@h-ai/storage` 等）
+- ❌ 在 contract 中使用 `z.any()` 或 `z.unknown()` 作为输出类型
+- ❌ 重复定义已存在的领域 contract
+- ❌ 导出只被单个 contract 接口使用的 `*OutputSchema`
+- ❌ 用独立 `*-routes.ts` 维护业务接口路径
+
+### 文件职责
+
+| 文件 | 只负责 |
+| --- | --- |
+| `*-contract.ts` | 业务接口 path、method、输入与输出边界 |
+| `*-schemas.ts` | 跨接口或跨层复用的输入、实体、数据结构 |
+| service `config/_serv.yml` | API 前缀、基础设施端点、跨端 Header 与加密 transport 配置 |
+
+## 常见模式
+
+### 带分页的列表接口
+
+```typescript
+import { apiContract, PaginationQuerySchema } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+const WidgetSchema = z.object({ id: z.string(), name: z.string() })
+
+const listWidgets = apiContract
+  .route({ method: 'GET', path: '/widgets', operationId: 'widget.list', tags: ['widget'] })
+  .input(PaginationQuerySchema.extend({ keyword: z.string().optional() }))
+  .output(apiContract.haiResultSchema(apiContract.paginatedSchema(WidgetSchema)))
+```
+
+### 路径参数
+
+```typescript
+// 路径中的 {id} 对应 input 中的 id 字段
+const getWidget = apiContract
+  .route({ method: 'GET', path: '/widgets/{id}', operationId: 'widget.getById', tags: ['widget'] })
+  .input(z.object({ id: z.string() }))
+  .output(apiContract.haiResultSchema(WidgetSchema))
+```
+
+### 无输入的端点
+
+```typescript
+const versionContract = apiContract
+  .route({ method: 'GET', path: '/system/version', operationId: 'system.version', tags: ['system'] })
+  .output(apiContract.haiResultSchema(z.object({ version: z.string() })))
+```
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/api-contract test
+pnpm --filter @h-ai/api-contract typecheck
+pnpm --filter @h-ai/api-contract lint
+```

package/templates/skills/hai-app-create/SKILL.md

@@ -28,13 +28,13 @@ description: "在 hai 应用中新增、修改或修复功能，按需求复用
 1. 读取 [development.md](development.md)：先按真实需求匹配框架能力、已安装版本与应用架构，再确定改动。适用能力包括同一模块已有 feature、配置和扩展点，不以导入包作为复用完成的证据。
 2. 读取所选模块的 skill 与实际公开类型，复用现有服务和组件。新增依赖或直接使用第三方 SDK 前说明已有能力的具体缺口；无需安装无关模块。
 3. 新增或改变行为时用有意义的目标用例验证，仍适用的回归保持通过；被明确新需求替代的模板断言同步更新并记录依据。按下方参考实现，使用 [hai-app-review](../hai-app-review/SKILL.md) 检查改动涉及的安全与质量边界。
-4. 运行当前项目已定义的门禁，报告行为证据、能力选择及未验证项。纯文案、格式和文档变化按影响验证，不强制新增测试。
+4. 按 [分轮验证与集中修复](../hai-app-tests/validation.md) 运行已有门禁：一轮先收集所有可执行结果，再归并修复、复测失败及受影响项；报告行为证据、能力选择及未验证项。纯文案、格式和文档变化按影响验证，不强制新增测试。
 
 ## 按需参考
 
 新增新手引导或帮助说明时读取 [UI 引导指南](../hai-ui/guide.md)，复用 fullstack 默认的共享 guide-store、locale 和稳定 data-guide 锚点。
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 适用场景
 - 行为开发与验证

package/templates/skills/hai-app-create/development.md

@@ -55,7 +55,7 @@ YAML 使用 `${HAI_DB_TYPE:sqlite}` 等显式引用，冒号后是未配置时
 
 `prod` 是文件模式名，对应 `HAI_CORE_ENV=production`；环境枚举为 `development | test | production | staging`。SvelteKit adapter-node 产物使用 `node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local build/index.js`。文件路径相对进程工作目录，公共文件随项目提交；容器通过部署平台或 `--env-file` 注入目标环境值。浏览器只接收公开白名单，构建产物和镜像不包含 `.env.local`。
 
-Fullstack 的环境文件在工程根；service 脚本通过 `../../.env*` 加载，Web/App/Desktop 的 Vite `envDir` 指向根目录。API workspace 的环境文件在 `apps/<name>-service/`。独立应用在各自根目录加载。浏览器配置在构建期注入时，改环境参数后须重新构建；fullstack 的公开应用元数据由 service `app.info` 返回。
+Fullstack 的环境文件在工程根；service 脚本通过 `../../.env*` 加载，Web/App/Desktop 的 Vite 自动 dotenv 加载关闭（`envDir: false`），开发和预览由 `core.config.loadEnvFiles` 从工程根读取，构建不读取部署环境文件。API workspace 的环境文件在 `apps/<name>-service/`。独立应用在各自根目录加载。静态 Web 通过 `runtime-config.js` 获取公开地址，部署环境覆盖无需重建镜像；原生包在复制静态资源前配置该入口。修改编译进客户端的默认值时仍需重新构建；fullstack 的公开应用元数据由 service `app.info` 返回。
 
 #### 迁移已有项目
 
@@ -125,7 +125,7 @@ hai create my-app
 
 ## 将需求映射到现有能力
 
-应用元信息只有一份配置来源：名称、版本、环境、默认语言与日志设置来自 `_core.yml`，使用 `core.config` 与 `core.logger`；Node 启动时不通过固定 `logging` 覆盖 YAML。SvelteKit 服务端 layout 和 fullstack `app.info` 仅公开必要元信息，不能下发整个 core 或模块配置。独立 Vite mobile-app 在 Node 构建阶段经 core 加载 YAML/环境覆盖并注入公开字段，配置变化需重新构建。环境覆盖使用 `HAI_CORE_NAME`、`HAI_CORE_VERSION`、`HAI_CORE_ENV`、`HAI_CORE_LOGGING_LEVEL` 等既有规则；容器明确配置生产环境，不能用另一个状态来源代替 `core.env`。
+应用元信息只有一份配置来源：名称、版本、环境、默认语言与日志设置来自 `_core.yml`，使用 `core.config` 与 `core.logger`；Node 启动时不通过固定 `logging` 覆盖 YAML。SvelteKit 服务端 layout 和 fullstack `app.info` 仅公开必要元信息，不能下发整个 core 或模块配置。独立 Vite 客户端经 Node/core 加载 YAML 默认值，Web 部署通过 `runtime-config.js` 应用公开白名单覆盖；只修改部署覆盖无需重建，修改构建默认值则须重新构建。环境覆盖使用 `HAI_CORE_NAME`、`HAI_CORE_VERSION`、`HAI_CORE_ENV`、`HAI_CORE_LOGGING_LEVEL` 等既有规则；容器明确配置生产环境，不能用另一个状态来源代替 `core.env`。
 
 开发前，对本次涉及的需求简述“需求 → 现有应用实现/框架能力 → 已安装版本与公开契约依据 → 最小业务补充/修改位置 → 成功、权限与失败验收”。简单任务可用几句话；跨模块任务用表格。查找顺序：已有应用实现 → 框架公开能力和配置 → 最小业务补充。
 
@@ -209,9 +209,9 @@ export function pageOffset(query: PageQuery): number {
 
 ## 验证与交付
 
-所有测试临时工程、镜像、容器、辅助进程、日志、截图与报告须在 finally/teardown 自动清理，成功、失败和取消均执行；只清理本次创建的资源，不提交验收产物。
+测试临时工程、镜像、容器、辅助进程与数据须在 finally/teardown 自动清理，成功、失败和取消均执行；只清理本次创建的资源。日志、截图与报告保留到分析和交付结束再清理，不提交验收产物。
 
 - 对新增/改变行为按 [hai-app-tests](../hai-app-tests/SKILL.md) 写有意义的测试；目标用例先因行为缺失失败，既有回归保持通过。UI/路由改动覆盖真实流程、异步失败与权限路径；纯文案/文档按影响验证。
-- 从当前 `package.json` 选择实际脚本，优先 workspace filter；按 `typecheck → lint → build（构建/配置/跨包变更）→ test → 相关 E2E` 验证，PowerShell 使用 `pnpm.cmd`。不能调用框架仓库私有命令替代应用检查。
+- 从当前 `package.json` 选择实际脚本，优先 workspace filter，PowerShell 使用 `pnpm.cmd`。多项门禁按 [分轮验证与集中修复](../hai-app-tests/validation.md) 先脚本化收集结果和日志，再集中修复、复测失败及受影响项；普通失败不立即从头重跑。不能调用框架仓库私有命令替代应用检查。
 - typecheck/lint 只覆盖部分质量规则；权限、事务、降级、真实 provider、浏览器、容器和原生交付各自需要适用行为证据。缺环境或密钥时报告未验证，不能用 mock 冒充真实集成。
 - 完成说明：实际复用能力与自定义缺口、修改路径、已执行命令/行为结果、同步的 contract/调用方/配置/i18n/文档、未验证项及原因。无需无关模块的“覆盖率”清单。

package/templates/skills/hai-app-create/reference.md

@@ -40,7 +40,7 @@
 ### Step 4：重构与验证（Refactor 阶段）
 
 1. 参照 `hai-app-review` 审查代码规范
-2. 依当前 scripts 顺序执行 `typecheck → lint → build（构建/配置/跨包变更）→ test`，优先 workspace filter，PowerShell 使用 `pnpm.cmd`
+2. 按 [分轮验证与集中修复](../hai-app-tests/validation.md) 收集适用门禁，普通失败不中断独立检查，汇总后集中修复、再验证；优先 workspace filter，PowerShell 使用 `pnpm.cmd`
 3. UI/路由/端到端改动执行相应 E2E；报告失败路径与安全验收结果，未运行的边界说明原因
 
 ## 目录结构约定
@@ -334,13 +334,14 @@ core.init() → crypto.init() → reldb.init() → cache.init() → iam.init()
 
 仅涉及容器构建/部署变更时使用本节；普通功能开发无需每次启动镜像。
 
-- 保持脚手架根目录 `Dockerfile`、`.dockerignore` 与 `package.json` 中 `build` / `compile` 命令与 hai.build.json同步。
+- 保持脚手架 `images/*.Dockerfile`、`.dockerignore` 与 `package.json` 中 `build` / `compile` 命令与 hai.build.json同步。保留 `.gitattributes`，让 `.dockerignore`、Dockerfile 和 POSIX 脚本统一使用 LF，保持跨平台输入一致并确保 Linux 脚本可运行。
 - Podman 多阶段构建保持 `--format docker --jobs=1`；前者保留 `HEALTHCHECK`，后者避免部分 Podman 5.8/Buildah 组合在并行 stage 构建时触发内部 semaphore panic。
-- 先复制 lockfile 与 workspace 配置执行 `pnpm fetch`，再复制源码并离线安装、构建；避免源码变化重复下载依赖，同时兼容新增 workspace。
+- 先复制 lockfile、workspace 配置与构建器准备的 `images/dependencies/` 安装输入执行 `pnpm fetch --ignore-scripts`，再复制源码并离线安装、构建；fetch、安装和 `pnpm pm deploy` 共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，避免重复下载，兼容新增 workspace、本地归档与补丁。
+- 默认容器面向 CPU 运行或远程 AI 服务，Dockerfile 设置 `ONNXRUNTIME_NODE_INSTALL_CUDA=skip`，跳过额外 CUDA/TensorRT 下载；使用宿主机 GPU 时定制镜像和运行参数，不修改本机 npm 或全局 AI/GPU 配置。
 - SvelteKit 服务使用 Node adapter；纯 Vite 前端使用带 SPA fallback 的静态镜像；fullstack 的 Service 与 Web 分别交付，Service 直接监听且不增加转发进程。
 - Web 的 `PUBLIC_*` 部署配置在容器启动时生成静态运行时配置，不作为 build arg 烘焙，确保同一镜像可跨环境部署。
 - 配置文件随镜像提供，并允许只读挂载覆盖；密钥只通过环境变量或 `--env-file` 注入。
-- 普通构建不携带 `data/`；持续写入使用运行期 volume；需要预置数据时显式维护独立 Dockerfile target 和 named build context，不把本机数据加入默认镜像。
+- 普通构建不携带 `data/`；持续写入使用运行期 volume；需要预置数据时显式维护独立 Dockerfile 和明确的 build context，不把本机数据加入默认镜像。
 - 数据库和本地存储的持续写入必须落到 volume，不能依赖镜像可写层。
 - 完成前实际启动镜像，验证健康端点、非 root 用户、环境变量覆盖、配置挂载和预置数据读取。
 

package/templates/skills/hai-app-review/SKILL.md

@@ -72,7 +72,7 @@ typecheck/lint 不能证明越权、租户隔离、事务、错误状态或资
 
 ## 门禁与输出
 
-从当前 package.json 选择实际 scripts，优先 workspace filter；PowerShell 使用 `pnpm.cmd`。按 typecheck → lint → build（构建/配置/跨包变更）→ test → 相关 E2E 执行。浏览器、真实 provider、容器和原生交付各自报告实际结果。
+从当前 package.json 选择实际 scripts，优先 workspace filter；PowerShell 使用 `pnpm.cmd`。按 [分轮验证与集中修复](../hai-app-tests/validation.md) 先收集全部可执行门禁及日志，再归并根因、集中修复、验证失败及受影响项；普通失败不中断独立检查。浏览器、真实 provider、容器和原生交付各自报告实际结果。
 
 交付说明需求/范围、带路径与影响的发现、已复用能力和必要缺口、已修正项、已执行门禁/行为证据、同步的 contract/调用方/i18n/配置/文档，以及未验证项和原因。只读审查报告问题与验证建议；不能凭审查清单宣称所有测试通过。
 

package/templates/skills/hai-app-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-app-tests
-description: "编写或修复 hai 应用的 Vitest/Playwright 测试，验证业务边界和完整用户流程。"
+description: "为 hai 应用编写或修复 Vitest/Playwright 测试，组织分轮验证、汇总失败和集中修复，验证需求与完整用户流程。"
 ---
 
 # hai-app-tests
@@ -9,7 +9,7 @@ description: "编写或修复 hai 应用的 Vitest/Playwright 测试，验证业
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 编写或修复 hai 应用的 Vitest/Playwright 测试，验证业务边界和完整用户流程 |
+| 能力 | 编写或修复 Vitest/Playwright 测试，组织质量门禁与业务流程的分轮验证 |
 | 适用场景 | 需求验收、缺陷回归或应用测试改进 |
 | 输入 | 验收条件、被测公共入口、现有测试和运行环境 |
 | 输出 | 可复现用例及明确区分静态、mock、浏览器/外部服务的结果 |
@@ -22,11 +22,12 @@ description: "编写或修复 hai 应用的 Vitest/Playwright 测试，验证业
 - 按 [development.md](../hai-app-create/development.md) 的真实行为与安全边界选测试；新增/改变业务行为、缺陷修复有目标用例，纯文案/格式/文档及无行为变化的可逆低影响修改不补镜像测试。
 - 不要求每个功能同时新增单元与 E2E；复用已有用例，选择能验证变化的最小适用层，关键跨层用户流程仍需端到端证据。
 - 新用例已通过时先检查是否已有能力；不能为达成 Red 人为破坏旧测试。
+- 执行多项门禁前读取 [分轮验证与集中修复](validation.md)：一轮先脚本化收集所有可执行检查及日志，普通失败不立即改代码；汇总去重后集中修复，再复测失败和受影响项。只有真实前置阻塞才暂停依赖检查；最终必需门禁均须对最终代码有效通过。小范围 TDD Red → Green 保留。
 - 外部服务未运行必须报告；mock/Testcontainers/浏览器/真实付费 Provider 的结果分开表述。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 适用场景
 - 行为验证与 TDD 工作流

package/templates/skills/hai-app-tests/reference.md

@@ -52,7 +52,7 @@
 
 1. 参照 `hai-app-review` 技能审查代码规范
 2. 重构后执行受影响测试与必要回归，确认已有行为保持通过
-3. 从当前 scripts 选择门禁，按 `typecheck → lint → build（构建/配置/跨包变更）→ test → 相关 E2E` 执行；PowerShell 使用 `pnpm.cmd`
+3. 多项门禁按 [分轮验证与集中修复](validation.md) 收集一轮结果，汇总后修复、再验证；不要把目标用例的小范围 TDD 扩大为每修一处就从头运行全量门禁。PowerShell 使用 `pnpm.cmd`
 
 ## 测试目录约定
 
@@ -436,7 +436,7 @@ await expect(page).toHaveURL('/admin/articles')
 
 ## 质量门禁
 
-从当前 package.json 确认实际脚本和 workspace 名称，按变更影响选择；不要为格式/文档改动运行无关 provider 或新增镜像测试。记录执行范围、mock/真实环境、退出结果与未验证原因。
+从当前 package.json 确认实际脚本和 workspace 名称，按 [分轮验证与集中修复](validation.md) 组织以下适用检查；不要为格式/文档改动运行无关 provider 或新增镜像测试。逐轮记录范围、状态/退出码、日志、mock/真实环境与未验证原因，完整日志按需读取。
 
 ```bash
 # 运行单元测试

package/templates/skills/hai-app-tests/validation.md

@@ -0,0 +1,31 @@
+# 分轮验证与集中修复
+
+适用于开发、审查修复、升级后的质量门禁与整体验收。默认执行“收集一轮 → 归并问题 → 集中修复 → 再验证”，不要遇到一个普通失败就修改代码并从头重跑。新增行为的目标用例仍可做小范围 TDD Red → Green；它不要求提前运行整套门禁。
+
+## 1. 确定本轮检查
+
+- 先读当前 `package.json`、任务依赖与环境要求，按影响范围列出命令、工作目录、前置条件和预期证据。优先 workspace filter；用户要求全量验收时保留全量范围。纯文案/文档修改只做适用检查，不新增镜像测试。
+- 一轮默认按 typecheck → lint → build（涉及构建/配置/模板/跨包契约）→ test → 相关 E2E 调度；顺序服从真实依赖。同轮收集不等于同时运行：只有输出目录、端口、数据库、容器与 fixture 均隔离的检查才可并行，共用 `dist`、`.svelte-kit` 或预览产物的构建与测试必须串行。
+- 使用现有任务编排或一个临时调度脚本逐项执行、捕获真实退出码并保存日志。不要用跨检查的 `&&`、全局 fail-fast 或 `|| true` 代替结果收集；脚本内部有前置短路时，确认后续检查是否真正执行，必要时分别调度等价子任务，保留原门禁的最终验收。
+
+## 2. 收集全部可执行结果
+
+- 本轮开始后保持被测源码、配置、依赖和运行环境稳定；协作 agent 也不得边测边改，不运行自动修复。普通类型错误、lint 错误、测试断言失败只记录，继续其余具备前置条件的检查。
+- 只有真实前置失败才阻塞依赖它的检查，例如依赖无法安装、执行器无法启动、上游构建未产生必要产物、必需服务不可用。标明阻塞原因，继续独立检查；确实无法继续收集时才提前结束本轮、集中修复阻塞。不得使用旧构建、旧镜像或旧截图让下游假通过。
+- 为每轮使用独立且被 Git 忽略的日志目录，例如 `tmp/validation/round-01/`。逐项记录命令/范围、源码版本及未提交改动、环境、状态（通过/失败/阻塞/未执行）、退出码、耗时和日志路径；未执行与不适用须说明原因，不能写成通过。超时、取消和环境失败单列，不能当作断言失败或忽略。
+- 调度脚本等子进程退出后再记录结果；重定向或管道不能覆盖实际退出码。所有必需项均有有效通过结果，整轮才算通过；收集到任何失败或阻塞时，汇总必须保留非成功状态。
+- 完整输出写日志，AI 先读汇总及每类失败的有限上下文，再按需定位原始日志；不反复载入整份成功日志、密集轮询或启动尚未结束的同一检查。长任务期间定期简述进度。
+
+## 3. 集中分析与修复
+
+- 本轮可执行检查结束后，把问题按根因去重，记录位置、证据、影响、修复项及关联门禁。上游故障造成的连锁失败合并处理；区分本次引入、原有问题和环境问题。
+- 在已有授权范围内集中修复本次范围的问题，保留仍有效的断言与回归。不能靠删断言、跳过用例、放宽超时或关闭规则换绿灯。环境故障先保存证据、确认恢复条件，再定向重试；不反复重跑到偶然通过。
+- 新发现的独立问题加入同一清单；修复期间的小范围诊断不触发从头全量重跑，也不能替代下一轮必要验收。
+
+## 4. 下一轮与完成条件
+
+- 修复后开启新一轮，先复测失败项、被阻塞项及受改动影响的检查和消费者；按同样方式收集完再修复。有影响范围不明、共享配置/依赖改变或用户要求时，扩大到全量门禁。
+- 只有源码、依赖、配置、工具、环境及所用产物等输入均未改变的已通过项才可复用，并注明来源轮次或缓存；输入变化使相关结果失效。最终所有必需检查必须对最终代码仍有效，缺项不能称为完成。真实部署、Provider、浏览器或原生验收不能只引用静态检查/构建缓存。
+- 保留原有 CI/发布门禁的失败阻断；问题收集时继续运行不代表允许失败提交发布或忽略 required checks。
+- 每轮都在 finally/teardown 停止本轮进程、清理本轮临时工程/容器/镜像/数据；确认退出和资源释放后再运行冲突任务。日志、截图与报告保留到问题分析和交付结束，再按项目约定清理，不覆盖失败证据、不提交验收产物、不删除用户资源。
+- 最终报告各项门禁状态、执行/复用范围、修复结果和未验证原因；mock、容器、真实服务及原生结果分别说明。只陈述实际证据，不以“脚本执行完了”代表验证通过。

package/templates/skills/hai-audit/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: hai-audit
-description: "使用 @h-ai/audit 记录、查询、统计和清理操作审计。"
+description: "接入 @h-ai/audit 记录业务操作，查询分页日志与统计，并按保留期清理。"
 ---
 
-# @h-ai/audit — 审计日志模块
+# hai-audit
 
 ## 能力契约
 
@@ -11,150 +11,25 @@ description: "使用 @h-ai/audit 记录、查询、统计和清理操作审计
 | --- | --- |
 | 能力 | 使用 @h-ai/audit 记录、查询、统计和清理操作审计 |
 | 适用场景 | 业务操作留痕与审计记录检索 |
-| 输入 | AuditConfigInput、已初始化 reldb、审计事件与查询条件 |
+| 输入 | AuditInitConfigInput、已初始化 reldb、审计事件与查询条件 |
 | 输出 | 记录/查询/统计的 HaiResult |
 | 限制 | 仅服务端；审计内容需脱敏，保留期和清理范围由应用策略决定。 |
 
-统一审计日志模块，基于 `@h-ai/reldb` 实现持久化，提供审计日志的记录、分页查询、清理与统计。
+## 使用路径
 
-## 运行环境
+1. 确认已初始化 reldb，校验 `AuditInitConfigInput` 后初始化 audit；每步失败停止后续操作。
+2. 在实际业务成功/失败边界记录事件，明确审计失败如何影响业务，不重复记录同一事件。
+3. 查询使用返回的分页元数据；清理前核对保留期及授权范围。凭证字段会被脱敏，个人信息仍需业务策略。
+4. 检查写入、查询和清理的 HaiResult，先关闭 audit 再关闭数据库。
 
-> ⚠️ **服务端模块（Node.js only）。** 审计日志由服务端自动记录，浏览器端通过 API 端点查询审计数据。
+## 按需参考
 
-## 依赖
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/reldb` | 数据库（审计日志持久化） | **必需** | 需在 `audit.init()` 前初始化 |
-
-## 使用步骤
-
-### 1. 配置
-
-审计模块依赖已初始化的 `@h-ai/reldb` 单例，无需独立配置文件。审计日志固定存储在 `hai_audit_logs` 表中。
-
-### 2. 初始化
-
-```ts
-import { audit } from '@h-ai/audit'
-import { reldb } from '@h-ai/reldb'
-
-// 先初始化依赖
-await reldb.init({ type: 'sqlite', database: './data.db' })
-
-// 再初始化审计模块（自动使用已初始化的 reldb 单例）
-const result = await audit.init()
-if (!result.success) {
-  // 处理错误
-}
-```
-
-自定义用户表映射：
-
-```ts
-await audit.init({
-  userTable: 'hai_iam_users',
-  userIdColumn: 'id',
-  userNameColumn: 'username',
-})
-```
-
-### 3. 关闭
-
-```ts
-const closeResult = await audit.close()
-if (!closeResult.success) {
-  throw new Error(closeResult.error.message)
-}
-```
-
-## 核心 API
-
-### 生命周期
-
-| 方法                  | 签名                                                             | 说明       |
-| --------------------- | ---------------------------------------------------------------- | ---------- |
-| `audit.init`          | `(config: AuditInitConfig) => Promise<HaiResult<void>>` | 初始化模块 |
-| `audit.close`         | `() => Promise<HaiResult<void>>`                                 | 关闭模块   |
-| `audit.isInitialized` | `boolean`                                                        | 初始化状态 |
-
-### 日志操作
-
-| 方法                  | 签名                                                                                | 说明                 |
-| --------------------- | ----------------------------------------------------------------------------------- | -------------------- |
-| `audit.log`           | `(input: CreateAuditLogInput) => Promise<HaiResult<AuditLog>>`             | 记录审计日志         |
-| `audit.list`          | `(options?: ListAuditLogsOptions) => Promise<HaiResult<PaginatedResult<AuditLogWithUser>>>` | 分页查询（items/total/page/pageSize，含用户名；使用返回的规范化元数据，默认 pageSize 20） |
-| `audit.getUserRecent` | `(userId: string, limit?: number) => Promise<HaiResult<AuditLog[]>>`       | 用户最近活动         |
-| `audit.cleanup`       | `(olderThanDays?: number) => Promise<HaiResult<number>>`                   | 清理旧日志           |
-| `audit.getStats`      | `(days?: number) => Promise<HaiResult<AuditStatItem[]>>`                   | 操作统计             |
-
-### 便捷记录器 (`audit.helper`)
-
-| 方法                                                                           | 说明         |
-| ------------------------------------------------------------------------------ | ------------ |
-| `audit.helper.login(userId, ip?, ua?)`                                         | 登录         |
-| `audit.helper.logout(userId, ip?, ua?)`                                        | 登出         |
-| `audit.helper.register(userId, ip?, ua?)`                                      | 注册         |
-| `audit.helper.passwordResetRequest(email, ip?, ua?)`                           | 密码重置请求 |
-| `audit.helper.passwordResetComplete(userId, ip?, ua?)`                         | 密码重置完成 |
-| `audit.helper.crud(input)` | CRUD 操作    |
-
-> `audit.log()` / `audit.helper.*()` 中的 `details` 仅会自动脱敏凭证类字段（如 `password` / `token` / `secret`）；邮箱、手机号默认保留原值。
-
-## 错误码
-
-| 错误码                            | code             | 说明         |
-| --------------------------------- | ---------------- | ------------ |
-| `HaiAuditError.LOG_FAILED`       | `hai:audit:001`  | 记录失败     |
-| `HaiAuditError.QUERY_FAILED`     | `hai:audit:002`  | 查询失败     |
-| `HaiAuditError.CLEANUP_FAILED`   | `hai:audit:003`  | 清理失败     |
-| `HaiAuditError.STATS_FAILED`     | `hai:audit:004`  | 统计失败     |
-| `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005`  | 初始化进行中 |
-| `HaiAuditError.NOT_INITIALIZED`  | `hai:audit:010`  | 模块未初始化 |
-| `HaiAuditError.CONFIG_ERROR`     | `hai:audit:012`  | 配置错误     |
-
-## 常见模式
-
-### 用户认证审计
-
-```ts
-// 登录
-await audit.helper.login(userId, request.ip, request.headers['user-agent'])
-
-// 登出
-await audit.helper.logout(userId, request.ip, request.headers['user-agent'])
-```
-
-### CRUD 操作审计
-
-```ts
-await audit.helper.crud({ userId, action: 'create', resource: 'users', resourceId: newUser.id, details: { name: newUser.name } })
-await audit.helper.crud({ userId, action: 'update', resource: 'roles', resourceId: roleId, details: { changes } })
-await audit.helper.crud({ userId, action: 'delete', resource: 'permissions', resourceId: permId })
-```
-
-### 仪表盘数据
-
-```ts
-// 最近日志
-const recentLogs = await audit.list({ pageSize: 10 })
-
-// 7 天统计
-const stats = await audit.getStats(7)
-```
-
-### 定期清理
-
-```ts
-// 清理 90 天前的日志
-const result = await audit.cleanup(90)
-if (result.success) {
-  logger.info(`Cleaned up ${result.data} old audit logs`)
-}
-```
-
-## 相关 Skills
-
-- `hai-reldb` — 数据库模块（审计模块依赖）
-- `hai-iam` — 身份认证与权限管理（审计的主要记录对象）
-- `hai-core` — 核心工具（日志、ID 生成、i18n）
+- [运行环境](reference.md#运行环境)
+- [依赖](reference.md#依赖)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码](reference.md#错误码)
+- [常见模式](reference.md#常见模式)
+- [相关 Skills](reference.md#相关-skills)