feat(agent): add verifier claim checks
This commit is contained in:
aruo
@@ -1,10 +1,10 @@
|
||||
# Executor Structured Output V2 实施 Issue
|
||||
# Executor Structured Output V2 可执行设计与实施 Issue
|
||||
|
||||
**状态**：分阶段实施中
|
||||
**状态**：阶段三实施中
|
||||
**严重程度**：高
|
||||
**创建日期**：2026-07-07
|
||||
**最后更新**：2026-07-08
|
||||
**文档类型**：可执行 issue / 分阶段实施说明
|
||||
**文档类型**：可执行设计 issue / 分阶段实施说明
|
||||
**范围**：Chat Executor 输出结构、Gatekeeper、Verifier、Composer 数据契约调整
|
||||
**关联问题**：
|
||||
|
||||
@@ -17,7 +17,25 @@
|
||||
|
||||
## 0. 给后续实现 Agent 的执行入口
|
||||
|
||||
这份文档不是单纯的数据结构草案，而是 `Executor Structured Output V2` 的分阶段实施 issue。后续 agent 接手时，应先理解问题背景和阶段边界，再进入具体字段定义。
|
||||
这份文档是 `Executor Structured Output V2` 的可执行设计 issue，不是单纯的数据结构草案。后续 agent 接手时，先按本节确认背景、当前阶段、执行纪律和验收边界，再进入后面的字段契约。
|
||||
|
||||
### 0.0 当前接手快照
|
||||
|
||||
截至 2026-07-08，阶段状态如下：
|
||||
|
||||
| 阶段 | 状态 | 记录 |
|
||||
|---|---|---|
|
||||
| 阶段一：Executor V2 输出契约 | 已完成、已归档、已提交 | `050cbc8 feat(agent): add executor evidence v2 contract` |
|
||||
| 阶段二：Gatekeeper 接入 VerifierInputHook | 已完成、已归档、已提交 | `c5e496e feat(agent): add executor gatekeeper hook` |
|
||||
| 阶段三：Verifier V2 可推导性校验 | 实施中 | active change：`openspec/changes/executor-verifier-claim-checks` |
|
||||
| 阶段四：Composer 输出最终答案 | 未开始 | 等阶段三归档并提交后再启动 |
|
||||
| 阶段五：回归评测与审计闭环 | 未开始 | 等 Composer 链路稳定后补齐 |
|
||||
|
||||
接手时的第一动作：
|
||||
|
||||
1. 先运行 `git status --short`，确认是否已有阶段三未提交改动。
|
||||
2. 如果 `openspec/changes/executor-verifier-claim-checks` 仍存在，继续阶段三，不要跳到 Composer。
|
||||
3. 阶段三完成后，必须先验证、归档 OpenSpec、回填 devflow、单独 commit，再进入阶段四。
|
||||
|
||||
推荐阅读顺序：
|
||||
|
||||
@@ -42,6 +60,13 @@
|
||||
- 验收失败如果是代码问题，agent 自行修复；如果是设计决策不明确，停下来问用户。
|
||||
- 本 issue 不要求一次性完成所有阶段；后续 agent 应从当前 git/OpenSpec/devflow 状态继续推进。
|
||||
|
||||
交付纪律：
|
||||
|
||||
- 每个阶段只解决该阶段的问题，不顺手做下一阶段。
|
||||
- 每个阶段至少要有主成功路径和新增失败路径测试。
|
||||
- 提交前必须确认 diff 只包含当前阶段内容。
|
||||
- 不提交、不推送，除非用户明确要求；本 issue 默认只指导阶段实现和本地提交。
|
||||
|
||||
---
|
||||
|
||||
## 0.1 背景
|
||||
@@ -187,13 +212,25 @@ Executor raw JSON
|
||||
| 阶段 | 名称 | 目标 | 状态 | 退出条件 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Executor V2 输出契约 | 移除 Executor 最终表达字段，只输出结构化诊断材料 | 已完成并归档 | `executor_evidence_v2` 可运行，最终用户不再看到 raw JSON |
|
||||
| 2 | Gatekeeper 接入 VerifierInputHook | 在 Verifier 前加入确定性拦截与审计 | 进行中 | `gatekeeper_result` 进入 Verifier payload 和 `self_evaluation` |
|
||||
| 3 | Verifier V2 可推导性校验 | 从 `facts_checked` 转向 `claim_checks`，判断 claims 是否可由证据推出 | 未开始 | Verifier 不再从自然语言答案抽取额外事实 |
|
||||
| 2 | Gatekeeper 接入 VerifierInputHook | 在 Verifier 前加入确定性拦截与审计 | 已完成并归档 | `gatekeeper_result` 进入 Verifier payload 和 `self_evaluation` |
|
||||
| 3 | Verifier V2 可推导性校验 | 从 `facts_checked` 转向 `claim_checks`，判断 claims 是否可由证据推出 | 实施中 | Verifier 不再从自然语言答案抽取额外事实 |
|
||||
| 4 | Composer 最终表达 | 由 Composer 根据 Verifier 允许材料生成最终用户答案 | 未开始 | PASS/LOW_CONFID/REJECT 都不读取 Executor `user_facing_answer` |
|
||||
| 5 | 回归评测与审计闭环 | 用测试和 eval fixtures 证明幻觉拦截链路有效 | 未开始 | 伪造 ID、张冠李戴、hypothesis 写成事实等场景都有回归覆盖 |
|
||||
|
||||
更详细的实施拆解见 `21. 实施阶段`。
|
||||
|
||||
阶段推进顺序必须串行：
|
||||
|
||||
```text
|
||||
阶段一 archive + commit
|
||||
-> 阶段二 archive + commit
|
||||
-> 阶段三 archive + commit
|
||||
-> 阶段四 archive + commit
|
||||
-> 阶段五 archive + commit
|
||||
```
|
||||
|
||||
不能在阶段三未归档提交时启动 Composer，也不能在 Composer 未稳定时把回归评测阶段提前做成大杂烩。
|
||||
|
||||
---
|
||||
|
||||
## 0.6 范围与非目标
|
||||
@@ -279,6 +316,22 @@ cmd /c openspec validate --specs
|
||||
|
||||
如阶段新增专门测试，应把测试类加入 Maven `-Dtest` 列表。
|
||||
|
||||
后续 agent 每个阶段的固定执行清单：
|
||||
|
||||
1. 确认当前阶段：读取本 issue、`git status --short`、`openspec status`。
|
||||
2. 确认 OpenSpec：没有 active change 时先创建；已有当前阶段 active change 时继续使用。
|
||||
3. 实现阶段内代码：只改该阶段要求的 prompt/service/hook/test，不夹带下一阶段。
|
||||
4. 验证：运行该阶段建议测试和 `cmd /c openspec validate ...`。
|
||||
5. 回填任务：更新 OpenSpec `tasks.md`、`decisions.md`，记录实际验证命令和结果。
|
||||
6. 归档：创建或更新 `devflow/projects/<date>-<change-id>/`，然后 `cmd /c openspec archive <change-id> -y`。
|
||||
7. 复验：归档后再次运行最小测试和 `cmd /c openspec validate --specs`。
|
||||
8. 提交：检查 `git diff --cached --stat`，确认只包含当前阶段，再单独 commit。
|
||||
|
||||
若步骤 4 或 7 失败：
|
||||
|
||||
- 代码或测试问题：自行修复并重新验证。
|
||||
- 阶段边界或协议设计问题：停止，向用户说明阻塞点，不进入下一阶段。
|
||||
|
||||
---
|
||||
|
||||
## 0.10 推荐实现切片
|
||||
@@ -297,6 +350,27 @@ cmd /c openspec validate --specs
|
||||
|
||||
---
|
||||
|
||||
## 0.11 为什么这样拆阶段
|
||||
|
||||
本 issue 的改造目标不是一次性重写 Chat 诊断链路，而是逐步切断“证据不足但自然语言先下结论”的通道。阶段拆分按风险来源分层：
|
||||
|
||||
| 阶段 | 切断的风险 | 为什么不能合并 |
|
||||
|---|---|---|
|
||||
| 阶段一 | Executor 提前输出最终诊断话术 | 先移除污染源，否则后面 Verifier/Composer 仍会被旧答案影响 |
|
||||
| 阶段二 | 伪造 ID、工具名不匹配、非法 schema 等物理级幻觉 | 这类问题不需要 LLM 判断，先用代码低成本拦截 |
|
||||
| 阶段三 | claim 与证据之间是否可推导 | 这是 Verifier 的语义职责，必须在 Gatekeeper 之后处理 |
|
||||
| 阶段四 | 最终用户答案夹带未验证事实 | 只有 Verifier 输出稳定后，Composer 才知道哪些材料可用 |
|
||||
| 阶段五 | 新链路是否真的防住历史幻觉场景 | 等链路完整后再做系统化回归，避免测试绑死临时实现 |
|
||||
|
||||
每个阶段的设计都必须满足两个条件：
|
||||
|
||||
- 可以独立验证，不依赖后续阶段已经完成。
|
||||
- 失败时可以独立回滚，不破坏已经归档提交的前置阶段。
|
||||
|
||||
因此后续实现时不要把“顺手移除临时 renderer”“顺手扩展 Gatekeeper 规则”“顺手接 Composer”混进阶段三。阶段三只解决 Verifier `claim_checks` 和有效 verdict guardrail。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计目标
|
||||
|
||||
当前 `executor_evidence_v1` 同时包含结构化诊断材料和自然语言表达字段：
|
||||
@@ -1440,13 +1514,13 @@ Composer 输出严格 JSON。
|
||||
|
||||
### 阶段二：Gatekeeper 接入 VerifierInputHook
|
||||
|
||||
状态：进行中。
|
||||
状态：已完成并归档。
|
||||
|
||||
当前 OpenSpec change：
|
||||
已完成记录：
|
||||
|
||||
```text
|
||||
openspec/changes/executor-gatekeeper-hook
|
||||
```
|
||||
- OpenSpec archive：`openspec/changes/archive/2026-07-07-executor-gatekeeper-hook`
|
||||
- devflow：`devflow/projects/2026-07-07-executor-gatekeeper-hook`
|
||||
- commit：`c5e496e feat(agent): add executor gatekeeper hook`
|
||||
|
||||
目标：在 Verifier 之前用确定性规则拦截物理级幻觉。
|
||||
|
||||
@@ -1487,7 +1561,6 @@ openspec/changes/executor-gatekeeper-hook
|
||||
|
||||
```powershell
|
||||
mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
|
||||
cmd /c openspec validate executor-gatekeeper-hook
|
||||
cmd /c openspec validate --specs
|
||||
```
|
||||
|
||||
@@ -1499,7 +1572,19 @@ cmd /c openspec validate --specs
|
||||
|
||||
### 阶段三：Verifier V2 可推导性校验
|
||||
|
||||
状态：未开始。
|
||||
状态：实施中。
|
||||
|
||||
当前 OpenSpec change：
|
||||
|
||||
```text
|
||||
openspec/changes/executor-verifier-claim-checks
|
||||
```
|
||||
|
||||
接手说明：
|
||||
|
||||
- 如果该 active change 仍存在，继续完成阶段三，不要启动阶段四。
|
||||
- 阶段三已有 OpenSpec proposal/design/spec/tasks，后续实现应先对照 `tasks.md` 逐项完成。
|
||||
- 阶段三完成后必须 archive、回填 devflow、单独 commit，推荐提交信息：`feat(agent): add verifier claim checks`。
|
||||
|
||||
目标：Verifier 不再逐字扫描自然语言，而是校验 claim 是否能由证据合理推出。
|
||||
|
||||
@@ -1532,11 +1617,22 @@ cmd /c openspec validate --specs
|
||||
- `gatekeeper_result.status=fail` + Verifier 返回 PASS 时，代码侧应降级或测试 prompt 禁止该行为。
|
||||
- `unsupported` / `overstated` 能进入低置信模板需要的 missing evidence 语义。
|
||||
|
||||
建议验证命令：
|
||||
|
||||
```powershell
|
||||
mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
|
||||
cmd /c openspec validate executor-verifier-claim-checks
|
||||
cmd /c openspec validate --specs
|
||||
```
|
||||
|
||||
阶段退出条件：
|
||||
|
||||
- Verifier prompt 已不再要求逐字扫描最终自然语言答案。
|
||||
- 审计中同时可见 `claim_checks` 和兼容 `facts_checked`。
|
||||
- 现有低置信重试链路不回归。
|
||||
- OpenSpec change 已 archive。
|
||||
- devflow 已回填 brief、evidence、decisions、acceptance。
|
||||
- 本阶段代码和文档已单独 commit。
|
||||
|
||||
### 阶段四：Composer 输出最终答案
|
||||
|
||||
|
||||
Reference in New Issue
Block a user