SiYuan Note CLI スキル
概要
SiYuan Note は、ワークスペース、ノートブック、ドキュメント、ブロックなどを管理する 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— ドキュメント ID 一覧を取得siyuan 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 "<破壊的操作の簡潔な説明>の前" -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 の使用に不可欠です。
ブロック — 基本単位
すべては一意の ID を持つブロックです。ドキュメントはルートとなるドキュメントブロック（タイプ d、すなわち NodeDocument）であり、その下に見出し、段落、リスト、コード、テーブルなどのコンテンツブロックがツリーを形成します。
コンテナブロック（子ブロックを保持でき、--parent として有効）：ドキュメント、引用、リスト、リスト項目、スーパーブロック、コールアウト、タブ、タブ項目。
リーフブロック（子を保持できず、--parent として無効）：見出し、段落、コードブロック、数式ブロック、テーブル、HTML ブロック、水平線、動画、音声、ウィジェット、iframe、属性ビュー、ブロッククエリ埋め込み。
tabs/tab-itemはタブコンテナ用に導入されたブロックタイプです。search -tのタイプフィルターリストではtabsとtabItemとして表示されます。
見出し階層 — --previous を使用し、--parent は使用しない
見出し（h1～h6）はリーフブロックです。UI 上で見出しの「下」にあるように見えるブロックは、AST 上では見出しの次の兄弟であり、子ではありません。見出しの下にブロックを挿入するには、見出しの ID（または現在その下にある最後のブロックの ID）を --parent ではなく --previous に指定します。
siyuan block insert --parent <docID> --previous <headingID> --data "テキスト" -w <パス>
ネストされたリスト — 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 は1つのブロックの全内容を新しい Markdown で置き換えます。新しいブロックは作成も追加もしません。既存の内容を変更し、かつ新しい内容も追加するには、最初に block update を呼び出し、その後 block append/prepend/insert を別々に呼び出します。新しい内容のパースされたブロックタイプが既存のブロックのタイプと異なる場合に更新を拒否するには、--lock-type を指定します。
document move と block move の違い
document move は、ドキュメント全体（およびそのすべての子）をターゲットのノートブックと親パスに移動します。タイトルベースのパスには --hpath、内部パスには --path を使用します。block move は、単一のコンテンツブロックを新しい親ブロックの下に再配置します。
Daily Note — dailynote と document の使い分け
Daily Note は、ノートブックの日次ノート保存パスにある特別なドキュメントです。日記/ジャーナル/日次ノートのリクエストには、document create ではなく dailynote 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を参照してください。