cli-anything-calibre 是一个用于 Calibre 电子书管理的状态化命令行封装工具，版本 1.0.0。它封装了真实的 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 安装，并需确认 calibredb、ebook-convert、ebook-meta 已在 PATH 中。
使用方式
支持基础命令模式与交互式 REPL 模式。不带子命令启动时进入交互式 REPL 会话，支持 Tab 补全和历史记录，可用 help 查看命令，用 quit 或 exit 退出。可通过 --json 标志输出供智能体消费的结构化 JSON。
命令分组
书库（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 查询语言
可用于 books search 与 books list --search，示例包括 author:asimov、title:"Foundation"、tags:fiction、rating:>3、series:"Foundation"、pubdate:[2020-01-01,2021-12-31]、identifiers:isbn:1234567890、has:cover、not:tags:fiction，以及 author:asimov and tags:scifi 等布尔组合。
关键元数据字段
包括 title（文本，书名）、authors（文本，作者，以 & 分隔）、tags（文本，逗号分隔标签）、series（文本，系列名）、series_index（浮点，系列位置）、rating（浮点，1-5 评分）、publisher（文本，出版社）、pubdate（日期时间，出版日期）、comments（文本，描述/评论）、languages（文本，语言代码）、identifiers（文本，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）。
面向 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。