@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +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。

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

@@ -0,0 +1,70 @@
+# RN3rdTemplate 模板仓库指南
+
+> 模板仓库地址：https://gitcode.com/lalhanOrz/RN3rdTemplate（git clone 默认分支 main）
+
+## 仓库结构
+
+```
+RN3rdTemplate/
+├── 0.77/                    # RNOH 0.77 完整模板工程
+├── 0.82/                    # RNOH 0.82 完整模板工程
+├── 0.84/                    # RNOH 0.84 完整模板工程
+├── scripts/                 # 仓库自带集成脚本（auto-integrate.sh / add-library.sh / parse-library.py 等）
+├── skills/                  # 相关技能目录
+├── README.md
+└── update-harmony-lib.md
+```
+
+## 版本对照表
+
+| 属性 | 0.77 模板 | 0.82 模板 | 0.84 模板 |
+|------|-----------|-----------|-----------|
+| React Native | 0.77.1 | 0.82.1 | 0.84.1 |
+| React | 18.3.1 | 19.1.1 | 19.2.3 |
+| RNOH 核心（react-native-harmony） | 0.77.18-1 | 0.82.30 | 0.84.2 |
+| compatibleSdkVersion | 5.0.0(12) | 5.0.0(12) | 5.0.0(12) |
+
+**版本选择规则**：读取目标库 `package.json` 的 `dependencies`（或 devDependencies/peerDependencies）中 `@react-native-oh/react-native-harmony` / `react-native-harmony` / `react-native` 的版本号，取 `major.minor`（如 `0.82.30` → `0.82`）对应模板目录。无法推断时必须询问用户，禁止猜测。
+
+**版本注意**：
+- 不同版本的 HAR 不通用，必须使用对应版本的模板
+- RNOH 0.82 的 `compatibleSdkVersion: '5.0.0(12)'` 可直接使用；**0.84 的 HAR 元数据要求最低 API 17**，使用 0.84 模板时需按知识库经验（`experiences/rnoh-example-template-compatiblesdkversion-upgrade`）升级 compatibleSdkVersion
+
+## 模板目录内容（以 0.82 为例）
+
+```
+0.82/
+├── app.json                          # RN 应用名（name/displayName）
+├── package.json                      # name: react-native-harmony-tester
+├── index.js                          # AppRegistry 入口（读 app.json 的 name）
+├── metro.config.js / tsconfig.json   # RN 构建配置
+├── src/index.tsx                     # App 根组件（Hello RNOH 占位）
+├── scripts/create-build-profile.js   # postinstall：由 template 生成 build-profile.json5
+└── harmony/
+    ├── AppScope/app.json5            # bundleName / label（$string:app_name）
+    ├── build-profile.template.json5  # 应用级构建配置模板（signingConfigs 为空）
+    ├── entry/
+    │   ├── oh-package.json5          # @rnoh/react-native-openharmony HAR（file:../../node_modules/...）
+    │   ├── build-profile.json5       # entry 模块 native 编译配置
+    │   └── src/main/
+    │       ├── cpp/                  # CMakeLists.txt + PackageProvider.cpp
+    │       ├── ets/
+    │       │   ├── RNPackagesFactory.ets   # 三方库 ArkTS Package 注册（默认空）
+    │       │   └── pages/Index.ets         # RN 页面加载（buildCustomRNComponent 默认空）
+    │       ├── resources/base/element/string.json  # EntryAbility_label
+    │       └── module.json5          # 权限（默认仅 INTERNET）、querySchemes（模板残留 weixin）
+    └── oh-package.json5
+```
+
+## 手动拷贝步骤（脚本不可用时的替代流程）
+
+1. `git clone --depth 1 https://gitcode.com/lalhanOrz/RN3rdTemplate.git <tmpDir>`
+2. 复制 `<tmpDir>/<版本>/` 全部内容到 `<libRoot>/example/`（排除 `.git`、`.DS_Store`、`.npmrc`）
+3. 删除 `<tmpDir>`，然后按 [APP_RENAME_GUIDE.md](APP_RENAME_GUIDE.md) 逐项修改 app 名称
+
+## 模板 README 自带注意事项
+
+1. `build-profile.template.json5` 中 `signingConfigs` 为空，未配置签名时产出 unsigned HAP 属预期，真机部署前需在 DevEco Studio 配置签名
+2. 每次新增/修改三方库后需运行 `npm run codegen` 重新生成代码
+3. 运行 Metro 前需执行 `hdc rport tcp:8081 tcp:8081` 端口转发
+4. 仓库根 `scripts/` 提供库集成辅助脚本（auto-integrate.sh 等，Bash 脚本，仅类 Unix 环境可用），本 SKILL 优先使用自带跨平台脚本 `scripts/create-example.cjs`

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

@@ -0,0 +1,47 @@
+# 渐进式验证指南
+
+> example 工程创建完成后的标准验证链。按顺序执行，前一步失败先修复再继续——每一步暴露的问题层次不同，越早暴露成本越低。
+
+## 验证链（全部通过的标准动作）
+
+```
+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++ 包符号已链入（纯 ETS 库跳过）
+```
+
+## 各步骤要点
+
+| 步骤 | 验证内容 | 要点 |
+|------|----------|------|
+| 1. npm install | 依赖解析 | 若依赖是本地库 tgz，确认 node_modules 中为实体目录非符号链接 |
+| 2. npm run dev | JS 依赖/alias/bundle | **成本最低，能暴露 alias/依赖问题，不要跳过直接做鸿蒙编译**。产物 `rawfile/bundle.harmony.js` 可 grep 校验：应含 Demo 特征字符串（如 `smoke_test.db`），不应含模板残留（如 `camera`） |
+| 3. ohpm install | HAR 解析 | `--all` 会同时在库源码模块内产生 oh_modules（库根 .gitignore 需覆盖） |
+| 4. hvigorw assembleHap | 原生编译 + 打包 | 未配置 signingConfigs 时产出 **unsigned HAP 属预期**，不是构建失败 |
+| 5. nm 符号检查 | C++ 链接 | `nm -gU {example}/harmony/entry/build/default/intermediates/libs/default/arm64-v8a/librnoh_app.so \| grep {cppPackageClassName}` |
+
+**hvigor 调用方式**（用 DevEco 自带 node）：
+
+```bash
+/Applications/DevEco-Studio.app/Contents/tools/node/bin/node \
+  /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js assembleHap --no-daemon
+```
+
+**SDK 版本注意**：
+- RNOH **0.82** 模板的 `compatibleSdkVersion: '5.0.0(12)'` 可直接使用
+- RNOH **0.84** 的 HAR 要求最低 API 17，需升级 compatibleSdkVersion（详见知识库 `experiences/rnoh-example-template-compatiblesdkversion-upgrade`）
+
+**真机部署**：模板不携带签名证书，部署前在 `build-profile.json5` 补 signingConfigs（postinstall 保留已有签名配置）。运行 Metro 前需 `hdc rport tcp:8081 tcp:8081`。
+
+## 常见故障排查
+
+| 现象 | 根因 | 解决 |
+|------|------|------|
+| `Unable to resolve module @react-native-ohos/...` | 库依赖用了 `file:../目录`，node_modules 中为符号链接 | 改用 `npm pack` tgz + `file:../xxx.tgz`，删旧链接重装 |
+| `TreeFS: Could not add directory node_modules/... already exists in the file map as a file` | node_modules 布局变更后 Metro/watchman 缓存污染 | `rm -rf node_modules/.cache && watchman watch-del-all` 后重跑 |
+| `add_subdirectory given source ".../oh_modules/.../src/main/cpp" which is not an existing directory` | CMake 路径误用 oh_modules（HAR 内无 cpp 源码） | 改为 `${NODE_MODULES}/{ohPackageName}/{sourceModulePath}/src/main/cpp` |
+| hvigor 报 entry 模块缺 build-profile | `harmony/entry/build-profile.json5` 缺失 | postinstall 会从 template 恢复；确认 `npm install` 已执行 |
+| 构建产物含模板残留字符串 | 旧 demo/依赖未清理 | 清理 src 下旧目录、移除模板库依赖后重跑 `npm run dev` |
+| bundle 中找不到库代码 | metro alias 未配置 | `metro.config.js` / `tsconfig.json` 补 `{alias}` → `node_modules/{ohPackageName}` 映射 |

package/vendor/Server/Skills/rn-lib-add-example/scripts/create-example.cjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * @tool create-example
+ * @description 从 RN3rdTemplate 模板仓库浅拷贝对应 RNOH 框架版本的 example 模板到目标三方库，修改 app 名称与工程标识，并清理安全残留（.npmrc）与模板残留（querySchemes）。跨平台（Windows/macOS/Linux），仅需 Node.js + git。
+ * @param libPath: string - 目标库根目录（绝对路径，含 package.json）
+ * @param version: string - RNOH 框架版本（0.77/0.82/0.84），缺省从库 package.json 自动推断
+ * @param appName: string - 应用显示名（缺省从库名派生，如 SqliteStorageExample）
+ * @param bundleName: string - 鸿蒙应用包名（缺省派生为 com.rnoh.{lib_name}）
+ * @param templateUrl: string - 模板仓库地址（默认 https://gitcode.com/lalhanOrz/RN3rdTemplate.git）
+ * @param force: boolean - example/ 已存在时是否删除重建
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const DEFAULT_TEMPLATE_URL = 'https://gitcode.com/lalhanOrz/RN3rdTemplate.git';
+const KNOWN_VERSIONS = ['0.77', '0.82', '0.84'];
+const EXCLUDED_ENTRIES = new Set(['.git', '.DS_Store', '.npmrc']);
+
+function info(msg) { console.log(`[INFO] ${msg}`); }
+function warn(msg) { console.log(`[WARN] ${msg}`); }
+function fail(msg) { console.error(`[ERROR] ${msg}`); process.exit(1); }
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--force') { args.force = true; continue; }
+    if (a.startsWith('--')) {
+      const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const val = argv[i + 1];
+      if (val === undefined || val.startsWith('--')) { args[key] = true; continue; }
+      args[key] = val;
+      i++;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function readJson(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+function writeJson(p, obj) { fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n'); }
+
+function detectVersion(libPkg) {
+  const sections = ['dependencies', 'devDependencies', 'peerDependencies'];
+  const keys = ['@react-native-oh/react-native-harmony', 'react-native-harmony', 'react-native'];
+  for (const section of sections) {
+    const deps = libPkg[section] || {};
+    for (const key of keys) {
+      if (deps[key]) {
+        const m = String(deps[key]).match(/(\d+)\.(\d+)/);
+        if (m) return `${m[1]}.${m[2]}`;
+      }
+    }
+  }
+  return null;
+}
+
+function deriveNames(libName, explicitAppName, explicitBundleName) {
+  const unscoped = libName.startsWith('@') ? libName.split('/').pop() : libName;
+  const short = (unscoped.replace(/^react-native-/, '') || unscoped);
+  const pascalBase = short
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+  return {
+    appName: explicitAppName || `${pascalBase}Example`,
+    bundleName: explicitBundleName || `com.rnoh.${short.toLowerCase().replace(/[^a-z0-9]+/g, '_')}`,
+    rnAppName: `${short.replace(/[^a-zA-Z0-9]/g, '_')}_example`,
+    pkgName: `${unscoped}-example`,
+  };
+}
+
+function copyDirFiltered(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (EXCLUDED_ENTRIES.has(entry.name)) {
+      if (entry.name === '.npmrc') {
+        warn(`已排除含潜在凭据的文件: ${path.join(dest, entry.name)}（严禁带入交付物）`);
+      }
+      continue;
+    }
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirFiltered(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function setStringValue(json, name, value) {
+  const item = (json.string || []).find((s) => s.name === name);
+  if (item) item.value = value;
+  return Boolean(item);
+}
+
+function renameApp(exampleDir, names) {
+  const changes = [];
+
+  const appJsonPath = path.join(exampleDir, 'app.json');
+  if (fs.existsSync(appJsonPath)) {
+    const appJson = readJson(appJsonPath);
+    appJson.name = names.rnAppName;
+    appJson.displayName = names.appName;
+    writeJson(appJsonPath, appJson);
+    changes.push(`app.json: name=${names.rnAppName}, displayName=${names.appName}`);
+  } else {
+    warn('未找到 app.json，跳过 RN 应用名修改');
+  }
+
+  const pkgPath = path.join(exampleDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = readJson(pkgPath);
+    pkg.name = names.pkgName;
+    writeJson(pkgPath, pkg);
+    changes.push(`package.json: name=${names.pkgName}`);
+  }
+
+  const appJson5Path = path.join(exampleDir, 'harmony', 'AppScope', 'app.json5');
+  if (fs.existsSync(appJson5Path)) {
+    let content = fs.readFileSync(appJson5Path, 'utf8');
+    const updated = content.replace(
+      /("bundleName"\s*:\s*")[^"]*(")/,
+      `$1${names.bundleName}$2`
+    );
+    if (updated !== content) {
+      fs.writeFileSync(appJson5Path, updated);
+      changes.push(`harmony/AppScope/app.json5: bundleName=${names.bundleName}`);
+    }
+  } else {
+    warn('未找到 harmony/AppScope/app.json5，跳过 bundleName 修改');
+  }
+
+  const scopeStrPath = path.join(
+    exampleDir, 'harmony', 'AppScope', 'resources', 'base', 'element', 'string.json'
+  );
+  if (fs.existsSync(scopeStrPath)) {
+    const scopeStr = readJson(scopeStrPath);
+    if (setStringValue(scopeStr, 'app_name', names.appName)) {
+      writeJson(scopeStrPath, scopeStr);
+      changes.push(`harmony/AppScope/.../string.json: app_name=${names.appName}`);
+    }
+  }
+
+  const entryStrPath = path.join(
+    exampleDir, 'harmony', 'entry', 'src', 'main', 'resources', 'base', 'element', 'string.json'
+  );
+  if (fs.existsSync(entryStrPath)) {
+    const entryStr = readJson(entryStrPath);
+    if (setStringValue(entryStr, 'EntryAbility_label', names.appName)) {
+      writeJson(entryStrPath, entryStr);
+      changes.push(`harmony/entry/.../string.json: EntryAbility_label=${names.appName}`);
+    }
+  }
+
+  const moduleJson5Path = path.join(exampleDir, 'harmony', 'entry', 'src', 'main', 'module.json5');
+  if (fs.existsSync(moduleJson5Path)) {
+    let content = fs.readFileSync(moduleJson5Path, 'utf8');
+    const updated = content.replace(
+      /[ \t]*"querySchemes"\s*:\s*\[[\s\S]*?\][ \t]*,?\s*\r?\n/,
+      ''
+    );
+    if (updated !== content) {
+      fs.writeFileSync(moduleJson5Path, updated);
+      changes.push('harmony/entry/src/main/module.json5: 已移除模板残留 querySchemes（库需要时请重新添加）');
+    }
+  }
+
+  return changes;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const libPath = path.resolve(args.libPath || args._[0] || '');
+  if (!args.libPath && args._.length === 0) {
+    fail('缺少参数：--lib-path <目标库根目录>');
+  }
+  if (!fs.existsSync(libPath)) fail(`库目录不存在: ${libPath}`);
+  const libPkgPath = path.join(libPath, 'package.json');
+  if (!fs.existsSync(libPkgPath)) fail(`未找到库 package.json: ${libPkgPath}`);
+  const libPkg = readJson(libPkgPath);
+
+  const exampleDir = path.join(libPath, 'example');
+  if (fs.existsSync(exampleDir)) {
+    if (!args.force) {
+      fail(`example/ 已存在: ${exampleDir}。如需重建请加 --force（将删除现有目录后重建）`);
+    }
+    warn('--force 生效：删除已有 example/ 目录');
+    fs.rmSync(exampleDir, { recursive: true, force: true });
+  }
+
+  const version = args.version || detectVersion(libPkg);
+  if (!version) {
+    fail(`无法从库 package.json 推断 RNOH 框架版本，请显式指定 --version（可选：${KNOWN_VERSIONS.join(' / ')}）`);
+  }
+  if (!KNOWN_VERSIONS.includes(version)) {
+    fail(`不支持的版本 ${version}，模板仓库可选版本：${KNOWN_VERSIONS.join(' / ')}`);
+  }
+
+  const templateUrl = args.templateUrl || DEFAULT_TEMPLATE_URL;
+  const names = deriveNames(libPkg.name || 'rn-lib', args.appName, args.bundleName);
+
+  info(`目标库: ${libPath}（${libPkg.name}@${libPkg.version || 'unknown'}）`);
+  info(`框架版本: ${version} → 模板 ${templateUrl}#${version}`);
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rn3rd-template-'));
+  try {
+    info(`浅拷贝模板仓库（git clone --depth 1）...`);
+    try {
+      execFileSync('git', ['clone', '--depth', '1', templateUrl, tmpDir], { stdio: 'inherit' });
+    } catch (e) {
+      fail(`git clone 失败: ${e.message}`);
+    }
+    const versionDir = path.join(tmpDir, version);
+    if (!fs.existsSync(versionDir)) {
+      fail(`模板仓库中不存在版本目录 ${version}/（可选：${KNOWN_VERSIONS.join(' / ')}）`);
+    }
+    info(`复制模板 ${version}/ → ${exampleDir}`);
+    copyDirFiltered(versionDir, exampleDir);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+
+  info('修改 app 名称与工程标识...');
+  const changes = renameApp(exampleDir, names);
+  for (const c of changes) info(`  - ${c}`);
+
+  console.log('');
+  console.log('=== example 工程创建完成 ===');
+  console.log(`  目录:       ${exampleDir}`);
+  console.log(`  应用名:     ${names.appName}`);
+  console.log(`  RN 注册名:  ${names.rnAppName}`);
+  console.log(`  鸿蒙包名:   ${names.bundleName}`);
+  console.log(`  npm 包名:   ${names.pkgName}`);
+  console.log('');
+  console.log('后续步骤:');
+  console.log(`  1. cd "${libPath}" && npm pack（先确认 .npmignore 已排除 example）`);
+  console.log(`  2. 修改 ${path.join('example', 'package.json')} 依赖为 file:../{tgz文件名}（禁止 file:../ 目录）`);
+  console.log('  3. 预置 example/src/RNTesterList.ts（模式 A）注册入口');
+  console.log('  4. cd example && npm install --legacy-peer-deps && npm run dev');
+  console.log('  5. cd harmony && ohpm install --all && hvigorw assembleHap --no-daemon');
+}
+
+main();

package/vendor/Server/Skills/rn-lib-update-doc/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: rn-lib-update-doc
+description: 将 RN 鸿蒙三方库文档与元数据按模板（默认 v0.4.2）迁移/升级：README 中英文、package.json 链接与 keywords、harmony oh-package.json5、CHANGELOG 格式；必要时从 usage-docs 拉正文并结合库实现改写；链接统一 CPF-RN 组织。Use when the user mentions 更新 README、readme 模板、0.4.2 文档、usage-docs 迁移、README_EN、文档模板升级、rn-lib-update-doc、更新文档、CHANGELOG 规范、package.json 链接.
+license: Apache-2.0
+compatibility: 需要 Node.js（脚本）与 curl（链接可达性校验），需对目标库与 usage-docs（可选）的文件读写权限
+metadata:
+  author: LoopEngine
+  version: "1.1.0"
+---
+
+## 路径约定
+
+`{SKILL_DIR}` = 本技能根目录，命令在 `{SKILL_DIR}` 下执行（即下文 `node scripts/...` 均为相对于 `{SKILL_DIR}` 的路径）；`$LIB` = 目标库根目录。
+
+# RN 三方库文档与元数据升级（rn-lib-update-doc）
+
+将目标库 **README / 包元数据 / CHANGELOG** 升级到规范：文档模板（默认 **v0.4.2**，见 [`references/model-0.4.2.md`](references/model-0.4.2.md)）、[CPF-RN](https://gitcode.com/CPF-RN) 组织链接、npm/harmony 包描述一致；内容必须与**当前库版本实际实现**一致；若本地有 usage-docs，再按 overview 模板覆盖回写该库中英文档。
+
+## 任务参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `libPath` | ✅ | 目标库根目录（含 package.json / README.md） |
+| `templateVersion` | ❌ | 文档模板版本，默认 0.4.2 |
+| `usageDocsPath` | ❌ | 本地 usage-docs 仓路径（config.json 无效时需提供） |
+
+---
+
+## 工作流程概览
+
+```
+Phase 1 确认模板版本 → Phase 2 判定格式/获取正文 → Phase 3 改写 README（含链接规范化）
+    → Phase 4 回写 usage-docs（可选） → Phase 5 规范包元数据 → Phase 6 规范 CHANGELOG
+```
+
+## 执行步骤
+
+```
+Task Progress:
+- [ ] Step 1: 确认文档模板版本（默认 0.4.2）
+- [ ] Step 2: 判定本库 README 格式；必要时从 usage-docs 迁移正文
+- [ ] Step 3: 按模板 + 库实际实现改写 README.md / README_EN.md
+- [ ] Step 3.5: 链接规范化（CPF-RN：Issue/PR/LICENSE/Autolink 等）
+- [ ] Step 4: 若有本地 usage-docs，按 overview 覆盖回写中英文
+- [ ] Step 5: 规范 package.json 与 harmony oh-package.json5
+- [ ] Step 6: 规范 CHANGELOG.md（Keep a Changelog）
+```
+
+### Step 1 — 确认文档模板
+
+**必须先问用户**：是否要更换文档模板版本？
+
+- **不更换** → 使用 [`references/model-0.4.2.md`](references/model-0.4.2.md) 与 [`references/model-0.4.2-overview.md`](references/model-0.4.2-overview.md)
+- **要更换** → 用户提供新模板路径，复制到 `references/` 后按新模板执行
+
+### Step 2 — 判定格式并获取正文来源
+
+```bash
+node scripts/detect-readme-format.cjs <lib-root> [--expect 0.4.2]
+```
+
+| 检测结果 | 动作 |
+|----------|------|
+| 已是目标模板（如 0.4.2） | 进入 Step 3 校对/补全 |
+| 已是 **0.4.1** 结构 | 以本库现有 README 为素材，直接 Step 3 升级 |
+| 非目标模板 / 仅外链 README | 从 usage-docs 迁正文（见下方） |
+
+**usage-docs：**
+
+```bash
+node scripts/resolve-usage-docs.cjs [--set <local-path>] [--print]
+node scripts/find-usage-doc.cjs --lib-path <lib-root> [--usage-docs <path>]
+```
+
+远端 fallback：`https://gitcode.com/CPF-RN/usage-docs`（raw：`.../raw/master/zh-cn/<alias>.md` 与 `en/<alias>.md`）
+
+### Step 3 — 按模板改造 README（必须贴合当前库）
+
+以 `model-0.4.2.md` 为骨架，结合 `package.json`、源码、`harmony/`、example、当前分支 Autolink 事实改写 `README.md` / `README_EN.md`。
+
+**硬性要求：**
+
+- 版本关系表、安装、Link、约束、示例、接口说明与**当前实现**一致
+- **贡献代码**：Issue / PR 链接必须指向 **CPF-RN 本库**（`https://gitcode.com/CPF-RN/rntpc_<alias>/issues` 与 `.../pulls`）
+- **开源协议**：LICENSE 链接指向 **CPF-RN 本库** `.../blob/master/LICENSE`（勿仅指向上游 GitHub LICENSE，除非协议章节明确说明上游协议且本库 LICENSE 文件不同）
+- 对照 [format-diff.md](references/format-diff.md) 完成章节与表头调整，并按其中 [ManualLink 章节规则](references/format-diff.md#manuallink-章节autolink-全支持时删除) 判断 Autolink 全支持时删除该章节（**必判**）
+
+### Step 3.5 — 链接规范化与可达性校验（**必做**）
+
+**禁止**仅做字符串级组织替换。所有写入 README / `package.json` 的链接，替换后必须 **HTTP 可达**（2xx/3xx）方可 `--write`。
+
+```bash
+node scripts/normalize-readme-links.cjs --lib-path "$LIB"
+node scripts/normalize-readme-links.cjs --lib-path "$LIB" --write
+```
+
+**校验规则（`scripts/link-verify.cjs`）：**
+
+1. 解析本库 GitCode：对 `git remote` / `repository` / `rntpc_<alias>` 等候选执行 `curl -L`，选用首个可达的 CPF-RN 仓库根 URL
+2. 组织迁移：含 `openharmony-sig` 的 URL 仅当 CPF-RN 目标**探测可达**才替换；不可达则保留原链并报告 `unverified-org-migration`
+3. Issue / PR / LICENSE：仅在仓库根 URL 已验证时，才改写到 `{libRepoBase}/issues`、`/pulls`、`/blob/master/LICENSE`
+4. 对 README 终稿中全部 `http(s)` 链接汇总校验（报告 `linkVerification.failures`）
+
+离线调试可加 `--skip-verify`；**交付前必须去掉**重新校验。
+
+**必须确认：**
+
+- 本库 Gitcode 在 [CPF-RN](https://gitcode.com/CPF-RN) 且仓库页可访问
+- README 中 **Issue / PR / LICENSE** 链接均可打开
+- Autolinking → `CPF-RN/ohos_react_native`；link-source-code → `CPF-RN/usage-docs`
+
+退出码 `2` 表示链接不可达或仓库未验证，修复后再 `--write`。
+
+### Step 4 — 回写 usage-docs（仅本地仓）
+
+有本地 usage-docs 时，用 `model-0.4.2-overview.md` 覆盖 `{usageDocs}/zh-cn/<alias>.md` 与 `en/<alias>.md`。无本地仓则跳过。
+
+### Step 5 — 规范 package.json 与 harmony oh-package.json5（**必做**）
+
+```bash
+node scripts/normalize-package-meta.cjs --lib-path "$LIB"
+node scripts/normalize-package-meta.cjs --lib-path "$LIB" --write
+```
+
+**package.json 检查项：**
+
+| 字段 | 要求 |
+|------|------|
+| `repository.url` | `https://gitcode.com/CPF-RN/rntpc_<alias>.git` |
+| `homepage` | `https://gitcode.com/CPF-RN/rntpc_<alias>` |
+| `bugs.url` | `https://gitcode.com/CPF-RN/rntpc_<alias>/issues` |
+| `license` | `"MIT"`（与库根 LICENSE 一致；若非 MIT 以 LICENSE 文件为准并告知用户） |
+| `publishConfig` | `{ "registry": "https://registry.npmjs.org/", "access": "public" }` |
+| `keywords` | 在现有基础上**补全**（去重）：`rnoh`、`harmonyos`、`openharmony`、`ohos` |
+
+**harmony 模块 `oh-package.json5`（每个 `harmony/**/oh-package.json5`，不含 example 内三方依赖副本时可跳过 example）：**
+
+| 字段 | 要求 |
+|------|------|
+| `license` | `"MIT"` |
+| `description` | 简短说明，与 `package.json` 的 `description` 一致或同义（如 `React Native Blur OpenHarmony module`） |
+
+脚本在写回 `homepage` / `bugs.url` / `repository` 前会调用 `link-verify.cjs` 校验可达性；验证失败时**拒绝 `--write`**（除非 `--skip-verify`）。
+
+### Step 6 — 规范 CHANGELOG.md（**必做**）
+
+按 [Keep a Changelog](https://keepachangelog.com/) 重组，参考 [`references/changelog-template.md`](references/changelog-template.md)。
+
+**结构要求：**
+
+1. 文首说明基于 Keep a Changelog
+2. `## [Unreleased]` 节（可为空）
+3. 鸿蒙化版本：`## [x.y.z] - YYYY-MM-DD`，下含 `### Added` / `Changed` / `Fixed` / `Deprecated` 等（无内容可省略该分类，但**禁止**仅用无序列表无分类）
+4. 上游 Release 可单独放在 `## Upstream Release Notes`，勿与鸿蒙版本混用 `## 鸿蒙化Log`、`### v4.x.x` 等旧标题
+
+**校验：**
+
+```bash
+node scripts/normalize-changelog.cjs --lib-path "$LIB"
+```
+
+退出码 `2` 表示格式不合规，需人工重组后再提交。
+
+## 需向用户确认
+
+1. 是否更换文档模板（Step 1；默认 0.4.2）
+2. 目标库根目录（若工作区不明确）
+3. usage-docs 本地路径（需拉取且 config 无效时）
+4. `license` 非 MIT 时是否仍强制写 MIT（以 LICENSE 文件为准）
+5. Step 4 回写前展示将覆盖的 usage-docs 路径
+
+## 不在范围内
+
+- 不修改库业务源码（仅文档与元数据；`package.json` / `CHANGELOG.md` / `OAT.xml` 等交付相关除外）
+- 不自动 git commit / push
+- 不替代 OAT / 交付件生成技能

package/vendor/Server/Skills/rn-lib-update-doc/config.json

@@ -0,0 +1,5 @@
+{
+  "usageDocsPath": null,
+  "remoteUsageDocs": "https://gitcode.com/CPF-RN/usage-docs",
+  "remoteDefaultBranch": "master"
+}

package/vendor/Server/Skills/rn-lib-update-doc/references/changelog-template.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [x.y.z] - YYYY-MM-DD
+
+### Added
+
+- new features
+
+### Changed
+
+- changes in existing functionality
+
+### Fixed
+
+- bug fixes
+
+### Deprecated
+
+- soon-to-be removed features
+
+## Upstream Release Notes
+
+> 可选：社区上游 Release 记录单独分区，避免与鸿蒙化版本混用旧式标题。
+
+### Release x.y.z
+
+#### Features
+
+- upstream changes