lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 收口 review 执行清单与 runtime 验证

Browse Source 
- 补齐 design/10-review 执行清单、验收标准与相关设计治理记录

- 迁移已完成的 tree、mindmap、runtime fallback、AI kernel 等设计和缺陷条目

- 推进 Rust Web runtime、tree/sidebar、page aggregate、mindmap 与 OnlyOffice 路由侧验证支撑

- 增加 task177-task180 smoke/audit 脚本及前端相关测试覆盖
This commit is contained in:
lix-2026
2026-05-14 05:52:08 +08:00
parent b4a452a8b7
commit 96e03645f7
69 changed files with 4780 additions and 979 deletions
Download Patch File Download Diff File Expand all files Collapse all files
design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md
+16 -11
View File
@@ -47,7 +47,7 @@
- [x] `Phase 2` 文档阅读态分离已经有实质代码
- [x] `Phase 3` 主 Sidebar 已出现 `kernelSidebarTree` 消费接缝
- [x] `Phase 4` 搜索已做 host/runtime 拆分，并开始返回 `nodeId` / `subtreeRootId` / `evidence`
- [x] `Phase 5` AI 面板已做 host/runtime 拆分，并开始向 AI bridge 传递 `node` / `subtree` / `outline` / `evidence`；长期执行面应收口到 `mnote-cli`，Web 只作为 CLI host / client，`openai-agents-python` / Hermes / Codex 只作为可插拔外置 agent
- [x] `Phase 5` AI 面板已做 host/runtime 拆分，并开始向 AI bridge 传递 `node` / `subtree` / `outline` / `evidence`；2026-05-13 起长期方向改为 Hermes 页面内客户端 + mnote Hermes skill/plugin，旧 CLI host 只保留为历史/兼容证据
- [x] `Phase 6` Mindmap 独立页已去掉 `editorStub` 主入口
- [x] `Phase 7` 阅读态已直接消费 `pageSubtree`，`BlockNote` 也已不是文档页默认唯一入口
@@ -107,7 +107,7 @@
| Phase 2 | 文档阅读页 server-first 化 | `PARTIAL` 接近 `DONE` | 阅读态/编辑态已明显分离，但仍有旧链回退和大量客户端状态集中在 `DocumentContent` |
| Phase 3 | Sidebar / 树结构 Rust 化 | `PARTIAL` 偏早期 | 主 Sidebar 已以 `kernelSidebarTree` 作为主树来源，但整体仍是超大客户端组件 |
| Phase 4 | 搜索 Rust 化与 island 化 | `PARTIAL` | host/runtime 懒加载拆分已做，结果形状也开始带 `nodeId` / `subtreeRootId` / `evidence`，但仍未完成 server-first 搜索页 |
| Phase 5 | AI 面板 bridge island 化 | `PARTIAL` | host/runtime 拆分已做，且已开始把 `node` / `subtree` / `outline` / `evidence` 送入 AI bridge；长期执行统一落在 `mnote-cli`，Web 面板只做 host / adapter，但 runtime 仍重，协议也未统一到真正“最小壳” |
| 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，旧链彻底删除仍待后续 |
@@ -290,10 +290,15 @@
---
## 10. Phase 5：AI 面板进一步收口为 `mnote-cli` host / 纯桥接 island
## 10. Phase 5：AI 面板收口为 Hermes 页面内客户端 / mnote plugin bridge
**当前状态：`PARTIAL`**
> 2026-05-13 口径更新：
> - 本阶段原先把页面 AI 继续收口为 `mnote-cli host / client`，现在已被 `design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md` 覆盖。
> - 新长期方向是：页面 AI 面板使用 Leptos 实现 Hermes 页面内客户端；Hermes session/message/tool event/usage/model 是 AI 会话真相；mnote 只通过 Hermes skill/plugin 暴露页面、树、artifact、edge 等业务能力。
> - `mnote-cli` 只能作为 plugin 内部适配器或调试入口，不能再被写成页面 AI 唯一长期执行面。
### 10.1 已落地事实
- [x] 文档页 AI 已拆为 host + runtime
@@ -301,24 +306,24 @@
- [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx)
- [x] Mindmap / OnlyOffice 也有类似 runtime 拆分
- [x] `GlobalAiAgentHost` 已不在 `(app)/layout.tsx` 主布局中挂载
- [x] 文档页 AI 已开始把 `node` / `subtree` / `outline` / `evidence` 传给 AI bridge；长期执行面应收口到 `mnote-cli`，页面 AI 只保留为 CLI host / client，`openai-agents-python` / Hermes / Codex 只作为可插拔外置 agent
- [x] 文档页 AI 已开始把 `node` / `subtree` / `outline` / `evidence` 传给 AI bridge；后续应改为 Hermes run/session context，由 Hermes 通过 mnote skill/plugin 回读和写入业务事实
- [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx)
- [route.ts](/mnt/Data1T/mnote/wolai-frontend/src/app/api/ai-agent/run/route.ts)
### 10.2 当前还没完成
- [ ] runtime 组件仍然非常重
- [ ] “最小会话协议、统一流式协议、页面上下文协议”还更多体现在组件内部，不是系统级协议层
- [ ] 还不能说 AI 面板已经变成“纯桥接壳”
- [ ] “最小会话协议、统一流式协议、页面上下文协议”还更多体现在组件内部，不是 Hermes client proxy / plugin tool contract
- [ ] 还不能说 AI 面板已经变成“只调用 Hermes 的页面内客户端”
- [ ] 页面级 AI adapter 仍然很大，只是改成了懒加载
- [ ] AI 已能消费 `node` / `subtree` / `outline` / `evidence` 上下文，但还不是统一的 `mnote-cli` kernel-first tool 协议；Web 面板也还没有彻底退成单纯 host / adapter
- [ ] AI 已能消费 `node` / `subtree` / `outline` / `evidence` 上下文，但还没有进入稳定 Hermes session/run context 与 mnote plugin tool 协议；Web 面板也还没有彻底退成 Hermes client
### 10.3 v2 后续任务
- [ ] 继续下沉 runtime 内状态与协议
- [ ] 把会话、tool event、client action 收口到共享协议层
- [ ] 让 runtime 再减重，而不只是拆文件
- [ ] 把当前上下文注入进一步收口为更稳定的 kernel node / subtree / edge bridge
- [ ] 移除页面 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
---
design/03-rust-web/process/3-15-runtime-fallback-retirement-checklist-v1.md
-155
View File
@@ -1,155 +0,0 @@
# 3-15 [process] Runtime Fallback 退场 Checklist v1
> 更新时间：2026-05-09
>
> 关联：
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-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/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md`
## 1. 目标
这份 checklist 只回答一件事：
> **把已经不该继续充当系统组件的 runtime fallback、compat、legacy 与对照链，尽快退出主路径。**
本轮采用激进退场口径：
- 能退场的先退场
- 退场对象同时退出运行时、默认入口与活跃设计口径
- `/mnt/Data1T/mnote/recycle` 只保留参考物，不再参与系统主路径
## 2. 主路径白名单
下面这些属于必须保活的主路径：
- [x] 文档页打开链继续可用
- [x] Sidebar 继续可用
- [x] `/api/tree/events` realtime 主链继续可用
- [x] 页面标题保存继续可用
- [x] 页面设置保存继续可用
- [x] 正文保存继续可用
下面这些不再享有默认兼容资格，可直接进入退场名单：
- [x] `BlockNote` fallback / 对照链
- [x] AI provider 直连分支（`Hermes` / `Codex` / 旧 orchestrator compat）
- [x] legacy Next compat / alias / debug 壳
- [x] TS page aggregate builder fallback
- [x] 仍以旧 owner / 旧 fallback 作为默认系统组件的活跃文档表述
## 3. 总原则
- [x] 不再把“开发态”作为保留 fallback 的理由
- [x] 不再把“以后可能参考”作为继续挂在主路径上的理由
- [x] 凡移入 `recycle/` 的对象，都必须先断开主路径 import / route / fallback 选择
- [x] 主路径缺口优先补 Rust-first 正式链，不恢复 legacy fallback
- [x] 次要入口允许直接 404 / 410 / 501，不再静默降级
## 4. 第一波：立即退场
### 4.1 `BlockNote` fallback / 对照链
- [x] 删除页面壳里“显式切回 BlockNote”的默认入口
- [x] 删除 `leptos-tiptap` host 中仅用于切回 `BlockNote` 的 fallback 触发链
- [x] 把 `BlockNote` 从“系统默认可退回编辑器”降为 `recycle` 参考实现
- [x] 活跃设计稿中不再把 `BlockNote` 写成系统 fallback，只允许写成历史对照链
### 4.2 AI provider 直连分支
- [x] 删除 Next `/api/ai-agent/run` 中 `provider=codex` 直连分支
- [x] 删除 Next `/api/ai-agent/run` 中 `provider=hermes` 直连分支
- [x] 删除 Rust `compat` 中代理到 legacy Next AI route 的优先分支
- [x] 删除 Rust `compat` 中 direct Hermes 分支
- [x] 删除 Rust `compat` 中 document AI orchestrator fallback 分支
- [x] 统一只保留 `mnote-cli` host 作为默认主执行入口
- [x] 次要 provider 请求改为明确失败，不再静默降级
### 4.3 legacy Next compat / alias / debug 壳
- [x] 删除 `/api/mnote-web/stream` 这类 tree stream compat alias
- [x] 删除 `legacy_next_proxy` 默认 fallback
- [x] 删除仅为 legacy Next upstream 保留的 route fallback
- [x] 删除默认可见 debug shell / compat shell 入口
- [x] 仅在明确内部调试需要时，才允许保留隔离后的 debug 文件到 `recycle/`
## 5. 第二波：主链清障后退场
### 5.1 `page aggregate` TS fallback
- [x] 删除 `/api/documents/page` 读链里的 TS builder fallback
- [x] 文档页读取只保留 Rust `/api/page-aggregate/:id` 正式快照
- [x] snapshot 不可用时直接显式失败，不再组装 fallback projection
- [x] 活跃设计稿不再写“Rust-first + TS fallback 混合态”，改成单一路径
### 5.2 页面域本地兼容状态
- [x] 识别 `page aggregate client state` 中仅为旧链兜底存在的字段
- [x] 删除标题 / 页面设置 / 正文之间的兼容性双轨状态
- [x] 删除只服务旧 fallback editor host 的状态同步分支
- [x] 页面域只保留围绕正式 `page.*` command family 的状态回流
### 5.3 tree realtime / sidebar 补偿链
- [x] 删除 preferred snapshot 选择链中只为旧链存在的补偿分支
- [x] 删除 Sidebar / page subtree / filetree 中旧 snapshot 回闪兜底
- [x] `3000` 主壳只保留 `/api/tree/events` snapshot + delta + resync 主链
- [x] 不再为 legacy route 额外维护第二条 live cache 语义
## 6. 第三波：统一归档到 `recycle/`
### 6.1 设计稿与说明
- [x] 将已退场实现对应的设计稿移到 `design/old/` 或 `recycle/design/`
- [x] 活跃 `process/` 文档移除对已退场 runtime 的默认依赖描述
- [x] `ARCHITECTURE.md` / `AGENTS.md` 不再把退场对象写成系统组件
### 6.2 参考实现与脚本
- [x] 将退场 runtime 的参考代码移动到 `recycle/` 对应目录
- [x] 将只服务旧链的 smoke / fixture / helper 脚本移到 `recycle/`
- [x] 清除主路径中对这些参考实现的 import、route 注册和 UI 入口
## 7. 执行顺序
- [x] 先完成第一波：砍掉次要入口默认资格
- [x] 再完成第二波：清掉主路径底下的假单一路径
- [x] 最后完成第三波：统一归档文档、脚本和参考代码
## 8. 验收标准
### 8.1 必须成立
- [x] 文档页仍能打开
- [x] Sidebar 仍能使用
- [x] tree realtime 主链仍能工作
- [x] 标题保存、页面设置保存、正文保存仍能工作
- [x] 默认主路径不再出现“切回 legacy / fallback / compat”按钮或自动分支
### 8.2 必须消失
- [x] 默认运行时不再自动触发 `BlockNote` fallback
- [x] 默认 AI 运行时不再直连 `Hermes` / `Codex` / 旧 orchestrator compat
- [x] 默认 gateway 不再把 legacy Next 当作未迁路径的总兜底
- [x] `/api/documents/page` 不再在 runtime 中组装 TS fallback projection
### 8.3 允许接受
- [x] 次要入口直接报错
- [x] 历史 debug 壳直接下线
- [x] 某些只服务旧链的测试暂时删除后再按新主链重建
## 9. 禁止项
- [x] 不以“先保留一下，以后可能有用”为理由继续保活 fallback
- [x] 不把已移入 `recycle/` 的代码继续通过主路径 import 回来
- [x] 不再新增任何新的 compat / fallback / legacy route
- [x] 不通过文档口径美化来掩盖 runtime 仍依赖 fallback 的事实
## 10. 一句话收口
> **这轮不是“继续整理兼容层”，而是“把不再属于系统组件的 fallback 全部赶出主路径，只保留主路径白名单”。**
design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md
+9 -7
View File
@@ -25,7 +25,7 @@
- Rust 内核和 Web 承载层如何分工
- 前端哪些部分应该退出当前重 React 壳
- `axum`、`Leptos` 这类 Rust Web 方案是否值得采用
- `mnote-cli` 应如何成为唯一长期 agent 执行面
- 页面 AI 应如何作为 Hermes 页面内客户端接入，并让 mnote 通过 Hermes skill/plugin 暴露业务能力
- 默认主编辑器已经切到页面内 `leptos-tiptap` island 后，剩余重编辑兼容链应如何继续收口
---
@@ -57,7 +57,8 @@
- **业务执行面：现有 Rust workspace 继续作为唯一业务真执行面**
- **Web 承载层：`axum`**
- **页面渲染模型：`Leptos Islands`**
- **AI 执行面：`mnote-cli`**
- **AI 会话与编排面：Hermes**
- **mnote AI 能力面：Hermes skill/plugin -> Rust runtime / kernel**
- **最后保留的重编辑兼容孤岛：少量编辑器 runtime（当前默认主编辑器已是页面内 `leptos-tiptap` island，`BlockNote` 仅保留为 `recycle/` 历史参考副本）**
一句话概括：
@@ -180,7 +181,7 @@
- 文档查询与聚合层
- 树结构装配层
- 搜索服务层
- AI bridge / CLI host 层；长期 agent 执行面只收口到 `mnote-cli`，Hermes 仅作为历史兼容 bridge / 外置 adapter
- Hermes client proxy 与 mnote tool bridge 层；页面 AI 会话真相归 Hermes，mnote 业务工具最终回到 Rust runtime / kernel
- 页面 SSR 外壳承载层
- 流式更新、通知、事件推送层
@@ -413,14 +414,15 @@ Leptos Islands 很适合承接下面这类长期目标：
目标：
- 继续桥接统一 CLI host
- 不再承担前端本地 orchestration
- 作为 Hermes 页面内客户端运行
- 不再承担前端本地 orchestration 或私有会话存储
- 不再成为常驻大壳的一部分
归位：
- 面板只保留最小 UI 与上下文桥接
- 工具执行全部走 `mnote-cli` + Rust tools
- 面板只保留 Hermes chat/session/run/tool event 的页面内子集 UI 与当前页面上下文桥接
- Hermes 持有 session / message / usage / model 真相
- mnote 通过 Hermes skill/plugin 暴露页面、树、artifact、edge 工具，最终执行回到 Rust runtime / kernel
- 面板按页面需要懒挂载成单独 island
### 9.5 Mindmap