企业官网建设流程全解析

book-to-skill：如何把 500 页技术书编译成按需加载的 Agent 技能，查询 token 省 24×–51×

【免费下载链接】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 是一个书籍转技能（book to skill）转换器，把 PDF、EPUB、DOCX 等技术书与文档编译成可被 Agent 按需加载的 SKILL.md 技能，面向用 Agent 编程的开发者：Agent 从真实章节内容作答，token 账单只付一次，之后按答案大小计费。

📍 场景切入：Agent 答不出书里的问题，通常卡在哪

你买过一本好书，通读一遍，三个月后连"第 7 章讲了什么"都想不起来。此时常见的三条补救路，每一条都卡壳：

• 搜 PDF：搜出来的是页码列表，不是答案，还得自己翻回去读；
• 问 Agent：它没有这本书的内容，要么编造（幻觉），要么承认自己不知道；
• 自己记笔记：攒出一份 200 行的文档，之后再没打开过。

book-to-skill 的走法不一样：把书编译成一份结构化技能（SKILL.md+ 章节文件），装进 Agent 的技能目录。之后你输入/你的书名 关键词，Agent 自己读对应章节文件，从书里的真实内容作答。书不再是躺在硬盘里的死文件，而成了工作流的一部分。

🚀 五分钟上手：两条命令跑通第一条转换

安装分两条路径，官方文档特意提醒别混淆：装成Agent 技能（得到/book-to-skill斜杠命令）要走 clone；用pip装的是纯文本提取引擎，不会注册技能（详见 docs/install.md）。

技能路径，任选其一：

# 方式 A：跨宿主一键安装，自动装进各 Agent 的技能目录 npx skills add virgiliojr94/book-to-skill # 方式 B：手动 clone（以 Claude Code 为例） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill ~/.claude/skills/book-to-skill

然后开一个 Agent 会话，指向你的书：

/book-to-skill ~/path/to/book.pdf my-book

转换会问你书是"技术型"还是"文字为主"、用途是什么，给出 token 与时间预估，你确认后开始生成。只想要提取引擎做脚本处理的话，pip可以直接从仓库装（包名book-to-skill，带[pdf,epub,docx]扩展），命令细节见 docs/install.md。环境没配齐也不怕，一条命令预检：

python3 scripts/extract.py --check

它按格式报告每种提取器"已装 / 缺失 / 补齐命令"，不需要任何输入文件。

🔍 机制拆解：四个值得看懂的设计

这一节回答"它凭什么做到"，每个机制按"是什么 → 为什么 → 仓库证据"展开。

3.1 提取作者的"工具箱"，而不是写读后感

机制：技能不是章节复述，而是从书中提取四类东西——命名框架（带适用场景的思维模型）、可执行原则（决策规则）、逐步方法、反模式（要避免什么、为什么）。SKILL.md质量规则还要求保留作者的确切表述："The 5 Whys"不能写成"多问几次为什么"，因为框架往往因特定原因才有那个特定名字。

为什么：摘要丢掉的恰恰是价值最高的部分——作者用多年实践结晶出的、可以被反复套用的结构。所以生成规范明确"绝不复制原文段落"，输出物应像你自己的手写学习笔记。

仓库证据：SKILL.md 的 Philosophy 与 Quality Rules 部分；docs/performance.md 记录了 v1.0.0 自适应深度改版前后同一章的对照——章节文件从 473 tokens 涨到 1,219 tokens、补上了实操示例，cheatsheet 的决策规则从 0 条增到 32 条，而"裸术语→定义"行从 9 条降到 0，说明 cheatsheet 被刻意做成了"决策层"而非第二份术语表。

3.2 章节按需加载：账单跟着问题走，不跟着页数走

机制：转换产物是一组文件——主SKILL.md（核心框架 + 章节索引，约 4,000 tokens）、chapters/下每章一个独立文件（各约 1,000 tokens）、glossary.md（约 1,500）、patterns.md（约 2,000）、cheatsheet.md（约 1,000）。章节文件只有被问到对应主题时才会被读入上下文，200 页的书，问一个主题只花约 5,000 tokens。

为什么：上下文压缩（compaction）通常从末尾截断，所以规范把最重要的内容前置进SKILL.md头部（front-loaded 设计）；而"按章拆分"让查询成本与答案成正比，与书的总页数脱钩。每章的 token 预算按两个维度自适应：技术书 + 研读深度最高给到 2,000–3,000 tokens，文字书 + 快速查阅只要 800–1,200 tokens（矩阵见 SKILL.md Step 7）。

仓库证据：README.md "What it generates" 一节给出各文件体量；docs/architecture.md 设计原则第 3、4 条（按需章节、前置式 SKILL.md）直接描述该机制。

3.3 流水线一分为二：确定性提取器 + 规范驱动的生成器

机制：系统一半是纯 Python 的确定性提取器（文档 → 干净文本 + 元数据，输出full_text.txt和metadata.json），另一半是生成器——你的 Agent 遵循SKILL.md里 Step 0–10 的规范，把文本变成结构化技能。前者可复现、可测试，后者需要语义理解，职责切得很干净。

为什么：把"不可出错的部分"（文本抽取、章节检测）与"需要智能的部分"（提炼框架、写摘要）分开，前者可以用测试锁死行为。一个容易忽略的细节：工作目录是每次运行唯一的<tempdir>/book_skill_work-<pid>/——历史上所有运行共享一个固定路径，后完成的提取会静默覆盖先前的输出，Agent 轮询到"另一本书"的元数据就构建了错误技能。现在以 PID 命名，并发互不干扰，BOOK_SKILL_WORKDIR环境变量仍可完全覆盖。

仓库证据：docs/architecture.md 的流水线图与组件表；book_to_skill/config.py 里default_output_dir()的注释完整记录了这次事故。同一文件还把 token 估算分成两套系数：空白分词的拉丁文本 0.75 词/token，而 CJK 几乎没有空格、按词分会严重低估，单独取 1.5 字/token。

3.4 从文档到 Agent 的三道关：看不见的指令进不来

机制：一份不可信文档会先进入 Agent 上下文，再流进生成出的技能，之后被别的 Agent 加载——这是一条"文档 → 上下文"的供应链，项目按三道关加固：

1. 提取时净化：每个解析器的输出在进入统计与full_text.txt前，剥离零宽字符与 Unicode 标签块，防止文档夹带的不可见指令抵达 Agent；净化后无任何可见内容的源直接拒收；
2. 解析器层防御：DOCX 解析前拒绝任何声明了 DTD 或实体的 XML 部件（防 XXE / 十亿笑声攻击）；文件路径在到达pdftotext等外部命令前先绝对化，防止-开头的文件名被当成命令行开关；
3. 生成后扫描：生成器规范里的建议性步骤，对产出的SKILL.md、章节文件、术语表等跑提示注入扫描，命中只报规则名与文件位置、绝不回显匹配文本，非零退出则停下交人工复核。

仓库证据：docs/architecture.md 的 Security 一节逐条列出；实现分别在 book_to_skill/sanitize.py、book_to_skill/parsers/docx.py 与 tools/scan_generated_skill.py。

📊 数据说话：省多少、花多少，数字都能复现

本节数字全部取自 docs/performance.md，用tiktoken（cl100k_base）实测计数、tools/discovery_tax.py建模，均可按文档给出的命令复现。

先回答"省多少"。下表统计的是回答一个目标问题需要进入上下文的 token 数（原表按书分行，这里改为按方案分行）：

两个关键判读：相对"整本灌入"省 24×–51×，且那份账单在每一轮对话重复发生；相对"翻找循环"省 2.4×–15.6×，那是一次性成本，随章节变大而放大。提取环节本身也有取舍：同一本 103 页技术书，pdftotext0.1 秒跑完但 0 表格 0 代码块；Docling 花 164 秒（约 1.5 秒/页），保住 48 个表格和 36 个代码块，token 数两者基本持平（27K vs 27K +1.2%）。

再回答"花多少"。一次完整转换（Claude Sonnet 4.5，按 $3/$15 每 MTok 输入/输出估算）：

平均约1 美元一本书，一次付清。想自己复现任意一本：

python3 tools/discovery_tax.py --full-text <工作目录>/full_text.txt --target-chapter 5

🧭 源码走读：六个值得先读的文件

• SKILL.md —— 生成器规范本体：Step 0（越界检查）到 Step 10（清理报告）的完整流程、四种操作模式、token 预算矩阵与质量规则；
• book_to_skill/parsers/ —— 每种格式一个解析模块（pdf、epub、docx、html、rtf、calibre、text），遵循"最优工具优先、stdlib 兜底"；
• book_to_skill/config.py —— 支持扩展名白名单、每次运行唯一的工作目录、中英文两套 token 估算系数、可选依赖映射；
• book_to_skill/sanitize.py —— 提取净化：剥离零宽与不可见 Unicode 字符，净化后空源拒收；
• tools/discovery_tax.py —— "发现循环税"测量器，性能文档里所有对比数字由它产出；
• tools/validate_skill.py 与 tools/scan_generated_skill.py —— 前者按宿主规则（--lens claude|copilot|amp|hermes）校验生成技能，后者做建议性注入扫描。

🤔 选型之前：四个最常被问的问题

问：直接把 PDF 塞进项目上下文不行吗？可以，但那是"每一轮、每一会话、永远"都在付全额 token 账单，而技能是摊还：付一次结构化成本，之后只加载相关切片。docs/faq.md 的结论值得记住——本质是摊还经济学，不是上下文大小问题；且原始文本注入是"检索"，技能是"推理"：加载章节文件时 Agent 用的是预提取的命名框架，不是关键词匹配。

问：1M 上下文窗口还不够大吗？窗口只改变"装得下"，不改变"更聪明"：每个 token 每次调用都计费；模型在接近满的上下文里检索特定事实的精度会下降（"lost in the middle"）；窗口也不等于结构——整本书每轮都要重新解析，而技能交付的是预提取框架。大窗口留给一次性材料，重复要用的知识做成技能。

问：这不就是 RAG 吗？工作时点不同：RAG 在查询时工作（分块 → 嵌入 → 相似检索 → 注入提示词），目标是"找到讲 X 的那段"；book-to-skill 在编译时工作，一次深度分析把作者的框架命名、描述适用场景、捕捉反模式。按任务形状选：几十本书的宽浅书库检索 → RAG 更合适；一两本要反复应用框架的书 → book-to-skill。docs/faq.md 的原话判断：RAG 索引一整个书架，book-to-skill 吃透一册书的书脊，二者互补。

问：热门书模型训练数据里就有，何必转换？训练数据是全网讨论的"压缩平均"，具体引文与章节位置可能幻觉；技能则锚定在你的真实副本上，每个框架名、每个章节号都出自你提供的文本。对模型完全陌生的内容——小众技术参考、公司内部文档、新近出版、译本——差距最大。

问：扫描版 PDF 为什么提取立即停止？扫描件是纯图像页、没有文本层，任何提取器都读不出内容。工具检查前几页就停下并说明原因，让你一秒失败，而不是处理完 400 页后得到一个空技能。先 OCR 再转换：

ocrmypdf input.pdf output.pdf

项目有意不自带 OCR（重依赖、慢且有损），图表里烘焙的文字在任何格式下都不提取。

📚 延伸路径：按你的目的挑一条读

• 想理解整体流水线与组件划分→ docs/architecture.md（含安全分层与"如何扩展新格式"）
• 想看生成器每一步的完整规范→ SKILL.md 与 docs/how-it-works.md
• 想复现 token 与成本数字→ docs/performance.md + tools/discovery_tax.py
• 想看全部输入形态与 fold-in 更新模式→ docs/usage.md
• 想在特定宿主安装（Copilot CLI / Amp / Codex / Hermes / Claude Code） → docs/install.md
• 想核对版权与公平使用边界（本地处理、输出是你的笔记、第三方版权书籍的技能保持私有） → README.md 末节
• 想看测试如何锁住行为→ tests/（提取、章节检测、发现税、扫描等测试套件）

book-to-skill 的不可替代之处只有一句话：它在编译期完成结构化，让一本书变成多宿主通用、按需加载、可以反复推理的框架资产——Agent 从此用作者的框架思考，而不是在原始页码里翻找。

【免费下载链接】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