mnote/ARCHITECTURE.md

# MNote 架构

> 更新时间：2026-07-25  
> 本文只描述**当前**产品形态与运行分层。协作规则见 `AGENTS.md`；预发瘦身见 `design/10-review/process/22-pre-release-legacy-purge-v1.md`；产品化收口见 `design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md`。

## 1. 产品形态

```text
MNote = VSCode 简化版工作区
      + tiptap Markdown 编辑器（leptos-tiptap island）
      + Pi Lab Page AI
      + LightRAG 知识库
      + simplemindmap / OnlyOffice
      + Vault 密码箱
      + Wolai 主题 Web 壳
      + libSQL 控制面（默认 libsql-local）
```

| 层 | 当前真源 / Owner |
|----|------------------|
| 工作区数据 | workspace folder；页面正文为 `.md` |
| 树 / 资源语义 | Rust kernel（`core-protocol` + `bridge-runtime`） |
| Web 入口 | `mnote-web`，公开端口 **3000** |
| 控制面 | libSQL/Turso store：auth、membership、share、sync state、AI policy / Pi scope |
| Page AI | Pi Lab（`/api/page-ai/pi/*`） |
| 知识库 | LightRAG + `mnote.knowledge_rag.*` |
| 密码箱 | Vault（store + web routes + extension/agent token） |
| 编辑投影 | Page Aggregate（`mnote.page_aggregate.v1`）；tiptap 为显示层 |

一句话：

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

### 1.1 云首发

- 与本地同栈：Pi Lab、LightRAG、OnlyOffice、Vault、树/文档主链。
- 控制面推荐 **`libsql-local`**：服务器上独立文件库，不依赖外部 Turso 账号；运维简单、可备份导出。
- `turso-remote` / replica：可选增强，不是首发前置条件。
- 部署包不含 `reference-code/`、`recycle/`、debug shell 默认路由。

## 2. 分层

### 2.1 Workspace / Storage

- 默认 source：`local_folder`（本机或服务器磁盘路径）
- 管理员通过控制面授权可读写目录
- 页面内上传默认 sibling assets；正文存相对 Markdown 链接
- `.md` / 附件 / mindmap / OnlyOffice **不**迁入 control-plane DB

### 2.2 Kernel / Projection

- `core-protocol`：树、资源、页面、AI access scope、page body write 等协议
- `bridge-runtime` + `mnote-web`：LocalFS → 稳定 projection / command
- 前端消费：`file_tree`、`page_tree`、`page_aggregate`、tree command result

| 层 | 角色 |
|----|------|
| Resource Tree | kernel 对象组织真源 |
| File Tree | 主组织投影；页面正文 `{title}.md` |
| Page Tree | 导航投影；不持有结构真相 |

正式命令面：`tree.*`。

### 2.3 Web Shell / Editor

- Owner：`mnote-web`（Rust SSR + browser runtime）
- 文档页：`leptos-tiptap` island + `browser/*.js`
- 正文保存：`page.body.write` / `/api/page-body/write`（文件版本）
- Watcher：clean 自动刷新；dirty 冲突态，不静默覆盖
- Realtime：WS `/api/realtime/ws` + SSE `/api/tree/events`
- Mindmap：视图/挂件；OnlyOffice：独立编辑器经资源进入

### 2.4 Page Aggregate

- 读取：`mnote.page_aggregate.v1`（`/api/page-aggregate/:id`）
- 本地正文真相是 `.md`；aggregate 是投影

### 2.5 Page AI（Pi Lab）

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

- Session / run / tool event 默认落 control-plane；Pi JSONL 为 runtime 工作副本
- Agent 工具 HTTP：`/api/mnote/tools/{manifest,call,audit}`
- 工具实现目录：`rust/crates/mnote-web/src/mnote_agent_tools/`
- Pi 直接依赖其中 `knowledge_rag` 的 agent 输出整形，以及 skill pack（含 `mnote-vault`）
- 流式 apply + suggest/review：Phase C 冻结

### 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` / `section_context` / `open_reference`

### 2.7 Vault

- 服务端 store + `/api/vault/*` 工作台；extension/agent 经 capability token
- 策略与 agent 用法：`/home/lix/.agent-infra/vault-policy.md`、`$mnote-vault`

### 2.8 Control-plane

```text
ControlPlaneStore
  └── TursoControlPlaneStore   mnote-web 唯一运行时
      ├── libsql-local         默认 / 云首发推荐
      ├── turso-remote         可选托管
      ├── turso-local-replica
      └── turso-synced
```

| 变量 | 用途 | 默认 |
|------|------|------|
| `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 | — |

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

### 2.9 代码入口

| 路径 | 职责 |
|------|------|
| `rust/crates/core-protocol/` | Kernel 类型与 projection 协议 |
| `rust/crates/bridge-runtime/` | query / command / traversal |
| `rust/crates/mnote-web/` | 3000 gateway、SSR、API、realtime |
| `rust/crates/mnote-web/browser/` | Sidebar / FileTree / document / Page AI host |
| `rust/spikes/leptos-tiptap-spike/` | 文档页编辑 island |
| `rust/crates/mnote-vault-core/` | Vault 核心 |
| `src/components/onlyoffice/` | OnlyOffice 静态资源 |

## 3. 当前收口缺口

阶段：local-first **MVP 后**；重点是统一与产品化，以及预发前去掉非首发代码面。

1. **WorkspacePath / ObjectIdentity** — 路径与 identity 统一到 kernel  
2. **DocumentBuffer / BufferStore** — 多 tab 仲裁与冲突 UI  
3. **Page Aggregate** — 以 Rust snapshot 为单一运行时真相  
4. **tree command context** — 菜单 / 快捷键 / AI enablement 同一 context  
5. **tree live cache** — watcher + WS/SSE 收进同一 cache  
6. **管理员目录授权 UI**  
7. **冲突合并 UI**  
8. **agent 写入审计**  
9. **本地轻量搜索**  
10. **分享与同步闭环**  
11. **插件资源模型** — mindmap / office 作为 Resource Tree 对象  
12. **预发瘦身** — 删除非 Pi 的 agent 宿主与巨型兼容网关；工具包重命名；见 `22-pre-release-legacy-purge-v1.md`

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

| 主题 | 文档 |
|------|------|
| 预发瘦身 | `design/10-review/process/22-pre-release-legacy-purge-v1.md` |
| 总收口 | `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` |
| control-plane | `design/02-convex-rust-long-term-architecture/process/2-9-turso-control-plane-cutover-v1.md` |
| Page Aggregate | `design/05-editor-mainline/` |
| 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` |
| Vault | `design/12-vault/` |

---

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