calibre-library

name: calibre-library description: >- 只读访问个人 Calibre 书库，通过 AJAX API 搜索、浏览、下载书籍。支持按 标题/作者/标签/ISBN 搜索，按作者/出版社/标签/丛书分类浏览，获取书籍详情与 元数据，下载 epub/mobi/pdf 等格式。Use when the user mentions Calibre, 书库, 找书, 下载书籍, 搜书, or wants to browse/search/download books. FORBIDDEN: Any write/modify/delete operations.

Calibre 书库（只读）

通过 Calibre Content Server AJAX API 搜索、浏览和下载书籍。

严禁任何写入、修改、删除操作。仅允许搜索、浏览和下载。

适用场景

• 按关键词搜索书籍（标题、作者、标签、ISBN）
• 按作者、出版社、标签、丛书分类浏览
• 获取书籍详情和元数据
• 下载书籍文件（epub、mobi、pdf 等）
• 查看最新入库书籍

不适用

• 添加、删除、修改书籍或元数据
• 管理书库设置或用户权限
• 上传文件到书库

配置

配置文件路径：~/.config/calibre-library/config.json

首次使用前，检查配置文件是否存在：

cat ~/.config/calibre-library/config.json

若不存在，提示用户创建：

mkdir -p ~/.config/calibre-library
cat > ~/.config/calibre-library/config.json << 'EOF'
{
  "base_url": "https://lib.pve.icu",
  "library_id": "library",
  "username": "",
  "password": ""
}
EOF

认证模式

读取配置后根据 username/password 决定认证方式：

• 无认证：两个字段均为空 → 直接请求
• Basic Auth：任一字段非空 → curl 附加 -u username:password

构建 curl 命令的模式：

# 读取配置
CONFIG=$(cat ~/.config/calibre-library/config.json)
BASE_URL=$(echo "$CONFIG" | python3 -c "import sys,json; print(json.load(sys.stdin)['base_url'])")
LIB_ID=$(echo "$CONFIG" | python3 -c "import sys,json; print(json.load(sys.stdin)['library_id'])")
USERNAME=$(echo "$CONFIG" | python3 -c "import sys,json; print(json.load(sys.stdin).get('username',''))")
PASSWORD=$(echo "$CONFIG" | python3 -c "import sys,json; print(json.load(sys.stdin).get('password',''))")

# 构建 auth 参数
AUTH=""
if [ -n "$USERNAME" ]; then AUTH="-u $USERNAME:$PASSWORD"; fi

# 示例请求
curl -sL $AUTH "$BASE_URL/ajax/search?query=三体&num=10&library_id=$LIB_ID"

实际使用中直接将读取到的值替换进 curl 命令即可，无需每次都执行完整脚本。

禁止将密码写入 SKILL.md 或提交到版本控制。

API 参考

所有 AJAX 端点返回 JSON。以下用 {BASE} 代替 base_url，{LIB} 代替 library_id。

1. 搜索书籍

GET {BASE}/ajax/search?query={keyword}&num={count}&library_id={LIB}

响应示例：

{
  "total_num": 59,
  "book_ids": [165522, 38336],
  "num": 2,
  "offset": 0
}

仅返回 book_ids，需用详情接口获取完整信息。翻页：设置 offset = 上一页 offset + num。

高级搜索语法

author:"刘慈欣"
tags:"科幻"
publisher:"重庆出版社"
series:"冰与火之歌"
isbn:9787229042066
date:>2025-01-01                     # 2025年之后入库（timestamp，非出版日期）
date:>30daysago                      # 最近30天入库
date:>yesterday                      # 昨天及之后入库
author:"刘慈欣" AND tags:"科幻"
author:"刘慈欣" AND date:>7daysago   # 组合：某作者最近7天入库

2. 书籍详情

单本：

GET {BASE}/ajax/book/{book_id}/{LIB}

批量（逗号分隔 ID）：

GET {BASE}/ajax/books?ids={id1},{id2}&library_id={LIB}

关键响应字段：

3. 分类列表

获取书库支持的所有分类：

GET {BASE}/ajax/categories/{LIB}

返回数组，每项包含 name、url、is_category。

4. 分类浏览

浏览某一分类下的条目：

GET {BASE}/ajax/category/{category_hex}/{LIB}?num={count}&offset={offset}

常用分类 hex ID：

响应示例（作者分类）：

{
  "category_name": "作者",
  "total_num": 70780,
  "offset": 0,
  "num": 3,
  "items": [
    {
      "name": "刘慈欣",
      "count": 110,
      "average_rating": 0.0,
      "url": "/ajax/books_in/617574686f7273/313336/library"
    }
  ]
}

每个 item 的 url 可直接用于获取该条目下的书籍。

5. 分类内书籍

获取某个作者/出版社/标签/丛书下的所有书籍 ID：

GET {BASE}{item_url}?num={count}&offset={offset}

item_url 来自分类浏览响应中 items[].url，或书籍详情的 category_urls 字段。

响应与搜索接口相同，返回 book_ids 数组。

6. 最新入库

通过搜索接口的 date: 过滤器按添加时间查询，date: 对应书籍的 timestamp（入库时间），而非 pubdate（出版日期）。

GET {BASE}/ajax/search?query=date:>{date_expr}&num={count}&sort=date&sort_order=desc&library_id={LIB}

date_expr 支持两种格式：

配合 sort=date&sort_order=desc 按入库时间倒序排列。

响应示例：

{
  "total_num": 112,
  "sort_order": "desc",
  "sort": "date",
  "book_ids": [274770, 274769, 274768],
  "query": "date:>30daysago"
}

7. 下载与封面

下载书籍文件：

GET {BASE}/get/{format}/{book_id}/{LIB}

format 小写：epub, mobi, pdf, azw3, txt 等。返回二进制文件。

建议保存到 ~/Downloads/，并通过 format_metadata.{format}.size 校验文件大小。

封面与缩略图：

GET {BASE}/get/cover/{book_id}/{LIB}
GET {BASE}/get/thumb/{book_id}/{LIB}

操作步骤

搜索并查看

1. 读取配置获取 BASE_URL 和 LIB_ID
2. 搜索：curl -sL $AUTH "$BASE_URL/ajax/search?query=关键词&num=10&library_id=$LIB_ID"
3. 提取 book_ids
4. 批量获取详情：curl -sL $AUTH "$BASE_URL/ajax/books?ids=ID1,ID2&library_id=$LIB_ID"
5. 向用户展示结果

按作者/出版社/标签浏览

1. 搜索 author:"刘慈欣" 找到书籍
2. 从书籍详情的 category_urls.authors 获取作者 URL
3. 请求该 URL 获取该作者全部 book_ids
4. 批量获取详情

或直接浏览分类：

1. 请求分类浏览接口列出作者/出版社列表
2. 从 items[].url 获取目标条目的书籍列表
3. 批量获取详情

下载书籍

1. 获取书籍详情，确认可用 formats 和 main_format 路径
2. 下载：curl -sL $AUTH "$BASE_URL/get/epub/{book_id}/$LIB_ID" -o ~/Downloads/书名.epub
3. 校验文件大小是否匹配 format_metadata.{format}.size

查看最新入库

1. 搜索：curl -sL $AUTH "$BASE_URL/ajax/search?query=date:>7daysago&num=20&sort=date&sort_order=desc&library_id=$LIB_ID"
2. 提取 book_ids，批量获取详情并展示
3. 根据用户需求调整时间范围（7daysago、30daysago、具体日期等）

输出格式

列表展示使用 bullet list：

- **三体三部曲** — 刘慈欣 (ID: 267085)
  格式: epub | 标签: 科幻, 经典 | ISBN: 9787229042066

单本详情包含：书名、作者、出版社、出版日期、丛书、标签、可用格式、ISBN、评分，以及从 comments 截取的简介（过长时截断）。

Checklist

使用前：

• 配置文件 ~/.config/calibre-library/config.json 存在且内容正确
• base_url 可访问（curl 返回 HTTP 200）
• 确认操作为只读（搜索/浏览/下载），无任何写入意图

使用后：

• 下载的文件大小与 format_metadata 一致
• 未执行任何写入、修改、删除操作

常见错误