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
2026-05-16 23:48:41 +08:00
parent f292c6710a
commit 46ede5e251
11 changed files with 231 additions and 53 deletions
@@ -12,6 +12,7 @@
 > - `/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/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-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-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`

@@ -35,12 +36,13 @@
 - 标题、正文、页面设置、page tree、AI 写入口尚未完全闭环到同一组 projection / command family。
 - `tree.*` 已是 preferred command name，但 `documents.*` 兼容命令面仍未完全降级。
 - `/api/tree/events` 已是 tree realtime 主链，但 Sidebar、page subtree、filetree、preferred snapshot 还没有完全统一到一套 live cache。
- AI 块工具已有最小闭环，但 selection、page_xml/text、多块插入、复杂块移动矩阵、持久 preview/review UI 和冲突矩阵仍未补齐。
+- AI 块工具已有最小闭环，但当前编辑路径以块操作（blockId）为中心——AI 被迫理解 UI 层概念，且本地 `.md` 文件无 AI 写入路径。`7-14` 提出应将 AI 编辑主路径修正为 markdown 文本级（search/replace），`mnote.block.*` 降级为结构性辅助，在线 Convex 文档与本地文件共用同一条 markdown 写入路径。

 补充 BlockNote / Tiptap AI 参考后的判断：

 - BlockNote AI 和 Tiptap AI Toolkit 可以参考的是 AI runtime shape 与 tool contract，不是 mnote 的事实源。
 - AI 方向下一步只应补基础底座：`PageAIContextBuilder`、`scope=selection`、`page_xml/text`、tool manifest annotations、`PageAIReviewSession`、accept/reject/retry/abort 状态机。
+- 2026-05-16 补充（受 `7-14` 方向修正）：AI 编辑主路径应从块级操作调整为 markdown 文本级 search/replace，新增 `mnote.doc.markdown_edit` 作为主要 AI 写入工具；当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应退役。在线 Convex 文档和本地 `.md` 文件共用同一条写入路径。
 - 在非 AI 主架构和 AI 基础合同打牢之前，不应扩展新的 AI agent 工作流、复杂 AI UI 或跨页面智能功能。

 因此，下一阶段不应优先“大改架构”或“大量加新功能”，而应优先做：
@@ -113,6 +115,14 @@
 - 不新增复杂 AI 自动化功能面。
 - 不把 `@blocknote/xl-ai` 或 BlockNote `AIExtension` 作为 runtime dependency。
 - 不让 AI 写入绕过 `dryRun/idempotencyKey/revision/conflictDetectionKey/revisionRef`。
+- **不把 `direct_block_edit_operations` / `local_rule` planner 当作长期 AI 编辑路径（当前为过渡实现，将被 `markdown_edit` 替代）。**
+- **不新增 `mnote.block.*` 工具；现有保留为结构性辅助。**
+
+**2026-05-16 新增（受 7-14 方向修正）：**
+
+- **Phase A（当前唯一活跃实施）**：`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强（search/replace + `format: "markdown"` + local source + Hermes 注册，7-14 v2 Phase A）。
+- **Phase B（下一阶段）**：退役 `direct_block_edit_operations`，`page_ai_workflow.rs` 改走 `markdown_edit`（7-14 v2 Phase B）。
+- 在线 Convex 文档和本地 `.md` 文件共用同一条 markdown AI 写入路径（`resolve_source` → Convex | LocalFS）。

 ### P1：定向 Bug Hunt

@@ -225,6 +235,29 @@ cargo test --manifest-path rust/Cargo.toml -p mnote-web document_shell_errors_wi
 - [ ] 更新 `design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md` 的每个 phase 证据。
 - [ ] 更新 `design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md` 的 Hermes 工具路由与审阅面 checklist。

+**新增（2026-05-16，受 7-14 方向修正）：**
+
+**Phase A（当前唯一活跃实施）：**
+- [ ] `mnote.doc.markdown_edit` 核心实现：resolve_source → search_replace → write_target
+- [ ] `mnote.doc.markdown_edit` 搜索替换语义：精确匹配 → fuzzy fallback → operationsFailed（7-14 §5）
+- [ ] `mnote.doc.markdown_edit` Convex 写入 adapter（复用 `page.body.save` 链路）
+- [ ] `mnote.doc.markdown_edit` 本地文件写入 adapter（`fs.writeFile` + GFM AST markdown 序列化）
+- [ ] `mnote.doc.fetch format: "markdown"` 增强（Page Aggregate 产出 PageMarkdown）
+- [ ] `mnote.doc.fetch` local source 支持（识别本地文件路径并返回 `.md` 原文）
+- [ ] Hermes tool manifest 注册 `mnote.doc.markdown_edit`
+- [ ] Hermes `mnote` plugin 更新：`mnote_doc_fetch` schema 增加 `format: "markdown"` 和本地文件路径支持
+- [ ] 乐观锁：`revision` 冲突检测
+- [ ] 单元测试 + smoke（在线 + 本地两种 source）
+
+**Phase B（下一阶段）：**
+- [ ] `direct_block_edit_operations` 退役（`page_ai_workflow.rs` `local_rule` 分支）
+- [ ] `page_ai_workflow.rs` 修正：system prompt 改为产 search/replace 对，底层走 `mnote.doc.markdown_edit`
+- [ ] 补全 operation schema（`content` 字段）
+- [ ] 浏览器 smoke：自然语言编辑可用（不使用「」格式）
+
+**Phase C（设计冻结，不实施）：**
+- [ ] 流式 apply + suggest/review 设计已冻结，不阻塞 Phase A/B 实施
+
 2026-05-16 Page Block AI context / format focused smoke 证据：

 - 新增并运行 `scripts/task-page-block-ai-context-format-smoke.js`，通过真实 3000 + 测试账号创建临时页，用 `mnote.page.save` 初始化 `p_1/p_2/p_3`，再验证 Hermes mnote tools 的 context / format / annotations / selection guard。
@@ -471,6 +504,8 @@ MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:300
 - [ ] 不把 `mnote.page.save` 包装成精确块编辑长期方案。
 - [ ] 不在 compat route 继续扩写长期业务语义。
 - [ ] 不把 BlockNote / Tiptap AI runtime 作为 mnote runtime 依赖。
+- [ ] 不把 `direct_block_edit_operations` / `local_rule` planner 当作长期 AI 编辑路径（当前为过渡实现，将被 `mnote.doc.markdown_edit` 替代）。
+- [ ] 不新增 `mnote.block.*` 工具；`mnote.block.*` 保留为结构性辅助，不做块操作向新工具的扩张。

 ---

@@ -481,6 +516,7 @@ MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:300
 - [ ] Page Aggregate 的标题 / 正文 / 页面设置 / page tree / AI fetch 回读形成同一组可验证真相。
 - [ ] `7-10` 的 Page Block AI Tooling 剩余矩阵完成或明确拆出后续 process 文档。
 - [ ] `7-11` 的 AI 基础 runtime 口径完成：context、format、manifest annotations、review session、状态机边界都有代码或明确后续 checklist。
+- [ ] 7-14 v2 Phase A + B 全部完成（`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强 + `page_ai_workflow.rs` 收口）；Phase C 设计已冻结。设计稿修正已由 7-14 v2 自行完成。
 - [ ] `tree.*` command 面对主要页面生命周期动作成为唯一 preferred runtime 主链。
 - [ ] tree realtime live cache 覆盖 Sidebar、Page Tree、File Tree、page subtree 的关键写后更新。
 - [ ] 至少一轮定向 bug hunt 完成，所有 P0/P1 blocker 已归档到 `bugs/*/done/` 或明确保留为后续 process。
@@ -490,5 +526,5 @@ MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:300
 ## 6. 给后续 /goal 的持续执行 Prompt

 ```text
-/goal objective: 持续执行 /mnt/Data1T/mnote/design/10-review/process/08-kernel-architecture-next-priority-review-and-checklist.md，按 P0 -> P1 顺序推进 MNOTE 架构收口、AI 基础底座和定向 bug hunt。每轮开始先读取 /home/lix/.codex/memories/PROFILE.md 与 ACTIVE.md，再读取 AGENTS.md、ARCHITECTURE.md、design/01-05-current-priority-overview.md、本 checklist、design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md 和 design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md。必须保护用户已有未提交改动，不回滚、不覆盖、不删除无关文件。优先使用多个 subagent 并行做只读审查和浏览器验证，主线程只整合证据和做小范围实现。执行顺序固定为：1) Page Aggregate 单一真源；2) tree command cutover；3) tree realtime live cache；4) AI 基础工具与审阅底座，只补 context/selection/page_xml/tool annotations/review session/conflict/idempotency，不扩新 AI 功能；5) 定向 bug hunt。每完成一个小项都要更新本 checklist 和对应 design/bugs 文档，补真实验证命令或证据路径。不要优先扩新功能，不要大改架构，不要把 compat/debug/fallback 当主链，不要把 BlockNote/Tiptap AI runtime 作为 mnote runtime 依赖。验证至少包含 git diff --check、相关 cargo test / smoke；如涉及 3000 页面，使用 mnote-tester 或浏览器自动化并保留截图/JSON 证据。
+/goal objective: 持续执行 /mnt/Data1T/mnote/design/10-review/process/08-kernel-architecture-next-priority-review-and-checklist.md，按 P0 -> P1 顺序推进 MNOTE 架构收口、AI 基础底座和定向 bug hunt。每轮开始先读取 /home/lix/.codex/memories/PROFILE.md 与 ACTIVE.md，再读取 AGENTS.md、ARCHITECTURE.md、design/01-05-current-priority-overview.md、本 checklist、design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md、design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md、design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md。必须保护用户已有未提交改动，不回滚、不覆盖、不删除无关文件。优先使用多个 subagent 并行做只读审查和浏览器验证，主线程只整合证据和做小范围实现。执行顺序固定为：1) Page Aggregate 单一真源；2) tree command cutover；3) tree realtime live cache；4) AI 基础工具与审阅底座，按 `7-14` v2 方向优先做 Phase A（`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强），Phase B 退役 `local_rule` planner + `page_ai_workflow.rs` 收口；Phase C（流式 apply + suggest/review）仅设计冻结不实施。同时补 context/selection/page_xml/tool annotations，不扩新 AI 功能；5) 定向 bug hunt。每完成一个小项都要更新本 checklist 和对应 design/bugs 文档，补真实验证命令或证据路径。不要优先扩新功能，不要大改架构，不要把 compat/debug/fallback 当主链，不要把 BlockNote/Tiptap AI runtime 作为 mnote runtime 依赖。验证至少包含 git diff --check、相关 cargo test / smoke；如涉及 3000 页面，使用 mnote-tester 或浏览器自动化并保留截图/JSON 证据。
 ```