WPS笔记内置官方Skill深度解析（二）：工具体系（读取/定位工具、写入工具和管理工具）

本文为WPS笔记内置wps-note Skill系列解析第二篇。第一篇我们拆解了该Skill的核心定位、底层block模型、XML交换规范与基础工作流，明确了“先定位→再读取→最后编辑”的核心操作原则。本文将聚焦工具体系的底层设计逻辑，全量拆解读取/定位工具、写入工具和管理工具的细节、实操要点与避坑红线，为后续实操应用奠定基础。

一、工具体系的底层设计逻辑

wps-note Skill的工具体系围绕WPS笔记AI原生操作场景设计，严格匹配“定位-读取-编辑-管理”全流程闭环，官方将其划分为三大核心类别，职责边界清晰，避免操作冗余与冲突：

读取/定位工具：解决“找得到”的问题，是所有操作的前置核心，负责定位笔记、内容块及获取结构信息，是避免操作报错的关键；

写入工具：解决“改得了”的问题，是核心操作载体，负责内容新增、修改、删除，内置原子性保障，避免脏数据；

管理工具：解决“管得好”的问题，负责笔记生命周期、标签、元数据查询及故障诊断，覆盖全流程配套需求。

二、核心工具全量拆解：读取/定位工具——所有操作的前置核心

读取/定位工具是Skill操作体系的基础，官方明确要求：任何编辑操作前，必须通过此类工具获取最新、有效的note_id与block_id，否则易触发BLOCK_NOT_FOUND等高频错误。按操作范围可分为4个子类，严格遵循官方CLI文档规范，具体拆解如下：

（一）全局笔记定位工具：从全笔记库锁定目标note_id

此类工具核心作用是获取目标笔记的唯一标识note_id，是所有操作的第一步，核心工具共3个，具体参数与实操要求如下表所示：

工具名	核心用途	关键参数	适用场景	避坑红线
get_current_note	获取当前打开笔记的note_id、元数据、字数统计、size_category	无参数	操作当前激活的笔记窗口，是操作当前笔记的第一步必调用工具	仅支持当前前台激活笔记，无法获取历史打开笔记；需通过其返回的size_category决定后续读取策略
list_notes	列出全量笔记，支持排序和分页	limit?、sort?、direction?、page?、page_size?	无明确关键词的笔记浏览，如查看最近编辑的10篇笔记	大笔记库建议搭配page、page_size分页调用，避免单次返回内容过多
search_notes	按关键词、标签、时间范围精准搜索笔记	keyword?、tags?、since?、before?、limit?	有明确关键词/标签的目标笔记定位，是获取note_id的核心方式	仅传tags可按标签浏览，多标签为交集筛选；替代旧版list_tag_notes工具

（二）单笔记结构定位工具：锁定目标内容的block_id

拿到note_id后，需通过此类工具获取笔记结构信息，找到目标内容对应的顶层block_id，是编辑操作的核心前提，核心工具共2个：

工具名	核心用途	关键参数	适用场景	避坑红线
get_note_outline	获取笔记完整大纲，返回顶层block的id、type、预览及分页信息（含word_count、size_category）	note_id、offset?、block_limit?、max_depth?、include_preview?	编辑前刷新block_id、长文档结构梳理、超大文档分页结构获取	编辑后需重新调用刷新id；>200 blocks的超大文档自动分页，需用next_offset续读
get_cursor_block	获取当前光标所在顶层block的id、type及所属note_id	无参数	围绕光标位置的快速编辑，如在光标处添加内容	光标在容器块（高亮块、分栏等）内部时，会返回UNSUPPORTED_POSITION错误

（三）精准内容读取工具：按需获取，避免token浪费

此类工具用于精准读取目标内容，官方要求：文档越大，越优先使用精准定位读取，而非全量读取，核心工具共4个：

工具名	核心用途	关键参数	适用场景	避坑红线
read_blocks	批量读取block的XML内容，或读取单个block上下文	note_id、block_ids（批量）或block_id+before?+after?（上下文）	编辑前确认内容、读取目标段落及上下文，长文档编辑首选	仅支持顶层block_id，容器内部id不可用于读写
read_section	按标题block_id读取完整章节（从当前标题到下一同级标题结束）	note_id、heading_block_id、max_blocks?、block_offset?	5K-20K字中文档按章节读取	heading_block_id必须是heading类型，否则报INVALID_BLOCK_TYPE错误；章节截断时用next_block_offset续读
read_note	读取笔记全文或分页读取全文XML	note_id、offset?、block_limit?	仅适用于<5K字的small类小文档	禁止直接读取长文档全文，>200 blocks的超大文档需分页续读（has_more: true时用next_offset）
search_note_content	在单篇笔记内搜索文本，返回匹配block的id、type与内容预览	note_id、query、max_results?	20K字以上大/超大文档精准定位	长文档定位首选，效率远高于顺序读取

（四）特殊内容与规范读取工具

用于处理非文本内容与格式规范查询，为补充性读取工具，核心工具共3个：

工具名	核心用途	关键参数	适用场景	避坑红线
read_image	读取图片block的base64格式内容，供AI视觉理解	note_id、block_id	识别图片内表格、提取图片文字	仅支持image类型单图block，不可用于图片分栏block
get_audio_transcript	获取语音录音卡片的转写文本，带说话人、时间戳	shorthand_id（从note_audio_card的attrs中获取）	语音笔记的转写、总结、翻译	断网时返回WEBSOCKET_NOT_CONNECTED错误，需检查网络后重试
get_xml_reference	获取完整XML格式参考文档，含标签、属性、写入示例	无参数	不确定XML写法时查询规范，避免报错	仅作参考，不可直接复制写入，需匹配对应block类型

三、核心工具全量拆解：写入工具——内容编辑的核心载体

写入工具是Skill的核心能力载体，所有写入操作均遵循严格的XML规范与原子性规则，官方分为核心写入、特殊内容写入、隐藏写入三类，具体拆解如下：

（一）核心写入工具

日常编辑的核心工具，覆盖单操作、多操作原子编辑，核心共2个：

工具名	核心用途	关键参数与操作规则	适用场景	避坑红线
edit_block	单操作编辑首选，支持4类核心操作	核心参数：note_id、op（操作类型）；4类操作必填项：replace需block_id+content，insert需anchor_id+position+content，delete需block_ids，update_attrs需block_id+attrs	单一段落/标题的修改、新增、删除、属性调整	编辑后block_id可能变化，连续操作需通过get_note_outline刷新id或用last_block_id锚定；表格需整表替换，不可修改单个单元格
batch_edit	多操作合并的原子事务编辑，保证全部成功或回滚	核心参数：note_id、operations数组；执行顺序固定（与数组顺序无关）：delete→replace→update_attrs→insert；返回new_block_ids、last_block_id	批量修改、搜索替换，需保证数据一致性的场景	不可依赖数组顺序控制执行逻辑；单次最多100个子操作，避免事务过大

（二）特殊内容写入工具

专门处理图片、AI生图等无法通过XML直接创建的内容，核心共2个：

工具名	核心用途	关键参数	适用场景	避坑红线
insert_image	唯一合法的图片插入工具，不可通过XML创建图片	note_id、anchor_id、position、src、alt?	插入在线/本地图片到笔记	需联网；src仅支持HTTP/HTTPS图片直链和base64 data URI，本地文件需转为base64；URL需返回image/*类型，否则报IMAGE_FETCH_FAILED错误
generate_image	AI文生图，返回图片URL，需配合insert_image插入	prompt、width?、height?	根据文本生成配图插入笔记	每用户每分钟限调用1次，生成耗时30-120秒，频繁调用会触发RATE_LIMITED错误

（三）隐藏写入工具

包括replace_block、insert_block、delete_blocks、update_block_attrs，功能与edit_block对应操作完全一致，可正常调用但默认不展示。适用于需要单独调用特定操作的场景，完整使用规则如下：

隐藏工具名	核心用途	关键参数	与edit_block的对应关系	适用场景
replace_block	替换单个block的内容	note_id、block_id、content	对应edit_block的op: "replace"操作	仅需执行单个替换操作，无需其他操作类型的场景
insert_block	在指定锚点block的前后插入新内容	note_id、anchor_id、position、content	对应edit_block的op: "insert"操作	仅需执行单个插入操作，无需其他操作类型的场景
delete_blocks	删除指定的一个或多个block	note_id、block_ids	对应edit_block的op: "delete"操作	仅需执行删除操作，无需其他操作类型的场景
update_block_attrs	更新单个block的属性	note_id、block_id、attrs	对应edit_block的op: "update_attrs"操作	仅需修改block属性，无需修改内容的场景

> 官方提示：日常操作优先使用edit_block统一入口，隐藏工具仅用于需要单独拆分操作的特殊场景，不推荐常规使用，避免冗余。

四、核心工具全量拆解：管理工具——笔记全生命周期与故障诊断

覆盖笔记创建删除、元数据管理、标签管理、故障诊断全流程，核心工具共7个，具体如下：

工具名	核心用途	关键参数	适用场景	避坑红线
create_note	创建空白笔记（仅含空段落），返回note_id与title	title?	新建标准化、模板类笔记	不支持传入初始内容，需后续用edit_block/batch_edit填充
delete_note	永久删除笔记，不可恢复	note_id/note_ids（最多100个）	删除无用笔记	操作前必须与用户二次确认，删除后无法通过任何方式恢复
sync_note	触发笔记与云端同步	note_id	编辑后手动同步，避免本地内容未上传	仅触发同步动作，不返回同步结果，同步完成状态需通过前端确认
get_note_info	获取笔记元数据（标题、创建/更新时间、简介、标签等），无需读取全文	支持单note_id查询、批量note_ids查询（最多100个）、全量分页查询（page+page_size）	批量获取标签、统计笔记信息	批量查询最多100个note_id，超出会触发INVALID_PARAMS错误
find_tags	列出或搜索全量标签，返回标签的id与name	keyword?	获取已有标签id、按关键词搜索标签	大标签库建议搭配keyword筛选，提升查询效率
get_note_stats	获取笔记使用统计数据，包括总笔记数、标签数、字数分布等	detailed?	统计笔记库整体使用情况	detailed=true时会返回详细分类统计，耗时更长，需合理选择
get_mcp_logs	获取MCP工具调用日志，用于诊断内部错误	limit?	工具调用返回INTERNAL_ERROR时排查原因	仅返回最近20条日志（默认），超出需调整limit参数

WPS AI

2026-03-21 07:48:57 北京

3 +1