怎样把检索候选变成可以交付的工程结论

Local RAG 返回结果之后，最危险的操作是把所有片段交给大模型，要求它「总结得更完整」。流畅会掩盖来源差异：Jira 的目标、Confluence 的旧设计和另一个 Commit 的同名 Method 被连成一段没有明显破绽的故事。

mt_rag 把检索结果称为 Evidence Candidate。Developer Output 的工作不是美化 Candidate，而是把它们变成一份可定位、可拒答、可评测的工程结论。

本篇知识地图#

flowchart TB
  H["Retrieval Hits"] --> V["Verified Path + Evidence"]
  V --> C["Canonical DeveloperAnswerV1"]
  C --> S["Business Summary"]
  C --> P["Simple Verified Chain"]
  C --> K["Code + Chinese Comments"]
  C --> F["Deterministic Confidence"]
  C --> R["Citation <= 10"]
  C --> G["Limitations / Gaps"]
  S --> O["Human-readable Answer"]
  P --> O
  K --> O
  F --> O
  R --> O
  G --> O
  O --> E["Retrieval / Grounding / Citation Eval"]

本章覆盖 Claim-to-evidence、Deterministic Confidence、Citation Contract、Human-first Rendering、Observability 和分层评测。

Canonical Answer 先于可见文章#

System Shadow 先由确定性代码生成 DeveloperAnswerV1：

status = complete | partial | insufficient
call_chain
code_with_chinese_comments
overall_confidence
citations (最多 10)
limitations
summary_facts

只有存在完整 Verified Path 时才能是 complete。没有路径但有可定位材料时是 partial；连可定位 Citation 都没有时是 insufficient。Controller 的最终动作不是 answer 或 rerank 时，会强制 force_insufficient，即使检索命中了很多相似文本，也不生成调用链。

这份结构是事实合同。Codex 可以把它组织成更自然的中文，不能改变 Chain、Confidence 或 Citation ID。

人类可读输出为什么固定前两节#

当前可见答案要求：

1. 业务 Summary：具体说明做什么、输入或触发、核心处理逻辑和结果/影响；
2. 简约调用链：一条经验证的 entry --> processing --> destination；
3. Code、Confidence、Citation、Limitations 和 Machine Data。

把 Summary 和 Chain 放在最前，是为了让工程师先读结论；把机器诊断放在后面，是为了避免一屏 Retrieval Count 代替业务说明。但 Summary 只能使用 summary_facts，不能因为写给人看就增加新的业务规则。

没有 Verified Chain 时，第二节明确写「证据不足，未生成调用链」。这句话不是失败体验，而是正确完成状态：读者知道缺的是关系证据，而不是误以为系统忘了展示。

Citation 必须覆盖 Chain，而不是装饰答案#

Citation 来源有两类：

• Article Evidence：Page/Section/Issue，带 Source Record、URL、Locator；
• Code Evidence：Repo、File、Class/Method、Line、Commit。

System Shadow 最多返回 10 条。排序优先覆盖选中 Verified Path 每条 Edge 的第一条 Evidence，再补其他 Path Evidence，最后才补相关 Retrieval Hit。这样 Citation Budget 首先用于支撑调用链，而不是展示十个相似页面。

如果一条 Edge 的 Required Evidence 没进入最终 Citation，答案降为 Partial，并把缺口写入 Limitation。只要 Path Evidence 的 Locator、Revision 或 Verification 不完整，整条 Path 不进入 call_chain。

Confidence 不是模型的自我感觉#

有 Verified Chain 时，System Shadow 的 Overall Confidence 由四部分组成：

0.40 base for a verified chain
+ 0.25 * edge evidence coverage
+ 0.20 * retrieval quality
+ 0.15 * source currentness

Retrieval Quality 看前十个 Hit 是否同时来自 Vector 与 Keyword Lane；Source Currentness 对 Confluence 使用 Freshness，对 Code 使用 Commit Currentness。没有 Chain 时 Confidence 上限为 0.49，只随可定位 Citation 少量增加。

这个公式不是概率校准后的「答案正确率」，而是一个可重复的工程信号。它的重要属性是：LLM 不能提高它；同一 Evidence 输入得到同一数值；缺 Verified Path 时有明确上限。后续若要把它解释为概率，还需要 Reliability Diagram 和真实标注集校准。

输出代码为什么只表达顺序#

当前 Code Section 生成的是：

const verifiedCallChain = [
  "entrySymbol", // 入口
  "providerMethod", // 经 CALLS 到达最终落点
] as const; // 只表达已验证顺序

它刻意不生成参数、Return Type、Error Handling 或 Runtime Value，因为 Graph Path 只证明 Node 顺序与 Relation。除非这些细节在 Code Evidence 中逐项验证，否则把它们补出来会扩大 Claim Surface。

真实开发任务仍应打开当前 Repo 验证 Signature、Tests 和 Config。RAG Output 缩短找入口时间，不取代当前 Working Tree Review。

三类观测数据不能混在一起#

当前系统区分：

观测面	记录内容	保留/用途
Generation Trace	Refresh 每一步的输入输出、Checkpoint、增删改、Error	按 Run 分区，采用月级保留策略
Query Log	Rewrite、Search、Neo4j、Controller、Rerank、Aggregate 事件	按 Query 分区，采用月级保留策略
Durable Lineage	Manifest、Traceability、Checkpoint、Event Journal	不受运行日志 Retention 清理

运行日志回答「这次发生了什么」，Durable Lineage 回答「当前投影由哪些输入生成、下次从哪里重放」。把 Query Log 当 Source of Truth，会在按月级策略清理后失去可重入状态；把 Durable Journal 当 UI 日志，又会难以排查单次延迟。

评测必须拆开 Retriever、Graph 和 Generator#

一份最终答案可以偶然正确，却建立在错误 Citation 上；也可以 Retriever 找到了正确文档，但 Generator 没有引用关键 Claim。因此至少分四层：

层	建议指标	本项目重点
Retrieval	Recall@K、MRR、Exact Top-1、Repo/Commit Match	Dense/Keyword/Exact 各自贡献
Graph	Anchor Coverage、Verified Path Coverage、False Path Rate	不允许 Candidate Edge 冒充 Chain
Grounding	Claim Faithfulness、Unsupported Claim Rate	Summary 只用 Canonical Facts
Citation	Citation Correctness、Completeness、Locator Validity	Edge Evidence 是否被覆盖

无答案 Query 也必须进入 Eval，衡量 insufficient Precision。只测「系统知道答案的问题」，会鼓励它为所有输入都生成内容。

近期某一完整 Shadow Generation 通过了本机完整性检查，Vector 与 Graph Cursor 均处于当前版本。这不是永久规模，也不是 Production Accuracy 指标；Production Cutover 尚未执行，Readiness 与线上效果必须分开报告。

这次快照还暴露出一个值得保留的评测缺口：Shadow 的检索重叠度没有达到通用 Readiness Gate 的门槛，但 Production Validator 仍可判 Ready，因为它使用了不同的 Citation Coverage 条件。两个 Gate 不一致。正确处理不是挑一个更好看的结果，而是统一定义，并在统一前把 ready=true 限定为「当前 Production Validator 的内部一致性通过」。

失败模式与取舍#

失败模式	输出行为	Trade-off
有 Hits、无 Verified Path	Partial/Insufficient，不生成 Chain	少给推测，保住调用关系正确性
Citation Locator 缺失	不纳入 Citation	可能减少参考数量，但每条都可回查
Edge Evidence 超过 10 条	优先覆盖 Path，标记未覆盖 Gap	Citation Budget 有上限，复杂分支需另开深度报告
Codex 改 Chain/Confidence	Reject，使用 Deterministic Renderer	可读性下降，Canonical Facts 不变
Summary 只有来源标题/统计	视为不具体，Fallback	需要更好的 Evidence，而不是更花哨措辞
Query Log 过期	返回明确过期状态；Durable Lineage 保留	控制磁盘，同时不破坏重放
Shadow Ready	仍不自动 Cutover	发布速度让位于独立授权与生产 Readback
两套 Readiness Gate 阈值不同	报告具体 Validator、Overlap 与 Citation Coverage	避免把内部完整性标志误读成统一质量门槛

可复核的项目证据#

• src/mt_rag/query/answer.py：DeveloperAnswerV1、Verified Chain、Citation、Confidence 和 Limitations；
• src/mt_rag/query/runtime.py：Canonical Answer、Codex Organizer 校验和 Fallback Renderer；
• src/mt_rag/core/observability.py：Generation Trace、Query Log 与 Retention；
• src/mt_rag/system_graph/query.py：Path Evidence 完整性；
• docs/02-runbooks/local-llm-service.md：External Strict Output、Streaming Progress 和 Query Log Contract；
• 本地 Readiness 产物：某次 Shadow 的 Generation、Cursor 与 Blocker 状态；
• docs/05-reports/phase-2-through-11-completion-report.md：测试、Reentry、Rollback 与未 Cutover 边界。

参考资料#

• ALCE：Automatic LLMs' Citation Evaluation；
• RAGAS；
• RAGChecker；
• Attributed Question Answering；
• BEIR；
• W3C PROV-O。

Local RAG 最终节省的是找证据的时间，不是取消验证的时间。答案可以不完整，但每个已写出的结论都应该知道自己由哪一条可复核证据支撑。