snapshot-checker 0.8.1 → 0.8.5

package/README.md

@@ -8,14 +8,38 @@
 
 - `report` 默认 `--trace-from` 由 `hitrace` 改为 **`mix`**（采集默认带 `--raw-data`，analysis 默认预处理 hitrace 并使用 **perfFirst** sidecar）。
 - 日志格式统一为行首 `[ISO8601] {级别} {正文}`（无 consola 颜色）。
-- 依赖升级：`hiperf_txt_parser` ^1.4、`hmtrace-parser` ^0.6；analysis trace 解码改由 pipeline 编排。
+- 依赖升级：`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` 返回 `PLAN_OPTION_OVERRIDE`，需重新 `plan`）；`0.x` 版本兼容比较 major+minor。
+- **机器可读输出**：全局 `--output-format json`（与采集目录 `--output-dir` 无关）；json 模式下 **stdout 仅 JSON**，日志写 **stderr**。
+- **顶层闭环命令**：`preflight`、`plan`、`apply`、`status`、`validate`（详见下文「CLI 总览」）。
+- **环境变量**：`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 静态注册（不再扫描目录动态加载）。
+
 **前置条件**
 
 - **Node.js** ≥ 18。
 - PATH 中可用 **`hdc`**，并已连接目标设备。
-- 本机 analysis 依赖 **`hiperf_txt_parser` ^1.4**、**`hmtrace-parser` ^0.6**（随包安装）：hitrace 预处理与索引由 hmtrace 构建，样本级并行解码与 hitrace 合并由 hiperf 完成。
+- 本机 analysis 依赖 **`hiperf_txt_parser` ^2.0**、**`hm-pt-core` ^1.0**、**`hmtrace-parser` ^0.8**（随 `npm install` 安装）：hitrace 预处理与索引由 hmtrace 构建，公共类型与 trace 机制由 hm-pt-core 提供，样本级并行解码与 hitrace 合并由 hiperf 完成。
+
+## 架构与 hmcommand-runner
+
+自 **0.8.x** 起，命令调度与执行引擎已提取为独立 npm 包 **[`hmcommand-runner`](https://www.npmjs.com/package/hmcommand-runner)**（当前依赖 `^1.3.0`）：
+
+| 层级 | 包 / 目录 | 职责 |
+|------|-----------|------|
+| 执行框架 | `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`。
 
 ---
 
@@ -49,6 +73,70 @@ 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`）。
+
+---
+
+## CLI 总览
+
+`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`，不可覆盖（不一致时退出码 `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`](skills/snapshot-checker/SKILL.md)。
+
+```bash
+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_UNSUPPORTED_SCHEMA`。完整列表见 [`skills/snapshot-checker/references/error_codes.md`](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` 仍可读，建议迁移至上表新名。
+
 ---
 
 ## `report` 命令
@@ -70,7 +158,7 @@ checkpoint 镜像失效等风险的专项采集与分析。按 `--risk-targets`
 
 ### analysis 阶段 trace 解码
 
-analysis 通过 `src/lib/pipeline.ts` 的 pipeline 执行，trace 解码由 `src/lib/perf_decode.ts` 编排（不再在 checker 内逐样本循环）：
+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`。
@@ -99,7 +187,7 @@ analysis 通过 `src/lib/pipeline.ts` 的 pipeline 执行，trace 解码由 `src
 
 | 选项 | 说明 |
 | ---- | ---- |
-| `--app <app>` | 应用包名 |
+| `--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 可执行文件；不配置则跳过 |
@@ -116,13 +204,16 @@ analysis 通过 `src/lib/pipeline.ts` 的 pipeline 执行，trace 解码由 `src
 | `--skip-non-backtrack` | `backtrackFS` 使用 `keepNonFsRevoked: false` |
 | `--drop-failed-samples` | 丢弃无 trace 解析器的 raw 样本 |
 
-**全局选项**（对各子命令均生效）
+**全局选项**（对各子命令均生效；完整说明见上文「CLI 总览」）
 
 | 选项 | 说明 |
 | ---- | ---- |
 | `--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` | 忽略失败并继续后续阶段（默认遇错即停） |
 
 ### 使用方式
 
@@ -149,7 +240,7 @@ analysis 通过 `src/lib/pipeline.ts` 的 pipeline 执行，trace 解码由 `src
 **`--list` 输出格式**（节选）：
 
 ```text
-[report] 场景命令（按 group 展示）:
+[report] 命令套件（按 group 展示）:
 
 Group: init
     [mac] hdc shell remount — hdc shell remount
@@ -179,12 +270,15 @@ Group: monitor
 
 ```text
 output/
+├── plan.json               # plan 命令生成（执行前）
+├── run_manifest.json       # apply 写入（执行状态）
 ├── dump_stack.txt          # 最终调用栈（文本）
-├── dump_stack.json         # 同上（JSON）
+├── 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
@@ -274,6 +368,20 @@ snapshot-checker report --app com.example.app --output-dir ./output
 
 **常见错误**
 
+缺 `--app`（退出码 `2`）：
+
+```bash
+snapshot-checker report --dry-run
+# ERROR_MISSING_APP: report requires --app <bundle_name>.
+```
+
+未知 `--group`（退出码 `2`，json 模式含 `available_groups`）：
+
+```bash
+snapshot-checker report --dry-run --app com.example.app --group missing
+# UNKNOWN_GROUP: Group 'missing' does not exist.
+```
+
 无效 `--trace-from` 值会直接报错并退出，例如：
 
 ```bash
@@ -297,57 +405,66 @@ snapshot-checker report-user --dry-run --app com.example.app --ability EntryAbil
 
 ---
 
-## `forkall` 命令（已过时）
+## 测试
 
-> **已过时**：请改用 `report`。`forkall` 仅保留兼容，后续可能移除。
+```bash
+npm test              # 单元与集成
+npm run test:perf     # 性能回归
+npm run test:all      # 全部
+npm run format        # Prettier 格式化 src / tests
+npm run format:check  # 仅检查格式（CI 可用）
+```
 
-针对单一 `--event-path` 做监控或「改配置后重启再采」。支持 `--mode monitor`（默认）与 `reboot-monitor`。详见 `snapshot-checker forkall --help` 或 `commands/forkall.ts`。
+### Agent 调用与评测
+
+Agent 相关能力已接入 CLI 与测试；**契约细节以 Skill 为准**，README「CLI 总览」提供速查。
+
+- 技能文档：[`skills/snapshot-checker/SKILL.md`](skills/snapshot-checker/SKILL.md)
+- 集成说明：[`skills/INTEGRATION.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`
 
 ```bash
-snapshot-checker forkall --event-path checkpoint/vfs_snapshot_dump_monitor --app com.example.app
+npm run test -- tests/agent_e2e.test.ts
 ```
 
----
-
-## 测试
+离线预览计划（无需设备）：
 
 ```bash
-npm test              # 单元与集成
-npm run test:perf     # 性能回归
-npm run test:all      # 全部
-npm run format        # Prettier 格式化 src / commands / tests / demos
-npm run format:check  # 仅检查格式（CI 可用）
+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
 ```
 
 ## 作为库使用
 
 ```ts
-import { resolveScenario, runScenarioGroups } from "snapshot-checker";
+import { resolveCommandSuite, runCommandSuiteGroups } from "snapshot-checker";
 import * as report from "snapshot-checker/commands/report";
 
 // dryRun: true 与 CLI --dry-run 相同，applyOptions 不会创建 outputDir
-const { groups, defaultGroupOrder } = resolveScenario(
+const { groups, defaultGroupOrder } = resolveCommandSuite(
   report,
   { app: "com.example.app", riskTargets: "all", dryRun: true },
   { hdcTarget: "DEVICE01" },
 );
 
-await runScenarioGroups({ groups, defaultGroupOrder, stopOnError: true });
+await runCommandSuiteGroups({ groups, defaultGroupOrder });
 ```
 
-独立示例：`demos/consumer-app`（见该目录 `README.md`）。
+默认遇错即停；需忽略失败继续时传 `stopOnError: false`。
 
 ---
 
-## CLI 场景框架
+## CLI 命令套件框架
+
+本工具将 `src/commands/*.ts` 静态注册为子命令，并由顶层命令提供 Agent 闭环（见「CLI 总览」）。每个命令套件导出 **`groups`**、**`defaultGroupOrder`**，可选 **`options`** 与 **`applyOptions(opts)`**。
 
-本工具按命名场景（`commands/*.ts`、`demos/*.ts`）注册子命令。每个场景导出 **`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`**。
 
-- **`commands/`**：设备联调场景，主场景 **`report`**、**`report-user`**（无 hidumper/revoke_switch 权限）；**`forkall`** 已过时（analysis 默认 `--trace-from mix`）。
-- **`demos/`**：示例场景（`context-demo`、`timeout-demo` 等）。
-- **`src/`**：实现采用 **下划线** 源文件名（如 `group_specs.ts`、`run_command.ts`、`lib/perf_decode.ts`、`runners/platform_shell_executor.ts`）。
+`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`、`--stop-on-error`、`-g,--group`、`--wait`、`--silent` 等。完整列表见 `snapshot-checker <scene> --help`。
+命令套件子命令通用开关：`--list`、`--dry-run`、`-g,--group`、`--wait`、`--silent`、`--continue-on-error` 等。完整列表见 `snapshot-checker <command> --help`。
 
 ### License
 

package/dist/src/cli.d.ts

@@ -1,3 +1,12 @@
 #!/usr/bin/env node
-export {};
+import type { Command } from "commander";
+export declare function createHyperStartUpCheckerProgram(): Command;
+export interface RunHyperStartUpCheckerCliOptions {
+    /** 是否在解析前执行 pkg 二进制 preflight（默认 true） */
+    preflight?: boolean;
+    /** 自定义 argv，默认 `process.argv` */
+    argv?: readonly string[];
+}
+/** 注册场景子命令并解析 CLI（npm 与独立二进制共用）。 */
+export declare function runHyperStartUpCheckerCli(options?: RunHyperStartUpCheckerCliOptions): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+CzC,wBAAgB,gCAAgC,IAAI,OAAO,CAoC1D;AAED,MAAM,WAAW,gCAAgC;IAC/C,0CAA0C;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iCAAiC;IACjC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,oCAAoC;AACpC,wBAAsB,yBAAyB,CAC7C,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,IAAI,CAAC,CAsFf"}