xsl
a044ea2e47
TtlCache（全输入进键/惰性过期/容量逐出/命中零 DB）+ search 接线 （空结果不缓存，保住 gap 埋点）+ invalidate_cache 真实现（T-P2-10）。 实现： - packages/retrieval/cache.py（新建）：CacheKey 全输入进键（query/body_shape/ occasion/entity_types 排序归一/rule_boost 排序序列化哈希/top_k/失效代数）； TtlCache 惰性过期 + OrderedDict LRU（超限 popitem 最旧）+ hits/misses/ evictions 计数与 stats()；clock 可注入（单测免 sleep，默认 monotonic）； asyncio 单循环不加锁的前提写在模块 docstring；正确性红线（只缓存不可变 值、命中零 DB）同处。纯逻辑，不 import 任何项目内模块（值类型由 service 以 PEP 695 泛型注入，避免循环依赖）。 - packages/retrieval/service.py：__init__ 加 keyword-only cache=None（默认 禁用，行为与现状一致，既有调用点不受影响）；from_settings 按 Settings 装配进程级共享缓存（retrieval_cache_enabled=False → None；TTL/容量变化 时重建）；search() 在 embed 之前查缓存——命中直接返回（零 DB、零 embed）， 写入与命中都做防御性拷贝（results 是 list，调用方拿不到缓存内引用）， 仅有结果时写缓存（空结果不缓存，record_gap 每次都跑）；invalidate_cache() 签名不变：自增 repo.INVALIDATION_VERSION（代数失效，旧代键永不命中， 与 T12 的契约保持）+ 清空共享实例（仅为立即回收内存，失效正确性只 依赖代数）。repo.py 未做任何改动。 测试： - 单测 tests/unit/test_retrieval_cache.py（21 例，fake repo/embedding + 注入时钟，不连库）：同参二连查零 DB 且结果相等、键分量矩阵（query/ occasion/body_shape/entity_types/rule_boost/top_k 任一变化 → miss）、 TTL 过期边界（60.0 过期/59.9 命中）、LRU 逐出与命中率/计数、空结果 不缓存且 gap 埋点每次触发、invalidate_cache() 代数失效（含自增语义 保留断言）、cache=None 与现状一致、from_settings 装配开关与共享实例、 rule_boost 哈希确定性。全量单测 494 passed（基线 473 + 新增 21）。 - 集成 tests/integration/test_retrieval_cache.py（2 例，真实 PG + pgvector）： 发布新实体 + invalidate_cache() 后同参检索立即可见（失效前缓存仍只吐 旧实体，证明缓存在工作——T-P2-10 验收语义）；不失效、TTL=1s 到期 （asyncio.sleep 1.1s）后新实体自然可见（双路径验收）。集成全量 40 passed。 偏差说明：无（invalidate_cache() 在代数失效之外顺带清空共享缓存实例， 失效正确性只依赖代数，清空仅为立即释放内存）。
packages/retrieval/ — 向量与混合检索
架构 §8.3。进程内包，CPU + PostgreSQL，无 HTTP 路由（被 agent / report 的 service 调用）。
模块
embedding.py：EmbeddingProviderProtocol +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）。