lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity

docs: 重构文档体系

Browse Source 
- 合并 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 文档规则
This commit is contained in:
兰缘小妖
2026-05-25 10:47:52 +08:00
parent a6504d5a62
commit 714b635aef
18 changed files with 428 additions and 542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
docs/README.md
View File

@@ -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/<type>.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/<type>.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/<type>.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 表或实现教程。
## 收尾说明示例