npm.io
0.8.7 • Published 2d agoCLI

snapshot-checker

Licence
MIT
Version
0.8.7
Deps
6
Size
455 kB
Vulns
0
Weekly
210
SummaryDependencyVersions

snapshot-checker

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

主场景为 report：按 checkpoint 风险目标采集 trace/perf，可选 hstack 与 sourcemap 解析，输出 dump_stack.*。

安装

前置条件

  • Node.js ≥ 18。
  • PATH 中可用 hdc，并已连接目标设备。
  • 本机 analysis 依赖 hiperf_txt_parser ^2.2、hm-pt-core ^2.0、hmtrace-parser ^0.9（随 npm install 安装）：hitrace 预处理与索引由 hmtrace 构建，公共类型与 trace 机制由 hm-pt-core 提供，样本级并行解码与 hitrace 合并由 hiperf 完成。
直接安装（推荐）
npm install -g snapshot-checker
snapshot-checker --help
snapshot-checker report --help

全局命令 snapshot-checker 即 CLI 入口。

本地构建

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

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

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

npm run dev -- report --help

独立二进制（npm run build:bin）与 npm 全局安装共用同一套命令注册；版本号均来自 package.json（pkg 构建时注入 HYPER_STARTUP_CHECKER_BUNDLED_VERSION）。

report 命令

checkpoint 镜像失效等风险的专项采集与分析。按 --risk-targets 选择 hiperf 事件；analysis 阶段可选用 hstack、sourcemap，并通过 --trace-format-profile 配置 trace 解码。

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

执行阶段（defaultGroupOrder）

阶段 说明
init remount、清理、checkpoint 开关等
monitor hitrace + hiperf record（事件由风险目标推导）
collect 从设备拉取 perf、hitrace 到 --output-dir
restore 复原 /proc/checkpoint/revoke_switch
filter 按目标进程过滤 perf
analysis 选 perf 输入、解码 trace（hitrace 预处理 + hiperf 并行 decode）、可选 backtrackFS、去重，导出 dump_stack.txt / .json / .xlsx
analysis 阶段 trace 解码

analysis 通过 src/lib/report/pipeline.ts 的 pipeline 执行，trace 解码由 src/lib/report/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> 应用包名（--list / --dry-run / 正式执行均必填）
--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 样本

全局选项（对各子命令均生效；完整说明见下文「Agent 闭环」）

选项 说明
--hdc-target <sn> 全部 hdc 命令加 -t <sn>
--parse-concurrency <n> perf 加载与 trace 解码 的 Worker 数，默认 1；profile=auto 且 format 含主线程 transformFieldDict 时解码回退单线程
--output-format <text|json> CLI 结果格式，默认 text
--log-level <level> 覆盖环境变量中的默认日志级别
--log-file [path] 日志追加写文件；省略 path 时写入 <output-dir>/workspace/checker.log
--continue-on-error 忽略失败并继续后续阶段（默认遇错即停）
使用方式

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

  1. --list：按 group 列出将要执行的命令，不创目录、不连设备执行（与集成测试 report --list 不创建 workspace 与 perf_txt 一致）。
  2. --dry-run：按默认阶段顺序列出完整命令序列，同样不创目录。
  3. 正式运行：省略上述开关，按 init → monitor → collect → restore → 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] 命令套件（按 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] 将要执行的命令:

  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/
├── plan.json               # plan 命令生成（执行前）
├── run_manifest.json       # apply 写入（执行状态）
├── dump_stack.txt          # 最终调用栈（文本）
├── dump_stack.json         # 同上（JSON）；validate 必需
├── dump_stack.xlsx         # 同上（Excel）
├── perf_txt/
│   └── hyperstart_perf.data.txt    # 设备 hiperf dump 文本
└── workspace/              # 中间产物
    ├── checker.log           # --log-file 默认路径
    ├── 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 解码。

示例

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

snapshot-checker report --dry-run --app com.example.app --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（与 0.6.x 默认一致）

snapshot-checker report --dry-run --app com.example.app --trace-from hitrace

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

--trace-from hiperf：采集带 --raw-data，analysis 不读 hitrace

snapshot-checker report --dry-run --app com.example.app --trace-from hiperf

monitor 中 hiperf record 带 --raw-data；analysis 为 perfOnly，不预处理 hitrace 索引。

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

snapshot-checker report --app com.example.app --parse-concurrency 4

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

按 group 预览

# 只看 init + monitor
snapshot-checker report --list --app com.example.app -g init,monitor

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

采集前等待

snapshot-checker report --dry-run --app com.example.app --risk-collect-wait 5

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

指定设备与风险目标

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

相机应用完整采集（hitrace + rls profile）

snapshot-checker report --app com.huawei.hmos.camera --output-dir .\output_camera --trace-format-profile rls --risk-targets all --backtrack-delay 75 --duration 75 --log-file --parse-concurrency 1 --log-key "pid" --trace-from hitrace --skip-backtrack
  • --trace-from hitrace：采集不带 --raw-data，analysis 使用 hitraceFirst sidecar（与 0.6.x 默认一致）。
  • --trace-format-profile rls：使用 RLS trace 解码 profile。
  • --skip-backtrack：跳过 backtrackFS 后处理；--backtrack-delay / --duration 均为 75 秒。
  • --log-file：日志写入 .\output_camera\workspace\checker.log（Windows 路径写法；Unix 可改为 ./output_camera）。

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

snapshot-checker report --app com.example.app --output-dir ./output

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

常见错误

缺 --app（退出码 2）：

snapshot-checker report --dry-run
# ERROR_MISSING_APP: report requires --app <bundle_name>.

未知 --group（退出码 2，json 模式含 available_groups）：

snapshot-checker report --dry-run --app com.example.app --group missing
# UNKNOWN_GROUP: Group 'missing' does not exist.

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

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

report-user 命令

面向无 hidumper / revoke_switch 权限的设备用户：选项与 report 基本一致，额外要求 --ability（与 --app 配合，用于 aa start -a 启动应用）。

  • init：不执行 hidumper / revoke_switch 相关步骤，改用 aa start + aa force-stop 管理应用生命周期。
  • monitor / collect / filter：不依赖 apppool_pids；hiperf 使用 --app 过滤，filter 阶段按 tgid 过滤。
  • 其余阶段（analysis 等）与 report 相同。
snapshot-checker report-user --dry-run --app com.example.app --ability EntryAbility

Agent 闭环

snapshot-checker --help 除命令套件子命令 report、report-user 外，还提供下列顶层命令（report 与 report-user 输出目录结构一致，闭环命令不按套件嵌套）：

命令 说明
preflight 运行前环境检查（Node、hdc、设备、应用、输出目录、命令套件权限等）
plan 生成可保存的执行计划 plan.json（不连设备、不执行）；默认 --command-suite report
apply 按 plan.json 执行采集与分析，写入 run_manifest.json；采用 plan 中 execution_options 与 global_options，不可覆盖（不一致时退出码 2 / PLAN_OPTION_OVERRIDE）
status 读取 run_manifest.json 执行状态
validate 验收 output-dir 产物（必需 dump_stack.json）

推荐 Agent 顺序：preflight → plan → apply → status → validate。详细契约见 skills/snapshot-checker/SKILL.md。

snapshot-checker preflight --app com.example.app --output-dir ./output --output-format json
snapshot-checker plan --command-suite report --app com.example.app --output-dir ./output --output-format json
snapshot-checker apply --plan ./output/plan.json --output-format json
snapshot-checker status --output-dir ./output --output-format json
snapshot-checker validate --output-dir ./output --output-format json
全局选项

对各子命令均生效（含顶层命令与 report / report-user）：

选项 说明
--output-format <text|json> CLI 结果写出格式，默认 text；与 --output-dir（采集产物目录）无关
--log-level <level> 日志级别；未设则读环境变量，默认 info
--log-file [path] 日志追加写文件；省略 path 时写入 <output-dir>/workspace/checker.log
--hdc-target <sn> 全部 hdc 命令加 -t <sn>
--parse-concurrency <n> perf 加载与 trace 解码 Worker 数，默认 1
--output-format json
  • stdout：仅一行 JSON（含 schema_version: "1"、ok、命令结果或 error.code）。
  • stderr：结构化日志与进度；自动设置 NO_COLOR=1。
  • 适用于 --list、--dry-run、正式执行，以及 preflight / plan / apply / status / validate。
退出码
退出码 含义
0 成功
1 执行失败、验收失败、preflight 有 fail 检查项
2 参数/契约错误（如缺 --app、未知 --group、Shell 参数非法、plan 文件无效或摘要不匹配）

常见 error.code：ERROR_MISSING_APP、ERROR_MISSING_ABILITY、UNKNOWN_GROUP、INVALID_IDENTIFIER、INVALID_NUMERIC、INVALID_PATH、PLAN_CHANGED、PLAN_VERSION_MISMATCH、PLAN_OPTION_OVERRIDE、PLAN_NOT_FOUND、MANIFEST_NOT_FOUND、MANIFEST_INVALID_JSON、MANIFEST_INVALID、MANIFEST_UNSUPPORTED_SCHEMA。完整列表见 skills/snapshot-checker/references/error_codes.md。

环境变量
变量 说明
HYPER_STARTUP_CHECKER_LOG_LEVEL 默认日志级别（优先于 LOG_LEVEL）
HYPER_STARTUP_CHECKER_BUNDLED_VERSION pkg 二进制嵌入版本（构建注入）
NO_COLOR / FORCE_COLOR 控制台颜色

旧名 SNAPSHOT_CHECKER_LOG_LEVEL、SNAPSHOT_CHECKER_BUNDLED_VERSION 仍可读，建议迁移至上表新名。

Agent 调用与评测

Agent 相关能力已接入 CLI 与测试；契约细节以 Skill 为准，上文提供速查。

  • 技能文档：skills/snapshot-checker/SKILL.md
  • 集成说明：skills/INTEGRATION.md
  • 端到端评测：tests/agent_e2e.test.ts（仅解析 JSON 与退出码，无需真实设备）
  • 安全与 Plan 完整性：tests/shell_identifiers.test.ts、tests/shell_params.test.ts、tests/plan_integrity.test.ts
npm run test -- tests/agent_e2e.test.ts

离线预览计划（无需设备）：

snapshot-checker plan --command-suite report --app com.example.app --output-dir ./output --output-format json
# 等价：snapshot-checker report --dry-run --app com.example.app --output-format json

架构与 hmcommand-runner

自 0.8.x 起，命令调度与执行引擎已提取为独立 npm 包 hmcommand-runner（当前依赖 ^1.3.2）：

层级 包 / 目录 职责
执行框架 hmcommand-runner CommandDef 类型、组调度（group:N）、Shell/Builtin/Embed Runner、registerCommandSuites
领域命令套件 src/commands/、src/lib/report/ 等 report/report-user 命令套件、hdc/hiperf/hitrace 命令拼装与解码

snapshot-checker 的公开 API（resolveCommandSuite、runCommandSuiteGroups、executeAll 等）从主包 re-export（底层委托 hmcommand-runner）。npm 仍可通过 snapshot-checker/commands/report 引用命令套件模块。若只需通用命令编排框架，可直接依赖 hmcommand-runner。

作为库使用

import { resolveCommandSuite, runCommandSuiteGroups } from "snapshot-checker";
import * as report from "snapshot-checker/commands/report";

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

await runCommandSuiteGroups({ groups, defaultGroupOrder });

默认遇错即停；需忽略失败继续时传 stopOnError: false。

CLI 命令套件框架

本工具将 src/commands/*.ts 静态注册为子命令，并由顶层命令提供 Agent 闭环（见「Agent 闭环」）。每个命令套件导出 groups、defaultGroupOrder，可选 options 与 applyOptions(opts)。

  • src/commands/：设备联调命令套件，report（主套件）、report-user（无 hidumper/revoke_switch 权限）。
  • src/lib/：领域实现（如 lib/report/decode.ts、lib/report/pipeline.ts、lib/report/command_suite.ts）；调度类型与执行器来自 hmcommand-runner。

plan.json 主要字段：command_suite、command_suite_options、commands、commands_digest、execution_options（如 ignorePlatform）、tool_version；plan --output-format json 的 stdout 含 ok: true、command: "plan"。run_manifest.json 与 preflight JSON 中套件标识同为 command_suite。

命令套件子命令通用开关：--list、--dry-run、-g,--group、--wait、--silent、--continue-on-error 等。完整列表见 snapshot-checker <command> --help。

测试

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

Agent 相关测试见上文「Agent 闭环 → Agent 调用与评测」。

更新说明

0.8.6 依赖升级
  • hmtrace-parser ^0.9.0：内置 profile 统一为 rls（default 为其别名）；checkpoint_revoked 字段改为 checkpoint_monitor_id / revoke_reason，FS 类型自动展开 revoke_reason；vfs_snapshot_dump_monitor 支持 op_flag 可读化。CLI 行为不变，仍通过 --trace-format-profile rls 选用该 profile。
0.8.5 依赖升级
  • hm-pt-core ^2.0：RecordSample.id / time / stream_id / period 统一为 bigint，与 hiperf 2.1+ 对齐；hiperf / hmtrace 均复用该类型，pipeline 不再需要类型断言。
  • hiperf_txt_parser ^2.2：依赖 hm-pt-core 2.0；fieldDict 解码后 raw 行改为键值展示，测试侧用保留 hex raw 的 fixture 模拟「perf 已解码」场景。
  • hmtrace-parser ^0.8.3、hmcommand-runner ^1.3.2：小版本对齐，无 CLI 行为变更。
0.7.0 相对 0.6.x 的破坏性变更
  • report 默认 --trace-from 由 hitrace 改为 mix（采集默认带 --raw-data，analysis 默认预处理 hitrace 并使用 perfFirst sidecar）。
  • 日志格式统一为行首 [ISO8601] {级别} {正文}（无 consola 颜色）。
  • 依赖升级：hiperf_txt_parser 2.0、hm-pt-core 1.0、hmtrace-parser 0.8；analysis trace 解码改由 pipeline 编排；公共类型与 trace 机制自 hm-pt-core 导入。
  • 若需与 0.6.x 相同默认行为，显式传入 --trace-from hitrace。
0.8.x Agent-friendly 变更（相对早期 0.8）
  • 统一 CLI 入口：npm 与 pkg 独立二进制共用 src/cli.ts，能力一致（含 report-user、--list、--dry-run、顶层闭环命令）。
  • 默认 fail-fast：命令套件执行遇错即停；需继续时使用 --continue-on-error（--stop-on-error 为同义显式写法）。失败时仍会补跑 restore 组。
  • 参数校验：report / report-user / plan 要求非空 --app；未知 --group 返回退出码 2 与稳定错误码（如 ERROR_MISSING_APP、UNKNOWN_GROUP）。
  • Shell 安全边界：进入 Shell 或重定向的参数经统一校验——标识符白名单（--app、--ability、--log-key、--hitrace-tag、--hdc-target 等 → INVALID_IDENTIFIER）；数值纯整数解析（--duration、--buffer-size → INVALID_NUMERIC）；路径拒绝 Shell 元字符（--output-dir、--hstack-tool-path、--sourcemap-dir → INVALID_PATH）。
  • Plan 完整性：plan.json 含 commands_digest 与 execution_options（如 ignorePlatform）；apply 校验存储 commands 与重新生成 commands 的双摘要，并始终采用 plan 保存的执行选项与全局选项（与 plan 不一致的 apply --ignore-platform、--hdc-target、--parse-concurrency 返回 PLAN_OPTION_OVERRIDE，需重新 plan）；0.x 版本兼容比较 major+minor。
  • 机器可读输出：全局 --output-format json（与采集目录 --output-dir 无关）；json 模式下 stdout 仅 JSON，日志写 stderr。
  • 顶层闭环命令：preflight、plan、apply、status、validate（详见「Agent 闭环」）。
  • 环境变量：HYPER_STARTUP_CHECKER_LOG_LEVEL、HYPER_STARTUP_CHECKER_BUNDLED_VERSION（旧名 SNAPSHOT_CHECKER_* 仍可读）。
  • CommandSuite 命名（依赖 hmcommand-runner@^1.3.0）：原 Scenario* API 与 JSON 字段 scenario / scenario_options 分别改为 CommandSuite*、command_suite / command_suite_options；plan / preflight 使用 --command-suite。
  • 命令套件源码位置：report / report-user 定义迁至 src/commands/，CLI 静态注册（不再扫描目录动态加载）。
License

MIT

Keywords

clibatchshellcommands