mnote/design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md

3-1 [process] Rust Web 长期架构实施清单 v2

更新时间：2026-04-29

基于以下实际状态重写：

• 当前未提交代码
• /mnt/Data1T/mnote/harness-tasks.json 中 task-059 ~ task-069
• /mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md
• /mnt/Data1T/mnote/design/old/03-rust-web/process/rust-web-long-term-checklist-v1.md
• /mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md

1. 这版为什么要重写

这次重写的原因很明确：

• task-059 ~ task-069 目前在 harness-tasks.json 里已经被标为 completed
• 但从当前未提交代码实际看，很多项只证明了：
  • 文档已补
  • 骨架已建
  • 局部组件已拆
  • eslint / cargo check 可过
• 并不能证明对应长期阶段已经真正完成

因此这版 checklist 的目标不是重复愿景，而是：

把长期路线重新落回“真实代码状态”，明确哪些已经落地、哪些只是最小接缝、哪些仍未开始。

说明（2026-04-22）： 这份清单仍保留为 Rust Web 分阶段全景参考，但当前最近一步不再是泛化推进全部 Phase， 而是优先推进 Page Aggregate、tree command cutover、tree realtime event stream。 当前执行优先级请先看 /mnt/Data1T/mnote/design/01-05-current-priority-overview.md。

复核补充（2026-04-29）：3000 默认 owner 已是 mnote-web，根页 / 文档页 / tree events / leptos-tiptap island 已进入 Rust Web 主链；本清单继续保留在 process/，因为主 API 全量迁移、旧 Next/React 链清理、Search/AI/Mindmap 轻壳化仍未完成。

---

2. 当前总判断

从当前代码看，长期路线的真实状态是：

2.1 已有明确进展

• Phase 0 的文档化边界梳理已经完成
• Phase 1 已落了一个最小 axum Web 骨架：rust/crates/mnote-web/
• Phase 1 已不再只是空骨架，现已包含 kernel / bridge / compat sidebar 的真实查询接缝
• Phase 1 已成为 3000 主 Web 入口 owner，根页、文档页、tree stream 与主要 shell marker 均由 mnote-web 输出
• Phase 2 文档阅读态分离已经有实质代码
• Phase 3 主 Sidebar 已出现 kernelSidebarTree 消费接缝
• Phase 4 搜索已做 host/runtime 拆分，并开始返回 nodeId / subtreeRootId / evidence
• Phase 5 AI 面板已做 host/runtime 拆分，并开始向 AI bridge 传递 node / subtree / outline / evidence；2026-05-13 起长期方向改为 Hermes 页面内客户端 + mnote Hermes skill/plugin，旧 CLI host 只保留为历史/兼容证据
• Phase 6 Mindmap 独立页已去掉 editorStub 主入口
• Phase 7 阅读态已直接消费 pageSubtree，BlockNote 也已不是文档页默认唯一入口

2.2 但大部分阶段都只是“部分落地”

• Phase 1 已不再只是 skeleton：3000 默认 owner 已是 Rust Web，根页 / 文档页 SSR 产品壳已进入主路径
• Phase 1 的主 API 全量迁移与 legacy compat 清理仍未完成
• Phase 3 legacy Sidebar 仍是超大客户端组件；当前 Rust Web 3000 已有页面树 / 文件树 SSR tab host，但 live stream 消费侧还未完全闭环
• Phase 4 搜索仍是前端 runtime 主导，不是 server-first 搜索页
• Phase 5 AI runtime 仍然很重，只是懒挂载了
• Phase 6 Mindmap 仍然是重前端交互壳，不是独立对象页壳
• Phase 7 文档页外围面板仍集中在 DocumentContent
• Phase 8 主入口已切到 mnote-web，Next App Router 降为 legacy compat / island bundle source；彻底删除旧链仍留给后续清理

2.3 结论

当前真实状态不是“Phase 0 ~ 8 已全部完成”，而是“Phase 0 的 Rust Web 主入口和页面壳目标已完成，但主 API 迁移仍处于部分落地；Phase 2/4/5/6/7 仍处于不同程度的部分落地，Phase 3 的 3000 SSR 树壳已补实但 legacy Sidebar 与 live stream 消费侧仍需继续收口；Phase 8 已完成主入口 owner cutover，但旧 Next/React 链仍作为 legacy compat / island source 保留”。

---

3. 重新定义状态口径

为了避免再次把“有骨架”写成“已完成”，v2 统一使用下面三种状态：

DONE

定义：

• 代码主路径已经切换
• 不是只有文档或骨架
• 用户可感知行为已经变了
• 后续只剩清理和补强

PARTIAL

定义：

• 已有真实代码改动
• 但仍是局部接缝、最小骨架、阶段性拆分
• 主路径尚未彻底切换

NOT_STARTED

定义：

• 还停留在设计或口径层
• 或只有零散基础，不足以算阶段开始

---

4. 基于真实代码的阶段总览

阶段	v1 口径	当前真实状态	说明
Phase 0	边界冻结	DONE	文档、候选模块、边界口径已经成形，但性能基线更多还是文档定义，不是完整观测系统
Phase 1	Rust Web 基础层	PARTIAL 接近 DONE	mnote-web 已成为 3000 主 Web 入口 owner，根页 / 文档页 SSR 产品壳、tree stream 与关键 API 接缝已落地；主 API 全量迁移、compat 清理与 legacy island source 清理仍未完成
Phase 2	文档阅读页 server-first 化	PARTIAL 接近 DONE	阅读态/编辑态已明显分离，但仍有旧链回退和大量客户端状态集中在 DocumentContent
Phase 3	Sidebar / 树结构 Rust 化	PARTIAL	主 Sidebar 已以 kernelSidebarTree 作为主树来源；Rust 3000 主文档壳已完成 Page Tree / File Tree create/delete 与页面内 mindmap asset create 的 no-refresh 验收，但整体仍是超大客户端组件
Phase 4	搜索 Rust 化与 island 化	PARTIAL	host/runtime 懒加载拆分已做，结果形状也开始带 nodeId / subtreeRootId / evidence，但仍未完成 server-first 搜索页
Phase 5	AI 面板 Hermes client island 化	PARTIAL	host/runtime 拆分已做，且已开始把 node / subtree / outline / evidence 送入 AI bridge；后续应把 Web 面板退成 Hermes 页面内客户端，把 mnote 能力注册为 Hermes skill/plugin，但 runtime 仍重，协议也未统一到 Hermes session/run/tool contract
Phase 6	Mindmap 独立对象化	PARTIAL	独立页脱离 editor stub 主入口，并补出 standalone / documentBridge 边界，但仍是客户端重壳
Phase 7	BlockNote 孤岛化	PARTIAL	阅读态已直接消费 pageSubtree，编辑器按需挂载，但外围 drawer/panel 仍集中在同一内容组件
Phase 8	旧前端壳下线	PARTIAL 接近 DONE	3000 gateway / 文档 shell / tree realtime / Search / AI bridge / Mindmap object shell 已由 mnote-web 持有；Next App Router 降为 legacy compat / island bundle source，旧链彻底删除仍待后续

---

5. Phase 0：基线与边界冻结

当前状态：DONE

5.1 已有事实

• 已有长期架构文档
• 已有长期 checklist 文档
• 已有 tree-first graph kernel 文档
• 已对文档页、Sidebar、Search、AI、Mindmap、OnlyOffice、BlockNote 做了模块级边界识别

5.2 当前仍不足的地方

• 真正可自动回归的性能基线系统仍未建立
• 统一 performance trace 采样点仍未进入运行时
• “冻结旧壳继续膨胀”目前更多靠文档与人工约束，不是代码级 guardrail

5.3 v2 完成判定

• 设计层边界冻结已完成
• 运行时观测层冻结仍未完成

---

6. Phase 1：Rust Web 基础层落地

当前状态：PARTIAL 接近 DONE；主入口和页面壳已完成，主 API 迁移与 compat 清理仍未完成

6.1 已落地事实

• Rust workspace 已并入 mnote-web
  • Cargo.toml
• 已存在 axum Web 骨架
  • Cargo.toml
• 已有统一 app/router 骨架
  • app.rs
  • mod.rs
• 已有 request context / middleware
  • context.rs
  • request_context.rs
• 已有最小 Hermes bridge route；当前仅按兼容 AI bridge 记录，不作为长期 agent 执行面
  • hermes.rs
• 已有 SSE / WS / compat route 骨架
• 已有真实 bridge / compat 接缝
  • bridge.rs
  • compat.rs
• kernel sidebar route 已通过 sidebar.dataset.list runtime plan + 通用 query transport 读取数据集
  • kernel.rs
• 3000 默认 owner 已是 mnote-web，GET / 返回 Rust Web workspace shell
  • gateway.rs
  • home.rs
• 已有主页面壳 SSR，/documents/:id 输出 Rust Web document shell、Page Aggregate marker 与 leptos_tiptap_island marker
  • web_shell.rs
  • document.rs
• Rust Web 已承接 tree commands、tree events、page aggregate、document save/title/options 等当前 3000 主链关键接缝
• 已用 task114/task115/task118/task119/task120/task121/task122 建立页面壳级和树 / 编辑器 runtime smoke 验证

6.2 仍未完成

• 主 API 还没有大面积全量从 Next route / legacy compat 迁出
• 当前 compat_next_base_path 仍说明它还带有兼容层属性，不是唯一承载层
• Next App Router / React islands 仍作为 legacy compat 与部分 bundle source 保留
• 复杂 runtime、OnlyOffice、历史 debug 链与旧前端代码还未完全清理

6.3 v2 后续任务

• 把 mnote-web 从 skeleton 提升为真实服务入口
• 把 sidebar kernel route 上的 fixture fallback 收到测试/开发边界，并承接真实页面壳与真实查询主链
• 明确 Next -> Rust Web 的流量切换边界：3000 归 mnote-web，Next 降为 legacy compat / island source
• 增加页面壳级集成验证，而不只是 cargo check
• 继续迁移剩余主 API，收缩 compat_next_base_path 与 legacy upstream 依赖

---

7. Phase 2：文档阅读页 server-first 化

当前状态：PARTIAL，但已经是最实的进展之一

7.1 已落地事实

• 文档页已在服务端预取 meta + content
  • page.tsx
• DocumentShell 已去掉 mounted gating
  • document-shell.tsx
• DocumentReadView 已作为阅读态渲染器落地
  • document-read-view.tsx
• DocumentContent 已有 isEditing / keepEditorMounted
  • document-content.tsx
• BlockNoteEditor 已不是默认唯一入口

7.2 当前还没完成

• 服务端读链失败时仍回退旧链
• 阅读态与编辑态虽已分开，但大量页面状态仍集中在 DocumentContent
• 评论、历史、回链、AI、页面选项虽然不是首屏阻塞，但仍在同一组件层集中管理
• 阅读页还不是一个真正极薄的 server-first 页面壳

7.3 v2 完成判定

• “先阅读、后编辑”的主行为已经出现
• “阅读页已经彻底轻壳化”还不能成立

---

8. Phase 3：Sidebar / 页面树 / 文件树 Rust 化与 island 化

当前状态：PARTIAL；3000 主文档壳 no-refresh 主链已闭环，Sidebar 瘦身仍未完成

8.1 已落地事实

• Sidebar 数据 query 契约此前已经有 Rust 化前进
• 布局服务端会先加载 sidebarInitialData
  • layout.tsx
• sidebar-data.ts 已生成 kernel_sidebar_projection 与 kernelSidebarTree
  • sidebar-data.ts
• 主 Sidebar 已以 sidebarData.kernelSidebarTree 作为初始树与同步来源
  • sidebar.tsx
• 已补统一 page_tree projection protocol，并让 PrivateTree / 文件树 / move-embed picker 共用
  • tree-projection.ts
• Rust Web 3000 workspace shell 已接入真实页面树 / 文件树 tab host、真实 row、UI 新建页面和 active page 链路
  • workspace_shell.rs
  • layout.rs
• Rust Web 3000 主文档壳已监听 tree:local-command 与同页 mindmap asset 写入，页面 create/delete 与页面内 mindmap create 均可在 Page Tree / File Tree 无刷新回显
  • layout.rs
  • task426-mnote-web-main-no-reload-smoke.js

8.2 当前真实问题

• Sidebar 仍然是超大客户端组件
  • sidebar.tsx
• 页面树 / 文件树在 3000 主文档壳下的 create/delete 与页面内 mindmap create 无刷新链路已验证；后续不能再用 3001/Next 或 /tree debug route 替代主链验收
• buildDocumentTree(...) 仅剩兼容 helper 与旧单测，不再位于树域主路径
• 主布局仍然默认常驻挂载 Sidebar
• 还不能叫“服务端输出 + 局部 island”，现在更像“服务端首包 + 超大客户端壳”

8.3 v2 后续任务

• 先拆 Sidebar 自身为 host / runtime 或分片 island
• 把树结构首包与交互态严格分层
• 把主 Sidebar 之外的 page tree、file tree、embed/move picker 也统一切到 kernel projection
• 把 3000 主文档壳内页面 create/delete 与页面内 mindmap create 的局部刷新协议显式化；后续新增资产类型时继续复用同一主入口验收口径
• 给 Sidebar 建立真正的切页重渲染基线

---

9. Phase 4：搜索系统 Rust 化与 island 化

当前状态：GREEN

9.1 已落地事实

• SearchPalette 已收口为轻量 host
  • search-palette.tsx
• 搜索 runtime 已按需动态加载
  • SearchPaletteHost.tsx
  • search-palette.runtime.tsx
• 搜索结果契约已开始带 nodeId / subtreeRootId / evidence
  • search-query-adapter.ts
  • search.ts

9.2 当前还没完成

• 主布局仍然默认挂载搜索 host
• 搜索仍主要是纯前端 runtime
• 没有真正的 server-first 搜索页
• 没有看到搜索 UI 直接接入 Rust Web 页面壳
• 结果形状虽已开始 kernel-aware，但检索真相层仍不是 Rust Web / kernel 真正主链
• 不能宣称“搜索系统 Rust 化”已完成，只能说“搜索 UI 体量开始拆分，结果契约开始收口”

9.3 v2 后续任务

• 把搜索页与浮层分开
• 先建立服务端搜索结果页壳
• 让 host 只保留热键与打开逻辑
• 减少全局常驻 store 对搜索的依赖
• 把 nodeId / subtreeRootId / evidence 结果形状继续推进到更真实的 Rust/kernel 检索主链

---

10. Phase 5：AI 面板收口为 Hermes 页面内客户端 / mnote plugin bridge

当前状态：PARTIAL

2026-05-14 口径更新：

• 本阶段原先把页面 AI 继续收口为 mnote-cli host / client，现在已被 design/07-ai/done/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md 覆盖。
• 新长期方向是：页面 AI 面板使用 Leptos 实现 ACP/Hermes 页面内客户端；产品层运行态索引、权限和审计默认落 SQLite control-plane；mnote 通过 Hermes skill/plugin 暴露页面、树、artifact、edge 等业务能力。Hermes/Reasonix runtime 的内部 session/message/tool event/usage/model 不等同于 MNote 产品层会话真相。
• mnote-cli 只能作为 plugin 内部适配器或调试入口，不能再被写成页面 AI 唯一长期执行面。
• design/07-ai/done/7-4-page-ai-hermes-panel-execution-checklist-v1.md 已把页面 AI 主链推进到 Hermes session/run/events，并完成 mnote.page.get、正文写入、标题/页面设置、artifact、legacy guard、持久化审计和正式 3000 smoke 矩阵；本节后续只跟踪 Rust Web 侧长期边界，不再保留旧 /api/ai-agent/run 待办作为当前状态。

10.1 已落地事实

• 文档页 AI 已拆为 host + runtime
  • DocumentAiAgentPanel.tsx
  • DocumentAiAgentPanel.runtime.tsx
• Mindmap / OnlyOffice 也有类似 runtime 拆分
• GlobalAiAgentHost 已不在 (app)/layout.tsx 主布局中挂载
• 页面 AI 主链已改为 mnote-web Hermes client proxy：创建/恢复 Hermes session，发起 Hermes run，消费 events，并从 Hermes session detail 刷新恢复
  • hermes_client.rs
• mnote 业务能力已通过 mnote Hermes tool routes 暴露，写入回到 Rust runtime / Page Aggregate command family / kernel
  • hermes_tools.rs
  • hermes_tools
• 旧 /api/ai-agent/run 在 mnote-web 中已退役为 410 legacy_ai_agent_run_retired guard，不再作为页面 AI 主入口
  • compat.rs

10.2 当前还没完成

• legacy React 文档页 AI runtime 文件仍然偏重，但它不再代表 Rust Web 3000 页面 AI 主链。
• node / subtree / edge 工具面还需要继续从页面上下文扩展成更稳定的 kernel-first Hermes plugin contract。
• Mindmap / OnlyOffice / generic AI 面板的旧域调用点仍需分别按各自 domain 拆迁移，不纳入“页面 AI Hermes 面板”完成定义。

10.3 v2 后续任务

• 移除页面 AI 对旧 /api/ai-agent/run 主路径的长期依赖，改走正式 Hermes client proxy
• 把会话、message、tool event、usage、model 选择交给 Hermes session 存储
• 把 mnote 页面、树、artifact、edge 第一批能力注册为 Hermes skill/plugin tools
• 把当前上下文注入进一步收口为 Hermes run context + 稳定 kernel node / subtree / edge tool bridge

---

11. Phase 6：Mindmap 独立对象化与独立页面化

当前状态：PARTIAL

11.1 已落地事实

• Rust 侧已有 Mindmap 对象协议与操作
• 独立页已先在服务端抓 initial projection，再交给客户端页面壳
• 独立页已直接使用 StandaloneMindmapView
  • page.tsx
• 旧 editorStub 依赖已经不在独立页入口上
• MindmapBlock.tsx 中已有 standalone / documentBridge 边界
  • MindmapBlock.tsx
• 文档内嵌导图已默认走 preview-first 入口

11.2 当前还没完成

• 独立导图页仍是客户端页面，不是独立对象页壳
• 仍然直接复用同一个重前端组件
• 文档内嵌导图虽然已经 preview-first，但进入编辑/沉浸态后仍复用同一套重组件
• Mindmap 还没有脱离“重交互前端壳优先”的事实
• 导图数据真相仍未通过 kernel subtree / command 形成稳定主链

11.3 v2 后续任务

• 把独立导图页壳和导图操作壳分离
• 让文档内嵌导图先变成轻预览/轻入口
• 继续把对象真相留在 Rust，而不是留在前端组件状态

---

12. Phase 7：文档编辑态与 BlockNote 孤岛化

当前状态：PARTIAL

12.1 已落地事实

• DocumentContent 已存在阅读态/编辑态切换
• BlockNoteEditor 已变成按需挂载
• keepEditorMounted 说明已开始按进入编辑态再保留编辑器
  • document-content.tsx
• 阅读态已直接消费 pageSubtree
  • document-content.tsx
  • document-read-view.tsx

12.2 当前还没完成

• DocumentContent 仍然同时管理：
  • DocumentAiAgentPanel
  • DocumentHistoryDrawer
  • DocumentCommentsDrawer
  • PageBacklinksPanel
  • PageOptionsSidebar
• pageSubtree 当前仍在前端内容层生成和消费，不是更薄的 Rust/kernel 输出边界
• 搜索/AI/阅读态虽然开始共享 node / subtree / outline / evidence 口径，但还没有回到统一的 kernel projection / subtree 真相协议面
• 这说明外围能力虽然不再阻塞首屏，但仍未真正完全从编辑器宿主层拆开
• BlockNote 还不能算“完全孤岛化”，只能算“默认不再首屏强挂”

12.3 v2 后续任务

• 把外围 drawer/panel 再次拆层
• 让编辑宿主只负责编辑
• 让阅读宿主只负责阅读
• 把 pageSubtree 的生成与消费继续下沉到更稳定的 server/kernel 边界

---

13. Phase 8：旧前端壳下线与兼容清理

当前状态：PARTIAL，主入口 owner cutover 已完成

13.1 直接证据

• 3000 默认 owner 已是 mnote-web Rust gateway。
• /auth、/documents/:id、/api/tree/events、/search、/api/hermes/bridge、/mindmap/:docId/:mindmapId 已具备 Rust Web owner / shell / transport contract。
• SKIP_NEXT_LEGACY=1 可证明核心 shell 不依赖 Next legacy upstream。
• Next App Router 已降为 legacy compat / React island bundle source，不再是主 Web 入口。

13.2 仍不能成立的说法

• “旧 Next/React 代码已经删除”
• “所有重交互 runtime 都已迁出 React island”
• “OnlyOffice、复杂编辑器与历史 debug 链都已完全退役”

13.3 v2 后续任务

• 继续清理 legacy compat route 与旧 Next 页面。
• 为仍保留的 React islands 建立更细的删除 / 替换清单。
• 保持 3104 只在显式 legacy/debug 场景可见，不恢复为公开入口。

---

14. 与 task-059 ~ task-069 的关系重定义

这组任务不应再被理解成：

• “长期 Phase 0 ~ 8 已全部完成”

更准确的理解应是：

• task-059 ~ task-061
  • 主要完成了长期路线的设计与口径定义
• task-062
  • 完成了 mnote-web 的最小骨架落地
• task-063
  • 完成了文档阅读态分离的核心第一步
• task-064
  • 只证明 Sidebar 主树已出现 kernel projection 消费接缝，不代表 Sidebar 重构完成
• task-065
  • 只证明搜索运行时开始拆重，不代表搜索系统完成 server-first 重构
• task-066
  • 只证明 AI host/runtime 拆分，不代表最小协议壳已经完成
• task-067
  • 只证明独立导图页切走 editor stub 主入口，并补出 standalone / documentBridge 边界，不代表 Mindmap 独立对象页完成
• task-068
  • 只证明 BlockNote 默认首屏强挂已解除，不代表完整孤岛化完成
• task-069
  • 只能算“统一回写了阶段口径”，不能算“Phase 8 真完成”

---

15. v2 推荐执行顺序

如果从真实代码继续往前推进，建议顺序改成：

1. Phase 1 继续做实
   • 先让 mnote-web 承接一条真实页面壳或真实查询主链
2. Phase 2 收尾
   • 把文档阅读页进一步轻壳化
3. Phase 3
   • 先打 Sidebar 本体，而不是继续写“已完成”
4. Phase 4 / Phase 5
   • 继续减 Search / AI runtime 重量
5. Phase 6
   • 让 Mindmap 真正从“重前端壳”中继续独立
6. Phase 7
   • 再拆 DocumentContent 外围面板
7. 最后才进入 Phase 8

---

16. 最终结论

当前未提交代码的真实含义是：

长期架构方向是对的，且已经开始进入真实代码；但 59-69 当前被标记为 completed 的口径明显偏乐观。

更准确的结论应是：

• Phase 0：基本完成
• Phase 1：已开始，骨架已落
• Phase 2：已明显落地，但未完全收尾
• Phase 3：仍远未完成
• Phase 4：只完成轻量拆分
• Phase 5：只完成轻量拆分
• Phase 6：只完成独立页去耦第一步
• Phase 7：只完成阅读/编辑分离第一步
• Phase 8：主入口 owner cutover 已完成，旧链清理继续推进

因此，从当前实际代码出发，接下来最需要的不是继续宣布完成，而是：

把 v1 的“愿景式 checklist”，改成 v2 的“基于真实代码状态的 checklist”，并据此重排后续 harness 任务状态。