docs(mvp): organize mvp documentation

2026-07-09 13:40:08 +08:00
parent 9c9a0024d4
commit 841437fa06
57 changed files with 452 additions and 675 deletions
@@ -0,0 +1,137 @@
+# 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`