dyn-hyperstartup-checker

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

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

默认行为（0.0.1）

• 主场景 report-user：--trace-from 默认为 mix（采集带 --raw-data，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 ^1.4、hmtrace-parser ^0.7（随包安装）：hitrace 预处理与索引由 hmtrace 构建，样本级并行解码与 hitrace 合并由 hiperf 完成。

安装

直接安装（推荐）

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

report-user 命令

面向无 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 管理应用生命周期。
• monitor / collect / filter：不依赖 apppool_pids；hiperf 使用 --app 过滤，filter 阶段按 tgid 过滤。

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

执行阶段（defaultGroupOrder）

| 阶段 | 说明 | | ---- | ---- | | init | remount、清理、aa start / aa force-stop 重置应用等 | | monitor | hitrace + hiperf record（事件由风险目标推导） | | collect | 从设备拉取 perf、hitrace 到 --output-dir | | restore | report-user 无命令（组为空；不含 revoke_switch 复原） | | filter | 按目标进程（tgid）过滤 perf | | analysis | 选 perf 输入、解码 trace（hitrace 预处理 + hiperf 并行 decode）、可选 backtrackFS、去重，导出 dump_stack.txt / .json / .xlsx |

analysis 阶段 trace 解码

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

1. 按 --trace-format-profile（或 auto 时从设备读取的 format）构建 trace registry。
2. 若 --trace-from 为 hitrace 或 mix：主线程一次调用 hmtrace-parser 的 buildHitraceIndexSnapshot 解析 workspace/hyperstart_hitrace.txt。
3. 调用 hiperf_txt_parser 的 decodePerfRawData，传入 hitrace 索引与 sidecar 策略；--parse-concurrency 大于 1 时在加载 perf 文本与trace 解码（profile 无需主线程 transform 时）均可使用 Worker 池。

--trace-from 与 hitrace sidecar 策略（analysis，默认由 trace-from 推导）

| --trace-from | 是否预处理 hitrace | sidecar 策略 | 说明 | | -------------- | ------------------ | ------------ | ---- | | mix（默认） | 是 | perfFirst | 先解码 perf raw，失败类样本再查 hitrace 索引 | | hitrace | 是 | hitraceFirst | 有对齐快照则先 apply hitrace，成功则跳过 perf raw 解码 | | hiperf | 否 | perfOnly | 仅解码 hiperf --raw-data，不读 hitrace 文件 |

采集阶段行为不变：hitrace 时 hiperf record 不带 --raw-data；hiperf / mix 时 带 --raw-data。hitrace 与 hiperf dump 在 monitor 中仍会执行。

风险目标 --risk-targets

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

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

主要选项

| 选项 | 说明 | | ---- | ---- | | --app <app> | 应用包名 | | --ability <ability> | 应用 Ability 名称（aa start -a），与 --app 必填 | | --risk-targets <targets> | 风险事件类型，默认 all | | --trace-from <source> | 采集：hiperf record 是否 --raw-data（mix 默认带，hiperf 带，hitrace 不带）。analysis：是否预处理 hitrace 及 sidecar 策略（见上表）；与 --trace-format-profile 独立 | | --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 读取 | | --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 |

使用方式

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

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

只跑部分阶段时，用 -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 -e checkpoint:... & ... hiperf dump ..." — 收集风险事件数据
  ...
  22. [builtin] [func:func] — 风险栈解码

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

输出目录

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

output/
├── dump_stack.txt          # 最终调用栈（文本）
├── dump_stack.json         # 同上（JSON）
├── dump_stack.xlsx         # 同上（Excel）
├── perf_txt/
│   └── hyperstart_perf.data.txt    # 设备 hiperf dump 文本
└── workspace/              # 中间产物
    ├── hyperstart_log.txt    # hilog 采集
    ├── hyperstart_hitrace.txt
    ├── 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 阶段并行 hitrace + hiperf record --raw-data，例如：

hiperf record --raw-data -e checkpoint:vfs_snapshot_dump_monitor,checkpoint:checkpoint_revoked ... -d 70 &
...
hiperf dump -i /data/local/tmp/perf.data -o /data/local/tmp/hyperstart_perf.data.txt

analysis 时对 hitrace 使用 perfFirst sidecar 策略。

--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 不读 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 索引。

加大解析并发（大 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.*；可用 --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