68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
# 工作区后台索引与保存开发说明
|
||
|
||
> 本文档用于团队开发和联调，说明 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 目录执行：
|
||
|
||
```powershell
|
||
uv run pytest tests/test_workspace.py tests/test_workspace_background.py -q -p no:cacheprovider
|
||
```
|
||
|
||
在 frontend 目录执行：
|
||
|
||
```powershell
|
||
pnpm exec vitest run src/services/apiClient.spec.ts src/stores/editorSave.spec.ts
|
||
```
|
||
|
||
回归覆盖：模型等待期间仍可打开工作区和创建目录、重复打开去重、快照变化重算、连续保存保留最新标题和标签、模型失败不回滚正文、重新打开恢复处理、请求超时及自动补存。
|
||
|
||
手动联调请使用测试 Vault：新增 Markdown 后打开；计算期间修改并保存两次；重新打开确认最后内容；在隔离配置中模拟模型不可用，核对正文保留与索引错误分别显示。
|
||
|
||
## 当前限制
|
||
|
||
路径登记按磁盘与数据库的路径集合判断变化，不等同于完整外部文件监听。多进程后台调度、生产任务队列、完整失败历史和原生文件监听属于后续工作。不要把当前进程内互斥用于推断多实例安全性。
|