book-to-skill 最近在 AI 工具圈里出现频率不低。它做的事情一句话就能说清楚：把一本技术书或一份长文档，转换成带结构的 Markdown 技能包，让 AI 在回答问题时只加载关键内容，而不是把整本书塞进上下文。项目标题里的“token 省 51 倍”，指的就是这种压缩方式带来的上下文开销变化。适合看这篇文章的人主要有三类：正在做 AI Agent 技能开发的人、想把团队文档整理成 AI 可用知识库的人，以及被大模型 token 成本困扰的深度用户。下面我会从它到底解决什么问题讲起，再拆解 token 为什么能省这么多，最后给出一条可以照着落地的实操链路和排查思路。
1. 先搞清楚它解决的是“塞不进去”和“读不起”两个问题
1.1 AI 上下文里的 token 到底是什么
大语言模型的“上下文”是受限的。模型一次能处理的文本量由上下文窗口决定，而窗口里的每个文本片段，都会被拆成 token 来计费和计算。中文里一个字可能对应一到几个 token，英文里一个单词大约是一个到两个 token。技术书的问题正好出在篇幅上：一本 300 页左右的技术书转成纯文本，几十万 token 是很常见的量级。
这个数字同时踩中两个痛点。一个是塞不下，模型的上下文窗口装不下这么多内容。另一个是读不起，即使硬塞进去，单次请求的 token 消耗和费用也会迅速飙升。所以很多 AI 工具面对整本技术书时，真正的问题不是“模型笨不笨”，而是“书根本进不了上下文”。
这里先区分一件容易混淆的事。日常开发中经常看到的“token 失效”“token 授权失败”“JWT 实现 token 续签”，指的是登录鉴权用的 access token。而这里讨论的 token，是大语言模型的计费和上下文单位。网络上很多 token 相关的报错，其实都属于前者。两者只是名字相同，背后的机制、使用场景和优化方式完全不同。book-to-skill 要省的是后者。
1.2 book-to-skill 的目标不是书摘要，而是可执行的技能描述
很多人第一次看到“把技术书变成 AI 技能”，会下意识理解成“给书做摘要”。这个理解差了一层。
摘要的目的是让人读完知道书里讲了什么；技能包的目的是让 AI 遇到具体任务时，能照着文件里的规则、步骤、代码样例和约束条件完成任务。换句话说，摘要面向的是“读完有印象”，技能包面向的是“照着做能出结果”。转换过程不是简单删减，而是把书里的知识重新组织成任务导向的内容。
这也是为什么输出格式经常是 Markdown。Markdown 轻量、可读、容易被模型解析。现在不少 AI Agent 平台都把技能文件定义为 Markdown，标题、列表、代码块、表格这些结构，能帮助模型分清哪些是规则、哪些是示例、哪些是参数。这和当前 AI Agent 技能开发的通用方式是一致的。
2. 51 倍 token 节省并不是玄学，它来自三层压缩
51 倍这个数字，第一次看到确实会觉得夸张。但拆开来看，一本技术书从原始文本到技能包，中间至少经过三层压缩。每一层去掉的内容，在具体任务里几乎都用不上。
2.1 第一层：去掉排版噪声
技术书转成纯文本后，第一层浪费在排版噪声上。页眉页脚、页码、目录、版权页、大段索引、交叉引用，这些内容对 AI 回答具体问题几乎没有帮助，却占着大量 token。第一遍清理时，可以直接删掉。
实际操作时，不要依赖简单的字符串替换。不同出版社的 PDF 排版差异很大，同一个正则规则很难一套跑完。更稳妥的方式是按页提取文本，看连续几页里哪些行反复出现，再判断它是不是页眉。目录和索引通常集中在书的前后位置，可以按位置批量清理，也可以通过关键词判断。
还有一个容易被忽略的来源：如果书原本是网页导出的 HTML，里面往往带着导航、页脚、上一篇下一篇之类的链接。这些内容在进入拆分之前就要先清理干净，否则会沿着章节拆分混进很多无关内容。
2.2 第二层：把章节内容改成任务导向
第二层压缩是内容重写。书里的一个章节可能用几千字解释一个概念，但真正支撑 AI 回答问题的是关键定义、约束条件和操作步骤。把“一段长解释”改写成“规则条目 + 注意事项 + 示例”，信息密度会明显提高。
我一般按这个结构处理每个章节：
- 章节标题和适用场景；
- 三到五条核心规则或结论；
- 关键参数或配置说明；
- 一个可以直接复制的命令或代码示例；
- 常见错误和对应处理方式。
这样处理后的一个章节，篇幅往往只有原来的十分之一左右。这一层是 token 节省的主要来源，也是最考验人的地方。如果只是把原文复制粘贴再删掉几句，省下来的 token 很有限。真正有效的做法，是根据书里会出现的真实任务反推，哪些内容值得保留。
2.3 第三层：保留代码样例和参数表，而不是转述解释
技术书里最值得保留的是代码、命令、配置文件、参数表和错误对照表。这些内容即使占一些 token，也应当尽量完整保留，因为 AI 生成答案时需要的是可直接使用的事实性参考，而不是二次转述。反过来，大段的背景介绍、历史沿革、概念对比，只保留结论就够了。
| 内容类型 | 处理策略 | 原因 |
|---|---|---|
| 命令、代码、配置文件 | 完整保留 | AI 需要直接可用的参考 |
| 参数表、选项说明 | 完整保留 | 回答参数类问题时不能缺失 |
| 概念解释、数学推导 | 压缩成结论 | 信息密度低，占用大 |
| 背景介绍、历史沿革 | 删除或一句话带过 | 对任务没有实质帮助 |
| 页眉页脚、目录、索引 | 删除 | 纯排版噪声 |
这个取舍没有统一公式。如果你面对的是一本工具书，代码和参数优先级最高；如果是一本算法书，核心公式和复杂度结论优先级更高。判断标准只有一个：AI 拿到这个技能包之后，用户最常问的那类问题，能不能从里面找到答案。
3. 实操流程：把一本 300 页的技术书变成技能包
3.1 前置条件
book-to-skill 这类转换任务的硬件要求不高。它主要做的是文本提取、清洗和结构化整理，CPU 和内存管够就能跑。如果输入是扫描版 PDF，需要 OCR，耗时会长一些，但普通笔记本也能处理。真正要提前确认的是输入格式。
| 输入格式 | 处理难度 | 常见问题 |
|---|---|---|
| Markdown | 低 | 几乎不需要清洗 |
| EPUB | 低到中 | 需要解包 XHTML，结构相对清楚 |
| HTML | 中 | 标签、导航、广告区块需要清理 |
| 中到高 | 文本流不稳定，扫描版还需要 OCR |
我的建议是，如果目标书有电子版，优先选结构清晰的来源，不要一开始就挑战扫描 PDF。依赖方面，常见做法是准备 Python 环境和几个处理库：PDF 解析用 PyMuPDF 或 pdfplumber，EPUB 处理用 ebooklib，HTML 解析用 BeautifulSoup，最后统一输出 Markdown。具体安装版本以你自己的环境为准。有的项目会封装好命令行工具，有的只给了一个处理思路，命令细节以项目文档为准。
3.2 提取文本并清理脏数据
第一步先跑单章。不要一上来就处理整本书。选信息量最大的一个章节，比如包含代码和参数表的那一章，先把它提取成文本，看清理之后大概是什么状态。这一步的目的是确认输入源的质量，而不是急着完成整本转换。
如果单章提取出来就有大量乱码、错位、表格丢失，说明整条链路还没建立。先解决提取和清洗，再继续。常见解决方法包括换一个 PDF 解析库、调整页面边距参数、或者换一个有文本层的 PDF 源文件。扫描版 PDF 必须先做 OCR，这一步绕不过去。
清理时至少做三件事：去掉连续出现的页眉页脚，去掉页码和目录占位符，去掉明显非正文区块。看到一份干净的文本后，再开始做章节拆分。
注意：扫描版 PDF 在没有文本层的情况下直接做后续处理，得到的只会是一堆空白或乱码。先确认这一层，不然所有后面的步骤都是在错误基础上打转。
3.3 按章节拆分
技术书的章节标题通常很明确，可以直接作为拆分点。把正文按章节切分成多个部分，每个部分作为一个独立单元处理。拆分之后做一次数量检查：一本 300 页左右的书大约十几到二十几个章节，结果应该和目录基本对齐。
如果某个章节特别长，比如占了全书三分之一，要考虑继续按小节拆分。不要一刀切。章节长度差异太大时，技能包内部的检索效率会下降。这里最简单的判断标准是：转换后的单章文件，能不能在保持信息完整的前提下，被快速扫一遍就理解。
3.4 结构化生成技能文件
对每个已拆分的章节，生成一个对应的技能文件。文件头部建议写清楚基础信息，方便模型识别，也方便人维护：
--- name: python-concurrency description: 提供 Python 并发编程相关的规则、代码示例和参数说明 source: 《Python 并发编程实战》第 2 版 when_to_use: 涉及线程、进程、异步、GIL 等问题时优先参考 ---这是一个示例结构，实际字段可以根据你的场景调整。正文部分放压缩后的规则、参数和代码样例。
如果借助大模型辅助生成，一定要给明确的压缩指令。比如“保留所有命令和参数，去掉背景解释，输出 Markdown 格式，不要扩展新内容”。否则模型很容易复述原文，甚至自己加例子，结果反而是增大了 token。
3.5 验证输出质量
转换完成不等于能用。先拿真实问题测试。把技能文件作为上下文或知识来源，问书里明确讲过的问题，看 AI 能不能按书里的规则回答。
建议至少覆盖三类问题。概念类问题，看回答是否完整；操作类问题，看步骤是否可执行；参数类问题，看数值和选项是否准确。任何一类回答不了，都要回到对应章节调整技能文件。不要只看一两个问题就判定成功，因为概念类问题通过，不代表参数细节没有丢。
4. 先跑单本书，再考虑批量转换
4.1 为什么必须先跑单任务
不要一开始就批量转换整个书架。原因有两个。第一，输入格式差异很大，没有经过单本验证的处理流程，很可能在某个文件上突然中断。第二，批量任务的失败成本高，一旦输出目录里混入错误文件，后面排查会花很多时间。
我习惯先挑一本结构简单、页数不超过四五百页的技术书，完整跑通提取、拆分、生成、验证四个环节。确认每个环节都稳定之后，再开始批量。这个过程不是浪费时间，是在帮你提前暴露格式问题。
4.2 批量转换时的文件命名和失败重试
批量处理时，输出文件命名要能对应回原书。推荐格式是“书名缩写_章节编号_章节名.md”。如果完全不重命名，几十本书处理完之后，你根本不知道某个技能文件来自哪个版本。
批量任务还要考虑失败重试。单本转换失败，不应该中断整个批次。建议记录每本书的处理状态：成功、失败、跳过。失败任务单独放到一个目录，等本批跑完再统一处理。日志里至少包含文件路径、错误类型和失败时间。
好的批量流程不是一次性全部跑完，而是尽量多跑成功、失败不遗漏、最后有汇总。这个思路适用于所有批量文档处理，不只是技术书转换。
4.3 输出目录和版本管理
技能文件处理完不意味着结束。原书如果更新版本，技能包也要跟着更新。建议在输出目录里保留原书元数据，比如书名、版本、处理日期，方便追溯来源。
如果是团队共同使用技能包，建议用版本控制管理技能文件。每次批量更新形成一个提交记录，新版本技能包效果变差时还能回退。这里最容易犯的错是只保留最新版，等发现新版回答质量下降时，旧版已经找不回来了。
5. 判断技能包好不好用，不能只看 token 数字
5.1 三个质量指标
token 从几十万降到几千，听起来很漂亮，但如果三个基本指标不过关，这个技能包就只是省了 token，丢了功能。
| 指标 | 验证方式 | 不合格表现 |
|---|---|---|
| 命中率 | 用书里明确有答案的问题测试 | AI 说“没找到”，但书里确实有 |
| 可执行性 | 把代码或命令拿到本地跑一遍 | 参数缺失、命令错误、步骤不完整 |
| 引用准确性 | 对比书中原文 | 结论和书不一致，疑似模型记忆发挥 |
验收时宁可多花时间做测试，也不要只检查文件大小。一次有效的验收，至少能发现几个具体问题。没有问题的概率很低。
5.2 技能包太大或太小
技能包太大，常见原因是保留了太多解释性文字，或者没按章节拆分。技能包太小，则可能是因为压缩过头，把关键参数和常用命令也删掉了。两种情况都要回到章节内容重新调整。
一个简单的判断方法：如果 AI 回答问题时经常说“书里没有提到”，但你确定书里有，说明技能文件里对应内容缺失。反过来，如果回答过于啰嗦、经常说废话，说明文件里噪声太多，可以继续压缩。
5.3 token 计费口径要统一
对比省了多少 token 之前，先统一口径。有的是按输入 token 计算，有的是按输入加输出计算；有的统计一整轮多轮对话，有的只统计单条请求。口径不一致，数字之间的比较没有意义。
book-to-skill 提到的 51 倍，更适合理解成一个量级参考，而不是每个场景的保证。实际收益取决于原书长度、压缩程度、提问方式、上下文里附带多少其他材料。不要拿着这个数字直接套到所有项目上。
6. 常见排查顺序和边界
6.1 转换后内容丢失或乱码
先看原始文件是什么格式。Markdown 类输入基本不会丢内容，PDF 类输入最容易出问题。排查顺序是：先确认 PDF 是文本层还是扫描图片，再确认提取工具是否正常工作，最后检查是某个章节出现的问题，还是全书普遍存在。
按“文件格式、提取工具、章节范围”这个顺序排查，比直接重新改算法要快。很多乱码问题，其实是解析库对某个字体或表格格式支持不好，换一个库就解决了。
6.2 AI 回答没有引用书里内容
先确认技能文件是否真的被加载到上下文里，再检查输入问题是否和技能文件内容匹配。如果文件已经加载，但回答依然不引用，就检查文件结构是不是太乱，导致模型没有把它当成权威来源。
一个比较有效的办法是在文件头部加一句使用说明，比如定义清楚“遇到相关问题时，优先参考本文件中的规则和代码示例”。这一步成本很低，但对模型行为影响很大。不要急着重新生成整个技能包，先加使用说明试试。
6.3 什么书籍适合，什么书籍不适合
比较适合的书籍有：工具书、官方文档、框架教程、语言速查、运维手册、配置指南。这类书结构清楚、规则明确，压缩后信息密度高。
不太适合的书籍有：长篇理论著作、散文式技术书、访谈录、图片为主的图册。图片类内容转成文本损失非常大，散文式内容压缩后容易丢失原意，访谈录本身也不是为任务执行设计的。
6.4 什么时候不要用这个方案
如果只是偶尔查一个问题，直接搜原书 PDF 可能比做技能包更快。如果书里大量内容是图片、图表、架构图，book-to-skill 很难完整保留。如果团队需要的是可追溯的原始出处，而不是压缩后的参考，那更稳妥的方案是保留原文配合检索。
这个方案真正适合的场景是：同一本技术书会被反复使用，AI 需要经常基于书中的规则完成任务，并且 token 成本已经成为实际负担。只有在这些前提下，花时间做技能包才划算。否则，你很可能是在为一件不需要频繁做的事情，付出一套过重的维护成本。
