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

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,373 +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 子操作
-
-```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）。
-
----
+- 先判断平台和插件可用性，复用已有 SPA 入口；原生 UI 变化验证权限拒绝、取消和返回路径。
+- TokenStorage 在原生端使用安全插件；Web 下不伪造持久化成功。
 
-## 相关 Skills
+## 按需参考
 
-- `hai-api-client`：HTTP 客户端（Token 管理依赖 capacitor 存储）
-- `hai-iam`：认证流程（登录获取 Token → 存储到 Capacitor）
-- `hai-ui`：移动端 UI 组件（SafeArea、BottomNav 等）
+详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
 
-原生交付必须单独执行 Tauri/Gradle/Xcode 打包，并在目标 OS/设备验证安装启动、登录/退出、重启会话、安全 TokenStore、真实 API 域名与覆盖升级。Web 构建/E2E 不代替原生验收。保存提交、包 hash、平台/工具链及逐项结果；缺平台写未验证，禁止静默 skip。hai-framework 仓库参考 `.github/workflows/native.yml` 与 desktop-app / mobile-app README 的「原生交付与验收」章节。
+- 运行环境
+- 适用场景
+- 使用步骤
+- 核心 API
+- 错误码 — `HaiCapacitorError`
+- 常见模式
+- 插件依赖
+- 相关 Skills