124 lines
6.8 KiB
Markdown
124 lines
6.8 KiB
Markdown
# 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）。
|
||
|
||
**不能违反的历史决策**:
|
||
1. Executor 已有完整的行动记忆和归一化质量等级，Verifier 不需要重复验证检索质量
|
||
2. Chat Supervisor 的职责是调度，Verifier 作为子 Agent 加入后不改变 Supervisor 的定位
|
||
3. 已有 evidence_score 做事后评分，Verifier 是事前门禁，两者不冲突
|
||
|
||
**需进入 OpenSpec 的上下文点**:
|
||
1. Verifier 不需要工具调用，只是一个质量核查 Agent
|
||
2. Verifier 需要访问 Executor 的输出 + 工具调用记录
|
||
3. Supervisor prompt 需要重写以包含 Verifier 调度规则
|
||
4. 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 句以内）：
|
||
1. Verifier 是轻量 Agent（无工具、无外部依赖），架构风险低。
|
||
2. MessagesModelHook 纯过滤逻辑，不引入新数据源。
|
||
3. LOW_CONFID 分级处理 + 回调仅一次的设计，避免无限循环风险。
|
||
4. REJECT 降级确保编造内容不到达用户。
|
||
5. 审计结论不影响现有 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`。
|