# 2026-05-18 [done] P0 内核优先 Bug 修复记录与进展

> 记录时间：2026-05-18
>
> 状态：`done`
>
> 范围：`03-rust-web`、`04-tree-domain`、`05-editor-mainline`、`07-ai`
>
> 口径：本文是本轮 P0 / 内核优先缺陷修复的总进展记录；单个缺陷的根因、修复点和证据仍以各分类 `bugs/<category>/done/` 下的明细文档为准。

## 1. 总结

本轮按“P0 优先 / 内核优先”的顺序完成了已确认缺陷的修复、验证和归档：

- `bugs/*/process/` 当前已无遗留缺陷文档。
- `design/10-review/process/08-*` 已迁入 `design/10-review/done/08-*`，10-review 当前无活跃 process 文档。
- Page Aggregate、tree command、tree realtime、AI markdown edit / block tools 的 P0/P1 blocker 已归档到对应 `bugs/*/done/`。
- 当前仍未实施的是 `7-10` / `7-16` 中 Phase C UI / Review Mode 相关项，已明确冻结，不计入本轮 P0 内核 bug blocker。

## 2. 本轮修复主线

### 2.1 Rust Web / Realtime / ACP

已归档缺陷：

- `bugs/03-rust-web/done/3-16-tree-realtime-ws-sse-doc-contract-drift-v1.md`
- `bugs/03-rust-web/done/3-17-sse-push-skips-polling-fallback-v1.md`
- `bugs/03-rust-web/done/3-18-ws-sse-delta-contract-split-v1.md`
- `bugs/03-rust-web/done/3-19-acp-reasonix-tool-call-missing-identity-fields-v1.md`
- `bugs/03-rust-web/done/3-20-acp-request-permission-no-response-v1.md`
- `bugs/03-rust-web/done/3-21-acp-run-payload-consumed-and-removed-v1.md`
- `bugs/03-rust-web/done/3-22-acp-permission-auto-deny-ui-shows-approval-actions-v1.md`

收口结果：

- `/api/realtime/ws` 与 `/api/tree/events` 的实时合同已按 WS 主链 / SSE fallback 口径收口。
- ACP Reasonix 工具调用身份字段、permission 响应、run payload 生命周期相关缺陷已进入 done。
- ACP permission 自动拒绝时，页面 AI UI 不再展示误导性的“允许 / 拒绝”审批动作。
- 这些缺陷不再作为当前 10-review P0 blocker 跟踪。

### 2.2 Tree Domain / File Tree

已归档缺陷：

- `bugs/04-tree-domain/done/4-46-filetree-resource-row-document-command-leak-v1.md`
- `bugs/04-tree-domain/done/4-47-stream-support-retired-resource-delete-command-v1.md`

收口结果：

- File Tree resource row 不再泄漏到 document command 语义。
- 资源归属继续按 Resource Tree -> File Tree projection -> `tree.resource.*` 命令面解释。
- stream_support 的资源 remove_asset 回归样例已同步到 `tree.resource.archive`，不再保留退役 `tree.resource.delete` 口径。

### 2.3 Editor Mainline / Page Aggregate

已归档缺陷：

- `bugs/05-editor-mainline/done/5-15-page-aggregate-client-state-second-truth-v1.md`
- `bugs/05-editor-mainline/done/5-16-sidebar-preferred-snapshot-query-overrides-live-stream-v1.md`
- `bugs/05-editor-mainline/done/5-17-document-title-source-drift-live-sidebar-over-head-v1.md`
- `bugs/05-editor-mainline/done/5-18-ai-write-body-does-not-sync-page-aggregate-content-v1.md`
- `bugs/05-editor-mainline/done/5-19-page-aggregate-prefers-editor-document-v1.md`
- `bugs/05-editor-mainline/done/5-20-page-body-save-strips-editor-document-before-convex-v1.md`
- `bugs/05-editor-mainline/done/5-21-page-body-save-rejects-invalid-editor-document-v1.md`
- `bugs/05-editor-mainline/done/5-22-documents-content-strips-editor-document-before-page-aggregate-v1.md`
- `bugs/05-editor-mainline/done/5-23-editor-document-semantic-validation-v1.md`
- `bugs/05-editor-mainline/done/5-9-c12-topbar-sidebar-toggle-noop-v1.md`

收口结果：

- Page Aggregate 标题、正文、页面设置、page tree、AI fetch 回读已经形成同一组可验证真相。
- AI 外部写入后，文档 shell 会同步 Page Aggregate JSON script / session snapshot，避免下一次 AI context 继续读旧正文。
- Sidebar preferred snapshot 与 live stream 的优先级漂移已从当前 P0 blocker 中移除。
- Page Aggregate 读侧已从 route 主链保留 `editorDocument / blockDocument`，不再在 `documents.content.get` 结果中提前剥离原生块文档字段。
- `editorDocument` 显式输入已补语义校验：必须带 `blocks`，且 `rootBlockIds` 必须引用真实块。

关键证据：

- `tmp/page-aggregate-refresh-persistence-smoke/mpagfma1.json`
- `tmp/page-aggregate-refresh-persistence-smoke/mpagfma1.png`

### 2.4 AI Markdown Edit / Block Tools

已归档缺陷：

- `bugs/07-ai/done/7-16-markdown-edit-normalized-search-byte-index-v1.md`
- `bugs/07-ai/done/7-17-markdown-edit-same-block-multi-op-overwrite-v1.md`
- `bugs/07-ai/done/7-18-ai-markdown-edit-phase-state-contract-drift-v1.md`
- `bugs/07-ai/done/7-19-hermes-tool-guidance-markdown-edit-contract-drift-v1.md`
- `bugs/07-ai/done/7-20-page-ai-workflow-bypasses-hermes-tool-executor-v1.md`
- `bugs/07-ai/done/7-21-markdown-edit-local-write-contract-bypass-v1.md`
- `bugs/07-ai/done/7-22-apply-block-ops-missing-write-preconditions-v1.md`
- `bugs/07-ai/done/7-23-markdown-edit-manifest-schema-contract-drift-v1.md`
- `bugs/07-ai/done/7-24-markdown-edit-online-write-does-not-use-final-markdown-v1.md`
- `bugs/07-ai/done/7-25-reasonix-block-edit-workflow-empty-block-ops-after-markdown-match-v1.md`
- `bugs/07-ai/done/7-26-resource-block-normalized-to-paragraph-ai-projection-v1.md`
- `bugs/07-ai/done/page-ai-block-edit-model-fallback-missing-content.md`
- `bugs/07-ai/done/7-27-markdown-edit-full-content-retains-old-blocks-v1.md`
- `bugs/07-ai/done/7-28-markdown-edit-selection-scope-not-enforced-v1.md`
- `bugs/07-ai/done/7-29-markdown-edit-flattens-inline-content-v1.md`
- `bugs/07-ai/done/7-30-block-tools-selection-scope-not-enforced-v1.md`
- `bugs/07-ai/done/7-31-page-ai-workflow-drops-read-summary-v1.md`
- `bugs/07-ai/done/7-32-markdown-edit-page-body-save-missing-preconditions-v1.md`
- `bugs/07-ai/done/7-33-markdown-edit-no-applied-operations-success-v1.md`

收口结果：

- 页面 AI 简单正文编辑主路径已收敛为 `mnote.doc.markdown_edit` + `mnote.doc.fetch` + `page_ai_workflow.rs` 统一 tool executor。
- `local_rule` / `direct_block_edit_operations` 不再作为当前 runtime 口径。
- 在线 Convex 文档和本地 `.md` 文件共用 markdown 写入合同。
- `mnote.doc.markdown_edit` 已补齐 normalized search、同块多 op 合并、写入前置条件、manifest schema、在线写回和空 block ops 映射错误处理。
- `mnote.block.insert_after` 支持多块插入并返回 `insertedBlockIds`，限制 `1..=20`。
- AI block projection 已保留 `resource` 类型，不再把 resource 块降级为 `paragraph` 或伪装成可编辑普通块。
- `mnote.doc.markdown_edit` 的 `full_content` 重建已改为 final markdown 真源，避免旧普通块残留。
- `mnote.doc.markdown_edit` / `page_ai_workflow` 已补 selection scope 服务端兜底，`allowedTargetBlockIds` 外的写入会被拒绝。
- `mnote.doc.markdown_edit` 写回普通块时不再无条件扁平化 inline content；未变更块保持原结构，单 inline text 节点的已变更块保留 marks / attrs。
- 单个 `mnote.block.*` 写工具已补 selection scope 服务端兜底，越界块写入会返回 `mnote_block_target_out_of_scope`。
- 页面 AI `block_edit_workflow` 现在会把模型 `summary` 返回给前端；“读取第一段 + 修改第二段”这类读写混合请求不再被固定写入文案吞掉读取结果。
- 在线 `mnote.doc.markdown_edit` 直接 `page.body.save` 写回时已携带当前 `revision/conflictDetectionKey`。
- `mnote.doc.markdown_edit` 全部 search 失败时返回 `mnote_markdown_edit_no_operations_applied`，不再误报成功或触发无意义保存。

关键证据：

- `tmp/page-block-ai-tools-smoke/mpag4966.json`
- `tmp/page-block-ai-tools-smoke/mpag4966-page.png`
- `tmp/hermes-tester/page-block-ai-tools-mpag4966/page-aggregate.json`
- `tmp/hermes-tester/page-block-ai-tools-mpag4966/doc-fetch-find.json`
- `tmp/page-block-ai-conflict-idempotency-smoke/mpafrevs.json`

## 3. 已执行验证

最新验证命令：

```bash
node --check scripts/task-page-block-ai-tools-smoke.js
node --check scripts/task-page-block-ai-conflict-idempotency-smoke.js
node --check scripts/task-page-aggregate-refresh-persistence-smoke.js
cargo fmt --manifest-path rust/Cargo.toml --all -- --check
cargo test --manifest-path rust/Cargo.toml -p bridge-runtime editor_document_roundtrip_preserves_resource_block_type -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web build_page_content -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_markdown_edit -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web block_edit_workflow -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_client -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web ssr::pages::layout::tests -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_block -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_manifest -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p mnote-web stream_change_preserves_remove_asset_delta_fields -- --nocapture
git diff --check -- scripts/task-page-block-ai-tools-smoke.js scripts/task-page-block-ai-conflict-idempotency-smoke.js scripts/task-page-aggregate-refresh-persistence-smoke.js rust/crates/core-protocol/src/editor/model.rs rust/crates/core-protocol/src/editor/tiptap.rs rust/crates/bridge-runtime/src/lib.rs rust/crates/mnote-web/src/editor_actor.rs rust/crates/mnote-web/src/hermes_tools/block.rs rust/crates/mnote-web/src/hermes_tools/manifest.rs rust/crates/mnote-web/src/routes/hermes_tools.rs design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md design/07-ai/process/7-16-page-block-ai-real-smoke-followup-matrix-v1.md design/10-review/README.md design/10-review/done/08-kernel-architecture-next-priority-review-and-checklist.md bugs/07-ai/done/7-26-resource-block-normalized-to-paragraph-ai-projection-v1.md
find bugs -path '*/process/*' -type f | sort
```

结果：

- 三个 Node smoke 脚本语法检查通过。
- Rust workspace 格式检查通过。
- `bridge-runtime` resource block roundtrip 回归测试通过：`1 passed`。
- `mnote-web hermes_tools` 测试通过：`39 passed`。
- `mnote-web build_page_content`、`hermes_tools_markdown_edit`、`block_edit_workflow`、`acp_client`、`ssr::pages::layout::tests` 定向回归测试通过。
- `mnote-web hermes_tools_block`、`hermes_tools_manifest` 定向回归测试通过。
- `mnote-web stream_change_preserves_remove_asset_delta_fields` 定向回归测试通过。
- 相关路径 `git diff --check` 通过。
- `bugs/*/process/` 文件列表为空。

## 4. 当前剩余边界

不是本轮未修 blocker：

- `design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md` 和 `design/07-ai/process/7-16-page-block-ai-real-smoke-followup-matrix-v1.md` 中仍有 Phase C UI / Review Mode 未勾项。
- 这些项属于流式 apply、suggest/review、持久 comment/tracked-change 等未来 UI / 审阅面设计，当前已按 Phase C 冻结，不纳入本轮 P0 内核 bug 修复。

后续若要继续推进，应另起 process 文档或新 bug，而不是重新打开本轮已归档的 P0 内核缺陷。
