@ohos-cpf/3rdloop 0.0.7 → 0.0.9

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

@@ -0,0 +1,133 @@
+## TurboModule 库（非 Fabric 组件）的测试策略差异
+
+### 问题现象
+NetInfo 是一个 TurboModule 库，不是 Fabric 组件库。按照 Fabric 组件库的测试策略编写 jest 单元测试时，会出现 mock 策略不匹配的问题：不需要 mock `codegenNativeComponent` 生成的 Fabric 原生组件，但需要 mock `NativeEventEmitter` 和 `NativeModules`（从 `react-native` 导入）。
+
+### 解决方案
+TurboModule 库的 jest mock 需求与 Fabric 组件库不同：
+- **不需要** mock `codegenNativeComponent` 生成的 Fabric 原生组件
+- **需要** mock `NativeEventEmitter` 和 `NativeModules`（从 `react-native` 导入）
+- **关键**：`NativeEventEmitter.addListener` 必须返回 `{ remove: () => void }` 对象（模拟 RN 的 `NativeEventSubscription`），而非 Node EventEmitter 的默认返回值。否则 `State.tearDown()` 中的 `this._nativeEventSubscription.remove()` 会报 `TypeError: ...remove is not a function`
+
+mock 实现示例：
+```javascript
+// __mocks__/react-native.js
+const { EventEmitter } = require('events');
+class MockNativeEventEmitter extends EventEmitter {
+  addListener(eventName, handler) {
+    const listener = super.addListener(eventName, handler);
+    return { remove: () => super.removeListener(eventName, handler) };
+  }
+}
+```
+
+### 结果
+TurboModule 库测试通过。这是所有 TurboModule 库通用的 mock 需求：`NativeEventEmitter`（返回 `{remove}` 对象的 `addListener`）、`NativeModules`、`Platform`。
+
+---
+
+## 导入路径从相对路径到包名的转换
+
+### 问题现象
+上游 demo 使用相对路径 `'../src'` 和 `'../../src'` 引用库源码。移植到 example 工程后，这些路径会解析到错误的目录（`example/src/` 自身而非库根目录的 `src/`），导致编译错误或导入了错误的模块。
+
+### 解决方案
+将所有导入路径改为包名 `'@react-native-ohos/netinfo'`，让 Metro 的 resolver 正确重定向。批量定位方法：`grep -rl "'../src'" example/src/`
+
+### 结果
+所有导入路径正确解析到库源码，编译通过。
+
+---
+
+## metro.config.js React 单例保护（tgz 包场景）
+
+### 问题现象
+即使通过 tgz 包安装（非 symlink 到库根目录），当 `watchFolders` 包含库根目录时，Metro 的 `nodeModulesPaths` 会包含库根目录的 `node_modules/react`，可能在不同导入上下文中解析到不同的 React 实例，导致 hooks 失效崩溃。
+
+### 解决方案
+在 `metro.config.js` 中包装 RNOH 的 `resolveRequest`：
+1. 先获取 RNOH 的 `resolveRequest` 引用
+2. 在包装函数中拦截裸 `react` 导入，强制解析到 example 的 `node_modules/react`
+3. 其余导入委托给 RNOH 的 resolver
+
+**关键约束**：不能直接设置 `resolveRequest` 覆盖 RNOH 的 harmony 解析器——这会导致 `.harmony.js` 平台文件解析全部失效。必须**包装** RNOH 的 `resolveRequest`，只拦截裸 `react` 导入。
+
+验证方法：`grep -oE '(node_modules|\.\./node_modules)/react/index\.js' bundle.harmony.js | sort | uniq -c`，应只有 1 个路径。
+
+### 结果
+React 单例保证，hooks 正常工作。
+
+---
+
+## useNetInfoInstance 的 configuration 参数无限重渲染
+
+### 问题现象
+在测试或 demo 中向 `useNetInfoInstance` 传入内联 configuration 对象（如 `<Comp config={{reachabilityShouldRun: () => true}} />`）时，每次渲染都会创建新对象引用，触发 `useEffect` 重新执行，调用 `setNetworkInfoManager(state)` 触发再次渲染，形成无限循环导致 Jest OOM。
+
+### 解决方案
+这是上游设计限制。`useNetInfoInstance` 的 `useEffect` 依赖 `[isPaused, configuration]`，内联对象引用每次都不同。测试中需避免传入内联 configuration，应使用 `useMemo` 或将配置定义为模块级常量。
+
+### 结果
+避免无限循环，测试正常运行。
+
+---
+
+## Jest 测试踩坑：mockReset 后 getCurrentState 返回 undefined
+
+### 问题现象
+`Cannot read properties of undefined (reading 'isInternetReachable')` 错误。
+
+### 解决方案
+`beforeEach` 中 `mockReset()` 后 `getCurrentState` 返回 `undefined`，`configure()` 创建新 State 时构造函数调用 `_fetchCurrentState()` 拿到 undefined。需在 `beforeEach` 中 `mockReset()` 后立即 `mockResolvedValue(defaultState)`。
+
+### 结果
+State 初始化正常，不再报 undefined 错误。
+
+---
+
+## Jest 测试踩坑：fetch() 无参数时 getCurrentState 未被调用
+
+### 问题现象
+测试中验证 `fetch()` 调用了 `getCurrentState`，但断言失败——`getCurrentState` 未被调用。
+
+### 解决方案
+`latest()` 方法有缓存时直接返回 `Promise.resolve(this._latestState)`，不调用 `getCurrentState`。测试中需要先 emit 事件设置缓存，再验证 `fetch()` 返回缓存值，而非验证 `getCurrentState` 被调用。
+
+### 结果
+测试断言正确反映实际行为。
+
+---
+
+## TurboModule 库的 jest 配置模板
+
+### 问题现象
+TurboModule 库同时有 `src/__tests__/` 和 `example/` 目录，jest 配置需要正确处理模块解析和测试文件范围。
+
+### 解决方案
+`__mocks__/react-native.js` 中需要提供 `NativeEventEmitter`（返回 `{remove}` 对象的 `addListener`）、`NativeModules`、`Platform`。这是所有 TurboModule 库通用的 mock 需求。
+
+库根目录 `jest.config.js` 模板要点：
+- `moduleNameMapper` 统一 `react-native` → mock 和 `react` → 单一路径
+- `testMatch` 精确限定到 `src/__tests__/*.spec.ts`，避免扫描 `example/harmony/oh_modules`
+- `tsconfig.jest.json` 不继承 `@react-native/typescript-config`
+
+### 结果
+jest 配置正确，测试扫描范围精确，模块解析统一。
+
+---
+
+## 测试覆盖率扫描方法（TurboModule 库）
+
+### 问题现象
+对于 NetInfo 这种非组件库（TurboModule 库），覆盖率维度与 Fabric 组件库不同，需要不同的扫描方法。
+
+### 解决方案
+从 TurboModule Spec 文件（`*Native*.ts`）提取方法列表，从 `src/index.ts` 提取公开导出的函数/hook，然后对照测试文件搜索每个 API 的使用情况。
+
+TurboModule 库的覆盖率维度包括：
+- **API 覆盖**：TurboModule spec 中定义的方法
+- **状态类型覆盖**：如网络状态 `cellular`、`wifi`、`none`、`unknown` 等各类型
+- **配置选项覆盖**：如 `useNetInfoInstance` 的 `configuration` 参数各选项
+
+### 结果
+覆盖率报告全面覆盖 TurboModule 库的所有维度。

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++ 是否有实现，不能信任上游注释；三条证据齐备才排除，防止过度排除（移出真实接口）与遗漏排除（误触归零）两类方向相反的失真。