cli-anything-joplin

cli-anything-joplin 是做什麼的？

使用此技能，可以透過一個由真實 joplin 終端二進位檔支援的狀態化 harness，自動化 Joplin 的筆記本、筆記、待辦事項、標籤、附件、搜尋、同步及匯入/匯出等工作流程。

需求

• Python 3.10+
• 可在環境中作為 joplin 使用的 Joplin 終端二進位檔
• 可選：傳遞 --profile 以指定特定的 Joplin 設定檔

安裝

cd joplin/agent-harness
pip install -e .

使用方式

# REPL 模式（預設）
cli-anything-joplin

# 機器可讀的一次性指令
cli-anything-joplin --json notebooks list

# 狀態化專案
cli-anything-joplin project new --name demo -o ./demo.joplin-harness.json
cli-anything-joplin --project ./demo.joplin-harness.json notes create "Meeting note"

# 僅測試（不自動儲存）
cli-anything-joplin --json --dry-run --project ./demo.joplin-harness.json notes create temp

JSON 輸出合約

啟用 --json 時，指令會回傳：

• ok：布林值
• command：穩定的指令識別碼，例如 notes.list、todos.toggle
• data：指令的酬載資料
• error：成功時為 null，失敗時為 { type, message }

指令群組

• project：new、open、save、info、json、status
• notebooks：list、create、use、remove
• notes：list、create、set、get、remove、copy、move、rename
• todos：list、create、toggle、clear、done、undone
• tags：list、add、remove、notetags、tagnotes
• search：run
• sync：run（--target、--upgrade、--use-lock）
• interop：import、export
• config：get、set、list、export、import-file
• attach：add
• status：show、restore
• backend：version、dump、keymap、geoloc、export-sync-status
• server：status、start、stop
• e2ee：status、target-status、decrypt、decrypt-file
• session：status、undo、redo、history

代理程式指南

• 建議使用 --json 以取得可解析的輸出。
• 執行多步驟工作流程時請使用 --project，這樣歷程記錄會保持持久化。
• 單次執行的變異指令會自動儲存專案，除非設定了 --dry-run。
• REPL 模式不會自動儲存；請明確執行 project save。
• 某些 Joplin CLI 建置版本會將 search 限制在 GUI 模式；如果看到 "only available in GUI mode"，請將搜尋視為盡力而為。
• Joplin 3.6.x 在 npm 全域佈局中可能會有損壞的 version 指令；harness 會回退到已安裝的套件中繼資料來取得 backend version， 依序探測符號連結解析後的二進位目錄、Windows 風格的兄弟目錄 node_modules/joplin、Unix 風格的父目錄 lib/node_modules/joplin， 以及最終的 npm root -g。
• 指令結果中的後端 stdout/stderr 是逐字輸出的；請不要假設 筆記內容或匯出檔案中已移除警告訊息。
• 失敗時，請使用與成功時相同的 command 欄位來解析 error （例如 config.import_file、e2ee.decrypt_file）。多字元的子指令會使用 一個點號分隔群組與子指令。

測試工作流程

# 快速回饋迴圈
python -m pytest -q cli_anything/joplin/tests/test_core.py
python -m pytest -q cli_anything/joplin/tests/test_full_e2e.py::TestCLISubprocess

# 真實後端（joplin 必須在 PATH 中）
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendCommands
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendWorkflows
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendIntegration

# 完整測試套件
python -m pytest -v --tb=no cli_anything/joplin/tests

# 驗證已安裝的主控台腳本進入點
CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest -v -s cli_anything/joplin/tests/test_full_e2e.py

目前驗證基準（Windows + Joplin CLI 3.6.2）：

• python -m pytest -q cli_anything/joplin/tests/test_core.py -> 107 passed
• python -m pytest -q cli_anything/joplin/tests -> 134 passed, 1 skipped