# Checker 开发

Checker 是 DiAL 的核心扩展单元。每个 checker 是 `src/server/checker/runner/<type>/` 下的自包含目录，包含类型、schema、语义校验、执行逻辑、序列化和断言。

适用场景：新增 checker、修改 checker 配置或 expect、调整 checker 注册机制、改动 checker 测试或用户文档同步规则。

新增或修改 checker 前必须阅读 [开发入口](README.md)、[配置文件](../user/configuration.md)、[校验规则](../user/expectations.md) 和 [Checker 用户文档](../user/checkers/README.md)。还应阅读现有同类 checker 的实现和测试，例如 `src/server/checker/runner/http/` 与 `tests/server/checker/runner/http/`。

## 设计原则

- 每个 checker 必须自包含在 `src/server/checker/runner/<type>/`。
- checker 专属类型、schema、validate、execute、expect 和协议辅助逻辑放在同一目录。
- 注册只修改 `src/server/checker/runner/index.ts`，中间层不新增 type switch。
- schema 层只描述契约，语义规则放入 `validate.ts`。
- `resolve()` 只做默认值填充、路径解析和单位转换，不执行校验。
- `execute()` 必须支持 `CheckerContext.signal` 超时取消。
- expect 字段必须选择合适断言模型，不为了统一而滥用 ValueMatcher。
- failure phase 命名遵循去单位后缀规则，例如 `durationMs` 对应 `duration`。

## 架构目标

```text
checkerRegistry
  ├── runner/index.ts
  ├── schema/builder.ts
  ├── schema/validate.ts
  ├── config-loader.ts
  ├── engine.ts
  └── store.ts
```

注册后，中间层通过 registry 自动委托 schema 生成、契约校验、配置 resolve、执行和序列化。新增 checker 不应在中间层新增 `switch/case` 或类型分支。

## 标准文件结构

| 文件          | 职责                                                  |
| ------------- | ----------------------------------------------------- |
| `index.ts`    | 模块入口，re-export Checker 类                        |
| `types.ts`    | Checker 专属类型                                      |
| `schema.ts`   | TypeBox 契约 schema，包含 config 和 expect            |
| `validate.ts` | 启动期语义校验                                        |
| `execute.ts`  | Checker 类，实现 resolve、execute、serialize          |
| `expect.ts`   | Checker 专用断言函数                                  |
| 其他文件      | 协议解析、编码、provider 适配、平台命令封装等专属逻辑 |

## 类型定义

在 `types.ts` 中定义：

- `RawXxxTargetConfig`
- `RawXxxExpectConfig`
- `ResolvedXxxExpectConfig`
- `ResolvedXxxTarget extends ResolvedTargetBase`

不需要修改顶层 `checker/types.ts`。base interface 使用 index signature 支持扩展。

## Schema

checker 必须提供 `CheckerSchemas`，包含 Authoring 和 Normalized 两套 config/expect 片段。Authoring 描述用户 YAML 可写 DSL，Normalized 描述 normalizer 输出。

常用 fragments：

| Fragment                            | 用途                      |
| ----------------------------------- | ------------------------- |
| `durationSchema`                    | 时长字符串                |
| `sizeSchema`                        | 大小单位                  |
| `statusCodePatternSchema`           | HTTP 状态码或范围         |
| `stringMapSchema`                   | headers、env 等字符串映射 |
| `createValueMatcherSchema()`        | ValueMatcher              |
| `createContentExpectationsSchema()` | ContentExpectations       |
| `createKeyedExpectationsSchema()`   | KeyedExpectations         |

默认对象策略为 `additionalProperties: false`。只有明确的动态键值表可以开放任意键名。

## 语义校验

在 `validate.ts` 中实现 JSON Schema 无法表达的规则，统一返回 `ConfigValidationIssue[]`，不要直接拼接最终错误字符串。

共享校验工具包括：

| 函数                             | 用途                         |
| -------------------------------- | ---------------------------- |
| `validateRawValueExpectation`    | 校验 Raw ValueExpectation    |
| `validateRawContentExpectations` | 校验 ContentExpectations     |
| `validateRawKeyedExpectations`   | 校验 KeyedExpectations       |
| `validateJsonPath`               | 校验项目支持的 JSONPath 子集 |
| `isJsonValue`                    | 判断合法 JSON value          |

## resolve 规范

`resolve()` 只做内置默认值填充、路径解析、单位转换，不执行校验。输入已经通过 Normalized schema 和语义校验，expect 已是 normalized 形态。

```typescript
const expect = target.expect as ResolvedXxxExpectConfig | undefined;
const resolvedExpect: ResolvedXxxExpectConfig = expect
  ? { ...expect, status: expect.status ?? [200] }
  : { status: [200] };
```

返回值使用 `satisfies ResolvedXxxTarget` 确保类型正确。

## execute 规范

- 始终记录 `timestamp` 和 `start = performance.now()`。
- 通过 `ctx.signal` 支持超时取消。
- 首个 expect 失败即停止，返回带 `failure` 的结果。
- 成功时 `failure: null, matched: true`。
- 异常时使用 `errorFailure()`。
- 不匹配时使用 `mismatchFailure()`。
- `expected` 参数应传用户可读值，必要时使用 `displayValueExpectation()`。

## expect 字段选择

| 场景                                 | 模型                |
| ------------------------------------ | ------------------- |
| 状态类结果且集合小而稳定             | enum 或 boolean     |
| 单值数字指标或字符串元数据           | ValueMatcher        |
| 文本、JSON、HTML、XML 或半结构化内容 | ContentExpectations |
| 动态键值表                           | KeyedExpectations   |

不要为了统一而把状态类字段改成 ValueMatcher。一个 expect 字段只能对应一种断言模型。

## 注册

1. 创建 `src/server/checker/runner/<type>/index.ts`。
2. 在 `src/server/checker/runner/index.ts` 添加导入。
3. 在 registry 初始化数组中添加 checker 实例。

注册后，schema builder、validate、config-loader、engine、store 会自动按 registry 分发。

## 测试要求

测试文件放在 `tests/server/checker/runner/<type>/`，结构镜像源文件。

| 测试类别     | 覆盖内容                                 |
| ------------ | ---------------------------------------- |
| 契约测试     | TypeBox schema 与 JSON Schema 导出一致性 |
| 语义校验测试 | 合法和非法配置                           |
| resolve 测试 | 默认值合并、路径解析、单位转换           |
| execute 测试 | 成功、失败、超时、expect 组合            |
| 注册测试     | registry 注册行为                        |
| 配置加载测试 | 含新 checker 的 YAML 完整加载流程        |

## 文档和 schema 更新

新增或修改 checker 时通常需要更新：

- `probes.example.yaml`
- `probe-config.schema.json`，通过 `bun run schema` 生成
- `docs/user/checkers/<type>.md`
- `docs/user/checkers/README.md`
- `docs/user/expectations.md`，仅当断言模型、状态模型或通用规则变化
- `docs/user/configuration.md`，仅当 target 通用字段或配置加载形态变化
- `docs/development/checker.md`，仅当 checker 开发机制、测试要求或 checklist 变化
- `docs/README.md` 和 `openspec/config.yaml`，仅当文档同步规则变化

## 验证命令

新增或修改 checker 后通常需要运行：

```bash
bun run schema
bun run schema:check
bun run check
```

影响构建、Docker 或发布包时追加运行 `bun run verify`。

## 完成检查清单

```text
□ checker 类型、schema、validate、resolve、execute、serialize 已实现
□ checker 已在 runner/index.ts 注册
□ 配置契约、语义校验和 JSON Schema 导出已同步
□ probes.example.yaml 已添加或更新示例
□ tests/server/checker/runner/<type>/ 已覆盖契约、校验、resolve、execute、注册和配置加载
□ docs/user/checkers/<type>.md 已添加或更新
□ docs/user/checkers/README.md 已添加或更新
□ 文档影响分析已完成，必要文档已同步
□ bun run schema 和 bun run schema:check 已通过
□ bun run check 已通过
□ bun run verify 已通过或记录未执行原因
```

## 更新触发条件

修改 checker 开发机制、目录结构、schema/validate/resolve/execute/expect 约定、测试要求、验证命令或文档同步 checklist 时，必须更新本文档。