644 lines
30 KiB
Markdown
644 lines
30 KiB
Markdown
# 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 和增量更新。
|