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

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

@@ -0,0 +1,358 @@
+# hai-capacitor — 详细用法
+
+从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
+
+> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块。设备、推送等领域操作返回 `HaiResult<T>`；TokenStorage 是直接 Promise 适配器，失败会拒绝。与 `@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 配合）
+
+先复用应用已有的 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: apiBase,
+  auth: {
+    storage: createCapacitorTokenStorage(),
+  },
+})
+```
+
+`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@aparajita/capacitor-secure-storage`：
+
+- Android → Android KeyStore + 加密 SharedPreferences
+- iOS → Keychain
+- Web → **不提供原生存储回退**；适配器方法拒绝 Promise，Web 入口选择 api-client 的 Cookie/内存存储
+
+读取、保存与删除失败均拒绝 Promise。调用方通过 `apiClient.auth` 串行更新凭据并捕获 setTokens/clear 失败；界面释放 loading，退出失败仍清理内存身份并提示错误。`clear()` 开始立即屏蔽本实例两类旧凭据，等待两个删除都结束；即使失败也保持屏蔽，相应 key 成功写入后重新开放。屏蔽不等于持久删除，跨实例/重启撤销仍依赖服务端退出/撤销会话。插件恢复后可以在同一实例重试，不缓存永久失败状态。
+
+任一 key 写入失败也会屏蔽整对凭据，避免 access 已落盘而 refresh 保存失败后的半完成登录。登录/注册保存失败后尝试 `auth.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<HaiResult<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<PushCleanup>`（cleanup 返回 `Promise<HaiResult<void>>`） |
+| `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 原生壳读取 `webDir` 指定的静态产物。纯 Vite 模板默认为 `dist`；SvelteKit 项目需配置静态适配器，输出可能是 `build`。构建器、容器与 `webDir` 必须一致，以下是 Vite 示例：
+
+```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(apiBase: string) {
+  return apiClient.init({
+    baseUrl: apiBase,
+    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 的「原生交付与验收」章节。
+
+推送仅在实际原生平台调用插件。`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-change-plan/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: hai-change-plan
+description: "框架增删改涉及数据结构、配置、核心流程或模块边界时，先说明方案与影响，等待用户决定后实施。"
+---
+
+# 变更影响与方案确认
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 将框架变更整理成维护者看得懂、能作决定的方案，并跟踪同步与验证 |
+| 适用场景 | 新增、修改、删除框架功能，或修复中发现需要改变结构、配置、核心流程、模块边界 |
+| 输入 | 用户目标、当前实现与调用方、现有配置和文档、已确认方案及授权 |
+| 输出 | 简明方案、具体影响、用户决定、同步清单和验证结果 |
+| 限制 | 未确认的重要变更先停在方案；普通业务私有实现不因此扩大成框架改造，已确认且未扩大的方案不重复确认 |
+
+## 何时先提方案
+
+发现以下任一实际变化，在修改对应实现、配置或模板之前说明方案，**等待用户明确同意推进**：
+
+- `type`、`interface`、Schema 等结构的字段、形状或语义改变，包括新增、删除及会改变执行方式的内部结构。
+- 模块配置或环境变量的名称、位置、默认值、可选/必填、校验、优先级、安全含义改变。
+- 初始化/关闭、请求处理、认证授权、数据读写、并发重试、部署/恢复等核心流程改变。
+- 模块职责、依赖关系、公开入口、调用方式或跨模块返回值/错误契约改变。
+
+先查源码、调用方和运行证据，给出足以决定的具体方案；不要只说“重构一下”“优化架构”。只读分析、现状复现及不改变上述边界的准备工作可以继续，不能先落地再要求追认。已有“修复”“按最佳方案”等一般授权，不代替尚未说明的重要方案；用户已明确指定并同意的具体方案无需重问。执行中出现新的重要影响，只确认新增部分。
+
+纯格式、注释纠错、翻译修正，或不改变上述结构与边界的内部修复，按已有授权继续；先简述实际影响即可。拿不准时说明具体不确定项，不为假设风险引入审批。
+
+## 怎样说明
+
+先用一两句话说明结论，再按实际复杂度交代：
+
+1. **为什么改、改成什么**：当前场景有什么问题，使用前后有什么变化。
+2. **影响谁**：涉及哪些模块、应用、CLI 模板和调用方；旧配置、数据、部署是否需要调整。
+3. **如何同步与验证**：需要更新哪些文档、注释、示例与测试；如何确认生效，失败如何恢复。
+4. **请用户决定**：给出推荐方案；确有取舍时列少量可行选项，并说明代价。
+
+技术名词和必要路径用于支持判断，避免堆文件清单与过程日志。简单变化一小段即可，复杂变化再分层。区分已确认事实、待验证假设、拟实施及已完成；明确哪些部分尚未获准，不把等待写成完成。
+
+## 确认后成套维护
+
+在当前任务记录中保存决定和影响范围，不额外创建重复台账。按[沟通与同步维护](../hai-app-create/collaboration.md)逐项核对相关 README（已有中英日版同步）、环境变量与模块配置项、`docs/` 使用说明、GitHub Pages 的内容源/导航/图片、注释与类型说明、调用方、测试和 CLI 模板。每项注明已同步，或不适用及原因。
+
+GitHub Pages 由文档源构建时修改源文件，不手改生成产物；配置示例按真实默认值与覆盖顺序核对，界面截图来自当前实际操作。按受影响范围验证，报告实际执行、复用与未验证边界。若实现与获准方案不同，先说明差异并重新确认新增影响。

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

@@ -0,0 +1,114 @@
+---
+name: hai-ci
+description: "维护 hai 应用的 CI/CD、GitHub Actions、质量门禁和凭据泄漏扫描。"
+---
+
+# hai-ci — CI/CD 与质量门禁规范
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 维护 hai 应用的 CI/CD、GitHub Actions、质量门禁和凭据泄漏扫描 |
+| 适用场景 | 应用 CI/CD 和质量门禁维护 |
+| 输入 | 现有 workflow、package scripts、权限和发布策略 |
+| 输出 | 可执行工作流与检查结果 |
+| 限制 | 默认验证真实 npm 依赖；最小 workflow 权限，不向不可信 PR 暴露 secret，未经授权不发布。 |
+
+> 面向 AI 助手和团队成员的仓库自动化指南。目标是让每个 PR 都能被机器稳定验证，同时避免把 secrets 暴露给不可信 PR 或第三方 Action。
+
+## 适用场景
+
+- 新增或修改 `.github/workflows/**`
+- 配置 `pnpm typecheck`、`pnpm lint`、`pnpm test`、`pnpm build`、E2E
+- 调整 secret scan、依赖扫描、安全扫描、release workflow 编排
+- 设计 required checks 的 CI 状态、workflow 权限、触发条件与 concurrency
+- 排查 CI flaky、缓存、矩阵构建或执行顺序问题
+
+不负责：PR 人工审查流程（用 `hai-pr-review`）、测试用例设计（用 `hai-app-tests`）、代码质量审查（用 `hai-app-review`）、云资源开通与应用部署 API（用 `hai-deploy`）。
+
+## 核心原则
+
+1. **确定性检查优先**：CI 只负责可重复的机器检查；测试内容设计交给 `hai-app-tests`，代码规范判断交给 `hai-app-review`。
+2. **最小权限**：默认 `permissions: contents: read`，只有 release、comment、pages 等明确场景才提升权限。
+3. **PR 不使用 secrets**：来自 fork 或不可信分支的 PR 不得运行读取 secrets 的 workflow。
+4. **禁用高风险组合**：禁止 `pull_request_target` + checkout PR 代码 + secrets/写权限。
+5. **按风险选择门禁**：核心 CI 必须稳定；E2E、发布、安全深扫可拆为独立 workflow，但关键权限/数据完整性路径不能因不稳定而长期没有验收。
+6. **可追溯**：workflow 改动必须说明触发条件、权限、缓存、失败路径和验证命令。
+
+## 标准 CI 工作流
+
+### PR / main 基础质量门禁
+
+建议顺序：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm lint
+pnpm build
+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 策略
+
+- 若 E2E 稳定且耗时可控，可作为 required check。
+- 若 E2E 依赖浏览器、服务、密钥或容易 flaky，先放到 `workflow_dispatch` / `schedule` / 独立 job。
+- 应用级 E2E 使用：`pnpm --filter <app> test:e2e`。
+
+### hai-framework 依赖策略
+
+- CI 默认使用 `pnpm-lock.yaml` 中的 npm/published 依赖，确保与真实安装环境一致。
+- 本地联调先查项目是否定义 `framework:use:local` / `framework:watch`；没有时按本项目 README 操作，不要让默认 PR CI 隐式依赖本机路径。
+- 需要验证本地 framework 改动时，创建显式的 sync/drift check 或双仓联动 PR。
+
+## GitHub Actions 安全清单
+
+- [ ] workflow 顶层声明 `permissions`
+- [ ] PR workflow 使用 `pull_request`，不用 `pull_request_target`
+- [ ] 不在 PR workflow 中读取 secrets
+- [ ] 第三方 action 固定版本；高风险 action 优先改为本地脚本或官方 action
+- [ ] 使用 `concurrency` 取消同分支旧任务
+- [ ] 不在 CI 日志打印 token、cookie、连接串、`.env` 内容
+- [ ] release workflow 独立提权，只在 main/tag/manual 触发
+- [ ] 失败日志可定位，不吞错、不 `|| true` 掩盖核心质量门禁
+
+## Secret scan 策略
+
+### 推荐
+
+- 用无 secrets 的高置信正则扫描常见密钥形态。
+- 技能/文档与配置同样可能泄漏凭据，不按目录整体排除；只对已确认的测试占位和固定误报做有依据的最小忽略，检查修改是否掩盖真实密钥。
+- 需要私有关键词表时，仅在受信任分支的独立 workflow 中运行，不对 fork PR 暴露。
+
+### 禁止
+
+- ❌ `pull_request_target` 中 checkout 不可信 PR 代码后读取 `secrets.*`
+- ❌ 把完整密钥关键词列表传给未知第三方 action
+- ❌ 为了通过扫描而删除失败证据或扩大忽略范围
+
+## Workflow 变更交付清单
+
+修改 CI/CD 时，PR 描述必须包含：
+
+- 触发条件：`pull_request` / `push` / `workflow_dispatch` / `schedule`
+- 权限：顶层和 job 级 `permissions`
+- 执行命令：每个 job 的核心命令
+- 安全影响：是否读取 secrets、是否写仓库、是否评论 PR
+- 验证方式：本地命令或 GitHub Actions dry run 结果
+
+## 相关 Skills
+
+- `hai-build` — 项目结构与质量门禁总览
+- `hai-app-tests` — Vitest / Playwright 测试规范
+- `hai-pr-review` — PR 审查与 AI Review 策略
+- `hai-deploy` — 应用部署与云服务开通
+- `hai-framework-sync` — 框架版本升级、差异分析与 npm/本地同步
+
+涉及发布时按本应用实际 registry/镜像/部署目标核验精确版本与提交，不以 tag 或 CI 绿灯代替发布产物；未经授权不发布。原生/容器交付按当前项目入口单独构建与启动验收，保存产物、平台和行为证据；缺平台写未验证，Web E2E 不代替原生验收。