@ohos-cpf/3rdloop 0.0.2 → 0.0.4

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

@@ -1,722 +1,722 @@
----
-name: rnoh-lib-rnt-search
-description: >-
-  从 rnt（React Native Tester）工程中定位 RN 鸿蒙三方库的 demo 并增量迁移到指定 RN 目标工程的 example/src 下。读取目标库 package.json 元数据生成候选名，扫描 {rnt-root}/*/rn-tester/examples/ 匹配 demo 目录，分析 demo 结构与外部依赖，复制 demo 文件（增量添加，不覆盖目标已有文件）并修正 import 路径与依赖。当用户需要从 rnt 工程查找并迁移 demo 到 RN 鸿蒙三方库 example 工程、单独执行 demo 查找/迁移步骤、向 example/src 增量添加 demo、分析 rnt demo 依赖时使用。适用于 rnt demo 定位、demo 迁移、demo 依赖分析、example 内容增量添加等场景。
-license: Apache-2.0
-compatibility: 需要 bash、node、npm；目标 RN 工程需已有 example/ 目录（缺失时引导使用 rn-lib-add-example 创建）
-allowed-tools: Bash Read Grep Glob Edit Write
-metadata:
-  version: "1.0.0"
-  category: rn-demo-porting
-  language: JavaScript/TypeScript
-  consumed-by: rnohLibAddExampleSkill
----
-
-# RN 鸿蒙三方库 rnt Demo 查找与迁移
-
-从 rnt（React Native Tester）工程中定位目标 RN 三方库的 demo 目录，迁移到指定 RN 目标工程的 `example/src/`，并完成 import 路径与依赖的修正。
-
-> ⚠️ **核心原则**：
-> 1. 通过 RNOH 框架版本（git 分支或元数据）自动对齐库与 rnt，版本一致时自动选择 demo 并直接迁移，无需人工确认。
-> 2. 本 SKILL 只负责「查找 + 迁移 demo 内容」，不创建/重建 example 工程模板、不做 Harmony 壳层（RNPackagesFactory/CMakeLists/build-profile 等）适配——这些由 `rn-lib-add-example` 完成。
-> 3. **增量添加，不覆盖**：迁移时目标 `example/src/` 已有的文件**保留不动**，仅添加 demo 中目标不存在的文件。冲突文件保留目标版本，在报告中列出供人工确认。
-> 4. 迁移完成后必须输出迁移报告，列出 demo 来源、文件清单、依赖增量、冲突文件（保留目标版本）、待人工确认项。
-
----
-
-## 路径约定
-
-`{SKILL_DIR}` = 本技能根目录（本 SKILL.md 所在目录）。命令均在 `{SKILL_DIR}` 下执行，使用 `scripts/...`、`references/...` 相对路径。
-
-## 何时使用
-
-- 用户要求从 rnt 工程查找并迁移某个 RN 三方库的 demo。
-- 用户要求向已有 RN 工程的 `example/src/` **增量添加** demo 内容（不覆盖已有文件）。
-- 用户在 `rn-lib-add-example` 流程中需要单独执行 Step 2（demo 查找与迁移）。
-- 用户想分析 rnt demo 的外部依赖，决定 example 需要补哪些包。
-- 用户拿到一个 rnt 工程根路径，想自动定位某个库的 demo 子目录。
-
-## 最小必要输入
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `libPath` | string | ✅ | 目标 RN 三方库根目录（含 `package.json`） |
-| `rntPath` | string | ✅* | rnt 工程根目录（含多个子工程，每个有 `rn-tester/examples/`） |
-| `demoPath` | string | ✅* | demo 目录绝对路径（用户已明确时直接传入，跳过扫描） |
-| `targetExampleSrc` | string | ❌ | 目标 RN 工程 `example/src/` 路径；缺省时按 `libPath/example/src` 推断 |
-| `cleanTarget` | boolean | ❌ | 迁移前是否清空目标 `example/src/`；默认 `false`（**增量添加，不覆盖已有文件**） |
-| `rnohVersion` | string | ❌ | 目标 RNOH 框架版本号（如 "0.82"）。未提供时自动从 rnt 分支检测。用于版本对齐与分支切换。 |
-
-> `rntPath` 与 `demoPath` 二选一：用户已明确 demo 路径时传 `demoPath` 跳过扫描；否则必须传 `rntPath` 由脚本扫描定位。
-
-**派生变量**：
-- `skillDir`：本 SKILL 所在目录
-- `libMeta`：`read-lib-meta.cjs` 输出的库元数据 JSON
-- `libVersion`：库的 RNOH 版本（`detect-rnoh-version.cjs` 输出）
-- `rntVersion`：rnt 的 RNOH 版本（`detect-rnoh-version.cjs` 输出）
-- `demoFiles`：demo 目录下待迁移的源文件清单
-- `demoDeps`：`analyze-demo-deps.cjs` 输出的外部依赖清单
-
-## 输入依赖
-
-- **前置SKILL**：无（可独立调用）。若目标 RN 工程 `example/` 不存在，引导用户先执行 `rn-lib-add-example` 创建模板。
-- **输入文件**：目标库 `package.json`、rnt 工程目录树、demo 源码目录。
-- **输出文件**：迁移后的 `example/src/` 文件 + 迁移报告 Markdown。
-
----
-
-## 工作流程概览
-
-```
-Phase 1: 读取库元数据（read-lib-meta.cjs）
-    ↓
-Phase 2: 版本检测与对齐（detect-rnoh-version.cjs，自动切换分支）
-    ↓
-Phase 3: 扫描 rnt 工程定位 demo（find-rnt-demo.sh，版本一致时自动选择）
-    ↓
-Phase 4: 分析 demo 结构与外部依赖（analyze-demo-deps.cjs）
-  4.1 外部依赖存在性检查（example/package.json 是否已声明）
-  4.2 从 rnt 工程提取缺失依赖的版本信息
-    ↓
-Phase 5: 迁移 demo 到目标 example/src（port-demo.sh）
-  5.1 build-profile.json5 模块路径越界检查
-  5.2 .har 文件路径验证
-    ↓
-Phase 6: 修正 import 路径与 displayName + 入口接入
-  6.1 相对路径修正
-  6.2 入口文件对齐
-  6.3 目标库引用对齐
-  6.4 入口文件接入
-  6.5 Navigation.tsx 硬编码标题修正
-  6.6 孤立文件检测与接入
-  6.7 菜单容器 ScrollView 适配
-  6.8 保留原有 App.tsx 入口
-  6.9 入口链路端到端验证
-    ↓
-Phase 7: 生成迁移报告并交付
-```
-
-> rnt 工程结构与 demo 目录约定详见 [references/RNT_PROJECT_STRUCTURE.md](references/RNT_PROJECT_STRUCTURE.md)。
-
----
-
-## Phase 1：读取库元数据
-
-读取目标库 `package.json`，提取用于 demo 搜索的候选名与鸿蒙化字段。
-
-```bash
-node scripts/read-lib-meta.cjs <libPath>
-```
-
-**关注字段**：
-
-| 字段 | 用途 |
-|------|------|
-| `packageName` | npm 包名，写入 example `dependencies` |
-| `alias` | `harmony.alias`，候选搜索名之一 |
-| `scoped` | 去掉 scope 的短名，候选搜索名之一 |
-| `dirBase` | 目录名，候选搜索名之一 |
-| `searchNames` | 候选搜索名数组（去重） |
-| `autolinkingResolved` | 鸿蒙化模块信息（供下游 `rn-lib-add-example` 壳层适配使用，本 SKILL 不直接处理） |
-
-> 脚本详情与字段说明参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md) 的「库元数据字段」章节。
-
----
-
-## Phase 2：版本检测与对齐
-
-检测目标库与 rnt 工程的 RNOH 框架版本，当版本不一致时自动切换分支对齐。版本一致后直接进入 Phase 3，**无需用户确认**。
-
-### 2.1 版本检测
-
-```bash
-# 检测库版本
-node scripts/detect-rnoh-version.cjs <libPath>
-
-# 检测 rnt 版本
-node scripts/detect-rnoh-version.cjs <rntPath>
-```
-
-**版本检测优先级**：
-
-| 优先级 | 来源 | 示例 |
-|--------|------|------|
-| 1 | Git 分支名 | `br_rnoh0.82` → `0.82` |
-| 2 | example/package.json | `react-native-harmony: npm:@react-native-oh/react-native-harmony@0.77.72` → `0.77` |
-| 3 | harmony subdirs oh-package.json5 | `@react-native-oh/*` 依赖版本 |
-| 4 | package.json peerDependencies | `react-native: *` |
-
-> 非 Git 仓库时自动降级到 package.json / oh-package.json5 检测。
-
-### 2.2 版本对齐
-
-| 场景 | 处理 |
-|------|------|
-| 库与 rnt 版本一致 | ✅ 直接进入 Phase 3 |
-| 库版本 ≠ rnt 版本，库有对应分支 | 自动 `git checkout` 切换库分支 |
-| 库版本 ≠ rnt 版本，rnt 有对应分支 | 自动 `git checkout` 切换 rnt 分支 |
-| 两者都无法切换到一致版本 | 报错终止，列出可用分支供用户参考 |
-
-**分支切换前必须检查工作区是否干净**：
-
-```bash
-# 检查是否有未提交的修改
-git -C <path> status --short
-```
-
-| 工作区状态 | 处理 |
-|-----------|------|
-| 干净（无输出） | 直接 `git checkout` |
-| 有未提交修改 | `git stash` 暂存 → `git checkout` → 迁移完成后 `git stash pop` 恢复 |
-
-### 2.3 example/package.json 版本一致性检测
-
-版本对齐后，检查 `example/package.json` 中的 `react-native` / `react-native-harmony` 版本是否与目标 RNOH 版本匹配：
-
-```bash
-# 读取 example/package.json 中的 react-native 版本
-node -e "const p=require('./example/package.json'); console.log(p.dependencies['react-native'], p.dependencies['react-native-harmony'])"
-```
-
-| 匹配状态 | 处理 |
-|---------|------|
-| ✅ 版本匹配 | 直接进入 Phase 3 |
-| ❌ 版本不匹配 | 在报告中标注「example/package.json react-native 版本与目标 RNOH 版本不一致」，由 `rn-lib-add-example` 更新 |
-
-> 版本不一致不阻塞迁移，但在报告中标记为高优先级待确认项。
-
-**分支切换示例**：
-
-```bash
-# 列出库的可用分支及版本
-node scripts/detect-rnoh-version.cjs <libPath> --list-branches
-
-# 切换到目标版本分支
-git -C <libPath> stash  # 如有未提交修改
-git -C <libPath> checkout br_rnoh0.82
-git -C <libPath> stash pop  # 恢复暂存（如有）
-```
-
-> ⚠️ 版本对齐自动执行，不暂停等待用户确认。Agent 检测到版本不一致时直接切换分支使其对齐。
-
----
-
-## Phase 3：扫描 rnt 工程定位 demo
-
-版本对齐完成后，扫描 rnt 工程定位目标库的 demo 目录。当版本一致且命中唯一 demo 时**自动选择**，无需用户确认。
-
-若用户已提供 `demoPath`，跳过本步直接进入 Phase 4。
-
-```bash
-bash scripts/find-rnt-demo.sh \
-  --lib-path <libPath> \
-  --rnt-path <rntPath>
-```
-
-**扫描规则**（详见 [references/RNT_PROJECT_STRUCTURE.md](references/RNT_PROJECT_STRUCTURE.md)）：
-
-1. 读取 `read-lib-meta.cjs` 的 `searchNames` 作为候选名
-2. 遍历 `{rntPath}/*/rn-tester/examples/{候选名}/`
-3. 命中后做大小写不敏感兜底匹配
-4. 输出每个 demo 路径一行；退出码：`0` = 唯一命中、`1` = 未找到、`2` = 多个命中
-
-**自动选择规则**：
-
-| 命中数 | 处理 |
-|--------|------|
-| 0 | 报错终止，提示用户手动提供 `--demo-path` 或检查 rnt 工程路径 |
-| 1 | ✅ 自动选择，直接进入 Phase 4 |
-| 多个 | 自动选择第一个命中项，报告中标注全部命中路径；用户可通过 `--demo-path` 指定其他 |
-
-> 版本一致 + 唯一命中 = 自动选择，不暂停等待用户确认。
-
----
-
-## Phase 4：分析 demo 结构与外部依赖
-
-扫描 demo 目录的源文件（`.ts`/`.tsx`/`.js`/`.jsx`），提取：
-
-1. **文件清单**：待迁移文件树（用于报告与迁移校验）
-2. **外部依赖**：从 `import ... from 'pkg'` 与 `require('pkg')` 中提取所有非相对路径的包名
-3. **目标库引用方式**：demo 中如何引用目标库（alias / 包名 / 相对路径）
-4. **入口文件**：`App.tsx` / `index.tsx` 位置与 `displayName` / `title` 取值
-
-```bash
-node scripts/analyze-demo-deps.cjs <demoPath> [--lib-name <packageName>] [--alias <harmony.alias>]
-```
-
-输出 JSON：
-
-```json
-{
-  "files": ["App.tsx", "index.tsx", "tests/index.tsx", "camera/CameraDemo.tsx"],
-  "externalDeps": ["@react-native-community/cli", "react-native-svg"],
-  "libReferences": [
-    { "kind": "named", "module": "react-native-camera-kit", "names": ["Camera", "CameraType"] }
-  ],
-  "entryFiles": { "app": "App.tsx", "index": "index.tsx", "displayName": "CameraKitDemo" }
-}
-```
-
-**依赖分类**：
-
-| 类别 | 判定 | 处理 |
-|------|------|------|
-| 目标库本身 | `module === alias` 或 `packageName` | 迁移后改为 `file:../<tgz>` 引用（由 `rn-lib-add-example` 完成） |
-| RNOH 框架 | `@react-native-oh/*` / `@rnoh/*` | 对齐目标 RNOH 版本，写入 example `dependencies` |
-| 通用 RN 依赖 | `react-native-*` / `@react-native-*` | 写入 example `dependencies`，版本与 example 模板对齐 |
-| 业务无关依赖 | 与目标库 demo 无关 | 列入「待人工确认」清单，不自动写入 |
-
-### 4.1 外部依赖存在性检查（必须执行）
-
-`analyze-demo-deps.cjs` 输出的 `externalDeps` 中每个包，**必须逐一检查**是否已在 `example/package.json` 的 `dependencies` 或 `devDependencies` 中声明：
-
-```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)))"
-```
-
-| 检查结果 | 处理 |
-|---------|------|
-| 依赖已在 example/package.json 中声明 | ✅ 无需处理 |
-| 依赖未声明，属于 RNOH/RN 通用包 | ⚠️ **高优先级**：在报告中标注「缺少依赖」，并从 rnt 工程的 `package.json` 中查找该包的版本与引用方式（如 `file:./rnoh_package/xxx.tgz`），在报告依赖增量清单中给出建议的写入值 |
-| 依赖未声明，属于业务无关包 | 列入「待人工确认」清单 |
-
-> ⚠️ **缺失依赖会导致运行时崩溃**。例如 demo 引用 `@rnoh/testerino` 但 example/package.json 未声明，所有使用 `Tester`/`TestCase`/`TestSuite` 的组件均无法渲染。此检查是**必执行项**，不可跳过。
-
-### 4.2 从 rnt 工程提取缺失依赖的版本信息
-
-当发现 example 缺少的依赖时，从 rnt 工程的 `package.json` 中提取该包的版本与引用方式：
-
-```bash
-# 在 rnt 子工程的 package.json 中搜索缺失依赖
-grep -r "<missingDep>" <rntPath>/*/package.json
-```
-
-常见情况：
-- `@rnoh/testerino` → rnt 工程中以 `file:./rnoh_package/testerino/rnoh-testerino-<version>.tgz` 形式引用，需将 tgz 复制到 example 目录并同样以 `file:` 方式引用
-- 其他 `@rnoh/*` 或 `@react-native-ohos/*` 包 → 从 rnt 工程或 npm registry 获取版本
-
-> 详细依赖处理规则参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md) 的「依赖分析与写入」章节。
-
----
-
-## Phase 5：迁移 demo 到目标 example/src
-
-```bash
-bash scripts/port-demo.sh \
-  --demo-path <demoPath> \
-  --target <targetExampleSrc> \
-  [--clean] \
-  [--exclude 'node_modules,build,__tests__']
-```
-
-**脚本行为**：
-
-1. 校验 `demoPath` 与 `targetExampleSrc` 存在
-2. `--clean` 时清空目标 `example/src/`（**默认不清空**，避免误删用户已有内容；执行前必须由用户确认）
-3. 默认排除 `node_modules/`、`build/`、`__tests__/`、`.cxx/`、`oh_modules/`
-4. 使用 `rsync -a --ignore-existing` 保留文件元数据，**仅添加目标不存在的文件**，已有文件保留不动
-5. 冲突文件（demo 与目标同名）保留目标版本，在输出中列出供 Agent 写入报告
-6. 输出迁移文件清单（相对路径）+ 冲突文件清单
-
-**迁移后目录约定**（典型 demo 结构）：
-
-```
-example/src/
-├── App.tsx              # demo 入口（含 displayName）
-├── index.tsx            # 导出 demo 给 testerino 注册
-├── tests/
-│   └── index.tsx        # testerino 测试用例注册（修正相对路径）
-├── camera/              # demo 功能子目录
-├── scanCode/
-└── components/          # demo 复用组件
-```
-
-> 迁移细节与边界情况（已有文件冲突处理、保留通用组件 `Navigation.tsx` 等）参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md)。**默认增量添加，冲突文件保留目标版本。**
-
-### 5.1 build-profile.json5 模块路径越界检查（必须执行）
-
-迁移后检查 `example/harmony/build-profile.json5` 与 `example/harmony/build-profile.template.json5` 中的 `modules[].srcPath`，确保所有模块路径**不越出** `example/harmony/` 工程根目录：
-
-```bash
-# 读取 build-profile.json5 中的模块路径
-node -e "const fs=require('fs'); const c=fs.readFileSync('example/harmony/build-profile.json5','utf8'); const m=c.match(/srcPath:\s*'([^']+)'/g); console.log(m)"
-```
-
-| 路径形式 | 判定 | 处理 |
-|---------|------|------|
-| `./entry`、`./safe_area` 等 `./` 开头 | ✅ 工程内路径 | 无需处理 |
-| `../../harmony/xxx` 等 `../` 开头 | ❌ **越界**，hvigor 报错 `Path escapes project root` | 见下方修正 |
-
-**越界路径修正步骤**：
-
-1. 将越界引用的模块目录**物理复制**到 `example/harmony/` 下（如 `cp -R ../../harmony/safe_area ./safe_area`）
-2. 修改 `build-profile.json5` 与 `build-profile.template.json5` 中的 `srcPath` 为工程内相对路径（如 `'../../harmony/safe_area'` → `'./safe_area'`）
-3. 同步修正被复制模块自身的 `oh-package.json5` 中 `file:` 引用路径（见 5.2）
-
-> ⚠️ **符号链接不可行**：hvigor 不跟随 symlink，必须物理复制目录。
-
-### 5.2 .har 文件路径验证（必须执行）
-
-被复制的模块（或原有模块）的 `oh-package.json5` 中 `file:` 引用的 `.har` 文件，**必须逐一验证存在性**：
-
-```bash
-# 读取模块 oh-package.json5 中的 file: 引用
-grep -o "file:[^,\"]*" example/harmony/<module>/oh-package.json5
-
-# 逐一验证文件存在
-ls -la example/harmony/<module>/../../node_modules/@react-native-oh/<pkg>/<xxx>.har
-```
-
-| 检查结果 | 处理 |
-|---------|------|
-| `.har` 文件存在于 `file:` 指定路径 | ✅ 无需处理 |
-| 路径多/少一层子目录（如 `harmony/react_native_openharmony.har` vs `react_native_openharmony.har`） | ❌ 修正 `oh-package.json5` 中的路径，使其指向实际 `.har` 文件位置 |
-| `.har` 文件不存在 | ❌ 报告标注，由 `rn-lib-add-example` 处理 |
-
-> ⚠️ `.har` 路径错误会导致 `ohpm install` 静默跳过该依赖，编译时报 `Cannot find module`。
-
----
-
-## Phase 6：修正 import 路径与 displayName
-
-迁移后**必须**检查并修正以下内容（使用 `Edit` 工具逐文件处理）。
-
-> ⚠️ **仅修正本次新增的文件**：如果某文件是目标已有的（冲突保留项），**不修改它**，仅在报告中标注需人工处理。
-
-### 6.1 相对路径修正
-
-`tests/index.tsx` 等子目录文件中引用 demo 内容的相对路径可能失效。常见修正：
-
-| 错误写法 | 正确写法 | 原因 |
-|----------|----------|------|
-| `./camera/CameraDemo` | `../camera/CameraDemo` | `tests/` 下的文件引用上级目录 |
-| `./components/Nav` | `../components/Nav` | 同上 |
-
-### 6.2 入口文件对齐
-
-- `example/src/App.tsx`：`displayName` / `title` 与 demo 名称一致
-- `example/src/index.tsx`：`export` 路径与迁入的 demo 目录结构一致
-
-### 6.3 目标库引用对齐
-
-确认 demo 中目标库的引用方式与 example 的 `metro.config.js` 别名一致：
-
-- demo 用 `import { X } from '<alias>'` → example `metro.config.js` 的 `extraNodeModules['<alias>']` 指向 `node_modules/<ohPackageName>`
-- demo 用 `import { X } from '<packageName>'` → 同步更新 `tsconfig.json` 的 `paths`
-
-> 完整路径修正检查清单参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md) 的「路径修正」章节。
-
-### 6.4 入口文件接入
-
-迁移后检查 demo 入口文件（如 `testCase/App.tsx`）是否已被 `example/src/index.tsx` 引用。若未接入，**仅在 `index.tsx` 是本次新增文件时**才更新它；若 `index.tsx` 是目标已有文件，不覆盖，在报告中标注需人工接入。
-
-| 场景 | 处理 |
-|------|------|
-| `index.tsx` 已引用 demo 入口 | ✅ 无需处理 |
-| `index.tsx` 是本次新增文件，未引用 demo 入口 | 更新 `index.tsx`，re-export demo 入口的默认导出和元数据 |
-| `index.tsx` 是目标已有文件，未引用 demo 入口 | ❌ 不覆盖；报告中标注「入口未接入，需人工在已有 index.tsx 中添加 re-export」 |
-| demo 入口即为 `index.tsx` | ✅ 无需处理 |
-
-**示例**（demo 入口在 `testCase/App.tsx`，`index.tsx` 原有独立内容）：
-
-```tsx
-// index.tsx — 更新为 re-export demo 入口
-export {
-  default,
-  displayName,
-  framework,
-  category,
-  title,
-  documentationURL,
-  description,
-  examples,
-} from './testCase/App';
-```
-
-**检查方法**：
-
-```bash
-# 确认 index.tsx 是否引用了 demo 入口
-grep -l "testCase/App\|demo/App\|./App" example/src/index.tsx
-```
-
-> 入口接入是迁移完成的必要步骤——未接入的 demo 入口不会在运行时生效。
-
-### 6.5 Navigation.tsx 硬编码标题修正
-
-rnt demo 中的 `Navigation.tsx`（或类似共享组件）常包含**其他库的硬编码标题**（如 `"RN Svg Capi Tester"`），是从 rnt 共享代码中遗留的。迁移后**必须**检测并修正。
-
-**检测**：`analyze-demo-deps.cjs` 的 `hardcodedTitles` 字段列出所有匹配 `RN <Xxx> (Capi )?Tester` 模式的硬编码文本。
-
-**修正规则**：
-
-| 字段 | 值 |
-|------|-----|
-| 匹配模式 | `RN\s+\w+(?:\s+\w+)*\s+(?:Capi\s+)?Tester` |
-| 替换值 | `RN <Alias> Tester`（Alias 从 `libMeta.alias` 取，首字母大写） |
-| 替换范围 | 仅替换 `hardcodedTitles` 中列出的**本次新增**文件；目标已有文件不修改，在报告中标注 |
-
-**示例**：
-
-```tsx
-// ❌ 迁移前（Navigation.tsx 遗留的 Svg 库标题）
-<Text>RN Svg Capi Tester</Text>
-
-// ✅ 迁移后（修正为 PDF 库标题，alias = "react-native-pdf"）
-<Text>RN Pdf Tester</Text>
-```
-
-**执行**：Agent 使用 `Edit` 工具，逐个替换 `hardcodedTitles` 中列出的**本次新增**文件里的硬编码文本。目标已有文件中的硬编码标题不修改，在报告中标注「需人工修正」。
-
-> 未修正的硬编码标题会导致 demo 界面显示错误的库名，属于必修正项。
-
-### 6.6 孤立文件检测与接入（必须执行）
-
-迁移后**必须**检查每个迁移的 `.tsx`/`.ts` 文件是否被入口文件（`index.tsx` 或 `App.tsx`）直接或间接引用。未被引用的文件为「孤立文件」，用户无法通过导航访问到这些 demo。
-
-**检测方法**：
-
-```bash
-# 列出迁移的所有 .tsx/.ts 文件
-find example/src -name "*.tsx" -o -name "*.ts" | grep -v node_modules | sort
-
-# 从入口文件开始，检查 import 链是否覆盖所有文件
-grep -rn "from '\./" example/src/index.tsx example/src/App.tsx
-```
-
-| 文件状态 | 处理 |
-|---------|------|
-| 文件被入口直接/间接引用 | ✅ 无需处理 |
-| 文件有 `export` 但未被入口引用（如 `demo03.tsx`、`demo05.tsx`） | ⚠️ **必须接入**：将组件加入 `index.tsx` 的 `demos` 数组（或 `App.tsx` 的菜单），确保用户可导航到 |
-| 文件无 `export`（纯内部模块） | 检查是否被其他文件引用；若确实无用，在报告中标注 |
-
-**接入示例**（孤立文件 `demo03.tsx` 导出 `SafeAreaProviderProp`）：
-
-```tsx
-// index.tsx — 将孤立文件组件加入 demos 数组
-import { SafeAreaProviderProp } from './demo03';
-
-const demos: IDemoItem[] = [
-  // ... 已有 demo ...
-  { Component: SafeAreaProviderProp, name: 'SafeAreaProviderProp (demo03)', key: 'SafeAreaProviderPropDemo03' },
-];
-```
-
-> ⚠️ 孤立文件不会在运行时被加载，用户无法访问其中的 demo。此检查是**必执行项**，不可跳过。
-
-### 6.7 菜单容器 ScrollView 适配（必须执行）
-
-当 `demos` 数组条目数 > 5 时，菜单内容可能超出屏幕高度。此时**必须**将菜单容器从 `<View>` 改为 `<ScrollView>`，否则底部的 demo 条目不可见、不可点击。
-
-**检测方法**：
-
-```bash
-# 统计 demos 数组条目数
-grep -c "Component:" example/src/index.tsx
-```
-
-| 条目数 | 处理 |
-|--------|------|
-| ≤ 5 | ✅ `<View>` 即可 |
-| > 5 | ⚠️ **必须**将菜单容器改为 `<ScrollView>` |
-
-**修正示例**：
-
-```tsx
-// ❌ 迁移前（View 不支持滚动，底部 demo 不可见）
-<View style={styles.demoNav}>{demoMenu}</View>
-
-// ✅ 迁移后（ScrollView 支持滚动）
-<ScrollView style={styles.demoNav}>{demoMenu}</ScrollView>
-```
-
-> 确保 `ScrollView` 已从 `react-native` 导入。仅修改本次新增的 `index.tsx`；若 `index.tsx` 是目标已有文件，在报告中标注需人工修改。
-
-### 6.8 保留原有 App.tsx 入口（必须执行）
-
-迁移 rnt demo 的 `index.tsx` 后，**必须**检查目标工程原有的 `App.tsx` 是否仍可访问。直接替换 `index.js` 的入口注册会丢失原有 demo。
-
-**检查方法**：
-
-```bash
-# 查看 index.js 注册的入口
-grep "registerComponent" example/index.js
-```
-
-| 场景 | 处理 |
-|------|------|
-| `index.js` 注册的是 `./src/App`（原有入口） | ⚠️ 若要使用 rnt 的 `index.tsx` 作为新入口，**必须**将原有 `App.tsx` 作为一个菜单项接入 `index.tsx` 的 `demos` 数组，确保用户可跳转到原有 demo |
-| `index.js` 注册的是 `./src/index`（rnt 入口） | 检查 `index.tsx` 是否已包含原有 `App.tsx` 的入口；若未包含，按下方示例接入 |
-| 无原有 `App.tsx` | ✅ 无需处理 |
-
-**接入示例**（将原有 App.tsx 作为菜单项）：
-
-```tsx
-// index.tsx — 保留原有 App.tsx 入口
-import OriginalApp from './App';
-
-const demos: IDemoItem[] = [
-  { Component: OriginalApp, name: 'Original Demo (App.tsx)', key: 'OriginalApp' },
-  // ... rnt 迁移的 demo ...
-];
-```
-
-同时更新 `index.js`：
-
-```js
-// index.js — 指向 rnt 迁移的 index.tsx
-import Demo from './src/index';
-AppRegistry.registerComponent(appName, () => Demo);
-```
-
-> ⚠️ 丢失原有 App.tsx 入口会导致已有 demo 不可访问。此检查是**必执行项**。
-
-### 6.9 入口链路端到端验证（必须执行）
-
-迁移完成后，**必须**验证从 `index.js` 到每个 demo 组件的完整引用链路畅通：
-
-```
-index.js → src/index.tsx → Demo 组件 → demos 数组 → 各 Test 组件 → ./demo/ 子组件
-```
-
-**验证清单**：
-
-| # | 检查项 | 验证方法 | 通过标准 |
-|---|--------|---------|---------|
-| 1 | `index.js` 注册的入口存在 | `grep "registerComponent" example/index.js` 然后检查指向的文件存在 | 文件存在且可导入 |
-| 2 | `index.tsx` 的 `demos` 数组覆盖所有迁移组件 | 对比 `demos` 数组与迁移文件列表 | 所有有 `export` 的组件都在 `demos` 中 |
-| 3 | 每个 Test 组件引用的 `./demo/XxxExample` 路径存在 | 逐一 `ls` 验证 | 文件存在 |
-| 4 | 菜单容器支持滚动（当条目 > 5） | 检查 `index.tsx` 中菜单容器是 `ScrollView` | ✅ |
-| 5 | Back 按钮可返回菜单 | 检查 `backClickHandle` 重置 `currentDemoKey` | ✅ |
-
-> 入口链路断裂会导致白屏或部分 demo 不可访问。此验证是**必执行项**。
-
----
-
-## Phase 7：生成迁移报告
-
-按模板生成 Markdown 报告，记录迁移全过程与待办项。
-
-```bash
-# 报告模板位于 assets/PORT_REPORT_TEMPLATE.md
-# Agent 读取模板后填充实际值并写入：
-#   {libPath}/rn-lib-ohos/rnt-demo-port-report.md   （若处于 rn-lib-ohos 流程中）
-#   或 {libPath}/rnt-demo-port-report.md              （独立调用时）
-```
-
-**报告必含**：
-
-1. **版本信息**：库分支、rnt 分支、RNOH 版本、example/package.json 版本一致性
-2. **demo 来源**：rnt 工程路径、demo 子目录、命中候选名
-3. **迁移文件清单**：相对路径列表 + 文件数（区分「本次新增」与「冲突保留目标版本」）
-4. **冲突文件清单**：demo 与目标同名的文件列表，标注「目标版本已保留，demo 版本未写入」
-5. **依赖增量**：新增依赖、版本、来源（demo import 分析）；**标注 example/package.json 中缺失的依赖**（Phase 4.1 检查结果）
-6. **路径修正记录**：每个修正的文件与改动（仅本次新增文件；含入口接入、Navigation.tsx 标题修正、孤立文件接入、ScrollView 适配、原有 App.tsx 保留）
-7. **构建前置检查结果**：
-   - build-profile.json5 模块路径越界检查（Phase 5.1）
-   - .har 文件路径验证（Phase 5.2）
-   - 外部依赖缺失清单（Phase 4.1）
-   - 入口链路验证结果（Phase 6.9）
-8. **待人工确认项**：业务无关依赖、版本不一致、冲突文件需人工合并、入口文件需人工接入等
-9. **后续步骤**：建议执行 `rn-lib-add-example` 完成 Harmony 壳层适配与依赖写入；执行 `npm i` → `ohpm install` → `npm run dev` → `devecocli build` 编译验证
-
-> 报告模板参见 [assets/PORT_REPORT_TEMPLATE.md](assets/PORT_REPORT_TEMPLATE.md)。
-
----
-
-## 与其他 SKILL 的协作
-
-| 协作 SKILL | 关系 | 调用时机 |
-|-----------|------|---------|
-| `rn-lib-add-example` | **下游** | 本 SKILL 完成 demo 迁移后，由 `rn-lib-add-example` 完成 example 模板创建（若缺失）、Harmony 壳层适配、依赖写入、License/OAT、构建验证 |
-| `rn-lib-ohos` | **父流程** | 在 `rn-lib-ohos` Step 5 中调用本 SKILL 执行 demo 查找与迁移，再由 `rn-lib-add-example` 完成壳层适配 |
-| `rnoh-lib-demo-coverage` | **下游（可选）** | 迁移完成后可调用覆盖率分析脚本评估 demo 对库 API 的覆盖程度 |
-
-**职责边界**：
-
-| 任务 | 负责SKILL |
-|------|----------|
-| 查找 rnt demo | 本 SKILL |
-| 分析 demo 依赖 | 本 SKILL |
-| 迁移 demo 文件 | 本 SKILL |
-| 修正 import 路径 | 本 SKILL |
-| 创建 example 模板 | `rn-lib-add-example` |
-| 写入 example/package.json 依赖 | `rn-lib-add-example` |
-| Harmony 壳层（RNPackagesFactory/CMakeLists/build-profile） | `rn-lib-add-example` |
-| License 头 / OAT.xml | `rn-lib-add-example` |
-| `npm run dev` 构建验证 | `rn-lib-add-example` |
-
----
-
-## 常见边界情况
-
-- **目标 example/ 不存在**：提示用户先执行 `rn-lib-add-example` 创建模板，本 SKILL 终止。
-- **rnt 工程无 `rn-tester/examples/` 子目录**：报告终止，提示用户检查 rnt 根路径。
-- **demo 与已有 example/src 内容冲突**：**增量添加，不覆盖**。冲突文件保留目标版本，demo 版本不写入，在报告中列出供人工确认是否合并。
-- **版本无法对齐**：库与 rnt 均无对应版本分支时报错终止，列出可用分支供用户参考。
-- **工作区有未提交修改**：切换分支前自动 `git stash`，迁移完成后 `git stash pop` 恢复。
-- **example/package.json 版本不匹配**：example 的 react-native/react-native-harmony 版本与目标 RNOH 版本不一致时，报告中标注为高优先级待确认项，不阻塞迁移。
-- **Navigation.tsx 含硬编码标题**：自动检测并替换为目标库的 alias（Phase 6.5）。
-- **demo 入口未被 index.tsx 引用**：自动检测并接入（Phase 6.4）。
-- **demo 引用了目标库的内部路径**（如 `react-native-camera-kit/src/internal`）：列入「待人工确认」，不自动改写。
-- **demo 含原生代码**（`.ets`/`.cpp`）：本 SKILL 仅迁移 JS/TS 层；原生代码由 `rn-lib-add-example` 壳层适配处理，报告标注。
-- **rnt 工程路径跨盘/网络挂载**：`rsync` 可能较慢，建议本地拷贝 rnt 工程后执行。
-- **demo 引用 rnt 特有外部依赖（如 @rnoh/testerino）**：example/package.json 未声明该依赖时，所有使用该依赖的组件运行时崩溃。Phase 4.1 检查并从 rnt 工程提取版本信息，在报告中标注为高优先级缺失项。
-- **build-profile.json5 模块路径越界**：`modules[].srcPath` 以 `../` 开头时 hvigor 报错 `Path escapes project root`。Phase 5.1 检测并物理复制模块到工程内，修正路径。符号链接不可行（hvigor 不跟随 symlink）。
-- **oh-package.json5 中 .har 路径错误**：`file:` 引用的 `.har` 路径多/少一层子目录时，`ohpm install` 静默跳过该依赖。Phase 5.2 逐一验证 .har 文件存在性。
-- **迁移的独立 demo 文件未被入口引用**：如 `demo03.tsx`、`demo05.tsx` 已迁移但未被 `index.tsx` 的 `demos` 数组引用，用户无法访问。Phase 6.6 检测并接入。
-- **菜单条目过多无法滚动**：demo 条目 > 5 且菜单容器为 `<View>` 时，底部条目不可见。Phase 6.7 检测并改为 `<ScrollView>`。
-- **替换入口丢失原有 App.tsx demo**：`index.js` 改为注册 `./src/index` 后，原有 `App.tsx` 的 demo 不可访问。Phase 6.8 将原有 App.tsx 作为菜单项接入。
-
-> 完整边界情况与处理策略参见 [references/PORT_VERIFICATION.md](references/PORT_VERIFICATION.md)。
-
----
-
-## 需向用户确认的信息
-
-| # | 节点 | 说明 |
-|---|------|------|
-| 1 | 目标库根目录路径 | 若未通过参数传入 |
-| 2 | rnt 工程路径 | 若未通过参数传入 |
-| 3 | 版本无法自动对齐 | 库与 rnt 均无对应版本分支时，提示用户手动指定 |
-| 4 | 是否清空目标 example/src | `--clean` 启用时必须确认 |
-| 5 | 业务无关依赖是否写入 | 列出后请用户决策 |
-| 6 | 冲突文件是否需要合并 | demo 与目标同名文件保留目标版本后，询问用户是否需要手动合并 |
-
----
-
-## Agent 禁止事项
-
-- **禁止**在版本未对齐时跳过版本检测直接迁移（必须先执行 Phase 2 确认版本一致或已切换分支）。
-- **禁止**在有未提交修改时直接 `git checkout`（必须先 `git stash`）。
-- **禁止**自动启用 `--clean` 清空目标 `example/src/`（必须用户明确同意）。
-- **禁止**覆盖目标 `example/src/` 已有文件（默认 `--ignore-existing`，冲突文件保留目标版本）。
-- **禁止**修改目标已有的文件（路径修正、入口接入、标题修正仅针对本次新增文件）。
-- **禁止**修改目标库 `src/`、`harmony/` 源码（本 SKILL 只动 `example/src/`）。
-- **禁止**自动写入 `example/package.json` 依赖（由 `rn-lib-add-example` 统一处理；本 SKILL 只产出依赖增量清单供下游使用）。
-- **禁止**跳过迁移报告生成。
-- **禁止**跳过入口文件接入检查（Phase 6.4 必须执行）。
-- **禁止**跳过 Navigation.tsx 硬编码标题修正（Phase 6.5 必须执行，仅针对本次新增文件）。
-- **禁止**跳过外部依赖存在性检查（Phase 4.1 必须执行，缺失依赖会导致运行时崩溃）。
-- **禁止**跳过 build-profile.json5 路径越界检查（Phase 5.1 必须执行，越界路径导致编译失败）。
-- **禁止**跳过 .har 文件路径验证（Phase 5.2 必须执行，路径错误导致 ohpm 静默跳过依赖）。
-- **禁止**跳过孤立文件检测（Phase 6.6 必须执行，孤立文件用户无法访问）。
-- **禁止**跳过菜单 ScrollView 适配（Phase 6.7 必须执行，条目 > 5 时不滚动导致底部不可见）。
-- **禁止**替换入口时丢失原有 App.tsx demo（Phase 6.8 必须执行，原有入口必须作为菜单项保留）。
-- **禁止**跳过入口链路端到端验证（Phase 6.9 必须执行）。
-- **禁止**使用符号链接解决 build-profile 路径越界（hvigor 不跟随 symlink，必须物理复制）。
-- **禁止**自动执行 `npm install` 或 `npm run dev`（验证由下游 SKILL 完成）。
-- **禁止**迁移 demo 中的 `node_modules/`、`build/`、`__tests__/`（脚本默认排除，Agent 不得绕过）。
-
----
-
-## 输出物清单
-
-1. **迁移后的 `example/src/` 文件** — demo 源码已增量添加（不覆盖已有文件），新增文件路径已修正，所有 demo 可通过菜单导航访问
-2. **迁移报告 Markdown**（`rnt-demo-port-report.md`） — 含来源、文件清单、冲突文件清单、依赖增量（含缺失依赖标注）、构建前置检查结果、待办项
-3. **依赖增量清单**（报告内章节） — 供 `rn-lib-add-example` 写入 `example/package.json` 使用；标注 example/package.json 中缺失的依赖及建议写入值
-4. **冲突文件清单**（报告内章节） — demo 与目标同名文件列表，标注目标版本已保留，供人工确认是否合并
-5. **待人工确认项清单**（报告内章节） — 业务无关依赖、冲突文件合并、入口文件接入、原生代码标注
-6. **构建前置检查结果**（报告内章节） — build-profile 路径越界、.har 路径验证、入口链路验证结果
+---
+name: rnoh-lib-rnt-search
+description: >-
+  从 rnt（React Native Tester）工程中定位 RN 鸿蒙三方库的 demo 并增量迁移到指定 RN 目标工程的 example/src 下。读取目标库 package.json 元数据生成候选名，扫描 {rnt-root}/*/rn-tester/examples/ 匹配 demo 目录，分析 demo 结构与外部依赖，复制 demo 文件（增量添加，不覆盖目标已有文件）并修正 import 路径与依赖。当用户需要从 rnt 工程查找并迁移 demo 到 RN 鸿蒙三方库 example 工程、单独执行 demo 查找/迁移步骤、向 example/src 增量添加 demo、分析 rnt demo 依赖时使用。适用于 rnt demo 定位、demo 迁移、demo 依赖分析、example 内容增量添加等场景。
+license: Apache-2.0
+compatibility: 需要 bash、node、npm；目标 RN 工程需已有 example/ 目录（缺失时引导使用 rn-lib-add-example 创建）
+allowed-tools: Bash Read Grep Glob Edit Write
+metadata:
+  version: "1.0.0"
+  category: rn-demo-porting
+  language: JavaScript/TypeScript
+  consumed-by: rnohLibAddExampleSkill
+---
+
+# RN 鸿蒙三方库 rnt Demo 查找与迁移
+
+从 rnt（React Native Tester）工程中定位目标 RN 三方库的 demo 目录，迁移到指定 RN 目标工程的 `example/src/`，并完成 import 路径与依赖的修正。
+
+> ⚠️ **核心原则**：
+> 1. 通过 RNOH 框架版本（git 分支或元数据）自动对齐库与 rnt，版本一致时自动选择 demo 并直接迁移，无需人工确认。
+> 2. 本 SKILL 只负责「查找 + 迁移 demo 内容」，不创建/重建 example 工程模板、不做 Harmony 壳层（RNPackagesFactory/CMakeLists/build-profile 等）适配——这些由 `rn-lib-add-example` 完成。
+> 3. **增量添加，不覆盖**：迁移时目标 `example/src/` 已有的文件**保留不动**，仅添加 demo 中目标不存在的文件。冲突文件保留目标版本，在报告中列出供人工确认。
+> 4. 迁移完成后必须输出迁移报告，列出 demo 来源、文件清单、依赖增量、冲突文件（保留目标版本）、待人工确认项。
+
+---
+
+## 路径约定
+
+`{SKILL_DIR}` = 本技能根目录（本 SKILL.md 所在目录）。命令均在 `{SKILL_DIR}` 下执行，使用 `scripts/...`、`references/...` 相对路径。
+
+## 何时使用
+
+- 用户要求从 rnt 工程查找并迁移某个 RN 三方库的 demo。
+- 用户要求向已有 RN 工程的 `example/src/` **增量添加** demo 内容（不覆盖已有文件）。
+- 用户在 `rn-lib-add-example` 流程中需要单独执行 Step 2（demo 查找与迁移）。
+- 用户想分析 rnt demo 的外部依赖，决定 example 需要补哪些包。
+- 用户拿到一个 rnt 工程根路径，想自动定位某个库的 demo 子目录。
+
+## 最小必要输入
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libPath` | string | ✅ | 目标 RN 三方库根目录（含 `package.json`） |
+| `rntPath` | string | ✅* | rnt 工程根目录（含多个子工程，每个有 `rn-tester/examples/`） |
+| `demoPath` | string | ✅* | demo 目录绝对路径（用户已明确时直接传入，跳过扫描） |
+| `targetExampleSrc` | string | ❌ | 目标 RN 工程 `example/src/` 路径；缺省时按 `libPath/example/src` 推断 |
+| `cleanTarget` | boolean | ❌ | 迁移前是否清空目标 `example/src/`；默认 `false`（**增量添加，不覆盖已有文件**） |
+| `rnohVersion` | string | ❌ | 目标 RNOH 框架版本号（如 "0.82"）。未提供时自动从 rnt 分支检测。用于版本对齐与分支切换。 |
+
+> `rntPath` 与 `demoPath` 二选一：用户已明确 demo 路径时传 `demoPath` 跳过扫描；否则必须传 `rntPath` 由脚本扫描定位。
+
+**派生变量**：
+- `skillDir`：本 SKILL 所在目录
+- `libMeta`：`read-lib-meta.cjs` 输出的库元数据 JSON
+- `libVersion`：库的 RNOH 版本（`detect-rnoh-version.cjs` 输出）
+- `rntVersion`：rnt 的 RNOH 版本（`detect-rnoh-version.cjs` 输出）
+- `demoFiles`：demo 目录下待迁移的源文件清单
+- `demoDeps`：`analyze-demo-deps.cjs` 输出的外部依赖清单
+
+## 输入依赖
+
+- **前置SKILL**：无（可独立调用）。若目标 RN 工程 `example/` 不存在，引导用户先执行 `rn-lib-add-example` 创建模板。
+- **输入文件**：目标库 `package.json`、rnt 工程目录树、demo 源码目录。
+- **输出文件**：迁移后的 `example/src/` 文件 + 迁移报告 Markdown。
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 读取库元数据（read-lib-meta.cjs）
+    ↓
+Phase 2: 版本检测与对齐（detect-rnoh-version.cjs，自动切换分支）
+    ↓
+Phase 3: 扫描 rnt 工程定位 demo（find-rnt-demo.sh，版本一致时自动选择）
+    ↓
+Phase 4: 分析 demo 结构与外部依赖（analyze-demo-deps.cjs）
+  4.1 外部依赖存在性检查（example/package.json 是否已声明）
+  4.2 从 rnt 工程提取缺失依赖的版本信息
+    ↓
+Phase 5: 迁移 demo 到目标 example/src（port-demo.sh）
+  5.1 build-profile.json5 模块路径越界检查
+  5.2 .har 文件路径验证
+    ↓
+Phase 6: 修正 import 路径与 displayName + 入口接入
+  6.1 相对路径修正
+  6.2 入口文件对齐
+  6.3 目标库引用对齐
+  6.4 入口文件接入
+  6.5 Navigation.tsx 硬编码标题修正
+  6.6 孤立文件检测与接入
+  6.7 菜单容器 ScrollView 适配
+  6.8 保留原有 App.tsx 入口
+  6.9 入口链路端到端验证
+    ↓
+Phase 7: 生成迁移报告并交付
+```
+
+> rnt 工程结构与 demo 目录约定详见 [references/RNT_PROJECT_STRUCTURE.md](references/RNT_PROJECT_STRUCTURE.md)。
+
+---
+
+## Phase 1：读取库元数据
+
+读取目标库 `package.json`，提取用于 demo 搜索的候选名与鸿蒙化字段。
+
+```bash
+node scripts/read-lib-meta.cjs <libPath>
+```
+
+**关注字段**：
+
+| 字段 | 用途 |
+|------|------|
+| `packageName` | npm 包名，写入 example `dependencies` |
+| `alias` | `harmony.alias`，候选搜索名之一 |
+| `scoped` | 去掉 scope 的短名，候选搜索名之一 |
+| `dirBase` | 目录名，候选搜索名之一 |
+| `searchNames` | 候选搜索名数组（去重） |
+| `autolinkingResolved` | 鸿蒙化模块信息（供下游 `rn-lib-add-example` 壳层适配使用，本 SKILL 不直接处理） |
+
+> 脚本详情与字段说明参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md) 的「库元数据字段」章节。
+
+---
+
+## Phase 2：版本检测与对齐
+
+检测目标库与 rnt 工程的 RNOH 框架版本，当版本不一致时自动切换分支对齐。版本一致后直接进入 Phase 3，**无需用户确认**。
+
+### 2.1 版本检测
+
+```bash
+# 检测库版本
+node scripts/detect-rnoh-version.cjs <libPath>
+
+# 检测 rnt 版本
+node scripts/detect-rnoh-version.cjs <rntPath>
+```
+
+**版本检测优先级**：
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1 | Git 分支名 | `br_rnoh0.82` → `0.82` |
+| 2 | example/package.json | `react-native-harmony: npm:@react-native-oh/react-native-harmony@0.77.72` → `0.77` |
+| 3 | harmony subdirs oh-package.json5 | `@react-native-oh/*` 依赖版本 |
+| 4 | package.json peerDependencies | `react-native: *` |
+
+> 非 Git 仓库时自动降级到 package.json / oh-package.json5 检测。
+
+### 2.2 版本对齐
+
+| 场景 | 处理 |
+|------|------|
+| 库与 rnt 版本一致 | ✅ 直接进入 Phase 3 |
+| 库版本 ≠ rnt 版本，库有对应分支 | 自动 `git checkout` 切换库分支 |
+| 库版本 ≠ rnt 版本，rnt 有对应分支 | 自动 `git checkout` 切换 rnt 分支 |
+| 两者都无法切换到一致版本 | 报错终止，列出可用分支供用户参考 |
+
+**分支切换前必须检查工作区是否干净**：
+
+```bash
+# 检查是否有未提交的修改
+git -C <path> status --short
+```
+
+| 工作区状态 | 处理 |
+|-----------|------|
+| 干净（无输出） | 直接 `git checkout` |
+| 有未提交修改 | `git stash` 暂存 → `git checkout` → 迁移完成后 `git stash pop` 恢复 |
+
+### 2.3 example/package.json 版本一致性检测
+
+版本对齐后，检查 `example/package.json` 中的 `react-native` / `react-native-harmony` 版本是否与目标 RNOH 版本匹配：
+
+```bash
+# 读取 example/package.json 中的 react-native 版本
+node -e "const p=require('./example/package.json'); console.log(p.dependencies['react-native'], p.dependencies['react-native-harmony'])"
+```
+
+| 匹配状态 | 处理 |
+|---------|------|
+| ✅ 版本匹配 | 直接进入 Phase 3 |
+| ❌ 版本不匹配 | 在报告中标注「example/package.json react-native 版本与目标 RNOH 版本不一致」，由 `rn-lib-add-example` 更新 |
+
+> 版本不一致不阻塞迁移，但在报告中标记为高优先级待确认项。
+
+**分支切换示例**：
+
+```bash
+# 列出库的可用分支及版本
+node scripts/detect-rnoh-version.cjs <libPath> --list-branches
+
+# 切换到目标版本分支
+git -C <libPath> stash  # 如有未提交修改
+git -C <libPath> checkout br_rnoh0.82
+git -C <libPath> stash pop  # 恢复暂存（如有）
+```
+
+> ⚠️ 版本对齐自动执行，不暂停等待用户确认。Agent 检测到版本不一致时直接切换分支使其对齐。
+
+---
+
+## Phase 3：扫描 rnt 工程定位 demo
+
+版本对齐完成后，扫描 rnt 工程定位目标库的 demo 目录。当版本一致且命中唯一 demo 时**自动选择**，无需用户确认。
+
+若用户已提供 `demoPath`，跳过本步直接进入 Phase 4。
+
+```bash
+bash scripts/find-rnt-demo.sh \
+  --lib-path <libPath> \
+  --rnt-path <rntPath>
+```
+
+**扫描规则**（详见 [references/RNT_PROJECT_STRUCTURE.md](references/RNT_PROJECT_STRUCTURE.md)）：
+
+1. 读取 `read-lib-meta.cjs` 的 `searchNames` 作为候选名
+2. 遍历 `{rntPath}/*/rn-tester/examples/{候选名}/`
+3. 命中后做大小写不敏感兜底匹配
+4. 输出每个 demo 路径一行；退出码：`0` = 唯一命中、`1` = 未找到、`2` = 多个命中
+
+**自动选择规则**：
+
+| 命中数 | 处理 |
+|--------|------|
+| 0 | 报错终止，提示用户手动提供 `--demo-path` 或检查 rnt 工程路径 |
+| 1 | ✅ 自动选择，直接进入 Phase 4 |
+| 多个 | 自动选择第一个命中项，报告中标注全部命中路径；用户可通过 `--demo-path` 指定其他 |
+
+> 版本一致 + 唯一命中 = 自动选择，不暂停等待用户确认。
+
+---
+
+## Phase 4：分析 demo 结构与外部依赖
+
+扫描 demo 目录的源文件（`.ts`/`.tsx`/`.js`/`.jsx`），提取：
+
+1. **文件清单**：待迁移文件树（用于报告与迁移校验）
+2. **外部依赖**：从 `import ... from 'pkg'` 与 `require('pkg')` 中提取所有非相对路径的包名
+3. **目标库引用方式**：demo 中如何引用目标库（alias / 包名 / 相对路径）
+4. **入口文件**：`App.tsx` / `index.tsx` 位置与 `displayName` / `title` 取值
+
+```bash
+node scripts/analyze-demo-deps.cjs <demoPath> [--lib-name <packageName>] [--alias <harmony.alias>]
+```
+
+输出 JSON：
+
+```json
+{
+  "files": ["App.tsx", "index.tsx", "tests/index.tsx", "camera/CameraDemo.tsx"],
+  "externalDeps": ["@react-native-community/cli", "react-native-svg"],
+  "libReferences": [
+    { "kind": "named", "module": "react-native-camera-kit", "names": ["Camera", "CameraType"] }
+  ],
+  "entryFiles": { "app": "App.tsx", "index": "index.tsx", "displayName": "CameraKitDemo" }
+}
+```
+
+**依赖分类**：
+
+| 类别 | 判定 | 处理 |
+|------|------|------|
+| 目标库本身 | `module === alias` 或 `packageName` | 迁移后改为 `file:../<tgz>` 引用（由 `rn-lib-add-example` 完成） |
+| RNOH 框架 | `@react-native-oh/*` / `@rnoh/*` | 对齐目标 RNOH 版本，写入 example `dependencies` |
+| 通用 RN 依赖 | `react-native-*` / `@react-native-*` | 写入 example `dependencies`，版本与 example 模板对齐 |
+| 业务无关依赖 | 与目标库 demo 无关 | 列入「待人工确认」清单，不自动写入 |
+
+### 4.1 外部依赖存在性检查（必须执行）
+
+`analyze-demo-deps.cjs` 输出的 `externalDeps` 中每个包，**必须逐一检查**是否已在 `example/package.json` 的 `dependencies` 或 `devDependencies` 中声明：
+
+```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)))"
+```
+
+| 检查结果 | 处理 |
+|---------|------|
+| 依赖已在 example/package.json 中声明 | ✅ 无需处理 |
+| 依赖未声明，属于 RNOH/RN 通用包 | ⚠️ **高优先级**：在报告中标注「缺少依赖」，并从 rnt 工程的 `package.json` 中查找该包的版本与引用方式（如 `file:./rnoh_package/xxx.tgz`），在报告依赖增量清单中给出建议的写入值 |
+| 依赖未声明，属于业务无关包 | 列入「待人工确认」清单 |
+
+> ⚠️ **缺失依赖会导致运行时崩溃**。例如 demo 引用 `@rnoh/testerino` 但 example/package.json 未声明，所有使用 `Tester`/`TestCase`/`TestSuite` 的组件均无法渲染。此检查是**必执行项**，不可跳过。
+
+### 4.2 从 rnt 工程提取缺失依赖的版本信息
+
+当发现 example 缺少的依赖时，从 rnt 工程的 `package.json` 中提取该包的版本与引用方式：
+
+```bash
+# 在 rnt 子工程的 package.json 中搜索缺失依赖
+grep -r "<missingDep>" <rntPath>/*/package.json
+```
+
+常见情况：
+- `@rnoh/testerino` → rnt 工程中以 `file:./rnoh_package/testerino/rnoh-testerino-<version>.tgz` 形式引用，需将 tgz 复制到 example 目录并同样以 `file:` 方式引用
+- 其他 `@rnoh/*` 或 `@react-native-ohos/*` 包 → 从 rnt 工程或 npm registry 获取版本
+
+> 详细依赖处理规则参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md) 的「依赖分析与写入」章节。
+
+---
+
+## Phase 5：迁移 demo 到目标 example/src
+
+```bash
+bash scripts/port-demo.sh \
+  --demo-path <demoPath> \
+  --target <targetExampleSrc> \
+  [--clean] \
+  [--exclude 'node_modules,build,__tests__']
+```
+
+**脚本行为**：
+
+1. 校验 `demoPath` 与 `targetExampleSrc` 存在
+2. `--clean` 时清空目标 `example/src/`（**默认不清空**，避免误删用户已有内容；执行前必须由用户确认）
+3. 默认排除 `node_modules/`、`build/`、`__tests__/`、`.cxx/`、`oh_modules/`
+4. 使用 `rsync -a --ignore-existing` 保留文件元数据，**仅添加目标不存在的文件**，已有文件保留不动
+5. 冲突文件（demo 与目标同名）保留目标版本，在输出中列出供 Agent 写入报告
+6. 输出迁移文件清单（相对路径）+ 冲突文件清单
+
+**迁移后目录约定**（典型 demo 结构）：
+
+```
+example/src/
+├── App.tsx              # demo 入口（含 displayName）
+├── index.tsx            # 导出 demo 给 testerino 注册
+├── tests/
+│   └── index.tsx        # testerino 测试用例注册（修正相对路径）
+├── camera/              # demo 功能子目录
+├── scanCode/
+└── components/          # demo 复用组件
+```
+
+> 迁移细节与边界情况（已有文件冲突处理、保留通用组件 `Navigation.tsx` 等）参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md)。**默认增量添加，冲突文件保留目标版本。**
+
+### 5.1 build-profile.json5 模块路径越界检查（必须执行）
+
+迁移后检查 `example/harmony/build-profile.json5` 与 `example/harmony/build-profile.template.json5` 中的 `modules[].srcPath`，确保所有模块路径**不越出** `example/harmony/` 工程根目录：
+
+```bash
+# 读取 build-profile.json5 中的模块路径
+node -e "const fs=require('fs'); const c=fs.readFileSync('example/harmony/build-profile.json5','utf8'); const m=c.match(/srcPath:\s*'([^']+)'/g); console.log(m)"
+```
+
+| 路径形式 | 判定 | 处理 |
+|---------|------|------|
+| `./entry`、`./safe_area` 等 `./` 开头 | ✅ 工程内路径 | 无需处理 |
+| `../../harmony/xxx` 等 `../` 开头 | ❌ **越界**，hvigor 报错 `Path escapes project root` | 见下方修正 |
+
+**越界路径修正步骤**：
+
+1. 将越界引用的模块目录**物理复制**到 `example/harmony/` 下（如 `cp -R ../../harmony/safe_area ./safe_area`）
+2. 修改 `build-profile.json5` 与 `build-profile.template.json5` 中的 `srcPath` 为工程内相对路径（如 `'../../harmony/safe_area'` → `'./safe_area'`）
+3. 同步修正被复制模块自身的 `oh-package.json5` 中 `file:` 引用路径（见 5.2）
+
+> ⚠️ **符号链接不可行**：hvigor 不跟随 symlink，必须物理复制目录。
+
+### 5.2 .har 文件路径验证（必须执行）
+
+被复制的模块（或原有模块）的 `oh-package.json5` 中 `file:` 引用的 `.har` 文件，**必须逐一验证存在性**：
+
+```bash
+# 读取模块 oh-package.json5 中的 file: 引用
+grep -o "file:[^,\"]*" example/harmony/<module>/oh-package.json5
+
+# 逐一验证文件存在
+ls -la example/harmony/<module>/../../node_modules/@react-native-oh/<pkg>/<xxx>.har
+```
+
+| 检查结果 | 处理 |
+|---------|------|
+| `.har` 文件存在于 `file:` 指定路径 | ✅ 无需处理 |
+| 路径多/少一层子目录（如 `harmony/react_native_openharmony.har` vs `react_native_openharmony.har`） | ❌ 修正 `oh-package.json5` 中的路径，使其指向实际 `.har` 文件位置 |
+| `.har` 文件不存在 | ❌ 报告标注，由 `rn-lib-add-example` 处理 |
+
+> ⚠️ `.har` 路径错误会导致 `ohpm install` 静默跳过该依赖，编译时报 `Cannot find module`。
+
+---
+
+## Phase 6：修正 import 路径与 displayName
+
+迁移后**必须**检查并修正以下内容（使用 `Edit` 工具逐文件处理）。
+
+> ⚠️ **仅修正本次新增的文件**：如果某文件是目标已有的（冲突保留项），**不修改它**，仅在报告中标注需人工处理。
+
+### 6.1 相对路径修正
+
+`tests/index.tsx` 等子目录文件中引用 demo 内容的相对路径可能失效。常见修正：
+
+| 错误写法 | 正确写法 | 原因 |
+|----------|----------|------|
+| `./camera/CameraDemo` | `../camera/CameraDemo` | `tests/` 下的文件引用上级目录 |
+| `./components/Nav` | `../components/Nav` | 同上 |
+
+### 6.2 入口文件对齐
+
+- `example/src/App.tsx`：`displayName` / `title` 与 demo 名称一致
+- `example/src/index.tsx`：`export` 路径与迁入的 demo 目录结构一致
+
+### 6.3 目标库引用对齐
+
+确认 demo 中目标库的引用方式与 example 的 `metro.config.js` 别名一致：
+
+- demo 用 `import { X } from '<alias>'` → example `metro.config.js` 的 `extraNodeModules['<alias>']` 指向 `node_modules/<ohPackageName>`
+- demo 用 `import { X } from '<packageName>'` → 同步更新 `tsconfig.json` 的 `paths`
+
+> 完整路径修正检查清单参见 [references/DEMO_PORTING_GUIDE.md](references/DEMO_PORTING_GUIDE.md) 的「路径修正」章节。
+
+### 6.4 入口文件接入
+
+迁移后检查 demo 入口文件（如 `testCase/App.tsx`）是否已被 `example/src/index.tsx` 引用。若未接入，**仅在 `index.tsx` 是本次新增文件时**才更新它；若 `index.tsx` 是目标已有文件，不覆盖，在报告中标注需人工接入。
+
+| 场景 | 处理 |
+|------|------|
+| `index.tsx` 已引用 demo 入口 | ✅ 无需处理 |
+| `index.tsx` 是本次新增文件，未引用 demo 入口 | 更新 `index.tsx`，re-export demo 入口的默认导出和元数据 |
+| `index.tsx` 是目标已有文件，未引用 demo 入口 | ❌ 不覆盖；报告中标注「入口未接入，需人工在已有 index.tsx 中添加 re-export」 |
+| demo 入口即为 `index.tsx` | ✅ 无需处理 |
+
+**示例**（demo 入口在 `testCase/App.tsx`，`index.tsx` 原有独立内容）：
+
+```tsx
+// index.tsx — 更新为 re-export demo 入口
+export {
+  default,
+  displayName,
+  framework,
+  category,
+  title,
+  documentationURL,
+  description,
+  examples,
+} from './testCase/App';
+```
+
+**检查方法**：
+
+```bash
+# 确认 index.tsx 是否引用了 demo 入口
+grep -l "testCase/App\|demo/App\|./App" example/src/index.tsx
+```
+
+> 入口接入是迁移完成的必要步骤——未接入的 demo 入口不会在运行时生效。
+
+### 6.5 Navigation.tsx 硬编码标题修正
+
+rnt demo 中的 `Navigation.tsx`（或类似共享组件）常包含**其他库的硬编码标题**（如 `"RN Svg Capi Tester"`），是从 rnt 共享代码中遗留的。迁移后**必须**检测并修正。
+
+**检测**：`analyze-demo-deps.cjs` 的 `hardcodedTitles` 字段列出所有匹配 `RN <Xxx> (Capi )?Tester` 模式的硬编码文本。
+
+**修正规则**：
+
+| 字段 | 值 |
+|------|-----|
+| 匹配模式 | `RN\s+\w+(?:\s+\w+)*\s+(?:Capi\s+)?Tester` |
+| 替换值 | `RN <Alias> Tester`（Alias 从 `libMeta.alias` 取，首字母大写） |
+| 替换范围 | 仅替换 `hardcodedTitles` 中列出的**本次新增**文件；目标已有文件不修改，在报告中标注 |
+
+**示例**：
+
+```tsx
+// ❌ 迁移前（Navigation.tsx 遗留的 Svg 库标题）
+<Text>RN Svg Capi Tester</Text>
+
+// ✅ 迁移后（修正为 PDF 库标题，alias = "react-native-pdf"）
+<Text>RN Pdf Tester</Text>
+```
+
+**执行**：Agent 使用 `Edit` 工具，逐个替换 `hardcodedTitles` 中列出的**本次新增**文件里的硬编码文本。目标已有文件中的硬编码标题不修改，在报告中标注「需人工修正」。
+
+> 未修正的硬编码标题会导致 demo 界面显示错误的库名，属于必修正项。
+
+### 6.6 孤立文件检测与接入（必须执行）
+
+迁移后**必须**检查每个迁移的 `.tsx`/`.ts` 文件是否被入口文件（`index.tsx` 或 `App.tsx`）直接或间接引用。未被引用的文件为「孤立文件」，用户无法通过导航访问到这些 demo。
+
+**检测方法**：
+
+```bash
+# 列出迁移的所有 .tsx/.ts 文件
+find example/src -name "*.tsx" -o -name "*.ts" | grep -v node_modules | sort
+
+# 从入口文件开始，检查 import 链是否覆盖所有文件
+grep -rn "from '\./" example/src/index.tsx example/src/App.tsx
+```
+
+| 文件状态 | 处理 |
+|---------|------|
+| 文件被入口直接/间接引用 | ✅ 无需处理 |
+| 文件有 `export` 但未被入口引用（如 `demo03.tsx`、`demo05.tsx`） | ⚠️ **必须接入**：将组件加入 `index.tsx` 的 `demos` 数组（或 `App.tsx` 的菜单），确保用户可导航到 |
+| 文件无 `export`（纯内部模块） | 检查是否被其他文件引用；若确实无用，在报告中标注 |
+
+**接入示例**（孤立文件 `demo03.tsx` 导出 `SafeAreaProviderProp`）：
+
+```tsx
+// index.tsx — 将孤立文件组件加入 demos 数组
+import { SafeAreaProviderProp } from './demo03';
+
+const demos: IDemoItem[] = [
+  // ... 已有 demo ...
+  { Component: SafeAreaProviderProp, name: 'SafeAreaProviderProp (demo03)', key: 'SafeAreaProviderPropDemo03' },
+];
+```
+
+> ⚠️ 孤立文件不会在运行时被加载，用户无法访问其中的 demo。此检查是**必执行项**，不可跳过。
+
+### 6.7 菜单容器 ScrollView 适配（必须执行）
+
+当 `demos` 数组条目数 > 5 时，菜单内容可能超出屏幕高度。此时**必须**将菜单容器从 `<View>` 改为 `<ScrollView>`，否则底部的 demo 条目不可见、不可点击。
+
+**检测方法**：
+
+```bash
+# 统计 demos 数组条目数
+grep -c "Component:" example/src/index.tsx
+```
+
+| 条目数 | 处理 |
+|--------|------|
+| ≤ 5 | ✅ `<View>` 即可 |
+| > 5 | ⚠️ **必须**将菜单容器改为 `<ScrollView>` |
+
+**修正示例**：
+
+```tsx
+// ❌ 迁移前（View 不支持滚动，底部 demo 不可见）
+<View style={styles.demoNav}>{demoMenu}</View>
+
+// ✅ 迁移后（ScrollView 支持滚动）
+<ScrollView style={styles.demoNav}>{demoMenu}</ScrollView>
+```
+
+> 确保 `ScrollView` 已从 `react-native` 导入。仅修改本次新增的 `index.tsx`；若 `index.tsx` 是目标已有文件，在报告中标注需人工修改。
+
+### 6.8 保留原有 App.tsx 入口（必须执行）
+
+迁移 rnt demo 的 `index.tsx` 后，**必须**检查目标工程原有的 `App.tsx` 是否仍可访问。直接替换 `index.js` 的入口注册会丢失原有 demo。
+
+**检查方法**：
+
+```bash
+# 查看 index.js 注册的入口
+grep "registerComponent" example/index.js
+```
+
+| 场景 | 处理 |
+|------|------|
+| `index.js` 注册的是 `./src/App`（原有入口） | ⚠️ 若要使用 rnt 的 `index.tsx` 作为新入口，**必须**将原有 `App.tsx` 作为一个菜单项接入 `index.tsx` 的 `demos` 数组，确保用户可跳转到原有 demo |
+| `index.js` 注册的是 `./src/index`（rnt 入口） | 检查 `index.tsx` 是否已包含原有 `App.tsx` 的入口；若未包含，按下方示例接入 |
+| 无原有 `App.tsx` | ✅ 无需处理 |
+
+**接入示例**（将原有 App.tsx 作为菜单项）：
+
+```tsx
+// index.tsx — 保留原有 App.tsx 入口
+import OriginalApp from './App';
+
+const demos: IDemoItem[] = [
+  { Component: OriginalApp, name: 'Original Demo (App.tsx)', key: 'OriginalApp' },
+  // ... rnt 迁移的 demo ...
+];
+```
+
+同时更新 `index.js`：
+
+```js
+// index.js — 指向 rnt 迁移的 index.tsx
+import Demo from './src/index';
+AppRegistry.registerComponent(appName, () => Demo);
+```
+
+> ⚠️ 丢失原有 App.tsx 入口会导致已有 demo 不可访问。此检查是**必执行项**。
+
+### 6.9 入口链路端到端验证（必须执行）
+
+迁移完成后，**必须**验证从 `index.js` 到每个 demo 组件的完整引用链路畅通：
+
+```
+index.js → src/index.tsx → Demo 组件 → demos 数组 → 各 Test 组件 → ./demo/ 子组件
+```
+
+**验证清单**：
+
+| # | 检查项 | 验证方法 | 通过标准 |
+|---|--------|---------|---------|
+| 1 | `index.js` 注册的入口存在 | `grep "registerComponent" example/index.js` 然后检查指向的文件存在 | 文件存在且可导入 |
+| 2 | `index.tsx` 的 `demos` 数组覆盖所有迁移组件 | 对比 `demos` 数组与迁移文件列表 | 所有有 `export` 的组件都在 `demos` 中 |
+| 3 | 每个 Test 组件引用的 `./demo/XxxExample` 路径存在 | 逐一 `ls` 验证 | 文件存在 |
+| 4 | 菜单容器支持滚动（当条目 > 5） | 检查 `index.tsx` 中菜单容器是 `ScrollView` | ✅ |
+| 5 | Back 按钮可返回菜单 | 检查 `backClickHandle` 重置 `currentDemoKey` | ✅ |
+
+> 入口链路断裂会导致白屏或部分 demo 不可访问。此验证是**必执行项**。
+
+---
+
+## Phase 7：生成迁移报告
+
+按模板生成 Markdown 报告，记录迁移全过程与待办项。
+
+```bash
+# 报告模板位于 assets/PORT_REPORT_TEMPLATE.md
+# Agent 读取模板后填充实际值并写入：
+#   {libPath}/rn-lib-ohos/rnt-demo-port-report.md   （若处于 rn-lib-ohos 流程中）
+#   或 {libPath}/rnt-demo-port-report.md              （独立调用时）
+```
+
+**报告必含**：
+
+1. **版本信息**：库分支、rnt 分支、RNOH 版本、example/package.json 版本一致性
+2. **demo 来源**：rnt 工程路径、demo 子目录、命中候选名
+3. **迁移文件清单**：相对路径列表 + 文件数（区分「本次新增」与「冲突保留目标版本」）
+4. **冲突文件清单**：demo 与目标同名的文件列表，标注「目标版本已保留，demo 版本未写入」
+5. **依赖增量**：新增依赖、版本、来源（demo import 分析）；**标注 example/package.json 中缺失的依赖**（Phase 4.1 检查结果）
+6. **路径修正记录**：每个修正的文件与改动（仅本次新增文件；含入口接入、Navigation.tsx 标题修正、孤立文件接入、ScrollView 适配、原有 App.tsx 保留）
+7. **构建前置检查结果**：
+   - build-profile.json5 模块路径越界检查（Phase 5.1）
+   - .har 文件路径验证（Phase 5.2）
+   - 外部依赖缺失清单（Phase 4.1）
+   - 入口链路验证结果（Phase 6.9）
+8. **待人工确认项**：业务无关依赖、版本不一致、冲突文件需人工合并、入口文件需人工接入等
+9. **后续步骤**：建议执行 `rn-lib-add-example` 完成 Harmony 壳层适配与依赖写入；执行 `npm i` → `ohpm install` → `npm run dev` → `devecocli build` 编译验证
+
+> 报告模板参见 [assets/PORT_REPORT_TEMPLATE.md](assets/PORT_REPORT_TEMPLATE.md)。
+
+---
+
+## 与其他 SKILL 的协作
+
+| 协作 SKILL | 关系 | 调用时机 |
+|-----------|------|---------|
+| `rn-lib-add-example` | **下游** | 本 SKILL 完成 demo 迁移后，由 `rn-lib-add-example` 完成 example 模板创建（若缺失）、Harmony 壳层适配、依赖写入、License/OAT、构建验证 |
+| `rn-lib-ohos` | **父流程** | 在 `rn-lib-ohos` Step 5 中调用本 SKILL 执行 demo 查找与迁移，再由 `rn-lib-add-example` 完成壳层适配 |
+| `rnoh-lib-demo-coverage` | **下游（可选）** | 迁移完成后可调用覆盖率分析脚本评估 demo 对库 API 的覆盖程度 |
+
+**职责边界**：
+
+| 任务 | 负责SKILL |
+|------|----------|
+| 查找 rnt demo | 本 SKILL |
+| 分析 demo 依赖 | 本 SKILL |
+| 迁移 demo 文件 | 本 SKILL |
+| 修正 import 路径 | 本 SKILL |
+| 创建 example 模板 | `rn-lib-add-example` |
+| 写入 example/package.json 依赖 | `rn-lib-add-example` |
+| Harmony 壳层（RNPackagesFactory/CMakeLists/build-profile） | `rn-lib-add-example` |
+| License 头 / OAT.xml | `rn-lib-add-example` |
+| `npm run dev` 构建验证 | `rn-lib-add-example` |
+
+---
+
+## 常见边界情况
+
+- **目标 example/ 不存在**：提示用户先执行 `rn-lib-add-example` 创建模板，本 SKILL 终止。
+- **rnt 工程无 `rn-tester/examples/` 子目录**：报告终止，提示用户检查 rnt 根路径。
+- **demo 与已有 example/src 内容冲突**：**增量添加，不覆盖**。冲突文件保留目标版本，demo 版本不写入，在报告中列出供人工确认是否合并。
+- **版本无法对齐**：库与 rnt 均无对应版本分支时报错终止，列出可用分支供用户参考。
+- **工作区有未提交修改**：切换分支前自动 `git stash`，迁移完成后 `git stash pop` 恢复。
+- **example/package.json 版本不匹配**：example 的 react-native/react-native-harmony 版本与目标 RNOH 版本不一致时，报告中标注为高优先级待确认项，不阻塞迁移。
+- **Navigation.tsx 含硬编码标题**：自动检测并替换为目标库的 alias（Phase 6.5）。
+- **demo 入口未被 index.tsx 引用**：自动检测并接入（Phase 6.4）。
+- **demo 引用了目标库的内部路径**（如 `react-native-camera-kit/src/internal`）：列入「待人工确认」，不自动改写。
+- **demo 含原生代码**（`.ets`/`.cpp`）：本 SKILL 仅迁移 JS/TS 层；原生代码由 `rn-lib-add-example` 壳层适配处理，报告标注。
+- **rnt 工程路径跨盘/网络挂载**：`rsync` 可能较慢，建议本地拷贝 rnt 工程后执行。
+- **demo 引用 rnt 特有外部依赖（如 @rnoh/testerino）**：example/package.json 未声明该依赖时，所有使用该依赖的组件运行时崩溃。Phase 4.1 检查并从 rnt 工程提取版本信息，在报告中标注为高优先级缺失项。
+- **build-profile.json5 模块路径越界**：`modules[].srcPath` 以 `../` 开头时 hvigor 报错 `Path escapes project root`。Phase 5.1 检测并物理复制模块到工程内，修正路径。符号链接不可行（hvigor 不跟随 symlink）。
+- **oh-package.json5 中 .har 路径错误**：`file:` 引用的 `.har` 路径多/少一层子目录时，`ohpm install` 静默跳过该依赖。Phase 5.2 逐一验证 .har 文件存在性。
+- **迁移的独立 demo 文件未被入口引用**：如 `demo03.tsx`、`demo05.tsx` 已迁移但未被 `index.tsx` 的 `demos` 数组引用，用户无法访问。Phase 6.6 检测并接入。
+- **菜单条目过多无法滚动**：demo 条目 > 5 且菜单容器为 `<View>` 时，底部条目不可见。Phase 6.7 检测并改为 `<ScrollView>`。
+- **替换入口丢失原有 App.tsx demo**：`index.js` 改为注册 `./src/index` 后，原有 `App.tsx` 的 demo 不可访问。Phase 6.8 将原有 App.tsx 作为菜单项接入。
+
+> 完整边界情况与处理策略参见 [references/PORT_VERIFICATION.md](references/PORT_VERIFICATION.md)。
+
+---
+
+## 需向用户确认的信息
+
+| # | 节点 | 说明 |
+|---|------|------|
+| 1 | 目标库根目录路径 | 若未通过参数传入 |
+| 2 | rnt 工程路径 | 若未通过参数传入 |
+| 3 | 版本无法自动对齐 | 库与 rnt 均无对应版本分支时，提示用户手动指定 |
+| 4 | 是否清空目标 example/src | `--clean` 启用时必须确认 |
+| 5 | 业务无关依赖是否写入 | 列出后请用户决策 |
+| 6 | 冲突文件是否需要合并 | demo 与目标同名文件保留目标版本后，询问用户是否需要手动合并 |
+
+---
+
+## Agent 禁止事项
+
+- **禁止**在版本未对齐时跳过版本检测直接迁移（必须先执行 Phase 2 确认版本一致或已切换分支）。
+- **禁止**在有未提交修改时直接 `git checkout`（必须先 `git stash`）。
+- **禁止**自动启用 `--clean` 清空目标 `example/src/`（必须用户明确同意）。
+- **禁止**覆盖目标 `example/src/` 已有文件（默认 `--ignore-existing`，冲突文件保留目标版本）。
+- **禁止**修改目标已有的文件（路径修正、入口接入、标题修正仅针对本次新增文件）。
+- **禁止**修改目标库 `src/`、`harmony/` 源码（本 SKILL 只动 `example/src/`）。
+- **禁止**自动写入 `example/package.json` 依赖（由 `rn-lib-add-example` 统一处理；本 SKILL 只产出依赖增量清单供下游使用）。
+- **禁止**跳过迁移报告生成。
+- **禁止**跳过入口文件接入检查（Phase 6.4 必须执行）。
+- **禁止**跳过 Navigation.tsx 硬编码标题修正（Phase 6.5 必须执行，仅针对本次新增文件）。
+- **禁止**跳过外部依赖存在性检查（Phase 4.1 必须执行，缺失依赖会导致运行时崩溃）。
+- **禁止**跳过 build-profile.json5 路径越界检查（Phase 5.1 必须执行，越界路径导致编译失败）。
+- **禁止**跳过 .har 文件路径验证（Phase 5.2 必须执行，路径错误导致 ohpm 静默跳过依赖）。
+- **禁止**跳过孤立文件检测（Phase 6.6 必须执行，孤立文件用户无法访问）。
+- **禁止**跳过菜单 ScrollView 适配（Phase 6.7 必须执行，条目 > 5 时不滚动导致底部不可见）。
+- **禁止**替换入口时丢失原有 App.tsx demo（Phase 6.8 必须执行，原有入口必须作为菜单项保留）。
+- **禁止**跳过入口链路端到端验证（Phase 6.9 必须执行）。
+- **禁止**使用符号链接解决 build-profile 路径越界（hvigor 不跟随 symlink，必须物理复制）。
+- **禁止**自动执行 `npm install` 或 `npm run dev`（验证由下游 SKILL 完成）。
+- **禁止**迁移 demo 中的 `node_modules/`、`build/`、`__tests__/`（脚本默认排除，Agent 不得绕过）。
+
+---
+
+## 输出物清单
+
+1. **迁移后的 `example/src/` 文件** — demo 源码已增量添加（不覆盖已有文件），新增文件路径已修正，所有 demo 可通过菜单导航访问
+2. **迁移报告 Markdown**（`rnt-demo-port-report.md`） — 含来源、文件清单、冲突文件清单、依赖增量（含缺失依赖标注）、构建前置检查结果、待办项
+3. **依赖增量清单**（报告内章节） — 供 `rn-lib-add-example` 写入 `example/package.json` 使用；标注 example/package.json 中缺失的依赖及建议写入值
+4. **冲突文件清单**（报告内章节） — demo 与目标同名文件列表，标注目标版本已保留，供人工确认是否合并
+5. **待人工确认项清单**（报告内章节） — 业务无关依赖、冲突文件合并、入口文件接入、原生代码标注
+6. **构建前置检查结果**（报告内章节） — build-profile 路径越界、.har 路径验证、入口链路验证结果