calibre-drafts-api

name	calibre-drafts-api
description	Use when the user mentions Calibre 草稿、元数据草稿、删除书籍草稿、drafts API、 批量更新元数据、批量提交元数据、批量删除书籍、清理标签草稿、撤销草稿、 元数据搜索、在线元数据、/api/drafts、/api/drafts/update、/api/drafts/cancel、 /api/drafts/delete、/api/metadata/search，或需要向 Calibre 配套服务提交待审核的 元数据修改、删除书籍请求或搜索在线元数据。

Calibre 书籍草稿 API

用于向本地 Calibre 配套服务提交待审核元数据草稿；生效需管理员审核。

配置

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

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

cat ~/.config/calibre-drafts-api/config.json

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

mkdir -p ~/.config/calibre-drafts-api
cat > ~/.config/calibre-drafts-api/config.json << 'EOF'
{
  "base_url": "http://localhost:3000"
}
EOF

配置说明

字段	必填	说明	示例
base_url	是	Calibre API 服务基址，不包含 /api 后缀	http://localhost:3000

常见配置示例

# Docker Compose 部署（默认）
{"base_url": "http://localhost:3000"}

# 直接运行后端
{"base_url": "http://localhost:8080"}

# 生产环境
{"base_url": "https://calibre-api.example.com"}

地址使用规则

• 配置的 base_url 不应包含尾随的 /api
• 所有接口路径由 base_url + /api/... 拼接
• ✅ 正确: 配置 http://localhost:3000，使用 http://localhost:3000/api/drafts/update
• ❌ 错误: 配置 http://localhost:3000/api，导致 http://localhost:3000/api/api/drafts/update

何时使用

使用此技能当：

• 需要批量提交 Calibre 书籍元数据更新草稿
• 需要提交删除书籍的待审核请求
• 清理垃圾标签、补全缺失元数据
• 搜索在线元数据（豆瓣等源）以获取正确的书籍信息
• 撤销已提交的待审核草稿（更新或删除）
• 调用本地 Calibre 配套服务的草稿 API

不使用此技能当：

• 只读访问 Calibre 书库（使用 calibre-library 技能）
• 直接修改 Calibre 数据库（不推荐，应通过官方 API）

ID 约定（重要）

• updates[].id（POST /api/drafts/update）：Calibre 书籍 ID（字符串，与书库/API 中书籍主键一致）。
• ids（POST /api/drafts/delete、POST /api/drafts/cancel）：书籍 ID 的数组，与上相同；不是草稿表主键或其它内部 ID。

批量更新草稿

• 方法/路径: POST /api/drafts/update
• Content-Type: application/json

请求体结构

• updates: 数组，每项含 id（书籍 ID 字符串）与 data（要修改的字段对象）。

字段更新规则（必须遵守）

字段类型	包含字段	不传 / null	[] 或 ""	非空值
Tags	tags	不更新	清空全部标签（唯一允许「清空」的字段）	设为该标签列表
Authors	authors	不更新	拒绝（不可清空作者）	更新作者列表
字符串	title, publisher, comments, isbn	不更新	拒绝（不可清空）	更新为该值

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "received": 3
  }
}

注意事项

1. 同一本书多次提交会合并：已有待审核草稿时，新提交会更新该草稿而非新建。
2. 只传需要改的字段：未出现的字段表示不更新。
3. 违规字段单独忽略：某字段违反规则时该字段被丢弃，其余合法字段仍保存；可查服务端日志确认。
4. 批量：一次请求可包含多本书。

更多 JSON 请求示例见 examples.md。

列出草稿

GET /api/drafts?limit=50&offset=0

（完整 URL：{基址}/api/drafts?...）

元数据搜索

• 方法/路径: GET /api/metadata/search
• 用途: 搜索在线元数据源（如豆瓣），获取书籍的标准元数据信息

查询参数

参数	类型	必填	说明
query	string	是	搜索关键词：书名、作者、ISBN 等

响应示例

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "douban:123456",
      "title": "三体",
      "authors": ["刘慈欣"],
      "publisher": "重庆出版社",
      "pubdate": "2008-1",
      "isbn": "9787536692930",
      "tags": ["科幻", "小说"],
      "rating": 9.3,
      "cover": "https://...",
      "comments": "文化大革命如火如荼..."
    }
  ]
}

使用场景

1. 补全缺失元数据前查询：搜索正确的书籍信息，然后通过 POST /api/drafts/update 提交草稿
2. 验证 ISBN：通过 ISBN 搜索，确认书籍信息是否正确
3. 查找标准出版信息：获取规范的出版社名称、出版日期等

注意事项

• 搜索结果来自在线源（如豆瓣），需要网络连接
• 返回的是候选列表，需要人工确认选择正确的条目
• id 字段（如 douban:123456）是元数据源的内部标识，不是 Calibre 书籍 ID

撤销草稿

• 方法/路径: POST /api/drafts/cancel
• Content-Type: application/json

用于撤销已提交、尚未审核通过的草稿：放弃本次待合并的修改，该书不再保留对应待审核草稿。

请求体（与删除接口相同形态；ids 为书籍 ID）：

{
  "ids": ["123", "456", "789"]
}

• ids（必填）：要撤销草稿的 Calibre 书籍 ID 列表。

响应：与更新接口类似，data.received 表示处理条数。

提交删除书籍草稿

• 方法/路径: POST /api/drafts/delete
• Content-Type: application/json
• 用途: 提交删除书籍的待审核草稿（危险操作，需管理员审核通过后才会真正删除书籍）

请求体（ids 为书籍 ID）：

{
  "ids": ["123", "456", "789"]
}

• ids（必填）：要删除的 Calibre 书籍 ID 列表。

响应：与更新接口类似，data.received 表示处理条数。

重要说明：

• 这是危险操作，提交后会创建"删除书籍"的待审核草稿
• 审核通过后，书籍将从 Calibre 书库中永久删除
• 删除前请确认书籍 ID 正确，误删除可能无法恢复
• 如果需要撤销删除草稿，使用 POST /api/drafts/cancel

与 cancel 的区分：

• POST /api/drafts/delete - 提交"删除书籍"的草稿
• POST /api/drafts/cancel - 撤销任何类型的待审核草稿（包括删除草稿）

常见错误

错误	后果	正确做法
未创建配置文件	请求失败，找不到服务地址	首次使用前检查并创建 ~/.config/calibre-drafts-api/config.json
配置的 base_url 包含 /api 后缀	路径重复（如 /api/api/drafts）	base_url 应为 http://localhost:3000，不包含 /api
误以为 /api/drafts/delete 是删除草稿	理解错误	该接口是提交删除书籍草稿，不是删除草稿记录
未确认就提交删除书籍草稿	可能误删重要书籍	删除前仔细确认书籍 ID，删除草稿需管理员审核
传 authors: []	请求被拒绝	Authors 不可清空，需要非空数组
传 "" 清空字符串字段	字段被忽略	字符串字段（title、publisher 等）不可清空，只有 tags: [] 可清空
误用草稿表 ID	找不到书籍	id 和 ids 均为 Calibre 书籍 ID，不是草稿记录内部 ID
误用元数据源 ID	找不到书籍	元数据搜索返回的 id（如 douban:123456）不是 Calibre 书籍 ID
忘记 Content-Type	请求失败	必须设置 Content-Type: application/json
重复提交同一书	草稿被合并而非新建	同一书多次提交会更新现有草稿，这是预期行为
传 null 值	字段被忽略	null 等同于不传，表示"不更新该字段"
直接使用搜索结果	可能信息不准确	元数据搜索返回候选列表，需人工确认后再提交草稿

与书库只读技能的关系

浏览/搜索书库仍用 calibre-library（只读）。本技能仅描述草稿写入、撤销与删除 HTTP 契约；调用前需确认服务已启动且基址正确。