# Contributing 本文档是 DiAL 的贡献入口，重点指导新增或修改 checker。通用开发命令和全局规则见 [DEVELOPMENT.md](DEVELOPMENT.md)，完整开发专题见 [docs/development/](docs/development/README.md)。 ## 通用贡献规则 - 使用中文编写注释、文档和项目内交流内容。 - 仅使用 `bun` 作为包管理器，禁止使用 npm、pnpm、yarn。 - 运行工具使用 `bunx`，禁止使用 npx、pnpx。 - 新增代码优先复用已有组件、工具和依赖库，不引入新依赖。 - 新增逻辑必须编写测试，不允许跳过测试。 - 每次代码变更必须执行文档影响分析，并按影响范围更新对应文档或说明无需更新。 ## 新增或修改 Checker 前必读 | 文档 | 用途 | | ------------------------------------------------------- | ---------------------------------------------------- | | [README.md](README.md) | 项目定位、快速开始和用户入口 | | [DEVELOPMENT.md](DEVELOPMENT.md) | 开发入口、常用命令、质量门禁和全局规则 | | [docs/README.md](docs/README.md) | 文档索引和文档归属矩阵 | | [Checker 开发](docs/development/checker-development.md) | checker 实现机制和详细 checklist | | [配置文件](docs/user/configuration.md) | YAML 顶层结构、变量和 target 通用字段 | | [校验规则](docs/user/expectations.md) | ValueMatcher、ContentExpectations、KeyedExpectations | | [Checker 用户文档](docs/user/checkers/README.md) | 已支持 checker 的配置和示例 | 还应阅读现有同类 checker 的实现和测试，例如 `src/server/checker/runner/http/`、`src/server/checker/runner/cmd/` 和对应 `tests/server/checker/runner/` 目录。 ## Checker 设计原则 - 每个 checker 必须自包含在 `src/server/checker/runner//`。 - 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 通常需要创建或修改： ```text src/server/checker/runner//types.ts src/server/checker/runner//schema.ts src/server/checker/runner//validate.ts src/server/checker/runner//execute.ts src/server/checker/runner//expect.ts src/server/checker/runner//index.ts src/server/checker/runner/index.ts tests/server/checker/runner// probes.example.yaml probe-config.schema.json docs/user/checkers/.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 | 详细说明见 [校验规则](docs/user/expectations.md) 和 [Checker 开发](docs/development/checker-development.md)。 ## 测试要求 | 测试类别 | 覆盖内容 | | ------------ | ---------------------------------------- | | 契约测试 | TypeBox schema 与 JSON Schema 导出一致性 | | 语义校验测试 | 合法和非法配置 | | resolve 测试 | 默认值合并、路径解析、单位转换 | | execute 测试 | 成功、失败、超时、expect 组合 | | 注册测试 | registry 注册行为 | | 配置加载测试 | 含新 checker 的 YAML 完整加载流程 | ## 文档同步矩阵 | 变更 | 必须更新 | | ------------------------ | ------------------------------------------------------------------------------------- | | 新增 checker | `docs/user/checkers/.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 后通常需要运行： ```bash bun run schema bun run schema:check bun run check bun run verify ``` 如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。 ## 完成 checklist ```text □ checker 类型、schema、validate、resolve、execute、serialize 已实现 □ checker 已在 runner/index.ts 注册 □ 配置契约、语义校验和 JSON Schema 导出已同步 □ probes.example.yaml 已添加或更新示例 □ tests/server/checker/runner// 已覆盖契约、校验、resolve、execute、注册和配置加载 □ docs/user/checkers/.md 已添加或更新 □ docs/user/checkers/README.md 已添加或更新 □ 文档影响分析已完成，必要文档已同步 □ bun run schema 和 bun run schema:check 已通过 □ bun run check 已通过 □ bun run verify 已通过或记录未执行原因 ```