mcpField
C
cli-anything-calibre

cli-anything-calibre

github.com/hkuds文档处理57.6k330 次安装5 周前更新
代码仓库

关于 cli-anything-calibre

cli-anything-calibre 是用于管理 Calibre 书库、编辑元数据和转换电子书的有状态命令行界面。它封装 Calibre 工具并提供结构化输出，供脚本和 AI Agent 使用；需另行安装 Calibre。

主要功能

  1. 01连接并查看书库
  2. 02搜索、添加、导出和移除书籍
  3. 03查看和编辑书籍元数据
  4. 04管理格式并转换书籍
  5. 05生成 EPUB、CSV 或 OPDS 目录
  6. 06提供易读和 JSON 输出

适用场景

  1. 01使用 Calibre 查询语言搜索书库
  2. 02批量更新书籍元数据
  3. 03将书籍转换为其他格式
  4. 04将 EPUB 章节分别导出为 PDF

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-calibre

安装后在 Claude Code 中输入/cli-anything-calibre确认已加载。

详细介绍

cli-anything-calibre

一个用于 Calibre 电子书管理的有状态 CLI 工具封装。它封装了真实的 Calibre 工具（calibredb、ebook-convert、ebook-meta），为 AI Agent 和脚本提供干净、结构化的界面，用于书库操作、元数据编辑和格式转换。

安装

此 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

# Verify tools are in PATH
which calibredb
which ebook-convert
which ebook-meta

用法

基本命令
# Show help
cli-anything-calibre --help

# Start interactive REPL mode
cli-anything-calibre

# Connect to a Calibre library
cli-anything-calibre library connect ~/Calibre\ Library

# Run with JSON output (for agent consumption)
cli-anything-calibre --json books list
REPL 模式

在不带子命令调用时，CLI 会进入交互式 REPL 会话：

cli-anything-calibre
# Enter commands interactively with tab-completion and history
# Use 'help' to see available commands
# Use 'quit' or 'exit' to leave

命令组

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
# Or with JSON output
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                    # Author contains "asimov"
title:"Foundation"               # Title phrase
tags:fiction                     # Tag match
rating:>3                        # Rating greater than 3
series:"Foundation"              # Series match
pubdate:[2020-01-01,2021-12-31]  # Date range
identifiers:isbn:1234567890      # Specific identifier
has:cover                        # Has cover image
not:tags:fiction                 # Negation
author:asimov and tags:scifi     # Boolean AND

关键元数据字段

字段类型描述
titletext书名
authorstext作者姓名（以 & 分隔）
tagstext以逗号分隔的标签
seriestext系列名称
series_indexfloat系列中的位置
ratingfloat评分 1-5
publishertext出版商名称
pubdatedatetime出版日期
commentstext描述/评论
languagestext语言代码
identifierstextISBN、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 标志）：供 Agent 使用的结构化 JSON
# Human output
cli-anything-calibre books list

# JSON output for agents
cli-anything-calibre --json books list

面向 AI Agent

以编程方式使用此 CLI 时：

  1. 始终使用 --json 标志以获得可解析的输出
  2. 检查返回码——0 表示成功，非零表示错误
  3. 解析 stderr 以获取失败时的错误信息
  4. 验证输出是否存在——在导出/转换操作之后
  5. 使用 --library 标志或 CALIBRE_LIBRARY 环境变量指定书库路径
  6. 章节导出需要 EPUB 格式——如有需要请先转换

更多信息

  • 完整文档：参见包中的 README.md
  • 架构 SOP：参见 agent-harness 目录中的 CALIBRE.md
  • 测试覆盖：参见 tests 目录中的 test_core.py 和 test_full_e2e.py
  • 方法论：参见 cli-anything-plugin 中的 HARNESS.md

版本

1.0.0

评论

支持 Markdown