Agent Board
b798f628ee
Persist PageTree expand state via control-plane view-state and align chevron/DOM with restored expansion; keep Sidex-style shallow page-tree scan and drop the unused recursive scanner that only added cargo noise. Add password vault workbench routes/runtime/skill/CLI, split page_ai_pi into a module package, and retire Hermes/ACP/OpenHub recycle + root harness evidence from the index while gitignoring recycle and local diag dumps. Archive superseded design/bugs docs under old/, point architecture at ARCHITECTURE.md, and refresh smokes for Pi S1–S7, vault, and editor regressions so the working tree can stay clean.
176 lines
8.8 KiB
Markdown
176 lines
8.8 KiB
Markdown
# 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` 为兼容指针，内容以本文为准。
|