From 714b635aef2c7f6153a36db3b6f55089adebb1b6 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Mon, 25 May 2026 10:47:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=BD=93=E7=B3=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 合并 DEVELOPMENT.md 至 docs/development/README.md - 合并 CONTRIBUTING.md 至 docs/development/checker.md - 合并 build-release.md 至 release.md - 合并 testing-quality.md 内容至各专题文档 - 合并 status-model.md 至 expectations.md - 新增 docs/user/README.md 用户入口 - 简化 docs/README.md 文档路由 - 各专题文档新增适用场景和更新触发条件 - 更新 openspec/config.yaml 文档规则 --- CONTRIBUTING.md | 131 --------------- DEVELOPMENT.md | 115 ------------- README.md | 23 +-- docs/README.md | 159 +++++++++--------- docs/development/README.md | 124 ++++++++++++-- docs/development/architecture.md | 8 + docs/development/backend.md | 29 +++- .../{checker-development.md => checker.md} | 66 +++++--- docs/development/frontend.md | 17 +- .../{build-release.md => release.md} | 20 +++ docs/development/testing-quality.md | 93 ---------- docs/user/README.md | 35 ++++ docs/user/checkers/README.md | 6 + docs/user/configuration.md | 12 +- docs/user/expectations.md | 55 ++++++ docs/user/status-model.md | 48 ------ docs/user/troubleshooting.md | 6 +- openspec/config.yaml | 23 ++- 18 files changed, 428 insertions(+), 542 deletions(-) delete mode 100644 CONTRIBUTING.md delete mode 100644 DEVELOPMENT.md rename docs/development/{checker-development.md => checker.md} (68%) rename docs/development/{build-release.md => release.md} (77%) delete mode 100644 docs/development/testing-quality.md create mode 100644 docs/user/README.md delete mode 100644 docs/user/status-model.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 25c1319..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,131 +0,0 @@ -# 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 已通过或记录未执行原因 -``` diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index 4ae68fa..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,115 +0,0 @@ -# DiAL 开发入口 - -本文档是 DiAL 项目的开发入口，保留常用命令、全局规则和专题导航。详细架构、前端、后端、构建、测试和 checker 开发说明位于 [`docs/development/`](docs/development/README.md)。用户使用说明见 [README.md](README.md) 和 [docs/README.md](docs/README.md)。 - -## 常用命令 - -| 命令 | 说明 | -| -------------------------------- | ---------------------------------------- | -| `bun install` | 安装依赖 | -| `bun run dev probes.yaml` | 启动双进程开发环境 | -| `bun run dev:server probes.yaml` | 仅启动后端 API server | -| `bun run dev:web` | 仅启动 Vite dev server | -| `bun run schema` | 生成 `probe-config.schema.json` | -| `bun run schema:check` | 检查导出 schema 是否同步 | -| `bun run typecheck` | TypeScript 类型检查 | -| `bun run lint` | ESLint 和 Prettier 格式检查 | -| `bun test` | 运行全部测试 | -| `bun run check` | `schema:check + typecheck + lint + test` | -| `bun run build` | 构建生产可执行文件 | -| `bun run verify` | `check + build` 完整验证 | -| `bun run release` | 跨平台发布打包 | -| `bun run clean` | 清理构建缓存与产物 | - -## 质量门禁 - -代码变更必须按影响范围执行验证。常规变更优先运行： - -```bash -bun run check -``` - -正式提交或影响构建、部署、发布、前后端集成的变更运行： - -```bash -bun run verify -``` - -新增或修改配置 schema 时必须运行： - -```bash -bun run schema -bun run schema:check -``` - -## 全局工程规则 - -- 使用中文编写注释、文档和项目内交流内容。 -- 仅使用 `bun` 作为包管理器，禁止使用 npm、pnpm、yarn。 -- 运行工具使用 `bunx`，禁止使用 npx、pnpx。 -- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。 -- 后端优先使用 Bun 内置 API，其次是 es-toolkit、主流三方库、项目公共工具，最后才自行实现。 -- 前端样式优先使用 TDesign 组件、组件 props、TDesign CSS tokens、`styles.css` CSS 类，最后才自行开发组件。 -- 前端禁止组件内联 `style`、覆盖 TDesign 内部类名、使用 `!important`、硬编码色值。 -- 当前项目未上线，不需要为旧行为做向前兼容，除非用户明确要求。 - -## 包管理、依赖与提交 - -- 仅使用 `bun` 安装依赖和运行项目脚本，锁文件为 `bun.lock`。 -- 运行外部工具使用 `bunx`。 -- 新增依赖前先确认 Bun 内置 API、es-toolkit、现有三方库和项目公共工具是否已满足需求。 -- Git 提交信息使用中文，格式为 `类型: 简短描述`。 -- 提交类型限定为 `feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。 -- 多行提交描述时，标题和正文之间空一行。 - -## 目录边界 - -| 目录 | 约定 | -| ------------------- | ---------------------------------------------------------- | -| `src/server/` | Bun 后端代码，不能 import `src/web/`，HTML import 集成除外 | -| `src/web/` | React Dashboard，不能 import `src/server/` 运行时实现 | -| `src/shared/` | 前后端共享 TypeScript 类型 | -| `scripts/` | 独立运行脚本，可 import 项目源码 | -| `tests/` | 测试目录，结构镜像 `src/` | -| `docs/user/` | 用户使用、配置、部署、checker 和排障文档 | -| `docs/development/` | 架构、开发规范、构建发布和测试质量 | -| `openspec/` | OpenSpec 变更管理与规格文档 | - -## 文档影响分析 - -每次代码变更都必须执行文档影响分析。 - -| 如果变更影响 | 更新 | -| --------------------------------------------------- | ------------------------------------------ | -| 用户可见行为、配置、checker、expect、部署、状态模型 | `docs/user/` 对应文档 | -| 开发流程、架构、测试、构建发布、checker 开发机制 | `docs/development/` 或 `CONTRIBUTING.md` | -| 项目定位、快速开始、核心能力列表、文档导航 | `README.md` | -| 开发入口、质量门禁、全局规则、专题导航 | `DEVELOPMENT.md` | -| 文档同步规则 | `docs/README.md` 和 `openspec/config.yaml` | - -如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](docs/README.md)。 - -## OpenSpec 协作规则 - -- 本项目 OpenSpec 使用 `fast-drive` schema，变更文档只包含 `design.md` 和 `tasks.md`，不创建 `proposal.md` 或 `specs/*.md`。 -- `design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth。 -- `tasks.md` 必须从 `design.md` 派生，一行一个 checkbox 任务。 -- 实现阶段按 `tasks.md` 顺序执行，完成后立即标记任务状态。 - -## 专题文档 - -| 主题 | 文档 | -| ---------------- | ---------------------------------------------------------------------------------- | -| 开发文档索引 | [docs/development/README.md](docs/development/README.md) | -| 架构与边界 | [docs/development/architecture.md](docs/development/architecture.md) | -| 后端开发 | [docs/development/backend.md](docs/development/backend.md) | -| 前端开发 | [docs/development/frontend.md](docs/development/frontend.md) | -| Checker 开发机制 | [docs/development/checker-development.md](docs/development/checker-development.md) | -| 构建与发布 | [docs/development/build-release.md](docs/development/build-release.md) | -| 测试与质量 | [docs/development/testing-quality.md](docs/development/testing-quality.md) | -| 文档总览 | [docs/README.md](docs/README.md) | -| 贡献指南 | [CONTRIBUTING.md](CONTRIBUTING.md) | - -## 已知限制 - -当前不做告警通知、拨测目标动态增删、认证鉴权和分布式部署。 diff --git a/README.md b/README.md index 854d087..37b2978 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ targets: lte: 5000 ``` -完整配置、checker 和 expect 规则参见 [配置文件](docs/user/configuration.md)、[Checker 参考](docs/user/checkers/README.md) 和 [校验规则](docs/user/expectations.md)。 +完整配置、checker、expect 和部署说明参见 [用户文档](docs/user/README.md)、[配置文件](docs/user/configuration.md)、[Checker 参考](docs/user/checkers/README.md) 和 [校验规则](docs/user/expectations.md)。 ## 生产运行 @@ -74,15 +74,16 @@ Docker、跨平台发布包和运行时注意事项参见 [部署文档](docs/us ## 文档导航 -| 入口 | 内容 | -| -------------------------------------------- | ---------------------------------------------------- | -| [文档总览](docs/README.md) | 全部文档入口和文档归属矩阵 | -| [配置文件](docs/user/configuration.md) | YAML 结构、变量、server、targets 通用字段 | -| [Checker 参考](docs/user/checkers/README.md) | 所有 checker 的配置、expect 和示例 | -| [校验规则](docs/user/expectations.md) | ValueMatcher、ContentExpectations、KeyedExpectations | -| [部署文档](docs/user/deployment.md) | 构建、Docker、发布包和容器运行边界 | -| [状态模型](docs/user/status-model.md) | UP/DOWN、failure、observation、detail | -| [故障排查](docs/user/troubleshooting.md) | 常见运行问题和排查入口 | +| 入口 | 内容 | +| -------------------------------------------- | ------------------------------------------- | +| [文档总览](docs/README.md) | 全部文档入口和文档归属矩阵 | +| [用户文档](docs/user/README.md) | 配置、部署、expect、排障和 checker 使用入口 | +| [配置文件](docs/user/configuration.md) | YAML 结构、变量、server、targets 通用字段 | +| [Checker 参考](docs/user/checkers/README.md) | 所有 checker 的配置、expect 和示例 | +| [校验规则](docs/user/expectations.md) | expect 规则、状态判定、failure、observation | +| [部署文档](docs/user/deployment.md) | 构建、Docker、发布包和容器运行边界 | +| [故障排查](docs/user/troubleshooting.md) | 常见运行问题和排查入口 | +| [开发文档](docs/development/README.md) | 开发入口、常用命令、质量门禁和专题索引 | ## 开发 @@ -91,7 +92,7 @@ bun run check # schema:check + typecheck + lint + test bun run verify # check + build ``` -开发入口参见 [DEVELOPMENT.md](DEVELOPMENT.md)。新增或修改 checker 前请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 +开发入口参见 [开发文档](docs/development/README.md)。新增或修改 checker 前请先阅读 [Checker 开发](docs/development/checker.md)。 ## License diff --git a/docs/README.md b/docs/README.md index 4e8315b..653aa7c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,40 +2,23 @@ 本文档是 DiAL 的文档路由入口。AI 工具和开发者应先阅读本文件判断本次任务需要读取和更新哪些专题文档，再按任务类型读取最小必要上下文。 -## 读者入口 - -| 读者 | 推荐入口 | -| -------------- | ------------------------------------------------------------------------------------------------------------ | -| 首次使用者 | [README 快速开始](../README.md#快速开始) | -| 配置编写者 | [配置文件](user/configuration.md)、[Checker 参考](user/checkers/README.md)、[校验规则](user/expectations.md) | -| 部署维护者 | [部署文档](user/deployment.md)、[故障排查](user/troubleshooting.md) | -| 项目开发者 | [开发文档索引](development/README.md)、[DEVELOPMENT.md](../DEVELOPMENT.md) | -| Checker 贡献者 | [CONTRIBUTING.md](../CONTRIBUTING.md)、[Checker 开发](development/checker-development.md) | -| AI 工具维护者 | 本文件的任务路由与文档归属矩阵、[OpenSpec 配置](../openspec/config.yaml) | - -## 按任务阅读路径 - -| 任务 | 必读文档 | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 新增 checker | [CONTRIBUTING.md](../CONTRIBUTING.md)、[Checker 开发](development/checker-development.md)、[Checker 参考](user/checkers/README.md)、相近 checker 用户文档 | -| 修改 checker 配置 | 对应 `docs/user/checkers/.md`、[配置文件](user/configuration.md)、[校验规则](user/expectations.md) | -| 修改 expect 机制 | [校验规则](user/expectations.md)、[后端开发](development/backend.md)、[Checker 开发](development/checker-development.md) | -| 修改前端 | [DEVELOPMENT.md](../DEVELOPMENT.md)、[前端开发](development/frontend.md)、[测试与质量](development/testing-quality.md) | -| 修改后端 API、store、engine、logger | [DEVELOPMENT.md](../DEVELOPMENT.md)、[后端开发](development/backend.md)、[测试与质量](development/testing-quality.md) | -| 修改构建、Docker、release | [构建与发布](development/build-release.md)、[部署文档](user/deployment.md) | -| 修改配置 schema | [配置文件](user/configuration.md)、相关 checker 文档、[后端开发](development/backend.md)、[测试与质量](development/testing-quality.md) | -| 修改文档规则 | 本文件、[DEVELOPMENT.md](../DEVELOPMENT.md)、[OpenSpec 配置](../openspec/config.yaml) | - -## 目录结构 +## 目录索引 ```text docs/ README.md + development/ + README.md + architecture.md + backend.md + frontend.md + release.md + checker.md user/ - deployment.md + README.md configuration.md + deployment.md expectations.md - status-model.md troubleshooting.md checkers/ README.md @@ -47,40 +30,75 @@ docs/ icmp.md dns.md llm.md - development/ - README.md - architecture.md - backend.md - frontend.md - checker-development.md - build-release.md - testing-quality.md - prompts/ - README.md ``` +`docs/prompts/` 是提示词资产目录，不属于常规开发流程和用户使用文档。代码、配置、部署或 checker 变更不需要更新该目录，除非任务明确要求维护提示词资产。 + +## 入口文档 + +| 入口 | 定位 | +| ------------------------------------------- | ------------------------------------------ | +| [项目 README](../README.md) | 项目整体介绍、快速开始、核心能力、文档引导 | +| [开发文档](development/README.md) | 开发入口、全局规则、常用命令、质量门禁 | +| [用户文档](user/README.md) | 用户使用入口、配置、部署、expect、排障 | +| [Checker 用户参考](user/checkers/README.md) | 各 checker 的配置项、expect 字段和示例 | + +## 按任务阅读路径 + +| 任务 | 必读文档 | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| 修改项目介绍或快速开始 | [项目 README](../README.md)、本文档 | +| 修改开发流程、质量门禁或工程规则 | [开发文档](development/README.md)、本文档、[OpenSpec 配置](../openspec/config.yaml) | +| 修改架构边界或启动流程 | [开发文档](development/README.md)、[架构与边界](development/architecture.md) | +| 修改后端 API、store、engine、logger | [开发文档](development/README.md)、[后端开发](development/backend.md) | +| 修改前端 | [开发文档](development/README.md)、[前端开发](development/frontend.md) | +| 新增或修改 checker | [Checker 开发](development/checker.md)、[Checker 用户参考](user/checkers/README.md)、相近 checker 文档 | +| 修改配置 schema | [配置文件](user/configuration.md)、[后端开发](development/backend.md)、相关 checker 文档 | +| 修改 expect 或状态模型 | [校验规则](user/expectations.md)、[后端开发](development/backend.md)、[Checker 开发](development/checker.md) | +| 修改构建、Docker、release | [构建与发布](development/release.md)、[部署文档](user/deployment.md) | +| 修改故障处理或运行依赖 | [故障排查](user/troubleshooting.md)、相关用户文档 | +| 修改文档规则或文档目录结构 | 本文档、[OpenSpec 配置](../openspec/config.yaml) | + ## 文档归属矩阵 -| 变更类型 | 默认更新位置 | -| ------------------------------------------------------------- | ------------------------------------------------------------ | -| 项目定位、核心能力、快速开始、文档导航变化 | `README.md` | -| 用户安装、首次运行、基础使用流程变化 | `README.md` | -| YAML 顶层结构、server、variables、targets 通用字段变化 | `docs/user/configuration.md` | -| checker 配置、expect 字段、示例变化 | `docs/user/checkers/` 对应文档 | -| ValueMatcher、ContentExpectations、KeyedExpectations 规则变化 | `docs/user/expectations.md` | -| 构建产物运行、Docker、发布包、运行时能力变化 | `docs/user/deployment.md` | -| UP/DOWN 判定、failure、observation、detail 行为变化 | `docs/user/status-model.md` | -| 常见运行问题、依赖命令、容器权限、配置校验问题变化 | `docs/user/troubleshooting.md` | -| 开发入口、常用命令、质量门禁、全局规则变化 | `DEVELOPMENT.md` | -| 架构边界、启动流程、运行时流程变化 | `docs/development/architecture.md` | -| 后端 API、store、engine、logger、expect 实现机制变化 | `docs/development/backend.md` | -| 前端技术栈、组件、样式、数据层规范变化 | `docs/development/frontend.md` | -| 新增或修改 checker 的开发机制变化 | `CONTRIBUTING.md`、`docs/development/checker-development.md` | -| 构建、发布、脚本、项目配置维护方式变化 | `docs/development/build-release.md` | -| 测试、lint、typecheck、hooks、格式化规范变化 | `docs/development/testing-quality.md` | -| 包管理、依赖、目录、提交、OpenSpec 约定变化 | `DEVELOPMENT.md` | -| 文档同步规则、文档影响分析规则变化 | `docs/README.md`、`openspec/config.yaml` | -| AI 提示词资产变化 | `docs/prompts/` | +| 变更类型 | 默认更新位置 | +| -------------------------------------------------------------- | -------------------------------------------------------------- | +| 项目定位、核心能力、快速开始、顶层文档导航 | `README.md` | +| 文档路由、文档更新规则、文档归属矩阵 | `docs/README.md`、`openspec/config.yaml` | +| 开发入口、常用命令、质量门禁、全局工程规则、OpenSpec 约定 | `docs/development/README.md` | +| 架构边界、启动流程、运行时流程、前后端边界 | `docs/development/architecture.md` | +| 后端 API、共享类型、store、engine、logger、expect 基础设施 | `docs/development/backend.md` | +| 前端技术栈、组件、样式、数据层、前端测试 | `docs/development/frontend.md` | +| checker 开发机制、schema/validate/resolve/execute/expect 约定 | `docs/development/checker.md` | +| 构建、发布、Dockerfile、脚本、前后端静态资源集成 | `docs/development/release.md` | +| YAML 顶层结构、server、variables、targets 通用字段 | `docs/user/configuration.md` | +| checker 配置、expect 字段、示例、用户可见 checker 行为 | `docs/user/checkers/.md`、`docs/user/checkers/README.md` | +| ValueMatcher、ContentExpectations、KeyedExpectations、状态模型 | `docs/user/expectations.md` | +| 构建产物运行、Docker 参数、发布包、运行时依赖 | `docs/user/deployment.md` | +| 常见运行问题、依赖命令、容器权限、配置校验问题 | `docs/user/troubleshooting.md` | + +## development 文档如何更新 + +开发文档解释“如何实现和维护”。代码变更影响开发者理解、开发流程、测试方式或架构边界时，必须更新 `docs/development/` 对应文档。 + +- 全局规则、常用命令、质量门禁、目录边界、OpenSpec 约定更新到 `docs/development/README.md`。 +- 架构图、启动链路、运行时流程、前后端边界更新到 `docs/development/architecture.md`。 +- 后端 API、配置加载、store、engine、logger、expect 基础设施和后端测试规范更新到 `docs/development/backend.md`。 +- 前端技术栈、组件边界、数据流、样式规则和前端测试规范更新到 `docs/development/frontend.md`。 +- checker 开发机制、文件结构、schema、validate、resolve、execute、expect、测试 checklist 更新到 `docs/development/checker.md`。 +- 构建、Docker、release、脚本和发布验证更新到 `docs/development/release.md`。 +- 不新增“杂项”开发文档；优先把内容放入上述最贴近的专题，确需新增专题时先更新本文档和 `openspec/config.yaml`。 + +## user 文档如何更新 + +用户文档解释“如何使用”和“用户能观察到什么”。变更影响用户配置、运行、部署、checker 行为、expect 规则、状态结果或排障方式时，必须更新 `docs/user/` 对应文档。 + +- 配置事实来源是 TypeBox schema、`probe-config.schema.json`、语义校验器和测试；`docs/user/configuration.md` 负责解释顶层结构和通用字段。 +- checker 专属字段和示例只在 `docs/user/checkers/.md` 完整展开，`docs/user/checkers/README.md` 只维护类型索引和选择建议。 +- expect 断言模型、UP/DOWN、`failure`、`observation`、快速失败顺序更新到 `docs/user/expectations.md`。 +- Docker、生产运行、发布包和运行时依赖更新到 `docs/user/deployment.md`。 +- 常见错误和排查路径更新到 `docs/user/troubleshooting.md`。 +- 用户文档避免解释内部实现细节，需要实现细节时链接到 `docs/development/`。 ## 文档影响分析 @@ -88,30 +106,13 @@ docs/ ```text 代码或配置变更 - ├─ 用户能感知吗？ - │ ├─ 配置 / checker / expect -> docs/user/ - │ ├─ 部署 / 运行 / release -> docs/user/deployment.md - │ ├─ 状态 / observation / failure -> docs/user/status-model.md - │ └─ 项目入口变化 -> README.md - ├─ 开发者需要知道吗？ - │ ├─ checker 机制 -> CONTRIBUTING.md + docs/development/checker-development.md - │ ├─ 架构边界 -> docs/development/architecture.md - │ ├─ 后端机制 -> docs/development/backend.md - │ ├─ 前端机制 -> docs/development/frontend.md - │ ├─ 构建测试质量 -> docs/development/testing-quality.md - │ └─ 开发入口规则 -> DEVELOPMENT.md - └─ 都不是 - └─ 收尾说明无需更新文档及原因 + -> 用户能感知吗？更新 docs/user/ 或 README.md + -> 开发者需要知道吗？更新 docs/development/ + -> 文档规则变化吗？更新 docs/README.md 和 openspec/config.yaml + -> 都不是？收尾说明写明无需更新文档及原因 ``` -## 维护原则 - -- 根目录入口文档保持轻量，不承载完整配置参考和实现教程。 -- 用户文档解释“如何使用”，开发文档解释“如何实现和维护”。 -- 配置事实来源是 TypeBox schema、`probe-config.schema.json`、语义校验器和测试；文档负责解释和示例。 -- 每次代码变更都必须做文档影响分析；有影响时更新对应专题文档，无影响时在收尾说明中写明原因。 -- 同一字段表只在最贴近读者的文档中完整展开，其他文档用链接引用。 -- README 不承载完整配置表和 checker 表，DEVELOPMENT 不承载完整架构百科和 checker 教程。 +同一事实只在最贴近读者的文档中完整展开，其他文档使用链接引用。根目录 README 保持轻量，不承载完整配置参考、checker 表或实现教程。 ## 收尾说明示例 diff --git a/docs/development/README.md b/docs/development/README.md index e78a586..7ef21a5 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -1,25 +1,115 @@ # 开发文档 -本目录承载 DiAL 的开发和维护专题。日常开发入口见 [`../../DEVELOPMENT.md`](../../DEVELOPMENT.md)，新增或修改 checker 前先阅读 [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)。 +本文档是 DiAL 的开发入口。AI 工具和开发者应先阅读 [`../README.md`](../README.md) 判断文档归属，再阅读本文和最小必要专题。 + +适用场景：修改源码、测试、构建脚本、开发流程、架构边界、checker 开发机制或项目工程规则。 ## 专题索引 -| 文档 | 内容 | -| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | -| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 | -| [backend.md](backend.md) | 后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型 | -| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 | -| [checker-development.md](checker-development.md) | 新增或修改 checker 的实现机制和完整 checklist | -| [build-release.md](build-release.md) | 开发服务、前后端集成、构建、Docker、release、脚本、环境变量 | -| [testing-quality.md](testing-quality.md) | lint、format、typecheck、test、hooks 和测试编写规范 | -| [../../DEVELOPMENT.md](../../DEVELOPMENT.md) | 包管理、依赖、目录、提交、OpenSpec 和项目级约定 | -| [../README.md](../README.md) | 文档影响分析、文档归属矩阵和按任务阅读路径 | +| 文档 | 内容 | +| ---------------------------------- | ------------------------------------------------------------------------------------------------- | +| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 | +| [backend.md](backend.md) | 后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型 | +| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 | +| [checker.md](checker.md) | 新增或修改 checker 的实现机制、测试要求、文档同步和 checklist | +| [release.md](release.md) | 开发服务、前后端集成、构建、Docker、release、脚本、环境变量 | +| [../README.md](../README.md) | 文档路由、文档归属矩阵、development/user 文档更新规则 | + +## 常用命令 + +| 命令 | 说明 | +| -------------------------------- | ---------------------------------------- | +| `bun install` | 安装依赖 | +| `bun run dev probes.yaml` | 启动双进程开发环境 | +| `bun run dev:server probes.yaml` | 仅启动后端 API server | +| `bun run dev:web` | 仅启动 Vite dev server | +| `bun run schema` | 生成 `probe-config.schema.json` | +| `bun run schema:check` | 检查导出 schema 是否同步 | +| `bun run typecheck` | TypeScript 类型检查 | +| `bun run lint` | ESLint 和 Prettier 格式检查 | +| `bun run format` | Prettier 自动格式化 | +| `bun test` | 运行全部测试 | +| `bun run check` | `schema:check + typecheck + lint + test` | +| `bun run build` | 构建生产可执行文件 | +| `bun run verify` | `check + build` 完整验证 | +| `bun run release` | 跨平台发布打包 | +| `bun run clean` | 清理构建缓存与产物 | + +## 质量门禁 + +代码变更必须按影响范围执行验证。 + +| 变更类型 | 必跑命令 | +| -------------------------------- | --------------------------------------------------------- | +| 常规代码变更 | `bun run check` | +| 构建、部署、发布、前后端集成变更 | `bun run verify` | +| 配置 schema 变化 | `bun run schema`、`bun run schema:check`、`bun run check` | +| checker 新增或修改 | `bun run schema`、`bun run schema:check`、`bun run check` | +| 仅文档变更 | 检查链接、索引和文档归属一致性 | + +正式提交或影响构建产物时优先运行 `bun run verify`。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。 + +## 全局工程规则 + +- 使用中文编写注释、文档和项目内交流内容。 +- 仅使用 `bun` 作为包管理器，禁止使用 npm、pnpm、yarn。 +- 运行工具使用 `bunx`，禁止使用 npx、pnpx。 +- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。 +- 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。 +- 前端样式优先使用 TDesign 组件、组件 props、TDesign CSS tokens、`styles.css` CSS 类，最后才自行开发组件。 +- 前端禁止组件内联 `style`、覆盖 TDesign 内部类名、使用 `!important`、硬编码色值。 +- 当前项目未上线，不需要为旧行为做向前兼容，除非用户明确要求。 + +## 包管理、依赖与提交 + +- 仅使用 `bun` 安装依赖和运行项目脚本，锁文件为 `bun.lock`。 +- 新增依赖前先确认 Bun 内置 API、es-toolkit、标准 Web API、现有三方库和项目公共工具是否已满足需求。 +- Git 提交信息使用中文，格式为 `类型: 简短描述`。 +- 提交类型限定为 `feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。 +- 多行提交描述时，标题和正文之间空一行。 + +## 目录边界 + +| 目录 | 约定 | +| ------------------- | ---------------------------------------------------------- | +| `src/server/` | Bun 后端代码，不能 import `src/web/`，HTML import 集成除外 | +| `src/web/` | React Dashboard，不能 import `src/server/` 运行时实现 | +| `src/shared/` | 前后端共享 TypeScript 类型 | +| `scripts/` | 独立运行脚本，可 import 项目源码 | +| `tests/` | 测试目录，结构镜像 `src/` | +| `docs/user/` | 用户使用、配置、部署、checker 和排障文档 | +| `docs/development/` | 架构、后端、前端、发布和 checker 开发文档 | +| `openspec/` | OpenSpec 变更管理与规格文档 | + +## 文档影响分析 + +每次代码变更都必须执行文档影响分析。 + +| 如果变更影响 | 更新 | +| --------------------------------------------------- | ------------------------------------------ | +| 用户可见行为、配置、checker、expect、部署、状态模型 | `docs/user/` 对应文档 | +| 开发流程、架构、测试、构建发布、checker 开发机制 | `docs/development/` 对应文档 | +| 项目定位、快速开始、核心能力列表、文档导航 | `README.md` | +| 文档同步规则或文档归属矩阵 | `docs/README.md` 和 `openspec/config.yaml` | + +如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。 + +## OpenSpec 协作规则 + +- 本项目 OpenSpec 使用 `fast-drive` schema，变更文档只包含 `design.md` 和 `tasks.md`，不创建 `proposal.md` 或 `specs/*.md`。 +- `design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth。 +- `tasks.md` 必须从 `design.md` 派生，一行一个 checkbox 任务。 +- 实现阶段按 `tasks.md` 顺序执行，完成后立即标记任务状态。 ## 事实来源 -| 主题 | 事实来源 | -| ---------------- | ---------------------------------------------------------- | -| 代码结构和实现 | `src/`、`scripts/`、`tests/` | -| 配置 schema | TypeBox fragments、`probe-config.schema.json`、schema 测试 | -| 项目全局规则 | `openspec/config.yaml`、`DEVELOPMENT.md`、本目录专题文档 | -| checker 贡献流程 | `CONTRIBUTING.md`、`checker-development.md` | +| 主题 | 事实来源 | +| -------------- | ---------------------------------------------------------- | +| 代码结构和实现 | `src/`、`scripts/`、`tests/` | +| 配置 schema | TypeBox fragments、`probe-config.schema.json`、schema 测试 | +| 项目全局规则 | `openspec/config.yaml`、本文档、本目录专题文档 | +| checker 流程 | [checker.md](checker.md) | + +## 更新触发条件 + +修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。 diff --git a/docs/development/architecture.md b/docs/development/architecture.md index 9bf4adc..d49c548 100644 --- a/docs/development/architecture.md +++ b/docs/development/architecture.md @@ -1,5 +1,9 @@ # 架构与边界 +本文档说明 DiAL 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。 + +适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。 + ## 项目结构 ```text @@ -104,3 +108,7 @@ Request | `src/server/checker/expect/` | 跨 checker 复用的断言基础设施 | | `src/web/` | React Dashboard | | `src/shared/api.ts` | 前后端共享 API 类型 | + +## 更新触发条件 + +修改项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。 diff --git a/docs/development/backend.md b/docs/development/backend.md index 6cc394e..30ad1ea 100644 --- a/docs/development/backend.md +++ b/docs/development/backend.md @@ -1,5 +1,9 @@ # 后端开发 +本文档说明 DiAL 后端的 API、配置加载、存储、拨测引擎、日志、expect 和错误模型开发约定。 + +适用场景：修改 `src/server/`、`src/shared/api.ts`、后端测试、配置契约、API 响应、store、engine、logger 或 expect 基础设施。 + ## 库使用优先级 | 优先级 | 来源 | 典型用途 | @@ -111,13 +115,28 @@ Ajv 保持严格拒绝模式：`allErrors: true`、不启用类型强制转换 | `ContentExpectations` | 返回内容或半结构化内容 | body、stdout、stderr、banner、response、output、result | | `KeyedExpectations` | 动态键值断言 | headers、DB rows 列值 | -详细 checker 开发流程见 [Checker 开发](checker-development.md)。 +详细 checker 开发流程见 [Checker 开发](checker.md)。 ## 错误模型 -| 类型 | 结构 | -| ------------ | ----------------------------------- | ------------------------------------------------------- | -| API 错误 | `{ error: "描述", status: }` | -| CheckFailure | `{ kind: "error" | "mismatch", phase, path, expected?, actual?, message }` | +- API 错误：`{ error: "描述", status: }` +- CheckFailure：`{ kind: "error" | "mismatch", phase, path, expected?, actual?, message }` expect 校验失败记录首个失败原因；网络、超时、进程崩溃统一为 `kind: "error"`。 + +## 后端测试与验证 + +| 变更类型 | 测试重点 | +| ---------------------- | ---------------------------------------- | +| API 路由 | `tests/server/app.test.ts` 集成行为 | +| 配置 schema 或语义校验 | schema 导出、合法配置、非法配置 | +| store | SQLite 写入、查询、分页、聚合和清理 | +| engine | 调度、并发、超时、结果写入和状态变化日志 | +| expect 基础设施 | matcher 语义、快速失败、错误信息 | +| checker runner | 见 [Checker 开发](checker.md#测试要求) | + +后端运行时代码统一通过注入的 Logger 输出日志，禁止直接使用 `console.*`。新增或修改后端逻辑通常需要运行 `bun run check`；影响构建产物或前后端集成时运行 `bun run verify`。 + +## 更新触发条件 + +修改后端 API、共享类型、配置契约、store、engine、logger、expect 基础设施、错误模型或后端测试规范时，必须更新本文档。 diff --git a/docs/development/checker-development.md b/docs/development/checker.md similarity index 68% rename from docs/development/checker-development.md rename to docs/development/checker.md index d3b4487..f1cb96d 100644 --- a/docs/development/checker-development.md +++ b/docs/development/checker.md @@ -1,8 +1,21 @@ # Checker 开发 -Checker 是 DiAL 的核心扩展单元。每个 checker 是 `src/server/checker/runner//` 下的自包含目录，包含该 checker 所需的类型、schema、校验、执行逻辑和断言。 +Checker 是 DiAL 的核心扩展单元。每个 checker 是 `src/server/checker/runner//` 下的自包含目录，包含类型、schema、语义校验、执行逻辑、序列化和断言。 -新增或修改 checker 前请同时阅读 [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)、[配置文件](../user/configuration.md)、[校验规则](../user/expectations.md) 和 [Checker 用户文档](../user/checkers/README.md)。 +适用场景：新增 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//`。 +- 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`。 ## 架构目标 @@ -136,26 +149,39 @@ const resolvedExpect: ResolvedXxxExpectConfig = expect - `probe-config.schema.json`，通过 `bun run schema` 生成 - `docs/user/checkers/.md` - `docs/user/checkers/README.md` -- `docs/user/expectations.md`，仅当断言模型或通用规则变化 -- `docs/development/checker-development.md`，仅当开发机制变化 -- `CONTRIBUTING.md`，仅当贡献流程或 checklist 变化 +- `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 -□ 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 -□ bun run schema -□ bun run schema:check -□ bun run check -□ bun run verify +□ 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 已通过或记录未执行原因 ``` + +## 更新触发条件 + +修改 checker 开发机制、目录结构、schema/validate/resolve/execute/expect 约定、测试要求、验证命令或文档同步 checklist 时，必须更新本文档。 diff --git a/docs/development/frontend.md b/docs/development/frontend.md index 883477b..340922b 100644 --- a/docs/development/frontend.md +++ b/docs/development/frontend.md @@ -1,5 +1,9 @@ # 前端开发 +本文档说明 DiAL Dashboard 的 React、TDesign、TanStack Query、组件、样式和前端测试约定。 + +适用场景：修改 `src/web/`、前端共享类型使用方式、Dashboard 数据流、组件结构、样式规则或前端测试。 + ## 技术栈 | 层面 | 技术 | 用途 | @@ -108,10 +112,19 @@ async function fetchJson(url: string): Promise { - 严禁使用 `!important`。 - 颜色统一使用 TDesign CSS tokens，不使用硬编码色值。 -## 前端测试 +## 前端测试与验证 - 测试目录为 `tests/web/`，结构对应 `src/web/`。 -- 重点测试 `constants/` 中的纯函数。 +- 单元测试重点覆盖 `constants/`、`utils/` 和 hooks 中的纯逻辑。 - 组件测试使用 jsdom 和 `@testing-library/react`。 - 测试用户行为而非实现细节。 - 只 mock 系统边界，例如 `fetch`。 +- 使用真实的 QueryClientProvider 包裹依赖 TanStack Query 的组件。 +- 异步错误断言使用 helper 或显式 try/catch，避免依赖 Bun `expect(...).rejects` 与 `await-thenable` 规则的类型不匹配。 +- 组件测试环境由 `tests/setup.ts` 和 `bunfig.toml` preload 提供，包含 ResizeObserver、IntersectionObserver、matchMedia、attachEvent 和 Recharts mock。 + +前端逻辑变更通常需要运行 `bun run check`。影响生产静态资源、前后端集成或构建流程时运行 `bun run verify`。 + +## 更新触发条件 + +修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。 diff --git a/docs/development/build-release.md b/docs/development/release.md similarity index 77% rename from docs/development/build-release.md rename to docs/development/release.md index 9a56435..b29127a 100644 --- a/docs/development/build-release.md +++ b/docs/development/release.md @@ -1,5 +1,9 @@ # 构建与发布 +本文档说明开发服务、前后端集成、生产构建、Docker 镜像、跨平台 release 和相关脚本维护方式。 + +适用场景：修改 `scripts/`、构建流程、Dockerfile、静态资源集成、release 打包、运行时环境变量或部署产物。 + ## 开发期运行 ```bash @@ -105,3 +109,19 @@ release 流程： - `scripts/build-common.ts` 中的 import specifier 输出必须使用 `/` 分隔符。 - 跨平台路径测试不得用当前平台 `path.sep` 伪装其他平台，应使用 `node:path.win32` 或等价注入方式模拟。 - 如本地 Docker 环境不支持 buildx 或多架构模拟，需在变更记录中说明未执行原因。 + +## 发布验证 + +| 变更类型 | 验证方式 | +| ---------------- | --------------------------------------- | +| 构建脚本 | `bun run verify` | +| release 脚本 | `bun run release` 或指定受影响 target | +| Dockerfile | 本地 `docker build`，无法执行时说明原因 | +| 静态资源集成 | `bun run build`，必要时启动产物手动验证 | +| 配置 schema 同步 | `bun run schema:check` | + +影响用户部署方式、Docker 运行参数、发布包内容或运行时依赖时，必须同步更新 [用户部署文档](../user/deployment.md)。 + +## 更新触发条件 + +修改开发服务、前后端集成、构建产物、Docker 镜像、release target、脚本参数或发布验证方式时，必须更新本文档。 diff --git a/docs/development/testing-quality.md b/docs/development/testing-quality.md deleted file mode 100644 index 4d95923..0000000 --- a/docs/development/testing-quality.md +++ /dev/null @@ -1,93 +0,0 @@ -# 测试与质量 - -## 质量命令 - -| 命令 | 说明 | -| ---------------------- | -------------------------------------------------------------- | -| `bun run lint` | ESLint 检查，含类型感知规则、导入排序、导入验证、Prettier 格式 | -| `bun run format` | Prettier 自动格式化 | -| `bun run schema:check` | 检查 `probe-config.schema.json` 是否与 TypeBox fragments 同步 | -| `bun run typecheck` | TypeScript 类型检查 | -| `bun test` | 运行所有测试 | -| `bun run check` | `schema:check + typecheck + lint + test` | -| `bun run verify` | `check + build` | - -## ESLint - -配置文件：`eslint.config.js`。 - -| 配置来源 | 用途 | -| -------------------------------------------- | ---------------------------------------- | -| `@eslint/js` recommended | JavaScript 基础规则 | -| `typescript-eslint` recommended-type-checked | TypeScript 类型感知规则 | -| `typescript-eslint` stylistic-type-checked | TypeScript 风格规则 | -| `eslint-plugin-perfectionist` | 导入语句和命名导出排序 | -| `eslint-plugin-import` | 导入路径验证、循环依赖检测、重复导入合并 | -| `eslint-plugin-prettier` | 将 Prettier 格式集成为 ESLint 规则 | - -后端运行时代码禁止直接使用 `console.*`，请通过注入的 Logger 实例输出日志。 - -## Prettier - -配置文件：`.prettierrc.json`。显式声明格式化参数，包括 `printWidth: 120`、`semi: true`、`singleQuote: false`、`trailingComma: "all"`、`endOfLine: "lf"`。 - -## TypeScript 严格标志 - -| 标志 | 值 | 说明 | -| ------------------------------------ | ----- | ------------------------------- | -| `strict` | true | 全局严格模式 | -| `noUnusedLocals` | true | 未使用局部变量视为错误 | -| `noUnusedParameters` | false | 保留关闭 | -| `noPropertyAccessFromIndexSignature` | true | 索引签名必须用括号访问 | -| `noUncheckedIndexedAccess` | true | 数组和 Map 访问必须运行时检查 | -| `noImplicitOverride` | true | 覆盖父类方法必须显式 `override` | -| `verbatimModuleSyntax` | true | 强制 `import type` 纯类型导入 | - -## Git hooks - -| Hook | 行为 | -| ------------ | ------------------------------------------ | -| `pre-commit` | lint-staged 对变更文件运行 eslint/prettier | -| `commit-msg` | commitlint 校验提交信息格式 | - -提交信息格式为 `类型: 简短描述`，类型限定为 `feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。 - -## 测试分层 - -| 层级 | 覆盖范围 | 位置 | -| -------- | ---------------------- | ----------------------------------------------------------------------------- | -| 单元测试 | 后端函数、纯函数、常量 | `tests/server/**/*.test.ts`、`tests/web/{constants,utils,hooks}/**/*.test.ts` | -| 组件测试 | React 组件渲染和交互 | `tests/web/components/**/*.test.tsx` | - -## 测试命令 - -```bash -bun test -bun test tests/server -bun test tests/web -bun run check -bun run verify -``` - -## 组件测试环境 - -组件测试使用 jsdom，配置位于 `tests/setup.ts`，通过 `bunfig.toml` preload 加载。 - -包含的 polyfill 和 mock： - -- ResizeObserver -- IntersectionObserver -- matchMedia -- attachEvent -- recharts 图表 mock - -## 编写规范 - -- 优先使用 `@testing-library/react` 的语义化查询。 -- 测试用户行为而非实现细节。 -- 只 mock 系统边界。 -- 使用真实的 QueryClientProvider 包裹组件。 -- 组件测试文件命名为 `tests/web/components/ComponentName.test.tsx`。 -- 异步错误断言使用 helper 或显式 try/catch，避免依赖 Bun `expect(...).rejects` 与 `await-thenable` 规则的类型不匹配。 -- polyfill 中的 intentional no-op 使用显式可解释写法。 -- 对 `process.exit` 等系统 API 使用 `spyOn` 受控 mock。 diff --git a/docs/user/README.md b/docs/user/README.md new file mode 100644 index 0000000..56d0168 --- /dev/null +++ b/docs/user/README.md @@ -0,0 +1,35 @@ +# 用户文档 + +本文档是 DiAL 的用户使用入口，说明如何阅读配置、部署、expect 规则、故障排查和各 checker 参考。 + +适用场景：编写 YAML 配置、部署 DiAL、理解拨测结果、排查运行问题、查询某个 checker 的字段和示例。 + +## 文档索引 + +| 文档 | 内容 | +| ---------------------------------------- | ------------------------------------------------- | +| [configuration.md](configuration.md) | YAML 顶层结构、变量、server、targets 通用字段 | +| [deployment.md](deployment.md) | 生产构建、Docker、ICMP 权限、发布包运行方式 | +| [expectations.md](expectations.md) | expect 规则、状态判定、failure、observation | +| [troubleshooting.md](troubleshooting.md) | 配置校验、变量、ICMP、CMD、Docker、证书和正则问题 | +| [checkers/README.md](checkers/README.md) | 各 checker 的配置项、expect 字段和示例 | + +## 按任务阅读 + +| 任务 | 建议阅读 | +| --------------------- | ---------------------------------------------------------------------- | +| 首次运行 | [项目快速开始](../../README.md#快速开始)、[配置文件](configuration.md) | +| 编写配置 | [配置文件](configuration.md)、[Checker 参考](checkers/README.md) | +| 编写 expect | [校验规则](expectations.md)、对应 checker 文档 | +| 容器或生产部署 | [部署](deployment.md)、[故障排查](troubleshooting.md) | +| 排查启动或运行问题 | [故障排查](troubleshooting.md)、相关 checker 文档 | +| 查询 checker 专属字段 | [Checker 参考](checkers/README.md) | + +## 用户文档更新规则 + +- 配置结构、变量、server、probes、targets 通用字段变化时，更新 [configuration.md](configuration.md)。 +- checker 配置项、expect 字段、示例或运行行为变化时，更新 `checkers/.md` 和 [checkers/README.md](checkers/README.md)。 +- expect 模型、状态判定、failure、observation 或快速失败顺序变化时，更新 [expectations.md](expectations.md)。 +- 构建产物运行方式、Docker 参数、镜像内置依赖、发布包结构变化时，更新 [deployment.md](deployment.md)。 +- 常见错误、运行依赖、权限、证书或配置校验排查方式变化时，更新 [troubleshooting.md](troubleshooting.md)。 +- 用户文档只解释“如何使用”和“用户能观察到什么”，实现细节放入 [`../development/`](../development/README.md)。 diff --git a/docs/user/checkers/README.md b/docs/user/checkers/README.md index 62bf345..4f2a997 100644 --- a/docs/user/checkers/README.md +++ b/docs/user/checkers/README.md @@ -2,6 +2,8 @@ Checker 是 DiAL 的拨测执行单元。每个 target 通过 `type` 选择一个 checker，并配置对应的专属字段和 `expect` 规则。 +适用场景：查询 checker 类型选择、专属配置、expect 字段、示例和各 checker 文档入口。 + ## 支持的类型 | 类型 | 用途 | 文档 | @@ -35,3 +37,7 @@ Checker 是 DiAL 的拨测执行单元。每个 target 通过 `type` 选择一 ## 通用断言模型 各 checker 的 `expect` 字段复用 `ValueMatcher`、`ContentExpectations` 和 `KeyedExpectations`。详情见 [校验规则](../expectations.md)。 + +## 更新触发条件 + +新增、移除或修改 checker 类型、用途、选择建议、通用字段或通用断言模型时，必须更新本文档。checker 专属字段变化还必须同步更新对应 `checkers/.md`。 diff --git a/docs/user/configuration.md b/docs/user/configuration.md index 228cabb..6f22636 100644 --- a/docs/user/configuration.md +++ b/docs/user/configuration.md @@ -91,12 +91,12 @@ targets: `variables` 是顶层动态键值表，key 必须符合 `[a-zA-Z_][a-zA-Z0-9_]*`，value 仅支持 string、number、boolean。`server`、`probes` 和 `targets` 中的字符串值可引用变量。 -| 语法 | 说明 | -| --------- | ------------------------- | ------------------------------------------ | -| `${key}` | 引用 variables 或环境变量 | -| `${key | default}` | variables 和环境变量都不存在时使用默认值 | -| `${key | }` | variables 和环境变量都不存在时使用空字符串 | -| `$${key}` | 转义输出字面量 `${key}` | +| 语法 | 说明 | +| ----------------- | ------------------------------------------ | +| `${key}` | 引用 variables 或环境变量 | +| `${key\|default}` | variables 和环境变量都不存在时使用默认值 | +| `${key\|}` | variables 和环境变量都不存在时使用空字符串 | +| `$${key}` | 转义输出字面量 `${key}` | 解析优先级为 `variables -> process.env -> 默认值`。三者均不存在时配置校验失败。字段值完整等于单个变量引用时会保留 number、boolean、string 类型；部分拼接时统一转为字符串。 diff --git a/docs/user/expectations.md b/docs/user/expectations.md index 4ae63d7..12fef5e 100644 --- a/docs/user/expectations.md +++ b/docs/user/expectations.md @@ -1,7 +1,58 @@ # 校验规则 +本文档说明 `expect` 规则、状态判定、failure、observation 和各 checker 的快速失败顺序。 + +适用场景：编写 `expect`、理解 UP/DOWN、排查 mismatch/error、查看返回结果中的 `failure` 和 `observation`。 + `expect` 描述拨测结果必须满足的条件。不同 checker 暴露不同字段，但共享三类基础断言模型：`ValueMatcher`、`ContentExpectations` 和 `KeyedExpectations`。 +## 状态判定 + +DiAL 使用单层状态模型。 + +| 状态 | 含义 | +| ------ | ---------------------------------------- | +| `UP` | 拨测结果符合 `expect` 规则 | +| `DOWN` | 拨测结果不符合 `expect` 规则，或执行失败 | + +执行失败（网络错误、超时、进程崩溃）和 expect 不匹配都统一为 `DOWN`，通过 `failure.kind` 区分原因。 + +| `failure.kind` | 含义 | +| -------------- | ---------------------------------------- | +| `error` | 网络、超时、进程、协议解析或内部执行错误 | +| `mismatch` | 拨测完成，但结果不满足 expect | + +## API 结果字段 + +API 返回的检查结果包含 `detail` 和 `observation`。 + +| 字段 | 说明 | +| ------------- | ------------------------------------------------------------ | +| `detail` | 后端按 checker 类型从结构化 observation 动态生成的人可读摘要 | +| `observation` | 保存该次检查的结构化观测数据 | +| `failure` | 保存首个错误或不匹配原因 | +| `matched` | 是否符合 expect | +| `durationMs` | 本次检查耗时 | +| `timestamp` | 本次检查时间 | + +`detail` 不写入 SQLite。存储层仅持久化 `observation` JSON、`failure` JSON、匹配状态、耗时和时间戳。 + +## observation 示例 + +不同 checker 的 observation 字段不同，常见信息包括： + +| Checker | observation 内容示例 | +| ------- | ------------------------------------------------------------------ | +| HTTP | 状态码、响应头、按需读取的 body 预览 | +| Cmd | exit code、stdout/stderr 预览 | +| TCP | 连接结果、banner 摘要 | +| UDP | 响应内容、来源地址、响应大小 | +| ICMP | 存活结果、丢包率、平均延迟、最大延迟 | +| DNS | RCODE、记录值、TTL、flags、CNAME 链 | +| LLM | HTTP 状态、模型输出、finish reason、token usage、流式首 token 时间 | + +Dashboard 基于存储的检查结果计算实时状态、可用率、耗时趋势、P95、状态条和故障段等指标。指标语义由后端应用层实现，SQLite 主要负责存储、筛选、排序、分页和基础聚合。 + ## ContentExpectations `body`、`stdout`、`stderr`、`banner`、`response`、`output`、`result` 等返回内容字段均使用数组。 @@ -102,3 +153,7 @@ expect: 旧字段 `maxDurationMs`、`maxPacketLoss`、`maxAvgLatencyMs`、`maxMaxLatencyMs` 和旧正则字段 `match` 已移除，请分别改用 `durationMs`、ICMP matcher 字段和 `regex`。 非法配置会阻止启动并输出错误信息。除动态键值表（`headers`、`env`、`variables`）外，未知字段会导致启动失败，请使用 YAML 注释表达说明。 + +## 更新触发条件 + +修改 expect 断言模型、状态判定、failure 字段、observation 字段、快速失败顺序或已移除字段说明时，必须更新本文档。 diff --git a/docs/user/status-model.md b/docs/user/status-model.md deleted file mode 100644 index b71d119..0000000 --- a/docs/user/status-model.md +++ /dev/null @@ -1,48 +0,0 @@ -# 目标状态判定 - -DiAL 使用单层状态模型。 - -| 状态 | 含义 | -| ------ | ---------------------------------------- | -| `UP` | 拨测结果符合 `expect` 规则 | -| `DOWN` | 拨测结果不符合 `expect` 规则，或执行失败 | - -执行失败（网络错误、超时、进程崩溃）和 expect 不匹配都统一为 `DOWN`，通过 `failure.kind` 区分原因。 - -| `failure.kind` | 含义 | -| -------------- | ---------------------------------------- | -| `error` | 网络、超时、进程、协议解析或内部执行错误 | -| `mismatch` | 拨测完成，但结果不满足 expect | - -## API 结果字段 - -API 返回的检查结果包含 `detail` 和 `observation`。 - -| 字段 | 说明 | -| ------------- | ------------------------------------------------------------ | -| `detail` | 后端按 checker 类型从结构化 observation 动态生成的人可读摘要 | -| `observation` | 保存该次检查的结构化观测数据 | -| `failure` | 保存首个错误或不匹配原因 | -| `matched` | 是否符合 expect | -| `durationMs` | 本次检查耗时 | -| `timestamp` | 本次检查时间 | - -`detail` 不写入 SQLite。存储层仅持久化 `observation` JSON、`failure` JSON、匹配状态、耗时和时间戳。 - -## observation 示例 - -不同 checker 的 observation 字段不同，常见信息包括： - -| Checker | observation 内容示例 | -| ------- | ------------------------------------------------------------------ | -| HTTP | 状态码、响应头、按需读取的 body 预览 | -| Cmd | exit code、stdout/stderr 预览 | -| TCP | 连接结果、banner 摘要 | -| UDP | 响应内容、来源地址、响应大小 | -| ICMP | 存活结果、丢包率、平均延迟、最大延迟 | -| DNS | RCODE、记录值、TTL、flags、CNAME 链 | -| LLM | HTTP 状态、模型输出、finish reason、token usage、流式首 token 时间 | - -## 趋势与统计 - -Dashboard 基于存储的检查结果计算实时状态、可用率、耗时趋势、P95、状态条和故障段等指标。指标语义由后端应用层实现，SQLite 主要负责存储、筛选、排序、分页和基础聚合。 diff --git a/docs/user/troubleshooting.md b/docs/user/troubleshooting.md index 7968693..0eab64f 100644 --- a/docs/user/troubleshooting.md +++ b/docs/user/troubleshooting.md @@ -20,10 +20,10 @@ DiAL 启动时会校验 YAML 配置。除动态键值表（`headers`、`env`、` 常见修复： | 问题 | 修复 | -| -------------- | ----------------------------------- | --------- | +| -------------- | ----------------------------------- | | 环境变量未设置 | 设置环境变量或在 `variables` 中声明 | -| 希望允许空值 | 使用 `${key | }` | -| 希望提供默认值 | 使用 `${key | default}` | +| 希望允许空值 | 使用 `${key\|}` | +| 希望提供默认值 | 使用 `${key\|default}` | | 希望输出字面量 | 使用 `$${key}` | ## ICMP checker 无法运行 diff --git a/openspec/config.yaml b/openspec/config.yaml index 11813c3..f20588b 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -3,20 +3,21 @@ schema: fast-drive context: | - 使用中文（注释、文档、交流），面向中文开发者 - openspec文档的关键字按openspec规范使用，不要翻译为中文 + - 本项目openspec使用fast-drive自定义schema，变更文档只包含design.md和tasks.md，无proposal.md和specs - **优先阅读docs/README.md**判断文档归属和本次任务需要读取的专题文档 - - README.md用于项目概览、快速开始和用户入口；DEVELOPMENT.md用于开发入口、全局规则和质量门禁；CONTRIBUTING.md仅在新增或修改checker、贡献流程时必读 - - 所有代码风格、命名、注解、依赖、API等开发规范以DEVELOPMENT.md和docs/development/下对应专题文档为准 - - 新增或修改checker时必须阅读CONTRIBUTING.md和docs/development/checker-development.md - - 每次代码变更都必须执行文档影响分析：判断是否影响用户可见行为、配置格式、checker行为、expect规则、API、部署方式、开发流程、架构边界、测试规范或构建发布流程 - - 若影响用户使用方式、配置格式、checker行为、expect规则、部署方式或运行行为，必须同步更新docs/user/下对应文档；README.md仅在项目定位、快速开始、核心能力列表或文档导航变化时更新 - - 若影响开发流程、架构边界、质量门禁、测试规范、构建发布流程或checker开发机制，必须同步更新DEVELOPMENT.md、CONTRIBUTING.md或docs/development/下对应文档 - - 若影响文档同步规则或文档归属矩阵，必须同步更新docs/README.md和openspec/config.yaml - - 若无需更新文档，必须在收尾说明中说明原因 + - README.md用于项目概览、快速开始和顶层文档引导；docs/user/README.md用于用户使用入口；docs/development/README.md用于开发入口、全局规则和质量门禁 + - 所有代码风格、命名、注解、依赖、API等开发规范以docs/development/README.md和docs/development/下对应专题文档为准 + - 新增或修改checker时必须阅读docs/development/checker.md、docs/user/checkers/README.md和相近checker用户文档 + - 每次代码变更都必须执行文档影响分析：判断是否影响用户可见行为、配置格式、checker行为、expect规则、API、部署方式、开发流程、架构边界、测试规范或构建发布流程 + - 若影响用户使用方式、配置格式、checker行为、expect规则、部署方式或运行行为，必须同步更新docs/user/下对应文档；README.md仅在项目定位、快速开始、核心能力列表或文档导航变化时更新 + - 若影响开发流程、架构边界、质量门禁、测试规范、构建发布流程或checker开发机制，必须同步更新docs/development/README.md或docs/development/下对应专题文档 + - 若影响文档同步规则或文档归属矩阵，必须同步更新docs/README.md和openspec/config.yaml + - 若无需更新文档，必须在收尾说明中说明原因 - 新增代码优先复用已有组件、工具、依赖库，不引入新依赖 - 新增的逻辑必须编写完善的测试，并保证测试的正确性，不允许跳过任何测试 - 这是基于bun实现的前端后一体化项目，使用bun作为唯一包管理器，严禁使用pnpm、npm，使用bunx运行工具，严禁使用npx、pnpx - src/server目录下是基于bun实现的后端代码 - - 后端库使用优先级：Bun 内置 API > es-toolkit > 主流三方库 > 项目公共工具 > 自行实现 + - 后端库使用优先级：Bun 内置 API > es-toolkit > 标准 Web API > 主流三方库 > 项目公共工具 > 自行实现 - src/web目录下是基于Bun HTML import、React、TDesign实现的前端代码 - 前端样式开发优先级：TDesign组件 > 组件props > TDesign CSS tokens(--td-*) > styles.css CSS类 > 自行开发组件 - 前端严禁：组件内联style属性、CSS覆盖TD内部类名、使用!important、硬编码色值 @@ -27,8 +28,6 @@ context: | - （当前项目未上线，不需要考虑向前兼容） rules: - explore: - - 本项目openspec使用fast-drive自定义schema，变更文档只包含design.md和tasks.md，无proposal.md和specs design: - 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线 tasks: @@ -36,5 +35,5 @@ rules: - 如果是代码存在更新必须 - 执行完整的测试、代码检查、格式检查等质量保障手段 - 执行文档影响分析，并按影响范围更新对应文档；若无需更新文档，必须在任务或收尾说明中明确写出原因 - - 新增或修改checker时必须更新docs/user/checkers/下对应用户文档，并在checker开发机制变化时更新CONTRIBUTING.md或docs/development/checker-development.md + - 新增或修改checker时必须更新docs/user/checkers/下对应用户文档，并在checker开发机制变化时更新docs/development/checker.md - 新增或修改配置字段时必须更新probe-config.schema.json、probes.example.yaml、docs/user/configuration.md或对应checker文档