@ohos-cpf/3rdloop 0.0.8 → 0.0.9

package/vendor/Archive/data/docs/experiences/arkts-typedarray-buffer-interface-cast-compile-fixes.md

@@ -0,0 +1,36 @@
+## ArkTS 严格模式两类高频编译错误修复模板（TypedArray.buffer / 接口强转实现类）
+
+### 问题现象
+
+ArkTS 严格模式下生成 Demo 代码时两类高频编译错误（mp3agic Demo 生成中 5 个编译错误全部属于这两类）：
+
+1. `arkts-no-structural-typing`：将 `new Uint8Array([1, 2]).buffer` 赋值给 `ArrayBuffer` 类型变量报错。根因：`.buffer` 属性类型为 `ArrayBufferLike`，属结构化类型，严格模式禁止此类赋值。
+2. `neither type sufficiently overlaps`：接口类型向实现类 `as` 强转报错（如 `ID3v2` → `ID3v23Tag`、`ID3v2Frame` → `ID3v2ObseleteFrame`）。根因：接口声明与类成员不重叠时，TS 认为两类型不重叠，直接强转非法。
+
+### 解决方案
+
+**模板 1：TypedArray → ArrayBuffer 安全构造**
+
+```typescript
+// ❌ const buf: ArrayBuffer = new Uint8Array([1, 2]).buffer;  // arkts-no-structural-typing
+// ✅
+const buf: ArrayBuffer = new ArrayBuffer(2);
+const view: Uint8Array = new Uint8Array(buf);
+view[0] = 1; view[1] = 2;
+```
+
+**模板 2：接口 → 实现类安全转型（替代 as 强转）**
+
+```typescript
+// ❌ const tag: ID3v23Tag = mp3.getId3v2Tag() as ID3v23Tag;
+// ✅
+const raw: ID3v2 = mp3.getId3v2Tag();
+if (!(raw instanceof ID3v23Tag)) { /* 错误处理 */ return; }
+const tag: ID3v23Tag = raw;
+```
+
+**注意**：instanceof 收窄修复会引入新的类型引用，必须同步补全对应 import 语句，否则下一轮编译报 `Cannot find name 'X'`。
+
+### 结果
+
+两类写法各消耗一轮编译循环后方才修复；后续遇到同类问题直接套用模板可各避免一轮编译循环。修复引入新类型时同步检查 import 可再省一轮。

package/vendor/Archive/data/docs/experiences/arkts-xts-compile-error-clustering-fix.md

@@ -0,0 +1,24 @@
+## ArkTS XTS 测试编译错误按根因聚类批量修复（含接口/实现类型不匹配等典型模式）
+
+### 问题现象
+mp3agic XTS 测试首轮编译出现 86 个错误。其中存在一类隐蔽的编译阻断：库接口声明的方法返回类型为 `Array<>` 而实现类实际返回 `JList<>`，导致**实现类实例无法赋值给接口类型参数**（如 `setId3v2Tag(v2Tag)`、`getId3v2Tag() === v2Tag`），测试代码中所有"实现类实例 → 接口参数/比较"路径全部编译失败。该类缺陷在 Demo 中不暴露（Demo 从不把具体实现类传给接受接口的方法），只有测试代码首次触达该赋值路径时才显现——**接口签名与实现返回类型不匹配是三方库测试代码的典型编译阻断源**。
+
+### 解决方案
+**按错误根因聚类批量修复**，而非逐条修。mp3agic 86 错误的根因只有 4 类，1 轮清零：
+- 75 × 裸断言 → 括号配平转换器脚本批量转换（1 次）
+- 4 × 重复 import → 去重（1 次）
+- 1 × null 实参 → 等价 falsy 值替换（1 次）
+- 6 × 接口/实现类型不匹配 → 修库接口声明（1 处修复消全部）
+
+**典型错误模式识别表**：
+
+1. **接口/实现返回类型不匹配**：`Argument of type 'ID3v23Tag' is not assignable to parameter of type 'ID3v2'. The types returned by 'getChapters()' are incompatible` + `is missing the following properties from type` → 库接口方法返回类型声明与实现类不一致。修复方式：**修接口声明对齐实现**（如 `Array<>` 改 `JList<>`），而非在测试里强转绕过。属源库机械性修正。
+
+2. **裸断言调用**：subagent 生成 `assertTrue(x)` / `assertEqual(a, b)` 裸函数调用而非 `expect(x).assertTrue()` 链式调用 → 批量 "Cannot find name 'assertTrue'" 错误。修复：编写括号配平转换器（解析顶层逗号切分双参断言、单参断言直接包裹）一次性转换。预防：生成 prompt 中给出断言正反例，明确 `assertTrue(x)` 裸调用是错误写法。
+
+3. **ArkTS 严格空值检查拒收 null 实参**：`new ID3v1Tag(null)` 报 `Argument of type 'null' is not assignable to parameter of type 'string'`。库源码虽有 `@ts-nocheck`，但**测试文件调用库 API 时仍受严格检查约束**。修复：库构造函数用 `if (data)` 判空（空串与 null 语义等价）时，改用 `new ID3v1Tag('')` 覆盖同一路径，需在注释中说明等价性依据。
+
+4. **未从根入口导出的类型需深层路径导入**：实现类（如 ID3v1Tag）与自定义异常类（NoSuchTagException 等）未在 `library/index.ets` 导出，测试需深层路径导入：`import { ID3v1Tag } from '@ohos/mp3agic/src/main/ets/components/mp3agic/ID3v1Tag'`。**异常类必须真实 import 后才能用 `e instanceof XxxException` 做类型断言**。
+
+### 结果
+86 个编译错误 1 轮修复后 clean 全量重建 BUILD SUCCESSFUL（Code Linter 0 Error）。根因聚类修复（4 类各修 1 次）远快于逐条修 86 次。同类错误重复出现在多个文件时，优先写一次性批量转换脚本而非逐文件手改。

package/vendor/Archive/data/docs/experiences/arkts-xts-doc-expected-value-runtime-probe.md

@@ -0,0 +1,35 @@
+## ArkTS 三方库 XTS 测试：用例文档预期值不可盲信，生成前用 Node 运行时探针实测锁定
+
+### 问题现象
+基于 XTS 用例描述文档直接生成断言代码时，文档中的预期结果大量来自对上游原版库（如 Java 版）行为的语义推断，与 ArkTS 移植版实际运行行为存在系统性偏差。mp3agic 案例实测：47 个用例中至少 8 处预期值错误，按文档值直接生成断言必然运行时失败。典型偏差类型：
+
+- **返回类型偏差**：文档预期 `getTrack()` 返回 string `'5'`，实际返回 number `5`（unpackTag 直接存 charCode，未转 string）
+- **越界访问偏差**：文档预期越界流派描述返回 `'Unknown'`，实际返回 `undefined`（数组负索引访问不抛异常，catch 回退分支不可达）
+- **空值返回偏差**：文档预期空标签 `getChapters()` 返回空列表，实际返回 `null`（frameSet 为 null 时直接 return null）
+- **默认值偏差**：文档预期新标签 `getPadding()` 默认 `true`，实际默认 `false`（字段声明 `protected padding: boolean = false`）
+- **异常行为偏差**：文档预期非法编码编号的 `toBytes` 抛 IllegalArgumentException，实际不抛异常返回普通文本字节（`characterSets[9]` 越界取 undefined 而非抛异常）
+- **构造参数语义偏差**：`new ID3v2PopmFrameData(false, null, 0)` 的空地址路径与文档描述不符（rating 非 null 时构造函数自动写入默认地址）
+
+### 解决方案
+**模式：生成前运行时探针锁定期望值**
+
+```
+流程：解析用例文档 → 提取全部断言点 → Node 探针直跑库源码逐条实测
+     → 实测值回填生成 prompt → 按实测值生成代码 → 编译验证
+```
+
+**适用条件**：库源码为纯 TS/ETS 且平台依赖可桩化（`@ohos.hilog` 可空桩、`@ohos.buffer`/`@ohos.fileio` 可替换）。mp3agic 类库（源码全 `.ts`、平台依赖仅日志/缓冲/文件 IO）完全满足。
+
+**Node 探针环境改造清单**（对库源码副本操作，约 30 分钟）：
+1. 桩模块：`@ohos.hilog`（空实现）、`@ohos.buffer`、`@ohos.fileio`。⚠️ fileio flag 语义映射：鸿蒙 `0o102` = O_RDWR|O_CREAT|O_TRUNC，且库传的是数字不是字符串
+2. import 路径补 `.ts` 扩展名（Node ESM 解析要求）：`perl -i -pe 's|from "(\./[A-Za-z0-9]+)"|from "./$1.ts"|g'`
+3. ArkTS 专有语法降级：`static const` → `static`
+4. 仅类型导入修正：接口文件改 `import type`，否则报 "does not provide an export named"
+5. ⚠️ 探针特有陷阱：Node class-fields 语义下子类字段声明会覆盖父类构造函数赋值（如 `private path: string` 声明清空 `super(path)` 的赋值），需在探针副本中注释掉该声明。该问题仅存在于探针环境，ArkTS 编译器不产生此语义，勿"修复"真实源码
+
+运行方式：Node 24+ `node --experimental-strip-types probe.mjs`，配合工程内真实样本夹具可覆盖从标签解析、字节序列化到 save 文件回读的全部断言路径。
+
+**补充（真机签名阻断的替代验证）**：真机要求签名 HAP，本机可能无目标包名的调试 Profile（CLI 无法代签）。此时探针可作为替代验证手段完成全部用例期望值的运行时验证（含异常类型/消息、字节布局、保存回读闭环），报告中如实标注"未真机执行 + 原因 + 替代验证手段"。
+
+### 结果
+mp3agic 案例中，8 处文档偏差、5 处库源码缺陷全部在写代码前发现，47/47 用例断言值与库实际行为吻合，编译后零运行时断言返工。成本约 30 分钟环境搭建 + 15 分钟探针编写，收益远超成本。**结论：文档预期值不可盲信，必须实测；实测与文档不符时以实测为准并在代码注释标注偏差。**

package/vendor/Archive/data/docs/experiences/arkts-xts-fixture-rawfile-testability-injection.md

@@ -0,0 +1,33 @@
+## XTS 测试夹具零依赖交付：rawfile 内置 + TestAbility 注入（替代 hdc file send 的首选方案）
+
+### 问题现象
+XTS 测试需要 MP3/ID3 样本文件等二进制夹具。传统方案依赖 `hdc file send` 手工推送文件到设备（需连接设备、逐个手工操作、CI 无法自动复跑）或外部网络下载（环境不可控、违反离线约束）。
+
+### 解决方案
+**夹具 rawfile 内置 + TestAbility 注入模式**（零网络、零手工设备操作）：
+
+1. 夹具文件放置 `entry/src/ohosTest/resources/rawfile/`（随 ohosTest HAP 自动打包，已验证 unzip HAP 可见 `resources/rawfile/`）
+2. 在 TestAbility.onCreate 中、`Hypium.hypiumTest` 调用之前，将 rawfile 夹具释放到应用沙箱目录：
+
+```typescript
+private prepareMp3Fixtures(): void {
+  const fixtureFiles: string[] = ['notags.mp3', 'v1andv24tags.mp3', /* ... */];
+  const filesDir: string = this.context.filesDir;
+  GlobalContext.getContext().setValue('path', filesDir);  // 若库通过 GlobalContext 读取工作目录（如 save() 依赖 'path' 键），必须在此设置
+  for (const name of fixtureFiles) {
+    const content: Uint8Array = this.context.resourceManager.getRawFileContentSync(name);
+    const file = fs.openSync(filesDir + '/' + name,
+        fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE | fs.OpenMode.TRUNC);
+    fs.writeSync(file.fd, content);
+    fs.closeSync(file);
+  }
+}
+```
+
+关键点：
+- `getRawFileContentSync` 一次性读入 rawfile 全部字节，配合 `fs.writeSync` 写入沙箱 `filesDir`（持久目录）
+- 若库通过 GlobalContext 读取工作目录（如 mp3agic 的 save() 依赖 `path` 键），必须在注入夹具前设置该键
+- 结构简单的样本（如极小 ID3 标签）可改用代码构造字节数组生成，完全不依赖资源文件；样本复杂/体积大时用 rawfile 内置
+
+### 结果
+mp3agic 47 个 XTS 用例的 MP3/ID3 样本全部随 HAP 打包注入，免设备手工操作、免外部脚本，CI 可直接复跑。**该模式为夹具交付首选方案；`hdc file send` 降为备选**（仅当夹具体积过大不适合随 HAP 打包时）。

package/vendor/Archive/data/docs/experiences/code-linter-chinese-comment-false-positive.md

@@ -0,0 +1,16 @@
+## Code Linter 对中文注释的误报模式与已知非阻断项
+
+### 问题现象
+
+Code Linter 的 `@security/no-commented-code` 规则会将含"代码样式"内容的中文注释（如 `setGenreDescription('Blues') 后 ...` 这类描述性注释）误判为注释掉的代码，产生 P2 级噪音告警。
+
+### 解决方案
+
+识别为误报，按 P2 噪音处理，不阻断流程。已知非阻断 Warning 清单：
+- `@security/no-commented-code`：中文注释误报（P2 噪音）
+- `@cross-device-app-dev/color-value`：十六进制颜色值写法
+- `file-naming-convention`（`@hw-stylistic/file-naming-convention`）：`001_` 序号前缀文件名与要求的大驼峰命名冲突，属工程既有约定
+
+### 结果
+
+以上 Warning 均不阻塞编译，按 P2 优化项按需处理即可，无需为消除告警改变代码结构或文件命名约定。真正需要修复的是 Error 级问题（0 Error 方可进入编译）。

package/vendor/Archive/data/docs/experiences/esobject-new-expression-variable-tracking.md

@@ -0,0 +1,33 @@
+# ESObject 声明 + 泛型构造的实例变量追踪语法级兜底
+
+### 问题现象
+
+ArkTS 测试代码常见写法：
+
+```ts
+let jList: ESObject = new JList<ESObject>();  // 声明类型是 ESObject，非类名
+jList.append(2);
+```
+
+基于 `checker.getTypeAtLocation` + `checker.typeToString` 的实例变量追踪依赖类型字符串包含导入类名，但"声明类型为 ESObject + 泛型构造"的组合无法命中（模块解析失败时更是全部失效），导致 `jList.append(2)` 这类"声明变量后调用实例方法"的匹配全部漏报。
+
+### 解决方案
+
+在 checker 类型推断之外增加**语法级兜底**：遍历 `VariableDeclaration` 时，若 initializer 是 `NewExpression`，直接取 callee 标识符映射到导入类名：
+
+```js
+if (node.initializer && ts.isNewExpression(node.initializer)) {
+  const callee = node.initializer.expression;
+  if (callee && ts.isIdentifier(callee) && importedSymbols.has(callee.text)) {
+    const displayName = importedSymbols.get(callee.text) || callee.text;
+    if (!varMap[node.name.text]) varMap[node.name.text] = [];
+    if (!varMap[node.name.text].includes(displayName)) varMap[node.name.text].push(displayName);
+  }
+}
+```
+
+`NewExpression` 的 `expression`（callee）与类型参数无关，因此天然覆盖泛型构造 `new JList<ESObject>()`，且在 checker 失效（模块解析失败）时依然工作。
+
+### 结果
+
+mp3agic 案例中 JList 等类的实例方法调用恢复匹配，覆盖率分析输出与人工 grep 盘点逐类一致。经验：基于 TS checker 的分析工具都应准备不依赖 checker 的语法级兜底路径，避免类型推断失效时静默丢失全部匹配。该修复已合入 `analyze-xts-coverage.cjs`（arkts-library-xts-coverage SKILL v1.1.0）。

package/vendor/Archive/data/docs/experiences/filesystem-case-sensitivity-module-resolution.md

@@ -0,0 +1,31 @@
+# 大小写不敏感文件系统导致模块解析静默失败
+
+### 问题现象
+
+在 macOS/Windows（大小写不敏感文件系统）上运行基于 TypeScript Compiler API 的分析工具时出现静默失真：
+
+1. 库入口候选路径写死为 `library/Index.ets`（大写 I），而库实际文件是小写 `index.ets`
+2. `fs.existsSync('library/Index.ets')` 在大小写不敏感文件系统上返回 `true`，函数返回**错误大小写**的路径
+3. 但内容缓存（`fileContents`）的键来自 `fs.readdirSync` 的**真实小写**路径
+4. 虚拟路径 `.../library/Index.ts` 在缓存中查不到 → `resolveModuleNames` 模块解析失败 → `checker` 类型推断全面失效 → 实例变量追踪返回空 → 所有"声明变量后调用实例方法"的匹配全部丢失
+
+**最危险之处**：脚本不报错、不降级，静默输出严重偏低的覆盖率（mp3agic 案例漏报约 84 个接口）。该问题在 Linux（大小写敏感）CI 上不复现——`existsSync` 返回 false 走深度搜索分支，路径行为不同，属于典型的"本机能跑、CI 表现不同"类缺陷。
+
+**典型特征信号**：类级覆盖率表中仅静态/工具类有覆盖、所有实例方法类为 0。
+
+### 解决方案
+
+路径匹配做大小写归一，两选一：
+
+```js
+// 方案 A（防御式）：精确查找失败后，构建小写键映射表二次查找
+const lowerMap = new Map(Object.keys(fileContents).map(k => [k.toLowerCase(), k]));
+const v = toPosix(candidate.replace(/\.ets$/, '.ts')).toLowerCase();
+if (lowerMap.has(v)) resolvedPath = lowerMap.get(v);
+```
+
+方案 B（根治）：入口文件定位函数返回前，用 `fs.readdirSync` 的真实文件名做大小写归一，保证虚拟路径键与缓存键严格一致。
+
+### 结果
+
+mp3agic 案例应用方案 A 后，`@ohos/mp3agic` 模块解析恢复，类型推断生效，实例方法类（EncodedText、ID3v22/23/24Tag 等）覆盖率从 0 恢复正常。大小写归一补丁对大小写敏感平台（Linux）无副作用，可直接合入。该修复已合入 `analyze-xts-coverage.cjs`（arkts-library-xts-coverage SKILL v1.1.0）。

package/vendor/Archive/data/docs/experiences/gitcode-clone-redirect-warning-normal.md

@@ -0,0 +1,13 @@
+## GitCode 仓库 git clone 输出重定向警告属正常行为，不代表克隆失败
+
+### 问题现象
+
+执行 `git clone https://gitcode.com/CPF-ApplicationTPC/mp3agic` 时输出"警告：重定向到 .../mp3agic.git/"，容易被误判为克隆失败，进而触发不必要的降级重试（如去掉 `--depth=1` 重新完整克隆）。
+
+### 解决方案
+
+该重定向警告是 GitCode 平台的正常行为（GitCode 会自动将无 `.git` 后缀的仓库地址重定向到带 `.git` 后缀的地址），不代表克隆失败。判断克隆是否成功应以命令退出码和目标目录实际内容为准，而非 stderr 警告文本。
+
+### 结果
+
+克隆实际成功、源码完整。只要 `git clone` 退出码为 0 且目标目录含仓库内容（`.git` 目录、`oh-package.json5` 等），即视为克隆成功，不应因重定向警告触发降级重试，避免浪费时间的无意义完整克隆。

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

@@ -0,0 +1,77 @@
+# 鸿蒙自动化测试框架关系与文档搜索经验
+
+## 一、arkXtest 框架命名混淆
+
+### 问题现象
+编写鸿蒙测试文档时，容易将 arkXtest 当作独立框架来描述，误以为存在独立的 arkXtest 包或 API，导致文档中框架名称使用混乱。
+
+### 解决方案
+明确 arkXtest 是框架统称而非独立框架。arkXtest = JsUnit + UITest + PerfTest 三者的统称，不存在独立的 arkXtest 包或 API。文档中需区分"统称"与"具体框架"。
+
+### 结果
+文档中正确区分框架统称与具体框架，消除 arkXtest 与 JsUnit/UITest 的命名混淆。
+
+---
+
+## 二、JsUnit 与 UITest 关系误判
+
+### 问题现象
+不清楚 JsUnit 与 UITest 之间的关系，容易将两者描述为平级框架，误导读者理解测试代码结构。
+
+### 解决方案
+理解两者的上下层依赖关系：UITest 脚本必须基于 JsUnit 的 describe/it 定义，在 it 回调中调用 UITest 接口。所有 UITest 测试用例本质上也是 JsUnit 测试用例。文档中使用"底座+上层"模式描述 JsUnit 与 UITest 的关系。
+
+### 结果
+文档准确表达 JsUnit（底座）与 UITest（上层）的依赖关系，避免平级错觉。
+
+---
+
+## 三、Hypium(Python) 与 arkXtest 关系不清
+
+### 问题现象
+不清楚 Hypium(Python) 与 arkXtest 体系的关系，难以判断 CI/CD 场景下应选用的测试框架。
+
+### 解决方案
+理解两者的完全独立性：Hypium(Python) 运行在 PC 端，通过 hdc 连接设备，不依赖设备端的 JsUnit/UITest 框架。与 arkXtest（设备端框架）完全独立。CI/CD 场景下 Hypium 更适合流水线集成。
+
+### 结果
+能根据场景正确选择测试框架：设备端测试用 arkXtest 体系（JsUnit/UITest），流水线集成用 Hypium(Python)。
+
+---
+
+## 四、API 版本标注遗漏
+
+### 问题现象
+标注 UITest API 版本时只标注了一套版本号，导致读者不清楚功能的实际可用范围。
+
+### 解决方案
+同时标注两套版本体系：OS API 版本（如 API 8/9/18/20/22）和 @ohos/hypium 包版本（如 1.0.1/1.0.25）。示例：Mock 能力从 @ohos/hypium 1.0.1 开始支持，运行在 API 8+ 设备上。两者缺一不可。
+
+### 结果
+版本信息完整，读者可准确判断功能的设备兼容性和包依赖。
+
+---
+
+## 五、devecocli docs search 中文关键词搜索失败
+
+### 问题现象
+使用纯中文关键词搜索 devecocli docs 时返回 SEARCH_FAILED。例如搜索"JsUnit 单元测试"失败。
+
+### 解决方案
+改用中英文混合关键词或更通用的关键词。例如搜索"arkXtest 测试框架"和"UiTest UI测试"均成功。
+
+### 结果
+搜索成功，获取到所需的鸿蒙测试框架文档。
+
+---
+
+## 六、devecocli docs search 结果只有摘要
+
+### 问题现象
+devecocli docs search 返回的结果只包含摘要，无法获取完整文档内容。
+
+### 解决方案
+搜索结果中提取文档 ID，再执行 `devecocli docs read <documentId>` 获取完整文档内容。
+
+### 结果
+成功获取完整的文档内容用于分析。

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

@@ -0,0 +1,98 @@
+# DevEco MCP 构建签名 HAP — 签名配置位置与构建监控经验
+
+> 来源知识条目: kn_msovnm6rd46de72c
+> 适用场景: 使用 DevEco MCP 工具（project_sync / build_project）对 HarmonyOS 工程执行同步、构建并生成签名 HAP
+
+---
+
+## 一、签名配置必须添加到工作区根目录的 build-profile.json5
+
+### 问题现象
+在 HarmonyOS 工程的子目录 `build-profile.json5`（如 `rntpc_react-native-pager-view/example/harmony/build-profile.json5`）中添加了 `signingConfigs` 配置后，执行 `deveco-mcp_build_project` 构建时，构建日志仍显示签名被跳过：
+
+```
+> hvigor WARN: Will skip sign 'hos_hap'. No signingConfigs profile is configured in current project.
+             If needed, configure the signingConfigs in /Users/lalhan/Desktop/3rdLibraryLoop/build-profile.json5.
+```
+
+导致产物只有 `entry-default-unsigned.hap`，没有签名 HAP。
+
+### 解决方案
+将 `signingConfigs` 配置添加到**工作区根目录**的 `build-profile.json5`（即 DevEco Studio 打开的项目根目录下的文件），而非嵌套子项目中的同名文件。
+
+DevEco MCP 的 `build_project` 和 `project_sync` 工具以工作区根目录为项目根，读取的是根级 `build-profile.json5`。
+
+根级 `build-profile.json5` 通常包含以下关键字段：
+- `app.products[].signingConfig` — 引用签名配置名
+- `app.signingConfigs[]` — 签名配置数组（需在此处添加签名配置）
+- `modules[].srcPath` — 指向实际 entry 模块路径
+
+### 结果
+签名配置被正确读取，构建任务执行 `SignHap`，产物目录下生成 `entry-default-signed.hap`（签名 HAP）。
+
+> ⚠️ 注意：根级 `build-profile.json5` 可能使用带引号 key 的标准 JSON 格式，而项目级可能使用 JSON5 无引号 key 格式。两种格式均有效，添加配置时需按各自风格书写。
+
+---
+
+## 二、利用构建日志 WARN 消息定位签名配置文件
+
+### 问题现象
+不确定应该修改哪个 `build-profile.json5` 来添加签名配置时，容易修改错误的文件（子项目级而非根级），导致签名仍然被跳过。
+
+### 解决方案
+构建日志中的 WARN 消息会直接给出需要修改的文件路径：
+
+```
+If needed, configure the signingConfigs in /Users/lalhan/Desktop/3rdLibraryLoop/build-profile.json5.
+```
+
+遇到签名跳过问题时，首先检查构建日志中此 WARN 消息指向的 `build-profile.json5` 路径，在该文件中添加 `signingConfigs`。
+
+### 结果
+通过 WARN 消息可直接定位到正确的配置文件路径，避免修改错误文件，快速解决签名跳过问题。
+
+---
+
+## 三、MCP build_project clean=true 构建超时的监控策略
+
+### 问题现象
+调用 `deveco-mcp_build_project` 并设置 `clean=true`（全量清理重建）时，MCP 请求超时：
+
+```
+MCP error -32001: Request timed out
+```
+
+实际构建在后台继续运行，约 3.5 分钟后完成，但无法直接从 MCP 响应获取构建结果。
+
+### 解决方案
+MCP 超时后，通过以下策略监控构建进度并确认结果：
+
+1. **监控产物目录**：用 `ls -la` 或 glob 工具检查 `entry/build/default/outputs/default/` 目录，等待 `entry-default-signed.hap` 文件出现。
+2. **检查构建日志**：读取构建日志文件，确认出现 `BUILD SUCCESSFUL` 标记和 `SignHap` 任务完成。
+3. **增量构建策略**：增量构建（不设置 clean）可在 MCP 超时内完成（约 2 秒），但**注意：增量构建无法触发重新签名**，如需重新签名必须 clean 构建。
+
+### 结果
+即使 MCP 请求超时，仍可通过监控产物目录和构建日志确认构建成功完成。
+
+> ⚠️ 建议：如果修改了签名配置后需要验证签名生效，必须使用 clean=true 进行全量构建，并用监控策略等待完成。
+
+---
+
+## 四、验证签名成功的快速方法
+
+### 问题现象
+构建完成后，如何快速判断签名是否成功应用到 HAP 产物。
+
+### 解决方案
+通过以下两种方式快速验证：
+
+1. **检查产物文件存在性**：检查 `entry/build/default/outputs/default/` 目录下是否同时存在 `entry-default-signed.hap` 和 `entry-default-unsigned.hap`。如果仅有 unsigned 版本，说明签名被跳过。
+2. **比较文件大小**：签名 HAP 比未签名 HAP 大约 672KB（签名数据）：
+
+| 文件 | 典型大小 | 差异 |
+|------|----------|------|
+| entry-default-unsigned.hap | ~72,585,629 bytes | 基准 |
+| entry-default-signed.hap | ~73,257,238 bytes | +671,609 bytes（约 672KB 签名数据） |
+
+### 结果
+通过文件存在性和大小差异可快速判断签名是否成功应用，无需深入解析 HAP 内部结构。

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

@@ -0,0 +1,87 @@
+## RN鸿蒙三方库渐进式编译验证经验（netinfo 0.82→0.84）
+
+### 问题现象1：codegen脚本添加 --generate-type all 导致编译失败
+
+运行 `npm run codegen` 报错 `error: unknown option '--generate-type'`。
+
+### 解决方案
+
+RNOH 提供两个不同的 codegen 命令，参数支持不同：
+
+| 命令 | 用途 | 支持 --generate-type | 使用位置 |
+|------|------|---------------------|---------|
+| `react-native codegen-harmony` | 应用构建阶段 codegen | 不支持 | example/package.json 的 codegen 脚本 |
+| `react-native codegen-lib-harmony` | 库开发阶段 codegen | 支持 | 库根 package.json 的 codegen-lib 脚本 |
+
+从 example 的 codegen 脚本中移除 `--generate-type all` 参数。如需使用该参数，应在库根 package.json 中添加 `codegen-lib` 脚本并使用 `react-native codegen-lib-harmony`。
+
+### 结果
+
+移除参数后 `npm run codegen` 成功生成 5 个文件，`npm run dev` 成功构建 JS bundle，hvigor 构建成功。SKILL 中 0.82→0.84 不兼容变更表标注的"新增 --generate-type all（必选）"影响文件为库根 package.json 的 codegen-lib 脚本，不是 example 工程的 codegen 脚本。
+
+---
+
+### 问题现象2：npm pack 超时（>120s）
+
+rnoh-build-har 执行后在 harmony/ 下产生临时工程文件（oh_modules 913MB、AppScope、build-profile.json5 等）。即使 .npmignore 已排除 harmony/oh_modules，npm pack 仍需遍历整个目录树导致超时。
+
+### 解决方案
+
+在 npm pack 前清理 rnoh-build-har 产生的临时文件：
+
+```bash
+rm -rf harmony/oh_modules harmony/<module>/build harmony/AppScope harmony/build-profile.json5 harmony/hvigor harmony/oh-package.json5
+```
+
+### 结果
+
+清理后 npm pack 在数秒内完成。建议在 HAR 构建成功并拷贝到 harmony/<module>.har 后、npm pack 之前执行清理。
+
+---
+
+### 问题现象3：多任务并行时构建日志来源无法确认
+
+多任务并行时，构建日志可能来自不同仓库。需验证日志路径来自当前任务仓库。
+
+### 解决方案
+
+```bash
+# 确认当前任务路径在日志中出现（应为大量匹配）
+grep -c "当前任务路径" <log_file>
+# 确认其他任务路径不在日志中（应为 0 匹配）
+grep -c "其他任务路径" <log_file>
+```
+
+### 结果
+
+本次验证结果：当前任务路径 183 次匹配，其他任务路径 0 次匹配，确认日志来源正确。构建日志应保存到任务仓库目录内，便于验证来源。
+
+---
+
+### 问题现象4：CMake 编译中断 vs 完整完成无法区分
+
+构建日志显示 CMake 在 CMakeTestCCompiler.cmake 阶段报错 ld.lld: error: unknown argument '-search_paths_first'，构建在 BuildNativeWithCmake 步骤中断。需判断 CMake 是否完整完成。
+
+### 解决方案
+
+检查构建日志中以下两个关键步骤是否都存在且无 ERROR：
+- `Finished :entry:default@BuildNativeWithCmake...` — CMake 配置阶段
+- `Finished :entry:default@BuildNativeWithNinja...` — C++ 编译阶段
+
+### 结果
+
+单一步骤完成不代表 CMake 完整完成，必须同时验证两个步骤。本次 netinfo 构建：CMake 11s 493ms + Ninja 4min 42s 464ms，两者均完整完成。
+
+---
+
+### 问题现象5：MCP check_ets_files 不支持 .ts 文件
+
+MCP 工具 check_ets_files 仅支持 .ets 扩展名，无法对 .ts 文件进行语法检查。
+
+### 解决方案
+
+.ts 文件需通过实际编译验证语法正确性，无法使用 MCP check_ets_files 工具检查。
+
+### 结果
+
+对 .ts 文件跳过 MCP 语法检查，直接通过 npm run codegen 和 hvigor 构建验证。

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 库的所有维度。