@ohos-cpf/3rdloop 0.0.8 → 0.0.9

package/vendor/Archive/data/docs/experiences/rnoh-example-local-lib-dep-use-tgz.md

@@ -0,0 +1,53 @@
+## RNOH example 本地库依赖必须用 npm pack tgz，禁止 file: 目录形式
+
+### 问题现象
+
+为 RN 鸿蒙三方库创建 example 工程时，在 `example/package.json` 中用目录形式的本地依赖（如 `"@react-native-ohos/xxx": "file:.."` 指向库根目录），`npm install` 后 node_modules 中该包为**符号链接**（`lrwxr-xr-x ... -> ../../..`，链接目标在 example 工程目录之外）。执行 `npm run dev` 报错：
+
+```
+Unable to resolve module @react-native-ohos/... could not be found within the project
+```
+
+原因：npm（实测 11.6.2）对目录型 `file:` 依赖默认以 symlink 方式安装，Metro/watchman 文件解析不跟随工程目录外的符号链接。
+
+### 解决方案
+
+1. 库根先在 `.npmignore` 中排除 `example`（否则整个 example 工程会被打进库包）
+2. 库根执行 `npm pack` 生成 `react-native-ohos-{包名去scope横线}-{版本}.tgz`
+3. example 依赖改为 `file:../{tgz文件名}`（如 `"file:../react-native-ohos-netinfo-12.0.1.tgz"`）
+4. 删除 node_modules 中旧符号链接后重新 `npm install` → node_modules 中变为实体目录
+
+同步的库根工程卫生：
+- `.gitignore` 追加 `harmony/{module}/oh_modules`、`harmony/{module}/oh-package-lock.json5`（ohpm --all 会在库源码模块内产生构建产物）
+- tgz 产物留在库根是 CPF-RN 系列仓库（netinfo、async-storage 等）的既定惯例
+
+### 结果
+
+node_modules 中库包为实体目录，Metro 解析正常，`npm run dev` 与鸿蒙编译全链路通过。CPF-RN 系列仓库的 example 均采用 tgz 方式，这是既定惯例，不要用 `file:..` 目录形式。
+
+---
+
+### 补充：node_modules 布局变更后必须清 Metro/watchman 缓存
+
+### 问题现象
+
+将 symlink 依赖替换为实体 tgz 目录后重跑构建，报错：
+
+```
+TreeFS: Could not add directory node_modules/@react-native-ohos/xxx ... already exists in the file map as a file
+```
+
+原因：Metro 文件映射缓存仍记录旧路径（该路径曾被记录为文件）。
+
+### 解决方案
+
+```bash
+rm -rf node_modules/.cache
+watchman watch-del-all
+```
+
+（或至少 `watchman watch-del` 当前工程）后重跑构建。
+
+### 结果
+
+构建成功。经验法则：**任何 node_modules 结构调整（symlink↔实体、删除重装）后都要清缓存再构建**。

package/vendor/Archive/data/docs/experiences/rnoh-example-prereserve-rntesterlist.md

@@ -0,0 +1,17 @@
+## 创建 RNOH example 壳层时必须预置 RNTesterList.ts 注册入口
+
+### 问题现象
+
+下游技能（rnoh-lib-demo-create / rnoh-cptf-api-test）探查 Demo 注册入口的**第一优先级是 `{projectRoot}/**/RNTesterList.ts`**（模式 A：`{key, category, module: require(...)}` 数组），而 example 模板原生只有 `App.tsx + tests/index.tsx` 模式、不含 RNTesterList——两者存在断层，导致后续 Demo 生成步骤探查不到注册入口。
+
+### 解决方案
+
+创建 example 壳层时在 `src/RNTesterList.ts` **预置模式 A 注册入口**：
+
+- 首项指向 `{exampleDir}/{libName}` 的 index.tsx（结构：`{key: '{libName}', category: '{category}', module: require('./{libName}')}`）
+- `App.tsx` 消费该列表渲染 Navigation 页面
+- 同时预置 1 个冒烟 Demo（如 sqlite 库的 openDatabase→executeSql→close 全链路）验证注册链路与原生桥通，保证不是空壳
+
+### 结果
+
+后续 Demo 生成步骤只需向 RNTesterList.ts 数组追加 `{key, category, module}` 条目即完成注册，与下游技能（rnoh-lib-demo-create 等）的探查逻辑（RNTesterList.ts 第一优先级）无缝衔接。

package/vendor/Archive/data/docs/experiences/rnoh-example-template-compatiblesdkversion-upgrade.md

@@ -0,0 +1,29 @@
+## RNOH example 模板 compatibleSdkVersion 必须手动升级
+
+### 问题现象
+从 RN3rdTemplate 模板仓库获取的 example 工程默认 `compatibleSdkVersion: '5.0.0(12)'`（API 12），但 RNOH 0.84 的 HAR 包元数据声明最低需要 API 17。构建时报错：
+```
+Error Message: The project's compatibleSdkVersion: 12 cannot be lower than the minimum compatible version 17 required by the dependencies: @react-native-ohos/netinfo.
+```
+此错误属于 `Specification Limit Violation`，构建直接失败。
+
+### 解决方案
+从 RN3rdTemplate 获取 example 模板后，必须手动升级 `example/harmony/build-profile.json5` 中的 `compatibleSdkVersion`：
+
+```json5
+// 修改前（模板默认）
+"compatibleSdkVersion": "5.0.0(12)"
+
+// 修改后（RNOH 0.84 要求）
+"compatibleSdkVersion": "5.0.5(17)"
+```
+
+**API 版本对应表**：
+| RNOH 版本 | 最低 API 版本 | compatibleSdkVersion |
+|-----------|-------------|---------------------|
+| 0.77 | 14 | 5.0.2(14) |
+| 0.82 | 15 | 5.0.3(15) |
+| 0.84 | 17 | 5.0.5(17) |
+
+### 结果
+升级 compatibleSdkVersion 后，`devecocli build` 不再报 `Specification Limit Violation` 错误，构建正常通过。此步骤是从模板创建 example 工程后的必做操作。

package/vendor/Archive/data/docs/experiences/rnoh-example-turbomodule-shell-adaptation-checklist.md

@@ -0,0 +1,41 @@
+## RNOH TurboModule 库 example 壳层适配清单与渐进式验证链
+
+### 问题现象
+
+基于 RNOH 模板为 TurboModule 三方库创建 example 壳层工程时，模板不能直接编译目标库，需适配多个 JS/Harmony 侧文件；且一次性做鸿蒙编译排查问题成本高。
+
+### 解决方案
+
+**壳层适配必查清单**（已在 sqlite-storage 库全量验证）：
+
+| 文件 | 适配内容 |
+|------|----------|
+| `harmony/entry/oh-package.json5` | 库 HAR 走 `file:../../node_modules/{ohPkg}/harmony/{module}.har` |
+| `harmony/entry/src/main/cpp/CMakeLists.txt` | `add_subdirectory` 指向 **node_modules**（严禁 oh_modules，HAR 无 cpp 源码）：`${NODE_MODULES}/{ohPkg}/{sourceModulePath}/src/main/cpp` |
+| `harmony/entry/src/main/cpp/PackageProvider.cpp` | include + make_shared `<cppPackageClassName>` |
+| `harmony/entry/src/main/ets/RNPackagesFactory.ets` | import 自 `<ohPkg>/ts`，new `<etsPackageClassName>`(ctx) |
+| `harmony/entry/src/main/ets/pages/Index.ets` | 纯 TurboModule 库：buildCustomRNComponent 保持空、arkTsComponentNames 为空数组 |
+| `harmony/build-profile.template.json5` | modules 追加库源码模块 `{name: '{harmonyModuleName}', srcPath: '../../harmony/{module}'}`；删除 `useNormalizedOHMUrl`；改 template 而非 build-profile.json5（postinstall 会覆盖） |
+| `module.json5` | 权限最小化（如 sqlite 仅 INTERNET；模板残留的 CAMERA/MICROPHONE 应删除） |
+| `metro.config.js` / `tsconfig.json` | `<alias>` → `node_modules/<ohPkg>` 映射 |
+
+**渐进式验证链**（全部通过的标准动作）：
+
+```
+1. cd example && npm install --legacy-peer-deps        # postinstall 生成 build-profile.json5
+2. npm run dev                                          # codegen + bundle-harmony → rawfile/bundle.harmony.js
+3. cd harmony && ohpm install --all                     # HAR 从 node_modules 经 file: 解析
+4. hvigorw assembleHap --no-daemon                      # CMake/Ninja + HAP 打包
+5. nm -gU .../librnoh_app.so | grep <cppPackageClassName>  # 确认库 C++ 包符号已链入
+```
+
+### 结果
+
+全链路 BUILD SUCCESSFUL。要点：
+
+- 第 2 步（npm run dev）就能暴露 alias/依赖问题，**成本最低，不要跳过直接做鸿蒙编译**
+- bundle 产物可 grep 校验：应含 Demo 特征字符串（如 `smoke_test.db`）、不应含模板残留（如 `camera`）
+- 未配置 signingConfigs 时产出 **unsigned HAP 属预期**（模板不携带签名证书），不是构建失败；真机部署前在 build-profile.json5 补签名即可
+- hvigor 调用方式：`/Applications/DevEco-Studio.app/Contents/tools/node/bin/node /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js assembleHap --no-daemon`（用 DevEco 自带 node）
+- RNOH **0.82** 的 `compatibleSdkVersion: '5.0.0(12)'` 可直接使用；知识库中"必须升级 API 17"的经验仅适用于 0.84
+- 创建 example 前先读库元数据（package.json 的 harmony.autolinking 字段），所有壳层文件的类名/路径/链接目标均由它派生，不要手抄

package/vendor/Archive/data/docs/experiences/rnoh-mcp-build-project-tool-risk.md

@@ -0,0 +1,18 @@
+## MCP deveco-mcp_build_project 工具可能构建错误项目
+
+### 问题现象
+使用 MCP `deveco-mcp_build_project` 工具对鸿蒙工程执行构建时，返回 `BUILD SUCCESSFUL` 但实际并未构建工作目录中的目标工程。该工具似乎使用 DevEco Studio 当前打开的项目，而非命令行指定的工作目录中的项目。如果仅依赖 MCP 工具的构建结果，会误认为编译通过而实际未通过。
+
+### 解决方案
+不要使用 MCP `deveco-mcp_build_project` 工具进行编译验证，改用 `devecocli build` 命令在项目目录中执行构建：
+
+```bash
+# 在 example/harmony 目录下执行
+cd example/harmony
+devecocli build --product default --build-mode debug
+```
+
+`devecocli build` 会自动解析模块依赖并在当前目录的工程上下文中执行构建，确保构建的是正确的项目。
+
+### 结果
+使用 `devecocli build` 后，构建结果准确反映当前工作目录工程的编译状态。避免了因 MCP 工具构建了错误项目而误判编译通过的陷阱。此问题在多任务并行开发时尤为危险——可能构建了另一个任务的工程而误认为当前任务编译通过。

package/vendor/Archive/data/docs/experiences/rnoh-npm-devdependencies-version-precheck.md

@@ -0,0 +1,29 @@
+## RN 框架升级时 npm devDependencies 版本可用性预检
+
+### 问题现象
+升级 RN 框架版本时（如 0.82→0.84），更新 package.json 中的 devDependencies 版本后执行 `npm install`，部分包因目标版本在 npm registry 中不存在而导致安装失败：
+- `@types/react-test-renderer@^19.2.0` — npm registry 中最高仅 19.1.0（无 19.2.x）
+- `react-native-macos@^0.84.1` — npm registry 中最高仅 0.81.9（尚未发布 0.84 对应版本）
+
+### 解决方案
+在更新 devDependencies 版本前，先使用 `npm view` 命令检查目标版本是否存在：
+
+```bash
+# 检查包的所有可用版本
+npm view <package> versions --json
+
+# 检查最新版本
+npm view <package> version
+```
+
+对于可能没有对应版本发布的包，使用兼容范围版本而非精确版本：
+- `@types/react-test-renderer` → 使用 `^19.0.0`（实际最高 19.1.0）
+- `react-native-macos` → 使用 `^0.81.9`（实际最高 0.81.9）
+
+**需特别关注的包**（可能滞后于 RN 主版本发布）：
+- `react-native-macos` — macOS 平台适配，通常滞后
+- `@types/react-test-renderer` — 类型定义包，可能滞后于 React 版本
+- 其他平台特定包（@types/*, react-native-windows 等）
+
+### 结果
+使用兼容范围版本后，`npm install --legacy-peer-deps` 成功完成，无版本解析失败错误。通过预检可以避免因版本不存在导致的安装失败，减少反复修改 package.json 的工作量。

package/vendor/Archive/data/docs/experiences/rnoh-repo-baseline-version-verification.md

@@ -0,0 +1,13 @@
+## 鸿蒙化仓库基线版本核验：任务指定的分支-基线组合可能不符
+
+### 问题现象
+任务指定「br_rnoh0.77 分支鸿蒙化基线版本 16.1.3」，实际核验发现 br_rnoh0.77 分支的 package.json 版本为 15.1.2（README.OpenSource 上游基线 15.1.0），而 16.1.3 基线（commit ca7aa46，含 82 项框架适配）实际在 **master 分支**。直接按任务描述假设分支-基线组合会导致 diff 基线选错。
+
+### 解决方案
+对任务指定的「分支-基线」组合一律先核验（可靠性从高到低）：
+1. `README.OpenSource` 的 `Version Number` 字段 — **最可靠**，是鸿蒙化仓库的权威声明
+2. `git log --all --grep="<版本号>"` + `git branch -a --contains <commit>` 定位版本提交所在分支
+3. `git show origin/<branch>:package.json` 交叉验证各分支的 package.json 版本
+
+### 结果
+核验后输出各分支版本矩阵（分支 × package.json 版本 × README.OpenSource 上游基线），在报告开篇显式澄清实际基线所在分支，避免下游基于错误基线做 diff 或升级。

package/vendor/Archive/data/docs/experiences/rnoh-repo-upstream-directory-mapping.md

@@ -0,0 +1,18 @@
+## 鸿蒙化仓库与上游的 JS 层目录结构存在系统性映射差异
+
+### 问题现象
+鸿蒙化仓库并非原样保留上游 src/ 结构，直接按上游路径合并 patch 时文件定位失败。以 react-native-camera-kit 为例的系统性映射差异：
+
+| 上游路径 | 鸿蒙仓库对应 |
+|----------|-------------|
+| `src/specs/CameraNativeComponent.ts` | `src/CameraKitNativeComponent.ts`（重命名+扩展） |
+| `src/types.ts` | `types/types.ts` |
+| `src/CameraProps.ts` | `types/CameraProps.ts` |
+| `src/Camera.android.tsx` / `Camera.ios.tsx` | `src/Camera.tsx`（自有实现，DeviceEventEmitter 桥接） |
+| `src/specs/NativeCameraKitModule.ts` | `src/NativeCameraKit.tsx` |
+
+### 解决方案
+合并 patch 前先建立「上游→鸿蒙」目录映射表（覆盖 Spec 文件、types、平台实现文件、codegen 脚本入口的对应关系），再按映射表转写文件变更，**不得假设鸿蒙仓库保留上游目录结构**。另注意 codegen 入口不同：鸿蒙侧使用自有脚本（如 camera-kit 的 `scripts/codegen-lib.js`，调用 react-native-harmony-cli 的 `commandCodegenLibHarmony`，指定 cpp/arkts 双输出）。
+
+### 结果
+按映射表转写后，Phase 2 精简 patch 从 280KB 缩至 9.3KB / 7 个相关文件；映射表可直接供后续 code-adapt 适配阶段引用，避免二次人工摸索路径。

package/vendor/Archive/data/docs/experiences/rnoh-stateless-library-zero-leak-verification.md

@@ -0,0 +1,31 @@
+# RNOH 无状态库"零泄露面"穷尽验证模式集
+
+### 问题现象
+
+RN 三方库鸿蒙化为纯 TurboModule 形态（无 NativeComponent），业务能力全部映射到鸿蒙系统静态一次性 API（如 `WebCookieManager` 的 fetchCookie/configCookieSync 等）时，整个实现呈现"零状态"特征：无事件监听（无 on/off、无 NativeEventEmitter/DeviceEventEmitter）、无 Map/Set/缓存容器、无实例字段、C++ 层为纯无捕获静态 host function 转发（零 NAPI 调用、零 new/malloc）。对这类库，内存检视重点应从"释放是否完整"转向"是否真的不存在隐藏的持有"，需要穷尽验证后才能下"零泄露面"结论。
+
+### 解决方案
+
+用以下 rg 模式集做穷尽验证（全库 0 命中即可确认零泄露面）：
+
+```bash
+# 1. 生命周期/监听/订阅
+rg -n "__onDestroy__|onDestroy|aboutToDisappear|onDropViewInstance|addListener|removeListener|EventEmitter|addEventListener" <ets/cpp/js 目录>
+# 2. 鸿蒙 on/off 订阅对
+rg -n "\.on\(|\.off\(" <ets 目录>
+# 3. 容器与静态状态
+rg -n "Map<|Set<|static |private " <ets 目录> --glob '*.ts' --glob '*.ets'
+# 4. C++ 内存与 NAPI（仅手写文件）
+rg -n "new |malloc|napi_|delete |free\(" <cpp 目录> -g '<手写文件 pattern>'
+# 5. 定时器
+rg -n "setInterval|setTimeout" <ets 目录>
+```
+
+要点：
+- C++ 检查必须区分手写文件与 `generated/` 目录（用 `-g` 限定只查手写文件），避免 codegen 产物干扰统计。
+- codegen 生成的空壳文件（EventEmitters/Props/ShadowNodes 等）单独确认"空实现无资源"即可，不逐文件深查。
+- codegen 组件空壳快速判定：无 NativeComponent 的库 codegen 仍会生成组件文件，看 Package 头文件（如 `BaseReactNativeXXXPackage.h`）中 `createComponentDescriptorProviders()`/`createComponentJSIBinderByName()` 返回值是否为空集合、`supportedComponentNames/supportedEventNames` 是否为空 vector——是则整组组件文件按空壳处理，NativeComponent 维度记"不适用"而非"通过"。
+
+### 结果
+
+rntpc_cookies（@react-native-ohos/cookies）实测六组模式全部 0 命中，确认零泄露面，内存检视评分 95/100（仅 1 处死代码单例轻微扣 5 分）。该验证模式集可作为所有 RNOH 鸿蒙化库无状态判定的标准流程，避免遗漏隐藏持有。

package/vendor/Archive/data/docs/experiences/rnoh-template-npmrc-credential-removal.md

@@ -0,0 +1,15 @@
+## RNOH 模板拷贝后必须立即删除含凭据的 .npmrc
+
+### 问题现象
+
+从模板创建 RNOH example 工程时，模板目录可能自带 `.npmrc`，其中内嵌私有 registry（如 swmansion）的 GitHub PAT **明文 `_authToken`**，且拷贝脚本默认不排除该文件，凭据会随交付物扩散。
+
+### 解决方案
+
+1. 拷贝模板后**第一件事**：检查并删除 `.npmrc`
+2. RNOH 0.82 全部依赖（`@react-native-oh/react-native-harmony` 0.82.30+ 等）可从公共 registry（npmmirror）解析，无需私有源
+3. 建议拷贝模板脚本显式排除 `.npmrc`；若需保留 registry 配置，改用不含 token 的镜像地址
+
+### 结果
+
+交付物中无凭据泄露。**任何含凭据的文件（.npmrc token、签名私钥等）严禁带入交付物**。

package/vendor/Archive/data/docs/experiences/rnoh-turbomodule-codegen-wiring-verification.md

@@ -0,0 +1,19 @@
+# RNOH 手写/codegen 双轨 TurboModule 接线验证方法
+
+### 问题现象
+
+RN 鸿蒙化库中经常同时存在手写 C++ TurboModule 类（如 `RTNCookiesTurboModule`）与 codegen 生成的同名 TurboModule（`generated/RNOH/generated/turbo_modules/RTNCookies.cpp`），两套实现方法数还不一致。仅看文件是否存在无法判断哪个真正生效，会把未接线的手写死代码当作实际实现来分析，得出错误结论。
+
+### 解决方案
+
+判断 C++ TurboModule 哪个真正生效，**不要看文件是否存在，而要看 Package 工厂链路中实际创建的类名**：
+
+1. 打开库的 Package 头文件（如 `BaseReactNativeCookiesPackage.h`，通常由 codegen 生成）
+2. 查看 `createTurboModule()` / 工厂方法中 `std::make_shared<XXX>` 实际实例化的类名
+3. `std::make_shared` 指向 codegen 生成类 → 手写类为未接线死代码；指向手写类 → codegen 类仅是接口壳
+
+若手写类未接线：它是死代码，运行期零分配零调用，内存上无泄露影响。此类发现应在检视报告中记为"观察项（0 分）"，注明无内存影响、建议归属编码质量/一致性检视阶段处理，不应计入内存扣分。
+
+### 结果
+
+rntpc_cookies 实测：`BaseReactNativeCookiesPackage.h:15-21` 只实例化 codegen 生成的 `RTNCookies`（5 方法），手写 `RTNCookiesTurboModule`（7 方法）为未接线死代码，按观察项（0 分）记录，未影响内存评分（95/100）。该方法适用于所有 RNOH 鸿蒙化库的 C++ 层分析。

package/vendor/Archive/data/docs/experiences/rnoh-turbomodule-cpp-methodmap-compatibility-check.md

@@ -0,0 +1,20 @@
+## RNOH TurboModule C++/ArkTS methodMap_ 兼容性预检方法
+
+### 问题现象
+升级 RNOH 框架版本时（如 0.82→0.84），上游三方库可能引入新的 TurboModule Spec 文件（如 `NativeRNCNetInfo.ts`）和 `__turboModuleProxy` 加载逻辑。需要判断鸿蒙侧 C++ methodMap_ 和 ArkTS TurboModule 是否需要对应修改，还是仅需通过 npm 依赖升级自动同步。
+
+### 解决方案
+在执行代码适配前，先对比上游 TurboModule Spec 中定义的方法签名与鸿蒙侧 C++ methodMap_ 和 ArkTS TurboModule 实现的方法列表：
+
+1. 读取上游 Spec 文件（`*Native*.ts`），提取所有方法签名
+2. 读取鸿蒙侧 C++ 代码中的 `methodMap_` 数组，提取已注册的方法名
+3. 读取鸿蒙侧 ArkTS TurboModule 实现，提取方法列表
+4. 对比三者的方法名和参数签名
+
+**判断规则**：
+- 如果上游 Spec 定义的方法与鸿蒙侧 C++ methodMap_ 和 ArkTS 实现完全匹配 → **无需任何 C++/ArkTS 代码修改**，仅需通过 npm 依赖升级自动同步 JS 层变更
+- 如果上游新增方法 → 需在鸿蒙侧 C++ 和 ArkTS 中新增对应实现
+- 如果上游删除/重命名方法 → 需清理鸿蒙侧旧实现
+
+### 结果
+以 rntpc_react-native-netinfo 0.82→0.84 升级为例：上游 v11.4.1→v12.0.1 引入了 `NativeRNCNetInfo.ts` Spec，定义了 4 个方法（configure/getCurrentState/addListener/removeListeners）。鸿蒙侧 C++ methodMap_ 和 ArkTS TurboModule 已包含完全相同的 4 个方法，因此无需任何 C++/ArkTS 代码修改，仅通过 npm 依赖升级即自动同步 JS 层变更。此预检可大幅减少不必要的工作量。

package/vendor/Archive/data/docs/experiences/scenario-doc-vs-source-signature-diff-four-patterns.md

@@ -0,0 +1,24 @@
+## 三方库 Demo 生成：场景文档与库源码签名差异四类模式与核对策略
+
+### 问题现象
+
+基于 Demo 场景描述文档生成 ArkTS 代码时，场景文档中的接口签名与库源码实际签名存在系统性差异（mp3agic 案例：6 处差异，全部通过"逐接口 read_file 源码核实"拦截，未凭文档字面值编码）。差异可归纳为四类：
+
+1. **容器类型不一致**：文档写 `Array<T>`，源码实为 `JList<T>`（如 setChapters/setChapterTOC/getChapters/getChapterTOC）
+2. **参数形态不一致**：文档写数组传参 `arrays: any[]`，源码为 rest 参数 `...arrays`（如 BufferTools.mergeArrayBuffer），调用必须展开为多参数
+3. **声明返回类型与实际不符**：源码声明 `number` 实际返回数组（如 unsynchroniseBuffer），源于库 `.ts` 文件带 `@ts-nocheck`，编译器不校验
+4. **接口行为与文档预期相反**：方法无条件抛异常（如 ID3v2ObseleteFrame.packFrame 无条件抛 NotSupportedException）或内部缺陷（如 ID3v24Tag.setGenreDescription 缺 `this.` 前缀，运行时抛 ReferenceError）
+
+另有符号约定陷阱：`BufferTools.setBit(0, 7, true)` 返回 Int8 有符号值 -128 而非 128。
+
+### 解决方案
+
+- 生成前对**容器参数类型、rest 参数、返回类型、无条件抛异常方法**四类差异做专项核对（比全量核对更聚焦）
+- 每个接口必须 read_file 库源码确认签名，**以源码为准**，禁止按场景文档字面值编码
+- **声明返回类型与实际不符的容错展示**：库源码带 @ts-nocheck 时，按声明类型接值（编译通过），用 `String(result)` 展示实际内容并在代码注释说明差异，避免 `as` 二次强转引入新编译错误
+- **行为与文档相反的接口演示策略**：无条件抛异常的接口按真实行为 try/catch 捕获展示异常名与消息，验证点注释标注"源码真实行为"，不捏造成功路径
+- 按源码参数序精确构造对象，可选参数用 undefined 占位（如 `ID3v2ChapterTOCFrameData(false, undefined, true, true, 'toc01', undefined)` 后再 setChilds）
+
+### 结果
+
+mp3agic Demo 生成中 6 处差异全部在编码前拦截，未产生签名相关编译循环。三方库 `.ts` 源码普遍带 `@ts-nocheck`，场景文档签名不可尽信，专项核对策略可复用于其他三方库 Demo 生成任务。

package/vendor/Archive/data/docs/experiences/static-analysis-grep-cross-validation.md

@@ -0,0 +1,29 @@
+# 静态分析工具输出的 grep 盘点交叉验证方法
+
+### 问题现象
+
+基于 AST/正则的 XTS 覆盖率分析脚本对 mp3agic 库输出 8/271（2.95%），而人工核验的真实覆盖为 100/271（36.90%），偏差 12 倍以上。脚本全程无报错、无降级提示（静默失败），失真结果险些被写入正式报告。
+
+### 解决方案
+
+**"人工 grep 盘点 + 逐类对账"验证法**：
+
+```bash
+# 盘点实例方法调用（变量名.方法名 形式，变量名按目标库测试代码整理）
+grep -ohE "(iD3v2[A-Za-z]*|encodedText|jList|bean[0-9]?)\.[a-zA-Z_]+\(" *.ets | sort | uniq -c | sort -rn
+# 盘点静态方法调用（类名.方法名 形式）
+grep -ohE "\b(BufferTools|ID3v2Frame|...)\.[a-zA-Z_]+\(" *.ets | sort | uniq -c
+```
+
+将 grep 结果按类聚合并与脚本输出的类级覆盖率表逐行核对。
+
+**三条可疑信号**（任一命中即应触发排查）：
+1. 覆盖率异常低（<5%）但测试文件体量大（2000+ 行）→ 必然有匹配缺陷
+2. 某个内容充实的测试文件覆盖数为 0 → 该文件 import 风格未被识别
+3. 类级覆盖率表中"仅静态/工具类有覆盖、所有实例方法类为 0" → 模块解析失败、类型推断失效的典型特征
+
+### 结果
+
+该方法一次性发现并证实了脚本全部 3 处匹配缺陷（深层路径 import 不识别、大小写不敏感文件系统模块解析失败、ESObject 声明变量追踪失效），修复后结果与人工盘点逐类一致。
+
+通用结论：**任何基于静态分析的工具输出，在写入正式报告前都应用轻量级动态手段（grep/wc）做一次 sanity check**——静态工具的静默失败模式远比报错危险。补丁验证应在临时目录的脚本副本上进行，验证通过后再合入共享脚本，避免影响后续任务且便于回归。