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