核心功能
calibre-metadata-apply 是专为 Calibre 电子书库设计的元数据编辑技能，通过连接运行中的 Calibre Content Server 实现远程元数据管理。支持通过书籍 ID 精准定位目标，可更新 title、authors、series、series_index、tags、publisher、pubdate、languages 等核心字段，并提供 comments_html、analysis 等辅助字段用于富文本注释和自动分析。
显著优点
- 精准ID操作：避免标题模糊匹配风险，通过数字ID直接锁定目标书籍
- 强制确认流程：必须执行 dry-run 并获取用户显式批准后才可应用变更，防止误操作
- 多源证据合成：支持文件内容提取（PDF首/末页）、网络检索等多渠道信息整合
- 分阶段处理：Light/Page-1/Deep 三级分析深度，用户可控成本与精度
- 状态持久化：通过
state/runs.json保存运行状态，支持断点续传和批量任务管理 - 环境安全：优先使用
--password-env环境变量传递认证信息，避免命令行泄露
潜在局限
- 依赖外部服务：必须预先配置并运行 Calibre Content Server，无法独立启动服务器
- Node.js 运行时要求：需要 Node 环境执行封装脚本，纯 Calibre 命令行无法直接使用
- 批量规模限制：未知文档恢复流程要求小批次展示全量结果，大规模库操作需分轮次交互
- PDF提取不稳定：依赖 ebook-convert/pdftotext 作为回退方案，部分加密或复杂PDF可能无法解析
- 子代理复杂度：重度分析任务需协调 subagent-spawn-command-builder，增加编排复杂度
适用人群
- 拥有千册级以上 Calibre 书库的个人研究者或数字图书馆管理员
- 需要批量修复日文/非拉丁字符书名排序规则（katakana/hiragana/latin）的专业用户
- 对元数据质量有严格要求，愿意投入时间进行逐本确认的深度整理者
- 已部署 Calibre Content Server 并接受 Digest 认证模式的技术用户
常规风险
- 误覆盖风险：虽然有多层确认，但
--apply后变更直接写入远程数据库，建议操作前备份 library - 认证信息泄露：非SSL部署使用 Digest 认证，需确保
.env文件权限控制（建议 600） - 子代理数据出境：启用 analysis worker 时，文本内容可能发送至外部模型端点，敏感资料需谨慎
- 网络连接波动：依赖
CALIBRE_SERVER_HOSTS故障转移机制，IP变更期间可能出现短暂不可用 - 并发冲突：多人同时操作同一 library 时可能产生元数据覆盖竞争，建议单用户或协调使用