Calibre Drafts API

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

配置说明

常见配置示例

# 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（要修改的字段对象）。

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

响应示例

{
  "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
• 用途: 搜索在线元数据源（如豆瓣），获取书籍的标准元数据信息

查询参数

响应示例

{
  "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
• 用途: 提交删除书籍的待审核草稿（危险操作，需管理员审核通过后才会真正删除书籍）

删除前二次确认（必须）

在真正调用 POST /api/drafts/delete 之前，必须满足以下条件：

1. 已向用户明确重复待删除的 书籍 ID 列表 和 总数量
2. 已得到用户对这批 精确 ID 的显式确认
3. 如果用户只表达了“删掉这些书”但没有明确确认最终 ID 列表，则先停在预览请求体，不要实际提交

这条规则高于便利性要求。删除草稿一旦审核通过，书籍会被永久删除。

请求体（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 - 撤销任何类型的待审核草稿（包括删除草稿）

Checklist

调用前：

• 配置文件 ~/.config/calibre-drafts-api/config.json 存在且 base_url 不含 /api
• 已确认本次操作属于草稿写入，而不是只读浏览
• 已确认使用的是 Calibre 书籍 ID，不是草稿记录 ID 或元数据源 ID
• 若调用删除接口，已向用户重复 ID 列表并得到显式确认

调用后：

• 已检查响应中的 code / message / data.received
• 已告知用户草稿仍需管理员审核才会生效
• 若是危险操作，已提醒可用 POST /api/drafts/cancel 撤销待审核草稿

常见错误

与书库只读技能的关系

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