DiAL/CONTRIBUTING.md

Contributing

本文档是 DiAL 的贡献入口，重点指导新增或修改 checker。通用开发命令和全局规则见 DEVELOPMENT.md，完整开发专题见 docs/development/。

通用贡献规则

• 使用中文编写注释、文档和项目内交流内容。
• 仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。
• 运行工具使用 bunx，禁止使用 npx、pnpx。
• 新增代码优先复用已有组件、工具和依赖库，不引入新依赖。
• 新增逻辑必须编写测试，不允许跳过测试。
• 每次代码变更必须执行文档影响分析，并按影响范围更新对应文档或说明无需更新。

新增或修改 Checker 前必读

文档	用途
README.md	项目定位、快速开始和用户入口
DEVELOPMENT.md	开发入口、常用命令、质量门禁和全局规则
docs/README.md	文档索引和文档归属矩阵
Checker 开发	checker 实现机制和详细 checklist
配置文件	YAML 顶层结构、变量和 target 通用字段
校验规则	ValueMatcher、ContentExpectations、KeyedExpectations
Checker 用户文档	已支持 checker 的配置和示例

还应阅读现有同类 checker 的实现和测试，例如 src/server/checker/runner/http/、src/server/checker/runner/cmd/ 和对应 tests/server/checker/runner/ 目录。

Checker 设计原则

• 每个 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。

文件清单

新增 checker 通常需要创建或修改：

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
docs/user/checkers/README.md

如果修改通用断言模型、开发机制或文档同步规则，还需要更新 docs/user/expectations.md、docs/development/checker-development.md、本文件或 docs/README.md。

分层要求

层	职责
types.ts	Raw/Resolved target 和 expect 类型
schema.ts	TypeBox Authoring/Normalized schema
validate.ts	JSON Schema 无法表达的语义校验
execute.ts	Checker 类，包含 resolve、execute、serialize
expect.ts	checker 专用断言
runner/index.ts	注册 checker

expect 模型选择

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

详细说明见 校验规则 和 Checker 开发。

测试要求

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

文档同步矩阵

变更	必须更新
新增 checker	docs/user/checkers/<type>.md、docs/user/checkers/README.md、probes.example.yaml
修改 checker 配置字段	对应 checker 用户文档、schema、测试、示例
修改 checker expect 字段	对应 checker 用户文档，必要时更新 docs/user/expectations.md
修改通用 expect 模型	docs/user/expectations.md、docs/development/checker-development.md
修改 checker 开发机制	docs/development/checker-development.md、本文件
修改文档同步规则	docs/README.md、openspec/config.yaml

验证命令

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

bun run schema
bun run schema:check
bun run check
bun run verify

如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。

完成 checklist

□ 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 已通过或记录未执行原因