# SKILL-VC-001 · 本地语义检索管线

> 让任意文档集合拥有毫秒级中文语义搜索：SQLite + sqlite-vec 嵌入式索引 + bge-small-zh 本地编码。零外部算力、零数据出域、索引单文件 3MB 级。

## 它解决什么问题

文档多到 grep 不够用：搜"怎么落地"找不到没写这三个字却讲了落地方法的章节。传统方案要么上重型引擎，要么调云端接口（数据出域 + 按量付费）。本管线证明：**一台普通 CPU 机器就能拥有私有语义检索**——真实体系 936 个文档块、3MB 索引、语义命中验收通过。

## 能力构成

- `vec_index.py`：核心库。滑窗分块（400 字/50 重叠）、内容 SHA256 去重（增量天然免费）、vec 虚表近邻检索、来源过滤、库存统计；
- `build_index.py`：建库入口，任意文档目录 → 可检索索引；
- `test_vec_index.py`：五个单元测试（分块/去重/近邻序/来源过滤/统计），桩编码器驱动，**不依赖模型下载**，任何环境 42ms 跑完；
- `VERIFY.md`：一页式独立验证指南——机械步骤 + 预期输出原文。

## 设计思想

1. **检索层是增强不是依赖**：降级路径（文件名检索）永远可用；
2. **增量是免费的**：内容指纹做主键，重复入库自动跳过；
3. **备份即拷文件**：SQLite 单文件库，`cp` 就是备份与迁移；
4. **只增不覆盖**：重建落新文件，随时可回退。

## 依赖

`pip install sqlite-vec sentence-transformers`（真模型检索需约 100MB 模型，首次运行自动下载并本地缓存；单测不需要）。