鸿蒙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 补充知识库、改进脚本。