snapshot-checker 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/README.md +103 -343
  2. package/dist/commands/forkall.d.ts +4 -12
  3. package/dist/commands/forkall.d.ts.map +1 -1
  4. package/dist/commands/forkall.js +46 -23
  5. package/dist/commands/forkall.js.map +1 -1
  6. package/dist/commands/report.d.ts +9 -0
  7. package/dist/commands/report.d.ts.map +1 -1
  8. package/dist/commands/report.js +153 -32
  9. package/dist/commands/report.js.map +1 -1
  10. package/dist/demos/context-demo.d.ts +10 -0
  11. package/dist/demos/context-demo.d.ts.map +1 -0
  12. package/dist/{commands/context_demo.js → demos/context-demo.js} +15 -18
  13. package/dist/demos/context-demo.js.map +1 -0
  14. package/dist/{commands → demos}/mac-example.d.ts +1 -3
  15. package/dist/demos/mac-example.d.ts.map +1 -0
  16. package/dist/{commands → demos}/mac-example.js +2 -4
  17. package/dist/demos/mac-example.js.map +1 -0
  18. package/dist/{commands/timeout_demo.d.ts → demos/timeout-demo.d.ts} +2 -2
  19. package/dist/demos/timeout-demo.d.ts.map +1 -0
  20. package/dist/demos/timeout-demo.js +35 -0
  21. package/dist/demos/timeout-demo.js.map +1 -0
  22. package/dist/src/cli.js +209 -169
  23. package/dist/src/cli.js.map +1 -1
  24. package/dist/src/executor.d.ts +1 -3
  25. package/dist/src/executor.d.ts.map +1 -1
  26. package/dist/src/executor.js +1 -3
  27. package/dist/src/executor.js.map +1 -1
  28. package/dist/src/groupSpecs.d.ts +1 -4
  29. package/dist/src/groupSpecs.d.ts.map +1 -1
  30. package/dist/src/groupSpecs.js.map +1 -1
  31. package/dist/src/index.d.ts +1 -1
  32. package/dist/src/index.d.ts.map +1 -1
  33. package/dist/src/index.js +1 -1
  34. package/dist/src/index.js.map +1 -1
  35. package/dist/src/lib/{common_groups.d.ts → presets.d.ts} +24 -2
  36. package/dist/src/lib/presets.d.ts.map +1 -0
  37. package/dist/src/lib/{common_groups.js → presets.js} +73 -24
  38. package/dist/src/lib/presets.js.map +1 -0
  39. package/dist/src/lib/{programmatic.d.ts → scenario.d.ts} +9 -11
  40. package/dist/src/lib/scenario.d.ts.map +1 -0
  41. package/dist/src/lib/{programmatic.js → scenario.js} +6 -10
  42. package/dist/src/lib/scenario.js.map +1 -0
  43. package/dist/src/logger.d.ts +23 -0
  44. package/dist/src/logger.d.ts.map +1 -0
  45. package/dist/src/logger.js +92 -0
  46. package/dist/src/logger.js.map +1 -0
  47. package/dist/src/runCommand.d.ts +27 -35
  48. package/dist/src/runCommand.d.ts.map +1 -1
  49. package/dist/src/runCommand.js +81 -70
  50. package/dist/src/runCommand.js.map +1 -1
  51. package/dist/src/runGroups.d.ts +6 -12
  52. package/dist/src/runGroups.d.ts.map +1 -1
  53. package/dist/src/runGroups.js +14 -19
  54. package/dist/src/runGroups.js.map +1 -1
  55. package/dist/src/runners/builtinFunctionRunner.d.ts +1 -0
  56. package/dist/src/runners/builtinFunctionRunner.d.ts.map +1 -1
  57. package/dist/src/runners/builtinFunctionRunner.js +5 -12
  58. package/dist/src/runners/builtinFunctionRunner.js.map +1 -1
  59. package/dist/src/runners/embedRunner.d.ts +1 -0
  60. package/dist/src/runners/embedRunner.d.ts.map +1 -1
  61. package/dist/src/runners/embedRunner.js +5 -1
  62. package/dist/src/runners/embedRunner.js.map +1 -1
  63. package/dist/src/runners/shellRunner.d.ts +1 -0
  64. package/dist/src/runners/shellRunner.d.ts.map +1 -1
  65. package/dist/src/runners/shellRunner.js +40 -8
  66. package/dist/src/runners/shellRunner.js.map +1 -1
  67. package/dist/src/runners/types.d.ts +9 -0
  68. package/dist/src/runners/types.d.ts.map +1 -1
  69. package/dist/src/types.d.ts +47 -77
  70. package/dist/src/types.d.ts.map +1 -1
  71. package/dist/src/types.js +37 -10
  72. package/dist/src/types.js.map +1 -1
  73. package/package.json +10 -3
  74. package/dist/commands/context_demo.d.ts +0 -18
  75. package/dist/commands/context_demo.d.ts.map +0 -1
  76. package/dist/commands/context_demo.js.map +0 -1
  77. package/dist/commands/mac-example.d.ts.map +0 -1
  78. package/dist/commands/mac-example.js.map +0 -1
  79. package/dist/commands/timeout_demo.d.ts.map +0 -1
  80. package/dist/commands/timeout_demo.js +0 -48
  81. package/dist/commands/timeout_demo.js.map +0 -1
  82. package/dist/src/lib/common_groups.d.ts.map +0 -1
  83. package/dist/src/lib/common_groups.js.map +0 -1
  84. package/dist/src/lib/foo.d.ts +0 -3
  85. package/dist/src/lib/foo.d.ts.map +0 -1
  86. package/dist/src/lib/foo.js +0 -7
  87. package/dist/src/lib/foo.js.map +0 -1
  88. package/dist/src/lib/programmatic.d.ts.map +0 -1
  89. package/dist/src/lib/programmatic.js.map +0 -1
  90. package/dist/src/lib/trace_formatter.d.ts +0 -9
  91. package/dist/src/lib/trace_formatter.d.ts.map +0 -1
  92. package/dist/src/lib/trace_formatter.js +0 -148
  93. package/dist/src/lib/trace_formatter.js.map +0 -1
package/README.md CHANGED
@@ -1,307 +1,118 @@
1
1
  # snapshot-checker
2
2
 
3
- 按顺序执行 **bat**、**mac**、**shell** 命令的 CLI 工具。支持**命令组**:可为每组命名,用 `--group` 指定执行某一或多个组;不指定时默认执行**当前系统支持的所有命令**(按 `defaultGroupOrder` 顺序)。
3
+ 面向 **Harmony/OpenHarmony 设备联调** 的采集与分析 CLI:通过 `hdc` 在设备上配置 trace 权限、后台拉取日志、并行执行 `hitrace` / `hiperf` 采样,并在本机对 perf 文本做解析、去重与调用栈输出。仓库内两条主场景为 **`forkall`**(可按需走「改机后重启」流程)与 **`report`**(多类风险目标、可选 hstack 与 sourcemap 解析)。
4
4
 
5
- ## 命令类型
5
+ ---
6
6
 
7
- | kind | 说明 | 默认执行范围 |
8
- | ------------------ | ---------------------------------- | ------------ |
9
- | `windows` | Windows 下执行命令 | 仅 Windows |
10
- | `mac` | 面向 macOS 的命令 | 仅 macOS |
11
- | `linux` | 面向 Linux 的命令 | 仅 Linux |
12
- | `embed` | 内置指令(如 `sleep` / `timeout`) | 全平台 |
13
- | `builtin-function` | 内置函数命令(JS/TS 函数) | 全平台 |
7
+ ## `forkall` 场景
14
8
 
15
- ## 安装与运行
9
+ 针对**单一自定义 trace 事件路径**(`--event-path`)做监控或「改配置后重启再采」模式。命令由 `applyOptions` 根据 CLI 注入,实际流水线见 `commands/forkall.ts` 与 `src/lib/presets.ts`。
16
10
 
17
- ```bash
18
- npm install
19
- npm run build
20
- npm start -- foo # 或: node dist/cli.js foo
21
- ```
22
-
23
- 开发时可直接用 tsx 跑(无需 build):
24
-
25
- ```bash
26
- npm run dev -- run
27
- ```
28
-
29
- ## 测试
30
-
31
- 项目使用 `node:test` + `tsx` 运行测试,测试文件位于 `tests/*.test.ts`。
32
-
33
- ```bash
34
- npm test
35
- ```
36
-
37
- 当前已覆盖的核心模块(`src/`):
38
-
39
- - `src/groupSpecs.ts`:组参数解析(默认展开、`name:repeat`、非法 repeat 回退)
40
- - `src/lib/programmatic.ts`:场景解析、group 参数规范化、按组执行的 stopOnError 行为
41
- - `src/runGroups.ts`(通过 programmatic 入口间接覆盖):跨组共享命令上下文
42
- - `src/lib/trace_formatter.ts`:profile 列表、未知 profile 回退、`dev` 配置映射
43
-
44
- ## 配置命令与组(commands 目录)
11
+ **典型阶段(`defaultGroupOrder` 由 `--mode` 决定)**
45
12
 
46
- 所有命令配置均放在项目根目录的 `commands/` 目录中:
13
+ - **`reboot`**(仅 `reboot-monitor`):上传 `hitrace_utils` / `hiperf`、写入事件占位、重启设备,并用内置 `timeout` 等待重启(可按键跳过)。
14
+ - **`init`**:remount、清理设备与本地残留日志、停后台 hitrace、强停应用、销毁镜像、检查事件列表、配置 checkpoint 开关、为 `--event-path` 对应节点配置权限。
15
+ - **`monitor`**:后台 `hilog` 追加到本地 `snapshot_log.txt`;取 `apppool` pid 注入 `monitor_target`;组合 `hitrace custom_event` + `hiperf record`(事件名为路径中 `/` 替换为 `:`)与 `--app` 触发的 launcher 脚本等。
16
+ - **`collect`**:拉取 `/data/local/tmp` 下的 perf、hitrace 等到 `--output-dir`。
17
+ - **`analysis`**(阶段名:**风险调用栈数据分析**):可选 Python 系统栈解栈;内置步骤按应用进程过滤 tg id、解码 perf、`dedupePerfData`,输出 `dump_stack.txt` / `dump_stack.json`。
47
18
 
48
- - `commands/*.ts`:场景配置文件,例如 `foo.ts`、`bar.ts`,通过 `snapshot-checker foo` / `snapshot-checker bar` 等命令使用
19
+ **模式**
49
20
 
50
- 一个最简单的配置文件形如:
21
+ | `--mode` | 说明 |
22
+ | ---------------- | ---- |
23
+ | `monitor` | 顺序:`init` → `monitor` → `collect` → `analysis`(默认) |
24
+ | `reboot-monitor` | 在首部增加 `reboot` 组,再执行同上 |
51
25
 
52
- ```ts
53
- export const groups: Groups = {
54
- env: [
55
- { kind: "shell", description: "打印当前目录", run: "pwd" },
56
- { kind: "shell", description: "Node 版本", run: "node -v" },
57
- ],
58
- list: [{ kind: "shell", description: "列出文件", run: "ls -la" }],
59
- };
60
-
61
- export const defaultGroupOrder: string[] = ["env", "list"];
62
- ```
63
-
64
- - 不指定 `--group` 时:按 `defaultGroupOrder` 依次执行各组,且**只执行当前系统支持**的命令(shell 全平台;bat 仅 Windows;mac 仅 macOS)。
65
- - 指定 `--group env list` 时:按给定顺序执行这些组内、且当前系统支持的命令。
66
-
67
- 每条命令可加 `cwd` 指定工作目录。
26
+ **主要 CLI(场景专有,运行于 `snapshot-checker forkall`)**
68
27
 
69
- ### 内置指令(embed)
28
+ | 选项 | 说明 |
29
+ | ------ | ------ |
30
+ | `--event-path <path>` | 内核 tracing 事件路径片段(脚本内会转成 `:` 分隔的 hiperf 事件名) |
31
+ | `--app <app>` | 应用包名;空则跳过通过 hidumper 创建实例等步骤 |
32
+ | `--system-symbol-file-path <path>` | 若提供:对导出 perf 文本做系统栈解析(Python) |
33
+ | `--log-key <key>` | `hilog` 过滤关键字,默认 `pid` |
34
+ | `--duration <seconds>` | 采样时长(秒),默认 `70` |
35
+ | `--default-timeout <seconds>` | `reboot-monitor` 下等待设备就绪,默认 `90` |
36
+ | `--buffer-size <bytes>` | hitrace/hiperf 缓冲,默认 `512000` |
37
+ | `--mode <mode>` | `monitor` 或 `reboot-monitor` |
38
+ | `--output-dir <path>` | 本地输出目录,默认 `.\output` |
39
+ | `--trace-format-profile <name>` | trace 解码 profile,默认 `default` |
40
+ | `--skip-perf-dedupe` | 解码后跳过 `dedupePerfData` |
70
41
 
71
- 除平台命令外,还支持内置指令(`kind: 'embed'`),由执行器内部实现,不依赖系统 shell。
42
+ 此外还有与子命令通用的选项(见下文「次要:CLI 场景框架」中的通用标志)。
72
43
 
73
- #### `sleep <seconds>`
44
+ **示例**
74
45
 
75
- 按指定秒数等待,例如:
76
-
77
- ```ts
78
- { kind: 'embed', run: 'sleep 3', description: '等待 3 秒' }
79
- ```
80
-
81
- #### `timeout <seconds>`(兼容 `timieout <seconds>`)
82
-
83
- 最多等待指定秒数,并实时显示剩余时间;在可交互终端下,用户按任意键可立即结束等待。
84
-
85
- 示例:
86
-
87
- ```ts
88
- {
89
- kind: 'embed',
90
- run: 'timeout 30',
91
- description: '最多等待 30 秒,按任意键跳过',
92
- }
93
- ```
94
-
95
- 行为说明:
96
-
97
- - 使用同一行原地刷新倒计时(`[timeout] 剩余 Ns...`)。
98
- - 到达超时时间后自动继续后续命令。
99
- - 若检测到键盘输入则立即结束等待并继续。
100
- - 在非 TTY 环境(如某些 CI)中会退化为仅按时间等待,不监听按键。
101
-
102
- 仓库内完整示例见 `commands/timeout_demo.ts`(`npm run dev -- timeout_demo` 或 `node dist/cli.js timeout_demo`)。
103
-
104
- ### 通用 lib 工具函数
105
-
106
- 推荐将通用逻辑放在 `src/lib/` 下(例如 `src/lib/foo.ts`),在场景文件中直接调用这些函数:
107
-
108
- ```ts
109
- import { buildTag, buildUserGreeting } from '../src/lib/foo.js';
110
-
111
- {
112
- kind: CommandKind.BuiltinFunction,
113
- description: '调用 lib/foo 的工具函数写入变量',
114
- func: (ctx) => {
115
- const user = ctx.user ?? 'unknown';
116
- ctx.builtinTag = buildTag('context_demo');
117
- ctx.fromFoo = buildUserGreeting(user);
118
- },
119
- }
120
- ```
121
-
122
- 仓库内完整示例见 `commands/context_demo.ts`。
123
-
124
- ### 命令之间传递变量(上下文)
125
-
126
- 命令执行器内置了一个**简单的上下文对象**,允许前一条命令将自己的输出写入变量,后续命令通过模板占位符引用这些变量。通过 CLI 跑场景时,该上下文在**整个场景执行期间**(含不同 `group`、不同块之间)**同一份共享**,因此可以把变量从 `getUser` 组传到 `greet` 组。仓库内示例见 `commands/context_demo.ts`。
127
-
128
- - **写入变量:**在命令上增加 `captureToVar` 元数据
129
- - **读取变量:**在 `run` / `file` / `args` / `cwd` / `description` 中使用 `{{varName}}` 占位符
130
-
131
- 示例:
132
-
133
- ```ts
134
- // commands/example.ts
135
- import type { Groups } from "../src/types.js";
136
-
137
- export const groups: Groups = {
138
- env: [
139
- {
140
- kind: "shell",
141
- description: "获取当前用户名",
142
- run: "whoami",
143
- // 将整段 stdout 写入变量 user
144
- // (比如 "alice"),供后续命令使用
145
- // @ts-expect-error: 由执行器在运行时识别的扩展字段
146
- captureToVar: {
147
- name: "user",
148
- },
149
- },
150
- ],
151
- greet: [
152
- {
153
- kind: "shell",
154
- description: "使用上一条命令得到的用户名",
155
- run: 'echo "hello, {{user}}"',
156
- },
157
- ],
158
- };
159
-
160
- export const defaultGroupOrder = ["env", "greet"];
46
+ ```bash
47
+ npm run build
48
+ npm start -- forkall --help
49
+ node dist/src/cli.js forkall --mode monitor --event-path snapshot/hmb_forkall_report_image_failure --app com.example.app
161
50
  ```
162
51
 
163
- #### 仅提取输出的一部分
52
+ ---
164
53
 
165
- 如果需要从输出中提取一部分(比如只要第一行的数字),可以使用 `pattern` 和 `groupIndex`:
54
+ ## `report` 场景
166
55
 
167
- ```ts
168
- {
169
- kind: 'shell',
170
- description: '获取某个进程 pid',
171
- run: 'pidof my-app',
172
- // @ts-expect-error: 由执行器在运行时识别的扩展字段
173
- captureToVar: {
174
- name: 'pid',
175
- pattern: '^(\\d+)', // 匹配第一行的数字
176
- groupIndex: 1, // 取第 1 个捕获组
177
- },
178
- },
179
- {
180
- kind: 'shell',
181
- description: '用 pid 做点事',
182
- run: 'echo "pid is {{pid}}"',
183
- }
184
- ```
56
+ 面向 **镜像失效等风险** 的专项采集与分析:可多选内核侧风险类型,拉取 ipc / 文件访问相关 tap;分析阶段可选用 **hstack** 解析 perf 文本与 **sourcemap** 符号化,或通过内置步骤在多个候选文件中挑选可用 perf 输入再解码。
185
57
 
186
- `captureToVar` 字段说明:
58
+ **典型阶段**
187
59
 
188
- - **name**: 变量名(如 `pid`、`user`)
189
- - **from**: 可选,`"stdout"`(默认)或 `"stderr"`,表示从哪个输出中取值
190
- - **pattern**: 可选,正则表达式字符串;不传时使用整个输出(去掉首尾空白)
191
- - **groupIndex**: 可选,指定要取的捕获组索引,默认 `1`
60
+ - **`init`**:与 forkall 共用的初始化(权限命令按所选风险类型生成)。
61
+ - **`monitor`**:多标签 `hitrace` + 多事件 `hiperf record`(由 `--risk-targets` 推导)。
62
+ - **`collect`**:同 forkall。
63
+ - **`analysis`**(阶段名:**镜像失效风险栈分析**):会先写回溯栈再做过滤/解码路径;配置了 hstack 时先跑外部工具再在 `_snapshot_perf.data.txt` 与原始快照间选输入。
192
64
 
193
- ### 多场景配置示例:foo / bar
65
+ **风险目标 `--risk-targets`**
194
66
 
195
- - `commands/config.ts` 中定义默认场景(供 `run` 使用)
196
- - 在 `commands/foo.ts` 中定义 `foo` 场景:
67
+ 逗号分隔,可选:`all`、`ipc`、`file`(语义见运行时日志中的中文展示名:**文件访问** **IPC 调用** 两类链路)。未知值会报错。
197
68
 
198
- ```ts
199
- // commands/foo.ts
200
- export const groups: Groups = {
201
- env: [
202
- { kind: "shell", description: "[foo] 打印当前目录", run: "pwd" },
203
- { kind: "shell", description: "[foo] 显示 Node 版本", run: "node -v" },
204
- ],
205
- list: [{ kind: "shell", description: "[foo] 列出当前目录", run: "ls -la" }],
206
- };
69
+ **主要 CLI**
207
70
 
208
- export const defaultGroupOrder: string[] = ["env", "list"];
209
- ```
210
-
211
- - `commands/bar.ts` 中定义 `bar` 场景:
71
+ | 选项 | 说明 |
72
+ | ------ | ------ |
73
+ | `--app <app>` | 应用包名 |
74
+ | `--hstack-tool-path <path>` | hstack 可执行文件;不配置则跳过该步并仅用原始 perf |
75
+ | `--sourcemap-dir <path>` | 传给 hstack 的 `-s` |
76
+ | `--log-key`、`--duration`、`--buffer-size` | 同 forkall |
77
+ | `--output-dir` | 默认 `.\output`;perf 文本子目录为 `perf_txt/` |
78
+ | `--trace-format-profile` | 同 forkall |
79
+ | `--risk-targets <targets>` | 默认 `all` |
80
+ | `--skip-perf-dedupe` | 同 forkall |
212
81
 
213
- ```ts
214
- // commands/bar.ts
215
- export const groups: Groups = {
216
- env: [
217
- { kind: "shell", description: "[bar] 打印当前目录", run: "pwd" },
218
- { kind: "shell", description: "[bar] 显示 Node 版本", run: "node -v" },
219
- ],
220
- list: [{ kind: "shell", description: "[bar] 列出当前目录", run: "ls -la" }],
221
- extra: [
222
- {
223
- kind: "shell",
224
- description: "[bar] 额外命令示例",
225
- run: "echo extra from bar",
226
- },
227
- ],
228
- };
229
-
230
- export const defaultGroupOrder: string[] = ["env", "extra", "list"];
82
+ ```bash
83
+ node dist/src/cli.js report --app com.example.app --risk-targets ipc,file
231
84
  ```
232
85
 
233
- CLI 会自动将 `commands` 目录下除 `config.*` 外的每个文件视为一个**场景命令**,文件名即子命令名:
234
-
235
- - `commands/foo.ts` → `snapshot-checker foo`
236
- - `commands/bar.ts` → `snapshot-checker bar`
237
-
238
- ## CLI 选项
239
-
240
- - `--wait`:所有**前台**命令跑完后,继续等待**后台**命令(`background: true`)自然退出再结束进程;不加则前台全部结束后会**优雅结束**这些后台子进程并立即退出 CLI。
241
- - `snapshot-checker <scene>` — 使用 `commands/<scene>.ts` 中的配置执行命令,例如:
242
- - `snapshot-checker foo` 使用 `commands/foo.ts` 的 `groups` 与 `defaultGroupOrder`
243
- - `snapshot-checker bar` 使用 `commands/bar.ts` 的 `groups` 与 `defaultGroupOrder`
244
- - `snapshot-checker foo --list` 仅列出 `foo` 场景中的命令,不执行
245
- - `snapshot-checker bar --list` 仅列出 `bar` 场景中的命令,不执行
86
+ ---
246
87
 
247
- ## 简单用例
88
+ ## 安装与本地开发
248
89
 
249
90
  ```bash
250
- # 使用 foo 场景(commands/foo.ts)执行命令
251
- node dist/cli.js foo
252
-
253
- # 仅查看 foo 场景中的命令(不执行)
254
- node dist/cli.js foo --list
255
-
256
- # 使用 bar 场景(commands/bar.ts)执行命令
257
- node dist/cli.js bar --group env,extra
258
-
259
- # 仅查看 bar 场景中的命令(不执行)
260
- node dist/cli.js bar --list
261
- ```
262
-
263
- ## 项目结构
264
-
265
- ```
266
- src/
267
- cli.ts # CLI 入口,负责解析参数并调用执行逻辑
268
- runCommand.ts # 单条/多条命令执行(无 group 概念)
269
- runGroups.ts # 组规格解析、分块、按组执行(含组间间隔)
270
- executor.ts # 统一导出 runCommand + runGroups
271
- types.ts # 类型定义
272
- index.ts # 库导出(从 commands/config.ts 导出默认 groups)
273
-
274
- commands/
275
- foo.ts # foo 场景示例:自定义 groups/defaultGroupOrder
276
- bar.ts # bar 场景示例:自定义 groups/defaultGroupOrder
277
-
278
- demos/
279
- consumer-app/ # 独立示例:npm install snapshot-checker 后的调用方式
91
+ npm install
92
+ npm run build
93
+ npm start -- --help # 或: node dist/src/cli.js --help
280
94
  ```
281
95
 
282
- ## 发布到 npm
96
+ 开发时可直接用源码跑(无需 build):
283
97
 
284
98
  ```bash
285
- npm login
286
- npm run build # prepublishOnly 也会在 publish 时执行
287
- npm publish
99
+ npm run dev -- forkall --list
288
100
  ```
289
101
 
290
- 若包名 `snapshot-checker` 已被占用,请在 `package.json` 中改为作用域包(如 `@your-org/snapshot-checker`)并相应更新下文导入路径。
291
-
292
- ## 作为库使用(npm install 之后)
102
+ ## 测试
293
103
 
294
- 安装:
104
+ 使用 `node:test` + `tsx`,文件位于 `tests/*.test.ts`。
295
105
 
296
106
  ```bash
297
- npm install snapshot-checker
107
+ npm test
298
108
  ```
299
109
 
300
- 在业务项目中调用**运行接口**(入口与源码中 `src/index.ts` 导出一致),并从一个或多个**包内场景模块**生成命令组(发布产物中为 `dist/commands/*.js`,通过 `exports` 暴露):
110
+ ## 作为库使用
111
+
112
+ 安装后可通过 `resolveScenario` + `runScenarioGroups` 注入场景 CLI 等价参数:
301
113
 
302
114
  ```ts
303
115
  import { resolveScenario, runScenarioGroups } from "snapshot-checker";
304
- import * as contextDemo from "snapshot-checker/commands/context_demo";
305
116
  import * as forkall from "snapshot-checker/commands/forkall";
306
117
 
307
118
  const { groups, defaultGroupOrder } = resolveScenario(forkall, {
@@ -313,108 +124,57 @@ const { groups, defaultGroupOrder } = resolveScenario(forkall, {
313
124
  await runScenarioGroups({ groups, defaultGroupOrder, stopOnError: true });
314
125
  ```
315
126
 
316
- 也可在业务项目自建 `commands/*.ts`,仅使用 `snapshot-checker` 的执行 API(`runScenarioGroups`、`getGroupChunks` 等),不引用包内场景。
317
-
318
- 独立 Node 示例工程(依赖 registry 上的本包):见 `demos/consumer-app/README.md`。
319
-
320
- 在该示例目录中可直接运行:
321
-
322
- ```bash
323
- cd demos/consumer-app
324
- npm install
325
- npm run context
326
- npm run forkall
327
- ```
328
-
329
- ## 包安装、更新与卸载
330
-
331
- ### 在业务项目中安装(推荐)
332
-
333
- ```bash
334
- npm install snapshot-checker
335
- ```
336
-
337
- 使用方式:
338
-
339
- ```bash
340
- npx snapshot-checker --help
341
- ```
342
-
343
- 卸载:
344
-
345
- ```bash
346
- npm uninstall snapshot-checker
347
- ```
348
-
349
- 更新到最新版本:
350
-
351
- ```bash
352
- npm install snapshot-checker@latest
353
- # 或更新已安装版本
354
- npm update snapshot-checker
355
- ```
356
-
357
- ### 全局安装(命令行直接可用)
127
+ 独立示例工程:`demos/consumer-app`(内含 `README` 与子命令演示)。
358
128
 
359
- ```bash
360
- npm install -g snapshot-checker
361
- snapshot-checker --help
362
- ```
129
+ ---
363
130
 
364
- 全局卸载/更新:
131
+ ## 次要:`snapshot-checker` CLI 场景框架与其它能力
365
132
 
366
- ```bash
367
- npm uninstall -g snapshot-checker
368
- npm install -g snapshot-checker@latest
369
- ```
133
+ 本工具本质是 **按命名场景(`commands/*.ts`、`demos/*.ts`)注册子命令**:每个文件导出 **`groups`**、**`defaultGroupOrder`**,可选 **`options`** 与 **`applyOptions(opts)`**——在运行时根据 Commander 解析结果重写命令表(`forkall` / `report` 即用此机制)。
370
134
 
371
- ### 本地调试安装(未发布时)
135
+ ### 命令类型与环境
372
136
 
373
- 在本仓库打包:
137
+ 默认只执行「当前操作系统支持」的条目:`windows` / `mac` / `linux` / `shell`;另有 **`embed`**(内置_sleep、timeout 等)与 **`builtin-function`**(TypeScript 函数)。不指定 `-g,--group` 时按 **`defaultGroupOrder`** 遍历各组。
374
138
 
375
- ```bash
376
- npm run build
377
- npm pack
378
- ```
139
+ ### `commands/` 最小场景
379
140
 
380
- 会生成 `snapshot-checker-<version>.tgz`,在目标项目中安装:
381
-
382
- ```bash
383
- npm install /path/to/snapshot-checker-<version>.tgz
141
+ ```ts
142
+ export const groups: Groups = {
143
+ env: [
144
+ { kind: "shell", description: "当前目录", run: "pwd" },
145
+ ],
146
+ };
147
+ export const defaultGroupOrder: string[] = ["env"];
384
148
  ```
385
149
 
386
- 卸载同样使用:
150
+ 子命令:`snapshot-checker <场景名>` 对应文件名(跳过 `config.*`)。
387
151
 
388
- ```bash
389
- npm uninstall snapshot-checker
390
- ```
152
+ ### 内置 `embed`
391
153
 
392
- ### 使用 npm link / unlink(本地软链调试)
154
+ - **`sleep <seconds>`** 休眠。
155
+ - **`timeout <seconds>`** — 倒计时等待,TTY 下可按键跳过;CI 中非 TTY 时仅延时。详见 `demos/timeout-demo.ts`。
393
156
 
394
- 在本仓库执行:
157
+ ### 命令上下文(`captureToVar`)
395
158
 
396
- ```bash
397
- npm link
398
- ```
159
+ 前序命令可把 stdout/stderr(或正则捕获组)写入变量,后续在 `run` / `cwd` 等处用 **`{{变量名}}`** 展开。示例见 `demos/context-demo.ts`。
399
160
 
400
- 在目标项目执行:
161
+ ### 其它 CLI 开关(作用于各场景子命令)
401
162
 
402
- ```bash
403
- npm link snapshot-checker
404
- ```
163
+ - **`--wait`** — 前台结束后仍等待后台命令自然退出;默认会结束后台进程后退出进程。
164
+ - **`--list`** — 只列出将要执行的命令。
165
+ - **`--dry-run`** — 打印序列但不执行。
166
+ - **`--stop-on-error`** — 遇错中止。
167
+ - **`-g,--group`** — 限定或重复某一组:`env:10,list` 等。
168
+ - **`--silent`**、`--interval`**、`--ignore-platform`、`--log-level`** 等 — 见 `snapshot-checker <scene> --help`。
405
169
 
406
- 取消软链(在目标项目):
170
+ ### `foo` / `bar` 与多场景
407
171
 
408
- ```bash
409
- npm unlink snapshot-checker
410
- ```
172
+ 仓库保留 `commands/foo.ts`、`commands/bar.ts` 等用于演示多套 `groups`;默认「运行」场景的入口仍可指向 `commands/config.ts`(若项目中使用 `run` 子命令时需与当前 `cli` 实现对齐)。
411
173
 
412
- 如需清理本机全局 link:
174
+ ### 发布与日常命令
413
175
 
414
- ```bash
415
- npm unlink -g snapshot-checker
416
- ```
176
+ 构建发布、全局/本地安装、`npm pack`、`npm link` 等与常规 Node 包相同;全局安装后:`snapshot-checker`。若远程包名不可用,可使用作用域名发布并相应调整 `package.json`。
417
177
 
418
- ## License
178
+ ### License
419
179
 
420
180
  MIT
@@ -1,13 +1,4 @@
1
1
  import type { Groups } from "../src/types.js";
2
- /**
3
- * forkall 场景的基础占位配置。
4
- * 实际要执行的命令会在 applyOptions 中,根据 CLI 传入的参数(eventPath/app 等)动态生成。
5
- *
6
- * 作为 npm 包被外部项目引用时:
7
- * import * as forkall from 'snapshot-checker/commands/forkall';
8
- * resolveScenario(forkall, { app, eventPath, ... })
9
- * 完整示例见 demos/consumer-app。
10
- */
11
2
  export declare const groups: Groups;
12
3
  export declare const defaultGroupOrder: string[];
13
4
  export declare const options: ({
@@ -30,10 +21,11 @@ interface ForkallOptions {
30
21
  mode?: string;
31
22
  outputDir?: string;
32
23
  traceFormatProfile?: string;
24
+ skipPerfDedupe?: boolean;
25
+ dropFailedSamples?: boolean;
26
+ dryRun?: boolean;
33
27
  }
34
- /**
35
- * 将 CLI 解析出来的参数应用到 forkall 场景,动态生成各阶段命令。
36
- */
28
+ /** 按 CLI 结果生成 reboot/monitor/collect/analysis 各阶段命令表 */
37
29
  export declare function applyOptions(ctx: {
38
30
  groups: Groups;
39
31
  defaultGroupOrder: string[];
@@ -1 +1 @@
1
- {"version":3,"file":"forkall.d.ts","sourceRoot":"","sources":["../../commands/forkall.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8B,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAS1E;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,EAAE,MAAW,CAAC;AAEjC,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAKrC,CAAC;AAEF,eAAO,MAAM,OAAO;;;;;;;;IA0CnB,CAAC;AAEF,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAkJD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CA+FlD"}
1
+ {"version":3,"file":"forkall.d.ts","sourceRoot":"","sources":["../../commands/forkall.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8B,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAkB1E,eAAO,MAAM,MAAM,EAAE,MAAW,CAAC;AAEjC,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAKrC,CAAC;AAEF,eAAO,MAAM,OAAO;;;;;;;;IAmDnB,CAAC;AAEF,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAkJD,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAqHlD"}