@h-ai/cli 0.1.0-alpha.56 → 0.1.0-alpha.58

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

@@ -2,18 +2,20 @@
 
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
-> 面向 AI 助手的 TDD 测试指南。**测试先行**：先写测试定义行为，再写实现让测试通过。涵盖 Vitest 单元测试与 Playwright E2E 测试。
+新增/改变业务行为或修复缺陷时先用目标用例定义行为，再实现。按 [development.md](../hai-app-create/development.md) 的需求与安全边界选择测试层；纯文案、格式、文档或无行为变化的可逆低影响修改按影响验证，不补只匹配文本/结构的镜像测试。
 
 ## 适用场景
 
 - 以 TDD 方式开发新功能（先写测试 → 确认失败 → 再实现 → 确认通过）
-- 为 `$lib/server/services/` 编写服务层单元测试
+- 为当前架构的公共服务入口编写单元/集成测试
 - 为 API 端点编写 E2E 测试（Playwright）
 - 为页面交互编写 UI E2E 测试（Playwright）
 - 为工具函数、Schema 校验编写单元测试
-- 需要提升测试覆盖率
+- 补齐有具体行为风险的验证缺口；覆盖率是定位线索，不是验收目标
 
-## TDD 核心工作流（必须严格遵循）
+## 行为验证与 TDD 工作流
+
+不要求每个改动同时新增单元与 E2E。先复用现有 fixture 与目标用例，按变化选最小适用层；跨 contract/服务/客户端或 UI 的关键流程仍需相应集成/端到端验证。
 
 ### 阶段一：需求分析（Red 前准备）
 
@@ -21,16 +23,17 @@
 2. **拆分测试点**：将需求转化为可验证的测试用例清单
 3. **确定测试类型**：
    - **单元测试（Vitest）**：服务层、工具函数、Schema 校验、HaiResult 处理
-   - **E2E 测试（Playwright）**：API 端点、页面交互、认证流程、跨模块集成
+   - **集成测试**：contract/procedure、事务、持久化、生命周期/失败清理、模块配置的真实组合
+   - **E2E 测试（Playwright）**：API 边界、页面交互、认证流程与跨层用户路径
 
 ### 阶段二：Red — 编写失败的测试
 
-1. **编写单元测试**：覆盖正常路径、边界路径、权限路径、错误路径
-2. **编写 E2E 测试**：覆盖 API 端点和关键用户交互流程
+1. **编写目标用例**：在适用的单元/集成/E2E 层验证目标变化，不重复创建其它层仅为打勾
+2. 对本次相关的正常、输入边界、越权/跨租户、依赖失败、事务/幂等/清理场景给出可观察断言；纯工具无需添加无关权限路径
 3. **运行测试确认新增目标用例因预期行为缺失而失败（既有回归保持通过）**：
    ```bash
-   pnpm --filter <app-name> test        # 单元测试 — 新增目标用例应 FAIL，既有回归应 PASS
-   pnpm --filter <app-name> test:e2e    # E2E 测试 — 新增目标用例应 FAIL，既有回归应 PASS
+   pnpm --filter <app-name> test        # 目标位于单元/集成时使用
+   pnpm --filter <app-name> test:e2e    # 目标位于 E2E 时使用；脚本以实际 package.json 为准
    ```
 4. 新增用例若已通过，先确认现有实现是否已满足需求；仅在用例没有覆盖目标行为时修正
 
@@ -39,7 +42,7 @@
 1. 参照 `hai-app-create` 技能编写实现代码
 2. 每实现一个功能点，立即运行对应测试确认通过
 3. 只写让测试通过的最小代码，不做过度设计
-4. 运行全部测试确认通过：
+4. 运行受影响测试及必要回归确认通过（按影响选择范围）：
    ```bash
    pnpm --filter <app-name> test        # 单元测试 — 应全部 PASS
    pnpm --filter <app-name> test:e2e    # E2E 测试 — 应全部 PASS
@@ -48,11 +51,13 @@
 ### 阶段四：Refactor — 重构优化
 
 1. 参照 `hai-app-review` 技能审查代码规范
-2. 重构后再次运行所有测试确认仍然通过
-3. 运行质量门禁：`pnpm typecheck && pnpm lint && pnpm test`
+2. 重构后执行受影响测试与必要回归，确认已有行为保持通过
+3. 从当前 scripts 选择门禁，按 `typecheck → lint → build（构建/配置/跨包变更）→ test → 相关 E2E` 执行；PowerShell 使用 `pnpm.cmd`
 
 ## 测试目录约定
 
+以下是常见组织方式；沿当前应用/workspace 的测试目录、alias 与脚本，不为目录一致性移动已有测试。
+
 ```
 tests/                             # 单元测试（Vitest）
   services/
@@ -73,27 +78,27 @@ e2e/                               # E2E 测试（Playwright）
 
 ## 核心规则
 
-1. **测试先行**：先写测试定义预期行为，再写实现代码。
+1. **行为测试先行**：新增/改变业务行为和修复缺陷时先定义目标用例；纯文案/格式/文档按影响验证。
 2. **统一入口**：通过框架模块公共 API 测试（`reldb.sql`、`iam.auth`），不直接调用内部实现。
 3. **从实际场景出发**：测试用例验证真实业务行为，不做形式覆盖。
 4. **先审查后修复**：测试不通过时先审查业务逻辑是否有问题，不直接修改测试迎合通过。
-5. **Mock 外部依赖**：单元测试中，数据库、缓存、网络请求使用 mock，不直连真实服务。
-6. **E2E 真实环境**：E2E 测试运行在完整应用环境中，不使用 mock。
+5. **明确隔离层**：单元测试沿真实注入边界 mock 外部依赖；DB/缓存集成用内存 SQLite 或隔离环境/Testcontainers，不能用 mock 证明真实持久化/事务。
+6. **区分证据**：端到端运行完整应用；可用受控外部依赖验证确定性错误路径，但报告替身范围。浏览器通过不等于真实 provider 通过；真实数据库/付费 provider/原生平台各自保留实际执行结果，缺环境说明未验证。
 
 ## 覆盖范围
 
-每个功能至少覆盖以下路径（单元测试 + E2E 按需）：
+按本次改变的行为选择适用路径；下表是设计依据，不要求每个路径在单元与 E2E 重复一遍。纯函数不必虚构权限场景，受保护资源则不能省掉未登录/缺权限与跨用户/租户验收：
 
 | 路径     | 说明                     | 单元测试示例       | E2E 测试示例            |
 | -------- | ------------------------ | ------------------ | ----------------------- |
 | 正常路径 | 核心功能可用             | 创建用户成功       | POST /api/users → 201   |
 | 边界路径 | 非法输入、空值、格式错误 | 空名称、超长字符串 | 空表单提交 → 校验提示   |
-| 权限路径 | 未认证、无权限           | 未登录调用服务     | 未登录访问 → 401/重定向 |
+| 权限路径 | 未认证、无权限           | 未登录调用服务     | 检查真实失败包络/HTTP 状态，kit 页面按实际策略重定向 |
 | 错误路径 | 服务异常、数据库错误     | DB 失败时的 HaiResult | 服务不可用 → 错误提示页 |
 
 ## 单元测试（Vitest）
 
-### 服务层测试模板
+### SQLite 持久化集成示例
 
 ```typescript
 import { reldb } from '@h-ai/reldb'
@@ -109,7 +114,10 @@ beforeAll(async () => {
   })
   expect(table.success).toBe(true)
 })
-afterAll(async () => { await reldb.close() })
+afterAll(async () => {
+  const closed = await reldb.close()
+  expect(closed.success).toBe(true)
+})
 
 describe('article persistence', () => {
   it('creates and reads the stored article', async () => {
@@ -123,7 +131,7 @@ describe('article persistence', () => {
 })
 ```
 
-服务层另测权限、校验和 DB 失败透传；mock 必须沿真实注入边界或 CRUD 仓库实例配置，create 返回 ExecuteResult，不能伪造为实体。
+本例验证框架真实持久化，不代替应用服务验收。应用另测相关权限、校验和 DB 失败透传；mock 必须沿真实注入边界或 CRUD 仓库实例配置，create 返回 ExecuteResult，不能伪造为实体。
 
 ### Schema 校验测试模板
 
@@ -166,7 +174,7 @@ describe('CreateUserSchema', () => {
 
 ### Playwright 配置
 
-项目中应有 `playwright.config.ts`（由 CLI 生成）：
+优先复用 CLI 已生成的 `playwright.config.ts`。下列为 SvelteKit preview 示例；API/fullstack/Vite 使用自身已有 webServer/服务组合与 scripts，不照搬 `pnpm preview`：
 
 ```typescript
 // playwright.config.ts
@@ -226,6 +234,8 @@ export default defineConfig({
 
 ### E2E 工具函数模板
 
+以下登录路径、表单字段与 API 仅作 SvelteKit 示例，必须替换为当前应用路由/认证流程；API service/typed client 测试从现有 contract 读取路径，不维护第二份路由常量。
+
 ```typescript
 // e2e/helpers.ts
 import type { APIRequestContext, Page } from '@playwright/test'
@@ -277,6 +287,8 @@ export async function registerAndLogin(
 
 ### API 端点 E2E 测试模板
 
+下例是返回 kit Response 的 SvelteKit 端点。serv/oRPC 普通 procedure 可能以 HTTP 200 返回失败 HaiResult，需同时检查 `success/error.code`；不能把 `error.httpStatus` 当作 response.status，也不能统一套用下列 401/201 断言。输入校验与传输错误另按实际状态测试。
+
 ```typescript
 // e2e/articles-api.spec.ts
 import { expect, test } from '@playwright/test'
@@ -359,6 +371,8 @@ test.describe('Articles Page', () => {
 
 ## TDD 用例设计策略
 
+以下展示候选验证点，实际按职责和已有用例选择；不要求将同一输入规则在所有层重复实现和测试。
+
 ### 从需求到测试用例的转换
 
 ```
@@ -367,9 +381,9 @@ test.describe('Articles Page', () => {
 ↓ 拆分测试点
 
 单元测试（Vitest）：
-  ✅ 创建文章成功返回 HaiResult.ok
-  ✅ 空标题返回 HaiResult.err + VALIDATION_FAILED
-  ✅ 超长标题（>100 字符）返回 HaiResult.err
+  ✅ 创建文章成功返回 ok(data)
+  ✅ 空标题被当前边界 Schema 拒绝
+  ✅ 超长标题（>100 字符）被拒绝
   ✅ DB 异常时透传错误
 
 Schema 测试（Vitest）：
@@ -388,10 +402,11 @@ E2E 测试（Playwright）：
 
 ## 断言规范
 
-- 始终校验 `result.success`
+- HaiResult 型 API 校验 `result.success`；其它返回、显式抛错与流式 API 按实际签名验证
 - 失败时校验 `error.code`（不只检查 `success === false`）
 - 使用类型缩窄后访问 data 或 error
-- E2E 断言使用 Playwright 内置 expect 匹配器
+- E2E 断言使用 Playwright 内置 expect 匹配器；同时检查用户可见结果和必要持久化状态，不能只断言 HTTP 200、按钮点击或成功提示
+- 失败验收检查错误码/状态与“没有副作用”；事务中途失败、重复回调/写入、取消/关闭等按需求检查一致性与资源退出
 
 ```typescript
 // ✅ 单元测试断言
@@ -421,6 +436,8 @@ await expect(page).toHaveURL('/admin/articles')
 
 ## 质量门禁
 
+从当前 package.json 确认实际脚本和 workspace 名称，按变更影响选择；不要为格式/文档改动运行无关 provider 或新增镜像测试。记录执行范围、mock/真实环境、退出结果与未验证原因。
+
 ```bash
 # 运行单元测试
 pnpm --filter <app-name> test
@@ -432,7 +449,10 @@ pnpm --filter <app-name> test:e2e
 pnpm --filter <app-name> test:coverage
 
 # 全量门禁
-pnpm typecheck && pnpm lint && pnpm test
+pnpm typecheck
+pnpm lint
+pnpm build # 构建/配置/跨包变更
+pnpm test
 ```
 
 ## 相关 Skills

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

@@ -17,9 +17,10 @@ description: "定位 hai 应用架构、模块依赖、初始化顺序、构建
 
 ## 使用路径
 
-- 先读当前 package.json 和 README，识别 SvelteKit / API workspace / Vite SPA / 原生 App，按实际 scripts 验证。
-- core → reldb/cache 等基础依赖 → iam/ai 等业务模块；逐步检查初始化，失败清理已创建资源。
-- Node 最低版本、Turbo 缓存 env/globalDependencies、build:clean 与框架构建模板保持同步。
+- 先读当前 package.json、lockfile 与 README，识别 SvelteKit / API workspace / fullstack / Vite SPA / 原生 App，按实际 scripts 验证。
+- 功能开发先用 [development.md](../hai-app-create/development.md) 把需求匹配到当前版本的框架能力与配置；再读取所选模块 skill 和公开类型。
+- 有生命周期的模块按真实依赖初始化、检查结果并反序清理；core、纯函数和工厂不套用相同生命周期。
+- 构建任务检查当前 engines、适配器、环境变量、缓存与目标产物，不能照搬框架仓库私有构建命令。
 
 ## 按需参考
 
@@ -28,6 +29,6 @@ description: "定位 hai 应用架构、模块依赖、初始化顺序、构建
 - 适用场景
 - 项目架构
 - 技能导航
-- TDD 开发工作流（强制）
+- 行为开发工作流
 - 统一编码规范
 - 标准工作流

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

@@ -2,13 +2,9 @@
 
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
-框架开发、CLI、服务端最低 Node.js 版本统一为 22.12.0；包与脚手架 engines、共享 node22 编译目标和 CI 最低版本必须同步。不再按 Node 20 编写兼容分支。
+应用 Node/工具链要求以当前 `package.json.engines`、lockfile 与 CI 为准。使用 Turbo 时核对影响产物的环境变量、共享配置和模式切换清理策略，并验证实际产物；不要假定应用使用框架仓库的 tsup/Turbo 私有脚本。
 
-tsup 包的 Turbo `build` 依赖不缓存的 `build:clean`（仅清本包 dist），再执行构建或恢复缓存。不要移除此步骤：Turbo 缓存恢复不会自动移除另一模式的多余文件。
-
-使用 Turbo 时，影响构建的环境变量必须进入任务 `env`，共享构建配置进入 `globalDependencies`。框架的 `HAI_DOCKER_PROD_BUILD=true` 关闭声明和 sourcemap，应与普通构建使用不同缓存；PUBLIC/VITE/TAURI 变量同样参与构建缓存。切换后验证实际产物并恢复普通开发构建。
-
-> 本技能是 hai-framework 应用开发的起点。帮助理解项目结构、定位正确的技能、并遵循 **TDD 驱动的标准工作流**。支持 SSR Web、SPA、Android/iOS 原生 App 等多端构建。
+本技能帮助识别应用架构、依赖和技能。日常开发决策、安全边界与能力选择见 [development.md](../hai-app-create/development.md)。
 
 ## 适用场景
 
@@ -20,26 +16,41 @@ tsup 包的 Turbo `build` 依赖不缓存的 `build:clean`（仅清本包 dist
 
 ## 项目架构
 
+### 先辨别当前项目
+
+| 架构 | 接口/服务 | UI 与客户端 | 常见位置（以当前项目为准） |
+| --- | --- | --- | --- |
+| SvelteKit | `@h-ai/kit`、文件路由与 server services | Svelte 组件与既有数据加载 | `src/routes/`、`src/lib/server/` |
+| API workspace | `@h-ai/api-contract` + `@h-ai/serv` | 无需页面 | `apps/*-contract`、`apps/*-service` |
+| fullstack | contract + serv，共享业务结构 | Vite Svelte Web/所选原生前端，typed client | `packages/*-contract`、`packages/*-serv`、`packages/*-shared`、`apps/*` |
+| Vite SPA/原生 | 远端服务 contract | `@h-ai/api-client` 与适用平台适配 | `src/App.svelte`、`src/lib/api.ts` 或 shared 客户端 |
+
+不要从目录名称推断运行环境；沿入口、导入与 scripts 核实。下列 SvelteKit 示例只适用于对应项目。
+
 ### 技术栈
 
 | 层次     | 技术                           |
 | -------- | ------------------------------ |
-| 框架     | SvelteKit 2 + Svelte 5 (Runes) |
+| UI     | Svelte 5 (Runes)；SvelteKit 或 Vite 以项目为准 |
 | 样式     | TailwindCSS 4 + DaisyUI 5      |
-| 语言     | TypeScript 5.7+ (strict)       |
+| 语言     | TypeScript 6 / 7 (strict)       |
 | 构建     | Vite + tsup                    |
-| 包管理   | pnpm                           |
+| 包管理   | pnpm 12                        |
 | 单元测试 | Vitest                         |
 | E2E 测试 | Playwright                     |
-| 原生 App | Capacitor 7                    |
+| 原生 App | Capacitor / Tauri / 小程序适配按当前项目选择 |
 | 公共 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` 脚本覆盖它。
+
+### SvelteKit Adapter 模式
+
+仅在项目实际使用 SvelteKit 和 `@h-ai/kit/adapter` 时使用；Vite SPA 不配置 SvelteKit adapter，fullstack 各前端按自身 scripts 构建。
 
 | 模式    | Adapter        | 认证方式              | 部署目标                |
 | ------- | -------------- | --------------------- | ----------------------- |
-| SSR Web | adapter-node   | Bearer access token + Cookie | Node.js 服务器          |
+| SSR Web | adapter-node   | 项目现有 Cookie/会话管道 | Node.js 服务器          |
 | SPA     | adapter-static | Bearer access token + httpOnly refresh cookie | CDN / 静态托管          |
 | Android | adapter-static | Bearer access token + Capacitor secure storage | Capacitor → Android APK |
 | iOS     | adapter-static | Bearer access token + Capacitor secure storage | Capacitor → iOS IPA     |
@@ -60,7 +71,7 @@ const config = {
 - `VITE_ADAPTER=node`（默认）→ adapter-node（SSR）
 - `VITE_ADAPTER=static` → adapter-static（SPA / 原生 App）
 
-### 目录结构
+### SvelteKit 目录示例
 
 ```
 项目根/
@@ -80,7 +91,6 @@ const config = {
       capacitor.ts                # Capacitor 初始化（原生 App）
       server/
         init.ts                   # 模块初始化入口（单例，SSR）
-        procedures/               # 应用私有 oRPC procedures（仅 API Service 场景）
       paraglide/                  # i18n 生成文件（禁止手动修改）
       components/                 # 应用组件
     routes/
@@ -100,12 +110,12 @@ const config = {
 ```
 core（基础能力：配置、日志、i18n、HaiResult）
   ├── crypto（加密：SM2/SM3/SM4）
-  ├── db（数据库：SQLite/PostgreSQL/MySQL）
+  ├── reldb（数据库：SQLite/PostgreSQL/MySQL）
   ├── cache（缓存：内存/Redis）
   ├── storage（存储：本地/S3）
   ├── ai（AI：LLM/MCP/Agent）
-  ├── iam（身份管理）← 依赖 crypto + db + cache
-  ├── payment（支付）← 依赖 db + crypto
+  ├── iam（身份管理）← 依赖 crypto + reldb + cache
+  ├── payment（支付）← 依赖 reldb + crypto
   ├── api-contract（公共 HTTP API 契约）← 纯定义，依赖 core + zod + oRPC contract
   ├── serv（Hono + oRPC API Service）← 依赖 api-contract；features 按需依赖 iam/storage/ai
   ├── kit（SvelteKit 集成）← Hook / guard / validate / response，不定义公共 contract
@@ -114,6 +124,8 @@ core（基础能力：配置、日志、i18n、HaiResult）
   └── ui（UI 组件库）← 依赖 core
 ```
 
+这是常见关联；具体配置/依赖以所选模块当前版本为准。其它能力（reach/audit/scheduler/datapipe/vecdb）及同模块 feature 的任务导航见 [需求能力表](../hai-app-create/development.md#将需求映射到现有能力)。
+
 ### 模块初始化顺序
 
 #### SSR 模式（hooks.server.ts）
@@ -151,14 +163,16 @@ if (!identity.success) {
 // 检查关闭结果；core 无 close，kit/api-contract/serv 不需要 init。
 ```
 
-#### SPA / 原生 App 模式（src/lib/api.ts）
+#### SPA / 原生 App 模式（已有 api.ts 或 shared 客户端）
+
+复用当前项目初始化函数、API base 运行时配置和 TokenStorage；以下仅展示浏览器 Cookie 模式。原生端按 `hai-api-client` / `hai-capacitor` 配置安全存储，不用 localStorage 持久化敏感 token。
 
 ```typescript
 import { apiClient } from '@h-ai/api-client'
 
 export async function initApi() {
   return apiClient.init({
-    baseUrl: import.meta.env.VITE_API_BASE_URL,
+    baseUrl: configuredApiBase, // 来自当前项目已校验的运行时配置
     auth: {}, // 浏览器默认 httpOnly cookie；原生 App 传入 Capacitor TokenStorage
     timeout: 15_000,
   })
@@ -201,6 +215,8 @@ logging:
 
 ### 模块使用（API 与集成）
 
+先按 [development.md 的需求能力表](../hai-app-create/development.md#将需求映射到现有能力) 匹配需求，再查以下 API 入口；不用通读所有技能。
+
 | 任务                  | 技能             | 触发关键词                                        |
 | --------------------- | ---------------- | ------------------------------------------------- |
 | 配置/日志/i18n/HaiResult | `hai-core`       | core.init, core.logger, core.config, HaiResult       |
@@ -222,16 +238,16 @@ logging:
 
 | 任务                   | 技能             | 触发关键词                             |
 | ---------------------- | ---------------- | -------------------------------------- |
-| 创建页面/组件/API/模型 | `hai-app-create` | 新建页面, 添加组件, API 端点, 数据模型 |
+| 新增/修改/修复应用功能 | `hai-app-create` | 页面, 组件, API, 模型, 功能修复 |
 | 代码审查与规范化       | `hai-app-review` | 审查, review, 规范, 优化               |
 | 编写/补充测试          | `hai-app-tests`  | 测试, test, 单测, 覆盖率, TDD, E2E     |
 | CI/CD 与质量门禁       | `hai-ci`         | CI, CD, GitHub Actions, workflow, secret scan |
 | PR / Issue 交付审查    | `hai-pr-review`  | PR, pull request, issue, CODEOWNERS, 自动 Review, AI Review |
 | hai-framework 同步     | `hai-framework-sync` | hai-framework, skills 同步, framework:use:local, framework:watch |
 
-## TDD 开发工作流（强制）
+## 行为开发工作流
 
-> 所有新功能开发必须遵循 TDD：**先写测试 → 确认失败 → 再实现 → 确认通过 → 重构**。
+新增/改变行为时：先写有意义的目标用例 → 确认因目标行为缺失失败 → 实现 → 通过 → 审查。纯文案、格式和文档变化按影响验证，不机械新增单元与 E2E 测试。
 
 ### 完整流程
 
@@ -262,7 +278,9 @@ pnpm --filter <app-name> test
 pnpm --filter <app-name> test:e2e
 
 # Refactor：质量门禁
-pnpm typecheck && pnpm lint && pnpm test
+pnpm typecheck
+pnpm lint
+pnpm test
 ```
 
 ## 统一编码规范
@@ -271,7 +289,8 @@ pnpm typecheck && pnpm lint && pnpm test
 
 - **禁止 `any`**：不确定类型用 `unknown`，在边界处做类型缩窄
 - **禁止 `console.log`**：使用 `core.logger`（trace/debug/info/warn/error/fatal）
-- **禁止硬编码密钥**：使用环境变量，新增变量需在 `.env` 中写入占位符
+- **禁止硬编码密钥**：使用服务端配置/环境变量；新增变量在 `.env.example` 中写入占位符，PUBLIC/VITE 变量不得包含密钥
+- **禁止无说明的 `as unknown as T`**：必要第三方断言写明依据；代码注释中文、日志英文并脱敏
 - **禁止硬编码用户文案**：所有用户可见文本必须使用 i18n key
 - **禁止修改 `src/lib/paraglide`** 生成文件
 
@@ -292,11 +311,12 @@ return kit.response.ok(result.data)
 
 ### 质量门禁
 
-每次变更后按顺序执行：
+按当前项目已定义的 scripts 和变更影响执行；PowerShell 使用 `pnpm.cmd`：
 
 ```bash
 pnpm typecheck    # TypeScript 类型检查
 pnpm lint         # ESLint 检查
+pnpm build        # 构建/配置/模板/跨包契约变更
 pnpm test         # Vitest 单元测试
 ```
 
@@ -304,14 +324,15 @@ pnpm test         # Vitest 单元测试
 
 ### 变更前：需求分析 + 测试设计
 
-1. 列出将修改的文件路径
-2. 确认哪些类型/接口会变
-3. 搜索确认引用关系（避免遗漏）
-4. **设计测试用例清单**（单元测试 + E2E 测试）
+1. 按 development.md 匹配适用框架能力、已有 feature/配置和实际版本，说明必要自定义缺口
+2. 列出将修改的文件路径
+3. 确认哪些类型/接口会变
+4. 搜索确认引用关系（避免遗漏）
+5. 按行为风险设计测试与安全验收场景
 
 ### 变更中：TDD 三步走
 
-1. **Red**：编写单元测试（Vitest）+ E2E 测试（Playwright），确认新增目标用例失败、既有回归通过
+1. **Red**：为新增/改变行为编写适用的单元/集成/E2E 测试，确认目标用例失败、既有回归通过
 2. **Green**：按技能指引完成功能实现，逐步让测试通过
 3. **Refactor**：审查代码规范、重构优化
 
@@ -319,8 +340,9 @@ pnpm test         # Vitest 单元测试
 
 1. `pnpm typecheck` 通过
 2. `pnpm lint` 通过
-3. `pnpm test` 通过（单元测试）
-4. `pnpm --filter <app-name> test:e2e` 通过（E2E 测试）
-5. 搜索确认所有引用点已更新
+3. 构建/配置/跨包变更 `pnpm build` 通过
+4. `pnpm test` 通过（单元测试）
+5. UI/路由/端到端改动执行相应 `test:e2e`；从 package.json 确认入口
+6. 搜索确认所有引用点已更新，报告未验证边界
 
-原生交付必须单独执行 Tauri/Gradle/Xcode 打包，并在目标 OS/设备验证安装启动、登录/退出、重启会话、安全 TokenStore、真实 API 域名与覆盖升级。Web 构建/E2E 不代替原生验收。保存提交、包 hash、平台/工具链及逐项结果；缺平台写未验证，禁止静默 skip。hai-framework 仓库参考 `.github/workflows/native.yml` 与 desktop-app / mobile-app README 的「原生交付与验收」章节。
+涉及原生交付时按当前项目 Tauri/Gradle/Xcode 等实际入口打包，在目标 OS/设备验证安装启动、会话、安全 TokenStorage、API 域名及覆盖升级。Web 构建/E2E 不代替原生验收；记录平台/工具链与结果，缺平台写未验证。

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

@@ -7,14 +7,6 @@ description: "维护 hai 应用的 CI/CD、GitHub Actions、质量门禁和凭
 
 ## 能力契约
 
-框架完整质量门禁在 Node.js 22.12.0（声明的最低版本）执行；升级 engines 时同步 CI、README 和脚手架，不能只在更高版本通过后宣称最低版本通过。
-
-框架发布通过实际 npm 精确版本和 GitHub Release 判断完成，不能只看 tag。部分失败重跑原提交，只补发缺失包；npm 全部成功后再建 tag/Release。查询异常与 404 必须区分，tag 指向其他提交时停止补发，禁止将新源码混入旧版本。
-
-Turbo 的 `build.env` 必须列出影响产物的变量；框架包含容器构建开关、E2E 构建模式及 PUBLIC/VITE/TAURI 前缀，共享 tsup 配置也纳入依赖。Docker/Testcontainers 连接变量通过测试任务透传。验证缓存须切换变量检查哈希和真实产物，不能只检查配置文本。
-
-框架仓库发布验收使用 `pnpm test:release-local`；其 E2E 与 CI 共用根 `pnpm e2e`，覆盖 CLI 和全部 Web 应用，不能缩减为仅 Admin Console。应用仓库应在自己的根 E2E 命令集中维护所有端到端入口。容器和原生验收须独立记录实际结果。
-
 | 项目 | 契约 |
 | --- | --- |
 | 能力 | 维护 hai 应用的 CI/CD、GitHub Actions、质量门禁和凭据泄漏扫描 |
@@ -41,7 +33,7 @@ Turbo 的 `build.env` 必须列出影响产物的变量；框架包含容器构
 2. **最小权限**：默认 `permissions: contents: read`，只有 release、comment、pages 等明确场景才提升权限。
 3. **PR 不使用 secrets**：来自 fork 或不可信分支的 PR 不得运行读取 secrets 的 workflow。
 4. **禁用高风险组合**：禁止 `pull_request_target` + checkout PR 代码 + secrets/写权限。
-5. **先轻后重**：核心 CI 必须稳定；E2E、发布、安全深扫可以拆成 manual/nightly 或独立 workflow。
+5. **按风险选择门禁**：核心 CI 必须稳定；E2E、发布、安全深扫可拆为独立 workflow，但关键权限/数据完整性路径不能因不稳定而长期没有验收。
 6. **可追溯**：workflow 改动必须说明触发条件、权限、缓存、失败路径和验证命令。
 
 ## 标准 CI 工作流
@@ -54,11 +46,13 @@ Turbo 的 `build.env` 必须列出影响产物的变量；框架包含容器构
 pnpm install --frozen-lockfile
 pnpm typecheck
 pnpm lint
-pnpm test
 pnpm build
+pnpm test
 ```
 
-测试覆盖范围与 TDD 断言由 `hai-app-tests` 定义；本技能只决定这些命令如何在 workflow 中稳定执行。
+从当前 package.json 确认实际 scripts，使用声明的最低 Node 版本验证并与 engines/README 同步；PowerShell 使用 `pnpm.cmd`。测试内容由 `hai-app-tests` 定义；本技能决定门禁如何稳定执行。
+
+lint/typecheck 只能执行已配置的规则。新增开发规范时区分可静态检测项（如显式 any/console.log）与必须行为验收项（如资源越权、事务/幂等、失败结果、生命周期清理），后者在适用单元/集成/E2E 中验证。禁止通过关闭规则、添加无依据忽略或把 `|| true` 加到门禁来“统一风格”。
 
 ### E2E 策略
 
@@ -69,7 +63,7 @@ pnpm build
 ### hai-framework 依赖策略
 
 - CI 默认使用 `pnpm-lock.yaml` 中的 npm/published 依赖，确保与真实安装环境一致。
-- 本地联调使用 `framework:use:local` / `framework:watch`，但不要让默认 PR CI 隐式依赖本机路径。
+- 本地联调先查项目是否定义 `framework:use:local` / `framework:watch`；没有时按本项目 README 操作，不要让默认 PR CI 隐式依赖本机路径。
 - 需要验证本地 framework 改动时，创建显式的 sync/drift check 或双仓联动 PR。
 
 ## GitHub Actions 安全清单
@@ -88,7 +82,7 @@ pnpm build
 ### 推荐
 
 - 用无 secrets 的高置信正则扫描常见密钥形态。
-- 排除示例 skill、锁文件、图片等容易误报的路径。
+- 技能/文档与配置同样可能泄漏凭据，不按目录整体排除；只对已确认的测试占位和固定误报做有依据的最小忽略，检查修改是否掩盖真实密钥。
 - 需要私有关键词表时，仅在受信任分支的独立 workflow 中运行，不对 fork PR 暴露。
 
 ### 禁止
@@ -115,5 +109,4 @@ pnpm build
 - `hai-deploy` — 应用部署与云服务开通
 - `hai-framework-sync` — hai-framework 与应用仓库同步策略
 
-发布完成判定始终查询根版本的 npm 包；发布 job 同步包版本但不提交，标签固定指向触发质量验收的源码提交。发布成功后由独立 job 提交版本同步；完整重跑即使无需补发也会执行同步，远端已存在相同内容时成功退出，分支有新源码时拒绝覆盖并要求从最新 main 重跑。
-原生交付必须单独执行 Tauri/Gradle/Xcode 打包，并在目标 OS/设备验证安装启动、登录/退出、重启会话、安全 TokenStore、真实 API 域名与覆盖升级。Web 构建/E2E 不代替原生验收。保存提交、包 hash、平台/工具链及逐项结果；缺平台写未验证，禁止静默 skip。hai-framework 仓库参考 `.github/workflows/native.yml` 与 desktop-app / mobile-app README 的「原生交付与验收」章节。
+涉及发布时按本应用实际 registry/镜像/部署目标核验精确版本与提交，不以 tag 或 CI 绿灯代替发布产物；未经授权不发布。原生/容器交付按当前项目入口单独构建与启动验收，保存产物、平台和行为证据；缺平台写未验证，Web E2E 不代替原生验收。

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

@@ -18,8 +18,10 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 ## 使用路径
 
 - Node 启动用 core.init({ configDir }) 加载配置；勿传 logging 覆盖 _core.yml 中的日志设置，除非任务明确要求。
+- 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开值，修改配置后重新构建。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
 - HAI_<配置名>_<路径> 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
+- 初始化前创建的默认、模块与嵌套 child Logger 在后续输出中应用当前全局 logging；configure/setLevel 也作用于已有实例。create 的显式 level/format/context 优先，未指定项动态继承。浏览器 json/pretty 与附加 redact 路径实际生效，消息文本仍由调用方脱敏。
 
 ## 按需参考
 

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

@@ -140,6 +140,8 @@ feature:
 
 `core.logger` 既是默认 Logger 实例，也是日志管理的统一入口。
 
+`core.init` 加载 `_core.yml.logging`、`configure` 和 `setLevel` 会改变已有默认、模块及嵌套 child Logger 的后续实际输出；不需要重新创建模块 Logger。`create` 显式指定的 level/format/context 保持优先，未指定选项动态继承全局配置；调用时 context 覆盖固定 context，附加 redact 规则统一生效。
+
 **日志记录**（实例方法）：`trace` / `debug` / `info` / `warn` / `error` / `fatal`
 
 ```typescript
@@ -525,9 +527,9 @@ logger.debug('Data fetched', { count: items.length })
 | 功能 | 行为 |
 |------|------|
 | `core.config` 文件配置 | 不支持；文件相关方法返回 `SERVICE_UNAVAILABLE`，配置应由服务端读取后下发 |
-| `format: 'json' \| 'pretty'` | 被忽略（始终输出到 DevTools console） |
-| 自定义 `redact` 配置 | 浏览器不使用该配置，但默认 sanitizeSensitiveFields 仍会清理上下文敏感字段；消息文本需调用方脱敏 |
-| `fatal` 级别 | 映射为 `console.error`（带 `[FATAL]` 前缀） |
-| context 输出 | JSON 字符串追加到消息末尾（非结构化对象） |
+| `format: 'json' \| 'pretty'` | 始终输出到 DevTools console；json 为包含 level/msg 的 JSON 字符串，pretty 为可读消息与上下文 |
+| 自定义 `redact` 配置 | 与默认 sanitizeSensitiveFields 同时生效；支持嵌套点/括号路径与 `*`，不修改调用方对象；消息文本需调用方脱敏 |
+| `fatal` 级别 | 映射为 console.error；pretty 带 `[FATAL]` 前缀，json 使用 `level: 'fatal'` |
+| context 输出 | pretty 追加 JSON 上下文，json 合并上下文到结构化 JSON 字符串 |
 
 云资源输出格式与部署配置消费见 [hai-deploy](../hai-deploy/SKILL.md)；这里的父节点覆盖规则同样适用。

package/templates/skills/hai-framework-sync/SKILL.md

@@ -38,6 +38,8 @@ description: "同步 hai-framework 通用 skills、AI 入口与应用依赖，
 
 ### 1. 判断来源
 
+先读取当前应用入口与 package.json/lockfile，记录实际 npm/local 模式及解析版本。同步 skill 不能证明新 API 已安装或可用：以目标依赖的公开 exports/types 验证示例与配置，未发布框架能力仅用于已授权本地联调。
+
 | 变更类型 | 首选位置 |
 | --- | --- |
 | 通用 hai 模块用法 | `hai-framework/packages/cli/templates/skills/hai-*/SKILL.md` |
@@ -55,14 +57,16 @@ description: "同步 hai-framework 通用 skills、AI 入口与应用依赖，
 
 - `AGENTS.md`
 - `.github/copilot-instructions.md`
-- `CLAUDE.md`（如存在）
+- `CLAUDE.md`（如存在，通过 `@AGENTS.md` 复用共享规则；不另复制 `.claude/skills/`，保留用户已有规则和技能）
 - `opencode.json`（如结构变化）
 
+新增/修改/修复任务入口必须能到达 `hai-app-create` 与其 `development.md`；审查入口能到达 `hai-app-review`。按目标架构/依赖交付所需模块技能，不把 SvelteKit 指令套到 API/Vite 项目。复制前比对应用私有覆盖，合并通用修正并保留差异，不能直接覆盖业务规则。
+
 ### 4. 验证
 
 按变更类型选择验证方式：
 
-- 仅模板 / skill 变更：检查 diff、入口引用与模板泛化程度。
+- 仅模板 / skill 变更：检查 diff、目标中实际存在的入口/相邻资源及其相对引用，确认没有框架仓库私有路径/命令；本地能力导航对可选 skill 先检查存在，不把目录缺失当成能力缺失。
 - 同步到应用仓库：按 `hai-ci` 定义的质量门禁运行。
 - 涉及 framework runtime 时，先确认应用 package.json 已定义下列脚本；没有时按 README 的本地联调方式操作：
 
@@ -75,6 +79,8 @@ pnpm framework:watch <package>
 ## 漂移检查清单
 
 - [ ] framework 模板和应用 `.agents/skills` 对同名 skill 内容一致，除非 PR 明确说明本地覆盖
+- [ ] 普通功能修改/修复也路由到能力匹配与安全/质量自查，不仅“创建项目”或手工调用 skill 才生效
+- [ ] 技能示例与目标实际依赖版本、架构、公开 API 一致；没有把模板更新当成 runtime 升级
 - [ ] `AGENTS.md` 的 skill 列表包含新增/重命名 skill
 - [ ] Copilot/Claude/OpenCode 入口能找到新增 skill
 - [ ] CI 默认不依赖 `/home/.../hai-framework` 本地路径

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

@@ -27,7 +27,7 @@ description: "审查 PR 范围、风险、验证证据和合并准备度。"
 - 设计 AI PR Review 方案
 - 选择 Copilot、CodeRabbit、reviewdog、DangerJS、Claude Code Action、Codex Action 等工具
 
-不负责：代码级质量审查（用 `hai-app-review` / 模块审查技能）、测试用例设计（用 `hai-app-tests`）、workflow 触发/权限/secret 细节（用 `hai-ci`）。
+代码级框架复用、安全与风格审查交给 [hai-app-review](../hai-app-review/SKILL.md)，测试用例设计交给 `hai-app-tests`，workflow 触发/权限/secret 细节交给 `hai-ci`。
 
 ## 审查分层
 
@@ -41,7 +41,8 @@ description: "审查 PR 范围、风险、验证证据和合并准备度。"
 
 - scope 是否清晰且与 issue 对齐
 - 测试是否覆盖成功路径、失败路径、边界条件
-- 是否符合 hai-framework 约定：HaiResult、i18n、日志、分层、TDD
+- 本次需求是否复用适用框架能力/feature/配置，自定义或新依赖是否有已安装版本的缺口依据（见 [development.md](../hai-app-create/development.md)）
+- 是否符合实际返回契约、i18n、日志、分层、当前 lint 风格，以及输入/越权/失败等适用行为验收；不能以导入包数量或 CI 全绿替代代码与安全审查
 - 是否引入密钥、权限扩大、workflow 风险或两仓漂移
 
 ### 第 3 层：AI Review（默认 advisory）
@@ -91,7 +92,7 @@ PR 描述必须说明：
 - [ ] PR 模板完整填写
 - [ ] CI required checks 全绿
 - [ ] 新行为有测试，失败路径有覆盖
-- [ ] 代码级质量问题已由 `hai-app-review` / 模块审查技能覆盖
+- [ ] 框架能力选择、代码风格与适用安全边界已由 `hai-app-review` 覆盖，有行为证据或明确未验证项
 - [ ] 文档 / skill / README 与代码同步
 - [ ] workflow 权限或 secrets 变化已由 `hai-ci` 审查
 - [ ] AI-assisted 内容已由人类复核
@@ -99,5 +100,5 @@ PR 描述必须说明：
 ## 相关 Skills
 
 - `hai-ci` — CI/CD 与 workflow 安全
-- `hai-review-module` / `hai-app-review` — 代码质量审查
+- `hai-app-review` — 应用代码质量与框架复用审查
 - `hai-framework-sync` — 两仓同步审查

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

@@ -18,6 +18,7 @@ description: "使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、C
 ## 使用路径
 
 - `_db.yml` 对应 core.config 的 db；先校验 ReldbConfigSchema，再 init 并检查 success。
+- `reldb.crud.table` / `tx.crud.table` 的 `dbType` 必填并与实际后端一致；`BaseReldbCrudRepository` 自动读取已初始化的配置。
 - 事务每步检查结果，避免把失败当普通返回值提交；同一事务操作须共享 tx。
 - SQL 值参数化；where/orderBy/json 列名不是任意用户输入。分页使用 PaginatedResult。