WPS Note MCP Skill

核心操作模式：先定位（outline / search）→ 再读取（read）→ 最后编辑（write）。所有内容以语义 XML 格式交换，所有定位基于 block_id（10 位字母数字）。

何时使用

• 用户提到 WPS 笔记、WPS Note、云笔记、金山笔记
• 用户要求读取、编辑、搜索、总结、翻译笔记内容
• 用户需要创建笔记、管理标签、整理笔记库
• 需要排查 MCP 工具调用失败（BLOCKNOTFOUND、EDITORNOTREADY 等错误）

不适用于：本地 Markdown 文件操作、WPS 文档/表格/演示等其他产品、纯概念讨论。

核心概念

Block 模型

• 笔记由 block 组成，每个 block 有唯一的 block_id。
• block 类型：paragraph、heading、blockquote、codeblock、list、table、image（单图/图片分栏）、horizontalrule、highlightblock、columns、embed、noteaudio_card。
• embed block（电子表格、视频、LaTeX、倒计时等）为只读占位符，不可编辑。
• noteaudiocard block 为语音录音卡片（只读），在 XML 中显示为 <NoteAudioCard/>，使用 getaudiotranscript 工具获取转写内容。
• 表格必须整表替换，无法编辑单个单元格。表格单元格仅支持简单块（段落、标题、引用、代码块、分隔线、图片），不可在单元格内嵌套高亮块、分栏、表格等容器类块。
• 容器嵌套限制：<highlightBlock> 内仅支持简单块（段落、标题、引用、代码块、分隔线、图片），不可嵌套 <highlightBlock>、<columns>、<table>。<columns> 的每个 <column> 内支持简单块和 <highlightBlock>，不可嵌套 <table> 或 <columns>。

note_id

• 大部分工具需要 note_id 来指定操作的笔记。
• 通过 listnotes 或 searchnotes 获取 noteid；若用户要操作当前打开的笔记，可直接调用 getcurrent_note 获取。
• getnoteinfo 可获取笔记元数据（含标签），支持三种模式：单个 noteid 查询、批量 noteids 查询（最多 100 个）、全量分页浏览（page/page_size/limit），无需读取全文内容。

XML 输入输出

• 所有内容以语义 XML 格式收发，使用标签如 <p>、<h1>-<h6>、<blockquote>、<codeblock>、<table>、<highlightBlock>、<columns> 等。
• 每个块级标签通过 id 属性标识 block_id，如 <p id="aB3kLm9xZq">内容</p>。
• 重要：写入操作（editblock 等）的 blockid / anchorid 只接受顶层 block ID（由 getnoteoutline 返回）。readnote XML 中容器（<highlightBlock>、<columns>、<table>）内部段落的 id 仅供阅读参考，不可用于写入操作。
• 写入时提供 XML 格式内容，系统自动转换为内部 block 模型。replace 的目标 block 由工具参数 blockid 指定，content 建议不写 id；若显式写了根块 id，必须与目标 blockid 一致。insert 时新内容中的块级标签应省略 id，系统自动分配新的 block_id。
• 行内 mark 使用语义标签：<strong>粗体</strong>、<em>斜体</em>、<s>删除线</s>、<u>下划线</u>、<a href="url">链接</a>。
• 标签管理：使用 managenotetags 工具管理笔记标签——直接添加/移除文件级标签，无需编辑文档内容。创建笔记后应调用 managenotetags({ note_id, add: ["标签名"] }) 分配标签；多级标签用 /，调用参数不要带 # 前缀；编辑已有笔记完成后若无标签也应补充。
• 行内自闭合元素：<emoji value="😀"/>（表情）、<latex formula="E=mc^2"/>（行内公式）、<br/>（硬换行）。
• 样式属性通过 <span> 传递：<span fontColor="#C21C13">红色文字</span>、<span fontHighlightColor="#FBF5B3">高亮文字</span>、<span fontSize="16">大号文字</span>。
• 颜色受预设色板约束，任意 hex 色值会被编辑器静默丢弃。各类颜色预设值：

- fontColor（12 色）：#080F17 #C21C13 #DB7800 #078654 #0E52D4 #0080A0 #757575 #DA326B #D1A300 #58A401 #116AF0 #A639D7 - fontHighlightColor（9 色）：#FBF5B3 #F8D7B7 #F7C7D3 #DFF0C4 #C6EADD #D9EEFB #D5DCF7 #E6D6F0 #E6E6E6 - highlightBlock 颜色（6 对 bg→border）：#FAF1E6→#FEC794、#FAE6E6→#F2A7A7、#E6FAEB→#AFE3BB、#E6EEFA→#98C1FF、#F5EBFA→#E5B5FD、#EBEBEB→#C5C5C5 - columnBackgroundColor（42 色，含纯色和渐变）： - 6 基础色：#FFF5EB #FFECEB #E8FCEF #EBF2FF #FAF0FF #F2F2F2 - 18 扩展纯色：#FCFAE1 #FEF6E7 #FFF5ED #FFF2F0 #FFF2F4 #FFF0F7 #EEFFEB #EBFFF5 #E8FCFC #EBF8FF #EBF1FF #F0EDFF #F2E7E4 #F0E6DA #F5EEDA #EDF0EB #EDEEF0 #F0E4DD - 6 饱和色：#FEF49C #BCFAAF #ADF4FF #C2D3FF #FFC7C7 #E0E0E0 - 12 渐变色：使用 CSS linear-gradient() 语法，如 linear-gradient(133deg,#FFFAF7 2.14%,#FFEDFE 96.88%)

• 完整 XML 格式参考已集成到 MCP Server Instructions 中自动注入（视客户端支持情况）。未注入时可调用 getxmlreference 工具按需获取。

只读 Token

• 部分笔记 token 为只读，写入工具会返回 DOCUMENTREADONLY。
• 此时 retryable: false——不要重试，应告知用户。读取操作不受影响。

响应格式

所有工具返回统一的标准信封：

{ "ok": true, "code": "OK", "message": "...", "retryable": false, "data": { ... }, "hints": [] }

• ok——调用是否成功。
• code——机器可读状态码（参见错误恢复）。
• retryable——为 true 时可直接重试。
• hints——建议的后续工具或操作。

工作流

1. 读取与理解笔记

get_current_note()                            → 获取 note_id + word_count + size_category（决定后续策略）
list_notes / search_notes                     → 按条件查找 note_id
get_note_outline(note_id)                     → 查看结构和 block ID（超大文档自动分页）
get_cursor_block()                           → 获取当前光标所在顶层 block_id
read_section(note_id, heading_id)             → 读取某个章节
read_blocks(note_id, block_ids)               → 批量读取指定 block
read_blocks(note_id, block_id, before, after) → 读取单个 block 及上下文
search_note_content(note_id, q)               → 在笔记内搜索文本
read_image(note_id, block_id)                 → 读取图片 block 的实际内容（base64）
get_audio_transcript(shorthand_id)            → 获取语音录音的转写内容
get_xml_reference()                           → 获取 XML 格式完整参考文档

对于长笔记，优先使用 getnoteoutline → readsection，而非 readnote，以减少 token 开销。

分页读取大文档

当笔记超过 200 blocks 时，readnote 和 getnoteoutline 的返回会自动分页——需通过 offset 和 blocklimit 参数切换分页查看不同部分。笔记本身无 block 数量上限，这些参数仅控制单次读取返回量。

read_note 示例：

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 }  ← 读完

也可手动控制每页大小：readnote({ noteid, offset: 0, block_limit: 50 })

getnoteoutline 同理——hasmore: true 时用 nextoffset 续读：getnoteoutline({ noteid, offset: nextoffset })

readsection 同理——截断时返回 nextblockoffset，传入 blockoffset 续读：

read_section({ note_id, heading_block_id, max_blocks: 50 })
→ truncated: true, next_block_offset: 50

read_section({ note_id, heading_block_id, block_offset: 50 })
→ truncated: false  ← 读完

文档大小策略

getcurrentnote 和 getnoteoutline 都返回 wordcount、sizecategory 和 estimatedxmlchars，据此选择读取策略：

原则：文档越大，越应该用搜索定位而非顺序读取。对于 large/verylarge 文档，优先使用 searchnotecontent 找到目标 block，再用 readblocks 读取其上下文。操作当前笔记时，先调 getcurrentnote 获取 size_category，再决定路径。

2. 编辑笔记内容

get_note_outline(note_id)                      → 获取最新 block ID
get_cursor_block()                            → 当前围绕光标位置编辑时，获取锚点 block
read_blocks(note_id, [target_id])              → 确认当前内容
insert_image(note_id, anchor_id, pos, src)     → 插入图片（独立工具，不走 XML，当前需联网）
generate_image(prompt, width?, height?)        → AI 文生图，返回图片 URL（配合 insert_image 插入笔记）
edit_block(note_id, op, ...)                   → 单个编辑操作（替换、插入、删除、更新属性、移动）
batch_edit(note_id, operations)                → 多个操作合并为一次原子事务

关键：编辑后 block ID 可能变化。连续 insert 可直接使用返回的 lastblockid 做锚点；操作其他 block 前通过 getnoteoutline 刷新。

参数约束：editblock / batchedit 只传当前 op 需要的字段。replace / insert 的 content 必须直接填写完整 XML 字符串，不能传纯文本、Markdown，或 "把第二段改成……" 这类自然语言编辑指令。

连续插入的正确做法（避免乱序）：

• 优先：在一次 insert 中将所有内容拼成完整 XML（如 "<h2>A</h2><p>...</p><h2>B</h2><p>...</p>"），按 XML 顺序依次插入，无需分多次调用。
• 链式：如果必须分多次 insert，每次使用上一次返回的 lastblockid 作为下一次的 anchorid，或在每次写入后调用 getnote_outline 刷新 ID。

3. 批量编辑（原子事务）

单个操作使用 editblock，多个操作使用 batchedit 合并为原子事务：

# 单个操作
edit_block(note_id, op: "replace", block_id: "id1", content: "<p>...</p>")
edit_block(note_id, op: "insert", anchor_id: "id2", position: "after", content: "<h2>...</h2><p>...</p>")

# 多个操作（原子事务）
batch_edit(note_id, operations: [
  { op: "delete",       block_ids: ["id1"] },
  { op: "replace",      block_id: "id2", content: "<p>...</p>" },
  { op: "update_attrs", block_id: "id3", attrs: { level: 2 } },
  { op: "move",         block_id: "id5", anchor_id: "id2", position: "after" },
  { op: "insert",       anchor_id: "id4", position: "after", content: "<h2>...</h2><p>...</p>" }
])

执行顺序固定（batchedit）：delete → replace → updateattrs → move → insert（与数组顺序无关）。

4. 管理笔记与标签

get_note_info(note_id)                      → 获取单个笔记元数据（含标签）
get_note_info(note_ids: [...])              → 批量获取多个笔记元数据（最多 100 个）
get_note_info(page, page_size)              → 分页浏览所有笔记元数据
search_notes(keyword, tags, since, before)  → 搜索笔记（也可按标签筛选笔记）
create_note(title)                          → 创建空白笔记（需用 edit_block 添加内容）
import_web_page(url)                       → 从白名单域名导入网页为笔记（微信公众号、知乎、豆瓣等）
delete_note(note_id)                        → 不可恢复——必须与用户确认
sync_note(note_id)                          → 触发同步
find_tags()                                 → 列出所有标签
find_tags(keyword)                          → 搜索标签
manage_note_tags(note_id, add, remove)      → 添加/移除笔记的文件级标签
get_note_stats(detailed)                    → 使用统计

工具速查表

读取/定位工具

示例：

get_note_outline({ note_id: "abc123" })
get_note_outline({ note_id: "abc123", offset: 100 })  // 分页续读
get_cursor_block()
read_blocks({ note_id: "abc123", block_ids: ["aB3kLm9xZq", "xY7nPq2wRt"] })
read_blocks({ note_id: "abc123", block_id: "xY7nPq2wRt", before: 2, after: 3 })
read_note({ note_id: "abc123" })
read_note({ note_id: "abc123", offset: 100 })  // 分页续读
read_note({ note_id: "abc123", offset: 0, block_limit: 50 })  // 手动控制每页大小
search_note_content({ note_id: "abc123", query: "季度总结" })
read_section({ note_id: "abc123", heading_block_id: "aB3kLm9xZq" })
read_section({ note_id: "abc123", heading_block_id: "aB3kLm9xZq", block_offset: 50 })  // 续读截断章节
read_image({ note_id: "abc123", block_id: "imgBlock01" })
get_audio_transcript({ shorthand_id: "sh_abc123" })
get_xml_reference()

写入工具

editblock / batchedit 操作类型：

content 仅在 replace / insert 中出现，且必须是完整 XML 字符串，不是自然语言、纯文本或 Markdown。

文件引用参数（CLI 和脚本场景）：当 content 或 operations 内容过大导致命令行截断时，可使用文件引用替代——contentfile（传入文件路径，Electron 读取后填入 content）、operationsfile（同理填入 operations）、__argsfile（从 JSON 文件读取全部参数）。已有显式值时文件引用被忽略。详见 references/CLIREFERENCE.md。

示例：

// 单个操作 — edit_block
edit_block({ note_id: "abc123", op: "replace", block_id: "xY7nPq2wRt", content: "<p>更新后的段落文本</p>" })
edit_block({ note_id: "abc123", op: "insert", anchor_id: "aB3kLm9xZq", position: "after", content: "<h2>新章节</h2><p>这里是新内容。</p>" })
edit_block({ note_id: "abc123", op: "delete", block_ids: ["xY7nPq2wRt", "kL5mNp8vBc"] })
edit_block({ note_id: "abc123", op: "update_attrs", block_id: "aB3kLm9xZq", attrs: { level: 2 } })
edit_block({ note_id: "abc123", op: "move", block_id: "imgBlock01", anchor_id: "aB3kLm9xZq", position: "after" })

// 多个操作（原子事务） — batch_edit
batch_edit({ note_id: "abc123", operations: [
  { op: "replace", block_id: "xY7nPq2wRt", content: "<p>更新后的段落文本</p>" },
  { op: "insert", anchor_id: "aB3kLm9xZq", position: "after", content: "<h2>新章节</h2>" }
]})

// 图片
insert_image({ note_id: "abc123", anchor_id: "aB3kLm9xZq", position: "after", src: "https://example.com/photo.png", alt: "示意图" })

// AI 文生图 → 插入笔记
generate_image({ prompt: "一只橘猫坐在窗台上，水彩画风格，暖色调" })
→ { image_url: "https://...", task_id: "...", width: 2688, height: 1536 }
// 然后用 insert_image 将返回的 image_url 插入笔记

// 导入网页为笔记
import_web_page({ url: "https://mp.weixin.qq.com/s/xxx" })
→ { fileId: "123456", title: "文章标题", intro: "摘要...", linkUrl: "https://xxx/note/123456" }

隐藏写入工具

以下工具仍可用但默认不展示，适用于需要单独调用的场景：

管理工具

示例：

list_notes({ sort: "update_time", direction: "desc", limit: 10 })
list_notes({ starred: true })                  // 仅列出已收藏笔记
search_notes({ keyword: "项目方案", tags: ["工作"], since: "2025-01-01T00:00:00Z" })
search_notes({ tags: ["工作"] })  // 按标签筛选笔记（替代原 list_tag_notes）
search_notes({ starred: true })  // 仅在已收藏笔记中搜索
create_note({ title: "会议记录 2025-03-03" })
get_current_note()
get_cursor_block()
get_note_info({ note_id: "abc123" })              // 单个笔记元数据（含标签）
get_note_info({ note_ids: ["abc123", "def456"] }) // 批量查询
get_note_info({ page: 1, page_size: 20 })         // 分页浏览所有笔记
get_note_info({ limit: 5 })                       // 仅获取前 5 条
find_tags()                       // 列出所有标签
find_tags({ keyword: "工作" })    // 搜索标签
manage_note_tags({ note_id: "abc123", add: ["工作", "项目"] })   // 为笔记添加标签
manage_note_tags({ note_id: "abc123", remove: ["草稿"] })        // 移除笔记标签
manage_note_tags({ note_id: "abc123" })                          // 查看当前标签
delete_note({ note_id: "abc123" })  // 不可恢复——必须先与用户确认！
get_mcp_logs({ limit: 20 })       // 查看最近的工具调用日志

Block 类型与 XML 标签

updateblockattrs 支持的属性

Troubleshooting

block ID 失效（BLOCKNOTFOUND）

现象：写入操作报 BLOCKNOTFOUND，即使之前刚读取过该 block。 原因：编辑操作会导致 block ID 变化，缓存的 ID 已过期。 解决：写入前总是先 getnoteoutline 或 searchnotecontent 刷新 ID；或使用上次 insert 返回的 lastblockid 作为下次 anchor_id。

表格编辑失败

现象：尝试编辑表格单元格时报错或内容丢失。 原因：表格只支持整表替换，不能编辑单个单元格。 解决：用 edit_block 的 replace 操作传入完整的 XML 表格（含表头分隔行）。

embed block 不可写

现象：对 embed block 调用 edit_block 的 replace 操作返回错误。 原因：电子表格、视频、音频、LaTeX 等嵌入内容为只读占位符。 解决：跳过 embed block，仅操作其他可编辑 block 类型。

笔记只读（DOCUMENTREADONLY）

现象：所有写入操作均返回 DOCUMENTREADONLY。 原因：当前笔记 token 为只读权限，不可重试。 解决：告知用户此笔记为只读。读取操作仍正常。

编辑器未就绪（EDITORNOTREADY）

现象：操作返回 EDITORNOTREADY。 原因：笔记编辑器仍在初始化，通常 1-2 秒可恢复。 解决：等待片刻后重试。若 3 次仍失败，请用户检查笔记应用。

WebSocket 未连接（WEBSOCKETNOTCONNECTED）

现象：getaudiotranscript 返回 WEBSOCKETNOTCONNECTED。 原因：网络断开或 WebSocket 连接中断。 解决：检查网络连接，等待 WebSocket 自动重连后重试。

其他注意事项

• 图片必须使用 insertimage 工具：图片不可通过 XML 创建（<img/> 标签为只读）。insertimage 当前走在线上传，调用时需联网。支持 HTTP/HTTPS URL 和 base64 data URI。本地文件路径不支持直接传入，需先读取并转为 base64 data URI。**URL 必须直接指向图片资源（返回 image/* 内容类型），不可为 HTML 页面链接。若 URL 返回 404、离线或非图片内容，将报 IMAGEFETCHFAILED 错误。editblock 的 replace/insert/updateattrs 不支持图片（但 move 可以移动图片 block**）。
• generateimage 为 AI 文生图：返回图片 URL，而不是直接插入笔记。需配合 insertimage 使用。每用户每分钟限 1 次，生成耗时约 30-120 秒。
• importwebpage 仅支持白名单域名：微信公众号、知乎、豆瓣等白名单域名可导入，非白名单域名会返回 INVALID_PARAMS。转换耗时约 5-30 秒。导入完成后自动创建新笔记并跳转。
• batchedit 执行顺序固定：delete → replace → updateattrs → move → insert，与数组顺序无关。
• move 操作支持所有 block 类型：包括图片（<img/>）、嵌入内容（<embed/>）等无法通过 XML 创建的只读标签。移动后 block_id 保持不变，无需刷新 outline。适用于调整内容顺序、重新组织文档结构。
• createnote 创建空白笔记：不支持初始内容，需用 editblock 填充。
• readsection 仅限标题：headingblockid 必须指向 heading block，否则报 INVALIDBLOCK_TYPE。
• getcursorblock 仅支持顶层 block：光标位于高亮块（subdoc）或分栏（columns）内部时，会返回 UNSUPPORTED_POSITION。
• delete_note 不可恢复：必须先与用户确认。
• 当响应包含 hints 时，遵循其建议——它们指明了最快的恢复路径。

错误码速查

完整错误详情参见 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: "<h1>标题</h1>" },
  { op: "insert", anchor_id, position: "after", content: "<p>模板内容...</p>" }
]})

模式 4：连续追加多段内容（避免乱序）

# 方式 A（推荐）：单次 insert 拼接完整 XML
edit_block({ note_id, op: "insert", anchor_id: "last_id", position: "after",
  content: "<h2>第一部分</h2><p>内容 A</p><h2>第二部分</h2><p>内容 B</p>" })

# 方式 B：链式 insert，用上次返回的 last_block_id 做锚点
edit_block({ ..., anchor_id: "id1", position: "after", content: "<h2>第一部分</h2><p>内容 A</p>" })
→ { last_block_id: "new_id_1" }
edit_block({ ..., anchor_id: "new_id_1", position: "after", content: "<h2>第二部分</h2><p>内容 B</p>" })
→ { 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: "<p>本报告涵盖 2025 年 Q1 各部门业绩表现。营收超出目标 15%。</p>" },
  { op: "insert", anchor_id: "p3mno", position: "after",
    content: "<h2>总结</h2><p>2025 年 Q1 是强劲的一个季度，所有关键指标均实现显著增长。</p>" }
]})
→ ok: true, last_block_id: "new_conclusion_id"

提示：batchedit / editblock 的 insert 操作中，content 可包含多个块级 XML 元素（如上例的 <h2> + <p>），它们按 XML 顺序插入，无需分多次调用。返回的 lastblockid 可直接用于后续操作。

步骤 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 模板和异常处理速查