WPS笔记内置官方Skill深度解析（一）：核心能力与操作逻辑

快乐小子新
快乐小子新

作为 WPS 笔记内测阶段推出的 AI 原生核心能力，内置的 wps-note Skill（本地路径一般为：D:\wpsnote-beta\resources\skills\wps-note\wps-note，官方仓库 ：https://github.com/wpsnote/wpsnote-skills）基于 MCP工具体系构建，以 block 文档模型为核心、XML 为统一内容交换格式，为 WPS 笔记的读取、编辑、管理提供了标准化、可扩展的操作范式。

  1. Skill 的核心定位与适用场景

1. 核心定位

该 Skill 是 WPS 笔记与 MCP 工具体系对接的核心桥梁，所有操作遵循 “先定位→再读取→最后编辑” 的核心模式：通过 outline（大纲）或 search（搜索）定位目标内容，读取对应 block 的 XML 内容后，再执行编辑操作，全程以 10 位字母数字组成的 block_id 作为定位核心标识。

2. 适用场景

当用户提及 “WPS 笔记”“云笔记”“金山笔记”，或提出读取、编辑、搜索、总结、翻译笔记内容，创建笔记、管理标签、整理笔记库等需求时，该 Skill 会自动触发；同时，它也适配 MCP 工具调用错误的排查（如 BLOCK_NOT_FOUND、EDITOR_NOT_READY 等典型错误）。

3. 不适用场景

需要明确的是，该 Skill不适用于本地 Markdown 文件操作、WPS 文档 / 表格 / 演示等其他 WPS 产品的操作，也不支持纯概念性的 WPS 笔记功能讨论 —— 其核心聚焦于 WPS 笔记本身的实操性操作。

二、核心概念：理解 Skill 操作的底层逻辑

1. Block 模型：笔记的最小操作单元

WPS 笔记的所有内容均由 block块构成，每个 block 对应唯一的 10 位字母数字 block_id，不同类型的 block 适配不同的笔记内容形态：

  • 基础块类型：段落（paragraph）、标题（heading）、引用（blockquote）、代码块（code_block）、列表（list）、表格（table）等；

  • 多媒体 / 特殊块类型：图片（image）、语音录音卡片（note_audio_card）、嵌入块（embed）、分栏（columns）、高亮块（highlight_block）等；

  • 特殊约束：

  • embed 块（电子表格、视频、LaTeX、倒计时等）为只读占位符，无法编辑；

  • note_audio_card 块为只读语音录音卡片（非占位符），在 XML 中显示为<NoteAudioCard/>，可通过get_audio_transcript工具获取转写内容；

  • 表格仅支持整表替换，不能修改单个单元格。

官方定义的block类型与对应XML标签、使用规则如下表所示，覆盖所有可操作与只读块类型：

Block 类型

对应XML标签

核心使用规则与说明

paragraph

<p>

基础段落块，支持所有行内语义标签（<strong>/<em>/<s>/<u>/<a>/<tag>）、行内自闭合元素（<emoji/>/<latex/>/<br/>）与样式<span>标签

heading

<h1>-<h6>

标题块，级别由标签名或level属性控制，支持行内语义标签与样式设置，可通过textAlign属性设置对齐方式

blockquote

<blockquote>

引用块，支持行内语义标签与样式设置，不可嵌套多层引用

code_block

<codeblock lang="...">

代码块，仅支持纯文本内容，代码语言通过lang属性指定，不可包含行内语义标签

list

`<p listType="bullet

ordered

table

<table>

表格块，采用<table>→<tr>→<td>标准结构，仅支持整表替换，不可编辑单个单元格，支持rowspan/colspan单元格合并

highlight_block

<highlightBlock>

高亮容器块，可包含多个子block元素，仅支持整块替换，内部子block的id不可用于写入操作

columns

<columns>→<column>

分栏容器块，每个<column>子标签可包含多个子block元素，仅支持整块替换，内部子block的id不可用于写入操作

image

<img/>

单图块，只读不可通过XML编辑/创建，必须通过insert_image工具插入

image_column

<imageColumn>

图片分栏块，只读，不可通过XML编辑/创建

horizontal_rule

<hr/>

分隔线块，支持直接通过XML插入，不可编辑内容仅可替换/删除

embed

<embed type="..."/>

嵌入内容块（电子表格、视频、LaTeX、倒计时等），只读占位符，不可编辑/替换

note_audio_card

<NoteAudioCard/>

语音录音卡片块，只读，不可编辑，需通过get_audio_transcript工具获取转写文本

2. note_id：笔记的唯一标识

绝大多数操作需要通过 note_id 指定目标笔记，获取方式分为三类：

  • 针对 “当前打开的笔记”：调用 get_current_note 工具直接获取；

  • 针对指定笔记：通过 list_notes（列出笔记）或 search_notes（搜索笔记）工具获取；

  • 元数据查询：get_note_info 工具支持单 note_id 查询、批量 note_ids 查询（最多 100 个）、全量分页浏览，无需读取笔记全文即可获取标题、标签等元数据。

3. XML：内容交换的统一格式

该 Skill 的所有内容收发均以语义 XML 为标准，核心规则包括：

  • 块级标签与 block_id 绑定：如<p id="aB3kLm9xZq">段落内容</p>，id 属性对应 block_id；

  • 写入操作的 ID 约束：edit_block 等写入操作仅接受 “顶层 block ID”（由 get_note_outline 返回），容器块（如 highlightBlock、columns、table）内部段落的 id 仅作阅读参考，不可用于写入；

  • 行内格式与标签：支持粗体（<strong>）、斜体（<em>）、删除线（<s>）、下划线（）、链接（<a href="url">链接</a>）、标签（<tag>#标签名</tag>）等语义标签；其中标签需以 #开头，多级标签用 // 分隔（如<tag>#工作 // 项目</tag>），且有严格约束：每级最多 20 字、最多 10 级，不支持 emoji / 空格 / 方括号等字符；<tag>不可嵌套在<a>内（标签与链接互斥），不合法内容会降级为纯文本并返回 warning；

  • 样式与特殊元素：通过传递字体颜色（fontColor）、文字高亮色（fontHighlightColor）等样式，任意 hex 色值会被编辑器静默丢弃，需使用预设色板值；支持表情（<emoji value="😀"/>）、行内公式（<latex formula="E=mc^2"/>）、硬换行（）等自闭合元素。

WPS笔记的复杂排版（分栏、高亮块、表格合并、公式插入等），需通过规范XML标签实现，结合get_xml_reference工具查询的规范，补充3个高频复杂排版的实操要点，避免因XML格式错误导致排版失效：

  1. 分栏排版：使用<grid>与<grid_column>标签，确保每个分栏包含独立block，示例：<grid id="xxx"><grid_column id="xxx"><p>分栏1内容</p></grid_column><grid_column id="xxx"><p>分栏2内容</p></grid_column></grid>，不可嵌套多个<grid>标签，否则会导致分栏错乱。

  1. 表格合并：仅支持单元格跨行（rowspan）、跨列（colspan）合并，需在<td>标签中添加对应属性，示例：<td id="xxx" rowspan="2" colspan="1">合并2行1列</td>，合并后需确保表格结构完整，不可出现单元格缺失，否则会触发TABLE_STRUCTURE_ERROR错误。

  1. 公式与代码块：公式使用<latex>标签，复杂公式需严格遵循LaTeX语法；代码块需用<pre>嵌套<code>标签，并指定lang属性，示例：<pre id="xxx"><code id="xxx" lang="python">print("hello")</code></pre>，避免直接使用<code>标签单独包裹代码块。

4. 只读 Token：权限约束

部分笔记的 token 为只读权限，此时所有写入操作会返回 DOCUMENT_READ_ONLY 错误，且 retryable 为 false（不可重试），但读取操作不受影响。

三、核心工作流：从读取到编辑的完整闭环

1. 读取与理解笔记：按需获取，适配文档大小

读取笔记的核心逻辑是 “按文档大小适配策略”，且操作当前笔记时需先调用 get_current_note 获取 size_category，再决定读取路径，避免无意义的全量读取：

  • 小文档（small，<5K 字）：直接调用 read_note 读取全文；

  • 中文档（medium，5K-20K 字）：先 get_note_outline 获取大纲，再 read_section 按章节读取；

  • 大文档（large，20K-80K 字）/ 超大文档（very_large，>80K 字）：先 search_note_content 精准定位目标 block，再 read_blocks 读取目标及上下文。

同时，read_note、get_note_outline、read_section 均支持分页，超大文档可通过 offset/block_limit 参数分批次读取，避免单次返回内容过载。

2. 编辑笔记内容：精准操作，保证原子性

编辑操作的核心是围绕 block_id 展开，核心工具包括：

  • 单操作编辑：edit_block 支持 replace（替换，必填 block_id+content）、insert（插入，必填 anchor_id+position+content）、delete（删除，必填 block_ids）、update_attrs（更新属性，必填 block_id+attrs）四类操作；

  • 批量原子编辑：batch_edit 将多个操作合并为原子事务（执行顺序固定：delete→replace→update_attrs→insert），保证 “全部成功或全部回滚”；

  • 特殊内容编辑：

  • 图片：需通过 insert_image 工具插入（不可通过 XML 创建），当前需联网；支持 HTTP/HTTPS URL 和 base64 data URI（本地文件需转为 base64 后传入），URL 必须直接指向图片资源（返回 image/* 内容类型），否则报 IMAGE_FETCH_FAILED 错误；

  • AI 文生图：调用 generate_image 获取图片 URL（每用户每分钟限 1 次，生成耗时约 30-120 秒）后，再用 insert_image 插入笔记。

编辑的关键注意点：操作后 block_id 可能变化，连续插入需使用上一次返回的 last_block_id 作为锚点，或重新调用 get_note_outline 刷新 ID。

3. 笔记与标签管理：标准化的元数据操作

针对笔记和标签的管理，Skill 提供了标准化工具：

  • 笔记管理：

  • create_note：创建空白笔记（仅含空段落，不支持初始内容，需用 edit_block 填充）；

  • delete_note：永久删除笔记（不可恢复，操作前必须与用户确认）；

  • sync_note：触发笔记与云端同步；

  • 标签管理：find_tags（列出 / 搜索标签）、行内<tag>标签写入（自动同步到左侧标签树）；

  • 元数据查询：get_note_info 支持单 / 批量 / 分页查询笔记元数据，无需读取全文。

WPS AI WPS AI
北京
浏览 1393
1
4
分享
4 +1
1 +1
全部评论