Decisions: chat-verifier-agent

过程日志

Clarify 阶段

入口摘要: 在 Chat 多 Agent 链路中新增 Verifier Agent，作为 Executor 输出后的质量门禁，做事实核查。

slug: chat-verifier-agent

规模分档: standard

Context 阶段

devflow/index.md 使用状态: 已命中。前序 change executor-action-memory-relevance（archived）提供了 Chat 多 Agent 当前链路（Supervisor → Planner → Executor）。

不能违反的历史决策:

Executor 已有完整的行动记忆和归一化质量等级，Verifier 不需要重复验证检索质量
Chat Supervisor 的职责是调度，Verifier 作为子 Agent 加入后不改变 Supervisor 的定位
已有 evidence_score 做事后评分，Verifier 是事前门禁，两者不冲突

需进入 OpenSpec 的上下文点:

Verifier 不需要工具调用，只是一个质量核查 Agent
Verifier 需要访问 Executor 的输出 + 工具调用记录
Supervisor prompt 需要重写以包含 Verifier 调度规则
groundedness_score 的阈值需要在代码中定义

Grill 阶段 — Question Pool

#	维度	问题	模式	状态
Q1	术语	evidence_score（事后评分）与 Verifier（事前门禁）职责是否冲突？	evidence-driven	已解决
Q2	边界	Verifier 需要的"工具调用记录"在 SupervisorAgent 中是否自动传递？	evidence-driven	已解决
Q3	边界	LOW_CONFID < 0.5 回调 Planner 后的新输出是否再次走 Verifier？循环上限多少？	user-interview	已解决
Q4	验收	Verifier 判决结果如何可观测？是否写入 agent_step 或 tool_invocation？	user-interview	已解决
Q5	验收	当前 Supervisor 硬编码 prompt 是否支持多 Agent 路由变更？	evidence-driven	已解决
Q6	技术	Verifier 如何隔离 Executor 的中间推理过程，只看到干净的 query + tool 记录 + 最终答案？	user-interview	已解决
Q7	验收	groundedness_score 阈值（0.5）是否需要配置化？	user-interview	已解决

Evidence-driven 结论

结论	证据来源	是否已汇报用户
evidence_score（异步事后）与 Verifier（同步事前门禁）不冲突	EvaluationService.java: @Async 注解	已汇报
SupervisorAgent 自动传递完整对话状态，Verifier 无需额外传递工具记录	Spring AI Alibaba SupervisorAgent 实现	已汇报
Supervisor prompt 为字符串字面量，直接修改即可	ChatService.java:353 .systemPrompt("...")	已汇报

User-interview 记录

问题	用户原话	确认状态	OpenSpec 回写
Q3: LOW_CONFID < 0.5 回调 Planner 循环上限？	"可以，回调一次"	已确认	已回写 proposal
Q4: Verifier 判决写入哪里做可观测？	"可以"（写入 diagnosis_session.self_evaluation JSON）	已确认	已回写 proposal
Q6: Verifier 如何隔离 Executor 中间推理？	"用 MessagesModelHook 过滤 messages"	已确认	已回写 design
Q7: groundedness_score 阈值是否需要配置化？	"需要配置化"	已确认	已回写 design

Specify 阶段 — Cross-Artifact 对齐检查

上游 → 下游	检查内容	状态
proposal → design	范围、约束、关键承诺是否进入 design	已对齐
design → specs	关键决策、模块地图是否进入 specs	已对齐
specs → tasks	可观察行为是否被 tasks 覆盖为可执行切片	已对齐

接口影响分级：

buildChatVerifierAgent() 新增方法 → L1（内部方法，无外部消费者）
VerifierInputHook 类 → L1（内部 Hook，无外部消费者）
Supervisor prompt 重写 → L1（仅影响 Chat 多 Agent 内部调度）
subAgents 列表变更 → L1（Supervisor 内部配置）
verifier.low-confidence-threshold 配置 → L1（新增配置项，不改已有配置）

Audit 阶段

模块链路：

用户 → Supervisor → Planner(步骤) → Executor(答案+工具记录)
                                           │
                                    Supervisor 调用 Verifier
                                           │
                              [VerifierInputHook BEFORE_MODEL]
                              ├─ 保留：system prompt + user query
                              ├─ 保留：tool call 记录（输入+返回）
                              ├─ 保留：Executor 最终答案
                              └─ 去除：Executor 中间推理、Planner 规划过程
                                           │
                                    Verifier 判决
                                           │
                         ┌─── PASS ───→ 直接输出
                         ├─── LOW_CONFID≥0.5 → 带声明输出
                         ├─── LOW_CONFID<0.5 → 回调 Planner(一次)
                         └─── REJECT → 降级输出
                                           │
                                 写入 self_evaluation JSON

架构风险评估（5 句以内）：

Verifier 是轻量 Agent（无工具、无外部依赖），架构风险低。
MessagesModelHook 纯过滤逻辑，不引入新数据源。
LOW_CONFID 分级处理 + 回调仅一次的设计，避免无限循环风险。
REJECT 降级确保编造内容不到达用户。
审计结论不影响现有 design/tasks，无需回写。

关键取舍

决策：LOW_CONFID < 0.5 回调 Planner 一次
- 原因：给系统一次修正机会，但避免无限循环
- 影响：Supervisor prompt 需维护"已回调"状态
- 风险接受：用户已确认
决策：Verifier 判决写入 diagnosis_session.self_evaluation JSON
- 原因：不改表结构，与 evidence_score 统一可观测体系
- 影响：ChatService 后处理需追加 JSON
- 风险接受：用户已确认

Archive-Ready Update

实现调整：最终运行链路由 ChatService 显式调用 planner -> executor -> verifier，不再依赖 Supervisor prompt 保证 verifier 被调用。
可追溯性补充：tool_trace_summary 增加 trace_ref、source_invocation_ids、查询样本、检索层级、相关性等级和来源文档标签。
可追溯性补充：facts_checked[*].evidence_refs 被 prompt 要求、代码解析并持久化。
验证记录：mvn -q -DskipTests compile 通过。
验证记录：运行会话 9138f064 走通 planner、executor、verifier，并持久化 verifier_evaluation.facts_checked[*].evidence_refs 与 tool_trace_summary[*].source_invocation_ids。
当前状态：OpenSpec change 已归档到 openspec/changes/archive/2026-07-03-chat-verifier-agent/，主规格已同步到 openspec/specs/chat-verifier-agent/spec.md。

6.8 KiB Raw Permalink Blame History Unescape Escape