核心用法
calibre-metadata-apply 是面向已运行 Calibre Content Server 的元数据编辑技能，通过 calibredb 命令行工具实现对书籍元数据的精准更新。核心工作流为：目标确认 → 提案合成 → 试运行(dry-run) → 正式应用(apply)。
关键特性：
- ID驱动更新：必须基于确切的书籍ID（如
ID1011）操作，禁止模糊匹配后直接修改 - 多字段支持：title/authors/series/series_index/tags/publisher/pubdate/languages/comments 等直接字段，以及 comments_html/analysis 等辅助字段
- 智能提案流程：当元数据缺失时，自动提取文件内容+网络检索生成候选方案，标注置信度（high/medium/low），经用户审批后才执行
- 分层确认机制：Light pass（元数据分析）→ Page-1 pass（首页精读）→ Deep pass（首尾5页+网络证据），每级需显式用户指令
执行安全：
- 强制dry-run预览变更
--apply需显式用户批准- 低置信度字段留空，标记
pending-review标签待后续处理 - 支持环境变量/配置文件托管连接参数，避免命令行泄露敏感信息
显著优点
1. 操作安全性高：多层人工确认关卡，杜绝误改；ID精准定位避免批量误操作
2. 远程友好：专为 Content Server 设计，支持主机故障转移（CALIBRE_SERVER_HOSTS）、WSL环境自适应
3. 审计可追溯：本地状态文件记录每次运行（state/runs.json），支持断点续传与回查
4. 灵活的认证方案：支持 Digest 认证、环境变量密码、可选 auth 缓存，不强制明文存储
5. 子代理减负：复杂分析任务可委托轻量级子代理，主会话保持决策权，避免长耗时阻塞
潜在缺点与局限性
1. 依赖预运行服务：必须已有 Calibre Content Server 运行，本技能不启动服务端
2. Node.js 依赖：运行时需 node 环境，非纯 Shell 方案
3. 日语/非拉丁语系需额外配置：reading_script（katakana/hiragana/latin）需首次使用时手动指定并持久化
4. PDF处理链冗长：ebook-convert → pdftotext → web-evidence 三级回退，部分场景提取效率受限
5. 子代理调用增加复杂度：需要 subagent-spawn-command-builder 配合，多技能编排时认知负担较重
适合人群
- 拥有中大型 Calibre 书库（数百至数千册）的资深用户
- 需要批量修正日文/多语言书籍元数据的整理者
- 对数据安全敏感、要求"预览-确认-执行"严谨流程的谨慎型用户
- 已通过 Calibre Content Server 实现多设备书库同步的技术用户
常规风险
- 认证信息泄露：虽默认禁用
--save-plain-password，但用户误操作或环境配置不当仍可能导致密码暴露 - 网络连接中断：远程 Content Server 不可达时，脚本会尝试多主机回退，但复杂网络环境（VPN/代理）下可能连接失败
- 元数据覆盖不可逆：即使有多层确认，最终
--apply执行后修改立即生效，建议配合 Calibre 自身备份机制 - 子代理任务失控：若子代理配置不当（模型/超时参数），长时间分析任务可能占用资源或产生意外费用
- 并发编辑冲突：多用户同时操作同一 Content Server 时，可能出现覆盖竞争，本技能未内置乐观锁机制