工作区后台索引与保存开发说明

本文档用于团队开发和联调，说明 Web Workspace 的打开、保存与后台向量更新边界。

更新日期：2026-09-06。代码基线：a5c44c4，已随 PR #31 合并到 main。

当前实现

打开知识库和保存正文不再等待 Embedding 推理。Markdown 是正文载体；SQLite 元数据和 FTS 可先使用，向量结果随后更新。这里的后台任务是 AI Core 进程内的 asyncio 任务，不是独立队列服务，也不是 Tauri 后台服务。

操作	请求完成前	后台阶段
打开 Vault	校验配置路径；路径集合变化时登记新文件、删除失效记录并返回真实文件树	标记需要更新时自动全量计算向量
HTTP PATCH 保存笔记	写正文、解析元数据、更新 FTS、清理旧向量并持久化待处理标记	按笔记计算向量，核对版本后写入
手动全量重建	HTTP 请求仍等待全量重建结果	推理期间不持有 Vault 写锁，提交阶段原子替换

note_service.update_note 的 defer_vectors 默认仍为 False；HTTP PATCH 路由显式传入 True。创建、移动及其他内部调用不能据此宣称已经全部后台化。

文件	职责
`backend/app/services/workspace_service.py`	文件登记、打开工作区、触发后台任务
`backend/app/services/note_service.py`	正文保存、即时元数据与全文索引
`backend/app/services/index_service.py`	后台任务去重、全量与单笔记向量更新、状态与关闭
`backend/app/services/coordination.py`	Vault 写入互斥
`frontend/src/features/vault/VaultEntry.vue`	等待提示、超时错误及重试
`frontend/src/stores/editor.ts`	保存快照、状态及连续输入补存
`frontend/src/components/common/AppShell.vue`	每轮请求结束后间隔 5 秒刷新索引状态

文件登记和保存的待处理标记与索引写入使用同一 SQLite 事务。
workspace_vectors_pending=1 表示工作区全量向量需要更新；note_vectors_pending:<note_id>=1 表示该笔记有待处理工作。
模型推理在写锁外执行；提交前重新核对磁盘快照或笔记记录。版本不一致时不写入旧结果，后台循环重新处理。
保存接口成功后，“已保存”代表正文和全文索引已写入，不代表向量已经就绪。向量不可用期间，语义检索可能尚未覆盖刚保存的内容。
模型失败保留待处理标记，正文不会因后台失败回滚。重新打开 Vault 可再次调度；不是保证持续重试的生产任务队列。
关闭后端会取消进程内后台任务；持久化标记保留。任务详情、活动任务 ID 和错误信息仍主要保存在内存，重启后不会保留完整任务历史。
前端保存期间继续输入时，当前请求完成后仍保持 dirty，并安排后续自动保存；落盘失败显示 save_failed。

GET /api/index/status 新增 vector_refresh_required: boolean，表示仍有待处理标记。它与 status 一起使用：失败、等待和运行中都可能需要向量更新。pending_jobs 不是百分比或剩余笔记数。

打开 Vault 请求超时为 15 秒；诊断和状态请求为 10 秒。超时表示前端停止等待，不保证服务端操作已经取消，不应因此认定保存成功或失败。

在 backend 目录执行：

uv run pytest tests/test_workspace.py tests/test_workspace_background.py -q -p no:cacheprovider

在 frontend 目录执行：

pnpm exec vitest run src/services/apiClient.spec.ts src/stores/editorSave.spec.ts

回归覆盖：模型等待期间仍可打开工作区和创建目录、重复打开去重、快照变化重算、连续保存保留最新标题和标签、模型失败不回滚正文、重新打开恢复处理、请求超时及自动补存。

手动联调请使用测试 Vault：新增 Markdown 后打开；计算期间修改并保存两次；重新打开确认最后内容；在隔离配置中模拟模型不可用，核对正文保留与索引错误分别显示。

路径登记按磁盘与数据库的路径集合判断变化，不等同于完整外部文件监听。多进程后台调度、生产任务队列、完整失败历史和原生文件监听属于后续工作。不要把当前进程内互斥用于推断多实例安全性。