核心功能与用法
mycroft 是一款面向 EPUB 和电子书的专业 CLI 工具，专注于将电子书内容转换为本地可查询的向量知识库。其核心工作流分为三个阶段：导入（ingest）→ 索引（index）→ 查询（query）。
导入与索引
用户通过 mycroft book ingest 将 EPUB 文件解析为结构化文本块，系统使用 OpenAI 的嵌入模型生成向量表示并存储于本地。工具提供两种成本优化模式：
- 标准模式：实时调用 API，即时完成索引
- 批处理模式（--batch）：利用 OpenAI Batch API 降低 50% 成本，但结果延迟可达 24 小时
可选 --summary 参数会为每个文本块生成 AI 摘要，显著提升后续检索质量，但会大幅增加时间和 token 消耗。
查询与交互
完成索引后，用户可通过三种方式与书籍交互：
1. `book ask`：直接向书籍提问，由 LLM 基于检索到的相关片段生成答案
2. `book search`：仅返回语义相似文本片段，不经过 LLM 合成，成本更低、可控性更强
3. `chat` 会话模式：支持多轮对话的 REPL 环境，保持上下文连续性
断点续传与容错
工具内置完善的任务恢复机制：标准导入中断后可 resume 从最后保存的块继续；批处理任务失败后自动重新提交。ingest status 提供实时进度监控。
显著优点
| 维度 | 优势 |
|------|------|
| **成本效率** | 批处理模式提供业界少见的 50% API 成本削减方案 |
| **数据主权** | 向量索引完全本地存储，原始书籍内容不落第三方云端 |
| **模块化设计** | search/ask/chat 分层清晰，用户可按需选择自动化程度 |
| **生产级健壮** | 断点续传、状态监控、强制非交互模式（--force）适合 CI/CD 集成 |
潜在局限与风险
硬性依赖：全程依赖 OpenAI API，无离线嵌入模型支持。这意味着：
- 必须持有有效的 OPENAI_API_KEY
- 无法完全离线运行
- 存在供应商锁定风险
成本陷阱：--summary 与批处理模式的组合使用逻辑复杂（摘要先批处理，嵌入后恢复），文档提示不够醒目，新手易误操作导致意外费用。
隐私边界：虽然向量数据本地存储，但导入和查询时的原始文本仍需传输至 OpenAI 服务器进行嵌入和补全，敏感内容存在泄露风险。
功能边界：专注 EPUB 格式，PDF、MOBI 等需外部转换；不支持多书籍联合查询或跨书籍知识图谱构建。
适合人群
- 研究者与学者：需要高频检索大量电子书的文献内容
- 技术写作者：构建个人知识库，快速定位参考资料
- 开发者：寻求可脚本化的文档处理 pipeline，集成至自动化工作流
- 成本敏感用户：愿意用时间换成本，接受批处理延迟
常规风险提示
- API 费用失控：批量导入大型书籍集时，务必先测试单本成本；开启
--summary前估算 token 消耗 - 会话隔离：
chat会话 ID 需手动管理，重启终端后需重新指定 session 继续对话 - 索引损坏：异常中断后
resume可能因底层文件损坏失败，建议定期备份mycroft config path指向的数据目录 - 模型漂移：OpenAI 嵌入模型版本更新可能导致同一书籍重新索引后向量空间不一致，影响检索稳定性
---
评估结论：功能聚焦、架构清晰的专业工具，适合已深度使用 OpenAI 生态的技术用户，非技术用户或隐私极度敏感场景需谨慎评估。