为知笔记 Skill（v2）#

基于为知笔记私有化 API 的连接器， 默认使用协作笔记模式，支持 Markdown 内容自动转换。

配置#

env

WIZ_ENDPOINT=http://192.168.1.121:30802
WIZ_TOKEN=<your_token>
WIZ_KB_GUID=c6522160-aca4-11ef-97d7-3bf3be62286f
WIZ_USER_ID=843909253@qq.com
WIZ_PASSWORD=i1ove1314W.

核心原则#

• 所有笔记操作默认使用 协作笔记（通过 WebSocket 协议）
• create_note / update_note 接受 Markdown 文本，自动转换为 blocks
• 传统 HTML 笔记通过 create_note(content_type='html') 显式创建

API 快速索引#

操作方法列出笔记api.get_note_list()搜索笔记api.search_notes(keyword)读取内容api.get_note_content(doc_guid)创建笔记api.create_note(title, markdown)更新笔记api.update_note(doc_guid, markdown)删除笔记api.delete_note(doc_guid)移动笔记api.move_note(doc_guid, category)复制笔记api.copy_note(doc_guid)分类管理api.list_categories() / create_category() / delete_category()标签管理api.list_tags() / add_tags() / remove_tags()评论api.get_comments() / add_comment()历史版本api.get_note_history() / get_note_version()分享api.share_note() / list_shares()附件api.get_note_attachments() / upload_attachment()模板创建api.create_from_template(template_name, title)Markdown转Blocksapi.markdown_to_blocks(md_text)

---

1. 笔记基础操作#

列出笔记#

python

api.get_note_list(version=0, count=50)

# 按分类列出
api.get_notes_by_category("/My Notes/", count=50)

搜索笔记#

python

results = api.search_notes(keyword="周报", with_abstract=True)
for note in results:
    print(note['title'], note['docGuid'])

读取笔记#

python

# 自动识别协作笔记 / 普通笔记
content = api.get_note_content(doc_guid)
detail = api.get_note_detail(doc_guid)  # 元数据

note_type = detail['info'].get('type')  # 'document' 或 'collaboration'

---

2. 创建笔记（协作笔记 + Markdown）#

create_note(title, content, category, tags) — 传入 Markdown，自动转为 blocks 并创建协作笔记。

python

result = api.create_note(
    title="2026年第17周周报",
    content="""# 本周完成

- 完成XXX模块开发
- 修复BUG #123

## 下周计划

- [ ] 开始YYY模块
- [ ] 编写测试文档

## 风险

> 暂无
""",
    category="/openclaw/周报/",
    tags="周报,openclaw"
)
# result = {docGuid, editorToken, title, category}

content_type 参数：

• markdown（默认）：Markdown 文本 → blocks
• blocks：直接传入 blocks 列表
• html：创建传统 HTML 笔记

---

3. 更新笔记#

python

api.update_note(
    doc_guid="xxx",
    content="""# 更新后的标题

新内容段落

- [x] 已完成任务
- [ ] 待办任务
""",
    title="更新后的标题"  # 可选，同时更新标题
)

---

4. 删除 / 移动 / 复制#

python

# 删除（移到回收站）
api.delete_note(doc_guid)

# 移动到其他分类
api.move_note(doc_guid, "/openclaw/归档/")

# 复制笔记
api.copy_note(doc_guid)                           # 自动加" - 副本"
api.copy_note(doc_guid, title="新标题", category="/其他分类/")

---

5. 分类（文件夹）管理#

python

# 列出所有分类
categories = api.list_categories()

# 创建分类
api.create_category(parent="/My Notes/", name="项目A")

# 删除分类
api.delete_category("/My Notes/项目A/")

# 重命名分类
api.rename_category("/My Notes/旧名称/", "新名称")

---

6. 标签管理#

python

# 列出所有标签
tags = api.list_tags()

# 为笔记添加标签
api.add_tags(doc_guid, ["周报", "重要"])

# 批量添加（逗号分隔字符串）
api.add_tags(doc_guid, "周报,2026,openclaw")

# 移除标签
api.remove_tags(doc_guid, "临时标签")

# 全局重命名标签
api.rename_tag("旧标签名", "新标签名")

---

7. 评论功能#

python

# 获取评论
comments = api.get_comments(doc_guid)

# 添加评论
api.add_comment(doc_guid, "这是一条评论内容")

# 删除评论
api.delete_comment(doc_guid, comment_guid)

---

8. 历史版本#

python

# 获取版本列表
versions = api.get_note_history(doc_guid)

# 读取指定版本内容
version_data = api.get_note_version(doc_guid, version_id)

---

9. 分享与权限#

python

# 分享笔记（生成链接）
share_info = api.share_note(
    doc_guid,
    access='read',    # 'read' 或 'edit'
    expire_days=30     # 0=永久
)
# share_info 包含分享URL

# 列出所有分享
api.list_shares()

# 取消分享
api.cancel_share(share_id)

---

10. 附件管理#

python

# 列出附件
attachments = api.get_note_attachments(doc_guid)

# 上传附件
result = api.upload_attachment(doc_guid, "/path/to/file.pdf")

# 下载附件
data = api.download_attachment(doc_guid, att_guid)

# 下载协作笔记图片
data = api.get_collaboration_image(doc_guid, image_name)

---

11. 模板创建#

python

# 可用模板：weekly_report / meeting_minutes / todo / reading_notes / project_plan / blank
result = api.create_from_template(
    template_name='weekly_report',
    title="2026年第17周周报",
    category="/openclaw/周报/",
    tags="周报",
    attendees="张三,李四",   # 会议模板变量
    recorder="王五",          # 会议模板变量
)

模板内容预览#

weekly_report（周报）

markdown

# {title}
## 本周完成
-
## 进行中
-
## 下周计划
-
## 风险与问题
>
## 备注

meeting_minutes（会议纪要）

markdown

# {title}
**日期**: {date}
**参会人**: {attendees}
**记录人**: {recorder}
## 会议议题
1.
## 讨论内容
### 议题一
### 议题二
## 决议
- [ ]
## 后续行动（表格）

todo（待办清单） 按紧急/重要四象限组织

project_plan（项目计划） 含时间线表格、风险评估表格

reading_notes（读书笔记） 含核心观点、章节摘要、精彩摘录

---

12. Markdown → Blocks 转换#

markdown_to_blocks(md_text) — 将 Markdown 转换为协作笔记 blocks 列表，支持：

语法转换结果# 标题``text_block(heading=1)``**粗体**``attributes: style-bold``*斜体*``attributes: style-italic``` 代码 ```attributes: style-code``[链接](url)``attributes: link``- 列表``list_block()``1. 有序``list_block(ordered=True)``- [x] 完成``list_block(checkbox='checked')``> 引用``text_block(quoted=True)````` ```code``` `````code_block()``| 表 |``table_block()``---``embed(embedType='hr')``![alt](src)``embed(embedType='image')

块快捷构造方法#

python

# 基础块
api.text_block('文本', heading=2)               # 标题/段落/引用
api.list_block('文本', ordered=True, level=2)    # 列表
api.table_block(['列1','列2'], [['a','b']])       # 表格（返回block+extra_data）
api.code_block('print("hello")', 'python')        # 代码块（返回block+extra_data）
api.divider_block()                               # 分隔线
api.image_block('https://...', '图片说明')         # 图片（URL或协作笔记内部文件名）

# v2.1 新增
api.link_block('百度', 'https://www.baidu.com')   # 链接文本
api.webpage_block('http://baidu.com')              # 嵌入网页
api.audio_block(src, file_name, file_size, file_type)  # 音频
api.file_block(src, file_name, file_size, file_type)   # 文件嵌入（office类型）
api.drawio_block(src)                              # 流程图/UML（SVG文件名）
api.encrypt_text_block(password, text, prompt)     # 加密文本块
api.formula_block(tex)                             # 数学公式

# 行内样式构造（加粗/链接等混合文本）
api.make_inline_block([
    ('标签：', True),    # True=加粗
    ('内容', False),     # False=普通
])

功能兼容性矩阵#

功能写入支持读取支持备注标题 (heading 1-3)✅✅段落文本✅✅加粗✅✅style-bold 属性_斜体_✅✅style-italic 属性删除线✅✅style-strikethrough 属性行内代码✅✅style-code 属性链接✅✅link 属性引用块✅✅quoted=True有序/无序列表✅✅复选框列表✅✅checked=True/False代码块✅✅需 extra_data表格✅⚠️写入完整，读取时单元格内容为空（已知限制）分割线✅✅图片✅✅URL或内部文件名音频✅✅需先上传附件获取src文件嵌入✅✅需先上传附件获取src流程图/UML✅✅需先上传SVG获取src加密文本✅✅AES加密数学公式✅✅LaTeX语法网页嵌入✅✅

---

13. 协作笔记底层操作（高级）#

python

# 创建协作笔记（直接用 blocks）
result = api.create_collaboration_note(
    title="标题",
    blocks=[
        api.text_block('一级标题', heading=1),
        api.text_block('正文'),
    ],
    category="/My Notes/",
    tags="标签"
)

# 更新协作笔记（内部 del + create）
api.update_collaboration_note(doc_guid, blocks, title="新标题")

# 获取 editorToken
token = api.get_collaboration_token(doc_guid)

# 获取原始 JSON 内容
raw = api.get_collaboration_content(token, doc_guid)
md = api.parse_collaboration_content(raw)

---

14. Wrapper 命令行#

bash

# 列出笔记
python wiznote_wrapper.py list [count]

# 搜索
python wiznote_wrapper.py search <keyword>

# 读取
python wiznote_wrapper.py get <doc_guid>

# 创建（Markdown）
python wiznote_wrapper.py create "标题" "Markdown内容" --category /My Notes/ --tags tag1,tag2

# 更新
python wiznote_wrapper.py update <doc_guid> "新Markdown内容" --title "新标题"

# 删除 / 移动 / 复制
python wiznote_wrapper.py delete <doc_guid>
python wiznote_wrapper.py move <doc_guid> /新分类/
python wiznote_wrapper.py copy <doc_guid> [新标题] [分类]

# 分类管理
python wiznote_wrapper.py categories
python wiznote_wrapper.py create_category /父分类/ 新名称
python wiznote_wrapper.py delete_category /分类路径/

# 标签管理
python wiznote_wrapper.py tags
python wiznote_wrapper.py add_tags <doc_guid> tag1,tag2
python wiznote_wrapper.py remove_tags <doc_guid> tag1

# 评论
python wiznote_wrapper.py comments <doc_guid>
python wiznote_wrapper.py add_comment <doc_guid> <text>

# 历史版本
python wiznote_wrapper.py history <doc_guid>

# 分享
python wiznote_wrapper.py share <doc_guid> [read|edit] [expire_days]
python wiznote_wrapper.py shares

# 附件
python wiznote_wrapper.py attachments <doc_guid>
python wiznote_wrapper.py upload <doc_guid> <file_path>

# 模板
python wiznote_wrapper.py templates
python wiznote_wrapper.py template weekly_report "标题" [分类]

# Markdown转Blocks预览
python wiznote_wrapper.py md2blocks "# 标题\n- 列表项"

---

15. 常见问题#

Q: Token 过期怎么办？#

A: Token 有效期约 15 分钟，API 会在初始化时自动登录获取。

Q: 如何创建普通 HTML 笔记？#

A: api.create_note(title, html, content_type='html')

Q: 协作笔记更新失败？#

A: update_collaboration_note 使用 del + create 方式覆盖，op 修改（err:1002）为已知限制。

Q: 分类不存在？#

A: 必须先通过 Web 界面创建分类，或使用 create_category() 创建。

Q: Markdown 表格导出？#

A: 支持，Markdown 表格自动转为 table_block。

技术架构#

• 认证：用户名密码 → token
• 普通笔记：REST API（create/save/download）
• 协作笔记：REST API 创建 + WebSocket（sharejs JSONv0 协议）读写
• 内容格式：Markdown → blocks（协作笔记） / HTML（普通笔记）
• 附件：Base64 / 二进制流

项目来源#

GitHub: https://github.com/damoncui668/wiz-mcp

更新记录#

• 2026-04-28 v2：全面升级
  • 笔记操作默认改为协作笔记模式
  • 新增： delete_note / move_note / copy_note
  • 新增：分类管理（创建/删除/重命名）
  • 新增：标签管理（添加/移除/重命名标签）
  • 新增：评论功能（查看/添加/删除）
  • 新增：历史版本（查看版本列表/读取版本）
  • 新增：分享功能（创建分享/列分享/取消分享）
  • 新增：附件上传
  • 新增： markdown_to_blocks 转换器（支持表格、代码块、复选框等）
  • 新增：5个笔记模板（周报/会议纪要/待办/读书笔记/项目计划）
  • 新增： create_from_template 一键从模板创建
  • 新增：Block 快捷构造方法（code_block / divider_block / image_block）
  • 调研报告： https://github.com/altairwei/WizNotePlus、https://github.com/WizTeam/WizQTClient、https://github.com/famotime/Wiznotes_tools
• 2026-05-14 v2.1：功能扩展
  • 新增：链接块 link_block(text, url)
  • 新增：网页嵌入块 webpage_block(url)
  • 新增：音频块 audio_block(src, file_name, file_size, file_type)
  • 新增：文件嵌入块 file_block(src, file_name, file_size, file_type)
  • 新增：流程图/UML 块 drawio_block(src)
  • 新增：加密文本块 encrypt_text_block(password, text, prompt)
  • 新增：公式块 formula_block(tex)
  • 新增：加粗/斜体/删除线行内样式 make_inline_block(parts)
  • 改进： table_block 动态列宽算法优化（中文按2倍宽度计算）
  • 改进： update_collaboration_note 支持删除线 style-strikethrough
  • 功能兼容性测试完成：标题/引用/链接/代码/公式/分割线/图片/音频/文件/流程图/表格/加密文本/网页嵌入