@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-code-check/references/CHECKLIST.md

@@ -0,0 +1,189 @@
+# React Native 代码检视清单
+
+本文档包含详细的检视检查项，用于 Phase 3 的深度检视阶段。
+
+---
+
+## 一、非兼容变更检查
+
+- [ ] 是否删除或重命名了公开 TurboModule 方法
+- [ ] 是否修改了 NAPI 接口函数名称或参数结构（影响 JS 侧调用）
+- [ ] 是否修改了 JS/TS 声明文件中的方法签名或返回类型
+- [ ] 是否修改了 `package.json` 中影响依赖解析的字段
+
+---
+
+## 二、C++ CAPI 实现检视（harmony/src/main/cpp/）
+
+### 2.1 TurboModule 实现
+
+- [ ] TurboModule 是否正确实现了 `getTurboModule()` 工厂函数
+- [ ] NAPI 接口函数签名与 JS 侧声明一致（方法名、参数类型、返回值类型）
+
+### 2.2 内存管理
+
+- [ ] `napi_create_*` 创建的对象在不需要时正确释放
+- [ ] `napi_ref` 在不需要时调用 `napi_delete_reference`
+- [ ] C++ 对象生命周期正确管理（无悬挂指针）
+- [ ] `malloc`/`new` 有对应 `free`/`delete`，无内存泄漏
+- [ ] TurboModule 实例销毁时释放所有持有的 C++ 资源
+- [ ] `napi_env` 生命周期内创建的对象不在 env 销毁后访问
+- [ ] `ArrayBuffer` 大数据用完后无强引用持有
+
+### 2.3 线程安全（重点）
+
+> ⚠️ **线程安全问题是 RN Native 模块最常见的严重问题，必须重点检查**
+
+- [ ] 子线程中不直接调用 NAPI 函数（必须通过 `napi_threadsafe_function`）
+- [ ] 主 JS 线程与 C++ 线程间共享的数据有锁保护（`std::mutex`）
+- [ ] `napi_threadsafe_function` 创建后在不再使用时调用 `napi_release_threadsafe_function`
+- [ ] 多线程场景中无竞态条件（Race Condition）
+
+### 2.4 错误处理
+
+- [ ] C++ 异常捕获并转为 NAPI 错误抛出
+- [ ] 每个返回分支均有明确的返回值赋值（无未初始化返回）
+- [ ] 所有 NAPI API 返回值检查（`napi_status` 不为 `napi_ok` 时有处理）
+- [ ] `OH_*` C API 的返回值是否有检查
+
+---
+
+## 三、ArkTS 胶水层检视（harmony/src/main/ets/）
+
+### 3.1 TurboModule 注册
+
+- [ ] TurboModule 正确注册（`createTurboModuleManager` 或 `TurboModuleRegistry.get`）
+- [ ] ArkUI Fabric 组件（如有）正确实现了 `RNComponentContext`
+
+### 3.2 代码规范
+
+- [ ] 日志调用使用 `RNLog` 而非原生 `console.log`
+- [ ] 无 `any` 类型使用（ArkTS 禁止 `as any`、隐式 any）
+- [ ] 无 `prototype` 动态修改
+- [ ] 泛型类型参数明确，避免推导歧义
+
+### 3.3 API 兼容性
+
+- [ ] 新增 API 使用是否超出 `minAPIVersion`
+- [ ] 是否使用已废弃的 OHOS API（`@deprecated` 标注的接口）
+- [ ] 权限申请是否正确（`requestPermissionsFromUser`）
+
+---
+
+## 四、异步处理
+
+- [ ] 所有异步 OHOS API 调用均有 `await` 或 `.then()` 处理
+- [ ] `try/catch` 覆盖所有 `await` 调用，catch 块有实质性错误处理（非空 catch）
+- [ ] 未处理的 Promise rejection（`.catch()` 或 `try/catch` 必须存在）
+- [ ] 并行异步操作使用 `Promise.all`，避免不必要的顺序 await
+
+---
+
+## 五、事件监听器管理
+
+- [ ] JS 侧注册的事件监听器在模块销毁时取消注册
+- [ ] C++ 层的回调函数在对象销毁时被正确移除
+- [ ] 重复注册同一事件不会造成监听器堆积
+
+---
+
+## 六、错误处理
+
+- [ ] 错误信息包含错误码和错误描述
+- [ ] `reject()` / `napi_reject_deferred` 调用后函数立即返回
+- [ ] switch-case 中每个 case 末尾有 `break`（避免 fall-through）
+
+---
+
+## 七、JS/TS 接口层（src/ 目录）
+
+- [ ] Native Module 方法类型声明完整（返回 `Promise<T>` 或同步类型明确）
+- [ ] 是否包含鸿蒙平台条件判断 `Platform.OS === 'harmony'`
+- [ ] 公共 API 有完整的 JSDoc 注释
+- [ ] 参数有基本校验（null check、类型检查）
+
+---
+
+## 八、跨平台一致性对比（harmony ↔ Android/iOS）
+
+> ⚠️ **这是 RN 三方库 PR 检视最关键的质量维度之一**。harmony 实现必须与 Android/iOS 原生模块在方法路由、参数类型、返回值格式上保持一致，否则 JS 侧调用同一 Native Module 时在鸿蒙平台上行为异常。
+
+### 8.1 TurboModule 方法路由一致性
+
+- [ ] harmony 的 TurboModule 方法列表是否与 Android NativeModule 完全对应
+- [ ] 缺失方法（Android 有但 harmony 无）是否标记为功能缺失
+- [ ] 多余方法（harmony 有但 Android 无）是否有合理说明
+
+### 8.2 TurboModule 名称一致性
+
+- [ ] harmony 注册的 TurboModule 名是否与 Android 注册名一致（JS 侧共用同一模块名）
+- [ ] NativeModule 名是否与 JS 侧 `NativeModules.XxxModule` 引用一致
+
+### 8.3 参数类型映射一致性
+
+- [ ] 同一 TurboModule 方法，harmony 解析的参数类型是否与 Android 一致（如 `bool` vs `string`）
+- [ ] 复杂对象参数的属性结构是否一致
+- [ ] 可选参数的处理方式是否一致（默认值 vs undefined）
+
+### 8.4 返回值格式一致性
+
+- [ ] `resolve()` 返回的数据结构是否与 Android `success()` 对齐
+- [ ] 返回值嵌套层级和字段名是否一致
+- [ ] 空值/空数组的返回格式是否一致
+
+### 8.5 错误码/错误消息一致性
+
+- [ ] `reject()` 的 error code 是否与 Android `error()` 对齐
+- [ ] 错误消息的格式和内容是否一致
+- [ ] 同一错误场景在不同平台的错误码是否相同
+
+### 8.6 功能实现完整性
+
+- [ ] Android 有实现但 harmony 为 Stub（返回固定值无实际操作）的标记为功能缺失
+- [ ] Android 有实现但 harmony 完全缺失的标记为方法缺失
+- [ ] 已知平台差异（如权限模型不同）是否有注释说明
+
+### 8.7 EventEmitter 事件名一致性
+
+- [ ] harmony 发送的事件名是否与 Android 发送的事件名一致
+- [ ] 事件数据格式（字段名、类型）是否一致
+- [ ] 事件监听器的注册/移除接口是否一致
+
+---
+
+## 九、安全性
+
+- [ ] 无硬编码的 API Key / Token / URL 等敏感信息
+- [ ] 网络请求校验 HTTPS 证书（禁止忽略证书错误）
+- [ ] 用户输入有校验和过滤（防注入）
+- [ ] 文件路径有安全校验（防路径穿越）
+- [ ] 敏感数据不在日志中输出
+
+---
+
+## 十、构建配置
+
+- [ ] `CMakeLists.txt` 链接的系统库均为必要依赖
+- [ ] `oh-package.json5` 新增依赖合理，无 `*` 通配版本
+- [ ] 编译选项无安全风险（如 `-fno-stack-protector` 等）
+
+---
+
+## 十一、代码规范
+
+- [ ] C++ 代码遵循现代 C++ 规范（优先使用 RAII、智能指针）
+- [ ] ArkTS 命名遵循驼峰规则（变量/方法小驼峰，类/接口大驼峰）
+- [ ] 无冗余的 `RNLog`/`console.log` 调试代码遗留
+- [ ] 公共 API 有完整注释
+- [ ] 文件头版权声明完整
+
+---
+
+## 十二、资源管理
+
+- [ ] 定时器有对应清理
+- [ ] `napi_env` 生命周期内创建的对象不在 env 销毁后访问
+
+---
+
+**使用说明**：在检视阶段按章节逐项检查，对发现的问题在报告中标注等级（CRITICAL/MAJOR/MINOR/SUGGEST）。

package/vendor/Server/Skills/rn-code-check/references/REPORT-TEMPLATE.md

@@ -0,0 +1,247 @@
+# React Native 代码检视报告模板
+
+本文档提供标准化的检视报告格式模板。
+
+---
+
+## 一、基本信息
+
+| 字段 | 内容 |
+|------|------|
+| **PR 地址** | {prUrl} |
+| **代码仓库** | {owner}/{repo} |
+| **目标分支** | {targetBranch} |
+| **PR 标题** | {prTitle（commit Subject）} |
+| **提交作者** | {author} <{email}> |
+| **提交时间** | {date} |
+| **Commit Hash** | {commitHash} |
+| **库类型** | React Native |
+| **报告生成时间** | {YYYY-MM-DD HH:mm} |
+
+---
+
+## 二、改动概述
+
+### 2.1 改动规模
+
+| 指标 | 数值 |
+|------|------|
+| 涉及文件数 | N 个 |
+| 新增行数 | +X 行 |
+| 删除行数 | -Y 行 |
+| 净变更 | +Z 行 |
+
+### 2.2 改动文件清单
+
+| 文件路径 | 类型 | 改动性质 | 改动摘要 |
+|----------|------|----------|----------|
+| `harmony/src/main/cpp/...` | C++ CAPI | 功能修复 | 修复跨线程回调未使用 napi_threadsafe_function |
+| `src/...` | JS/TS | 接口更新 | 新增平台判断逻辑 |
+
+### 2.3 整体改动意图
+
+{根据 commit message 和 diff 内容描述改动意图}
+
+---
+
+## 三、检视结果汇总
+
+| 等级 | 问题数 |
+|------|--------|
+| 🔴 严重 (CRITICAL) | N |
+| 🟠 主要 (MAJOR)    | N |
+| 🟡 次要 (MINOR)    | N |
+| 🔵 建议 (SUGGEST)  | N |
+
+---
+
+## 四、详细检视意见
+
+### [文件路径]
+
+#### 🔴 严重问题
+
+**[问题标题]**
+- **位置**：第 X 行
+- **描述**：...
+- **建议**：...
+
+```diff
+- 问题代码
++ 建议改法
+```
+
+---
+
+## 五、影响分析
+
+- **功能影响**：本次改动是否引入新功能或修改现有行为
+- **兼容性影响**：对外暴露的 TurboModule API 是否向后兼容
+- **性能影响**：是否优化了跨线程调用性能或内存占用
+- **安全影响**：是否修复或引入了内存安全或线程安全问题
+
+---
+
+## 六、跨平台一致性对比
+
+> 对比 PR diff 涉及的 harmony 实现与 Android/iOS 原生模块的方法路由、参数类型、返回值格式一致性。
+
+| 对比维度 | harmony 实现 | Android 实现 | 一致性 | 问题等级 |
+|----------|-------------|-------------|--------|----------|
+| TurboModule 方法路由 | `methodName1`, `methodName2`, ... | `methodName1`, `methodName2`, ... | ✅一致 / ❌缺失X个方法 | 🔴/🟠/✅ |
+| TurboModule 名称 | `XxxModule` | `XxxModule` | ✅一致 / ❌不一致 | 🔴/✅ |
+| 参数类型映射 | `call.argument('key')` 类型 | `call.argument('key')` 类型 | ✅一致 / ❌类型不匹配 | 🔴/✅ |
+| 返回值格式 | `{code: 0, data: [...]}` | `{code: 0, data: [...]}` | ✅一致 / ❌格式不同 | 🟠/✅ |
+| 错误码/消息 | code: `"E_XXX"` | code: `"E_XXX"` | ✅一致 / ❌不匹配 | 🟠/✅ |
+| 功能完整性 | 全部实现 / Stub: X个 | 全部实现 | ✅完整 / ❌缺失X个方法 | 🔴/✅ |
+| EventEmitter 事件名 | `eventName1`, `eventName2` | `eventName1`, `eventName2` | ✅一致 / ❌不一致 | 🟠/✅ |
+
+### 不一致详情
+
+#### [方法名]
+- **Android 实现**：{描述 Android 的方法签名、参数类型、返回值、错误处理}
+- **harmony 实现**：{描述 harmony 的对应实现}
+- **差异**：{具体差异说明}
+- **风险**：{JS 侧调用时可能的行为差异}
+- **建议**：{修复建议}
+
+---
+
+## 七、总体评估
+
+**结论**：[APPROVED / NEEDS_REVISION / REJECTED]
+
+**说明**：...
+
+---
+
+## 八、合入建议分级
+
+> 根据问题严重程度统计，按照分级标准判定合入建议等级。
+
+### 8.1 问题统计
+
+| 等级 | 数量 | 说明 |
+|------|------|------|
+| 🔴 **Critical** | N 个 | 必须修复，会导致崩溃、数据损坏、安全漏洞 |
+| 🟠 **Major** | N 个 | 强烈建议修复，影响功能正确性/性能/兼容性 |
+| 🟡 **Minor** | N 个 | 建议修复，代码质量/规范/可读性问题 |
+| 🔵 **Suggest** | N 个 | 可选改进，不强制要求修复 |
+
+### 8.2 合入建议
+
+**等级标识**：✅ PASS / ⚠️ CONDITIONAL / 🔧 NEED_FIX / ❌ REJECT
+
+**判定结果**：{等级标识}
+
+**分级理由**：
+- {根据分级标准说明判定理由}
+- {例如：存在 1 个 Critical 级别问题（子线程直接调用 NAPI），判定为 NEED_FIX，需修复后合入}
+- {线程安全问题示例：回调函数在子线程执行但未使用 napi_threadsafe_function，会导致 JS 崩溃}
+
+**合入条件**（仅 CONDITIONAL/NEED_FIX 时填写）：
+- {列出必须满足的条件，如：修复线程安全问题、使用 napi_threadsafe_function、补充测试用例等}
+
+---
+
+## 九、修改点详细分级清单
+
+> 每个修改点的具体分析，明确标注所属的合入建议级别。
+
+### 9.1 建议合入级修改点 ✅
+
+> 无风险或低风险修改，可直接合入。
+
+| # | 文件 | 修改内容 | 风险评估 | 说明 |
+|---|------|----------|----------|------|
+| 1 | `src/...` | 删除无用导入 | 低风险 | 代码清理，不影响功能 |
+
+### 9.2 条件合入级修改点 ⚠️
+
+> 需满足特定条件后方可合入。
+
+| # | 文件 | 修改内容 | 潜在风险 | 合入条件 |
+|---|------|----------|----------|----------|
+| 1 | `harmony/src/main/ets/...` | 新增 TurboModule 方法 | 需验证跨平台一致性 | 补充 JS 端测试用例 |
+
+### 9.3 修改后合入级修改点 🔧
+
+> 存在明确问题，需修复后方可合入。
+
+| # | 文件 | 位置 | 问题描述 | 修复建议 | 严重级别 |
+|---|------|------|----------|----------|----------|
+| 1 | `harmony/src/main/cpp/...` | `callback()` | 子线程直接调用 NAPI 函数 | 使用 napi_threadsafe_function | 🔴 Critical |
+
+### 9.4 不允许合入级修改点 ❌
+
+> 严重问题，不建议合入。
+
+| # | 文件 | 位置 | 问题描述 | 影响 | 严重级别 |
+|---|------|------|----------|------|----------|
+| 1 | `harmony/src/main/cpp/...` | NAPI 模块 | napi_ref 未正确释放导致内存泄漏 | 长期运行内存增长 | 🔴 Critical |
+
+---
+
+## 十、result.txt 文件生成规范
+
+> 检视完成后，生成 `result.txt` 文件供前端展示和数据库存储。
+
+```txt
+=== 合入建议分级报告 ===
+PR 地址：{prUrl}
+仓库：{owner}/{repo}
+PR 编号：#{prNumber}
+生成时间：{YYYY-MM-DD HH:mm:ss}
+
+【合入建议】：{等级标识}
+
+【问题统计】
+- Critical 级别：{criticalCount} 个
+- Major 级别：{majorCount} 个  
+- Minor 级别：{minorCount} 个
+- Suggest 级别：{suggestCount} 个
+
+【分级理由】
+{分级理由详细说明}
+
+【详细分析】
+━━━ Critical 级别问题 ━━━
+{列出所有 Critical 问题，每个占一行，重点关注线程安全/内存问题}
+
+━━━ Major 级别问题 ━━━
+{列出所有 Major 问题，每个占一行}
+
+━━━ Minor 级别问题 ━━━
+{列出所有 Minor 问题，每个占一行}
+
+━━━ Suggest 级别问题 ━━━
+{列出所有 Suggest 问题，每个占一行}
+
+━━━ 合入建议 ━━━
+{最终合入建议和条件说明}
+
+=== 分级结束 ===
+```
+
+---
+
+*本报告由 RNCodeCheck 自动生成，仅供参考，最终合入决策由人工评审确认。*
+
+---
+
+## 报告生成说明
+
+1. **文件命名**：必须为 `check-report.md`
+2. **保存路径**：必须在 `{outputDir}` 下
+3. **文件列表**：同时生成 `changed-files.txt`（每行一个文件路径）
+4. **无鸿蒙变更**：若 PR 只修改 `android/` 或 `ios/`，在报告中注明"本次 PR 无鸿蒙平台代码变更"并给出 APPROVED
+5. **线程安全优先**：对 C++ CAPI 的内存安全和线程安全问题给予最高优先级标记为 CRITICAL
+
+---
+
+**问题等级定义**：
+
+- 🔴 **CRITICAL（严重）**：会导致崩溃、数据损坏、安全漏洞的严重问题，必须修复
+- 🟠 **MAJOR（主要）**：影响功能正确性、性能、兼容性的重要问题，强烈建议修复
+- 🟡 **MINOR（次要）**：代码质量问题、规范问题、可读性问题，建议修复
+- 🔵 **SUGGEST（建议）**：可选的改进建议，不强制要求修复

package/vendor/Server/Skills/rn-lib-add-example/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: rn-lib-add-example
+description: 为 RN 鸿蒙三方库创建 example 示例工程：从 RN3rdTemplate 模板仓库（gitcode.com/lalhanOrz/RN3rdTemplate）浅拷贝对应 RNOH 框架版本（0.77/0.82/0.84）的模板到库根 example/，自动修改 app 名称与 bundleName 等工程标识，清理 .npmrc 凭据与模板残留，以 npm pack tgz 方式接入本地库依赖并适配鸿蒙壳层，预置 RNTesterList 注册入口，最终按渐进式验证链（npm install → npm run dev → ohpm install → hvigorw assembleHap）确认工程可构建。当三方库仓库缺失 example/ 目录、或需要基于标准模板重建结构完整的 example 壳层工程（含 package.json、入口 index、RNTesterList 页面注册、harmony 构建配置）时使用。
+license: Apache-2.0
+compatibility: 需要 Node.js ≥ 16 与 git（可访问 gitcode.com），库依赖接入需 npm；鸿蒙侧编译验证需 DevEco Studio（ohpm/hvigorw）；需目标库根目录写权限
+metadata:
+  author: LoopEngine
+  version: "1.0.0"
+  category: rn-engineering
+  invoked-by: 三方库 example 工程准备流程
+  consumed-by: rnoh-lib-demo-create、rnoh-cptf-api-test
+---
+
+# RN 三方库添加 Example 工程
+
+从 RN3rdTemplate 模板仓库浅拷贝对应 RNOH 框架版本的模板工程，修改 app 名称后接入目标库依赖，产出结构完整、可构建、可注册 Demo 的 example 壳层工程。
+
+> ⚠️ **核心原则**：
+> 1. 库依赖一律 `npm pack` + `file:../xxx.tgz`，**禁止 `file:../目录`**（npm 会以 symlink 安装，Metro 无法解析）
+> 2. 拷贝模板后第一件事：**删除 `.npmrc`**（模板可能内嵌私有 registry 明文 token，含凭据文件严禁带入交付物）
+> 3. 必须**预置 `src/RNTesterList.ts`（模式 A）注册入口**，与下游 Demo 生成/测试技能（rnoh-lib-demo-create、rnoh-cptf-api-test）的探查逻辑无缝衔接
+> 4. 壳层适配的类名/路径/链接目标全部由库 `package.json` 的 harmony 元数据派生，禁止手抄猜测
+> 5. 验证遵循渐进式链：`npm run dev` 成本最低、最先执行，不要跳过直接做鸿蒙编译
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libRoot` | string | ✅ | 目标库根目录（含 package.json） |
+| `version` | string | ❌ | RNOH 框架版本（0.77/0.82/0.84），缺省从库 package.json 自动推断 |
+| `appName` | string | ❌ | 应用显示名，缺省从库名派生（如 `SqliteStorageExample`） |
+| `bundleName` | string | ❌ | 鸿蒙包名，缺省派生为 `com.rnoh.{lib_name}` |
+| `templateUrl` | string | ❌ | 模板仓库地址，默认 https://gitcode.com/lalhanOrz/RN3rdTemplate.git |
+| `force` | boolean | ❌ | example/ 已存在时是否删除重建（默认询问用户） |
+
+---
+
+## 输入依赖
+
+- **前置SKILL**：无，可独立调用
+- **输入文件**：目标库根 `package.json`（读 name/version/harmony.autolinking 元数据）
+- **外部依赖**：git、Node.js ≥ 16、npm；验证阶段需 DevEco Studio（ohpm/hvigorw）
+- **MCP工具**：可选 `kb_search`（查询鸿蒙平台特定约束）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 前置检查与框架版本确定
+    ↓
+Phase 2: 浅拷贝模板并修改 app 名称（create-example.cjs）
+    ↓
+Phase 3: 库依赖接入（tgz）与壳层适配
+    ↓
+Phase 4: 预置 RNTesterList 注册入口与冒烟 Demo
+    ↓
+Phase 5: 渐进式验证链
+    ↓
+Phase 6: 库根工程卫生与输出报告
+```
+
+---
+
+## Phase 1：前置检查与框架版本确定
+
+### 1.1 检查 example/ 现状
+
+- **已存在** → **询问用户**：覆盖重建（`--force`）、增量更新、或取消
+- **缺失** → 继续 Phase 2
+
+### 1.2 读取库元数据
+
+读取 `libRoot/package.json`，提取 `name`、`version`、`harmony.alias`、`harmony.autolinking.*`（ohPackageName / etsPackageClassName / cppPackageClassName / cmakeLibraryTargetName）与源码模块路径（`harmony/{module}/`）。后续壳层适配全部由这些字段派生。
+
+### 1.3 确定 RNOH 框架版本
+
+从库 `dependencies` 中 `@react-native-oh/react-native-harmony` / `react-native-harmony` / `react-native` 的版本取 `major.minor`（如 `0.82.30` → `0.82`）。无法推断时**询问用户**，禁止猜测。
+
+> 版本对照表与模板目录结构参见 [模板仓库指南](references/TEMPLATE_REPO_GUIDE.md)
+
+---
+
+## Phase 2：浅拷贝模板并修改 app 名称
+
+执行主脚本（自动完成：浅克隆 → 复制 `{version}/` → `example/` → 排除 `.npmrc`/`.DS_Store` → 修改 app 名称 → 清理 querySchemes 模板残留）：
+
+```bash
+node {skillDir}/scripts/create-example.cjs \
+  --lib-path <libRoot> \
+  [--version 0.82] [--app-name XxxExample] [--bundle-name com.rnoh.xxx] [--force]
+```
+
+脚本完成后抽查确认：
+
+| 检查项 | 期望 |
+|--------|------|
+| `example/app.json` | name/displayName 已改为目标应用名 |
+| `example/package.json` | name 已替换（非 `react-native-harmony-tester`） |
+| `harmony/AppScope/app.json5` | bundleName 已替换（非模板残留 `com.harmony.wechat.lib.demo`） |
+| `example/.npmrc` | 不存在（含凭据文件必须删除） |
+| `grep -rn "wechat\|weixin" example/` | 无匹配 |
+
+> 脚本不可用（无 git 等）时的手动步骤与改名点位明细参见 [App 名称修改指南](references/APP_RENAME_GUIDE.md)
+
+---
+
+## Phase 3：库依赖接入（tgz）与壳层适配
+
+### 3.1 库依赖接入
+
+1. 库根 `.npmignore` 追加 `example`
+2. 库根 `npm pack` 生成 tgz
+3. `example/package.json` 依赖写 `"file:../{tgz文件名}"`
+
+> ⚠️ 禁止 `file:../目录` 形式（symlink 问题，详见核心原则 1）
+
+### 3.2 壳层适配
+
+按必查清单逐项适配（oh-package HAR 路径、CMakeLists 指向 node_modules、PackageProvider.cpp、RNPackagesFactory.ets、Index.ets、build-profile.template.json5 modules、metro/tsconfig alias、权限最小化）：
+
+> 完整清单参见 [壳层适配必查清单](references/SHELL_ADAPTATION_CHECKLIST.md)
+
+---
+
+## Phase 4：预置 RNTesterList 注册入口与冒烟 Demo
+
+下游技能探查 Demo 注册入口的第一优先级是 `{projectRoot}/**/RNTesterList.ts`（模式 A：`{key, category, module}` 数组），模板原生不含该文件，必须预置：
+
+1. 创建 `example/src/RNTesterList.ts`，首项 `{key: '{libName}', category: '{category}', module: require('./{libName}')}`
+2. `App.tsx`（或 `src/index.tsx`）消费该列表渲染 Navigation 页面
+3. 预置 1 个冒烟 Demo（`{exampleDir}/{libName}/index.tsx` + 最小可用页面，覆盖库核心链路如 open→exec→close）验证注册链路与原生桥通
+
+> 模式 A 代码模板参见 [壳层适配必查清单](references/SHELL_ADAPTATION_CHECKLIST.md) 第五节
+
+---
+
+## Phase 5：渐进式验证链
+
+按顺序执行，前一步失败先修复再继续：
+
+```
+1. cd example && npm install --legacy-peer-deps
+2. npm run dev                    # 成本最低，暴露 alias/依赖问题
+3. cd harmony && ohpm install --all
+4. hvigorw assembleHap --no-daemon
+5. nm -gU .../librnoh_app.so | grep <cppPackageClassName>   # 纯 ETS 库跳过
+```
+
+> 各步骤要点、unsigned HAP 预期、hvigor 调用方式与故障排查表参见 [渐进式验证指南](references/VERIFICATION_GUIDE.md)
+
+---
+
+## Phase 6：库根工程卫生与输出报告
+
+### 6.1 库根工程卫生
+
+- `.npmignore` 确认已含 `example`
+- `.gitignore` 追加 `harmony/{module}/oh_modules`、`harmony/{module}/oh-package-lock.json5`
+- npm pack 的 tgz 留在库根（CPF-RN 仓惯例）
+
+### 6.2 输出报告
+
+输出确认信息，包含：
+
+- example 目录路径与框架版本（RN/React/react-native-harmony）
+- 应用标识（appName / bundleName / npm 包名 / RN 注册名）
+- 库依赖接入方式（tgz 文件名）
+- 壳层适配完成项（对照必查清单）
+- RNTesterList 预置情况与冒烟 Demo 说明
+- 验证链各步执行结果（npm run dev / ohpm / hvigorw / 符号检查）
+- 需用户后续确认的事项（签名配置、真机部署）
+
+---
+
+## 异常处理
+
+| 异常场景 | 处理方式 |
+|----------|----------|
+| example/ 已存在且用户未确认 | 停止，等待用户选择（覆盖/增量/取消） |
+| 无法推断框架版本 | 询问用户显式指定 --version |
+| git clone 失败（网络） | 重试或提示用户配置代理/镜像后重试 |
+| 模板仓库无对应版本目录 | 列出可用版本，询问用户降级/升级选择 |
+| npm run dev 报 Unable to resolve module | 检查库依赖是否误用 file: 目录（改 tgz），详见验证指南故障表 |
+| TreeFS file map 报错 | 清 `node_modules/.cache` + `watchman watch-del-all` 后重跑 |
+| 未配置签名产出 unsigned HAP | 属预期，提醒用户真机部署前补 signingConfigs |
+
+---
+
+## 参考资料
+
+- [模板仓库指南](references/TEMPLATE_REPO_GUIDE.md) — RN3rdTemplate 结构、版本对照、手动拷贝步骤
+- [App 名称修改指南](references/APP_RENAME_GUIDE.md) — 名称派生规则、必改点位、改名校验
+- [壳层适配必查清单](references/SHELL_ADAPTATION_CHECKLIST.md) — 库元数据、tgz 接入、壳层适配、RNTesterList 预置
+- [渐进式验证指南](references/VERIFICATION_GUIDE.md) — 验证链、各步要点、故障排查表
+- RN3rdTemplate 仓库：https://gitcode.com/lalhanOrz/RN3rdTemplate

package/vendor/Server/Skills/rn-lib-add-example/references/APP_RENAME_GUIDE.md

@@ -0,0 +1,40 @@
+# App 名称修改指南
+
+> `scripts/create-example.cjs` 已自动完成以下全部修改点；本指南用于人工核对与脚本不可用时的手动修改。
+
+## 名称派生规则
+
+以库 `@react-native-ohos/react-native-sqlite-storage` 为例：
+
+| 名称项 | 派生规则 | 示例值 |
+|--------|----------|--------|
+| 应用显示名（appName） | 去 scope、去 `react-native-` 前缀后 PascalCase + `Example` | `SqliteStorageExample` |
+| RN 注册名（app.json name） | 短名中非字母数字字符转 `_` + `_example` | `sqlite_storage_example` |
+| 鸿蒙包名（bundleName） | `com.rnoh.` + 短名小写（非 `[a-z0-9]` 转 `_`） | `com.rnoh.sqlite_storage` |
+| npm 包名（package.json name） | 去 scope 包名 + `-example` | `react-native-sqlite-storage-example` |
+
+用户显式指定 `--app-name` / `--bundle-name` 时以用户为准。
+
+## 必改点位
+
+| # | 文件 | 修改内容 |
+|---|------|----------|
+| 1 | `example/app.json` | `name` → RN 注册名（AppRegistry 用，必须是合法标识符，禁止连字符）；`displayName` → 应用显示名 |
+| 2 | `example/package.json` | `name` → npm 包名（替换模板的 `react-native-harmony-tester`） |
+| 3 | `example/harmony/AppScope/app.json5` | `bundleName` → 鸿蒙包名（替换模板残留的 `com.harmony.wechat.lib.demo`） |
+| 4 | `example/harmony/AppScope/resources/base/element/string.json` | `app_name` 的 `value` → 应用显示名（桌面图标标签，`app.json5` 的 `label` 引用它） |
+| 5 | `example/harmony/entry/src/main/resources/base/element/string.json` | `EntryAbility_label` 的 `value` → 应用显示名 |
+| 6 | `example/harmony/entry/src/main/module.json5` | 移除模板残留的 `querySchemes: ["weixin"]` 整段（库确实需要 scheme 时再按需添加） |
+
+## 完成后校验
+
+1. `grep -rn "wechat\|weixin" example/` → 应无匹配（模板残留清零）
+2. `grep -rn "harmony-tester\|RN Tester" example/ --include="*.json*"` → 应无匹配（改名完整）
+3. `example/app.json` 的 `name` 与 `example/index.js` 中 `AppRegistry.registerComponent(appName, ...)` 读取的来源一致（index.js 自动读取 app.json，无需改动）
+4. `bundleName` 全局唯一，不与其他已装应用冲突
+
+## 安全清理（必做）
+
+- 删除 `example/.npmrc`（若存在）：模板可能内嵌私有 registry 的明文 `_authToken`，任何含凭据的文件严禁带入交付物
+- 删除 `example/.DS_Store` 等 macOS 元数据文件
+- RNOH 0.77/0.82/0.84 全部依赖可从公共 registry（npmmirror）解析，无需私有源