Files

T

zhuyongxin 841437fa06 docs(mvp): organize mvp documentation

2026-07-09 13:40:08 +08:00

5.0 KiB

Raw Permalink Blame History

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 工程师，当前实现仍有一个明显短板：

证据链已经“有了”，但还没有被收敛成清晰、稳定、可测试的工程契约。

这会直接影响三个面试问题的回答质量：

工具失败时系统会怎样降级？
Verifier 看到的 evidence 到底是否一致、可审计？
这些失败路径和降级行为有没有稳定测试，而不是只靠 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 只做三件事：

收敛 evidence tool 的落库契约，让 lookup_knowledge、query_logs、query_metrics 的公共语义一致。
明确失败 / 无证据 / 去重 / verifier 非法输出等降级契约，让 ToolTraceSummaryService 和 ChatService 面向统一状态工作。
增加专项离线测试，覆盖证据摘要与关键降级路径。

范围

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 离线化

预期结果

完成后，项目在面试里应能更清楚地表述为：

我不仅把 Agent 的工具调用落到了库里，
还把 evidence trace、失败语义和 verifier 降级路径收敛成了稳定契约，
并用离线测试覆盖了这些关键失败场景。

5.0 KiB Raw Permalink Blame History Unescape Escape