lix-2026
cdff672aa5
Document the VSCode-like local-first product shape, demote Convex to a control-plane role, and retire stale architecture drafts. Add local workspace migration/export references plus smoke coverage for no-Convex managed workspace startup, local markdown title/body/options persistence, asset upload behavior, and Convex fixture export. Verification: git diff --cached --check; node scripts/check-local-first-convex-guard.js --staged; node scripts/task444-convex-workspace-export-local-fixture-smoke.js; node scripts/task166-local-first-managed-workspace-no-convex-smoke.js; node scripts/task167-local-markdown-title-body-options-no-convex-smoke.js
114 lines
6.5 KiB
Markdown
114 lines
6.5 KiB
Markdown
# 当前完整架构
|
||
|
||
> 更新时间：2026-05-19
|
||
>
|
||
> 范围：`/mnt/Data1T/mnote` 当前可见实现、主线口径、历史退役边界和后续功能缺口。
|
||
|
||
## 1. 当前产品形态
|
||
|
||
当前项目口径固定为：
|
||
|
||
> **MNote = VSCode 简化版工作区 + tiptap 的 Markdown 前端编辑器 + Hermes / Reasonix agent + simplemindmap / office 插件 + Wolai 主题 Web 壳 + 鉴权控制面。**
|
||
|
||
这意味着：
|
||
|
||
- 本地 workspace folder 是早期产品默认数据真相。
|
||
- 本地 `.md` 文件是页面正文真相；Page Aggregate、tiptap state、AI context 都是投影或工作副本。
|
||
- Rust kernel / projection / command 持有树、页面、资源和权限语义。
|
||
- tiptap 是 Markdown 的前端显示与交互层，不是 agent 的主工作面。
|
||
- Hermes / Reasonix 默认应像 VSCode 中的 agent 一样，在授权目录白名单内用自身 patch / diff / 文件编辑能力修改文件。
|
||
- Convex / 服务端不再是默认正文、附件、AI 会话全文主存储，而是 auth、membership、share grants、sync state、AI policy、cloud source、compat 和 sync replica 控制面。
|
||
|
||
上位设计已完成并迁入：
|
||
|
||
- [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. 当前分层
|
||
|
||
### 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.*` 当主存储。
|
||
|
||
### 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。
|
||
- 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
|
||
-> Hermes / Reasonix 在白名单目录内运行
|
||
-> 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`；Convex 只保存必要 metadata / audit / sync replica。
|
||
|
||
## 3. 已完成收口
|
||
|
||
- Local-first workspace 上位设计和 checklist 已完成，迁入 `design/02-convex-rust-long-term-architecture/done/2-2-*`。
|
||
- `cargo fmt --check --all`、`local_folder`、`hermes_tools`、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 默认主存储口径。
|
||
|
||
## 4. 仍在推进的功能缺口
|
||
|
||
1. **管理员目录授权 UI / API**
|
||
- 需要把 `access-policy.json` 和当前 auth actor、admin grant、read/write/share 权限做成可管理界面。
|
||
- 管理员可授权任意 canonical 目录；普通用户只能访问自己的受管 my-space 或被授权目录。
|
||
|
||
2. **VSCode-like 冲突处理 UI**
|
||
- 当前已有 clean/dirty watcher 行为和冲突态 smoke。
|
||
- 还需要做可用的“接受磁盘版本 / 保留当前版本 / 打开 diff 合并”交互。
|
||
|
||
3. **agent 写入审计**
|
||
- local-first agent 应回收 changed files、diff summary、tool/run id、actor、workspace root、permission level。
|
||
- audit 默认本地落盘，同步开启时再上报控制面。
|
||
|
||
4. **本地全文搜索、引用和索引**
|
||
- 本地 `.md` workspace 需要独立索引：全文搜索、反链、页面引用、资源引用、标签。
|
||
- 不能依赖 Convex search 才能搜索本地工作区。
|
||
|
||
5. **分享与同步闭环**
|
||
- 需要把 share grants、shared workspace cache、shared AI session、只读/可写权限和冲突处理连成产品级闭环。
|
||
- 控制面不可用时不得扩大本地缓存权限。
|
||
|
||
6. **插件资源模型**
|
||
- simplemindmap / office 应作为 Resource Tree 对象打开和保存。
|
||
- Markdown 中只保留链接或嵌入引用，不把复杂对象强塞进普通正文块。
|
||
|
||
7. **旧 Convex 数据迁移产品化**
|
||
- 当前已有 fixture/offline 导出脚本。
|
||
- 后续需要真实 Convex workspace 导出入口、迁移进度、冲突报告、回滚/备份策略。
|
||
|
||
## 5. 已退役或降级口径
|
||
|
||
以下说法不再作为当前主线：
|
||
|
||
- “Convex 是默认正文 / 附件 / AI 会话全文主存储。”
|
||
- “`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 主运行时。”
|
||
|
||
历史文件如果需要保留这些说法，必须明确标注为 `[recycle]`、legacy、review snapshot 或 compat / cloud source 背景。
|