perf: persist model-isolated sqlite-vec indexes and index new notes incrementally

docs/README.md

@@ -37,6 +37,7 @@
 - [前端构建分块优化开发说明](development/前端构建分块优化开发说明.md)
 
 - [工作区后台索引与保存开发说明](development/工作区后台索引与保存开发说明.md)
+- [模型隔离向量索引与增量登记](development/模型隔离向量索引与增量登记.md)
 - [Mermaid 预览与缩放开发说明](development/Mermaid预览与缩放开发说明.md)
 - [扩展安装持久化与社区包开发说明](development/扩展安装持久化与社区包开发说明.md)
 - [模型上下文管理](development/模型上下文管理.md)

docs/contracts/后端接口契约-开发版.md

@@ -202,6 +202,7 @@ RunCancelled
 ## 2026-09-06：后台索引补充
 
 - `POST /api/workspace/open` 返回可使用的 WorkspaceSnapshot，不等待向量推理。
+- 外部新增文件登记后按笔记持久化后台向量任务，不再因此设置全库重建标记；已存在的全库待处理标记仍继续执行。模型空间与维度的持久化 sqlite-vec 索引从已有向量转换，接口响应结构不变。实现与性能验证见 [模型隔离向量索引与增量登记](../development/模型隔离向量索引与增量登记.md)。
 - `PATCH /api/notes/{note_id}` 成功代表正文、元数据和 FTS 已保存；后台向量失败不撤销这次保存。
 - `GET /api/index/status` 新增 `vector_refresh_required: boolean`，表示工作区或笔记存在向量待处理标记。该字段不是进度百分比；任务失败时也可为 true。
 - `pending_jobs` 返回真实未完成索引任务数（包含运行中），不再固定为 0。全库待重建或运行中的全量重建计一个任务；逐笔记刷新按待处理标记计数。`running_jobs` 返回当前运行数。失败后保留的待重建标记仍计入未完成数。

docs/development/performance/2026-09-06-sqlite-vec-search.json

@@ -0,0 +1,29 @@
+{
+  "blocks": 4000,
+  "dimensions": 384,
+  "top_k": 20,
+  "migration_ms": 1329.5076999929734,
+  "same_top_k": true,
+  "measurements": {
+    "python_json_scan": {
+      "median_ms": 1289.638800022658,
+      "samples_ms": [
+        1289.638800022658,
+        1238.6701999930665,
+        1115.6752999813762,
+        1436.7559000093024,
+        1833.9683999947738
+      ]
+    },
+    "sqlite_vec": {
+      "median_ms": 19.673499977216125,
+      "samples_ms": [
+        29.709700000239536,
+        17.876600002637133,
+        35.13619999284856,
+        19.673499977216125,
+        18.28439999371767
+      ]
+    }
+  }
+}

docs/development/模型隔离向量索引与增量登记.md

@@ -0,0 +1,24 @@
+# 模型隔离向量索引与增量登记
+
+## 目标与实现
+
+向量仍保存在本地 `app.db`，重启复用。`routed_block_vectors` 主键升级为 `(space_id, dimensions, block_id)`，同维度不同模型、同模型不同维度均独立存储。每个空间建立以模型标识和维度的 SHA-256 命名的 `vec0` 虚拟表，动态表名不包含厂商输入。
+
+首次访问旧空间时，在事务中将已有 JSON 向量转换为归一化 float32 索引，不重新调用 Embedding 模型。随后检索由 sqlite-vec 执行精确 KNN，避免每次在 Python 中解码所有向量、计算点积。该实现是精确搜索，不是 ANN；依据归一化向量的欧氏距离换算余弦分数。参见 [sqlite-vec KNN 文档](https://alexgarcia.xyz/sqlite-vec/features/knn.html)。
+
+覆盖检查和 KNN 使用同一事务。向量更新、删除及笔记级联删除通过触发器清理派生索引，新向量与原始向量在同一保存点写入。索引缺失或不完整仍明确失败/按已有策略回退，不混入其他模型结果。本地专用笔记按 `local_only` 元数据过滤，不同空间的结果继续使用 RRF 融合。
+
+数据库搜索及旧空间转换在线程中运行，不阻塞异步服务事件循环。首次转换仍会占用 SQLite 写事务；超大库应进一步评估迁移耗时。新增空间保留原空间索引，暂不自动清理历史空间。
+
+## 外部新增文件
+
+文件树检测到新增 Markdown 后先登记元数据与全文索引，然后为每条新笔记持久化 `note_vectors_pending:<note_id>`，逐笔记在后台计算。不再因新增文件设置全库重建标记；已存在的全库待处理标记仍保留，以免跳过之前未完成的任务。
+
+新增文件在推理期间再次变化时校验快照并重试，只同步该笔记。写入失败保留待处理标记。手动“重建全部”仍执行全库重建，正常重新打开已完成的工作区不再入队。
+
+## 验证
+
+- 隔离数据库运行后端全套测试：637 项通过；最终覆盖检查优化另运行检索及后台工作区回归，96 项通过。
+- 新增用例验证同模型不同维度并存、重新连接复用且查询不解码向量 JSON、旧表迁移只计算查询向量，以及外部新增文件不触发全量重建。
+- `backend/scripts/vector-index-benchmark.py` 使用临时数据库、固定随机种子，比较 4000 条 384 维向量的 top-20，旧新路径结果顺序一致。5 次采样中位数：Python 扫描约 1289.64 ms，sqlite-vec 约 19.67 ms；首次转换约 1329.51 ms。该结果只测向量检索，不包含查询 Embedding、重排与 HTTP 耗时，不代表端到端加速比例。
+- 原始结果：[2026-09-06-sqlite-vec-search.json](performance/2026-09-06-sqlite-vec-search.json)。基准可用后端虚拟环境 Python 直接执行上述脚本，不读写用户 Vault。