0.0.5 • Published 9h agoCLI

dyn-hyperstartup-checker

Licence

MIT

Version

0.0.5

Deps

Size

492 kB

Vulns

Weekly

Summary Dependency Versions

dyn-hyperstartup-checker

面向 Harmony/OpenHarmony 超启动联调 的采集与分析 CLI：通过 hdc 清理环境、拉取日志、并行执行 hitrace / hiperf 采样，并在本机解码 perf、去重与导出调用栈。

主场景为 report-user：面向无 hidumper / revoke_switch 权限的设备，按 checkpoint 风险目标采集 trace/perf，可选 hstack 与 sourcemap 解析，输出 dump_stack.* 与交互报告 trace_report.html。使用 --app 时必须同时指定 --ability。

默认行为

主场景 report-user：--trace-from 默认为 mix（init 探测平台是否支持 --raw-data，不支持时回退 hitrace；analysis 预处理 hitrace 并使用 perfFirst sidecar）。
日志格式为行首 [ISO8601] {级别} {正文}；环境变量 DYN_HYPERSTARTUP_CHECKER_LOG_LEVEL / LOG_LEVEL 可设默认级别。
采集与 workspace 中间产物文件名使用 hyperstart_ 前缀（如 hyperstart_hitrace.txt）。
若需 analysis 优先 hitrace 侧车，显式传入 --trace-from hitrace。

前置条件

Node.js ≥ 18。
PATH 中可用 hdc，并已连接目标设备。
本机 analysis 依赖（随包安装）：hiperf_txt_parser ^2.3、hmtrace-parser ^0.11、hm-pt-core ^2.1、hm-trace-report ^0.1。

安装

直接安装（推荐）

npm install -g dyn-hyperstartup-checker
dyn-hyperstartup-checker --help
dyn-hyperstartup-checker report-user --help

全局命令 dyn-hyperstartup-checker 即 CLI 入口。

本地构建

用于开发本仓库或联调未发布改动：

git clone <仓库地址>
cd dyn-hyperstartup-checker
npm install
npm run build
npm start -- report-user --help     # 或: node dist/src/cli.js report-user --help

开发时可跳过构建，直接用源码：

npm run dev -- report-user --help

面向无 hidumper / revoke_switch 权限的设备用户：checkpoint 镜像失效等风险的专项采集与分析。按 --risk-targets 选择 hiperf 事件；analysis 阶段可选用 hstack、sourcemap，并通过 --trace-format-profile 配置 trace 解码。额外要求 --ability（与 --app 配合，用于 aa start -a 启动应用）。

init：不执行 hidumper / revoke_switch；aa start + aa force-stop 管理应用；探测 hiperf --raw-data；非 debug 应用直接失败。
monitor / collect / filter：不依赖 apppool_pids；hiperf 使用 --app；monitor 延迟 30s 写入 target_tgid，collect 读取，filter 按 tgid 过滤。

--trace-from 同时影响采集（hiperf 是否 --raw-data）与 analysis（是否读 hyperstart_hitrace.txt、如何与 perf 样本合并）；详见下文「analysis 阶段 trace 解码」。

执行阶段（defaultGroupOrder，无 restore）

阶段	说明
`init`	remount、清理、`aa start` / `aa force-stop`、raw-data 探测等
`monitor`	`hitrace` + `hiperf record`（事件由风险目标推导；risk collect 与 hiperf dump 拆分）
`collect`	读取 target_tgid，从设备拉取 perf、hitrace 到 `--output-dir`
`filter`	按目标进程（tgid）过滤 perf
`analysis`	解码 trace、可选 `backtrackFS`、去重，导出 `dump_stack.*` 与 `trace_report.html`

analysis 阶段 trace 解码

analysis 通过 src/lib/pipeline.ts 的 pipeline 执行，trace 解码由 src/lib/perf_decode.ts 编排（不再在 checker 内逐样本循环）：

按 --trace-format-profile（或 auto 时从设备读取的 format）构建 trace registry；--event-match-mode 控制 event ID 匹配（strict / nearest）。
若 --trace-from 为 hitrace 或 mix：解析 workspace/hyperstart_hitrace.txt 并构建索引；hiperf 时由 decoded perf 合成 hitrace。
调用 hiperf_txt_parser 的 decodePerfRawData；导出 trace_report.html（Hitrace + Hiperf 交互，经 hm-trace-report）；再可选 backtrack / dedupe，写 dump_stack.*。

--trace-from 与 hitrace sidecar 策略（analysis；init 探测后可能写入 effective_trace_from）

`--trace-from`	是否预处理 hitrace	sidecar 策略	说明
`mix`（默认）	是	`perfFirst`	先解码 perf raw，失败类样本再查 hitrace 索引
`hitrace`	是	`hitraceFirst`	有对齐快照则先 apply hitrace，成功则跳过 perf raw 解码
`hiperf`	合成	`perfOnly`	解码 perf 后合成 hitrace（`hyperstart_hitrace.from_perf.txt`）并导出 HTML

采集：hitrace 时 hiperf record 不带 --raw-data；hiperf / mix 时带 --raw-data（平台不支持时 init 回退为 hitrace）。

风险目标 --risk-targets

逗号分隔，默认 all。可选：all、backtrack（失效回溯）、direct（直接失效）。

key	展示名	hiperf 事件
`backtrack`	失效回溯	`checkpoint:vfs_snapshot_dump_monitor`
`direct`	直接失效	`checkpoint:checkpoint_revoked`

主要选项

选项	说明
`--app <app>`	应用包名（须为 debug 构建）
`--ability <ability>`	应用 Ability 名称（`aa start -a`），与 `--app` 必填
`--app-start-wait <seconds>`	init 阶段 `aa start` 后等待秒数，默认 `20`；`0` 跳过
`--risk-targets <targets>`	风险事件类型，默认 `all`
`--trace-from <source>`	采集：hiperf record 是否 `--raw-data`。analysis：sidecar / 合成策略（见上表）
`--hiperf-stack-mode <mode>`	`fp`（默认）或 `dwarf`（附加 `--delay-unwind`）
`--hitrace-tag <tags>`	额外 hitrace tag，逗号分隔（与 hyperstart 合并）
`--trace-from-threshold <ms>`	hitrace/perf 对齐阈值（毫秒）；未配置不校验；`--trace-from hiperf` 时忽略
`--trace-from-threshold-opt <onExceed>`	超出对齐阈值时：`drop`（默认）或 `ignore`；`hiperf` 时忽略
`--hstack-tool-path <path>`	hstack 可执行文件；不配置则跳过
`--sourcemap-dir <path>`	传给 hstack 的 `-s`
`--log-key <key>`	hilog 过滤字段，默认 `pid`
`--duration <seconds>`	采集时长（秒），默认 `70`
`--backtrack-delay <seconds>`	monitor 后台检测延迟，默认 `80`
`--risk-collect-wait <seconds>`	开始采集前等待，默认 `0`
`--buffer-size <bytes>`	hitrace 缓冲区，默认 `512000`
`--output-dir <path>`	输出根目录，默认 `./output`
`--trace-format-profile <name>`	trace 解码 profile，默认 `default`；可用 `auto` 从设备 format 读取
`--event-match-mode <mode>`	event ID 匹配：`strict`（默认）或 `nearest`
`--keep-decoded-perf`	保留解码后中间 perf（`_hyperstart_perf.trace_decoded.txt`）
`--filter-hitrace`	按 target_tgid 过滤并导出 `hyperstart_hitrace.filtered.txt`
`--skip-perf-dedupe`	跳过 `dedupePerfData`
`--skip-backtrack`	跳过 `backtrackFS`（不影响采集）
`--skip-non-backtrack`	`backtrackFS` 使用 `keepNonFsRevoked: false`
`--drop-failed-samples`	丢弃无 trace 解析器的 raw 样本

全局选项（对各子命令均生效）

选项	说明
`--hdc-target <sn>`	全部 `hdc` 命令加 `-t <sn>`
`--parse-concurrency <n>`	perf 加载与 trace 解码的 Worker 数，默认 `1`；`profile=auto` 且 format 含主线程 `transformFieldDict` 时解码回退单线程
`--log-file [path]`	日志追加写文件；省略 path 时写入 `<output-dir>/workspace/checker.log`
`--log-level <level>`	日志级别；未设则读 `DYN_HYPERSTARTUP_CHECKER_LOG_LEVEL` / `LOG_LEVEL`，默认 `info`

使用方式

建议按「预览 → 执行」顺序操作：

--list：按 group 列出将要执行的命令，不创目录、不连设备执行（与集成测试 report-user --list 不创建 workspace 与 perf_txt 一致）。
--dry-run：按默认阶段顺序列出完整命令序列，同样不创目录。
正式运行：省略上述开关，按 init → monitor → collect → filter → analysis 依次执行。

只跑部分阶段时，用 -g / --group 指定，例如 -g init,monitor 或 -g collect,filter,analysis。

控制台输出

运行前摘要（--dry-run 与正式运行均会打印， --list 时不打印）：

ℹ [trace-from] mix
ℹ [风险目标] 失效回溯、直接失效
ℹ [backtrack] 保留非 FS revoked

含义：--trace-from 当前取值（采集 raw-data 与 analysis sidecar 策略均据此）、已选风险目标、是否执行 backtrackFS 及过滤策略。

--list 输出格式（节选）：

[report-user] 场景命令（按 group 展示）:

Group: init
    [mac] hdc shell remount — hdc shell remount
    ...
Group: monitor
    [mac] [background] hdc shell "hilog -t kmsg | grep pid" >> ./output/workspace/hyperstart_log.txt — 收集日志到本地
    ...

--dry-run 输出格式（节选）：

(dry-run) [report-user] 将要执行的命令:

  1. [mac] hdc shell remount — hdc shell remount
  ...
  13. [mac] hdc shell "hitrace hyperstart ... & hiperf record ... & wait" — 收集风险事件数据
  14. [mac] hdc shell "hiperf dump -i ... -o ..." — 导出 hiperf 采集数据
  ...
  22. [builtin] [func:func] — 风险栈解码

正式执行时，每条命令还会输出进度行，例如 ▶ (13/22) [mac] 收集风险事件数据，结束后打印 退出码 与耗时。

输出目录

成功跑完 --output-dir ./output（默认）后，典型结构如下：

output/
├── dump_stack.txt          # 最终调用栈（文本）
├── dump_stack.json         # 同上（JSON）
├── dump_stack.xlsx         # 同上（Excel）
├── trace_report.html       # Hitrace/Hiperf 交互报告（file:// 可打开）
├── perf_txt/
│   └── hyperstart_perf.data.txt    # 设备 hiperf dump 文本
└── workspace/              # 中间产物
    ├── hyperstart_log.txt    # hilog 采集
    ├── hyperstart_hitrace.txt
    ├── hyperstart_hitrace.from_perf.txt   # --trace-from hiperf 时合成
    ├── hyperstart_hitrace.filtered.txt    # --filter-hitrace 时
    ├── _hyperstart_perf.trace_decoded.txt # --keep-decoded-perf 时
    ├── perf.data
    └── _hyperstart_perf.data.txt          # hstack 解析后 perf（若配置了 hstack）

未配置 --hstack-tool-path 时，analysis 阶段会跳过 hstack，日志出现 [hstack] 未配置，跳过解析，直接使用 perf_txt/hyperstart_perf.data.txt 解码。

示例

预览完整流水线（不创目录）

dyn-hyperstartup-checker report-user --dry-run --app com.example.app --ability EntryAbility --output-dir ./output

默认 --trace-from mix：monitor 将 risk collect 与 hiperf dump 拆成两条命令，例如：

# 收集风险事件数据
hitrace hyperstart ... & hiperf record --raw-data -e checkpoint:... -s fp ... -d 70 & wait
# 导出 hiperf 采集数据
hiperf dump -i /data/local/tmp/perf.data -o /data/local/tmp/hyperstart_perf.data.txt

init 会探测平台是否支持 --raw-data；不支持时回退 hitrace。analysis 对 hitrace 使用 perfFirst sidecar，并导出 trace_report.html。

--trace-from hitrace：采集不带 --raw-data

dyn-hyperstartup-checker report-user --dry-run --app com.example.app --ability EntryAbility --trace-from hitrace

monitor 中 hiperf record 不带 --raw-data；analysis 使用 hitraceFirst sidecar。

--trace-from hiperf：采集带 --raw-data，analysis 由 perf 合成 hitrace

dyn-hyperstartup-checker report-user --dry-run --app com.example.app --ability EntryAbility --trace-from hiperf

monitor 中 hiperf record 带 --raw-data；analysis 为 perfOnly 解码后合成 hitrace，并导出 trace_report.html。

加大解析并发（大 perf 文本）

dyn-hyperstartup-checker report-user --app com.example.app --ability EntryAbility --parse-concurrency 4

在 loadPerfData 与 decodePerfRawData 阶段启用 Worker（需 profile 不强制主线程 decode）。

按 group 预览

# 只看 init + monitor
dyn-hyperstartup-checker report-user --list --app com.example.app --ability EntryAbility -g init,monitor

# 只看采集后的拉取与分析
dyn-hyperstartup-checker report-user --dry-run --app com.example.app --ability EntryAbility -g collect,filter,analysis

采集前等待

dyn-hyperstartup-checker report-user --dry-run --app com.example.app --ability EntryAbility --risk-collect-wait 5

输出中会出现 [embed] sleep 5 — 等待 5 秒后开始收集风险事件数据；默认 0 时不插入该步骤。

指定设备与风险目标

dyn-hyperstartup-checker report-user --app com.example.app --ability EntryAbility \
  --hdc-target DEVICE01 \
  --risk-targets backtrack,direct \
  --trace-format-profile auto \
  --hstack-tool-path /path/to/hstack \
  --sourcemap-dir /path/to/sourcemaps

正式采集（需已连接 hdc 设备）

dyn-hyperstartup-checker report-user --app com.example.app --ability EntryAbility --output-dir ./output

执行完成后在 ./output/ 下查看 dump_stack.* 与 trace_report.html；可用 --log-file 将完整日志写入 ./output/workspace/checker.log。

常见错误

无效 --trace-from 值会直接报错并退出，例如：

dyn-hyperstartup-checker report-user --dry-run --app com.example.app --ability EntryAbility --trace-from both
# [--trace-from] 无效值: "both"。可选: hiperf、hitrace、mix

测试

npm test              # 单元与集成
npm run test:perf     # 性能回归
npm run test:all      # 全部
npm run format        # Prettier 格式化 src / commands / tests
npm run format:check  # 仅检查格式（CI 可用）

作为库使用

import { resolveScenario, runScenarioGroups } from "dyn-hyperstartup-checker";
import * as reportUser from "dyn-hyperstartup-checker/commands/report-user";

// dryRun: true 与 CLI --dry-run 相同，applyOptions 不会创建 outputDir
const { groups, defaultGroupOrder } = resolveScenario(
  reportUser,
  {
    app: "com.example.app",
    ability: "EntryAbility",
    riskTargets: "all",
    dryRun: true,
  },
  { hdcTarget: "DEVICE01" },
);

await runScenarioGroups({ groups, defaultGroupOrder, stopOnError: true });

CLI 场景框架

本工具按命名场景（commands/*.ts）注册子命令。每个场景导出 groups、defaultGroupOrder，可选 options 与 applyOptions(opts)。

commands/：设备联调场景，当前发布含 report-user（无 hidumper/revoke_switch 权限；analysis 默认 --trace-from mix）。
src/：实现采用 下划线 源文件名（如 group_specs.ts、run_command.ts、lib/perf_decode.ts、runners/platform_shell_executor.ts）。

通用开关（各场景子命令可用）：--list、--dry-run、--stop-on-error、-g,--group、--wait、--silent 等。完整列表见 dyn-hyperstartup-checker <scene> --help。

License

MIT

Keywords

cli batch shell commands