Menü
Query and edit a SiYuan knowledge base via its API.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
| name | siyuan |
| description | Query and edit a SiYuan knowledge base via its API. |
| version | 1.0.0 |
| author | FEUAZUR |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["SiYuan","Notes","Knowledge Base","PKM","API"],"related_skills":["obsidian","notion"],"homepage":"https://github.com/siyuan-note/siyuan"}} |
| prerequisites | {"env_vars":["SIYUAN_TOKEN"],"commands":["curl","jq"]} |
| required_environment_variables | [{"name":"SIYUAN_TOKEN","prompt":"SiYuan API token","help":"Settings > About in SiYuan desktop app"},{"name":"SIYUAN_URL","prompt":"SiYuan instance URL (default http://127.0.0.1:6806)","required_for":"remote instances"}] |
您可以通过 curl 调用 SiYuan 内核 API，对自托管知识库中的块和文档进行搜索、读取、创建、更新及删除操作。无需任何额外工具，只需拥有 curl 工具和 API 令牌即可。
${HERMES_HOME:-~/.hermes}/.env 文件中：
SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806
如果未进行设置，SIYUAN_URL 的默认值为 http://127.0.0.1:6806。
所有 SiYuan API 调用均采用 带 JSON 数据体的 POST 请求。每个请求都遵循以下格式：
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"param": "value"}'
响应内容为结构如下的 JSON 格式：
{"code": 0, "msg": "", "data": { ... }}
code: 0 表示操作成功。其他任何值均代表错误——请查看 msg 字段以获取详细信息。
ID 格式： SiYuan ID 的格式为 20210808180117-6v0mkxr（14位时间戳 + 7位字母数字组合）。
| 操作 | 接口地址 |
|---|---|
| 全文搜索 | /api/search/fullTextSearchBlock |
| SQL 查询 | /api/query/sql |
| 读取块内容 | /api/block/getBlockKramdown |
| 读取子块 | /api/block/getChildBlocks |
| 获取路径 | /api/filetree/getHPathByID |
| 获取属性 | /api/attr/getBlockAttrs |
| 列出笔记本 | /api/notebook/lsNotebooks |
| 列出文档 | /api/filetree/listDocsByPath |
| 创建笔记本 | /api/notebook/createNotebook |
| 创建文档 | /api/filetree/createDocWithMd |
| 追加块内容 | /api/block/appendBlock |
| 更新块内容 | /api/block/updateBlock |
| 重命名文档 | /api/filetree/renameDocByID |
| 设置属性 | /api/attr/setBlockAttrs |
| 删除块内容 | /api/block/deleteBlock |
| 删除文档 | /api/filetree/removeDocByID |
| 导出为 Markdown 格式 | /api/export/exportMdContent |
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'
直接查询区块数据库。仅 SELECT 语句是安全的。
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'
常用字段包括：id、parent_id、root_id、box（笔记本编号）、path、content、type、subtype、created、updated。
以 Kramdown（类似 Markdown 的格式）返回块内容。
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{}' | jq '.data.notebooks[] | {id, name, closed}'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"notebook": "NOTEBOOK_ID",
"path": "/Meeting Notes/2026-03-22",
"markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
}' | jq '.data'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "My New Notebook"}' | jq '.data.notebook.id'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"parentID": "DOCUMENT_OR_BLOCK_ID",
"data": "New paragraph added at the end.",
"dataType": "markdown"
}' | jq '.data'
此外，还提供以下接口：/api/block/prependBlock（参数相同，用于在块的开头插入内容）以及 /api/block/insertBlock（使用 previousID 而非 parentID，用于在指定块之后插入内容）。
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "BLOCK_ID",
"data": "Updated content here.",
"dataType": "markdown"
}' | jq '.data'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "DOCUMENT_ID", "title": "New Title"}'
自定义属性必须以 custom- 作为前缀：
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "BLOCK_ID",
"attrs": {
"custom-status": "reviewed",
"custom-priority": "high"
}
}'
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "BLOCK_ID"}'
要删除整个文档：请使用 /api/filetree/removeDocByID，并传入参数 {"id": "DOC_ID"}。
要删除笔记本：请使用 /api/notebook/removeNotebook，并传入参数 {"notebook": "NOTEBOOK_ID"}。
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'
SQL 查询中常见的 type 值：
| 类型 | 描述 |
|---|---|
d | 文档（根块） |
p | 段落 |
h | 标题 |
l | 列表 |
i | 列表项 |
c | 代码块 |
m | 数学公式块 |
t | 表格 |
b | 引用块 |
s | 超级块 |
html | HTML 块 |
YYYYMMDDHHmmss-xxxxxxx 的格式，其他格式的 ID 均需被拒绝。data 之前，务必先检查响应中的 code != 0。LIMIT 限制数据量，并通过 jq 工具提取所需内容。lsNotebooks 获取其 ID。如果您更倾向于使用原生集成而非 curl，可以安装 SiYuan MCP 服务器：
# In ~/.hermes/config.yaml under mcp_servers:
mcp_servers:
siyuan:
command: npx
args: ["-y", "@porkll/siyuan-mcp"]
env:
SIYUAN_TOKEN: "your_token"
SIYUAN_URL: "http://127.0.0.1:6806"
Create, read, edit Excel .xlsx spreadsheets and CSVs.
Create, read, edit Excel .xlsx spreadsheets and CSVs.
Curate LLM training data: dedupe, filter, PII redaction.
Scrape sites with stealth browsing and Cloudflare bypass.
Clean training loops with built-in distributed support.
Roleplay a hostile user to find and triage UX pain points.