Claude Skills for 思源笔记

version
1.0.0
GitHub stars
18

Install

/plugin install siyuan@siyuan-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add zhiluop/siyuan-skills.

Contents

Discovered from source

Skills 4

通用文章导入 Skill

从各种来源(微信公众号、知乎、掘金、博客等)抓取文章并导入到思源笔记。

快速开始

基本用法

# 导入单篇文章
python scripts/import_article.py <文章URL>

# 指定笔记本
python scripts/import_article.py <文章URL> <笔记本名称>

处理图片

import subprocess

# 上传单张图片
result = subprocess.run([
    'python', 'scripts/upload_image.py',
    'https://example.com/image.jpg', '图片描述'
], capture_output=True, text=True)

if result.returncode == 0:
    _, asset_path, _ = result.stdout.strip().split('|', 2)
    print(f"资源路径:{asset_path}")

支持的文章来源

来源域名特殊处理
微信公众号mp.weixin.qq.com图片必须下载
知乎专栏zhuanlan.zhihu.com移除推荐内容
掘金juejin.cn处理代码块
其他博客任意 URL检查防盗链

核心特性

1. 自动图片处理

网络图片(尤其是微信)不能直接在思源显示,会自动:

  • 下载到临时目录
  • 上传到思源资源库
  • 替换为本地路径
  • 清理临时文件

2. 防止重复导入

创建文档前自动检查是否已存在,避免重复。

3. 默认笔记本

网络文章统一存入 知识储备 笔记本,自动创建。

关键约束

Windows 环境乱码问题

重要:Windows 下必须使用 Python 脚本调用 API,避免 curl 中文乱码

# ✅ 正确
response = requests.post(
    f'{api_url}/api/filetree/createDocWithMd?token={token}',
    json={'notebook': nb_id, 'path': '/标题', 'markdown': content}
)

# ❌ 错误(会产生乱码)
curl -X POST "..." -d '{"markdown": "中文内容"}'

文档命名规范

使用简单字符,避免特殊符号:

✅ /技术文章-20250125
✅ /RDL技术详解
❌ /标题:包含@#$特殊字符

参考文档

配置文件

推荐在仓库根目录放置 .claude/siyuan.json(也兼容根目录 siyuan.json):

{
    "api_url": "http://127.0.0.1:6806",
    "api_token": "your-api-token",
    "local_path": "/path/to/siyuan/workspace"
}
  • local_path 应指向思源工作目录根目录,资源会保存到 {local_path}/data/assets/
  • 如果思源在 Docker 中而脚本在宿主机执行,local_path 应填写宿主机挂载路径,而不是容器内路径
  • 不使用 WebDAV 时,remote_path 可以省略,或保留但设置 webdav: false

常见问题

Q: 图片无法显示? A: 使用 upload_image.py 下载上传,详见 图片处理参考

Q: 如何验证文档创建成功? A: 使用 SQL 查询验证,详见 API 参考

Q: 如何避免重复创建文档? A: 创建前检查函数,详见 工作流程

思源笔记 Excalidraw 图表生成器

为思源笔记生成 Excalidraw 风格的图表,直接输出 SVG 文件并自动保存到思源笔记资源目录。

工作流程

  1. 分析内容 - 识别概念、关系、层次结构
  2. 选择图表类型 - 根据内容特性选择最佳可视化形式
  3. 生成 SVG - 创建 Excalidraw 风格的 SVG 图表
  4. 保存文件 - 自动保存到思源笔记资源目录
  5. 返回路径 - 提供可直接在思源笔记中使用的资源路径

配置文件读取

必须首先读取 siyuan.json 配置文件,获取保存路径信息:

{
    "local_path": "本地路径(优先使用)",
    "remote_path": {
        "webdav": true,
        "url": "WebDAV 服务器地址",
        "username": "用户名",
        "password": "密码",
        "assets_path": "资源目录路径"
    }
}

路径选择规则

  1. 优先使用 local_path:如果 local_path 非空,直接保存到该路径下的 data/assets/ 目录
  2. 备选使用 remote_path:如果 local_path 为空,通过 WebDAV 上传到 remote_path.assets_path

图表类型选择指南

根据内容特性选择最合适的图表形式:

类型英文使用场景设计要点
流程图Flowchart步骤说明、工作流程、任务执行顺序箭头连接步骤,清晰表达流程走向
思维导图Mind Map概念发散、主题分类、灵感捕捉中心向外发散,放射状结构
层级图Hierarchy组织结构、内容分级、系统拆解自上而下或自左至右的层级节点
关系图Relationship要素影响、依赖、互动关系图形间用连线表示关联
对比图Comparison方案或观点对照分析左右两栏或表格形式
时间线图Timeline事件发展、项目进度以时间为轴,标出关键时间点
矩阵图Matrix双维度分类、优先级定位X/Y 两个维度的坐标平面
自由布局Freeform零散内容、灵感记录无结构限制,自由放置

SVG 输出格式

文件命名规范

格式:excalidraw-[主题]-[时间戳].svg

示例:

  • excalidraw-系统架构-20260125171200.svg
  • excalidraw-用户注册流程-20260125171200.svg
  • excalidraw-商业模式-20260125171200.svg

SVG 结构模板

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" 
     viewBox="0 0 1200 800" 
     width="1200" 
     height="800"
     style="background-color: #ffffff;">
  
  <!-- Excalidraw 风格定义 -->
  <defs>
    <!-- 手绘风格滤镜 -->
    <filter id="roughness">
      <feTurbulence type="fractalNoise" baseFrequency="0.04" numOctaves="2" result="noise"/>
      <feDisplacementMap in="SourceGraphic" in2="noise" scale="1" xChannelSelector="R" yChannelSelector="G"/>
    </filter>
    
    <!-- 箭头标记 -->
    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#1e1e1e"/>
    </marker>
    
    <!-- 手写字体样式 -->
    <style>
      .excalidraw-text {
        font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
        font-size: 20px;
        fill: #1e1e1e;
      }
      .excalidraw-title {
        font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
        font-size: 28px;
        font-weight: bold;
        fill: #1e40af;
      }
      .excalidraw-subtitle {
        font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
        font-size: 20px;
        fill: #3b82f6;
      }
      .excalidraw-body {
        font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
        font-size: 16px;
        fill: #374151;
      }
    </style>
  </defs>
  
  <!-- 图表内容区域 -->
  <g id="content">
    <!-- 在此处添加图表元素 -->
  </g>
  
</svg>

设计规范

颜色方案

用途颜色代码说明
标题#1e40af深蓝色
副标题/连接线#3b82f6亮蓝色
正文文字#374151深灰色
强调/重点#f59e0b金色
成功/完成#10b981绿色
警告/注意#ef4444红色
边框/线条#1e1e1e黑色
背景填充#f3f4f6浅灰色
画布背景#ffffff白色

字体大小规范

  • 标题:24-28px
  • 副标题:18-20px
  • 正文/说明:14-16px
  • 标注/小字:12px

布局规范

  • 画布尺寸:1200 x 800 像素(可根据内容调整)
  • 边距:四周保留 40-60px 边距
  • 元素间距:相邻元素间保持 20-40px 间距
  • 对齐方式:使用网格对齐,保持视觉整洁

Excalidraw 手绘风格要点

  1. 线条:略带不规则,模拟手绘效果
  2. 圆角:矩形使用圆角(rx="8")
  3. 填充:使用半透明或斜线填充
  4. 阴影:轻微的投影效果增加层次感

SVG 元素模板

矩形框(节点)

<g class="node">
  <rect x="100" y="100" width="200" height="60" 
        rx="8" ry="8"
        fill="#f3f4f6" 
        stroke="#1e1e1e" 
        stroke-width="2"/>
  <text x="200" y="135" text-anchor="middle" class="excalidraw-text">节点文本</text>
</g>

椭圆(起止点)

<g class="terminal">
  <ellipse cx="200" cy="100" rx="80" ry="40"
           fill="#e0f2fe"
           stroke="#1e1e1e"
           stroke-width="2"/>
  <text x="200" y="105" text-anchor="middle" class="excalidraw-text">开始</text>
</g>

菱形(判断)

<g class="decision">
  <polygon points="200,50 280,100 200,150 120,100"
           fill="#fef3c7"
           stroke="#1e1e1e"
           stroke-width="2"/>
  <text x="200" y="105" text-anchor="middle" class="excalidraw-text">条件?</text>
</g>

箭头连接线

<line x1="300" y1="130" x2="400" y2="130"
      stroke="#1e1e1e"
      stroke-width="2"
      marker-end="url(#arrowhead)"/>

曲线箭头

<path d="M 100 100 Q 150 50 200 100"
      fill="none"
      stroke="#1e1e1e"
      stroke-width="2"
      marker-end="url(#arrowhead)"/>

虚线连接

<line x1="100" y1="100" x2="200" y2="100"
      stroke="#3b82f6"
      stroke-width="2"
      stroke-dasharray="8,4"/>

完整示例

示例 1:简单流程图

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" width="800" height="400" style="background-color: #ffffff;">
  <defs>
    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#1e1e1e"/>
    </marker>
    <style>
      .excalidraw-text { font-family: "Virgil", sans-serif; font-size: 16px; fill: #1e1e1e; }
      .excalidraw-title { font-family: "Virgil", sans-serif; font-size: 24px; fill: #1e40af; font-weight: bold; }
    </style>
  </defs>
  
  <!-- 标题 -->
  <text x="400" y="40" text-anchor="middle" class="excalidraw-title">用户注册流程</text>
  
  <!-- 开始 -->
  <ellipse cx="100" cy="200" rx="60" ry="30" fill="#e0f2fe" stroke="#1e1e1e" stroke-width="2"/>
  <text x="100" y="205" text-anchor="middle" class="excalidraw-text">开始</text>
  
  <!-- 箭头 -->
  <line x1="160" y1="200" x2="220" y2="200" stroke="#1e1e1e" stroke-width="2" marker-end="url(#arrowhead)"/>
  
  <!-- 步骤1 -->
  <rect x="230" y="170" width="120" height="60" rx="8" fill="#f3f4f6" stroke="#1e1e1e" stroke-width="2"/>
  <text x="290" y="205" text-anchor="middle" class="excalidraw-text">填写信息</text>
  
  <!-- 箭头 -->
  <line x1="350" y1="200" x2="410" y2="200" stroke="#1e1e1e" stroke-width="2" marker-end="url(#arrowhead)"/>
  
  <!-- 判断 -->
  <polygon points="490,140 560,200 490,260 420,200" fill="#fef3c7" stroke="#1e1e1e" stroke-width="2"/>
  <text x="490" y="205" text-anchor="middle" class="excalidraw-text">验证?</text>
  
  <!-- 箭头 -->
  <line x1="560" y1="200" x2="620" y2="200" stroke="#1e1e1e" stroke-width="2" marker-end="url(#arrowhead)"/>
  
  <!-- 结束 -->
  <ellipse cx="700" cy="200" rx="60" ry="30" fill="#d1fae5" stroke="#1e1e1e" stroke-width="2"/>
  <text x="700" y="205" text-anchor="middle" class="excalidraw-text">完成</text>
</svg>

示例 2:思维导图

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 600" width="1000" height="600" style="background-color: #ffffff;">
  <defs>
    <style>
      .center { font-family: "Virgil", sans-serif; font-size: 24px; fill: #1e40af; font-weight: bold; }
      .branch { font-family: "Virgil", sans-serif; font-size: 18px; fill: #3b82f6; }
      .leaf { font-family: "Virgil", sans-serif; font-size: 14px; fill: #374151; }
    </style>
  </defs>
  
  <!-- 中心节点 -->
  <ellipse cx="500" cy="300" rx="100" ry="50" fill="#dbeafe" stroke="#1e40af" stroke-width="3"/>
  <text x="500" y="305" text-anchor="middle" class="center">核心主题</text>
  
  <!-- 分支1 -->
  <line x1="600" y1="280" x2="750" y2="150" stroke="#3b82f6" stroke-width="2"/>
  <rect x="720" y="120" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
  <text x="780" y="150" text-anchor="middle" class="branch">分支一</text>
  
  <!-- 分支2 -->
  <line x1="600" y1="320" x2="750" y2="450" stroke="#3b82f6" stroke-width="2"/>
  <rect x="720" y="430" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
  <text x="780" y="460" text-anchor="middle" class="branch">分支二</text>
  
  <!-- 分支3 -->
  <line x1="400" y1="280" x2="250" y2="150" stroke="#3b82f6" stroke-width="2"/>
  <rect x="160" y="120" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
  <text x="220" y="150" text-anchor="middle" class="branch">分支三</text>
  
  <!-- 分支4 -->
  <line x1="400" y1="320" x2="250" y2="450" stroke="#3b82f6" stroke-width="2"/>
  <rect x="160" y="430" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
  <text x="220" y="460" text-anchor="middle" class="branch">分支四</text>
</svg>

实现步骤

步骤 1:生成 SVG 内容

根据用户需求分析内容,选择合适的图表类型,生成 SVG 代码。

步骤 2:调用上传脚本

使用提供的 upload_asset.py 脚本上传 SVG 文件:

import subprocess
import json

# 步骤 2.1:调用上传脚本
result = subprocess.run([
    'python', 'scripts/upload_asset.py', svg_content, topic
], capture_output=True, text=True)

# 步骤 2.2:解析返回结果
if result.returncode == 0:
    # 返回格式:ASSET_PATH|资源路径|消息
    _, asset_path, message = result.stdout.strip().split('|', 2)
    print(f"✅ {message}")
    print(f"📍 资源路径:{asset_path}")
else:
    # 返回格式:ERROR|错误消息
    error_msg = result.stdout.strip().split('|', 1)[1]
    print(f"❌ {error_msg}")

步骤 3:返回资源路径

# 返回思源笔记可用的 Markdown 图片引用
print(f"\n📖 在思源笔记中使用:")
print(f"![图表描述]({asset_path})")

输出确认模板

生成图表后,向用户报告:

✅ Excalidraw 图表已生成!

📍 保存位置:
assets/excalidraw-[主题]-[时间戳].svg

🎨 图表说明:
- 图表类型:[所选类型]
- 选择原因:[为什么选择这种类型]
- 包含元素:[主要内容概述]

📖 在思源笔记中使用:
在文档中插入以下 Markdown:
![图表描述](assets/excalidraw-[主题]-[时间戳].svg)

或者直接拖放 SVG 文件到编辑器中。

需要调整吗?比如修改布局、添加元素、调整配色?

注意事项

  1. 字体兼容性:SVG 使用 Virgil 字体模拟 Excalidraw 手写风格,如系统未安装会回退到 sans-serif
  2. 文件大小:保持 SVG 简洁,避免过于复杂的路径
  3. 编码格式:始终使用 UTF-8 编码
  4. 思源笔记兼容:生成的 SVG 可直接在思源笔记中显示
  5. WebDAV 安全:上传时使用 HTTPS(如可用)

依赖环境

运行 upload_asset.py 脚本需要以下环境:

Python 环境

  • Python 3.6 或更高版本
  • requests 库

安装依赖

# 安装 requests 库
pip install requests

配置文件

确保 siyuan.json 文件存在于项目根目录,包含以下字段:

{
    "local_path": "本地路径(优先使用)",
    "remote_path": {
        "webdav": true,
        "url": "WebDAV 服务器地址",
        "username": "用户名",
        "password": "密码",
        "assets_path": "资源目录路径"
    }
}

upload_asset.py 脚本说明

upload_asset.py 是专门为思源笔记 Excalidraw 资源上传设计的脚本,功能如下:

主要功能

  1. 自动选择保存方式:根据 siyuan.json 配置,优先使用本地保存,备选 WebDAV 上传
  2. 生成文件名:自动生成带时间戳的文件名,避免冲突
  3. 路径规范化:自动处理路径格式,确保与思源笔记兼容
  4. 错误处理:完善的异常处理和友好的错误提示

使用方法

命令行使用
python scripts/upload_asset.py <svg_content> <topic>

参数说明:

  • svg_content: SVG 内容(需用引号包裹)
  • topic: 图表主题

示例:

python scripts/upload_asset.py "<?xml version='1.0'...?>" "系统架构"
作为模块使用
from scripts.upload_asset import upload_asset

success, asset_path, message = upload_asset(svg_content, "系统架构")

if success:
    print(f"✅ {message}")
    print(f"📍 资源路径:{asset_path}")
else:
    print(f"❌ {message}")

返回格式

脚本的标准输出格式如下:

成功
ASSET_PATH|assets/excalidraw-系统架构-20260125171200.svg|已保存到本地: /path/to/siyuan/data/assets/excalidraw-系统架构-20260125171200.svg
失败
ERROR|上传失败: WebDAV 连接超时

路径选择逻辑

  1. 检查 local_path:如果 local_path 非空且有效,直接保存到本地

    • 保存路径:{local_path}/data/assets/{filename}
  2. 使用 WebDAV:如果 local_path 为空,检查 remote_path.webdav

    • 上传 URL:{remote_path.url}/{remote_path.assets_path}{filename}
    • 使用 Basic Authentication 进行认证
  3. 失败处理:如果两者都不可用,返回错误信息

配置补充说明

  • local_path 应指向思源工作目录根目录,而不是 assets 目录本身
  • 如果思源运行在 Docker 中,只有当脚本也运行在容器内时才应填写容器路径;否则请填写宿主机挂载路径
  • 不使用 WebDAV 时,只保留 local_path 即可;remote_path.webdav 可设为 false

WebDAV 上传详情

脚本使用 Python requests 库进行 WebDAV 上传:

  • HTTP 方法:PUT
  • 认证方式:Basic Authentication
  • Content-Type:image/svg+xml
  • 超时时间:30 秒

依赖要求

pip install requests

参考资源

思源笔记风味 Markdown (SFMarkdown)

概述

思源笔记风味 Markdown 是在标准 Markdown 基础上扩展的一套语法,支持块级引用、双向链接、属性查询、SQL 嵌入等思源笔记特有的功能。

维基链接

文档链接

[[文档名称]]              // 链接到同名文档
[[文档名称|显示别名]]    // 链接到文档并显示自定义名称

块级链接

((块ID))                 // 引用特定块

每个思源笔记块都有唯一的块 ID,格式类似 20250125000000-1a2b3c4d。

协议链接

siyuan://blocks/块ID     // 使用 siyuan:// 协议直接跳转到块

嵌入语法

思源笔记提供三种块引用方式:

引用块

右键点击内容块 → 复制 → 引用块

> ((20250125000000-1a2b3c4d))
  • 引用块会显示引用标记
  • 源内容更新时,所有引用处自动更新
  • 可以通过引用跳转到源内容

嵌入块

右键点击内容块 → 复制 → 嵌入块

嵌入块直接显示原始内容,保留格式和样式。

块超链接

允许跳转到笔记内的任意块,是比文档小一级的基本单位。

标注和高亮

引用块

> 这是一段引用文本

行内代码

这是一段 `行内代码` 示例

粗体和斜体

**粗体文本**
*斜体文本*
***粗斜体文本***

删除线

~~删除线文本~~

下划线

<u>下划线文本</u>

属性和元数据

思源笔记支持自定义属性功能。

添加属性

可以为任意块添加自定义属性,通过思源笔记界面设置或通过 API 添加。

SQL 查询嵌入

```sql
SELECT * FROM blocks WHERE type='d'

使用 SQL 查询来动态获取和显示块内容。

### 标签系统

```markdown
#标签名

支持文档树和块引重构的标签系统。

列表语法

无序列表

- 列表项 1
- 列表项 2
  - 子列表项 2.1
  - 子列表项 2.2

有序列表

1. 列表项 1
2. 列表项 2
   1. 子列表项 2.1
   2. 子列表项 2.2

任务列表

- [ ] 未完成任务
- [x] 已完成任务

代码块

\```python
def hello():
    print("Hello, SiYuan!")
\```

支持 200+ 编程语言的语法高亮。

表格

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| 数据 1 | 数据 2 | 数据 3 |
| 数据 4 | 数据 5 | 数据 6 |

数学公式

行内公式

$E = mc^2$

块级公式

$$
f(x) = \int_{-\infty}^{\infty} e^{-x^2} dx
$$

图片

基本语法

![图片描述](assets/image.png)

![图片描述](assets/image.png "图片标题")

思源笔记会自动将图片资源存储在 assets/ 目录下。

通过脚本插入图片

当需要在现有文档中插入图片时,使用 insert_image.py 脚本。

使用方法
# 插入本地 assets 图片
python scripts/insert_image.py "文档标题" "assets/image.svg" "图片说明"

# 插入 URL 图片
python scripts/insert_image.py "文档标题" "https://example.com/image.png" "图片说明" --url
参数说明
参数说明示例
doc_title目标文档标题(支持部分匹配)"我的笔记"
image_path图片路径assets/diagram.svg 或 https://example.com/image.png
caption图片说明文字(可选)"流程图"
--url标识图片路径为 URL(可选)--url
返回格式
成功: SUCCESS|块ID|消息
失败: ERROR|错误消息
示例
# 插入本地 SVG 流程图
python scripts/insert_image.py "流程图示例_WebDAV" "assets/excalidraw-flowchart-20260125.svg" "用户注册流程"

# 插入网络图片
python scripts/insert_image.py "技术文档" "https://example.com/architecture.png" "系统架构图" --url
注意事项
  • 文档标题支持模糊匹配,会查找包含指定标题的文档
  • 图片会插入到文档末尾
  • 插入后会自动添加时间戳注释
  • URL 图片不会下载到本地,直接使用原始链接

Excalidraw 图表

当需要创建图表、流程图、思维导图、架构图或可视化内容时,优先调用 siyuan-excalidraw skill 进行绘图。

工作流程

  1. 调用绘图 skill:使用 siyuan-excalidraw skill 生成图表
  2. 获取返回路径:skill 会将 SVG 保存到指定路径并返回资源路径
  3. 插入图片:使用 Markdown 图片语法插入图表

图片语法

![图表描述](返回的资源路径 "图表名称")

示例:

![用户注册流程](assets/excalidraw-用户注册流程-20260125171200.svg "用户注册流程")

注意事项

  • Excalidraw 图表默认保存为 SVG 格式
  • 资源路径可以是本地路径或 WebDAV 远程路径
  • siyuan-excalidraw skill 会自动处理路径选择和文件保存

链接

[链接文本](https://example.com)
[链接文本](path/to/file.md)

分割线

---

或

***

脚注

这是一段文本[^1]

[^1]: 这是脚注内容

思源笔记特有功能

块缩放聚焦

所有块都支持聚焦编辑,提高写作专注度。

面包屑导航

在上下文中轻松切换文档路径。

大纲列表

支持多层级列表折叠。

横向排版

支持块的横向排列,适合并排显示多个内容块。

完整示例

# 思源笔记示例文档

这是一篇关于思源笔记的示例文档。

## 维基链接示例

你可以链接到 [[技术笔记]] 或 [[项目计划|我的项目计划]]。

也可以引用特定的块:((20250125000000-1a2b3c4d))

## 嵌入和引用

> 这是一段引用块,可以 ((嵌入其他块))

## 列表示例

### 任务清单
- [ ] 学习思源笔记基本语法
- [x] 安装思源笔记
- [ ] 创建第一个笔记

### 项目清单
1. 需求分析
2. 系统设计
3. 开发实现
4. 测试上线

## 代码示例

```python
# 思源笔记 API 示例
import requests

def create_block(content):
    url = "http://localhost:6806/api/block/insertBlock"
    data = {
        "dataType": "markdown",
        "data": content,
        "previousID": ""
    }
    response = requests.post(url, json=data)
    return response.json()

表格示例

功能描述快捷键
双向链接文档间的相互链接[[
块引用引用任意内容块((
属性面板查看和编辑属性Alt + P

数学公式

质能方程:$E = mc^2$

高斯积分: $$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$

标签示例

#思源笔记 #知识管理 #双链

参考资源


## 注意事项

1. **块 ID**:思源笔记会自动为每个块分配唯一的 ID,格式为 `日期时间-随机字符`
2. **资源路径**:图片等资源默认存储在 `assets/` 目录下
3. **Markdown 兼容性**:思源笔记支持导出标准 Markdown,但双向链接等特性在标准 Markdown 中无法体现
4. **版本兼容**:思源笔记的 .sy.zip 格式包含所有资源和元数据,用于完整备份

## 参考

- [思源笔记官方文档](https://b3log.org/siyuan/)
- [思源笔记 GitHub 仓库](https://github.com/siyuan-note/siyuan)
- [思源笔记 API 文档](https://b3log.org/siyuan/zh-Hans/api/)

思源笔记技能指南

思源笔记是一款基于内容块的隐私优先知识管理工具。本技能提供了思源笔记的核心操作指南,涵盖内容块管理、模板开发、API交互和闪卡系统等功能模块。

核心概念

  • 内容块(Block):思源笔记的基本单位,每个块通过全局唯一 ID 标识。ID 由时间戳和 7 位随机字符组成,形如 202008250000-a1b2c3d。
  • 默认 API 端口:http://127.0.0.1:6806
  • 数据存储:SQLite 数据库,主表为 blocks

功能模块

模块描述参考文档
内容块操作内容块的创建、查询、修改和删除,以及块引用和嵌入块的使用block.md
模板开发模板片段的创建和使用,支持动态内容生成和变量替换template.md
API 交互思源笔记 API 的调用方法,包括 RESTful 接口和 WebSocketapi.md
闪卡系统间隔重复记忆系统的使用,卡片创建、复习和管理flashcard.md

快速参考

块类型代码(用于 SQL 查询)

代码类型
d文档块
h标题块
l列表块(包含有序/无序/任务)
i列表项块
b引述块
callout提示块
s超级块
p段落块
c代码块
m公式块
t表格块
av数据库块
query_embed嵌入块
子类型(subtype)
  • 列表块/列表项块:o(有序)、u(无序)、t(任务)
  • 标题块:h1~h6

常用语法

块引用
((块ID "锚文本"))
((块ID))
嵌入块
{{SELECT * FROM blocks WHERE content LIKE '%关键词%'}}
API 调用
POST http://127.0.0.1:6806/api/xxx
Content-Type: application/json

{
  "key": "value"
}

API 示例

获取块 Kramdown 源码
curl -X POST http://127.0.0.1:6806/api/block/getBlockKramdown \
  -H "Content-Type: application/json" \
  -d '{"id": "202008250000-a1b2c3d"}'
SQL 查询
curl -X POST http://127.0.0.1:6806/api/query/sql \
  -H "Content-Type: application/json" \
  -d '{"stmt": "SELECT * FROM blocks WHERE type=\"d\""}'

模板示例

注意:思源笔记模板使用 .action{action} 语法(而非 {{action}})来避免语法冲突。

简单日期模板
今天是 `.action{ now | date "2006-01-02" }`。

# `.action{ .title }`

文档ID:`.action{ .id }`
查询块模板
.action{ $blocks := queryBlocks "SELECT * FROM blocks WHERE content LIKE '?' LIMIT ?" "%关键词%" "5" }
.action{ range $blocks }
- ((`.action{ .id }`))
.action{ end }
带条件的模板
.action{ $before := (div (now.Sub (toDate "2006-01-02" "2020-02-19")).Hours 24) }
距离 2020-02-19 已经过去 `.action{ $before }` 天

经验教训与最佳实践

API 调用注意事项

1. API 调用与输出是分离的

问题:脚本在输出成功消息时崩溃,但 API 调用已经完成,导致重复创建文档。

原因:

# API 调用成功
result = self._request("/api/filetree/createDocWithMd", data)

# 输出崩溃(但这不影响前面的 API 调用)
print(f"✅ 文档创建成功!")  # Windows GBK 编码无法显示 emoji

解决方案:

  • API 调用成功后立即返回,将输出放在 try-catch 中
  • 或者将 API 调用和输出分离,确保 API 操作完成后再处理输出
  • 在重复操作前先检查是否已存在
2. 跨平台编码问题

问题:Windows 控制台默认使用 GBK 编码,无法显示某些字符(如 emoji)。

解决方案:

# 方法 1:使用 UTF-8 编码运行脚本
python -X utf8 script.py

# 方法 2:在代码中设置输出编码
import sys
import io
if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# 方法 3:避免使用特殊字符
print("[成功] 文档创建成功!")  # 而不是 ✅
3. 文档路径的正确使用

问题:删除文档时使用了错误的路径格式。

关键区别:

  • 系统路径:/20260125135312-pkzku0u.sy (用于 removeDoc)
  • 人类可读路径:/测试文档-20260125-135311 (用于显示)

正确用法:

# 错误 - 使用人类可读路径
api.removeDoc(notebook_id, '/测试文档-20260125-135311')

# 正确 - 使用系统路径(.sy 文件)
api.removeDoc(notebook_id, '/20260125135312-pkzku0u.sy')

# 获取系统路径的方法
query = f"SELECT path FROM blocks WHERE id = '{doc_id}'"
result = api.query_sql(query)
system_path = result[0]['path']  # /20260125135312-pkzku0u.sy
4. API 端点验证

问题:使用了不存在的 API 端点(如 /api/block/getBlockInfo),导致请求失败。

解决方案:

  • 在使用 API 前,参考官方文档验证端点是否存在
  • 常见错误端点:
    • ❌ /api/block/getBlockInfo → ✅ /api/block/getBlockKramdown
    • ❌ /api/filetree/getDoc → ✅ 使用 SQL 查询获取文档内容
    • ❌ /api/search/searchBlock → ✅ 使用 /api/query/sql 执行搜索
5. 避免重复操作

问题:由于脚本崩溃或重复运行,导致创建重复文档。

解决方案:

def ensure_doc_exists(notebook_id, path, markdown_content):
    """确保文档存在,不存在则创建"""
    # 先检查是否存在
    query = f"""
    SELECT id, content
    FROM blocks
    WHERE box = '{notebook_id}'
    AND hpath = '{path}'
    AND type = 'd'
    """
    result = api.query_sql(query)

    if result:
        doc_id = result[0]['id']
        print(f"文档已存在: {path} (ID: {doc_id})")
        return doc_id
    else:
        return api.create_doc(notebook_id, path, markdown_content)

Markdown 图片格式规范

重要:思源笔记中的图片必须使用标准 Markdown 格式 ![alt](url)

正确格式 ✅
![图片说明](https://example.com/image.jpg)
![封面图](https://mmbiz.qpic.cn/xxx/0?wx_fmt=jpeg)
![本地图片](assets/image.png)
错误格式 ❌
!图片 https://example.com/image.jpg
图片:https://example.com/image.jpg
<img src="https://example.com/image.jpg">
图片 URL 类型
类型示例说明
网络图片https://example.com/img.jpg直接使用 URL,无需下载
微信图片https://mmbiz.qpic.cn/...使用原始 URL
本地图片assets/image.png相对于文档的本地路径

注意:不要下载图片后上传,直接使用原始 URL 链接即可。

修复错误格式的图片

如果图片格式错误,使用以下方法修复:

# 1. 查询包含图片的块
query = f"SELECT id, content FROM blocks WHERE content LIKE '%http%' AND type='p'"
result = api.query_sql(query)

# 2. 找到格式错误的图片并修复
for block in result:
    content = block['content']
    if 'mmbiz.qpic.cn' in content or 'example.com' in content:
        # 提取URL(假设格式为 "文本 URL")
        url = content.split()[-1] if ' ' in content else content
        # 转换为标准格式
        new_content = f'![图片]({url})'
        # 更新块
        api.update_block(block['id'], new_content)

测试与调试

推荐的测试流程
  1. 先测试连接:列出笔记本验证 API 连接
  2. 使用测试笔记本:在专门的测试笔记本中操作
  3. 创建临时文档:使用带时间戳的文档名
  4. 验证结果:查询数据库确认操作成功
  5. 清理测试数据:测试完成后删除临时文档
调试技巧
# 1. 保存 API 响应到文件以便检查
with open('debug_response.json', 'w', encoding='utf-8') as f:
    json.dump(result, f, ensure_ascii=False, indent=2)

# 2. 使用 SQL 查询验证数据状态
query = "SELECT * FROM blocks WHERE id = 'xxx' ORDER BY created DESC LIMIT 5"

# 3. 记录操作日志
import logging
logging.basicConfig(filename='siyuan_api.log', level=logging.DEBUG)

Sponsors

Details

Marketplace
zhiluop/siyuan-skills
Category
Community