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

35
docs/user/README.md Normal file
View File

@@ -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/<type>.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)。

6
docs/user/checkers/README.md
View File

@@ -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/<type>.md`。

12
docs/user/configuration.md
View File

@@ -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 类型；部分拼接时统一转为字符串。

55
docs/user/expectations.md
View File

@@ -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 字段、快速失败顺序或已移除字段说明时，必须更新本文档。

48
docs/user/status-model.md
View File

@@ -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 主要负责存储、筛选、排序、分页和基础聚合。

6
docs/user/troubleshooting.md
View File

@@ -20,10 +20,10 @@ DiAL 启动时会校验 YAML 配置。除动态键值表（`headers`、`env`、`
常见修复：
| 问题 | 修复 |
| -------------- | ----------------------------------- | --------- |
| -------------- | ----------------------------------- |
| 环境变量未设置 | 设置环境变量或在 `variables` 中声明 |
| 希望允许空值 | 使用 `${key | }` |
| 希望提供默认值 | 使用 `${key | default}` |
| 希望允许空值 | 使用 `${key\|}` |
| 希望提供默认值 | 使用 `${key\|default}` |
| 希望输出字面量 | 使用 `$${key}` |
## ICMP checker 无法运行