lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
031a08288be856f5708c098136db580a59fe1353
mnote/design/old/07-ai/process/7-49-local-understanding-graphrag-kernel-v1.md
T

30 KiB
Raw Blame History

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 能回答跨章节、跨资料的系统性问题。

目标链路：

原始文件 / 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 表：

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 管理存储，例如：

/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 的附属数据库中：

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

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

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。

输出：

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：

{
  "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 增量更新

增量粒度：

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 种”应属于：

{
  "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 返回：

{
  "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

第一阶段目标：

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：

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 日志，属于同编号历史碰撞，不能作为本文完成证据。以下勾选只按当前实际代码确认。

  • 冻结派生数据新存储口径：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 全链路仍未完全收口，不能勾选。
  • 新增 understanding.sqlite 最小 schema。
    • 证据：routes/understanding.rs 已创建 understanding_meta、understanding_node、understanding_edge，并通过 understanding_sqlite_path() 持久化。
  • 实现 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。
  • 实现 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 完整结构。
  • 增加 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。
  • 实现 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 已完成的最小能力

  • control-plane index store：search-index.json、evidence.sqlite、understanding.sqlite 默认位于 control-plane 管理目录，不写入用户 workspace 的旧 .mnote/index。
  • 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。
  • Understanding HTTP routes：/api/understanding/status|rebuild|cleanup_legacy|jobs|search_nodes|traverse|query|read_evidence|mindmap_projection 已注册。
  • Hermes tools：mnote.understanding.* 九个工具已在 manifest、dispatch、skill allowlist 中注册。
  • 最小 deterministic graph builder：从 evidence_resource / evidence_block 生成 document/resource、section、claim、concept node 与 contains/support/example edge。
  • EvidenceLocator 回读桥：mnote.understanding.read_evidence 复用 mnote.evidence.read 的 read payload。
  • 旧派生数据显式 cleanup：支持 dry-run plan 和 apply，范围限定旧 .mnote/index 与 *.ocr sidecar。
  • LLM runtime 配置面：默认 OmniRoute combo DeepSeek-v4-flash，extractor / reviewer 可分别通过环境变量覆盖。
  • 确定性 graph reviewer：重建后记录 last_review_json，检查 edge node 引用、locator JSON parse、canonical name 重复，并在 jobs/status 返回 locator parse success rate 与失败阶段。
  • mindmap projection 证据链增强：projection 节点 metadata 已包含 supportingEdges / supportingEdgeKinds / evidence / confidence / createdBy；该能力降级为 answer-level 辅助，不再作为主 UI。
  • 最小测试：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 和增量更新。

Reference in New Issue View Git Blame Copy Permalink