# 页面 AI 块编辑 — model 主路径操作缺少 content（direct path 架构定位错误）

> 发现时间：2026-05-16
>
> 更新时间：2026-05-18（运行时收口验证）
>
> 状态：`[done]`
>
> 关联主线：`07-ai` / `05-editor-mainline`
>
> 关联设计稿：`design/07-ai/done/7-13-page-block-editor-runtime-actor-v1.md`
>
> 关联代码：
> - `rust/crates/mnote-web/src/routes/page_ai_workflow.rs` — block_edit_workflow, direct_block_edit_operations（应退役）, call_block_edit_model（唯一正确路径）
> - `rust/crates/mnote-web/src/hermes_tools/block.rs:436` — doc_apply_block_ops, replace 操作缺少 content

## 症状

用户用自然语言在页面 AI 面板输入块编辑指令时，`mnote.page_ai.block_edit_workflow` 返回 400：

```
replace 操作缺少 content
```

## 复现步骤

1. 打开任意文档
2. 点击右下角「AI 助手」
3. 输入自然语言指令，如 `把第一段文字改成：AI成功修改了这一段。`
4. → `POST /api/page-ai/block-edit-workflow` 返回 400
5. 页面上显示 `mnote.page_ai.block_edit_workflow 失败`

## 架构问题：两条路径的设计是错误的

当前 `block_edit_workflow` 有两条路径，但**正确的路径只有一条**：

### 唯一正确路径：Model path（`call_block_edit_model`）

```
用户自然语言 → 模型理解语义 → 产出 operations JSON → doc_apply_block_ops → 写入
```

这是 AI 面板应有的行为：用户说人话，模型理解意图，产出操作。这是**唯一主路径**。

### 应退役路径：Direct path（`direct_block_edit_operations`）

```
用户特定格式 → 正则抠「」内文本 → 直接拼 operations → 写入
```

这不是 AI，这是**命令行**。它要求用户按固定格式输入（「」引号），本质是把 AI 面板当成 shell 在用。当前它"能用"只是因为绕过了模型调用，看起来"快"，但：
- 不能处理自然语言（"把这段话改简洁一些"）
- 不能批量推理（"把所有 TODO 改成已完成"）
- 不能跨块理解（"把第一段和第二段合并"）
- 和 AI 对话的本意完全背离

**结论**：direct path 应该退役，model path 是唯一主路径。

## 当前 model 主路径的具体缺陷

系统 prompt（`page_ai_workflow.rs:274`）只说了 `op` 四选一，**没有告诉模型每种 operation 需要的字段**：

```
当前 prompt:
"operations 的 op 只能是 replace、insert_after、delete、move_after。优先使用 page_xml 中的 block id；禁止输出解释文字。"

缺少的信息:
- replace 需要 blockId（或 matchText）+ content
- insert_after 需要 blockId（或 matchText）+ content
- delete 只需要 blockId（或 matchText）
- move_after 需要 blockId + targetBlockId
```

模型不知道 schema，自然会漏掉 `content` 字段。DeepSeek v4 Flash 的 `response_format: json_object` 只保证输出是合法 JSON，不保证字段齐全。

## 更深层问题：块操作粒度是否合理

当前 AI 编辑通过 `operations: [{ op: "replace", blockId: "...", content: "..." }]` 这种逐个块操作的方式执行。但：

1. **mnote 的在线文档本质上是一个 markdown 文件**，Tiptap 只是其块级 UI 表现层
2. **本地 md 文件模式**下，Tiptap 退化为纯显示层，编辑直接在 markdown 文本上进行
3. 在线文档应该**向本地文档靠拢**——对 AI 而言，最自然的编辑方式是"给我一段 markdown，我返回修改后的 markdown"，而不是"给我 blocks 数组，我逐个块产出 op"

如果在线文档和本地文档走两套 AI 编辑口径（一套块操作、一套文本操作），长期维护成本翻倍。

## 建议修复方向

### 立即修复（让 model 主路径可用）
1. **补全 system prompt 的 operation JSON schema**：明确 replace/insert_after 需要 `content` 字段，给出完整示例

### 架构收口（应该做的）
2. **退役 direct path**：`direct_block_edit_operations` + `quoted_segments` 整条路径标记 deprecated
3. **考虑降低块操作粒度**：AI 编辑是否可以走 markdown diff 而非逐个块 ops？在线文档和本地 md 能否共用同一条 AI 写入路径？
4. **在线/本地口径收敛**：在 `design/07-ai/` 中明确在线文档 AI 编辑应向本地 md 的简洁模型靠拢

## 证据

- Browser smoke (2026-05-16)：
  - Direct path（「」quote，本质是命令行）: ✅ 177ms — 这说明不了 AI 能力，只是正则匹配
  - Model path（自然语言，真 AI）: ❌ 400，replace 缺少 content
- 代码：`page_ai_workflow.rs` system prompt 缺 operation schema
- 用户反馈：direct path 不是 AI 面板应有的行为，应退役

## 运行时修复

- [page_ai_workflow.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/page_ai_workflow.rs:67) 当前运行时已退役 direct path，所有块编辑请求统一走模型输出 `search/replace` 对，再进入 `mnote.doc.markdown_edit`。
- [page_ai_workflow.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/page_ai_workflow.rs:307) system prompt 已改为明确要求 `operations[].search` 与 `operations[].replace`，不再要求模型输出旧的 block op `content` 字段。
- [page_ai_workflow.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/page_ai_workflow.rs:109) fast-path 写入已改走统一 mnote tool executor，避免绕过 tool toggle / audit / idempotency。

## 验证

- `cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_workflow -- --nocapture`
  - 结果：3 passed
- `cargo test --manifest-path rust/Cargo.toml -p mnote-web markdown_edit -- --nocapture`
  - 结果：8 passed

## 剩余说明

旧的 `direct_block_edit_operations` / `quoted_segments` helper 当前仅作为 dead code 与历史单测保留，不再是 `block_edit_workflow` 的运行时入口；后续可单独清理测试语义，但不影响本缺陷的运行时修复。