核心用法
calibre-catalog-read 是专为 Calibre 电子书库设计的只读查询与 AI 分析技能。它通过 Node.js 和 Python 脚本组合，连接运行中的 Calibre Content Server，提供三种基础查询能力：列表浏览（list）、条件搜索（search）、ID 精确检索（id）。对于单本书籍，支持完整的 AI 阅读分析流水线：文本提取 → 子代理深度分析 → SQLite 缓存 → Calibre comments 元数据回写。
关键架构特点是主代理/子代理严格分离：主代理负责快速控制（验证意图、启动任务、返回进度），子代理承担耗时分析（内容理解、生成结构化评论）。聊天场景强制采用双回合异步模型——第一回合仅启动并返回 "running in background"，第二回合通过完成事件触发结果应用，避免阻塞聊天监听器。
显著优点
- 智能路由：ID 请求默认只读，仅当显式出现"修正/編集/変更/fix/edit"等动词时才路由至编辑技能
- 弹性连接：支持多主机故障转移（CALIBRE_SERVER_HOSTS）、自动解析 WSL nameserver、环境变量缺省加载
- 分析缓存：SQLite 持久化避免重复分析，支持哈希校验增量更新
- 生产级安全：密码环境变量隔离、Digest 认证方案、子代理超时与模型配置可复用
局限性与风险
- 依赖外部服务：必须预配置并运行 Calibre Content Server，本地 calibre-server 启动不在本技能 scope 内
- 单书串行：明确限制一次只处理一本书，批量场景需外部编排
- 文本提取门槛：依赖 ebook-convert，部分 DRM 或扫描版 PDF 可能无法提取
- 漫画/图像书排除：pipeline 自动跳过 manga/comic 标签书籍，此类内容无法使用分析功能
- 网络可达性敏感：WSL/容器场景下 HOST:PORT 必须显式可达，localhost 假设被禁止
适合人群
个人电子书收藏者、小型图书馆管理员、Calibre 重度用户，需要将 AI 生成的书籍摘要/评论自动沉淀到元数据库中。特别适合拥有数千册以上藏书、希望"让 AI 先读一遍"建立可检索评论档案的高级用户。
常规风险
- 子代理长时运行可能因内容长度或模型响应慢而超时，需预先确认 timeout 配置
- 回写 comments 属于"远程数据修改"（非目录只读），虽在设计上接受但需用户知情
- 多用户共享 Content Server 时，需确保 CALIBRE_PASSWORD 权限边界清晰