From ac7023988e86f6bb6b7fc8eee35fdc25f1d98f3b Mon Sep 17 00:00:00 2001 From: lix-2026 Date: Sat, 9 May 2026 20:51:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=E5=B9=B6=E6=95=B4=E7=90=86=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=E7=A8=BF=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 同步 AGENTS、ARCHITECTURE 与 01-05 总览中的 page aggregate / tree realtime 当前口径\n- 更新 3-3、5-5、5-6 对当前 Rust-first page aggregate 与 tree live stream 进展的描述\n- 将已被 wolai-aline 流程取代的 5-8 迁入 old 并标记 recycle --- AGENTS.md | 4 ++- ARCHITECTURE.md | 27 +++++++------- design/01-05-current-priority-overview.md | 15 ++++---- ...-rust-web-tree-realtime-event-stream-v1.md | 14 ++++---- ...age-aggregate-single-truth-alignment-v1.md | 36 +++++++++---------- ...6-page-aggregate-alignment-checklist-v1.md | 5 +-- ...ai-editor-state-automation-test-plan-v1.md | 2 +- 7 files changed, 53 insertions(+), 50 deletions(-) rename design/{ => old}/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md (96%) diff --git a/AGENTS.md b/AGENTS.md index e5b9e6fc..96cd75df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,8 @@ - `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 验证时启用。 - 前端主路径应消费稳定 projection，不应在 UI 层重新拼出第二份对象真相。 +- Next `documents/page` 读取主链已优先消费 Rust `mnote.page_aggregate.v1` 快照；TS `page-aggregate-builder` 仅保留为 fallback / adapter，不再把“前端手工拼 `meta + content`”描述为当前主路径。 +- `3000` 当前主壳已接入 Rust Web `/api/tree/events` 的 snapshot / delta / resync consumer，并已有 browser smoke 验证；后续收口重点是统一 live cache 与减少补偿链，而不是把它描述成“还没接 live stream”。 - 文档页默认主编辑器已切到页面内 `leptos-tiptap` island；`BlockNote` 当前是 fallback / 对照链，不再代表默认主编辑器方向。 - 当前最优先的架构收口不是继续扩编辑器 UI，而是 `Page Aggregate`、`tree command cutover`、`tree realtime event stream` 三条主线。 @@ -52,7 +54,7 @@ - `/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md` - `/mnt/Data1T/mnote/design/05-editor-mainline/process/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/04-tree-domain/process/4-6-tree-command-protocol-cutover-stage2-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` ## 设计稿目录规则 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 2f9b7eff..92d8e7b7 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # MNOTE 当前架构梳理 -> 更新时间：2026-04-28 +> 更新时间：2026-05-09 本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。 @@ -76,20 +76,22 @@ - `Breadcrumb` - 文档页头标题消费链 -这说明当前工作区树链已经开始收口，但还不是最终的单一正式 realtime 主链。 +这说明当前工作区树链已经进入正式收口阶段：`3000` 主壳已直接接入 `/api/tree/events` 的 snapshot / delta / resync consumer，并有浏览器 smoke 验证；但 preferred snapshot、page subtree、filetree 与补偿链还没有完全统一成唯一 live cache。 ## 4. 文档页主链 ### 4.1 入口 +- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/documents/page/route.ts` +- `/mnt/Data1T/mnote/wolai-frontend/src/lib/documents/page-aggregate-loader.ts` - `/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/documents/[id]/page.tsx` -当前文档页入口已经不再直接把若干独立字段散传给页面壳，而是： +当前文档页读取主链已经不再由页面入口手工拼若干独立字段，而是： -1. 拉取 `documents.meta.get` -2. 拉取 `documents.content.get` -3. 在前端入口组装 `PageAggregateProjection` -4. 传给 `DocumentShell -> DocumentContent` +1. Next `GET /api/documents/page` 优先请求 Rust `/api/page-aggregate/:id` +2. 若返回可信的 `mnote.page_aggregate.v1` 快照，则直接作为 `PageAggregateProjection` +3. 只有在 snapshot 不可用或不可信时，才回退到 TS builder 组装 fallback projection +4. 页面入口与 `DocumentContent` 都消费这同一份聚合结果 对应聚合类型定义： @@ -148,6 +150,7 @@ 当前真实状态是： +- 读取主链已优先消费 Rust `mnote.page_aggregate.v1` snapshot - 标题链路已开始与工作区树 canonical snapshot 对齐 - 正文默认由 `leptos-tiptap` island 编辑与保存 - 页面设置已有一部分进入 island 运行时语义 @@ -155,13 +158,13 @@ 但仍未完成的关键点是： -1. Rust 侧还没有原生 `Page Aggregate` 契约 -2. 标题 / 正文 / 页面设置还不是同一组 page aggregate command family -3. 页面聚合当前仍主要由前端入口装配，而不是 Rust 直接输出 +1. Rust 侧虽已提供最小 `Page Aggregate` snapshot，但页面设置、页头标题与 AI 写入口还没有完整闭环到同一组聚合真相 +2. 标题 / 正文 / 页面设置虽已开始收口到 `page.*` family，但 projection 回流与运行时语义仍未完全统一 +3. 客户端仍保留 fallback builder、preferred sidebar snapshot 与本地 aggregate state reducer，说明页面域单一真源仍在推进中 因此当前正确表述应是： -> **文档页已经进入 page aggregate 过渡态，但页面域单一真源仍在推进中。** +> **文档页读取主链已进入 Rust-first `page aggregate` 过渡态，但页面域单一真源仍未闭环。** ## 6. 当前树域结构 @@ -262,7 +265,7 @@ OnlyOffice 仍然是： 对应设计稿： -- `/mnt/Data1T/mnote/design/04-tree-domain/process/4-6-tree-command-protocol-cutover-stage2-v1.md` +- `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md` ### 8.3 Tree Realtime Event Stream diff --git a/design/01-05-current-priority-overview.md b/design/01-05-current-priority-overview.md index 3e8a0e95..3ad51b22 100644 --- a/design/01-05-current-priority-overview.md +++ b/design/01-05-current-priority-overview.md @@ -1,6 +1,6 @@ # 01-05 当前主线与优先级总览 -> 更新时间：2026-04-22 +> 更新时间：2026-05-09 这份总览只做一件事： @@ -35,10 +35,10 @@ 原因： - 默认主编辑器已经切到页面内 `leptos-tiptap` island -- 标题单一真源已经开始收口 -- 文档页入口已经消费前端侧 `PageAggregateProjection` -- 但 Rust 侧还没有原生 `Page Aggregate` 契约 -- 标题 / 正文 / 页面设置仍未统一成同一组 page aggregate command family +- 文档页读取主链已优先消费 Rust `mnote.page_aggregate.v1` 快照 +- 标题单一真源与页面写链都已经开始收口到 `page.*` family +- 但页面设置运行时语义、页头标题回流与 AI 设置面仍未完全闭环 +- TS fallback / 页面本地 aggregate state 仍说明页面域尚未完全统一 ### 2.2 Tree Command Cutover @@ -61,8 +61,9 @@ 原因： - 当前 sidebar 已有 query snapshot、tree stream、preferred snapshot 选择链 -- 但正式的 snapshot + delta 主链还没有完全成为唯一实时事实来源 -- 这会持续带来 refetch 补偿、freshness 选择和旧快照回闪问题 +- `3000` 当前主壳已接入 `/api/tree/events` 的 snapshot + delta + resync consumer，并已有 browser smoke +- 但 Sidebar、page subtree、filetree 与 preferred snapshot 还没有完全统一到同一条 live cache +- 这仍会持续带来 refetch 补偿、freshness 选择和旧快照回闪问题 ## 3. 当前仍应保留但不在第一线的 process diff --git a/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md b/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md index 6f030edb..28986662 100644 --- a/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md +++ b/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md @@ -1,6 +1,6 @@ # 3-3 [process] Rust Web Tree Realtime Event Stream 方案 v1 -> 更新时间：2026-04-29 +> 更新时间：2026-05-09 > > 关联文档： > - `/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md` @@ -258,9 +258,9 @@ Rust Web 负责： - iframe/postMessage tree shell 不是正式 realtime 主链 -## 9. 当前实现复核（2026-04-29） +## 9. 当前实现复核（2026-05-09） -这份方案继续留在 `process/`，因为 Rust Web transport 已落地，但当前 `3000` 的 Rust SSR tree/sidebar 消费侧还没有完整闭环到 live stream。 +这份方案继续留在 `process/`，因为 Rust Web transport 与当前 `3000` 主壳 live consumer 已落地，但 page subtree / filetree / preferred snapshot 仍未完全统一到同一条正式 live cache。 ### 9.1 已完成 @@ -269,12 +269,12 @@ Rust Web 负责： - [x] `stream_support.rs` 已有 cursor、delta、resync 的基础判定逻辑。 - [x] `/api/stream/events` 与 WebSocket snapshot / resync 骨架已存在。 - [x] legacy React 侧已有 `useSidebarTreeStream` 与 `EventSource` consumer，并有协议 / delta 单测。 -- [x] `task112` / `task120` 已覆盖 `/api/tree/events` snapshot 可用性。 +- [x] 当前 `3000` Rust shell 已直接挂载 tree live `EventSource` consumer，并通过 `data-mnote-tree-live-applied` 应用 delta / resync。 +- [x] `task112` / `task120` / `task123` 已覆盖 `/api/tree/events` snapshot、delta / resync 与 stream owner 可用性。 +- [x] `task165` 已验证双 pane 不重复建立第二条 tree live stream。 ### 9.2 仍未完成 -- [ ] 当前 Rust Web 3000 SSR workspace/sidebar shell 还没有直接挂载 live `EventSource` consumer；它主要依赖 SSR snapshot 与交互后重读。 -- [ ] delta / resync 尚缺面向当前 3000 Rust shell 的浏览器级 smoke。 - [ ] Sidebar、page subtree、filetree 还没有全部统一到同一条 live stream cache。 - [ ] WS 目前只证明 snapshot/resync 骨架，尚未成为主实时链路。 -- [ ] 不能把本稿移动到 `done/`，直到 `3000` 当前主界面的树消费侧也完成 snapshot + delta + resync 验收。 +- [ ] 不能把本稿移动到 `done/`，直到 `3000` 当前主界面的 page subtree / filetree / preferred snapshot 补偿链也完成统一验收。 diff --git a/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md b/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md index 91ccdc72..0361a0d3 100644 --- a/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md +++ b/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md @@ -1,11 +1,11 @@ # 5-5 [process] 主编辑区与树域单一真源对齐方案 v1 -> 更新时间：2026-04-22 +> 更新时间：2026-05-09 > > 关联文档： > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-4-leptos-tiptap-mainline-correction-v1.md` > - `/mnt/Data1T/mnote/design/old/05-editor-mainline/process/5-3-tiptap-leptos-rust-migration-checklist-v1.md` -> - `/mnt/Data1T/mnote/design/04-tree-domain/process/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md` +> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md` > - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-4-tree-projection-protocol-contract-v1.md` > - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md` > - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md` @@ -34,7 +34,7 @@ 它现在更接近于： -> **`Rust-aware + Convex-backed + 前端本地组装` 的混合态。** +> **`Rust snapshot 优先 + Convex-backed + 前端 fallback / 本地 state 仍存在` 的混合态。** 因此，当前看到的这些“小问题”： @@ -60,10 +60,9 @@ 但以下事实仍然成立： -- 标题链路虽已开始与树域 canonical snapshot 对齐，但还没有和正文、页面设置统一成同一组 page aggregate command family -- 页面正文是一条独立保存链 -- 页面设置又是一条独立更新链 -- 页面树 / 文件树与页头标题的一致性已明显改善，但当前 page aggregate projection 仍主要由前端装配而不是 Rust 原生提供 +- 读取主链虽已优先消费 Rust `mnote.page_aggregate.v1` snapshot，但 snapshot 不可用时仍保留 TS fallback +- 标题、正文、页面设置虽已开始收口到同一组 page aggregate command family，但 projection 回流与运行时语义还没完全闭环 +- 页面树 / 文件树与页头标题的一致性已明显改善，但页头标题、页面设置与编辑器 runtime 还没有完全共享同一份聚合真相 - `pageOptions` 已部分进入 `leptos-tiptap` 运行时语义层，但还没有整体收口完成 所以当前不能把这条线描述成： @@ -110,27 +109,24 @@ ## 3.1 当前页面数据并不是一个统一聚合 -当前文档页在加载时，实际上是把几类数据拆开读取，再由前端壳层重新拼装： +当前文档页读取主链已经优先走 Rust `mnote.page_aggregate.v1` 快照，再在 snapshot 不可用或不可信时回退到 TS builder： -- 页面 meta -- 页面标题 -- 页面设置 -- 页面正文 -- 页面子树快照 +- Rust `/api/page-aggregate/:id` snapshot +- TS fallback builder +- 页面本地 aggregate state reducer +- preferred sidebar snapshot / 页头标题补偿链 -这意味着当前不是： +这意味着当前已经不再是： -- Rust 返回一份稳定的 page aggregate projection +- `page.tsx` 手工拉 `meta + content` 再现场拼 props -而是： +但也还不是： -- Next route 先查 meta -- 再查 content -- 再把 `title/options/content/pageSubtree` 手动组成页面 props +- 页面所有读写、标题回流、页面设置运行时语义都只围绕一份 Rust page aggregate 自动闭环 这条链本身已经说明： -> **当前页面不是消费一份 canonical page projection，而是消费几份分裂的子结果。** +> **当前页面已经进入 Rust-first 聚合读取阶段，但 canonical page projection 仍未成为页面域唯一真相。** ### 3.1.1 标题链已开始收口，但尚未完成页面聚合统一 diff --git a/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md b/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md index f2dd0b69..613fe7a3 100644 --- a/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md +++ b/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md @@ -1,6 +1,6 @@ # 5-6 [process] Page Aggregate 单一真源对齐执行清单 v1 -> 更新时间：2026-04-22 +> 更新时间：2026-05-09 > > 关联文档： > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md` @@ -30,6 +30,7 @@ ### 2.1 已经成立的事实 - [x] `leptos-tiptap` 已经成为页面内正式主编辑区，不再是 iframe bridge。 +- [x] `/api/documents/page` 已优先消费 Rust `mnote.page_aggregate.v1` snapshot，TS builder 退为 fallback。 - [x] 正文保存已经能按 `workspaceId/documentId` 正确落到对应页面。 - [x] 当前主编辑区已具备可继续推进的基础交互能力。 - [x] 当前问题已经不再是“能不能接入主编辑器”，而是“接入后如何收口为单一真源”。 @@ -78,7 +79,7 @@ - [x] 不再继续给 `DocumentPageProps`、`DocumentContentProps` 零散加字段来扩页面真相。 - [x] 文档页加载入口能明确区分“聚合读取结果”和“局部 UI 临时态”。 -补充：当前已新增 `page-aggregate-builder.ts`、`page-aggregate-loader.ts` 与 `/api/documents/page`，文档页 SSR 入口和 `DocumentContent` 的内容重试补拉都已改为消费同一份 `PageAggregateProjection`，不再由 `page.tsx` 手工拼 `meta + content`。Rust 侧仍未直接暴露同名 `Page Aggregate` projection route，但 `storage-convex-bridge` 与 `bridge-runtime` 已开始接受 `page.head.updateTitle / page.layout.updateOptions / page.body.save` 这组 page command family 的命名口径，因此这里先按“等价契约已出现”勾选完成。 +补充：当前已新增 `page-aggregate-builder.ts`、`page-aggregate-loader.ts` 与 `/api/documents/page`，文档页 SSR 入口和 `DocumentContent` 的内容重试补拉都已改为消费同一份 `PageAggregateProjection`，不再由 `page.tsx` 手工拼 `meta + content`。Rust 侧当前已直接暴露 `/api/page-aggregate/:id` 与 `mnote.page_aggregate.v1` snapshot；`page-aggregate-loader.ts` 会先校验并消费这条 Rust 读链，只有 snapshot 不可用或不可信时才回退到 TS builder。与此同时，`storage-convex-bridge` 与 `bridge-runtime` 已开始接受 `page.head.updateTitle / page.layout.updateOptions / page.body.save` 这组 page command family 的命名口径，因此这里按“读取契约已进入 Rust-first，写入命令面已开始收口”勾选完成。 ### 4.3 退出标准 diff --git a/design/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md b/design/old/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md similarity index 96% rename from design/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md rename to design/old/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md index 0e911f60..d8f4163b 100644 --- a/design/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md +++ b/design/old/05-editor-mainline/process/5-8-wolai-editor-state-automation-test-plan-v1.md @@ -1,4 +1,4 @@ -# 5-8 [process] Wolai 编辑态自动化测试方案 v1（已收口） +# 5-8 [process][recycle] Wolai 编辑态自动化测试方案 v1（已收口） > 更新时间：2026-04-30 >