Struct VecDb 

pub struct VecDb { /* private fields */ }

vec0 虚表封装：向量持久化 + 带阈值过滤的 KNN 查询

职责边界：只做 vec0 虚表的建表/增删查，不含 embedding 生成 （EmbeddingEngine 在 SemanticEngine 层调用）与 CodeNode 业务逻辑 （node_json 的序列化由调用方负责）。单库单连接（与 SearchStore 同 进程契约：WAL + busy_timeout）。

Implementations

impl VecDb

pub fn open(path: impl AsRef<Path>) -> Result<Self>

打开或创建向量数据库（注册扩展 + 建表延迟到首次插入）

pub fn table_dimension(&self) -> Result<Option<usize>>

当前虚表的向量维度（表不存在返回 None）

pub fn insert_batch(&self, items: &[(String, String, Vec<f32>)]) -> Result<()>

批量插入向量（node_json 由调用方序列化）

首次插入时按首个向量维度建表。file_path 归一化与 FTS5 表同规则 （跨平台路径键统一，删除/过滤同基准）。

pub fn knn( &self, query_json: &str, limit: usize, max_distance: f64, ) -> Result<Vec<KnnRow>>

带阈值过滤的 KNN 查询：返回余弦距离 ≤ max_distance 的全部行

vec0 的 KNN 是 LIMIT 截断，无法在 SQL 侧表达距离谓词 （knn_match 是唯一 distance 约束，见 sqlite-vec best_index 实现）， 因此用循环扩样保证阈值语义正确：

• 从 limit 起步采样，若返回行数 == 采样数且最后一行仍 ≤ 阈值， 说明可能有更多候选被截断 → 翻倍重查；
• 直到返回行数 < 采样数（表尽）或最后一行 > 阈值（边界内已全） 或达到 MAX_KNN_CANDIDATES 上限。

该策略与旧实现（全量加载 + 逐条余弦 + 过滤）在阈值语义上 完全等价，且正常场景（阈值过滤后结果远小于 limit）只查一次。 表不存在时返回空（等价于空索引）。

扩样重查的去重：翻倍 LIMIT 后，前一次已取过的行会再次返回 （KNN 结果按距离稳定排序），按 node_json 去重合并，保证 返回行数 = 阈值内候选数（不因扩样重复）。

pub fn remove_by_file(&self, file_path: &str) -> Result<usize>

删除指定文件路径关联的所有向量（file_path 键与插入同基准）

pub fn clear(&self) -> Result<()>

清空所有向量

pub fn entry_count(&self) -> Result<usize>

当前向量条数（表不存在视为 0）