08 定向 Bug Hunt + 架构文档刷新
## 08 定向 Bug Hunt（3.5） - Bug 1: 侧栏「复制页面」从 `/api/documents/duplicate` 迁移到 `copyTreeCommand()` → `/api/tree/commands`（`tree.subtree.copy`） - Bug 2: 侧栏「清空垃圾箱」标注 TODO，等待 Rust `tree.trash.empty` - Bug 3: 文档页「应用模板」标注 TODO，等待 Rust `tree.page.template` - Bug 4: 删除 `createChildDocumentCommand` 死代码（函数 + 类型 + 旧 Next.js `/api/documents/create-child` 路由） - 归档 4 份 bug 文档到 `bugs/04-tree-domain/done/` 和 `bugs/05-editor-mainline/done/` ## 架构文档刷新 - ARCHITECTURE.md: MVP 状态标记、三层树模型（§6.4）、8.4 AI 方向按 7-14 v2 修正、新增 8.5 定向 Bug Hunt 节、刷新 §5 和 §9 卡点描述 - AGENTS.md: 匹配 ARCHITECTURE.md 的 AI 方向和三层模型口径 - 08 checklist: 标记 7-14 v2 影响（Phase A/B/C 重命名、新增 9 项 checklist） 关联设计稿: 7-14 v2, 08
This commit is contained in:
lix-2026
+96
-8
@@ -1,6 +1,8 @@
|
||||
# MNOTE 当前架构梳理
|
||||
|
||||
> 更新时间：2026-05-16
|
||||
>
|
||||
> **当前阶段：初步 MVP 已达成。** 3000 下文档页完整读写链路（标题、正文、页面设置、Page Aggregate）、Sidebar/File Tree/Page Tree 三层树模型、tree command（`tree.*` preferred）、tree realtime SSE（snapshot/delta/resync）、页面 AI 快速编辑（fast-path < 1s，当前 `local_rule` planner 为过渡实现，长期方向为 markdown 级编辑，见 7-14）均已通过真实浏览器 smoke 验证。剩余工作集中在单一真源收口、live cache 统一、AI 编辑路径从块级收敛到 markdown 文本层，而非继续证明架构可行性。
|
||||
|
||||
本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。
|
||||
|
||||
@@ -19,6 +21,7 @@
|
||||
3. `mnote-web` 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
|
||||
4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
|
||||
5. `BlockNote` 已退出文档页默认主路径，仅作为历史参考实现 / 对照材料保留
|
||||
6. 页面 AI 工具链已建立最小闭环：`POST /api/page-ai/block-edit-workflow` 提供快速编辑 route（当前 `local_rule` planner 为过渡态，长期方向为 `mnote.doc.markdown_edit` 文本级搜索替换，见 7-14）；Hermes tools（`mnote.doc.*` / `mnote.block.*`）承担复杂任务编排
|
||||
|
||||
一句话收口：
|
||||
|
||||
@@ -27,6 +30,8 @@
|
||||
补充口径：
|
||||
|
||||
> **主 Web 执行面当前以 `mnote-web` 为 3000 owner；Next App Router 只保留为 legacy compat、交互 island bundle source 与显式 debug/迁移辅助边界。**
|
||||
>
|
||||
> **页面 AI 块编辑当前以 fast-path `local_rule` planner（`/api/page-ai/block-edit-workflow`）为简单操作首选；Hermes agent（`mnote.doc.*` / `mnote.block.*` tools）保留为复杂任务编排器。**
|
||||
|
||||
## 2. 当前主线目录
|
||||
|
||||
@@ -155,16 +160,23 @@
|
||||
- `page_tree` / `pageSubtree` 已进入统一聚合入口
|
||||
- 页面/块 AI tools 已开始通过 Page Aggregate block projection 读取、定位、dry-run、替换、插入和受限移动块，并经 `page.body.save -> documents:updateContent` 持久化
|
||||
|
||||
但仍未完成的关键点是：
|
||||
2026-05-16 更新：以下四项已通过真实 3000 browser smoke 验证（证据见 `tmp/page-aggregate-*` 目录）：
|
||||
|
||||
1. Rust 侧虽已提供最小 `Page Aggregate` snapshot 和 block projection v1，但当前 block projection 仍主要从 `documents.content` / local markdown content 投影，不是 EditorBlockDocument 原生落库完成态
|
||||
2. 标题 / 正文 / 页面设置虽已开始收口到 `page.*` family，但 projection 回流与运行时语义仍未完全统一
|
||||
3. AI 块工具最小闭环已启动，但 `scope=selection`、`format=page_xml/text`、多块插入、复杂块移动矩阵和持久审阅 UI 仍未完成
|
||||
4. 客户端仍保留 preferred sidebar snapshot 与本地 aggregate state reducer，说明页面域单一真源仍在推进中
|
||||
- 标题写入后 Page Aggregate、页头、Breadcrumb、Sidebar、Page Tree、File Tree 一致性（`task110`）
|
||||
- 正文保存后 `body.revision` / `conflictDetectionKey` / `blockDocument` 同步（`task-page-aggregate-body-sync-smoke`）
|
||||
- 页面设置写入后 `layout.pageOptions` 与 island runtime DOM 同步，刷新后不退回（`task-page-aggregate-options-sync-smoke` / `task-page-aggregate-refresh-persistence-smoke`）
|
||||
- Convex 不可用时返回 degraded error（503 + `x-error-code=convex_unavailable`），不返回伪 fixture（route 级负向测试）
|
||||
|
||||
仍未完成的关键点是：
|
||||
|
||||
1. Rust 侧已提供最小 `Page Aggregate` snapshot 和 block projection v1，但当前 block projection 仍主要从 `documents.content` / local markdown content 投影（`projectionSource=documents.content`），不是 EditorBlockDocument 原生落库完成态
|
||||
2. 标题 / 正文 / 页面设置虽已收口到 `page.*` family 并通过 smoke，但客户端仍保留 `PageAggregateClientState` reducer（混合 server snapshot / draft title / local content），页面域单一真源仍未完全闭环
|
||||
3. AI 块工具最小闭环已启动且 fast-path < 1s，但 `scope=selection`、`format=page_xml/text`、多块插入、复杂块移动矩阵和持久审阅 UI 仍未完成
|
||||
4. Sidebar 仍通过 preferred snapshot（initial / query / tree_stream）做 freshness 选择，tree realtime live cache 未统一
|
||||
|
||||
因此当前正确表述应是：
|
||||
|
||||
> **文档页读取主链已进入 Rust-first `page aggregate` 过渡态，但页面域单一真源仍未闭环。**
|
||||
> **文档页读取主链已进入 Rust-first `page aggregate` 过渡态，标题/正文/页面设置 smoke 已通过，但页面域单一真源（ClientState → Rust snapshot）与 tree realtime live cache 仍未闭环。**
|
||||
|
||||
## 6. 当前树域结构
|
||||
|
||||
@@ -221,6 +233,20 @@
|
||||
|
||||
> **`3000` 主壳当前已不再通过 `/api/tree/projections/*` 额外维护第二条 runtime live fallback；snapshot / delta / resync 直接消费 `/api/tree/events` 载荷。**
|
||||
|
||||
### 6.4 Resource Tree / File Tree / Page Tree 三层模型
|
||||
|
||||
当前树域已建立三层语义（合同见 `design/04-tree-domain/done/4-24-*` 与 `design/05-editor-mainline/done/5-12-*`）：
|
||||
|
||||
- **Resource Tree**：长期 canonical 对象组织树，Rust kernel 持有语义。资源类型包括 page、mindmap、attachment、onlyoffice、code 等（`KernelObjectIdentity`、`KernelProjectionResourceKind` 已在 `core-protocol` 落地）。
|
||||
- **File Tree**：Resource Tree 的主组织投影。展示页面文件夹、`{title}.md`（非 `index.md`）、mindmap、附件等资源。文件树行消费 Rust `/api/tree/projections/file` 或等价 projection，不在前端临时拼装第二真相。
|
||||
- **Page Tree**：面向阅读/导航的快捷投影。只显示页面关系和导航语义，不拥有排序、父子、附件归属的最终真相。
|
||||
|
||||
关键规则：
|
||||
|
||||
- 文件树点击 mindmap 打开 mindmap object editor，不被 `{title}.md` 吞掉
|
||||
- `{title}.md` 只代表页面正文（Page Aggregate body），mindmap / OnlyOffice / 附件是不同 object model
|
||||
- 页面树不持有独立结构真相，只显示文档导航关系
|
||||
|
||||
## 7. Mindmap 与 OnlyOffice
|
||||
|
||||
### 7.1 Mindmap
|
||||
@@ -253,6 +279,17 @@ OnlyOffice 仍然是：
|
||||
目标：
|
||||
|
||||
- 让标题 / 页面设置 / 正文 / page tree 统一成同一组 page aggregate projection 与 command family
|
||||
- 前端不在页面壳、island 外侧、Sidebar preferred snapshot 外再拼第二份页面真相
|
||||
|
||||
当前进度（2026-05-16）：
|
||||
|
||||
- ✅ 文档页读取主链已 Rust-first，TS builder 退出 runtime，Next compat 返回 410
|
||||
- ✅ 标题单一真源 smoke 通过（`task110`）：页头/Breadcrumb/Sidebar/Page Tree/File Tree 一致
|
||||
- ✅ 正文写入后 `body.revision` / `blockDocument` 同步 smoke 通过
|
||||
- ✅ 页面设置写入后 `pageOptions` 同步与刷新持久化 smoke 通过
|
||||
- ✅ Convex 不可用时返回 degraded error，不返回伪 fixture
|
||||
- ⬜ block projection 从 EditorBlockDocument 原生落库（当前仍从 `documents.content` 投影）
|
||||
- ⬜ 客户端 `PageAggregateClientState` reducer 退役，页面域完全以 Rust snapshot 为单一运行时真相
|
||||
|
||||
对应设计稿：
|
||||
|
||||
@@ -290,9 +327,58 @@ OnlyOffice 仍然是：
|
||||
- 把 `mnote.page.save` 固定为页面级兜底写入工具，不再代表长期精确块编辑主入口
|
||||
- 补齐 `scope=selection`、`format=page_xml/text`、多块插入、复杂块移动矩阵和持久审阅 UI
|
||||
|
||||
当前进度（2026-05-16，按 7-14 v2 更新）：
|
||||
|
||||
- ✅ 页面 AI 快速编辑 route 已上线：`POST /api/page-ai/block-edit-workflow`
|
||||
- ✅ 简单编辑本地 planner（`local_rule`）已验证：788ms（过渡实现，将被 `markdown_edit` 替代）
|
||||
- ✅ Hermes tools（`mnote.doc.*` / `mnote.block.*`）已可读取和写入块投影
|
||||
- ✅ 参考实现已确认两层模型可行性：CLI Main（Lark Doc）`str_replace` 对应 `markdown_edit`，`block_*` 对应 `apply_block_ops`
|
||||
- ⬜ **Phase A（当前唯一活跃实施）**：`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强（search/replace + `format: "markdown"` + local source + Hermes 注册）
|
||||
- ⬜ **Phase B（下一阶段）**：退役 `direct_block_edit_operations`，`page_ai_workflow.rs` 改走 `markdown_edit`，system prompt 产 search/replace 对
|
||||
- ⬜ `scope=selection`、`format=page_xml/text` 稳定输出
|
||||
- ⬜ tool manifest annotations（`readonly` / `destructive` / `requiresApproval` 等）
|
||||
- ⬜ **Phase C（设计冻结，不实施）**：`StreamApplyController` + `ReviewSession` + `GhostTextOverlay`（流式 apply + suggest/review）
|
||||
- ⬜ stale revision / idempotency 重放保护（已有 revision 乐观锁覆盖，补端到端 smoke）
|
||||
|
||||
关键原则（2026-05-16 补充，按 7-14 v2 更新）：
|
||||
|
||||
- **两层操作模型**（参考 CLI Main Lark Doc）：文本级 `mnote.doc.markdown_edit`（str_replace）为主路径（覆盖 80%+ 场景），块级 `mnote.doc.apply_block_ops` 为结构性辅助（< 20%）
|
||||
- AI 编辑主路径应从块级降维到 markdown 文本层：新增 `mnote.doc.markdown_edit`（search/replace 或 full_content）作为主要 AI 写入工具
|
||||
- `mnote.block.*` 降级为结构性辅助（拖拽排序、精确块删除等），不删除
|
||||
- 当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应退役并替换为模型产出 search/replace 对
|
||||
- 在线 Convex 文档和本地 `.md` 文件共用同一条 markdown AI 写入路径（`resolve_source` → Convex | LocalFS）
|
||||
- Markdown 既是 AI 编辑格式也是人类可读格式，不需要 XML 中间层
|
||||
- 流式 apply + suggest/review（参考 BlockNote AI 的 `StreamToolExecutor` + `suggestChanges`）仅作为 Phase C 设计冻结，当前不实施
|
||||
|
||||
对应设计稿：
|
||||
|
||||
- `/mnt/Data1T/mnote/design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`
|
||||
- `/mnt/Data1T/mnote/design/10-review/process/09-page-ai-fast-block-edit-runtime-review.md`
|
||||
- `/mnt/Data1T/mnote/design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md`
|
||||
|
||||
### 8.5 定向 Bug Hunt 与质量基线
|
||||
|
||||
目标：
|
||||
|
||||
- 围绕已知架构风险做定向排查，而非泛泛"找 bug"
|
||||
|
||||
优先关注：
|
||||
|
||||
- Page Aggregate 回流不一致
|
||||
- AI 块写入 conflict / stale revision
|
||||
- File Tree `{title}.md` 与 page title 同步
|
||||
- tree stream resync / 双浏览器一致性
|
||||
- debug / compat / fallback 是否混入首屏主链
|
||||
|
||||
已有 smoke 体系（`scripts/` 目录）：
|
||||
|
||||
- `task110-page-title-single-truth-smoke.js`：标题全链路一致性
|
||||
- `task-page-aggregate-body-sync-smoke.js`：正文写入后 Page Aggregate 同步
|
||||
- `task-page-aggregate-options-sync-smoke.js`：页面设置写入后同步
|
||||
- `task-page-aggregate-refresh-persistence-smoke.js`：刷新持久化
|
||||
- `task123-rust-web-tree-live-stream-consumer-smoke.js`：tree realtime 消费
|
||||
- `task169-mindmap-realtime-smoke.js`：mindmap 隔离与持久化
|
||||
- `task179-tree-create-delete-no-reload-smoke.js`：树操作无刷新
|
||||
|
||||
## 9. 当前不该再用的旧口径
|
||||
|
||||
@@ -302,7 +388,9 @@ OnlyOffice 仍然是：
|
||||
- “主编辑器还没切到页面内 Leptos island”
|
||||
- “当前最优先是继续证明 `leptos-tiptap` 能不能跑”
|
||||
- “当前最优先是先做树域 UI 重构”
|
||||
- “Rust Web 还只是实验，没有接真实页面链路”
|
||||
- “页面 AI 编辑必须经过 Hermes agent，没有快路径”
|
||||
|
||||
当前真正的卡点已经变成：
|
||||
当前真正的卡点已经从“能不能跑”变成：
|
||||
|
||||
> **单一真源如何收口，以及 projection / command / realtime 三条链如何从兼容态进入正式主链。**
|
||||
> **单一真源如何收口（Page Aggregate ClientState → Rust snapshot），projection / command / realtime 三条链如何从兼容态进入正式主链，以及 AI 块编辑如何从“能写”变成产品级可靠（selection、review、conflict、idempotency）。**
|
||||
|
||||
Reference in New Issue
Block a user