mnote/CURRENT_ARCHITECTURE.md

# 当前完整架构

> 更新时间：2026-06-28
>
> 范围：`/mnt/Data1T/mnote` 当前可见实现、local-first MVP 后阶段主线口径、历史退役边界和后续功能缺口。
>
> 2026-07-03 口径更新：当前 runtime 已收口为 OpenHub / native agent + LightRAG + Turso/libSQL。知识库与 Page AI 融合方向以 LightRAG + OpenHub 为准；WeKnora 仅保留为历史设计、参考实现或可选备用 provider 边界，Hermes / Reasonix 仅保留 legacy/debug/外部工作流边界。旧 `/api/hermes/*`、`hermes_tools/*`、ACP runtime 命名属于历史命名或迁移中的兼容层，不代表当前产品定义。

## 1. 当前产品形态

当前项目口径固定为：

> **MNote = VSCode 简化版工作区 + tiptap 的 Markdown 前端编辑器 + OpenHub + LightRAG AI + simplemindmap / office 插件 + Wolai 主题 Web 壳 + 鉴权控制面。**

这意味着：

- 初步 MVP 已建立，后续不是继续证明 Rust Web、local-first 或 tiptap island 是否成立，而是收紧底座、减少 compat、补齐产品化闭环。
- 本地 workspace folder 是早期产品默认数据真相。
- 本地 `.md` 文件是页面正文真相；Page Aggregate、tiptap state、AI context 都是投影或工作副本。
- Rust kernel / projection / command 持有树、页面、资源和权限语义。
- tiptap 是 Markdown 的前端显示与交互层，不是 agent 的主工作面。
- OpenHub / native agent 默认应像 VSCode 中的 agent 一样，在授权目录白名单内用自身 patch / diff / 文件编辑能力修改文件。
- LightRAG + OpenHub 是当前默认知识库与 Page AI 融合方向；MNote 负责 source registry、权限、FileTree 灯号、dashboard/status UI 和 citation/open-reference 映射。WeKnora 仅保留为历史设计、参考实现或备用 provider 边界。
- Turso/libSQL control-plane 是默认 auth、membership、share grants、sync state、AI policy、OpenHub scope / AI policy 控制面；Convex / 服务端不再是默认正文、附件、AI 会话全文主存储，也不再是默认控制面，只保留历史迁移源、显式 cloud source、compat 和 sync replica 边界。旧 ACP/Hermes runtime session 属于迁移兼容层。

上位设计已完成并迁入：

- [2-2 local-first workspace 与 Convex 控制面降级方案](/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md)
- [2-8 Convex 替换为 Rust SQLite 控制面](/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/done/2-8-convex-replace-with-rust-sqlite-control-plane-v1.md)
- [2-9 Turso / libSQL 控制面切换](/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/process/2-9-turso-control-plane-cutover-v1.md)

## 2. 当前分层

### 2.1 Workspace / Storage

- `local_folder` 是默认 source：`/mnt/Data1T/Mnote_data/users/<actor>/workspaces/my-space/` 是受管“我的空间”默认根。
- 管理员通过控制面授权用户可读写目录；普通用户不能自助获得全盘读写。
- 上传到本地 Markdown 页面时，图片和附件默认写入 sibling assets，例如 `README.assets/image.png`，正文保存相对 Markdown 链接。
- Convex source 仍可作为 cloud / compat / sync replica 或历史迁移源，但新增功能不能默认把 `documents.*`、`mediaAssets.*`、`aiSessions.*` 当主存储，也不能把根 Convex functions 重新作为默认控制面。

### 2.2 Rust Kernel / Projection

- `core-protocol` 定义树、资源、页面、AI access scope、page body write 等协议语义。
- `bridge-runtime` 和 `mnote-web` 负责把 LocalFS / Convex / future sync source 归一成稳定 projection 与 command。
- 前端只消费 `file_tree`、`page_tree`、`page_aggregate`、tree command result 和少量 editor runtime payload。

### 2.3 Web Shell / Editor

- `mnote-web` 是当前 3000 owner；Next / React 前端已退入 `recycle/`，只作为历史参考或 island bundle source。
- 文档页默认编辑 host 是页面内 `leptos-tiptap` island。
- 前端 runtime 已完成第一轮模块级拆分：浏览器 JS 功能默认从 `rust/crates/mnote-web/browser/*.js` 定位，tiptap island 行为默认从 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs` 定位；`layout.rs` / `tree.rs` / `web_shell.rs` 主要保留 SSR/bootstrap/route/asset 注入职责，不再作为大型 raw string 功能入口。
- local source 正文保存主入口已收口到带文件版本的 `page.body.write` / `/api/page-body/write`；`/api/documents/save` 只作为 compat adapter。
- 文件 watcher 发现 agent / 外部编辑器写入后，clean editor 自动刷新，dirty editor 进入冲突态，不静默覆盖。

### 2.4 AI Runtime

- local-first 普通 Markdown 编辑主路径是：

```text
当前页面定位到真实 .md 文件
  -> MNote 计算登录用户 allowed roots / current file / selection
  -> OpenHub / native agent 在白名单目录内运行
  -> agent 使用自身 patch / diff / 文件编辑能力写文件
  -> MNote watcher / refresh 同步 Page Aggregate 与 tiptap
```

- `mnote.doc.fetch`、`mnote.doc.markdown_edit`、`mnote.doc.apply_block_ops`、`mnote.block.*` 和 `mnote.page.*` 保留为 cloud / remote agent / compat / 复杂结构辅助工具。
- `/api/page-ai/block-edit-workflow` 不再作为 local-first 普通正文编辑主路径。
- AI session 全文在 local source 下默认写入 `ai-sessions/private/*.jsonl` 或 `ai-sessions/shared/<share-id>/*.jsonl`；OpenHub scope / AI policy 默认落到 Turso/libSQL control-plane；旧 ACP/Hermes runtime session 仅为迁移兼容层；Convex 只作为显式 legacy/cloud metadata / audit / sync replica 边界。

### 2.5 Knowledge RAG / LightRAG

- 知识库问答、资料 ingestion / query / citation / open-reference 当前主线为 LightRAG + OpenHub tool facade。
- MNote 不复制 provider 图谱或 chunk，不把 provider storage 当用户正文真相；原始 source 仍属于 local-folder / Resource Tree。
- MNote 维护 provider-neutral source registry，用于映射 `workspaceId/rootUri/sourcePath/sourceHash/providerDocId/stale/deletedAt/status`；历史 `lightRagDocId` 字段只作为兼容字段。
- FileTree 的资料库灯号来自 source registry：绿灯已索引、黄灯正在索引或删除提交中、红灯失败 / 过期、无灯未索引或已移除。
- LightRAG 相关 dashboard、status bridge、source registry 和 MCP bridge 是当前默认 provider 边界；WeKnora 仅作为备用 provider / 历史设计参考，不得被新增能力假设为默认存在。
- Agent 只通过 `mnote.knowledge_rag.status/query/open_reference` 访问知识库；旧 LiteParse、OCR sidecar、`mnote.evidence.*` 与本地资料索引工具已退役为历史 / recycle 边界。
### 2.6 Control-plane 后端

当前 control-plane 存储后端已抽象为 `ControlPlaneStore` trait；mnote-web 运行时只允许 Turso/libSQL 系列后端：

- **TursoControlPlaneStore**（`libsql`）：mnote-web 运行时后端，支持 local libSQL、remote URL + token、local replica + sync、synced database。
- **SqliteControlPlaneStore**（`rusqlite`）：仅用于 `control-plane-admin` 迁移/导出和 Rust 测试隔离，不再作为 mnote-web runtime fallback。
- 启动时通过 `MNOTE_CONTROL_PLANE_BACKEND` 选择；默认 `libsql-local`，显式 `sqlite` 会被 mnote-web/dev-hot/desktop-hot/prod 启动链拒绝。

环境变量：

| 变量 | 用途 | 默认值 |
|------|------|--------|
| `MNOTE_CONTROL_PLANE_BACKEND` | 后端模式（libsql-local/turso-remote/turso-local-replica/turso-synced） | `libsql-local` |
| `MNOTE_TURSO_LOCAL_PATH` | libSQL local 文件路径 | `/mnt/Data1T/Mnote_data/control-plane/control-plane-libsql.db` |
| `MNOTE_TURSO_DATABASE_URL` | Turso remote URL | — |
| `MNOTE_TURSO_AUTH_TOKEN` | Turso 认证 token | — |
| `MNOTE_TURSO_LOCAL_REPLICA_PATH` | Turso local replica 路径 | `/mnt/Data1T/Mnote_data/control-plane/control-plane-replica.db` |
| `MNOTE_TURSO_SYNCED_PATH` | libSQL synced 本地路径 | `/mnt/Data1T/Mnote_data/control-plane/control-plane-synced.db` |
| `MNOTE_TURSO_SYNC_INTERVAL_MS` | replica/synced 同步间隔 | 未设置 |

第一阶段**只迁移 control-plane 元数据**（users、sessions、workspaces、directory grants、share links、
sync state、AI policy/runtime、audit），本地 `.md` / 附件 / mindmap / OnlyOffice 文件不迁入 Turso。
OpenHub 会话库后续作为单独阶段评估。


## 3. 已完成 MVP 收口

- Local-first workspace 上位设计和 checklist 已完成，迁入 `design/02-convex-rust-long-term-architecture/done/2-2-*`。
- 3000 下文档页、Sidebar/File Tree/Page Tree、tree command preferred path、tree realtime WS 主链 / SSE fallback、本地上传下载、AI 会话本地化与 VSCode-like agent 运行口径已建立。
- `cargo fmt --check --all`、`local_folder`、legacy tool facade、local/shared AI session、local-first Convex guard、Convex export fixture、local asset upload smoke、external-change conflict smoke 均已作为 `2-2` 验收证据记录。
- 本地上传链路已避免 Convex media asset，落盘相对 Markdown 链接。
- 本地 AI 会话已区分 private / shared / cloud，并在 UI 上显示来源。
- Convex guard 已阻止 active 路径重新引入未标注的 Convex documents / media / aiSessions 默认主存储口径，并拦截根 `convex/` functions 源码回流默认控制面。
- Runtime 可维护收口已完成：`document-editor-adapter-runtime.js`、`sidebar-tree-runtime.js`、`tree-shell-runtime.js` 与 `leptos-tiptap-spike/src/lib.rs` 已拆到模块级，`mnote-web --lib`、`leptos-tiptap-spike --lib`、格式化、diff check 与 CodeGraph pending 0 已作为 `design/10-review/done/16-*` 的验收记录。
- 当前 smoke 分类与默认基线以 `scripts/TESTING_REFERENCE.md` 为准；默认入口是 `3000 Rust SSR + leptos-tiptap island + local-first workspace + Turso/libSQL control-plane auth`。

## 4. MVP 后阶段功能缺口

1. **WorkspacePath / ObjectIdentity runtime 消费统一**
   - 继续把本地路径、资源 identity、页面正文 `.md`、附件、mindmap、office 资源归属统一到 kernel / projection contract。
   - 防止 UI、compat route 或临时文件逻辑重新生成第二套资源真相。

2. **DocumentBuffer / BufferStore**
   - 让 tiptap、文件 watcher、agent 写入、冲突检测和页面 tab 共用打开态与文件版本仲裁。
   - 避免 dirty editor、资源 tab、文件树点击之间各自维护状态。

3. **Page Aggregate compat 瘦身 / kernel-native projection**
   - 继续退役 legacy `body.content` / compat join 边界。
   - local-first 正文真相保持为 `.md` 文件，Page Aggregate 只输出稳定投影。

4. **tree command context / context key**
   - 菜单、快捷键、按钮、AI 写入能力的 enablement 判断应收口到同一套 command context。
   - 文件树和主编辑器右键菜单不能继续各自硬编码。

5. **tree live cache 统一**
   - 把 local-folder watcher、projection refresh、WS/SSE snapshot/delta/resync 收进同一 live cache。
   - 减少 polling 或重复补偿链。

6. **Runtime owner 剩余专项**
   - `design/03-rust-web/reference/3-23-sidebar-local-folder-resource-runtime-followup-v1.md` 记录 local folder / resource 编排拆分后的参考边界；新的执行项应另起 process 稿。
   - `design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md` 继续承接 Page AI sidebar runtime owner 细化。

7. **管理员目录授权 UI / API**
   - 需要把 `access-policy.json` 和当前 auth actor、admin grant、read/write/share 权限做成可管理界面。
   - 管理员可授权任意 canonical 目录；普通用户只能访问自己的受管 my-space 或被授权目录。

8. **VSCode-like 冲突处理 UI**
   - 当前已有 clean/dirty watcher 行为和冲突态 smoke。
   - 还需要做可用的“接受磁盘版本 / 保留当前版本 / 打开 diff 合并”交互。

9. **agent 写入审计**
   - local-first agent 应回收 changed files、diff summary、tool/run id、actor、workspace root、permission level。
   - audit 默认本地落盘，同步开启时再上报控制面。

10. **本地轻量搜索与知识库 RAG 边界**
   - 本地 `.md` workspace 需要独立索引：全文搜索、反链、页面引用、资源引用、标签。
   - 不能依赖 Convex search 才能搜索本地工作区。
   - 多资料 OCR / parse / index / RAG 不再由本地 evidence / LiteParse 承担，默认走 LightRAG provider；WeKnora 仅备用。

11. **分享与同步闭环**
   - 需要把 share grants、shared workspace cache、shared AI session、只读/可写权限和冲突处理连成产品级闭环。
   - share grant 是产品层共享授权，local access grant 是本机目录授权；显式分享不能自动扩大本机 filesystem root 权限。
   - 控制面不可用时不得扩大本地缓存权限。

12. **插件资源模型**
   - simplemindmap / office 应作为 Resource Tree 对象打开和保存。
   - Markdown 中只保留链接或嵌入引用，不把复杂对象强塞进普通正文块。

13. **旧 Convex 数据迁移产品化**
   - 当前已有 fixture/offline 导出脚本。
   - 后续需要真实 Convex workspace 导出入口、迁移进度、冲突报告、回滚/备份策略。
   - 根 `convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`，只作为审计和迁移对照素材。

## 5. 已退役或降级口径

以下说法不再作为当前主线：

- “Convex 是默认正文 / 附件 / AI 会话全文主存储。”
- “Convex 是默认 auth / membership / share / AI runtime 控制面。”
- “`mnote.doc.markdown_edit` 是 local-first 普通 Markdown 编辑唯一主路径。”
- “页面 AI 必须走 `/api/page-ai/block-edit-workflow` 或 `mnote.block.*` 才能改正文。”
- “`/api/documents/save` 是长期正文保存主入口。”
- “BlockNote 是当前默认编辑器或系统事实源。”
- “Next App Router / wolai-frontend 是 3000 主运行时。”
- “LiteParse / 本地 OCR sidecar / evidence search 仍是资料库 RAG 默认 fallback。”
- “MNote 需要为 LightRAG 结果再建一套 RAG 索引真相。”
- “WeKnora 是当前默认知识库 provider。”
- “Hermes / Reasonix 是当前 Page AI 默认 agent runtime。”

历史文件如果需要保留这些说法，必须明确标注为 `[recycle]`、legacy、review snapshot 或 compat / cloud source 背景。