lanyuanxiaoyao
714b635aef
- 合并 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 文档规则
128 lines
8.7 KiB
Markdown
128 lines
8.7 KiB
Markdown
# DiAL 文档
|
||
|
||
本文档是 DiAL 的文档路由入口。AI 工具和开发者应先阅读本文件判断本次任务需要读取和更新哪些专题文档，再按任务类型读取最小必要上下文。
|
||
|
||
## 目录索引
|
||
|
||
```text
|
||
docs/
|
||
README.md
|
||
development/
|
||
README.md
|
||
architecture.md
|
||
backend.md
|
||
frontend.md
|
||
release.md
|
||
checker.md
|
||
user/
|
||
README.md
|
||
configuration.md
|
||
deployment.md
|
||
expectations.md
|
||
troubleshooting.md
|
||
checkers/
|
||
README.md
|
||
http.md
|
||
cmd.md
|
||
db.md
|
||
tcp.md
|
||
udp.md
|
||
icmp.md
|
||
dns.md
|
||
llm.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` |
|
||
| 文档路由、文档更新规则、文档归属矩阵 | `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/`。
|
||
|
||
## 文档影响分析
|
||
|
||
每次代码变更都必须执行文档影响分析。
|
||
|
||
```text
|
||
代码或配置变更
|
||
-> 用户能感知吗？更新 docs/user/ 或 README.md
|
||
-> 开发者需要知道吗？更新 docs/development/
|
||
-> 文档规则变化吗？更新 docs/README.md 和 openspec/config.yaml
|
||
-> 都不是？收尾说明写明无需更新文档及原因
|
||
```
|
||
|
||
同一事实只在最贴近读者的文档中完整展开，其他文档使用链接引用。根目录 README 保持轻量，不承载完整配置参考、checker 表或实现教程。
|
||
|
||
## 收尾说明示例
|
||
|
||
```text
|
||
文档影响分析：本次修改了 HTTP checker 的配置字段，已更新 docs/user/checkers/http.md、docs/user/configuration.md 和 probe-config.schema.json。
|
||
```
|
||
|
||
无需更新文档时：
|
||
|
||
```text
|
||
文档影响分析：本次仅调整内部测试 helper，未改变用户可见行为、配置、架构边界或开发流程，因此无需更新文档。
|
||
```
|