From 2dcf415940ad3d560d38110d02d1f131e576559f Mon Sep 17 00:00:00 2001 From: sinohqb Date: Wed, 29 Jul 2026 10:16:37 +0800 Subject: [PATCH] docs(v0.5): add spec and tracer-bullet tickets for judgement semantics & scenario versioning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 范围：期望与规则叠加生效、连通用例报告标注、场景版本化（ADR-0001/0002 约束）。 工单 01-05 按依赖序编号，01/02/03 可并行，03→04→05 线性链。 --- .../issues/01-expectation-rule-additive.md | 14 ++++ .../issues/02-connectivity-case-annotation.md | 13 ++++ .../v0.5/issues/03-scenario-version-field.md | 14 ++++ .../issues/04-run-records-scenario-version.md | 13 ++++ .../issues/05-compare-same-version-guard.md | 13 ++++ .scratch/v0.5/spec.md | 77 +++++++++++++++++++ 6 files changed, 144 insertions(+) create mode 100644 .scratch/v0.5/issues/01-expectation-rule-additive.md create mode 100644 .scratch/v0.5/issues/02-connectivity-case-annotation.md create mode 100644 .scratch/v0.5/issues/03-scenario-version-field.md create mode 100644 .scratch/v0.5/issues/04-run-records-scenario-version.md create mode 100644 .scratch/v0.5/issues/05-compare-same-version-guard.md create mode 100644 .scratch/v0.5/spec.md diff --git a/.scratch/v0.5/issues/01-expectation-rule-additive.md b/.scratch/v0.5/issues/01-expectation-rule-additive.md new file mode 100644 index 0000000..80d32f3 --- /dev/null +++ b/.scratch/v0.5/issues/01-expectation-rule-additive.md @@ -0,0 +1,14 @@ +# 01 — 期望与规则叠加生效 + +**What to build:** 用例同时配置期望（关键词/时延上限）与显式评估规则时，两者都参与判定：期望始终派生为隐式判定并追加执行，任一不满足则用例不通过。期望派生的判定结果与显式规则结果同构落库（reason 标明来源为期望），前端结果列表无需特殊处理即可看到。`rule_logic`（all/any/weighted）只组合显式规则；隐式期望判定是叠加其上的硬约束。只写期望不写规则的存量用例行为保持不变。 + +**Blocked by:** None — can start immediately. + +**Status:** ready-for-agent + +- [ ] 同时配置期望与规则的用例，期望不满足时用例不通过（即使显式规则全部通过） +- [ ] 期望派生判定以 EvalResult 形式存储，reason 可辨识来源为期望 +- [ ] rule_logic=any/weighted 时，隐式期望判定不参与组合计算，仍作为独立硬约束 +- [ ] 纯期望用例（无显式规则）的判定行为与升级前一致 +- [ ] 引擎单元测试覆盖叠加通过/失败矩阵（先例：现有引擎测试） +- [ ] 全部现有测试保持绿色 diff --git a/.scratch/v0.5/issues/02-connectivity-case-annotation.md b/.scratch/v0.5/issues/02-connectivity-case-annotation.md new file mode 100644 index 0000000..04c4adb --- /dev/null +++ b/.scratch/v0.5/issues/02-connectivity-case-annotation.md @@ -0,0 +1,13 @@ +# 02 — 连通用例报告标注 + +**What to build:** 质量负责人打开单次或对比报告时，能一眼分辨哪些用例是连通用例（无任何规则与期望、收到回复即通过）：报告中的用例条目携带连通标记，summary 新增连通用例数与"判定型通过率"（判定型通过数 ÷ 判定型总数）参考指标。总通过率口径不变——分母不剔除连通用例与执行失败（ADR-0002 硬约束）。连通与否由报告生成层从"该用例无任何判定结果且无轮次错误"推导，不新增存储字段。 + +**Blocked by:** None — can start immediately. + +**Status:** ready-for-agent + +- [ ] 单次报告中连通用例带明确标记，前端可见 +- [ ] 对比报告中连通用例同样标注 +- [ ] summary 含连通用例数与判定型通过率；全为连通用例时判定型通过率不除零 +- [ ] 总通过率数值与升级前一致（口径未变） +- [ ] 报告单元测试覆盖标注与判定型通过率计算（先例：现有报告测试） diff --git a/.scratch/v0.5/issues/03-scenario-version-field.md b/.scratch/v0.5/issues/03-scenario-version-field.md new file mode 100644 index 0000000..be4fdb0 --- /dev/null +++ b/.scratch/v0.5/issues/03-scenario-version-field.md @@ -0,0 +1,14 @@ +# 03 — 场景版本字段与升版逻辑 + +**What to build:** 评测工程师编辑场景时，系统自动维护场景版本（ADR-0001）：场景新增整型 version（存量迁移回填 1）；修改考纲字段（用例集 / 模型绑定 / LLM 配置）保存后版本 +1；仅修改名称、描述、标签等元数据不升版。版本由系统维护，创建与更新 API 不接受外部指定。场景 API 返回版本号，场景管理页可见当前版本。 + +**Blocked by:** None — can start immediately. + +**Status:** ready-for-agent + +- [ ] 新建场景 version=1；数据库迁移（batch mode）为存量场景回填 1 +- [ ] 修改用例集 / model_bindings / llm_config 任一项后 version+1 +- [ ] 仅改名称/描述/标签时 version 不变 +- [ ] API 请求体中携带 version 被忽略（不可外部指定） +- [ ] 场景列表/详情 API 返回 version，前端场景页展示 +- [ ] 集成测试覆盖升版与不升版两类编辑（先例：现有场景 API 测试） diff --git a/.scratch/v0.5/issues/04-run-records-scenario-version.md b/.scratch/v0.5/issues/04-run-records-scenario-version.md new file mode 100644 index 0000000..777be0e --- /dev/null +++ b/.scratch/v0.5/issues/04-run-records-scenario-version.md @@ -0,0 +1,13 @@ +# 04 — 运行记录场景版本 + +**What to build:** 每次评测运行（无论手动 / AI 助手 / CLI 触发）在创建时快照当时的场景版本。运行 API 返回 scenario_version；运行列表与报告头以 `v3` 式样展示版本号，让人能识别考纲变更前后的运行分界。数据库迁移为存量运行回填其场景当前版本（场景已删除的回填 1）。 + +**Blocked by:** 03 — 场景版本字段与升版逻辑。 + +**Status:** ready-for-agent + +- [ ] 新建运行记录 scenario_version = 场景当前版本，三种触发来源一致 +- [ ] 迁移回填存量运行；孤儿运行（场景已删）回填 1 +- [ ] 运行列表 API 与报告数据含 scenario_version +- [ ] 前端运行列表与报告头展示版本号 +- [ ] 集成测试覆盖创建快照与迁移回填（先例：现有运行 API 测试、迁移测试） diff --git a/.scratch/v0.5/issues/05-compare-same-version-guard.md b/.scratch/v0.5/issues/05-compare-same-version-guard.md new file mode 100644 index 0000000..4e7403a --- /dev/null +++ b/.scratch/v0.5/issues/05-compare-same-version-guard.md @@ -0,0 +1,13 @@ +# 05 — 对比报告同版本校验 + +**What to build:** 对比报告的可比性收紧为"同场景且同版本"（ADR-0001）：跨版本对比时 API 返回 400，提示中包含双方版本号；报告生成层同步拒绝。报告页的对比候选下拉只列出与已选运行同场景同版本的运行，用户无需自行核对版本。 + +**Blocked by:** 04 — 运行记录场景版本。 + +**Status:** ready-for-agent + +- [ ] 同场景不同版本的两次运行对比：API 400，detail 含双方版本号 +- [ ] 同场景同版本对比正常生成（含动态用例场景——同考纲即可比） +- [ ] 报告生成层对跨版本对比抛出明确错误 +- [ ] 前端对比候选按同场景 + 同版本过滤；跨版本被拒时提示可读 +- [ ] 集成与单元测试覆盖拒绝与放行两侧（先例：现有对比报告测试） diff --git a/.scratch/v0.5/spec.md b/.scratch/v0.5/spec.md new file mode 100644 index 0000000..2d99fe5 --- /dev/null +++ b/.scratch/v0.5/spec.md @@ -0,0 +1,77 @@ +--- +labels: [ready-for-agent] +status: open +title: v0.5 判定语义对齐与场景版本化 +--- + +# v0.5 Spec：判定语义对齐与场景版本化 + +领域依据：`CONTEXT.md` 术语表、ADR-0001（场景版本化）、ADR-0002（通过率含执行失败）。 + +## Problem Statement + +评测工程师在使用平台时遇到三类"结果与直觉不符"的问题： + +1. 给用例同时写了期望（keywords / 时延上限）和评估规则后，期望被静默忽略——只有规则生效，用户以为两者都在把关。 +2. 忘记配置判定标准的用例被计为"通过"，报告通过率虚高，且无法在报告中分辨哪些用例真正经过判定、哪些只是连通验证。 +3. 编辑场景（增删用例、改模型绑定）后，新旧两次运行仍可生成对比报告——实际考纲已变，对比结论不可信，用户无从察觉。 + +## Solution + +让判定行为与领域模型一致： + +1. **期望与规则叠加生效**——期望始终转化为隐式判定并与显式规则同时执行，任一不满足即不通过。 +2. **连通用例显式标注**——报告与运行详情中标出连通用例，并补充"判定型通过率"参考指标；总通过率口径不变（ADR-0002）。 +3. **场景版本化**——场景携带版本号，仅考纲字段变更时递增；运行记录所用版本；对比报告要求同场景同版本，否则拒绝。 + +## User Stories + +1. 作为评测工程师，我希望用例的期望和规则同时生效，以便我写下的每一条约束都真实参与判定。 +2. 作为评测工程师，我希望期望不满足时能在结果里看到独立的判定条目（含原因），以便区分是哪条约束失败。 +3. 作为评测工程师，我希望已有的"只写期望不写规则"的用例行为保持不变，以便升级后历史场景不需要改造。 +4. 作为质量负责人，我希望报告里明确标出连通用例，以便判断通过率里有多少"未经判定的通过"。 +5. 作为质量负责人，我希望看到"判定型通过率"参考指标，以便在连通用例较多时仍能评估真实回答质量。 +6. 作为质量负责人，我希望总通过率口径保持含执行失败（ADR-0002），以便延续用户视角的质量定义。 +7. 作为评测工程师，我希望场景在我修改用例集、模型绑定或 LLM 配置时自动升版，以便可比性边界由系统维护而非靠记忆。 +8. 作为评测工程师，我希望仅改名称、描述、标签时版本不变，以便修文案不会断开历史可比性。 +9. 作为评测工程师，我希望每次运行记录当时的场景版本，以便回看报告时知道它对应哪一版考纲。 +10. 作为评测工程师，我希望对比报告只允许同场景同版本的两次运行，以便对比结论始终基于同一考纲。 +11. 作为评测工程师，我希望在报告页选择对比对象时只看到可比的运行，以便不必自己排查版本是否一致。 +12. 作为评测工程师，我希望跨版本对比被拒绝时得到明确提示（含双方版本号），以便理解原因并选择正确的运行。 +13. 作为质量负责人，我希望运行列表和报告中展示场景版本号，以便快速识别考纲变更前后的运行分界。 +14. 作为 AI 助手（OpenClaw），我希望通过标准 API 触发的评测同样记录场景版本，以便机器触发的运行与手动运行可比性规则一致。 +15. 作为系统维护者，我希望存量场景和运行在迁移后获得确定的版本值，以便升级不产生"版本未知"的悬空数据。 + +## Implementation Decisions + +- **期望叠加语义**：引擎不再"无规则才派生"，改为始终从期望派生隐式规则（keywords → keyword_match，时延 → response_time），追加到显式规则之后执行。隐式规则不参与 `rule_logic` 的 any/weighted 组合——用例通过 = 显式规则按 rule_logic 判定通过 **且** 全部隐式期望判定通过。期望是硬约束，规则组合逻辑只作用于显式规则。 +- **隐式判定的可见性**：期望派生的判定结果与显式规则结果同构存储（EvalResult），reason 中标明来源为期望，前端无需特殊处理即可展示。 +- **连通用例识别**：无显式规则且期望为空的用例即连通用例（与 CONTEXT.md 定义一致），判定发生在报告生成层而非存储层——不新增字段，由"该用例无任何 EvalResult 且无 turn 错误"推导。 +- **报告标注**：单次与对比报告的 case 条目携带连通标记；summary 增加连通用例数与判定型通过率（判定型通过数 ÷ 判定型总数）；总通过率分母不变。 +- **场景版本字段**：场景模型与表新增整型 version（默认 1）。更新场景时，仓储层比较考纲字段（cases / model_bindings / llm_config）序列化值，有差异则 version+1；元数据字段变更不升版。版本由系统维护，API 不接受外部指定。 +- **运行记录版本**：运行模型与表新增 scenario_version；创建运行时从当前场景快照。迁移回填：存量场景 version=1，存量运行 scenario_version 回填为其场景当前版本（场景已删除的回填 1）。 +- **对比校验升级**：对比接口在现有"同场景"校验上追加"同版本"，不满足返回 400，detail 含双方版本号。报告生成层同步收紧（ValueError）。 +- **前端适配**：报告页对比候选按"同场景 + 同版本"过滤；运行列表、报告头、对比报告头展示版本号（如 `v3`）。 +- **数据库迁移**：一条 Alembic 迁移（batch mode，SQLite），两表各加一列，带 server_default 回填。 + +## Testing Decisions + +- 只测外部行为：API 响应、引擎产出的运行/结果对象、报告 JSON 结构；不断言内部函数调用。 +- **引擎单元层**（MockChannel，先例 `test_engine.py`）：期望+规则叠加通过/失败矩阵、纯期望用例行为不变、rule_logic=any/weighted 时隐式规则不入组合、连通用例收到回复即通过。 +- **报告单元层**（先例 `test_report.py`）：连通标记、判定型通过率计算、跨版本对比抛 ValueError。 +- **API 集成层**（TestClient，先例 `test_scenarios.py` / `test_runs_api.py` / `test_reports_api.py`）：考纲变更升版 vs 元数据变更不升版、运行携带 scenario_version、跨版本对比 400 及提示内容、报告 summary 新字段。 +- 迁移回填以集成测试覆盖（先例 `test_model_config_migration.py`）。 + +## Out of Scope + +- platform"决定评测策略"的分支逻辑（意图已记录于 CONTEXT.md，行为未定义）。 +- "未判定（unchecked）"结果状态——连通用例仍计通过，仅标注。 +- 场景版本历史浏览、回滚、按版本查看旧考纲内容（只存当前版本号，不存版本快照）。 +- 多环境 / Deployment 概念（拷问已裁定为伪需求）。 +- 前端测试基线、报告趋势看板等其他 v0.5 候选项。 + +## Further Notes + +- 通过率口径受 ADR-0002 保护：任何实现不得把执行失败或连通用例从总通过率分母中剔除。 +- 场景版本语义受 ADR-0001 约束：升版判据以该 ADR 为准，如实现中发现新的考纲字段（未来扩展），需同步更新 ADR。 +- 期望叠加会使部分历史场景的通过率下降（原本被忽略的期望开始生效）——这是修正而非回归，发布说明中需说明。