feat(kb): kb_search 混合检索 RRF 合流与三路引擎接线（REQ-259）

Author: Aparencia

app/src-tauri/src/commands_ai_chat_kb.rs

@@ -129,8 +129,17 @@ fn kb_run(
     flag: CancelFlag,
     settings: &AiSettings,
 ) -> Result<(), String> {
-    // ① 本地检索（零成本零上传——不受闸门约束）
-    let hits = match state.db.kb_search(question, KB_QA_HITS_LIMIT) {
+    // ① 本地检索（零成本零上传——不受闸门约束；REQ-259：引擎就绪自动语义合流；
+    // 锁与 db 调用同作用域——引擎借用不逃逸锁生命周期）
+    let hits = {
+        let slot = state
+            .embedding_slot
+            .lock()
+            .map_err(|e| format!("embedding 引擎锁中毒: {}", e))?;
+        let engine = (slot.engine.dims().is_some()).then(|| slot.engine.as_ref());
+        state.db.kb_search_hybrid(engine, question, KB_QA_HITS_LIMIT)
+    };
+    let hits = match hits {
         Ok(h) => h,
         Err(e) => {
             // 检索层故障：failed 占位 + 诚实错误（与断网同类降级路径）

app/src-tauri/src/commands_kb.rs

@@ -45,10 +45,18 @@ pub fn kb_search(
     if q.chars().count() > KB_QUERY_MAX_CHARS {
         return Err(format!("查询过长（≤{} 字符）", KB_QUERY_MAX_CHARS));
     }
-    state
-        .db
-        .kb_search(q, limit.unwrap_or(KB_SEARCH_DEFAULT_LIMIT).min(KB_SEARCH_MAX_LIMIT))
-        .map_err(|e| e.to_string())
+    // REQ-259：引擎就绪时语义合流（锁与 db 调用同作用域——借用不逃逸）
+    let result = {
+        let slot = state
+            .embedding_slot
+            .lock()
+            .map_err(|e| format!("embedding 引擎锁中毒: {}", e))?;
+        let engine = (slot.engine.dims().is_some()).then(|| slot.engine.as_ref());
+        state
+            .db
+            .kb_search_hybrid(engine, q, limit.unwrap_or(KB_SEARCH_DEFAULT_LIMIT).min(KB_SEARCH_MAX_LIMIT))
+    };
+    result.map_err(|e| e.to_string())
 }
 
 /// 索引统计（设置页/角标——含脏源/失败计数，索引失败不静默）。

app/src-tauri/src/commands_kb_discovery.rs

@@ -28,9 +28,16 @@ pub fn kb_discovery_suggest(
         return Err("相关素材建议未开启（设置 → 学习库 → 相关素材建议开关；默认关——本地检索本身不受影响）".to_string());
     }
     drop(flags);
-    state
-        .db
-        .kb_discovery_suggest(concept_id)
+    // REQ-259：证据候选走混合检索（锁与 db 调用同作用域——借用不逃逸）
+    let result = {
+        let slot = state
+            .embedding_slot
+            .lock()
+            .map_err(|e| format!("embedding 引擎锁中毒: {}", e))?;
+        let engine = (slot.engine.dims().is_some()).then(|| slot.engine.as_ref());
+        state.db.kb_discovery_suggest_hybrid(engine, concept_id)
+    };
+    result
         .map_err(|e| e.to_string())?
         .ok_or_else(|| "概念不存在（可能已删除或不在当前体系）".to_string())
 }

app/src-tauri/src/kb_discovery.rs

@@ -50,12 +50,23 @@ pub struct DiscoveryResult {
 }
 
 impl Db {
-    /// 概念发现建议（只读编排；概念不存在 → None——命令层映射"概念不存在"）。
+    /// 概念发现建议（FTS-only 等价入口——仅测试保留；生产走 *_hybrid）。
+    #[cfg(test)]
+    pub fn kb_discovery_suggest(&self, concept_id: i64) -> Result<Option<DiscoveryResult>> {
+        self.kb_discovery_suggest_hybrid(None, concept_id)
+    }
+
+    /// 概念发现建议（REQ-259：engine=Some 时证据候选走混合检索 RRF 合流——
+    /// 引擎不可用由检索层自决降级；相似概念提示仍按名称/词法重叠规则）。
     ///
     /// @ai-context: 检索只读派生索引 kb_*；排除集 = 该概念在 knowledge_links
     ///              已引用的 note/fragment target（引用通道唯一入口且概念链
     ///              只落在自身体系内，无需 system 维度二次过滤）。
-    pub fn kb_discovery_suggest(&self, concept_id: i64) -> Result<Option<DiscoveryResult>> {
+    pub fn kb_discovery_suggest_hybrid(
+        &self,
+        engine: Option<&dyn crate::kb_embed::EmbeddingEngine>,
+        concept_id: i64,
+    ) -> Result<Option<DiscoveryResult>> {
         // ① 概念取回（查询面 name/essence + 排除集归属体系）
         let concept = self.with_conn(|conn| {
             Ok(conn
@@ -93,7 +104,7 @@ impl Db {
         if query.chars().count() > DISCOVERY_QUERY_MAX_CHARS {
             query = query.chars().take(DISCOVERY_QUERY_MAX_CHARS).collect();
         }
-        let hits = self.kb_search(&query, DISCOVERY_LIMIT)?;
+        let hits = self.kb_search_hybrid(engine, &query, DISCOVERY_LIMIT)?;
         let evidence: Vec<KbHit> = hits
             .into_iter()
             .filter(|h| {

app/src-tauri/src/kb_embed.rs

@@ -8,9 +8,9 @@
 //! @ai-context: Onnx/Ollama 具体引擎后续模块实现（OnnxEmbedding 需 ort + 模型
 //!              文件 + BERT 分词——模型分发复用 model_registry）；本模块红线：
 //!              引擎产物只是派生索引材料，绝不写结构层（人工裁决闸门铁律）。
-//! 注意：向量编解码与 cosine top-K 的检索合流接线（kb_search 混合 RRF /
-//! reindex 回填）落地前尚未被生产路径引用——dead_code 临时豁免，混合检索
-//! 接线轮必须移除本属性（TODO REQ-259）；引擎槽/契约/Noop 已被命令层引用。
+//! 注意：向量写入侧（encode_embedding + META_* 键）待 reindex 回填轮接线——
+//! 读侧（decode/cosine/META_DIM）已被 kb_search_semantic 引用；dead_code 临时
+//! 豁免缩小至写入侧，reindex 回填轮移除本属性（TODO REQ-259）。
 #![allow(dead_code)]
 
 use std::error::Error;

app/src-tauri/src/kb_search.rs

@@ -15,7 +15,9 @@ use rusqlite::Connection;
 
 use crate::db::Db;
 use crate::error::Result;
+use crate::kb_embed::EmbeddingEngine;
 use crate::kb_fts::{build_snippet, like_pattern, plan_query};
+use crate::kb_search_semantic::semantic_merge;
 
 /// 默认/上限命中数（命令层 clamp——防超大 payload）。
 pub const KB_SEARCH_DEFAULT_LIMIT: usize = 10;
@@ -46,6 +48,7 @@ pub struct KbHit {
 }
 
 /// 查询行（snippet 后处理前置结构）。
+#[derive(Clone)]
 struct HitRow {
     chunk_id: i64,
     source_kind: String,
@@ -83,13 +86,24 @@ impl Db {
         })
     }
 
-    /// 全库混合检索（FTS-only 现状；embedding 就绪后本签名不变——融合在
-    /// 本层内部演化，调用方零感知）。
-    ///
-    /// @ai-context: 语义：空查询/全停用词 → 空列表（"库内未找到"诚实口径由
-    ///              命令层措辞）；FTS 语法意外（tokenizer 拒绝奇形 token）
-    ///              → 降级整句 LIKE，检索不因单个查询语法被击穿。
+    /// 全库混合检索 FTS-only 等价入口（仅测试保留——生产走 *_hybrid）。
+    #[cfg(test)]
     pub fn kb_search(&self, query: &str, limit: usize) -> Result<Vec<KbHit>> {
+        self.kb_search_hybrid(None, query, limit)
+    }
+
+    /// 混合检索入口（REQ-259）：调用方持引擎时传 Some（命令层经状态槽取）。
+    ///
+    /// @ai-context: 融合口径（设计 §5.4）：FTS 候选（保词法精度）∪ 向量余弦
+    ///              top-K（保语义召回）→ rrf_merge（k=60）→ limit 截断；向量
+    ///              仅当 kb_meta.embedding_dim 与引擎 dim 一致时参与（模型更换
+    ///              未重建 → 降级 + 日志提示重建，不产出维度错乱结果）。
+    pub fn kb_search_hybrid(
+        &self,
+        engine: Option<&dyn EmbeddingEngine>,
+        query: &str,
+        limit: usize,
+    ) -> Result<Vec<KbHit>> {
         let limit = limit.clamp(1, KB_SEARCH_MAX_LIMIT);
         let plan = plan_query(query);
         if plan.fts.is_none() && plan.like_terms.is_empty() {
@@ -128,6 +142,38 @@ impl Db {
                 },
                 None => like_hits(conn, &plan.like_terms, limit)?,
             };
+            // 语义合流（可选）：向量候选 + RRF 融合（任何失败/不一致 → 降级直通）
+            let hybrid = if let Some(eng) = engine {
+                let fts_ids: Vec<i64> = rows.iter().map(|r| r.chunk_id).collect();
+                semantic_merge(conn, eng, query, &fts_ids, limit)?
+            } else {
+                None
+            };
+            if let Some((merged, used_semantic)) = hybrid {
+                let merged_ids: Vec<i64> = merged;
+                // 补齐向量独有命中（FTS 未召回但语义召回的 chunk 行）
+                let have: std::collections::HashSet<i64> =
+                    rows.iter().map(|r| r.chunk_id).collect();
+                let missing: Vec<i64> = merged_ids
+                    .iter()
+                    .copied()
+                    .filter(|id| !have.contains(id))
+                    .collect();
+                if !missing.is_empty() {
+                    rows.extend(rows_by_ids(conn, &missing)?);
+                }
+                let by_id: std::collections::HashMap<i64, HitRow> =
+                    rows.into_iter().map(|r| (r.chunk_id, r)).collect();
+                rows = merged_ids
+                    .iter()
+                    .filter_map(|id| by_id.get(id).cloned())
+                    .collect();
+                if used_semantic {
+                    for r in rows.iter_mut() {
+                        r.score_kind = "rrf".to_string();
+                    }
+                }
+            }
             // limit 契约统一收口（fts 候选按 8× 放大取回——过滤后必须裁回；
             // 审查 H1：此前仅在 like 过滤分支内截断，fts-only 常态超发 8 倍）
             rows.truncate(limit);
@@ -150,6 +196,26 @@ impl Db {
     }
 }
 
+/// 按 id 列表批量取命中行（语义独有候选补齐——HIT_COLUMNS 同口径）。
+fn rows_by_ids(conn: &Connection, ids: &[i64]) -> Result<Vec<HitRow>> {
+    if ids.is_empty() {
+        return Ok(Vec::new());
+    }
+    let placeholders = (0..ids.len()).map(|_| "?").collect::<Vec<_>>().join(",");
+    let sql = format!(
+        "SELECT {} FROM kb_chunks c {} WHERE c.id IN ({})",
+        HIT_COLUMNS, HIT_JOINS, placeholders
+    );
+    let ids_vec: Vec<&dyn rusqlite::ToSql> = ids.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
+    let mut stmt = conn.prepare(&sql)?;
+    let hit_rows = stmt
+        .query_map(rusqlite::params_from_iter(ids_vec.iter().copied()), map_hit_row)?
+        .collect::<rusqlite::Result<Vec<_>>>()?;
+    let mut rows = hit_rows;
+    rows.iter_mut().for_each(|r| r.score_kind = "rrf".to_string());
+    Ok(rows)
+}
+
 /// 命中列（三通道共用；c.id 恒有——fts 通道经影子表 join 原 chunk 行）。
 const HIT_COLUMNS: &str = "c.id, c.source_kind, c.note_id, c.fragment_id,
     n.title, g.name, c.heading, c.text";

app/src-tauri/src/kb_search_semantic.rs

@@ -0,0 +1,63 @@
+//! kb 检索的语义合流模块（REQ-259，v0.19.5；kb_search.rs 行数拆分）。
+//!
+//! @ai-context: 引擎不可达（Noop/推理失败/dim 与库内回填不符）时一律返回 None
+//!              ——调用方 FTS 直通，检索可用性红线不因语义层被击穿；模型更换
+//!              未重建时降级并打日志提示（不产出维度错乱结果）。
+//! @ai-context: 全库向量线扫在内存解码后逐条余弦（数千 chunk × 512 维毫秒级）
+//!              ——量级未到向量索引门槛（设计 §六 YAGNI 记录）。
+
+use rusqlite::{params, Connection};
+
+use crate::kb_embed::{cosine_top_k, decode_embedding, EmbeddingEngine, META_DIM};
+use crate::kb_fts::rrf_merge;
+
+/// 语义合流：查询嵌入 → 全库已嵌向量余弦 top-K → 与词法候选 RRF 融合。
+///
+/// 返回 (merged_ids, used_semantic)；语义不可用/不一致 → Ok(None)。
+pub(crate) fn semantic_merge(
+    conn: &Connection,
+    engine: &dyn EmbeddingEngine,
+    query: &str,
+    fts_ids: &[i64],
+    limit: usize,
+) -> rusqlite::Result<Option<(Vec<i64>, bool)>> {
+    let Some(dim) = engine.dims() else {
+        return Ok(None);
+    };
+    // 引擎 dim 必须与库内回填 dim 一致（模型更换未重建 → 降级并提示重建）
+    // 行缺失=从未回填（None）；行存在但值 NULL 也读为 None——两种均按未回填
+    let stored_dim: Option<i64> = {
+        let mut stmt = conn.prepare("SELECT value FROM kb_meta WHERE key = ?1")?;
+        let mut rows = stmt.query_map(params![META_DIM], |r| r.get::<_, Option<i64>>(0))?;
+        match rows.next() {
+            Some(Ok(v)) => v,
+            Some(Err(e)) => return Err(e),
+            None => None,
+        }
+    };
+    if stored_dim.is_some_and(|d| d as usize != dim) {
+        eprintln!("[kb-search] embedding dim 不匹配（库={stored_dim:?} 引擎={dim}）——降级 FTS-only，请重建索引");
+        return Ok(None);
+    }
+    let Ok(qvec) = engine.embed(&[query.to_string()]) else {
+        return Ok(None); // 引擎推理失败 → 降级（检索可用性红线）
+    };
+    let Some(qvec) = qvec.into_iter().next() else {
+        return Ok(None);
+    };
+    // 全库已嵌向量（只取非 NULL——重嵌中/未嵌行自然缺席）
+    let decoded: Vec<(i64, Vec<u8>)> = {
+        let mut stmt = conn.prepare("SELECT id, embedding FROM kb_chunks WHERE embedding IS NOT NULL")?;
+        let rows = stmt.query_map([], |r| Ok((r.get::<_, i64>(0)?, r.get::<_, Vec<u8>>(1)?)))?;
+        rows.collect::<rusqlite::Result<Vec<_>>>()?
+    };
+    let vec_rows = decoded
+        .into_iter()
+        .filter_map(|(id, blob)| decode_embedding(&blob, dim).map(|v| (id, v)));
+    let vec_ids: Vec<i64> = cosine_top_k(&qvec, vec_rows, limit * 8)
+        .into_iter()
+        .map(|(id, _)| id)
+        .collect();
+    let merged = rrf_merge(&[fts_ids.to_vec(), vec_ids], limit);
+    Ok(Some((merged, true)))
+}

app/src-tauri/src/lib.rs

@@ -256,6 +256,8 @@ mod kb_fts;
 mod kb_index;
 mod kb_reindex;
 mod kb_search;
+// REQ-259（v0.19.5）：kb 检索语义合流（RRF 融合独立模块——行数拆分）
+mod kb_search_semantic;
 mod commands_kb;
 // v0.19.1（REQ-260）：学习库问答编排（检索分支分流——纯聊链路零改动）
 mod kb_prompt;