@ohos-cpf/3rdloop 0.0.8 → 0.0.9

package/vendor/Archive/data/docs/experiences/kn_mspubgak8d30bfce.md

@@ -0,0 +1,128 @@
+## HarmonyOS 签名配置与已签名 HAP 构建经验
+
+> 来源：rntpc_react-native-netinfo (0.84) signingConfigs 配置与已签名 HAP 构建任务
+
+---
+
+### 问题现象一：devecocli signature generate 无法自动生成签名
+
+执行 `devecocli signature generate --force` 时报错：
+```
+Failed to automatically generate signatures. Run devecocli auth login to sign in.
+```
+
+影响场景：CI/CD 环境、无华为账号的开发环境、自动化脚本。
+
+### 解决方案
+
+`devecocli signature generate` 需要先登录华为账号（`devecocli auth login`）。未登录时不可用。
+
+替代方案：手动配置 `build-profile.json5` 中的 `signingConfigs`，复用本机已有的 DevEco Studio 签名材料。查找流程：
+1. 检查 `~/.ohos/config/` 目录中是否有匹配当前 bundleName 的签名材料
+2. 在其他成功构建的项目中查找相同 bundleName 的 build-profile.json5 配置
+3. 直接复用该配置中的 signingConfigs
+
+### 结果
+
+成功通过手动复用签名材料完成签名配置，无需华为账号登录。
+
+---
+
+### 问题现象二：签名材料的复用约束不明确
+
+不同项目间复用 HarmonyOS 签名材料（.p12/.cer/.p7b）时，不清楚哪些可以复用、哪些不能。
+
+### 解决方案
+
+签名材料复用关键约束：
+
+| 约束维度 | 说明 |
+|---------|------|
+| **bundleName** | .p7b Profile 文件与 bundleName 绑定，不同 bundleName 不能复用同一 .p7b |
+| **机器绑定** | DevEco Studio 生成的加密密码（storePassword/keyPassword）与机器绑定，同一机器不同项目可复用 |
+| **runtimeOS** | type 必须匹配（HarmonyOS vs OpenHarmony） |
+
+实践验证：bundleName 相同的项目可成功复用签名材料（包括加密密码），在 `SignHap` 步骤一次性通过。
+
+### 结果
+
+明确了签名材料复用规则，bundleName 相同的项目间可安全复用全部签名材料。
+
+---
+
+### 问题现象三：signingConfigs 配置结构参考
+
+需要手动填充 build-profile.json5 中空的 signingConfigs 数组。
+
+### 解决方案
+
+signingConfigs 配置结构：
+
+```json5
+signingConfigs: [
+  {
+    name: 'default',           // 必须与 products[].signingConfig 一致
+    type: 'HarmonyOS',         // 或 'OpenHarmony'
+    material: {
+      storeFile: '...p12',     // 密钥库文件
+      storePassword: '...',    // 密钥库密码（明文或DevEco加密格式）
+      keyAlias: 'debugKey',    // 密钥别名
+      keyPassword: '...',      // 密钥密码（明文或DevEco加密格式）
+      certpath: '...cer',      // 证书文件
+      profile: '...p7b',       // Profile 文件（bundleName 绑定）
+      signAlg: 'SHA256withECDSA',  // 签名算法
+    },
+  },
+]
+```
+
+加密密码格式识别：DevEco Studio 生成的加密密码以 `0000001B` 开头，十六进制格式。明文密码也可直接使用。两种格式在 build-profile.json5 中都有效。
+
+### 结果
+
+成功填充 signingConfigs 数组，name 与 products[].signingConfig 一致，构建时签名步骤通过。
+
+---
+
+### 问题现象四：如何验证已签名 HAP 构建成功
+
+构建完成后不确定签名是否成功。
+
+### 解决方案
+
+已签名 HAP 位于：
+```
+entry/build/default/outputs/default/entry-default-signed.hap
+```
+
+与未签名的对比：
+- `entry-default-unsigned.hap` — 打包后未签名
+- `entry-default-signed.hap` — 签名后（比未签名大约 650KB，为签名块）
+
+构建日志中 `SignHap` 步骤成功即表示签名完成。确认文件大小 > 0。
+
+### 结果
+
+通过检查 entry-default-signed.hap 文件存在且大小 > 0，确认签名构建成功。
+
+---
+
+### 问题现象五：MCP build_project 工具构建超时
+
+调用 `deveco-mcp_build_project` 时超时（Request timed out），首次构建（含 clean）耗时较长超过 MCP 工具默认超时时间。
+
+### 解决方案
+
+改为直接使用 hvigorw 命令行构建，设置 300s 超时：
+
+```bash
+/Applications/DevEco-Studio.app/contents/tools/node/bin/node \
+  /Applications/DevEco-Studio.app/contents/tools/hvigor/bin/hvigorw.js \
+  --mode module -p module=entry@default assembleHap -p buildMode=debug --no-daemon
+```
+
+注意：`hvigorw.js` 是 JS 文件，必须用 node 执行，不能直接作为 shell 脚本运行。
+
+### 结果
+
+通过 hvigorw 命令行直接构建成功绕过 MCP 工具超时限制，完成首次 clean build。对于首次 clean build 或大型项目，优先使用 hvigorw 命令行直接构建。

package/vendor/Archive/data/docs/experiences/kn_mspug2de3cb1f7c3.md

@@ -0,0 +1,115 @@
+# RNOH 应用部署验证与 hilog 日志分析经验
+
+## RNOH 应用 Error 级日志噪音白名单
+
+### 问题现象
+RNOH (React Native OpenHarmony) 应用在正常启动运行时，会产生大量 Error 级别的 hilog 日志。仅凭 Error 级日志数量判断应用状态会导致误判，将框架层面的预期行为误读为应用崩溃。
+
+### 解决方案
+以下 Tag 的 Error 日志均为非致命的框架噪音，可列入白名单：
+
+| 来源 Tag | 日志内容 | 实际含义 |
+|---------|---------|---------|
+| `RNOH_CPP` | `Couldn't provide turbo module "RedBox"/"SoundManager"/"IntentAndroid"/"FrameRateLogger"` | 应用未集成这些可选 TurboModule，RNOH 尝试加载已注册名称但找不到。框架设计行为，不影响功能。 |
+| `RNOH_ARK` (DisplayMetricsManager) | `Failed to get customDensity` / `Failed to get maxFontScale` / `Failed to get window decor height` | 设备不支持该能力查询，降级处理。 |
+| `RNOH_ARK` (DevMenu) | `Shake to open Dev Menu is disabled` + `permission.ACCELEROMETER` 缺失 | 摇一摇 DevMenu 被禁用，需在 module.json5 添加加速度计权限才能用，但不影响应用运行。 |
+| `JSPackagerClient` / `ArkCompiler` | `Websocket connection failed` / `Decode failed, client websocket disconnect` | debug 构建尝试连接 Metro bundler 但未运行。应用使用预打包 JS 继续。 |
+| `NETSTACK` | `lws_service stop`（重复） / `CURLcode result 7` / `epoll wait event 0 err: 111` | 对于 netinfo 等网络探测应用，这些是正常工作行为（检测网络是否可用），而非 Bug。 |
+| `WMSDecor` | `GetDecorVisible: device not support` | 设备不支持窗口装饰功能。 |
+| `Text` / `FontConfig` | `GetFileData: Path or realPath is nullptr` / `CheckConfigFile: Null data` | 字体配置缺失，使用默认字体。 |
+| `PARAM_WATCHER` | `Failed to add watcher for persist.rosen.animationtrace.enabled` | 系统参数监听失败，系统级。 |
+
+### 结果
+在自动化部署验证流程中，将上述噪音日志 Tag 列入白名单可避免误报。NETSTACK 类日志需结合应用类型判断——网络探测类应用中这些是正常行为。
+
+---
+
+## 判断 RNOH 应用是否真正崩溃的可靠方法
+
+### 问题现象
+仅凭 Error 级日志数量无法准确判断应用是否真正崩溃，需要多维度综合判断。
+
+### 解决方案
+不要仅凭 Error 级日志数量判断应用状态，应综合以下 4 个维度：
+
+1. **Level F (Fatal) 日志**：有无 Fatal 级日志（最可靠指标）
+2. **faultlog 崩溃日志**：使用 `get_hilog_or_faultlog_recent` 设置 `is_crash_log=true` 查询有无崩溃记录
+3. **UI 树验证**：使用 `get_app_ui_tree`（full 模式）获取 UI 树，grep 搜索目标组件关键词，确认应用 UI 是否正常渲染（进程存活且功能正常的最直接证据）
+4. **进程存活**：`aa start` 返回 `start ability successfully` 后 UI 树能成功 dump，说明进程未崩溃退出
+
+### 结果
+当 3 个维度（无 Fatal、无 faultlog、UI 正常渲染目标组件）全部通过时，Error 日志可全部归类为框架噪音，结论为"应用正常"。此方法在实际部署验证任务中验证有效。
+
+---
+
+## hdc snapshot_display 截图命令后缀限制
+
+### 问题现象
+使用 `hdc shell snapshot_display -f /data/local/tmp/xxx.png` 截图时报错：`error: fileName /data/local/tmp/xxx.png invalid, suffix must be .jpeg`。
+
+### 解决方案
+`snapshot_display` 命令只支持 `.jpeg` 后缀，不支持 `.png`。必须使用 `.jpeg` 扩展名：
+```bash
+hdc shell snapshot_display -f /data/local/tmp/screenshot.jpeg
+hdc file recv /data/local/tmp/screenshot.jpeg ./
+```
+
+### 结果
+改用 `.jpeg` 后缀后截图成功。后续截图操作统一使用 `.jpeg` 后缀，避免 `snapshot_display` 报错。
+
+---
+
+## MCP perform_ui_action screenshot 多设备环境 hvd 参数问题
+
+### 问题现象
+当环境中存在多个可用设备（包括未运行的模拟器）时，MCP 工具 `perform_ui_action` 的 screenshot 操作会要求通过 `hvd` 参数指定目标设备，即使只有一个真机已连接。
+
+### 解决方案
+多设备环境下可改用 `hdc` 命令行直接截图作为替代方案：
+```bash
+hdc shell snapshot_display -f /data/local/tmp/screenshot.jpeg
+hdc file recv /data/local/tmp/screenshot.jpeg ./
+```
+若必须使用 MCP 工具，则需传入 `hvd` 参数明确指定目标设备 ID。
+
+### 结果
+使用 hdc 命令行绕过 MCP 工具的多设备限制，成功完成截图。在多设备环境中推荐优先使用 hdc 命令行。
+
+---
+
+## RNOH 示例项目 Bundle Name 复用的部署策略
+
+### 问题现象
+RNOH 示例项目（netinfo、pager-view 等）共用 bundle name `com.harmony.wechat.lib.demo`。直接部署新应用而不卸载旧应用，会导致旧应用残留，UI 树内容不匹配，无法确认是否为新部署的应用。
+
+### 解决方案
+部署新应用前必须先卸载旧应用：
+```bash
+hdc shell bm uninstall -n com.harmony.wechat.lib.demo
+hdc install <new-hap-path>
+```
+
+### 结果
+先卸载再安装后，UI 树内容与新部署应用匹配，可可靠确认应用正常启动。共用 bundle name 的项目必须遵循此策略。
+
+---
+
+## RNOH 应用部署验证标准流程
+
+### 问题现象
+RNOH 应用部署到设备后缺乏标准化的验证流程，容易遗漏关键检查步骤导致误判应用状态。
+
+### 解决方案
+推荐以下 8 步标准部署验证流程：
+
+1. **清除残留**：`hdc shell bm uninstall -n <bundleName>`（清除旧应用残留）
+2. **安装 HAP**：`hdc install <hap-path>`（安装新 HAP）
+3. **清日志缓冲**：`hdc shell hilog -r`（清除历史日志干扰）
+4. **启动应用**：`hdc shell aa start -a EntryAbility -b <bundleName>`（启动 Ability）
+5. **等待渲染**：等待 8-10 秒（确保 UI 完成渲染）
+6. **UI 树验证**：调用 `get_app_ui_tree`（full 模式）获取 UI 树 JSON，grep 搜索目标组件关键词（如 `netinfo/NetInfo/RNCNetInfo`），确认应用正常启动且非设备残留的其他应用
+7. **日志检查**：调用 `get_hilog_or_faultlog_recent` 分别按 `level=F`、`is_crash_log=true`、`level=E` 过滤
+8. **日志分析**：分类分析 Error 日志，排除噪音白名单后确认无致命错误
+
+### 结果
+此流程在 rntpc_react-native-netinfo (0.84) 部署验证任务中验证有效，8 步全部通过后可确认应用正常启动无崩溃。流程可复用于其他 RNOH 应用的部署验证。

package/vendor/Archive/data/docs/experiences/kn_skill_opt_001.md

@@ -0,0 +1,38 @@
+# 知识导入SKILL优化经验
+
+## 一、SKILL修改过度推断
+
+### 问题现象
+知识导入过程中，AI 基于经验文档的主题关键词（如"测试""Hypium"）与 SKILL description 的语义重叠，推断关联了未在经验文档中显式提及的 SKILL（TPCXTSCodeSkill、TPCXTSExecutionSkill）并进行修改。实际经验文档只记录了通用技术知识，未指出任何 SKILL 的流程缺陷。
+
+### 解决方案
+收紧 SKILL 类分类标准，要求两个条件同时满足才算 SKILL 类：1) 经验显式提及 SKILL 名称或步骤名；2) 内容指出该流程环节存在具体缺陷。禁止仅凭主题关键词重叠推断关联。SKILL 定位指南中删除"关键词重叠匹配"规则，改为仅支持"精确名称匹配"和"步骤名匹配"。
+
+### 结果
+经验文档未显式提及 SKILL 时不再误修改 SKILL，所有内容归为知识类导入知识库。默认归属原则为"宁可多导入知识库，不可误修改 SKILL"。
+
+---
+
+## 二、知识库内容未结构化整理
+
+### 问题现象
+导入知识库时，将原始经验文档的 Markdown 内容原封不动作为 content 参数传入 kb_add_document，未经过任何结构化整理。导致知识库中存储的是原始文档而非可高效检索复用的经验条目。
+
+### 解决方案
+在 SKILL.md 的 Phase 3 中增加内容结构化整理要求，强制按"问题现象/解决方案/结果"三段式重组。将原始文档中的"关键发现""踩坑记录""可复用建议"拆解为独立条目，每个条目聚焦一个问题。在 MCP_TOOL_USAGE.md 中新增"知识库内容结构化格式"章节，给出标准模板。
+
+### 结果
+知识库中存储的是结构化的经验条目，每个条目可独立检索，问题-方案-结果关系清晰，复用效率提升。
+
+---
+
+## 三、MCP 工具可用性未前置检查
+
+### 问题现象
+SKILL 直接假设 kb_add_document 工具可用，未在执行前验证 MCP Gateway 是否运行、工具是否注册。当 opencode 未配置 mcp-gateway 时，到调用阶段才发现工具不可用，导致知识类导入被迫跳过。
+
+### 解决方案
+在 Phase 3 新增"3.0 MCP 工具可用性检查"步骤，先调用 gateway_health 和 gateway_list_tools 确认 kb_add_document 可用。在 MCP_TOOL_USAGE.md 新增"第0章 MCP Gateway 可用性验证"，包含健康检查、工具列表确认、配置方法和 opencode 重启提示。
+
+### 结果
+工具不可用时在最早阶段发现并跳过，避免到调用阶段才失败。用户可获知明确的配置指引，快速修复后重新执行。

package/vendor/Archive/data/docs/experiences/loop-artifacts-verification-evidence-triangle.md

@@ -0,0 +1,19 @@
+## 跨循环产物复用核验的证据三角模式与汇总指标分解
+
+### 问题现象
+"loop N 复用 loop N-1 产物"的核验任务中存在两类陷阱：
+1. 仅凭前序步骤报告的"成功"结论即判定通过，报告与实物可能不一致；
+2. 任务描述中的汇总数字（如"设备端 95/95，共 154/154"）在前序报告中没有直接对应的单一数字，只对总数会漏掉口径错配。
+
+### 解决方案
+**证据三角模式**——关键声明必须三方交叉验证：
+1. 报告声明：读前序步骤报告结论；
+2. 实物产物：文件存在性 + 大小 + 时间戳（如 HAR 22MB / tgz 44MB / 签名与未签名 HAP 实体文件）；
+3. 现场 git/文件查询：如 `git merge-base br_rnoh0.84 br_rnoh0.82` 实测分支血缘、直接读依赖清单文件原文、实际列目录比对测试文件清单（jest.config.js、__mocks__/、src/__tests__/、example/src/suites/ 逐一对账）。
+
+**汇总指标分解规则**：验收标准含汇总数字时逐项拆解到报告分项对账。示例："95/95" = 自动套件 85/85 + Hooks 探针 10/10；"154/154" = Jest 59 + 85 + 10，分解后才确认口径一致。
+
+**自动生成产物权威级规则**：链路中自动生成的 diff/扫描件（如 rn-scan-exports.cjs 生成的 api-diff_*.md）存在已知偏差（对 Nitro HybridObject 架构，Spec 文件为 `*.nitro.ts` 而非 `Native*.ts` 命名，扫描器规则不覆盖，导致"TurboModule Spec 变更：无"误判）。若后续人工分析报告已修正，验收一律以修正结论件为准，自动件仅作参考——否则会拿错误基线对账。
+
+### 结果
+react-native-mmkv loop0 产物核验 5/5 通过：分支血缘（merge-base = 预期 commit c047ada）、编译产物、依赖版本、测试产物（与报告清单一一对应）均经实物交叉验证，测试口径 59+85+10=154 分解对账一致。可复用结论：任何"loop N 复用 loop N-1 产物"的核验任务，直接套用证据三角模式与汇总指标分解规则。

package/vendor/Archive/data/docs/experiences/macos-bash-replace-build-ps1.md

@@ -0,0 +1,19 @@
+## macOS/Linux 环境替代 build.ps1 执行 devecocli build 的方法
+
+### 问题现象
+
+build.ps1 在 macOS 环境不可用（无 pwsh/powershell）。而构建流程强制"必须通过 build.ps1 执行"的底层原因是：直接调用 devecocli build 会导致 hvigor daemon 继承 Agent pipe 句柄不释放，造成 session 永久阻塞。
+
+### 解决方案
+
+等效替代方案：**bash 重定向到日志文件 + timeout 参数**
+
+```bash
+devecocli build --modules entry > build.log 2>&1
+```
+
+原理：daemon 继承的是文件句柄而非管道句柄，同样规避了 pipe 句柄继承导致的 session 阻塞，与 build.ps1 的防护机制等价。构建错误从 build.log 日志文件中读取。
+
+### 结果
+
+macOS 环境下实际执行 3 轮编译均无 session 阻塞，效果与 build.ps1 等同。macOS/Linux 环境执行鸿蒙编译验证可直接采用此方案。

package/vendor/Archive/data/docs/experiences/macos-bsd-diff-q-illegal-option.md

@@ -0,0 +1,15 @@
+# macOS 下 diff -q 报 "illegal option" 的解决方法
+
+### 问题现象
+
+在 macOS（zsh/BSD 工具链）下执行 `diff -q` 组合用法时报 "illegal option" 错误，导致命令链中断。原因是误用了 GNU diff 的语法组合，macOS 自带的 BSD diff 不支持该用法。
+
+### 解决方案
+
+改用以下任一方式：
+- 直接用 `diff` 全量比对（观察输出差异）
+- 用 `cmp -s file1 file2` 做静默比对（通过退出码判断是否相同，适合脚本）
+
+### 结果
+
+命令链不再中断。macOS 环境下涉及 GNU/BSD 工具差异时，优先考虑 `cmp -s` 替代 `diff -q` 的脚本化场景用法。

package/vendor/Archive/data/docs/experiences/migrate-cjs-compatible-api-version-map-limit.md

@@ -0,0 +1,17 @@
+## migrate.cjs --compatible-api 版本上限陷阱与正确取值方法
+
+### 问题现象
+
+执行 `node migrate.cjs --compatible-api 26` 报 `未知 compatible-api 版本` 错误。根因：migrate.cjs 的 API_VERSION_MAP 存在版本上限（当前最高 24），设备 API 版本（26）超出映射表范围时直接传入即报错。而 SKILL 流程原指示"探测设备 API 版本作为 --compatible-api 传入"，未考虑此上限。
+
+### 解决方案
+
+correct 取值流程：
+1. `hdc shell param get const.ohos.apiversion` 获取设备 API 版本
+2. 若设备 API 超出脚本 API_VERSION_MAP 上限，读取 `DevEco-Studio.app/Contents/sdk/default/sdk-pkg.json` 的 `apiVersion` 字段获取已安装 SDK API 版本
+3. 取 **min(设备 API, 已安装 SDK API)** 作为 `--compatible-api`（编译面向已安装 SDK，实际以已安装 SDK API 为准）
+4. 重跑后校验：脚本输出含 `迁移完成`，且产物 `compatibleSdkVersion ≤ 设备 API`
+
+### 结果
+
+以已安装 SDK API(24) 作为 compatible-api 重跑迁移成功，编译验证通过。设备 API 高于 SDK API 时必须以 SDK API 为准，不可直接传设备 API。

package/vendor/Archive/data/docs/experiences/mp3agic-arkts-library-behavior-quirks.md

@@ -0,0 +1,21 @@
+## mp3agic 鸿蒙移植库源码行为缺陷与签名实测清单
+
+### 问题现象
+
+mp3agic 鸿蒙移植库（`.ts` 源码带 `@ts-nocheck`）存在多处与场景文档/预期不符的实际行为，按文档字面调用会运行时出错或展示错误结果。
+
+### 解决方案（实测行为清单）
+
+| 接口 | 实际行为（以源码为准） | Demo 处理方式 |
+|------|----------------------|--------------|
+| `ID3v24Tag.setGenreDescription` | 内部引用缺 `this.` 前缀（@ts-nocheck 掩盖的库缺陷），运行时抛 ReferenceError | try/catch 捕获展示 |
+| `ID3v2ObseleteFrame.packFrame` | 无条件抛 `NotSupportedException` | try/catch 捕获展示异常名与消息，验证点标注"源码真实行为" |
+| `unsynchroniseBuffer` | 声明返回 `number`，实际返回数组 | 按声明类型接值，`String(result)` 展示实际内容 |
+| `BufferTools.setBit(0, 7, true)` | 返回 Int8 有符号值 `-128` 而非 `128` | 按有符号值展示 |
+| `setChapters` / `setChapterTOC` / `getChapters` / `getChapterTOC` | 容器类型为 `JList<T>` 而非文档所写 `Array<T>` | 按 JList 构造/接值 |
+| `BufferTools.mergeArrayBuffer` | rest 参数 `...arrays` 而非文档所写数组参数 | 调用时展开为多参数 |
+| `ID3v2ChapterTOCFrameData` 构造函数 | 签名 `(unsynchronisation, bytes?, isRoot?, isOrdered?, id?, children?)` | 按参数序精确构造，可选参用 undefined 占位后再 setChilds |
+
+### 结果
+
+mp3agic Demo 生成中全部差异按源码实测行为处理，编译与功能验证通过。再次使用该库时直接对照本清单，无需重新逐接口核实。

package/vendor/Archive/data/docs/experiences/ohos-face-detection-scan-api-mapping.md

@@ -0,0 +1,15 @@
+## 鸿蒙人脸检测/取帧/码制过滤 API 对等性核查结论（RN camera-kit 适配锚点）
+
+### 问题现象
+RN react-native-camera-kit 18.x 新增人脸检测能力（onFaceDetected / onFaceDetectionInstallStatus 事件、faceDetectionEnabled 等 props）、码制过滤（allowedBarcodeTypes），需核查鸿蒙侧 Kit 对等性后才能下「可否适配」结论。
+
+### 解决方案
+新原生能力先查 Kit 对等性再下结论。本次核查锚点（devecocli docs search / 官方文档验证）：
+
+- **人脸检测** → `@kit.CoreVisionKit` `faceDetector`（API 12+）：`detect(VisionInfo) → Face[]{pose{yaw,pitch,roll}, rect, points}`。约束：**仅接受 RGBA_8888 PixelMap、面向图片而非视频流、需限流**
+- **取帧** → `image.ImageReceiver`（readLatestImage）+ 相机预览流 surface
+- **码制过滤** → `scanCore.ScanType` 枚举（14 种，覆盖绝大部分 CodeFormat）。例外：`code-39-mod-43`（iOS-only）无对等；`interleaved-2of5` 近似映射 ITF14_CODE 需实测
+- **通路冲突风险识别**：鸿蒙现有扫码走 `customScan(ViewControl)`（ScanKit 独占 surface），人脸检测需独立 ImageReceiver 支路 ——「扫码 + 人脸检测同时开启」的通路并存策略是适配阶段的重点验证项，分析报告应显式提示
+
+### 结果
+Kit 对等性核查支持「人脸检测可适配但有限制」的结论：需 RGBA_8888 像素格式转换 + 调用限流 + 独立取帧通路设计；码制过滤基本可覆盖（2 个例外项需降级或实测）。

package/vendor/Archive/data/docs/experiences/pr-metadata-and-diff-integrity-verification.md

@@ -0,0 +1,12 @@
+## PR 元数据判读与 diff 完整性核验经验
+
+### 问题现象
+（1）仓库给 PR 打了「静态检查失败」标签，但 PR 元数据 API 显示 `ci_state_passed=true`，两处信息矛盾，容易误判 CI 状态；（2）单 commit PR 中 pr.patch（单次 commit patch）与累积 diff 的关系不确定，需要快速确认 diff 完整性；（3）从 diff 文本提取变更文件列表的 `sed 's/diff --git a\/.* b\/\//'` 命令在 macOS（BSD sed）上报 "unterminated substitute in regular expression"，导致 changed-files.txt 生成为 **0 字节空文件**，且直至收尾才被发现，险些遗漏。
+
+### 解决方案
+1. CI/标签矛盾时，**以 PR 元数据 API 的 mergeable_state 为准**，标签仅作线索；静态检查结论以本地独立检查 + 基线对照为准。
+2. 单 commit PR 快速判定：`git log --oneline` 确认 PR 分支 HEAD 的父提交即 base master tip 时，pr.patch == 累积 diff，可用于**交叉校验 diff 完整性**；但"必须生成累积 diff"的流程仍应执行，两者一致时相互印证（如 mp3agic PR #53：11 文件 +2605 行两者一致）。
+3. macOS BSD sed 对 `a\/.* b\/` 转义组合不兼容。改用管道方案：`grep "^diff --git" pr-diff.txt | awk '{print $4}' | sed 's/^b\///'`，并在生成后 `wc -l` 校验非空。**通用教训**：所有"生成文件"类步骤都应附带非空校验，0 字节空文件在收尾前不易被察觉。
+
+### 结果
+在 mp3agic PR #53 检视中：以 PR 元数据为准避免了被仓库标签误导；pr.patch 与累积 diff 一致相互印证了 diff 完整性；替换命令后 changed-files.txt 正常生成，后续检视范围判断未失据。

package/vendor/Archive/data/docs/experiences/rn-coverage-index-signature-pseudo-member-false-negative.md

@@ -0,0 +1,32 @@
+## RN 覆盖率分析中索引签名伪成员假阴性的识别与 grep 对账
+
+### 问题现象
+
+RN 三方库用例覆盖度检视中，覆盖率脚本（rn-analyze-test-coverage.cjs / rn-analyze-demo-coverage.cjs，AST 模式）报告的未覆盖列表出现形如 `X.key` 的接口（X 为纯类型接口，key 为通用词），但人工核验发现该类型变量在测试代码中被大量使用，属于脚本假阴性。由于归零规则 6（有效覆盖率 < 100% → 评分 0 分）的放大效应，**单个此类假阴性即可翻转整个评分**（实例：rntpc_cookies 库按假阴性计算 22/23=95.65% < 100% 误触归零 → grep 对账修正后 23/23=100%，评分 0 ↔ 95）。
+
+根因链（三层叠加）：
+1. 接口提取脚本 rn-extract-interfaces.cjs 将上游 index.d.ts 中的索引签名 `[key: string]: T` 提取为伪字段（memberName=签名参数名 key，运行时不存在名为 key 的真实属性）；
+2. 覆盖率脚本 AST 匹配器只处理 PropertyAccessExpression（属性名等值匹配）、对象字面量与 JSX 属性，**不处理 ElementAccessExpression（方括号索引访问）**，而索引签名的合法用法恰恰是 `obj["xxx"]` / `obj[变量]`；
+3. 即使测试写点访问 `obj.xxx`，属性名是业务名而非 `key`，同样不命中 → 索引签名伪成员在属性名等值匹配体系下**必然**假阴性。
+
+### 解决方案
+
+**三条可疑信号**（识别未覆盖项是否为伪成员，可复用）：
+1. memberName 是"类型签名参数名"风格的通用词（`key`/`value`/`index`），而非业务命名；
+2. 所属 className 是纯类型接口（kind=field、layer=js、type=type-decl，无运行时类），即索引签名宿主；
+3. 测试代码中有该类型显式标注的变量（如 `const c: Cookies = {...}`），逻辑上不可能"完全没用"。
+
+**grep 盘点对账**（验证方法）：对疑似伪成员，在测试与 Demo 源码中 grep 宿主类型变量的所有访问形式：
+- 方括号访问：`varName[`（字面量键 `varName["xxx"]`、变量键 `varName[k]`、计算键 `varName[expr]` 三种形式）
+- 点访问：`varName.`（任意属性名，只要变量类型为该接口）
+
+任一形式命中且语义上使用了该索引签名类型 → 判定为脚本假阴性，修正为已覆盖（来源标注 test/demo/both），并重新计算有效覆盖率。
+
+### 结果
+
+rntpc_cookies 实例验证：`Cookies.key` 疑似伪成员经 grep 对账命中 6+ 处（变量键+字面量键+计算键+点访问，以及对 `get()`/`getFromResponse()` 返回值的索引断言），且 `Cookie.fields` 用例通过布尔断言验证了 4 种键访问形式的正确性 → 判定已覆盖（both），有效覆盖率修正为 100%，最终评分 95 分而非 0 分。
+
+可复用结论：
+1. 任何"脚本未覆盖列表 → 扣分/归零"链路，评分前必须对未覆盖项**逐项 grep 交叉验证**（测试与 Demo 双来源）；memberName 为通用词且所属为纯类型接口时尤其必查。
+2. **归零边缘警觉**：排除平台特有接口后有效覆盖率恰好差 1-2 项达到 100%，是伪成员/假阴性的高发信号，此时必须逐项核验而非直接套规则。
+3. 脚本侧根治方向：覆盖率脚本 AST 匹配器补充 ElementAccessExpression（索引访问）识别 + 变量类型映射，可从源头消除此类假阴性。

package/vendor/Archive/data/docs/experiences/rn-memory-check-severity-calibration.md

@@ -0,0 +1,21 @@
+# RN 鸿蒙内存检视严重度标定原则（destroy 豁免/死代码单例/观察项）
+
+### 问题现象
+
+内存泄露检视按固定扣分表执行时，两类场景容易误判：
+1. 无状态模块未重写 `__onDestroy__`，机械执行"未释放扣 20 分"会把零泄露面的优秀库误判为 0 分或低分档。
+2. 模块级 `export default new Logger(...)` 这类 eager 单例，若全仓库无任何 import（死代码），运行期零分配，严格意义上不是泄露，容易被高估为实际泄露风险。
+
+### 解决方案
+
+三条可复用标定原则：
+
+1. **无状态模块 destroy 豁免**：`__onDestroy__` 缺失是否扣分，取决于模块是否存在可释放资源（事件监听/系统资源句柄/Map/Set 容器/回调引用/实例字段）。零字段模块不重写 destroy 属正确最小化设计，不构成泄露风险，不扣分。判定前须先用穷尽验证模式集确认"零泄露面"（rg 六组模式全 0 命中）。
+
+2. **死代码单例两档标定**：`模块级 new 单例` 分两档——(a) 被 import → 加载即常驻，若体量固定记轻微～中等；(b) 全仓库无引用死代码 → 记轻微（0～-5），并在报告中注明"运行期零分配，非严格泄露"，避免把死代码当成实际泄露高估风险。
+
+3. **观察项（0 分）分级**：内存检视中发现的非内存问题（未接线死代码、codegen 滞后等）记入泄露风险清单但标注"观察（0 分）"，说明不扣分理由（无内存影响）+ 指引归属阶段（编码质量/一致性检视）。不稀释内存评分语义，同时不丢失信息。
+
+### 结果
+
+rntpc_cookies 校准案例：无状态库 + 1 处死代码单例（Logger.ets 模块级 new，全仓库无 import）→ 95 分（轻微 -5）；未接线死代码、codegen 滞后按观察项（0 分）记录不扣分。若死代码也不存在应为 100 分。观察项计入扣分会把优秀库误判到"良好"档，此标定原则可避免该类评分漂移。

package/vendor/Archive/data/docs/experiences/rn-platform-specific-api-exclusion-evidence.md

@@ -0,0 +1,24 @@
+## RN 平台特有接口排除判定：上游注释仅为线索，鸿蒙侧实现是决定性判据
+
+### 问题现象
+
+RN 三方库鸿蒙化用例覆盖度检视中，对未覆盖列表做平台特有接口排除时存在**过度排除**失真风险：上游 index.d.ts 中标注 `// Android only`、`// iOS only` 的接口，若按注释机械排除，会把鸿蒙侧真实存在的接口移出有效分母，掩盖真实覆盖缺口。
+
+反例（rntpc_cookies 库）：`removeSessionCookies`（上游标注 Android only）与 `clearByName`（上游标注 iOS only）虽被标注为单平台专属，但鸿蒙侧 TurboModule Spec **均有实现**（`clearSessionCookieSync` / 过期 Cookie 覆写删除）——不得排除。过度排除与假阴性方向相反，但同样导致有效覆盖率失真。
+
+### 解决方案
+
+平台特有接口排除的正确证据链（建议三条齐备才排除）：
+1. **上游平台限定标注**（`// Android only`、`// iOS only` 等）——仅为线索，不能单独作为排除依据；
+2. **鸿蒙 JS 入口的平台门控**——如 `flush` 仅在 `Platform.OS === 'android'` 时调原生，鸿蒙为 no-op；
+3. **鸿蒙侧 TurboModule Spec / ArkTS / C++ 转发均无实现**——决定性判据（对应检视 CHECKLIST 平台特有识别特征 4）。
+
+判定优先级：上游 d.ts 平台注释 ≠ 排除依据；以鸿蒙侧是否有 TurboModule/ArkTS 实现为决定性判据。保守判定原则：无法确定是否平台特有时**不排除**（按正常未覆盖处理），只有证据链明确时才排除。
+
+### 结果
+
+rntpc_cookies 实例验证：
+- `flush`（上游标注 Android only + 鸿蒙 JS 入口 no-op + 鸿蒙侧无实现）与 `getAll`（上游标注 iOS only + 鸿蒙侧三层均未实现、调用抛 TypeError）证据链齐备，正确排除；
+- `removeSessionCookies` / `clearByName` 因鸿蒙侧 TurboModule 有实现而**不排除**，避免了掩盖真实覆盖状态。
+
+可复用结论：平台特有排除判定必须核对鸿蒙侧 TurboModule Spec / ArkTS / C++ 是否有实现，不能信任上游注释；三条证据齐备才排除，防止过度排除（移出真实接口）与遗漏排除（误触归零）两类方向相反的失真。

package/vendor/Archive/data/docs/experiences/rn-upstream-version-diff-pitfalls.md

@@ -0,0 +1,17 @@
+## RN 上游版本 diff 操作踩坑集（grep 二进制 / CHANGELOG 来源 / patch 噪音 / 平台并行文件）
+
+### 问题现象
+对比上游两个 npm tgz 版本生成 patch 与检索 release notes 时的操作性坑：
+1. 全量 patch 中 `grep "^diff"` 报 "Binary file matches"
+2. CHANGELOG.md 不在 npm tgz 内，无法从源码包获取上游 release notes
+3. 脚本生成的 patch 仍包含 android/ios 原生平台代码与 .DS_Store 噪音（280KB 中大部分是原生变更）
+4. 上游共享实现（如 `Camera.tsx`）与平台特化文件（`.android.tsx` / `.ios.tsx`）是三份并行文件，只 diff 入口 index.ts 会漏掉平台文件变更（实测：共享版无变更但平台版有 props 默认值注入变更）
+
+### 解决方案
+1. patch 含二进制文件（.DS_Store/gradle 等）时用 `grep -a` 强制文本模式
+2. release notes 从 GitHub Releases 页面获取（webfetch releases 页可行；raw CHANGELOG.md 可能超时）
+3. 两阶段 diff 是必要的：Phase 1 全量 → Phase 2 按相关文件清单筛选精简，不能信任脚本的默认排除已覆盖 patch 本身
+4. diff 时显式覆盖共享实现与平台特化文件（`.tsx` / `.android.tsx` / `.ios.tsx` 三份并行），不能只看入口文件
+
+### 结果
+Phase 2 精简后 patch 从 280KB 缩至 9.3KB（7 文件），平台文件的 props 默认值注入变更未被遗漏，patch 可直接用于后续适配。

package/vendor/Archive/data/docs/experiences/rn-version-gap-risk-rating-rules.md

@@ -0,0 +1,13 @@
+## RN 库版本差距双口径记录与风险评级规则
+
+### 问题现象
+版本差距报告只记录单一口径（至任务指定版本或至 npm latest 之一）会误导升级决策；同时 major 版本号跨度容易被直接当作 breaking change 信号，导致风险高估或低估。
+
+### 解决方案
+1. **双口径记录**：同时给出「至任务指定版本」与「至 npm latest」两档差距，并在升级建议中提示可顺带对齐 latest patch。实测：camera-kit npm dist-tags.latest 为 18.0.1，任务指定对比 18.0.0，18.0.1 仅含 iOS 修复。
+2. **major ≠ breaking change**：major 版本号不等于 breaking change，须逐条核对 CHANGELOG 的 breaking 项是否触及 JS 层接口契约：
+   - camera-kit 18.0.0 官方明确声明「No known breaking changes were done」，major 仅为预防性标记（新增人脸检测）
+   - 17.0.0 的 breaking（移除 `iOsSleepBeforeStarting`）是原生侧 only 属性，16.1.3 的 JS Spec 中本就不存在，对 JS 接口契约无影响，可降级处理
+
+### 结果
+风险评级基于「breaking 项是否触及 JS 层契约」逐条核对而非版本号跨度，评级更准确；双口径让升级决策同时看到至指定版本与至最新版的差距。

package/vendor/Archive/data/docs/experiences/rn-view-lib-native-contract-diff-fabric-spec.md

@@ -0,0 +1,16 @@
+## RN View 型库的原生接口契约必须同时覆盖 Fabric 组件 Spec
+
+### 问题现象
+对 RN 三方库做版本差异分析时，diff 脚本（rn-scan-exports.cjs / generate-diff.js）自动判定为「✅ 无需原生适配 — 接口未变更」，但对 react-native-camera-kit（16.1.3 → 18.0.0）实测该结论是**假阴性**：上游 `src/specs/CameraNativeComponent.ts`（Fabric 组件 Spec，`codegenNativeComponent` 输入）新增了 4 个 props（faceDetectionEnabled / faceDetectionThrottleMs / allowedBarcodeTypes / iOsDeferredStart）+ 2 个事件（onFaceDetected / onFaceDetectionInstallStatus）。Fabric 组件 Spec 是 codegen 的直接输入，其变更意味着鸿蒙侧必须：① 同步更新组件 Spec 文件 → ② 重跑 codegen（generated/ ETS+C++ 产物变化）→ ③ ETS 原生层实现新 props/事件（人脸检测为全新原生能力）。
+
+### 解决方案
+RN 库的原生接口契约 = **TurboModule Spec + Fabric Component Spec 两部分**，只检查前者会漏掉 View 型库的主要原生变更面：
+
+- 脚本的「TurboModule Spec 变更」检查只覆盖 `src/specs/Native*Module.ts`，不覆盖组件 Spec 文件
+- 脚本判定后，务必**人工 diff** `src/specs/*Component*.ts`（或所有 `codegenNativeComponent` 输入文件），重点检查：
+  - `NativeProps` / 组件 interface 的 props 增删
+  - `DirectEventHandler` / `BubblingEventHandler` 事件增删
+- 判定矩阵：**TurboModule Spec 变更 OR 组件 Spec 变更 → 需要原生适配（codegen + 原生实现）**
+
+### 结果
+camera-kit 正确结论为「需要原生适配（类型 A）」，人工复核推翻了脚本假阴性结论。相机/播放器/地图/WebView 等 View 型库尤其常见组件 Spec 变更，是脚本自动判定的重灾区；分析报告中应显式记录对自动结论的修正及原因，避免下游直接采信脚本结论。

package/vendor/Archive/data/docs/experiences/rnoh-adapter-package-version-field-semantics.md

@@ -0,0 +1,18 @@
+## RNOH 鸿蒙适配包版本字段双层语义（re-export 架构）
+
+### 问题现象
+验收/核验 RNOH 三方库升级时，按字面直读 `packages/{lib}/package.json` 的 `version` 字段会误判核验失败。典型案例：react-native-mmkv 升级到上游 4.3.2 后，`@react-native-ohos/react-native-mmkv` 包的 `version` 仍为 4.0.0，且与交付物 tgz 文件名 `react-native-ohos-react-native-mmkv-4.0.0.tgz` 一致——这并非升级不到位。
+
+### 解决方案
+鸿蒙适配包采用 re-export 架构（JS 层仅 re-export 上游 npm 包）时，版本字段具有双层语义：
+- `version` 字段 = 鸿蒙适配包**自身**的版本号（历史沿袭，可能与上游版本完全不同步），与交付物 tgz 文件名对应；
+- `dependencies` 中的上游源库条目（如 `"react-native-mmkv": "4.3.2"`）= 实际生效的上游版本，上游升级即依赖升级。
+
+核验步骤：
+1. 先读版本差异分析报告，确认包架构（re-export / 源内复制 / fork）——不同架构下"上游版本"所在字段不同；
+2. re-export 架构 → 检查 `dependencies` 中上游源库条目；源内复制 → 检查 `version` 或源码内版本标注；
+3. 与交付物 tgz 文件名交叉确认适配包自身版本；
+4. 在核验记录中显式写明该语义说明，避免后续循环再次踩坑。
+
+### 结果
+react-native-mmkv（上游 4.3.1→4.3.2）核验实测：`version: 4.0.0` 为适配包自身版本（升级全程未变），`dependencies.react-native-mmkv: 4.3.2` 为上游版本，判定核验通过。可复用结论：RNOH 三方库（@react-native-ohos/*）核验版本时，永远同时看 `version`（适配包自身）与 `dependencies`（上游源库）两个字段，并与 tgz 文件名交叉确认。

package/vendor/Archive/data/docs/experiences/rnoh-arkts-sqlite-rows-array-format.md

@@ -0,0 +1,18 @@
+## RNOH sqlite 库 ArkTS 层 SELECT 返回 rows 为数组，与上游 iOS/Android 形态不一致
+
+### 问题现象
+
+react-native-sqlite-storage 的鸿蒙实现中，SELECT 查询返回 `{rowsAffected, rows: [...]}`（**rows 为数组**，见 SQLitePluginTurboModule.ts 的 `queryResultcall = { 'rowsAffected': 0, 'rows': results }`），而上游 iOS/Android 返回 RS 对象（`{length, item(i)}`）。照搬上游示例的取值代码（如 `rows.item(0)` 或 `rows.length`）在鸿蒙侧行为异常。
+
+### 解决方案
+
+Demo/测试代码必须兼容两种形态：
+
+```typescript
+const row = Array.isArray(rows) ? rows[0] : rows.item(0);
+const count = Array.isArray(rows) ? rows.length : rows.length;
+```
+
+### 结果
+
+同一份 Demo 代码在鸿蒙与 iOS/Android 形态下均可正常取值。**鸿蒙化库写 Demo 时不能照搬上游示例的返回值取用代码**，必须先查证鸿蒙侧 TurboModule 的实际返回结构（读 `harmony/` 模块源码中 methodMap 对应实现）。

package/vendor/Archive/data/docs/experiences/rnoh-dependency-residue-scan-strategy.md

@@ -0,0 +1,18 @@
+## RNOH 依赖残留分层判定与大仓库扫描安全策略
+
+### 问题现象
+1. 三方库升级后扫描"旧版本依赖残留"时，`grep -rn '"pkg": "0.82...' example packages` 在含 node_modules（example npm install 后数百 MB）的仓库上 120s 超时被强制终止。
+2. 扫描发现 devDependencies 中存在旧版本工具链（如 `@react-native/eslint-config: 0.82.0`）时，直接判"核验失败"或隐藏不报都是错误处置。
+
+### 解决方案
+**扫描执行安全**（解决超时与误报）：
+- 用 `rg` 替代 `grep` 全量扫描，并叠加排除参数：`-g '!node_modules' -g '!oh_modules' -g '!package-lock.json' -g '!*.har' -g '!*.hap' -g '!\.git'`
+- 只扫依赖清单白名单文件：根/example 的 package.json、oh-package.json5、nitro.json、overrides/resolutions
+- 只匹配 RNOH 框架相关包名的版本号模式（react-native / react-native-harmony / @rnoh/react-native-openharmony / nitro-modules / harmony-cli）
+
+**残留分层判定**（二分法）：
+- **框架/运行时/编译链依赖（阻断项）**：属于 RNOH 框架依赖、参与编译链（HAR→tgz→codegen→JS Bundle→ohpm→devecocli build）或参与运行时的旧版本引用 → 判核验失败；
+- **开发工具依赖滞后（记录项）**：如 ESLint 配置等代码风格工具，不参与编译链与运行时 → 非阻断。定性时做三对照：上游基线版本（diff-output 中上游 package.json）+ example 侧同款版本 + 编译链涉及范围。
+
+### 结果
+实测 30s 内完成扫描、零误报；`@react-native/eslint-config: 0.82.0` 判定为低风险 devDep 遗留（上游 4.3.2 基线用 0.85.3，example 侧同款已升 0.84.1）。处置原则：如实写入核验记录"遗留记录"节 + 给出风险定性（低风险）+ 不阻断验收。隐藏不报或直接判失败都是错误的。