lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a40fa25ae6889df560e3f72f9a90a312b5d9ed14
mnote/ARCHITECTURE.md
T
Agent Board 262e66b02e feat: purge legacy agent hosts and land vault Chrome extension path 
Retire ACP/Hermes/OpenCode surfaces and rename hermes_tools to
mnote_agent_tools so Page AI stays on Pi Lab only. Add Chrome vault
extension + extension token route, pre-release purge design, and soft-retire
legacy smokes for the small-group production cut.
2026-07-25 14:25:37 +08:00

7.1 KiB
Raw Blame History

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. 产品形态

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）

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

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

Reference in New Issue View Git Blame Copy Permalink