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

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) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景

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

@@ -42,12 +42,14 @@ await capacitor.close()
 
 ### 2. Token 安全存储（与 api-client 配合）
 
+先复用应用已有的 API 初始化入口。示例中的 `apiBase` 由应用解析公开运行配置，已经包含 API 前缀，不重复拼接 `/api/v1`。Web 部署可通过 `runtime-config.js` 覆盖地址；原生包在复制静态资源前设置公开配置。
+
 ```typescript
 import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
 await apiClient.init({
-  baseUrl: import.meta.env.PUBLIC_API_BASE,
+  baseUrl: apiBase,
   auth: {
     storage: createCapacitorTokenStorage(),
   },
@@ -236,7 +238,7 @@ export async function initCapacitor() {
 
 ### SPA 模式配置（必需）
 
-Capacitor 应用使用 Vite 构建 SPA，并让原生壳读取 `dist`：
+Capacitor 原生壳读取 `webDir` 指定的静态产物。纯 Vite 模板默认为 `dist`；SvelteKit 项目需配置静态适配器，输出可能是 `build`。构建器、容器与 `webDir` 必须一致，以下是 Vite 示例：
 
 ```typescript
 // capacitor.config.ts
@@ -258,9 +260,9 @@ export default config
 import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
-export async function initApi() {
+export async function initApi(apiBase: string) {
   return apiClient.init({
-    baseUrl: `${import.meta.env.PUBLIC_API_BASE}/api/v1`,
+    baseUrl: apiBase,
     auth: {
       storage: createCapacitorTokenStorage(),
     },

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

@@ -52,6 +52,8 @@ pnpm test
 
 从当前 package.json 确认实际 scripts，使用声明的最低 Node 版本验证并与 engines/README 同步；PowerShell 使用 `pnpm.cmd`。测试内容由 `hai-app-tests` 定义；本技能决定门禁如何稳定执行。
 
+AI 本地验收和排查按 [分轮验证与集中修复](../hai-app-tests/validation.md) 收集所有可执行结果，再集中修复；普通失败不立即从头重跑。独立 CI job 可继续收集结果，真实前置失败则阻塞其依赖 job；必需检查与发布步骤仍须全部成功，不以继续收集为由设置 `continue-on-error` 或放行失败。
+
 lint/typecheck 只能执行已配置的规则。新增开发规范时区分可静态检测项（如显式 any/console.log）与必须行为验收项（如资源越权、事务/幂等、失败结果、生命周期清理），后者在适用单元/集成/E2E 中验证。禁止通过关闭规则、添加无依据忽略或把 `|| true` 加到门禁来“统一风格”。
 
 ### E2E 策略

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

@@ -1,6 +1,6 @@
 ---
 name: hai-core
-description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地化和 HaiResult。"
+description: "配置 hai 应用启动、YAML/环境变量、日志、i18n 与 HaiResult；排查配置覆盖和错误本地化。"
 ---
 
 # hai-core
@@ -18,7 +18,7 @@ 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，不接收完整模块配置、密钥或日志脱敏上下文。
+- 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开默认值，修改这些编译默认值需要重新构建。静态 Web 的公开 API 地址等通过 `runtime-config.js` 覆盖时无需重建镜像，原生包在复制静态资源前准备配置入口。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
 - `HAI_<配置名>_<路径>` 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
 - 环境文件采用六类：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，这五类均提交 Git。`.env.local` 为本机私有配置，不提交 Git。优先级为进程环境 > `.env.local` > 环境文件 > `.env`；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 脚本按相同顺序传入 `--env-file`。`core.init` 不自行读取 dotenv。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
@@ -26,7 +26,7 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景