feat: add knowledge search explain endpoint

project-docs/V2-ai-platform-embedding-pgvector-2026-06-22.md

@@ -44,6 +44,13 @@
    - PostgreSQL + pgvector 环境会重新写入 `knowledge_chunks.embedding`。
    - Python SDK 新增 `reindex_knowledge_documents(...)`。
 
+7. 检索 explain 闭环。
+   - 新增 `GET /api/v1/knowledge-chunks/search/explain`。
+   - 返回 normalized terms、候选 chunk 数、命中数、keyword/vector/hybrid 分数。
+   - 返回每个候选项的 `included`、`rank`、`filter_reason`。
+   - Python SDK 新增 `explain_knowledge_search(...)`。
+   - JSON fallback 的向量分改为 cosine 口径，便于和 pgvector cosine 距离保持一致。
+
 ## 生产配置建议
 
 ```powershell
@@ -73,3 +80,4 @@ python -m alembic upgrade head
 - provider 不可用且允许 fallback 时：chunk 仍可写入，检索仍可用，但 provider 显示 `local-hash`。
 - pgvector 可用时：优先使用数据库向量距离排序。
 - pgvector 不可用时：回退 JSON embedding，不影响法律问答主链路。
+- explain 接口可说明命中依据和过滤原因，用于法律问答可信度展示和检索调参。