cli-anything-calibre 是做什麼的？
一個狀態化的 CLI 工具，用於 Calibre 電子書管理。包裝了真實的 Calibre 工具（calibredb、ebook-convert、ebook-meta），為 AI 代理和腳本提供乾淨、結構化的介面來處理圖書館操作、元數據編輯和格式轉換。
安裝
此 CLI 是作為 cli-anything-calibre 套件的一部分安裝的：
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness
先決條件：
- Python 3.10+
- 系統上必須安裝 Calibre (硬性依賴)
# Debian/Ubuntu
sudo apt-get install calibre
# macOS
brew install --cask calibre
# 確認工具在 PATH 中
which calibredb
which ebook-convert
which ebook-meta
使用方法
基本命令
# 顯示幫助
cli-anything-calibre --help
# 啟動互動式 REPL 模式
cli-anything-calibre
# 連接到 Calibre 圖書館
cli-anything-calibre library connect ~/Calibre\ Library
# 使用 JSON 輸出執行（供代理使用）
cli-anything-calibre --json books list
REPL 模式
當不帶子命令呼叫時，CLI 會進入互動式 REPL 會話：
cli-anything-calibre
# 使用 Tab 補全和歷史記錄互動地輸入命令
# 使用 'help' 檢視可用命令
# 使用 'quit' 或 'exit' 離開
命令群組
Library
圖書館管理命令。
| 命令 | 說明 |
|---|---|
connect <path> | 設定活躍圖書館路徑 |
info | 顯示圖書館統計資訊（書籍數量、格式、資料庫大小） |
check | 使用 calibredb check_library 驗證圖書館完整性 |
Books
書籍操作（包裝 calibredb）。
| 命令 | 說明 |
|---|---|
list | 列出書籍，支援過濾和排序 |
search <query> | 使用 Calibre 查詢語言搜尋 |
add <files> | 新增書籍檔案到圖書館 |
remove <ids> | 移除書籍（移至回收筒或永久刪除） |
show <id> | 顯示書籍的完整元數據 |
export <ids> | 將書籍匯出到目錄 |
export-chapters <id> | 將每章導出為單獨的 PDF（需要 EPUB 格式） |
Meta
元數據編輯（包裝 calibredb set_metadata）。
| 命令 | 說明 |
|---|---|
get <id> [field] | 取得元數據（全部或特定欄位） |
set <id> <field> <value> | 設定元數據欄位 |
embed <ids> | 將元數據嵌入到書籍檔案中 |
Formats
格式管理（包裝 calibredb + ebook-convert）。
| 命令 | 說明 |
|---|---|
list <id> | 列出書籍的可用格式 |
add <id> <file> | 為書籍新增格式 |
remove <id> <fmt> | 從書籍移除格式 |
convert <id> <input_fmt> <output_fmt> | 轉換書籍格式 |
Custom
自訂欄位（包裝 calibredb）。
| 命令 | 說明 |
|---|---|
list | 列出所有自訂欄位 |
add <label> <name> <type> | 建立自訂欄位 |
remove <label> | 刪除自訂欄位 |
set <id> <label> <value> | 設定自訂欄位值 |
Catalog
目錄生成。
| 命令 | 說明 |
|---|---|
catalog <output> | 生成圖書館目錄（EPUB、CSV 或 OPDS） |
範例
連接並列出書籍
連接到你的 Calibre 圖書館並列出書籍。
cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list
# 或使用 JSON 輸出
cli-anything-calibre --json books list --search "author:asimov"
搜尋和過濾
使用 Calibre 查詢語言搜尋書籍。
cli-anything-calibre books search "title:Foundation"
cli-anything-calibre books search "author:asimov and tags:scifi"
cli-anything-calibre books search "rating:>3"
元數據編輯
設定書籍的元數據欄位。
cli-anything-calibre meta set 42 title "新標題"
cli-anything-calibre meta set 42 series "Foundation"
cli-anything-calibre meta set 42 series_index 1
cli-anything-calibre meta set 42 tags "scifi,classic"
cli-anything-calibre meta set 42 rating 5
格式轉換
在電子書格式之間轉換。
cli-anything-calibre formats convert 42 EPUB MOBI
cli-anything-calibre formats convert 42 EPUB PDF --output /tmp/book.pdf
將章節匯出為 PDF
將 EPUB 的每章節匯出為單獨的 PDF 檔案。
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs --chapters 1-5
Calibre 查詢語言
與 books search 和 books list --search 一起使用：
author:asimov # 作者包含 "asimov"
title:"Foundation" # 書名片語
tags:fiction # 標籤匹配
rating:>3 # 評分大於 3
series:"Foundation" # 系列匹配
pubdate:[2020-01-01,2021-12-31] # 日期範圍
identifiers:isbn:1234567890 # 特定識別碼
has:cover # 有封面圖片
not:tags:fiction # 否定
author:asimov and tags:scifi # 布林 AND
關鍵元數據欄位
| 欄位 | 類型 | 說明 |
|---|---|---|
title | text | 書名 |
authors | text | 作者姓名（以 & 分隔） |
tags | text | 逗號分隔的標籤 |
series | text | 系列名稱 |
series_index | float | 系列中的位置 |
rating | float | 評分 1-5 |
publisher | text | 出版社名稱 |
pubdate | datetime | 出版日期 |
comments | text | 描述/評論 |
languages | text | 語言代碼 |
identifiers | text | ISBN、ASIN 等 (type:value) |
支援的格式
輸入： EPUB、MOBI、AZW、AZW3、PDF、HTML、DOCX、ODT、FB2、TXT、RTF、LIT 等
輸出（轉換）： EPUB、MOBI、AZW3、PDF、HTML、DOCX、TXT 等
狀態管理
CLI 會保留會話狀態，包含：
- 會話檔案：
~/.cli-anything-calibre/session.json - 圖書館路徑持久化：活躍的圖書館會跨會話儲存
- 環境變數覆蓋：
CALIBRE_LIBRARY環境變數
輸出格式
所有命令都支援雙重輸出模式：
- 人類可讀（預設）：表格、顏色、格式化文字
- 機器可讀（
--json旗標）：供代理使用的結構化 JSON
# 人類輸出
cli-anything-calibre books list
# 供代理使用的 JSON 輸出
cli-anything-calibre --json books list
供 AI 代理使用
當以程式化方式使用此 CLI 時：
- 始終使用
--json旗標 以獲得可解析的輸出 - 檢查回傳碼 - 0 表示成功，非零表示錯誤
- 解析 stderr 以取得失敗時的錯誤訊息
- 驗證輸出是否存在（在匯出/轉換操作後）
- 使用
--library旗標 或CALIBRE_LIBRARY環境變數來指定圖書館路徑 - 章節匯出需要 EPUB 格式 - 如有需要，先進行格式轉換
更多資訊
- 完整文件：請參閱套件中的 README.md
- 架構 SOP：請參閱 agent-harness 目錄中的 CALIBRE.md
- 測試覆蓋率：請參閱 tests 目錄中的 test_core.py 和 test_full_e2e.py
- 方法論：請參閱 cli-anything-plugin 中的 HARNESS.md
版本
1.0.0