mnote/design/07-ai/process/7-27-online-markdown-writeback-final-content-truth-v2.md

7-27 [process] 在线 Markdown_edit 以最终 Markdown 为写回真源 v2

更新：2026-05-18（v2：整合 CLI Main 参考实现分析，确认方向，补充见解）

2026-05-19 local-first 口径补充：

• 本文仍适用于 convex_workspace / 在线文档的 mnote.doc.markdown_edit 修复，但当前默认产品形态已切到 local-first workspace。
• 本地 .md 路径的默认 AI 编辑主路径是“授权文件引用 + agent 原生 patch/diff + watcher 同步”；mnote.doc.markdown_edit 只作为本地受控代理 fallback、cloud / remote agent 或 compat 路径。
• 后续新增 AI 编辑能力默认先保证本地 .md 与 {mdBase}.assets/ 相对路径不被改写为 Convex media asset；在线 Convex 文档路径只作为可选 cloud / sync / share source。

当前状态：PROCESS

关联缺陷：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-17-markdown-edit-same-block-multi-op-overwrite-v1.md

上位设计：design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md

参考实现：design/05-editor-mainline/reference-code/cli-main/shortcuts/doc/（str_replace skill） rust/crates/mnote-web/src/routes/local_markdown_parser.rs（已有 GFM→blocks 解析器）

---

0. 参考实现分析：CLI Main（Lark Doc）怎么做？

0.1 实现结构

CLI Main 的 docs +update --api-version v2 将 str_replace、block_replace、block_insert_after 等命令以 PUT 请求发送到 Lark OpenAPI：

// docs_update_v2.go:140-157
body := map[string]interface{}{
    "format":  runtime.Str("doc-format"),
    "command": cmd,           // "str_replace" | "block_replace" | ...
}
body["pattern"] = runtime.Str("pattern")    // str_replace 的搜索文本
body["content"] = runtime.Str("content")    // 替换文本或新内容
body["block_id"] = blockID                  // block_* 操作的目标块
body["revision_id"] = runtime.Int("revision-id")

// API: PUT /open-apis/docs_ai/v1/documents/{id}

关键：str_replace 只传 pattern + content，不传 final_md。 服务端（Lark OpenAPI）在收到 command: "str_replace" 后，由服务端负责在文档的 XML/block 存储中找到匹配的文本并替换。

0.2 与 mnote 的架构对应

CLI Main (Lark Doc)	mnote	角色
Lark OpenAPI 服务端	Rust doc_markdown_edit + execute_page_body_save	执行文本替换→block 持久化
str_replace API 端点	mnote.doc.markdown_edit 工具	AI 调用的文本级编辑入口
块操作 API 端点	mnote.doc.apply_block_ops + mnote.block.*	AI 调用的块级编辑入口
CLI 客户端（lark-cli）	Hermes agent / page_ai_workflow	AI 编排层，只产生{pattern, content}对

mnote 的 Rust kernel 就是那个"服务端"。 所以在 Rust 层实现 markdown→block content 的转换是正确的方向——这不是"在客户端做服务端的事"，而是 mnote 的 Rust 层本来就承担服务端职责。

0.3 CLI Main 对我们设计的启发

1. str_replace 是不可拆分的原子操作 — CLI Main 的 str_replace 由服务端完整执行。一旦 pattern + content 送出，客户端不需要处理块映射。mnote 的 doc_markdown_edit 也应该是一条完整的原子路径：接收 operations → 搜索替换 → 产生 final_md → 直接转换 final_md 为 blocks 并写回。不应该把 operations 暴露给下游做二次推导。

2. 文档中的所有纯文本搜索替换只需一条 API 调用 — CLI Main 不支持在一次请求中组合多个 str_replace。mnote 支持多条 operation 是更灵活的设计，但兑现这个灵活性的前提是：多条 operation 在服务端累积应用到 md 后，只产出一组最终的 block content 写回，而不是每条 operation 独立映射到 block。

3. pattern 不限制为精确文本 — CLI Main 的 str_replace 文档鼓励 Markdown 模式下的"前缀...后缀"省略号语法（"start...end"），允许模糊定位。这和我们已有的四级匹配策略（精确→忽略空白→段落 fuzzy→失败）方向一致。

4. CLI Main 在客户端做预检查 — docs_update_check.go 中有 checkDocsUpdateReplaceMultilineMarkdown，在发送请求前就检查 Markdown 中的空行是否会违反服务端的单块内文本替换限制。同理，mnote 在转换 final_md 时也应该做预检：发现跨块内容变化时，要么走 GFM 解析器重建多块 content，要么清楚告知 AI "这条 operation 需要多块替换"。

5. mnote 的 final_md 方法比 CLI Main 更可靠 — CLI Main 把 pattern 发给服务端，由服务端重新执行匹配。如果服务端的匹配策略与模型预期的不同，结果会意外。mnote 的做法（在 Rust 层计算 final_md，然后用 final_md 生成 block content）把匹配阶段和写回阶段解耦——匹配结果对 AI 可见（文档中说"已验证将 X 替换为 Y"），不会出现「客户端匹配成功、服务端匹配失败」的不一致。

0.4 与 CLI Main 的根本差异：为何不能照搬

CLI Main 的方案（客户端只传 pattern + content，服务端做匹配+转换）依赖 Lark OpenAPI 对文档 block 存储的完全控制。mnote 的 Convex 后台（documents:updateContent）只接受完整的 blocks 数组作为 content，没有 str_replace 端点。

这迫使 mnote 的 Rust 层必须自己做 final_md → block content 的转换。这个转换就是我们的"服务端逻辑"，是正确且必要的。

---

---

1. 问题

1.1 当前架构

mnote.doc.markdown_edit 在在线 Convex 文档路径下有两套编辑结果：

搜索替换 → 最终 md ✅（正确的结果）

                  ↓
      build_block_ops_from_markdown_edit(blocks, operations, applied)
                  ↓ 二次推导
      doc_apply_block_ops → page.body.save

• 第一层: search_replace(&md, &search, &replace) — 在完整的 markdown 字符串上顺序执行操作，支持精确/忽略空白/段落 fuzzy 四级匹配。
• 第二层: build_block_ops_from_markdown_edit — 不从最终 md 提取修改，而是从原始 blocks 和原始 operations 重新推导每次命中。

最终 markdown 被丢弃了。 写入层使用的不是计算好的文本结果，而是从原始 operations 反查 blocks 的二次推导。

1.2 由此导致的已知缺陷

缺陷	表现	根因
7-17 同块多操作覆盖	两次 op 命中同块 → 第二 op 从原始文本计算，覆盖第一 op	推导层不累积
7-24 在线不以最终 md 为真源	full_content 无法映射到块 operations → 全部拒绝	推导层不支持全文替换
7-25 命中后空 block_ops	markdown 层匹配成功，block 映射失败 → 空 ops	两套匹配规则不一致

当前「修复」是安全降级：推导失败从伪成功变成明确错误码，但推导本身仍然存在。

1.3 为什么推导不可靠

build_block_ops_from_markdown_edit 当前采用「每 operation 从 block.text 反查 + 维护 block_states 累积文本」策略 [doc.rs:1048-1103]，已在共享匹配函数和累积方面改进，但根本问题仍在：

1. full_content 模式必须跳过推导：全文替换的最终 md 与原始 blocks 没有逐 op 对应关系
2. 跨块替换不可映射：一条 search: "TODO" 命中多个块时，推导层只产生一次 replace op
3. 格式变化丢失：heading/todo 前缀在 markdown 中记录了结构语义，推导层只传文本

---

2. 设计目标

2.1 核心原则

最终 markdown 是写回的唯一真源。 文本层算出的结果不经二次推导直接落地。

2.2 目标范围

• 在线 Convex 文档的 mnote.doc.markdown_edit 以最终 md 为唯一真源生成 page.body.save 的 content 载荷
• 本地文件路径不变（已经以最终 md 直接 fs::write）
• mnote.block.* / mnote.doc.apply_block_ops 不做改动
• full_content 模式不再被拒绝，支持
• 复杂块（mindmap、resource、table、image）在往返中保持不变

2.3 非目标（Phase C 范畴）

• 流式 apply（见 7-14 §7）
• suggest/review 模式
• 本地 .md 文件的块标识持久化（本地文件没有 block identity）

---

3. 方案：Markdown → Block Content 直接写回

3.1 流程图（替换后）

搜索替换 → 最终 md ✅
                ↓
   parse_final_markdown_to_blocks(&md, &original_blocks)
                ↓
   [blocks with preserved IDs + metadata + new blocks]
                ↓
   build_page_content(&original_body_content, &parsed_blocks)
                ↓
   execute_page_body_save_from_aggregate(state, context, input, &aggregate, next_content, changed_blocks)

3.2 数据流

原始 blocks (来自 aggregate.body.blockDocument.blocks):
  b1: { type: "paragraph", text: "第一段", revisionRef: "r1" }
  b2: { type: "heading", text: "标题", revisionRef: "r2", props: { level: 2 } }
  b3: { type: "resource", ... }  ← 复杂块，全文不做修改

↓ blocks_to_markdown (当前，增强前)

当前 md (include_ids=true):
  第一段 <!-- block:b1 -->
  标题 <!-- block:b2 -->
  [resource: 资源块] <!-- block:b3 -->

↓ 搜索替换

最终 md:
  新第一段 <!-- block:b1 -->
  新标题 <!-- block:b2 -->
  [resource: 资源块] <!-- block:b3 -->

↓ parse_final_markdown_to_blocks (新增)

解析后的 blocks:
  b1: { type: "paragraph", text: "新第一段", revisionRef: "r1" }  ← 文本更新，其他不变
  b2: { type: "heading", text: "新标题", revisionRef: "r2", props: { level: 2 } }
  b3: { type: "resource", ... }  ← 保持原始内容不动（复杂块不可编辑）

↓ build_page_content (新增)

最终 content (aggregate.body.content 格式):
  [b1_legacy, b2_legacy, b3_legacy]  ← 复用原始块的非文本属性

3.3 组件设计

3.3.1 blocks_to_markdown 增强（已有函数，扩展）

当前只输出 <!-- block:ID -->，需要扩展为带类型和 revisionRef：

// 当前:
format!("{text} <!-- block:{id} -->")

// 增强后:
format!("{text} <!-- block:{id}:{block_type}:{revision_ref} -->")

对 heading 块额外附加 `level` 字段：

```rust
// heading 块:
format!("{text} <!-- block:{id}:heading:{revision_ref}:level={level} -->")

解析器还原后从 level 字段恢复正确的 heading 级别。

对 heading 和 todo 等结构化块，前缀已经正确输出（`## `、`- [ ] `），解析器据此还原类型。

对复杂块（mindmap、resource、table、image）——即 `is_editable == false` 或在 `block_projection_blocks` 中标记了 `unsupportedReason` 的块——输出特殊标记使其不会被解析器修改：

```text
[mnote-raw-block:block_id]  <!-- block:{id}:{block_type}:{revision_ref} -->

然后写回层把这些块从原始 blocks 中按 ID 复制，不做任何修改。

3.3.2 parse_final_markdown_to_blocks（新增函数）

签名：

/// 解析最终 markdown 为块列表，保留块元数据
///
/// * `final_md` — 搜索替换后的 markdown
/// * `original_blocks` — 从 aggregate.body.blockDocument.blocks 读取的原始块
///
/// 返回解析后的块列表，每个块包含后续写回所需的所有字段
fn parse_final_markdown_to_blocks(
    final_md: &str,
    original_blocks: &[Value],
) -> Vec<ParsedBlockInfo> {
    // 1. 利用 comrak 或逐行解析提取
    //    - `<!-- block:id:type:rev -->` 中的块元数据
    //    - 对带 ID 的块：保留原始块的属性
    //    - 对无 ID 的文本块：标记为"新块"
    //    - 对 [mnote-raw-block:...] 标记：原样保留原始块
    // 2. 返回重建后的块列表
}

返回值 ParsedBlockInfo:

struct ParsedBlockInfo {
    block_id: Option<String>,        // None = 新块（无原始 ID）
    block_type: String,              // "paragraph" / "heading" / ...
    text: String,
    block_revision_ref: Option<String>,  // 从注释或原始块继承
    is_new: bool,                    // true = 非原始块，需要分配新 ID
    original_block: Option<Value>,   // 从原始 blocks 复制（若 block_id 匹配）
    props: Option<Value>,            // 从原始块保留的属性
}

解析步骤：

1. 按换行分割 markdown 行，忽略空行
2. 对每行提取 <!-- block:id:type:rev --> 注释（正则：<!-- block:([^:]+):([^:]+):([^: ]+) --> 或类似）
3. 若无注释但有 [mnote-raw-block:id] 标记 → 从原始 blocks 按 ID 复制
4. 若既无注释也无原始标记 → 创建新 paragraph 块，无 blockId（由写入层生成）
5. 从注释中获取 block_type；若无注释，从行前缀推断（## → heading，- [ ] → todo）
6. 用行中 <!-- 前的部分作为文本内容
7. 对带 ID 的块，从原始 blocks 查找并复制 revisionRef、props

3.3.3 build_page_content（新增函数）

将解析后的块列表与原始 body/content 合并，生成最终的 Convex content 数组：

fn build_page_content(
    original_content: &Value,    // 原始的 aggregate.body.content
    parsed_blocks: &[ParsedBlockInfo],
) -> Value {
    // 按 parsed_blocks 顺序遍历
    //   - 若 block_id 在 original 中存在：
    //       复制 original 中该块的完整结构，仅替换 text
    //   - 若 block_id 为 None（新块）：
    //       生成新 block_id，作为 paragraph 追加
    //   - 若 original 中的复杂块不在 parsed 中：
    //       保留（markdown_edit 不主动删块）
    // 返回 Value::Array
}

3.3.4 在 doc_markdown_edit 中的集成（替换现有 online 写回）

// 当前（doc.rs ~line 856）:
let block_ops = build_block_ops_from_markdown_edit(&blocks, &operations, applied);
if applied > 0 && block_ops.is_empty() { ... }
let revision = ...;
let conflict_detection_key = ...;
let apply_result = doc_apply_block_ops_with_meta(state, context, input, &aggregate, block_ops, revision, conflict_detection_key).await?;

// 替换为:
let parsed = parse_final_markdown_to_blocks(&md, &blocks);
let next_content = build_page_content(&current_body_content(&aggregate), &parsed);
let changed_blocks = build_changed_blocks_summary(&original_blocks, &parsed);
execute_page_body_save_from_aggregate(state, context, input, &aggregate, next_content, changed_blocks).await?

---

4. 边界情况处理

4.1 原始块 ID 在最终 md 中消失

可能发生在：

• 用户手动删除了 <!-- block:id --> 注释（极罕见，通过 AI 输出不可能）
• 模型输出的 search/replace 跨段合并了内容

策略：保留该原始块在 content 中的位置。build_page_content 对在 original 中存在但不在 parsed 中的块，按原样复制到最终 content。

4.2 新建块（无原始 ID）

用户可能要求"在末尾加一段总结"。模型输出 full_content 或 search/replace 产生的新文本带 <!-- block:new_paragraph -->。解析器标记为 is_new=true，写入层分配新的 blockId。

策略：新块使用临时 ID 格式 ai_block_{timestamp}_{counter}，与现有 mnote.block.insert_after 的块 ID 风格一致。

4.3 复杂块保留

resource/mindmap/table/image 块在 blocks_to_markdown 中被序列化为特殊标记 [mnote-raw-block:id]。搜索替换通常不会命中这些行（因为它们不含普通文本），但如果意外命中：

策略：在 search_replace 中，如果 search 路径包含了复杂块的特殊标记，整条 operation 标记为 failed。解析器遇到 [mnote-raw-block:...] 标记时，直接从 original blocks 复制。

4.4 搜索替换未命中任何块（applied > 0 但所有命中都是新文本）

当模型输出的 full_content 完全不同于原文时可能出现。

策略：parse_final_markdown_to_blocks 对每一行都产生块。如果没有任何 <!-- block:id --> 注释，所有块标记为 is_new=true。build_page_content 追加新块在后面，同时保留所有原始复杂块。

4.5 revision / conflictDetectionKey 一致性

build_block_ops_from_markdown_edit 当前依赖 doc_apply_block_ops_with_meta 来传递 revision。替换为直接调用 execute_page_body_save_from_aggregate，它从 aggregate 读取 revision/conflictDetectionKey [block.rs:1178-1189]。

策略：新路径从已经读到的 aggregate 中获取 revision/conflictDetectionKey，与现有路径完全一致。

4.6 dryRun 模式

当前 online 路径中 dry_run 由 doc_apply_block_ops 内部处理（不真正写入）。新路径也需要支持：

策略：若 dryRun == true，调用 build_page_content 但不调用 execute_page_body_save_from_aggregate，返回 diff 预览。diff 格式与当前 docs.md:plan_update 的 diff 格式一致。

---

5. 与已有代码的互动

5.1 build_block_ops_from_markdown_edit 的删除

该函数不再被 doc_markdown_edit 调用。它是一个私有 fn（仅 doc.rs 内部可见），唯一调用者被移除后成为死代码。

策略：直接删除函数体。保留调用处的行作为注释（// 退役：7-27 改为 final_md→blocks 直接写回），供后续参考。

5.2 block_projection_blocks 的继续使用

仍然需要原始 blocks 作为元数据源（提取 revisionRef、props、复杂块）。不改变。

5.3 local_markdown_parser 的复用

parse_final_markdown_to_blocks 可以复用 local_markdown_parser::markdown_to_blocks 对 GFM 结构的解析（heading、todo、code block、list），但需要用自己的逻辑提取 <!-- block:... --> 注释。不一定要用 comrak 的 HtmlBlock 解析；更可靠的方法是正则提取注释，然后从剩余内容中推断块类型。

策略：默认使用简单的行级处理（非 comrak），因为 blocks_to_markdown 的输出是每行一块的简单格式，不需要完整的 GFM AST。

⚠️ 跨行约束：行级处理仅适用于 blocks_to_markdown 产出的单行块格式。以下情况需要 fallback 到 local_markdown_parser::markdown_to_blocks：

• 代码块（block_text 含 \n）
• 用户通过 full_content 自由书写的多段 markdown
• 解析跳过了 <!-- block:id --> 的行之间的纯段落

fallback 策略：对无 <!-- block:... --> 注释的连续行，收集后一次性通过 GFM 解析器分割为多个常规块。

5.4 changed_blocks 摘要生成

当前返回的 applyResult.changedBlocks 由 doc_apply_block_ops 产生。新路径需要自己生成：

fn build_changed_blocks_summary(
    original_blocks: &[Value],
    parsed_blocks: &[ParsedBlockInfo],
) -> Vec<Value> {
    // 对比原始 blocks 和解析后的 blocks
    // 对文本改变的块输出 { op: "replace", blockId, content }
}

响应体中的 changedBlocks 字段格式不变，保持与下游消费者（SSE delta 等）的兼容。

---

6. 实施计划

步骤 1：增强 blocks_to_markdown（小）

文件: doc.rs:574

改动：

• 注释格式从 <!-- block:{id} --> 改为 <!-- block:{id}:{type}:{rev} -->
• 对复杂块（editable==false 或 unsupportedReason!=null）输出 [mnote-raw-block:{id}] <!-- block:{id}:{type}:{rev} -->

风险: 低。纯格式变更，向前兼容——旧注释格式的 md 在解析器看来只是缺类型/rev，可通过 fallback 从原始 blocks 查。

测试: 更新现有 test_blocks_to_markdown_with_ids，验证新格式。

步骤 2：实现 parse_final_markdown_to_blocks（中）

新建模块：doc_md_to_blocks.rs 或放在 doc.rs 末尾

核心逻辑（~120 行）：

struct ParsedBlock {
    block_id: Option<String>,
    block_type: String,
    text: String,
    revision_ref: Option<String>,
    original: Option<Value>,
    is_new: bool,
}

fn parse_final_markdown_to_blocks(md: &str, originals: &[Value]) -> Vec<ParsedBlock> {
    // 1. 为 originals 建立 block_id → Value 的 HashMap
    // 2. 将 md 按行分割
    // 3. 对每行：
    //    a. 用正则提取 <!-- block:id:type:rev --> 或 [mnote-raw-block:id]
    //    b. 若无注释 → is_new=true, type="paragraph"
    //    c. 若有注释 → 查 originals_map 继承 revision_ref/props
    //    d. 提取 <!-- 前的纯文本
    // 4. 判断块类型：若注释中有 type 则用注释的，否则从行前缀推断
    // 5. 返回 ParsedBlock 列表
}

正则示例：

lazy_static! {
    static ref BLOCK_COMMENT_RE: Regex = Regex::new(
        r"<!--\s*block:([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]*)\s*-->"
    ).unwrap();
    static ref RAW_BLOCK_RE: Regex = Regex::new(
        r"\[mnote-raw-block:([a-zA-Z0-9_-]+)\]"
    ).unwrap();
}

测试：

• test_parse_empty_md → 空输入 → 空输出
• test_parse_with_block_ids → 包含 <!-- block:b1:paragraph:r1 --> → 返回正确 ParsedBlock
• test_parse_no_ids → 纯文本 → 全部 is_new
• test_parse_raw_block → [mnote-raw-block:b3] → 从 originals 复制
• test_parse_type_from_prefix → ## Title → type="heading"
• test_parse_todo_prefix → - [x] Done → type="todo"

步骤 3：实现 build_page_content（中）

文件: 与步骤 2 同模块（~80 行）

fn build_page_content(original_content: &Value, parsed: &[ParsedBlock]) -> Value {
    // 1. 为 original_content 建立 block_id → full_block 映射
    // 2. 遍历 parsed_blocks：
    //    - 有 block_id 且 original 中存在 → 复制 original 块，更新 text
    //    - 无 block_id → 创建新 paragraph 块
    //    - 有 block_id 但不在 original 中 → 复制 original 中能找到的（从已处理集合中移除）
    // 3. 遍历 original_content 中的复杂块（不在 parsed 中出现的）→ 追加
    // 4. 返回 Value::Array
}

测试：

• test_build_content_preserves_unmodified_blocks
• test_build_content_updates_text
• test_build_content_preserves_complex_blocks
• test_build_content_new_blocks_appended

步骤 4：替换 doc_markdown_edit 的 online 写回路径（小）

文件: doc.rs:854-900

将现有的：

let aggregate = aggregate_value(state, context, input).await?;
let blocks = block_projection_blocks(&aggregate);
let block_ops = build_block_ops_from_markdown_edit(&blocks, &operations, applied);
if applied > 0 && block_ops.is_empty() { ... }
let apply_result = doc_apply_block_ops_with_meta(...).await?;

替换为：

let aggregate = aggregate_value(state, context, input).await?;
let blocks = block_projection_blocks(&aggregate);
let parsed = parse_final_markdown_to_blocks(&md, &blocks);
let original_content = current_body_content(&aggregate);
let next_content = build_page_content(&original_content, &parsed);
let changed_blocks = build_changed_blocks_summary(&blocks, &parsed);
let apply_result = execute_page_body_save_from_aggregate(
    state, context, input, &aggregate, next_content, changed_blocks
).await?;

新增 build_changed_blocks_summary（~30 行）。

风险: 中。第一次替换时需要与现有测试对照输出，确保 changed_blocks 格式一致。

测试：

• 现有 hermes_tools_markdown_edit_* 测试全部重新运行——断言现有行为不变
• 新增 test_markdown_edit_online_single_replacement：验证单块替换后 content 正确
• 新增 test_markdown_edit_online_full_content：验证全文替换不再被拒绝
• 新增 test_markdown_edit_online_preserves_complex_blocks：验证 mindmap 块不变

步骤 5：更新 full_content 处理（小）

文件: doc.rs:785-800

当前 full_content 构造一个 search: current_md.trim(), replace: full.trim() 的 operation。替换后不再需要这个折中——直接解析 full_content 为 blocks。

改动：在 parse_final_markdown_to_blocks 中，若没有任何 <!-- block:id --> 注释，所有块标记为 is_new。build_page_content 只追加新块 + 保留原始复杂块。

测试：

• test_markdown_edit_online_full_content_creates_new_blocks
• test_markdown_edit_online_full_content_preserves_complex

步骤 6：清理（小）

• 删除 build_block_ops_from_markdown_edit 函数体（私有 fn，唯一调用者已移除）
• 在原调用位置保留注释：// 退役：7-27 改为 final_md→blocks 直接写回
• 更新 manifest/guidance 文字：full_content 不再被拒绝

---

7. 测试矩阵

场景	输入	期望输出	优先级
单块精确 search/replace	{search:"第一段", replace:"新内容"}	文本更新，blockId/revisionRef 不变	P0
单块忽略空白 match	{search:"第 一 段", replace:"新内容"}	文本更新（原块中"第一段"→"新内容"）	P0
多 operation 命中同块	[{op1},{op2}] 同块	最终文本 = 两次替换累积结果	P0
full_content	"新全文"	新文本创建新块，原复杂块保留	P0
影响 heading	search 命中 heading 文本	heading 类型不变，文本更新	P1
包含复杂块文档的替换	只改 paragraph 文本	resource/mindmap 块不变	P1
dryRun 不落盘	dryRun: true	返回 diff，无写入	P1
revision 过期	aggregate revision 已过期	冲突错误，不写入	P1
原始块 ID 消失	搜索替换删除了 <!-- block --> 注释	该原始块保留（不从 content 删除）	P2
空 operations	[]	错误码	P2
纯文本 md（无块注释）	"摘要\n\n补充"	全部 is_new，追加到末尾	P2

---

8. 灰度/回滚

不设 feature flag。直接替换 online 写回路径。理由：

• 旧路径（7-24/7-25 修复后）在 full_content 等场景是安全降级（拒绝写入），新路径是功能增强。不会出现「旧路径能写入、新路径不能」的退化。
• 现有 hermes_tools_markdown_edit_* 测试集 + 新增 5 个测试组合足够兜底。
• 若确实需要回滚，用 git revert 回退本次改动即可。

灰度策略：默认开启，观察到新增测试全部 pass 后合入主线。

---

9. 关联文件清单

文件	变更类型	变更内容
doc.rs blocks_to_markdown	修改	注释格式增强
doc.rs doc_markdown_edit	修改	online 写回路径
新建 doc_md_to_blocks.rs	新增	parse_final_markdown_to_blocks + build_page_content + build_changed_blocks_summary
doc.rs build_block_ops_from_markdown_edit	标记	#[deprecated]
hermes_tools.rs tests	新增	~5 个新测试
manifest.rs / guidance.md	微调	full_content 不再标记为拒绝

---

10. 开放问题

1. <!-- block:id:type:rev --> 注释在行中可能被模型生成的 search/replace 破坏。例如模型输出 {search: "第一段 <!-- block:", replace: "新段"} 前半个注释。这是用户级错误（模型错误地替换了元数据），写入层应在 parse 阶段检测不完整的注释并报错。
2. full_content 场景下的块类型保留。如果用户要求"把整个文档改写成大纲格式"，模型输出不包含 <!-- block--> 注释的全部新文本，此时 heading/todo 类型从 GFM 前缀推断。但列表、引用、代码块等格式需确认 local_markdown_parser 的 markdown_to_blocks 返回的结构是否足够完整。
3. 行内格式（bold、italic、link）能否在往返中保持。当前 blocks_to_markdown 只输出文本（block_text），丢弃所有 marks。在线文档的 text 存储包含 marks（bold/italic/code/link），当前 doc_markdown_edit 的整体设计不保证行内格式——这超出了 7-24/7-25 的范围，但建议在 7-14 的 Phase A/B 之后评估。