Appearance
一次检索请求怎样被约束：Retriever、Metadata Filter 与 Query Rewrite
同一 Retriever 可以先接内存 BM25，再换向量/混合检索；ContextManager 只消费标准 RetrievedChunk 。企业知识库请求必须先按用户可见项目过滤，再做相似度排序；否则 top-K 里可能出现无权限文档。
Retriever Abstraction
Retriever 应只暴露 query→ranked evidence contract，隐藏 OpenAI Vector Store、PGVector、Elasticsearch 等实现差异，便于 eval 和替换。
Metadata Filtering
Metadata Filter 在候选生成阶段就收窄 tenant/project、文档类型、时间、版本和 ACL 范围：这既提升 precision，也防止未授权内容进入 reranker、cache 或模型 Context。权限控制应尽可能下推到数据源/索引查询层，不能靠检索后删除，更不能靠 Prompt 要求模型“不要引用”。
Query Rewrite / Expansion
Query Rewrite 把含糊、口语或上下文依赖的表达转换为更适合检索的 query；Expansion 可以并行生成同义词或子查询提高 recall。原始 query 和结构化约束必须保留，低置信改写应允许回退，并用 retrieval eval 判断它是否真的改善召回，而不是只看“改写后更像搜索词”。
Failure Modes
Context、Retrieval、Tool Catalog 混成一个巨型函数
症状： 同一函数搜文档、选工具、裁历史、写 memory。
为什么危险： 职责和指标无法分离。
处理： ContextManager 消费 Retriever/ToolRegistry 结构化结果，各自独立 contract/eval。
权限 Filter 在召回后才做 Post-filter
症状： 先对全租户向量库搜索，再在应用层删除无权结果。
为什么危险： 未授权内容可能已经进入日志、reranker、缓存或模型 Context，形成数据泄漏。
处理： 把 tenant/project/ACL 作为检索前或检索内部过滤条件，结果再做 defense-in-depth 检查。
Query Rewrite 丢失原始约束
症状： rewrite 只保留主题词，删除时间、实体、权限或否定条件。
为什么危险： 检索结果表面相关但不满足用户真实问题，后续模型很难恢复丢掉的约束。
处理： 保留 original query + structured constraints；rewrite 只补检索表达，并允许低置信时回退原 query。
如何验证
| Case | 断言 |
|---|---|
| Context、Retrieval、Tool Catalog 混成一个巨型函数 | 替换 Fake Retriever/ToolRegistry 能独立测试 Context selection。 |
| 权限 Filter 在召回后才做 Post-filter | 跨两个 tenant 放入高相似文档，断言未授权 document id 从 candidate set 开始就不可见。 |
| Query Rewrite 丢失原始约束 | 构造含日期/实体/否定条件的 query，断言 rewrite 后约束字段仍存在且检索结果满足。 |
自测
- 权限 filter 应在相似度检索前还是把候选召回后再过滤？如果顺序错误，会暴露什么风险或浪费？
- Query rewrite 把一个精确错误码改写成泛化自然语言后反而召回变差。什么时候应该禁止或约束 rewrite？