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

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

@@ -0,0 +1,38 @@
+# 分轮验证与集中修复
+
+适用于开发、审查修复、升级后的质量门禁与整体验收。默认执行“收集一轮 → 归并问题 → 集中修复 → 定向回归通过 → 较完整验收”，不要遇到一个普通失败就修改代码并从头重跑。新增行为的目标用例仍可做小范围 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. 集中分析与修复
+
+- 本轮可执行检查结束后，把问题按根因去重，记录位置、证据、影响、修复项及关联门禁。上游故障造成的连锁失败合并处理；区分本次引入、原有问题和环境问题。
+- 在已有授权范围内集中修复本次范围的问题，保留仍有效的断言与回归。不能靠删断言、跳过用例、放宽超时或关闭规则换绿灯。环境故障先保存证据、确认恢复条件，再定向重试；不反复重跑到偶然通过。
+- 下载超时先区分 registry、DNS、代理等网络前提与实际编译/业务错误。复用包管理器的有界重试、可信镜像和缓存，保留总时限与每次结果；只对可安全重复的瞬时网络操作重试，不重试断言或掩盖业务失败。超时/取消后确认本轮进程树及已登记资源回收，再重试或启动冲突任务。
+- 新发现的独立问题加入同一清单；修复期间的小范围诊断不触发从头全量重跑，也不能替代下一轮必要验收。
+
+## 4. 先定向回归，再扩大验收
+
+- 集中修复后，先用最小适用范围验证原失败、已解除的阻塞及直接受影响的消费者；保留必要构建/服务前置。定向回归仍失败时继续归并和修复，只重跑失败及受新改动影响的项，暂不启动较完整门禁。
+- 相关问题均已验证解决后，再按影响扩大到工作区或完整用户流程验收；影响范围不明、共享配置/依赖改变或用户要求全量时，执行全量门禁。扩大验收发现新问题时，仍回到“收集 → 集中修复 → 定向回归通过 → 扩大验收”，不要每改一处就重复整套流程。
+- 只有源码、依赖、配置、工具、环境及所用产物等输入均未改变的已通过项才可复用，并注明来源轮次或缓存；输入变化使相关结果失效。最终所有必需检查必须对最终代码仍有效，缺项不能称为完成。真实部署、Provider、浏览器或原生验收不能只引用静态检查/构建缓存。
+- 保留原有 CI/发布门禁的失败阻断；问题收集时继续运行不代表允许失败提交发布或忽略 required checks。
+- 每轮都在 finally/teardown 停止本轮进程、清理本轮临时工程/容器/镜像/数据；确认退出和资源释放后再运行冲突任务。日志、截图与报告保留到问题分析和交付结束，再按项目约定清理，不覆盖失败证据、不提交验收产物、不删除用户资源。
+- 部署夹具先检查固定公开基础镜像，仅确认缺失才拉取；成功 create 先登记完整 ID，再在私有 PID namespace 内异步准备 APT/pip/sshd。所有准备 exec 转交同一取消信号，等待本地客户端 close 后按该 ID 停止全树并核验消失。总准备 deadline 早于 hook 并预留回收预算；公共缓存不删，私有 tag 回收前复核内容 ID/owner。未取得可信 create 回执或测试进程被强制终止时记录未知，不能按名称或 label 认领资源。
+- 浏览器执行器默认将每轮、每组的证据分别放入忽略的 `test-results/run-*/group-*`；只清理本轮临时数据库/上传数据。显式 `HAI_AUTH_EVIDENCE_DIR`、`--output` 和 Playwright HTML 输出目录会保留，取消也不删除已有报告。不要复制私有环境、密钥或业务数据库到证据目录。
+- 经托管 `test:e2e` 入口为服务子进程提供绝对 `HAI_E2E_DATA_ROOT` 和显式测试后端，隔离继承的 `HAI_*` / `PUBLIC_*` / `VITE_*` 与用户 `.env.local`。仅本轮测试启用 `HAI_E2E=1`；普通开发与生产的 dotenv 加载、共享后端守卫不放宽。启用 transport 的验收使用本轮可信 ring 和 registry，不能关闭加密掩盖客户端契约问题。
+- 最终报告各项门禁状态、执行/复用范围、修复结果和未验证原因；mock、容器、真实服务及原生结果分别说明。只陈述实际证据，不以“脚本执行完了”代表验证通过。
+
+公开 API 变更需验证 package.exports 实际入口与配套声明，核对根/子路径真实导入和浏览器打包；不使用 src/dist 深层导入绕过缺失公开产物。Svelte 默认组件、明确 selective/type-only 导出与 client/server 分隔按实际契约验收，不把内部 Provider/Deps 扩成公共 API。

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

@@ -1,160 +1,37 @@
 ---
 name: hai-audit
-description: "使用 @h-ai/audit 记录、查询、统计和清理操作审计。"
+description: "接入 @h-ai/audit 记录业务操作，查询分页日志与统计，并按保留期清理。"
 ---
 
-# @h-ai/audit — 审计日志模块
+# hai-audit
 
 ## 能力契约
 
-| 项目 | 契约 |
-| --- | --- |
-| 能力 | 使用 @h-ai/audit 记录、查询、统计和清理操作审计 |
-| 适用场景 | 业务操作留痕与审计记录检索 |
-| 输入 | AuditConfigInput、已初始化 reldb、审计事件与查询条件 |
-| 输出 | 记录/查询/统计的 HaiResult |
-| 限制 | 仅服务端；审计内容需脱敏，保留期和清理范围由应用策略决定。 |
+| 项目     | 契约                                                       |
+| -------- | ---------------------------------------------------------- |
+| 能力     | 使用 @h-ai/audit 记录、查询、统计和清理操作审计            |
+| 适用场景 | 业务操作留痕与审计记录检索                                 |
+| 输入     | AuditInitConfigInput、已初始化 reldb、审计事件与查询条件   |
+| 输出     | 记录/查询/统计的 HaiResult                                 |
+| 限制     | 仅服务端；审计内容需脱敏，保留期和清理范围由应用策略决定。 |
 
-统一审计日志模块，基于 `@h-ai/reldb` 实现持久化，提供审计日志的记录、分页查询、清理与统计。
+## 使用路径
 
-## 运行环境
+1. 确认已初始化 reldb，校验 `AuditInitConfigInput` 后初始化 audit；init 等待DDL就绪才成功，失败保持未初始化；每步失败停止后续操作。
+2. 在实际业务成功/失败边界记录事件，明确审计失败如何影响业务，不重复记录同一事件。
+3. 查询使用返回的分页元数据；清理前核对保留期及授权范围。凭证字段会被脱敏，个人信息仍需业务策略。
+4. 检查写入、查询和清理的 HaiResult，先关闭 audit 再关闭数据库。
 
-> ⚠️ **服务端模块（Node.js only）。** 审计日志由服务端自动记录，浏览器端通过 API 端点查询审计数据。
+常见事件使用 `audit.helper` 与公开 `AuditHelper` 类型；内部记录器装配工厂不从包入口导出。
 
-## 依赖
+## 按需参考
 
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@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)

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

@@ -0,0 +1,148 @@
+# hai-audit 参考
+
+统一审计日志模块，基于 `@h-ai/reldb` 实现持久化，提供审计日志的记录、分页查询、清理与统计。
+
+
+`audit.init()` 会等待自动建表和仓库就绪才返回成功；DDL 失败保持 `isInitialized=false`，修正数据库后可重试。自定义 JOIN、统计和清理也使用同一就绪屏障；初始化期间关闭会使迟到结果失效。先检查 init 的 HaiResult，再立即记录或查询；audit 不拥有共享 RelDB 的连接，关闭 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?: AuditInitConfigInput) => 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）

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

@@ -1,6 +1,6 @@
 ---
 name: hai-build
-description: "定位 hai 应用架构、模块依赖、初始化顺序、构建模式和对应技能。"
+description: "构建或排查 hai 应用的源码、容器镜像和桌面产物；识别工程架构、依赖与对应构建入口。"
 ---
 
 # hai-build
@@ -22,25 +22,31 @@ description: "定位 hai 应用架构、模块依赖、初始化顺序、构建
 - 功能开发先用 [development.md](../hai-app-create/development.md) 把需求匹配到当前版本的框架能力与配置；再读取所选模块 skill 和公开类型。
 - 有生命周期的模块按真实依赖初始化、检查结果并反序清理；core、纯函数和工厂不套用相同生命周期。
 - 构建任务检查当前 engines、适配器、缓存与目标产物，不能照搬框架仓库私有构建命令。
+- 多项门禁按 [分轮验证与集中修复](../hai-app-tests/validation.md) 先收集结果再集中修复；遵守产物依赖与资源隔离，不并行清理/重建同一输出目录，不用旧产物补成通过。
 
 ## 构建与部署
 
-- `pnpm build` 默认仅编译源码（调用 compile）；`pnpm build --target docker` 根据 hai.build.json 构建并导出 app/可选 web 镜像，auto 优先可达 Podman、其次 Docker，可用 --runtime 显式指定。
-- compile 交付源码编译结果，docker 交付镜像归档，desktop 交付 Tauri 系统安装包；每次只选一种。images[].target 是 Dockerfile 阶段名，fullstack 的 app 使用 runtime、web 使用 web，不能与 CLI target 混用；参数默认值和示例必须与真实入口同步。
+- 创建默认包含开发期部署工具，可用 --no-deploy 关闭。每个镜像使用 images/ 中独立 Dockerfile，Web 配置位于 images/web/，不使用镜像阶段 target 配置。
+- 构建器生成 images/dependencies/ 安装输入；fetch、安装和生产依赖整理共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，并复用依赖层。file: 归档、补丁、workspace 元数据必须进入下载上下文；原生依赖缓存按系统/架构/ABI 区分。基础镜像、中间件及工具指定版本，禁止 latest。
+- 默认容器面向 CPU 运行或远程 AI 服务，Dockerfile 设置 `ONNXRUNTIME_NODE_INSTALL_CUDA=skip`，跳过额外 CUDA/TensorRT 下载；使用宿主机 GPU 时定制镜像和运行参数，不修改本机 npm 或全局 AI/GPU 配置。
+- pnpm run deploy --build 显式串联构建、打包和发布；--bundle-only 只交付完整离线包与跨平台脚本；--services 以服务器成功状态为基线只更新选中服务。完整包自动包含自建中间件镜像，服务器禁止联网拉取。
+- `pnpm build` 默认仅编译源码（调用 compile）；`pnpm build --target docker` 根据 hai.build.json 的 dockerfile 构建并导出 app/可选 web 镜像，可用 --images web 只构建前端，auto 优先可达 Podman、其次 Docker，可用 --runtime 显式指定。
+- compile 交付源码编译结果，docker 交付镜像归档，desktop 交付 Tauri 系统安装包；每次只选一种。images[].dockerfile 指向独立镜像文件，最终阶段作为交付镜像；参数默认值和示例必须与真实入口同步。
 - Podman 的客户端代理通过预定义构建参数传递，覆盖 Windows/macOS 远程引擎的服务端默认值；代理地址必须能从构建容器访问，--no-http-proxy 禁止此传递。不要把代理写成 Dockerfile ENV 或固化进交付镜像。
 - --network 默认沿用引擎网络；只有实际构建网络无法访问依赖/代理时才显式选择网络，pasta 仅适用于 rootless Podman。build 与 run 的主机名解析可能不同，须验证构建网络中的可达性，不默认改成 host 网络。
-- 从运行 build 的应用根 package.json.version 读取版本，不能使用 CLI/框架版本或服务子包版本代替。清单格式 version=2，appVersion 为应用版本；镜像 tar 名含版本、buildId 区分同版本构建，Tauri 也接收根版本。不要手改清单或保留无版本的交付归档。
-- 构建不区分 dev/test/prod，不加载部署环境覆盖，不注入运行期凭据；完整镜像清单含 SHA-256，全部成功才发布 latest。不要让 compile、Dockerfile 或 Tauri beforeBuildCommand 递归调用自身的原生/镜像构建。
+- 从运行 build 的应用根 package.json.version 读取版本，不能使用 CLI/框架版本或服务子包版本代替。清单格式 version=3，appVersion 为应用版本；appContainerPort/webContainerPort 仅记录 images 配置显式填写的端口，部分构建也保留未选镜像端口，未填写时沿用部署默认值。镜像 tar 名含版本、buildId 区分同版本构建，Tauri 也接收根版本。不要手改清单或保留无版本的交付归档。
+- 构建不区分 dev/test/prod，不加载部署环境覆盖，不注入运行期凭据；所选镜像清单含 SHA-256，全部成功才更新本机最近构建指针（不是镜像标签）。不要让 compile、Dockerfile 或 Tauri beforeBuildCommand 递归调用自身的原生/镜像构建。
 - Vite 的 envDir 与 SvelteKit 的 kit.env.dir 是独立加载入口，必须同时阻止构建阶段读取工程根的 .env 文件；开发/预览由 core loader 注入，运行期由 deploy 注入。用临时 .env.local 哨兵值检查输出，避免只过滤进程变量却仍把私有文件固化进产物。
 - 静态客户端通过 runtime-config.js 或原生宿主初始化脚本获取公开地址与元数据；仅投影公开白名单，禁止将完整 process.env、服务配置或密钥序列化到浏览器。预览与容器启动均须验证真实登录，不能依赖构建期 API 地址让 E2E 通过。
+- Fullstack Capacitor App 在 `public/runtime-config.js` 提供公开 API 地址，再编译并同步原生资源；Tauri 从启动进程的 PUBLIC_API_BASE 注入。不能把开发代理的 .env 配置当作已安装原生包的运行配置。
 - `pnpm build --target desktop --platform windows|linux|macos --arch x64|arm64` 调用对应工程的 Tauri build。要求在目标系统准备 Rust target、SDK 和打包工具，不假定跨系统编译。原生安装包必须按目标系统实测。
-- deploy 只消费已有产物，详见 [hai-deploy](../hai-deploy/SKILL.md)。网络不通时 --bundle-only 生成 tar，按说明手工搬运；packaged 不代表部署已运行。
-- 测试临时工程、镜像、容器、辅助进程、日志、截图和报告必须在 finally/teardown 自动清理，失败/取消也清理；不得提交测试产物或删除用户既有资源。
+- deploy 默认消费已有产物，--build 显式先构建，详见 [hai-deploy](../hai-deploy/SKILL.md)。网络不通时 --bundle-only 生成 tar，按说明手工搬运；packaged 不代表部署已运行。
+- 测试临时工程、镜像、容器、辅助进程和数据必须在 finally/teardown 自动清理，失败/取消也清理；日志、截图和报告保留到分析和交付结束再清理，不得提交测试产物或删除用户既有资源。
 - 浏览器测试的数据放入本轮独立临时目录；Windows 等子进程与服务退出后再删除数据库和上传文件，不依赖下一轮测试补清理。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 适用场景
 - 项目架构

package/templates/skills/hai-build/reference.md

@@ -42,7 +42,7 @@
 | 公共 API | oRPC contract + Hono + typed client |
 | 认证     | Bearer access token + httpOnly refresh cookie（浏览器推荐） |
 
-pnpm 专属配置放在 `pnpm-workspace.yaml`，`.npmrc` 仅用于注册表与认证。Docker 缓存层使用 `pnpm fetch` 读取锁文件；pnpm 12 的该命令不支持 `--frozen-lockfile`。后续仍通过 `pnpm install --offline --frozen-lockfile` 校验清单与锁文件一致。容器裁剪用 `pnpm pm deploy --filter <服务包> --prod <目标目录>`，确保执行内置命令，避免项目同名 `deploy` 脚本覆盖它。
+pnpm 专属配置放在 `pnpm-workspace.yaml`，`.npmrc` 仅用于注册表与认证。Docker 缓存层使用 `pnpm fetch` 读取锁文件；pnpm 12 的该命令不支持 `--frozen-lockfile`。后续仍通过 `pnpm install --offline --frozen-lockfile` 校验清单与锁文件一致。容器裁剪用 `pnpm pm deploy --filter <服务包> --prod <目标目录>`，确保执行内置命令，避免项目同名 `deploy` 脚本覆盖它。保留 `.gitattributes`，让 `.dockerignore`、Dockerfile 和 POSIX 脚本统一使用 LF，保持跨平台输入一致并确保 Linux 脚本可运行。
 
 ### SvelteKit Adapter 模式
 
@@ -150,13 +150,15 @@ const db = await reldb.init(dbConfig.data)
 if (!db.success) return db
 const cached = await cache.init(cacheConfig.data)
 if (!cached.success) {
-  await reldb.close()
-  return cached
+  const cleanup = await reldb.close()
+  return cleanup.success ? cached : cleanup
 }
 const identity = await iam.init(iamConfig.data)
 if (!identity.success) {
-  await cache.close()
-  await reldb.close()
+  const cacheCleanup = await cache.close()
+  const dbCleanup = await reldb.close()
+  if (!cacheCleanup.success) return cacheCleanup
+  if (!dbCleanup.success) return dbCleanup
   return identity
 }
 // 应用结束时 await iam.close()、cache.close()、reldb.close()；
@@ -277,12 +279,15 @@ pnpm --filter <app-name> test:e2e
 pnpm --filter <app-name> test
 pnpm --filter <app-name> test:e2e
 
-# Refactor：质量门禁
+# Refactor：按下方分轮验证流程收集适用门禁
 pnpm typecheck
 pnpm lint
+pnpm build # 构建/配置/模板/跨包契约变更
 pnpm test
 ```
 
+以上命令按 [分轮验证与集中修复](../hai-app-tests/validation.md) 调度，不在普通失败时立即修改并从头重跑。
+
 ## 统一编码规范
 
 ### 强制规则
@@ -311,7 +316,7 @@ return kit.response.ok(result.data)
 
 ### 质量门禁
 
-按当前项目已定义的 scripts 和变更影响执行；PowerShell 使用 `pnpm.cmd`：
+按当前项目已定义的 scripts 和变更影响选择检查，执行 [分轮验证与集中修复](../hai-app-tests/validation.md)：普通失败先记录，独立检查继续，汇总后集中修复。PowerShell 使用 `pnpm.cmd`：
 
 ```bash
 pnpm typecheck    # TypeScript 类型检查
@@ -338,11 +343,9 @@ pnpm test         # Vitest 单元测试
 
 ### 变更后：验证
 
-1. `pnpm typecheck` 通过
-2. `pnpm lint` 通过
-3. 构建/配置/跨包变更 `pnpm build` 通过
-4. `pnpm test` 通过（单元测试）
-5. UI/路由/端到端改动执行相应 `test:e2e`；从 package.json 确认入口
-6. 搜索确认所有引用点已更新，报告未验证边界
+1. 按影响范围调度一轮 typecheck/lint/build/test；UI/路由/端到端改动加相应 E2E，从 package.json 确认入口
+2. 记录全部可执行结果与日志；真实前置失败只阻塞依赖项，普通失败不边测边改
+3. 归并问题并集中修复，再验证失败、阻塞及受影响项；最终必需门禁对最终代码有效通过
+4. 搜索确认所有引用点已更新，报告未验证边界与结果来源
 
 涉及原生交付时按当前项目 Tauri/Gradle/Xcode 等实际入口打包，在目标 OS/设备验证安装启动、会话、安全 TokenStorage、API 域名及覆盖升级。Web 构建/E2E 不代替原生验收；记录平台/工具链与结果，缺平台写未验证。