feat: ValueMatcher 支持 primitive 原始值简写，等价于 { equals: value }

2026-05-19 17:07:47 +08:00
parent 8d8549d07f
commit 12cd05b04e
37 changed files with 1836 additions and 1022 deletions
--- a/openspec/specs/expect-rule-system/spec.md
+++ b/openspec/specs/expect-rule-system/spec.md
@@ -7,6 +7,8 @@
 ### Requirement: ValueMatcher 统一匹配器
 系统 SHALL 提供共享 `ValueMatcher` 作为所有非状态类 expect 的基础匹配结构。`ValueMatcher` SHALL 支持 `equals`、`contains`、`regex`、`exists`、`empty`、`gt`、`gte`、`lt` 和 `lte` 字段。`equals` MUST 支持任意 JSON value，并使用深度相等比较。`contains` 和 `regex` SHALL 将实际值转换为字符串后匹配。`gt`、`gte`、`lt` 和 `lte` SHALL 将实际值转换为有限数字后比较，无法转换为有限数字时 SHALL 判定不匹配。一个 `ValueMatcher` 对象包含多个 matcher 字段时，系统 SHALL 要求全部 matcher 均通过。

+所有类型为 `ValueMatcher` 的 expect 字段 SHALL 同时接受 primitive 原始值（string / number / boolean / null）作为简写形式。原始值简写 SHALL 等价于 `{ equals: value }`。系统 SHALL 在语义校验入口将 primitive 原始值归一化为 `{ equals: value }` 对象形式，后续 resolve 和运行期逻辑 SHALL 仅处理 ValueMatcher 对象形式。数组和对象 MUST NOT 作为原始值简写；需要对数组或对象执行 equals 匹配时，配置 MUST 显式写成 `{ equals: value }`。
+
 #### Scenario: equals 匹配对象
 - **WHEN** 实际值为 `{status: "ok", count: 1}` 且 matcher 为 `{equals: {status: "ok", count: 1}}`
 - **THEN** 系统 SHALL 使用深度相等判定该 matcher 通过
@@ -23,8 +25,28 @@
 - **WHEN** 实际值为 `"healthy"` 且 matcher 为 `{contains: "health", regex: "^ready$"}`
 - **THEN** 系统 SHALL 在任一 matcher 不满足时判定该 matcher 对象不通过

+#### Scenario: 字符串原始值简写等价 equals
+- **WHEN** expect 字段配置为 `finishReason: "stop"` 且实际值为 `"stop"`
+- **THEN** 系统 SHALL 将 `"stop"` 归一化为 `{equals: "stop"}` 并判定通过
+
+#### Scenario: 数字原始值简写等价 equals
+- **WHEN** expect 字段配置为 `rowCount: 1` 且实际值为 `1`
+- **THEN** 系统 SHALL 将 `1` 归一化为 `{equals: 1}` 并判定通过
+
+#### Scenario: 布尔原始值简写等价 equals
+- **WHEN** expect 字段配置为 ValueMatcher 类型且值为 `true`，实际值为 `true`
+- **THEN** 系统 SHALL 将 `true` 归一化为 `{equals: true}` 并判定通过
+
+#### Scenario: null 原始值简写等价 equals
+- **WHEN** expect 字段配置为 ValueMatcher 类型且值为 `null`，实际值为 `null`
+- **THEN** 系统 SHALL 将 `null` 归一化为 `{equals: null}` 并判定通过
+
+#### Scenario: 原始值简写不匹配
+- **WHEN** expect 字段配置为 `finishReason: "stop"` 且实际值为 `"error"`
+- **THEN** 系统 SHALL 判定不通过并生成 mismatch failure
+
 ### Requirement: ValueMatcher 启动期校验
-系统 SHALL 在启动期对所有 `ValueMatcher` 对象执行严格的类型和语义校验。`contains` MUST 为 string。`equals` MAY 为任意 JSON value。`exists` 和 `empty` MUST 为 boolean。`gt`、`gte`、`lt` 和 `lte` MUST 为有限数字（`Number.isFinite`）。`regex` MUST 为可编译的 string pattern，并通过 ReDoS 风险校验。ValueMatcher 对象 MUST 至少包含一个合法 matcher 字段，空对象 `{}` SHALL 导致启动期配置错误。ValueMatcher 对象 MUST NOT 包含未知字段，任何不属于 `equals`、`contains`、`regex`、`exists`、`empty`、`gt`、`gte`、`lt`、`lte` 的字段 SHALL 导致启动期配置错误。
+系统 SHALL 在启动期对所有 `ValueMatcher` 字段执行严格的类型和语义校验。校验 SHALL 同时接受 primitive 原始值和 ValueMatcher 对象两种形式。当输入为 primitive 原始值时，系统 SHALL 视为合法配置（等价于 `{equals: value}`），无需进一步校验 matcher 字段。当输入为 ValueMatcher 对象时，`contains` MUST 为 string。`equals` MAY 为任意 JSON value。`exists` 和 `empty` MUST 为 boolean。`gt`、`gte`、`lt` 和 `lte` MUST 为有限数字（`Number.isFinite`）。`regex` MUST 为可编译的 string pattern，并通过 ReDoS 风险校验。ValueMatcher 对象 MUST 至少包含一个合法 matcher 字段，空对象 `{}` SHALL 导致启动期配置错误。ValueMatcher 对象 MUST NOT 包含未知字段，任何不属于 `equals`、`contains`、`regex`、`exists`、`empty`、`gt`、`gte`、`lt`、`lte` 的字段 SHALL 导致启动期配置错误。

 #### Scenario: 空 matcher 对象被拒绝
 - **WHEN** YAML 配置中任一 matcher 对象为空 `{}`
@@ -42,6 +64,26 @@
 - **WHEN** YAML 配置中任一 matcher 的 `exists` 或 `empty` 值不是布尔类型
 - **THEN** 系统 SHALL 在启动期配置校验失败，提示该字段必须为布尔值

+#### Scenario: 字符串原始值校验通过
+- **WHEN** YAML 配置中 ValueMatcher 字段值为字符串 `"stop"`
+- **THEN** 系统 SHALL 接受该配置，视为 `{equals: "stop"}`
+
+#### Scenario: 数字原始值校验通过
+- **WHEN** YAML 配置中 ValueMatcher 字段值为数字 `5000`
+- **THEN** 系统 SHALL 接受该配置，视为 `{equals: 5000}`
+
+#### Scenario: null 原始值校验通过
+- **WHEN** YAML 配置中 ValueMatcher 字段值为 `null`
+- **THEN** 系统 SHALL 接受该配置，视为 `{equals: null}`
+
+#### Scenario: 数组原始值被拒绝
+- **WHEN** YAML 配置中 ValueMatcher 字段值为数组 `[1, 2]`
+- **THEN** 系统 SHALL 在启动期配置校验失败，提示必须为 primitive 原始值或 matcher 对象；如需数组 equals 匹配应写成 `{equals: [1, 2]}`
+
+#### Scenario: 对象原始值必须显式 equals
+- **WHEN** YAML 配置中 ValueMatcher 字段值为对象 `{foo: "bar"}`，且 `foo` 不是合法 matcher 字段
+- **THEN** 系统 SHALL 在启动期配置校验失败，提示 `foo` 是未知 matcher；如需对象 equals 匹配应写成 `{equals: {foo: "bar"}}`
+
 ### Requirement: empty matcher 语义
 `empty: true` SHALL 在以下情况判定通过：实际值为 `null`、`undefined`、空字符串 `""`、空数组 `[]` 或空对象 `{}`。`empty: false` SHALL 在以上条件均不满足时判定通过。数字 `0` 和布尔 `false` SHALL NOT 被视为 empty。

--- a/openspec/specs/probe-config/spec.md
+++ b/openspec/specs/probe-config/spec.md
@@ -101,6 +101,8 @@

 除 `headers`、`env`、`variables` 等明确声明为动态键值表的对象外，配置中的未知字段 SHALL 导致启动期配置错误。系统 MUST NOT 静默忽略未知字段。

+所有 ValueMatcher 类型的 expect 字段 SHALL 在 JSON Schema 契约中声明为 `anyOf: [primitiveValue, matcherObject]` 联合类型，同时接受 primitive 原始值（string / number / boolean / null）和 ValueMatcher 对象。语义 validator SHALL 在校验 ValueMatcher 字段之前执行归一化，将 primitive 原始值转换为 `{equals: value}` 对象形式。数组和对象 MUST NOT 作为 ValueMatcher 原始值简写；需要对数组或对象执行 equals 匹配时，配置 MUST 显式写成 `{equals: value}`。
+
 #### Scenario: target 缺少必填字段
 - **WHEN** YAML 中某个 target 缺少 id 或 type 字段
 - **THEN** 系统 SHALL 以错误退出，提示哪个 target 缺少哪个字段
@@ -194,9 +196,29 @@
 - **THEN** 系统 SHALL 以错误退出，提示该 target 的 status 数字不合法

 #### Scenario: durationMs matcher 非法
- **WHEN** YAML 中某个 target 的 `expect.durationMs` 不是合法 `ValueMatcher`
+- **WHEN** YAML 中某个 target 的 `expect.durationMs` 不是合法 `ValueMatcher` 也不是 primitive 原始值
 - **THEN** 系统 SHALL 以错误退出，提示该 target 的 expect.durationMs 格式错误

+#### Scenario: durationMs 原始值简写合法
+- **WHEN** YAML 中某个 target 配置 `expect.durationMs: 5000`
+- **THEN** 系统 SHALL 接受该配置，归一化为 `{equals: 5000}` 后校验通过
+
+#### Scenario: ValueMatcher 字段字符串简写合法
+- **WHEN** YAML 中某个 target 配置 `expect.finishReason: "stop"`
+- **THEN** 系统 SHALL 接受该配置，归一化为 `{equals: "stop"}` 后校验通过
+
+#### Scenario: ValueMatcher 字段 null 简写合法
+- **WHEN** YAML 中某个 target 配置 ValueMatcher 字段值为 `null`
+- **THEN** 系统 SHALL 接受该配置，归一化为 `{equals: null}` 后校验通过
+
+#### Scenario: ValueMatcher 字段数组简写非法
+- **WHEN** YAML 中某个 target 配置 ValueMatcher 字段值为数组 `[1, 2]`
+- **THEN** 系统 SHALL 以错误退出，提示该字段必须为 primitive 原始值或 matcher 对象；如需数组 equals 匹配应写成 `{equals: [1, 2]}`
+
+#### Scenario: ValueMatcher 字段对象简写非法
+- **WHEN** YAML 中某个 target 配置 ValueMatcher 字段值为对象 `{foo: "bar"}`，且 `foo` 不是合法 matcher 字段
+- **THEN** 系统 SHALL 以错误退出，提示 `foo` 是未知 matcher；如需对象 equals 匹配应写成 `{equals: {foo: "bar"}}`
+
 #### Scenario: ping target 缺少 host
 - **WHEN** YAML 中某个 target 配置 `type: ping` 但缺少 `ping.host`
 - **THEN** 系统 SHALL 以错误退出，提示该 target 缺少 ping.host 字段
@@ -271,7 +293,23 @@

 #### Scenario: 导出配置 JSON Schema
 - **WHEN** 仓库生成或检查配置契约
- **THEN** 根目录 SHALL 存在 draft-07 `probe-config.schema.json`，且其内容 SHALL 与当前公共 fragments 和已注册 checker fragments 组装出的完整 schema 一致（包含 variables 段和 target 的 id/name 字段）
+- **THEN** 根目录 SHALL 存在 draft-07 `probe-config.schema.json`，且其内容 SHALL 与当前公共 fragments 和已注册 checker fragments 组装出的完整 schema 一致（包含 variables 段和 target 的 id/name 字段）。所有 ValueMatcher 字段的 schema SHALL 声明为 `anyOf: [primitiveValue, matcherObject]` 联合类型
+
+#### Scenario: JSON Schema ValueMatcher 接受原始值
+- **WHEN** 使用 JSON Schema 校验配置文件中 ValueMatcher 字段值为数字 `5000`
+- **THEN** JSON Schema 校验 SHALL 通过，因为 ValueMatcher schema 声明为 `anyOf: [primitiveValue, matcherObject]`
+
+#### Scenario: JSON Schema ValueMatcher 接受 matcher 对象
+- **WHEN** 使用 JSON Schema 校验配置文件中 ValueMatcher 字段值为 `{lte: 5000}`
+- **THEN** JSON Schema 校验 SHALL 通过
+
+#### Scenario: JSON Schema ValueMatcher 拒绝数组原始值
+- **WHEN** 使用 JSON Schema 校验配置文件中 ValueMatcher 字段值为数组 `[1, 2]`
+- **THEN** JSON Schema 校验 SHALL 失败，因为数组不属于 primitive 原始值或 matcher 对象
+
+#### Scenario: JSON Schema ValueMatcher 接受 equals 数组对象
+- **WHEN** 使用 JSON Schema 校验配置文件中 ValueMatcher 字段值为 `{equals: [1, 2]}` 或 `{equals: {status: "ok"}}`
+- **THEN** JSON Schema 校验 SHALL 通过，因为 `equals` 支持任意 JSON value
 系统 SHALL 支持使用单位字符串配置读取上限，单位包括 `B`、`KB`、`MB` 和 `GB`。

 #### Scenario: 解析 MB