fix knowledge rag docx sidecar locator
This commit is contained in:
lix-2026
+84
-12
@@ -2,7 +2,7 @@
|
||||
|
||||
> 创建时间：2026-06-09
|
||||
>
|
||||
> 当前状态：`process`
|
||||
> 当前状态：`done`
|
||||
>
|
||||
> Owner：07-ai / knowledge-rag / LightRAG native parser / office-preview
|
||||
>
|
||||
@@ -118,15 +118,86 @@ PDF 对照样本：
|
||||
|
||||
MinerU parse 已能输出 `positions.type=bbox` 与 page anchor，PDF 当前先消费现有 bbox，不作为 7-56 首要补丁对象。
|
||||
|
||||
## 5. 后续收口
|
||||
## 5. 完成实现
|
||||
|
||||
- MNote `knowledge_rag` mapper 应优先消费 provider sidecar 中的 `blockid/positions`，逐步退役 query-time quote 反查 block。
|
||||
- office-preview 应优先使用 `paraid.anchor` 或 paraid range 定位；没有可用 paraId 时再用 `text_fingerprint/displayQuote` 做降级匹配。
|
||||
2026-06-09 已完成 DOCX 查询与点击定位主链收口。
|
||||
|
||||
### 5.1 LightRAG provider 合同
|
||||
|
||||
- `/query/search` 保持关键词检索入口，`SearchRequest.query` 最小长度为 2。
|
||||
- `/query/search` 新增 `include_sidecar=true`，结果 chunk 返回原始 `sidecar` 与 `heading`。
|
||||
- 返回 chunk 保留 `source_chunk_id`，`chunk_id` 可继续用 `#match-N` 表示同一 chunk 内第 N 个关键词命中。
|
||||
- LightRAG `kv_store_text_chunks.json` 中的 paragraph semantic chunk 已携带 `sidecar.refs`，例如 `doc-ff0b60997a285a85e5704a114d7b3ffa-chunk-158` 返回 52 个 block refs，MNote 不再需要凭完整 chunk 文本猜测来源 block。
|
||||
|
||||
### 5.2 MNote citation / locator 合同
|
||||
|
||||
- `/api/knowledge-rag/search` exact 模式请求 LightRAG `/query/search` 时显式传 `include_sidecar=true`。
|
||||
- `map_reference_plan(...)` 优先消费 LightRAG chunk `sidecar.refs`，按 `occurrenceIndex` 在 refs 指向的 blocks 中精确选择含 query 的 block。
|
||||
- `find_lightrag_sidecar_block(...)` 已从“文本打分匹配”改为“sidecar.refs 精确 block 选择”；没有 refs 或 refs 中没有 query 命中时不伪造精确 locator。
|
||||
- `displayQuote` / `locatorEvidenceText` 使用选中的 sidecar block 文本，搜索结果不再展示整段 chunk window 导致的重复、错位上下文。
|
||||
- `sourceChunkId` 被写入 mapped reference，便于诊断 match chunk 与原始 LightRAG chunk 的对应关系。
|
||||
|
||||
### 5.3 Office preview 定位
|
||||
|
||||
- `mnote.open_resource_locator` 透传 `paragraphOrdinal / paraIdStart / paraIdEnd / textFingerprint / query / searchQuery`。
|
||||
- 同一 DOCX 点击不同搜索结果时，resource tab 的 base href 比较会剔除定位参数，避免把同一资源误判成新资源而重新加载。
|
||||
- DOCX preview 优先用 `evidenceText` 精确段落锚定，再考虑 paragraph ordinal 附近搜索；避免短 query 命中相邻段落。
|
||||
- `page=0` 不再写入 Office preview URL 或 panel state，避免污染定位状态。
|
||||
|
||||
### 5.4 验证证据
|
||||
|
||||
LightRAG API 证据：
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: $LIGHTRAG_API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
http://127.0.0.1:9621/query/search \
|
||||
-d '{"query":"吡咯烷","limit":2,"max_per_chunk":2,"include_chunk_content":true,"include_sidecar":true}'
|
||||
```
|
||||
|
||||
结果摘要：
|
||||
|
||||
```text
|
||||
chunk_id=doc-ff0b60997a285a85e5704a114d7b3ffa-chunk-158#match-0
|
||||
source_chunk_id=doc-ff0b60997a285a85e5704a114d7b3ffa-chunk-158
|
||||
sidecar.refs=52
|
||||
first_ref=700ee42acf09aadc31f028f523f52fa9
|
||||
```
|
||||
|
||||
MNote 验证：
|
||||
|
||||
```bash
|
||||
cargo test -p mnote-web knowledge_rag -- --nocapture
|
||||
MNOTE_KNOWLEDGE_RAG_PYRROLIDINE_QUERY='吡咯烷' MNOTE_KNOWLEDGE_RAG_TOP_N=5 \
|
||||
node scripts/task543-knowledge-rag-pyrrolidine-top5-locator-smoke.js
|
||||
MNOTE_KNOWLEDGE_RAG_REPOSITION_QUERY='吡咯烷' \
|
||||
node scripts/task541-knowledge-rag-search-panel-office-reposition-smoke.js
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
cargo test: 51 passed
|
||||
task543: 前 5 个搜索结果 apiBlockId/uiBlockId/panelBlockId 一致
|
||||
task543: 第 3 条已定位到 “吡咯烷,5 h, 90%”，不再跳到下一段
|
||||
task541: 搜索面板关闭后状态保持；同一 DOCX 第二次定位 loadCount=0
|
||||
```
|
||||
|
||||
用户验收：
|
||||
|
||||
```text
|
||||
2026-06-09：用户确认本次 DOCX 的查询合格。
|
||||
```
|
||||
|
||||
## 6. 后续收口
|
||||
|
||||
- MNote `knowledge_rag` mapper 已优先消费 provider sidecar refs；后续只需继续把 hybrid/mix 查询返回的 chunk provenance 也推向同一合同。
|
||||
- office-preview 已优先用 sidecar block 的 evidenceText 精确段落锚定；后续可继续增强真实 `paraId` DOM 标注，减少 paragraph ordinal 对 docx-preview DOM 的依赖。
|
||||
- 重新索引 DOCX 后才能让旧资料库命中使用新 sidecar 粒度。
|
||||
- LightRAG 服务需要重启后才会使用本地源码改动。
|
||||
- 本轮已执行 `systemctl --user restart mnote-lightrag.service`，`/health` 返回 healthy；当前 parser routing 仍是 `*:native-iteP,*:mineru-iteP,*:legacy-R`，DOCX 默认走 native。
|
||||
|
||||
## 6. MNote 与 LightRAG 的新分工
|
||||
## 7. MNote 与 LightRAG 的新分工
|
||||
|
||||
LightRAG 已提供 keyword / vector / graph / hybrid 检索、rerank、query 与 chunk/reference 返回。MNote 不应继续维护第二套召回、排序或 sidecar exact search 作为主路径。
|
||||
|
||||
@@ -160,13 +231,14 @@ LightRAG
|
||||
- MNote query-time sidecar quote 反查
|
||||
- 旧 `docs_search` / `mnote.evidence.search` / LiteParse local evidence search
|
||||
|
||||
## 7. 退役计划
|
||||
## 8. 退役计划
|
||||
|
||||
阶段 A：完成 provider positions 消费。
|
||||
阶段 A：完成 provider positions 消费。已完成 DOCX exact search 主链：
|
||||
|
||||
- `knowledge_rag` locator 解析 `positions.type=bbox / paraid / text_fingerprint`。
|
||||
- citation URL 与 resource tab 透传 `paragraphOrdinal / paraIdStart / paraIdEnd / textFingerprint`。
|
||||
- office-preview 优先按段落定位，再回退到当前文本定位。
|
||||
- [x] `knowledge_rag` locator 解析 `positions.type=bbox / paraid / text_fingerprint`。
|
||||
- [x] citation URL 与 resource tab 透传 `paragraphOrdinal / paraIdStart / paraIdEnd / textFingerprint`。
|
||||
- [x] office-preview 优先按 sidecar block 的 evidenceText 定位段落，再按 paragraph ordinal 附近校验定位。
|
||||
- [x] LightRAG `/query/search` 返回 `sidecar.refs`，MNote exact search 不再使用 query-time 文本打分反查。
|
||||
|
||||
阶段 B：退役 query-time sidecar 反查与旧 evidence/docs 搜索。
|
||||
|
||||
@@ -183,14 +255,14 @@ LightRAG
|
||||
- 保留 source-map / locator 兼容读取，用于历史索引和旧 OCR 结果打开。
|
||||
- 新索引统一由 LightRAG parser sidecar 产出定位信息。
|
||||
|
||||
## 8. 不做
|
||||
## 9. 不做
|
||||
|
||||
- 不在 MNote 新增一套 DOCX parser。
|
||||
- 不把 DOCX 默认切到 Docling。
|
||||
- 不在 MNote 实现 rerank；rerank 仍走 LightRAG 原生能力。
|
||||
- 不把 DOCX 无 bbox 伪造成 PDF 页内精确定位。
|
||||
|
||||
## 9. Agent / MCP 边界
|
||||
## 10. Agent / MCP 边界
|
||||
|
||||
LightRAG 官方内核不提供 Skill/MCP/plugin 系统；社区已有 `lightragmcp`、`mcp-lightrag` 等 MCP server，可把 LightRAG query、文档管理、图谱查询包装成 Agent 工具。这一层适合接给 Reasonix / Hermes / Claude Desktop 这类 Agent runtime，但它不能替代 MNote 的 source registry 与引用打开能力。
|
||||
|
||||
Reference in New Issue
Block a user