cli-anything-siyuan

cli-anything-siyuan 是做什麼的？

用於 SiYuan（思源筆記）的命令列工具， 一個注重本地優先的知識管理與筆記應用程式。

此 CLI 透過 HTTP API (http://127.0.0.1:6806) 連接到正在執行的 SiYuan 核心， 並提供對記事本、文件、區塊、搜尋以及匯出的結構化存取。

先決條件

• SiYuan 必須正在執行（設定 → 關於會顯示 API token）
• Python 3.10+
• 安裝：pip install cli-anything-siyuan 或從 agent-harness/ 目錄執行 pip install -e .

命令群組

notebook — 記事本管理

子命令	說明
list	列出所有記事本
create <name>	建立新記事本
rename <id> <name>	重新命名記事本
remove <id>	刪除記事本
open <id>	開啟記事本

doc — 文件管理

子命令	說明
create <notebook> <path> [--md "content"]	建立文件
list <notebook> [path]	列出文件
tree <notebook> [--path / --depth]	顯示文件樹
get <id>	依 ID 取得文件路徑
rename <id> <title>	重新命名文件
remove <id>	刪除文件

block — 區塊操作

子命令	說明
insert <data> [--previous / --parent]	插入區塊
update <id> <data>	更新區塊
delete <id>	刪除區塊
get <id>	取得區塊的 kramdown 原始碼
children <id>	取得子區塊

其他命令

命令	說明
sql <stmt>	對區塊資料庫執行 SQL
search <query>	跨區塊進行全文搜尋
export md <doc-id>	將文件匯出為 Markdown
tag list	列出所有標籤
version	顯示 SiYuan 核心版本
status	顯示連線與工作階段狀態
repl	啟動互動式 REPL

代理指引

• 請一律使用 --json 以取得機器可讀的輸出
• 進階搜尋：使用 sql "SELECT * FROM blocks WHERE content LIKE '%keyword%'" 進行 SQL 層級的存取
• 文件 ID 格式如 20210817205410-2kvfpfn（基於時間戳）
• API token 可在 SiYuan 設定 → 關於中找到
• 連線預設值：http://127.0.0.1:6806

範例

# 列出記事本（JSON 格式）
cli-anything-siyuan --json notebook list

# 以 Markdown 建立文件（--md 標記，注意 shell 跳脫）
cli-anything-siyuan doc create nb1 /projects/new --md "## Title\n\nContent"

# 建立文件 — 透過標準輸入傳入 Markdown（避免 shell 跳脫問題）
# PowerShell here-string（逐字，無需跳脫）：
@'
## Title
Content with `backticks` and (parentheses) and "quotes"
'@ | cli-anything-siyuan doc create nb1 /projects/new --md -

# Bash heredoc：
# cat <<'EOF' | cli-anything-siyuan doc create nb1 /projects/new --md -
# ## Title
# Content with `backticks` and (parentheses)
# EOF

# SQL 搜尋
cli-anything-siyuan sql "SELECT id, content FROM blocks WHERE content LIKE '%meeting%' LIMIT 5"

# 匯出
cli-anything-siyuan export md doc123

# 進入 REPL
cli-anything-siyuan

錯誤處理

• 連線錯誤：請確認 SiYuan 正在執行且 API token 正確
• API 錯誤：回傳 {"code": N, "msg": "..."} — 請檢查 msg 欄位
• 認證錯誤：請確認 ~/.siyuan-cli.json 或 SIYUAN_TOKEN 環境變數中的 token