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

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

@@ -0,0 +1,352 @@
+# hai-capacitor — 详细用法
+
+从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
+
+> `@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）。
+
+## 相关 Skills
+
+- `hai-api-client`：HTTP 客户端（Token 管理依赖 capacitor 存储）
+- `hai-iam`：认证流程（登录获取 Token → 存储到 Capacitor）
+- `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 的「原生交付与验收」章节。

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

@@ -1,24 +1,30 @@
 ---
 name: hai-ci
-description: 设计和维护 hai-framework 应用仓库的 CI/CD、GitHub Actions、质量门禁、secret scan 与 workflow 安全；当需求涉及 CI、GitHub Actions、required checks、泄漏扫描或 release workflow 编排时使用。
+description: "维护 hai 应用的 CI/CD、GitHub Actions、质量门禁和凭据泄漏扫描。"
 ---
 
 # hai-ci — CI/CD 与质量门禁规范
 
 ## 能力契约
 
+框架完整质量门禁在 Node.js 22.12.0（声明的最低版本）执行；升级 engines 时同步 CI、README 和脚手架，不能只在更高版本通过后宣称最低版本通过。
+
+框架发布通过实际 npm 精确版本和 GitHub Release 判断完成，不能只看 tag。部分失败重跑原提交，只补发缺失包；npm 全部成功后再建 tag/Release。查询异常与 404 必须区分，tag 指向其他提交时停止补发，禁止将新源码混入旧版本。
+
+Turbo 的 `build.env` 必须列出影响产物的变量；框架包含容器构建开关、E2E 构建模式及 PUBLIC/VITE/TAURI 前缀，共享 tsup 配置也纳入依赖。Docker/Testcontainers 连接变量通过测试任务透传。验证缓存须切换变量检查哈希和真实产物，不能只检查配置文本。
+
+框架仓库发布验收使用 `pnpm test:release-local`；其 E2E 与 CI 共用根 `pnpm e2e`，覆盖 CLI 和全部 Web 应用，不能缩减为仅 Admin Console。应用仓库应在自己的根 E2E 命令集中维护所有端到端入口。容器和原生验收须独立记录实际结果。
+
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 设计和维护 hai-framework 应用仓库的 CI/CD、GitHub Actions、质量门禁、secret scan 与 workflow 安全；当需求涉及 CI、GitHub Actions、required checks、泄漏扫描或 release workflow 编排时使用。 |
-| 适用场景 | 当任务与 `hai-ci` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 用户目标、仓库与运行环境上下文、现有配置、授权范围和质量门禁 |
-| 输出 | 与目标匹配的配置/代码/文档或审查结论，以及可复现的验证结果 |
-| 限制 | 不扩张用户授权，不输出或固化密钥，不跳过失败门禁，不假定外部服务状态 |
+| 能力 | 维护 hai 应用的 CI/CD、GitHub Actions、质量门禁和凭据泄漏扫描 |
+| 适用场景 | 应用 CI/CD 和质量门禁维护 |
+| 输入 | 现有 workflow、package scripts、权限和发布策略 |
+| 输出 | 可执行工作流与检查结果 |
+| 限制 | 默认验证真实 npm 依赖；最小 workflow 权限，不向不可信 PR 暴露 secret，未经授权不发布。 |
 
 > 面向 AI 助手和团队成员的仓库自动化指南。目标是让每个 PR 都能被机器稳定验证，同时避免把 secrets 暴露给不可信 PR 或第三方 Action。
 
----
-
 ## 适用场景
 
 - 新增或修改 `.github/workflows/**`
@@ -29,8 +35,6 @@ description: 设计和维护 hai-framework 应用仓库的 CI/CD、GitHub Action
 
 不负责：PR 人工审查流程（用 `hai-pr-review`）、测试用例设计（用 `hai-app-tests`）、代码质量审查（用 `hai-app-review`）、云资源开通与应用部署 API（用 `hai-deploy`）。
 
----
-
 ## 核心原则
 
 1. **确定性检查优先**：CI 只负责可重复的机器检查；测试内容设计交给 `hai-app-tests`，代码规范判断交给 `hai-app-review`。
@@ -40,8 +44,6 @@ description: 设计和维护 hai-framework 应用仓库的 CI/CD、GitHub Action
 5. **先轻后重**：核心 CI 必须稳定；E2E、发布、安全深扫可以拆成 manual/nightly 或独立 workflow。
 6. **可追溯**：workflow 改动必须说明触发条件、权限、缓存、失败路径和验证命令。
 
----
-
 ## 标准 CI 工作流
 
 ### PR / main 基础质量门禁
@@ -70,8 +72,6 @@ pnpm build
 - 本地联调使用 `framework:use:local` / `framework:watch`，但不要让默认 PR CI 隐式依赖本机路径。
 - 需要验证本地 framework 改动时，创建显式的 sync/drift check 或双仓联动 PR。
 
----
-
 ## GitHub Actions 安全清单
 
 - [ ] workflow 顶层声明 `permissions`
@@ -83,8 +83,6 @@ pnpm build
 - [ ] release workflow 独立提权，只在 main/tag/manual 触发
 - [ ] 失败日志可定位，不吞错、不 `|| true` 掩盖核心质量门禁
 
----
-
 ## Secret scan 策略
 
 ### 推荐
@@ -99,8 +97,6 @@ pnpm build
 - ❌ 把完整密钥关键词列表传给未知第三方 action
 - ❌ 为了通过扫描而删除失败证据或扩大忽略范围
 
----
-
 ## Workflow 变更交付清单
 
 修改 CI/CD 时，PR 描述必须包含：
@@ -111,8 +107,6 @@ pnpm build
 - 安全影响：是否读取 secrets、是否写仓库、是否评论 PR
 - 验证方式：本地命令或 GitHub Actions dry run 结果
 
----
-
 ## 相关 Skills
 
 - `hai-build` — 项目结构与质量门禁总览
@@ -120,3 +114,6 @@ pnpm build
 - `hai-pr-review` — PR 审查与 AI Review 策略
 - `hai-deploy` — 应用部署与云服务开通
 - `hai-framework-sync` — hai-framework 与应用仓库同步策略
+
+发布完成判定始终查询根版本的 npm 包；发布 job 同步包版本但不提交，标签固定指向触发质量验收的源码提交。发布成功后由独立 job 提交版本同步；完整重跑即使无需补发也会执行同步，远端已存在相同内容时成功退出，分支有新源码时拒绝覆盖并要求从最新 main 重跑。
+原生交付必须单独执行 Tauri/Gradle/Xcode 打包，并在目标 OS/设备验证安装启动、登录/退出、重启会话、安全 TokenStore、真实 API 域名与覆盖升级。Web 构建/E2E 不代替原生验收。保存提交、包 hash、平台/工具链及逐项结果；缺平台写未验证，禁止静默 skip。hai-framework 仓库参考 `.github/workflows/native.yml` 与 desktop-app / mobile-app README 的「原生交付与验收」章节。