@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-rnt-search/assets/PORT_REPORT_TEMPLATE.md

@@ -0,0 +1,219 @@
+# rnt Demo 迁移报告模板
+
+> Agent 读取此模板，填充 `{{占位符}}` 实际值后写入目标路径。
+> 输出路径：`{libPath}/rnt-demo-port-report.md`（或 `{libPath}/rn-lib-ohos/rnt-demo-port-report.md` 处于父流程中时）
+
+---
+
+# rnt Demo 迁移报告 — {{库名}}
+
+> 生成时间：{{生成时间}}
+> 生成工具：rnoh-lib-rnt-search v1.0.0
+
+## 1. 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 目标库 | {{packageName}} |
+| 库版本 | {{version}} |
+| harmony.alias | {{alias}} |
+| 目标库根目录 | {{libPath}} |
+| 目标 example/src | {{targetExampleSrc}} |
+| rnt 工程根 | {{rntPath}} |
+| 库分支 | {{libBranch}} |
+| rnt 分支 | {{rntBranch}} |
+| RNOH 版本 | {{rnohVersion}} |
+| example/package.json RN 版本 | {{exampleRnVersion}} |
+| 版本一致性 | ✅ 一致 / ❌ 不一致 |
+
+## 2. demo 来源
+
+| 项 | 值 |
+|----|-----|
+| rnt 子工程 | {{rntSubproject}} |
+| demo 目录路径 | {{demoPath}} |
+| 命中候选名 | {{matchedSearchName}} |
+| 扫描方式 | 自动扫描 / 用户指定 |
+| demo 结构 | 根级入口 / testCase 嵌套 / 混合 |
+
+## 3. 库元数据（read-lib-meta.cjs 摘要）
+
+```json
+{{libMetaJson}}
+```
+
+> 完整元数据由 `read-lib-meta.cjs` 输出。`autolinkingResolved` 供下游 `rn-lib-add-example` 壳层适配使用。
+
+## 4. 迁移文件清单
+
+迁移文件总数：{{文件总数}}
+
+> 迁移模式：**增量添加**（`--ignore-existing`），不覆盖目标已有文件。
+
+| # | 相对路径 | 类型 | 迁移状态 | 备注 |
+|---|---------|------|---------|------|
+| 1 | App.tsx | 入口 | ✅ 新增 | displayName: {{displayName}} |
+| 2 | index.tsx | 导出 | ✅ 新增 / ⚠️ 冲突保留 | — |
+| 3 | tests/index.tsx | testerino 注册 | ✅ 新增 | 路径已修正 |
+| ... | ... | ... | ... | ... |
+
+### 4.0 冲突文件清单（目标版本已保留）
+
+> 以下文件在目标 `example/src/` 中已存在，**目标版本已保留，demo 版本未写入**。请人工确认是否需要合并：
+
+| # | 相对路径 | 目标版本来源 | 建议 |
+|---|---------|-------------|------|
+| 1 | {{冲突文件}} | example 模板 / 上次迁移 | 手动对比差异后决定是否合并 |
+| ... | ... | ... | ... |
+
+> 若无冲突文件，本节标注「无冲突」。
+
+### 4.1 排除项
+
+以下目录/文件未迁移（脚本默认排除）：
+
+- `node_modules/`
+- `build/`
+- `__tests__/`（demo 自带测试）
+- `.cxx/` / `oh_modules/`
+- `.DS_Store` / `*.log`
+
+### 4.2 原生代码（若有）
+
+> demo 含以下原生文件，未迁移到 `example/src/`，需由 `rn-lib-add-example` 处理壳层适配：
+
+| 文件 | 类型 | 建议处理 |
+|------|------|---------|
+| {{原生文件}} | .ets / .cpp / .h | 移至 `example/harmony/` |
+
+## 5. 依赖增量清单
+
+### 5.1 目标库本身
+
+| 包名 | 引用方式 | 建议写入 example/package.json |
+|------|---------|------------------------------|
+| {{packageName}} | `import { X } from '{{alias}}'` | `"{{packageName}}": "file:../{{tgzName}}"` |
+
+### 5.2 RNOH 框架依赖
+
+| 包名 | 当前版本 | 建议版本 | 来源 |
+|------|---------|---------|------|
+| @react-native-oh/react-native-harmony | — | {{rnohVersion}} | example 模板默认 |
+
+### 5.3 RN 通用依赖
+
+| 包名 | demo 引用 | 建议版本来源 |
+|------|----------|-------------|
+| {{pkgName}} | `import { X } from '{{pkgName}}'` | example 模板 / rnt 工程 |
+
+### 5.4 待人工确认依赖
+
+> 以下依赖未自动分类，请用户确认是否写入 example/package.json：
+
+| 包名 | demo 引用 | 说明 |
+|------|----------|------|
+| {{pkgName}} | `import { X } from '{{pkgName}}'` | {{说明}} |
+
+## 6. 路径修正记录
+
+> 仅记录**本次新增文件**的修正。目标已有文件（冲突保留项）不修改，其待修正项列入第 10 章待人工确认。
+
+| # | 文件 | 修正类型 | 修正前 | 修正后 | 原因 |
+|---|------|---------|--------|--------|------|
+| 1 | index.tsx | 入口接入 | 独立内容 | re-export testCase/App | demo 入口未接入（仅新增文件） |
+| 2 | testCase/Navigation.tsx | 硬编码标题 | "RN Svg Capi Tester" | "RN Pdf Tester" | 遗留其他库标题 |
+| ... | ... | ... | ... | ... | ... |
+
+## 7. 入口文件信息
+
+| 文件 | 字段 | 值 |
+|------|------|-----|
+| {{appPath}} | displayName | {{displayName}} |
+| {{appPath}} | title | {{title}} |
+| index.tsx | 接入方式 | re-export {{appPath}} / 独立入口 |
+| {{testIndexPath}} | 注册组件名 | {{registeredNames}} |
+
+## 8. 目标库引用方式
+
+| demo 引用方式 | example 配置建议 | 状态 |
+|--------------|-----------------|------|
+| `import { X } from '{{alias}}'` | metro.config.js extraNodeModules | 待 rn-lib-add-example 配置 |
+| `import { X } from '{{packageName}}'` | tsconfig.json paths | 待 rn-lib-add-example 配置 |
+
+## 9. 验证检查结果
+
+| # | 检查项 | 结果 | 备注 |
+|---|--------|------|------|
+| 1.1.1 | 文件完整性 | ✅ / ❌ | {{备注}} |
+| 1.1.2 | 入口文件存在 | ✅ / ❌ | {{备注}} |
+| 1.1.3 | testerino 注册存在 | ✅ / ❌ | {{备注}} |
+| 1.1.4 | 无排除项残留 | ✅ / ❌ | {{备注}} |
+| 1.1.5 | index.tsx 引用 demo 入口 | ✅ / ❌ | {{备注}} |
+| 1.2.1 | 子目录下无错误相对路径 | ✅ / ❌ | {{备注}} |
+| 1.2.2 | import 路径可解析 | ✅ / ❌ | {{备注}} |
+| 1.3.1 | 目标库引用方式一致 | ✅ / ❌ | {{备注}} |
+| 1.3.2 | displayName 存在 | ✅ / ❌ | {{备注}} |
+| 1.3.3 | 无硬编码其他库标题 | ✅ / ❌ | {{备注}} |
+| 1.4.1 | 外部依赖已列出 | ✅ / ❌ | {{备注}} |
+| 1.4.2 | 无未识别 require | ✅ / ❌ | {{备注}} |
+| 1.4.3 | **外部依赖已在 example/package.json 声明** | ✅ / ❌ | {{缺失依赖列表}} |
+| 1.5.1 | **无孤立文件（所有 demo 可导航）** | ✅ / ❌ | {{孤立文件列表}} |
+| 1.5.2 | **菜单可滚动（条目 > 5 时为 ScrollView）** | ✅ / ❌ | {{条目数}} |
+| 1.5.3 | **原有 App.tsx 可访问** | ✅ / ❌ | {{备注}} |
+| 1.5.4 | **入口链路端到端完整** | ✅ / ❌ | {{备注}} |
+| 1.6.1 | **build-profile 无越界路径** | ✅ / ❌ | {{备注}} |
+| 1.6.2 | **.har 文件路径有效** | ✅ / ❌ | {{备注}} |
+| 1.7.1 | 库与 rnt 版本一致 | ✅ / ❌ | {{备注}} |
+| 1.7.2 | example/package.json 版本匹配 | ✅ / ❌ | {{备注}} |
+
+## 10. 构建前置检查结果
+
+| # | 检查项 | 结果 | 备注 / 修正内容 |
+|---|--------|------|----------------|
+| 1 | **外部依赖缺失清单** | ✅ 无缺失 / ❌ 缺失 | {{缺失依赖列表 + 建议写入值}} |
+| 2 | **build-profile.json5 路径越界** | ✅ 无越界 / ❌ 已修正 | {{修正详情：复制了哪些模块、修改了哪些 srcPath}} |
+| 3 | **.har 文件路径验证** | ✅ 全部有效 / ❌ 已修正 | {{修正详情：哪些 oh-package.json5 的 file: 路径被修改}} |
+| 4 | **入口链路验证** | ✅ 完整 / ❌ 有断裂 | {{断裂点}} |
+
+## 11. 待人工确认项
+
+| # | 项 | 说明 | 建议 |
+|---|----|------|------|
+| 1 | 冲突文件合并 | demo 与目标同名文件已保留目标版本（见 4.0 章） | 手动对比差异后决定是否合并 |
+| 2 | 入口文件接入 | 若 index.tsx 为已有文件且未引用 demo 入口 | 手动在已有 index.tsx 中添加 re-export |
+| 3 | 已有文件硬编码标题 | 目标已有文件中的 Navigation.tsx 等含其他库标题 | 手动修正或确认无需处理 |
+| 4 | 业务无关依赖 | demo 引用了与目标库无关的包 | 确认是否写入 example/package.json |
+| 5 | 版本不一致 | example/package.json RN 版本与目标 RNOH 版本不一致 | 由 rn-lib-add-example 更新 |
+| ... | ... | ... | ... |
+
+## 12. 后续步骤建议
+
+本 SKILL 已完成 demo 文件**增量迁移**（不覆盖已有文件）与新增文件路径修正。建议执行以下后续步骤：
+
+1. **执行 `rn-lib-add-example`** 完成：
+   - example 模板创建（若缺失）
+   - `example/package.json` 依赖写入（消费本报告第 5 章，**特别是缺失依赖**）
+   - `metro.config.js` / `tsconfig.json` 别名配置（消费本报告第 8 章）
+   - Harmony 壳层适配（RNPackagesFactory.ets / CMakeLists.txt / build-profile.template.json5 等）
+   - License 头补全 / OAT.xml 过滤项
+
+2. **编译验证**（确认构建前置检查全部通过后）：
+   ```bash
+   cd example && npm i --legacy-peer-deps    # 安装 JS 依赖
+   cd harmony && ohpm install                 # 安装鸿蒙原生依赖
+   cd .. && npm run dev                       # 生成 JS bundle
+   cd harmony && devecocli build              # 编译鸿蒙工程
+   ```
+   > `npm i` 只装 JS 依赖，`ohpm install` 才装 .har 依赖，两者都不可省略。
+
+3. **（可选）执行 `rnoh-lib-demo-coverage`** 评估 demo 对库 API 的覆盖程度。
+
+4. **人工确认**本报告第 11 章的待确认项，特别是：
+   - 缺失依赖是否已写入 example/package.json
+   - 冲突文件是否需要手动合并（第 4.0 章）
+   - 已有 index.tsx 是否需要手动接入 demo 入口
+   - 已有文件中的硬编码标题是否需要修正
+
+---
+
+> 报告生成完毕。如有疑问，请检查 `references/` 下的详细指南。

package/vendor/Server/Skills/rnoh-lib-rnt-search/references/DEMO_PORTING_GUIDE.md

@@ -0,0 +1,345 @@
+# Demo 迁移详细指南
+
+> 本文档说明 demo 迁移的完整流程、库元数据字段、依赖分析规则、路径修正检查清单。
+
+---
+
+## 1. 库元数据字段
+
+`scripts/read-lib-meta.cjs` 输出 JSON，各字段用途：
+
+| 字段 | 类型 | 来源 | 用途 |
+|------|------|------|------|
+| `packageName` | string | `package.json.name` | npm 包名，写入 example `dependencies` |
+| `version` | string | `package.json.version` | tgz 版本号 |
+| `alias` | string | `harmony.alias` 或 scoped | metro 别名，候选搜索名 |
+| `scoped` | string | packageName 去 scope | 候选搜索名 |
+| `dirBase` | string | 目录 basename | 候选搜索名 |
+| `searchNames` | string[] | 上述去重 | demo 扫描候选名列表 |
+| `autolinking` | object \| null | `harmony.autolinking` | 鸿蒙化链接配置（供下游壳层适配） |
+| `autolinkingResolved` | object | 脚本推断 | 源码模块路径、CMake 路径等（供下游使用） |
+| `codegenConfig` | object \| null | `package.json.codegenConfig` | codegen 配置 |
+
+### 1.1 autolinkingResolved 字段
+
+| 字段 | 说明 | 下游用途 |
+|------|------|---------|
+| `ohPackageName` | ohpm 包名 | `RNPackagesFactory.ets` import |
+| `sourceModulePath` | `harmony/{module}/` 路径 | CMake `add_subdirectory`、`build-profile.template.json5` 的 `srcPath` |
+| `harmonyModuleName` | 源码模块目录名 | `build-profile.template.json5` 的 `modules[].name` |
+| `hasCpp` | 是否有 C++ 源码 | 决定是否写 CMake |
+| `cmakeCppPath` | C++ 源码路径（node_modules 下） | CMake `add_subdirectory` |
+| `cmakeShortName` | CMake 短名 | `add_subdirectory` 第二参数 |
+| `etsPackageClassName` | ETS Package 类名 | `RNPackagesFactory.ets` |
+| `cppPackageClassName` | C++ Package 类名 | `PackageProvider.cpp` |
+| `cmakeLibraryTargetName` | CMake link target | `target_link_libraries` |
+
+> ⚠️ `sourceModulePath` **不要**写入 `package.json` 的 `harmony.autolinking.mainHarPath`（会导致 RNOH CLI 扫不到 `.har`）。
+
+---
+
+## 2. 依赖分析与写入
+
+### 2.1 依赖分类
+
+`scripts/analyze-demo-deps.cjs` 扫描 demo 源码的 `import` / `require` 语句，按以下规则分类：
+
+| 类别 | 判定规则 | 处理方式 |
+|------|---------|---------|
+| **相对路径** | `import './xxx'` / `import '../xxx'` | 忽略（demo 内部引用） |
+| **Node 内置** | `fs` / `path` / `util` / `os` 等 | 忽略 |
+| **React 核心** | `react` / `react-native` | 忽略（example 模板已内置） |
+| **目标库本身** | `module === alias` 或 `packageName` | 标注，由 `rn-lib-add-example` 改为 `file:../<tgz>` |
+| **RNOH 框架** | `@react-native-oh/*` / `@rnoh/*` / `react-native-harmony` | 列入 example `dependencies`，版本对齐 RNOH |
+| **RN 通用包** | `react-native-*` / `@react-native-*` / `@react-native-community/*` | 列入 example `dependencies` |
+| **其他第三方** | 不属于以上类别 | 列入「待人工确认」清单 |
+
+### 2.2 依赖版本对齐
+
+迁移报告产出依赖增量时，**不自动指定版本号**，由 `rn-lib-add-example` 按以下规则对齐：
+
+| 依赖类型 | 版本来源 |
+|----------|---------|
+| 目标库本身 | `libPath/package.json` 的 `version`，引用方式 `file:../<name>-<version>.tgz` |
+| RNOH 框架 | example 模板默认版本，或用户指定的 RNOH 版本 |
+| 通用 RN 包 | example 模板已有版本优先；模板无则取 rnt 工程的版本 |
+| 其他第三方 | 询问用户，或取 rnt 工程版本 |
+
+### 2.3 依赖写入职责
+
+> ⚠️ 本 SKILL **不**自动写入 `example/package.json`。只产出依赖增量清单，由下游 `rn-lib-add-example` 统一写入。
+
+理由：
+1. 版本对齐需要 example 模板上下文，本 SKILL 不感知模板版本
+2. 避免多次写入冲突（`rn-lib-add-example` 也会写依赖）
+3. 保持职责单一：本 SKILL 只做「分析」，不做「写入」
+
+### 2.4 外部依赖存在性检查（必执行）
+
+`analyze-demo-deps.cjs` 输出的 `externalDeps` 中每个包，**必须逐一检查**是否已在 `example/package.json` 中声明。缺失依赖会导致运行时崩溃。
+
+**典型缺失场景**：
+
+| 缺失依赖 | 原因 | 影响 | 补齐方式 |
+|---------|------|------|---------|
+| `@rnoh/testerino` | rnt demo 使用 testerino 测试框架，example 未声明 | 所有 `Tester`/`TestCase`/`TestSuite` 组件无法渲染 | 从 rnt 工程复制 `rnoh-testerino-<version>.tgz` 到 example 目录，以 `file:` 方式写入 dependencies |
+| `@react-native-ohos/<pkg>` | demo 引用了其他鸿蒙化库但 example 未安装 | 引用该库的组件崩溃 | 从 rnt 工程或 npm registry 获取版本，写入 dependencies |
+| 其他第三方包 | demo 引用了 example 未安装的包 | 引用该包的组件崩溃 | 询问用户或从 rnt 工程获取版本 |
+
+**检查方法**：
+
+```bash
+# 读取 example/package.json 已声明的依赖
+node -e "const p=require('<libPath>/example/package.json'); const all={...p.dependencies,...p.devDependencies}; console.log(JSON.stringify(Object.keys(all)))"
+
+# 对比 analyze-demo-deps.cjs 的 externalDeps 输出，找出未声明的包
+```
+
+### 2.5 从 rnt 工程提取缺失依赖版本
+
+当发现缺失依赖时，从 rnt 工程的 `package.json` 中提取版本与引用方式：
+
+```bash
+# 在 rnt 子工程的 package.json 中搜索缺失依赖
+grep -r "<missingDep>" <rntPath>/*/package.json
+```
+
+常见模式：
+- `@rnoh/testerino` → `"file:./rnoh_package/testerino/rnoh-testerino-0.0.12.tgz"` → 复制 tgz 到 example，以 `file:./rnoh-testerino-0.0.12.tgz` 引用
+- `@react-native-ohos/*` → `"http://<registry>/<pkg>/-/<pkg>-<version>.tgz"` 或 `"file:../<xxx>.har"` → 按相同方式写入
+
+---
+
+## 3. 迁移流程细节
+
+### 3.1 迁移前检查
+
+| 检查项 | 通过条件 | 失败处理 |
+|--------|---------|---------|
+| `demoPath` 存在 | 目录可访问 | 报错终止，提示用户重新提供 |
+| `targetExampleSrc` 存在 | 目录可访问 | 引导用户先执行 `rn-lib-add-example` 创建模板 |
+| `targetExampleSrc` 可写 | 有写权限 | 报错并终止 |
+| 目标已有同名文件 | 列出冲突文件 | **保留目标版本**，demo 版本不写入（`--ignore-existing`），报告中标注冲突项供人工确认 |
+
+### 3.2 --clean 选项
+
+`--clean` 启用时，迁移前清空 `targetExampleSrc`：
+
+```bash
+# 脚本行为
+rm -rf <targetExampleSrc>/*
+# 然后复制 demo 内容
+```
+
+> ⚠️ `--clean` **必须**由用户明确同意。Agent 不得自动启用。**默认模式为增量添加（`--ignore-existing`），不覆盖已有文件**。建议保留通用组件 `Navigation.tsx`（若 demo 仍使用）——脚本默认不清除 `components/Navigation.tsx`，可通过 `--clean-all` 强制全清。
+
+### 3.3 默认排除项
+
+`port-demo.sh` 默认排除以下目录/文件：
+
+| 排除项 | 原因 |
+|--------|------|
+| `node_modules/` | demo 自身的依赖，example 会重新 install |
+| `build/` | 构建产物 |
+| `__tests__/` | demo 自带的测试，example 有自己的 testerino 注册 |
+| `.cxx/` / `oh_modules/` | 鸿蒙构建产物 |
+| `.DS_Store` | macOS 垃圾文件 |
+| `*.log` | 日志文件 |
+
+可通过 `--exclude` 参数追加自定义排除项。
+
+### 3.4 rsync 复制
+
+使用 `rsync -a --ignore-existing` 保留文件元数据（mtime、权限），**仅添加目标不存在的文件，不覆盖已有文件**：
+
+```bash
+rsync -a --ignore-existing \
+  --exclude 'node_modules/' \
+  --exclude 'build/' \
+  --exclude '__tests__/' \
+  --exclude '.cxx/' \
+  --exclude 'oh_modules/' \
+  --exclude '.DS_Store' \
+  --exclude '*.log' \
+  "<demoPath>/" "<targetExampleSrc>/"
+```
+
+> 注意末尾 `/`：`<demoPath>/` 表示复制目录内容，`<demoPath>`（无 `/`）会复制目录本身。
+>
+> `--ignore-existing` 确保目标已有文件保留不动，冲突文件在脚本输出中列出供 Agent 写入报告。
+
+---
+
+## 4. 路径修正检查清单
+
+迁移完成后，**逐文件**检查以下内容（使用 `Edit` 工具）。
+
+> ⚠️ **仅修正本次新增的文件**：如果某文件是目标已有的（冲突保留项），**不修改它**，仅在报告中标注需人工处理。
+
+### 4.1 相对路径修正
+
+| 文件 | 检查内容 | 修正规则 |
+|------|---------|---------|
+| `tests/index.tsx` | 引用 demo 子目录的路径 | `./xxx` → `../xxx`（tests/ 在 src/tests/ 下，引用上级） |
+| `tests/*.tsx` | 同上 | 同上 |
+| 任何子目录文件 | 引用其他子目录 | 确保相对路径从 `example/src/` 起算 |
+
+**示例**：
+
+```tsx
+// ❌ 迁移前（rnt demo 内 tests/index.tsx）
+import { CameraDemo } from './camera/CameraDemo';
+import { Navigation } from './components/Navigation';
+
+// ✅ 迁移后（example/src/tests/index.tsx）
+import { CameraDemo } from '../camera/CameraDemo';
+import { Navigation } from '../components/Navigation';
+```
+
+### 4.2 入口文件对齐与接入
+
+| 文件 | 检查内容 |
+|------|---------|
+| `App.tsx`（可在嵌套子目录如 `testCase/App.tsx`） | `displayName` / `title` 与 demo 名称一致 |
+| `index.tsx`（根级） | 是否已引用 demo 入口；若未引用，re-export demo 入口 |
+| `Test/index.tsx` 或 `tests/index.tsx` | testerino 注册的组件名与 `App.displayName` 一致 |
+
+**入口接入检查**：
+
+```bash
+# 确认 index.tsx 是否引用了 demo 入口（testCase/App, demo/App, ./App 等）
+grep -l "testCase/App\|demo/App\|./App" example/src/index.tsx
+```
+
+若未引用，**仅在 `index.tsx` 是本次新增文件时**才更新为 re-export；若 `index.tsx` 是目标已有文件，不覆盖，在报告中标注「入口未接入，需人工处理」：
+
+```tsx
+// index.tsx — 更新为 re-export demo 入口（仅当 index.tsx 是本次新增文件时）
+export {
+  default,
+  displayName,
+  framework,
+  category,
+  title,
+  documentationURL,
+  description,
+  examples,
+} from './testCase/App';
+```
+
+### 4.3 Navigation.tsx 硬编码标题修正
+
+`Navigation.tsx`（或类似共享组件）从 rnt 复制后可能包含**其他库的硬编码标题**。
+
+**检测**：`analyze-demo-deps.cjs` 的 `hardcodedTitles` 字段列出所有匹配 `RN <Xxx> (Capi )?Tester` 的文本。
+
+**修正**（**仅针对本次新增的文件**，目标已有文件不修改，在报告中标注）：
+
+```tsx
+// ❌ 迁移前（遗留的 Svg 库标题）
+<Text>RN Svg Capi Tester</Text>
+
+// ✅ 迁移后（替换为目标库 alias，如 react-native-pdf → Pdf）
+<Text>RN Pdf Tester</Text>
+```
+
+### 4.4 目标库引用对齐
+
+确认 demo 中目标库的引用方式与 example 配置一致：
+
+| demo 引用方式 | example 需配置 |
+|--------------|---------------|
+| `import { X } from '<alias>'` | `metro.config.js` 的 `extraNodeModules['<alias>']` 指向 `node_modules/<ohPackageName>` |
+| `import { X } from '<packageName>'` | `tsconfig.json` 的 `paths['<packageName>']` 指向 `./node_modules/<ohPackageName>` |
+| `import { X } from '<packageName>/src/internal'` | 列入「待人工确认」，不自动改写 |
+
+> 引用方式对齐的最终写入由 `rn-lib-add-example` 完成。本 SKILL 只检查并在报告中标注不一致项。
+
+---
+
+## 5. 迁移后自检
+
+迁移完成后，执行以下自检（不需运行 `npm install`，仅静态检查）：
+
+| 检查项 | 方法 | 通过标准 |
+|--------|------|---------|
+| 文件完整性 | 对比 `demoPath` 与 `targetExampleSrc` 文件清单 | **本次新增文件**全部迁移到位（冲突文件保留目标版本，不计入缺失） |
+| 入口文件存在 | `find example/src -name "App.tsx" -o -name "index.tsx"` | 两个文件都存在（可嵌套） |
+| index.tsx 接入 | `grep "testCase/App\|demo/App\|./App" example/src/index.tsx` | index.tsx 引用 demo 入口（若 index.tsx 为已有文件未接入，标注为待人工确认） |
+| 相对路径有效 | grep `from '\./` 在子目录下 | 无错误的同级引用（仅检查本次新增文件） |
+| 目标库引用一致 | grep `import.*from.*'<alias>\|<packageName>'` | 引用方式与 example 配置一致（仅检查本次新增文件） |
+| 无硬编码标题 | grep `RN.*Tester` 在 Navigation.tsx 等 | 无其他库的遗留标题（仅本次新增文件已修正；已有文件标注待人工处理） |
+| 无残留排除项 | `ls example/src/node_modules` 等 | 不存在（应被排除） |
+| **外部依赖已声明** | 对比 `externalDeps` 与 `example/package.json` | 所有外部依赖已在 dependencies/devDependencies 中声明（Phase 4.1） |
+| **无孤立文件** | 对比迁移文件列表与 index.tsx demos 数组 | 所有有 export 的组件都被入口直接/间接引用（Phase 6.6） |
+| **菜单可滚动** | 检查 demos 条目数与菜单容器类型 | 条目 > 5 时菜单容器为 ScrollView（Phase 6.7） |
+| **原有 App.tsx 可访问** | 检查 index.tsx 是否包含 OriginalApp 菜单项 | 原有 demo 入口未丢失（Phase 6.8） |
+| **入口链路完整** | index.js → src/index.tsx → demos → 各组件 → ./demo/ | 全链路可导入（Phase 6.9） |
+| **build-profile 无越界** | 检查 modules[].srcPath 是否以 ../ 开头 | 所有路径在工程内（Phase 5.1） |
+| **.har 路径有效** | 逐一 ls 验证 oh-package.json5 中的 file: 引用 | 所有 .har 文件存在（Phase 5.2） |
+
+> 自检脚本由 Agent 串联执行，结果写入迁移报告。
+
+---
+
+## 6. 构建前置检查
+
+迁移完成后、执行编译前，必须确认以下构建前置条件已满足：
+
+### 6.1 build-profile.json5 模块路径越界
+
+`example/harmony/build-profile.json5` 与 `build-profile.template.json5` 中的 `modules[].srcPath` **不可**以 `../` 开头（越出工程根目录）。
+
+**典型问题**：库的源码模块在 `libPath/harmony/safe_area/`，build-profile 引用为 `../../harmony/safe_area` → hvigor 报错。
+
+**修正**：
+1. `cp -R <libPath>/harmony/<module> example/harmony/<module>`
+2. 修改 `srcPath` 为 `./<module>`
+3. 修正被复制模块的 `oh-package.json5` 中 `.har` 路径
+
+> 符号链接不可行：hvigor 不跟随 symlink。
+
+### 6.2 .har 文件路径验证
+
+被复制模块的 `oh-package.json5` 中 `file:` 引用的 `.har` 文件路径可能因目录层级变化而失效。
+
+**典型问题**：原始路径 `file:../../node_modules/@react-native-oh/react-native-harmony/harmony/react_native_openharmony.har`（多一层 `harmony/`），复制后应为 `file:../../node_modules/@react-native-oh/react-native-harmony/react_native_openharmony.har`。
+
+**验证方法**：逐一 `ls -la` 检查每个 `file:` 引用的文件是否存在。
+
+### 6.3 编译验证步骤
+
+确认前置检查通过后，按以下顺序执行编译：
+
+```bash
+# 1. 安装 JS 依赖
+cd example && npm i --legacy-peer-deps
+
+# 2. 安装鸿蒙原生依赖
+cd harmony && ohpm install
+
+# 3. 生成 JS bundle
+cd .. && npm run dev
+
+# 4. 编译鸿蒙工程
+cd harmony && devecocli build
+```
+
+> `npm i` 只装 JS 依赖，`ohpm install` 才装原生 .har 依赖，两者都不可省略。
+
+---
+
+## 7. 与 rn-lib-add-example 的衔接
+
+本 SKILL 完成后，迁移报告中的以下内容会被 `rn-lib-add-example` 消费：
+
+| 报告章节 | 下游用途 |
+|----------|---------|
+| 依赖增量清单 | 写入 `example/package.json` 的 `dependencies` |
+| 目标库引用方式 | 配置 `metro.config.js` 的 `extraNodeModules` |
+| 入口文件 displayName | 配置 `App.tsx` 与 `Test/index.tsx` 注册 |
+| 版本一致性检测结果 | 决定是否需要更新 example/package.json 的 react-native / react-native-harmony 版本 |
+| 待人工确认项 | 由用户或 Agent 在壳层适配阶段决策 |
+| 原生代码标注 | 决定是否需要 CMake / RNPackagesFactory 适配 |
+
+> 迁移报告是本 SKILL 的**唯一交付物**，下游 SKILL 通过读取报告获取所需信息。