@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-demo-create/references/DEMO_CODE_RULES.md

@@ -0,0 +1,422 @@
+# Demo 代码规则
+
+> Demo 代码生成必须遵循以下规范，确保在 HarmonyOS 平台正确运行。
+
+---
+
+## 1. 目录结构
+
+在 Phase 1.2 探查到的 `exampleDir` 下创建 Demo 目录：
+
+```
+{exampleDir}/{libName}/
+├── index.tsx                  # 主入口（Tester 框架 + 元数据导出）
+└── demo/
+    ├── 001_{描述1}Page.tsx    # 每个 Demo 一个文件
+    ├── 002_{描述2}Page.tsx
+    └── ...
+```
+
+`{exampleDir}` 由探查确定，不硬编码。常见值：`rn-tester/examples/`、`example/src/`、`demo/src/` 等。
+
+### 命名规范
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 目录 | `{序号}_{kebab-case描述}` | `001_basic-gradient` |
+| 文件 | `{描述}Page.tsx` | `BasicGradientPage.tsx` |
+| 类名 | `{PascalCase}Page` | `BasicGradientPage` |
+| TAG 常量 | `库_页面名` | `LinearGradient_BasicGradientPage` |
+
+---
+
+## 2. 导入顺序
+
+```typescript
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { View, Text, ScrollView, TouchableOpacity, StyleSheet } from 'react-native';
+import { ComponentName } from '@react-native-ohos/{libName}';
+```
+
+### 2.1 type 导入规范
+
+对于仅有类型定义的导出（如 `EdgeInsets`、`Metrics`），使用 TypeScript inline type 语法，与运行时导出混写在同一条 import 语句中：
+
+```typescript
+import {
+  SafeAreaProvider,
+  useSafeAreaInsets,
+  initialWindowSafeAreaInsets,
+  type EdgeInsets,
+} from 'react-native-safe-area-context';
+```
+
+> ✅ 使用 `import { type EdgeInsets }` inline type 语法
+> ❌ 不使用 `import type { EdgeInsets } from '...'`（无法与运行时导出混写）
+
+---
+
+## 3. 组件结构规范
+
+### 3.1 根组件
+
+- ❌ **不要使用** `SafeAreaView` 和 `StatusBar`
+- ❌ **不要使用** `ScrollView` 作为 Demo 页面的根容器
+- ✅ **使用** `View` 作为 Demo 页面的根容器
+
+```typescript
+return (
+  <View style={styles.container}>
+    {/* Demo 内容 */}
+  </View>
+);
+```
+
+### 3.2 ScrollView 嵌套问题
+
+- Tester 框架的 `TestCase` 组件内部已包含 `ScrollView`
+- Demo 页面再用 `ScrollView` 作为根容器 → 嵌套 ScrollView → HarmonyOS 上内层高度塌陷为 0 → Demo 完全不可见
+- **主入口文件 index.tsx 的最外层可以使用 ScrollView**（不在 TestCase 内部）
+- **Demo 页面文件（00X_xxxPage.tsx）的根组件必须用 View**
+
+### 3.3 Hook 调用位置约束
+
+Hook 必须在组件顶层调用，不可在事件回调、条件分支、循环中调用。对于依赖 Context 值的 Hook（如 `useSafeAreaInsets()`、`useSafeArea()`），必须放在对应 Provider 的子组件中：
+
+```typescript
+// ✅ 正确：拆分 InnerComponent，Hook 在 Provider 子组件中调用
+const InnerComponent = () => {
+  const insets = useSafeArea(); // Hook 在组件顶层，且在 SafeAreaProvider 子组件中
+  return <Text>{JSON.stringify(insets)}</Text>;
+};
+
+const DemoPage = () => {
+  return (
+    <View style={styles.container}>
+      <SafeAreaProvider>
+        <InnerComponent />
+      </SafeAreaProvider>
+    </View>
+  );
+};
+
+// ❌ 错误：Hook 在 Provider 外部调用，Context 无值会抛出异常
+const DemoPage = () => {
+  const insets = useSafeArea(); // 抛出 NO_INSETS_ERROR
+  return <SafeAreaProvider><Text>{JSON.stringify(insets)}</Text></SafeAreaProvider>;
+};
+
+// ❌ 错误：Hook 在事件回调中调用
+const handlePress = () => {
+  const insets = useSafeArea(); // 违反 Hook 规则
+};
+```
+
+### 3.4 Provider 子组件拆分
+
+当 Demo 需要验证依赖 Context 的接口时，须将使用该接口的组件拆分为独立子组件，放在 Provider 内部渲染：
+
+| 场景 | 拆分方式 | 示例 |
+|------|----------|------|
+| Hook 依赖 Context | 拆分 InnerComponent，Hook 在其中调用 | `useSafeArea()` 在 `SafeAreaProvider` 子组件中 |
+| Consumer 组件 | 直接在 Provider 内部渲染 | `<SafeAreaConsumer>{(insets) => ...}</SafeAreaConsumer>` |
+| Provider 注入初始值 | Provider 包裹子组件，子组件读取注入值 | `<SafeAreaProvider initialSafeAreaInsets={...}><Inner /></SafeAreaProvider>` |
+
+---
+
+## 4. 状态管理
+
+```typescript
+const TAG = '{libName}_{DemoName}';
+
+React.useEffect(() => {
+  console.log(`[${TAG}] Component mounted`);
+  return () => {
+    console.log(`[${TAG}] Component unmounted`);
+  };
+}, []);
+
+const handleAction = useCallback(() => {
+  console.log(`[${TAG}] Action triggered`);
+}, []);
+```
+
+---
+
+## 5. 禁止使用的组件和 API
+
+| 禁止项 | 原因 | 替代方案 |
+|--------|------|----------|
+| `Slider` | HarmonyOS 不支持 | 按钮组控制数值 |
+| `SafeAreaView` | Tester 框架不需要 | `View` |
+| `StatusBar` | Tester 框架不需要 | 移除 |
+| `console.error()` | 触发系统弹窗 | `console.warn()` |
+| `fetch` API 文件操作 | HarmonyOS 不支持 | 库自身 API 或原生文件 API |
+
+### Slider 替代方案
+
+```typescript
+<View style={styles.buttonRow}>
+  <TouchableOpacity onPress={() => handleValueChange(-0.1)}>
+    <Text>-0.1</Text>
+  </TouchableOpacity>
+  <TouchableOpacity onPress={() => handleValueChange(0.01)}>
+    <Text>+0.01</Text>
+  </TouchableOpacity>
+</View>
+```
+
+---
+
+## 6. 平台兼容性
+
+基于源码探查的 `Platform.OS === 'harmony'` 分支结果：
+
+- **只使用** harmony 分支中定义的属性、常量和 API
+- **禁止使用**仅在 iOS/Android 分支中存在的属性（HarmonyOS 下为 `undefined`，导致运行时报错）
+
+### 常见陷阱
+
+| 陷阱 | iOS/Android | HarmonyOS |
+|------|-------------|-----------|
+| 路径常量 | `DocumentDirectoryPath` | `FilesDirectoryPath` |
+| 路径常量 | `CachesDirectoryPath` | `CacheDirectoryPath` |
+| 路径常量 | `MainBundlePath`（iOS） | 不存在 |
+
+### 事件监听
+
+使用源码探查到的事件名称，不要猜测。区分 Promise 方法（需要 `async/await`）和同步方法。
+
+---
+
+## 6.1 废弃接口验证技巧
+
+当 Demo 需要验证 `@deprecated` 废弃接口的兼容性时，使用以下技巧：
+
+### 引用相等性比较
+
+废弃别名接口通常是直接赋值（`export const SafeAreaContext = SafeAreaInsetsContext`），使用 `===` 比较引用是最可靠的验证方式：
+
+```typescript
+const [isSameContext, setIsSameContext] = useState(false);
+
+const handleVerify = useCallback(() => {
+  setIsSameContext(SafeAreaContext === SafeAreaInsetsContext);
+}, []);
+```
+
+> ✅ 引用相等性比较（`===`）比功能对比更可靠
+> ❌ 不要用 `JSON.stringify()` 比较后转回对象比较
+
+### 废弃 Hook 验证
+
+废弃 Hook（如 `useSafeArea()`）内部通常调用非废弃 Hook（如 `useSafeAreaInsets()`），验证时展示返回值一致即可：
+
+```typescript
+const insets = useSafeArea();
+// 直接展示返回值，验证其为有效的 EdgeInsets 对象
+<Text>useSafeArea 返回: {JSON.stringify(insets)}</Text>
+```
+
+### 废弃常量验证
+
+废弃常量（如 `initialWindowSafeAreaInsets`）通常派生自非废弃常量（如 `initialWindowMetrics?.insets`），在 `useEffect` 中读取并展示：
+
+```typescript
+useEffect(() => {
+  setWindowInsetsText(initialWindowSafeAreaInsets ? JSON.stringify(initialWindowSafeAreaInsets) : 'null');
+}, []);
+```
+
+### 废弃 Props 验证
+
+废弃 Props（如 `initialSafeAreaInsets`）作为 Provider 的 fallback 值，通过子组件读取注入的初始值来验证：
+
+```typescript
+const customInitialInsets: EdgeInsets = { top: 50, right: 0, bottom: 50, left: 0 };
+
+<SafeAreaProvider initialSafeAreaInsets={customInitialInsets}>
+  <InnerComponent onInsets={handleInsets} />
+</SafeAreaProvider>
+```
+
+---
+
+## 7. 权限请求
+
+涉及敏感权限的操作（麦克风、相机、定位、存储等），**必须在操作前主动请求权限**：
+
+```typescript
+const handleStartRecording = useCallback(async () => {
+  try {
+    const authorized = await AudioRecorder.requestAuthorization();
+    if (!authorized) {
+      setResultInfo('权限被拒绝，请在设置中开启');
+      return;
+    }
+    // 继续执行操作...
+  } catch (error: any) {
+    setResultInfo(`失败: ${error?.message || error}`);
+  }
+}, []);
+```
+
+**规则**：
+- 涉及麦克风：录音前必须调用 `requestAuthorization()`
+- 涉及相机：拍照/录像前必须请求相机权限
+- 涉及定位：获取位置前必须请求位置权限
+- 涉及存储：读写文件前可能需要请求存储权限
+- **不要假设权限已授予**，即使 manifest 中已声明权限
+
+---
+
+## 8. 原生事件兜底方案
+
+HarmonyOS 端的 `emitDeviceEvent` 事件传递可能不稳定。对于需要实时更新的数据，**使用 JS 端计时器兜底**：
+
+```typescript
+const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+const startTimeRef = useRef<number>(0);
+
+const startTimer = useCallback(() => {
+  startTimeRef.current = Date.now();
+  timerRef.current = setInterval(() => {
+    const elapsed = (Date.now() - startTimeRef.current) / 1000;
+    setRecordingTime(elapsed);
+  }, 100);
+}, []);
+
+const clearTimer = useCallback(() => {
+  if (timerRef.current !== null) {
+    clearInterval(timerRef.current);
+    timerRef.current = null;
+  }
+}, []);
+
+// 开始录音时启动计时器
+startTimer();
+
+// 停止录音时只清除计时器，不重置时长（保留最终值）
+clearTimer();
+```
+
+**规则**：
+- 可同时保留原生事件回调（`onProgress`）和 JS 计时器，以原生事件为主、JS 计时器为兜底
+- 停止操作时**只清除计时器，不要重置时长**（用户需要看到最终时长）
+- 涉及暂停/恢复功能时，计时器需支持暂停（停止 interval）和恢复（重新启动 interval，累计已过时长）
+- 组件卸载时必须清除计时器，防止内存泄漏
+
+---
+
+## 9. 日志输出规范
+
+| 方法 | 行为 | 使用场景 |
+|------|------|----------|
+| `console.error()` | ❌ 触发系统弹窗，阻断用户操作 | **禁止使用** |
+| `console.warn()` | ✅ 仅输出黄色警告日志，不弹窗 | 错误信息输出 |
+| `console.log()` | ✅ 正常日志输出 | 调试日志 |
+
+```typescript
+// ❌ 错误：会弹窗
+console.error(`[${TAG}] Failed: ${error}`);
+
+// ✅ 正确：只输出警告
+console.warn(`[${TAG}] Failed: ${error?.message || error}`);
+```
+
+---
+
+## 10. 异步处理
+
+使用 `async/await` + `try/catch`，不用 `.then()/.catch()` 链式调用：
+
+```typescript
+// ✅ 正确
+const handleAction = useCallback(async () => {
+  try {
+    const result = await someAsyncAPI();
+    setResult(result);
+  } catch (error: any) {
+    console.warn(`[${TAG}] Failed: ${error?.message || error}`);
+  }
+}, []);
+
+// ❌ 禁止
+someAsyncAPI()
+  .then(result => setResult(result))
+  .catch(error => console.error(error));
+```
+
+---
+
+## 11. 样式定义
+
+使用 `StyleSheet.create` 定义所有样式，包含完整的 UI 元素样式：
+
+```typescript
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 16, backgroundColor: '#fff' },
+  card: { padding: 16, borderRadius: 8, backgroundColor: '#f5f5f5', marginBottom: 12 },
+  button: { padding: 12, borderRadius: 6, backgroundColor: '#007AFF', alignItems: 'center' },
+  buttonText: { color: '#fff', fontSize: 14 },
+  buttonRow: { flexDirection: 'row', gap: 8, marginVertical: 8 },
+  text: { fontSize: 14, color: '#333' },
+});
+```
+
+---
+
+## 12. 组件定义风格
+
+```typescript
+const ComponentName = () => {
+  // hooks
+  // handlers
+  return (
+    <View style={styles.container}>
+      {/* 内容 */}
+    </View>
+  );
+};
+
+export default ComponentName;
+```
+
+---
+
+## 13. 禁止事项汇总
+
+❌ **不要**：
+- 添加任何注释（代码中不使用 `//` 或 `/* */`）
+- 创建不必要的文件（如 README.md，除非明确要求）
+- 生成 TODO/FIXME 占位符
+- 使用不存在的组件或 API
+- 使用 iOS/Android 的 API 属性，必须检查 `Platform.OS === 'harmony'` 分支
+- 照搬官方文档或 npm 上的示例代码，未验证 HarmonyOS 平台兼容性
+- 使用 `ScrollView` 作为 Demo 页面的根组件
+- 使用 `console.error()` 输出错误日志
+- 使用 `fetch` API 进行文件系统读写操作
+- 在涉及敏感权限的操作前不请求权限
+- 停止操作时重置计时/计数值为 0（应保留最终值）
+- 使用 `Slider` 组件
+- 在事件回调/条件分支/循环中调用 Hook
+- 在 Provider 外部调用依赖 Context 的 Hook
+- 使用 `import type { ... }` 单独导入类型（应使用 inline `type` 语法混写）
+- 用 `JSON.stringify()` 比较废弃别名（应使用 `===` 引用比较）
+
+✅ **应该**：
+- 所有状态更新通过 setState() 进行
+- 使用 React 最佳实践（hooks, memoization）
+- 保持代码简洁和可读
+- 遵循现有项目的代码风格
+- 先探查 JS 层接口与平台兼容性再生成 Demo 代码
+- 使用 `View` 作为 Demo 页面的根组件
+- 使用 `console.warn()` 替代 `console.error()`
+- 在涉及敏感权限的操作前主动调用权限请求 API
+- 对需要实时更新的数据使用 JS 端计时器兜底
+- 停止操作时保留最终计时/计数值
+- 使用 `async/await` + `try/catch`
+- Hook 在组件顶层调用，依赖 Context 的 Hook 放在 Provider 子组件中
+- 使用 `import { type EdgeInsets }` inline type 语法
+- 废弃别名验证使用 `===` 引用相等性比较
+- 依赖 Context 的组件拆分为 Provider 子组件

package/vendor/Server/Skills/rnoh-lib-demo-create/references/QUALITY_CHECKLIST.md

@@ -0,0 +1,95 @@
+# 质量检查清单
+
+> Demo 代码生成完成后，逐项校验以下清单。所有必须项（✅）通过后才能交付。
+
+---
+
+## 1. 接口探查完整性
+
+| # | 检查项 | 类型 | 通过标准 |
+|---|--------|------|----------|
+| 1.1 | JS 层导出接口已探查 | ✅ 必须 | 函数/类/组件/Hooks/常量已列出 |
+| 1.2 | 平台兼容性 API 已探查 | ✅ 必须 | harmony 分支可用/不可用属性已列出；无平台分支库标记为全部可用 |
+| 1.3 | TurboModule Spec 已探查 | ✅ 必须 | 方法签名、Promise/同步、事件名已确认 |
+| 1.4 | 类型定义已探查 | ⚠️ 推荐 | 参数类型、Props 接口已确认 |
+| 1.5 | 事件名称已确认 | ✅ 必须 | DeviceEventEmitter 事件名来自源码，非猜测 |
+| 1.6 | 废弃接口已探查 | ✅ 必须 | 废弃接口名、别名关系、替代接口已记录（如涉及） |
+| 1.7 | upstream-cache 源码已追溯 | ⚠️ 推荐 | 鸿蒙化库 re-export 上游源码时已追溯实际实现 |
+
+---
+
+## 2. 代码规范
+
+| # | 检查项 | 类型 | 通过标准 |
+|---|--------|------|----------|
+| 2.1 | Demo 页面根组件用 View | ✅ 必须 | 无 ScrollView 作为根组件 |
+| 2.2 | 未使用 SafeAreaView/StatusBar | ✅ 必须 | Tester 框架不需要 |
+| 2.3 | 未使用 Slider | ✅ 必须 | 已用按钮组替代 |
+| 2.4 | 未使用 console.error() | ✅ 必须 | 已替换为 console.warn() |
+| 2.5 | 未使用 fetch API 文件操作 | ✅ 必须 | 使用库自身 API |
+| 2.6 | 代码中无注释 | ✅ 必须 | 无 `//` 或 `/* */` |
+| 2.7 | 使用 async/await + try/catch | ✅ 必须 | 无 .then()/.catch() 链 |
+| 2.8 | 样式用 StyleSheet.create | ✅ 必须 | 完整 UI 元素样式 |
+| 2.9 | TAG 常量命名规范 | ⚠️ 推荐 | `库名_页面名` 格式 |
+| 2.10 | Hook 在组件顶层调用 | ✅ 必须 | 不在事件回调/条件分支/循环中调用 Hook |
+| 2.11 | 依赖 Context 的 Hook 在 Provider 子组件中 | ✅ 必须 | 拆分 InnerComponent，Hook 在 Provider 内部调用 |
+| 2.12 | type 导入使用 inline 语法 | ⚠️ 推荐 | `import { type EdgeInsets }` 而非 `import type { EdgeInsets }` |
+
+---
+
+## 3. 平台兼容性
+
+| # | 检查项 | 类型 | 通过标准 |
+|---|--------|------|----------|
+| 3.1 | 未使用 iOS/Android 专属属性 | ✅ 必须 | 基于 harmony 分支探查结果；无平台分支库全部可用 |
+| 3.2 | 路径常量使用 HarmonyOS 版本 | ✅ 必须 | FilesDirectoryPath 而非 DocumentDirectoryPath |
+| 3.3 | 事件名称与源码一致 | ✅ 必须 | 来自探查结果，非猜测 |
+| 3.4 | 方法调用方式正确 | ✅ 必须 | Promise 方法用 await，同步方法直接调用 |
+| 3.5 | 废弃接口验证使用引用比较 | ⚠️ 推荐 | 使用 `===` 验证别名关系（如涉及废弃接口） |
+
+---
+
+## 4. 权限与兜底
+
+| # | 检查项 | 类型 | 通过标准 |
+|---|--------|------|----------|
+| 4.1 | 敏感权限操作前请求权限 | ✅ 必须 | 麦克风/相机/定位/存储操作前有 requestAuthorization |
+| 4.2 | 实时数据有 JS 计时器兜底 | ✅ 必须 | 原生事件不可靠时 setInterval 兜底 |
+| 4.3 | 停止操作时保留最终值 | ✅ 必须 | 只 clearInterval，不重置状态值 |
+| 4.4 | 组件卸载时清除计时器 | ✅ 必须 | useEffect return 中 clearInterval |
+
+---
+
+## 5. Tester 集成
+
+| # | 检查项 | 类型 | 通过标准 |
+|---|--------|------|----------|
+| 5.1 | index.tsx 包含 Tester 框架集成 | ✅ 必须 | Tester + TestSuite + TestCase |
+| 5.2 | index.tsx 包含元数据导出 | ✅ 必须 | displayName/framework/category/title/description/examples |
+| 5.3 | 注册入口已更新 | ✅ 必须 | registerFile 已追加新 Demo 注册，路径正确 |
+| 5.4 | 注册路径为相对路径 | ✅ 必须 | 从 registerFile 到 indexFile 的相对路径，不硬编码 |
+| 5.5 | 文件命名规范 | ⚠️ 推荐 | 00X_kebab-case描述Page.tsx |
+| 5.6 | 注册模式与现有模式一致 | ✅ 必须 | 模式 A/B/C 与 registerFile 现有注册模式匹配，未破坏已有结构 |
+| 5.7 | 注册模式已识别记录 | ✅ 必须 | 已读取 registerFile 内容，识别并记录注册模式（A/B/C） |
+
+---
+
+## 6. 工程结构探查
+
+| # | 检查项 | 类型 | 通过标准 |
+|---|--------|------|----------|
+| 6.1 | example/demo 目录已探查 | ✅ 必须 | exampleDir 已确定 |
+| 6.2 | 注册入口文件已探查 | ✅ 必须 | registerFile 已确定 |
+| 6.3 | 依赖已存在于 package.json | ✅ 必须 | 生成前已验证 |
+
+---
+
+## 7. 自动化校验
+
+运行校验脚本进行 SKILL 规范检查：
+
+```bash
+bash {skillDir}/scripts/validate-skill.sh {skillDir}
+```
+
+脚本输出 `ALL CHECKS PASSED` 表示 SKILL 结构合规。

package/vendor/Server/Skills/rnoh-lib-demo-create/references/SOURCE_EXPLORATION.md

@@ -0,0 +1,169 @@
+# 源码探查指南
+
+> 生成 Demo 代码前必须完成 JS 层接口与平台兼容性探查，确保 Demo 只使用 HarmonyOS 平台实际支持的 API。本探查仅关注 RN 工程的 JS 层，不涉及鸿蒙原生侧配置。
+
+---
+
+## 1. 探查 JS 层导出接口
+
+**搜索路径（优先级从高到低）：**
+
+1. `node_modules/{harmonyPkgName}/index.js` 或 `index.ts`（推荐）
+2. `node_modules/{harmonyPkgName}/src/index.js` 或 `index.tsx`（备选）
+3. `{projectRoot}/.upstream-cache/{upstreamPkgName}@{version}/package/src/index.tsx`（上游源码缓存，用于鸿蒙化库）
+4. `{projectRoot}/src/index.tsx`（鸿蒙化库源码入口）
+
+> ⚠️ 鸿蒙化三方库的入口文件（如 `src/index.tsx`）可能 re-export 上游源码（`export * from 'react-native-safe-area-context/src/SafeAreaContext'`），需追溯 `.upstream-cache/` 下的实际上游源码文件才能看到完整实现。
+
+**提取信息**：
+- 导出的函数列表：函数名、参数、返回值
+- 导出的类/对象：类名（如 `NativeModules.XxxModule`）、方法列表
+- React 组件：组件名、Props 类型、事件回调 Props（onXxx）
+- Hooks：Hook 函数名、参数、返回值
+- 常量/枚举：常量名及值
+
+---
+
+## 2. 探查平台兼容性 API
+
+> ⚠️ **关键步骤**：确保 Demo 代码只使用 HarmonyOS 平台实际支持的 API、属性和常量。
+
+### 2.1 平台条件分支（Platform.OS）
+
+读取库的入口文件，查找 `Platform.OS === 'harmony'`、`Platform.OS === 'ios'`、`Platform.OS === 'android'` 等条件分支。不同平台分支下暴露的 API、属性、常量可能不同。
+
+```
+示例（react-native-audio）：
+  if (Platform.OS === 'ios') {
+    AudioUtils = { MainBundlePath, DocumentDirectoryPath, ... }
+  } else if (Platform.OS === 'harmony') {
+    AudioUtils = { FilesDirectoryPath, CacheDirectoryPath, TempsDirectoryPath }
+  }
+  → HarmonyOS 下 AudioUtils 没有 DocumentDirectoryPath
+```
+
+### 2.2 导出的常量和工具对象
+
+检查库导出的常量对象（如 `AudioUtils`、`AudioSource`），确认 HarmonyOS 分支下实际包含哪些属性。如果某个属性只在 iOS/Android 分支中定义，在 HarmonyOS 下使用会得到 `undefined`。
+
+### 2.3 提取信息
+
+| 信息 | 说明 | 示例 |
+|------|------|------|
+| HarmonyOS 可用常量 | 只使用 harmony 分支中定义的属性 | `FilesDirectoryPath`（非 `DocumentDirectoryPath`） |
+| HarmonyOS 不可用 API | 标记为禁止使用 | `DocumentDirectoryPath`、`MainBundlePath` |
+| 方法调用方式 | Promise vs 同步 | `startRecording()` 返回 Promise |
+| 事件名称 | DeviceEventEmitter 监听的事件名 | `recordingProgress`、`recordingFinished` |
+
+### 2.4 核心规则
+
+- **只使用 `Platform.OS === 'harmony'` 分支中定义的属性和 API**
+- 如果某个属性只在 iOS/Android 分支中存在，**绝对不能在 Demo 中使用**
+- 如果库没有 `Platform.OS === 'harmony'` 分支，说明可能未适配 HarmonyOS，需要额外确认
+
+### 2.4.1 无平台分支库的探查策略
+
+部分库（如 `react-native-safe-area-context`）没有 `Platform.OS === 'harmony'` 分支，而是通过 TurboModule 原生适配。此类库的特征：
+
+| 特征 | 说明 | 示例 |
+|------|------|------|
+| 无 Platform.OS 分支 | 入口文件和所有源码中无 `Platform.OS === 'harmony'` 等条件判断 | `react-native-safe-area-context` |
+| TurboModule 原生适配 | 鸿蒙侧通过 `src/specs/Native*.ts` 定义 TurboModule Spec | `NativeSafeAreaContext.ts` |
+| 全部导出可用 | JS 层所有导出在 HarmonyOS 上全部可用，无需过滤 | `useSafeAreaInsets`、`SafeAreaProvider` 等 |
+| `.native.ts` 后缀 | 部分常量通过 `InitialWindow.native.ts` 获取原生值 | `initialWindowSafeAreaInsets` |
+
+> 探查时若发现库无 `Platform.OS` 分支，应检查是否存在 TurboModule Spec（`src/specs/Native*.ts`），若存在则标记为"全部导出可用"，跳过 iOS/Android 属性过滤步骤。
+
+### 2.4.2 废弃接口探查
+
+库源码中可能包含 `@deprecated` 标注的废弃接口，需额外提取：
+
+| 探查项 | 提取信息 | 示例 |
+|--------|----------|------|
+| 废弃接口列表 | 接口名、废弃原因、替代接口 | `useSafeArea()` → 替代 `useSafeAreaInsets()` |
+| 别名关系 | 废弃接口与非废弃接口的别名关系 | `SafeAreaContext = SafeAreaInsetsContext`（引用赋值） |
+| 废弃常量 | 废弃的常量及其数据来源 | `initialWindowSafeAreaInsets` → `initialWindowMetrics?.insets` |
+| 废弃 Props | 废弃的组件属性及其 fallback 行为 | `initialSafeAreaInsets` → SafeAreaProvider 初始 fallback |
+
+> 废弃接口在 HarmonyOS 平台仍正常可用，需生成 Demo 验证其兼容性。探查时需记录废弃接口与非废弃接口的别名关系（直接赋值 `=` 还是函数调用），用于 Demo 中引用相等性比较。
+
+### 2.5 常见陷阱
+
+| 陷阱 | iOS/Android | HarmonyOS |
+|------|-------------|-----------|
+| 路径常量 | `DocumentDirectoryPath` | `FilesDirectoryPath` |
+| 路径常量 | `CachesDirectoryPath` | `CacheDirectoryPath` |
+| 路径常量 | `MainBundlePath`（iOS） | 不存在 |
+
+---
+
+## 3. 探查 TurboModule Spec
+
+**搜索路径**：`node_modules/{harmonyPkgName}/src/**/Native*.ts` 或 `generated/ts/` 目录
+
+**提取信息**：
+- 方法签名：方法名、参数类型、返回值类型
+- 调用方式：Promise 返回（需 `await`）还是同步调用
+- 事件定义：`addListener` 方法监听的事件名称
+
+---
+
+## 4. 探查类型定义
+
+**搜索路径**：`node_modules/{harmonyPkgName}/**/*.d.ts`
+
+**提取信息**：
+- 参数详细类型（可选参数、联合类型）
+- 返回值类型
+- Props 接口定义（组件属性）
+- 枚举/类型别名定义
+
+---
+
+## 5. 探查结果汇总
+
+完成探查后，汇总为接口能力清单用于 Demo 代码生成：
+
+| 信息 | 说明 | 示例 (audio) |
+|------|------|-------------|
+| JS 导出函数 | 库入口导出的函数 | `AudioRecorder.startRecording()` |
+| JS 导出组件 | 库入口导出的 React 组件 | 无（纯 API 库） |
+| JS 导出常量 | 库入口导出的常量对象 | `AudioUtils` |
+| HarmonyOS 可用属性 | harmony 分支中定义的属性 | `FilesDirectoryPath`, `CacheDirectoryPath`, `TempsDirectoryPath` |
+| HarmonyOS 不可用属性 | 仅 iOS/Android 分支存在的属性 | `DocumentDirectoryPath`, `MainBundlePath` |
+| 方法调用方式 | Promise vs 同步 | `startRecording()` 返回 Promise |
+| 事件名称 | DeviceEventEmitter 事件名 | `recordingProgress`, `recordingFinished` |
+| 平台分支模式 | 有分支 / 无分支（TurboModule 全适配） | 有分支（audio）/ 无分支（safe-area-context） |
+| 废弃接口清单 | 废弃接口名、别名关系、替代接口 | `useSafeArea()` → `useSafeAreaInsets()` |
+
+---
+
+## 6. MCP 工具辅助
+
+### 6.1 提取接口规格
+
+调用 `script_rn_extract_interfaces` 提取接口规格 JSON，用于交叉验证描述文档中的接口签名：
+
+```
+调用 script_rn_extract_interfaces：
+  - libroot: {{库源码根目录}}
+  - output: {{libroot}}/interface-spec.json
+```
+
+### 6.2 查询鸿蒙知识
+
+调用 `kb_search` 查询鸿蒙平台特定约束：
+
+```
+调用 kb_search：
+  - query: "HarmonyOS 权限请求" / "ArkTS 限制" / "RNOH 事件机制"
+```
+
+---
+
+## 7. 处理策略
+
+1. **JS 层探查优先** - 从 `node_modules/` 读取库的 JS 入口文件
+2. **平台兼容性验证** - 读取 `Platform.OS === 'harmony'` 分支，确认可用 API
+3. **禁止使用 iOS/Android 专属属性** - 不照搬官方文档或 npm 示例代码
+4. **参考描述文档** - Demo 描述文档中的接口签名需与源码交叉验证