From learning-skills
Manages WPS notes via MCP tools: reads, edits, searches, creates, tags using block model and XML format. Activates on WPS Note mentions, note operations, or MCP errors like BLOCK_NOT_FOUND.
npx claudepluginhub wpsnote/wpsnote-skills --plugin learning-skillsThis skill uses the workspace's default tool permissions.
核心操作模式:**先定位(outline / search)→ 再读取(read)→ 最后编辑(write)**。所有内容以语义 XML 格式交换,所有定位基于 `block_id`(10 位字母数字)。
Bulk imports local documents from Obsidian vaults, SiYuan notes, WeChat archives, downloads, or directories into WPS Notes. Supports HTML, Markdown, PDF, DOCX, PPTX, XLSX with images and rich text. Triggers on import requests to WPS Notes.
Orchestrates Joplin MCP tools for note, notebook, and tag management. Guides setup via API token, editing vs updating notes, reading long content, ID handling, bulk tagging, and workflows.
Provides SiYuan Notes core knowledge: content blocks, references, embeds, API calls, templates, flashcards. Use for basic concepts, API principles, block syntax, template development, general operations.
Share bugs, ideas, or general feedback.
核心操作模式:先定位(outline / search)→ 再读取(read)→ 最后编辑(write)。所有内容以语义 XML 格式交换,所有定位基于 block_id(10 位字母数字)。
BLOCK_NOT_FOUND、EDITOR_NOT_READY 等错误)不适用于:本地 Markdown 文件操作、WPS 文档/表格/演示等其他产品、纯概念讨论。
block_id。paragraph、heading、blockquote、code_block、list、table、image(单图/图片分栏)、horizontal_rule、highlight_block、columns、embed、note_audio_card。embed block(电子表格、视频、LaTeX、倒计时等)为只读占位符,不可编辑。note_audio_card block 为语音录音卡片(只读),在 XML 中显示为 <NoteAudioCard/>,使用 get_audio_transcript 工具获取转写内容。<highlightBlock> 内仅支持简单块(段落、标题、引用、代码块、分隔线、图片),不可嵌套 <highlightBlock>、<columns>、<table>。<columns> 的每个 <column> 内支持简单块和 <highlightBlock>,不可嵌套 <table> 或 <columns>。note_id 来指定操作的笔记。list_notes 或 search_notes 获取 note_id;若用户要操作当前打开的笔记,可直接调用 get_current_note 获取。get_note_info 可获取笔记元数据(含标签),支持三种模式:单个 note_id 查询、批量 note_ids 查询(最多 100 个)、全量分页浏览(page/page_size/limit),无需读取全文内容。<p>、<h1>-<h6>、<blockquote>、<codeblock>、<table>、<highlightBlock>、<columns> 等。id 属性标识 block_id,如 <p id="aB3kLm9xZq">内容</p>。edit_block 等)的 block_id / anchor_id 只接受顶层 block ID(由 get_note_outline 返回)。read_note XML 中容器(<highlightBlock>、<columns>、<table>)内部段落的 id 仅供阅读参考,不可用于写入操作。replace 的目标 block 由工具参数 block_id 指定,content 建议不写 id;若显式写了根块 id,必须与目标 block_id 一致。insert 时新内容中的块级标签应省略 id,系统自动分配新的 block_id。<strong>粗体</strong>、<em>斜体</em>、<s>删除线</s>、<u>下划线</u>、<a href="url">链接</a>、<tag>#标签名</tag>。<tag>#name</tag> 可在段落等行内内容中使用。文本必须以 # 开头;多级标签用 / 分隔(如 <tag>#工作/项目</tag>);id 属性可选,已有标签可通过 find_tags 获取 id 后传入,新标签可省略 id,系统自动创建。标签同步到左侧标签树自动完成。限制:<tag> 优先放在笔记第一个 block(首行)中;每级最多 20 字、最多 10 级;不支持 emoji、空格、方括号等字符;<tag> 不可嵌套在 <a> 内(标签与链接互斥)。不合法内容会降级为纯文本并返回 warning。创建笔记后应在写入正文前先插入标签行;编辑已有笔记完成后若无标签也应补充。<emoji value="😀"/>(表情)、<latex formula="E=mc^2"/>(行内公式)、<br/>(硬换行)。<span> 传递:<span fontColor="#C21C13">红色文字</span>、<span fontHighlightColor="#FBF5B3">高亮文字</span>、<span fontSize="16">大号文字</span>。fontColor(12 色):#080F17 #C21C13 #DB7800 #078654 #0E52D4 #0080A0 #757575 #DA326B #D1A300 #58A401 #116AF0 #A639D7fontHighlightColor(9 色):#FBF5B3 #F8D7B7 #F7C7D3 #DFF0C4 #C6EADD #D9EEFB #D5DCF7 #E6D6F0 #E6E6E6highlightBlock 颜色(6 对 bg→border):#FAF1E6→#FEC794、#FAE6E6→#F2A7A7、#E6FAEB→#AFE3BB、#E6EEFA→#98C1FF、#F5EBFA→#E5B5FD、#EBEBEB→#C5C5C5columnBackgroundColor(42 色,含纯色和渐变):
#FFF5EB #FFECEB #E8FCEF #EBF2FF #FAF0FF #F2F2F2#FCFAE1 #FEF6E7 #FFF5ED #FFF2F0 #FFF2F4 #FFF0F7 #EEFFEB #EBFFF5 #E8FCFC #EBF8FF #EBF1FF #F0EDFF #F2E7E4 #F0E6DA #F5EEDA #EDF0EB #EDEEF0 #F0E4DD#FEF49C #BCFAAF #ADF4FF #C2D3FF #FFC7C7 #E0E0E0linear-gradient() 语法,如 linear-gradient(133deg,#FFFAF7 2.14%,#FFEDFE 96.88%)get_xml_reference 工具按需获取。DOCUMENT_READ_ONLY。retryable: false——不要重试,应告知用户。读取操作不受影响。所有工具返回统一的标准信封:
{ "ok": true, "code": "OK", "message": "...", "retryable": false, "data": { ... }, "hints": [] }
ok——调用是否成功。code——机器可读状态码(参见错误恢复)。retryable——为 true 时可直接重试。hints——建议的后续工具或操作。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 格式完整参考文档
对于长笔记,优先使用 get_note_outline → read_section,而非 read_note,以减少 token 开销。
当笔记超过 200 blocks 时,read_note 和 get_note_outline 的返回会自动分页——需通过 offset 和 block_limit 参数切换分页查看不同部分。笔记本身无 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 } ← 读完
也可手动控制每页大小:read_note({ note_id, offset: 0, block_limit: 50 })
get_note_outline 同理——has_more: true 时用 next_offset 续读:get_note_outline({ note_id, offset: next_offset })
read_section 同理——截断时返回 next_block_offset,传入 block_offset 续读:
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 ← 读完
get_current_note 和 get_note_outline 都返回 word_count、size_category 和 estimated_xml_chars,据此选择读取策略:
| size_category | 字数范围 | 策略 |
|---|---|---|
small | <5K 字 | read_note 直接读取全文 |
medium | 5K-20K 字 | get_note_outline → read_section 按章节读取 |
large | 20K-80K 字 | search_note_content 精准定位 → read_blocks 读取目标 + 上下文 → 编辑 |
very_large | >80K 字 | 同 large,精准定位优先 search_note_content;get_note_outline 支持分页读取(offset/block_limit)可按需获取结构 |
原则:文档越大,越应该用搜索定位而非顺序读取。对于 large/very_large 文档,优先使用 search_note_content 找到目标 block,再用 read_blocks 读取其上下文。操作当前笔记时,先调 get_current_note 获取 size_category,再决定路径。
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 可直接使用返回的 last_block_id 做锚点;操作其他 block 前通过 get_note_outline 刷新。
参数约束:edit_block / batch_edit 只传当前 op 需要的字段。replace / insert 的 content 必须直接填写完整 XML 字符串,不能传纯文本、Markdown,或 "把第二段改成……" 这类自然语言编辑指令。
连续插入的正确做法(避免乱序):
insert 中将所有内容拼成完整 XML(如 "<h2>A</h2><p>...</p><h2>B</h2><p>...</p>"),按 XML 顺序依次插入,无需分多次调用。insert,每次使用上一次返回的 last_block_id 作为下一次的 anchor_id,或在每次写入后调用 get_note_outline 刷新 ID。单个操作使用 edit_block,多个操作使用 batch_edit 合并为原子事务:
# 单个操作
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>" }
])
执行顺序固定(batch_edit):delete → replace → update_attrs → move → insert(与数组顺序无关)。
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) → 搜索标签
get_note_stats(detailed) → 使用统计
| 工具 | 用途 | 关键参数 |
|---|---|---|
get_note_outline | 获取结构大纲(含 title、word_count、block_count、size_category、estimated_xml_chars、blocks 列表、pagination)——获取 block_id 和文档规模的主要方式,超大文档自动分页 | note_id、max_depth?、include_preview?、offset?、block_limit? |
get_cursor_block | 获取当前光标所在顶层 block 的 block_id、block_type 和 note_id;光标位于高亮块或分栏内部时不支持 | (无参数) |
read_blocks | 按 ID 批量读取 block 的 XML 内容和属性,或读取单个 block 及前后上下文 | note_id、block_ids(批量)或 block_id+before?+after?(上下文) |
read_note | 读取全文或分页读取(XML),超大文档自动分页并返回 pagination(含 has_more + next_offset) | note_id、max_length?、offset?、block_limit? |
search_note_content | 在笔记内搜索文本,返回匹配 block 的 block_id/type/preview,用于编辑前定位 | note_id、query、max_results? |
read_section | 按标题读取完整章节(到下一同级标题),截断时返回 next_block_offset 用于续读 | note_id、heading_block_id、max_blocks?、block_offset? |
read_image | 读取图片 block 的实际内容(base64),可供视觉理解 | note_id、block_id |
get_audio_transcript | 获取语音录音(NoteAudioCard)的转写文本,返回句子列表(含说话人、时间戳) | shorthand_id(从 outline 的 note_audio_card block attrs 获取) |
get_xml_reference | 获取 XML 格式完整参考文档(所有标签、属性、写入示例) | (无参数) |
示例:
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()
| 工具 | 用途 | 关键参数 |
|---|---|---|
edit_block | 单个编辑操作(推荐入口),编辑后 block_id 可能变化需重新获取。insert 操作返回 new_block_ids 和 last_block_id。move 操作移动后 block_id 不变 | note_id、op(replace/insert/delete/update_attrs/move)、block_id/anchor_id/block_ids、content/attrs |
batch_edit | 多个操作的原子事务(全部成功或全部回滚),执行顺序固定。返回 new_block_ids 和 last_block_id | note_id、operations[] |
insert_image | 插入图片(图片不可通过 XML 创建,必须用此工具),当前走在线上传,返回 block_id 和尺寸 | note_id、anchor_id、position、src、alt? |
generate_image | AI 文生图,返回图片 URL(配合 insert_image 插入笔记)。每用户每分钟限 1 次,耗时 30-120 秒 | prompt、width?(默认 2688)、height?(默认 1536) |
import_web_page | 从白名单域名(微信公众号、知乎、豆瓣等)导入网页内容为笔记,返回笔记 ID、标题和摘要。耗时 5-30 秒 | url |
edit_block / batch_edit 操作类型:
op | 必填字段 |
|---|---|
"replace" | block_id、content |
"insert" | anchor_id、position("before"/"after")、content |
"delete" | block_ids |
"update_attrs" | block_id、attrs |
"move" | block_id、anchor_id、position("before"/"after") |
content 仅在 replace / insert 中出现,且必须是完整 XML 字符串,不是自然语言、纯文本或 Markdown。
文件引用参数(CLI 和脚本场景):当 content 或 operations 内容过大导致命令行截断时,可使用文件引用替代——content_file(传入文件路径,Electron 读取后填入 content)、operations_file(同理填入 operations)、__args_file(从 JSON 文件读取全部参数)。已有显式值时文件引用被忽略。详见 references/CLI_REFERENCE.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" }
以下工具仍可用但默认不展示,适用于需要单独调用的场景:
| 工具 | 用途 | 关键参数 |
|---|---|---|
replace_block | 替换单个 block 内容 | note_id、block_id、content |
insert_block | 在指定位置前后插入 | note_id、anchor_id、position、content |
delete_blocks | 删除 block | note_id、block_ids |
update_block_attrs | 修改 block 属性 | note_id、block_id、attrs |
| 工具 | 用途 | 关键参数 |
|---|---|---|
list_notes | 列出笔记,支持排序和分页,返回 { notes, meta } | limit?、sort?、direction?、since?、before?、page?、page_size?、starred? |
create_note | 创建空白笔记(仅含空段落),返回 { fileId, title } | title? |
get_note_info | 获取笔记元数据(不读全文),返回 title、时间、intro、tags、starred | note_id(单个)、note_ids(批量)、limit?、page+page_size(分页) |
get_current_note | 获取当前笔记 ID、元数据和文档统计(含 word_count、size_category) | (无参数) |
get_cursor_block | 获取当前光标所在 block 的 block_id、block_type 和 note_id;位于高亮块/分栏内部时不支持 | (无参数) |
search_notes | 搜索笔记(关键词 + 标签交集 + 时间范围),也可仅传 tags 按标签浏览 | keyword?、tags?、since?、before?、sort?、direction?、limit?、starred? |
find_tags | 列出或搜索标签,返回 { id, name } 数组 | keyword?(不传列出全部,传入则搜索) |
sync_note | 触发笔记与云端同步 | note_id |
delete_note | 永久删除笔记(不可恢复),须先与用户确认 | note_id 或 note_ids(批量,最多 100) |
get_note_stats | 使用统计(总笔记数、标签数、分布等) | detailed? |
get_mcp_logs | MCP 调用日志,用于诊断 INTERNAL_ERROR | limit? |
示例:
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: "工作" }) // 搜索标签
delete_note({ note_id: "abc123" }) // 不可恢复——必须先与用户确认!
get_mcp_logs({ limit: 20 }) // 查看最近的工具调用日志
| Block 类型 | XML 标签 | 说明 |
|---|---|---|
paragraph | <p> | 支持行内 mark(<strong>、<em>、<s>、<u>、<a>、<tag>)及行内节点(<emoji/>、<latex/>、<br/>) |
heading | <h1>-<h6> | 级别由标签名或 attrs.level 控制 |
blockquote | <blockquote> | 支持行内 mark 和 <br/> 换行 |
code_block | <codeblock lang="..."> | 纯文本内容;语言通过 lang 属性指定 |
list | <p listType="bullet|ordered|todo"> | 通过 listType、listLevel、checked 属性控制;有序列表额外支持 listId 和 listValue |
table | <table> | <tr> → <td> 结构;必须整表替换。单元格仅支持简单块(<p>、<h1>-<h6>、<blockquote>、<codeblock>、<hr/>、<img/>),不可嵌套 <highlightBlock>、<columns>、<table> 等容器 |
highlight_block | <highlightBlock> | 高亮块,仅支持简单块(<p>、<h1>-<h6>、<blockquote>、<codeblock>、<hr/>、<img/>),不可嵌套 <highlightBlock>、<columns>、<table> 等容器 |
columns | <columns> → <column> | 分栏布局,每个 column 支持简单块和 <highlightBlock>,不可嵌套 <table> 或 <columns> |
image | <img/> | 只读——不可通过 XML 创建或修改,使用 insert_image 工具插入单张图片 |
image_column | <imageColumn> | 只读——图片分栏展示,不可通过 XML 创建 |
horizontal_rule | <hr/> | 分隔线 |
embed | <embed type="..."/> | 只读——不可编辑或替换 |
note_audio_card | <NoteAudioCard/> | 只读——语音录音卡片,使用 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 |
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 调用 edit_block 的 replace 操作返回错误。
原因:电子表格、视频、音频、LaTeX 等嵌入内容为只读占位符。
解决:跳过 embed block,仅操作其他可编辑 block 类型。
DOCUMENT_READ_ONLY)现象:所有写入操作均返回 DOCUMENT_READ_ONLY。
原因:当前笔记 token 为只读权限,不可重试。
解决:告知用户此笔记为只读。读取操作仍正常。
EDITOR_NOT_READY)现象:操作返回 EDITOR_NOT_READY。
原因:笔记编辑器仍在初始化,通常 1-2 秒可恢复。
解决:等待片刻后重试。若 3 次仍失败,请用户检查笔记应用。
WEBSOCKET_NOT_CONNECTED)现象:get_audio_transcript 返回 WEBSOCKET_NOT_CONNECTED。
原因:网络断开或 WebSocket 连接中断。
解决:检查网络连接,等待 WebSocket 自动重连后重试。
insert_image 工具:图片不可通过 XML 创建(<img/> 标签为只读)。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 类型:包括图片(<img/>)、嵌入内容(<embed/>)等无法通过 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(空白笔记)
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:分页读取超大文档(无标题结构时优先,分页仅控制读取量,笔记无 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"
提示:
batch_edit/edit_block的 insert 操作中,content 可包含多个块级 XML 元素(如上例的<h2>+<p>),它们按 XML 顺序插入,无需分多次调用。返回的last_block_id可直接用于后续操作。
步骤 5:验证结果
read_section({ note_id: "note_xyz", heading_block_id: "h1abc", max_blocks: 5 })
→ 确认摘要已更新、结论已添加
结果:笔记摘要已替换为新内容,文末新增"总结"章节。