@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-version-diff/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: rnoh-lib-version-diff
+description: >-
+  用于 RN 鸿蒙三方库升级适配：版本分析与差异生成。
+  从鸿蒙化仓库 git URL 出发，自动提取上游基线版本、查询 npm 最新版本、判定升级类型，
+  通过两阶段 diff 流程（全量生成 + AI 筛选精简）生成 JS 层接口差异文档并输出结构化适配检查清单。
+  当用户需要分析某个 RN 三方库的鸿蒙化版本与上游最新版本的差距、判断是否需要原生适配、
+  对比上游两个版本之间的 JS 接口变更时使用。典型场景：用户提供了鸿蒙化仓库的 git URL
+  （如 gitcode.com/CPF-RN/rntpc_xxx），想升级到新的 RNOH 版本（如 0.84），
+  需要先搞清楚当前鸿蒙化基线版本是多少、上游最新版本是多少、JS 层接口有哪些变更。
+  也适用于：使用 devecocli docs search 核查鸿蒙 API 可行性、生成版本对比报告
+  供后续代码适配阶段使用。
+license: MIT
+compatibility: 需要 node、npm、tar、diff；仅需 npm registry 访问；鸿蒙 API 核查需 devecocli CLI。注意：脚本会对 diff 做行为验证（PATH 中 DevEco toolchains 等不兼容 diff 会被自动跳过），可用环境变量 DIFF_BIN 指定绝对路径
+allowed-tools: Bash Read Grep Glob Write
+metadata:
+  version: "1.0.0"
+  phase: "1-of-4"
+---
+
+# RN 鸿蒙三方库版本分析与差异生成
+
+分析 RN 鸿蒙三方库的上游版本变更。通过对比两个版本的 JS 层接口契约（导出、TurboModule Spec），判断鸿蒙侧是否需要原生适配。
+
+## 目录结构
+
+```
+{SKILL_DIR}/
+├── SKILL.md
+├── scripts/
+│   ├── detect-upstream-version.js   # 提取基线版本 + 查询 npm 最新版本
+│   └── generate-diff.js             # 两阶段 diff 生成（全量 + 精简）
+│     # 注: 接口扫描功能由 ../../../MCP/scripts/rn-scan-exports.cjs 提供
+├── references/
+│   ├── OHOS_API_LOOKUP.md           # 鸿蒙 API 核查流程（devecocli docs search）
+│   ├── OHOS_ADAPTATION.md           # 鸿蒙化适配判断规则
+│   └── script-reference.md          # 脚本参数与用法详解
+└── templates/
+    └── report-template.md           # 版本分析报告模板
+```
+
+## 何时使用
+
+- 用户提供了一个 RN 鸿蒙三方库的 git 仓库 URL，想要升级到新的 RNOH 版本。
+- 用户想知道某个鸿蒙化三方库当前基于上游哪个版本、上游最新版本是多少、差距多大。
+- 用户需要判断是否需要原生（ETS/C++）适配，还是只需合并 JS 代码 + 重新 codegen。
+
+## 最小必要输入
+
+- **必要**：鸿蒙化仓库的 git URL（如 `https://gitcode.com/CPF-RN/rntpc_lottie-turbo-react-native`）
+- **必要**：目标 RNOH 版本号（如 `0.84`），用于确定分支名（通常为 `br_rnoh0.84`）
+- **有帮助**：上游 npm 包名（如不知道会自动推断）
+- **有帮助**：已知的当前基线版本号（如不知道会自动检测）
+
+## 工作流程
+
+```
+Step 1: 提取基线版本 + 查询 npm 最新版本
+Step 2: 升级类型判定（A/B/C）
+Step 3: 检查目标分支是否存在
+Step 4: 两阶段 diff 生成（仅类型 A）
+  Phase 1: 生成全量文件变更清单 + 接口差异分析
+  Phase 2: AI 筛选相关文件 → 生成精简 patch
+Step 5: 鸿蒙 API 核查（仅涉及原生能力时）
+Step 6: 生成版本分析报告
+```
+
+---
+
+## Step 1：提取基线版本
+
+### 如果已指定基线版本和目标版本
+
+直接记录，跳到 Step 2。仅需从 `README.OpenSource` 文件获取上游仓库 URL：
+
+```bash
+# 查看 README.OpenSource 获取 Upstream URL
+cat <鸿蒙化仓库>/README.OpenSource
+```
+
+### 如果未指定基线版本
+
+```bash
+node scripts/detect-upstream-version.js <git-repo-url>
+```
+
+脚本自动完成：解析 git URL → 获取 package.json → 从 `harmony.alias` 匹配上游包名 → 查询 npm registry 获取 `dist-tags.latest`。
+
+**回退方案**：如果脚本输出"未找到匹配的上游版本号"，检查仓库根目录的 `README.OpenSource` 文件——其中包含 `Version Number` 和 `Upstream URL` 字段，比 package.json 依赖列表更可靠（鸿蒙化仓库会用 `@react-native-ohos/` 前缀替换上游包名）。
+
+记录以下信息：基线版本、npm 最新版本、版本状态（落后/最新/超前）、上游仓库 URL。
+
+---
+
+## Step 2：升级类型判定
+
+| 版本状态 | 升级类型 | 后续动作 |
+|----------|----------|----------|
+| 落后 (behind) | **类型 A：上游版本升级 + 框架适配** | 执行 Step 4 |
+| 最新 (latest) | **类型 B：纯框架版本适配** | 跳过 Step 4 |
+| 超前 (ahead) | **类型 C：特殊情况** | 人工排查 |
+
+**核心原则**：只有类型 A 需要生成 diff。类型 B 意味着 JS 层未变更——只需更新 RNOH 框架版本 + 重新 codegen。
+
+---
+
+## Step 3：检查目标分支
+
+```bash
+git ls-remote --heads <鸿蒙化仓库URL>
+```
+
+如果 `br_rnoh0.84` 分支不存在，使用已有的最高版本分支（如 `br_rnoh0.82`）作为起点，在报告中标注需要跨版本升级。
+
+---
+
+## Step 4：两阶段 diff 生成（仅类型 A）
+
+### 版本格式
+
+| 格式 | 示例 | 适用场景 |
+|------|------|----------|
+| `v` + 版本号 | `v7.2.2`, `v7.4.0` | 大多数非 scoped 包 |
+| 纯版本号 | `7.2.2`, `7.4.0` | 部分仓库 |
+| `@scope/name@version` | `@react-native-async-storage/async-storage@3.1.1` | **scoped 包**（`@scope/` 前缀） |
+
+如果不确定有哪些可用版本，通过 npm 查看：
+
+```bash
+npm view <npm包名> versions --json
+```
+
+### Phase 1：生成全量 diff + 接口差异分析
+
+```bash
+node scripts/generate-diff.js \
+  --npm-package <npm包名> \
+  --tgz1 <基线版本号> \
+  --tgz2 <目标版本号> \
+  --output-dir <输出目录>
+```
+
+生成 4 个文件：
+
+| 文件 | 说明 |
+|------|------|
+| `diff_*.patch` | 全量 diff 补丁（仅 JS 层，已排除原生平台代码） |
+| `summary_*.md` | 文件变更摘要（按文件统计增删行数） |
+| `structure_*.md` | 适配分析报告（以接口差异为锚点：接口未变更→只需合并 JS；接口变更→按变更项展开 + 文件计数） |
+| `api-diff_*.md` | 接口差异适配检查清单（每个变更项含 checkbox、方法签名、适配动作） |
+
+其中 `structure_*.md` 和 `api-diff_*.md` 由脚本内部调用 `rn-scan-exports.cjs`（位于 `../../../MCP/scripts/`）对比两个版本的 JS 导出和 TurboModule Spec 自动生成。
+
+**核心逻辑**：如果 JS 层接口未变更 → "无需原生适配，只需合并 JS + codegen"。如果接口变更 → 列出每个变更的方法及其签名作为适配检查项。
+
+### Phase 2：AI 筛选相关文件 → 生成精简 patch
+
+Phase 1 的全量 patch 可能仍包含与适配无关的文件（已删除的包、示例代码、配置文件等）。Phase 2 通过 AI 筛选：
+
+1. **阅读** `structure_*.md` 和 `api-diff_*.md`，理解哪些接口发生了变更
+2. **阅读** `summary_*.md`，查看完整的文件变更列表（路径 + 增删行数）
+3. **AI 判断**：对变更列表中的每个文件，判断是否与接口变更相关：
+   - **包含**：实现变更接口的 JS/TS 源码文件、TurboModule Spec 文件、含 codegenConfig 的 package.json
+   - **排除**：已删除的包、示例代码、文档、CI 配置、构建脚本、原生平台代码
+4. **写入** 筛选后的文件列表到 `relevant-files.txt`（每行一个路径）
+5. **生成精简 patch**：
+
+```bash
+node scripts/generate-diff.js \
+  --npm-package <npm包名> \
+  --tgz1 <基线版本号> \
+  --tgz2 <目标版本号> \
+  --files relevant-files.txt \
+  --output-dir <输出目录>
+```
+
+生成的 `diff_*.patch` 只包含相关文件（通常缩小 70-90%）。
+
+**AI 筛选标准**：
+- 如果 TurboModule Spec 变更 → 包含所有新旧 Spec 文件（看新增了什么、移除了什么）
+- 如果公共接口变更 → 包含定义/实现该接口的文件
+- 如果导出变更 → 包含入口文件（index.ts/tsx）
+- 始终包含含 codegenConfig 变更的 package.json
+- 绝不包含：example/、docs/、.github/、原生平台目录、已删除的包目录
+
+---
+
+## Step 5：鸿蒙 API 核查
+
+当接口变更涉及原生能力（存储、相机、蓝牙等）时，使用 `devecocli docs search` 核查 OHOS API 可行性后再下结论。
+
+```bash
+devecocli docs search "<关键词>" --catalog harmonyos-references --limit 10
+```
+
+完整核查流程见 [references/OHOS_API_LOOKUP.md](references/OHOS_API_LOOKUP.md)。
+
+---
+
+## Step 6：生成版本分析报告
+
+使用 [templates/report-template.md](templates/report-template.md) 模板生成结构化版本分析报告。
+
+**关键要求**：报告的「差异文件位置」章节必须列出所有产出文件的**完整绝对路径**，不可使用相对路径。读者通过该表格即可定位到每个生成文件。
+
+风险等级：
+- 🟢 低风险：仅补丁版本差距，无 breaking change
+- 🟡 中风险：小版本差距，有 API 变更但向后兼容
+- 🔴 高风险：大版本差距，有 breaking change 或原生层重构
+
+适配判断规则见 [references/OHOS_ADAPTATION.md](references/OHOS_ADAPTATION.md)。
+
+---
+
+## 常见边界情况
+
+### detect-upstream-version.js 无法匹配包名
+
+检查仓库根目录的 `README.OpenSource` 文件——其中包含 `Version Number` 和 `Upstream URL` 字段，比 package.json 依赖列表更可靠。
+
+### 文件重命名 / 跨目录移动
+
+脚本不支持 rename 检测。如果上游版本间存在文件移动，diff 会显示为「旧路径删除 + 新路径新增」。通过对比 `summary_*.md` 中删除和新增的文件路径，人工识别文件移动。`structure_*.md` 报告中的文件分类统计也可辅助判断。
+
+### rn-scan-exports.cjs 在 monorepo 中找不到入口文件
+
+如果仓库是 monorepo 结构，`rn-scan-exports.cjs` 可能需要指定子包目录。直接运行：
+
+```bash
+node ../../../MCP/scripts/rn-scan-exports.cjs --compare \
+  <分支1目录>/packages/<包名> \
+  <分支2目录>/packages/<包名> \
+  --output api-diff.md
+```
+
+### devecocli 未安装
+
+尝试 `ohpm install -g @ohos/deveco-cli` 或通过 DevEco Studio 安装。也可使用 MCP 工具 `script_deveco_docs`（如果可用）。
+
+---
+
+## 输出物清单
+
+### 类型 A（上游版本升级 + 框架适配）
+
+1. **版本分析报告**（Markdown）— 版本差距、风险评估、适配检查清单。报告的「差异文件位置」章节须列出所有产出文件的完整绝对路径
+2. **精简 diff patch**（`diff_*.patch`）— 只包含相关 JS 文件，供 code-adapt skill 使用
+3. **接口差异检查清单**（`api-diff_*.md`）— 每个接口变更含 checkbox，指导适配（内容已嵌入报告）
+4. **适配分析报告**（`structure_*.md`）— 接口驱动的分析 + 文件计数（内容已嵌入报告）
+5. **源码目录** — 两个版本的源码导出，供参考
+
+### 类型 B（纯框架版本适配）
+
+1. **版本分析报告** — 版本状态（最新）、RNOH 框架版本对比、codegen 说明
+2. 无 diff/summary/structure 文件（上游未变更）

package/vendor/Server/Skills/rnoh-lib-version-diff/references/OHOS_ADAPTATION.md

@@ -0,0 +1,77 @@
+# 鸿蒙化适配判断规则
+
+上游版本升级后，按以下规则判断鸿蒙侧是否需要同步修改。结合版本差异分析结果，为报告的「鸿蒙化适配分析」章节提供判断依据。
+
+## 文件路径映射
+
+| 上游路径 | 鸿蒙对应 |
+|----------|----------|
+| `src/index.ts(x)` | 同路径 + `Platform.OS === 'harmony'` 分支 |
+| `src/Native*.ts` | 同路径 → codegen → `harmony/**/generated/` |
+| `android/` | `harmony/` ETS TurboModule + C++ Package |
+| `ios/` | `harmony/` ETS TurboModule + C++ Package |
+| `example/android`, `example/ios` | `example/harmony/` |
+
+## 判断矩阵
+
+| 上游变更 | 需鸿蒙适配 | 典型动作 |
+|----------|-----------|----------|
+| 纯 JS 逻辑，无 native 交互 | 通常否 | 合并 JS 即可 |
+| 新增/修改 export API | 是 | 同步 `src/`，检查 harmony 调用 |
+| TurboModule 方法增删改 | 是 | 改 Spec → codegen → ETS/C++ |
+| Android/iOS 权限/生命周期 | 是 | 在 ETS 用 OHOS API 对等实现 |
+| 事件名/NativeEventEmitter 变更 | 是 | 对齐 JS 层 + 原生 emit 事件名 |
+| `package.json` peerDeps 升级 | 待评估 | 查目标 RNOH 版本兼容矩阵 |
+| 仅 README/CHANGELOG | 否 | — |
+| 仅 `.github`/CI | 否 | — |
+
+## RNOH 框架版本适配要点
+
+跨 RNOH 版本升级时（如 0.77 → 0.84）额外检查：
+
+1. **Codegen 版本**：项目 `codegen-lib` script 与目标 RNOH CLI 是否匹配
+2. **TurboModule 架构**：新架构下 Spec 路径、`TurboModuleRegistry` 用法
+3. **Package 基类**：RNOHPackage（新）vs RNPackage（旧）
+4. **Example 壳工程**：`example/harmony/` 中 Package 注册、依赖版本
+5. **HAR 构建**（仅含 native cpp 的库）：变更后是否需要重新打 har 包
+
+## 库类型与流程分支
+
+| 类型 | 判定 | 后续适配流程 |
+|------|------|-------------|
+| `native-harmony` | 有 `harmony/` HAR + TurboModule/Fabric/cpp | 完整流程（codegen + autolinking + HAR） |
+| `js-only-harmony` | 有 `harmony/` 但无 cpp/autolinking | 跳过 HAR/cpp 门禁 |
+| `pure-js` | 无 native 或纯 JS 鸿蒙实现 | 跳过 codegen、autolinking、HAR |
+
+## 升级类型 A：上游版本升级 + 框架适配
+
+当版本状态为"落后"时，需同时处理：
+1. **上游 JS 代码合并** — 应用 diff patch 中的 JS 变更
+2. **TurboModule Spec 同步** — 上游方法增删改时更新 Spec + 重跑 codegen
+3. **鸿蒙原生层适配** — Android/iOS 原生变更需在 `harmony/` 中对等实现
+4. **RNOH 框架版本适配** — 跨版本时验证 API 兼容性 + 重新 codegen
+
+## 升级类型 B：纯框架版本适配
+
+当版本状态为"最新"时，上游 JS 代码无差异，只需：
+1. **RNOH 框架版本升级** — 更新 package.json / oh-package.json5 中的 RNOH 依赖版本
+2. **重新 codegen** — 使用目标版本 CLI 重新生成 generated/ 代码
+3. **API 兼容性验证** — ETS 业务代码、Package 注册代码、C++ 层依赖的 RNOH API
+
+## 鸿蒙 API 核查（涉及原生能力时必做）
+
+凡涉及原生能力的「需适配」「需评估」项，**分析阶段**须完成 API 核查后再下结论：
+
+1. 使用 **`devecocli docs search`** 搜索鸿蒙 API 文档（见 [OHOS_API_LOOKUP.md](OHOS_API_LOOKUP.md)）
+2. 搜 `harmonyos-references` 确认 API 签名
+3. 搜 `harmonyos-guides` 确认约束（实时性、权限、步骤）
+4. 写入报告「鸿蒙 API 核查表」
+5. 适配建议须引用核查表中的 Kit/API
+
+## 输出标记
+
+在报告中使用：
+- ✅ **需要适配** / ✅ **可实现**（须有 API 核查依据）
+- ❌ **无需适配** / ❌ **无法实现**（须有 API 核查依据）
+- ⚠️ **待评估** / ⚠️ **部分实现**
+- 🔶 **合理差异**（iOS/Android-only，文档标注 Support=No）

package/vendor/Server/Skills/rnoh-lib-version-diff/references/OHOS_API_LOOKUP.md

@@ -0,0 +1,224 @@
+# 鸿蒙 API 核查（devecocli docs search）
+
+版本差异分析中发现上游变更涉及原生能力时，**禁止仅凭 Android/iOS 实现或训练记忆推断 OHOS API**。凡涉及原生能力（相机、扫码、蓝牙、定位、文件、权限等），**必须**使用 `devecocli docs search` 完成核查后再写入报告。
+
+## devecocli docs search 命令
+
+### 命令格式
+
+```
+devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>
+```
+
+### 参数
+
+| 参数 | 必选 | 说明 |
+|------|------|------|
+| `keywords...` | ✅ | 搜索关键词，多个关键词用空格隔开。将搜索版本说明、指南、API参考、最佳实践、FAQ、变更预告等中的内容 |
+| `--catalog` | ❌ | 文档类别，默认 `all`（所有分类） |
+| `--format` | ❌ | 输出格式：`default`（默认）、`json` |
+| `--limit` | ❌ | 返回条数，默认 10。输出结果包括文档ID、标题、文档的概括内容 |
+
+### `--catalog` 取值
+
+| 取值 | 文档类别 |
+|------|----------|
+| `harmonyos-releases` | 版本说明 |
+| `harmonyos-guides` | 指南 |
+| `harmonyos-references` | API参考 |
+| `best-practices` | 最佳实践 |
+| `harmonyos-faqs` | FAQ |
+| `harmonyos-roadmap` | 变更预告 |
+| `all` | 所有分类（默认） |
+
+### 输出内容
+
+每条搜索结果包含：
+- **文档ID** — 唯一标识
+- **标题** — 文档标题
+- **概括内容** — 文档摘要
+
+使用 `--format json` 可获取结构化输出，便于程序化处理。
+
+---
+
+## 何时必须做 API 核查
+
+满足**任一**条件即触发（纯 JS 库无 `harmony/` 原生逻辑时可跳过，报告标注「不适用 API 核查」）：
+
+| 触发条件 | 示例 |
+|----------|------|
+| 上游新增/修改 Android/iOS 原生能力 | MLKit 人脸、CameraX 条码过滤 |
+| 新增 Fabric prop / 事件需 ETS 实现 | `allowedBarcodeTypes`、`onFaceDetected` |
+| TurboModule 方法需 OHOS 系统 API | 权限、文件、传感器 |
+| 报告「需适配项」含 harmony ETS 动作 | 「ScanService 映射 scanTypes」 |
+| 可行性结论为「待评估」 | 需查文档后才能判定可实现/不可实现 |
+
+**不触发**：纯 JS 逻辑、README/CI、仅 build 版本号 bump、上游 iOS-only 且已判定「合理差异」。
+
+---
+
+## 核查流程（每个需适配特性执行一次）
+
+```
+上游 Android/iOS 变更
+    ↓ 提取能力关键词（动词 + 名词 + Kit 名）
+    ↓
+① devecocli docs search --catalog harmonyos-references（必做）
+    搜 API 参考 → 确认 API 签名、Interface/Enum、权限
+    ↓
+② devecocli docs search --catalog harmonyos-guides（推荐）
+    搜指南 → 确认实现步骤、实时性/性能约束
+    ↓
+③ devecocli docs search --catalog best-practices（按需）
+    搜最佳实践 → 确认性能约束、推荐实现
+    ↓
+④ 填写报告「鸿蒙 API 核查表」一行
+    ↓
+⑤ 反哺报告的适配建议与可行性结论
+```
+
+### Step ① 搜 API 参考（必做）
+
+从上游变更提取 **Kit / 模块 / API 名**，搜索 API 参考文档：
+
+```bash
+# 示例：搜索 Scan Kit 的 scanCore 和 ScanType
+devecocli docs search "ScanKit scanCore ScanType" --catalog harmonyos-references --limit 10
+
+# 示例：搜索 Camera Kit 的 MetadataOutput
+devecocli docs search "CameraKit MetadataOutput 人脸" --catalog harmonyos-references --limit 10
+
+# 使用 JSON 格式获取结构化输出
+devecocli docs search "photoAccessHelper MediaLibraryKit" --catalog harmonyos-references --format json --limit 10
+```
+
+记录到报告：
+- **模块导入**（如 `import { scanCore } from '@kit.ScanKit'`）
+- **关键 API 签名**（方法名、参数类型、返回值）
+- **Enum 取值**（若有映射需求）
+- **权限 / 系统能力**（文档有明确标注才写）
+
+### Step ② 搜指南（推荐；实时性/权限/步骤不明时必做）
+
+```bash
+# 搜指南：扫码开发步骤
+devecocli docs search "扫码 ScanKit 开发" --catalog harmonyos-guides --limit 10
+
+# 搜指南：相机开发
+devecocli docs search "相机预览 拍照 Camera" --catalog harmonyos-guides --limit 10
+```
+
+关注：**是否支持实时/流式**、**性能约束**、**与 Android/iOS 能力差异**、**推荐实现步骤**。
+
+### Step ③ 搜最佳实践（按需）
+
+```bash
+# 性能约束不明确时搜最佳实践
+devecocli docs search "实时人脸检测 CoreVision 性能" --catalog best-practices --limit 5
+```
+
+---
+
+## 可行性判定（写入报告）
+
+| 判定 | 含义 | 报告写法 |
+|------|------|----------|
+| ✅ **可实现** | 有明确 OHOS API，语义与上游基本一致 | 列出 Kit + API + 映射策略 |
+| ⚠️ **部分实现** | 有 API 但能力子集不同（如仅矩形框、无 yaw/pitch） | 说明缺失字段与降级方案 |
+| 🔶 **合理差异** | 上游 iOS/Android-only，OHOS 无对等且可 no-op | 文档标注 Support=No |
+| ❌ **无法实现** | 文档明确不支持或无任何 Kit 可覆盖 | 说明依据 + 建议遗留项 |
+
+**禁止**在无 API 核查的情况下使用「可实现」「无法实现」等结论。
+
+---
+
+## 上游能力 → 鸿蒙 Kit 速查（搜索时优先匹配）
+
+| 上游领域（Android/iOS） | 优先搜的鸿蒙 Kit / 关键词 | 典型搜索词 |
+|-------------------------|-------------------------|------------|
+| 相机预览/拍照/闪光灯 | Camera Kit | `CameraKit PhotoSession 闪光灯` |
+| 相机元数据/人脸框 | Camera Kit Metadata | `CameraKit MetadataOutput FACE_DETECTION` |
+| 条码/二维码扫描 | Scan Kit | `ScanKit scanCore customScan ScanType` |
+| 静态图 OCR/人脸 | Core Vision Kit | `CoreVision faceDetector 人脸检测` |
+| 相册/媒体库 | Media Library Kit | `MediaLibraryKit photoAccessHelper` |
+| 音频播放 | Media Kit / Audio Kit | `AVPlayer AudioKit 音频播放` |
+| 权限 | Ability Kit | `abilityAccessCtrl 权限申请` |
+| 蓝牙/BLE | Connectivity Kit | `bluetooth BLE 蓝牙` |
+| 定位 | Location Kit | `geoLocationManager 定位` |
+| 文件读写 | Core File Kit | `CoreFileKit fileIo 文件读写` |
+| 网络 HTTP | Network Kit | `@ohos.net.http 网络请求` |
+
+同一特性可能存在**多条 API 路径**（如人脸：Core Vision 静态图 vs Camera Metadata 实时框），须**都搜**后在报告中对比，不得只搜一条就下结论。
+
+---
+
+## 搜索技巧
+
+### 1. 关键词组合策略
+
+- **Kit 名 + 核心类名 + 方法名**：精确搜 API 参考
+  ```bash
+  devecocli docs search "ScanKit scanCore ScanType" --catalog harmonyos-references
+  ```
+- **中文能力描述**：搜指南和最佳实践
+  ```bash
+  devecocli docs search "实时扫码 相机" --catalog harmonyos-guides
+  ```
+- **英文 + 中文混合**：扩大覆盖面
+  ```bash
+  devecocli docs search "CameraKit 相机预览" --catalog all
+  ```
+
+### 2. 多 catalog 交叉验证
+
+```bash
+# 同一关键词搜不同 catalog
+devecocli docs search "scanCore" --catalog harmonyos-references --limit 10
+devecocli docs search "scanCore" --catalog harmonyos-guides --limit 10
+devecocli docs search "scanCore" --catalog best-practices --limit 5
+```
+
+### 3. JSON 格式批量处理
+
+```bash
+# JSON 输出便于提取文档 ID 和标题
+devecocli docs search "CameraKit" --catalog harmonyos-references --format json --limit 20
+```
+
+---
+
+## 报告输出：鸿蒙 API 核查表（必填专节）
+
+写入版本分析报告独立章节「**鸿蒙 API 核查**」。每行对应一个**上游原生能力增量**（不是每个 commit 一行，按整合主题一行即可）：
+
+| 列 | 说明 |
+|----|------|
+| 上游能力 | 如 `allowedBarcodeTypes`、Android MLKit 实时人脸 |
+| 上游实现摘要 | Android/iOS 用什么 API |
+| 鸿蒙 Kit/API | 核查后的模块 + 关键 API（附搜索关键词） |
+| 能力对比 | 与上游一致 / 子集 / 无对等 |
+| 约束与风险 | 来自 guides / best-practices 的性能、权限、版本限制 |
+| 可行性 | ✅ / ⚠️ / 🔶 / ❌ |
+| 建议动作 | 具体 ETS 文件与实现策略 |
+| API 核查状态 | 分析中 / 已完成 |
+
+---
+
+## 与 Android/iOS 映射方法
+
+1. **读上游 diff**：确认 Android 类/方法（如 `setAllowedBarcodeTypes`）或 iOS `@objc` prop
+2. **抽象能力**：过滤条码类型 / 实时人脸检测 / 延迟启动预览 等
+3. **OHOS 关键词搜索**：用能力词搜 Kit，而非直接搜 Android 类名
+4. **字段级映射**：在核查表中写清 upstream 字段 → OHOS 字段（例：`CodeFormat 'qr'` → `scanCore.ScanType.QR_CODE`）
+5. **事件 payload 映射**：upstream `FaceData.yaw` → OHOS 若无则标 ⚠️ 部分实现
+
+---
+
+## 禁止事项
+
+- **禁止**未执行 `devecocli docs search` 就写「鸿蒙用 XXX API 可实现」
+- **禁止**只搜一个关键词就判定「无法实现」（须至少搜 API 参考 + 指南两个 catalog）
+- **禁止**把 Core Vision Kit 静态检测与 Camera 实时能力混为一谈而不对比
+- **禁止**在「鸿蒙 API 核查表」留空却给出总体「可实现/不可实现」结论
+- **禁止**在分析阶段写具体 `.ets` 实现代码（只写 API 依据与策略）