lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b798f628ee5a9da86c009ea1626be9a37c8c75ef
mnote/ARCHITECTURE.md
T
Agent Board b798f628ee chore: land tree view-state, vault, Pi module split, and repo hygiene 
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.
2026-07-21 05:13:05 +08:00

8.8 KiB
Raw Blame History

MNote 架构

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

1. 产品形态

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）

当前页 → 真实 .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

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 为兼容指针，内容以本文为准。

Reference in New Issue View Git Blame Copy Permalink