HarmonyOS冻屏自动化定位与trace/perf分析

鸿蒙专家

偶发冻屏最难处理的地方，是准备抓现场时页面又恢复了。等重新操作，一切可能又正常，关键几秒很容易错过。appfreeze-dev-analysis 的思路是：在 CodeAgent 中启动一个持续观察的子任务，检测到卡死信号后自动抓取 trace 和 perf，再调用分析技能，结合工程代码返回报告。这个任务在后台执行，不会阻塞主 Agent 的正常开发测试任务。

一、安装与启动观察任务

从官方技能仓安装完整的 developtools_dfx_skills，按仓库说明把技能加载到 CodeAgent，并配置分析依赖。安装后新建会话，让 Agent 检查依赖。连接并解锁手机，运行待测的调试应用，然后在 CodeAgent 中输入观察指令，例如：持续监控当前 HarmonyOS 工程的应用是否发生卡死问题，卡死时抓日志并结合代码分析。观察 30 分钟。监听 ready 后告诉我，我来操作应用；每次采集后主动返回分析报告，继续监听，直到我要求停止。也可以简短地说“帮我盯着当前应用，卡死时抓日志分析”。多台设备连接时补上目标设备；工具或工程不在默认位置时，再提供路径。首次配置需按仓库说明满足相应条件，日常使用不必每次手工重配。

二、报告里有什么，怎么用

耗时分析报告监控任务在检测到触发事件后，主动采集约 10 秒的 trace 和 perf，并返回耗时分析报告。收到 Agent 提示后，先看 timeout-analysis.md，再打开 capture.htrace。报告会包含采集时间范围、主线程状态，以及建议检查的代码位置。

原文给出了一份报告摘要，来自 GLM-5 对历史 CPU 繁忙事件的离线分析，数据和表述经过人工核对，用来展示报告能提供的线索。诊断结论是：点击处理链同步执行 runBusyCpu，主线程持续计算，无法及时处理后续消息。采样调用链为 anonymous Index.ts:545:33→ menuAction Index.ts:306:34→ runBusyCpu Index.ts:327:21。本地源码中，Index.ets 第 135 行调用 runBusyCpu，第 157—159 行是计算循环：

2. const summary = this.runBusyCpu();
3. while (Date.now() < end) {
4.   acc += Math.sqrt(i * 1.000001) + Math.sin(i % 360) * Math.cos(i % 180);
5.   i++; // 其余循环控制省略
6. }

复制代码

修改建议是移除或限制这个用于制造故障的测试循环。真实业务遇到同类问题，先减少重复计算，再考虑任务池或 Worker，完成后回主线程更新 UI。给函数加 async，不会自动把同步计算移到其他线程。复测方法是用相同输入核对输出，主动录制修改后的操作，检查耗时和交互。原文也说明，本事件尚无修复后的测量数据。

报告会如实说明日志未能获取的信息：这份记录只覆盖约 9.7 秒，缺少完整系统资源信息和故障快照栈；perf 样本数不能换算成某行代码的毫秒数，15005 ms 的任务时长也不能这样分摊。历史安装包与 SourceMap 的构建身份未核验，源码行号应作为候选位置使用。拿到报告后，下一步是打开采样记录，核对它是否支持这个判断。

三、在采样记录里验证调用链

SmartPerf Host 可以本地查看合并 htrace。原文示例使用 6.0.0.36 发布包，一次导入就能看到调度轨道和 HiPerf 采样。选择 Open trace file 打开记录，展开 HiPerf → 目标进程 → 主线程，框选区间后打开 Bottom Up。点击 runBusyCpu，右侧 Call Stack 可以继续看到 menuAction 和 anonymous。

这里的 26.4% 属于选中的采样位置，不代表整个函数的耗时占比，也不能与报告全窗口的统计直接对比。SmartPerf 显示的 TS 位置还要通过同构建 SourceMap 反解为 ETS 位置。如果习惯在 IDE 里查代码，也可以使用 DevEco Studio Profiler。原文示例为同一历史事件单独导入 perf：展开 Callstack，框选主线程采样，打开 Bottom Up，再双击 Index.ts 的业务帧。这组操作展示查栈和跳转，未验证 IDE 同时显示合并文件的两类轨道。

这样就能把“主线程很忙”落到具体的调用和循环上。换成自己的工程时，仍要确认源码、SourceMap 和安装包属于同一构建；能跳转到某一行，只说明找到了可查看的位置。

四、采集约束与排障注意事项

开发态通常使用 aa attach，避免进程过早被系统结束。若 IDE 已持有调试会话，观察任务需要识别并复用，结束时不能解除其他任务的调试状态。

检测命中后，hiprofiler_cmd 在同一会话中使用 ftrace-plugin 和 hiperf-plugin 录制约 10 秒。perf 参数为 1000 Hz、hw-cpu-cycles、fp，保留 offcpu 和 cpu-limit 25，不另起 hiperf。这意味着采集从检测信号之后开始，无法追回此前的 trace。分析上一份报告时可以继续等待下一轮采集，但录制或封存期间的新信号不会排队补录。需要看完整操作时，应协调停止监听，提前开始一次主动录制，避免两个 trace 任务争用设备。

遇到锁等待等阻塞，主线程可能没有 CPU 样本。只有确认采集有效、同一进程仍卡死且确实没有主线程样本，才在停止采集、确认调试归属后考虑 LLDB 补栈。如果已有样本只是缺业务符号，先补 SourceMap 或符号。

开发结束时，记得告诉 Agent：停止观察，分析完已经采集的事件并汇总，确认采集退出且清理完成。事件处理完后再看 session-report.md。completed 表示适用分析流程和证据检查完成，partial 表示仍有缺口；根因和修复建议都需要结合证据判断。如果只拿到文件，没有报告，就让 Agent 检查观察子任务、导出状态和分析队列。采集脚本还活着，不代表 Agent 仍在处理事件。

第一次试用，可以先选一个已知的卡死操作：等 ready，再复现，确认能主动收到报告，并沿报告里的调用链找到代码。这个过程跑通后，再把它留在后台，用于日常调试。