- name
- siyuan-note
- description
- 思源笔记（SiYuan Note）本地 API 操作助手。用于读写笔记本、文档、块、搜索、模板、SQL 查询等本地笔记操作。触发场景：用户提到"思源笔记"、"SiYuan"、"帮我创建文档"、"搜索笔记"、"查询数据库"等。
思源笔记（SiYuan Note）API Skill
基础规范
- API 基础 URL：
http://127.0.0.1:6806 - 认证：请求头
Authorization: Token <你的API Token>（在 思源笔记 → 设置 → 关于 中查看） - 方法：全部 POST，Content-Type:
application/json - 返回格式：
{ "code": 0, "msg": "", "data": ... }，code非 0 表示异常
注意：代码执行必须包含 Token，调用示例会标注需要 Token 的端点。
常用操作速查
列出所有笔记本
curl -X POST http://127.0.0.1:6806/api/notebook/lsNotebooks \
-H "Authorization: Token <TOKEN>"创建文档（通过 Markdown）
curl -X POST http://127.0.0.1:6806/api/filetree/createDocWithMd \
-H "Authorization: Token <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"notebook": "<笔记本ID>", "path": "/我的文档", "markdown": "# 标题\
\
内容"}'执行 SQL 查询
curl -X POST http://127.0.0.1:6806/api/query/sql \
-H "Authorization: Token <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"stmt": "SELECT * FROM blocks WHERE content LIKE '\''%关键词%'\'' LIMIT 10"}'插入块到文档
curl -X POST http://127.0.0.1:6806/api/block/appendBlock \
-H "Authorization: Token <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"data": "新段落内容", "dataType": "markdown", "parentID": "<父块ID>"}'搜索文档
curl -X POST http://127.0.0.1:6806/api/query/sql \
-H "Authorization: Token <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"stmt": "SELECT id, hpath, title FROM blocks WHERE type = '\''d'\'' AND title LIKE '\''%搜索词%'\'' LIMIT 20"}'核心工作流程
工作流程 1：创建新文档
- 调用
lsNotebooks列出笔记本 → 拿到notebook ID - 调用
createDocWithMd创建文档 → 拿到文档ID - （可选）调用
setBlockAttrs设置文档属性
工作流程 2：搜索并读取笔记
- 调用
getNotebookConf确认笔记本存在 - 调用 SQL
SELECT * FROM blocks WHERE content LIKE '%关键词%' LIMIT N全文搜索 - 对文档 ID 调用
getBlockKramdown或exportMdContent获取内容
工作流程 3：向文档追加内容
- 获取目标文档的根块 ID（通常等于文档 ID 本身）
- 调用
appendBlock在文档末尾追加新块 - 或调用
prependBlock在文档开头插入
工作流程 4：使用模板
- 调用
renderSprig渲染 Sprig 模板表达式（如{{now | date "2006-01-02"}}） - 结合
createDocWithMd创建带有日期标题的文档
SQL 查询要点
关键表：
blocks— 所有块（段落、标题、代码块等）
- id / hpath / title / content / type / subtype / markdown / created / updated
blocks表中type = 'd'为文档，标题块type = 'h'，段落type = 'p'
常用查询：
-- 搜索包含关键词的块
SELECT id, hpath, content FROM blocks
WHERE content LIKE '%关键词%' LIMIT 20;
-- 列出某笔记本下所有文档
SELECT id, title, hpath FROM blocks
WHERE notebook = '<笔记本ID>' AND type = 'd';
-- 搜索文档标题
SELECT id, hpath, title FROM blocks
WHERE type = 'd' AND title LIKE '%标题%' LIMIT 10;重要限制
- SQL 接口在发布模式（Publication）下需要开启文档读写权限，否则会被禁止
- 资源文件上传使用
multipart/form-data，不是 JSON - API 全部为本地调用，思源笔记必须运行在本地
完整 API 参考
见 references/api.md（包含所有端点的完整说明）