鸿蒙DFX故障定位：八大Skill与perf-analysis实践

鸿蒙专家

日志很多，定位链路要固定
HarmonyOS/OpenHarmony 应用出现闪退、冻屏、内存持续上涨、句柄超限时，开发者通常能拿到故障日志、堆快照、trace 或采样栈。难点不是没有数据，而是如何从成千上万行内容里先定界、再归因。DFX Skills 是面向这类场景的问题定界定位技能集合。按原文定位，它不是孤立脚本，而是给 AI Agent 使用的工作流大脑：每个技能由 SKILL.md 工作流、scripts 量化脚本、references 故障模式库三部分组成，目标是把「解析日志—匹配故障模式—归因—给建议」串起来，最终输出「三级根因+证据链+修复建议」。
1.3.0 版本于 2026 年 9 月 1 日发布，在 1.2.0 七个故障分析技能基础上新增 perf-analysis，并首次引入 MCP 服务架构。这个变化把覆盖范围从故障分析扩展到性能分析，也意味着部分分析动作可以通过宿主 MCP 工具完成，而不是完全依赖手写查询。

八个技能怎么选：先看现象，再准备证据
选型时建议按三个问题走：第一，故障属于崩溃、卡死、内存/句柄泄漏、性能还是 API 调用失败；第二，手上是 appfreeze 日志、JS 堆栈、Native 调用栈、rawheap、sample/smaps、fd_leak 文件还是 trace/perf；第三，是否需要跨到 Native 或系统侧继续深挖。下面按故障域拆开。

崩溃与无响应
应用卡死、冻屏，日志出现 APPFREEZE、THREAD_BLOCK 等关键字时，用 appfreeze-analysis。它先读日志摘要，再按 overview/resources/event-queue/fault-stack/other-threads/binder/attachments 分区段加载，先排除整机低内存、高负载、热限频等系统级异常，再聚焦主线程或业务线程的 EventHandler 队列阻塞、等锁、Binder 链路。1.3.0 将业务线程阻塞判定改为同一线程 3s 与 6s 的堆栈对比，降低被主线程耗时栈带偏的风险；同时修复 BUSSINESS/BUSINESS 历史拼写兼容问题，旧日志也能解析。
应用启动闪退或点击后白屏，日志是 TypeError、ReferenceError 等 ArkTS/JS 异常，用 jscrash-analysis。它按 Reason→Error name→Error message 多级分类，匹配故障模式库的三级根因体系，定位第一个应用栈帧并标注框架栈传播路径；SourceMap 缺失时仍可分析原始堆栈。1.3.0 增加 OOM 快照联动：当定性为 OutOfMemoryError 且提供了堆快照，自动转交 jsleak-analysis，一次输入产出两份报告。
Native C/C++ 崩溃，出现段错误、空指针或 libxxx.so 调用栈，用 cppcrash-analysis。它按信号分类，分析崩溃地址，联合 Maps、寄存器、线程证据判断第一现场，并把调用栈分成崩溃帧、首个非运行时调用方、首个应用帧。只有符号或二进制可用时才执行 llvm-addr2line、llvm-objdump 深挖。1.3.0 新增 HSP 加载失败识别、NAPI ProcessAll 回调崩溃定位、符号表反解状态门禁；责任领域对齐后，系统侧根因只输出系统模块修改，应用侧只输出应用修改，混合责任分开输出。

内存与资源泄漏
JS/ArkTS 内存持续上涨，手里有堆快照时，用 jsleak-analysis。它支持 rawheap 转 heapsnapshot，调用 heap_cluster 按 Retained Size 排序，检查 Detached DOM、全局引用/window/Cache、闭包持有 context、异常大对象，并匹配 ROOT_VM/FRAME/LOCAL_HANDLE/GLOBAL_HANDLE 故障模式。1.3.0 加入全图强引用最短路径查找，避免弱引用被误报；单快照聚类增加 --top N；还支持 rawheap+htrace+js_map 三合一日志入口，自动完成 HTrace 转 DB、快照聚类、Node ID 到 Native 地址映射，并支持续跑跳过已完成阶段。
内存上涨但问题不在 JS 层，PSS 持续上升时，用 nativeleak-analysis。它先识别 sample、smaps、profiler、kernel 文件类型，判断泄漏类型占比和内存变化趋势；PSS 泄漏细分到 jemalloc、ArkTS、ashmem、anon，结合 profiler 火焰图定位热点函数和调用路径，并覆盖 DMA buffer/GPU 资源泄漏模板、kernel 侧 DMA/GPU/ASHMEM/SLAB 分析。1.3.0 修正 trace_streamer 的 HTrace 转 DB 数据解析，并与 jsleak-analysis 的三合一功能共享。
出现 RESOURCE_OVERLIMIT 告警，或后台进程句柄数突破 20000，日志为 [pid]_fd_leak.txt 时，用 fdleak-analysis。它提取故障头、句柄类型 Top、目录 Top，按 ashmem/socket/pipe/sync_file/dmabuf 五类专项还原申请栈，并按 FdTrack 调用方向定位。该技能严格区分当前句柄存量与 10 分钟全量申请统计，避免把已关闭 FD 的申请栈误判为泄漏。

性能与 API 失败
列表滑动卡顿、应用启动慢、游戏掉帧，手上有 trace 或 perf 数据时，用 perf-analysis。它是 DFX Skills 首个基于 MCP 服务的技能，也是第一个面向性能问题的端到端分析能力：用一句自然语言描述问题，技能按「环境就绪→日志就绪→根因分析」自动推进，探测 MCP 工具可用性，识别或引导抓取 trace/perf，把日志转为 SQLite，再按问题描述路由到子 Skill。10 个子 Skill 覆盖启动分析、丢帧分析、调度分析、频点分布、IO 分析、负载对比、游戏性能、渲染管线检测、hiperf 热点采样、通用即席探索。1.3.0 要求全程通过宿主 MCP 工具调用，禁止手写 SQL，避免遗漏框架自动注入参数；内置 hitrace 与 hiperf 抓取指南，设备已连接时可现场采集。
系统 API 调用失败、返回错误码但不知道含义，或日志 domain_id 与模块对不上、调用栈 .so 归属不清时，用 apifault-analysis。它是八项中唯一的静态诊断技能，流程为环境发现→线索提取与模块识别→分诊查询→深潜分析→报告生成，依托 error_codes.json、api_chain.json、common_issues.md 知识库查询；低置信度时会反向追踪源码、校验调用时序与权限声明，最后输出结构化诊断报告。

1.3.0 的工程化取舍
原文把 1.3.0 的主线概括为更准、更稳、不背锅、更全面。落到工程实践上，可以理解为四类改动：一是判定更准，例如 appfreeze 用 3s/6s 堆栈对比、jsleak 用全图强引用最短路径；二是解析更稳，例如修复 BUSSINESS/BUSINESS 拼写兼容、修正 trace_streamer 的 HTrace 转 DB；三是责任边界更清楚，例如 cppcrash 区分系统侧、应用侧和混合责任，fdleak 区分句柄存量与全量申请；四是覆盖更全，新增 perf-analysis，并引入 MCP 服务架构、OOM 快照联动和三合一日志入口。

调用方式与落地建议
使用时不需要逐条敲脚本，把日志交给 AI Agent，用自然语言说明问题；Agent 命中关键字后进入对应技能工作流，最终给出 Markdown 报告。例如冻屏场景可以这样发起：

2. 请使用 appfreeze-analysis skill，分析故障日志：appfreeze.log 和采样栈：sample_stacks.txt

复制代码

落地时建议先保证输入与技能匹配：appfreeze 用故障日志和采样栈，jscrash 保留原始堆栈与 SourceMap（没有 SourceMap 也可分析原始堆栈），OOM 场景提供堆快照可触发 jsleak 联动，cppcrash 深挖前准备符号或二进制，fdleak 使用 [pid]_fd_leak.txt，perf 场景提供 trace/perf 或在设备连接时按指南采集。cppcrash 在符号或二进制不可用时会限制深挖，这属于证据边界，不是把所有问题都强行归因。
代码仓库已开源：https://gitcode.com/openharmony-sig/developtools_dfx_skills ，内含完整 SKILL.md 工作流、脚本工具和故障模式库。原文给出的定位是把故障工单处理时长从小时级压缩到分钟级，性能问题定位也可通过自然语言驱动；实际效果仍取决于日志完整性和证据质量。如果遇到误判、漏报或新故障模式，可按原文说明提交 Issue 或 PR 补充知识库、改进脚本。

热心网友1

感谢分享，这套“先定界、再归因”的思路说得很清楚，尤其是按故障域拆成八个技能、再按“现象+手上证据”来选型，比直接翻日志高效多了。 几个细节我觉得挺实用：appfreeze 把业务线程阻塞判定改成同一线程 3s 与 6s 的堆栈对比，确实能减少被主线程耗时栈带偏；jsleak 的全图强引用最短路径查找、避免弱引用误报，以及 rawheap+htrace+js_map 三合一日志入口支持续跑，实际排查内存问题时能省不少折腾。fdleak 区分“当前句柄存量”和“10 分钟全量申请统计”这点也很关键，不然很容易把已关闭 FD 的申请栈当成泄漏。 另外想请教下，perf-analysis 要求全程通过宿主 MCP 工具调用、禁止手写 SQL，这个在设备已连接、现场抓 trace/perf 的场景下稳定性怎么样？还有帖子最后“1.3.0 的工程化取舍”那部分好像被截断了，方便的话期待补全，想看看版本升级背后的取舍逻辑。

热心网友4

感谢分享，这篇梳理得很清楚，尤其是按“现象—证据—是否跨Native/系统侧”三个问题来选技能，比单纯列功能实用多了。之前遇到冻屏和句柄超限时最头疼的就是日志太多、不知道从哪切，看到 appfreeze 按 overview/resources/event-queue 分区加载，以及 fdleak 严格区分当前存量和十分钟全量申请统计，感觉能少踩不少“把已关闭 FD 误判成泄漏”的坑。 另外 1.3.0 把 jsleak 和 nativeleak 的 HTrace 转 DB 能力打通、jscrash 定性 OOM 后自动转交 jsleak 这点挺顺的，等于一次输入能沿着链路走下去。perf-analysis 用自然语言描述问题再路由到子 Skill、全程走宿主 MCP 工具而不手写 SQL，这个方向对性能分析入门很友好，不过实际用起来如果问题描述比较含糊，路由准确率怎么样？还有帖子最后“原文把 1.3.0”似乎没贴完，方便的话可以补一下工程化取舍那部分。

热心网友7

这篇把八大 Skill 按故障域和证据类型来选型的思路讲得很清楚，尤其是先判断现象、再看手头是 appfreeze 日志、JS 堆栈、rawheap、smaps 还是 trace/perf，最后决定要不要往 Native 或系统侧深挖，这个顺序对实际定位很有帮助。1.3.0 里几处改动也很有价值，比如 appfreeze 用同一线程 3s 与 6s 堆栈对比来降低误判，jscrash 在 OOM 时联动 jsleak，jsleak 支持 rawheap、htrace、js_map 三合一日志入口，以及 perf-analysis 走 MCP 且禁止手写 SQL，这些都是在减少定位链路上的手工拼凑。 如果后续要方便团队落地，可以考虑把“现象—手上证据—对应 Skill—输出物”整理成一张速查表或决策树，会更容易在故障现场快速选对技能。另外正文最后一句似乎被截断了，1.3.0 的工程化取舍部分如果补全，整篇会更完整。感谢分享。