feat(recall): 新增召回来源诊断信号

[ottercoconut]

背景

Linear issue：LINK-195

当前 RAG 召回链路中，sparse / dense 因分数阈值过滤或无命中返回空列表时，会被 RecallPipeline 视为合法成功路，不进入 failed_sources。当最终融合候选只剩 BM25 时，对外仍容易被理解为“三路成功的 hybrid 召回”，缺少可观测信号说明本次实际已经退化为 BM25-only。

本 PR 按 .specs/link-195/brief.md 与已冻结 acceptance 的结论收敛范围：只新增诊断信号供前端、纯召回 JSON、日志和后续模块消费；不改 prompt、生成策略、rerank、Java 落库或错误码。

改动内容

召回诊断模型

• 新增 RecallDiagnostics，包含：
  • source_mode
  • degraded
  • active_sources
  • per_source_counts
  • empty_sources
  • failed_sources
• 新增四个 source_mode：
  • hybrid：bm25 / sparse / dense 都有候选贡献
  • bm25_only：只有 bm25 有候选贡献
  • missing_sparse：bm25 + dense 有候选，sparse 无候选
  • missing_dense：bm25 + sparse 有候选，dense 无候选
• reason 字段不在首版实现中返回。

Pipeline 行为

• RecallPipeline 在完整三路启用且结果落入四态时构造 recall_diagnostics。
• 合法空命中仍不是失败，failed_sources 仍只表示异常失败路。
• 三路全空保持既有空召回语义，不新增 source_mode，避免扩大 LINK-195 范围。
• 非 hybrid 诊断会写结构化 warning 日志，包含 source_mode、active_sources、per_source_counts、empty_sources、failed_sources。

对外响应

• POST /api/v1/rag/stream 的成功终态带出 recall_diagnostics：
  • answer_done
  • recall_done
• POST /api/v1/recall 成功 JSON 响应带出同构 recall_diagnostics。
• SSE error 终态不新增该字段，保持现有错误契约。

文档同步

已同步：

• docs/api/http_contracts.md
• docs/internals/recall_pipeline.md
• docs/internals/recall_generation.md
• docs/internals/recall_http_api.md

非目标

本 PR 明确不做以下事情：

• 不重写 RRF / weighted_score 算法。
• 不取消或弱化 sparse / dense 阈值配置能力。
• 不改 BM25 retriever 逻辑。
• 不改 rerank 策略。
• 不改 RAG prompt 或 LLM 生成调用。
• 不新增错误码。
• 不改 Java 对话落库或 MQ ChatTurnMessage 契约。
• 不新增数据库字段或 Alembic migration。

测试

已执行：

.venv/bin/pytest tests/unit/core/pipeline/recall tests/unit/application tests/unit/api -q

结果：

130 passed, 5 warnings

文档同步检查：

.venv/bin/python scripts/quality/check_docs_sync.py --staged

结果：

OK: 14 changed file(s), no doc-sync issues

风险与说明

• recall_diagnostics 是新增字段；旧消费方忽略该字段即可保持兼容。
• degraded=true 不是错误，只表示召回来源结构退化，不能等同于请求失败。
• 三路全空仍按现有空召回处理，避免为本 issue 引入未冻结的 empty source mode。
• .specs/link-195/ 为本地 spec-as-test 过程产物，按项目规范不进入提交。