cli-anything-calibre 是做什么的？
一个为 Calibre 电子书管理设计的有状态 CLI 工具。它包装了真实的 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 输出运行（供 AI 代理使用）
cli-anything-calibre --json books list
REPL 模式
不带子命令调用时，CLI 会进入交互式 REPL 会话：
cli-anything-calibre
# 使用 Tab 补全和历史记录交互式输入命令
# 输入 'help' 查看可用命令
# 输入 'quit' 或 'exit' 退出
命令组
库管理
库管理命令。
| 命令 | 描述 |
|---|---|
connect <path> | 设置活动库路径 |
info | 显示库统计信息（图书数量、格式、数据库大小） |
check | 使用 calibredb check_library 验证库完整性 |
图书操作
图书操作（包装 calibredb）。
| 命令 | 描述 |
|---|---|
list | 列出图书，支持过滤和排序 |
search <query> | 使用 Calibre 查询语言搜索 |
add <files> | 向库中添加图书文件 |
remove <ids> | 删除图书（移到回收站或永久删除） |
show <id> | 显示图书的完整元数据 |
export <ids> | 将图书导出到目录 |
export-chapters <id> | 将每个章节导出为单独的 PDF（需要 EPUB 格式） |
元数据编辑
元数据编辑（包装 calibredb set_metadata）。
| 命令 | 描述 |
|---|---|
get <id> [field] | 获取元数据（全部或特定字段） |
set <id> <field> <value> | 设置元数据字段 |
embed <ids> | 将元数据嵌入到图书文件中 |
格式管理
格式管理（包装 calibredb + ebook-convert）。
| 命令 | 描述 |
|---|---|
list <id> | 列出图书的可用格式 |
add <id> <file> | 为图书添加格式 |
remove <id> <fmt> | 从图书中删除格式 |
convert <id> <input_fmt> <output_fmt> | 转换图书格式 |
自定义列
自定义列（包装 calibredb）。
| 命令 | 描述 |
|---|---|
list | 列出所有自定义列 |
add <label> <name> <type> | 创建自定义列 |
remove <label> | 删除自定义列 |
set <id> <label> <value> | 设置自定义字段值 |
目录生成
目录生成。
| 命令 | 描述 |
|---|---|
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 "New 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标志）：用于 AI 代理消费的结构化 JSON
# 人类输出
cli-anything-calibre books list
# 为 AI 代理准备的 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