diff --git a/docs/RAG数据流程.md b/docs/RAG数据流程.md
index d362e65..9c13473 100644
--- a/docs/RAG数据流程.md
+++ b/docs/RAG数据流程.md
@@ -67,18 +67,27 @@
 
 | 用途 | 模型 | 说明 |
 |------|------|------|
-| 主 LLM | qwen3.6-flash | 回答生成、上下文理解 |
-| 意图分析 | qwen-turbo | 轻量快速，用于问题改写与意图判断 |
+| 主 LLM | deepseek-v4-flash | 回答生成、上下文理解 |
+| 意图分析 | deepseek-v4-flash | JSON 结构化输出（`INTENT_RESPONSE_FORMAT=True`） |
 | VLM | qwen-vl-plus | 图片理解与描述生成 |
-| 云端重排序 | qwen3-rerank | DashScope API 调用，替代本地 BGE-reranker |
+| 云端重排序 | qwen3-rerank | DashScope API 调用 |
+| 本地重排序 | bge-reranker-base | ONNX Runtime，用于图片 CrossEncoder 二次评分 |
+| Embedding | bge-base-zh-v1.5 | 文本向量化 |
 
-### 1.3 v7.0.0 架构变更要点
+### 1.3 架构变更要点
 
-- **Reranker**：从本地 BGE-reranker 切换为云端 DashScope API（qwen3-rerank）
+- **Reranker**：从本地 BGE-reranker 切换为云端 DashScope API（qwen3-rerank），本地 reranker 保留用于图片 CrossEncoder 二次评分
 - **MMR 去重**：使用文本相似度模式（`MMR_USE_EMBEDDING=false`），基于 Jaccard 系数
 - **Agentic 引擎**：拆分为多个子模块（agentic_search / agentic_answer / agentic_citation 等）
 - **Graph RAG**：模块已清空，不再使用
 
+**v7.1 新增变更**：
+
+- **性能插桩**：`/rag` 流式响应新增 `stages_ms` 字段，记录 8 个管线阶段耗时（intent / cache / search / vlm / image / rescue / llm / post）
+- **CrossEncoder 图片二次评分**：`select_images` 最终排序前新增 P3 阶段，用本地 bge-reranker-base 对 `(query, vlm_desc)` 做语义精排，映射为 ±5 分调整量；CE 负分图片直接剔除
+- **意图分析 JSON 强制输出**：新增 `INTENT_RESPONSE_FORMAT` 配置开关，推理模型需设为 False
+- **缓存管理端点**：新增 `POST /cache/clear` 一键清除精确缓存 + 语义缓存
+
 ---
 
 ## 二、请求入口
@@ -340,8 +349,11 @@ enhance_retrieved_chunks(contexts, query, kb_name)
 | 查询类型 | 参数调整 |
 |----------|----------|
 | 精确图号查询（"图2.3"） | `MAX_IMAGES=2, MIN_SCORE=5.0` |
-| 弱图片意图（"发电量图"） | `MAX_IMAGES=1` |
-| 普通查询 | `MAX_IMAGES=2` |
+| 数据驱动（检索含图片切片） | `MAX_IMAGES=5, MIN_SCORE=2.0` |
+| 文本引用图表 | `MAX_IMAGES=3, MIN_SCORE=2.0` |
+| 普通查询 | `MAX_IMAGES=2, MIN_SCORE=3.0` |
+
+表格嵌入图片时 `MAX_IMAGES` 可扩展至 15。
 
 **步骤二：提取图表引用**
 
@@ -359,18 +371,37 @@ referenced_figures = {'2.3': {'source_file': 'xxx.pdf'}, ...}
 |--------|------|
 | 图号精确匹配（查询中有"图2.3"） | +10 分 |
 | 表号精确匹配 | +10 分 |
-| 关键词匹配（"发电量"等） | +2 分/个 |
-| 字符重叠 | +0.2 分/字符 |
+| 关键词匹配（"发电量"等） | +2 分/个，上限 8 |
+| 字符重叠 | +0.2 分/字符，上限 3 |
 | 章节匹配 | +1.5 分 |
 | 图片类型（chart > image） | +2 / +1 分 |
-| 向量相似度 | +2 分（最高） |
-| 引用匹配（需章节相关） | +8 分 |
 
-**步骤四：图文关联补充**
+**步骤四：VLM 与章节关联调整**
 
-遍历 top 5 文本块中引用的图表编号，查找对应的图片切片并补充到结果中。
+| 条件 | 调整 |
+|------|------|
+| VLM 描述与查询相关（`_check_vlm_relevance >= 0.5`） | +2 分 |
+| VLM 描述与查询不相关（`< 0.3`） | -3 分 |
+| 图片章节与主检索不匹配（`section_similarity < 0.3`） | -5 分 |
+| 图号/表号被文本引用 + 章节匹配 | +8~+13 分 |
+| 来源文件匹配 primary_sources | +2 分 |
 
-**步骤五：返回 top N 图片**
+**步骤五：CrossEncoder 语义精排（P3）**
+
+对所有过线候选图片，用本地 bge-reranker-base 对 `(query, vlm_desc_or_caption)` 做二次评分：
+
+```python
+ce_scores = engine.reranker.predict([(query, desc) for desc in descriptions])
+# 映射：ce_score > 0 → adjustment ∈ (0, +5]，ce_score < 0 → adjustment ∈ [-5, 0)
+img['score'] += adjustment
+# CE 负分图片直接剔除
+```
+
+**步骤六：后置过滤**
+
+`_filter_images_by_answer()` 根据 LLM 回答内容反向筛选图片，过滤回答中未提及的无关图片。
+
+**步骤七：返回 top N 图片**
 
 ```python
 scored_images.sort(key=lambda x: x['score'], reverse=True)
@@ -607,3 +638,279 @@ VLM 描述示例（更精准）：
 | `parsers/mineru_parser.py` | 文档解析 | `parse_with_mineru()`, `MinerUChunk` |
 | `knowledge/manager.py` | 知识库管理 | `add_file_to_kb()`, `generate_lightweight_image_description()` |
 | `knowledge/lazy_enhance.py` | 懒加载增强 | `lazy_vlm_description()`, `enhance_retrieved_chunks()` |
+| `core/cache.py` | 三层精确缓存 | `RAGCacheManager`, `get_cache_manager()` |
+| `core/semantic_cache.py` | 语义缓存 | `SemanticCache`, `get_semantic_cache()` |
+| `knowledge/image_cleanup.py` | 孤儿文件清理 | `cleanup_image_orphans()`, `collect_referenced_images()` |
+| `cleanup_orphans.py` | 孤儿文件清理脚本 | `--force` 执行删除，默认 dry-run |
+| `sync_vlm_cache.py` | VLM 缓存同步 | `--re-embed` 强制重算 embedding |
+| `eval_image_retrieval.py` | 图片检索评测 | 检索层 + 选择层分层评测 |
+
+---
+
+## 十二、缓存系统
+
+### 12.1 三层精确缓存（core/cache.py）
+
+`RAGCacheManager` 管理三个独立的 `LRUCache` 实例：
+
+| 缓存层 | Key 构造 | TTL | 容量 | kb_version 关联 |
+|--------|----------|-----|------|-----------------|
+| Query Cache | `MD5(query:kb_name:kb_version)` | 1h | 500 | ✅ 版本失效 |
+| Embedding Cache | `MD5(emb:{text})` | 24h | 2000 | ✅ 版本失效 |
+| Rerank Cache | `MD5(rerank:{query}:{sorted_doc_ids})` | 1h | 1000 | ❌ 变更时全清空 |
+
+**知识库版本失效机制**：
+
+```python
+def increment_kb_version(kb_name):
+    old_version = self._kb_versions.get(kb_name, 0)
+    self._kb_versions[kb_name] = old_version + 1
+    # 失效旧版本
+    self.query_cache.invalidate_by_version(old_version)
+    self.embedding_cache.invalidate_by_version(old_version)
+    self.rerank_cache.clear()  # Rerank 无 kb_version，全量清空
+```
+
+`sync.py` 文档变更时调用 `increment_kb_version()` 触发失效。
+
+**写入保护**：`CACHE_MIN_SCORE = 0.3`，检索结果最高分低于此值时不写缓存，避免低质量结果被缓存。
+
+### 12.2 语义缓存（core/semantic_cache.py）
+
+`SemanticCache` 使用 FAISS 向量索引实现语义级缓存：
+
+```
+查找：query_embedding → FAISS ANN 搜索 → 余弦相似度 > 0.92 → 候选
+二次验证：Jaccard(query, cached._raw_query) >= 0.5 → 确认命中
+存储：query_embedding + result → FAISS add
+```
+
+**Jaccard 二次验证**（字符级）：
+
+```python
+set_a = set(query)      # 字符集合
+set_b = set(cached_query)
+similarity = |intersection| / |union|
+```
+
+**Intent 与 RAG 共用 FAISS 索引**，通过 `cache_type` 字段隔离：
+
+| 缓存类型 | cache_type 值 | Embedding 输入 | 读取条件 |
+|----------|---------------|---------------|---------|
+| RAG 回答 | `"rag_answer"` | `embedding(query|collections)` | `cache_type == "rag_answer"` |
+| 意图分析 | `"intent_analysis"` | `embedding(query)` | `cache_type != "rag_answer"` |
+
+**容量管理**：默认 `max_size=10000`，达到上限时 `self.clear()` 全清空（非 LRU 淘汰）。
+
+**Intent 精确缓存**（独立于 FAISS）：`_exact_cache: Dict[str, IntentAnalysis]`，key = `query + 最近2条历史摘要`，上限 500 条，无 TTL，满后停止接收新条目。
+
+### 12.3 缓存命中链路
+
+一个 `/rag` 请求依次经过以下缓存检查点：
+
+```
+请求进入 chat_routes.rag()
+  │
+  ├─ ① 语义缓存读取（FAISS）
+  │    key = embedding(retrieval_query|collections)
+  │    要求 cache_type == "rag_answer"
+  │    二次验证: Jaccard >= 0.5
+  │    ├─ 命中 → 直接流式返回缓存答案，流程结束
+  │    └─ 未命中 → 继续
+  │
+  ├─ ② intent_analyzer.analyze()
+  │    ├─ 精确缓存: key = query + 历史摘要
+  │    ├─ 语义缓存: key = embedding(query)，cache_type != "rag_answer"
+  │    └─ 未命中 → 调 LLM → 写入两层缓存
+  │
+  ├─ ③ engine.search()
+  │    ├─ Query Cache: MD5(query:kb_name:kb_version)
+  │    ├─ Embedding Cache: MD5(emb:{text})
+  │    └─ Rerank Cache: MD5(rerank:{query}:{sorted_doc_ids})
+  │
+  ├─ ④ LLM 生成回答
+  │
+  └─ ⑤ 语义缓存写入（FAISS）
+       存入 { cache_type: "rag_answer", answer, sources, images, _raw_query }
+```
+
+**缓存清除**：`POST /cache/clear` 端点清除 Query/Embedding/Rerank 缓存 + 语义缓存（需网关认证）。
+
+---
+
+## 十三、图片选择管线
+
+### 13.1 评分流程（select_images）
+
+完整的图片选择管线包含 7 个阶段：
+
+```
+score_image_relevance()      ← P1: 基础分（关键词/图号/章节/类型）
+    ↓
+VLM 相关性调整              ← _check_vlm_relevance()  -3 / +2 分
+    ↓
+章节关联惩罚                ← section_similarity < 0.3 → -5 分
+    ↓
+图号/表号引用加分            ← 文本引用匹配 → +8~+13 分
+    ↓
+来源文件加分                ← primary_sources 匹配 → +2 分
+    ↓
+MIN_SCORE 过滤              ← 动态阈值 2.0~5.0
+    ↓
+CrossEncoder 二次评分        ← P3: 本地 reranker 对 (query, desc) 精排
+    ↓                             正相关 +5，负相关 -5 且直接剔除
+MAX_IMAGES 预算控制          ← 动态上限 2~15 张
+    ↓
+_filter_images_by_answer()  ← 后置过滤：LLM 回答关键词重叠
+```
+
+### 13.2 图片召回保障
+
+图片切片在检索层面临 CrossEncoder 系统性低分（0.002~0.08 vs 文本 0.3~0.9），有多重保障机制：
+
+| 机制 | 位置 | 说明 |
+|------|------|------|
+| 图片独立召回 | `engine._search_image_chunks()` | 对 image/chart 切片单独查询 ChromaDB |
+| `_image_boost` 标记 | `chat_routes.py` | 图片意图查询时，为匹配的图片切片打 1.5x/2.0x boost 标记 |
+| 章节聚类救援 | `_rescue_section_cluster()` | 当整章节切片全被 rerank 压制时，保底分配分数 |
+| BM25 分歧救援 | `_rescue_bm25_divergence()` | BM25 高排名但 rerank 低分的切片被恢复 |
+| 词法匹配救援 | `_rescue_lexical_match()` | 切片文本精确包含查询关键词时提升分数 |
+
+---
+
+## 十四、VLM 懒加载增强
+
+**入口文件**：`knowledge/lazy_enhance.py`
+**触发位置**：`chat_routes.py` `generate()` 函数
+
+### 14.1 触发条件
+
+| 切片类型 | 触发条件 | 调用模型 |
+|----------|---------|---------|
+| image / chart | `has_vlm_desc=False` 且 `image_path` 非空 | VLM（qwen-vl-plus） |
+| table | `has_summary=False` 且 `score > 0.7` | LLM（表格摘要） |
+| table + 关联图片 | `has_vlm_desc=False` 且 `image_path` 非空 | VLM |
+
+### 14.2 增强流程
+
+```
+缓存检查（图片 MD5 哈希 → .data/cache/vlm/{hash}.txt）
+    ├─ 缓存命中（内容 ≥ 5 字符）→ 直接返回
+    └─ 缓存未命中 →
+         ├─ 调用 VLM/LLM 生成描述/摘要
+         ├─ 空描述保护（< 5 字符）→ 不写缓存，不更新向量库
+         ├─ 写入缓存文件
+         └─ 更新 ChromaDB
+              ├─ metadata: { has_vlm_desc: True, vlm_desc: description }
+              ├─ embedding: 用 VLM 描述重新计算向量（通过 RAGEngine 单例获取模型）
+              └─ document: 更新为 VLM 描述文本
+```
+
+**embedding 模型获取**：`KnowledgeBaseManager` 没有 `embedding_model` 属性，通过 `_get_embedding_model()` 从 `RAGEngine` 单例获取。
+
+### 14.3 后台异步化
+
+VLM/LLM 调用在后台线程执行，不阻塞主流程：
+
+```python
+# chat_routes.py 中
+_bg_contexts = copy.deepcopy(contexts)  # 深拷贝避免线程竞争
+_t = threading.Thread(target=_background_enhance, daemon=True)
+_t.start()
+# 主流程继续 select_images + LLM 生成
+```
+
+后台线程使用 `asyncio.run()` + 60s 超时保护。首次查询时图片使用 caption + section 作为临时描述，后台生成完成后写入 ChromaDB，下次查询直接使用缓存。
+
+---
+
+## 十五、文档解析与切片
+
+### 15.1 MinerU 解析流程
+
+**入口文件**：`parsers/mineru_parser.py`
+
+支持两种云端 API 模式：
+
+| 模式 | 端点 | 延迟 | 适用场景 |
+|------|------|------|---------|
+| v4 precise | `/api/v4/` | 较长（需排队） | 高精度 PDF 解析 |
+| v1 agent | `/api/v1/agent/` | ~10s | 轻量级文档处理 |
+
+**V2 格式转换**（`_parse_v2_content_list`）：
+
+MinerU 返回的 content_list 被转换为 `MinerUChunk` 对象，提取的字段包括：`_v2_table_type`、`_v2_table_nest_level`、`_v2_list_type`、`sub_type`（部分字段在下游切片时被丢弃）。
+
+**标题检测**（`parsers/heading_rules.py`）：
+
+基于规则的多级标题检测，`_validate_level()` 长度守卫防止长文本误判为标题：
+
+| 级别 | 最大长度 | 超出后 |
+|------|---------|--------|
+| H1 | 40 字符 | 降级为普通文本 |
+| H2 | 60 字符 | 降级为普通文本 |
+| H3 | 50 字符 | 降级为普通文本 |
+
+`chinese_article` 规则额外限制 `max_length=30`，`numeric_level1` 排除以标点结尾的误判。
+
+### 15.2 切片后处理
+
+**`_post_process_chunks`** 核心逻辑：
+
+1. **连续标题链合并**：连续 title 类切片合并为一个 chunk（保留最高 text_level）
+2. **body 合并后 text_level 重置**：body 合并进 title buffer 后执行 `buffer.text_level = 0`，防止下一个标题被错误合并
+3. **元数据写入**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `chunk_type` | str | `text` / `title` / `table` / `image` / `chart` |
+| `section` | str | 章节路径（如 `综述 > 2.3发电`） |
+| `text_level` | int | 标题级别（0=body, 1=H1, 2=H2, 3=H3） |
+| `image_path` | str | 图片文件名 |
+| `bbox` | str | 页面坐标（仅 PDF） |
+| `has_vlm_desc` | bool | 是否已有 VLM 描述 |
+
+---
+
+## 十六、性能插桩
+
+**入口文件**：`api/chat_routes.py` `generate()` 函数
+
+### 16.1 各阶段计时
+
+在 SSE 流式生成器中初始化计时字典，记录 8 个管线阶段耗时：
+
+| 阶段 key | 记录时机 | 覆盖范围 |
+|----------|----------|----------|
+| `intent` | 意图分析完成后 | IntentAnalyzer.analyze() |
+| `cache` | 语义缓存检查后 | semantic_cache.lookup() |
+| `search` | 混合检索+切片处理完成后 | engine.search() + 上下文提取 |
+| `vlm` | VLM 懒加载完成后 | enhance_retrieved_chunks() |
+| `image` | select_images 完成后 | 图片选择 |
+| `rescue` | 救援管线+上下文构建完成后 | 聚类/BM25/预算 |
+| `llm` | LLM 流式生成完成后 | engine.generate_answer_stream() |
+| `post` | finish 事件构建完成后 | 答案对齐+debug 事件 |
+
+### 16.2 数据输出
+
+**SSE finish 事件**：
+
+```json
+{
+  "type": "finish",
+  "timing": {
+    "total_ms": 12345,
+    "stages_ms": {
+      "intent": 4200, "cache": 50, "search": 900,
+      "vlm": 10, "image": 30, "rescue": 200,
+      "llm": 6800, "post": 150
+    }
+  }
+}
+```
+
+**服务端日志**：
+
+```
+[性能] 总12345ms | 意图4200 缓存50 检索900 VLM10 图片30 救援200 LLM6800 后处理150
+```
diff --git a/docs/待解决风险项.md b/docs/待解决风险项.md
new file mode 100644
index 0000000..c18a93e
--- /dev/null
+++ b/docs/待解决风险项.md
@@ -0,0 +1,125 @@
+# 待解决风险项
+
+> 本文档记录已识别但尚未实施修复的风险项，供后续迭代参考。
+> 更新日期：2026-06-21
+
+---
+
+## P1: SemanticCache 满容量全清空
+
+**文件**：`core/semantic_cache.py:161-164`
+
+**现状**：当 FAISS 索引达到 `max_size`（默认 10000）时，执行 `self.clear()` 全清空，而非 LRU 淘汰最旧条目。
+
+**影响**：高使用量下缓存命中率周期性断崖式下降，下一波请求全部 miss。
+
+**建议方案**：
+- 短期：可接受，断崖后缓存会重新积累
+- 长期：改为分批淘汰（每次淘汰最旧 N 条），或引入 TTL 自动过期
+
+**风险等级**：中（性能波动，不影响正确性）
+
+---
+
+## P2: _exact_cache 满后永久拒绝新条目
+
+**文件**：`core/intent_analyzer.py:412-413`
+
+**现状**：
+
+```python
+if len(self._exact_cache) < self._exact_cache_max:  # 500
+    self._exact_cache[exact_key] = analysis
+```
+
+500 条满后不再接受新条目，且无淘汰机制。服务运行一段时间后，精确缓存变为固定快照。
+
+**影响**：后续查询的精确缓存命中率逐渐归零，退化为每次都走语义缓存或 LLM 调用。
+
+**建议方案**：改用 `OrderedDict` + 淘汰最旧条目，与 `LRUCache` 保持一致。
+
+**风险等级**：低（性能退化，不影响正确性）
+
+---
+
+## P3: Jaccard 字符级阈值偏松
+
+**文件**：`core/intent_analyzer.py:450-473`
+
+**现状**：语义缓存二次验证使用字符级 Jaccard 相似度，阈值 0.5。中文短句共享大量单字（如"如何申请" vs "如何拒绝"），Jaccard = 2/4 = 0.5 刚好过线。
+
+**影响**：语义相似但意图不同的查询可能误命中缓存。
+
+**建议方案**：
+- 方案 A：提升阈值到 0.6
+- 方案 B：改用 bigram Jaccard（相邻字对作为集合元素）
+
+**风险等级**：低（误命中概率不高，且有 embedding 0.92 阈值前置过滤）
+
+---
+
+## P4: /cache/clear 无 DEV_MODE 守卫
+
+**文件**：`api/sync_routes.py:322`
+
+**现状**：`POST /cache/clear` 端点仅使用 `@require_gateway_auth`，没有 `DEV_MODE` 检查。生产环境任何认证用户都能清缓存。其他 dev-only 端点（如 `document_routes.py` 的预览接口）有 `DEV_MODE` 守卫。
+
+**影响**：生产环境缓存被误清，导致短暂的性能下降。
+
+**建议方案**：添加 `DEV_MODE` 检查，或限制为 admin 角色。
+
+**风险等级**：中（生产环境影响）
+
+---
+
+## P5: PDF TOC 目录数据未单独处理
+
+**文件**：`parsers/mineru_parser.py`
+
+**现状**：PDF 文档的目录页（TOC）被 MinerU 解析为多个 text_level=1 的标题切片，内容包含 `....1` 等页码标记。这些目录切片入库后污染 section 元数据，干扰章节过滤和上下文扩展。
+
+**影响**：RAG 检索时目录切片可能被误判为相关章节，干扰上下文扩展的 section 精确匹配。
+
+**建议方案**：
+- 解析阶段检测 TOC 模式（连续短标题 + 页码标记）
+- 标记 `chunk_type: 'toc'` 或直接跳过不入库
+
+**风险等级**：中（影响检索质量）
+
+---
+
+## P6: PDF chart VLM 描述缺失
+
+**文件**：`knowledge/lazy_enhance.py`、`parsers/mineru_parser.py`
+
+**现状**：部分 PDF 图表切片的 VLM 描述为空。原因可能是：
+1. MinerU VLM API 对部分图表返回空 content（上游问题）
+2. 解析阶段的提取条件过严（如要求 `'|' in markdown` 才提取 chart_markdown）
+
+**影响**：无 VLM 描述的图表切片退化为纯关键词匹配，图片选择准确率下降。
+
+**建议方案**：
+- 上游：跟进 MinerU API 的空 content 问题
+- 本地兜底：用 `caption + section + 上下文文本` 拼接作为 fallback 描述
+- 定期重算：用 `sync_vlm_cache.py --re-embed` 批量重算
+
+**风险等级**：低（有 lazy_enhance 兜底，首次查询后补生成）
+
+---
+
+## P7: 图片选择负面用例误召回
+
+**文件**：`api/chat_routes.py`
+
+**现状**：定义/原则类查询（如"五化终端定义"、"防洪调度原则"）不应返回图片，但 `select_images` 仍返回了 2-3 张。根因：
+1. `_filter_images_by_answer` 的关键词重叠阈值对长回答偏宽松
+2. 兜底逻辑：过滤后为空时保留分数最高的 1 张
+
+**影响**：用户看到不相关的图片，降低信任度。
+
+**建议方案**：
+- 增加查询意图判断：纯定义/原则类查询不应触发图片返回
+- 移除兜底逻辑或提高兜底阈值
+- 增加"不应返回图片"的负面评测用例
+
+**风险等级**：中（影响用户体验）