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

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

@@ -0,0 +1,145 @@
+# hai-audit 参考
+
+统一审计日志模块，基于 `@h-ai/reldb` 实现持久化，提供审计日志的记录、分页查询、清理与统计。
+
+## 运行环境
+
+> ⚠️ **服务端模块（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 模式
 
@@ -277,12 +277,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 +314,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 +341,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 不代替原生验收；记录平台/工具链与结果，缺平台写未验证。

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

@@ -1,6 +1,6 @@
 ---
 name: hai-cache
-description: "使用 @h-ai/cache 的 Memory/Redis 缓存、TTL、集合、排行榜和锁。"
+description: "实现或排查 Memory/Redis 缓存、TTL、集合与分布式锁，处理过期、回源和并发边界。"
 ---
 
 # hai-cache
@@ -15,188 +15,21 @@ description: "使用 @h-ai/cache 的 Memory/Redis 缓存、TTL、集合、排行
 | 输出 | 缓存和锁操作的 HaiResult，获锁 data 为 boolean |
 | 限制 | 仅服务端；Memory 不跨节点。release/extend 携带本次 owner，避免锁过期后误操作新持有者。 |
 
-> `@h-ai/cache` 提供统一缓存接口，支持 Memory 与 Redis 后端，包含 KV / Hash / List / Set / ZSet / 分布式锁 六类操作。
+## 使用路径
 
-内存 KV 在到期时间点即失效。整数计数器拒绝 null/boolean/array、非整数增量和安全整数溢出，失败不修改原值；Hash 的 `__proto__` / `constructor` 名称按普通字段保留。
+1. 先确定单进程 Memory 还是共享 Redis；配置校验与 init 成功后才使用。cache 不依赖 reldb。
+2. 根据 KV/Hash/List/Set/ZSet 选择公开操作，明确 TTL、空值和回源失败的业务含义。
+3. 每次获锁生成唯一 owner，检查 success 与 data；续期/释放复用该 owner，丢锁后停止受保护工作。
+4. 验证过期、连接失败、并发与锁过期后的旧任务；最后 close。
 
-## 运行环境
+## 按需参考
 
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端无需直接操作缓存，由服务端模块（如 IAM、Scheduler）内部使用。
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-## 适用场景
-
-- 缓存热点数据减少数据库查询
-- 会话存储（配合 IAM）
-- 分布式缓存（Redis）与本地测试缓存（Memory）
-- 集合操作（权限缓存、标签集合）
-- 排行榜（ZSet）与队列（List）
-- 分布式锁（多节点部署互斥控制）
-
-## 使用步骤
-
-### 1. 配置
-
-```yaml
-# config/_cache.yml
-type: memory # memory | redis
-# Redis 配置（type=redis 时生效）：
-# host: localhost
-# port: 6379
-# password: ''
-# db: 0
-# keyPrefix: 'hai:'
-```
-
-约定环境变量优先于 YAML，例如 `HAI_CACHE_TYPE`、`HAI_CACHE_HOST`、
-`HAI_CACHE_KEYPREFIX`。
-
-### 2. 初始化与关闭
-
-```typescript
-import { cache } from '@h-ai/cache'
-
-await cache.init(core.config.get('cache'))
-// 使用后关闭
-await cache.close()
-```
-
-`cache.config` 返回的是脱敏后的配置快照；Redis `password` / `url` 等敏感值不会原样暴露给日志或调试输出。
-
-## 核心 API
-
-### KV 操作（`cache.kv`）
-
-| 方法                                | 说明                 |
-| ----------------------------------- | -------------------- |
-| `get / set / del / exists`          | 基础读写与存在性判断 |
-| `expire / expireAt / ttl / persist` | TTL 管理             |
-| `incr / incrBy / decr / decrBy`     | 计数器操作           |
-| `mget / mset`                       | 批量读写             |
-| `scan / keys / type`                | Key 检索与类型判断   |
-
-```typescript
-await cache.kv.set('user:123', { name: '张三' }, { ex: 3600 })
-const result = await cache.kv.get<{ name: string }>('user:123')
-if (result.success && result.data) {
-  // result.data.name === '张三'
-}
-
-await cache.kv.del('user:123')
-```
-
-### Hash/List/Set/ZSet（`cache.hash/list/set_/zset`）
-
-- `cache.hash`：对象字段读写（如用户 profile 局部更新）
-- `cache.list`：队列/消息顺序处理
-- `cache.set_`：去重集合（成员关系、权限集合）
-- `cache.zset`：分数排序（排行榜、权重调度）
-
-```typescript
-await cache.hash.hset('profile:1', { nickname: 'alice' })
-await cache.list.lpush('queue:jobs', 'job-1', 'job-2')
-await cache.set_.sadd('role:admin:perms', 'user.read', 'user.write')
-await cache.zset.zadd('rank:daily', { member: 'u1', score: 100 })
-```
-
-### 分布式锁（`cache.lock`）
-
-| 方法       | 说明                                       |
-| ---------- | ------------------------------------------ |
-| `acquire`  | 尝试获锁（SET NX EX），返回 true/false     |
-| `release`  | 释放锁（支持 owner 验证，防止误释放）      |
-| `isLocked` | 检查锁是否被持有                           |
-| `extend`   | 续期锁 TTL（支持 owner 验证）              |
-
-```typescript
-// 每次尝试生成唯一 owner，后续释放/续期复用同一个值
-const owner = core.id.generate()
-const acquired = await cache.lock.acquire('my-lock', { ttl: 30, owner })
-if (acquired.success && acquired.data) {
-  try {
-    // 长任务仅在仍持有锁时续期；失败或 data=false 时停止依赖锁的后续操作
-    const extended = await cache.lock.extend('my-lock', 60, owner)
-    if (!extended.success || !extended.data) {
-      logger.warn('Lock extension failed; protected work cancelled')
-    }
-    else {
-      // 受保护的操作
-    }
-  }
-  finally {
-    await cache.lock.release('my-lock', owner)
-  }
-}
-
-// 检查
-const locked = await cache.lock.isLocked('my-lock')
-```
-
-**最佳实践：**
-
-- `owner` 每次获锁尝试唯一，释放/续期复用该值；仅用 nodeId 会使同节点旧任务误释放过期后重新获得的锁
-- 释放锁时传入 `owner` 防止误释放他人锁
-- Memory 后端适合开发/测试；Redis 后端用 Lua 脚本保证 release/extend 原子性
-
-## 错误码 — `HaiCacheError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiCacheError.CONNECTION_FAILED` | `hai:cache:001` | 连接失败 |
-| `HaiCacheError.OPERATION_FAILED` | `hai:cache:002` | 操作失败 |
-| `HaiCacheError.SERIALIZATION_FAILED` | `hai:cache:003` | 序列化失败 |
-| `HaiCacheError.DESERIALIZATION_FAILED` | `hai:cache:004` | 反序列化失败 |
-| `HaiCacheError.KEY_NOT_FOUND` | `hai:cache:005` | 键不存在 |
-| `HaiCacheError.TIMEOUT` | `hai:cache:006` | 超时 |
-| `HaiCacheError.NOT_INITIALIZED` | `hai:cache:010` | 未初始化 |
-| `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
-| `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
-
-## 常见模式
-
-### 缓存命中与回源（未缓存空值，不防穿透）
-
-```typescript
-async function getUserCached(userId: string) {
-  const cached = await cache.kv.get<User>(`user:${userId}`)
-  if (cached.success && cached.data)
-    return cached.data
-
-  const user = await userRepo.findById(userId)
-  if (user.success && user.data) {
-    await cache.kv.set(`user:${userId}`, user.data, { ex: 3600 })
-    return user.data
-  }
-  return null
-}
-```
-
-### 分布式锁保护共享资源
-
-```typescript
-const lockKey = 'batch:import'
-const owner = core.id.generate()
-const acquired = await cache.lock.acquire(lockKey, { ttl: 60, owner })
-if (acquired.success && acquired.data) {
-  try {
-    await runBatchImport()
-  }
-  finally {
-    await cache.lock.release(lockKey, owner)
-  }
-}
-else if (acquired.success) {
-  logger.info('Another node is running the import')
-}
-else {
-  logger.error('Lock acquisition failed', { code: acquired.error.code })
-}
-```
-
-## 相关 Skills
-
-- `hai-build`：模块初始化顺序（cache 在 db 之后、iam 之前）
-- `hai-core`：配置与 HaiResult 模型
-- `hai-iam`：会话存储与权限缓存（底层使用 cache）
-- `hai-scheduler`：定时任务分布式锁（底层使用 cache.lock）
-- `hai-reach`：消息发送互斥锁（底层使用 cache.lock）
-- `hai-kit`：SvelteKit 集成层
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码 — `HaiCacheError`](reference.md#错误码--haicacheerror)
+- [常见模式](reference.md#常见模式)
+- [相关 Skills](reference.md#相关-skills)

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

@@ -0,0 +1,187 @@
+# hai-cache 参考
+
+> `@h-ai/cache` 提供统一缓存接口，支持 Memory 与 Redis 后端，包含 KV / Hash / List / Set / ZSet / 分布式锁 六类操作。
+
+内存 KV 在到期时间点即失效。整数计数器拒绝 null/boolean/array、非整数增量和安全整数溢出，失败不修改原值；Hash 的 `__proto__` / `constructor` 名称按普通字段保留。
+
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端无需直接操作缓存，由服务端模块（如 IAM、Scheduler）内部使用。
+
+## 适用场景
+
+- 缓存热点数据减少数据库查询
+- 会话存储（配合 IAM）
+- 分布式缓存（Redis）与本地测试缓存（Memory）
+- 集合操作（权限缓存、标签集合）
+- 排行榜（ZSet）与队列（List）
+- 分布式锁（多节点部署互斥控制）
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_cache.yml
+type: memory # memory | redis
+# Redis 配置（type=redis 时生效）：
+# host: localhost
+# port: 6379
+# password: ''
+# db: 0
+# keyPrefix: 'hai:'
+```
+
+约定环境变量优先于 YAML，例如 `HAI_CACHE_TYPE`、`HAI_CACHE_HOST`、
+`HAI_CACHE_KEYPREFIX`。
+
+### 2. 初始化与关闭
+
+```typescript
+import { cache } from '@h-ai/cache'
+
+await cache.init(core.config.get('cache'))
+// 使用后关闭
+await cache.close()
+```
+
+`cache.config` 返回的是脱敏后的配置快照；Redis `password` / `url` 等敏感值不会原样暴露给日志或调试输出。
+
+## 核心 API
+
+### KV 操作（`cache.kv`）
+
+| 方法                                | 说明                 |
+| ----------------------------------- | -------------------- |
+| `get / set / del / exists`          | 基础读写与存在性判断 |
+| `expire / expireAt / ttl / persist` | TTL 管理             |
+| `incr / incrBy / decr / decrBy`     | 计数器操作           |
+| `mget / mset`                       | 批量读写             |
+| `scan / keys / type`                | Key 检索与类型判断   |
+
+```typescript
+await cache.kv.set('user:123', { name: '张三' }, { ex: 3600 })
+const result = await cache.kv.get<{ name: string }>('user:123')
+if (result.success && result.data) {
+  // result.data.name === '张三'
+}
+
+await cache.kv.del('user:123')
+```
+
+### Hash/List/Set/ZSet（`cache.hash/list/set_/zset`）
+
+- `cache.hash`：对象字段读写（如用户 profile 局部更新）
+- `cache.list`：队列/消息顺序处理
+- `cache.set_`：去重集合（成员关系、权限集合）
+- `cache.zset`：分数排序（排行榜、权重调度）
+
+```typescript
+await cache.hash.hset('profile:1', { nickname: 'alice' })
+await cache.list.lpush('queue:jobs', 'job-1', 'job-2')
+await cache.set_.sadd('role:admin:perms', 'user.read', 'user.write')
+await cache.zset.zadd('rank:daily', { member: 'u1', score: 100 })
+```
+
+### 分布式锁（`cache.lock`）
+
+| 方法       | 说明                                       |
+| ---------- | ------------------------------------------ |
+| `acquire`  | 尝试获锁（SET NX EX），返回 true/false     |
+| `release`  | 释放锁（支持 owner 验证，防止误释放）      |
+| `isLocked` | 检查锁是否被持有                           |
+| `extend`   | 续期锁 TTL（支持 owner 验证）              |
+
+```typescript
+// 每次尝试生成唯一 owner，后续释放/续期复用同一个值
+const owner = core.id.generate()
+const acquired = await cache.lock.acquire('my-lock', { ttl: 30, owner })
+if (acquired.success && acquired.data) {
+  try {
+    // 长任务仅在仍持有锁时续期；失败或 data=false 时停止依赖锁的后续操作
+    const extended = await cache.lock.extend('my-lock', 60, owner)
+    if (!extended.success || !extended.data) {
+      logger.warn('Lock extension failed; protected work cancelled')
+    }
+    else {
+      // 受保护的操作
+    }
+  }
+  finally {
+    await cache.lock.release('my-lock', owner)
+  }
+}
+
+// 检查
+const locked = await cache.lock.isLocked('my-lock')
+```
+
+**最佳实践：**
+
+- `owner` 每次获锁尝试唯一，释放/续期复用该值；仅用 nodeId 会使同节点旧任务误释放过期后重新获得的锁
+- 释放锁时传入 `owner` 防止误释放他人锁
+- Memory 后端适合开发/测试；Redis 后端用 Lua 脚本保证 release/extend 原子性
+
+## 错误码 — `HaiCacheError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiCacheError.CONNECTION_FAILED` | `hai:cache:001` | 连接失败 |
+| `HaiCacheError.OPERATION_FAILED` | `hai:cache:002` | 操作失败 |
+| `HaiCacheError.SERIALIZATION_FAILED` | `hai:cache:003` | 序列化失败 |
+| `HaiCacheError.DESERIALIZATION_FAILED` | `hai:cache:004` | 反序列化失败 |
+| `HaiCacheError.KEY_NOT_FOUND` | `hai:cache:005` | 键不存在 |
+| `HaiCacheError.TIMEOUT` | `hai:cache:006` | 超时 |
+| `HaiCacheError.NOT_INITIALIZED` | `hai:cache:010` | 未初始化 |
+| `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
+| `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
+
+## 常见模式
+
+### 缓存命中与回源（未缓存空值，不防穿透）
+
+```typescript
+async function getUserCached(userId: string) {
+  const cached = await cache.kv.get<User>(`user:${userId}`)
+  if (cached.success && cached.data)
+    return cached.data
+
+  const user = await userRepo.findById(userId)
+  if (user.success && user.data) {
+    await cache.kv.set(`user:${userId}`, user.data, { ex: 3600 })
+    return user.data
+  }
+  return null
+}
+```
+
+### 分布式锁保护共享资源
+
+```typescript
+const lockKey = 'batch:import'
+const owner = core.id.generate()
+const acquired = await cache.lock.acquire(lockKey, { ttl: 60, owner })
+if (acquired.success && acquired.data) {
+  try {
+    await runBatchImport()
+  }
+  finally {
+    await cache.lock.release(lockKey, owner)
+  }
+}
+else if (acquired.success) {
+  logger.info('Another node is running the import')
+}
+else {
+  logger.error('Lock acquisition failed', { code: acquired.error.code })
+}
+```
+
+## 相关 Skills
+
+- `hai-build`：模块初始化顺序（cache 在 iam 之前；cache 自身不依赖 reldb）
+- `hai-core`：配置与 HaiResult 模型
+- `hai-iam`：会话存储与权限缓存（底层使用 cache）
+- `hai-scheduler`：定时任务分布式锁（底层使用 cache.lock）
+- `hai-reach`：消息发送互斥锁（底层使用 cache.lock）
+- `hai-kit`：SvelteKit 集成层

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

@@ -1,6 +1,6 @@
 ---
 name: hai-capacitor
-description: "使用 @h-ai/capacitor 接入原生设备、相机、推送、状态栏和安全 Token 存储。"
+description: "在 Android/iOS 应用中接入 @h-ai/capacitor 设备、相机、推送与安全 Token 存储，处理 Web/原生差异。"
 ---
 
 # hai-capacitor
@@ -13,16 +13,17 @@ description: "使用 @h-ai/capacitor 接入原生设备、相机、推送、状
 | 适用场景 | Android/iOS 原生壳集成与平台差异处理 |
 | 输入 | Capacitor 配置、原生插件、设备权限和平台状态 |
 | 输出 | 原生操作结果及 TokenStorage 适配器 |
-| 限制 | 区分浏览器与 Android/iOS；安全存储需原生插件，Web 不降级到 localStorage。H5 验证不能代替真机验证。 |
+| 限制 | 区分浏览器与 Android/iOS；安全存储需原生插件，Web 使用 httpOnly Cookie/内存认证，不降级到 localStorage。H5 验证不能代替真机验证。 |
 
 ## 使用路径
 
 - 先判断平台和插件可用性，复用已有 SPA 入口；原生 UI 变化验证权限拒绝、取消和返回路径。
 - TokenStorage 在原生端使用安全插件；Web 下不伪造持久化成功。
+- 原生打包前确认公开 API 地址的运行配置入口；fullstack App 使用 `public/runtime-config.js`，构建不会读取部署环境文件。这里只放公开地址，不能放 Token 或密钥。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景