docs: 重构文档体系

2026-05-24 20:18:18 +08:00
parent 483cdc596b
commit a6504d5a62
28 changed files with 2030 additions and 2155 deletions
--- a/docs/user/expectations.md
+++ b/docs/user/expectations.md
@@ -0,0 +1,104 @@
+# 校验规则
+
+`expect` 描述拨测结果必须满足的条件。不同 checker 暴露不同字段，但共享三类基础断言模型：`ValueMatcher`、`ContentExpectations` 和 `KeyedExpectations`。
+
+## ContentExpectations
+
+`body`、`stdout`、`stderr`、`banner`、`response`、`output`、`result` 等返回内容字段均使用数组。
+
+| 规则       | 说明                                                   |
+| ---------- | ------------------------------------------------------ |
+| `contains` | 内容包含指定文本                                       |
+| `regex`    | 正则匹配，启动期会拒绝存在 ReDoS 风险的模式            |
+| `json`     | JSONPath 提取值比较，`path` 必填                       |
+| `css`      | CSS 选择器提取 HTML 元素，`selector` 必填，`attr` 可选 |
+| `xpath`    | XPath 提取 XML/HTML 节点，`path` 必填                  |
+
+示例：
+
+```yaml
+expect:
+  body:
+    - contains: "ok"
+    - json:
+        path: "$.status"
+        equals: "ready"
+```
+
+ContentExpectations 数组按顺序快速失败。数组项可以是直接 matcher，也可以是 `json`、`css`、`xpath` 提取器规则。一条规则不能混用直接 matcher 和 extractor，多个 extractor 也不能共存。Extractor 未配置 matcher 时等价于 `exists: true`。
+
+## ValueMatcher
+
+`ValueMatcher` 用于单个标量值、数字指标和字符串元数据。
+
+| 字段       | 说明                            |
+| ---------- | ------------------------------- |
+| `equals`   | 精确匹配，支持 JSON 深度相等    |
+| `contains` | 字符串包含                      |
+| `regex`    | 正则匹配，固定使用无 flags 正则 |
+| `empty`    | 判断是否为空                    |
+| `exists`   | 判断是否存在                    |
+| `gte`      | 大于等于                        |
+| `lte`      | 小于等于                        |
+| `gt`       | 大于                            |
+| `lt`       | 小于                            |
+
+一个 matcher 对象内多个字段为 AND 语义。`exists: false` 不能和其他 matcher 组合。
+
+ValueMatcher expect 字段可直接写 string、number、boolean 或 null，等价于 `{ equals: value }`。数组和对象必须显式写成 `{ equals: ... }`。
+
+```yaml
+expect:
+  durationMs:
+    lte: 5000
+  finishReason: "stop"
+```
+
+## KeyedExpectations
+
+`headers`、DB `rows[]` 中的列值等动态键值对象使用 `KeyedExpectations`。每个键的值支持 `ValueMatcher` 的全部字段，字面量值自动等价于 `{ equals: value }`。
+
+```yaml
+expect:
+  headers:
+    Content-Type:
+      contains: "application/json"
+```
+
+## 大小和时长格式
+
+| 类型 | 示例                             |
+| ---- | -------------------------------- |
+| 大小 | `4KB`、`10MB`、`1GB`、直接数字   |
+| 时长 | `500ms`、`30s`、`5m`、`2h`、`7d` |
+
+`maxBodyBytes`、`maxOutputBytes`、`maxResponseBytes`、`maxBannerBytes` 等大小字段支持 `KB`、`MB`、`GB` 单位。
+
+## 快速失败顺序
+
+| Checker    | 顺序                                                                                                                                                                             |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| HTTP       | `status -> headers -> body -> durationMs`                                                                                                                                        |
+| Cmd        | `exitCode -> durationMs -> stdout -> stderr`                                                                                                                                     |
+| DB         | `durationMs -> rowCount -> rows -> result`                                                                                                                                       |
+| TCP        | `connected -> banner -> durationMs`                                                                                                                                              |
+| UDP        | `responded -> responseSize -> response -> sourceHost -> sourcePort -> durationMs`                                                                                                |
+| ICMP       | `alive -> packetLossPercent -> avgLatencyMs -> maxLatencyMs -> durationMs`                                                                                                       |
+| DNS system | `values -> valueCount -> durationMs`                                                                                                                                             |
+| DNS server | `responded -> rcode -> values -> valueCount -> answerCount -> ttlMin -> ttlMax -> authoritative -> recursionAvailable -> truncated -> authenticatedData -> result -> durationMs` |
+| LLM http   | `status -> headers -> output -> finishReason -> rawFinishReason -> usage -> durationMs`                                                                                          |
+| LLM stream | `status -> headers -> stream.completed -> stream.firstTokenMs -> output -> finishReason -> rawFinishReason -> usage -> durationMs`                                               |
+
+## JSON Schema
+
+仓库根目录导出 `probe-config.schema.json`。在 YAML 文件顶部添加以下注释可在编辑器中获得提示和校验：
+
+```yaml
+# yaml-language-server: $schema=./probe-config.schema.json
+```
+
+## 已移除字段
+
+旧字段 `maxDurationMs`、`maxPacketLoss`、`maxAvgLatencyMs`、`maxMaxLatencyMs` 和旧正则字段 `match` 已移除，请分别改用 `durationMs`、ICMP matcher 字段和 `regex`。
+
+非法配置会阻止启动并输出错误信息。除动态键值表（`headers`、`env`、`variables`）外，未知字段会导致启动失败，请使用 YAML 注释表达说明。