504 lines
18 KiB
Markdown
504 lines
18 KiB
Markdown
# Knowledge Core 与 Retrieval Core：PR 审阅问题与修复复盘
|
||
|
||
> 本文记录 `feat/knowledge-retrieval-core` 合并前后的两轮代码审阅、问题复现、修复过程与工程经验。
|
||
> 它既是团队内部的问题档案，也可作为后续技术文档、课程报告和博客文章的素材底稿。
|
||
|
||
> 2026-08-30 状态补充：本文中的 43 项测试是当时该模块的历史基线，不应替换为当前全仓测试数。相关修复仍有效，当前完整后端回归为 71 项通过，Knowledge/Retrieval 已通过 `notes.*` 与 `rag.search` Tool 接入 Agent Runtime。
|
||
|
||
## 1. 背景
|
||
|
||
Knowledge Core 与 Retrieval Core 建立了项目第一条完整的本地知识检索链路：
|
||
|
||
```text
|
||
Markdown Vault
|
||
→ Markdown Block 解析
|
||
→ SQLite 元数据 / FTS5 / sqlite-vec
|
||
→ FTS 与向量双路召回
|
||
→ RRF 融合与轻量 Reranker
|
||
→ Metadata Filter
|
||
→ Citation 与 Snippet
|
||
```
|
||
|
||
功能分支完成后进行了两轮审阅。第一轮主要检查路径安全、索引一致性、PATCH 语义、检索分页和重建行为；第二轮重点验证第一轮修复是否真正覆盖事务失败和大数据边界。
|
||
|
||
审阅不是只看现有测试是否通过，而是主动构造失败条件，例如：
|
||
|
||
- 让 embedding、向量删除或索引元信息写入主动抛出异常；
|
||
- 创建同目录、同标题的重复笔记；
|
||
- 使用 `../`、Windows 盘符等恶意 folder；
|
||
- 制造超过候选池以及超过 1000 条的 FTS 命中；
|
||
- 比较 `blocks` 与 `vec_blocks` 的 ID 集合；
|
||
- 在接口报错后重新读取 Markdown、SQLite 和向量表，检查是否发生部分提交。
|
||
|
||
## 2. 审阅与修复时间线
|
||
|
||
| 阶段 | 提交 | 内容 |
|
||
| --- | --- | --- |
|
||
| 功能分支首轮修复 | `8771745` | 路径逃逸、更新部分提交、失效向量和基础分页 |
|
||
| 功能分支二次修复 | `6cf531f` | 跨表事务、Metadata Filter、PATCH tags、rebuild 回滚 |
|
||
| 合并提交 | `9348225` | 将 Knowledge/Retrieval Core 合并到 `main` |
|
||
| 合并后第一批修复 | `af8ccb0` | `index_meta` 事务一致性、重复创建冲突 |
|
||
| 合并后第二批修复 | `32f249c` | 删除一致性、FTS 精确过滤与分页 |
|
||
|
||
最终回归测试结果：
|
||
|
||
```text
|
||
43 passed
|
||
```
|
||
|
||
## 3. 问题总览
|
||
|
||
| 编号 | 问题 | 主要风险 | 最终处理 |
|
||
| --- | --- | --- | --- |
|
||
| P-01 | folder 可逃逸 Vault | 任意位置写入或删除 Markdown | 路径标准化，并校验 resolve 后仍位于 Vault |
|
||
| P-02 | VectorStore 的 upsert 实际为 INSERT | 正常 PATCH 主键冲突 | delete-then-insert，实现幂等 upsert |
|
||
| P-03 | 元数据与向量分开提交 | 接口失败但数据库已部分改变 | 共用连接和 SQLite 事务 |
|
||
| P-04 | 更新正文后遗留旧向量 | Top-K 被无效向量占据 | 比较新旧 Block ID，事务内清理失效向量 |
|
||
| P-05 | PATCH tags 语义错误 | 省略字段却清空标签，空数组无法清空 | 严格区分 `None` 与 `[]` |
|
||
| P-06 | 固定候选池破坏过滤与分页 | 合法结果漏召回，total 不准确 | 先扩充候选，最终改为 FTS SQL 侧过滤和分页 |
|
||
| P-07 | rebuild 忽略 scope/note_ids 且先清空 | 请求语义错误，失败留下半成品 | 拒绝未支持范围，扫描在前，备份与失败恢复 |
|
||
| P-08 | `index_meta` 在主事务外写入 | 文件回滚但索引已更新 | 将 `index_meta` 纳入同一事务 |
|
||
| P-09 | POST 同路径静默覆盖 | 原笔记无提示丢失 | 数据库预检 + 文件排他创建 + 409 |
|
||
| P-10 | 删除由三个独立操作组成 | notes、向量和文件互相不一致 | tombstone + SQLite 同事务 + 失败恢复 |
|
||
|
||
## 4. P-01：folder 路径逃逸
|
||
|
||
### 4.1 问题原因
|
||
|
||
最初的笔记路径由下面的逻辑生成：
|
||
|
||
```python
|
||
folder_part = folder.strip().strip("/")
|
||
rel_path = f"{folder_part}/{safe_title}.md"
|
||
absolute_path = vault / rel_path
|
||
```
|
||
|
||
代码只去除了 folder 两端的斜杠，没有处理：
|
||
|
||
- `..` 和 `.` 路径段；
|
||
- Windows 反斜杠；
|
||
- `C:\...` 等盘符路径；
|
||
- NUL 字节；
|
||
- 符号链接或规范化后越过 Vault 的路径。
|
||
|
||
因此 `folder="../outside"` 会使最终路径落到 Vault 之外。
|
||
|
||
### 4.2 后果
|
||
|
||
攻击者或错误的前端输入可以在 Vault 外创建 Markdown。数据库会保存这个越界路径，后续读取和删除接口还会继续访问该文件，风险从“越界写入”扩大为“越界读取和删除”。
|
||
|
||
### 4.3 解决思路
|
||
|
||
路径安全不能只依赖字符串替换，需要同时完成两层校验：
|
||
|
||
1. 输入层拒绝明显非法的路径片段；
|
||
2. 文件系统层对最终路径执行 `resolve()`，确认它仍属于 Vault。
|
||
|
||
### 4.4 最终方案
|
||
|
||
`note_service.py` 新增 `_normalize_folder()` 和安全的 `_abs_path()`：
|
||
|
||
- 同时按 `/` 和 `\` 拆分目录；
|
||
- 拒绝 `.`、`..`、盘符和 NUL；
|
||
- 对 Vault 与目标执行 `resolve()`；
|
||
- 使用 `Path.is_relative_to()` 验证目标未逃逸；
|
||
- 所有读、写、删操作统一经过 `_abs_path()`。
|
||
|
||
回归测试覆盖 `../../outside`、`..\..\etc`、`C:\Windows` 和 `a/../b` 等输入。
|
||
|
||
## 5. P-02 与 P-03：伪 upsert 和索引部分提交
|
||
|
||
### 5.1 问题原因
|
||
|
||
Block ID 根据 `note_id + heading_path + content` 稳定生成。只修改标题或标签时，正文 Block ID 不会改变。
|
||
|
||
最初 `SqliteVecStore.upsert()` 名为 upsert，实际执行的却是普通 INSERT：
|
||
|
||
```sql
|
||
INSERT INTO vec_blocks (block_id, embedding) VALUES (?, ?)
|
||
```
|
||
|
||
同一个 Block 再次写入时会触发 sqlite-vec 主键冲突。同时，元数据和 FTS 已经在另一个事务中提交，向量失败无法回滚前面的修改。
|
||
|
||
### 5.2 后果
|
||
|
||
一次仅修改标题的 PATCH 就可能出现：
|
||
|
||
```text
|
||
HTTP：500
|
||
Markdown：已写入
|
||
notes / blocks / FTS：已更新
|
||
vec_blocks：写入失败
|
||
```
|
||
|
||
调用方看到的是“更新失败”，系统内部却已经改变。这类部分提交比直接失败更危险，因为客户端重试可能继续扩大不一致。
|
||
|
||
### 5.3 解决思路
|
||
|
||
- upsert 必须具备幂等性；
|
||
- notes、blocks、FTS 与 vec_blocks 都在同一个 SQLite 文件内，应共用连接和事务；
|
||
- Repository 和 VectorStore 既要支持独立调用，也要支持加入调用方事务。
|
||
|
||
### 5.4 最终方案
|
||
|
||
VectorStore 的 upsert 改为：
|
||
|
||
```text
|
||
DELETE existing block_id
|
||
→ INSERT new embedding
|
||
```
|
||
|
||
`repository.replace_note_metadata()`、`vector_store.upsert()` 和 `vector_store.delete()` 都可接收外部连接。`index_note()` 打开一个连接和事务，把元数据、FTS、失效向量删除、新向量插入放在同一提交边界中。
|
||
|
||
## 6. P-04：失效向量残留
|
||
|
||
### 6.1 问题原因
|
||
|
||
更新正文后，Repository 会删除旧 Block 并插入新 Block，但早期实现只写入新向量，没有删除内容已经不存在的旧向量。vec0 没有到 blocks 表的外键约束，因此这些向量不会自动级联删除。
|
||
|
||
### 6.2 后果
|
||
|
||
实测一次全文更新后出现：
|
||
|
||
```text
|
||
blocks = 1
|
||
vec_blocks = 2
|
||
```
|
||
|
||
旧向量仍会参加 KNN 排名，但随后无法取得 Block 上下文。反复编辑后，失效向量可能占满 Top-K，使真正有效的结果无法进入候选集。
|
||
|
||
### 6.3 解决思路与方案
|
||
|
||
更新前取得旧 `block_id`，解析后得到新 `block_id`，计算集合差：
|
||
|
||
```text
|
||
stale = old_ids - new_ids
|
||
missing = new_ids - old_ids
|
||
```
|
||
|
||
- 删除 `stale` 对应向量；
|
||
- 只为 `missing` 写入新向量；
|
||
- 未变化 Block 沿用原向量；
|
||
- 整个过程与 Block 替换使用同一事务。
|
||
|
||
测试以集合不变量验证修复：
|
||
|
||
```text
|
||
set(vec_blocks.block_id) == set(blocks.block_id)
|
||
```
|
||
|
||
## 7. P-05：PATCH tags 语义错误
|
||
|
||
### 7.1 问题原因
|
||
|
||
解析器曾使用真值判断：
|
||
|
||
```python
|
||
resolved_tags = list(tags) if tags else parse_frontmatter_tags()
|
||
```
|
||
|
||
但 PATCH 中的 `None` 和 `[]` 含义不同：
|
||
|
||
- `None`：客户端没有提交 tags，应保留原值；
|
||
- `[]`：客户端明确要求清空标签。
|
||
|
||
真值判断把两种状态混为一谈。另外，更新服务直接把 `None` 传给解析器，导致原有 API 标签被 frontmatter 或空数组替换。
|
||
|
||
### 7.2 后果
|
||
|
||
- 仅修改标题也会意外清空标签；
|
||
- 显式提交空数组时，反而可能重新读取 frontmatter 标签，无法清空。
|
||
|
||
### 7.3 最终方案
|
||
|
||
解析器改为判断 `tags is not None`。更新服务根据 PATCH 语义计算有效标签：
|
||
|
||
```python
|
||
effective_tags = record.tags if tags is None else tags
|
||
```
|
||
|
||
回归测试分别覆盖省略、替换和清空三种情况。
|
||
|
||
## 8. P-06：候选池、Metadata Filter 与分页
|
||
|
||
### 8.1 第一阶段问题
|
||
|
||
初版 FTS 和向量召回都固定只取 50 条候选，然后才执行 Metadata Filter 和分页：
|
||
|
||
```text
|
||
Top 50 → Metadata Filter → offset/limit
|
||
```
|
||
|
||
这会产生两个错误：
|
||
|
||
1. 第 51 条以后的页面永远无法访问；
|
||
2. 满足 folder/tag 条件的结果如果排在第 51 条以后，会被错误地过滤掉。
|
||
|
||
实测 60 个匹配 Block 请求 `offset=50` 时，响应为 `total=50, items=[]`。
|
||
|
||
### 8.2 中间修复为什么仍不完整
|
||
|
||
第一轮修复根据 `offset + limit` 扩大候选池，并在有过滤条件时 overscan；FTS 模式则把上限扩大到 1000。
|
||
|
||
这解决了常见的小数据场景，但本质只是把硬边界从 50 移到了 1000。第二轮实测 1010 个匹配 Block，请求 `offset=1000` 时仍得到：
|
||
|
||
```json
|
||
{"total": 1000, "items": []}
|
||
```
|
||
|
||
### 8.3 最终解决思路
|
||
|
||
全文检索分页不应先把所有结果加载到 Python 再切片，应由数据库完成：
|
||
|
||
```text
|
||
FTS MATCH
|
||
+ Metadata WHERE
|
||
→ COUNT(*) 得到精确 total
|
||
→ ORDER BY bm25
|
||
→ LIMIT / OFFSET
|
||
```
|
||
|
||
### 8.4 最终方案
|
||
|
||
Repository 新增 FTS 精确分页查询：
|
||
|
||
- JOIN `blocks` 与 `notes`；
|
||
- folder 和 note_id 使用 SQL `IN`；
|
||
- tags 使用 `json_each()`；
|
||
- 时间范围使用 `julianday()` 比较；
|
||
- 相同过滤条件分别用于 COUNT 和数据页查询；
|
||
- `RetrievalEngine` 为纯 FTS 模式使用专用查询路径。
|
||
|
||
最终测试确认 1010 个匹配 Block 在 `offset=1000, limit=10` 时返回：
|
||
|
||
```text
|
||
total = 1010
|
||
items = 10
|
||
```
|
||
|
||
向量与 Hybrid 模式仍属于 Top-K 近邻召回，其 `total` 表示候选集数量，不等价于全文数据库的全局命中数。这是检索模型本身的语义差异，需要在接口文档和前端展示中保持明确。
|
||
|
||
## 9. P-07：rebuild 请求语义与失败恢复
|
||
|
||
### 9.1 问题原因
|
||
|
||
接口模型公开了 `scope=all/notes/vectors` 和 `note_ids`，但最初所有请求都会无条件清空全部索引并全量扫描 Vault。旧索引在扫描和 embedding 之前就被删除，中途失败会留下空库或半成品。
|
||
|
||
### 9.2 后果
|
||
|
||
- 调用方请求只重建向量，实际却清空 notes 和 FTS；
|
||
- 指定 note_ids 仍触发全量重建；
|
||
- 单个损坏文件或 embedding 异常即可破坏原本可用的索引。
|
||
|
||
### 9.3 最终方案
|
||
|
||
当前 MVP 明确只支持全量重建：
|
||
|
||
- 非 `scope="all"` 或非空 `note_ids` 返回 `400 UNSUPPORTED_SCOPE`；
|
||
- 清理旧索引前先把 Vault 文件全部读取到内存，读取失败不影响旧索引；
|
||
- 重建前备份 SQLite 文件；
|
||
- 中途失败时恢复备份，并记录 failed Job；
|
||
- 成功或失败后清理临时备份。
|
||
|
||
`force` 当前仍是预留字段，没有行为差异。后续实现增量重建时，应一起明确它的契约，避免再次出现“参数被接受但没有效果”。
|
||
|
||
## 10. P-08：`index_meta` 位于主事务之外
|
||
|
||
### 10.1 问题如何被复审发现
|
||
|
||
第一轮修复已经把 notes、blocks、FTS 和向量放进同一事务，看起来解决了原子性问题。但 `index_meta` 仍在该事务提交后，通过新连接单独写入。
|
||
|
||
通过故障注入让 `set_index_meta()` 抛出异常后发现：
|
||
|
||
```text
|
||
主索引事务：已经提交新内容
|
||
index_meta：失败
|
||
update_note：捕获异常，恢复旧 Markdown
|
||
最终结果：Markdown 是旧内容，索引是新内容
|
||
```
|
||
|
||
这说明“把主要写操作放进事务”还不够，只要事务外仍有能够决定接口成功或失败的步骤，部分提交依然存在。
|
||
|
||
### 10.2 最终方案
|
||
|
||
`repository.set_index_meta()` 增加可选连接参数：
|
||
|
||
- 独立调用时自行开连接、开事务并提交；
|
||
- 收到外部连接时加入已有事务，不自行提交和关闭。
|
||
|
||
`index_note()` 在主事务退出前写入 `index_meta`。现在任何一步失败都会回滚全部 SQLite 修改，外层再恢复 Markdown，从而保持文件与索引一致。
|
||
|
||
## 11. P-09：POST 同路径静默覆盖
|
||
|
||
### 11.1 问题原因
|
||
|
||
笔记的相对路径和 note_id 都由 `folder + title` 确定。创建接口写文件前没有检查同路径资源是否存在，Repository 又使用 `ON CONFLICT DO UPDATE`，因此第二次 POST 会被当作更新执行。
|
||
|
||
### 11.2 后果
|
||
|
||
连续创建同目录、同标题笔记时：
|
||
|
||
```text
|
||
第一次：original
|
||
第二次：replacement
|
||
note_id：相同
|
||
最终正文：replacement
|
||
```
|
||
|
||
原笔记没有任何冲突提示就被覆盖。更严重的是，早期失败回滚逻辑会在第二次索引失败时删除目标文件，连第一篇原文也一并丢失。
|
||
|
||
### 11.3 解决思路与方案
|
||
|
||
创建和更新必须具有不同语义：
|
||
|
||
- POST 只创建新资源，冲突时返回 409；
|
||
- PATCH 才允许修改已有资源。
|
||
|
||
最终实现包含双重保护：
|
||
|
||
1. 根据稳定 note_id 查询 SQLite，存在则返回 `409 RESOURCE_CONFLICT`；
|
||
2. 使用 `Path.open("x")` 排他创建文件，处理数据库检查与文件写入之间的并发竞争。
|
||
|
||
只有本次请求确实创建了新文件，后续索引失败时才会删除它，因此不会误删旧文件。
|
||
|
||
## 12. P-10：删除操作部分提交
|
||
|
||
### 12.1 问题原因
|
||
|
||
早期删除流程是三个独立步骤：
|
||
|
||
```text
|
||
提交 notes / blocks / FTS 删除
|
||
→ 单独提交向量删除
|
||
→ 删除 Markdown
|
||
```
|
||
|
||
如果第二步向量删除失败，第一步无法回滚，第三步不会执行。
|
||
|
||
### 12.2 后果
|
||
|
||
故障注入后的状态为：
|
||
|
||
```text
|
||
notes：已删除
|
||
blocks / FTS：已删除
|
||
vec_blocks：仍存在
|
||
Markdown：仍存在
|
||
HTTP：失败
|
||
```
|
||
|
||
系统无法通过普通读取接口找到笔记，但文件和孤立向量仍在，调用方也无法判断是否应该重试。
|
||
|
||
### 12.3 解决思路
|
||
|
||
SQLite 内的四类数据可以使用同一事务；Markdown 文件不能加入 SQLite 事务，因此需要补偿事务。直接先删文件不利于恢复，先提交数据库又会在文件删除失败时不一致，所以采用可恢复的 tombstone：
|
||
|
||
```text
|
||
Markdown 原子 rename 为非 .md tombstone
|
||
→ 同一 SQLite 事务删除 metadata / blocks / FTS / vectors
|
||
→ 成功：删除 tombstone
|
||
→ 失败：rollback SQLite，并把 tombstone rename 回原路径
|
||
```
|
||
|
||
### 12.4 最终方案
|
||
|
||
- `repository.delete_note()` 和 `vector_store.delete()` 都支持外部连接；
|
||
- `note_service.delete_note()` 负责建立统一事务；
|
||
- 原文件先移动为同目录下带随机 UUID 的 `.deleting` 文件；
|
||
- SQLite 失败时恢复原文件；
|
||
- SQLite 成功后清理 tombstone；
|
||
- tombstone 不以 `.md` 结尾，因此即使最终清理因系统原因失败，也不会被 Vault 扫描器重新索引。
|
||
|
||
回归测试通过让向量删除主动失败，确认 notes、Block、向量和 Markdown 全部恢复到删除前状态。
|
||
|
||
## 13. 测试策略
|
||
|
||
这次审阅新增的测试不只验证成功路径，还验证跨层不变量和失败恢复。
|
||
|
||
### 13.1 路径安全
|
||
|
||
- `test_create_note_rejects_path_traversal`
|
||
|
||
### 13.2 写入与回滚
|
||
|
||
- `test_update_note_rolls_back_file_on_index_error`
|
||
- `test_update_note_rolls_back_index_when_index_meta_fails`
|
||
- `test_create_note_rejects_existing_path_without_overwrite`
|
||
- `test_delete_note_rolls_back_when_vector_delete_fails`
|
||
|
||
### 13.3 向量一致性
|
||
|
||
- `test_update_removes_stale_vectors`
|
||
- `test_patch_partial_content_no_orphan_vectors`
|
||
|
||
### 13.4 PATCH 契约
|
||
|
||
- `test_patch_tags_semantics`
|
||
|
||
### 13.5 检索过滤与分页
|
||
|
||
- `test_search_pagination_total_reflects_all_matches`
|
||
- `test_fts_pagination_is_not_truncated_at_one_thousand`
|
||
- `test_fts_metadata_filter_recalls_beyond_candidate_pool`
|
||
|
||
### 13.6 rebuild
|
||
|
||
- `test_rebuild_rejects_unsupported_scope_and_note_ids`
|
||
- `test_rebuild_failure_restores_old_index`
|
||
|
||
测试运行方式：
|
||
|
||
```powershell
|
||
cd backend
|
||
uv run pytest -q
|
||
```
|
||
|
||
## 14. 可复用的工程经验
|
||
|
||
### 14.1 函数名不能替代语义验证
|
||
|
||
一个函数叫 `upsert`，不代表它真的具备幂等更新能力。审阅时应继续检查底层 SQL、唯一键行为和重复调用结果。
|
||
|
||
### 14.2 原子性要覆盖完整的成功判定路径
|
||
|
||
只把主要数据表放进事务还不够。日志、索引版本、元信息等后续步骤如果仍会让接口失败，也必须加入事务，或者被设计为不影响主操作结果。
|
||
|
||
### 14.3 文件系统与数据库需要补偿事务
|
||
|
||
SQLite 可以回滚，文件系统通常不能参与数据库事务。跨两种存储介质时，可采用临时文件、原子 rename、tombstone 和失败恢复构造可补偿流程。
|
||
|
||
### 14.4 PATCH 必须区分“未提供”和“显式为空”
|
||
|
||
`None`、空列表、空字符串和缺失字段经常具有不同业务含义。使用简单真值判断容易破坏部分更新语义。
|
||
|
||
### 14.5 固定扩大候选池不是分页方案
|
||
|
||
把上限从 50 调到 1000 只能推迟问题。只要 API 允许更大的 offset，硬截断就会再次暴露。能由数据库完成的过滤、计数和分页，应尽量下推到数据库。
|
||
|
||
### 14.6 回归测试应验证失败后的状态
|
||
|
||
只断言“抛出了异常”无法证明回滚正确。异常后还应重新读取每个存储层，检查文件、元数据、FTS 和向量是否满足不变量。
|
||
|
||
## 15. 后续可以继续改进的方向
|
||
|
||
- 为 rebuild 使用临时数据库或 SQLite Backup API，成功后原子切换，替代直接复制数据库文件；
|
||
- 明确并实现 `force`、`scope` 和 `note_ids` 的完整语义；
|
||
- 为 tombstone 增加启动时清理或恢复机制；
|
||
- 对并发创建、更新、删除增加集成测试；
|
||
- 明确 FTS 的精确 total 与 Vector/Hybrid 候选 total 在 API 层的差异；
|
||
- 建立更大规模的检索 Benchmark，持续观察召回率、延迟和索引体积；
|
||
- 在服务层引入结构化日志，记录回滚、tombstone 清理失败和 rebuild 恢复结果。
|
||
|
||
## 16. 相关文件
|
||
|
||
```text
|
||
backend/app/services/note_service.py Note CRUD、文件补偿与索引编排
|
||
backend/app/repository.py SQLite 元数据、FTS 查询与事务接入
|
||
backend/app/retrieval/vectorstore.py sqlite-vec 幂等写入和删除
|
||
backend/app/retrieval/engine.py FTS/Vector/Hybrid 检索编排
|
||
backend/app/services/index_service.py 全量重建与失败恢复
|
||
backend/app/knowledge/parser.py Block ID 与 tags 解析语义
|
||
backend/tests/test_retrieval.py 审阅回归测试
|
||
docs/development/Knowledge与Retrieval-Core开发说明.md 模块开发说明
|
||
```
|