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；首条读取 target_tgid（monitor 开始后 30s 滞后写入设备临时文件） | | restore | 复原 /proc/checkpoint/revoke_switch | | filter | 按 target_tgid 过滤 perf（不再在 filter 阶段 pgrep） | | 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 | | --hitrace-tag <tags> | 额外 hitrace tag，逗号分隔；含 ffrt 时采集 FFRT 事件并启用 analysis 聚合（见下文 异步解栈 / FFRT） | | --enable-perf-tracing-mark | 须与 --hitrace-tag ffrt 联用：hiperf -e 追加 tracing_mark_write:tracing_mark_write，采集异步解栈关联的 perf 标记 | | --hiperf-stack-mode <mode> | hiperf record 栈回溯：fp（默认）或 dwarf（自动附加 --delay-unwind，warn 可能导致调用栈丢失） | | --output-dir <path> | 输出根目录，默认 ./output | | --trace-format-profile <name> | trace 解码 profile，默认 default；可用 auto 从设备 format 读取 | | --skip-perf-dedupe | 跳过 dedupePerfData | | --filter-hitrace | analysis 按 target_tgid 过滤 hitrace，导出 workspace/hyperstart_hitrace.filtered.txt（不覆盖原文件） | | --keep-decoded-perf | 将 trace 解码成功的 perf 写入 workspace/_hyperstart_perf.trace_decoded.txt | | --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）
├── trace_report.html       # Hitrace 交互报告（含 hiperf 反向查询；启用 ffrt 时含 FFRT Tab）
├── perf_txt/
│   └── hyperstart_perf.data.txt    # 设备 hiperf dump 文本
└── workspace/              # 中间产物
    ├── checker.log           # --log-file 默认路径
    ├── hyperstart_log.txt    # hilog 采集
    ├── hyperstart_hitrace.txt
    ├── hyperstart_hitrace.filtered.txt   # --filter-hitrace 时导出
    ├── perf.data
    └── _hyperstart_perf.data.txt   # hstack 解析后 perf（若配置了 hstack）

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

trace_report.html 交互报告

analysis 在 --trace-from 为 mix / hitrace，或 --hitrace-tag 含 ffrt 时，于 <output-dir>/trace_report.html 生成自包含 HTML（内嵌 hiperf 样本与 callchain，可直接 file:// 打开）。

| Tab | 说明 | | --- | ---- | | Hitrace | 虚拟滚动主表；按 tid / 任务 / 事件下拉筛选；内容列支持子串检索与 ↑↓ 跳转（匹配行居中、关键词高亮）；点击含 snap 的行从右侧滑出 Hiperf 侧栏 | | FFRT | --hitrace-tag 含 ffrt 时出现；左侧按 gid 列表展示，含子任务标签（文件访问 / 失效触发）；详情见下表 |

FFRT 详情页（选中左侧 gid 后）：

| 区块 | 说明 | | ---- | ---- | | 标题栏 | gid / label / tgid；Exec 片段以时间范围摘要展示（不单独成表） | | 任务发起 | 生命周期中的提交 / 发起类事件（submit_begin 等，不含 exec_begin） | | 子任务 | 与 gid 关联的 checkpoint 事件，仅 vfs_snapshot_dump_monitor（文件访问）与 checkpoint_revoked（失效触发） | | FFRT生命周期 | 完整生命周期事件表，默认折叠，置于页底 |

异步解栈 / FFRT

当目标场景需要异步解栈（如 FFRT 任务在 worker 线程执行、同步帧指针栈无法覆盖完整调用链）时，须同时使能：

| 选项 | 作用 | | ---- | ---- | | --hitrace-tag ffrt | hitrace 采集 FFRT 事件（submit_begin / exec 等），analysis 聚合 gid 并导出 FFRT Tab | | --enable-perf-tracing-mark | hiperf 追加 tracing_mark_write:tracing_mark_write，与 hitrace ffrt 标记时间对齐，供异步解栈关联 |

二者缺一不可：仅开 ffrt 而无 tracing_mark_write 时，perf 侧缺少异步任务标记；仅开 --enable-perf-tracing-mark 而无 ffrt tag 时，CLI 不会追加该 hiperf 事件。

推荐采集命令（Agent 亦见 skills/snapshot-checker/SKILL.md）：

snapshot-checker report --app com.example.app \
  --hitrace-tag ffrt \
  --enable-perf-tracing-mark \
  --skip-perf-dedupe

• --hitrace-tag ffrt：采集 FFRT 生命周期与异步任务上下文。
• --enable-perf-tracing-mark：hiperf 采集 tracing_mark_write，与 ffrt 标记对齐以支持异步解栈。
• --skip-perf-dedupe：保留 FFRT / tracing_mark 相关 perf 样本，避免 dedupe 误删。

validate 在 plan 含 analysis 且满足上述 trace 报告条件时，将 trace_report.html 列为必需产物（trace_report_html check）。

示例

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

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 过滤；collect 同样首条读取 target_tgid，filter 按 tgid 写回 perf。
• 其余阶段（analysis 等）与 report 相同。

snapshot-checker report-user --dry-run --app com.example.app --ability EntryAbility

Agent 闭环

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

| 命令 | 说明 | | ---- | ---- | | schema | 输出 CLI 参数协议（required、default、enum、side_effect 等）；Agent 应优先读取，避免与 Skill 文档漂移 | | 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 | 按 plan.json 推导预期产物并验收（默认读 <output-dir>/plan.json；--no-plan 为 legacy，仅验 dump_stack.json） |

推荐 Agent 顺序：schema → preflight → plan → apply → status → validate。失败时优先执行 JSON 中的 error.next_actions 或 checks[].next_actions；user_input_required: true 时必须询问用户。详细契约见 skills/snapshot-checker/SKILL.md。

snapshot-checker schema --output-format json
snapshot-checker schema plan --output-format json    # 仅 plan 子命令 schema
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"）。
• stderr：结构化日志与进度；自动设置 NO_COLOR=1。
• 适用于 --list、--dry-run、正式执行，以及 schema / preflight / plan / apply / status / validate。

统一信封字段（各命令 JSON 均尽量包含，旧字段保留不删）：

| 字段 | 说明 | | ---- | ---- | | ok | 当前命令是否成功 | | command | 子命令名 | | status | 协议状态：READY / RUNNING / SUCCEEDED / FAILED / PARTIAL_SUCCESS / VERIFY_FAILED 等 | | tool.name / tool.version | 工具名与版本 | | warnings / errors | 非阻断与阻断摘要 | | next_actions | 建议 Agent 执行的下一步（如 rerun_plan、validate） | | error | 失败时的结构化错误（含 category、recoverable、retryable、user_input_required） |

validate 额外提供 checks[]：每项含 id、status、required 及可选 next_actions（如缺 dump_stack.json 时建议重跑 analysis；缺 trace_report.html 时检查 --trace-from / --hitrace-tag 是否满足导出条件）。

run_manifest.json 在 apply 后还可含 phase、failed_group、allowed_actions、recommended_actions；--continue-on-error 且部分失败时 status 为 partial_success。

退出码

| 退出码 | 含义 | | ------ | ---- | | 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、HIPERF_RAW_DATA_UNSUPPORTED 等。json 模式下多数错误附带 next_actions（如 HIPERF_RAW_DATA_UNSUPPORTED 建议 --trace-from hitrace 后重新 plan）。完整列表见 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 与退出码，无需真实设备）
• 协议 schema：tests/schema.test.ts、tests/error_recovery.test.ts
• 安全与 Plan 完整性：tests/shell_identifiers.test.ts、tests/shell_params.test.ts、tests/plan_integrity.test.ts

npm run test -- tests/agent_e2e.test.ts tests/schema.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"、status: "READY" 与 next_actions（建议 apply）。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.9.0 trace 交互报告与 FFRT

• trace_report.html：analysis 导出自包含 Hitrace / Hiperf / FFRT 交互报告（内嵌 perf 与 callchain，支持 file://）；Hitrace 虚拟滚动、列筛选、内容检索跳转、Hiperf 侧栏反向查询。
• FFRT Tab：按 gid 聚合；详情含任务发起、子任务（checkpoint 文件访问 / 失效触发）、标题栏 Exec 摘要、默认折叠的 FFRT生命周期。
• FFRT / 异步解栈：需异步解栈时须使能 --hitrace-tag ffrt 与 --enable-perf-tracing-mark（建议联用 --skip-perf-dedupe）。
• --enable-perf-tracing-mark：与 ffrt tag 联用时 hiperf 采集 tracing_mark_write，与 hitrace ffrt 标记对齐。
• --hiperf-stack-mode：默认 fp；dwarf 自动附加 --delay-unwind 并 warn 调用栈丢失风险。
• target_tgid：monitor 开始后 30s 滞后 pgrep 写入设备临时文件，collect 首条读取；filter 不再 pgrep。
• --filter-hitrace：按 target_tgid 导出过滤后的 hitrace 至 workspace/hyperstart_hitrace.filtered.txt。
• validate：plan 含 analysis 且需 trace 报告时验收 trace_report_html。
• 依赖：hmtrace-parser ^0.9.4；构建时打包 trace_html 客户端 bundle。

0.8.8 Agent 协议化 CLI

• schema 命令：snapshot-checker schema [--output-format json] 输出各子命令参数 schema（required、default、enum、side_effect、allow_in_apply），Agent 无需硬编码参数表。
• 统一 JSON 信封：preflight / plan / apply / status / validate 及失败路径补齐 status、tool、warnings、errors、next_actions。
• 错误恢复字段：error 含 category、recoverable、retryable、user_input_required 与 next_actions（覆盖 ERROR_MISSING_APP、UNKNOWN_GROUP、PLAN_OPTION_OVERRIDE、HIPERF_RAW_DATA_UNSUPPORTED 等）。
• validate checks[]：按 plan 推导必需产物，失败项附带可执行的 next_actions；默认读 plan.json，--no-plan 为 legacy。
• manifest 状态扩展：支持 partial_success（--continue-on-error）；新增 phase、failed_group、allowed_actions、recommended_actions。

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