@ohos-cpf/3rdloop 0.0.2 → 0.0.3

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

@@ -1,77 +1,82 @@
-# 鸿蒙化适配判断规则
-
-上游版本升级后，按以下规则判断鸿蒙侧是否需要同步修改。结合版本差异分析结果，为报告的「鸿蒙化适配分析」章节提供判断依据。
-
-## 文件路径映射
-
-| 上游路径 | 鸿蒙对应 |
-|----------|----------|
-| `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）
+# 鸿蒙化适配判断规则
+
+上游版本升级后，按以下规则判断鸿蒙侧是否需要同步修改。结合版本差异分析结果，为报告的「鸿蒙化适配分析」章节提供判断依据。
+
+## 文件路径映射
+
+| 上游路径 | 鸿蒙对应 |
+|----------|----------|
+| `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/` |
+
+> ⚠️ 以上为典型映射。实际鸿蒙化仓库可能重命名/移动/合并上游文件（实测 camera-kit：`src/specs/CameraNativeComponent.ts` → `src/CameraKitNativeComponent.ts`，`src/types.ts` → `types/types.ts`，平台文件合并为自有 `src/Camera.tsx`）。合并 patch 前先建立实际映射表（见报告「上游→鸿蒙目录映射」章节），不得假设鸿蒙仓库原样保留上游目录结构。
+
+## 判断矩阵
+
+| 上游变更 | 需鸿蒙适配 | 典型动作 |
+|----------|-----------|----------|
+| 纯 JS 逻辑，无 native 交互 | 通常否 | 合并 JS 即可 |
+| 新增/修改 export API | 是 | 同步 `src/`，检查 harmony 调用 |
+| TurboModule 方法增删改 | 是 | 改 Spec → codegen → ETS/C++ |
+| Fabric 组件 Spec props/事件增删改（`codegenNativeComponent` 输入文件） | 是 | 改组件 Spec → 重跑 codegen → ETS 原生实现新 props/事件 |
+| Android/iOS 权限/生命周期 | 是 | 在 ETS 用 OHOS API 对等实现 |
+| 事件名/NativeEventEmitter 变更 | 是 | 对齐 JS 层 + 原生 emit 事件名 |
+| `package.json` peerDeps 升级 | 待评估 | 查目标 RNOH 版本兼容矩阵 |
+| 仅 README/CHANGELOG | 否 | — |
+| 仅 `.github`/CI | 否 | — |
+
+> ⚠️ **自动判定盲区**：`rn-scan-exports.cjs` 只检查 TurboModule Spec，不覆盖 Fabric 组件 Spec。View 型库（相机/播放器/地图/WebView）的组件 Spec 变更（props/事件增删）须**人工 diff** `codegenNativeComponent` 输入文件，命中即「需要原生适配」（实测 camera-kit 16.1.3→18.0.0 曾因此产生假阴性）。
+
+## 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

@@ -1,224 +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 依据与策略）
+# 鸿蒙 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 依据与策略）