132 lines
7.0 KiB
Markdown
132 lines
7.0 KiB
Markdown
# 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/<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 通常需要创建或修改：
|
|
|
|
```text
|
|
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 |
|
|
|
|
详细说明见 [校验规则](docs/user/expectations.md) 和 [Checker 开发](docs/development/checker-development.md)。
|
|
|
|
## 测试要求
|
|
|
|
| 测试类别 | 覆盖内容 |
|
|
| ------------ | ---------------------------------------- |
|
|
| 契约测试 | 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 后通常需要运行：
|
|
|
|
```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/<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 已通过或记录未执行原因
|
|
```
|