cli-anything-siyuan用命令行與 Agent 原生管理思源筆記SiYuan知識庫【免費下載鏈接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/項目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本文是基于cli-anything-siyuan的一份完整實戰(zhàn)指南該項目為思源筆記SiYuan提供了一套終端 CLI harness通過其 HTTP API 直接操作筆記本notebook、文檔document、內(nèi)容塊block并支持全文搜索、SQL 查詢與 Markdown 導(dǎo)出。讀完本文你將掌握從安裝配置、連接認(rèn)證、一次性命令到交互式 REPL 的完整用法理解底層客戶端如何與思源內(nèi)核通信并能在腳本與 AI Agent 工作流中直接調(diào)用這套 CLI。項目定位與工作原理思源筆記是一款本地優(yōu)先local-first、注重隱私的知識管理工具其內(nèi)核Go 編寫默認(rèn)在http://127.0.0.1:6806提供 HTTP API使用Authorization: Token xxx進(jìn)行認(rèn)證。由于思源沒有獨立的 headless CLI 模式cli-anything-siyuan的架構(gòu)策略是連接到一個正在運(yùn)行的思源實例通過其 HTTP API 提供對筆記本、文檔、內(nèi)容塊、搜索與導(dǎo)出的結(jié)構(gòu)化訪問。這一思路可以概括為三層調(diào)用鏈終端命令 (cli-anything-siyuan) → core/client.py 中的 SiYuanClientHTTP POST /api/... → 運(yùn)行中的思源內(nèi)核 (Gin HTTP Server, 端口 6806)從源碼結(jié)構(gòu)看整個包分為四個部分siyuan_cli.py基于 Click 的命令行入口定義全部命令組與 REPLcore/client.pyHTTP API 客戶端負(fù)責(zé)連接、認(rèn)證與請求/響應(yīng)封裝core/session.pyREPL 會話狀態(tài)管理與持久化utils/siyuan_backend.py自動發(fā)現(xiàn)思源數(shù)據(jù)目錄、探測連接并嘗試從配置文件讀取 API token。前置條件使用前需要滿足兩個條件思源筆記SiYuan正在運(yùn)行版本 3.x且 API 服務(wù)已啟用Python 3.10環(huán)境。包本身對 Python 3.10/3.11/3.12 提供官方支持見 setup.py 中的 classifiers運(yùn)行時僅依賴click8.0與requests2.28兩個核心庫。安裝在倉庫的agent-harness目錄下使用 pip 安裝cd agent-harness pip install -e .若需要 REPL 交互模式推薦安裝帶replextra 的版本這會額外引入prompt_toolkit3.0pip install -e .[repl]從 setup.py 可以看到安裝完成后會注冊cli-anything-siyuan這個控制臺命令入口指向siyuan_cli:cli。如果你需要跑測試還可以安裝testextra引入pytest7.0。連接配置文件、環(huán)境變量與 CLI 參數(shù)CLI 默認(rèn)連接http://127.0.0.1:6806思源默認(rèn) API 端口就是 6806。連接信息可以通過三種方式提供優(yōu)先級由高到低為CLI 參數(shù) → 環(huán)境變量 → 配置文件 → 默認(rèn)值見 client.py 中l(wèi)oad_config的實現(xiàn)。方式一配置文件在用戶主目錄創(chuàng)建~/.siyuan-cli.json{ host: 127.0.0.1, port: 6806, token: your-api-token-here }文件采用 UTF-8含 BOM讀取即使是從 Windows 導(dǎo)出的帶 BOM 文件也能正確解析。方式二環(huán)境變量export SIYUAN_HOST127.0.0.1 export SIYUAN_PORT6806 export SIYUAN_TOKENyour-token注意從源碼看環(huán)境變量的優(yōu)先級高于配置文件——load_config會先讀配置文件作為基礎(chǔ)值再用SIYUAN_HOST、SIYUAN_PORT、SIYUAN_TOKEN覆蓋client.py。這非常適合在 CI 或多環(huán)境場景中臨時覆蓋連接目標(biāo)。方式三CLI 參數(shù)cli-anything-siyuan --host 192.168.1.10 --port 6806 --token abc version全局參數(shù)--host、--port、--token以及--config path可以在啟動時覆蓋一切配置--json則切換為機(jī)器可讀的 JSON 輸出。獲取 API Token在思源界面中打開設(shè)置 → 關(guān)于 → API Token即可查看。除此之外utils/siyuan_backend.py中的get_api_token_from_conf()還提供了自動發(fā)現(xiàn)能力它會嘗試從思源的配置文件Windows 下為%USERPROFILE%\SiYuan\conf\conf.jsonLinux/macOS 下為~/.config/siyuan/conf/conf.json中讀取api.token字段方便免手動復(fù)制 tokensiyuan_backend.py。配置優(yōu)先級測試驗證單元測試 test_core.py 對三種配置來源分別做了驗證默認(rèn)值應(yīng)為127.0.0.1:6806環(huán)境變量會被load_config讀取顯式傳入配置文件路徑時以文件內(nèi)容為準(zhǔn)。這從測試層面確認(rèn)了配置加載的完整邏輯。底層客戶端連接、認(rèn)證與錯誤處理理解SiYuanClient有助于排查問題。核心實現(xiàn)在 core/client.py所有 API 調(diào)用統(tǒng)一走_(dá)post(endpoint, data)POST 到http://{host}:{port}{endpoint}超時 30 秒若配置了 token請求頭會帶上Authorization: Token {token}Content-Type 為application/json響應(yīng)處理遵循思源 API 約定HTTP 狀態(tài)非 200 或 JSON 體中code ! 0都會被包裝成SiYuanClientError拋出ping()通過調(diào)用/api/system/version探測內(nèi)核是否可達(dá)失敗時返回False而非拋異常。CLI 層通過_CatchErrors這個自定義 Click Group 將SiYuanClientError統(tǒng)一轉(zhuǎn)換為Error: ...輸出并退出碼 1siyuan_cli.py因此任何 API 錯誤都不會以堆棧的形式污染終端。無參數(shù)直接運(yùn)行cli-anything-siyuan時CLI 會先ping()探測連接若無法連接會給出明確的提示信息并引導(dǎo)你使用--host --port --token或環(huán)境變量進(jìn)行配置siyuan_cli.py。一次性命令快速操作知識庫常用示例# 列出所有筆記本 cli-anything-siyuan notebook list # 列出筆記本JSON 輸出適合腳本/Agent 解析 cli-anything-siyuan --json notebook list # 查看思源內(nèi)核版本 cli-anything-siyuan version # 執(zhí)行 SQL 查詢直接訪問塊數(shù)據(jù)庫 cli-anything-siyuan sql SELECT * FROM blocks LIMIT 5 # 全文搜索內(nèi)容塊 cli-anything-siyuan search keyword # 將文檔導(dǎo)出為 Markdown cli-anything-siyuan export md doc-id # 查看連接與會話狀態(tài) cli-anything-siyuan status # 通過 stdin 向指定父塊插入多行內(nèi)容 cat note.md | cli-anything-siyuan block insert --parent block-id # 通過 stdin 更新塊內(nèi)容 echo new content | cli-anything-siyuan block update block-id完整命令組一覽以下是 README 中給出的全部命令按功能分組命令說明notebook list列出所有筆記本notebook create name創(chuàng)建筆記本notebook rename id name重命名筆記本notebook remove id刪除筆記本notebook open id打開筆記本doc create notebook-id path創(chuàng)建文檔doc list notebook-id [path]列出文檔doc tree notebook-id展示文檔樹doc get id按 ID 獲取文檔路徑doc rename id title重命名文檔doc remove id刪除文檔block insert data插入內(nèi)容塊傳-或省略則從 stdin 讀取block update id data更新內(nèi)容塊傳-或省略則從 stdin 讀取block delete id刪除內(nèi)容塊block get id獲取內(nèi)容塊的 kramdown 源碼block children id獲取子內(nèi)容塊sql stmt執(zhí)行 SQL 查詢search query全文搜索export md doc-id導(dǎo)出為 Markdowntag list列出所有標(biāo)簽version顯示思源版本status顯示連接狀態(tài)命令背后的 API 映射從 core/client.py 的源碼可以看清每條命令對應(yīng)的思源內(nèi)核 APInotebook 組lsNotebooks、createNotebook、renameNotebook、removeNotebook、openNotebookclient.pydoc 組createDocWithMd、listDocsByPath、listDocTree、getHPathByID、renameDocByID、removeDocByIDclient.pyblock 組insertBlock、prependBlock、appendBlock、updateBlock、deleteBlock、getBlockKramdown、getChildBlocksclient.py查詢與導(dǎo)出query/sql、search/fullTextSearchBlock、export/exportMdContent、tag/getTag、system/versionclient.py。tag list還特別在請求中攜帶了ignoreMaxListHint: true確保在標(biāo)簽數(shù)量巨大的工作區(qū)也能返回完整列表而不會被思源的Conf.FileTree.MaxListCount截斷。block 插入的錨點要求block insert必須且只能提供以下三種錨點之一siyuan_cli.py否則會直接報UsageError--parent id作為指定塊的子塊插入--previous id插到指定塊之前--next id插到指定塊之后。同時可通過--data-type指定內(nèi)容類型默認(rèn)markdown也支持dom。中文與多行內(nèi)容stdin 管道的最佳實踐當(dāng)內(nèi)容包含反引號、引號、括號等特殊字符或需要寫入多行文本時直接作為命令行參數(shù)容易觸發(fā) shell 轉(zhuǎn)義問題。為此block insert、block update與doc create --md都支持從 stdin 讀取內(nèi)容——數(shù)據(jù)參數(shù)傳-或直接省略。這里有一個值得注意的實現(xiàn)細(xì)節(jié)_read_stdin()讀取的是sys.stdin.buffer的原始字節(jié)然后用utf-8-sig解碼siyuan_cli.py。這樣設(shè)計的原因是Windows 上的 PowerShell 按控制臺代碼頁如中文系統(tǒng)的 GBK傳輸文本會先破壞 CJK 字符直接讀原始字節(jié)再解碼是最穩(wěn)妥的方式。CLI 入口還會強(qiáng)制將 stdout/stderr 重配置為 UTF-8保證中文輸出在 Windows 終端下不亂碼siyuan_cli.py。實戰(zhàn)示例——PowerShell here-string完全無需轉(zhuǎn)義 ## 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) EOFREPL 交互模式不帶任何參數(shù)直接運(yùn)行cli-anything-siyuan即進(jìn)入交互式 REPLcli-anything-siyuan進(jìn)入后會看到版本橫幅與提示符◆ cli-anything · Siyuan v1.0.0 ◇ Install: npx skills add HKUDS/CLI-Anything --skill cli-anything-siyuan -g -y ◇ Global skill: ~/.agents/skills/cli-anything-siyuan/SKILL.md Type help for commands, quit to exit siyuan ? notebook list siyuan ? doc tree notebook-id siyuan ? search meeting notes siyuan ? help siyuan ? quitREPL 內(nèi)可用help查看命令幫助quit、exit或q退出status顯示當(dāng)前連接與上下文狀態(tài)。REPL 的解析邏輯位于 siyuan_cli.py輸入先經(jīng)shlex.split分詞再按notebook、doc、block、sql、search、export分發(fā)到對應(yīng)處理函數(shù)命令中同樣支持--json開關(guān)切換 JSON 輸出。會話狀態(tài)持久化REPL 不是無狀態(tài)的core/session.py中的SessionManager會把當(dāng)前上下文保存到~/.cli-anything-siyuan/session.jsonsession.py包括current_notebook_id/current_notebook_name當(dāng)前打開的筆記本current_doc_id/current_doc_path當(dāng)前操作的文檔connected連接標(biāo)記history命令歷史。例如在 REPL 里執(zhí)行notebook create后會話會自動記錄新筆記本并打開它siyuan_cli.py后續(xù)命令可以直接基于該上下文工作。狀態(tài)采用臟標(biāo)記 退出時 flush的寫入策略避免每次操作都寫盤。對應(yīng)測試test_save_load_roundtrip驗證了保存/加載的完整往返test_core.py。為 Agent 與腳本準(zhǔn)備JSON 輸出與 SQL 檢索cli-anything-siyuan的設(shè)計目標(biāo)之一就是 Agent 原生agent-native所有命令都支持--json輸出方便程序化解析。針對 Agent 使用場景官方 skill 文檔skills/SKILL.md給出了幾條關(guān)鍵建議機(jī)器可讀輸出始終使用--json獲得結(jié)構(gòu)化結(jié)果SQL 級檢索需要精確查詢時使用sql SELECT * FROM blocks WHERE content LIKE %keyword%直接訪問思源的塊數(shù)據(jù)庫SQLiteID 格式文檔/塊 ID 是時間戳式的形如20210817205410-2kvfpfn連接默認(rèn)值http://127.0.0.1:6806。一個典型的 Agent 檢索流程可以是# 1. 定位目標(biāo)筆記本 cli-anything-siyuan --json notebook list # 2. 查看文檔樹 cli-anything-siyuan --json doc tree notebook-id # 3. 用 SQL 精準(zhǔn)檢索內(nèi)容 cli-anything-siyuan --json sql SELECT id, content FROM blocks WHERE content LIKE %meeting% LIMIT 5 # 4. 導(dǎo)出為 Markdown 交給下游處理 cli-anything-siyuan export md doc-id錯誤排查指南癥狀可能原因與處理Error: Cannot connect to SiYuan. Is it running?思源未啟動或 host/port 配置錯誤用--host --port --token或環(huán)境變量修正API error: {msg}內(nèi)核返回的code ! 0按msg字段定位具體問題認(rèn)證失敗檢查~/.siyuan-cli.json或SIYUAN_TOKEN中的 token 是否正確可在思源設(shè)置 → 關(guān)于 → API Token重新獲取中文亂碼確認(rèn)按本文方式使用 stdin 管道utf-8-sig解碼且 CLI 已強(qiáng)制 UTF-8 輸出運(yùn)行測試項目自帶單元測試與端到端測試便于驗證安裝是否正常# 單元測試無需外部依賴基于 mock cd agent-harness pip install -e .[test] python -m pytest cli_anything/siyuan/tests/test_core.py -v # E2E 測試需要正在運(yùn)行的思源實例 python -m pytest cli_anything/siyuan/tests/test_full_e2e.py -v -s單元測試覆蓋了三塊核心邏輯配置加載默認(rèn)值/環(huán)境變量/文件、客戶端 API 調(diào)用ping、list_notebooks、create_doc_with_md的請求體、query_sql結(jié)果解析、會話狀態(tài)管理test_core.py。create_doc_with_md的測試還驗證了請求體必須通過json關(guān)鍵字傳遞notebook、path、markdown三個字段與思源 API 契約保持一致。許可證cli-anything-siyuan采用AGPL-3.0許可證與思源筆記SiYuan保持一致。【免費下載鏈接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/項目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考