Siyuan

SiYuan Note API，用於通過 curl 在自託管知識庫中搜索、讀取、創建和管理塊和文檔。

技能元數據


來源	可選 — 使用 `hermes skills install official/productivity/siyuan` 安裝
路徑	`optional-skills/productivity/siyuan`
版本	`1.0.0`
作者	FEUAZUR
許可證	MIT
標籤	`SiYuan`, `Notes`, `Knowledge Base`, `PKM`, `API`
相關技能	`obsidian`, `notion`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。

SiYuan Note API

通過 curl 使用 SiYuan 內核 API，在自託管知識庫中搜索、讀取、創建、更新和刪除塊和文檔。無需額外工具——只需 curl 和 API 令牌。

前提條件

安裝並運行 SiYuan（桌面版或 Docker）
獲取你的 API 令牌：設置 > 關於 > API 令牌
將其存儲在 ~/.hermes/.env 中：
```
SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806
```
如果未設置，SIYUAN_URL 默認為 http://127.0.0.1:6806。

API 基礎

所有 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]'

搜索（SQL）

直接查詢塊數據庫。僅 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（筆記本 ID）, 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"}。

將文檔導出為 Markdown

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 塊

陷阱

所有端點均為 POST —— 即使是隻讀操作。請勿使用 GET。
SQL 安全：僅使用 SELECT 查詢。INSERT/UPDATE/DELETE/DROP 具有危險性，絕不應發送。
ID 驗證：ID 需匹配模式 YYYYMMDDHHmmss-xxxxxxx。拒絕任何其他格式。
錯誤響應：在處理 data 之前，務必檢查響應中的 code != 0。
大型文檔：塊內容和導出結果可能非常大。在 SQL 中使用 LIMIT，並通過管道傳遞給 jq 以僅提取所需內容。
筆記本 ID：在使用特定筆記本時，請先通過 lsNotebooks 獲取其 ID。

替代方案：MCP 服務器

如果您傾向於原生集成而非使用 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"

技能元數據​

參考：完整 SKILL.md​

SiYuan Note API

前提條件​

API 基礎​

快速參考​

常見操作​

搜索（全文）​

搜索（SQL）​

讀取塊內容​

讀取子塊​

獲取人類可讀路徑​

獲取塊屬性​

列出筆記本​

列出筆記本中的文檔​

創建文檔​

創建筆記本​

向文檔追加塊​

更新塊內容​

重命名文檔​

設置塊屬性​

刪除塊​

將文檔導出為 Markdown​

塊類型​

陷阱​

替代方案：MCP 服務器​