摘要：

上周完成三合一导入与 LLM 用量统计后，团队反馈两类体验问题：一是 RAG 侧栏只能看到 citations，不知道本次走的是 FULLTEXT 还是 LIKE 兜底；二是 Map-Reduce 摘要常在笔记末尾生成 ```mermaid mindmap``` 脑图块，对复习笔记反而造成干扰。本周交付：（1）RagRetrievalStatsTracker + GET /api/ai/rag/stats，SSE meta 与侧栏展示 retrievalMode 及命中率；（2）HomeView「一键摘要」按钮，调用已有 /api/ai/summarize 追加到文末；（3）优化 CONTENT_EXTRACT Prompt + MermaidStripUtil 后处理，默认 smartnotes.ai.summarize.include-mermaid=false；（4）修复 Import 跳转后 loadNotebook 误 abort SSE 的竞态。

一、本周背景与目标

第十二周 Import 三源合一与 llm/usage 解决了「数据入口」和「成本可见」。联调中仍有两处体验债：

第一，RAG 检索是黑盒。用户看到 citations 却不知道 FULLTEXT 是否命中；也无法量化「关键词 RAG 命中率」。

第二，摘要笔记末尾常出现 mindmap。这是早期 Prompt 为满足任务书「Mermaid 结构生成」要求，在 CONTENT_EXTRACT_SYSTEM 中强制「结尾增加 mermaid mindmap」。LLM 生成的脑图语法易错、节点冗长，移动端预览尤其难读。

第三，Import「导入到新笔记」偶发 SSE 断开。根因是 router 跳转后 HomeView onMounted 再次 loadNotebook，内部 stopAiGeneration() 中止了刚建立的 SSE。

因此本周的目标：（1）RAG 检索路径可观测；（2）编辑器内一键摘要；（3）默认关闭摘要中的 mermaid；（4）修复 SSE 竞态。

二、mindmap 的删除

2.1 mindmap

笔记里的 ```mermaid ... mindmap ... ``` 是 Mermaid 语法的「脑图」块，由大模型在摘要/Reduce 阶段按 Prompt 生成，用于可视化知识结构。

2.2 为什么要默认关闭

任务书要求的是「具备 Mermaid 生成能力」，不等于「每篇笔记都必须带脑图」。实测问题：

语法不稳定：中文节点 + 特殊符号易导致 md-editor 渲染失败；
信息重复：标题与列表已表达结构，mindmap 多为同义重复；
体积大：占 token 与版面，不利于打印/复习。

2.3 三层保障

（1）Prompt：CONTENT_EXTRACT / Reduce 合并指令改为「禁止输出 mermaid」；
（2）后处理：MermaidStripUtil.stripMermaidBlocks 在 MapReduceSummarizeService.postProcess 中执行；
（3）配置：smartnotes.ai.summarize.include-mermaid=false（默认）。需演示 Mermaid时改为 true 即可。

三、RAG 检索统计：FULLTEXT / LIKE / MISS

3.1 设计

RagChatService.retrieveNotes 返回路径枚举：

FULLTEXT — MySQL FULLTEXT（ngram）命中；
LIKE — FULLTEXT 空结果时的 title/content 模糊兜底；
MISS — 无召回，回答固定话术。

RagRetrievalStatsTracker 在每次 chat 后 record(mode)，snapshot() 输出 RagRetrievalStatsVO（总次数、各路径占比）。

RagChatResultVO 新增 retrievalMode；RAG SSE meta 同步携带，前端侧栏显示「本次：FULLTEXT 命中」等标签。

3.2 接口

GET /api/ai/rag/stats — JVM 内存统计，重启清零（与 llm/usage 策略一致）。

3.3 前端

AiChatPanel 副标题展示本次 retrievalMode；累计 stats 行展示 FULLTEXT/LIKE/未命中 百分比。

四、编辑器「一键摘要」

HomeView 顶栏新增「一键摘要」，与「AI 排版」「生成习题」并列：

调用 POST /api/ai/summarize（Map-Reduce，已去 mermaid）；
以 --- + ## AI 摘要 追加到文末，不覆盖原文；
agentReady 与 llm/status 联动置灰。

适用场景：已有长笔记想快速压缩，无需走 Import SSE 全量重写。

五、Import SSE 竞态修复

问题：ImportView createAndOpenNewNote → router.push → loadNotebook → startAiImport；HomeView onMounted 再次 openNote → loadNotebook → stopAiGeneration → ClientAbortException。

修复：loadNotebook 仅在 switching 笔记 id 时 stopAiGeneration；同一 id 且 aiGenerating 时跳过 reload。reloadCurrent 使用 force: true 显式刷新。

GlobalExceptionHandler 对 ClientAbortException 降级为 debug，避免 SSE 断开刷 ERROR 栈。

六、联调清单

1. 导入/摘要新笔记 → 文末无 ```mermaid 块（include-mermaid=false）。
2. 侧栏 RAG 提问 → 显示 retrievalMode；stats 百分比更新。
3. 编辑器「一键摘要」→ 文末追加 ## AI 摘要。
4. Import 导入到新笔记 → SSE 完整写入，后端无 ClientAbort ERROR。

七、小结

第十三周让 RAG「黑盒变灰盒」、摘要「图表变 prose」，并修掉 Import 链路最后一个稳定性 bug。mindmap 并非错误，而是早期 Prompt 的产品化取舍；默认关闭后笔记更适合日常复习，需要时仍可通过配置打开。