核心用法
calibre-metadata-apply 是一个面向 Calibre 电子书库的受控元数据更新工具，通过 calibredb 命令行与 Content Server 交互完成远程元数据修改。其核心执行流程采用强制确认机制：必须先通过只读查询锁定目标图书 ID，经用户确认后方可构建 JSONL 变更载荷；执行前必须完成 dry-run 预演，获得明确批准后才能真正应用变更。
技能支持两类字段更新：直接字段（title、authors、series、tags 等标准元数据）和辅助字段（comments_html、analysis、analysis_tags 等增强型标记）。对于缺失元数据的场景，提供证据驱动的提案合成模式——结合文件内容提取与网络来源生成候选值，并标注置信度（high/medium/low），由用户逐项审批或编辑后再执行。
显著优点
1. 安全优先架构：强制 dry-run → 用户确认 → apply 的三段式流程杜绝误操作；密码优先使用环境变量（--password-env），禁止默认明文存储。
2. 灵活的分层分析：Light/Page-1/Deep 三阶渐进分析，用户可按需选择深度，避免过度读取隐私或版权敏感内容。
3. 子代理解耦：重型候选生成任务通过 subagent-spawn-command-builder 派生子会话执行，主会话保持轻量响应，支持 turn-split 长运行拆分。
4. 完善的审计与回查：每轮运行持久化至 state/runs.json，输出完整的变更/挂起/错误清单，支持批量 diff 报告。
5. 多语言排序支持：内置日语假名/拉丁读法配置，持久化用户偏好。
潜在缺点与局限
- 依赖外部服务：需可访问的 Calibre Content Server，且依赖 Node.js 运行时与
calibredb二进制文件，部署门槛高于纯本地脚本。 - 网络与认证复杂度：多用户场景需管理
CALIBRE_USERNAME/PASSWORD，Token 缓存路径（~/.config/calibre-metadata-apply/）需自行保障权限。 - PDF 提取鲁棒性：默认 fallback 链（ebook-convert → pdftotext）在扫描版 PDF 或复杂排版场景可能失效，需切换至 web-evidence-first 模式弥补。
- 批量规模受限：未知文档恢复流程要求单批次必须能在聊天窗口完整展示行级结果，大规模库的全量自动化处理需人工分批次确认。
- 子代理隐私风险：若启用重型候选生成，文本/元数据将发送至配置的模型端点，对敏感藏书需显式禁用子代理流程。
适合人群
- 拥有数百至数千册电子书、需要规范化元数据的个人或小型团队管理员；
- 对数据准确性要求高、不愿接受自动覆盖的谨慎型用户；
- 需要处理日文/非拉丁语系藏书并自定义排序规则的东亚语言用户；
- 具备基础命令行能力，能部署 Calibre Content Server 的技术用户。
常规风险
- 误写风险：尽管有多重确认，若用户未仔细核对 dry-run 输出仍可能批量错误修改；建议首次使用先在测试库验证。
- 凭证泄露：虽然默认禁止
--save-plain-password，但手动覆盖或环境变量配置不当仍可能导致密码暴露在进程列表或日志中。 - 服务可用性：长时间 turn-split 运行期间，若 Content Server 重启或网络中断，需人工介入恢复状态。
- 模型幻觉：Low confidence 候选若被用户误批准确认，可能引入错误元数据；建议对冲突来源保持为空或标记
pending-review。