calibre-catalog-read

核心用法

calibre-catalog-read 是一款面向 Calibre 电子书库的智能化分析工具，通过连接 Calibre Content Server 提供两种核心能力：一是只读目录查询（list/search/id），支持以 JSON 格式快速检索书库；二是单书 AI 分析管道，完整执行「导出→分析→缓存→元数据回写」流程。该技能采用主代理-子代理分离架构，主代理负责快速控制平面（验证意图、启动任务、返回进度），子代理承担繁重的内容分析平面，通过 SQLite 缓存分析状态，确保聊天界面不会因长时分析而阻塞。

显著优点

该技能最大亮点在于其异步非阻塞设计，严格遵循「两回合执行模型」：第一回合快速启动子代理并返回确认，第二回合在分析完成后自动处理结果。支持多语言分析（通过 --lang 参数），并智能排除漫画/图像类书籍以避免资源浪费。安全机制完善，密码通过环境变量传递，可选的认证缓存文件自动设置 0o600 权限（仅所有者可读写）。此外，完善的 SQLite 缓存机制可避免重复分析，配合 hash 状态检查实现增量更新。

潜在缺点与局限性

首先，该技能依赖完整的 Calibre 套件（calibredb、ebook-convert）以及 Node.js 和 Python (uv) 环境，部署门槛较高。其次，作为 T3 级来源（社区/个人维护），虽代码透明但缺乏官方组织背书，在高安全隔离的生产环境受限。功能上目前仅支持单书顺序处理，无法批量并行分析。此外，需要用户自行配置可访问的 Calibre Content Server 地址，且对网络稳定性有要求，长文本分析可能面临超时风险。

适合的目标群体

本技能最适合拥有大型 Calibre 电子书库的个人用户、学术研究人员、以及需要进行系统性阅读笔记管理的数字阅读爱好者。特别适合那些希望为藏书自动生成深度分析、再读指南，并将这些结构化数据直接写回 Calibre 元数据（comments 字段）的高级用户。对于构建个人知识管理系统或数字人文研究项目的用户尤为实用。

使用风险与注意事项

主要风险包括：1) 外部命令调用依赖（通过 subprocess 调用 calibredb/ebook-convert），尽管参数经过验证但仍需确保二进制文件可信；2) 网络通信安全，需确保连接的 Calibre Content Server 处于可信网络环境；3) 环境变量配置复杂性，CALIBRE_PASSWORD 必须正确设置且避免使用 --save-plain-password；4) 长文本处理时的资源消耗和超时风险，建议通过 runTimeoutSeconds 合理配置。此外，该技能会修改远程 Calibre 数据库的 comments 元数据，使用前建议备份书库。