feat: 新增 ICMP/Ping checker，支持跨平台主机存活检测与延迟监控

实现 type: ping checker，通过 Bun.spawn 调用系统 ping 命令，自行实现跨平台
输出解析器（Linux/macOS/Windows 含中文 locale），支持 alive、丢包率、延迟、
耗时等 expect 断言，复用现有 checker 架构零外部依赖。

包含完整的类型定义、TypeBox schema、语义校验、命令构建、解析、断言、执行、
注册、配置加载测试，以及 probe-config.schema.json 更新和文档更新。

审查修复：提取 buildPingCommand 为独立纯函数并补充跨平台单测，补充
maxDurationMs/maxAvgLatencyMs 类型非法和空字符串 host 边界测试用例。

变更已归档，delta specs 已同步至 main specs。

tests/server/checker/config-loader.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 
 import type { ResolvedCommandTarget } from "../../../src/server/checker/runner/cmd/types";
 import type { ResolvedHttpTarget } from "../../../src/server/checker/runner/http/types";
+import type { ResolvedPingTarget } from "../../../src/server/checker/runner/icmp/types";
 import type { ResolvedTcpTarget } from "../../../src/server/checker/runner/tcp/types";
 
 import { loadConfig, parseDuration } from "../../../src/server/checker/config-loader";
@@ -1974,4 +1975,99 @@ targets:
     expect(t.expect?.connected).toBe(false);
     expect(t.expect?.maxDurationMs).toBe(5000);
   });
+
+  test("解析最简 ping 配置", async () => {
+    const configPath = join(tempDir, "minimal-ping.yaml");
+    await writeFile(
+      configPath,
+      `targets:
+  - id: "gateway"
+    type: ping
+    ping:
+      host: "10.0.0.1"
+`,
+    );
+
+    const config = await loadConfig(configPath);
+    expect(config.targets).toHaveLength(1);
+    const t = config.targets[0]! as ResolvedPingTarget;
+    expect(t.type).toBe("ping");
+    expect(t.ping).toEqual({ count: 3, host: "10.0.0.1", packetSize: 56 });
+    expect(t.group).toBe("default");
+    expect(t.intervalMs).toBe(30000);
+    expect(t.timeoutMs).toBe(10000);
+  });
+
+  test("解析 ping expect 配置", async () => {
+    const configPath = join(tempDir, "ping-expect.yaml");
+    await writeFile(
+      configPath,
+      `targets:
+  - id: "gateway"
+    type: ping
+    ping:
+      host: "10.0.0.1"
+      count: 5
+      packetSize: 1472
+    expect:
+      alive: true
+      maxPacketLoss: 10
+      maxAvgLatencyMs: 200
+      maxMaxLatencyMs: 500
+      maxDurationMs: 5000
+`,
+    );
+
+    const config = await loadConfig(configPath);
+    const t = config.targets[0]! as ResolvedPingTarget;
+    expect(t.ping).toEqual({ count: 5, host: "10.0.0.1", packetSize: 1472 });
+    expect(t.expect).toEqual({
+      alive: true,
+      maxAvgLatencyMs: 200,
+      maxDurationMs: 5000,
+      maxMaxLatencyMs: 500,
+      maxPacketLoss: 10,
+    });
+  });
+
+  test("ping 缺少 host 抛出错误", async () => {
+    await expectConfigError(
+      "ping-no-host.yaml",
+      `targets:
+  - id: "gateway"
+    type: ping
+    ping: {}
+`,
+      "ping.host",
+    );
+  });
+
+  test("ping count 非法抛出错误", async () => {
+    await expectConfigError(
+      "ping-bad-count.yaml",
+      `targets:
+  - id: "gateway"
+    type: ping
+    ping:
+      host: "10.0.0.1"
+      count: 0
+`,
+      "ping.count",
+    );
+  });
+
+  test("ping expect 未知字段抛出错误", async () => {
+    await expectConfigError(
+      "ping-unknown-expect.yaml",
+      `targets:
+  - id: "gateway"
+    type: ping
+    ping:
+      host: "10.0.0.1"
+    expect:
+      status: [200]
+`,
+      "expect.status 是未知字段",
+    );
+  });
 });

tests/server/checker/runner/icmp/command.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+
+import type { ResolvedPingTarget } from "../../../../../src/server/checker/runner/icmp/types";
+
+import { buildPingCommand } from "../../../../../src/server/checker/runner/icmp/command";
+
+function makeTarget(overrides?: Partial<ResolvedPingTarget>): ResolvedPingTarget {
+  return {
+    description: null,
+    group: "default",
+    id: "test",
+    intervalMs: 30000,
+    name: null,
+    ping: { count: 3, host: "10.0.0.1", packetSize: 56 },
+    timeoutMs: 10000,
+    type: "ping",
+    ...overrides,
+  };
+}
+
+describe("buildPingCommand", () => {
+  test("Linux 默认参数", () => {
+    const cmd = buildPingCommand(makeTarget(), "linux");
+    expect(cmd).toEqual(["ping", "-c", "3", "-s", "56", "-W", "10", "10.0.0.1"]);
+  });
+
+  test("Linux 秒向上取整", () => {
+    const cmd = buildPingCommand(makeTarget({ timeoutMs: 10500 }), "linux");
+    expect(cmd[6]).toBe("11");
+  });
+
+  test("Linux timeoutMs < 1000 向上取整为 1", () => {
+    const cmd = buildPingCommand(makeTarget({ timeoutMs: 500 }), "linux");
+    expect(cmd[6]).toBe("1");
+  });
+
+  test("macOS 毫秒", () => {
+    const cmd = buildPingCommand(makeTarget(), "darwin");
+    expect(cmd).toEqual(["ping", "-c", "3", "-s", "56", "-W", "10000", "10.0.0.1"]);
+  });
+
+  test("Windows 格式", () => {
+    const cmd = buildPingCommand(makeTarget(), "win32");
+    expect(cmd).toEqual(["ping", "-n", "3", "-l", "56", "-w", "10000", "10.0.0.1"]);
+  });
+
+  test("自定义 count 和 packetSize", () => {
+    const cmd = buildPingCommand(
+      makeTarget({ ping: { count: 5, host: "10.0.0.1", packetSize: 1472 }, timeoutMs: 5000 }),
+      "linux",
+    );
+    expect(cmd).toEqual(["ping", "-c", "5", "-s", "1472", "-W", "5", "10.0.0.1"]);
+  });
+});

tests/server/checker/runner/icmp/execute.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { ResolvedPingTarget } from "../../../../../src/server/checker/runner/icmp/types";
+import type { CheckerContext } from "../../../../../src/server/checker/runner/types";
+
+import { IcmpChecker } from "../../../../../src/server/checker/runner/icmp/execute";
+
+const checker = new IcmpChecker();
+const originalSpawn = Bun.spawn;
+
+afterEach(() => {
+  Bun.spawn = originalSpawn;
+  mock.restore();
+});
+
+function makeCtx(): CheckerContext {
+  return { signal: new AbortController().signal };
+}
+
+function makeTarget(overrides?: Partial<ResolvedPingTarget>): ResolvedPingTarget {
+  return {
+    description: null,
+    group: "default",
+    id: "ping-local",
+    intervalMs: 30000,
+    name: null,
+    ping: { count: 3, host: "127.0.0.1", packetSize: 56 },
+    timeoutMs: 10000,
+    type: "ping",
+    ...overrides,
+  };
+}
+
+function mockSpawn(stdout: string, exitCode = 0) {
+  const calls: string[][] = [];
+  const spawnMock = mock((command: string[]) => {
+    calls.push(command);
+    return {
+      exitCode,
+      exited: Promise.resolve(exitCode),
+      kill: mock(() => undefined),
+      stderr: new Response("").body,
+      stdout: new Response(stdout).body,
+    };
+  });
+  Bun.spawn = spawnMock as unknown as typeof Bun.spawn;
+  return calls;
+}
+
+describe("IcmpChecker execute", () => {
+  test("执行 ping 并匹配默认 alive", async () => {
+    const calls = mockSpawn(`3 packets transmitted, 3 received, 0% packet loss, time 2003ms
+rtt min/avg/max/mdev = 1.234/2.345/3.456/0.567 ms`);
+    const result = await checker.execute(makeTarget(), makeCtx());
+    expect(result.matched).toBe(true);
+    expect(result.failure).toBeNull();
+    expect(result.statusDetail).toBe("alive, avg 2.345ms, loss 0% (3/3)");
+    expect(calls[0]).toContain("ping");
+  });
+
+  test("alive 失败短路", async () => {
+    mockSpawn(`3 packets transmitted, 0 received, 100% packet loss, time 2003ms`);
+    const result = await checker.execute(makeTarget({ expect: { alive: true, maxAvgLatencyMs: 100 } }), makeCtx());
+    expect(result.matched).toBe(false);
+    expect(result.failure?.phase).toBe("alive");
+    expect(result.statusDetail).toBe("unreachable (0/3 received)");
+  });
+
+  test("反向 alive 断言通过", async () => {
+    mockSpawn(`3 packets transmitted, 0 received, 100% packet loss, time 2003ms`);
+    const result = await checker.execute(makeTarget({ expect: { alive: false } }), makeCtx());
+    expect(result.matched).toBe(true);
+  });
+
+  test("packetLoss 断言失败", async () => {
+    mockSpawn(`3 packets transmitted, 2 received, 33% packet loss, time 2003ms
+rtt min/avg/max/mdev = 1.234/156.000/340.000/0.567 ms`);
+    const result = await checker.execute(makeTarget({ expect: { maxPacketLoss: 10 } }), makeCtx());
+    expect(result.matched).toBe(false);
+    expect(result.failure?.phase).toBe("packetLoss");
+    expect(result.statusDetail).toContain("max 340ms");
+  });
+
+  test("解析失败返回结构化错误", async () => {
+    mockSpawn("unexpected output");
+    const result = await checker.execute(makeTarget(), makeCtx());
+    expect(result.matched).toBe(false);
+    expect(result.failure).toMatchObject({ kind: "error", path: "parse", phase: "ping" });
+  });
+
+  test("spawn 失败返回 ping 命令不可用", async () => {
+    Bun.spawn = mock(() => {
+      throw new Error("ENOENT");
+    });
+    const result = await checker.execute(makeTarget(), makeCtx());
+    expect(result.matched).toBe(false);
+    expect(result.failure?.message).toContain("ping 命令不可用");
+    expect(result.statusDetail).toBe("ping command not found");
+  });
+
+  test("预 abort 返回超时错误", async () => {
+    mockSpawn(`3 packets transmitted, 3 received, 0% packet loss, time 2003ms`);
+    const controller = new AbortController();
+    controller.abort();
+    const result = await checker.execute(makeTarget(), { signal: controller.signal });
+    expect(result.matched).toBe(false);
+    expect(result.failure).toMatchObject({ path: "timeout", phase: "ping" });
+  });
+});
+
+describe("IcmpChecker resolve", () => {
+  test("解析默认值", () => {
+    const target = checker.resolve(
+      { id: "ping", ping: { host: "10.0.0.1" }, type: "ping" },
+      { configDir: "/tmp", defaultIntervalMs: 30000, defaults: {}, defaultTimeoutMs: 10000 },
+    );
+    expect(target.ping).toEqual({ count: 3, host: "10.0.0.1", packetSize: 56 });
+    expect(target.group).toBe("default");
+  });
+
+  test("serialize 返回摘要和配置", () => {
+    const serialized = checker.serialize(makeTarget({ ping: { count: 5, host: "10.0.0.1", packetSize: 1472 } }));
+    expect(serialized.target).toBe("ping 10.0.0.1");
+    expect(JSON.parse(serialized.config)).toEqual({ count: 5, host: "10.0.0.1", packetSize: 1472 });
+  });
+});

tests/server/checker/runner/icmp/expect.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  checkAlive,
+  checkAvgLatency,
+  checkMaxLatency,
+  checkPacketLoss,
+} from "../../../../../src/server/checker/runner/icmp/expect";
+
+describe("ping expect", () => {
+  test("alive 通过和失败", () => {
+    expect(checkAlive(true, true).matched).toBe(true);
+    const result = checkAlive(false, true);
+    expect(result.matched).toBe(false);
+    expect(result.failure?.phase).toBe("alive");
+  });
+
+  test("packetLoss 通过和失败", () => {
+    expect(checkPacketLoss(0, 10).matched).toBe(true);
+    const result = checkPacketLoss(33, 10);
+    expect(result.matched).toBe(false);
+    expect(result.failure?.phase).toBe("packetLoss");
+  });
+
+  test("avgLatency 通过和失败", () => {
+    expect(checkAvgLatency(12, 200).matched).toBe(true);
+    const result = checkAvgLatency(156, 100);
+    expect(result.matched).toBe(false);
+    expect(result.failure?.phase).toBe("avgLatency");
+  });
+
+  test("maxLatency 通过和失败", () => {
+    expect(checkMaxLatency(340, 500).matched).toBe(true);
+    const result = checkMaxLatency(340, 200);
+    expect(result.matched).toBe(false);
+    expect(result.failure?.phase).toBe("maxLatency");
+  });
+
+  test("未配置阈值默认通过", () => {
+    expect(checkPacketLoss(100, undefined).matched).toBe(true);
+    expect(checkAvgLatency(null, undefined).matched).toBe(true);
+    expect(checkMaxLatency(null, undefined).matched).toBe(true);
+  });
+});

tests/server/checker/runner/icmp/parse.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+
+import { parsePingOutput } from "../../../../../src/server/checker/runner/icmp/parse";
+
+describe("parsePingOutput", () => {
+  test("解析 Linux ping 输出", () => {
+    const stats = parsePingOutput(
+      `3 packets transmitted, 3 received, 0% packet loss, time 2003ms
+rtt min/avg/max/mdev = 1.234/2.345/3.456/0.567 ms`,
+      "linux",
+    );
+    expect(stats).toEqual({
+      alive: true,
+      avgLatencyMs: 2.345,
+      maxLatencyMs: 3.456,
+      minLatencyMs: 1.234,
+      packetLoss: 0,
+      received: 3,
+      transmitted: 3,
+    });
+  });
+
+  test("解析 macOS ping 输出", () => {
+    const stats = parsePingOutput(
+      `3 packets transmitted, 3 packets received, 0.0% packet loss
+round-trip min/avg/max/stddev = 1.234/2.345/3.456/0.567 ms`,
+      "darwin",
+    );
+    expect(stats?.avgLatencyMs).toBe(2.345);
+    expect(stats?.packetLoss).toBe(0);
+  });
+
+  test("解析 Windows 英文 ping 输出", () => {
+    const stats = parsePingOutput(
+      `Packets: Sent = 3, Received = 3, Lost = 0 (0% loss),
+Approximate round trip times in milli-seconds:
+    Minimum = 1ms, Maximum = 3ms, Average = 2ms`,
+      "win32",
+    );
+    expect(stats).toMatchObject({ avgLatencyMs: 2, maxLatencyMs: 3, minLatencyMs: 1, packetLoss: 0 });
+  });
+
+  test("解析 Windows 中文 ping 输出", () => {
+    const stats = parsePingOutput(
+      `数据包: 已发送 = 3，已接收 = 3，丢失 = 0 (0% 丢失)，
+往返行程的估计时间(以毫秒为单位):
+    最短 = 1ms，最长 = 3ms，平均 = 2ms`,
+      "win32",
+    );
+    expect(stats).toMatchObject({ avgLatencyMs: 2, maxLatencyMs: 3, minLatencyMs: 1, packetLoss: 0 });
+  });
+
+  test("解析全部丢包", () => {
+    const stats = parsePingOutput(`3 packets transmitted, 0 received, 100% packet loss, time 2003ms`, "linux");
+    expect(stats).toMatchObject({ alive: false, avgLatencyMs: null, maxLatencyMs: null, minLatencyMs: null });
+  });
+
+  test("无法解析返回 null", () => {
+    expect(parsePingOutput("unexpected output", "linux")).toBeNull();
+  });
+});

tests/server/checker/runner/icmp/validate.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+
+import type { RawTargetConfig } from "../../../../../src/server/checker/types";
+
+import { validatePingConfig } from "../../../../../src/server/checker/runner/icmp/validate";
+
+function validate(target: RawTargetConfig) {
+  return validatePingConfig({ defaults: {}, targets: [target] });
+}
+
+describe("validatePingConfig", () => {
+  test("有效配置无错误", () => {
+    expect(validate({ id: "ping", ping: { count: 3, host: "127.0.0.1", packetSize: 56 }, type: "ping" })).toEqual([]);
+  });
+
+  test("host 缺失", () => {
+    const issues = validate({ id: "ping", ping: {}, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("ping.host"))).toBe(true);
+  });
+
+  test("host 类型非法", () => {
+    const issues = validate({ id: "ping", ping: { host: 123 }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("ping.host"))).toBe(true);
+  });
+
+  test("count 非法", () => {
+    const issues = validate({ id: "ping", ping: { count: 0, host: "127.0.0.1" }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("ping.count"))).toBe(true);
+  });
+
+  test("packetSize 非法", () => {
+    const issues = validate({ id: "ping", ping: { host: "127.0.0.1", packetSize: 65501 }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("ping.packetSize"))).toBe(true);
+  });
+
+  test("ping 未知字段", () => {
+    const issues = validate({ id: "ping", ping: { host: "127.0.0.1", timeout: 5 }, type: "ping" });
+    expect(issues.some((item) => item.code === "unknown-field" && item.path.endsWith("ping.timeout"))).toBe(true);
+  });
+
+  test("expect 未知字段", () => {
+    const issues = validate({ expect: { status: [200] }, id: "ping", ping: { host: "127.0.0.1" }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("expect.status"))).toBe(true);
+  });
+
+  test("expect 数值非法", () => {
+    const issues = validate({ expect: { maxPacketLoss: 101 }, id: "ping", ping: { host: "127.0.0.1" }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("expect.maxPacketLoss"))).toBe(true);
+  });
+
+  test("maxDurationMs 类型非法", () => {
+    const issues = validate({ expect: { maxDurationMs: -1 }, id: "ping", ping: { host: "127.0.0.1" }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("expect.maxDurationMs"))).toBe(true);
+  });
+
+  test("maxAvgLatencyMs 类型非法", () => {
+    const issues = validate({
+      expect: { maxAvgLatencyMs: "slow" },
+      id: "ping",
+      ping: { host: "127.0.0.1" },
+      type: "ping",
+    });
+    expect(issues.some((item) => item.path.endsWith("expect.maxAvgLatencyMs"))).toBe(true);
+  });
+
+  test("host 为空字符串", () => {
+    const issues = validate({ id: "ping", ping: { host: "  " }, type: "ping" });
+    expect(issues.some((item) => item.path.endsWith("ping.host"))).toBe(true);
+  });
+});

tests/server/checker/runner/registry.test.ts

@@ -66,12 +66,18 @@ describe("CheckerRegistry", () => {
     const second = createDefaultCheckerRegistry();
     first.register(createChecker("custom"));
 
-    expect(first.supportedTypes).toEqual(["http", "cmd", "db", "tcp", "custom"]);
-    expect(second.supportedTypes).toEqual(["http", "cmd", "db", "tcp"]);
+    expect(first.supportedTypes).toEqual(["http", "cmd", "db", "tcp", "ping", "custom"]);
+    expect(second.supportedTypes).toEqual(["http", "cmd", "db", "tcp", "ping"]);
     expect(
       first.definitions.every(
         (checker) => checker.schemas.config && checker.schemas.defaults && checker.schemas.expect,
       ),
     ).toBe(true);
   });
+
+  test("默认 registry 注册 ping type", () => {
+    const registry = createDefaultCheckerRegistry();
+    expect(registry.supportedTypes).toContain("ping");
+    expect(registry.get("ping").configKey).toBe("ping");
+  });
 });