feat(rag): align LightRAG native citations and MCP bridge

2026-06-09 09:20:56 +08:00
parent 0e8b03daf8
commit 8e3be8b0b7
39 changed files with 2255 additions and 2732 deletions
@@ -0,0 +1,27 @@
+---
+name: mnote_lightrag_bridge
+description: Use when an agent has LightRAG references or file_path/chunk_id and must convert them into MNote clickable citation links or openable local resource locators. Pair with lightrag_native for retrieval, but use this bridge for MNote source registry and citation/open-reference mapping.
+---
+
+# MNote LightRAG Bridge
+
+用途：把 LightRAG 原生检索结果映射成 MNote 可点击、可打开、可定位的引用。它不是检索系统本身。
+
+## 工具分层
+
+- `lightrag_native`：LightRAG 原生 MCP，负责 `query_text`、`query_data`、graph、documents、pipeline。
+- `mnote_lightrag_bridge`：MNote bridge，负责 source registry、`file_path/chunk_id` 映射、`citationUrl`、`openAction`。
+
+## 使用流程
+
+1. 先用 `lightrag_native.query_text` 或 `lightrag_native.query_data` 做资料库检索。
+2. 从返回的 `references[]` 里取 `file_path`，有 `chunk_id` 时一并保留。
+3. 调用 `mnote_lightrag_bridge.open_mnote_reference`，输入 `file_path` / `chunk_id` / `workspace_id` / `root_uri`。
+4. 最终回答引用 bridge 返回的 `citationMarkdown` 或让 MNote UI 渲染 citation；不要手写 `/documents`、`file://`、LightRAG dashboard URL。
+
+## 边界
+
+- `file_path` 是 LightRAG provider 内部文件名，不等于用户本地相对路径。
+- 只有 MNote registry 命中的 reference 才能映射回本地资源和页面。
+- `locatorDegraded=true` 时必须说明“来源定位降级”，不能伪造页码、bbox、段落或坐标。
+- 不要用 bridge 做召回、重排、全文 fallback 或资料管理。