DiAL/docs/development/checker-development.md

Checker 开发

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

新增或修改 checker 前请同时阅读 ../../CONTRIBUTING.md、配置文件、校验规则 和 Checker 用户文档。

架构目标

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 形态。

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/development/checker-development.md，仅当开发机制变化
• CONTRIBUTING.md，仅当贡献流程或 checklist 变化

完成检查清单

□ src/server/checker/runner/<type>/types.ts
□ src/server/checker/runner/<type>/schema.ts
□ src/server/checker/runner/<type>/validate.ts
□ src/server/checker/runner/<type>/execute.ts
□ src/server/checker/runner/<type>/expect.ts
□ src/server/checker/runner/<type>/index.ts
□ src/server/checker/runner/index.ts
□ tests/server/checker/runner/<type>/
□ probes.example.yaml
□ probe-config.schema.json
□ docs/user/checkers/<type>.md
□ bun run schema
□ bun run schema:check
□ bun run check
□ bun run verify