snapshot-checker

面向 Harmony/OpenHarmony 设备联调 的采集与分析 CLI：通过 hdc 在设备上配置 trace 权限、后台拉取日志、并行执行 hitrace / hiperf 采样，并在本机对 perf 文本做解析、去重与调用栈输出。仓库内两条主场景为 forkall（可按需走「改机后重启」流程）与 report（多类风险目标、可选 hstack 与 sourcemap 解析）。

前置条件

• Node.js ≥ 18（见 package.json 的 engines）。
• 使用 forkall / report 时需在 PATH 中可用 hdc，并已连接目标设备；示例中的 Windows 风格路径（如 .\output）可按本机环境改为相对或绝对路径。

解析依赖：本机分析阶段使用 hiperf_txt_parser、hmtrace-parser（见 package.json 的 dependencies）。

forkall 场景

针对单一自定义 trace 事件路径（--event-path）做监控或「改配置后重启再采」模式。命令由 applyOptions 根据 CLI 注入，实际流水线见 commands/forkall.ts 与 src/lib/presets.ts。

典型阶段（defaultGroupOrder 由 --mode 决定）

• reboot（仅 reboot-monitor）：上传 hitrace_utils / hiperf、写入事件占位、重启设备，并用内置 timeout 等待重启（可按键跳过）。
• init：remount、清理设备与本地残留日志、停后台 hitrace、强停应用、销毁镜像、检查事件列表、配置 checkpoint 开关、为 --event-path 对应节点配置权限。
• monitor：后台 hilog 追加到本地 snapshot_log.txt；取 apppool pid 注入 monitor_target；组合 hitrace custom_event + hiperf record（事件名为路径中 / 替换为 :）与 --app 触发的 launcher 脚本等。
• collect：拉取 /data/local/tmp 下的 perf、hitrace 等到 --output-dir。
• analysis（阶段名：风险调用栈数据分析）：可选 Python 系统栈解栈；内置步骤按应用进程过滤 tg id、解码 perf、dedupePerfData，输出 dump_stack.txt / dump_stack.json。

模式

| --mode | 说明 | | ---------------- | ---- | | monitor | 顺序：init → monitor → collect → analysis（默认） | | reboot-monitor | 在首部增加 reboot 组，再执行同上 |

主要 CLI（场景专有，运行于 snapshot-checker forkall）

| 选项 | 说明 | | ------ | ------ | | --event-path <path> | 内核 tracing 事件路径片段（脚本内会转成 : 分隔的 hiperf 事件名） | | --app <app> | 应用包名；空则跳过通过 hidumper 创建实例等步骤 | | --system-symbol-file-path <path> | 若提供：对导出 perf 文本做系统栈解析（Python） | | --log-key <key> | hilog 过滤关键字，默认 pid | | --duration <seconds> | 采样时长（秒），默认 70 | | --default-timeout <seconds> | reboot-monitor 下等待设备就绪，默认 90 | | --buffer-size <bytes> | hitrace/hiperf 缓冲，默认 512000 | | --mode <mode> | monitor 或 reboot-monitor | | --output-dir <path> | 本地输出目录，默认 .\output | | --trace-format-profile <name> | trace 解码 profile，默认 default | | --skip-perf-dedupe | 解码后跳过 dedupePerfData |

此外还有与子命令通用的选项（见下文「次要：CLI 场景框架」中的通用标志）。

示例

npm run build
npm start -- forkall --help
node dist/src/cli.js forkall --mode monitor --event-path snapshot/hmb_forkall_report_image_failure --app com.example.app

report 场景

面向 镜像失效等风险 的专项采集与分析：可多选内核侧风险类型，拉取 ipc / 文件访问相关 tap；分析阶段可选用 hstack 解析 perf 文本与 sourcemap 符号化，或通过内置步骤在多个候选文件中挑选可用 perf 输入再解码。

典型阶段

• init：与 forkall 共用的初始化（权限命令按所选风险类型生成）。
• monitor：多标签 hitrace + 多事件 hiperf record（由 --risk-targets 推导）。
• collect：同 forkall。
• analysis（阶段名：镜像失效风险栈分析）：会先写回溯栈再做过滤/解码路径；配置了 hstack 时先跑外部工具再在 _snapshot_perf.data.txt 与原始快照间选输入。

风险目标 --risk-targets

逗号分隔，可选：all、ipc、file（语义见运行时日志中的中文展示名：文件访问 与 IPC 调用 两类链路）。未知值会报错。

主要 CLI

| 选项 | 说明 | | ------ | ------ | | --app <app> | 应用包名 | | --hstack-tool-path <path> | hstack 可执行文件；不配置则跳过该步并仅用原始 perf | | --sourcemap-dir <path> | 传给 hstack 的 -s | | --log-key、--duration、--buffer-size | 同 forkall | | --output-dir | 默认 .\output；perf 文本子目录为 perf_txt/ | | --trace-format-profile | 同 forkall | | --risk-targets <targets> | 默认 all | | --skip-perf-dedupe | 同 forkall |

node dist/src/cli.js report --app com.example.app --risk-targets ipc,file

安装与本地开发

npm install
npm run build
npm start -- --help          # 或: node dist/src/cli.js --help

全局或本地安装后，二进制入口为 snapshot-checker（与 npm start 等价，均指向 dist/src/cli.js）。

开发时可直接用源码跑（无需先 build）：

npm run dev -- forkall --list
npm run dev -- report --help

测试

使用 node:test + tsx，文件位于 tests/*.test.ts。

npm test

作为库使用

安装后可通过 resolveScenario + runScenarioGroups 注入场景 CLI 等价参数：

import { resolveScenario, runScenarioGroups } from "snapshot-checker";
import * as forkall from "snapshot-checker/commands/forkall";

const { groups, defaultGroupOrder } = resolveScenario(forkall, {
  app: "com.example.app",
  eventPath: "snapshot/hmb_forkall_report_image_failure",
  mode: "monitor",
});

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

独立示例工程：demos/consumer-app（内含 README 与子命令演示）。

次要：snapshot-checker CLI 场景框架与其它能力

本工具本质是 按命名场景（commands/*.ts、demos/*.ts）注册子命令：每个文件导出 groups、defaultGroupOrder，可选 options 与 applyOptions(opts)——在运行时根据 Commander 解析结果重写命令表（forkall / report 即用此机制）。

命令类型与环境

默认只执行「当前操作系统支持」的条目：Shell 可为单平台 windows / mac / linux 或多平台数组；另有 embed（内置 sleep、timeout 等）与 builtin（TypeScript 函数）。不指定 -g,--group 时按 defaultGroupOrder 遍历各组。

commands/ 最小场景

export const groups: Groups = {
  env: [
    { kind: "shell", description: "当前目录", run: "pwd" },
  ],
};
export const defaultGroupOrder: string[] = ["env"];

子命令名与 commands/、demos/ 下场景文件的主文件名（不含扩展名）一致；扫描时会排除主名为 config 的文件（config.*），避免与专用配置入口混淆。

内置 embed

• sleep <seconds> — 休眠。
• timeout <seconds> — 倒计时等待，TTY 下可按键跳过；CI 中非 TTY 时仅延时。详见 demos/timeout-demo.ts。

命令上下文（captureToVar）

前序命令可把 stdout/stderr（或正则捕获组）写入变量，后续在 run / cwd 等处用 {{变量名}} 展开。示例见 demos/context-demo.ts。

其它 CLI 开关（作用于各场景子命令）

• --wait — 前台结束后仍等待后台命令自然退出；默认会结束后台进程后退出进程。
• --list — 只列出将要执行的命令。
• --dry-run — 打印序列但不执行。
• --stop-on-error — 遇错中止。
• -g,--group — 限定或重复某一组：env:10,list 等。
• --silent、--interval、--ignore-platform、--log-level 等 — 见 snapshot-checker <scene> --help。

commands/ 与 demos/ 中的场景

• commands/：面向设备联调的主场景，当前为 forkall、report。
• demos/：示例与教学用场景，例如 context-demo（captureToVar 与 {{变量}} 展开）、timeout-demo（embed 的 timeout）、mac-example；demos/consumer-app 为独立子包，演示以库方式调用场景（见该目录下的 README.md）。

若 commands/ 与 demos/ 下出现同名场景文件，先加载者优先注册，后者跳过（控制台会给出警告）。

发布与日常命令

构建发布、全局/本地安装、npm pack、npm link 等与常规 Node 包相同；全局安装后：snapshot-checker。若远程包名不可用，可使用作用域名发布并相应调整 package.json。

License

MIT