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

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
@@ -11,192 +11,31 @@ description: "使用 @h-ai/cache 的 Memory/Redis 缓存、TTL、集合、排行
 | --- | --- |
 | 能力 | 使用 @h-ai/cache 的 Memory/Redis 缓存、TTL、集合、排行榜和锁 |
 | 适用场景 | 缓存读写、过期策略或共享资源互斥 |
-| 输入 | CacheConfigInput、key/value、TTL、每次获锁的唯一 owner |
-| 输出 | 缓存和锁操作的 HaiResult，获锁 data 为 boolean |
+| 输入 | CacheConfigInput、key/value、TTL；acquire 返回本次获锁唯一 owner |
+| 输出 | 缓存和锁操作的 HaiResult，获锁 data 为唯一 owner 或 null |
 | 限制 | 仅服务端；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. 读取 acquire 成功返回的唯一 owner，检查 success 与 data；续期/释放复用该 owner，丢锁后停止受保护工作。
+4. 验证过期、连接失败、并发与锁过期后的旧任务；最后 close。
 
-## 运行环境
+Cluster 的 mset/集合运算/多键 blocking pop 须同 slot；mget/del/exists 可跨 slot，但无全局原子性。scan 使用字符串游标遍历全部主节点，返回去除 keyPrefix 的逻辑 key；拓扑/条件变化后重新遍历。
 
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端无需直接操作缓存，由服务端模块（如 IAM、Scheduler）内部使用。
+## 按需参考
 
-## 适用场景
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-- 缓存热点数据减少数据库查询
-- 会话存储（配合 IAM）
-- 分布式缓存（Redis）与本地测试缓存（Memory）
-- 集合操作（权限缓存、标签集合）
-- 排行榜（ZSet）与队列（List）
-- 分布式锁（多节点部署互斥控制）
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码 — `HaiCacheError`](reference.md#错误码--haicacheerror)
+- [常见模式](reference.md#常见模式)
+- [相关 Skills](reference.md#相关-skills)
 
-## 使用步骤
+单键 compareAndSwap(key, expected, value, {px?,keepTtl?}) 比较 JSON 序列化快照并原子替换，必须检查 success 与 boolean data。expected=undefined 表示不存在，value=undefined 表示删除，null 是值；px 正整数且与 keepTtl 互斥。比较失败不修改 TTL；跨节点版本状态优先使用 CAS 而不是租约后无条件 SET。
 
-### 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 集成层
+`kv.set` 返回 `HaiResult<boolean>`：`data=true` 表示实际写入，NX/XX 未命中返回 `success=true,data=false` 且不改变原值或 TTL。签发票据、会话或登记公钥前必须检查这两个字段。`ex/px/exat/pxat` 分别使用秒、毫秒、Unix 秒、Unix 毫秒，须为正安全整数且只能指定一种，与 `keepTtl=true` 互斥；`nx/xx` 也互斥。零、负数、小数、非有限值或溢出返回 `INVALID_SET_OPTIONS`（`cache:016`），不会写成永久键。过去的正绝对时间表示立即过期。省略期限会移除原 TTL；`keepTtl` 保留已有 TTL，新键仍永久保存。memory 和 Redis 都保存 JSON 快照。

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

@@ -0,0 +1,229 @@
+# 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'))
+// 使用后关闭
+const closed = await cache.close()
+if (!closed.success) throw new Error(closed.error.message)
+```
+
+
+初始化只在健康检查成功后发布连接；失败时释放候选资源。若清理仍失败，初始化错误的 `error.ext.cleanupPending` 为 `true`。`cache.close()` 返回 `Promise<HaiResult<void>>`，等待正在进行的初始化，并合并并发关闭。开始清理后 `isInitialized` 为 `false`，配置与业务操作不再可用；清理失败仍保留资源，后续 `close()` 或 `init()` 先重试释放，成功前不会创建替代连接。调用方必须检查关闭结果。
+
+```ts
+const closed = await cache.close()
+if (!closed.success) {
+  // 处理清理故障后有限重试；再次失败应向应用报告。
+  const retried = await cache.close()
+  if (!retried.success) throw new Error(retried.error.message)
+}
+```
+
+
+`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')
+```
+
+### Cluster 多键与扫描
+
+`mget/del/exists` 跨 slot 时有界并发且无整体原子性/快照；mget 保留输入顺序，DEL 失败可能已部分删除，重试幂等。`mset`、集合交/并/差和多键 blocking pop 须同 slot，否则返回 `CROSS_SLOT`；使用共同的 `{hash-tag}`，MSET 不做部分写入回退。
+
+scan 首次传字符串 `'0'`，后续原样传回不透明游标，返回 `'0'` 表示完成。Cluster 覆盖所有 master；同配置和拓扑的另一应用节点可接续。拓扑、match 或 keyPrefix 改变时返回 `SCAN_TOPOLOGY_CHANGED`，从 `'0'` 重启；无效游标或 count 返回 `INVALID_SCAN`。返回去除 keyPrefix 的逻辑 key，前缀 glob 字符按字面量解释；keys 同样扫描并去重。SCAN 无快照，可能重复，count 仅为正整数提示值。
+
+```ts
+const first = await cache.kv.scan('0', { match: 'users:*', count: 100 })
+if (first.success && first.data[0] !== '0') {
+  const next = await cache.kv.scan(first.data[0], { match: 'users:*', count: 100 })
+}
+```
+
+### 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），返回唯一 owner 或 null |
+| `release`  | 释放锁（必须携带本次 owner，防止误释放） |
+| `isLocked` | 检查锁是否被持有                           |
+| `extend`   | 续期锁 TTL（必须携带本次 owner） |
+
+```typescript
+// acquire 返回本次唯一 owner，后续释放/续期必须复用该凭据
+const acquired = await cache.lock.acquire('my-lock', { ttl: 30 })
+if (acquired.success && acquired.data) {
+  const owner = 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` 必须取自成功的 acquire.data；缓存内部每次生成唯一凭据，不能使用 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` | 配置错误 |
+| `HaiCacheError.INVALID_SCAN` | `hai:cache:013` | 游标或 count 无效 |
+| `HaiCacheError.SCAN_TOPOLOGY_CHANGED` | `hai:cache:014` | 拓扑或条件变化，重新遍历 |
+| `HaiCacheError.CROSS_SLOT` | `hai:cache:015` | 多键操作不在同一 slot |
+
+## 常见模式
+
+### 缓存命中与回源（未缓存空值，不防穿透）
+
+```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 acquired = await cache.lock.acquire(lockKey, { ttl: 60 })
+if (acquired.success && acquired.data) {
+  const owner = acquired.data
+  try {
+    await runBatchImportWithConditionalCommit()
+  }
+  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 集成层
+
+Cluster 与 Sentinel 数据节点认证使用 `password`，Cluster 发现的新节点继承同一鉴权配置。`url` 模式只使用 URL 内凭据，单独 password 不覆盖 URL。
+
+单键 compareAndSwap(key, expected, value, {px?,keepTtl?}) 比较 JSON 序列化快照并原子替换，必须检查 success 与 boolean data。expected=undefined 表示不存在，value=undefined 表示删除，null 是值；px 正整数且与 keepTtl 互斥。比较失败不修改 TTL；跨节点版本状态优先使用 CAS 而不是租约后无条件 SET。
+
+owner 只校验租约续期/释放，不是资源 fencing token。暂停或过期后旧任务仍可能执行，最终持久化写入必须使用资源自己的 CAS/代际条件/事务约束。批量导入等应用函数须在每次提交时校验条件，不能只靠锁包裹 Promise。
+
+## 生产共享状态
+
+生产仅使用 Redis（含 Cluster）；memory 只用于开发/明确测试。Redis 故障返回失败，不回退本机缓存。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化成功前检查，只有 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试豁免。不要将租约当作最终写入条件，外部未知效果须按稳定业务键核对。
+
+`kv.set` 返回 `HaiResult<boolean>`：`data=true` 表示实际写入，NX/XX 未命中返回 `success=true,data=false` 且不改变原值或 TTL。签发票据、会话或登记公钥前必须检查这两个字段。`ex/px/exat/pxat` 分别使用秒、毫秒、Unix 秒、Unix 毫秒，须为正安全整数且只能指定一种，与 `keepTtl=true` 互斥；`nx/xx` 也互斥。零、负数、小数、非有限值或溢出返回 `INVALID_SET_OPTIONS`（`cache:016`），不会写成永久键。过去的正绝对时间表示立即过期。省略期限会移除原 TTL；`keepTtl` 保留已有 TTL，新键仍永久保存。memory 和 Redis 都保存 JSON 快照。

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 下不伪造持久化成功。
+- TokenStorage 在原生端使用安全插件；Web/插件不可用或存储失败时拒绝 Promise。调用方处理 setTokens/clear 失败并释放 loading；clear 的实例内屏蔽不替代服务端撤销。
+- 原生打包前确认公开 API 地址的运行配置入口；fullstack App 使用 `public/runtime-config.js`，构建不会读取部署环境文件。这里只放公开地址，不能放 Token 或密钥。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景
@@ -32,3 +33,5 @@ description: "使用 @h-ai/capacitor 接入原生设备、相机、推送、状
 - 常见模式
 - 插件依赖
 - 相关 Skills
+
+推送仅在实际原生平台调用插件。`push.register({ signal? })` 与 `push.listen(callbacks, { signal? })` 的设置阶段限时 30 秒（包含权限和监听器挂载）；失败、超时、取消及 `capacitor.close()` 都会停止回调并移除本次拥有的句柄，迟到的句柄在完成后立即移除，不调用影响其他消费者的 removeAllListeners。listen 成功后信号仍有效，也可调用返回的 cleanup。cleanup 与 close 均返回 `HaiResult<void>`；原生 remove 失败返回 `PUSH_CLEANUP_FAILED`（`capacitor:032`），失败句柄保留供再次调用重试，成功移除的句柄不重复操作。模块关闭后立即不可用；重新初始化前先重试遗留清理。自动化验证控制插件时序，不能代替 Android/iOS 真机 FCM/APNs 权限、注册与反复挂载验收。

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

@@ -2,7 +2,7 @@
 
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
-> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合时，Token 仅存于原生安全存储，不回退到 Web `localStorage`。
+> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块。设备、推送等领域操作返回 `HaiResult<T>`；TokenStorage 是直接 Promise 适配器，失败会拒绝。与 `@h-ai/api-client` 配合时，Token 仅存于原生安全存储，不回退到 Web `localStorage`。
 
 ## 运行环境
 
@@ -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(),
   },
@@ -58,9 +60,11 @@ await apiClient.init({
 
 - Android → Android KeyStore + 加密 SharedPreferences
 - iOS → Keychain
-- Web → **不回退到 localStorage**；`get*()` 返回 `null`，`set*()` / `clear()` 为 no-op
+- Web → **不提供原生存储回退**；适配器方法拒绝 Promise，Web 入口选择 api-client 的 Cookie/内存存储
+
+读取、保存与删除失败均拒绝 Promise。调用方通过 `apiClient.auth` 串行更新凭据并捕获 setTokens/clear 失败；界面释放 loading，退出失败仍清理内存身份并提示错误。`clear()` 开始立即屏蔽本实例两类旧凭据，等待两个删除都结束；即使失败也保持屏蔽，相应 key 成功写入后重新开放。屏蔽不等于持久删除，跨实例/重启撤销仍依赖服务端退出/撤销会话。插件恢复后可以在同一实例重试，不缓存永久失败状态。
 
-所有方法内置 try-catch；原生安全存储异常时 get 返回 `null`、set/clear 静默失败并记录日志。
+任一 key 写入失败也会屏蔽整对凭据，避免 access 已落盘而 refresh 保存失败后的半完成登录。登录/注册保存失败后尝试 `auth.clear()` 清理部分数据；清理失败继续显示未确认删除的错误，不能只清界面身份或宣称持久删除成功。
 
 #### Preferences 子操作
 
@@ -165,7 +169,7 @@ await capacitor.statusBar.show()
 | API | 用途 | 返回值 |
 | --- | --- | --- |
 | `capacitor.init()` | 初始化模块（检测环境） | `HaiResult<void>` |
-| `capacitor.close()` | 关闭模块，重置状态 | `Promise<void>` |
+| `capacitor.close()` | 关闭模块并回收推送，失败可重试 | `Promise<HaiResult<void>>` |
 | `capacitor.getPlatform()` | 获取当前平台 | `'android' \| 'ios' \| 'web'` |
 | `capacitor.isNative()` | 是否为原生环境 | `boolean` |
 | `capacitor.isInitialized` | 是否已初始化 | `boolean` |
@@ -176,7 +180,7 @@ await capacitor.statusBar.show()
 | `capacitor.device.getInfo()` | 设备信息 | `HaiResult<DeviceInfo>` |
 | `capacitor.device.getAppVersion()` | 应用版本 | `HaiResult<{ version, build }>` |
 | `capacitor.push.register()` | 注册推送 | `HaiResult<PushRegistration>` |
-| `capacitor.push.listen(callbacks)` | 监听推送事件 | `HaiResult<() => Promise<void>>`（async 清理函数） |
+| `capacitor.push.listen(callbacks)` | 监听推送事件 | `HaiResult<PushCleanup>`（cleanup 返回 `Promise<HaiResult<void>>`） |
 | `capacitor.camera.takePhoto(options?)` | 拍照 / 选取图片 | `HaiResult<PhotoResult>` |
 | `capacitor.statusBar.configure(config)` | 配置状态栏 | `HaiResult<void>` |
 | `capacitor.statusBar.show()` | 显示状态栏 | `HaiResult<void>` |
@@ -236,7 +240,7 @@ export async function initCapacitor() {
 
 ### SPA 模式配置（必需）
 
-Capacitor 应用使用 Vite 构建 SPA，并让原生壳读取 `dist`：
+Capacitor 原生壳读取 `webDir` 指定的静态产物。纯 Vite 模板默认为 `dist`；SvelteKit 项目需配置静态适配器，输出可能是 `build`。构建器、容器与 `webDir` 必须一致，以下是 Vite 示例：
 
 ```typescript
 // capacitor.config.ts
@@ -258,9 +262,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(),
     },
@@ -350,3 +354,5 @@ async function captureAndUpload() {
 - `hai-ui`：移动端 UI 组件（SafeArea、BottomNav 等）
 
 原生交付必须单独执行 Tauri/Gradle/Xcode 打包，并在目标 OS/设备验证安装启动、登录/退出、重启会话、安全 TokenStore、真实 API 域名与覆盖升级。Web 构建/E2E 不代替原生验收。保存提交、包 hash、平台/工具链及逐项结果；缺平台写未验证，禁止静默 skip。hai-framework 仓库参考 `.github/workflows/native.yml` 与 desktop-app / mobile-app README 的「原生交付与验收」章节。
+
+推送仅在实际原生平台调用插件。`push.register({ signal? })` 与 `push.listen(callbacks, { signal? })` 的设置阶段限时 30 秒（包含权限和监听器挂载）；失败、超时、取消及 `capacitor.close()` 都会停止回调并移除本次拥有的句柄，迟到的句柄在完成后立即移除，不调用影响其他消费者的 removeAllListeners。listen 成功后信号仍有效，也可调用返回的 cleanup。cleanup 与 close 均返回 `HaiResult<void>`；原生 remove 失败返回 `PUSH_CLEANUP_FAILED`（`capacitor:032`），失败句柄保留供再次调用重试，成功移除的句柄不重复操作。模块关闭后立即不可用；重新初始化前先重试遗留清理。自动化验证控制插件时序，不能代替 Android/iOS 真机 FCM/APNs 权限、注册与反复挂载验收。

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,15 +18,17 @@ 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，不接收完整模块配置、密钥或日志脱敏上下文。
+- 自动加载和监听精确跳过 `_deploy.yml` / `_deploy.yaml`，部署 CLI 按目标环境和凭据独立解析；业务 `deploy.yml`、手动 `config.load` 不受影响。单项 load 返回失败时记日志并继续，必需配置须 validate 并检查 success；目录扫描、日志设置等异常仍可能传播。
+- 应用名称、版本、环境、默认语言和日志设置统一从 `_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。
+- 日志可用 `{ error }` 记录原生 Error；两端先规范化诊断再字段/URL 脱敏，配置 redact 路径仍生效。原异常不变，错误子图循环/深度用固定标记；message/stack 自由文本中的秘密需调用方先清理或遮蔽整条路径。
 - 初始化前创建的默认、模块与嵌套 child Logger 在后续输出中应用当前全局 logging；configure/setLevel 也作用于已有实例。create 的显式 level/format/context 优先，未指定项动态继承。浏览器 json/pretty 与附加 redact 路径实际生效，消息文本仍由调用方脱敏。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景
@@ -36,3 +38,5 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 - 常见模式
 - 相关 Skills
 - 浏览器侧使用
+
+Node 请求/SSR 必须用 `core.i18n.runWithLocale(locale, callback)`（kit 同名方法）包裹实际异步 resolve；serv 自动建立请求语言上下文。浏览器 setGlobalLocale/createLocaleStore 继续管理应用语言，SSR 的 UI setter/store 不写全局值。显式 MessageOptions.locale 优先；进程默认语言仅在启动时设置。