用途
该技能在 macOS 上通过命令行管理电子书与 calibre 书库，覆盖格式转换、封面、目录、元数据、书库查询与批量修改、输出校验等任务。每次调用都是 calibre 自带 CLI 工具的短进程；辅助脚本运行在 calibre 捆绑的 Python 上，无需额外安装。技能不会启动服务器，也不会直接编辑 metadata.db，书库写入都经 calibredb 完成。已对照 macOS 上的 calibre 9.16 验证。
统一入口
所有操作都通过 scripts/calibre.sh 执行。它会定位应用、应用超时（CALIBRE_TIMEOUT，默认 600 秒）并强制英文输出，因为 calibre 会按系统语言本地化消息，并给新书打上界面语言标签。例如在匈牙利语 Mac 上，一本英文小说若不传 --language 会被标记为 hun。
先运行检查：
C=scripts/calibre.sh
bash $C check [LIBRARY]
输出应用、版本、书库（默认 calibre 配置的书库）、锁状态与 epubcheck。缺少 calibre 时先征求是否安装（brew install --cask calibre）；epubcheck 可选（brew install epubcheck），存在时脚本会使用。
参考文档：references/cli-reference.md 列出 ebook-convert 按输入/输出格式的选项、目录/章节 XPath、calibredb 子命令、搜索语法与字段格式、ebook-meta、ebook-polish；references/recipes.md 覆盖 Kindle/Kobo 转换、文件夹批处理、DOCX→EPUB、EPUB→Markdown、添加书籍、导出、目录、封面、抓取元数据；references/gotchas.md 用于写入被拒、元数据读取异常或转换结果异常时，也说明安全姿态。
主要能力
从 Markdown/HTML 章节生成 EPUB
bash $C py scripts/md_to_epub.py chapters/ -o book.epub --title "The Salt Road" \
--authors "Mara Lind" --language en --cover cover.jpg \
[--series "Coastline" --series-index 2] [--publisher P --tags "a,b" --pubdate 2026-05-01] \
[--toc-levels 2] [--css extra.css] [--order a.md b.md …] [--inline-toc]
章节为文件夹中的 .md/.html 文件，按自然顺序排序（2 在 10 前）。README*、NOTES* 和 _* 会被跳过，JSON 会列出所有被跳过的文件，需与用户意图核对；文件名排序不符合预期时用 --order。每章成为独立 spine 文档，首个 # 标题作为目录条目，## 成为二级条目；无标题章节从 front matter 的 title: 或文件名生成并给出警告。Markdown 支持脚注、表格、围栏代码、智能引号；本地图片被复制进来，章节文件间的链接会被重写。--language 必填，应按文本设置而非用户地区。输出类型由扩展名决定，脚本会回读书籍，标题、作者、系列、封面或章节列表与要求不符时以退出码 4 结束。
PDF 转 EPUB 并生成质量报告
bash $C py scripts/pdf_to_epub.py book.pdf -o book.epub --language en [--title T --authors A] [--cover c.jpg]
拒绝扫描版 PDF（无文本层，退出码 3），因其需先 OCR。脚本以启发式参数运行 ebook-convert 后修复结果：重接行尾断词（con-tinued→continued，well-known 等真实复合词保留）、合并句中段落断裂、删除孤立页码与页眉、从章节标题重建空目录。向用户报告 fixes（改了什么）和 remaining_issues（没改好的）。PDF→EPUB 无法无损，需指出问题而非称结果干净，再用 ebook_check.py 或解压查看若干章节。表格、脚注、多栏布局、带说明的图通常保留较差，源文件含这些时应说明。
其他转换与单文件元数据
bash $C ebook-convert in.epub out.azw3 [--cover c.jpg --title T --authors "A & B" --language en]
bash $C ebook-meta book.epub
bash $C ebook-meta book.epub -a "Jane Doe" --author-sort "Doe, Jane" -s "Series" -i 2 -l en
格式由扩展名决定；KEPUB、AZW3、MOBI、PDF、DOCX、TXT、HTMLZ 均可作为输出。Markdown 输出为 .txt 加 --txt-output-formatting markdown，因为 .md 不是可输出扩展名。元数据选项适用于所有转换；--authors 用 & 分隔多人，逗号不分隔作者（"Doe, Jane" 是一位作者）。文件夹批处理在 shell 中循环，每个文件独立进程，可逐个检查退出码。
书库查询、添加与导出
bash $C calibredb list --for-machine -f title,authors,series,series_index,tags --search 'series:"=Harbor Lights"'
bash $C calibredb search 'cover:false'
bash $C calibredb add --authors "A" --title "T" --languages eng book.epub
bash $C calibredb export --to-dir out/ --formats epub 12,13
默认书库为 calibre 配置者，用 --with-library PATH 指定其他书库。搜索语法包括 field:value（包含）、field:"=exact"、field:"~regex"、and/or/not、cover:false、formats:pdf、#custom: 等。
批量元数据修改
不要手工循环 calibredb set_metadata。使用脚本规划、备份、写入并回读：
B=scripts/bulk_metadata.py
bash $C py $B --variants "Jane Doe"
bash $C py $B --ids 1,2,3,4,5 --set authors="Jane Doe" --set series="Harbor Lights" --series-order pubdate
bash $C py $B … same … --apply --backup before.json
bash $C py $B --restore before.json --apply
先定位书籍。--variants 列出每种作者拼写及其书籍，包括 Doe, Jane 与 J. Doe；仅首字母匹配与相似名（John Doe、Jane Doe-Smith）会被标记而不合并，需结合书名与系列判断，身份不明时询问用户。先试运行并逐条核对 old→new，再 --apply。设置 authors 也会设置 author_sort（仅用 calibredb 会保留旧值）；--series-order pubdate 将所选书籍按 1…n 编号。日期以 UTC 正午存储，因为裸写的 1995-03-01 会落在 3 月 2 日。报告已应用的修改与备份路径以便撤销。
书库在 calibre 中打开时，GUI 或 calibre-server 运行期间 calibredb 会拒绝所有本地书库的写入甚至读取。此时脚本会经该程序在本机的 Content server 写入（若其允许本地写入），否则以退出码 6 结束并说明如何启用。绝不要终止或退出用户的 calibre 来绕过锁定，应请其关闭或开启 Content server。bash $C lock 可查看状态。
输出校验
bash $C py scripts/ebook_check.py book.epub --expect-title "T" --expect-authors "A" --expect-language en \
--expect-toc 6 --expect-cover [--expect-series S --expect-series-index 2] [--max-epubcheck-errors 0]
JSON 包含元数据、带层级的目录、封面、图片、epubcheck 结果与 issues（页眉、页码、断词、句中断裂、纯图片页、缺目录、Unknown author、无语言）。--strict 时任何 issue 都以退出码 4 结束。转换退出码 0 不等于完成，需核对用户要求（标题、作者、语言、章节、封面）并告知检查了什么。
使用方式
脚本以 bash $C py scripts/<name>.py … 运行，向 stdout 输出 JSON，支持 --help。退出码：2 用法错误，3 输入缺失或不可读，4 校验失败，5 calibre 错误，6 书库被锁定。
适用场景
电子书格式互转与批量处理、为 Markdown/HTML 稿件制作 EPUB、PDF 转 EPUB 并评估质量、查询与导出 calibre 书库、批量修正作者/系列等元数据、发布前校验电子书。
限制
仅面向 macOS；依赖本机 calibre；无文本层的扫描 PDF 被拒绝，需先 OCR；PDF→EPUB 非无损，表格、脚注、多栏与带说明图片保留较差；书库被 GUI/server 占用时写入受限，只能经允许本地写入的 Content server，否则无法写入；默认超时 600 秒。