状态：已实施（2026-09-03；真机验收待执行） 依据：v0.19 检索与发现层设计（已批准，[ ] 已归档） · ADR-029 · REQ-260 · REQ-262（部分）
AI 对话新增「📚 学习库问答」会话模式：提问 → 本地全库检索（FTS5/trigram + 2 字 LIKE，v0.19.0 索引）→ 命中片段列表恒返回（本地零成本零上传，不受 AI 闸门约束）；生成回答仅当 content_gate + kb_qa_enabled 双闸门开（默认关）→ 片段打包（budget_allocator pack_fragments 转正：档位硬顶 + 诚实截断）→ 流式生成 + 逐条引用（meta_json 持久化 + 引用 chips 跳笔记高亮命中词）；断网/Provider 故障 → 该条回退命中列表 + 诚实错误可重试。
| 层 | 内容 |
|---|---|
| 数据层 | chat_sessions.retrieval 列（创建时定死——已有会话不改语义）+ chat_messages.meta_json 列（ensure_column 幂等补列，既有表零改动）；ChatSession/ChatMessage 契约扩展（list/get/insert 行映射）· set_chat_message_meta（会话限定写） |
| 设置 | AiSettings.kb_qa_enabled（默认关）+ kb_qa_tier（light/standard/deep 默认 standard）· kb_qa_gate（content_gate + kb 开关双闸门——goal_plan_gate 同款范式）· ai_set_kb_qa 最小面命令 · ai_get_settings 视图字段 |
| 编排 | commands_ai_chat_kb（kb_chat_send/kb_chat_regenerate——纯聊链路零改动分流）：单活跃流注册先行 → 用户消息落库（编辑重发语义沿用）→ kb_search → KbHits 事件恒发 → 闸门关：命中列表引导文案落库（hits-only meta）+ Done；闸门开：客户端解析失败/流失败 → failed 占位 + meta 命中照挂（引用不丢）+ Failed 事件；成功 → 全文取回 → kb_prompt 打包 → 流式生成 → 回答落库 + answer meta + Done/Aborted |
| 纯函数 | kb_prompt（KB_SYSTEM_PROMPT 只依据片段/无命中明说；kb_build_context 片段打包 [n] 出处标签 + 预算截断诚实标记；kb_meta_json {mode,hits} 契约 + as_history 历史过滤——hits-only 引导不冒充回答喂后续上下文；kb_hits_only_content 零命中诚实文案）——10 用例 |
| 事件 | ChatStreamEvent::KbHits（hits 载荷——FE 流内先达；终态后消息 metaJson 持久化再渲染） |
| 前端 | types/chat+kb（ChatSession.retrieval/ChatMessage.metaJson/KbHit/KbMessageMeta/KbIndexStats/KbReindexEvent）· utils/kbHits（parseKbMeta/firstMarkedTerm/hitLabel/isNoteHit——7 用例）· CitationChips（引用卡片：📄 笔记·节标题 / 📎 碎片·组 + snippet 一行；笔记可点跳转，碎片仅展示——4 用例）· ChatPage 新会话模式入口（侧栏 ＋ 纯聊 / 📚 学习库问答）+ 会话徽标 · useChatStream per-session hits 累积 · ChatMessageList 双产物渲染（流内 chips + 终态 meta chips，failed 也保留引用）· 跳笔记高亮命中词最小面：App focusNoteSearch → NotesPage 选中/滚动 → NoteReadingView 外部搜索注入（复用 A2 搜索高亮与定位）· SettingsPage「学习库」段（LearningLibraryPanel：引擎状态如实/生成开关+档位/索引统计+脏源与失败角标/全量重建+进度条，8s 轻量自新） |
- 双闸门默认关（content_gate 之上 kb_qa_enabled）；命中列表恒可用不受闸门约束；首次云端提示沿用（v0.16 CLOUD_NOTICE）
- 预算档位复用 budget_allocator（tier_tokens 换算片段预算硬顶；pack_fragments 由 dead_code 转正 + 截断诚实标记注入上下文）
- 成本/审计：流完成 usage_json 落库（既有 ai_usage/消息全文轨迹可见）；meta_json 只存检索引用概要防正文膨胀
- 降级链实测路径：AI 未开 → hits-only 引导；客户端配置缺失/断网/Provider 故障 → failed 占位 + 引用保留 + 重试（chat_regenerate 整链重跑）；无 embedding → FTS 精度工作
- Rust：kb_prompt 10 用例 + db_ai_chat（retrieval/meta_json 迁移幂等 roundtrip）+ ai_settings（kb_qa_gate 三态矩阵）——
kb_/ai_settings/db_ai_chat过滤全绿；全量套件 3 例预存失败同 v0.19.0（与本次变更域无关，登记观察） - 前端：kbHits 解析/词提取/标签 7 用例 · CitationChips 渲染/点击跳转带词/碎片禁点/空命中 4 用例 · tsc 零错误；全量 vitest 70 文件 523 用例全绿（终验口径；早前一次并跑曾现 KnowledgeGraphView 偶发，隔离单跑与终验均绿）
- clippy：本批域零警告（too_many_arguments/repeat 建议已清理）
- 学习库问答开箱即用：发送即得本地命中片段列表（AI 未开 → 引导直达设置，不灰死）
- 开启 AI 后：问"我在哪学过 XX" → 命中列表 + 带引用回答；点引用跳笔记并高亮命中词
- 断网/Provider 故障 → 该条回退命中列表 + 诚实错误可重试
- 每问成本/轨迹可见（usage/全文/meta 引用）
- 设置→学习库 引擎状态/统计/重建如实；回归全绿
- 设计/ADR：设计 §七/§9 · ADR-029 · REQ-260/REQ-262
- 后续：v0.19.2 读路径 B（检索建议）· v0.19.3 语义增强（embedding）·
/ask命令别名（spec 明确下批接线，不阻塞本路径）· kb_discovery 发现开关随 v0.19.2 注册 feature_flags
- 真机验收（上述 5 项）
- 全量回归收尾（cargo test / vitest / tsc / clippy 报告归档）