WPS笔记内置官方Skill深度解析（四）：其他规范与错误排查
WPS 笔记内置的 wps-note Skill 是 AI 原生能力的核心载体，其核心价值在于将 WPS 笔记的操作标准化、流程化：通过 block 模型拆解笔记内容，以 XML 统一交换格式，结合 “先定位 - 再读取 - 后编辑” 的操作逻辑，适配不同大小的文档场景，既保证了操作的精准性，又兼顾了效率与原子性。该 Skill 覆盖了正常操作流程与异常处理场景，为WPS 笔记用户提供了从内容定位、读取到编辑、管理的全闭环能力，是 AI 赋能笔记管理的关键落地形式。
本文为WPS笔记内置wps-note Skill系列解析第四篇，承接前三篇内容——第一篇拆解核心定位与底层模型，第二篇详解阐述工具体系，第三篇阐述工具编排模式。
本文将补全前三篇未覆盖的官方完整规范细节。
1. Block属性更新（update_attrs）完整支持规则
edit_block的update_attrs操作与update_block_attrs工具，仅支持官方指定的block属性修改，不可自定义属性，全量支持规则如下表：
目标Block类型 | 支持修改的属性 | 属性可选值与说明 |
heading | level | 1-6，对应标题级别h1-h6 |
heading | textAlign | left/center/right，标题对齐方式 |
paragraph | textAlign | left/center/right，段落对齐方式 |
code_block | language | 标准代码语言标识字符串（如python、java、javascript等） |
todo列表子项 | checked | true/false，待办项的勾选状态 |
highlight_block | colorPair | 官方预设的背景-边框色对，对应highlightBlock颜色规范 |
columns | columnCount | 2-4，分栏数量 |
2. 标签（<tag>）写入完整约束与规范
标签是WPS笔记分类管理的核心功能，<tag>标签的写入有严格的官方约束，所有不合法内容会被降级为纯文本并返回warning，完整规则如下：
基础格式：必须以#开头，标准格式为<tag>#标签名</tag>，可嵌入在<p>、<h1>-<h6>等块级标签的行内内容中；
层级规则：多级标签用//分隔，格式为<tag>#一级标签//二级标签//三级标签</tag>，最多支持10级层级，每级标签名称最多20个字符；
字符限制：标签名称仅支持中文、英文、数字、下划线，不支持emoji、空格、方括号、特殊符号等非法字符；
互斥规则：<tag>标签不可嵌套在<a>链接标签内，标签与链接互斥，不可同时使用；
ID使用规则：已有标签可通过find_tags工具获取标签id，写入时传入id属性（格式<tag id="标签id">#标签名</tag>），避免创建重复标签；新标签可省略id属性，系统会自动创建并同步到左侧标签树。
3. 样式颜色预设值完整规范
WPS笔记编辑器仅支持官方预设的色值，任意非预设hex色值会被编辑器静默丢弃，全量预设色值规范如下，确保写入的样式可正常生效：
（1）字体颜色（fontColor）- 12色
#080F17、#C21C13、#DB7800、#078654、#0E52D4、#0080A0、#757575、#DA326B、#D1A300、#58A401、#116AF0、#A639D7
（2）文字高亮颜色（fontHighlightColor）- 9色
#FBF5B3、#F8D7B7、#F7C7D3、#DFF0C4、#C6EADD、#D9EEFB、#D5DCF7、#E6D6F0、#E6E6E6
（3）高亮块（highlightBlock）背景-边框色对 - 6组
背景色 | 对应边框色 |
#FAF1E6 | #FEC794 |
#FAE6E6 | #F2A7A7 |
#E6FAEB | #AFE3BB |
#E6EEFA | #98C1FF |
#F5EBFA | #E5B5FD |
#EBEBEB | #C5C5C5 |
（4）分栏背景色（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%)
高频错误全解析：现象、根源与解决方案
Skill 实操中高频异常及解决方法：
BLOCK_NOT_FOUND（block ID 失效）：编辑操作导致 block ID 变化，缓存 ID 过期；解决：写入前调用 get_note_outline 或 search_note_content 刷新 ID，或使用 last_block_id 作为锚点；
EDITOR_NOT_READY（编辑器未就绪）：笔记编辑器初始化中；解决：等待 1-2 秒后重试，3 次失败则请用户检查笔记应用；
DOCUMENT_READ_ONLY（笔记只读）：笔记 token 为只读权限；解决：告知用户，仅执行读取操作；
IMAGE_FETCH_FAILED（图片获取失败）：insert_image 的 URL 非图片资源 / 离线 / 404；解决：检查 URL 有效性，本地文件转为 base64 后传入。
结合官方故障排查文档与内测高频错误案例，整理10类最常见的操作错误，按错误类型分类，明确错误现象、根源及解决方案，帮助大家快速定位问题、高效排查，避免重复踩坑。
（一）定位类错误（最高频，占比40%）
错误代码 | 错误现象 | 错误根源 | 解决方案 |
BLOCK_NOT_FOUND | 调用编辑、读取工具时，提示“block不存在” | 1. block_id过期（编辑后未刷新）；2. 使用容器内部block_id；3. block已被删除 | 1. 调用get_note_outline刷新block_id；2. 仅使用顶层block_id；3. 确认block未被删除 |
NOTE_NOT_FOUND | 调用工具时，提示“笔记不存在” | 1. note_id错误；2. 笔记已被删除；3. 未同步云端笔记 | 1. 重新通过search_notes获取正确note_id；2. 确认笔记未被删除；3. 调用sync_note同步云端 |
UNSUPPORTED_POSITION | 调用get_cursor_block时报错 | 光标位于容器块（高亮块、分栏、表格内部） | 将光标移动到顶层段落、标题等非容器block内，重新调用 |
（二）编辑类错误（占比35%）
错误代码 | 错误现象 | 错误根源 | 解决方案 |
INVALID_XML | 调用编辑工具时，提示“XML格式无效” | 1. XML标签缺失闭合；2. 使用非官方支持的标签；3. 特殊符号未转义 | 1. 检查XML标签，确保闭合完整；2. 仅使用官方支持的标签；3. 特殊符号转义（<→<、>→>） |
TABLE_STRUCTURE_ERROR | 编辑表格时，提示“表格结构错误” | 1. 单元格合并后结构不完整；2. 表格缺少<thead>或<tbody>标签；3. 行、列数量不匹配 | 1. 检查合并单元格的rowspan/colspan属性，确保结构完整；2. 补充缺失的表格标签；3. 调整行、列数量，确保匹配 |
ATOMIC_OPERATION_FAILED | 调用batch_edit时，提示“原子操作失败” | 1. 子操作超出100个；2. 部分子操作的block_id无效；3. 操作顺序冲突 | 1. 拆分batch_edit调用；2. 检查所有子操作的block_id有效性；3. 遵循“delete→replace→update_attrs→insert”固定顺序 |
（三）特殊内容与系统类错误（占比25%）
错误代码 | 错误现象 | 错误根源 | 解决方案 |
IMAGE_FETCH_FAILED | 调用insert_image时，提示“图片获取失败” | 1. src不是HTTP/HTTPS直链或base64；2. URL返回非image/*类型；3. 网络中断 | 1. 更换合规的src格式；2. 确认URL返回image类型；3. 检查网络，重新调用 |
RATE_LIMITED | 调用generate_image时，提示“调用频率受限” | 每分钟调用超过1次，触发官方限流 | 控制调用频率，间隔1分钟以上，重新调用 |
INTERNAL_ERROR | 调用工具时，提示“内部错误” | 1. 工具调用参数异常；2. 系统服务临时故障；3. 笔记文件损坏 | 1. 检查参数格式；2. 等待1-2分钟重试；3. 调用get_mcp_logs排查故障，必要时重启WPS笔记 |
INVALID_PARAMS | 调用工具时，提示“参数无效” | 1. 参数缺失（如edit_block缺少op参数）；2. 参数格式错误；3. 批量查询note_id超过100个 | 1. 补充缺失参数；2. 修正参数格式；3. 拆分批量查询，控制在100个以内 |
官方定义的全量错误码、可重试性与标准恢复方法如下，实现错误排查全覆盖：
错误码 | 是否可重试 | 标准恢复方法 |
INVALID_PARAMS | 否 | 对照官方inputSchema修正参数格式、补充必填参数、调整参数范围 |
EDITOR_NOT_READY | 是 | 等待1-2秒编辑器初始化完成后重试，3次失败请用户检查WPS笔记应用是否正常打开 |
NO_ACTIVE_EDITOR_WINDOW | 是 | 请用户打开WPS笔记窗口并激活目标笔记后重试 |
BLOCK_NOT_FOUND | 否 | 调用get_note_outline刷新获取最新的有效block_id，确认目标block未被删除 |
INVALID_BLOCK_TYPE | 否 | 检查操作的block类型是否符合工具要求，如read_section仅支持heading类型block |
INVALID_CONTENT | 否 | 修正XML内容格式，检查标签闭合、非法标签、特殊符号转义 |
DOCUMENT_READ_ONLY | 否 | 告知用户当前笔记为只读权限，仅可执行读取操作，不可写入 |
FRONTEND_TIMEOUT | 是 | 缩小操作范围（如减少批量操作数量）后重试，或等待网络恢复后重试 |
IMAGE_FETCH_FAILED | 是 | 检查图片URL是否为直链、是否可正常访问、是否为image/*类型，本地文件转为base64格式后重试 |
GENERATE_IMAGE_FAILED | 否 | 修正生图prompt，检查用户登录状态与白名单权限，不可重复重试 |
RATE_LIMITED | 是 | 严格遵循工具频率限制，等待60秒后重试，如generate_image每分钟限1次 |
WEBSOCKET_NOT_CONNECTED | 是 | 检查网络连接，等待WebSocket自动重连后重试 |
INTERNAL_ERROR | 是 | 先重试1次，若仍失败调用get_mcp_logs查看详细日志排查问题，必要时请用户重启WPS笔记 |
TABLE_STRUCTURE_ERROR | 否 | 修正表格XML结构，检查单元格合并后的行列匹配、标签闭合、必填标签完整性 |
ATOMIC_OPERATION_FAILED | 否 | 拆分批量操作数量，检查所有子操作的参数与block_id有效性，遵循固定执行顺序 |
NOTE_NOT_FOUND | 否 | 重新通过search_notes/list_notes获取正确的note_id，确认笔记未被删除、已同步云端 |
UNSUPPORTED_POSITION | 否 | 将光标移动到顶层非容器block内，重新调用工具 |
