SiYuan 筆記 CLI 技能
總覽
SiYuan 筆記提供一個 CLI (siyuan) 以管理工作區、筆記本、文件、區塊等。
二進位檔必須存在於 PATH 環境變數中（可用 siyuan --version 驗證）。
CLI 版本： v3.8.9。以下指令反映此版本。
注意： 若在
PATH找不到siyuan，可嘗試使用替代指令名稱SiYuan-Kernel。
工作流程
對於每位使用者的要求，請遵循以下順序：
1. 探索可用的工作區
執行 siyuan workspace list（不需要 -w 旗標）以取得已註冊工作區的清單。
若使用者未指定工作區，請列出清單並要求他們選擇。
siyuan workspace list
siyuan workspace info # 顯示目前的預設工作區
2. 鎖定工作區路徑
在使用者選定工作區（或直接提供路徑）後，儲存該工作區路徑，並將其用作後續所有指令（workspace 子指令除外）的 -w 參數。
3. 執行要求的指令
構建並執行目標指令，並在指令後加上 -w <工作區路徑>（workspace 子指令除外）。
在需要解析結果時，使用 -f json 以利程式化輸出。
若指令失敗，請檢查：(1) 工作區路徑是否有效，(2) 是否已提供所需的旗標（如 --id），(3) 已安裝的 CLI 版本中是否存在該子指令。
常見模式
取得區塊/文件 ID
許多指令需要區塊或文件 ID（--id）。可透過以下方式取得 ID：
siyuan sql "SELECT id, content FROM blocks WHERE type='d'" -w <路徑> -f json— 列出文件 IDsiyuan document list --notebook <id> -w <路徑> -f json— 列出筆記本中的文件siyuan search <關鍵字> -w <路徑> -f json— 搜尋並從結果中取得 ID
破壞性操作 — 驗證、預覽、確認
將刪除/清理（remove、delete、clean、clear、purge）、復原（history rollback、repo checkout、repo file rollback）以及替換/覆蓋操作（例如 import data、以 file write 覆蓋既有檔案、或帶有 --overwrite 的範本指令）視為破壞性操作。
- 使用唯讀指令驗證工作區、目標 ID/路徑以及受影響的範圍。請檢查子文件、相關資料或既有內容是否也將受到影響；請勿僅憑指令名稱推斷範圍。
- 先以
--dry-run執行預期的指令，並檢查其輸出：siyuan notebook remove --id <id> --dry-run -w <路徑>--dry-run重新嘗試。 - 若使用者授權或受影響範圍不明確，或預覽顯示出超出要求的效果，請總結工作區、目標及後果，並在繼續前要求明確確認。請勿猜測目標或暗中擴大範圍。
- 一旦範圍經驗證並獲得授權，請在執行破壞性操作前於目標工作區中建立復原快照：
siyuan repo create --memo "Before <破壞性操作的簡短說明>" -w <路徑> - 僅當驗證後的效果與使用者要求或明確確認相符時，才能在不使用
--dry-run的狀態下執行，且必須保持相同的工作區、目標與選項。若其中任何一項變更，請重複驗證、預覽與操作前快照。
JSON 輸出解析
使用 -f json 以利程式化解析。JSON 結構取決於子指令：workspace list 回傳陣列，而 workspace info 回傳物件。在使用 jq 或類似工具進行過濾前，請檢查指令的輸出結構；請勿假設每個結果都是陣列。
工作區鎖定錯誤
若指令以代碼 24 退出並報告 lock workspace [...] failed，表示該工作區已被另一個 SiYuan 程序（例如桌面應用程式）使用中。請關閉另一個程序，或改為操作其他工作區。
寫入操作後建立快照
在對話期間，請分別追蹤每個工作區實際的資料變更，包括因指令失敗而留下的部分變更。快照建立本身不計為需要另一個快照的新資料變更。
在完成任務或結束工作階段前，請總結變更，並在每個有修改的工作區中建立資料快照，使用該工作區的路徑及其自身的變更摘要：
siyuan repo create --memo "<此工作區變更的簡短摘要>" -w <已修改工作區路徑>
--memo 應簡潔描述建立/修改/刪除了什麼（例如 "在 /Projects 建立 3 份文件，更新 README，移除過時筆記"）。請為每個工作區驗證成功與否；若快照失敗，請回報受影響的工作區與錯誤，而非聲稱已儲存。跳過沒有資料變更的工作區；唯讀工作階段不需要任何快照。
這些快照保留了變更後的狀態。它們不能取代破壞性操作前所需的復原快照。
領域概念
理解這些 SiYuan 特有概念對於正確使用 CLI 至關重要：
區塊（Block）— 基本單位
所有東西都是一個具有唯一 ID 的區塊。文件是一個文件區塊（類型 d，即 NodeDocument），作為根節點；內容區塊（標題、段落、清單、程式碼、表格）在其下形成樹狀結構。
容器區塊（可容納子區塊，可用作 --parent）：文件、引用、清單、清單項目、超級區塊、提示框、分頁容器、分頁項目。
葉區塊（不可容納子區塊，不可用作 --parent）：標題、段落、程式碼區塊、數學區塊、表格、HTML 區塊、水平線、影片、音訊、小工具、iframe、屬性檢視、區塊查詢嵌入。
tabs/tabItem是為分頁容器引入的區塊類型；它們在search -t類型過濾清單中顯示為tabs和tabItem。
標題層級 — 使用 --previous，而非 --parent
標題（h1-h6）是葉區塊。在使用者介面中「位於」標題下方的區塊，在 AST 中是該標題的後續兄弟節點，而非其子節點。若要將區塊插入到標題下方，請將標題的 ID（或目前位於其下最後一個區塊的 ID）作為 --previous 傳入，不要作為 --parent：
siyuan block insert --parent <文件ID> --previous <標題ID> --data "text" -w <路徑>
巢狀清單 — list-item 不能直接包含 list-item
清單項目（list-item）不能直接包含另一個清單項目。若要巢狀清單，請建立一個清單（NodeList）作為外部清單項目的子節點，然後將清單項目加入到該內部清單中。清單項目的父節點必須永遠是清單。
hPath — 人類可讀路徑
hPath 是文件樹中顯示的基於標題的路徑（例如 /Diary/2024/June）。重新命名文件會更改其 hPath，但不會更改其 ID。
document list和document move：--hpath接受基於標題的路徑；--path接受基於內部 ID 的路徑（預設值：/）。這些旗標不可互換。document create：--path指定父文件路徑（預設值：/）；此指令不提供--hpath。請檢查已安裝版本中siyuan document create --help的說明，而不是假設其路徑旗標與list/move相同。
block update — 取代，非附加
block update 用新的 Markdown取代一個區塊的完整內容。它不會建立或附加新區塊。若要同時修改既有內容並新增內容，請先呼叫 block update，然後分別呼叫 block append/prepend/insert。傳入 --lock-type 可在新內容的解析區塊類型與既有區塊類型不同時拒絕更新。
document move 與 block move 的區別
document move 將整個文件（及其所有子文件）移動到目標筆記本和父路徑，使用 --hpath 指定基於標題的路徑，或使用 --path 指定內部路徑。block move 將單個內容區塊重新定位到新的父區塊下。
日常筆記 — 何時使用 dailynote 與 document
日常筆記是位於筆記本日常筆記儲存路徑的特殊文件。對於日記/日誌/日常筆記的要求，請使用 dailynote create（而非 document create）來開啟今天的筆記，然後使用 dailynote append/prepend 來新增內容。
筆記本圖示與文件圖示的區別
attr set 變更文件區塊的圖示 — 它無法設定筆記本的圖示。對於筆記本，請使用 notebook set-icon（特定表情符號）或 notebook random-icon（隨機表情符號）。
全域旗標
這些旗標可用於每個子指令：
| 旗標 | 說明 |
|---|---|
-w, --workspace <路徑> | 工作區路徑（除 workspace 外所有指令都需要；對 serve 為可選，預設使用預設工作區）。 |
-f, --format <table|json> | 輸出格式（預設值：table） |
-v, --log-level <字串> | 日誌等級：off、trace、debug、info、warn、error、fatal（預設值由 conf.json 中的 system.logLevel 決定） |
--dry-run | 驗證並列印將發生的操作，但不實際進行變更 |
--home-dir <路徑> | 使用者設定檔的基礎目錄（預設值為系統使用者家目錄） |
注意： 除
-w（或--workspace）外，所有旗標皆為可選。若未指定可選旗標，CLI 將使用預設值。
子指令參考
每個指令的詳細旗標與範例，請載入
references/commands.md。
| 指令 | 子指令 |
|---|---|
siyuan workspace | list、info |
siyuan notebook | list、create、open、close、rename、remove、set-icon、random-icon |
siyuan document | list、get/info、create、rename、move、duplicate、remove、search |
siyuan block | get、children、insert、append、prepend、update、delete、move、stat、dom、kramdown、breadcrumb、batch-get、batch-kramdown |
siyuan sql "<陳述句>" | (直接) |
siyuan search <查詢> | (直接，含旗標) |
siyuan export | md、html、docx、sy、md-zip、preview、data |
siyuan import | md、sy、data |
siyuan dailynote | create、append、prepend |
siyuan asset | unused、clean、stat、upload |
siyuan attr | get、set、batch-get |
siyuan bookmark | list、labels、rename、remove |
siyuan tag | list、rename、remove |
siyuan history | list、get、search、rollback、clear |
siyuan ref | backlinks、mentions、refresh |
siyuan repo | list、create、diff、checkout、tag、untag、purge、search、file |
siyuan sync | pull、push、status |
siyuan database | search、get、keys、render、unused、clean、key、item |
siyuan file | list、read、write、copy、rename、delete、find、grep、stat |
siyuan inbox | list、get、convert |
siyuan outline | get |
siyuan template | search、get、create、save-as、render、remove |
siyuan system | current-time |
siyuan serve | (直接，含旗標) |
siyuan completion | bash、fish、powershell、zsh |
注意：
serve接受所有全域旗標及其自身旗標（--accessAuthCode、--attach-ui、--enable-pprof、--lang、--mode、--port、--readonly、--ssl、--safe-mode、--wd）。它不需要-w；完整的旗標清單位於references/commands.md。