Librarian

📚 librarian

将任意电子书转换为整洁、统计 Token 数量的 Markdown 章节——通过 MCP 让 Claude 阅读你的书架，并发现它误引书籍内容的情况。确定性 RAG：无需嵌入、网络或 API 密钥。

任何输入格式——FB2、EPUB、DOCX、HTML、TXT/MD、带文本层的 PDF——都会转换为包含整洁章节和 Token 数量的目录。无需网络、大模型或随机性：相同输入始终会生成字节完全一致的输出。

安装

uv tool install librarian-cli
# or: pipx install librarian-cli

离线约定：安装和运行均无需网络（分词器词汇表已随软件包提供）。

快速开始

lib ingest examples/*.epub
lib list
lib find curiouser
lib get <book-id> --budget 3000

命令

命令	用途
lib ingest <files…> [--force] [--no-keep-source] [--config cfg.toml] [--verbose]	将书籍处理到书库中；打印文件 · ID · 状态 · 评分表。
lib list [<book-id>]	不带参数——列出所有书籍；带 ID——列出该书的章节（编号、标题、Token 数量、摘要）。
lib get <book-id> <spec>	按范围（1-3,7）将章节打印到标准输出。
lib get <book-id> --budget N [--from K]	从 K 开始，贪心地打印连续章节，直到 Token 总数达到 N。
lib find <query> [--limit 10] [--book <id>] [--reindex] [--json]	在整个书库的章节、标题和作者中进行全文搜索（bm25、片段、俄语/英语词干提取）。
lib info <book-id>	JSON：书籍元数据 + 质量指标。
lib doctor [<book-id>]	不带 ID——列出待审核书籍和损坏的目录；带 ID——生成该书的报告。
lib reingest --all [--config cfg.toml] [--verbose]	使用当前代码/配置从 source/ 重建书库。
lib rm <book-id>	删除一本书并重建索引。
lib serve [--library <path>]	在书库上运行基于标准输入/输出的 MCP 服务。
lib verify "quote" [--book ID] [--json] [--limit N]	对照一本书核查引文，或在整个书库中确认其出处。

书库根目录：--library <path>（或 LIB_HOME 环境变量，默认为 ./library）。数据写入标准输出，诊断信息写入标准错误。退出代码：0 成功，1 运行时错误，2 用法错误。

让 Claude 阅读你的书架

librarian-cli 内置了一个基于标准输入/输出的 MCP 服务，提供 6 个只读工具——list_books、list_chapters、find、get_chapters、book_info、verify_quote——Claude 可以浏览目录、搜索书籍、在 Token 预算内获取章节，并自行核对引文与原文：确定性 RAG，无需嵌入、网络或 API 密钥。

Claude Code：

claude mcp add librarian --env LIB_HOME=$HOME/books -- uvx librarian-cli

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "librarian": {
      "command": "uvx",
      "args": ["librarian-cli"],
      "env": { "LIB_HOME": "/path/to/books" }
    }
  }
}

验证引文

一个能发现 Claude 错误引用你书籍内容的 MCP 服务。

lib verify "quote" 会检查引文是否确实原文出现在你的书库中；标点、大小写、ё/е 和 Markdown 格式不计入比较。支持两种模式：

• 书籍模式（--book <id>）：完整扫描一本书——“这本书确实这么说了吗？”无需搜索索引即可使用。
• 书架模式（不指定 --book）：通过 FTS5 候选项在整个书库中查找出处——“这段引文出自哪本书？”引文至少需要 5 个有意义的词（不计停用词），否则会跳过检查，返回 verdict: null。

lib verify "Рукописи не горят" --book bulgakov-master-i-margarita
lib verify "рукописи не горят никогда"

verdict	含义
exact	规范化后匹配（标点/大小写/ё/排版不计入比较）
close	相似度 ≥ 0.95——几乎完全匹配，差异会以逐词对比的形式显示
distorted	相似度 ≥ 0.75——位置正确，但对引文的记忆有误
not_found	相似度 < 0.75——在书籍/书库中找不到类似内容
null	未运行检查：引文为空，或未指定 --book 的短引文

退出代码（类似 grep 的语义，有意偏离项目通常采用的“1 = 运行时错误”规则——参见 docs/MILESTONES.md 中的偏差 38）：

退出码	情况	stdout
0	exact / close——已确认引文	完整报告 / JSON
1	distorted / not_found——未确认引文	完整报告 / JSON
1	运行时错误（未知书籍 ID、无搜索索引、索引已锁定）	空
2	用法错误：引文为空/过短（verdict: null）、--limit < 1	空（错误消息输出到 stderr）

脚本判别规则：退出码为 1 且 stdout 非空表示“已检查，但未确认”；退出码为 1 且 stdout 为空表示发生错误（诊断信息输出到了 stderr）。退出码 0 包含 close——严格的 CI 门禁必须检查 --json 输出中的 verdict == "exact"，不能只看退出码。

质量

每本书都会根据五项指标（覆盖率、结构、垃圾内容、编码、连字符处理）获得一个分数：ok（分数 ≥ 0.90，且没有硬性触发项）——静默保存；review（0.60 ≤ 分数 < 0.90，或存在触发项）——保存并发出警告，详情可通过 lib doctor <id> 查看；failed（分数 < 0.60）——不予保存。扫描版和受密码保护的 PDF 会如实判定为失败（OCR 和 DRM 移除不在支持范围内）。

确定性

此流水线不访问网络、不调用大模型，也不使用随机数——同一输入文件始终会生成逐字节完全相同的输出。这使得导入过程可复现且可缓存，也让 lib serve 的 RAG 具备确定性：嵌入不会发生漂移，模型调用也不会导致每次运行结果不同。

局限性

• PDF：适用于排版常规的书籍；复杂版式可能会被标记为 review。
• 不会规避 DRM；源文件是否合法由用户负责。
• 不支持联网文件系统（NFS/SMB）（在这类文件系统上，建议锁不可靠）。
• 不支持 MOBI/DJVU 和没有文本层的扫描件（v3 候选功能：OCR、calibre）。
• CLI 消息目前为俄语；计划支持英语输出。
• lib verify：不支持跨章节的引文（v1）——最多只能在其中一半内容上得到 distorted。
• lib verify：引文长度约为 150 个字符时，将单个词替换为其他词仍可能得到 close；对于较短引文，替换一个词会如实判定为 distorted——三词引文中有一个词被替换，确实属于失真。
• lib verify 书架模式（不指定 --book）需要 FTS5 搜索索引；CLI 的书籍模式（--book <id>）无需该索引。lib serve 整体仍需要 FTS5——无论调用哪个工具，启动时都会同步索引。
• lib verify 书籍模式会使用纯 Python 扫描整章文本；较长的书籍可能需要几秒钟的 CPU 时间。MCP 工具会在线程中运行，不会阻塞服务的其他部分。

俄语版

俄语文档请参阅 README.ru.md。