Siyuan Skill

思源筆記（SiYuan）— 核心知識與最佳實踐

本 Skill 是思源筆記的知識庫，教 AI 怎麼「用好」思源的特色功能。 不包含個人歸檔規則（那是 note-flow 的職責）。

1) 核心概念：內容塊（Content Block）

思源的唯一核心概念是內容塊。所有內容都是塊，文件本身也是塊。

塊的類型

關鍵原則

• 文件也是塊 — 每個 .sy 文件有一個 block ID，就是文件 ID
• 塊可互轉 — 標題可轉段落、列表項可轉段落等
• 塊有屬性 — 每個塊都有 id、updated、type，可附加自訂屬性
• 塊級粒度 — 引用、嵌入、標籤都在塊級別操作

2) 引用與雙向連結

思源最強大的功能。建立引用後，自動產生正向連結和反向連結。

引用內容塊語法

((<block_id> '動態錨文字'))    ← 單引號：錨文字隨原文變化（推薦）
((<block_id> "靜態錨文字"))    ← 雙引號：錨文字固定不變

連結方向

關係圖

引用會在關係圖中可視化，可以看到塊之間的網絡關係。

• 全域關係圖：所有筆記的關聯網絡
• 局部關係圖：以某個塊為中心的關聯

最佳實踐

API 操作

建立引用不需要特殊 API — 直接在 markdown 內容中寫 ((<id> '文字')) 即可，思源渲染時自動解析。

3) 標籤系統

標籤用於標記內容塊，所有打過標籤的塊會在標籤面板（Alt+4 / ⌃4）中列出。

語法

#標籤名#                  ← 基本標籤（前後都要 #）
#分類/子分類#              ← 層級標籤（用 / 分隔）
#工具/LibreNMS#           ← 範例：工具類層級標籤

常見錯誤

❌ `#Docker#`             → 行內代碼，不會變成標籤
❌ #Docker                → 缺少結尾 #
❌ # Docker#              → # 後有空格，變成 Markdown 標題
✅ #Docker#               → 正確
✅ 這是內容 #Task#        → 正確，標籤可以跟在文字後面
✅ #工具/Docker#          → 正確，層級標籤

最佳實踐

API 操作

# 查詢所有標籤
POST /api/search/getTags  {}

# SQL 查詢帶特定標籤的塊
SELECT * FROM blocks WHERE tag LIKE '%標籤名%'

4) 屬性系統

每個塊都可以附加屬性（key-value），用於分類、過濾、模板化。

內建屬性

自訂屬性

以 custom- 開頭的屬性可自由定義：

{: custom-priority="high" custom-status="in-progress" }

API 操作

# 設定屬性
POST /api/attr/setBlockAttrs
{ "id": "<block_id>", "attrs": { "custom-priority": "high" } }

# 讀取屬性
POST /api/attr/getBlockAttrs
{ "id": "<block_id>" }

# SQL 查詢有特定屬性的塊
SELECT * FROM attributes WHERE name = 'custom-priority' AND value = 'high'

5) 嵌入塊（Query Embed）

用 SQL 動態查詢並嵌入其他塊的內容，保持即時更新。

語法

在思源中用 {{ }} 包裹 SQL：

{{ SELECT * FROM blocks WHERE tag LIKE '%會議%' AND created >= '20260201' ORDER BY created DESC LIMIT 10 }}

常用場景

6) SQL 查詢技巧

思源內建 SQLite 資料庫，可透過 API 查詢。

主要資料表

blocks 表重要欄位

常用查詢

-- 搜尋文件標題
SELECT id, content, hpath FROM blocks WHERE type='d' AND content LIKE '%關鍵字%'

-- 搜尋含特定標籤的塊
SELECT * FROM blocks WHERE tag LIKE '%工具/LibreNMS%'

-- 查某文件的所有子塊
SELECT * FROM blocks WHERE root_id = '<doc_id>' ORDER BY sort

-- 查引用某塊的所有來源
SELECT * FROM refs WHERE def_block_id = '<block_id>'

-- 查某筆記本下最近更新的文件
SELECT id, content, updated FROM blocks 
WHERE type='d' AND box='<notebook_id>' 
ORDER BY updated DESC LIMIT 10

-- 查某文件下的標題結構
SELECT id, content, type, subType FROM blocks 
WHERE root_id = '<doc_id>' AND type = 'h'

API 呼叫

POST /api/query/sql
{ "stmt": "SELECT id, content FROM blocks WHERE type='d' AND content LIKE '%關鍵字%' LIMIT 10" }

⚠️ 注意：SQL 查詢有索引延遲，文件操作後幾秒到幾十秒才更新。需要即時性的用 listDocsByPath。

7) REST API 常用端點

文件操作

塊操作

插入到正確位置（insertBlock 定位指南）

核心概念：heading 下的所有內容塊，parent_id = heading_id

不管是普通文件，還是 {{{col}}} / {{{row}}} 三欄 superblock 裡的 heading，content（list/paragraph）都是以 heading 本身為父節點，不是 heading 的父容器。

標準查法：找 section 最後一個 list block

-- Step 1：找目標 heading
SELECT id FROM blocks
WHERE root_id = '<doc_id>' AND type = 'h' AND content LIKE '%關鍵字%'
LIMIT 1

-- Step 2：找該 heading 下最後一個 list block
SELECT id FROM blocks
WHERE parent_id = '<heading_id>' AND type = 'l'
ORDER BY sort DESC LIMIT 1

插入決策：

POST /api/block/insertBlock
{ "dataType": "markdown", "data": "- 新內容", "previousID": "<上方決定的 ID>" }

⚠️ 不要用 appendBlock——它追加到整個文件末尾，不是 heading 下方。

{{{col}}} / {{{row}}} 三欄結構說明：

{{{col                    ← col superblock（root_id 的直接子塊）
  {{{row                  ← row superblock（col 的子塊）
    ### ⏰ 重點工作        ← heading（row 的子塊）
    ---                   ← divider（row 的子塊）
    - [ ] 待辦項目        ← list（heading 的子塊！不是 row 的子塊）
  }}}
}}}

→ 要插入到某一欄，找該欄的 heading_id，再用上方查法找 previousID。

搜尋與查詢

屬性

匯出

請求格式

所有 API 都是 POST + JSON，需要 Authorization header：

POST http://<host>:6806/api/<endpoint>
Authorization: Token <your_token>
Content-Type: application/json

8) 踩坑筆記

9) 筆記設計原則

結構原則

關聯建立原則

索引頁設計規範

標準區塊順序：

1. 引用塊提示（> 💼 筆記本名稱）
2. 🚀 快速入口（表格化）
3. 🔥 近期活躍（如適用）
4. 📋 速查表（如適用）
5. 📂 結構說明（目錄樹）

母文件模板：

> 💼 筆記本名稱 / 分類

## 🚀 快速入口

| 項目 | 說明 |
|---|---|
| ((<id> '項目A')) | 說明 |
| ((<id> '項目B')) | 說明 |

---

## 📂 結構

- ((<id> '子分類1'))
- ((<id> '子分類2'))

清理原則