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

工具能力 Tool capabilities

默认 37 个工具，开启设备与构建工具后 55 个。DitingAgent 向宿主提供这些工具。前半部分是每个工具能做什么，后半部分是宿主接入、预算与权限。 37 tools by default, 55 with device and build tools enabled. DitingAgent exposes these tools to the host. The first half covers each tool; the second covers host setup, budgets, and permissions.

会话与报告工具Session and report tools

这 6 个工具构成一次分析的生命周期。Trace 只转换一次，后续 run 复用会话中的数据库、能力和 EvidenceStore。These six tools make up the analysis lifecycle. A trace is converted once; later runs reuse the database, capabilities, and evidence store in the session.

open_trace
转换 HTrace、探测真实能力并创建（或复用）会话；同一目标重复打开是幂等的。Convert the HTrace, detect actual capabilities, and create or reuse a session. Reopening the same target is idempotent.
close_trace
关闭会话；purge_workspace=true 时删除转换工作区。Close the session; purge_workspace=true removes the conversion workspace.
list_traces
列出会话快照：Trace 能力、Evidence 数量、可用工具和分析进度。List session snapshots: capabilities, evidence count, available tools, and analysis progress.
begin_analysis
声明场景、现象和边界，创建分析上下文；返回预载证据、Skill、预算状态和场景预分析错误。Declare the scenario, symptom, and boundaries; create an analysis context and return preloaded evidence, skills, budget state, and preflight errors.
submit_analysis_result
提交语义 Draft；应用层执行证据约束、归一化和确定性校验，失败会返回可修正错误。Submit the semantic draft. The application enforces evidence constraints, normalisation, and deterministic validation; failures return fixable errors.
render_report
写出 findings、evidence、unknowns、validation 与 run 元数据，并渲染自包含 HTML 报告。Write findings, evidence, unknowns, validation, and run metadata, then render a self-contained HTML report.

长操作Long operations

3 个工具管理构建、抓取和安装长任务。任务在后台保留状态和 Evidence，不阻塞 Agent 主循环；可以查询、请求取消并读取产物。Three tools manage long build, capture, and install jobs. Jobs keep state and evidence in the background without blocking the agent loop, and can be inspected, cancelled, or read afterwards.

list_operations
列出当前进程中的 build / capture / install 长操作及其状态、进度和结果。List build / capture / install operations in the process with their state, progress, and results.
cancel_operation
请求取消一个长操作；构建会尽量终止 hvigorw 进程。Request cancellation of an operation; builds try to terminate the hvigorw process.
get_operation_evidence
读取 build / capture / install 长操作生成的 Evidence，用于后续校验和报告。Read evidence produced by an operation for later validation and reporting.

Trace 取证工具Trace inspection tools

16 个只读工具。调用时会检查当前 Trace 的能力、预算和输入契约；能力不足返回 CAPABILITY_MISSING。Sixteen read-only tools. Each call checks trace capability, budget, and input contract; missing support returns CAPABILITY_MISSING.

概览与边界Overview and boundaries

get_trace_overview
读取 Trace 元数据、进程、能力和 Perf 样本概况；通常作为第一次调用。Read trace metadata, processes, capabilities, and Perf sample overview; typically the first call.
compare_traces
对当前 Trace 与已注册基线做受限元数据对比。Compare the current trace with a registered baseline using a bounded metadata comparison.
query_trace_sql
对当前 Trace 的只读 SQLite 执行一条受限 SELECT / WITH 查询；有白名单、参数绑定、行数和超时限制。Run one restricted SELECT / WITH query against the read-only trace database, with allowlisting, bound parameters, row limits, and a timeout.
inspect_problem_window_candidates
从最后一次有效输入推导问题区间候选，支持给定持续时间；无显式边界时用于发现。Derive problem-window candidates from the last valid input, optionally with a duration; used for discovery when no explicit boundary exists.

进程、CPU、内存与 IOProcesses, CPU, memory, and IO

inspect_processes
列出 Trace 中的进程与线程：ipid、OS pid、进程名、主线程和线程角色；支持进程名或 PID 过滤，用于确定后续工具需要的 ipid/pid。List processes and threads in the trace: ipid, OS pid, process name, main thread, and thread roles. Filter by process name or PID to resolve the ipid/pid needed by later tools.
inspect_cpu
按窗口汇总 CPU 调度与负载：每线程 Running、状态分布、CPU 分布、Top 进程和可选的 cpu_usage 系统负载。Summarise CPU scheduling and load for a window: per-thread running time, state distribution, CPU distribution, top processes, and optional cpu_usage system load.
inspect_memory
汇总进程 RSS/VM/PSS、GPU 内存和系统内存采样；需要 memory preset 或包含 memory-plugin 的 Trace。Summarise process RSS/VM/PSS, GPU memory, and system memory samples; requires a memory preset or a trace containing memory-plugin data.
inspect_io
汇总整机磁盘读写、峰值速度和采样数；需要 io preset 或包含 diskio-plugin 的 Trace。Summarise disk reads/writes, peak throughput, and sample counts; requires an IO preset or a trace containing diskio-plugin data.

冷启动Cold start

inspect_cold_start_candidates
返回 Trace 范围、候选进程和主线程、真实的 app_startup 阶段、首帧候选和最早 Slice；不按固定 Marker 名称合成阶段。Return trace range, process and main-thread candidates, real app_startup stages, first-frame candidates, and earliest slices; stages are not synthesised from fixed marker names.
inspect_cold_start_timeline
在选定目标 ipid 后，围绕进程创建或后备锚点返回有界时间线：线程、浅层 Slice、跨进程 Slice、应用帧与 frame_maps 关系。After a target ipid is selected, return a bounded timeline around process creation or a fallback anchor: threads, shallow slices, cross-process slices, app frames, and frame_maps relations.

响应与完成Response and completion

inspect_completion_latency_candidates
寻找输入、首个响应、完成和动画结束候选；支持操作 Slice、开始/完成/响应 Marker、TouchUp/Pointer 输入、应用帧和 frame_maps。Find input, first-response, completion, and animation-end candidates; supports operation slices, start/completion/response markers, TouchUp/Pointer input, app frames, and frame_maps.
inspect_completion_latency_phases
在边界确认后，对响应阶段和响应后阶段做确定性取证：线程调度投影、Slice 热点、大帧、映射呈现帧和 Perf TID 范围。After boundaries are confirmed, gather deterministic evidence for response and post-response phases: thread scheduling projections, slice hotspots, large frames, mapped presentation frames, and Perf TID ranges.

帧、线程与 PerfFrames, threads, and Perf

inspect_frame_jank
按刷新率计算帧预算，识别 actual / expected 应用帧、产帧线程、慢帧、deadline miss、坏帧簇、有效 FPS 和 RS 映射帧。Derive the frame budget from refresh rate and identify actual/expected app frames, producer threads, slow frames, deadline misses, bad-frame clusters, effective FPS, and mapped RS frames.
inspect_frame
对单个应用帧做下钻：返回该帧应用线程的 Slice 热点、frame_maps 关联的 RenderService 帧与 Slice、线程调度投影，以及按刷新率计算的帧预算/超出量。frame_id 来自 inspect_frame_jank。Drill into one application frame: return slice hotspots on the frame's app thread, frame_maps-linked RenderService frames and slices, thread scheduling projection, and frame budget/overrun from refresh rate. The frame_id comes from inspect_frame_jank.
inspect_thread_execution
对精确区间内的单个关键线程做调度投影：状态时长、最长连续状态、CPU 分布、迁移、调度片和原始优先级。Project one critical thread within an exact interval: state durations, longest continuous state, CPU distribution, migrations, scheduler slices, and raw priority.
inspect_perf_profile
在精确问题窗口和进程/线程范围内聚合 Perf 样本：采集配置、样本权重、线程与 CPU 分布、符号化率、应用热点和调用上下文；只在存在真实 perf-samples 时开放。Aggregate Perf samples for a precise window and process/thread range: collection config, sample weights, thread and CPU distribution, symbolisation, app hotspots, and call context. Available only when real perf-samples exist.

工具返回确定性的摘要和 Evidence ID。超过内联预算时，完整数据保留在会话中，用 get_evidence 按路径和分页读取。Tools return deterministic summaries and Evidence IDs. Above the inline budget, the full payload stays in the session and is paged through get_evidence.

证据检索
与 bundleEvidence and
bundles

读取会话中的 Evidence；用 bundle 导出、合并和比较跨会话的证据快照。Read evidence in the session; use bundles to export, merge, and compare evidence snapshots across sessions.

list_evidence
列出会话内 Evidence 的 ID、工具、摘要和字节数，支持按工具过滤和分页。List Evidence IDs, tools, summaries, and byte sizes in the session, with optional tool filtering and paging.
get_evidence
按 Evidence ID 读取完整数据，或用点路径、offset、limit 分页读取大结果。Read the complete record by Evidence ID, or page a large result using a dot path, offset, and limit.
export_bundle
导出当前会话的完整 Evidence、unknowns 和目标 Trace SHA-256，写入带 canonical digest 的 JSON bundle。Export the session's complete evidence, unknowns, and target trace SHA-256 into a JSON bundle with a canonical digest.
import_bundle
校验 bundle digest 和目标 SHA-256 后合并记录；重复记录跳过，同 ID 不同内容报错，导入内容不执行。Verify the bundle digest and target SHA-256, then merge records. Duplicate records are skipped, conflicting content errors, and imported content is never executed.
compare_bundles
比较两个 bundle 的记录成员、目标摘要和 unknowns；缺失记录代表 omission，不证明行为等价。Compare record membership, target summaries, and unknowns across two bundles. Missing records are omissions and do not prove behavioural equivalence.

设备、构建
与环境（opt-in）Device, build
and environment (opt-in)

这 18 个工具只在启动 server 时带 --enable-device 才会出现。构建、签名和安装工具完成代码到设备的闭环；设备与抓取工具会真实操作设备；应用包与 native 库工具读取本地文件。它们不在 Trace evidence 预算内。These eighteen tools appear only when the server starts with --enable-device. Build, signing, and install tools close the loop from code to device; device and capture tools operate the device; app-package and native-library tools read local files. They sit outside the trace-evidence budget.

inspect_device
读取 HarmonyOS 设备、系统版本、API、ABI、已安装 Bundle 和可用 hitrace 类别。Read the HarmonyOS device, system version, API, ABI, installed bundles, and available hitrace categories.
inspect_screen
抓取截图并解析 uitest dumpLayout 控件树，返回文本、类型、bounds 和 center。Capture a screenshot and parse the uitest dumpLayout control tree, returning text, type, bounds, and center.
act
按元素选择器或坐标执行 tap、swipe、key、text、wait；会真实点击、滑动和输入。Run tap, swipe, key, text, and wait by element selector or coordinates; really taps, swipes, and types on the device.
pull_artifact
通过 hdc 从 /data/local/tmp/ 拉取 Trace、截图或日志，返回本地路径、大小和 SHA-256。Pull traces, screenshots, or logs from /data/local/tmp/ over hdc, returning the local path, size, and SHA-256.
capture_trace
用 hiprofiler_cmd 抓 Trace，支持 ui / startup / memory / io / network / full / perf preset；可在抓取期间执行 UI steps，默认抓完自动打开 Trace。Capture with hiprofiler_cmd using ui / startup / memory / io / network / full / perf presets. UI steps can run during capture, and the trace opens automatically by default.
inspect_environment
只读检查 hdc、Command Line Tools、ohpm / hvigor / Java / Node 和官方下载页；不安装、不修改环境。Read-only check of hdc, Command Line Tools, ohpm / hvigor / Java / Node, and the official download page; installs and modifies nothing.
install_environment
在 confirm=true 时把 Command Line Tools 安装到 ~/.diting/tools 并注册 hdc；URL 安装必须提供 SHA-256。With confirm=true, install Command Line Tools into ~/.diting/tools and register hdc. URL installs require a SHA-256.
inspect_app_package
读取应用的 codePath、nativeLibraryPath、HAP 路径和可读性；用户版本安装目录通常不可读，不绕过权限。Read the app's codePath, nativeLibraryPath, HAP paths, and readability. User-build install directories are often unreadable; permissions are not bypassed.
pull_app_library
尝试从应用 libs 或可读 HAP 中拉取 .so 到本地；权限不足返回 APP_PATH_DENIED。Try to pull a .so from app libs or a readable HAP; insufficient access returns APP_PATH_DENIED.
extract_native_libraries
从本地 HAP/HSP/ZIP 提取 libs/**/*.so，返回本地路径和 SHA-256。Extract libs/**/*.so from a local HAP/HSP/ZIP, returning local paths and SHA-256.
inspect_native_library
解析 ELF .so 的架构、依赖、build-id 和符号；完整反编译和调用图交给 REA。Inspect ELF .so architecture, dependencies, build-id, and symbols; full decompilation and call graphs go to REA.
inspect_abilities
从本地 module.json5/app.json5 或设备 bm dump 读取 Bundle、module、Ability 和 launcher ability。Read bundle, module, abilities, and the launcher ability from local module.json5/app.json5 or device bm dump.
clear_app_data
通过 aa force-stop + bm clean 清除应用 data/cache，可分别控制。Clear app data/cache through aa force-stop + bm clean, with separate controls.
sign_app
用 hap-sign-tool 对 HAP/HSP 做 localSign，可选 verify-app；密码不回显。Use hap-sign-tool to localSign a HAP/HSP with optional verify-app; passwords are never echoed.
build_app
用 hvigorw assembleHap 构建 HarmonyOS 工程并返回 HAP 产物。Build a HarmonyOS project with hvigorw assembleHap and return the HAP artifact.
package_app
用 hvigorw assembleApp 打包 App Pack 并返回 .app 产物。Package an App Pack with hvigorw assembleApp and return the .app artifact.
install_app
通过 hdc install 安装本地 .hap/.hsp/.app。Install a local .hap/.hsp/.app through hdc install.
uninstall_app
通过 hdc uninstall 卸载应用，可选择保留数据。Uninstall an app through hdc uninstall, optionally keeping its data.

构建与设备工具需要 hdc、Command Line Tools 和 HarmonyOS 工程；签名还需要 keystore、证书和 profile。开启前先看 安装页的设备与构建步骤；完整参数和错误码见 权限边界。Build and device tools need hdc, Command Line Tools, and a HarmonyOS project; signing also needs a keystore, certificate, and profile. See the device and build setup steps before enabling them; see integration boundaries for configuration and error codes.

未知与 handoffUnknowns and handoff

把未解决的问题留下，把一次会话的状态带走；恢复时仍以 Evidence 和 revision 为准。Leave unresolved questions behind and carry a session state forward; restoration still follows evidence and revisions.

record_unknown
记录一个残余未知项，生成稳定 unknown_id 和不可变 mutation evidence；校验所有 Evidence 引用。Record a residual unknown, generate a stable unknown_id and immutable mutation evidence, and validate every evidence reference.
update_unknown
按 expected_revision 追加一次完整状态修订；revision 过期时拒绝覆盖。Append a complete state revision using expected_revision; stale revisions are rejected instead of overwritten.
list_unknowns
按状态、严重级别和领域列出残余未知项，支持分页。List residual unknowns by status, severity, and domain, with paging.
verify_unknown
用当前 Evidence 校验未知项的引用和 resolution；标记 resolved 时必须存在 supporting evidence。Validate evidence references and a resolution against current evidence; a resolved item requires supporting evidence.
snapshot_session
把会话 Evidence、unknowns、分析结果和链路状态写成带 digest 的 handoff 快照。Write session evidence, unknowns, analysis results, and chain state to a digest-bearing handoff snapshot.
resume_session
读取 handoff，按目标 SHA-256 复用或重开 Trace，并恢复 Evidence、unknowns 与分析结果；不执行导入内容。Read a handoff, reopen or reuse the trace by target SHA-256, and restore evidence, unknowns, and analysis results; imported content is never executed.
load_handoff
只读取 handoff 的目标、分析结果和限制，不打开 Trace 会话。Read the handoff target, analysis results, and limitations without opening a trace session.

接入宿主 Connect a host

需要 Node.js 18+ 和 Python 3.12+；npx 首次运行会准备环境。先检测宿主，再写入配置并运行健康检查。 Node.js 18+ and Python 3.12+ are required; the first npx run prepares the environment. Detect the host, write its config, then run the health check.

terminal / bash 
# 1. detect the host
npx diting-agents@latest setup --detect

# 2. register and verify
npx diting-agents@latest setup --client dsh --yes --allow-root ~/traces
npx diting-agents@latest doctor

# 3. or run the stdio server manually
npx diting-agents@latest mcp \
  --workspace .diting/sessions \
  --allow-root ~/traces

其他宿主可以用 setup --client generic 打印通用 JSON；Windows、macOS 和 Linux 使用同一条 npx 命令。 For other hosts, setup --client generic prints a JSON configuration. Windows, macOS, and Linux use the same npx command.

完整安装与接入步骤Full installation and setup

01 DeepSeek Harness 宿主 Agent 循环、模型和工具选择。Host agent loop, model, and tool selection.
02 Claude Code 通过宿主配置直接发现工具。Discover tools directly through host config.
03 Codex 把取证交给 server，把解释留给模型。Server handles evidence; the model explains.
04 其他 宿主Other hosts 通过通用 JSON 接入。Connect through the generic JSON config.

会话复用与转换缓存 Session reuse and conversion cache

01open_trace转换、探测能力、创建会话。Convert, detect capabilities, create session.
02begin_analysis声明场景、现象、边界和预算。Declare scenario, symptom, boundary, and budget.
03inspect_*按能力取证，返回摘要和 Evidence ID。Inspect by capability; return summaries and Evidence IDs.
04submit提交语义 Draft，执行确定性校验。Submit the semantic draft; run deterministic validation.
05render_report写出 findings、evidence、unknowns、validation 和 HTML。Write findings, evidence, unknowns, validation, and HTML.

缓存与复用Caching and reuse

同一个会话内，转换后的只读 DB、能力声明和 EvidenceStore 跨 run 复用。未调用 begin_analysis 时，每次工具调用使用独立的 run 级预算；开始分析后，预算和 seal 在整次分析内共享。 Within one session, the read-only database, capability declaration, and evidence store are reused across runs. Before begin_analysis, each tool call gets an independent run-scoped budget; during analysis, budget and seal are shared across the whole analysis.

会话 TTL 与容量Session TTL and capacity

默认空闲 TTL 为 1440 分钟，最多保留 8 个会话；close_trace(purge_workspace=true) 立即删除转换工作区。历史目录可以用 diting-agent clean 清理。 Default idle TTL is 1440 minutes with a maximum of 8 sessions. close_trace(purge_workspace=true) removes the conversion workspace immediately; historical directories can be cleaned with diting-agent clean.

结果预算与 Evidence Result budgets and evidence

单次结果超过 --max-result-bytes（默认 64 KB）时，宿主只拿到摘要、字节数和 Evidence ID。完整数据仍在会话中，可以用点路径、offset 和 limit 分页读取。 When a result exceeds --max-result-bytes (64 KB by default), the host receives a summary, byte count, and Evidence ID. The complete payload remains in-session and can be paged by dot path, offset, and limit.

64KB inline default
1440min session TTL
08max sessions
oversized result / envelopeBOUNDED

{

  "evidence_id": "ev-0007",

  "summary": "4 frame clusters, 17 slow frames",

  "data_bytes": 18342,

  "full_evidence_persisted": true,

  "read_with": "get_evidence"

}

01evidence id
∞pages available
00silent truncation
read / paginate 
get_evidence(
  evidence_id="ev-0007",
  path="clusters",
  offset=0,
  limit=50
)

设备、构建与权限边界 Device, build, and permissions

DitingAgent 继承启动用户的文件权限，没有额外沙箱。设备与构建工具默认关闭；一旦开启，它们会真实操作设备、构建工程或写入签名产物。 DitingAgent inherits the launching user’s file permissions and has no extra sandbox. Device and build tools are off by default; once enabled, they really operate the device, build projects, or write signing artifacts.

01 路径白名单Path allowlist 生产环境至少用 --allow-root 指定 Trace 目录。In production, point --allow-root at the trace directory at minimum.
02 设备操作需要显式开启Device actions are opt-in act 会真的 tap / swipe；pull_artifact 会读取设备文件。act really taps and swipes; pull_artifact reads device files.
03 环境安装要确认Environment installs need confirmation install_environment 只有 confirm=true 才解压写入，URL 必须带 SHA-256。install_environment only writes with confirm=true; URL installs require a SHA-256.
04 关闭会话，清理工作区Close the session, purge the workspace 用 close_trace(purge_workspace=true)，或按 TTL / 容量自动淘汰。Use close_trace(purge_workspace=true), or let TTL and capacity evict sessions.

宿主拥有 Agent 循环、模型选择和用户审批；DitingAgent 拥有 Trace 转换、取证、Evidence、校验和报告。设备与构建工具始终需要显式开启。 The host owns the agent loop, model choice, and user approvals. DitingAgent owns build/sign/install execution, trace conversion, inspection, evidence, validation, and reporting. Device and build tools always require an explicit opt-in.