企业官网建设流程全解析

book-to-skill 完整选型指南：为什么"一次约 1 美元的转换"胜过大窗口的整书塞入

【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill

一句话定位：book-to-skill 把任意一本技术书（PDF、EPUB 等）编译成一个按需加载的结构化 Agent Skill，让后续每次会话只为真正用到的那几千 token 付费。

读完你能带走三样东西：一张"手里有书、想让 Agent 可靠地用它时该选哪种交付方式"的决策表；决策表背后每一格的实测成本数字；以及它刻意不做什么（扫描版 PDF、图内文字）以及为什么必须这么做。

怎么选：六种交付方式的决策表

结论先摆在这里。当你想"让 Agent 用上这本书"时，六种方式的分工如下：

下面三条轴分别回答这张表背后的三个问题：钱花在哪、边界在哪、谁和谁各管什么。

成本轴：贵的不是"书大"，而是"每轮都在付费"

一次性编译成本：大约一本书一美元，一次付清

转换的完整成本 = 提取 + 生成 Skill。按 docs/performance.md 中 Claude Sonnet 4.5 价格（$3/$15 每 MTok）估算：Think Python 2 约 $0.88、Working Backwards 约 $0.96、Pro Git 约 $1.23、Moby-Dick 约 $1.42。口语化地说：大约一本书一美元，一次付清，换回来的是之后每次使用都只用零头。

每轮成本：24×–51× 的差距来自"账单重复次数"

回答一个针对性问题需要进上下文的 token 数，tools/discovery_tax.py 对真实书籍文本实测如下：

book-to-skill 一侧的 ~5,000 = 常驻核心 SKILL.md（约 4K）+ 一个预编译章节（约 1K）。注意两个关键差异：

• 整书倾倒的账单每轮都重复。200K 的上下文不是付一次，而是"每一轮、每一次会话、永远"。这才是 24×–51× 这个数字的本质——它比的是摊销次数，不是体积。
• 连"聪明的在线翻目录"也省：发现循环（Agent 自己读 ToC、拉章节、必要时回溯）是一次性成本，但它随章节变大而膨胀（12K → 78K），而 Skill 一侧基本恒定。

为什么能恒定？因为章节是按需加载——在被问到之前不占预算。SKILL.md 的 Quality Rule #6 原话："Chapter files are on-demand — they don't count against skill budget until loaded"；生成规范还要求 SKILL.md 头部放最核心内容（主题索引负责导航到正确的章节文件）。

常见误区 → 事实

误区："Claude 现在有 1M token 窗口，整本书一直挂着不就行了？"

事实：更大的窗口改变的是"装得下什么"，不是"什么更聪明"。三个不可替代的理由：按 token 按调用付费，1M 窗口只是让一张持续产生的大账单成为可能；recall 随填充度退化（"lost in the middle"），一个 1K 的精选章节在单问题上胜过 200K 原始散文；窗口 ≠ 结构——整本书在上下文里仍是每轮都要重新解析的原始文本，而 Skill 交付的是预提取的框架。

我的建议是分工明确：一次性扫过、以后再也不碰的材料用大窗口；会反复取用的知识做 Skill。窗口解决"装得下"，不解决"每轮都贵"和"召回退化"。

边界轴：它处理不了什么，以及为什么必须这么设计

扫描版 PDF：前 5 页的廉价预检，一秒内失败

⚠️ 扫描版 PDF 是一叠页面图像，里面没有文字层。所有提取工具读的都是文字层，所以无论跑哪个工具，扫描版都提不出任何内容。

book-to-skill 的行为是：检查前几页，然后在那里停下来并解释原因。这不是故障，而是设计。book_to_skill/parsers/pdf.py 中的looks_image_only只做一次廉价探针：

subprocess.run(["pdftotext", "-f", "1", "-l", str(pages), ...]) # 只读前 5 页

意图写得很直白：让扫描版"一秒内失败"，而不是对 400 页书跑完整条提取链后得到一个空 Skill。命中时抛出 book_to_skill/exceptions.py 中定义的ExtractionError——它被明确设计为"按源失败、批量安全"：批量转换时一个坏源被跳过并警告，其余源继续处理。错误信息本身可操作：直接给出ocrmypdf input.pdf output.pdf的修复指引。测试侧也钉死了这个行为：tests/test_book_to_skill.py 断言探针只查前 5 页、异常文本同时包含scanned与ocrmypdf字样。

为什么不自带 OCR：给所有人加一条又慢又有损的依赖，不值

先讲后果，再讲意图：若内置 OCR，意味着给每个用户引入一个重量级依赖和一条又慢又有损的流水线步骤，而受益的只是一小部分持有扫描版的用户——且这个场景专用工具（ocrmypdf）处理得更好。这一点在依赖层可见：book_to_skill/dependencies.py 的可选依赖探测覆盖 PDF 链的 pdftotext / pypdf / pdfminer.six / docling 四者，不含任何 OCR 引擎；README.md 的 Requirements 段落也只列这些工具，并直接把扫描版列为"需要用户先动手"的场景。同理适用于图片：图表、示意图里烘焙进位图的文字，从任何格式中都不会被提取——这是跨格式的统一策略，而非某个解析器的疏漏。

图内文字：EPUB 超 5 张图就提前报警

与其默默丢内容，不如把损失说破。book_to_skill/parsers/epub.py 的count_epub_images统计归档内图片数量，book_to_skill/utils.py 在超过 5 张时打印警告（"contains N image(s); their content is not extracted"），生成的 Skill 的 Scope & Limits 段也会声明这些源图片未被读取。选型时看到这类声明，别当 bug 报——它是设计边界。

常见误区 → 事实

误区："提取一停就报错，是不是工具坏了？"

事实：停下本身就是正确行为。它的价值恰在于尽早告诉你这条路走不通，且失败只花一秒钟。一个静默跑完 400 页、最后交付空 Skill 的工具才是坏工具。

分工轴：RAG、训练数据、NotebookLM 各管什么

RAG：它管书架索引，Skill 管单本精熟

RAG 在查询时工作：切块 → 嵌入 → 找相似向量 → 注入提示词，优化目标是"帮我找到讲到 X 的那部分"。book-to-skill 在编译时工作：一次深度分析，提取作者真正构建的框架、为它们命名、描述使用时机、捕获反模式。两句对照能说明分水岭：

RAG 的答案："这里有一些接近你查询的块。" Skill 的答案："这是这位作者构建的 12 个框架，随时可以拿来推理。"

按任务形态选：宽而浅（几十本书的库、按关键词定位）→ RAG 胜出；窄而深（一本书或多份紧密相关资料、工作时要应用其框架）→ book-to-skill 胜出。二者是互补，不是竞争：RAG 给整个书架建索引，book-to-skill 吃透一本书的书脊。"编译时"的性质在产物上看得见：SKILL.md 生成规范要求 cheatsheet 优先收录决策规则（"When X, do Y, because Z"）、决策树、权衡矩阵与识别信号，并明确避免裸的术语定义行——存的是作者的判断，不是对句子的相似度索引。

训练数据：模型的记忆 vs 你手上的副本

误区："Clean Code、DDIA 这些名著模型训练时肯定见过，再转换不是多此一举？"

事实：模型确实有通识，但那是被压缩、被整个互联网对这本书的讨论平均化过的版本，对具体引文和章节位置可能产生幻觉。

book-to-skill 以你手上的实际副本为准：每个框架名、每条反模式清单、每个章节号都锚定在你提供的文本上——没有训练数据漂移，没有幻觉出来的章节标题。生成规范对这种引用纪律有硬性要求：Step 2.6 要求对大书用 REPL 式访问（grep/sed按需拉章节，而非整文件读取），生成前用grep -c验证某个框架是否真的出现在书中；Quality Rule #7 规定绝不复制书的原始文本，永远综合、总结、提取信号。它尤其擅长处理模型完全不了解的书：小众技术参考、公司内部文档、近期出版物、翻译作品。

NotebookLM：跨书搜索 vs 单点深耕

如果工作流是"我有 80 本互不相干的书、想跨全部书目搜索"，NotebookLM 是正确工具，不必勉强。book-to-skill 为另一类任务而生：在某个特定主题上深入钻研，把多份相关文档（论文、章节、笔记）折叠进一个统一的 Skill，并随新材料到来持续更新——把定制知识库直接整合进编码或写作工作流，而不是放在一个单独的浏览器标签页里。这条"多文档融合 + 持续更新"能力有明确实现：SKILL.md 定义了四种操作模式，其中Mode 4: Update / Fold-in专门把新来源折叠进已有 Skill——新章节从现有最大章节号之后继续编号，glossary 合并后重新排序，SKILL.md 中递增章节数并更新主题索引。

选型准则：何时用、何时别用、何时自己动手

何时用 book-to-skill：这本书你会反复取用——倾倒的每轮持续账单迟早超过一次性转换成本；或者你有一组紧密相关的资料要"应用其框架"而非"检索其句子"。

何时别用：材料只用一次（大窗口直接扫）；书目宽而浅（RAG）；需要跨全部书目搜索（NotebookLM 类）。大窗口是"一遍过"场景的好工具，不是 Skill 的替代。

何时要自己动手：⚠️ 扫描版 PDF 先ocrmypdf input.pdf output.pdf再转换；图表、示意图里的文字从任何格式都不会被提取，这类图请自行整理进笔记。这两条是工具的设计边界，不是缺陷。

关于版权：book-to-skill 不随附任何书籍内容，处理全部本地进行；产出的 Skill 是结构化的综合衍生品（Quality Rule #7 禁止复制原文），第三方受版权保护的书的 Skill 应保持私有，只有你自己的写作或开放许可内容才允许公开（详见 README.md 的 Copyright & fair use 章节）。

延伸阅读

• docs/performance.md — 实测 token 成本、发现循环税的完整方法论与复现命令
• docs/how-it-works.md — Steps 0–10 完整工作流与批量容错行为
• docs/install.md — 各宿主安装与可选提取器清单

【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill