为知笔记 Skill（v2）

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

配置

WIZ_ENDPOINT=http://your-wiznote-server:port
WIZ_TOKEN=<your_token>
WIZ_KB_GUID=<your_kb_guid>
WIZ_USER_ID=your_email@example.com
WIZ_PASSWORD=your_password

核心原则

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

API 快速索引

1. 笔记基础操作

列出笔记

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

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

搜索笔记

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

读取笔记

# 自动识别协作笔记 / 普通笔记
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 并创建协作笔记。

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. 更新笔记

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

新内容段落

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

4. 删除 / 移动 / 复制

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

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

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

5. 分类（文件夹）管理

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

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

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

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

6. 标签管理

# 列出所有标签
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. 评论功能

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

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

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

8. 历史版本

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

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

9. 分享与权限

# 分享笔记（生成链接）
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. 附件管理

# 列出附件
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. 模板创建

# 可用模板：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（周报）

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

meeting_minutes（会议纪要）

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

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

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

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

12. Markdown → Blocks 转换

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

块快捷构造方法

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')        # 代码块
api.divider_block()                               # 分隔线
api.image_block('https://...', '图片说明')         # 图片

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

# 创建协作笔记（直接用 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 命令行

# 列出笔记
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