@ohos-cpf/3rdloop 0.0.2 → 0.0.3

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

@@ -1,198 +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
+---
+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

@@ -1,40 +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）解析，无需私有源
+# 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）解析，无需私有源

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

@@ -1,78 +1,78 @@
-# 壳层适配必查清单（库依赖接入）
-
-> 模板拷贝与改名完成后，将目标库接入 example 工程的必查清单。所有类名/路径/链接目标均由库 `package.json` 的元数据派生，禁止手抄猜测。
-
-## 一、库元数据读取
-
-从库根 `package.json` 读取以下字段，作为后续所有适配的输入：
-
-| 字段 | 用途 |
-|------|------|
-| `name` / `version` | npm 依赖名与 tgz 版本号 |
-| `harmony.alias` | metro/tsconfig 别名 |
-| `harmony.autolinking.ohPackageName` | ohpm 包名 |
-| `harmony.autolinking.etsPackageClassName` | `RNPackagesFactory.ets` import 的类名 |
-| `harmony.autolinking.cppPackageClassName` | `PackageProvider.cpp` 的类名 |
-| `harmony.autolinking.cmakeLibraryTargetName` | `CMakeLists.txt` link 目标 |
-| 源码模块路径（`harmony/{module}/`） | `build-profile.template.json5` 的 `modules[]` 与 CMake 路径 |
-
-## 二、库依赖接入（⚠️ 必须用 tgz）
-
-1. 库根 `.npmignore` 追加 `example`（否则 npm pack 会把整个 example 工程打进库包）
-2. 库根执行 `npm pack` 生成 `{包名去scope横线}-{版本}.tgz`
-3. `example/package.json` 依赖写 `"file:../{tgz文件名}"`
-4. 重装后确认 `node_modules/{ohPackageName}` 为**实体目录**而非符号链接
-
-> ⚠️ **禁止 `file:../目录` 形式**：npm 对目录型 `file:` 依赖默认以 symlink 安装，Metro/watchman 不跟随工程目录外的链接，`npm run dev` 报 `Unable to resolve module`。CPF-RN 系列仓库（netinfo、async-storage 等）均采用 tgz 方式，这是既定惯例。
-
-## 三、壳层适配必查文件
-
-| 文件 | 适配内容 |
-|------|----------|
-| `harmony/entry/oh-package.json5` | 追加库 HAR：`"{ohPackageName}": "file:../../node_modules/{ohPackageName}/harmony/{module}.har"` |
-| `harmony/entry/src/main/cpp/CMakeLists.txt` | `add_subdirectory` 指向 **node_modules**：`${NODE_MODULES}/{ohPackageName}/{sourceModulePath}/src/main/cpp`。⚠️ 严禁 oh_modules（HAR 内无 cpp 源码）。纯 ETS 库（无 cpp）跳过 |
-| `harmony/entry/src/main/cpp/PackageProvider.cpp` | `#include "{cppPackageClassName}.h"` + `std::make_shared<{cppPackageClassName}>(ctx)` |
-| `harmony/entry/src/main/ets/RNPackagesFactory.ets` | `import { {etsPackageClassName} } from '{ohPackageName}/ts'`，并在返回数组中 `new {etsPackageClassName}(ctx)` |
-| `harmony/entry/src/main/ets/pages/Index.ets` | 纯 TurboModule 库：`buildCustomRNComponent` 保持空、`arkTsComponentNames` 为空数组；有 Fabric 组件的库在此注册 |
-| `harmony/build-profile.template.json5` | `modules` 追加库源码模块 `{name: '{harmonyModuleName}', srcPath: '../../harmony/{module}'}`；删除 `useNormalizedOHMUrl`。⚠️ 改 template 而非 build-profile.json5（postinstall 会用 template 覆盖生成） |
-| `harmony/entry/src/main/module.json5` | 权限最小化：仅保留库所需权限（如 sqlite 仅 INTERNET），模板默认已只有 INTERNET，勿盲目添加 |
-| `metro.config.js` / `tsconfig.json` | `{alias}` → `node_modules/{ohPackageName}` 映射 |
-
-## 四、模板残留清理
-
-- `module.json5` 的 `querySchemes`（脚本已自动移除；库需要时再按需添加）
-- `src/` 下模板旧 demo 目录（当前模板仅 `src/index.tsx`，无旧 demo；若模板升级后带旧 demo 须删除）
-- 全局 `grep -rn "wechat\|weixin\|camera" example/` 确认无残留
-- 确认 `example/.npmrc` 已删除（含凭据文件严禁带入交付物）
-
-## 五、RNTesterList 注册入口预置
-
-下游技能（rnoh-lib-demo-create / rnoh-cptf-api-test）探查 Demo 注册入口的**第一优先级是 `{projectRoot}/**/RNTesterList.ts`**。模板原生只有 `App.tsx + src/index.tsx` 模式，必须**预置模式 A 注册入口**，否则后续 Demo 生成步骤找不到注册入口。
-
-### 5.1 创建 `example/src/RNTesterList.ts`
-
-```typescript
-export interface RNTesterModule {
-  key: string;
-  category: string;
-  module: any;
-}
-
-export const RNTesterList: RNTesterModule[] = [
-  {
-    key: '{libName}',
-    category: '{category}',
-    module: require('./{libName}'),
-  },
-];
-```
-
-首项指向 `{exampleDir}/{libName}/index.tsx`（后续由 Demo 生成技能创建）。同时预置 1 个**冒烟 Demo**（`{exampleDir}/{libName}/index.tsx` + 一个最小可用页面，如 sqlite 库的 openDatabase→executeSql→close 全链路）验证注册链路与原生桥通，保证不是空壳。
-
-### 5.2 `App.tsx` 消费 RNTesterList 渲染页面
-
-将 `src/index.tsx`（或 App 组件）改为消费 `RNTesterList` 渲染 Navigation 列表页，点击进入各 Demo 页面。
-
-### 5.3 衔接约定
-
-后续 Demo 生成步骤只需向 `RNTesterList` 数组追加 `{key, category, module}` 条目即完成注册，无需再改 App.tsx。
+# 壳层适配必查清单（库依赖接入）
+
+> 模板拷贝与改名完成后，将目标库接入 example 工程的必查清单。所有类名/路径/链接目标均由库 `package.json` 的元数据派生，禁止手抄猜测。
+
+## 一、库元数据读取
+
+从库根 `package.json` 读取以下字段，作为后续所有适配的输入：
+
+| 字段 | 用途 |
+|------|------|
+| `name` / `version` | npm 依赖名与 tgz 版本号 |
+| `harmony.alias` | metro/tsconfig 别名 |
+| `harmony.autolinking.ohPackageName` | ohpm 包名 |
+| `harmony.autolinking.etsPackageClassName` | `RNPackagesFactory.ets` import 的类名 |
+| `harmony.autolinking.cppPackageClassName` | `PackageProvider.cpp` 的类名 |
+| `harmony.autolinking.cmakeLibraryTargetName` | `CMakeLists.txt` link 目标 |
+| 源码模块路径（`harmony/{module}/`） | `build-profile.template.json5` 的 `modules[]` 与 CMake 路径 |
+
+## 二、库依赖接入（⚠️ 必须用 tgz）
+
+1. 库根 `.npmignore` 追加 `example`（否则 npm pack 会把整个 example 工程打进库包）
+2. 库根执行 `npm pack` 生成 `{包名去scope横线}-{版本}.tgz`
+3. `example/package.json` 依赖写 `"file:../{tgz文件名}"`
+4. 重装后确认 `node_modules/{ohPackageName}` 为**实体目录**而非符号链接
+
+> ⚠️ **禁止 `file:../目录` 形式**：npm 对目录型 `file:` 依赖默认以 symlink 安装，Metro/watchman 不跟随工程目录外的链接，`npm run dev` 报 `Unable to resolve module`。CPF-RN 系列仓库（netinfo、async-storage 等）均采用 tgz 方式，这是既定惯例。
+
+## 三、壳层适配必查文件
+
+| 文件 | 适配内容 |
+|------|----------|
+| `harmony/entry/oh-package.json5` | 追加库 HAR：`"{ohPackageName}": "file:../../node_modules/{ohPackageName}/harmony/{module}.har"` |
+| `harmony/entry/src/main/cpp/CMakeLists.txt` | `add_subdirectory` 指向 **node_modules**：`${NODE_MODULES}/{ohPackageName}/{sourceModulePath}/src/main/cpp`。⚠️ 严禁 oh_modules（HAR 内无 cpp 源码）。纯 ETS 库（无 cpp）跳过 |
+| `harmony/entry/src/main/cpp/PackageProvider.cpp` | `#include "{cppPackageClassName}.h"` + `std::make_shared<{cppPackageClassName}>(ctx)` |
+| `harmony/entry/src/main/ets/RNPackagesFactory.ets` | `import { {etsPackageClassName} } from '{ohPackageName}/ts'`，并在返回数组中 `new {etsPackageClassName}(ctx)` |
+| `harmony/entry/src/main/ets/pages/Index.ets` | 纯 TurboModule 库：`buildCustomRNComponent` 保持空、`arkTsComponentNames` 为空数组；有 Fabric 组件的库在此注册 |
+| `harmony/build-profile.template.json5` | `modules` 追加库源码模块 `{name: '{harmonyModuleName}', srcPath: '../../harmony/{module}'}`；删除 `useNormalizedOHMUrl`。⚠️ 改 template 而非 build-profile.json5（postinstall 会用 template 覆盖生成） |
+| `harmony/entry/src/main/module.json5` | 权限最小化：仅保留库所需权限（如 sqlite 仅 INTERNET），模板默认已只有 INTERNET，勿盲目添加 |
+| `metro.config.js` / `tsconfig.json` | `{alias}` → `node_modules/{ohPackageName}` 映射 |
+
+## 四、模板残留清理
+
+- `module.json5` 的 `querySchemes`（脚本已自动移除；库需要时再按需添加）
+- `src/` 下模板旧 demo 目录（当前模板仅 `src/index.tsx`，无旧 demo；若模板升级后带旧 demo 须删除）
+- 全局 `grep -rn "wechat\|weixin\|camera" example/` 确认无残留
+- 确认 `example/.npmrc` 已删除（含凭据文件严禁带入交付物）
+
+## 五、RNTesterList 注册入口预置
+
+下游技能（rnoh-lib-demo-create / rnoh-cptf-api-test）探查 Demo 注册入口的**第一优先级是 `{projectRoot}/**/RNTesterList.ts`**。模板原生只有 `App.tsx + src/index.tsx` 模式，必须**预置模式 A 注册入口**，否则后续 Demo 生成步骤找不到注册入口。
+
+### 5.1 创建 `example/src/RNTesterList.ts`
+
+```typescript
+export interface RNTesterModule {
+  key: string;
+  category: string;
+  module: any;
+}
+
+export const RNTesterList: RNTesterModule[] = [
+  {
+    key: '{libName}',
+    category: '{category}',
+    module: require('./{libName}'),
+  },
+];
+```
+
+首项指向 `{exampleDir}/{libName}/index.tsx`（后续由 Demo 生成技能创建）。同时预置 1 个**冒烟 Demo**（`{exampleDir}/{libName}/index.tsx` + 一个最小可用页面，如 sqlite 库的 openDatabase→executeSql→close 全链路）验证注册链路与原生桥通，保证不是空壳。
+
+### 5.2 `App.tsx` 消费 RNTesterList 渲染页面
+
+将 `src/index.tsx`（或 App 组件）改为消费 `RNTesterList` 渲染 Navigation 列表页，点击进入各 Demo 页面。
+
+### 5.3 衔接约定
+
+后续 Demo 生成步骤只需向 `RNTesterList` 数组追加 `{key, category, module}` 条目即完成注册，无需再改 App.tsx。