3.8 KiB
Context
当前 command checker 使用 "command" 作为 type 和 configKey，对应源码目录 src/server/checker/runner/command/、测试目录 tests/server/checker/runner/command/、spec 目录 openspec/specs/command-checker/。
测试中使用了 true、false、sleep、bash、yes | head 等 Unix 系统命令，在纯 Windows 环境（无 Git Bash）下无法运行。probes.example.yaml 中的示例命令（uname -a、ls /tmp、date）同样不跨平台。
项目未上线，无向前兼容负担。
Goals / Non-Goals
Goals:
- 将 type/configKey 从
"command"统一重命名为"cmd"，包括源码目录、测试目录、spec 目录、YAML 配置键名 - 测试改用
bun -e "..."替代系统命令，确保 Windows/macOS/Linux 三平台通过 - probes.example.yaml 提供跨平台示例
Non-Goals:
- 不加 shell 模式（现有 exec + args 已覆盖所有 shell 场景）
- 不加重试机制（失败是拨测指标）
- 不精简 resolve() 中 intervalMs/timeoutMs（收益小，接口改动大）
- 不加 successExitCodes 别名（已有 expect.exitCode）
Decisions
D1: type 与 configKey 统一为 cmd
YAML 配置形态变为：
defaults:
cmd:
maxOutputBytes: "100MB"
targets:
- name: "test"
type: cmd
cmd:
exec: "bun"
args: ["-e", "console.log('hello')"]
理由： cmd 简洁，且 type 与 configKey 保持一致（与 HTTP checker 的 http/http 对称）。
替代方案： 只改 type 不改 configKey → 会出现 type: cmd + command: {...} 的不一致，否决。
D2: 内部属性名统一为 cmd
ResolvedCommandTarget 接口中的 command 属性名也改为 cmd：
// Before
interface ResolvedCommandTarget {
command: ResolvedCommandConfig;
type: "command";
}
// t.command.exec
// After
interface ResolvedCommandTarget {
cmd: ResolvedCommandConfig;
type: "cmd";
}
// t.cmd.exec
理由： 内外一致，避免 configKey 是 cmd 但内部属性是 command 的割裂。
D3: 源码目录重命名 runner/command/ → runner/cmd/
所有 import 路径同步更新。测试目录 tests/server/checker/runner/command/ → tests/server/checker/runner/cmd/。
理由： 目录名与 type/configKey 保持一致，降低认知负担。
D3: 跨平台测试命令替换表
| 原命令 | 替换为 |
|---|---|
true |
bun -e "process.exit(0)" |
false |
bun -e "process.exit(1)" |
echo hello |
bun -e "console.log('hello')" |
sleep 10 |
bun -e "await Bun.sleep(10000)" |
bash -c "echo error >&2" |
bun -e "process.stderr.write('error\n')" |
bash -c "yes | head -1000" |
bun -e "process.stdout.write('y\n'.repeat(1000))" |
理由： bun 是项目唯一运行时依赖，三平台均可用，无需额外安装。
D4: probes.example.yaml 示例策略
示例命令改用 bun -e "..." 或跨平台命令（如 bun --version），不再使用 uname、ls /tmp 等 Unix 专属命令。
D5: spec 目录重命名
openspec/specs/command-checker/ → openspec/specs/cmd-checker/，与 type 名称对齐。
D6: 不加 shell 模式
用户需要管道/重定向时，用现有参数即可：
cmd:
exec: "/bin/bash"
args: ["-c", "df -h | grep /dev/sda1"]
shell 模式本质是语法糖——内部仍然是 Bun.spawn([shell, "-c", exec])。增加代码复杂度（shell 检测、参数推断、互斥校验）但收益有限。
Risks / Trade-offs
- [全量重命名可能遗漏引用] → 通过全局搜索
"command"字面量确保无遗漏，CI 类型检查兜底 - [测试中
bun -e启动开销比原生命令大] → 拨测场景不敏感，测试可接受毫秒级差异 - [probes.example.yaml 示例不如 Unix 命令直观] → 加注释说明用途，保持可读性