113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
## 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 命令直观] → 加注释说明用途，保持可读性
|