# 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 和增量更新。