feat: 新增两个 OpenSpec 变更提案 — CMD Checker 增强与前端指标增强

openspec/changes/cmd-checker-enhancement/design.md

@@ -0,0 +1,112 @@
+## 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 配置形态变为：
+
+```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`：
+
+```typescript
+// 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 模式
+
+用户需要管道/重定向时，用现有参数即可：
+
+```yaml
+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 命令直观] → 加注释说明用途，保持可读性