HarmonyOS App Performance Analysis
npm ↗ GitHub ↗
Diting
安装Install
GitCode ↗

从代码到报告，
端到端闭环。 From code to report,
an end-to-end loop.

DitingAgent 的工作流覆盖改代码、构建、签名、安装、启动、抓 Trace 和分析；也可以从已有 HTrace 开始。两条路径最终进入同一套转换、边界、取证、校验和报告流程。 DitingAgent connects edit, build, sign, install, launch, trace capture, analysis, and reporting into one loop. Start from a code change or an existing HTrace.

七个阶段，一条闭环。Seven stages, one loop.

不是一串独立工具：上一阶段的产物直接成为下一阶段的输入，报告结果又回到宿主 Agent，驱动下一次改动。This is not a row of separate tools: each stage feeds the next, and the report returns to the host agent to drive the next change.

  1. 01 改代码Edit code 宿主 AgentHost agent project
  2. 02 构建Build DitingDiting build_app
  3. 03 签名Sign DitingDiting sign_app
  4. 04 安装Install DitingDiting install_app
  5. 05 启动Launch Agent / DitingAgent / Diting act · launch_app
  6. 06 抓 TraceCapture DitingDiting capture_trace
  7. 07 分析并报告Analyze + report Agent / DitingAgent / Diting open_trace → render_report

报告结果回到宿主 Agent，决定下一次代码改动。The report returns to the host agent and drives the next code change.

两种起点Two starting points

从一次代码改动开始时，Agent 可以构建、签名、安装并启动应用，再抓 Trace；如果已有 HTrace，直接进入分析。 When starting from a code change, the agent can build, sign, install, and launch the app before capturing a trace. With an existing HTrace, start directly at analysis.

改代码 → 构建、签名与安装Code change → build, sign, install

需要 --enable-device。Agent 可以修改工程，用 build_app、sign_app 和 install_app 完成构建、签名与安装；package_app 可生成 App Pack。随后启动应用并在目标交互期间抓 Trace。 Requires --enable-device. The agent edits the project, uses build_app, sign_app, and install_app to build, sign, and install it, can use package_app for an App Pack, then launches the app and captures a trace around the target interaction.

01buildbuild_app
02signsign_app
03installinstall_app
04capturecapture_trace

构建、签名和安装需要 HarmonyOS 工程、hvigor 与签名材料；这些工具默认关闭。Build, signing, and install need a HarmonyOS project, hvigor, and signing assets; these tools are opt-in.

构建与设备工具Build and device tools

Agent 会话分析Agent session analysis

把 Trace 交给 Agent 会话；宿主通过 open_trace 打开，再用 begin_analysis 声明场景和边界。转换后按场景选择工具，不需要重新抓取。 Hand the trace to an agent session. The host opens it with open_trace, then declares the scenario and boundary with begin_analysis. After conversion, tools are selected by scenario; no re-capture is needed.

tool callshost agent
open_trace("case.htrace")

begin_analysis(
  scenario_type="frame-jank",
  scenario="scroll list",
  symptom="repeated dropped frames",
  refresh_rate_hz=120
)
工具与流程Tools and workflow

设备路径：屏幕、操作与抓取Device path: screen, actions, capture

设备工具让 Agent 读取屏幕、按控件操作真机、复现交互，并在正确的时间窗口启动 hiprofiler。 Device tools let the agent read the screen, drive the real UI by element, reproduce an interaction, and start hiprofiler in the right window.

01

确认设备与能力Check device and capabilitiesinspect_device

读取 HarmonyOS 版本、API、ABI、Bundle 和 hitrace 类别。先确认设备在线，避免在错误目标上抓取。Read HarmonyOS version, API, ABI, bundles, and hitrace categories. Confirm the device is online before capturing on the wrong target.

02

看当前界面Inspect the current screeninspect_screen

返回截图和 uitest dumpLayout 控件树，包含文本、类型、bounds 和 center。Agent 据此选择要操作的控件。Returns a screenshot and the uitest dumpLayout tree with text, type, bounds, and center. The agent uses it to choose a target.

03

按控件操作Act on UI elementsact

按顺序执行 tap、swipe、key、text 和 wait，支持元素选择器或坐标。它会实际执行点击、滑动和输入。Runs tap, swipe, key, text, and wait in sequence, using element selectors or coordinates. It performs tap, swipe, and text input on the device.

04

在操作期间抓 TraceCapture during the interactioncapture_trace

用 hiprofiler_cmd 抓 ftrace 和可选 hiperf samples，可在抓取期间继续执行 UI steps；默认抓完自动打开 Trace。采集时长会按 steps 自动延长。Uses hiprofiler_cmd for ftrace and optional hiperf samples; UI steps can run during capture, and the trace opens automatically by default. Capture time extends to fit the steps.

设备工具默认关闭，并且不在 Trace evidence 预算内。它们会真实操作设备；执行前应确认目标、动作和可回退路径。设备能力与命令语法随 HarmonyOS 版本变化。Device tools are off by default and sit outside the trace-evidence budget. They really operate the device; confirm the target, action, and recovery path first. Device capabilities and command syntax vary by HarmonyOS version.

分析流水线Analysis pipeline

转换、边界、取证、校验和报告是确定性的应用层流程。Agent 在存在业务语义分歧的地方做判断。 Conversion, boundaries, inspection, validation, and reporting are deterministic application-layer steps. The agent makes the calls where business semantics are ambiguous.

01

转换与能力探测Convert and detect capabilitiesopen_trace

HTrace 经 TraceStreamer 转成 SQLite，再检查真实表结构。只有存在实际数据的能力才会开放，例如帧、调度、Marker 或 Perf。HTrace is converted to SQLite by TraceStreamer, then the actual schema is inspected. A capability opens only when real data exists — frames, scheduling, markers, or Perf.

02

固定问题边界Fix the problem boundarybegin_analysis

优先级为显式 time_range、唯一 Marker 对、场景语义边界，最后才是最后输入加持续时间。冷启动还会区分进程复用和稳定首页。Priority: explicit time_range, a unique marker pair, scenario semantics, then last input plus duration. Cold start additionally separates process reuse from a settled home page.

03

按场景取证Inspect by scenarioinspect_*

工具面包含 16 个 Trace 取证工具，按能力开放；每个结果都有预算、摘要和 Evidence ID。大结果留在会话里，用 get_evidence 按路径和分页读取。The surface includes 16 trace inspection tools, gated by capability. Every result has a budget, summary, and Evidence ID. Large results stay in-session and are paged with get_evidence.

04

提交并校验 DraftSubmit and validate the draftsubmit_analysis_result

应用层检查数值、证据引用、边界、限制条件和结论强度。不通过时返回可修正的错误。The application checks values, evidence references, boundaries, limitations, and claim strength. A failed draft returns a fixable error.

05

生成可带走的报告Render a portable reportrender_report

输出 self-contained report.html，并保留 findings、evidence、validation 和 run 元数据。报告可以离线打开，也可以直接归档。Writes a self-contained report.html and keeps findings, evidence, validation, and run metadata. The report opens offline and can be archived directly.

场景边界与指标 Scenario boundaries and metrics

场景Scenario 开始Starts at 结束Ends at 常见误判Common pitfalls
COLD START 新进程创建new process creation 应用定义的启动完成 / 稳定首页帧app-defined startup end / stable home frame 进程复用、最早出现的帧process reuse, the earliest frame
RESPONSE 有效输入valid input 第一帧有效反馈first effective frame 完整动作、业务完成full action, business completion
COMPLETION 输入 / 操作 Slice 起点input / operation slice start 业务完成business completion 动画结束、帧空档、窗口末帧animation end, frame gap, last frame
FRAME JANK 显式窗口 / 交互区间explicit window / interaction interval 窗口结束window end 整个 RenderService 的负载all RenderService load

四类场景都可以分析已有 HTrace。开启设备工具后，也可以让 Agent 先用 inspect_screen 和 act 操作手机，再用 capture_trace 在交互期间抓取。 All four scenarios work with an existing HTrace. With device tools enabled, the agent can first inspect and operate the phone, then use capture_trace around the interaction.

查看设备路径See the device path

01

从进程创建，
到稳定首页。 From process creation
to a stable home page.

STARTUP

冷启动分析先确认目标进程是新建进程，并排除进程复用；随后找到应用自己的启动完成语义。最早呈现的帧、第一个 Slice 或首页出现，都不自动等于启动完成。 Cold-start analysis first proves the target process is new, rules out process reuse, then finds the app’s own startup-completion semantics. The earliest presented frame, the first slice, or the home page appearing are not automatically the end.

要回答什么The question

从进程创建到用户真正可以使用的首页稳定态，时间花在了哪里？主线程、启动阶段、加载器、渲染和首帧之间的关系是什么？ From process creation to a home page the user can actually use, where did the time go? How do the main thread, startup stages, loaders, rendering, and the first frame relate?

取证关注What gets inspected

  • 进程创建、同名进程和主线程身份。Process creation, same-name processes, and main-thread identity.
  • 直接读取的 app_startup 阶段，避免按名字合成。Real app_startup stages read from the trace, without inventing stages from marker names.
  • 应用帧、首帧候选和 frame_maps 映射。App frames, first-frame candidates, and frame_maps relationships.
  • 包名相关的跨进程 Slice、加载器和根 Slice。Package-related cross-process slices, loaders, and root slices.
Start新进程创建，拒绝进程复用。New process creation; reject reuse.
End应用自定义启动完成，或稳定的首页帧。App-defined startup completion, or a stable home frame.
Guardrail首帧只用于发现；确认“首页稳定”需要额外证据。The first frame is discovery only; a stable home page needs additional evidence.
Toolsinspect_cold_start_candidates
inspect_cold_start_timeline
02

响应时延：输入到
第一帧反馈 Response latency: input to
the first frame

INPUT → FEEDBACK

响应时延回答“用户有没有立刻看到反应”。它从有效输入开始，在第一帧包含可见反馈时结束。页面跳转完成、动画消失或数据全部落位，属于完成时延，不属于响应时延。 Response latency answers “did the user see a reaction immediately?” It starts at valid input and ends at the first frame containing visible feedback. A finished navigation, a finished animation, or fully loaded data belongs to completion — not response.

要回答什么The question

输入有没有被接收？应用线程和渲染线程之间，是哪一段让用户觉得“没反应”？首个有效帧是绘制出来的，还是只产生了一个空帧？ Was the input received? Which part of the app and render pipeline makes the interface feel unresponsive? Was the first effective frame actually presented, or merely produced as an empty frame?

取证关注What gets inspected

  • Touch / Pointer / Click 输入打点与生效时间。Touch, pointer, or click input events and their effective timestamps.
  • 应用实际帧、RS 映射帧和首帧候选。Actual app frames, RS-mapped frames, and first-frame candidates.
  • UI 线程在输入后的调度、长 Slice 和关键调用。UI-thread scheduling after input, long slices, and critical calls.
  • 输入到手势回调、布局、绘制和提交的链路。The chain from input to gesture callback, layout, draw, and submit.
Start有效用户输入。A valid user input.
End第一帧包含有效视觉反馈。The first frame with effective visual feedback.
Guardrail响应与完成分开计算；有效反馈需要可见变化，空帧不计入。Response and completion are measured separately; effective feedback requires a visible change, so empty frames do not count.
Toolsinspect_completion_latency_candidates
inspect_thread_execution
inspect_frame_jank
03

完成时延：输入到
业务完成 Completion latency: input
to business completion

INPUT → BUSINESS END

完成时延必须拆成输入到有效反馈、反馈后到业务完成、输入到业务完成三段。没有应用完成语义时，动画结束、帧静止和窗口最后一帧只能作为发现候选，不能单独证明 completion_proven。 Completion latency splits into input-to-response, post-response work, and input-to-business-end. Without app completion semantics, animation end, quiet frames, and the last frame in the window are discovery candidates only — none of them alone can prove completion_proven.

要回答什么The question

用户看到反馈之后，应用还在做什么？业务完成是由一个唯一、正 duration 的操作 Slice 定义，还是由应用显式 Marker 定义？反馈后阶段的主线程、调度、I/O 和渲染，谁在拖长尾？ After the user sees feedback, what is the app still doing? Is business completion defined by a unique positive-duration operation slice or an explicit marker? In the post-response phase, which main-thread work, scheduling, I/O, or rendering extends the tail?

取证关注What gets inspected

  • 唯一操作 Slice 的 [ts, ts+dur]，以及开始/完成 Marker。The unique operation slice’s [ts, ts+dur], plus start and completion markers.
  • 有效响应点、应用实际帧和映射呈现帧。The effective response point, actual app frames, and mapped presented frames.
  • 反馈后阶段的线程调度、热点 Slice 和大帧。Post-response thread scheduling, slice hotspots, and large frames.
  • Perf 样本用于印证长尾工作；时间线仍是主证据。Perf samples corroborate the tail; the timeline remains the primary evidence.
Start输入生效，或操作 Slice 起点。Effective input, or operation-slice start.
End应用声明的业务完成。App-declared business completion.
Guardrail动画结束、帧空档和窗口末帧只作为候选；完成需要应用语义或明确 Marker。Animation end, frame gaps, and the last frame are candidates; completion needs app semantics or an explicit marker.
Toolsinspect_completion_latency_candidates
inspect_completion_latency_phases
inspect_perf_profile
04

帧率与卡顿：
预算与慢帧 Frame rate and jank:
budget and slow frames

REFRESH-AWARE

帧预算按当前显示刷新率计算，不采用固定 60 Hz。分析会识别实际应用帧和期望帧、慢帧簇、deadline miss，以及通过 frame_maps 严格关联的 RenderService 帧；它不会把整个 RenderService 的负载直接算到目标应用头上。 The frame budget comes from the actual display refresh rate. Analysis identifies actual and expected app frames, slow-frame clusters, deadline misses, and strictly mapped RenderService frames. It does not attribute all RenderService load to the app under test.

要回答什么The question

窗口内的有效 FPS 是多少？哪些帧超出了预算？坏帧是孤立的还是成簇的？产帧线程、渲染管线和应用主线程之间，哪一段最接近可见卡顿？ What is the effective FPS in the window? Which frames exceed the budget? Are bad frames isolated or clustered? Which part of the producer-thread, render-pipeline, and main-thread chain is closest to the visible jank?

取证关注What gets inspected

  • 刷新率、帧预算、actual / expected 应用帧。Refresh rate, frame budget, actual and expected app frames.
  • 慢帧、deadline miss、坏帧簇和有效 FPS。Slow frames, deadline misses, bad-frame clusters, and effective FPS.
  • 产帧线程候选、活跃渲染区间和 RS 映射帧。Frame-producer candidates, active render intervals, and RS-mapped frames.
  • 窗口内关键线程调度、长 Slice 与 Perf 热点。Critical-thread scheduling, long slices, and Perf hotspots within the window.
Window显式区间，或一次有界交互。An explicit interval, or one bounded interaction.
Budget按实际刷新率推导。Derived from the actual display refresh rate.
Guardrail200 ms 帧空档只用于发现；应用根因需要应用线程与帧映射证据。A 200 ms frame gap is discovery only; an app root cause needs app-thread and frame-mapping evidence.
Toolsinspect_frame_jank
inspect_thread_execution
inspect_perf_profile

边界应作为分析结果记录。每一条结论都应该能回答：从什么时候开始，到什么时候结束，为什么是这里。 The boundary is part of the analysis result. Every finding should answer: where did it start, where did it end, and why there?

应用层与 Agent 的职责Application and agent responsibilities

应用层Application layer

  • 转换 Trace、声明能力、执行有界查询与统计。Convert traces, declare capabilities, run bounded queries and statistics.
  • 保存完整 Evidence，投影有界摘要。Persist complete evidence and project bounded summaries.
  • 校验数值、边界、引用和最终报告。Validate values, boundaries, references, and the final report.

模型Model

  • 在候选边界中选择符合业务语义的那个。Choose the boundary that matches business semantics.
  • 决定下一步调用哪个取证工具。Decide which evidence tool to call next.
  • 关联证据，写出解释、置信度和建议；提交的是 Draft。Relate evidence and write the explanation, confidence, and advice — submitted as a draft.

宿主模型不重新计算线程分布、CPU 状态、唤醒链或 Perf Profile；这些确定性对象由应用层从 Evidence 合并。模型通过 工具读取 Trace，不能绕过工具访问原始数据库。The host model does not recompute thread profiles, CPU states, wake-up chains, or Perf profiles; the application merges those objects from evidence. The model reads the trace through tools and cannot access the raw database directly.

安装与第一次运行Installation and first run