mnote/ARCHITECTURE.md

# MNote 架构

> 更新时间：2026-07-19  
> 本文只描述**当前**产品形态、运行分层与收口缺口。历史迁移、退役路径与 changelog 不在此展开；协作规则见 `AGENTS.md`，执行 checklist 见 `design/`。

## 1. 产品形态

```text
MNote = VSCode 简化版工作区
      + tiptap Markdown 编辑器（leptos-tiptap island）
      + Pi Rust Page AI
      + LightRAG 知识库
      + simplemindmap / OnlyOffice 插件
      + Wolai 主题 Web 壳
      + Turso/libSQL 鉴权控制面
```

| 层 | 当前真源 / Owner |
|----|------------------|
| 工作区数据 | 本地 workspace folder；页面正文为 `.md` |
| 树 / 资源语义 | Rust kernel（`core-protocol` + `bridge-runtime`） |
| Web 入口 | `mnote-web`，公开端口 **3000** |
| 控制面 | Turso/libSQL：auth、membership、share、sync state、AI policy / Pi scope |
| Page AI | Pi Lab（`/api/page-ai/pi/*`），默认唯一产品级入口 |
| 知识库 | LightRAG + `mnote.knowledge_rag.*` facade |
| 编辑投影 | Page Aggregate（`mnote.page_aggregate.v1`）；tiptap 为显示层，非对象真源 |

一句话：

> **本地文件夹是数据真相，Rust kernel 持有语义，Turso/libSQL 持有控制面，前端只消费稳定 projection。**

## 2. 分层

### 2.1 Workspace / Storage

- 默认 source：`local_folder`  
  受管根：`/mnt/Data1T/Mnote_data/users/<actor>/workspaces/my-space/`
- 管理员通过控制面授权可读写目录；普通用户不能自助全盘读写
- 页面内上传默认写入 sibling assets（如 `README.assets/image.png`），正文存相对 Markdown 链接
- 本地 `.md` / 附件 / mindmap / OnlyOffice **不**迁入 control-plane DB

### 2.2 Kernel / Projection

- `core-protocol`：树、资源、页面、AI access scope、page body write 等协议
- `bridge-runtime` + `mnote-web`：LocalFS（及显式 cloud/compat source）→ 稳定 projection / command
- 前端只消费：`file_tree`、`page_tree`、`page_aggregate`、tree command result、少量 editor runtime payload

树域三层：

| 层 | 角色 |
|----|------|
| Resource Tree | kernel 对象组织真源（page / mindmap / attachment / onlyoffice / …） |
| File Tree | 主组织投影；页面正文行为 `{title}.md` |
| Page Tree | 导航投影；不持有结构真相 |

正式命令面：`tree.*`（如 `tree.node.create` / `rename` / `tree.subtree.move`）。`documents.*` 仅为兼容层。

### 2.3 Web Shell / Editor

- Owner：`mnote-web`（Rust SSR + browser runtime）
- 文档页默认编辑 host：页面内 `leptos-tiptap` island  
  - browser JS：`rust/crates/mnote-web/browser/*.js`  
  - island：`rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`  
  - `layout.rs` / `tree.rs` / `web_shell.rs` 只做 SSR / bootstrap / route / asset 注入
- 正文保存主入口：`page.body.write` / `/api/page-body/write`（带文件版本）；`/api/documents/save` 为 compat
- Watcher：clean editor 自动刷新；dirty editor 进入冲突态，不静默覆盖
- Realtime：WS 主链 `/api/realtime/ws` + SSE fallback `/api/tree/events`（snapshot / delta / resync）
- Mindmap：tree-first 的视图 / 挂件，非对象真源  
- OnlyOffice：独立页面型编辑器，经附件/资源跳转进入

### 2.4 Page Aggregate

- 读取主链：Rust `mnote.page_aggregate.v1` snapshot（`/api/page-aggregate/:id`）
- 输出含 `blockDocument` / `blockProjectionVersion` / `projectionSource`
- 本地正文真相是 `.md`；aggregate 是投影，不是第二份正文库
- 仍属过渡态：block projection 多从 markdown content 投影；客户端仍有 `PageAggregateClientState` reducer

### 2.5 Page AI（Pi Rust）

```text
当前页 → 真实 .md
  → AiAccessScope / allowed roots / selection
  → Pi Rust Page AI（/api/page-ai/pi/*）
  → agent 原生 patch/diff 写文件
  → watcher / BufferStore / refresh → Page Aggregate + tiptap
```

- Pi session 元数据 / run / tool event 默认落 control-plane；Pi JSONL 仅为 runtime 工作副本
- `mnote.doc.*` / `mnote.block.*` / `mnote.page.*`：cloud / remote / compat / 复杂结构辅助
- `/api/page-ai/block-edit-workflow`：非 local-first 默认正文路径
- 流式 apply + suggest/review：**Phase C 冻结，当前不实施**
- 遗留 ACP / Hermes / Reasonix / OpenCode：兼容面，默认主壳不注入；不得新增能力；退役须原子覆盖 sidebar、route、runtime、wrapper（`hermes_tools` 中 provider-neutral 契约按实际消费者保留）

### 2.6 Knowledge RAG（LightRAG）

- 资料 ingestion / query / citation / open-reference 主路径：LightRAG
- MNote 只维护 source registry、权限、FileTree 灯号、status UI、citation 映射、tool facade
- Agent 工具：`mnote.knowledge_rag.status` / `query` / `open_reference`
- 不把 provider storage 当用户正文真相；不复制图谱/chunk 为第二套索引

### 2.7 Control-plane

```text
ControlPlaneStore
  ├── TursoControlPlaneStore   mnote-web 唯一运行时
  │   ├── libsql-local         默认
  │   ├── turso-remote
  │   ├── turso-local-replica
  │   └── turso-synced
  └── SqliteControlPlaneStore  仅 admin 迁移/导出与测试隔离
```

| 变量 | 用途 | 默认 |
|------|------|------|
| `MNOTE_CONTROL_PLANE_BACKEND` | 后端模式 | `libsql-local` |
| `MNOTE_TURSO_LOCAL_PATH` | local 文件 | `/mnt/Data1T/Mnote_data/control-plane/control-plane-libsql.db` |
| `MNOTE_TURSO_DATABASE_URL` | remote URL | — |
| `MNOTE_TURSO_AUTH_TOKEN` | remote token | — |
| `MNOTE_TURSO_LOCAL_REPLICA_PATH` | replica 路径 | `…/control-plane-replica.db` |
| `MNOTE_TURSO_SYNCED_PATH` | synced 路径 | `…/control-plane-synced.db` |
| `MNOTE_TURSO_SYNC_INTERVAL_MS` | sync 间隔 | 未设置 |

- 只存元数据：users、sessions、workspaces、directory grants、share、sync state、AI policy/runtime、audit
- `sqlite` 不得作为 mnote-web runtime；启动链拒绝
- 备份：`control-plane-admin export-target-to-sqlite` → 再导入 libSQL/Turso，不回退 SQLite 运行

### 2.8 代码入口

| 路径 | 职责 |
|------|------|
| `rust/crates/core-protocol/` | Kernel 类型与 projection 协议 |
| `rust/crates/bridge-runtime/` | query / command / traversal |
| `rust/crates/mnote-web/` | 3000 gateway、SSR shell、API、compat、realtime |
| `rust/crates/mnote-web/browser/` | Sidebar / FileTree / document adapter / Page AI host JS |
| `rust/spikes/leptos-tiptap-spike/` | 文档页默认编辑 island |
| `wolai-backend/app/` | 辅助后端 / 异步处理 |
| `src/components/onlyoffice/` | OnlyOffice 静态与插件资源 |

`recycle/` 为历史回收区，不作为当前实现依据。

## 3. 当前收口缺口

阶段：local-first **MVP 后**。底座与主路径已立；重点是统一与产品化，不是扩 compat 或旧主链。

1. **WorkspacePath / ObjectIdentity** — 路径、identity、资源归属统一到 kernel contract  
2. **DocumentBuffer / BufferStore** — runtime 已有；多 tab 仲裁与冲突 UI 体验收口  
3. **Page Aggregate** — 瘦身 compat join；退役 ClientState 混合 reducer，以 Rust snapshot 为单一运行时真相  
4. **tree command context** — 菜单 / 快捷键 / AI enablement 同一 context，勿各处硬编码  
5. **tree live cache** — watcher + WS/SSE 收进同一 cache，减补偿链  
6. **管理员目录授权 UI** — grant / access-policy 可管理  
7. **冲突合并 UI** — 接受磁盘 / 保留编辑器 / diff 合并  
8. **agent 写入审计** — changed files、diff、run id、actor 本地落盘，可同步控制面  
9. **本地轻量搜索** — workspace 全文 / 反链 / 标签，不依赖 cloud search  
10. **分享与同步闭环** — share grant ≠ 本机 filesystem root；控制面不可用时不扩权限  
11. **插件资源模型** — mindmap / office 作为 Resource Tree 对象  
12. **遗留兼容面退役** — ACP/Hermes/Reasonix/OpenCode 原子删除；Convex 仅显式 cloud/compat  

执行稿：`design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md`

## 4. 设计索引（当前）

| 主题 | 文档 |
|------|------|
| 总收口 | `design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md` |
| tree-first kernel | `design/01-tree-first-graph-kernel/reference/1-tree-first-graph-kernel-v1.md` |
| local-first + control-plane | `design/02-convex-rust-long-term-architecture/done/2-2-*.md`、`process/2-9-turso-control-plane-cutover-v1.md` |
| Page Aggregate | `design/05-editor-mainline/reference/5-5-*.md`、`done/5-6-*.md` |
| AI 文件编辑 | `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md` |
| LightRAG | `design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md` |
| tree command / realtime | `design/04-tree-domain/done/4-6-*.md`、`design/03-rust-web/done/3-3-*.md`、`3-14-*.md` |
| Resource / File / Page Tree | `design/04-tree-domain/done/4-24-*.md` |

---

`CURRENT_ARCHITECTURE.md` 为兼容指针，内容以本文为准。