
siyuan
Claude Skills for 思源笔记
- version
- 1.0.0
- GitHub stars
- 18
Install
/plugin install siyuan@siyuan-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add zhiluop/siyuan-skills.
Contents
Discovered from sourceSkills 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技术详解
❌ /标题:包含@#$特殊字符
参考文档
- API 参考:references/api.md - 思源 API 详细文档
- 图片处理:references/image-processing.md - 图片处理最佳实践
- 工作流程:references/workflows.md - 完整导入流程和实现细节
配置文件
推荐在仓库根目录放置 .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 文件并自动保存到思源笔记资源目录。
工作流程
- 分析内容 - 识别概念、关系、层次结构
- 选择图表类型 - 根据内容特性选择最佳可视化形式
- 生成 SVG - 创建 Excalidraw 风格的 SVG 图表
- 保存文件 - 自动保存到思源笔记资源目录
- 返回路径 - 提供可直接在思源笔记中使用的资源路径
配置文件读取
必须首先读取 siyuan.json 配置文件,获取保存路径信息:
{
"local_path": "本地路径(优先使用)",
"remote_path": {
"webdav": true,
"url": "WebDAV 服务器地址",
"username": "用户名",
"password": "密码",
"assets_path": "资源目录路径"
}
}
路径选择规则
- 优先使用
local_path:如果local_path非空,直接保存到该路径下的data/assets/目录 - 备选使用
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.svgexcalidraw-用户注册流程-20260125171200.svgexcalidraw-商业模式-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 手绘风格要点
- 线条:略带不规则,模拟手绘效果
- 圆角:矩形使用圆角(rx="8")
- 填充:使用半透明或斜线填充
- 阴影:轻微的投影效果增加层次感
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"")
输出确认模板
生成图表后,向用户报告:
✅ Excalidraw 图表已生成!
📍 保存位置:
assets/excalidraw-[主题]-[时间戳].svg
🎨 图表说明:
- 图表类型:[所选类型]
- 选择原因:[为什么选择这种类型]
- 包含元素:[主要内容概述]
📖 在思源笔记中使用:
在文档中插入以下 Markdown:

或者直接拖放 SVG 文件到编辑器中。
需要调整吗?比如修改布局、添加元素、调整配色?
注意事项
- 字体兼容性:SVG 使用 Virgil 字体模拟 Excalidraw 手写风格,如系统未安装会回退到 sans-serif
- 文件大小:保持 SVG 简洁,避免过于复杂的路径
- 编码格式:始终使用 UTF-8 编码
- 思源笔记兼容:生成的 SVG 可直接在思源笔记中显示
- 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 资源上传设计的脚本,功能如下:
主要功能
- 自动选择保存方式:根据
siyuan.json配置,优先使用本地保存,备选 WebDAV 上传 - 生成文件名:自动生成带时间戳的文件名,避免冲突
- 路径规范化:自动处理路径格式,确保与思源笔记兼容
- 错误处理:完善的异常处理和友好的错误提示
使用方法
命令行使用
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 连接超时
路径选择逻辑
-
检查
local_path:如果local_path非空且有效,直接保存到本地- 保存路径:
{local_path}/data/assets/{filename}
- 保存路径:
-
使用 WebDAV:如果
local_path为空,检查remote_path.webdav- 上传 URL:
{remote_path.url}/{remote_path.assets_path}{filename} - 使用 Basic Authentication 进行认证
- 上传 URL:
-
失败处理:如果两者都不可用,返回错误信息
配置补充说明
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/ 目录下。
通过脚本插入图片
当需要在现有文档中插入图片时,使用 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 进行绘图。
工作流程
- 调用绘图 skill:使用
siyuan-excalidrawskill 生成图表 - 获取返回路径:skill 会将 SVG 保存到指定路径并返回资源路径
- 插入图片:使用 Markdown 图片语法插入图表
图片语法

示例:

注意事项
- 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} $$
标签示例
#思源笔记 #知识管理 #双链
参考资源
- 思源笔记官网:https://b3log.org/siyuan/
- 思源笔记 GitHub:https://github.com/siyuan-note/siyuan
## 注意事项
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 接口和 WebSocket | api.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 格式 
正确格式 ✅



错误格式 ❌
!图片 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''
# 更新块
api.update_block(block['id'], new_content)
测试与调试
推荐的测试流程
- 先测试连接:列出笔记本验证 API 连接
- 使用测试笔记本:在专门的测试笔记本中操作
- 创建临时文档:使用带时间戳的文档名
- 验证结果:查询数据库确认操作成功
- 清理测试数据:测试完成后删除临时文档
调试技巧
# 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