# 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`