docs: align runtime architecture guidance

This commit is contained in:
lix-2026
2026-05-26 07:29:15 +08:00
parent e1681331a3
commit 0a15595066
14 changed files with 134 additions and 35 deletions
+26 -5
View File
@@ -8,6 +8,7 @@
- 本地文件夹是早期产品默认数据真相;本地 `.md` 是页面正文真相。Rust SQLite `control-plane` 是默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 控制面;`Convex` / 服务端只保留为历史迁移源、显式 cloud source、compat 和 sync replica 边界,不再作为新增能力的默认正文、附件、AI 会话全文主存储或默认控制面。
- `Rust kernel` 持有树、子树、边、projection、query、command 的语义主导权;新增树规则不要继续散落到前端、Next route 或临时 compat 层。
- `mnote-web` 是当前 Rust Web 承载层,负责 transport、projection 分发、兼容切流;`compat``fixture` 只用于过渡和测试,不应继续承载长期业务语义。`3000` 是唯一前端公开入口;`3104` 已退役为仅显式 debug/internal 使用的边界。`/tree``/document-debug` 等 debug 壳默认关闭,仅在显式 debug/runtime 验证时启用。
- 前端 runtime 已完成第一轮模块级拆分:`layout.rs` / `tree.rs` / `web_shell.rs` 不再是大型内嵌 JS 的主要定位入口。查 Sidebar、FileTree、tree shell、document adapter 等浏览器功能时,默认先看 `rust/crates/mnote-web/browser/*.js`;查 tiptap island 行为时,默认先看 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`,再回到根 `lib.rs` / Rust route。
- 前端主路径应消费稳定 projection,不应在 UI 层重新拼出第二份对象真相。
- Next `documents/page` 读取主链已优先消费 Rust `mnote.page_aggregate.v1` 快照;TS `page-aggregate-builder` 仅保留为历史 adapter / test helper,不再作为 runtime fallback,也不再把“前端手工拼 `meta + content`”描述为当前主路径。
- `3000` 当前主壳已接入 Rust Web WebSocket push 主链(`/api/realtime/ws`+ SSE fallback`/api/tree/events`)的 snapshot / delta / resync consumer,并已有 browser smoke 验证(2026-05-17 WS 迁移 `57ec8322`);后续收口重点是统一 live cache 与减少补偿链,而不是把它描述成“还没接 live stream”。
@@ -24,6 +25,17 @@
- `page-ai/block-edit-workflow` route 只保留为兼容门面或非 local source 的快捷路径,不作为 local-first 普通 Markdown 编辑默认主路径;local-first 下优先给 Hermes / Reasonix 授权文件引用并让 agent 使用自身文件编辑能力。`mnote.doc.markdown_edit` 是 cloud / remote agent / compat fallback`mnote.block.*` 保留为结构性辅助。
- 树域三层模型:`Resource Tree`kernel 对象组织真源)→ `File Tree`(主组织投影,`{title}.md` 为页面正文行)→ `Page Tree`(导航投影,不持有结构真相)。涉及资源归属优先走 Rust kernel 的 `KernelObjectIdentity` / `KernelProjectionResourceKind`
## Runtime 模块定位
- `mnote-web` 浏览器 runtime 的当前 canonical 入口是 `rust/crates/mnote-web/browser/`
- Sidebar 装配:`sidebar-tree-runtime.js`,已拆出 workspace、page tree、filetree command/open/upload、attachment open、page settings、live apply 等模块。
- FileTree 通用能力:`filetree-runtime.js``filetree-selection-runtime.js``filetree-context-menu-runtime.js``filetree-dnd-runtime.js``filetree-keyboard-runtime.js`
- Page AI sidebar host`sidebar-page-ai-runtime.js`owner 属于 `07-ai`,不归 `03-rust-web` tree/filetree runtime。
- 文档页 host adapter`document-editor-adapter-runtime.js`,已拆出 pane、resource tab、mindmap host、slash positioning、Tiptap conversion、session 等模块。
- debug/internal tree shell`tree-shell-runtime.js`,已拆出 page、filetree、picker、DOM、render、icons、state 等模块。
- `leptos-tiptap` island 的当前 canonical 入口是 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/`;新增编辑器行为不得继续直接堆入 `lib.rs`,除非它确实是 wasm-bindgen entrypoint、Leptos 壳层信号编排或仍未形成稳定模块边界。
- CodeGraph 查 JS 功能时应能直接定位这些 `.js` 文件中的顶层函数;若结果仍落到 Rust raw string 或大型旧壳,先检查是否查错历史 / recycle 路径或索引未同步。
## 目录优先级
- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/`
@@ -63,18 +75,20 @@
- `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
- `/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md`
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference/5-5-page-aggregate-single-truth-alignment-v1.md`
- `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`
- `/mnt/Data1T/mnote/design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`
- `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-6-page-aggregate-alignment-checklist-v1.md`
- `/mnt/Data1T/mnote/design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`
- `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
- `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
- `/mnt/Data1T/mnote/design/03-rust-web/done/3-3-rust-web-tree-realtime-event-stream-v1.md`
- `design/03-rust-web/done/3-14-rust-web-tree-realtime-ws-push-v1.md`
- `/mnt/Data1T/mnote/design/10-review/process/08-kernel-architecture-next-priority-review-and-checklist.md`
- `/mnt/Data1T/mnote/design/10-review/done/08-kernel-architecture-next-priority-review-and-checklist.md`
- `/mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md`
- `/mnt/Data1T/mnote/design/10-review/done/10-current-mnote-ai-runtime-review-v1.md`
- `/mnt/Data1T/mnote/design/10-review/done/11-current-full-architecture-review-v1.md`
- `/mnt/Data1T/mnote/design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md`
- `/mnt/Data1T/mnote/design/04-tree-domain/done/4-24-resource-tree-filetree-pagetree-source-contract-checklist-v1.md`
- `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-12-main-editor-object-tab-resource-alignment-checklist-v1.md`
- `/mnt/Data1T/mnote/design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`
- `/mnt/Data1T/mnote/design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md`
- `/mnt/Data1T/mnote/design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md`
## 设计稿目录规则
@@ -104,6 +118,7 @@
- 不要擅自恢复、覆盖、删除用户已有改动。
- 若发现与当前任务无关的脏改动,保持不动;若怀疑会影响当前任务,先确认再处理。
- 若当前问题只是 UI 表现异常,先确认是否是实验性 tree shell、compat 路径、轮询或 fallback 混入首屏主链,而不是直接怀疑 Convex 本身。
- Reasonix / subagent 只能作为受控叶子 worker:任务书必须限定读写范围、验证命令、交付文件和禁止项;不得自行再启动 runner、subagent、额外 worktree 或修改任务书。Codex/Hermes 主控必须复核 diff、handoff/result、验证证据和 git 状态后才能采纳。
## CodeGraph 使用
@@ -126,6 +141,12 @@
- 后端开发:`cd /mnt/Data1T/mnote/wolai-backend && uvicorn app.main:app --reload --port 8000`
- Convex 自托管:仅在显式 cloud / compat / sync replica 或历史导出场景参考 `/mnt/Data1T/mnote/recycle/20260522-convex-runtime-retirement/infra/convex/README.md`
## Smoke 基线
- 当前 smoke 分类与默认基线以 `scripts/TESTING_REFERENCE.md` 为准。
- 默认浏览器验证入口是 `3000 Rust SSR + leptos-tiptap island + local-first workspace + SQLite control-plane auth`
- 退役 Convex / Next / 3104 / BlockNote 路径的 smoke 不作为默认回归基线;只有显式 legacy/cloud/compat 任务才运行对应脚本。
## 默认测试账号
- 后续网页测试、浏览和 smoke 默认使用当前 SQLite control-plane Auth 测试账号:邮箱 `mnote.e2e@example.com`,密码 `MnoteE2E123!`,用户名 `mnote-e2e`
+23 -7
View File
@@ -1,10 +1,12 @@
# MNOTE 当前架构梳理
> 更新时间:2026-05-22
> 更新时间:2026-05-26
>
> 2026-05-22 口径更新:产品形态已切换为 local-first workspace,且初步 MVP 已建立;本地文件夹是默认数据真相,Rust SQLite control-plane 承接 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 等默认控制面。Convex 仅保留为历史迁移源、显式 cloud source / compat / sync replica 边界;根 `convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`,不再作为 active deploy source。相关设计已完成并迁入 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md` 与 `design/02-convex-rust-long-term-architecture/done/2-8-convex-replace-with-rust-sqlite-control-plane-v1.md`。本地 Markdown 图片与附件上传已新增 `/api/local-folder/assets/upload`,页面内上传默认写入 `{mdBase}.assets/` 并保存相对 Markdown 路径,不再走 Convex media asset。
>
> **当前阶段:local-first MVP 后阶段。** 3000 下文档页、Sidebar/File Tree/Page Tree 三层树模型、tree command`tree.*` preferred)、tree realtime WS 主链 / SSE fallback、本地 Markdown 上传、上传下载、AI 会话本地化与 VSCode-like agent 运行口径均已建立。剩余工作集中在 `WorkspacePath/ObjectIdentity` runtime 消费统一、`DocumentBuffer/BufferStore`、Page Aggregate compat 瘦身、tree command context、live cache 统一、VSCode-like 冲突合并 UI、agent diff 审计、本地索引 / 分享 / 同步闭环,而不是继续扩张专用 page-ai fast-path 或 Convex 主存储链。
>
> 2026-05-26 口径更新:前端 runtime 大块已完成模块级拆分。`layout.rs` / `tree.rs` / `web_shell.rs` 不再是浏览器 JS 功能的主要符号定位入口;Sidebar、FileTree、document adapter、tree shell 等 runtime 入口位于 `rust/crates/mnote-web/browser/*.js`tiptap island 入口位于 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。CodeGraph 可直接索引这些 JS / Rust 模块;当前 smoke 分类见 `scripts/TESTING_REFERENCE.md`。
本文只描述当前仓库中真实成立的主线结构,以及当前最优先的架构收口点。
@@ -23,7 +25,7 @@
3. `mnote-web` 是当前 Rust Web 主执行面,负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime streamNext App Router 已降为 legacy compat / island bundle source,不再是当前主入口
4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
5. `BlockNote` 已退出文档页默认主路径,仅作为历史参考实现 / 对照材料保留
6. 页面 AI 当前最合理的长期形态是:MNote 只负责页面定位、白名单目录权限、agent runtime 管理、文件变更同步;Hermes / Reasonix 直接在授权工作区内编辑本地文件。`page_ai_workflow` 只保留为 debug / 历史兼容门面,`mnote.doc.markdown_edit`作为 local-first 默认、fallback 或 remote fallback`mnote.block.*` 只保留为复杂结构辅助层
6. 页面 AI 当前最合理的长期形态是:MNote 只负责页面定位、白名单目录权限、agent runtime 管理、文件变更同步;Hermes / Reasonix 直接在授权工作区内编辑本地文件。`page_ai_workflow` 只保留为 debug / 历史兼容门面,`mnote.doc.markdown_edit` 不作为 local-first 默认正文编辑入口,只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback`mnote.block.*` 只保留为复杂结构辅助层
一句话收口:
@@ -78,8 +80,20 @@
当前 Sidebar/工作区壳的当前实现在 Rust mnote-web SSR
- 工作区壳渲染入口:`gateway.rs``root_entry`
- 文档页壳/文档面板:`web_shell.rs``document_page_shell``build_document_panes_bootstrap_json`
- Sidebar tree stream 消费:`layout.rs` 嵌入 JS`startWithSse` / `startWithWebSocket`
- FileTree 渲染与交互:`tree.rs` 嵌入 JS
- Sidebar / FileTree / tree live runtime`rust/crates/mnote-web/browser/sidebar-tree-runtime.js``filetree-*.js``tree-live-controller.js` 等模块;`layout.rs` 只负责 SSR/bootstrap 和 script 注入。
- FileTree 渲染与交互:`rust/crates/mnote-web/browser/filetree-runtime.js``filetree-selection-runtime.js``filetree-context-menu-runtime.js``filetree-dnd-runtime.js``filetree-keyboard-runtime.js`
- debug/internal tree shell runtime`rust/crates/mnote-web/browser/tree-shell-runtime.js``tree-shell-*.js` 模块;`tree.rs` 只负责 route、HTML shell、asset route 和测试断言。
### 3.3 Runtime 模块化现状
当前 CodeGraph / IDE / 浏览器 stack trace 的定位入口应按模块查找:
- `rust/crates/mnote-web/browser/document-editor-adapter-runtime.js`:文档页 host adapter entrypoint,子模块负责 pane、resource tab、mindmap host、slash position、Tiptap conversion 和 session runtime。
- `rust/crates/mnote-web/browser/sidebar-tree-runtime.js`Sidebar entrypoint,子模块负责 workspace、page tree、filetree open/command/upload、attachment open、page settings 和 live applyPage AI sidebar host 位于 `sidebar-page-ai-runtime.js`owner 属于 `07-ai`
- `rust/crates/mnote-web/browser/tree-shell-runtime.js`debug/internal tree shell entrypoint,子模块负责 page tree、filetree、picker、render、DOM、icons 和 state。
- `rust/spikes/leptos-tiptap-spike/src/editor_runtime/`tiptap island runtime 模块集合;根 `lib.rs` 只保留 wasm entrypoint、Leptos shell 信号编排和仍未稳定外置的薄壳。
对应完成记录见 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`。剩余专项边界不再回到 raw string 问题,而是分别由 `design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md``design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md` 承接。
## 4. 文档页主链
@@ -297,7 +311,7 @@ OnlyOffice 仍然是:
对应设计稿:
- `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
- `/mnt/Data1T/mnote/design/03-rust-web/done/3-3-rust-web-tree-realtime-event-stream-v1.md`
### 8.4 Page / Block AI Tooling
@@ -325,10 +339,10 @@ OnlyOffice 仍然是:
关键原则(2026-05-18 口径更新):
- **local-first 主路径**:当前页面解析成授权 `.md` 文件,Hermes / Reasonix 在白名单目录内直接读写,MNote 负责权限、审计和前台同步
- **local-first 文件编辑模型**:普通 Markdown 编辑走“页面定位 + 授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”;MNote 不提供普通 Markdown 编辑工具,`mnote.doc.markdown_edit` 不再作为默认、fallback 或 remote fallback`mnote.doc.apply_block_ops` 仅作为块级结构性辅助。CLI Main Lark Doc 只能作为 skill/workflow 纪律的有限参考,不作为当前编辑架构主参考。
- **local-first 文件编辑模型**:普通 Markdown 编辑走“页面定位 + 授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”;MNote 不提供 local-first 默认普通 Markdown 编辑工具,`mnote.doc.markdown_edit` 只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback`mnote.doc.apply_block_ops` 仅作为块级结构性辅助。CLI Main Lark Doc 只能作为 skill/workflow 纪律的有限参考,不作为当前编辑架构主参考。
- `mnote.block.*` 降级为结构性辅助(拖拽排序、精确块删除等),不删除
- 当前 `local_rule` planner`direct_block_edit_operations`)是过渡实现,应继续退役
- cloud / remote agent 无法直接访问本地文件时,不默回退到 `mnote.doc.markdown_edit`需要另行设计显式同步 / cloud source 边界
- cloud / remote agent 无法直接访问本地文件时,不能静默回退到 `mnote.doc.markdown_edit`必须通过显式 cloud source / remote fallback / compat 边界和权限设计承接
- Markdown 既是 AI 编辑格式也是人类可读格式,不需要 XML 中间层
- 流式 apply + suggest/review(参考 BlockNote AI 的 `StreamToolExecutor` + `suggestChanges`)仅作为 Phase C 设计冻结,当前不实施
@@ -355,6 +369,8 @@ OnlyOffice 仍然是:
已有 smoke 体系(`scripts/` 目录):
- `scripts/TESTING_REFERENCE.md`:当前 smoke 分类、默认基线和退役脚本说明
- `task110-page-title-single-truth-smoke.js`:标题全链路一致性
- `task-page-aggregate-body-sync-smoke.js`:正文写入后 Page Aggregate 同步
- `task-page-aggregate-options-sync-smoke.js`:页面设置写入后同步
+15 -8
View File
@@ -1,6 +1,6 @@
# 当前完整架构
> 更新时间:2026-05-22
> 更新时间:2026-05-26
>
> 范围:`/mnt/Data1T/mnote` 当前可见实现、local-first MVP 后阶段主线口径、历史退役边界和后续功能缺口。
@@ -44,6 +44,7 @@
- `mnote-web` 是当前 3000 ownerNext / 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 进入冲突态,不静默覆盖。
@@ -71,6 +72,8 @@
- 本地上传链路已避免 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 + SQLite control-plane auth`
## 4. MVP 后阶段功能缺口
@@ -94,32 +97,36 @@
- 把 local-folder watcher、projection refresh、WS/SSE snapshot/delta/resync 收进同一 live cache。
- 减少 polling 或重复补偿链。
6. **管理员目录授权 UI / API**
6. **Runtime owner 剩余专项**
- `design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md` 继续承接 local folder / resource 编排中仍适合拆出的稳定 helper。
- `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 或被授权目录。
7. **VSCode-like 冲突处理 UI**
8. **VSCode-like 冲突处理 UI**
- 当前已有 clean/dirty watcher 行为和冲突态 smoke。
- 还需要做可用的“接受磁盘版本 / 保留当前版本 / 打开 diff 合并”交互。
8. **agent 写入审计**
9. **agent 写入审计**
- local-first agent 应回收 changed files、diff summary、tool/run id、actor、workspace root、permission level。
- audit 默认本地落盘,同步开启时再上报控制面。
9. **本地全文搜索、引用和索引**
10. **本地全文搜索、引用和索引**
- 本地 `.md` workspace 需要独立索引:全文搜索、反链、页面引用、资源引用、标签。
- 不能依赖 Convex search 才能搜索本地工作区。
10. **分享与同步闭环**
11. **分享与同步闭环**
- 需要把 share grants、shared workspace cache、shared AI session、只读/可写权限和冲突处理连成产品级闭环。
- share grant 是产品层共享授权,local access grant 是本机目录授权;显式分享不能自动扩大本机 filesystem root 权限。
- 控制面不可用时不得扩大本地缓存权限。
11. **插件资源模型**
12. **插件资源模型**
- simplemindmap / office 应作为 Resource Tree 对象打开和保存。
- Markdown 中只保留链接或嵌入引用,不把复杂对象强塞进普通正文块。
12. **旧 Convex 数据迁移产品化**
13. **旧 Convex 数据迁移产品化**
- 当前已有 fixture/offline 导出脚本。
- 后续需要真实 Convex workspace 导出入口、迁移进度、冲突报告、回滚/备份策略。
-`convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`,只作为审计和迁移对照素材。
+14
View File
@@ -8,6 +8,7 @@
- Rust kernel / projection / command 持有树、页面、资源和权限语义;新增树规则不要散落到前端、Next route 或临时 compat 层。
- Rust SQLite control-plane 已承接默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 等控制面;Convex / 服务端不再是默认正文、附件、AI 会话全文主存储,只保留历史迁移源、显式 cloud source、compat 和 sync replica 边界。
- `mnote-web` 是当前 3000 owner;旧 Next / React / wolai-frontend 已移入 `recycle/`,默认不作为当前实现依据。
- 前端 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` 的历史 raw string 当作当前符号定位入口。
## Stack
@@ -22,8 +23,10 @@
| Path | Contents |
|------|----------|
| `rust/crates/mnote-web/` | Rust web gateway (axum + Leptos SSR, `:3000`) |
| `rust/crates/mnote-web/browser/` | Browser runtime modules for sidebar, filetree, document adapter, tree shell, Page AI panel host |
| `rust/crates/core-protocol/` | Kernel types, projection protocol, tree/graph terms |
| `rust/crates/bridge-runtime/` | Kernel query/command, projection bridge, source normalization |
| `rust/spikes/leptos-tiptap-spike/src/editor_runtime/` | Leptos-tiptap island runtime modules; use before editing root `lib.rs` |
| `rust/crates/mnote-cli/` | CLI tool (`sidebar dataset`, `page get/create/title/save/move`, `block insert/patch`) |
| `rust/crates/storage-convex-bridge/` | Convex compat / cloud source / sync-replica bridge for Rust |
| `recycle/20260522-convex-runtime-retirement/convex/` | Retired root Convex functions source retained for audit / migration reference |
@@ -51,6 +54,16 @@
- Use `codegraph_search` for symbol names, `codegraph_callers` / `codegraph_callees` for call flow, `codegraph_impact` before risky edits, `codegraph_context` for focused task context, and `codegraph_files` / `codegraph_status` for index inspection.
- Use native search only for literal text, comments, log messages, or after a specific file is already identified.
- Keep the project index fresh in development: run `codegraph sync .` after code changes; use `codegraph index . --force` when the index looks stale or after broad restructuring.
- Runtime split is the current CodeGraph baseline: JS functions should be found in `browser/*.js` and editor runtime symbols in `editor_runtime/*.rs`. If search results point to `recycle/`, historical design docs, or old Rust raw strings, treat them as historical context unless the task explicitly targets legacy code.
## Reasonix Worker Boundary
- Reasonix is a leaf worker, not a main controller.
- Do not start nested Reasonix runners, subagents, extra worktrees, or rewrite task prompts from inside a Reasonix task.
- Coding tasks must use an explicitly assigned write scope and report every modified file.
- Read-only and browser tasks must leave `modified_files` empty and prove it with `git status --short` / `git diff --stat`.
- Browser verification must produce the artifact contract from `design/07-ai/process/7-35-reasonix-browser-test-contract-v1.md`: `result.json`, `final.md`, handoff files, screenshots, console/network evidence, and environment preconditions.
- Codex/Hermes main controller accepts Reasonix output only after checking handoff/result files, diff, validation evidence, and current repo status. Natural-language conclusions without artifacts are leads, not verification.
## Reference-Code Comparison
@@ -63,6 +76,7 @@
- **Local-first default**: start from Rust `mnote-web`, LocalFS/local_folder projection, Page Aggregate, File Tree, Resource Tree, and SQLite control-plane auth/session/actor. Use Convex paths only for explicit cloud source, compat, sync-replica, migration, or rollback work.
- **Smoke test pattern**: standalone Playwright scripts under `scripts/task-*.js` using a shared harness (`ensureAuthenticated`, `createTempDocument`, `cleanupDocuments`). All use `"use strict"` and `require("playwright")` (`scripts/task110-page-title-single-truth-smoke.js:1-4`).
- **Smoke baseline**: use `scripts/TESTING_REFERENCE.md` for current/compat/manual/retired classification. Default browser baseline is `3000 Rust SSR + leptos-tiptap island + local-first workspace + SQLite control-plane auth`.
- **Rust workspace**: edition 2021, resolver "2", MIT license. All crates inherit workspace version (`rust/Cargo.toml:2-8`).
- **Convex boundary**: root `convex/` has been retired to `recycle/20260522-convex-runtime-retirement/convex/`; `infra/convex/` has been retired to `recycle/20260522-convex-runtime-retirement/infra/convex/`; do not recreate either as an active deploy source without a new architecture decision. `recycle/wolai-frontend/convex` is also historical. Keep Rust `transport/convex.rs` and `storage-convex-bridge` as explicit cloud/compat boundaries; do not mechanically delete them with the retired functions source.
- **AI editing path**: local-first Markdown editing should prefer `currentFile + selection + allowedRoots / aiAccessScope + agent native patch/diff + watcher sync`. `mnote.doc.*` / `mnote.block.*` are cloud, remote, compat, or complex-structure helpers.
+23 -1
View File
@@ -1,6 +1,12 @@
# 01-05 当前主线与优先级总览
> 更新时间:2026-05-22
> 更新时间:2026-05-26
>
> 2026-05-26 口径补充:
> - 前端 runtime 第一轮模块级拆分已完成并归档到 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md``layout.rs` / `tree.rs` / `web_shell.rs` 大型 raw string 已不再是 CodeGraph 符号定位的主要问题。
> - 当前定位浏览器功能默认看 `rust/crates/mnote-web/browser/*.js`,定位 tiptap island 行为默认看 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。
> - 当前 smoke 分类和默认基线以 `scripts/TESTING_REFERENCE.md` 为准;退役 Convex / Next / 3104 / BlockNote 路径只在显式 legacy/cloud/compat 任务中运行。
> - Reasonix 只作为受控叶子 worker;不得自行启动 runner/subagent/worktree,结果必须由 Codex/Hermes 主控复核 handoff、diff、验证证据和 git 状态。
>
> 2026-05-22 口径补充:
> - Rust SQLite control-plane 已承接默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 控制面。
@@ -119,6 +125,22 @@ P0-P6 已经有最小闭环证据;P7 已完成阶段性瘦身,但还不是
- 本地 folder sidebar watch 已从整页 HTML refetch 改为 projection API 刷新
- 当前重点已从“是否接入 live stream”转为减少补偿链、缩薄 legacy consumer 和补稳定 smoke。
### 2.4 Runtime 模块级可维护收口
当前状态:
- `/mnt/Data1T/mnote/design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`
- `/mnt/Data1T/mnote/design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md`
- `/mnt/Data1T/mnote/design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md`
阶段性结论:
- `web_shell.rs` 文档页 host adapter 已外置到 `browser/document-editor-adapter-runtime.js` 并继续拆成 pane、resource tab、mindmap host、slash position、Tiptap conversion、session 等模块。
- `sidebar-tree-runtime.js` 已降到 3,000 行以下,sidebar workspace、page tree、filetree open/command/upload、attachment open、page settings、live apply 等边界已模块化;Page AI 主体属于 `sidebar-page-ai-runtime.js``07-ai` owner。
- `tree-shell-runtime.js` 已降到 2,500 行以下,debug/internal tree shell 的 page/filetree/picker/render/DOM/icons/state 已有模块边界。
- `leptos-tiptap-spike/src/lib.rs` 已降到 5,000 行以下,编辑器 runtime 模块位于 `editor_runtime/`
- CodeGraph 当前应直接索引这些 JS / Rust 模块;后续不再通过“继续拆 raw string”解决问题,而是按 `3-23``7-38` 和 BufferStore / Page Aggregate / live cache 等 owner 继续收口。
## 3. 当前仍应保留但不在第一线的 reference / done
下面这些文档仍然有效,但当前不应排在第一优先;引用时必须叠加 2026-05-21 之后的 local-first MVP 后阶段口径:
@@ -303,10 +303,10 @@ UI / 浏览器可见项必须有真实浏览器截图或结构化 smoke 证据
| filetree keyboard/clipboard/DND/context menu | ✅ | filetree-dnd-runtime.js + filetree-keyboard-runtime.js |
| document pane host / conflict panel runtime | ✅ | acceptDiskVersion/keepCurrentEditorVersion/writeMergedConflictResult + 已迁出的 DOM helper |
| local upload 主流程审计 | ✅ | 全部 6 个函数已迁入 local-upload-runtime.js |
| WS/SSE tree live smoke | ⚠️ | task487 REDtree live transport 尚未接入 local_foldertask479/488/489/451 ✅ |
| WS/SSE tree live smoke | | task487 已收敛为 `local-folder-events`task479/488/489/451 ✅ |
| **SIDEBAR_TREE_JS 主 runtime 外置** | ✅ | 10,655 行 → sidebar-tree-runtime.js(超出原计划范围) |
### browser/ 最终模块清单(11 文件)
### browser/ 阶段模块清单(3-20 归档时 11 文件)
| 文件 | 行数 | 说明 |
|------|------|------|
@@ -191,12 +191,12 @@ codegraph sync .
| browser/ 模块 | 11 个 JS 文件,总计 ~11,000 行 |
| editor_runtime/ 模块 | 19 个 Rust 模块(另有 mod.rs |
| 浏览器 smoke | task479/488/489/451 全部 PASS |
| 测试 | editor 13/13web full 最近一次 529/54920 failed,非本轮 editor runtime / sidebar 外置改动面) |
| 测试 | editor 13/13web full 在 3-21 当时最近一次 529/54920 failed,非本轮 editor runtime / sidebar 外置改动面);后续 `10-review/done/16` 已完成全量 `mnote-web --lib` 通过 |
| CodeGraph | 350+ 文件索引完成 |
### 后续已拆出
| 项 | 说明 |
|----|------|
| mnote-web 全量 lib 测试失败 | `cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1` 最近一次仍 20 failedwatcher OS limit、legacy proxy、access policy dialog、Hermes block tools 403、local search index、resource trash 503、web_shell 旧断言等),已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`,不再阻塞本文件归档。 |
| sidebar runtime 二阶段瘦身 | `sidebar-tree-runtime.js` 已解决 Rust raw string 定位问题,但仍是 1 万行 JS 巨文件;后续拆分计划已拆`design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md`。 |
| mnote-web 全量 lib 测试失败 | 这是 3-21 归档时的历史状态;后续已由 `10-review/done/16` 收口到全量 `mnote-web --lib` 通过。 |
| sidebar runtime 二阶段瘦身 | `sidebar-tree-runtime.js` 已解决 Rust raw string 定位问题;后续二阶段拆分已完成并记录`design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md``design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`。 |
@@ -62,7 +62,7 @@ rust/crates/mnote-web/browser/sidebar-tree-runtime.js
## 4. 不建议的下一步
- 不建议直接整体重写 `sidebar-tree-runtime.js`
- 不建议把 `mnote-web --lib` 全量失败作为本文件前置阻塞;该问题已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`
- 不建议把 `mnote-web --lib` 在 3-22 创建时的全量失败作为本文件前置阻塞;后续已由 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md` 收口到全量 `mnote-web --lib` 通过
- 不建议为了 DRY 把 shell 业务编排强行迁入小 helper,尤其是需要 workspace/root/document/session 状态的函数。
## 5. 验收基线
@@ -2,7 +2,7 @@
> 创建时间:2026-05-25
> 状态:`process`
> 来源:`design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch B / Batch D。
> 来源:`design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch B / Batch D。
## 1. 背景
@@ -6,7 +6,7 @@
> 触发背景:
> - `bugs/0524.md` 第 4 条删除本地 Markdown 附件链接后 `Ctrl+Z/Ctrl+Y` 不可用,根因是编辑器删除路径绕过 Tiptap/ProseMirror history。
> - 修复过程中 CodeGraph 能索引 Rust 符号,但 `rust/spikes/leptos-tiptap-spike/src/lib.rs` 单文件约一万行,职责过多,主控和 worker 都需要反复字面搜索。
> - `design/03-rust-web/process/3-19-rust-web-browser-runtime-module-extraction-v1.md` 解决 Rust Web shell/browser host runtime 外置化;本设计补齐编辑器主线拆分。
> - `design/03-rust-web/done/3-19-rust-web-browser-runtime-module-extraction-v1.md` 解决 Rust Web shell/browser host runtime 外置化;本设计补齐编辑器主线拆分。
## 1. 结论
@@ -400,7 +400,9 @@ UI / 浏览器可见项必须有真实浏览器截图或结构化 smoke 证据
- `history_safe_commands.rs` 已有 `delete_top_level_block_with_history` / `delete_selected_attachment_link_with_history` 可复用模式。
- 建议:实现 `move_top_level_block_with_history``duplicate_top_level_block_with_history`
## 7. 最终完成状态
## 7. 5-29 阶段完成状态
> 注:本节记录 5-29 归档时的阶段状态。后续 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md` 已继续拆分 `leptos-tiptap-spike/src/lib.rs`,当前根文件已降到 5,000 行以下。
### 文件规模变化
@@ -2,7 +2,7 @@
> 创建时间:2026-05-25
> 状态:`process`
> 来源:`design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch A。
> 来源:`design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch A。
> 2026-05-26 更新:`design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md` 已把 Page AI 主体迁入 `browser/sidebar-page-ai-runtime.js`;本文件继续作为后续 AI owner 收口 checklist。
## 1. 背景
@@ -16,7 +16,7 @@
本 checklist 不重新打开已经完成的 raw string 外置化任务。`layout.rs` / `tree.rs` 的原始巨型 JS raw string 问题已经解决;本轮聚焦剩余的文档页 host adapter、sidebar-tree JS 巨文件、tree-shell JS 巨文件和 Tiptap island runtime 巨型 Rust 文件。
## 2. 当前基线
## 2. 创建时基线
代码基线以 2026-05-26 本地检查为准:
@@ -36,13 +36,24 @@ rust/spikes/leptos-tiptap-spike/src/lib.rs 7,951 行
- `mnote-web/browser/` 已有 12 个 JS runtime 文件,CodeGraph 已按 JavaScript 索引。
- `leptos-tiptap-spike/src/editor_runtime/` 已拆出 `mindmap_node_view.rs``bridge_events.rs``bridge_dispatch.rs``slash_actions.rs``table_commands.rs``table_toolbar_view.rs` 等模块。
仍未达标:
创建本 checklist 时仍未达标:
- `web_shell.rs``render_editor_island_adapter_script()` 仍是大型 inline module script。
- `sidebar-tree-runtime.js` 已可索引,但单文件仍超过一万行,职责过多。
- `tree-shell-runtime.js` 已可索引,但仍混合 page tree、file tree、picker、DOM patch、DND、icon/render 等职责。
- `leptos-tiptap-spike/src/lib.rs` 仍接近八千行,CSS、mount、runtime bridge、slash UI、block menu、resource identity、command handler 仍混在一起。
归档后真实状态(2026-05-26):
```text
rust/crates/mnote-web/src/routes/web_shell.rs 2,578 行
rust/crates/mnote-web/browser/sidebar-tree-runtime.js 2,770 行
rust/crates/mnote-web/browser/tree-shell-runtime.js 2,482 行
rust/spikes/leptos-tiptap-spike/src/lib.rs 3,632 行
```
上述未达标项已由 Batch A-E 解决;剩余 Page AI owner 细化已转入 `design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md`local folder/resource 编排细化已转入 `design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md`
## 3. 范围边界
本轮做模块拆分,不做语义重写。
@@ -76,7 +87,7 @@ rust/spikes/leptos-tiptap-spike/src/lib.rs 7,951 行
优先级:最高。
原因:这是当前仍留在 Rust raw string 里的最大前端 runtime,直接影响最初的 CodeGraph 问题。
原因:这是创建本 batch 时仍留在 Rust raw string 里的最大前端 runtime,直接影响最初的 CodeGraph 问题。
目标文件:
+7 -1
View File
@@ -1,6 +1,6 @@
# design 设计稿索引
> 更新时间:2026-05-22
> 更新时间:2026-05-26
>
> 当前产品口径:`VSCode 简化版工作区 + tiptap 的 Markdown 前端编辑器 + Hermes/Reasonix agent + simplemindmap/office 插件 + Wolai 主题 Web 壳 + 鉴权控制面`。
>
@@ -10,6 +10,10 @@
>
> 后续新增设计默认以 MVP 后阶段为基线:优先推进 `WorkspacePath/ObjectIdentity`、`DocumentBuffer/BufferStore`、Page Aggregate compat 瘦身、tree command context、live cache 统一、agent diff / 冲突合并 / 本地索引 / 分享同步产品化;不要再把旧 Convex / Next / BlockNote 主链、根 `convex/` functions 源码或 Convex Auth 默认控制面当作新增能力默认方向。
>
> Runtime 可维护口径:`3-19`、`3-20`、`3-21`、`3-22`、`5-28`、`5-29` 与 `10-review/done/16` 已完成第一轮前端 runtime 模块级拆分。`layout.rs` / `tree.rs` / `web_shell.rs` 大型 raw string 问题不再是当前主问题;浏览器 JS 默认从 `rust/crates/mnote-web/browser/*.js` 定位,tiptap island 默认从 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs` 定位。剩余 runtime 专项按 owner 分流:local folder/resource 编排看 `03-rust-web/process/3-23`Page AI sidebar owner 看 `07-ai/process/7-38`。
>
> Smoke 口径:当前分类与默认基线以 `/mnt/Data1T/mnote/scripts/TESTING_REFERENCE.md` 为准;退役 Convex / Next / 3104 / BlockNote 脚本不再占用默认 smoke 基线。
>
> 状态口径以当前仓库真实代码为准:
> - `[done]`:对应阶段或收口目标已经在当前主线代码中成立
> - `[process]`:方向已进入主线,且当前可以直接拆 checklist / owner / 验收继续执行
@@ -21,6 +25,8 @@
- `01-05` 当前有效主线与优先级,请先看:
`/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
- Runtime 模块级拆分完成态,请看:
`/mnt/Data1T/mnote/design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`
- MVP 后阶段剩余 `process/` 的执行顺序,请看:
`/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-8-mvp-post-process-execution-order-v1.md`