mnote/ARCHITECTURE.md

# MNOTE 当前架构梳理

> 更新时间：2026-06-07
>
> 2026-05-22 口径更新：产品形态已切换为 local-first workspace，且初步 MVP 已建立；本地文件夹是默认数据真相，Turso/libSQL control-plane 承接 auth、membership、share grants、sync state、AI policy、OpenHub scope / AI policy 等默认控制面。旧 ACP/Hermes runtime session 只保留为迁移兼容层。Convex 仅保留为历史迁移源、显式 cloud source / compat / sync replica 边界；根 `convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`，不再作为 active deploy source。相关设计已完成并迁入 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md` 与 `design/02-convex-rust-long-term-architecture/done/2-8-convex-replace-with-rust-sqlite-control-plane-v1.md`。本地 Markdown 图片与附件上传已新增 `/api/local-folder/assets/upload`，页面内上传默认写入 `{mdBase}.assets/` 并保存相对 Markdown 路径，不再走 Convex media asset。
>
> **当前阶段：local-first MVP 后阶段。** 3000 下文档页、Sidebar/File Tree/Page Tree 三层树模型、tree command（`tree.*` preferred）、tree realtime WS 主链 / SSE fallback、本地 Markdown 上传、上传下载、AI 会话本地化与 VSCode-like agent 运行口径均已建立。剩余工作集中在 `WorkspacePath/ObjectIdentity` runtime 消费统一、`DocumentBuffer/BufferStore`、Page Aggregate compat 瘦身、tree command context、live cache 统一、VSCode-like 冲突合并 UI、agent diff 审计、本地轻量搜索 / 分享 / 同步闭环，而不是继续扩张专用 page-ai fast-path 或 Convex 主存储链。
>
> 2026-05-26 口径更新：前端 runtime 大块已完成模块级拆分。`layout.rs` / `tree.rs` / `web_shell.rs` 不再是浏览器 JS 功能的主要符号定位入口；Sidebar、FileTree、document adapter、tree shell 等 runtime 入口位于 `rust/crates/mnote-web/browser/*.js`，tiptap island 入口位于 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。CodeGraph 可直接索引这些 JS / Rust 模块；当前 smoke 分类见 `scripts/TESTING_REFERENCE.md`。
>
> 2026-07-03 口径更新：当前 runtime 已收口为 OpenHub / native agent + LightRAG + Turso/libSQL。知识库问答、资料 ingestion / query / citation / open-reference 默认走 LightRAG provider；OpenHub 负责 Page AI 面板、opencode/native agent 执行、会话和工具事件承载；WeKnora 只保留为历史设计、参考实现或可选备用 provider 边界，不再作为当前默认知识库主链。Hermes / Reasonix 仅保留 legacy/debug/外部工作流边界。旧 `/api/hermes/*`、`hermes_tools/*`、ACP runtime 命名属于历史命名或迁移中的兼容层，不代表当前产品定义。

本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。

## 1. 当前主线结论

当前仓库的主线不是：

- `BlockNote-first`
- `Mindmap-first`
- “先拆掉 Convex 再谈 Rust”

当前主线固定为：

1. `tree-first graph kernel` 是长期对象真相层
2. 本地文件夹是默认数据真相，Turso/libSQL control-plane 是默认账号、分享、同步、协作和 AI 隔离控制面；Convex 退居历史迁移源与显式 cloud / compat 边界
3. `mnote-web` 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
5. `BlockNote` 已退出文档页默认主路径，仅作为历史参考实现 / 对照材料保留
6. 页面 AI 当前最合理的长期形态是：MNote 只负责页面定位、白名单目录权限、OpenHub / native agent scope 管理、文件变更同步；OpenHub / native agent 直接在授权工作区内编辑本地文件。`page_ai_workflow` 只保留为 debug / 历史兼容门面，`mnote.doc.markdown_edit` 不作为 local-first 默认正文编辑入口，只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback；`mnote.block.*` 只保留为复杂结构辅助层
7. 知识库资料处理主线是 LightRAG + OpenHub：资料 ingestion、检索、引用和跨文档问答默认由 LightRAG provider 承担；OpenHub / native agent 通过 MNote provider-neutral tool facade 使用知识库能力；WeKnora 仅作为历史设计、参考实现或备用 provider 边界，MNote 不再并行维护 LiteParse / evidence SQLite / OCR sidecar 作为资料库索引真相

一句话收口：

> **Rust 持有语义主导权，本地文件夹是默认数据真相，Turso/libSQL control-plane 持有默认控制面；Convex 只保留历史迁移源、显式 cloud source / compat / sync replica 能力，前端逐步从重壳转向消费稳定 projection 与少量交互 island。**

补充口径：

> **主 Web 执行面当前以 `mnote-web` 为 3000 owner；Next App Router 只保留为 legacy compat、交互 island bundle source 与显式 debug/迁移辅助边界。**
>
> **页面 AI 的 local-first 主路径应尽量贴近 VSCode：当前页面解析成真实 `.md` 文件，OpenHub / native agent 在授权目录白名单内直接读写，tiptap 只消费后台文件变化后的最新投影。知识库问答默认走 LightRAG provider，并经 MNote source registry 和 citation/open-reference 回到本地资源。**

## 2. 当前主线目录

- `/mnt/Data1T/mnote/recycle/wolai-frontend/`
  已退役移入 recycle。React island 与 legacy compat 代码的历史来源；Next.js App Router 已被 Rust mnote-web SSR 替代，不再作为 3000 主入口。
- `/mnt/Data1T/mnote/rust/crates/core-protocol/`
  Kernel 类型、projection 协议、编辑器协议、树 / 图核心术语。
- `/mnt/Data1T/mnote/rust/crates/bridge-runtime/`
  Kernel query / command、bridge transport、Tiptap <-> editor document 适配、命令解释层。
- `/mnt/Data1T/mnote/rust/crates/mnote-web/`
  Rust Web route、kernel projection、documents/search/mindmap shell、OpenHub bridge、stream transport、compat，以及显式开启时的 debug shell；它是当前主 Web gateway / shell / transport owner。旧 Hermes bridge 命名仅作为 legacy route / tool facade 兼容层存在。
- `/mnt/Data1T/mnote/recycle/20260522-convex-runtime-retirement/convex/`
  根 `convex/` functions 源码已退役并软删除到这里；不再作为 active deploy source。历史 `schema.ts`、`aiSessions.ts`、Auth functions 仅用于审计 / 迁移对照，默认控制面已由 Turso/libSQL control-plane 承接。
- `/mnt/Data1T/mnote/recycle/wolai-frontend/convex/`
  已随 wolai-frontend 移入 recycle，不允许作为当前 Convex deploy fallback。
- `/mnt/Data1T/mnote/recycle/20260522-convex-runtime-retirement/infra/convex/`
  Convex 自托管服务基础设施已软删除到回收区；只作为显式 cloud source / compat / sync replica 或历史数据导出的历史对照，不再被 `desktop:hot` / `dev:hot` 默认启动链路要求。
- `/mnt/Data1T/mnote/wolai-backend/`
  辅助后端与异步处理，不是当前页面主链。

## 3. 当前页面运行结构

### 3.1 根布局与 legacy island source（已退役）

- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/app/layout.tsx`

该文件已随 wolai-frontend 移入 `recycle/`，不再作为当前实现依据。

注意：

> **3000 当前根入口与文档页 shell 由 `mnote-web` Rust SSR 持有；Next App Router 已完全退役。**

### 3.2 工作区壳与 Sidebar（已迁移至 Rust SSR）

以下文件已随 wolai-frontend 移入 `recycle/`，不再作为当前实现依据：

- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/app-layout-shell.tsx`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/hooks/use-sidebar-data.ts`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/tree-stream/use-sidebar-tree-stream.ts`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts`

当前 Sidebar/工作区壳的当前实现在 Rust mnote-web SSR：
- 工作区壳渲染入口：`gateway.rs`（`root_entry`）
- 文档页壳/文档面板：`web_shell.rs`（`document_page_shell`、`build_document_panes_bootstrap_json`）
- Sidebar / FileTree / tree live runtime：`rust/crates/mnote-web/browser/sidebar-tree-runtime.js`、`filetree-*.js`、`tree-live-controller.js` 等模块；`layout.rs` 只负责 SSR/bootstrap 和 script 注入。
- FileTree 渲染与交互：`rust/crates/mnote-web/browser/filetree-runtime.js`、`filetree-selection-runtime.js`、`filetree-context-menu-runtime.js`、`filetree-dnd-runtime.js`、`filetree-keyboard-runtime.js`。
- debug/internal tree shell runtime：`rust/crates/mnote-web/browser/tree-shell-runtime.js` 及 `tree-shell-*.js` 模块；`tree.rs` 只负责 route、HTML shell、asset route 和测试断言。

### 3.3 Runtime 模块化现状

当前 CodeGraph / IDE / 浏览器 stack trace 的定位入口应按模块查找：

- `rust/crates/mnote-web/browser/document-editor-adapter-runtime.js`：文档页 host adapter entrypoint，子模块负责 pane、resource tab、mindmap host、slash position、Tiptap conversion 和 session runtime。
- `rust/crates/mnote-web/browser/sidebar-tree-runtime.js`：Sidebar entrypoint，子模块负责 workspace、page tree、filetree open/command/upload、attachment open、page settings 和 live apply；Page AI sidebar host 位于 `sidebar-page-ai-runtime.js`，owner 属于 `07-ai`。
- `rust/crates/mnote-web/browser/tree-shell-runtime.js`：debug/internal tree shell entrypoint，子模块负责 page tree、filetree、picker、render、DOM、icons 和 state。
- `rust/spikes/leptos-tiptap-spike/src/editor_runtime/`：tiptap island runtime 模块集合；根 `lib.rs` 只保留 wasm entrypoint、Leptos shell 信号编排和仍未稳定外置的薄壳。

对应完成记录见 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`。剩余专项边界不再回到 raw string 问题，而是分别由 `design/03-rust-web/reference/3-23-sidebar-local-folder-resource-runtime-followup-v1.md` 和 `design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md` 承接。

## 4. 文档页主链

### 4.1 入口

文档页入口的当前实现在 Rust mnote-web：

- 文档页壳 SSR：`web_shell.rs`（`document_page_shell`），直接输出 HTML + bootstrap JSON
- Page Aggregate 快照 API：`web_shell.rs`（`page_aggregate`）返回 `/api/page-aggregate/:id`
- 前端桌面/窗口面板布局：`web_shell.rs`（`build_document_panes_bootstrap_json`）

历史 wolai-frontend Next 文档页入口（已移入 `recycle/`）：
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/documents/page-aggregate-loader.ts`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/app/(app)/documents/[id]/page.tsx`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/documents/page-aggregate.ts`

### 4.2 文档壳（已迁移至 Rust SSR）

历史 React 文档壳组件（已随 wolai-frontend 移入 `recycle/`，不再作为当前实现）：
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/document-shell.tsx`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/document-content.tsx`

当前文档壳由 Rust mnote-web SSR 输出：
- `web_shell.rs` → `document_page_shell` 直接渲染 HTML shell，不在前端保留 React 文档壳 runtime。

### 4.3 默认编辑器 host（已迁移至 WASM island）

历史 React 编辑器 host（已移入 `recycle/`）：
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/editor-host-config.ts`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/editor-host.tsx`
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/leptos-tiptap-island-editor-host.tsx`

当前默认主编辑器是页面内 Leptos/WASM island，由 Rust mnote-web SSR 加载：
- WASM 产物：`rust/spikes/leptos-tiptap-spike/`
- 加载路由：`web_shell.rs` → `leptos_tiptap_manifest` / `leptos_tiptap_asset`

### 4.5 BlockNote 的当前位置

- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/blocknote-editor.tsx`

`BlockNote` 已随 wolai-frontend 移入 recycle，仅作为历史对照材料，不参与当前实现。

而不是默认主编辑器方向。

## 5. 当前编辑器与页面聚合关系

当前文档页已经开始消费统一的 `PageAggregateProjection`，但仍不能说“页面域已完全统一成 Rust 单一真源”。

当前真实状态是：

- 读取主链已优先消费 Rust `mnote.page_aggregate.v1` snapshot
- Page Aggregate 已输出 `blockDocument`、`blockProjectionVersion` 与 `projectionSource`
- 标题链路已开始与工作区树 canonical snapshot 对齐
- 正文默认由 `leptos-tiptap` island 编辑与保存
- 页面设置已有一部分进入 island 运行时语义
- `page_tree` / `pageSubtree` 已进入统一聚合入口
- 页面/块 AI tools 可通过 Page Aggregate block projection 读取、定位、dry-run、替换、插入和受限移动块；local-first 普通正文编辑不再要求走块工具，在线 / cloud / compat 场景才回到受控 mnote tool 写入。

2026-05-16 更新：以下四项已通过真实 3000 browser smoke 验证（证据见 `tmp/page-aggregate-*` 目录）：

- 标题写入后 Page Aggregate、页头、Breadcrumb、Sidebar、Page Tree、File Tree 一致性（`task110`）
- 正文保存后 `body.revision` / `conflictDetectionKey` / `blockDocument` 同步（`task-page-aggregate-body-sync-smoke`）
- 页面设置写入后 `layout.pageOptions` 与 island runtime DOM 同步，刷新后不退回（`task-page-aggregate-options-sync-smoke` / `task-page-aggregate-refresh-persistence-smoke`）
- Convex 不可用时返回 degraded error（503 + `x-error-code=convex_unavailable`），不返回伪 fixture（route 级负向测试）

仍未完成的关键点是：

1. Rust 侧已提供最小 `Page Aggregate` snapshot 和 block projection v1，但当前 block projection 仍主要从 `documents.content` / local markdown content 投影（`projectionSource=documents.content`），不是 EditorBlockDocument 原生落库完成态
2. 标题 / 正文 / 页面设置虽已收口到 `page.*` family 和 local-first 文件版本模型，但客户端仍保留 `PageAggregateClientState` reducer（混合 server snapshot / draft title / local content），页面域单一真源仍未完全闭环
3. AI 块工具继续作为复杂结构辅助；local-first 普通 Markdown 编辑主路径已经转为“授权文件引用 + agent 原生 patch/diff + watcher 同步”
4. Sidebar 仍通过 preferred snapshot（initial / query / tree_stream）做 freshness 选择，tree realtime live cache 未统一

因此当前正确表述应是：

> **文档页读取主链已进入 Rust-first `page aggregate` 过渡态，标题/正文/页面设置 smoke 已通过，但页面域单一真源（ClientState → Rust snapshot）与 tree realtime live cache 仍未闭环。**

## 6. 当前树域结构

### 6.1 Kernel projection 与 route

- `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/kernel.rs`

当前 Rust 已提供：

- `sidebar_tree`
- `page_tree`
- `file_tree`
- `subtree`
- `edges`
- `graph`

这些 route 说明树域 projection family 已经在 Rust 侧具备清晰边界。

### 6.2 树命令现状

- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/documents/tree-command-client.ts`
- `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/tree.rs`
- `/mnt/Data1T/mnote/rust/crates/storage-convex-bridge/src/mapping.rs`

当前树命令已经开始以 `tree.*` 为 preferred command name，例如：

- `tree.node.create`
- `tree.node.rename`
- `tree.subtree.move`

但兼容层仍广泛保留：

- `documents.create`
- `documents.title.update`
- `documents.move`

这说明 tree command cutover 已开始，但还没有完成。

### 6.3 树 realtime 现状

当前 Sidebar 已有：

- query snapshot
- tree stream
- preferred snapshot 选择

正式的 snapshot + delta 主链已经固定到 `mnote-web` 的 `/api/tree/events`，Next `/api/mnote-web/stream` 只保留 compat alias。

因此当前正确表述应是：

> **树域 realtime 主链由 Rust Web `/api/tree/events` 持有，前端只消费稳定 stream contract 与 projection。**

补充：

> **`3000` 主壳当前已不再通过 `/api/tree/projections/*` 额外维护第二条 runtime live fallback；snapshot / delta / resync 直接消费 `/api/tree/events` 载荷。**

### 6.4 Resource Tree / File Tree / Page Tree 三层模型

当前树域已建立三层语义（合同见 `design/04-tree-domain/done/4-24-*` 与 `design/05-editor-mainline/done/5-12-*`）：

- **Resource Tree**：长期 canonical 对象组织树，Rust kernel 持有语义。资源类型包括 page、mindmap、attachment、onlyoffice、code 等（`KernelObjectIdentity`、`KernelProjectionResourceKind` 已在 `core-protocol` 落地）。
- **File Tree**：Resource Tree 的主组织投影。展示页面文件夹、`{title}.md`（非 `index.md`）、mindmap、附件等资源。文件树行消费 Rust `/api/tree/projections/file` 或等价 projection，不在前端临时拼装第二真相。
- **Page Tree**：面向阅读/导航的快捷投影。只显示页面关系和导航语义，不拥有排序、父子、附件归属的最终真相。

关键规则：

- 文件树点击 mindmap 打开 mindmap object editor，不被 `{title}.md` 吞掉
- `{title}.md` 只代表页面正文（Page Aggregate body），mindmap / OnlyOffice / 附件是不同 object model
- 页面树不持有独立结构真相，只显示文档导航关系

## 7. Mindmap 与 OnlyOffice

### 7.1 Mindmap

当前 Mindmap 不再是系统中心，而是：

- `tree-first graph kernel` 的一种视图 / 编辑挂件

它仍有：

- 文档内嵌块形态
- 独立页面形态

但不应再被理解为对象真相层。

### 7.2 OnlyOffice

OnlyOffice 仍然是：

- 独立页面型编辑器

它不直接嵌入正文主编辑画布；正文中通常通过附件块跳转进入。

## 8. 当前最优先的架构收口

当前最优先的三条主线，不是继续大规模 UI 重写，而是：

### 8.1 Page Aggregate

目标：

- 让标题 / 页面设置 / 正文 / page tree 统一成同一组 page aggregate projection 与 command family
- 前端不在页面壳、island 外侧、Sidebar preferred snapshot 外再拼第二份页面真相

当前进度（2026-05-16）：

- ✅ 文档页读取主链已 Rust-first，TS builder 退出 runtime，Next compat 返回 410
- ✅ 标题单一真源 smoke 通过（`task110`）：页头/Breadcrumb/Sidebar/Page Tree/File Tree 一致
- ✅ 正文写入后 `body.revision` / `blockDocument` 同步 smoke 通过
- ✅ 页面设置写入后 `pageOptions` 同步与刷新持久化 smoke 通过
- ✅ local-first `page.body.write` / `/api/page-body/write` 与 `expectedFileVersion` 已成为本地正文写入主入口，`/api/documents/save` 降级为 compat adapter
- ✅ 本地 Markdown 图片 / 附件上传写入 sibling assets，并由真实浏览器 smoke 覆盖保存后刷新恢复
- ✅ Convex 不可用时返回 degraded error，不返回伪 fixture
- ⬜ cloud / compat block projection 继续减少 `documents.content` 后备；local-first 正文真相已转为 `.md` 文件投影
- ⬜ 客户端 `PageAggregateClientState` reducer 退役，页面域完全以 Rust snapshot 为单一运行时真相

对应设计稿：

- `/mnt/Data1T/mnote/design/05-editor-mainline/reference/5-5-page-aggregate-single-truth-alignment-v1.md`
- `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-6-page-aggregate-alignment-checklist-v1.md`
- `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`

### 8.2 Tree Command Cutover

目标：

- 让 `tree.*` 成为正式命令面
- `documents.*` 降为兼容层

对应设计稿：

- `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`

### 8.3 Tree Realtime Event Stream

目标：

- 让 snapshot + delta 正式成为树域实时主链
- 减少当前 query/refetch/freshness 补偿链的长期存在

对应设计稿：

- `/mnt/Data1T/mnote/design/03-rust-web/done/3-3-rust-web-tree-realtime-event-stream-v1.md`

### 8.4 Page / Block AI Tooling

目标：

- 让 local-first 页面 AI 默认走“页面定位 -> 授权文件引用 -> agent 原生 patch/diff -> 前台同步”
- 把 `mnote.page.save` 固定为页面级兜底写入工具，不再代表普通正文编辑默认入口
- 把 `mnote.doc.*` / `mnote.block.*` 收口为兼容 / cloud / 复杂结构辅助工具
- 补齐 `scope=selection`、白名单目录权限、changed_files/diff 审计、前台同步刷新矩阵

当前进度（2026-05-19，按 `2-2` 完成态更新）：

- ✅ 页面 AI 与 ACP runtime 已能承载本地优先方向
- ✅ `page_ai_workflow` 已在 local source 下退出主路径
- ✅ legacy tool facade（`mnote.doc.*` / `mnote.block.*`）已可作为兼容 / cloud / 复杂结构辅助层读取和写入
- ✅ 本地优先设计已经收口为 VSCode-like 运行模型：页面定位 + 白名单目录 + agent 直改文件 + tiptap 同步显示
- ✅ 页面 AI 默认输入已收口到 `currentFile + selection + allowedRoots / aiAccessScope`
- ✅ legacy ACP runtime 曾显式带白名单目录运行；当前主线转向 OpenHub / native agent scope
- ⬜ MNote 回收 changed_files / diff 审计
- ⬜ `scope=selection`、`format=page_xml/text` 继续作为结构化辅助输出，不作为普通 Markdown 编辑必需路径
- ⬜ tool manifest annotations 继续补齐 destructive / requiresApproval 等高级语义
- ⬜ **Phase C（设计冻结，不实施）**：`StreamApplyController` + `ReviewSession` + `GhostTextOverlay`（流式 apply + suggest/review）
- ⬜ stale revision / idempotency 重放保护（已有 revision 乐观锁覆盖，补端到端 smoke）

关键原则（2026-05-18 口径更新）：

- **local-first 主路径**：当前页面解析成授权 `.md` 文件，OpenHub / native agent 在白名单目录内直接读写，MNote 负责权限、审计和前台同步
- **local-first 文件编辑模型**：普通 Markdown 编辑走“页面定位 + 授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”；MNote 不提供 local-first 默认普通 Markdown 编辑工具，`mnote.doc.markdown_edit` 只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback，`mnote.doc.apply_block_ops` 仅作为块级结构性辅助。CLI Main Lark Doc 只能作为 skill/workflow 纪律的有限参考，不作为当前编辑架构主参考。
- `mnote.block.*` 降级为结构性辅助（拖拽排序、精确块删除等），不删除
- 当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应继续退役
- cloud / remote agent 无法直接访问本地文件时，不能静默回退到 `mnote.doc.markdown_edit`；必须通过显式 cloud source / remote fallback / compat 边界和权限设计承接
- Markdown 既是 AI 编辑格式也是人类可读格式，不需要 XML 中间层
- 流式 apply + suggest/review（参考 BlockNote AI 的 `StreamToolExecutor` + `suggestChanges`）仅作为 Phase C 设计冻结，当前不实施

对应设计稿：

- `/mnt/Data1T/mnote/design/old/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`（历史执行记录；不再作为 active 入口）
- `/mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md`
- `/mnt/Data1T/mnote/design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`
- `/mnt/Data1T/mnote/design/old/07-ai/process/7-14-local-first-ai-markdown-editing-convergence-v1.md`（历史回收稿；不再作为当前实现依据）

### 8.5 Knowledge RAG / LightRAG

目标：

- 把资料库 ingestion、检索、引用和跨文档问答统一交给 LightRAG provider；OpenHub / native agent 只通过 MNote provider-neutral tool facade 调用。
- MNote 只保留 source registry、allowed roots / 权限、FileTree 灯号、资料库设置 UI、provider status UI、citation/open-reference 映射和 agent tool facade。
- LiteParse、旧 OCR sidecar、旧 evidence search / local-index agent tools 作为历史迁移和 recycle 边界，不再作为默认 fallback。

当前进度（2026-07-03）：

- ✅ LightRAG 是当前默认知识库 provider，OpenHub / native agent 是 Page AI 执行与交互主链。
- ✅ MNote `source registry` 记录 `workspaceId/rootUri/sourcePath/sourceHash/providerDocId/stale/deletedAt/status`，FileTree 灯号从 registry 映射为已索引 / 正在索引 / 失败 / 未索引；历史 `lightRagDocId` 只作为兼容字段。
- ✅ WeKnora 仅保留为历史设计、参考实现或备用 provider 边界，不再作为新增主路径。
- ✅ Agent 默认使用 `mnote.knowledge_rag.status/query/open_reference`，不再暴露旧 `mnote.evidence.*` 作为资料库检索主路径。

对应设计稿：

- `/mnt/Data1T/mnote/design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md`
- `/mnt/Data1T/mnote/design/10-review/done/20-post-lightrag-runtime-hardening-checklist-v1.md`

### 8.6 定向 Bug Hunt 与质量基线

目标：

- 围绕已知架构风险做定向排查，而非泛泛"找 bug"

优先关注：

- Page Aggregate 回流不一致
- AI 块写入 conflict / stale revision
- File Tree `{title}.md` 与 page title 同步
- tree stream resync / 双浏览器一致性
- debug / compat / fallback 是否混入首屏主链

已有 smoke 体系（`scripts/` 目录）：

- `scripts/TESTING_REFERENCE.md`：当前 smoke 分类、默认基线和退役脚本说明

- `task110-page-title-single-truth-smoke.js`：标题全链路一致性
- `task-page-aggregate-body-sync-smoke.js`：正文写入后 Page Aggregate 同步
- `task-page-aggregate-options-sync-smoke.js`：页面设置写入后同步
- `task-page-aggregate-refresh-persistence-smoke.js`：刷新持久化
- `task123-rust-web-tree-live-stream-consumer-smoke.js`：tree realtime 消费
- `task169-mindmap-realtime-smoke.js`：mindmap 隔离与持久化
- `task179-tree-create-delete-no-reload-smoke.js`：树操作无刷新

## 9. 当前不该再用的旧口径

下面这些说法现在都不准确：

- “默认文档页仍然是 `BlockNoteEditor`”
- “主编辑器还没切到页面内 Leptos island”
- “当前最优先是继续证明 `leptos-tiptap` 能不能跑”
- “当前最优先是先做树域 UI 重构”
- “Rust Web 还只是实验，没有接真实页面链路”
- “页面 AI 编辑必须经过 Hermes agent，没有快路径”
- “WeKnora 是当前默认知识库 provider。”
- “Hermes / Reasonix 是当前 Page AI 默认 agent runtime。”
- “页面 AI 编辑必须经过 MNote 专用工具才能改普通 Markdown”

当前真正的卡点已经从“能不能跑”变成：

> **管理员目录授权、文件版本冲突合并、agent diff 审计、本地轻量搜索 / 分享 / 同步如何产品化；知识库 RAG 主路径为 LightRAG + OpenHub tool facade，WeKnora 仅备用；Page Aggregate ClientState、projection / command / realtime 兼容链如何继续瘦身。**

## 10. Control-plane 后端架构与运行配置

### 10.1 后端架构

当前 control-plane 存储后端已从单一 `rusqlite` 抽象为 `ControlPlaneStore` trait；mnote-web 运行时只允许 Turso/libSQL 系列后端：

```text
ControlPlaneStore trait
  ├── TursoControlPlaneStore      mnote-web 运行时后端
  │   ├── libsql-local            默认本地运行模式，无云依赖
  │   ├── turso-remote            真实 Turso dev/prod DB
  │   ├── turso-local-replica     本地 replica + remote sync
  │   └── turso-synced            libSQL synced database
  └── SqliteControlPlaneStore     仅限 control-plane-admin 迁移/导出和 Rust 测试隔离
```

### 10.2 环境变量

```text
MNOTE_CONTROL_PLANE_BACKEND=libsql-local|turso-remote|turso-local-replica|turso-synced
MNOTE_TURSO_LOCAL_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-libsql.db
MNOTE_TURSO_DATABASE_URL=libsql://...
MNOTE_TURSO_AUTH_TOKEN=...
MNOTE_TURSO_LOCAL_REPLICA_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-replica.db
MNOTE_TURSO_SYNCED_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-synced.db
MNOTE_TURSO_SYNC_INTERVAL_MS=5000
```

### 10.3 默认策略

- **普通开发/desktop/prod runtime**：默认 `libsql-local`，不再读取 `MNOTE_CONTROL_PLANE_DB_PATH`。
- **云端验证**：显式使用 `turso-remote`、`turso-local-replica` 或 `turso-synced`，并从本机私有 env/secret manager 加载 URL/token。
- **SQLite 边界**：`sqlite` 不能作为 mnote-web runtime backend；只允许 `control-plane-admin` 做迁移源、导出备份格式和 Rust 单测隔离。

### 10.4 未迁移数据（第一阶段不迁）

- 本地 `.md` 页面正文：仍是 local-first 正文真相。
- 本地附件、图片、mindmap、OnlyOffice 文件。
- `.mnote/index/evidence.sqlite`：已从当前主线退役。
- LightRAG 自身存储、WeKnora / OpenHub 自身存储。
- OpenHub 自身 SQLite 会话库（第二阶段单独评估）。

### 10.5 备份与恢复策略

SQLite 不再作为运行时回滚后端。需要离线留档或人工核验时，用 `control-plane-admin export-target-to-sqlite` 导出备份；恢复方向应是从备份重新导入 libSQL/Turso 目标库，而不是让 mnote-web 改回 SQLite 运行。

### 10.6 测试与脚本纪律

- 所有 smoke 和脚本**不得直接 `sqlite3` CLI 写 production control-plane DB**。
- 需要 seed 数据时必须走 Rust API / 测试 seed endpoint / `scripts/lib/control-plane-dev-seed.js` 或 `scripts/lib/control-plane-test-env.js` helper。
- 禁止通过临时文件覆盖 `MNOTE_CONTROL_PLANE_DB_PATH` 绕过真实 store。
- 相关设计：`design/02-convex-rust-long-term-architecture/process/2-9-turso-control-plane-cutover-v1.md`