核心用法
calibre-catalog-read 是一个面向 Calibre Content Server 的只读目录技能，提供三类核心能力：
1. 轻量检索：list/search/id 三种模式快速查询书库元数据，返回结构化 JSON；
2. 单本深度分析：通过 run_analysis_pipeline.py 执行「导出→AI分析→缓存→回写 comments」的完整工作流；
3. 会话内自然引用：当用户闲聊中提到某本书时，自动触发轻量 lookup，确认馆藏状态。
显著优点
- 严格只读隔离：目录查询与 comments 回写分离，title/authors/tags/series 等核心元数据编辑被强制路由至
calibre-metadata-apply，避免误操作； - 异步非阻塞：重分析任务委托子代理（subagent），主代理在 Turn A 立即返回进度，Turn B 通过 completion 事件触发结果应用，聊天会话零等待；
- 企业级连接弹性：支持多主机故障转移（
CALIBRE_SERVER_HOSTS）、自动读取.env认证、WSL 主机发现； - 缓存与幂等：SQLite 缓存分析结果，基于内容哈希避免重复计算；
- 多语言适配：通过
--lang参数控制生成书评的语言，不硬编码文案。
潜在缺点与局限性
- 单本串行：一次仅处理一本书，批量分析需外部编排；
- 依赖外部服务：需预先启动 Calibre Content Server，且对网络连通性敏感；
- 环境门槛高：必须同时满足 Node、Python (uv)、calibredb、ebook-convert 四位运行时；
- 漫画/图像书排除：title/tags 含漫画特征时自动跳过文本分析，可能误伤图文混排书籍；
- 子代理配置复杂：首次会话需确认 model/thinking/timeout，对新手不够友好。
适合人群
- 已部署 Calibre Content Server 的资深电子书收藏者；
- 希望通过 AI 自动生成书评摘要并沉淀到书库元数据的自动化爱好者；
- 熟悉 Node/Python 工具链、能接受命令行配置的技术用户。
常规风险
- 认证泄露：密码通过环境变量传递，若
.env权限设置不当存在泄露风险； - 子代理超时：长文本分析可能触发
runTimeoutSeconds，导致任务僵死需人工重试； - comments 覆盖：回写操作会覆盖原有 comments 字段，建议先行备份；
- 网络分区：主代理与 Content Server 之间的连接中断会导致分析结果无法回写，需依赖状态文件重试。