# DiAL 文档

本文档是 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
  user/
    deployment.md
    configuration.md
    expectations.md
    status-model.md
    troubleshooting.md
    checkers/
      README.md
      http.md
      cmd.md
      db.md
      tcp.md
      udp.md
      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
```

## 文档归属矩阵

| 变更类型                                                      | 默认更新位置                                                 |
| ------------------------------------------------------------- | ------------------------------------------------------------ |
| 项目定位、核心能力、快速开始、文档导航变化                    | `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/`                                              |

## 文档影响分析

每次代码变更都必须执行文档影响分析。

```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
  └─ 都不是
      └─ 收尾说明无需更新文档及原因
```

## 维护原则

- 根目录入口文档保持轻量，不承载完整配置参考和实现教程。
- 用户文档解释“如何使用”，开发文档解释“如何实现和维护”。
- 配置事实来源是 TypeBox schema、`probe-config.schema.json`、语义校验器和测试；文档负责解释和示例。
- 每次代码变更都必须做文档影响分析；有影响时更新对应专题文档，无影响时在收尾说明中写明原因。
- 同一字段表只在最贴近读者的文档中完整展开，其他文档用链接引用。
- README 不承载完整配置表和 checker 表，DEVELOPMENT 不承载完整架构百科和 checker 教程。

## 收尾说明示例

```text
文档影响分析：本次修改了 HTTP checker 的配置字段，已更新 docs/user/checkers/http.md、docs/user/configuration.md 和 probe-config.schema.json。
```

无需更新文档时：

```text
文档影响分析：本次仅调整内部测试 helper，未改变用户可见行为、配置、架构边界或开发流程，因此无需更新文档。
```