From siyuan
Provides SiYuan Notes core knowledge: content blocks, references, embeds, API calls, templates, flashcards. Use for basic concepts, API principles, block syntax, template development, general operations.
npx claudepluginhub zhiluop/siyuan-skills --plugin siyuanThis skill uses the workspace's default tool permissions.
思源笔记是一款基于内容块的隐私优先知识管理工具。本技能提供了思源笔记的核心操作指南,涵盖内容块管理、模板开发、API交互和闪卡系统等功能模块。
Edits SiYuan-flavored Markdown (SFMD) with wiki links, block quotes/embeds, attributes, SQL queries. Use for SiYuan .md files, double-chain syntax, image insertion via Python script.
Queries SiYuan notes for content via Node.js: search keywords/titles/tags, recent blocks, tasks, documents, backlinks. Use for note retrieval requests like 'query my xxx'.
Generates Obsidian Flavored Markdown with wikilinks, callouts, embeds, frontmatter properties, tags, and block references for creating/editing notes in Obsidian vaults.
Share bugs, ideas, or general feedback.
思源笔记是一款基于内容块的隐私优先知识管理工具。本技能提供了思源笔记的核心操作指南,涵盖内容块管理、模板开发、API交互和闪卡系统等功能模块。
202008250000-a1b2c3d。http://127.0.0.1:6806blocks| 模块 | 描述 | 参考文档 |
|---|---|---|
| 内容块操作 | 内容块的创建、查询、修改和删除,以及块引用和嵌入块的使用 | block.md |
| 模板开发 | 模板片段的创建和使用,支持动态内容生成和变量替换 | template.md |
| API 交互 | 思源笔记 API 的调用方法,包括 RESTful 接口和 WebSocket | api.md |
| 闪卡系统 | 间隔重复记忆系统的使用,卡片创建、复习和管理 | flashcard.md |
| 代码 | 类型 |
|---|---|
d | 文档块 |
h | 标题块 |
l | 列表块(包含有序/无序/任务) |
i | 列表项块 |
b | 引述块 |
callout | 提示块 |
s | 超级块 |
p | 段落块 |
c | 代码块 |
m | 公式块 |
t | 表格块 |
av | 数据库块 |
query_embed | 嵌入块 |
o(有序)、u(无序)、t(任务)h1~h6((块ID "锚文本"))
((块ID))
{{SELECT * FROM blocks WHERE content LIKE '%关键词%'}}
POST http://127.0.0.1:6806/api/xxx
Content-Type: application/json
{
"key": "value"
}
curl -X POST http://127.0.0.1:6806/api/block/getBlockKramdown \
-H "Content-Type: application/json" \
-d '{"id": "202008250000-a1b2c3d"}'
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 调用已经完成,导致重复创建文档。
原因:
# API 调用成功
result = self._request("/api/filetree/createDocWithMd", data)
# 输出崩溃(但这不影响前面的 API 调用)
print(f"✅ 文档创建成功!") # Windows GBK 编码无法显示 emoji
解决方案:
问题: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("[成功] 文档创建成功!") # 而不是 ✅
问题:删除文档时使用了错误的路径格式。
关键区别:
/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
问题:使用了不存在的 API 端点(如 /api/block/getBlockInfo),导致请求失败。
解决方案:
/api/block/getBlockInfo → ✅ /api/block/getBlockKramdown/api/filetree/getDoc → ✅ 使用 SQL 查询获取文档内容/api/search/searchBlock → ✅ 使用 /api/query/sql 执行搜索问题:由于脚本崩溃或重复运行,导致创建重复文档。
解决方案:
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 格式 



!图片 https://example.com/image.jpg
图片:https://example.com/image.jpg
<img src="https://example.com/image.jpg">
| 类型 | 示例 | 说明 |
|---|---|---|
| 网络图片 | 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)
# 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)