WizNote

为知笔记（WizNote）API连接器，支持笔记的增删改查、搜索、附件管理、分类、标签、评论、分享等全部操作。当用户提到"为知笔记"、"WizNote"、"Wiz"，或需要在为知笔记中进行任何操作时使用此技能。

Install

openclaw skills install @wangfengxiang/wiznote

为知笔记 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转Blocks	`api.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
- 功能兼容性测试完成：标题/引用/链接/代码/公式/分割线/图片/音频/文件/流程图/表格/加密文本/网页嵌入

WizNote

Install

为知笔记 Skill（v2）

配置

核心原则

API 快速索引

1. 笔记基础操作

列出笔记

搜索笔记

读取笔记

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

3. 更新笔记

4. 删除 / 移动 / 复制

5. 分类（文件夹）管理

6. 标签管理

7. 评论功能

8. 历史版本

9. 分享与权限

10. 附件管理

11. 模板创建

模板内容预览

12. Markdown → Blocks 转换

块快捷构造方法

功能兼容性矩阵

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

14. Wrapper 命令行

15. 常见问题

Q: Token 过期怎么办？

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

Q: 协作笔记更新失败？

Q: 分类不存在？

Q: Markdown 表格导出？

技术架构

项目来源

更新记录

Related skills