@h-ai/cli 0.1.0-alpha.53 → 0.1.0-alpha.55

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

@@ -1,6 +1,6 @@
 ---
 name: hai-cache
-description: 使用 @h-ai/cache 进行内存或 Redis 缓存操作（kv/hash/list/set/zset/分布式锁）；当需求涉及缓存读写、TTL 管理、集合运算、排行榜、缓存一致性策略或分布式互斥锁时使用。
+description: "使用 @h-ai/cache 的 Memory/Redis 缓存、TTL、集合、排行榜和锁。"
 ---
 
 # hai-cache
@@ -9,22 +9,20 @@ description: 使用 @h-ai/cache 进行内存或 Redis 缓存操作（kv/hash/lis
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/cache 进行内存或 Redis 缓存操作（kv/hash/list/set/zset/分布式锁）；当需求涉及缓存读写、TTL 管理、集合运算、排行榜、缓存一致性策略或分布式互斥锁时使用。 |
-| 适用场景 | 当任务与 `hai-cache` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 模块配置、类型化业务参数、依赖初始化状态和目标运行环境 |
-| 输出 | 符合模块公共 API 的实现或示例；业务结果使用 HaiResult，并同步必要测试与文档 |
-| 限制 | 遵守 init → use → close 生命周期与运行环境边界；不绕过类型、授权、输入校验或敏感信息保护 |
+| 能力 | 使用 @h-ai/cache 的 Memory/Redis 缓存、TTL、集合、排行榜和锁 |
+| 适用场景 | 缓存读写、过期策略或共享资源互斥 |
+| 输入 | CacheConfigInput、key/value、TTL、每次获锁的唯一 owner |
+| 输出 | 缓存和锁操作的 HaiResult，获锁 data 为 boolean |
+| 限制 | 仅服务端；Memory 不跨节点。release/extend 携带本次 owner，避免锁过期后误操作新持有者。 |
 
 > `@h-ai/cache` 提供统一缓存接口，支持 Memory 与 Redis 后端，包含 KV / Hash / List / Set / ZSet / 分布式锁 六类操作。
 
----
+内存 KV 在到期时间点即失效。整数计数器拒绝 null/boolean/array、非整数增量和安全整数溢出，失败不修改原值；Hash 的 `__proto__` / `constructor` 名称按普通字段保留。
 
 ## 运行环境
 
 > ⚠️ **服务端模块（Node.js only）。** 浏览器端无需直接操作缓存，由服务端模块（如 IAM、Scheduler）内部使用。
 
----
-
 ## 适用场景
 
 - 缓存热点数据减少数据库查询
@@ -34,8 +32,6 @@ description: 使用 @h-ai/cache 进行内存或 Redis 缓存操作（kv/hash/lis
 - 排行榜（ZSet）与队列（List）
 - 分布式锁（多节点部署互斥控制）
 
----
-
 ## 使用步骤
 
 ### 1. 配置
@@ -66,8 +62,6 @@ await cache.close()
 
 `cache.config` 返回的是脱敏后的配置快照；Redis `password` / `url` 等敏感值不会原样暴露给日志或调试输出。
 
----
-
 ## 核心 API
 
 ### KV 操作（`cache.kv`）
@@ -114,32 +108,35 @@ await cache.zset.zadd('rank:daily', { member: 'u1', score: 100 })
 | `extend`   | 续期锁 TTL（支持 owner 验证）              |
 
 ```typescript
-// 获锁（TTL 30 秒，owner 用于标识持有者）
-const acquired = await cache.lock.acquire('my-lock', { ttl: 30, owner: 'node-1' })
+// 每次尝试生成唯一 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', 'node-1')
+    await cache.lock.release('my-lock', owner)
   }
 }
 
-// 续期
-await cache.lock.extend('my-lock', 60, 'node-1')
-
 // 检查
 const locked = await cache.lock.isLocked('my-lock')
 ```
 
 **最佳实践：**
 
-- `owner` 使用稳定的节点标识（如 `nodeId`），不要每次随机生成
+- `owner` 每次获锁尝试唯一，释放/续期复用该值；仅用 nodeId 会使同节点旧任务误释放过期后重新获得的锁
 - 释放锁时传入 `owner` 防止误释放他人锁
 - Memory 后端适合开发/测试；Redis 后端用 Lua 脚本保证 release/extend 原子性
 
----
-
 ## 错误码 — `HaiCacheError`
 
 | 错误码 | code | 说明 |
@@ -154,11 +151,9 @@ const locked = await cache.lock.isLocked('my-lock')
 | `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
 | `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
 
----
-
 ## 常见模式
 
-### 缓存穿透保护
+### 缓存命中与回源（未缓存空值，不防穿透）
 
 ```typescript
 async function getUserCached(userId: string) {
@@ -179,22 +174,24 @@ async function getUserCached(userId: string) {
 
 ```typescript
 const lockKey = 'batch:import'
-const acquired = await cache.lock.acquire(lockKey, { ttl: 60, owner: nodeId })
+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, nodeId)
+    await cache.lock.release(lockKey, owner)
   }
 }
-else {
+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 之前）

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

@@ -1,6 +1,6 @@
 ---
 name: hai-capacitor
-description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全存储、设备信息、推送通知、相机、状态栏），构建 Android/iOS 原生应用；当需求涉及原生 App 开发、Capacitor 集成、安全存储或原生设备功能时使用。
+description: "使用 @h-ai/capacitor 接入原生设备、相机、推送、状态栏和安全 Token 存储。"
 ---
 
 # hai-capacitor
@@ -9,371 +9,26 @@ description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全存储、设备信息、推送通知、相机、状态栏），构建 Android/iOS 原生应用；当需求涉及原生 App 开发、Capacitor 集成、安全存储或原生设备功能时使用。 |
-| 适用场景 | 当任务与 `hai-capacitor` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 用户目标、仓库与运行环境上下文、现有配置、授权范围和质量门禁 |
-| 输出 | 与目标匹配的配置/代码/文档或审查结论，以及可复现的验证结果 |
-| 限制 | 不扩张用户授权，不输出或固化密钥，不跳过失败门禁，不假定外部服务状态 |
+| 能力 | 使用 @h-ai/capacitor 接入原生设备、相机、推送、状态栏和安全 Token 存储 |
+| 适用场景 | Android/iOS 原生壳集成与平台差异处理 |
+| 输入 | Capacitor 配置、原生插件、设备权限和平台状态 |
+| 输出 | 原生操作结果及 TokenStorage 适配器 |
+| 限制 | 区分浏览器与 Android/iOS；安全存储需原生插件，Web 不降级到 localStorage。H5 验证不能代替真机验证。 |
 
-> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合时，Token 仅存于原生安全存储，不回退到 Web `localStorage`。
+## 使用路径
 
----
-
-## 运行环境
-
-> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力；`createCapacitorTokenStorage()` 仅在原生环境持久化 token，纯 Web 不做不安全回退。`capacitor.preferences` 仍可用于普通偏好数据。
-
----
-
-## 适用场景
-
-- Android/iOS 原生应用开发（Svelte 5 + Vite + Capacitor）
-- Token 安全存储（`@aparajita/capacitor-secure-storage`）
-- 设备信息获取（平台、型号、版本）
-- 推送通知注册与监听（FCM / APNs）
-- 原生相机拍照 / 相册选取
-- 状态栏配置（沉浸式、颜色、样式）
-
----
-
-## 使用步骤
-
-### 1. 初始化与关闭
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-// 应用启动时初始化（检测 Capacitor 环境可用性）
-const result = await capacitor.init()
-if (!result.success) {
-  // result.error.code === HaiCapacitorError.NOT_AVAILABLE.code
-  // 非 Capacitor 环境（纯 Web）
-}
-
-// 检查状态
-capacitor.isInitialized // boolean
-capacitor.getPlatform() // 'android' | 'ios' | 'web'
-capacitor.isNative()    // true = 原生 App
-
-// 关闭模块（重置状态）
-await capacitor.close()
-```
-
-### 2. Token 安全存储（与 api-client 配合）
-
-```typescript
-import { apiClient } from '@h-ai/api-client'
-import { createCapacitorTokenStorage } from '@h-ai/capacitor'
-
-await apiClient.init({
-  baseUrl: import.meta.env.PUBLIC_API_BASE,
-  auth: {
-    storage: createCapacitorTokenStorage(),
-  },
-})
-```
-
-`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@aparajita/capacitor-secure-storage`：
-
-- Android → Android KeyStore + 加密 SharedPreferences
-- iOS → Keychain
-- Web → **不回退到 localStorage**；`get*()` 返回 `null`，`set*()` / `clear()` 为 no-op
-
-所有方法内置 try-catch；原生安全存储异常时 get 返回 `null`、set/clear 静默失败并记录日志。
-
-#### Preferences 子操作
+- 先判断平台和插件可用性，复用已有 SPA 入口；原生 UI 变化验证权限拒绝、取消和返回路径。
+- TokenStorage 在原生端使用安全插件；Web 下不伪造持久化成功。
 
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-// 返回 HaiResult<string | null>
-const result = await capacitor.preferences.get('my_key')
-if (result.success) {
-  // result.data — 值或 null
-}
-
-await capacitor.preferences.set('my_key', 'value')
-await capacitor.preferences.remove('my_key')
-```
-
-### 3. 设备信息
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-const info = await capacitor.device.getInfo()
-if (info.success) {
-  info.data.platform    // 'android' | 'ios' | 'web'
-  info.data.model       // 'Pixel 7'
-  info.data.osVersion   // '14'
-  info.data.manufacturer // 'Google'
-  info.data.isVirtual   // false
-}
-
-const version = await capacitor.device.getAppVersion()
-if (version.success) {
-  version.data.version // '1.0.0'
-  version.data.build   // '42'
-}
-```
-
-### 4. 推送通知
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-// 注册推送（请求权限 + 获取设备 Token）
-const reg = await capacitor.push.register()
-if (reg.success) {
-  // 将 reg.data.token 上报给后端
-  await api.post('/push/register', { token: reg.data.token })
-}
-
-// 监听推送事件（返回 HaiResult 包裹的 async 清理函数）
-const listenResult = await capacitor.push.listen({
-  onReceived: (notification) => {
-    // 前台收到推送
-    // notification: { id, title?, body?, data? }
-  },
-  onActionPerformed: (notification) => {
-    // 用户点击推送
-  },
-})
-
-// 停止监听
-if (listenResult.success) {
-  await listenResult.data()
-}
-```
-
-### 5. 相机
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-const photo = await capacitor.camera.takePhoto({
-  quality: 80,           // 0-100
-  source: 'camera',      // 'camera' | 'photos' | 'prompt'
-  resultType: 'base64',  // 'uri' | 'base64' | 'dataUrl'
-  width: 800,            // 最大宽度（可选）
-  height: 600,           // 最大高度（可选）
-})
-
-if (photo.success) {
-  const imgSrc = `data:image/${photo.data.format};base64,${photo.data.data}`
-}
-```
-
-### 6. 状态栏
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-await capacitor.statusBar.configure({
-  backgroundColor: '#ffffff',
-  style: 'dark',    // 'dark' | 'light' | 'default'（文字颜色）
-  overlay: true,     // 沉浸式
-})
-
-await capacitor.statusBar.hide()
-await capacitor.statusBar.show()
-```
-
----
-
-## 核心 API
-
-| API | 用途 | 返回值 |
-| --- | --- | --- |
-| `capacitor.init()` | 初始化模块（检测环境） | `HaiResult<void>` |
-| `capacitor.close()` | 关闭模块，重置状态 | `Promise<void>` |
-| `capacitor.getPlatform()` | 获取当前平台 | `'android' \| 'ios' \| 'web'` |
-| `capacitor.isNative()` | 是否为原生环境 | `boolean` |
-| `capacitor.isInitialized` | 是否已初始化 | `boolean` |
-| `createCapacitorTokenStorage()` | 创建 Token 存储 | `TokenStorage`（兼容 api-client） |
-| `capacitor.preferences.get(key)` | 安全读取 Preference | `HaiResult<string \| null>` |
-| `capacitor.preferences.set(key, value)` | 安全写入 Preference | `HaiResult<void>` |
-| `capacitor.preferences.remove(key)` | 安全删除 Preference | `HaiResult<void>` |
-| `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.camera.takePhoto(options?)` | 拍照 / 选取图片 | `HaiResult<PhotoResult>` |
-| `capacitor.statusBar.configure(config)` | 配置状态栏 | `HaiResult<void>` |
-| `capacitor.statusBar.show()` | 显示状态栏 | `HaiResult<void>` |
-| `capacitor.statusBar.hide()` | 隐藏状态栏 | `HaiResult<void>` |
-
----
-
-## 错误码 — `HaiCapacitorError`
-
-| 错误码                                       | code                   | 说明                 |
-| -------------------------------------------- | ---------------------- | -------------------- |
-| `HaiCapacitorError.INIT_FAILED`              | `hai:capacitor:001`    | 初始化失败           |
-| `HaiCapacitorError.NOT_AVAILABLE`            | `hai:capacitor:002`    | Capacitor 不可用     |
-| `HaiCapacitorError.INIT_IN_PROGRESS`         | `hai:capacitor:003`    | 正在初始化中         |
-| `HaiCapacitorError.NOT_INITIALIZED`          | `hai:capacitor:010`    | 模块未初始化         |
-| `HaiCapacitorError.PREFERENCES_GET_FAILED`   | `hai:capacitor:011`    | Preferences 读取失败 |
-| `HaiCapacitorError.PREFERENCES_SET_FAILED`   | `hai:capacitor:012`    | Preferences 写入失败 |
-| `HaiCapacitorError.PREFERENCES_REMOVE_FAILED`| `hai:capacitor:013`    | Preferences 删除失败 |
-| `HaiCapacitorError.DEVICE_INFO_FAILED`       | `hai:capacitor:020`    | 获取设备信息失败     |
-| `HaiCapacitorError.APP_VERSION_FAILED`       | `hai:capacitor:021`    | 获取应用版本失败     |
-| `HaiCapacitorError.PUSH_REGISTER_FAILED`     | `hai:capacitor:030`    | 推送注册失败         |
-| `HaiCapacitorError.PUSH_LISTEN_FAILED`       | `hai:capacitor:031`    | 推送监听失败         |
-| `HaiCapacitorError.CAMERA_FAILED`            | `hai:capacitor:040`    | 拍照/相册失败        |
-| `HaiCapacitorError.STATUS_BAR_FAILED`        | `hai:capacitor:050`    | 状态栏配置失败       |
-
----
-
-## 常见模式
-
-### Mobile App 标准初始化
-
-```typescript
-// src/lib/capacitor.ts
-import { capacitor } from '@h-ai/capacitor'
-
-export async function initCapacitor() {
-  const result = await capacitor.init()
-  if (!result.success) {
-    return
-  }
-
-  if (capacitor.isNative()) {
-    await capacitor.statusBar.configure({
-      backgroundColor: '#ffffff',
-      style: 'light',
-      overlay: false,
-    })
-  }
-}
-```
-
-```svelte
-<!-- src/App.svelte -->
-<script lang='ts'>
-  import { onMount } from 'svelte'
-  import { initCapacitor } from './lib/capacitor'
-
-  onMount(() => { initCapacitor() })
-</script>
-```
-
-### SPA 模式配置（必需）
-
-Capacitor 应用使用 Vite 构建 SPA，并让原生壳读取 `dist`：
-
-```typescript
-// capacitor.config.ts
-import type { CapacitorConfig } from '@capacitor/cli'
-
-const config: CapacitorConfig = {
-  appId: 'com.example.app',
-  appName: 'Example App',
-  webDir: 'dist',
-}
-
-export default config
-```
-
-### Token 存储 + 认证流程
-
-```typescript
-// src/lib/api.ts
-import { apiClient } from '@h-ai/api-client'
-import { createCapacitorTokenStorage } from '@h-ai/capacitor'
-
-export async function initApi() {
-  return apiClient.init({
-    baseUrl: `${import.meta.env.PUBLIC_API_BASE}/api/v1`,
-    auth: {
-      storage: createCapacitorTokenStorage(),
-    },
-  })
-}
-
-export { apiClient }
-```
-
-### 推送通知完整流程
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-export async function setupPush() {
-  if (!capacitor.isNative()) {
-    return
-  }
-
-  const reg = await capacitor.push.register()
-  if (!reg.success) {
-    return
-  }
-
-  // 上报 Token 给后端
-  await api.post('/push/register', {
-    token: reg.data.token,
-    platform: capacitor.getPlatform(),
-  })
-
-  // 监听推送
-  const listenResult = await capacitor.push.listen({
-    onReceived: (n) => {
-      // 前台通知处理
-    },
-    onActionPerformed: (n) => {
-      // 用户点击跳转
-    },
-  })
-}
-```
-
-### 拍照上传
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-async function captureAndUpload() {
-  const photo = await capacitor.camera.takePhoto({
-    source: 'camera',
-    resultType: 'base64',
-    quality: 80,
-    width: 1024,
-  })
-
-  if (!photo.success) {
-    return
-  }
-
-  // 上传 base64 给后端
-  await api.post('/files/upload', {
-    data: photo.data.data,
-    format: photo.data.format,
-  })
-}
-```
-
----
-
-## 插件依赖
-
-| 插件 | 类型 | 用于 |
-| --- | --- | --- |
-| `@capacitor/core` | peerDependency（必需） | 核心运行时 |
-| `@aparajita/capacitor-secure-storage` | 可选 peerDependency（原生 token 存储必需） | `createCapacitorTokenStorage()` |
-| `@capacitor/preferences` | peerDependency（必需） | `capacitor.preferences.*` 普通偏好数据 |
-| `@capacitor/device` | 可选 | `getDeviceInfo()` |
-| `@capacitor/app` | 可选 | `getAppVersion()` |
-| `@capacitor/push-notifications` | 可选 | `registerPush()` / `listenPush()` |
-| `@capacitor/camera` | 可选 | `takePhoto()` |
-| `@capacitor/status-bar` | 可选 | `configureStatusBar()` / `show/hide` |
-
-可选插件未安装时，对应 API 调用会返回 `err`（动态 import 失败被 catch）。
-
----
+## 按需参考
 
-## 相关 Skills
+详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
 
-- `hai-api-client`：HTTP 客户端（Token 管理依赖 capacitor 存储）
-- `hai-iam`：认证流程（登录获取 Token → 存储到 Capacitor）
-- `hai-ui`：移动端 UI 组件（SafeArea、BottomNav 等）
+- 运行环境
+- 适用场景
+- 使用步骤
+- 核心 API
+- 错误码 — `HaiCapacitorError`
+- 常见模式
+- 插件依赖
+- 相关 Skills