@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-rnt-search/scripts/port-demo.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# @tool port-demo
+# @description 将 rnt demo 目录内容**增量添加**到目标 RN 工程的 example/src/ 下。
+#              默认不覆盖目标已有文件（--ignore-existing），冲突文件保留目标版本并记录。
+#              支持默认排除项（node_modules/build/__tests__ 等）、--clean 清空目标、
+#              --clean-all 强制全清（含通用组件 Navigation.tsx）、--exclude 追加排除项。
+# @param demo-path: string - rnt demo 目录绝对路径
+# @param target: string - 目标 example/src/ 目录绝对路径
+# @param clean: boolean - 迁移前清空目标（默认 false）
+# @param clean-all: boolean - 强制清空目标含通用组件（默认 false）
+# @param exclude: string - 逗号分隔的追加排除项
+
+set -euo pipefail
+
+DEMO_PATH=""
+TARGET=""
+CLEAN="false"
+CLEAN_ALL="false"
+EXCLUDE_EXTRA=""
+
+usage() {
+  cat <<'EOF'
+Usage: port-demo.sh --demo-path <demo-dir> --target <example-src> [--clean] [--clean-all] [--exclude 'a,b,c']
+
+Incrementally add rnt demo contents into target example/src/.
+Default mode: do NOT overwrite existing files (rsync --ignore-existing).
+Conflicting files are kept as-is (target version wins) and listed in output.
+
+Options:
+  --clean        Clear target before copy (requires user confirmation in SKILL flow)
+  --clean-all    Force clear all including components/Navigation.tsx
+  --exclude      Comma-separated additional exclude patterns
+
+Exit codes:
+  0 = success
+  1 = error (missing args, paths not found, rsync failed)
+EOF
+}
+
+log() { printf '[port-demo] %s\n' "$*" >&2; }
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --demo-path) DEMO_PATH="${2:-}"; shift 2 ;;
+    --target) TARGET="${2:-}"; shift 2 ;;
+    --clean) CLEAN="true"; shift ;;
+    --clean-all) CLEAN_ALL="true"; CLEAN="true"; shift ;;
+    --exclude) EXCLUDE_EXTRA="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$DEMO_PATH" ]] || { echo "--demo-path is required" >&2; exit 1; }
+[[ -n "$TARGET" ]] || { echo "--target is required" >&2; exit 1; }
+[[ -d "$DEMO_PATH" ]] || { echo "Demo path not found: $DEMO_PATH" >&2; exit 1; }
+
+DEMO_PATH="$(cd "$DEMO_PATH" && pwd)"
+
+# Ensure target exists (create if missing, but warn — example/src should already exist)
+if [[ ! -d "$TARGET" ]]; then
+  log "Target directory does not exist: $TARGET"
+  log "Creating target directory. If example/ does not exist, run rn-lib-add-example first."
+  mkdir -p "$TARGET"
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+
+# Build exclude arguments
+EXCLUDE_ARGS=(
+  --exclude 'node_modules/'
+  --exclude 'build/'
+  --exclude '__tests__/'
+  --exclude '.cxx/'
+  --exclude 'oh_modules/'
+  --exclude '.git/'
+  --exclude '.hg/'
+  --exclude 'dist/'
+  --exclude 'coverage/'
+  --exclude '.cache/'
+  --exclude '.DS_Store'
+  --exclude '*.log'
+  --exclude 'oh-package-lock.json5'
+)
+
+# Unless --clean-all, protect Navigation.tsx at any depth (shared component)
+if [[ "$CLEAN_ALL" != "true" ]]; then
+  EXCLUDE_ARGS+=(--filter 'protect Navigation.tsx')
+fi
+
+# Append user-provided excludes
+if [[ -n "$EXCLUDE_EXTRA" ]]; then
+  IFS=',' read -ra EX_ITEMS <<< "$EXCLUDE_EXTRA"
+  for item in "${EX_ITEMS[@]}"; do
+    item="$(echo "$item" | xargs)"  # trim whitespace
+    [[ -n "$item" ]] && EXCLUDE_ARGS+=(--exclude "$item")
+  done
+fi
+
+# Pre-copy: detect conflicts (files in both demo and target, excluding excludes)
+log "Checking for conflicts between demo and target..."
+CONFLICTS=""
+while IFS= read -r line; do
+  [[ -n "$line" ]] && CONFLICTS="$CONFLICTS$line"$'\n'
+done < <(
+  cd "$DEMO_PATH" && find . -type f \
+    -not -path './node_modules/*' \
+    -not -path './build/*' \
+    -not -path './__tests__/*' \
+    -not -path './.cxx/*' \
+    -not -path './oh_modules/*' \
+    -not -name '.DS_Store' \
+    -not -name '*.log' 2>/dev/null | while read -r f; do
+      [[ -f "$TARGET/$f" ]] && echo "$f"
+  done
+)
+
+if [[ -n "$CONFLICTS" ]]; then
+  log "Conflicting files found in target (target version will be KEPT, demo version SKIPPED):"
+  printf '%s\n' "$CONFLICTS" >&2
+  log "These files will NOT be overwritten. Review the report and manually merge if needed."
+fi
+
+# Clean target if requested
+if [[ "$CLEAN" == "true" ]]; then
+  log "Cleaning target: $TARGET (clean-all=$CLEAN_ALL)"
+  if [[ "$CLEAN_ALL" == "true" ]]; then
+    find "$TARGET" -mindepth 1 -delete 2>/dev/null || true
+  else
+    # Preserve Navigation.tsx at any depth if it exists
+    NAV_TMP=""
+    NAV_FILES=$(find "$TARGET" -name "Navigation.tsx" -type f 2>/dev/null)
+    if [[ -n "$NAV_FILES" ]]; then
+      NAV_TMP="$(mktemp -d)"
+      while IFS= read -r nav_file; do
+        rel_nav="${nav_file#$TARGET/}"
+        mkdir -p "$NAV_TMP/$(dirname "$rel_nav")"
+        cp "$nav_file" "$NAV_TMP/$rel_nav"
+        log "Preserved $rel_nav"
+      done <<< "$NAV_FILES"
+    fi
+    find "$TARGET" -mindepth 1 -delete 2>/dev/null || true
+    if [[ -n "$NAV_TMP" ]]; then
+      cd "$NAV_TMP" && find . -type f -exec sh -c 'mkdir -p "$TARGET/$(dirname "{}")" && cp "$NAV_TMP/{}" "$TARGET/{}"' _ {} \;
+      rm -rf "$NAV_TMP"
+    fi
+  fi
+fi
+
+# Copy using rsync (incremental: do NOT overwrite existing files)
+log "Copying demo $DEMO_PATH -> $TARGET (incremental, no overwrite)"
+log "Excludes: ${EXCLUDE_ARGS[*]}"
+
+if ! command -v rsync >/dev/null 2>&1; then
+  log "rsync not found, falling back to cp"
+  # Fallback: cp -Rn with manual excludes (-n = no clobber, do not overwrite)
+  cd "$DEMO_PATH"
+  for item in *; do
+    [[ -e "$item" ]] || continue
+    case "$item" in
+      node_modules|build|__tests__|.cxx|oh_modules|.git|.hg|dist|coverage|.cache) continue ;;
+      *) cp -Rn "$item" "$TARGET/" ;;
+    esac
+  done
+else
+  rsync -a --ignore-existing "${EXCLUDE_ARGS[@]}" "$DEMO_PATH/" "$TARGET/"
+fi
+
+# Output migrated file list
+log "Migration complete. Migrated files (excluding excluded):"
+cd "$TARGET" && find . -type f \
+  -not -path './node_modules/*' \
+  -not -path './build/*' \
+  -not -path './__tests__/*' \
+  -not -path './.cxx/*' \
+  -not -path './oh_modules/*' \
+  -not -name '.DS_Store' \
+  -not -name '*.log' | sort
+
+log "Done. File count: $(cd "$TARGET" && find . -type f -not -path './node_modules/*' -not -path './build/*' | wc -l | tr -d ' ')"
+
+# Output conflict files (kept target version) for report generation
+if [[ -n "$CONFLICTS" ]]; then
+  log "=== CONFLICT FILES (target version kept, demo version skipped) ==="
+  printf '%s\n' "$CONFLICTS" >&2
+  log "=== END CONFLICT FILES ==="
+fi

package/vendor/Server/Skills/rnoh-lib-rnt-search/scripts/read-lib-meta.cjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Read RN third-party library metadata from package.json.
+ * Used by rnoh-lib-rnt-search to generate candidate search names for rnt demo lookup.
+ *
+ * Usage: node read-lib-meta.cjs <lib-root>
+ *
+ * Output: JSON with library metadata including searchNames for demo scanning.
+ * Exit codes: 0 = success, 1 = error (missing package.json or invalid args)
+ */
+const fs = require('fs');
+const path = require('path');
+
+const libRoot = process.argv[2];
+if (!libRoot) {
+  console.error('Usage: node read-lib-meta.cjs <lib-root>');
+  process.exit(1);
+}
+
+const pkgPath = path.join(libRoot, 'package.json');
+if (!fs.existsSync(pkgPath)) {
+  console.error(`package.json not found: ${pkgPath}`);
+  process.exit(1);
+}
+
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const packageName = pkg.name || '';
+const scoped = packageName.includes('/') ? packageName.split('/').pop() : packageName;
+const alias = pkg.harmony?.alias || scoped;
+const autolinking = pkg.harmony?.autolinking || null;
+const dirBase = path.basename(libRoot);
+
+const searchNames = [...new Set([alias, scoped, dirBase, packageName].filter(Boolean))];
+
+/**
+ * HAR source module dir (harmony/{module}/), for manual CMake only — NOT package.json mainHarPath.
+ * Used by downstream rn-lib-add-example for shell adaptation.
+ */
+function inferSourceModulePath(root) {
+  const harmonyDir = path.join(root, 'harmony');
+  if (!fs.existsSync(harmonyDir)) {
+    return null;
+  }
+  const dirs = fs
+    .readdirSync(harmonyDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && d.name !== 'react_native_openharmony')
+    .map((d) => d.name);
+  const withOhPackage = dirs.filter((name) =>
+    fs.existsSync(path.join(harmonyDir, name, 'oh-package.json5')),
+  );
+  if (withOhPackage.length === 1) {
+    return `harmony/${withOhPackage[0]}`;
+  }
+  return null;
+}
+
+function findHarFilesUnder(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...findHarFilesUnder(full));
+    } else if (entry.name.endsWith('.har')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function warnIfMisconfiguredMainHarPath(root, linking, sourceModulePath) {
+  if (!linking || linking === true || !linking.mainHarPath) {
+    return null;
+  }
+  const configured = linking.mainHarPath;
+  const scanDir = path.join(root, configured);
+  const harsInConfigured = findHarFilesUnder(scanDir);
+  if (harsInConfigured.length === 0) {
+    return (
+      `package.json harmony.autolinking.mainHarPath="${configured}" 目录内无 .har 文件，` +
+      'RNOH CLI autolinking 会静默跳过该库。删除 mainHarPath（.har 在 harmony/ 根时默认即可），' +
+      'example CMake 请用 autolinkingResolved.sourceModulePath，勿写入 package.json。'
+    );
+  }
+  if (sourceModulePath && configured === sourceModulePath) {
+    return (
+      `mainHarPath 与源码模块路径相同 (${configured})，通常表示误配：` +
+      'CLI 的 mainHarPath 是 .har 扫描目录，不是 harmony/{module}/ 源码目录。'
+    );
+  }
+  return null;
+}
+
+function resolveAutolinkingFields(root, linking) {
+  if (!linking || linking === true) {
+    return {};
+  }
+  const ohPackageName = linking.ohPackageName || packageName;
+  const sourceModulePath = inferSourceModulePath(root);
+  const cppDir = sourceModulePath
+    ? path.join(root, sourceModulePath, 'src/main/cpp')
+    : null;
+  const hasCpp = cppDir ? fs.existsSync(cppDir) : false;
+  const target = linking.cmakeLibraryTargetName || '';
+  const cmakeShortName = target.startsWith('rnoh_')
+    ? target.slice('rnoh_'.length)
+    : target.replace(/_/g, '-');
+  const mainHarPathWarning = warnIfMisconfiguredMainHarPath(root, linking, sourceModulePath);
+  const harmonyModuleName = sourceModulePath
+    ? path.basename(sourceModulePath)
+    : null;
+
+  return {
+    ohPackageName,
+    sourceModulePath,
+    harmonyModuleName,
+    hasCpp,
+    cmakeCppPath: hasCpp
+      ? `\${NODE_MODULES}/${ohPackageName}/${sourceModulePath}/src/main/cpp`
+      : null,
+    cmakeShortName: cmakeShortName || alias.replace(/-/g, '_'),
+    etsPackageClassName: linking.etsPackageClassName || null,
+    cppPackageClassName: linking.cppPackageClassName || null,
+    cmakeLibraryTargetName: target || null,
+    mainHarPathWarning,
+  };
+}
+
+const autolinkingResolved = resolveAutolinkingFields(libRoot, autolinking);
+
+const result = {
+  packageName,
+  version: pkg.version || '',
+  alias,
+  scoped,
+  dirBase,
+  searchNames,
+  autolinking,
+  autolinkingResolved,
+  codegenConfig: pkg.codegenConfig || null,
+};
+
+console.log(JSON.stringify(result, null, 2));
+
+if (autolinkingResolved.mainHarPathWarning) {
+  console.error(`\n[WARN] ${autolinkingResolved.mainHarPathWarning}`);
+  process.exitCode = 1;
+}

package/vendor/Server/Skills/rnoh-lib-test-align/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: rnoh-lib-test-align
+description: >-
+  用于 RN 鸿蒙三方库升级适配：测试对齐与补全。
+  当用户已经完成代码适配和编译验证（rnoh-lib-code-adapt），
+  需要将上游社区的测试用例移植到本地工程、
+  修复移植后的编译问题、进行测试覆盖率扫描、补充缺失的测试用例时使用。
+  典型场景：用户说"帮我把上游的测试 demo 搬过来"、
+  "测试用例编译不过帮我修"、"覆盖率不够需要补测试"、
+  "上游新增了哪些 API 但我们没有测试覆盖"。
+  也适用于：单独从某个 RN 三方库仓库提取测试 demo、分析测试覆盖率缺口、
+  生成补充测试用例代码。本 skill 的输入通常来自 rnoh-lib-code-adapt。
+compatibility: 需要 git、node、npm、python3、rsync，以及网络访问能力
+allowed-tools: Bash Read Grep Glob Edit Write
+metadata:
+  version: "1.0.0"
+---
+
+# RN 鸿蒙三方库测试对齐与补全
+
+三方库升级适配流程的第三阶段。将上游社区测试用例移植到本地鸿蒙化工程，修复编译问题，扫描测试覆盖率缺口，补充缺失的测试用例。
+
+## 最小必要输入
+
+- **必要**：上游仓库 URL + 版本标签（用于克隆仓库提取测试用例）
+- **必要**：本地鸿蒙化工程目录路径（移植目标）
+- **有帮助**：diff patch 文件（用于判断上游新增了哪些 API 需要测试覆盖）
+
+## 工作流
+
+### 第 1 步：移植上游测试用例
+
+使用 `scripts/port-test-demo.sh` 从上游仓库提取测试 demo 到本地工程。
+
+详细用法参考 [references/port-test-demo-guide.md](references/port-test-demo-guide.md)。
+
+```bash
+./scripts/port-test-demo.sh \
+  --git-url https://github.com/react-native-picker/picker \
+  --branch v2.11.4 \
+  --template-dir /path/to/RN3rdTemplate/0.84
+```
+
+脚本自动完成：git clone → 检测 demo 目录 → 安装依赖 → 拷贝文件 → 合并入口。
+
+**注意**：`workspace:` 协议依赖会自动转换为 `file:` 本地依赖。
+
+### 第 2 步：修复移植后的编译问题
+
+运行 `npm run dev` 收集所有编译错误，按类型分类后逐个修复。
+
+| 问题 | 修复方法 |
+|------|---------|
+| 依赖缺失 | `npm install <包名>` |
+| 导入路径错误（相对路径 → 包名） | 上游 demo 用 `'../src'`、`'../../src'` 引用库源码，移植后路径会解析到错误目录。需改为包名（如 `'@react-native-ohos/netinfo'`），用 `grep -rl "'../src'" example/src/` 批量定位 |
+| 平台不兼容 | 添加 `'harmony'` 分支或条件渲染跳过 |
+| API 不存在 | 检查是否需要适配（回到 rnoh-lib-code-adapt） |
+| 类型错误 | 添加类型断言或调整类型定义 |
+| 资源文件缺失 | 手动 `rsync -av` 拷贝 |
+
+平台不兼容代码用条件渲染跳过：
+
+```typescript
+{Platform.OS !== 'harmony' ? <IOSOnlyComponent /> : null}
+```
+
+### 第 3 步：测试覆盖率扫描
+
+识别未覆盖的 API/组件/props。
+
+#### 覆盖率分析方法
+
+1. **提取所有公开 API**：从 TurboModule spec 文件（`*Native*.ts`）中提取导出方法和属性
+2. **提取所有组件 Props**：从 Fabric 组件 spec（`*NativeComponent.js`）中提取所有 props 定义
+3. **提取所有 NativeCommands**：从 spec 中的 `codegenNativeCommands` 提取命令列表
+4. **扫描测试用例**：在 `src/index.tsx` 和测试文件中搜索每个 API/Props/Command 的使用
+5. **生成覆盖率报告**，格式参考下方模板
+
+> ⚠️ **TurboModule 库（非 Fabric 组件库）的覆盖率维度**：对于 NetInfo 等 TurboModule 库，步骤 2-3（组件 Props、NativeCommands）不适用。覆盖率维度改为：
+> - **API 覆盖**：从 TurboModule spec（`*Native*.ts`）提取方法列表，从 `src/index.ts` 提取公开导出的函数/hook
+> - **状态类型覆盖**：如网络状态 `cellular`、`wifi`、`none`、`unknown` 等各类型
+> - **配置选项覆盖**：如 `useNetInfoInstance` 的 `configuration` 参数各选项（`reachabilityShouldRun`、`reachabilityRequestTimeout` 等）
+
+#### 覆盖率判断标准
+
+- **已覆盖**：API/Prop/Event 在测试代码中有实际调用和使用
+- **缺失**：在 spec 中定义但测试代码中未使用
+- **不适用**：鸿蒙平台不支持、依赖原生运行时（如 `global.nativeFabricUIManager`）、或已标注为其他平台专属
+
+#### 覆盖率报告模板
+
+```markdown
+## 测试覆盖率报告
+
+### 组件 Props 覆盖率
+| Prop | 是否测试 | 测试位置 | 状态 |
+|------|---------|---------|------|
+| source | ✅ | src/index.tsx:30 | 已覆盖 |
+| resizeMode | ❌ | — | 缺失 |
+
+覆盖率: 1/2 (50%)
+
+### 事件覆盖率
+| 事件 | 是否测试 | 状态 |
+|------|---------|------|
+| onChange | ✅ | 已覆盖 |
+| onLoad | ❌ | 缺失 |
+
+覆盖率: 1/2 (50%)
+
+### NativeCommands 覆盖率
+| Command | 是否测试 | 状态 |
+|---------|---------|------|
+| setNativeSelectedIndex | ❌ | 不适用（依赖 Fabric 原生环境） |
+```
+
+### 第 4 步：补充缺失的测试用例
+
+根据覆盖率报告，为缺失项生成补充测试。包括两部分：
+
+#### 4a. 补充 Demo 用例（功能演示）
+
+参考上游 demo 实现，为缺失的 props/events 创建演示组件：
+
+```typescript
+// 新增 Prop 测试 Demo
+function NewPropExample() {
+  return (
+    <MyComponent
+      newProp={newValue}
+      onNewEvent={(e) => console.log(e.nativeEvent)}
+    />
+  );
+}
+```
+
+#### 4b. 补充单元测试（逻辑验证）
+
+为组件核心逻辑编写 jest 单元测试。**React 19 + RN 0.84 环境下有特定的 mock 和配置要求**，详见：
+
+- [references/unit-test-template.md](references/unit-test-template.md) — 测试模板和设计原则
+- [references/jest-troubleshooting.md](references/jest-troubleshooting.md) — 常见问题排错（React 多副本、异步渲染、原生模块崩溃等）
+
+**关键注意事项（React 19 + RN 0.84）**：
+
+1. **React 多副本问题**：库根目录和 example 目录可能各有一份 `node_modules/react`，导致 hooks 失效。必须在 `jest.config.js` 的 `moduleNameMapper` 中强制统一 React 路径。
+2. **React 19 异步渲染**：`react-test-renderer` 在 React 19 中已弃用且默认异步渲染。必须设置 `globalThis.IS_REACT_ACT_ENVIRONMENT = true` 并用 `act()` 包裹 `TestRenderer.create()`。
+3. **Fabric 原生组件 mock**：`*NativeComponent.js` 深度导入 react-native 内部模块，必须为每个 Fabric 组件创建独立 mock。
+4. **react-native mock**：测试环境中 react-native 原生桥不可用，必须创建 `__mocks__/react-native.js` 提供最小化导出。
+
+> ⚠️ **TurboModule 库与 Fabric 组件库的测试策略差异**：
+> - **Fabric 组件库**：需要 mock `codegenNativeComponent` 生成的 Fabric 原生组件（如上文第 3 点），覆盖率维度以 Props/Events/Commands 为主
+> - **TurboModule 库（如 NetInfo）**：**不需要** mock `codegenNativeComponent`，但需要 mock `NativeEventEmitter` 和 `NativeModules`（从 `react-native` 导入）。**关键**：`NativeEventEmitter.addListener` 必须返回 `{ remove: () => void }` 对象（模拟 RN 的 `NativeEventSubscription`），否则 `State.tearDown()` 中的 `this._nativeEventSubscription.remove()` 会报 `TypeError: ...remove is not a function`。详见 [references/jest-troubleshooting.md](references/jest-troubleshooting.md) 问题 8。
+
+### 第 5 步：编译与测试验证
+
+```bash
+# 1. JS Bundle 构建（生成 harmony/entry/src/main/resources/rawfile/bundle.harmony.js）
+npm run dev
+
+# 2. 单元测试（如有）
+npx jest --config jest.config.js --verbose
+
+# 3. 确认无编译错误、测试全部通过
+```
+
+### 第 6 步：设备运行时验证
+
+编译通过 ≠ 运行时正常。必须在真实鸿蒙设备上验证应用能否启动和渲染。
+
+#### 6a. 签名配置与 HAP 部署
+
+> ⚠️ **签名配置规则（重要）**：当工程的 `build-profile.json5` 中 `signingConfigs` 为空（`[]`）或缺失时，**不要自行创建签名文件**。应从平台统一签名配置文件读取并合并到工程中。
+
+**签名配置文件**：位于 `3rdLibraryLoop/Server/` 目录下的 `.signing` 文件（相对于本 SKILL 目录为 `../../.signing`）。
+
+该文件包含预置的 HarmonyOS 签名材料（证书、密钥库、Profile），格式如下：
+
+```json
+{
+  "app": {
+    "signingConfigs": [
+      {
+        "name": "default",
+        "type": "HarmonyOS",
+        "material": {
+          "certpath": "$HOME/.ohos/config/xxx.cer",
+          "keyAlias": "debugKey",
+          "keyPassword": "xxx",
+          "profile": "$HOME/.ohos/config/xxx.p7b",
+          "signAlg": "SHA256withECDSA",
+          "storeFile": "$HOME/.ohos/config/xxx.p12",
+          "storePassword": "xxx"
+        }
+      }
+    ]
+  }
+}
+```
+
+> `.signing` 文件中的 `certpath`/`profile`/`storeFile` 路径指向 `$HOME/.ohos/config/` 目录下的签名材料，由 DevEco Studio 自动生成。直接使用文件中的原始路径即可，无需手动修改。
+
+**合并步骤**：
+
+1. 读取 `.signing` 文件中的 `signingConfigs` 数组
+2. 将其写入目标工程的 `build-profile.json5` 的 `app.signingConfigs` 字段
+3. 确保 `products` 中的 `signingConfig` 引用名称匹配（通常为 `"default"`）
+4. 使用 `devecocli build` 构建签名 HAP
+5. 安装到设备：`hdc install <hap-path>`
+
+**判断是否需要合并签名**：
+
+```bash
+# 检查 build-profile.json5 是否已有签名配置
+grep -c "signingConfigs" build-profile.json5
+# 检查 signingConfigs 是否为空
+grep "signingConfigs" build-profile.json5
+# 如果输出 "signingConfigs": [] 则需要合并
+```
+
+**使用 devecocli 构建签名 HAP**：
+
+```bash
+cd <project>/example/harmony
+
+# 清理构建产物
+devecocli build clean
+
+# 构建签名 HAP
+devecocli build --modules entry@default --build-mode debug
+```
+
+构建产物路径：`<project>/example/harmony/entry/build/default/outputs/default/entry-default-unsigned.hap`
+
+> **注意**：文件名虽含 `unsigned`，但配置了 `signingConfigs` 后 hvigor 会自动签名。可通过构建日志中是否出现 `Will skip sign` 警告判断签名是否生效——无此警告即签名成功。
+
+#### 6b. 常见运行时崩溃
+
+| 崩溃信息 | 根因 | 修复 |
+|---------|------|------|
+| `Element type is invalid: got: object` | `index.tsx` 缺少 `export default` | 在 `AppRegistry.registerComponent` 前添加 `export default ExampleApp;` |
+| `Cannot read property 'useState' of null` | Metro 产生两个 React 实例 | 修复 `metro.config.js`，包装 RNOH 的 resolveRequest |
+| 白屏无渲染 | 设备加载了旧的 rawfile bundle | 重新 `npm run dev` 并重新构建 HAP |
+| `no signature file` (HAP 安装失败) | `build-profile.json5` 中 `signingConfigs` 为空 | 从 `.signing` 文件读取签名配置并合并（见 6a） |
+
+**详细排查步骤和修复代码参考** [references/runtime-troubleshooting.md](references/runtime-troubleshooting.md)。
+
+#### 6c. Metro Dev Server 验证
+
+启动 Metro 并设置端口转发，让设备实时加载最新 bundle：
+
+```bash
+hdc fport tcp:8081 tcp:8081
+npm run start
+```
+
+在设备上重新打开应用，观察 Metro 控制台是否有 bundle 请求日志。
+
+## 常见边界情况
+
+### 上游没有独立的 demo 目录
+
+使用 `--demo-dirs` 参数手动指定目录，或直接拷贝相关测试文件到 `src/` 下。
+
+### 上游 demo 使用 monorepo 结构
+
+`port-test-demo.sh` 会自动检测 `packages/*/example` 结构。如自动检测失败，手动指定 `--demo-dirs packages/core/example`。
+
+### 测试用例依赖了未鸿蒙化的三方库
+
+- 纯 JS 库可以直接安装使用
+- 依赖原生代码且无鸿蒙化版本：在测试中 mock 或条件渲染跳过
+
+### 资源文件（动画、图片）缺失
+
+`port-test-demo.sh` 会自动拷贝 assets 目录。如遗漏，手动 `rsync -av` 拷贝。
+
+### Metro 产生重复 React 实例导致 hooks 崩溃
+
+库通过 `"file:.."` symlink 安装时，库根目录和 example 目录各有一份 `node_modules/react`。Metro 会为两个路径分别创建模块实例，导致 `ReactSharedInternals.H` 为 null，调用 `useState()` 时崩溃。
+
+**关键约束**：不能在 `metro.config.js` 中直接设置 `resolveRequest` 覆盖 RNOH 的 harmony 解析器——这会导致 `.harmony.js` 平台文件解析全部失效。必须**包装** RNOH 的 `resolveRequest`，只拦截裸 `react` 导入。详见 [references/runtime-troubleshooting.md](references/runtime-troubleshooting.md)。
+
+### 设备加载旧 bundle 导致修复不生效
+
+鸿蒙应用启动时按优先级尝试多个 bundle 来源（Metro → 设备文件 → rawfile 资源）。如果 Metro 未运行且 HAP 未重新构建，设备会加载编译进 HAP 的旧 `rawfile/bundle.harmony.js`。必须重新执行 `npm run dev` 并在 DevEco Studio 中重新 Build → Run。
+
+## 输出物清单
+
+1. **移植后的测试用例代码** — 在 `src/index.tsx` 和 `src/` 目录下
+2. **测试覆盖率报告** — 记录 API/Props/Events/Commands 的覆盖情况
+3. **补充的测试用例** — Demo 用例 + jest 单元测试
+4. **编译和测试验证结果** — `npm run dev` 通过、jest 测试通过
+5. **设备运行时验证结果** — 应用在设备上正常启动渲染，无运行时崩溃
+
+这些输出物是 rnoh-lib-func-test skill 的输入。