138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# ISS-005 证据链补齐与降级契约收敛
|
||
|
||
**状态**：进行中（sm-flow）
|
||
**严重程度**：高
|
||
**发现时间**：2026-07-04
|
||
**来源**：P1-A 面试打磨项 / 基于 ISS-003 的当前实现复核
|
||
**关联**：ISS-003（Verifier 证据链、失败路径可验证性）、`chat-verifier-agent`、`mvp-demo-trace-acceptance`
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
当前 MVP 已具备：
|
||
|
||
- `lookup_knowledge`、`query_logs`、`query_metrics` 的工具调用落库
|
||
- Verifier 基于 `tool_trace_summary` 做事实核查
|
||
- `LOW_CONFID` / `REJECT` 的用户侧降级输出
|
||
- trace API 可回放 session、agent_step、tool_invocation 和 self_evaluation
|
||
|
||
但如果目标是拿这个项目去面试 Agent 工程师，当前实现仍有一个明显短板：
|
||
|
||
**证据链已经“有了”，但还没有被收敛成清晰、稳定、可测试的工程契约。**
|
||
|
||
这会直接影响三个面试问题的回答质量：
|
||
|
||
1. 工具失败时系统会怎样降级？
|
||
2. Verifier 看到的 evidence 到底是否一致、可审计？
|
||
3. 这些失败路径和降级行为有没有稳定测试，而不是只靠 runtime 演示？
|
||
|
||
---
|
||
|
||
## 当前现状复核
|
||
|
||
### 1. 工具落库入口已经存在，但契约不统一
|
||
|
||
- `QueryLogsTools` 和 `QueryMetricsTools` 通过 `ToolInvocationRecorder.recordEvidenceTool(...)` 记录 evidence tool 调用。
|
||
- `LookupKnowledgeTool` 仍保留独立的 `saveToolInvocation(...)` 路径，自己构造 `ToolInvocation` 实体。
|
||
|
||
这意味着：
|
||
|
||
- evidence tool 的公共字段有一套约定
|
||
- knowledge retrieval 又有一套定制字段拼装
|
||
|
||
两者都能工作，但**没有形成统一的“证据调用记录契约”**。
|
||
|
||
### 2. 失败 / 无结果 / 去重命中的语义不够显式
|
||
|
||
当前实现里：
|
||
|
||
- `query_logs` 未命中时会返回 `success=false` + `"未找到匹配的日志"`
|
||
- `query_metrics` 失败时会返回 `success=false`
|
||
- `lookup_knowledge` 去重命中时会返回 `found=false`，但 `tool_invocation.success=true`
|
||
- `ToolTraceSummaryService` 通过 `success`、`relevanceLevel`、`dedupReason` 等字段做启发式摘要
|
||
|
||
这些行为在代码里是分散成立的，但**没有被定义成统一契约**，导致：
|
||
|
||
- Verifier 能看到的“失败”和“无证据”边界不够稳定
|
||
- 评测时难以明确统计哪些是“调用失败”、哪些是“无命中”、哪些是“已检索过”
|
||
|
||
### 3. ChatService 的降级路径有实现，但测试矩阵不完整
|
||
|
||
`ChatService` 已处理：
|
||
|
||
- `verifier_output` 缺失或无法解析 → fallback `LOW_CONFID`
|
||
- `REJECT` → degraded output
|
||
- `LOW_CONFID` → disclaimer output
|
||
|
||
但目前缺少成体系的专项验证，尤其是：
|
||
|
||
- Verifier 输出非法 JSON
|
||
- evidence tool 查询失败
|
||
- knowledge lookup 无有效证据
|
||
- fallback 文案是否只基于 verifier 缺口拼装
|
||
|
||
---
|
||
|
||
## 影响
|
||
|
||
- **面试表达弱化**：你能讲“我有 trace”，但还不能很硬地讲“我的失败路径是有契约和测试保护的”。
|
||
- **评测基础不稳**：后续 P1-B 做 case-based harness 时，统计口径会受 evidence 语义不一致影响。
|
||
- **Verifier 可审计性打折**：当前实现可用，但 still relies on code convention，而不是一份明确收敛后的工程协议。
|
||
|
||
---
|
||
|
||
## 本 issue 目标
|
||
|
||
P1-A 只做三件事：
|
||
|
||
1. 收敛 evidence tool 的落库契约，让 `lookup_knowledge`、`query_logs`、`query_metrics` 的公共语义一致。
|
||
2. 明确失败 / 无证据 / 去重 / verifier 非法输出等降级契约，让 `ToolTraceSummaryService` 和 `ChatService` 面向统一状态工作。
|
||
3. 增加专项离线测试，覆盖证据摘要与关键降级路径。
|
||
|
||
---
|
||
|
||
## 范围
|
||
|
||
### In scope
|
||
|
||
- `ToolInvocationRecorder` 契约增强
|
||
- `LookupKnowledgeTool` 入库路径收敛
|
||
- `QueryLogsTools` / `QueryMetricsTools` evidence 语义对齐
|
||
- `ToolTraceSummaryService` 对失败 / no-hit / mixed evidence 的摘要规则收敛
|
||
- `ChatService` 对 verifier 非法输出与降级输出的专项测试
|
||
- 与该 change 直接相关的文档、OpenSpec、devflow 记录
|
||
|
||
### Out of scope
|
||
|
||
- 不引入新的数据库表或 schema 变更
|
||
- 不扩展新的 evidence tool
|
||
- 不做 P1-B 评测集 / harness
|
||
- 不做前端 trace UI
|
||
- 不处理敏感配置和默认 `mvn test` 离线化
|
||
|
||
---
|
||
|
||
## 预期结果
|
||
|
||
完成后，项目在面试里应能更清楚地表述为：
|
||
|
||
```text
|
||
我不仅把 Agent 的工具调用落到了库里，
|
||
还把 evidence trace、失败语义和 verifier 降级路径收敛成了稳定契约，
|
||
并用离线测试覆盖了这些关键失败场景。
|
||
```
|
||
|
||
---
|
||
|
||
## 相关文件
|
||
|
||
- `src/main/java/com/superbiz/agent/service/ToolInvocationRecorder.java`
|
||
- `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`
|
||
- `src/main/java/com/superbiz/agent/agent/tool/QueryLogsTools.java`
|
||
- `src/main/java/com/superbiz/agent/agent/tool/QueryMetricsTools.java`
|
||
- `src/main/java/com/superbiz/agent/service/ToolTraceSummaryService.java`
|
||
- `src/main/java/com/superbiz/agent/service/ChatService.java`
|
||
- `src/test/java/com/superbiz/agent/service/ChatServiceSequentialAgentTest.java`
|
||
- `src/test/java/com/superbiz/agent/tool/LookupKnowledgeToolTest.java`
|