feat(rag): replace LiteParse flows with LightRAG provider

2026-06-07 01:10:31 +08:00
parent f46c2fb5d0
commit 1f25364374
40 changed files with 7232 additions and 2350 deletions
@@ -0,0 +1,643 @@
+# 7-49 [recycle] Local Understanding GraphRAG Kernel v1
+
+> 创建时间：2026-06-06
+>
+> 当前状态：`RECYCLED`
+>
+> 退役时间：2026-06-06
+>
+> 退役原因：该稿以自研 Understanding GraphRAG Kernel / mindmap projection 为主线，已被 LightRAG 单外挂知识库问答路线取代。相关代码接线已撤回；后续不再按本文推进。
+>
+> Owner：07-ai / 03-rust-web / control-plane / 01-tree-first-graph-kernel
+>
+> 上位依据：
+> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+> - `/mnt/Data1T/mnote/CURRENT_ARCHITECTURE.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-46-document-evidence-retrieval-kernel-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-48-paperless-ngx-reference-resource-ingestion-job-index-v1.md`
+> - `/mnt/Data1T/mnote/design/03-rust-web/done/3-25-local-folder-mineru-ocr-sidecar-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`
+>
+> 参考来源：
+> - `reference-code/Understand-Anything`
+> - `reference-code/PageIndex`
+> - `reference-code/BookRAG`
+> - `reference-code/Kwipu`
+> - `sqlite-graphrag` / `sqlite-knowledge-graph` 类本地 GraphRAG 方案
+
+## 1. 第一结论
+
+MNote 需要新增一层 `Local Understanding GraphRAG Kernel`。它不是替换当前 evidence search，而是在 `EvidenceLocator` 之上生成可查询的本地理解图，让 agent 能回答跨章节、跨资料的系统性问题。
+
+目标链路：
+
+```text
+原始文件 / Markdown / PDF / Word / OCR provider result
+  -> Evidence Kernel: quote + locator + source-map
+  -> Structure Tree: document / section / page / table / list
+  -> Understanding Graph Builder: concept / entity / claim / relation
+  -> SQLite GraphRAG Store: graph + FTS + embedding + locator
+  -> Query Planner: simple / complex / global
+  -> Evidence-backed Answer: answer item -> graph edge -> EvidenceLocator
+```
+
+主适配策略：
+
+- `Understand Anything`：作为“通用理解图生成器”的工程骨架参考，采用扫描、确定性抽取、LLM 语义抽取、graph reviewer、增量更新和 JSON graph artifact 思路。
+- `sqlite-graphrag / sqlite-knowledge-graph`：作为本地持久化和查询引擎参考，默认落 SQLite，不新增常驻 graph 服务。
+- `PageIndex / BookRAG`：只作为算法参考，借鉴 structure tree、tree search、query planning、hierarchy + graph + evidence mapping，不直接集成其运行时。
+- 默认 LLM runtime：Understanding Graph 的语义抽取和 reviewer 默认走 OmniRoute combo `DeepSeek-v4-flash`，用于充分利用当前 NVIDIA 免费资源；但 provider / combo / model 必须可配置，不允许写死到 schema 或 graph 数据中。
+
+关键修正：**OCR 结果、parse 结果、source-map、搜索索引和理解图都是派生数据，默认不应写入用户正文目录。** 它们应写入 MNote 管理的 SQLite / artifact store / graph store，并通过 locator 回到用户原始文件。
+
+## 2. 数据真相与派生数据边界
+
+### 2.1 真相分层
+
+| 数据 | 默认真相 | 默认存放 | 说明 |
+| --- | --- | --- | --- |
+| 用户 Markdown 正文 | 用户 `.md` 文件 | 用户 workspace | 可编辑、可同步、可备份 |
+| 用户附件 / PDF / Word / 图片 | 用户原始文件 | 用户 workspace | MNote 不替代原始资源 |
+| OCR 文本 | 派生 artifact | MNote SQLite / artifact store | 可删除重建，不污染用户目录 |
+| parse 文本 | 派生 artifact | MNote SQLite / artifact store | 可删除重建 |
+| source-map / bbox / page map | 派生定位 artifact | MNote SQLite / artifact store | 可由 parser/OCR 重建 |
+| search index | 派生索引 | SQLite FTS / graph store | 不作为正文真相 |
+| understanding graph | 派生理解图 | SQLite graph tables | node/edge 必须能追溯 locator |
+
+### 2.2 不再默认写用户目录
+
+旧方案曾把 OCR 结果写入 owner Markdown 同目录的 `{pageStem}.ocr/`，并把本地索引写入 `.mnote/index/`。这解决了可见性和可迁移性，但会把大量机器派生数据混入用户目录：
+
+- 用户文件树被 OCR / parse / source-map / index 污染。
+- 同步、备份、搜索、分享时很难区分正文和派生物。
+- 多用户 / share / team workspace 中，派生数据权限和正文权限容易混淆。
+- graph / index rebuild 后会产生大量无业务意义的文件变更。
+
+新口径：
+
+- 用户目录只保存用户原始内容和用户显式插入的引用。
+- OCR / parse / index / graph 默认落到 MNote 管理存储。
+- 如果用户需要导出 OCR 文本，可提供显式 `export OCR` 或 `insert OCR link/content`，但这不是默认路径。
+- 当前阶段旧 OCR sidecar 和旧 `.mnote/index` 都视为测试派生数据，不做兼容读取，不做迁移导入；切到新存储后可直接清理。
+
+## 3. 推荐存储形态
+
+### 3.1 Control-plane artifact store
+
+派生文本和 source-map 不建议全部塞进普通 control-plane 表，也不建议回到用户目录。第一版可以用 SQLite + content-addressed blob 表：
+
+```sql
+derived_artifacts(
+  artifact_id TEXT PRIMARY KEY,
+  workspace_id TEXT NOT NULL,
+  root_uri TEXT NOT NULL,
+  owner_document_id TEXT,
+  owner_document_path TEXT,
+  source_root_relative_path TEXT NOT NULL,
+  artifact_kind TEXT NOT NULL, -- ocr_text | parse_text | source_map | page_image | thumbnail
+  provider TEXT NOT NULL,
+  source_hash TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  content_text TEXT,
+  content_blob_path TEXT,
+  mime_type TEXT,
+  size_bytes INTEGER,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  stale INTEGER NOT NULL DEFAULT 0
+);
+```
+
+原则：
+
+- 小文本可以直接 `content_text`。
+- 大 source-map / page image / provider 原始结果可进入 MNote 管理的 artifact blob 目录，表内只存 hash 和路径。
+- blob 目录必须在 MNote data root 下，而不是用户 workspace 下。
+- artifact 必须用 `workspace_id + root_uri + source_root_relative_path + source_hash` 绑定原始文件版本。
+
+### 3.2 Evidence / GraphRAG SQLite
+
+旧 `.mnote/index/evidence.sqlite` 不迁移为新真相。新 evidence / understanding store 应直接创建在 MNote 管理存储，例如：
+
+```text
+/mnt/Data1T/Mnote_data/control-plane/indexes/{workspace_hash}/evidence.sqlite
+/mnt/Data1T/Mnote_data/control-plane/indexes/{workspace_hash}/understanding.sqlite
+```
+
+或统一放到 control-plane DB 的附属数据库中：
+
+```text
+ATTACH '.../indexes/{workspace_hash}/evidence.sqlite' AS evidence;
+ATTACH '.../indexes/{workspace_hash}/understanding.sqlite' AS understanding;
+```
+
+第一版建议仍使用独立 SQLite 文件，避免 control-plane 主库被大 FTS / embedding / graph 写放大拖慢。
+
+## 4. Understanding Graph Schema
+
+### 4.1 Node
+
+```sql
+understanding_node(
+  node_id TEXT PRIMARY KEY,
+  workspace_id TEXT NOT NULL,
+  root_uri TEXT NOT NULL,
+  node_kind TEXT NOT NULL, -- document | section | page | table | list | concept | entity | claim | method | condition
+  canonical_name TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  summary TEXT,
+  language TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  evidence_locator_json TEXT,
+  source_artifact_id TEXT,
+  confidence REAL NOT NULL DEFAULT 1.0,
+  created_by TEXT NOT NULL, -- deterministic | llm | reviewer | user
+  source_hash TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);
+```
+
+### 4.2 Edge
+
+```sql
+understanding_edge(
+  edge_id TEXT PRIMARY KEY,
+  workspace_id TEXT NOT NULL,
+  root_uri TEXT NOT NULL,
+  from_node_id TEXT NOT NULL,
+  to_node_id TEXT NOT NULL,
+  edge_kind TEXT NOT NULL,
+  relation_label TEXT NOT NULL,
+  evidence_locator_json TEXT,
+  source_artifact_id TEXT,
+  confidence REAL NOT NULL DEFAULT 1.0,
+  created_by TEXT NOT NULL,
+  source_hash TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);
+```
+
+通用 `edge_kind`：
+
+- `document_contains_section`
+- `section_contains_page`
+- `section_contains_table`
+- `section_contains_claim`
+- `concept_has_subtype`
+- `concept_has_example`
+- `concept_defined_by`
+- `entity_has_property`
+- `method_has_condition`
+- `claim_supported_by`
+- `table_row_supports_claim`
+- `term_alias_of`
+- `mentions`
+- `related_to`
+
+注意：不为“保护基”这种单一领域写专用 schema。化学、生物、财务、法律文档都应落到通用 concept / entity / claim / property / condition / evidence 关系上。
+
+### 4.3 Search Surfaces
+
+SQLite store 同时提供：
+
+- FTS：`node.display_name / summary / claim text / artifact text`。
+- embedding：可选，先作为 table/provider 抽象，不强制第一版。
+- graph query：固定 relation traversal。
+- tree query：按 document / section / page / table 聚合。
+
+## 5. Builder Pipeline
+
+### 5.1 确定性抽取
+
+默认不先调用 LLM，先从 artifacts 做可重复抽取：
+
+- Markdown headings / wikilinks / frontmatter / resource links。
+- PDF / Word source-map 的 page、section、table、list。
+- OCR / parse artifact 的段落、页、表格行。
+- 文件系统资源归属、owner document、source hash。
+
+输出：
+
+```text
+document -> section -> page -> block/table/list
+```
+
+### 5.2 LLM 语义抽取
+
+LLM 只做确定性结构无法得到的语义层：
+
+- concept / entity。
+- claim / definition。
+- subtype / example / alias。
+- method / condition / property。
+- table row 到 claim 的解释性关系。
+
+LLM 输出必须是结构化 JSON，且每条 node/edge 必须带输入 evidence id 或 locator。
+
+默认 LLM runtime：
+
+```json
+{
+  "understandingGraph": {
+    "semanticExtractor": {
+      "provider": "omniroute",
+      "routeKind": "combo",
+      "comboName": "DeepSeek-v4-flash",
+      "modelHint": "deepseek-v4-flash",
+      "purpose": "semantic_extraction",
+      "fallback": "deterministic_only"
+    },
+    "graphReviewer": {
+      "provider": "omniroute",
+      "routeKind": "combo",
+      "comboName": "DeepSeek-v4-flash",
+      "modelHint": "deepseek-v4-flash",
+      "purpose": "graph_review",
+      "enabledByDefault": false
+    }
+  }
+}
+```
+
+配置原则：
+
+- `DeepSeek-v4-flash` 只作为默认推荐 combo，理由是适合后台异步批处理，并能优先利用当前 NVIDIA 免费资源。
+- 实际 runtime 通过 OmniRoute combo / model registry 解析当前可用 ID，例如 `deepseek-v4-flash` 或 provider-scoped `deepseek/deepseek-v4-flash`，MNote 侧不把具体上游 ID 写死进 graph schema。
+- MNote 不直接持有外部 provider key；鉴权、配额、fallback 和账号健康检查由 OmniRoute 承接。
+- 无额度、离线或 provider 失败时，任务进入 retry / failed，或降级为 `deterministic_only`；不得把未完成的 LLM graph build 标记为成功。
+- semantic extractor 和 reviewer 可分别覆盖模型：抽取默认便宜高速，reviewer 可在 spike 或显式 rebuild 时换成更高质量模型。
+- prompt、日志和 graph artifact 不记录 provider token、上传 URL 或完整外部响应，只记录 job id、model route、失败阶段和可审计摘要。
+
+禁止：
+
+- 只输出无来源结论。
+- 把 LLM 推理结果当原文事实。
+- 在没有 locator 的情况下写入高置信 graph edge。
+
+### 5.3 Graph Reviewer
+
+借鉴 Understand Anything 的 reviewer，但第一版不做大模型全量审查。先做三类检查：
+
+- 结构检查：node/edge 引用是否存在，locator JSON 是否可解析。
+- 证据检查：edge 的 `evidence_locator_json` 能否读回 quote。
+- 去重检查：alias / canonical_name 是否过度分裂。
+
+LLM reviewer 只在 spike 阶段或用户显式重建时运行。
+
+### 5.4 增量更新
+
+增量粒度：
+
+```text
+source file hash
+  -> artifact hash
+  -> section subtree hash
+  -> graph node/edge source_hash
+```
+
+文件变化时：
+
+- 原始文件 hash 未变：不重建。
+- artifact 变：只删除并重建该 source_hash 派生的 node/edge。
+- section 变：只重建对应 subtree。
+- graph schema version 变：排队重建当前 workspace graph。
+
+## 6. Query Planner
+
+Planner 负责把用户问题变成 retrieval plan，而不是让 agent 直接猜关键词。
+
+### 6.1 Query Types
+
+借鉴 BookRAG：
+
+- `simple`：单点事实，走 evidence search / node search。
+- `complex`：多个子问题，分别检索后合成。
+- `global`：列举、统计、总结、分类，走 tree / graph aggregation。
+
+“羧酸/羧基的保护基有哪些，列举 5 种”应属于：
+
+```json
+{
+  "queryType": "global",
+  "operation": "LIST",
+  "targetConcept": "羧酸保护基",
+  "constraints": {
+    "limit": 5
+  }
+}
+```
+
+执行策略：
+
+1. term normalize：羧酸 / 羧基 / COOH / CO2H / carboxylic acid / carboxyl。
+2. graph search：找 concept node。
+3. relation traversal：`concept_has_subtype` / `concept_has_example`。
+4. evidence read：回读每个候选的 locator。
+5. answer synthesize：仅用回读证据组织答案。
+
+### 6.2 Tool Contract
+
+新增 MNote tools：
+
+- `mnote.understanding.status`
+- `mnote.understanding.rebuild`
+- `mnote.understanding.cleanup_legacy`
+- `mnote.understanding.jobs`
+- `mnote.understanding.search_nodes`
+- `mnote.understanding.traverse`
+- `mnote.understanding.query`
+- `mnote.understanding.read_evidence`
+- `mnote.understanding.mindmap_projection`
+
+其中 `mnote.understanding.query` 返回：
+
+```json
+{
+  "ok": true,
+  "queryType": "global",
+  "operation": "LIST",
+  "items": [
+    {
+      "name": "苄酯",
+      "nodeId": "concept:...",
+      "supportingEdges": ["edge:..."],
+      "evidence": [
+        {
+          "quote": "...",
+          "locator": { "schema": "mnote.evidence_locator.v1" },
+          "citationMarkdown": "[...](/documents/...)"
+        }
+      ],
+      "confidence": 0.82
+    }
+  ],
+  "diagnostics": {
+    "planner": "understanding_graph",
+    "fallbackUsed": false
+  }
+}
+```
+
+## 7. Understanding Dashboard 与任务面板
+
+2026-06-06 路线修正：官方 Understand Anything dashboard 的价值不是“mindmap”，而是完整的 graph explorer：图布局、节点/边类型过滤、layer/community、搜索高亮、节点详情、guided tour、path finder、export、schema warning 和源码/证据面板。当前 MNote simplemindmap 不应继续作为 7-49 主 UI 承载。
+
+第一阶段改为 **官方 UA dashboard 走通优先**：
+
+- 暂缓 `understanding_mindmap_projection` 的产品化 UI 工作。
+- 先安装/运行官方 UA dashboard，用 UA 原生 `knowledge-graph.json` 或 MNote 转换出的 UA-compatible graph 检查体验。
+- 若 dashboard 效果符合预期，再决定是 vendor/fork UA dashboard 组件，还是在 MNote Web 中实现同等的 `Understanding Dashboard`。
+- mindmap 只保留为后续轻量能力：answer-level 子图、导出、插入文档旁边；不再要求覆盖完整 Understanding Graph Explorer。
+
+### 7.1 Official UA Dashboard Spike
+
+第一阶段目标：
+
+```text
+MNote understanding graph / evidence graph
+  -> UA-compatible knowledge-graph.json
+  -> official Understand Anything dashboard
+  -> browser-visible graph explorer spike
+```
+
+验收：
+
+- dashboard 能打开并渲染图，不依赖 MNote mindmap。
+- 至少能展示 document / section / concept / claim / evidence source 节点。
+- 支持搜索、节点点击、相邻关系高亮、类型过滤或 layer/legend 中至少两类交互。
+- 节点详情能看到 summary、created_by/confidence、source artifact、EvidenceLocator 摘要。
+- 能从节点或证据 panel 回到 MNote evidence/open action，或者明确记录第一阶段暂缺的 deep-link 差距。
+
+边界：
+
+- 官方 dashboard 只是体验 spike，不是 MNote 的长期事实源。
+- 不把 `.understand-anything/knowledge-graph.json` 当成 MNote graph 真相；真相仍在 `understanding.sqlite` / evidence store。
+- 不绕过 MNote workspace/root 权限直接读用户文件。
+- 不把 UA dashboard 的代码库 schema 原样扩展成 MNote 长期 schema；需要通过 adapter 投影。
+
+### 7.2 Mindmap Projection（暂缓产品化）
+
+保留只读派生 projection，但不作为第一阶段主 UI：
+
+```text
+understanding graph node/edge
+  -> understanding_mindmap_projection
+  -> MNote mindmap view
+```
+
+原则：
+
+- mindmap view 是派生展示，不是 graph 真相，也不是用户手工 mindmap 资源真相。
+- 真相仍在 `understanding.sqlite` 的 node / edge / evidence locator 表中。
+- projection 可按 document / section / concept / query result 生成，支持刷新和重建。
+- 节点点击后展示 summary、created_by、confidence、source artifact、evidence quote 和 locator open action。
+- 边点击后展示 relation_label、edge_kind、支持证据和 reviewer 状态。
+- 支持过滤 `deterministic | llm | reviewer | user` 来源，避免把 LLM 抽取和确定性结构混在一起。
+
+后续 UI surface：
+
+- graph query 答案页可打开“查看理解图”，只展示本次答案涉及的 node / edge / evidence 子图。
+- 文档页资源 tab 可提供 `导出为 mindmap` 或 `插入子图`。
+- 不再把完整 workspace understanding graph 塞进 simplemindmap。
+
+### 7.3 后台任务面板
+
+Understanding Graph 属于异步派生数据系统，必须有后台任务可见性。后台面板至少展示：
+
+- job kind：`resource_parse`、`local_ocr`、`evidence_index_refresh`、`understanding_graph_build`、`understanding_graph_review`、`understanding_mindmap_projection_refresh`。
+- job state：`queued | running | retrying | failed | done | stale`。
+- 输入范围：workspace、root、document、section subtree、source artifact。
+- LLM runtime：provider、combo、model route、purpose、retry count。
+- 产出统计：artifact count、node count、edge count、locator count、mindmap node count。
+- 质量指标：locator 回读成功率、抽取 recall / precision、reviewer 发现的问题类型。
+- 失败诊断：OCR 噪声、parser 失败、OmniRoute 无额度、LLM JSON schema invalid、locator 断裂、schema version mismatch。
+- 操作：retry、rebuild selected scope、mark stale、open evidence、open mindmap projection。
+
+边界：
+
+- 后台任务面板只读展示 job 账本和触发显式 rebuild，不允许绕过权限直接读 SQLite。
+- LLM prompt、provider token、上传 URL 和完整外部响应不在 UI 展示。
+- projection refresh 不能通过轮询长期驱动，优先由 ResourceWorkJob 状态变化和 realtime event 推送触发。
+
+## 8. 与现有 7-46 / 7-48 的关系
+
+### 8.1 7-46 Evidence Kernel
+
+`7-46` 仍是 quote / locator / open action 的基础。但其文件布局需要直接切到新存储：
+
+- `source-map.json` 不再写入 `{pageStem}.ocr/`。
+- `evidence.sqlite` 不再写入用户 workspace 的 `.mnote/index/`。
+- 旧 `{pageStem}.ocr/` 和 `.mnote/index/` 不作为 runtime fallback，不新增 legacy reader。
+
+### 8.2 7-48 Resource Work Kernel
+
+`7-48` 的 `ResourceWorkJob` 应扩展为派生数据任务账本：
+
+- `local_ocr`
+- `resource_parse`
+- `evidence_index_refresh`
+- `understanding_graph_build`
+- `understanding_graph_review`
+- `understanding_mindmap_projection_refresh`
+- `workspace_sanity_check`
+
+任务结果应记录 artifact id、node/edge count、locator count、失败阶段和 rebuild reason。
+
+## 9. 旧派生数据清理
+
+当前阶段所有既有 OCR / index 都视为测试派生数据。为降低实现复杂度，不做旧格式兼容、导入器或双写。
+
+### 9.1 清理范围
+
+可清理对象：
+
+- 旧 `{pageStem}.ocr/` 目录。
+- 旧 `.mnote/index/` 目录。
+- 旧 `search-index.json`。
+- 旧 `evidence.sqlite`。
+- 旧 source-map / bbox / OCR provider 结果文件。
+
+不可清理对象：
+
+- 用户 Markdown 正文。
+- 用户附件、PDF、Word、图片原始文件。
+- 用户显式创建的 mindmap / office / resource 文件。
+- 用户显式导出的 OCR 文本。
+
+### 9.2 清理方式
+
+新增一次性 cleanup job：
+
+- job kind：`legacy_derived_data_cleanup`。
+- 默认只扫描当前 workspace root 下的已知派生路径。
+- 清理前记录删除清单、文件数量、总字节数和 root。
+- 清理后强制触发 `resource_parse`、`evidence_index_refresh`、`understanding_graph_build`。
+- 清理失败不得影响用户原始文件打开，只标记派生数据 stale。
+
+运行时口径：
+
+- 新 search / evidence / understanding routes 只读 control-plane index store。
+- watcher 不再监听旧 `.mnote/index` 写入。
+- UI 不再展示旧 OCR sidecar 作为系统文件；如果用户目录中仍残留，只按普通文件显示或由 cleanup job 删除。
+- status API 只返回 `storageLocation: "control_plane"`，不保留 `workspace_legacy` 状态。
+
+## 10. 权限与隐私
+
+- 派生 artifact 和 graph 必须继承原始 root / workspace / grant 权限。
+- 用户失去 root 访问权限后，不得再从 graph 查询到该 root 的 node/edge。
+- share workspace 下，graph query 必须按 user / workspace / rootUri 过滤。
+- OCR provider token、上传 URL、provider 原始响应不进入 graph。
+- graph node/edge 只存必要 quote / summary；完整 artifact 读取必须走权限检查。
+- 派生数据删除策略应跟随 workspace disconnect / revoke / explicit cleanup。
+- mindmap projection 必须继承 graph query 的权限过滤，不得展示用户无权访问的 node / edge。
+
+## 11. 第一阶段 Spike
+
+目标不是做完整产品，而是证明 GraphRAG 层真的解决 FTS 失败的系统性问题。
+
+### 11.1 输入
+
+- 使用当前测试账号已有保护基书资源。
+- 读取现有 evidence / OCR / parse artifact。
+- 不写用户目录。
+
+### 11.2 实现范围
+
+1. 建一个最小 `understanding.sqlite`。
+2. 从 evidence blocks 生成 section tree。
+3. 对一个章节范围做 LLM 语义抽取：
+   - concept
+   - subtype/example
+   - definition/claim
+   - locator
+4. 写入 node/edge。
+5. 实现一个 CLI 或 route：
+   - 输入问题：“羧酸/羧基的保护基有哪些，列举 5 种”
+   - 输出 graph-backed items + citation。
+6. 输出本次 spike 的 UA-compatible dashboard graph：
+   - 至少包含目标 concept、候选 subtype/example、supporting edge、evidence locator/source 节点。
+   - 能在官方 UA dashboard 中打开并完成搜索、节点点击、过滤/图例等基础交互。
+7. 后台任务面板能看到 build / extraction / dashboard projection refresh 的状态和失败原因。
+
+### 11.3 验收
+
+- 不能只靠 FTS topK 直接回答。
+- 每个条目必须有 node/edge 和 EvidenceLocator。
+- 每个 EvidenceLocator 必须能用 `mnote.evidence.read/open` 回读或打开。
+- dashboard graph 必须能解释答案来源：答案条目 -> graph edge -> EvidenceLocator。
+- job 面板必须能看到 OmniRoute route、node/edge count、locator 回读率和失败阶段。
+- 手标至少 30 个候选实体，抽取 recall >= 70% 才继续。
+- precision 低于 70% 时必须记录错误类型：OCR 噪声、术语归一失败、LLM 幻觉、章节边界错误、关系 schema 不足。
+- 增量更新单个 source artifact 后，不触发整库 full rebuild。
+
+## 12. 非目标
+
+- 不把 Understand Anything、BookRAG、PageIndex、Kwipu 整包引入 MNote runtime。
+- 不把官方 UA dashboard 当成 MNote 长期事实源；第一阶段只作为体验 spike / adapter 验证。
+- 不新增默认常驻 graph 服务。
+- 不把 graph DB 当正文真相。
+- 不把 understanding dashboard / mindmap projection 当用户手工 mindmap 真相。
+- 不让 agent 直接读 SQLite 文件绕过 tool / permission。
+- 不把 OCR 文本默认插入用户 Markdown。
+- 不兼容旧 OCR sidecar 或 `.mnote/index` 作为 runtime fallback。
+
+## 13. 后续实施顺序
+
+2026-06-06 复核口径：mempalace 中能命中 7-49 前期只读勘察与 sqlite-graphrag 评估，但未找到当前 `7-49-local-understanding-graphrag-kernel-v1.md` 的完成记录；另有 2026-06-01 旧 `7-49 external audit / OpenClaw provider tests` 日志，属于同编号历史碰撞，不能作为本文完成证据。以下勾选只按当前实际代码确认。
+
+- [x] 冻结派生数据新存储口径：control-plane artifact store + control-plane index store。
+  - 证据：`local_search_index.rs` 的 `local_index_storage_dir()` 默认写入 `/mnt/Data1T/Mnote_data/control-plane/indexes/{workspace_hash}`，`evidence_sqlite_path()` / `understanding_sqlite_path()` 均落在该目录；`evidence.sqlite` 已新增 `derived_artifacts` 表存 parse/OCR/source-map 派生文本；status 返回 `storageLocation: "control_plane"` 与 `derivedArtifactCount`。
+- [ ] 给 7-46 直接切到 control-plane storage，删除 workspace legacy writer / reader 分支。
+  - 复核：evidence/search index 主路径已切 control-plane index store；但 OCR sidecar、source-map/旧 sidecar 读取和 7-46 全链路仍未完全收口，不能勾选。
+- [x] 新增 `understanding.sqlite` 最小 schema。
+  - 证据：`routes/understanding.rs` 已创建 `understanding_meta`、`understanding_node`、`understanding_edge`，并通过 `understanding_sqlite_path()` 持久化。
+- [x] 实现 `legacy_derived_data_cleanup` 与 `mnote.understanding.cleanup_legacy`，显式清理旧 OCR sidecar / `.mnote/index` 测试派生数据。
+  - 证据：`local_search_index::legacy_derived_data_cleanup()` 扫描 `.mnote/index` 与 `*.ocr` 目录；`routes/understanding::cleanup_legacy()` 要求显式 `dryRun`，写操作走 workspace write access，清理后刷新 evidence index 并尝试重建 understanding graph。
+- [x] 实现 section tree builder。
+  - 证据：`rebuild_understanding_graph()` 从 `evidence_block.section_path_json` 生成 `section` node 和 `document_contains_section` edge，并生成 `claim` node / `section_contains_claim` edge。当前只是最小 section/claim tree，不含 page/table/list 完整结构。
+- [x] 增加 Understanding Graph LLM runtime 配置：默认 OmniRoute combo `DeepSeek-v4-flash`，支持 extractor / reviewer 分别覆盖。
+  - 证据：`default_llm_runtime()` 已输出 `semanticExtractor` / `graphReviewer` 两套配置；支持 `MNOTE_UNDERSTANDING_EXTRACTOR_*` 与 `MNOTE_UNDERSTANDING_REVIEWER_*` 环境变量分别覆盖，reviewer 默认关闭并保留 `deterministic_only` fallback。
+- [ ] 实现最小 LLM semantic extractor + reviewer。
+  - 复核：当前抽取是 `deterministic_term_extractor` / `deterministic_protecting_group_normalizer`，没有实际 LLM 调用、JSON schema 校验或 reviewer。
+- [x] 实现 `mnote.understanding.query`。
+  - 证据：HTTP route、Hermes tool manifest、tool dispatch 均已注册；查询先读 `understanding.sqlite` 的 concept edge，再 fallback evidence graph / sqlite search。
+- [ ] 安装并走通官方 UA dashboard spike，暂缓 MNote mindmap 产品化适配。
+  - 复核：已确认官方 dashboard 功能面更接近 7-49 需求；但尚未把 MNote graph 转成 UA-compatible `knowledge-graph.json` 并真实打开 dashboard。
+- [ ] 增加后台 Understanding job 面板，展示 build / review / dashboard projection refresh 状态。
+  - 复核：`mnote.understanding.jobs` 已有合成 jobs API/tool，并返回 review、locator parse success rate 与失败阶段；但没有后台 UI 面板，也未接真实 ResourceWorkJob 账本。
+- [ ] 跑保护基书 spike，并记录 recall / precision / locator 回跳率和 mindmap 可解释性。
+  - 复核：代码里有最小单元测试覆盖羧酸保护基 query variant 和 term extraction；未见真实保护基书 spike、人工标注 30 个实体、recall/precision 记录或浏览器验证证据。
+- [ ] 若 spike 通过，再扩到多文档 workspace 和 UI。
+  - 复核：当前仍是单 workspace/root 的最小 kernel/tool 路径，未进入多文档 UI 产品化。
+
+## 14. 2026-06-06 实际代码完成情况复核
+
+### 14.1 已完成的最小能力
+
+- [x] control-plane index store：`search-index.json`、`evidence.sqlite`、`understanding.sqlite` 默认位于 control-plane 管理目录，不写入用户 workspace 的旧 `.mnote/index`。
+- [x] control-plane artifact table：`evidence.sqlite.derived_artifacts` 已存 `parse_text` / `ocr_text` / `source_map`，带 workspace/root/source hash/content hash/stale 字段；`local_index.status` 返回 `derivedArtifactCount`。
+- [x] Understanding HTTP routes：`/api/understanding/status|rebuild|cleanup_legacy|jobs|search_nodes|traverse|query|read_evidence|mindmap_projection` 已注册。
+- [x] Hermes tools：`mnote.understanding.*` 九个工具已在 manifest、dispatch、skill allowlist 中注册。
+- [x] 最小 deterministic graph builder：从 `evidence_resource` / `evidence_block` 生成 document/resource、section、claim、concept node 与 contains/support/example edge。
+- [x] EvidenceLocator 回读桥：`mnote.understanding.read_evidence` 复用 `mnote.evidence.read` 的 read payload。
+- [x] 旧派生数据显式 cleanup：支持 dry-run plan 和 apply，范围限定旧 `.mnote/index` 与 `*.ocr` sidecar。
+- [x] LLM runtime 配置面：默认 OmniRoute combo `DeepSeek-v4-flash`，extractor / reviewer 可分别通过环境变量覆盖。
+- [x] 确定性 graph reviewer：重建后记录 `last_review_json`，检查 edge node 引用、locator JSON parse、canonical name 重复，并在 jobs/status 返回 locator parse success rate 与失败阶段。
+- [x] mindmap projection 证据链增强：projection 节点 metadata 已包含 `supportingEdges` / `supportingEdgeKinds` / `evidence` / `confidence` / `createdBy`；该能力降级为 answer-level 辅助，不再作为主 UI。
+- [x] 最小测试：`understanding_rebuild_query_and_mindmap_use_control_plane_store`、`legacy_cleanup_removes_only_derived_sidecars`、query variant 和 term extraction 单测已存在。
+
+### 14.2 未完成或只能算部分完成
+
+- [ ] artifact runtime cutover：已有 `derived_artifacts` 表和 parse/OCR/source-map 写入；但 parse/OCR runtime 仍会写 legacy sidecar 文件，尚未改成只依赖 artifact store/blob store。
+- [ ] 7-46 evidence kernel 全面切流：evidence/search index 路径已切，但旧 OCR sidecar / source-map / fallback 边界未完全删除。
+- [ ] LLM semantic extractor：没有调用 OmniRoute / DeepSeek-v4-flash，也没有结构化 LLM graph artifact。
+- [ ] LLM Graph reviewer：确定性结构/locator/去重检查已落地；但还没有显式 rebuild 时可启用的 LLM reviewer。
+- [ ] 增量更新：`understanding.rebuild` 仍是按当前 evidence 全量重建；没有 source artifact / section subtree 粒度的 node/edge 删除重建。
+- [ ] 后台任务面板：无 UI surface；jobs API 已返回 review/locator 指标，但仍未接真实 ResourceWorkJob 账本。
+- [ ] 官方 UA dashboard spike：尚未安装/启动 dashboard，也没有 MNote -> UA-compatible graph adapter。
+- [ ] 资源 tab / workspace `Understanding Dashboard`：当前没有浏览器 runtime / SSR UI 入口。
+- [ ] 保护基书 spike 验收：没有真实资源验证、locator 回跳率、recall/precision 或截图/浏览器证据。
+
+### 14.3 当前归档判断
+
+本文不能移动到 `done`。当前实际完成的是 `Local Understanding GraphRAG Kernel` 的最小 deterministic kernel/tool spike；产品化条件仍卡在 artifact store、LLM extractor/reviewer、任务账本/UI、真实保护基书 spike 和增量更新。