@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

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,377 +1,37 @@
 ---
 name: hai-capacitor
-description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全存储、设备信息、推送通知、相机、状态栏），构建 Android/iOS 原生应用；当需求涉及原生 App 开发、Capacitor 集成、安全存储或原生设备功能时使用。
+description: "在 Android/iOS 应用中接入 @h-ai/capacitor 设备、相机、推送与安全 Token 存储，处理 Web/原生差异。"
 ---
 
 # hai-capacitor
 
-> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合实现 App 端 Token 安全存储。
+## 能力契约
 
----
-
-## 运行环境
-
-> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力，纯 Web 环境下部分功能退化（如 Preferences 退化为 localStorage）。
-
----
-
-## 适用场景
-
-- Android/iOS 原生应用开发（SvelteKit + Capacitor）
-- Token 安全存储（Capacitor Preferences → SharedPreferences / UserDefaults）
-- 设备信息获取（平台、型号、版本）
-- 推送通知注册与监听（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 { api } from '@h-ai/api-client'
-import { createCapacitorTokenStorage } from '@h-ai/capacitor'
-
-await api.init({
-  baseUrl: import.meta.env.PUBLIC_API_BASE,
-  auth: {
-    storage: createCapacitorTokenStorage(),
-    refreshUrl: '/api/v1/auth/refresh',
-  },
-})
-```
-
-`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@capacitor/preferences`：
-
-- Android → SharedPreferences（应用沙盒）
-- iOS → UserDefaults
-- Web → localStorage（退化，建议仅原生端使用）
-
-所有方法内置 try-catch，Preferences 异常时 get 返回 `null`、set/clear 静默失败并记录日志。
-
-#### Preferences 子操作
-
-```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,     // 沉浸式
-})
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 使用 @h-ai/capacitor 接入原生设备、相机、推送、状态栏和安全 Token 存储 |
+| 适用场景 | Android/iOS 原生壳集成与平台差异处理 |
+| 输入 | Capacitor 配置、原生插件、设备权限和平台状态 |
+| 输出 | 原生操作结果及 TokenStorage 适配器 |
+| 限制 | 区分浏览器与 Android/iOS；安全存储需原生插件，Web 使用 httpOnly Cookie/内存认证，不降级到 localStorage。H5 验证不能代替真机验证。 |
 
-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.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`    | 状态栏配置失败       |
-
----
-
-## 常见模式
-
-### Android 应用标准初始化
-
-```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/routes/+layout.svelte -->
-<script lang="ts">
-  import { onMount } from 'svelte'
-  import { initCapacitor } from '$lib/capacitor'
-
-  onMount(() => { initCapacitor() })
-</script>
-```
-
-### SPA 模式配置（必需）
-
-Capacitor 应用必须使用 SPA 模式：
-
-```typescript
-// src/routes/+layout.ts
-export const prerender = true
-export const ssr = false
-```
-
-```javascript
-// svelte.config.js
-import adapter from '@sveltejs/adapter-static'
-
-const config = {
-  kit: {
-    adapter: adapter({
-      pages: 'build',
-      assets: 'build',
-      fallback: 'index.html',
-    }),
-  },
-}
-```
+- 先判断平台和插件可用性，复用已有 SPA 入口；原生 UI 变化验证权限拒绝、取消和返回路径。
+- TokenStorage 在原生端使用安全插件；Web/插件不可用或存储失败时拒绝 Promise。调用方处理 setTokens/clear 失败并释放 loading；clear 的实例内屏蔽不替代服务端撤销。
+- 原生打包前确认公开 API 地址的运行配置入口；fullstack App 使用 `public/runtime-config.js`，构建不会读取部署环境文件。这里只放公开地址，不能放 Token 或密钥。
 
-### Token 存储 + 认证流程
+## 按需参考
 
-```typescript
-// src/lib/api.ts
-import { api } from '@h-ai/api-client'
-import { createCapacitorTokenStorage } from '@h-ai/capacitor'
-
-export async function initApi() {
-  return api.init({
-    baseUrl: `${import.meta.env.PUBLIC_API_BASE}/api/v1`,
-    auth: {
-      storage: createCapacitorTokenStorage(),
-      refreshUrl: '/auth/refresh',
-    },
-  })
-}
-
-export { api }
-```
-
-### 推送通知完整流程
-
-```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（必需） | 核心运行时 |
-| `@capacitor/preferences` | peerDependency（必需） | Token 存储 |
-| `@capacitor/device` | 可选 | `getDeviceInfo()` |
-| `@capacitor/app` | 可选 | `getAppVersion()` |
-| `@capacitor/push-notifications` | 可选 | `registerPush()` / `listenPush()` |
-| `@capacitor/camera` | 可选 | `takePhoto()` |
-| `@capacitor/status-bar` | 可选 | `configureStatusBar()` / `show/hide` |
-
-可选插件未安装时，对应 API 调用会返回 `err`（动态 import 失败被 catch）。
-
----
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
-## 相关 Skills
+- 运行环境
+- 适用场景
+- 使用步骤
+- 核心 API
+- 错误码 — `HaiCapacitorError`
+- 常见模式
+- 插件依赖
+- 相关 Skills
 
-- `hai-api-client`：HTTP 客户端（Token 管理依赖 capacitor 存储）
-- `hai-iam`：认证流程（登录获取 Token → 存储到 Capacitor）
-- `hai-ui`：移动端 UI 组件（SafeArea、BottomNav 等）
+推送仅在实际原生平台调用插件。`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 权限、注册与反复挂载验收。