` → `| ` 结构；必须整表替换。单元格仅支持简单块（` `、` `-``、``、``、`
`、`![]() `），不可嵌套 ``、``、`` 等容器 |
| `highlight_block` | `` | 高亮块，仅支持简单块（``、` `-``、``、``、`
`、`![]() `），不可嵌套 ``、``、`` 等容器 |
| `columns` | `` → `` | 分栏布局，每个 column 支持简单块和 ``，不可嵌套 `` 或 `` |
| `image` | `![]() ` | **只读**——不可通过 XML 创建或修改，使用 `insert_image` 工具插入单张图片 |
| `image_column` | `` | **只读**——图片分栏展示，不可通过 XML 创建 |
| `horizontal_rule` | `
` | 分隔线 |
| `embed` | `` | **只读**——不可编辑或替换 |
| `note_audio_card` | `` | **只读**——语音录音卡片，使用 `get_audio_transcript` 获取转写内容 |
### `update_block_attrs` 支持的属性
| Block 类型 | 属性 | 可选值 |
|-----------|------|--------|
| `heading` | `level` | 1–6 |
| `heading` | `textAlign` | `"left"`、`"center"`、`"right"` |
| `paragraph` | `textAlign` | `"left"`、`"center"`、`"right"` |
| `code_block` | `language` | 语言标识字符串 |
| `todo_list` 子项 | `checked` | `true` / `false` |
## Troubleshooting
### block ID 失效（`BLOCK_NOT_FOUND`）
**现象**：写入操作报 `BLOCK_NOT_FOUND`，即使之前刚读取过该 block。
**原因**：编辑操作会导致 block ID 变化，缓存的 ID 已过期。
**解决**：写入前总是先 `get_note_outline` 或 `search_note_content` 刷新 ID；或使用上次 insert 返回的 `last_block_id` 作为下次 `anchor_id`。
### 表格编辑失败
**现象**：尝试编辑表格单元格时报错或内容丢失。
**原因**：表格只支持整表替换，不能编辑单个单元格。
**解决**：用 `edit_block` 的 `replace` 操作传入完整的 XML 表格（含表头分隔行）。
### embed block 不可写
**现象**：对 embed block 调用 `edit_block` 的 `replace` 操作返回错误。
**原因**：电子表格、视频、音频、LaTeX 等嵌入内容为只读占位符。
**解决**：跳过 embed block，仅操作其他可编辑 block 类型。
### 笔记只读（`DOCUMENT_READ_ONLY`）
**现象**：所有写入操作均返回 `DOCUMENT_READ_ONLY`。
**原因**：当前笔记 token 为只读权限，不可重试。
**解决**：告知用户此笔记为只读。读取操作仍正常。
### 编辑器未就绪（`EDITOR_NOT_READY`）
**现象**：操作返回 `EDITOR_NOT_READY`。
**原因**：笔记编辑器仍在初始化，通常 1-2 秒可恢复。
**解决**：等待片刻后重试。若 3 次仍失败，请用户检查笔记应用。
### WebSocket 未连接（`WEBSOCKET_NOT_CONNECTED`）
**现象**：`get_audio_transcript` 返回 `WEBSOCKET_NOT_CONNECTED`。
**原因**：网络断开或 WebSocket 连接中断。
**解决**：检查网络连接，等待 WebSocket 自动重连后重试。
### 其他注意事项
- **图片必须使用 `insert_image` 工具**：图片不可通过 XML 创建（`![]() ` 标签为只读）。`insert_image` 当前走在线上传，调用时需联网。支持 HTTP/HTTPS URL 和 base64 data URI。**本地文件路径不支持直接传入，需先读取并转为 base64 data URI**。**URL 必须直接指向图片资源（返回 image/* 内容类型），不可为 HTML 页面链接**。若 URL 返回 404、离线或非图片内容，将报 `IMAGE_FETCH_FAILED` 错误。`edit_block` 的 replace/insert/update_attrs 不支持图片（但 **move 可以移动图片 block**）。
- **`generate_image` 为 AI 文生图**：返回图片 URL，而不是直接插入笔记。需配合 `insert_image` 使用。每用户每分钟限 1 次，生成耗时约 30-120 秒。
- **`import_web_page` 仅支持白名单域名**：微信公众号、知乎、豆瓣等白名单域名可导入，非白名单域名会返回 `INVALID_PARAMS`。转换耗时约 5-30 秒。导入完成后自动创建新笔记并跳转。
- **`batch_edit` 执行顺序固定**：delete → replace → update_attrs → move → insert，与数组顺序无关。
- **`move` 操作支持所有 block 类型**：包括图片（`![]() `）、嵌入内容（``）等无法通过 XML 创建的只读标签。移动后 block_id 保持不变，无需刷新 outline。适用于调整内容顺序、重新组织文档结构。
- **`create_note` 创建空白笔记**：不支持初始内容，需用 `edit_block` 填充。
- **`read_section` 仅限标题**：`heading_block_id` 必须指向 `heading` block，否则报 `INVALID_BLOCK_TYPE`。
- **`get_cursor_block` 仅支持顶层 block**：光标位于高亮块（subdoc）或分栏（columns）内部时，会返回 `UNSUPPORTED_POSITION`。
- **`delete_note` 不可恢复**：必须先与用户确认。
- 当响应包含 `hints` 时，**遵循其建议**——它们指明了最快的恢复路径。
### 错误码速查
| 错误码 | 可重试 | 恢复方法 |
|--------|--------|----------|
| `INVALID_PARAMS` | 否 | 按 inputSchema 修正参数 |
| `EDITOR_NOT_READY` | 是 | 等待后重试 |
| `NO_ACTIVE_EDITOR_WINDOW` | 是 | 请用户打开笔记窗口 |
| `BLOCK_NOT_FOUND` | 否 | 刷新大纲获取有效 ID |
| `INVALID_BLOCK_TYPE` | 否 | 检查 block 类型 |
| `INVALID_CONTENT` | 否 | 修正内容格式 |
| `DOCUMENT_READ_ONLY` | 否 | 告知用户 |
| `FRONTEND_TIMEOUT` | 是 | 缩小范围或重试 |
| `IMAGE_FETCH_FAILED` | 是 | 检查图片 URL 是否直接指向图片资源，修正后重试 |
| `GENERATE_IMAGE_FAILED` | 否 | 修正 prompt 或检查白名单/登录状态 |
| `RATE_LIMITED` | 是 | 等待 60 秒后重试 |
| `WEBSOCKET_NOT_CONNECTED` | 是 | 检查网络，等待 WebSocket 重连后重试 |
| `INTERNAL_ERROR` | 是 | 重试；查 `get_mcp_logs`（隐藏工具） |
完整错误详情参见 `references/ERROR_CODES.md`。
## 常用编排模式
最高频的多工具组合，无需查阅完整用例手册即可使用。
**模式 1：搜索定位 → 分段读取**（长文档优先）
```
search_notes({ keyword }) → note_id
get_note_outline({ note_id }) → heading block ID
read_section({ note_id, heading_block_id }) → 按需读取章节
```
**模式 2：笔记内批量搜索替换**
```
search_note_content({ note_id, query }) → 匹配的 block_id 列表
read_blocks({ note_id, block_ids }) → 读取完整内容
batch_edit({ note_id, operations: [{ op: "replace", ... }, ...] }) → 原子替换
```
**模式 3：创建 → 填充模板**
```
create_note({ title }) → note_id（空白笔记）
manage_note_tags({ note_id, add: ["标签名"] }) → 分配标签
get_note_outline({ note_id }) → 获取空 block ID
batch_edit({ note_id, operations: [
{ op: "replace", block_id, content: "标题" },
{ op: "insert", anchor_id, position: "after", content: "模板内容... " }
]})
```
**模式 4：连续追加多段内容**（避免乱序）
```
# 方式 A（推荐）：单次 insert 拼接完整 XML
edit_block({ note_id, op: "insert", anchor_id: "last_id", position: "after",
content: "第一部分内容 A 第二部分内容 B " })
# 方式 B：链式 insert，用上次返回的 last_block_id 做锚点
edit_block({ ..., anchor_id: "id1", position: "after", content: "第一部分内容 A " })
→ { last_block_id: "new_id_1" }
edit_block({ ..., anchor_id: "new_id_1", position: "after", content: "第二部分内容 B " })
→ { last_block_id: "new_id_2" }
```
**模式 5：移动 block（图片、嵌入内容等）**
```
get_note_outline({ note_id }) → 找到源 block 和目标位置
edit_block({ note_id, op: "move", block_id: "img_id", anchor_id: "target_heading", position: "after" })
→ block_id 不变，无需刷新 outline
```
**模式 6：管理笔记标签**
```
find_tags() → 查看已有标签名
manage_note_tags({ note_id, add: ["工作", "项目"] }) → 添加标签
manage_note_tags({ note_id, remove: ["草稿"] }) → 移除标签
manage_note_tags({ note_id }) → 查看当前标签
```
**模式 7：分页读取超大文档**（无标题结构时优先，分页仅控制读取量，笔记无 block 上限）
```
read_note({ note_id })
→ pagination: { total_blocks: 350, has_more: true, next_offset: 100 }
read_note({ note_id, offset: 100 })
→ pagination: { has_more: true, next_offset: 200 }
read_note({ note_id, offset: 200 })
→ pagination: { has_more: false } ← 读完
```
更多组合模式和端到端场景参见 `references/USE_CASES.md`。
## 完整示例
**用户说**："帮我找到 Q1 报告，更新摘要部分，加一个结论"
**步骤 1**：定位笔记
```
search_notes({ keyword: "Q1 报告" })
→ data.notes[0].note_id = "note_xyz"
```
**步骤 2**：读取结构
```
get_note_outline({ note_id: "note_xyz" })
→ blocks: [
{ id: "h1abc", type: "heading", preview: "Q1 报告" },
{ id: "p1def", type: "paragraph", preview: "执行摘要..." },
{ id: "h2ghi", type: "heading", preview: "营收" },
{ id: "h2jkl", type: "heading", preview: "下一步计划" },
{ id: "p3mno", type: "paragraph", preview: "继续监控..." }
]
```
**步骤 3**：确认当前内容
```
read_blocks({ note_id: "note_xyz", block_ids: ["p1def"] })
→ "本季度各部门..."
```
**步骤 4**：原子编辑（替换摘要 + 插入结论）
```
batch_edit({ note_id: "note_xyz", operations: [
{ op: "replace", block_id: "p1def",
content: "本报告涵盖 2025 年 Q1 各部门业绩表现。营收超出目标 15%。 " },
{ op: "insert", anchor_id: "p3mno", position: "after",
content: "总结2025 年 Q1 是强劲的一个季度，所有关键指标均实现显著增长。 " }
]})
→ ok: true, last_block_id: "new_conclusion_id"
```
> 提示：`batch_edit` / `edit_block` 的 insert 操作中，content 可包含多个块级 XML 元素（如上例的 `` + ``），它们按 XML 顺序插入，无需分多次调用。返回的 `last_block_id` 可直接用于后续操作。
**步骤 5**：验证结果
```
read_section({ note_id: "note_xyz", heading_block_id: "h1abc", max_blocks: 5 })
→ 确认摘要已更新、结论已添加
```
**结果**：笔记摘要已替换为新内容，文末新增"总结"章节。
## 参考文档
- [API 参考](references/API_REFERENCE.md)——全部工具的完整 inputSchema
- [CLI 参考](references/CLI_REFERENCE.md)——`wpsnote-cli` 的 canonical 命令面、CLI 特有行为和 JSON 输出格式
- [错误码](references/ERROR_CODES.md)——详细错误码、hints 系统和恢复模式
- [用例手册](references/USE_CASES.md)——按复杂度递进的完整用例集（含端到端工作流示例）、Prompt 模板和异常处理速查
|