# `packages/retrieval/` — 向量与混合检索

架构 §8.3。进程内包，CPU + PostgreSQL，无 HTTP 路由（被 agent / report 的
service 调用）。

## 模块

- `embedding.py`：`EmbeddingProvider` Protocol + `DeterministicEmbedder`
  （测试/dev 的确定性假实现，sha256 种子 → 归一化 1024 维向量）+ 工厂。
  真实 BGE-M3 ONNX 加载是后续任务（`kb_embedding_device` 已预留）。
- `repo.py`：`kb_chunk` / `kb_gap` 数据访问。一条 CTE 完成硬过滤 +
  向量召回（`<=>` 余弦）+ 关键词召回（`ts_rank`）。
- `rerank.py`：RRF 融合重排的纯数学（单测逐项断言，不连库）。
- `service.py`：编排 embed → 检索 →（无结果）gap 埋点。

管线：

```
硬过滤(SQL WHERE) → 向量召回(pgvector) → 关键词召回(tsvector)
→ RRF 融合 + 权重重排 → 输出 ScoredChunk；空结果落 kb_gap
```

重排权重（可配置，需用黄金集调参）：
`最终分 = 0.45×向量 + 0.2×关键词 + 0.25×规则权重 + 0.1×新鲜度`

## 两条不能妥协的要求

- **硬过滤零漏**（FR-KB-06 / T-P2-04）：draft/禁忌实体必须在 SQL 的
  WHERE 里排除，不能靠权重压低 —— 这是过滤问题，不是排序问题。
  集成测试 `tests/integration/test_hybrid_retrieval.py` 断言"禁忌实体
  即使向量最近也绝不出现"。
- **规则命中要有明显加权**：专业规则的可信度高于语义相似度（`rule_boost`
  接口已留，规则引擎联动属后续任务）。
- p95 < 200ms（NFR-PERF-06）。