# CPU Checker

`type: cpu` 用于检查本机 CPU 使用率，基于两次系统快照计算总体和每核心的忙碌比例。

## 配置项

| 字段                 | 说明                             | 必填 | 默认值  |
| -------------------- | -------------------------------- | ---- | ------- |
| `cpu.sampleDuration` | CPU 采样窗口，支持时长格式       | 否   | `1s`    |
| `cpu.includePerCore` | 是否在结果中输出每核心使用率数组 | 否   | `false` |

`sampleDuration` 必须小于 target 的 `timeout`。

## expect 校验项

| 字段                  | 说明                                                                          | 必填 | 默认值 |
| --------------------- | ----------------------------------------------------------------------------- | ---- | ------ |
| `usagePercent`        | 总体 CPU 使用率，范围 `0-100`，使用 `ValueMatcher`                            | 否   | 无     |
| `idlePercent`         | 总体 CPU 空闲率，与 `usagePercent` 互补（`idlePercent = 100 - usagePercent`） | 否   | 无     |
| `maxCoreUsagePercent` | 单核心最高使用率，使用 `ValueMatcher`                                         | 否   | 无     |
| `minCoreUsagePercent` | 单核心最低使用率，使用 `ValueMatcher`                                         | 否   | 无     |
| `durationMs`          | 完整执行耗时校验，使用 `ValueMatcher`                                         | 否   | 无     |

所有百分比字段范围为 `0-100`，表示所有可见逻辑 CPU 的总体比例，不是"核心数 × 100"。

## 示例

```yaml
- id: "local-cpu"
  name: "本机 CPU"
  type: cpu
  interval: "30s"
  timeout: "5s"
  cpu:
    sampleDuration: "1s"
  expect:
    usagePercent:
      lte: 85
    maxCoreUsagePercent:
      lte: 95
```

输出每核心使用率：

```yaml
- id: "local-cpu-detail"
  name: "本机 CPU 详细"
  type: cpu
  cpu:
    sampleDuration: "2s"
    includePerCore: true
  expect:
    usagePercent:
      lte: 80
```

## 语义说明

CPU checker 采集的是 DiAL 进程运行环境通过系统 API（`os.cpus()`）可见的 CPU 视图。在容器中，它可能不等于严格的 cgroup quota 使用率。

`usagePercent` 和 `idlePercent` 互补，恒等于 100。`sampleDuration` 决定了两次快照之间的等待时间，窗口越长结果越稳定，但会增加 checker 执行耗时。

## 不支持的功能

- CPU 温度、电源状态、频率
- `userPercent` / `systemPercent`（用户态/系统态占比）
- `loadAverage`（系统负载均值）
- 进程级 CPU 使用率
- Linux cgroup 精确 CPU 计算
- `logicalCoreCount` 作为 expect 字段（仅在 observation 中输出）

## 更新触发条件

修改 CPU checker 配置、expect 字段、行为或语义时，必须更新本文档。