AI辅助问题定位指导

本文档介绍如何利用AI能力辅助开发者快速定位三类常见问题：性能类问题、稳定性类问题和功能类问题。

问题定位AI Skill总览

问题类型	Skill名称	适用场景
稳定性类问题	rnoh-stability-triage	崩溃、冻屏、内存异常、资源泄漏等
稳定性代码检视	rnoh-stability-review	代码层面的稳定性风险预判
性能类问题	rnoh-performance-diagnosis	渲染卡顿、启动慢、内存占用高等
功能类问题	rnoh-feature-diagnosis	功能异常、API不生效、组件行为异常等

一、稳定性类问题定位

1.1 适用场景

遇到以下情况时，使用 rnoh-stability-triage skill：

应用异常退出（闪退、Crash）
应用冻屏（界面卡死、无响应）
内存异常（OOM、内存持续增长）
资源泄漏（句柄/线程/监听器未释放）
SIGSEGV、SIGABRT、SIGBUS、SIGTRAP等信号
UAF（释放后访问）、空指针、死锁

1.2 最小必要输入

在使用AI辅助定位前，请准备好以下信息：

崩溃日志
- FaultLog、CppCrash日志
- native backtrace
- JS异常栈（如果是JS Crash）
版本信息
- RNOH版本号（如 0.72.53、0.77.18、0.82.3、0.84.1）
- React Native版本
- HarmonyOS API Level
触发场景
- 启动阶段、页面切换、实例销毁、动画执行、图片加载等
运行日志
- hilog、启动日志、生命周期日志

1.3 AI分析流程

用户输入 → 问题画像提取 → 历史修复匹配 → 代码验证 → 归因判断 → 修复建议

第一步：提取问题画像

AI会从日志中提取以下五元组：

现象：闪退/卡死/OOM/泄漏
类别：应用异常退出/应用冻屏/内存异常/资源泄漏
线程或错误：JS线程、主线程、SIGSEGV等
模块：ImageComponentInstance、JSVMRuntime等
触发阶段：启动、销毁、动画等

第二步：历史修复匹配

AI会优先检查历史稳定性修复汇总，判断问题是否已在后续版本修复：

0.72稳定性修复汇总（约95条）
0.77稳定性修复汇总（约42条）
0.82稳定性修复汇总（约19条）

第三步：归因判断

AI会给出三类归因结果：

更像框架问题
更像用户代码问题
暂时无法定性（需补充信息）

1.4 使用示例

输入示例：

使用rnoh-stability-triage分析以下崩溃：

FaultLog:
Signal: SIGSEGV
Crash thread: JS thread
Backtrace:
#00 pc 00012345 librnoh_core.so (ImageComponentInstance::onImageLoad+124)
#01 pc 00023456 librnoh_core.so (ImageComponentInstance::handleCallback+56)

版本：0.82.1
触发场景：页面退出后立即重新进入时崩溃

输出格式：

# 稳定性问题分析

## 1. 结论摘要
问题类别：应用异常退出（SIGSEGV）
触发阶段：实例销毁后回调继续执行
置信度：高

## 2. 历史修复匹配
命中：图片回调晚于实例销毁导致悬空URI崩溃（0.82.3）
提交：[409e3d355](https://gitcode.com/OpenHarmony-RN/ohos_react_native/commit/409e3d355...)
MR：[!1985](https://gitcode.com/OpenHarmony-RN/ohos_react_native/merge_requests/1985)

## 3. 归因判断
结论：更像框架问题
原因：崩溃栈落在框架内部模块，与历史修复高度匹配

## 4. 修复建议
1. 升级到0.82.3或以上版本
2. 如无法升级，回捞提交409e3d355的补丁

1.5 代码检视Skill

如需在代码层面预判稳定性风险，使用 rnoh-stability-review skill：

适用场景：

PR提交前自查
代码评审时系统检查
已定位到可疑模块，需在代码层面确认

检视分类：

A：应用异常退出风险（销毁后访问、初始化时序、noexcept滥用等）
B：应用冻屏风险（锁顺序、锁重入、持锁回调等）
C：内存异常风险（循环引用、UAF典型路径等）
D：资源泄漏风险（监听器未注销、线程未回收等）
E：华为官方通用规范（Node-API、libuv、ArkUI等）

二、性能类问题定位

2.1 适用场景

遇到以下情况时，使用 rnoh-performance-diagnosis skill：

页面渲染卡顿、掉帧
应用启动慢
滑动/滚动不流畅
动画执行卡顿
内存占用异常高
CPU占用持续高

2.2 问题分类

类别	典型现象	定位重点
渲染性能	UI卡顿、掉帧、动画卡	布局耗时、组件层级、重渲染
启动性能	冷启动慢、首屏加载慢	Bundle加载、初始化链路、预加载
内存性能	内存占用高、OOM	对象持有、缓存策略、图片资源
列表性能	滑动卡顿、列表加载慢	renderItem复杂度、虚拟列表配置
通信性能	JS-Native交互慢	TurboModule调用频率、序列化开销

2.3 最小必要输入

性能数据
- trace分析结果 -帧率数据（FPS）
- 内存占用曲线
- CPU使用率
场景描述
- 问题发生的具体页面/组件
- 操作序列（如：进入页面→滚动列表→退出）
- 预期vs实际表现
代码上下文
- 相关组件代码片段
- 列表配置（如FlatList/FlashList参数）
- TurboModule调用方式

2.4 AI分析流程

现象描述 → 性能归类 → 热点识别 → 根因推断 → 优化建议

第一步：性能归类

AI根据现象判断属于哪类性能问题：

渲染类、启动类、内存类、列表类、通信类

第二步：热点识别

AI识别可能的性能热点：

布局计算频繁
重渲染触发过多
对象创建/销毁频繁
JS-Native通信高频

第三步：根因推断

AI分析可能的根因：

组件设计问题（如深层嵌套、复杂shouldComponentUpdate）
配置问题（如列表未使用虚拟化、图片未压缩）
通信问题（如频繁同步调用TurboModule）

2.5 常见性能问题与解决方案

问题	常见根因	解决方案
页面渲染卡顿	组件层级过深、频繁重渲染	减少层级、使用memo/shouldComponentUpdate、避免在渲染中创建对象
列表滑动卡顿	renderItem复杂、未使用虚拟列表	使用FlashList/FlatList、优化renderItem、设置正确的windowSize
启动慢	Bundle过大、初始化链路长	使用HBC字节码、预加载、延迟加载非关键模块
图片加载慢	图片未压缩、未使用缓存	压缩图片、使用图片缓存、预加载关键图片
动画卡顿	useNativeDriver=false	使用useNativeDriver=true、用transform代替top/left

2.6 使用示例

输入示例：

使用rnoh-performance-diagnosis分析：

现象：列表滚动时明显卡顿，FPS降至30以下
组件：使用FlatList展示100条数据
 renderItem：每个item包含3张图片、2个文本、1个按钮
配置：未设置windowSize、未设置removeClippedSubviews

版本：0.77

输出格式：

# 性能问题分析

## 1. 性能归类
类别：列表性能问题
热点：renderItem复杂度过高

## 2. 根因分析
1. renderItem包含多个复杂组件（图片、文本、按钮）
2. 未启用虚拟列表优化配置
3. 可能存在不必要的重渲染

## 3. 优化建议
1. 优化renderItem：
   - 使用memo包裹Item组件
   - 图片使用缓存策略
   - 避免在render中创建新对象

2. 优化FlatList配置：
   ```tsx
   <FlatList
     data={data}
     renderItem={renderItem}
     keyExtractor={keyExtractor}
     windowSize={5}          // 减少渲染窗口
     removeClippedSubviews={true}  // 移除不可见组件
     maxToRenderPerBatch={10}      // 控制批量渲染数量
     initialNumToRender={10}       // 初始渲染数量
   />

考虑使用FlashList替代FlatList（性能更优）


---

## 三、功能类问题定位

### 3.1 适用场景

遇到以下情况时，使用 `rnoh-feature-diagnosis` skill：

- API调用不生效或返回异常值
- 组件行为与预期不符
- 事件回调未触发或触发异常
- 配置项未生效
- 平台差异导致功能异常

### 3.2 问题分类

| 类别 | 典型现象 | 定位重点 |
| ---- | -------- | -------- |
| API问题 | 调用返回null/undefined、Promise未resolve | API版本支持、参数合法性、TurboModule配置 |
| 组件问题 | 显示异常、交互异常、样式异常 | 组件属性、事件处理、平台适配 |
| 事件问题 | 回调未触发、触发时机错误 | 事件注册、生命周期、监听器管理 |
| 配置问题 | 配置未生效、默认值异常 | 配置方式、优先级、版本兼容 |
| 平台问题 | HarmonyOS表现与iOS/Android不同 | 平台差异文档、规格说明 |

### 3.3 最小必要输入

1. **问题描述**
   - 预期行为 vs 实际行为
   - 问题发生的具体API/组件/配置项

2. **使用代码**
   - 相关调用代码片段
   - 配置代码
   - 参数传递方式

3. **环境信息**
   - RNOH版本
   - HarmonyOS版本/API Level
   - 是否在Debug/Release模式

### 3.4 AI分析流程

问题描述 → 功能归类 → 规格对照 → 代码检查 → 原因判断 → 解决方案


**第一步：功能归类**

AI判断问题属于哪类功能问题：
- API类、组件类、事件类、配置类、平台类

**第二步：规格对照**

AI对照官方规格文档：
- 该API/组件在HarmonyOS上的支持情况
- 已知的平台差异
- 版本支持范围

**第三步：代码检查**

AI检查可能的代码问题：
- 参数类型/格式是否正确
- 调用时机是否正确
- 配置方式是否正确

### 3.5 常见功能问题与解决方案

| 问题 | 常见原因 | 解决方案 |
| ---- | -------- | -------- |
| API返回null/undefined | API在该版本不支持、参数非法 | 检查版本支持文档、校验参数、使用降级方案 |
| StatusBar样式不生效 | HarmonyOS为系统级UI，不与页面绑定 | 页面切换时手动重置、封装跨平台组件 |
| Keyboard事件不触发 | RN不在最上层子窗口、监听器未正确注册 | 调整窗口层级、检查监听器注册方式 |
| 图片加载失败 | 路径格式错误、沙箱路径配置问题 | 使用正确路径格式、参考沙箱加载示例 |
| Modal关闭后仍显示 | ArkUI Dialog在window最上层 | 页面切换时主动关闭、用View替代Modal实现 |
| Linking.canOpenURL返回false | scheme未在module.json5配置 | 在querySchemes中配置目标应用scheme |

### 3.6 使用示例

**输入示例：**

使用rnoh-feature-diagnosis分析：

问题：StatusBar.setBackgroundColor('#FF0000') 设置不生效预期：状态栏背景变为红色实际：状态栏背景未变化

版本：0.77 代码： StatusBar.setBackgroundColor('#FF0000', true);


**输出格式：**

功能问题分析

1. 功能归类

类别：平台类问题具体：StatusBar平台差异

2. 规格说明

HarmonyOS的StatusBar属于系统级UI能力：

状态栏配置由系统统一管理
不与单个页面生命周期绑定
页面切换后样式不会自动回退

3. 原因判断

非代码问题，属于平台能力差异：

StatusBar.setBackgroundColor可以生效
但页面切换后样式不会自动恢复
需要手动管理状态栏状态

4. 解决方案

封装跨平台StatusBar管理组件：

// 推荐封装
if (Platform.OS === 'harmony') {
  // HarmonyOS：不使用StatusBar，或手动管理
} else {
  StatusBar.setBackgroundColor('#FF0000', true);
}

在页面切换时手动重置：
- 进入页面时设置目标样式
- 退出页面时恢复默认样式
参考文档：
- RN StatusBar在HarmonyOS上的行为说明


---

## 四、最佳实践

### 4.1 问题定位通用原则

1. **先分类再深入**：明确问题属于哪类，再针对性定位
2. **最小化输入**：不要求用户提供所有信息，基于已有信息分析
3. **证据优先**：结论需要证据支撑，不臆测
4. **渐进式收敛**：先给倾向，再给证据，最后给置信度
5. **可执行建议**：给出具体可执行的下一步动作

### 4.2 使用AI辅助的注意事项

1. **提供准确版本号**：历史修复匹配依赖版本边界
2. **描述具体场景**：避免笼统描述，说明具体操作序列
3. **补充关键日志**：FaultLog、hilog是定位崩溃的关键
4. **包含代码片段**：代码检视需要具体代码上下文
5. **反馈分析结果**：AI分析后补充更多信息可继续收敛

### 4.3 问题定位流程图

问题发现 → 确定问题类型 → 准备必要信息 → 使用对应Skill → AI分析 → 验证结论 → 执行修复 ↓ ↓ 稳定性/性能/功能补充信息继续分析


---

## 五、相关文档

- [稳定性编码规范](./稳定性编码规范/稳定性编码规范.md)
- [稳定性分析方法](./稳定性问题介绍/稳定性分析方法.md)
- [稳定性案例](./稳定性问题介绍/稳定性案例.md)
- [性能调优](../04-调优/性能调优.md)
- [使用类FAQ](../02-开发/03-场景与实践/使用类FAQ.md)