本原创文章帖发布在华为开发者联盟社区，欢迎开发者前往访问评论交流，更多与该内容相关讨论，请点击原帖查看：

鸿蒙应用问题定位定界DFX Skill 五大实战，轻松掌握故障定界与修复-华为开发者话题 | 华为开发者联盟

✨ 从问题场景出发，用 AI Agent 驱动故障定界与修复

基于 OpenHarmony-SIG / developtools_dfx_skills

DFX 问题定界定位技能集

—————————————————————————————————————————————

💡 前言：DFX Skills 能帮你做什么？

      DFX Skills 是面向 HarmonyOS / OpenHarmony 生态的故障自动化分析技能集，将DFX专家经验沉淀为可被 AI Agent 调用的 Skill。本文从 5 个实战问题场景出发，结合 cppcrash-analysis、jscrash-analysis、jsleak-analysis、appfreeze-analysis、perf-analysis 等技能，拆解"遇到问题 → 用哪个 Skill → 怎么操作"的完整链路。

      开源仓地址：https://gitcode.com/openharmony-sig/developtools_dfx_skills?ha_source=zxqy-IT&ha_sourceId=89000468

——————————————————————————————————————————

🎯 场景 1 | [符号表引导] faultlog 分析后希望提供符号表，怎么提示 AI？

✅ A：

      DFX Skills 设有"符号表反解状态门禁"机制。技能在输出修复建议前，自动判断关键栈帧是否已符号化，未反解时会在建议中要求补充匹配 BuildID 的符号文件。

📋 门禁判断规则

• 已反解：明确说明已用匹配 BuildID 的符号文件，且提供了函数名或源码行

• 未反解：未核对 BuildID，或关键帧仍仅有裸地址、<so>+offset

• 门禁动作：应用侧未反解 → 要求提供应用 .so/符号；系统侧未反解 → 要求提供系统模块符号

💬 你应该怎么告诉 AI？

🔧 CppCrash最佳实践：

我已准备好符号表，请帮我反解：1. 符号表 .so 路径：D:/symbols/libentry.z.so2源码项目根目录：D:/MyHarmonyApp请用 ohos_llvm_tools.py addr2line 反解后结合源码分析。

📝 JSCrash 最佳实践：

SourceMap 反解请求：1. sourceMaps.json 目录：build/default/cache/.../release/2. crash 日志文件路径:/MyHarmonyApp请用hstack反解后重新分析根因。

🛠️ 涉及技能：cppcrash-analysis · jscrash-analysis

—————————————————————————————————————————————

🎯 场景 2 | [符号化流程] 有符号表的情况下怎么反编译日志提供给 Agent？

✅ A：

      无需手动反编译——把符号表/SourceMap 和故障日志一起交给 Agent，技能自动完成反解、校验和源码定位全流程。

🔧Native 层（CppCrash）：agent通过addr2line + objdump工具实现native层反解

cppcrash-analysis/Script目录下反解工具实现原理：

• main.py 提取关键日志：Reason、信号、寄存器、调用栈帧

• 识别到 .so 裸地址后，检查是否有匹配 BuildID 的符号

• addr2line 将 pc 偏移还原为 函数名 + 源文件:行号：

python "<skill-root>/scripts/ohos_llvm_tools.py" addr2line "libentry.z.so" 0xa3f0

• 需要分析多参数/虚表/函数指针时，objdump 反汇编 pc 附近指令：

python "<skill-root>/scripts/ohos_llvm_tools.py" objdump "libentry.z.so" output/

• 提供源码目录后，技能结合行号上下文检查空值、边界、线程和回调时序

📝 ArkTS 层（JSCrash）：agent通过hstack + SourceMap工具实现arcts侧的反解

      jscrash-analysis/Scripts目录下反解工具实现原理：

• 出现 "Cannot get SourceMap info, dump raw stack" 或混淆函数名时，视为未反解

• 提供sourceMaps.json后，先做 UUID/构建指纹校验

• 指纹一致 → 执行 hstack 反解：

Windows: hstack.bat -i "<crash-dir>" -o "<output-dir>" -s "<source-map-dir>"
Linux/macOS: hstack -i "<crash-dir>" -o "<output-dir>" -s "<source-map-dir>"

• 启用混淆时加 -n 提供 nameCache.json，同步还原方法名

• 反解后校验至少一个应用帧还原为 源文件:函数:行:列，后续以反解堆栈为准

🛠️ 涉及技能：cppcrash-analysis（ohos_llvm_tools.py） ·jscrash-analysis（hstack）

—————————————————————————————————————————————

🎯 场景 3 | [快照对比] 📊 多个快照希望对比分析怎么做？

✅ A：

      jsleak-analysis 内置 heap_cluster.js，支持三种对比模式。把快照交给 Agent 并描述诉求即可自动选择。具体功能介绍如下：

📈 多快照总榜（--multi）

      适用：多份快照聚合分析，找出持续出现、累计占用最大的对象。

& $NODE "$SKILL_DIR/scripts/node/heap_cluster.js" --multi --multi-top 20 "D:/snapshots/" "D:/output/"

• 产出：累计 Retained Size、出现次数、平均排名、代表引用链

🔄 双版本增长对比（--compare）

      适用：旧版本 vs 新版本，分析哪些对象新增了、增长了。

& $NODE "$SKILL_DIR/scripts/node/heap_cluster.js" --compare --compare-top 20 "D:/v1/" "D:/v2/" "D:/output/"

• 产出：新增对象 TopN、增长对象 TopN、增长量/比例、相似引用链组

• 判断是"新增泄漏"还是"已有泄漏加重"

🔧测试版差值对比（--compare-experimental）

      适用：优先展示 retained size 差值最大的对象。

& $NODE "$SKILL_DIR/scripts/node/heap_cluster.js" --compare-experimental --compare-top 20 "D:/v1/" "D:/v2/" "D:/output/"

🤖 对比后技能做什么？

• 为每个嫌疑对象匹配故障模式（ROOT_VM / ROOT_FRAME / LOCAL_HANDLE / GLOBAL_HANDLE）

• 输出三级根因，给出回归排查建议

• 提供 native hook DB 时可执行 GlobalHandler 关联 native 堆栈

🛠️ 涉及技能：jsleak-analysis（heap_cluster.js --multi / --compare / --compare-experimental）

—————————————————————————————————————————————

🎯 场景 4 | [多版本对比] ⚡️ 多个版本的 trace 文件如何做对比？

✅ A：

      perf-analysis 支持多日志独立分析 + 汇总归并。把多个 trace 路径给 Agent，技能逐个转换、独立分析，最后归并 Top 3 根因。

📝 操作流程

📥 步骤 1：把 trace 路径告诉 Agent

请分析以下 trace，对比两版本性能差异：v1（基线）：D:/traces/v1/trace_v1.sysv2（新版）：D:/traces/v2/trace_v2.sys问题：列表滑动卡顿，新版本更严重

🔄 步骤 2：逐个转换为 SQLite

      对每个 trace 调用convert_hitrace_to_sqlite，返回 sqlite_path 和时间范围。

🤖 步骤 3：自动选择分析 Skill

• "卡顿/丢帧" → frame_drop_analysis

• "启动/冷启动" → launch_perf

• "调度/线程阻塞" → sched_analysis

• "负载对比" → load_compare

• 无法明确时 → ad_hoc_exploration

⚡️ 步骤 4：逐个 run_skill 分析

      auto_continue=True 自动执行到完成，单个失败不阻断其他。

🎯 步骤 5：汇总根因

• 去重归并：同一根因合并

• 排序取 Top 3：按严重度 × 涉及日志数

• 标注涉及哪些版本

📄 输出示例：

【性能分析完成】 trace 2 个1. RS 渲染耗时过长(v2): 优化复杂布局2. UI 线程 Binder 超时(v1,v2): 异步化跨进程调用3. 主线程连续耗时回调(v2): 拆分长任务为分帧执行对比结论：v2 丢帧更严重，RS 负载从偶发变持续

🛠️ 涉及技能：perf-analysis（run_skill + frame_drop_analysis / load_compare）

—————————————————————————————————————————————

🎯 场景 5 | [日志采集] 🐞 appfreeze、jsleak 怎么在开发态复现抓日志？

✅ A：

      DFX Skills 遵循"日志就绪"原则——缺失时主动引导采集。以下是两类故障在开发态的复现与抓取方法。

⚡️一、AppFreeze（冻屏/卡死）

• 系统在主线程/业务线程阻塞 6 秒后自动生成 faultlog（THREAD_BLOCK_6S 等）

• 开发态复现：代码中模拟主线程阻塞（sleep、死循环、死锁）

• 文件路径：/data/log/faultlog/ 和 /data/log/reliability/

• 把 faultlog + 采样栈文件交给 Agent，技能先读 overview 再按需读取各区段

• 官方指导：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/appfreeze-guidelines日志获取

💧 二、JS 内存泄漏（jsleak）

• DevEco Studio Profiler → Memory，在操作前后各抓一次 .rawheap 形成基线 + 对比

• 文件路径：/data/log/memleak/，格式：memleak-js-{bundleName}-{pid}-{timestamp}.rawheap

• .rawheap 可能使用 .log 扩展名，确认后创建副本

• 技能内置 rawheap_translator 自动转为 .heapsnapshot 再聚类

• 多快照可用 --multi 或 --compare 自动对比

🎯 通用：trace + perf 抓取（性能场景）

💡 直接使用 perf-analysis 技能内置的抓取指南（catch-trace.md + catch-perf.md），技能会在缺失日志时自动引导你完成 hdc hitrace 和 hiperf 采集，无需手动查文档。

🛠️ 涉及技能：appfreeze-analysis · jsleak-analysis · perf-analysis

—————————————————————————————————————————————

📋 五大场景速查表

—————————————————————————————————————————————

🎯 写在最后

      DFX Skills 的设计哲学是"让专家经验可复制"。无论崩溃、卡死、卡顿、内存泄漏还是性能问题，只需用自然语言描述问题、提供日志，AI Agent 自动完成从日志解析到根因定位的全流程。

🌟 五个场景的共同特点：

• ✨ 不需要记复杂命令——技能内置脚本自动执行

• ✨ 不需要猜符号表怎么给——门禁机制自动引导

• ✨ 不需要手动对比快照/trace——内置对比分析模式

• ✨ 不需要翻文档查怎么抓日志——内置采集指南，缺失时主动引导

⭐

让每一位开发者都拥有专家级的故障诊断能力

OpenHarmony-SIG / developtools_dfx_skills

----------------------------------------------------------------------------------------------------------

🔗 官网开发者学堂视频：https://developer.huawei.com/consumer/cn/training/result?type2List=201783644516849879&orderBy=1&courseType=5?ha_source=zxqy-IT&ha_sourceId=89000468

🔗 社区DFX专题文章： https://developer.huawei.com/consumer/cn/forum/subject/2101218731402391001?ha_source=zxqy-IT&ha_sourceId=89000468

【扫码加入 HarmonyOS DFX 技术交流群】