1. 这个项目到底在解决什么问题先说一个我自己的真实场景。去年我花了大概三周时间啃一本讲分布式系统设计的书边读边在笔记软件里记了上百条摘录读完那一刻感觉自己懂了。结果两个月后项目里要设计一个幂等重试机制我脑子里只剩一个模糊的印象——“那本书里好像讲过”具体怎么落地、有哪些坑全忘了。翻笔记笔记是死的搜关键词搜出来的是一堆孤立段落没有上下文没有可执行的步骤。最后我还是重新翻了一遍原书相关章节等于白读。这个痛点我相信不止我一个人有。技术书的特点是信息密度高、逻辑链条长、概念之间有依赖关系但人的记忆是线性的、易衰减的。传统的“读书-记笔记-复习”流程本质上是在用人力对抗遗忘曲线效率极低。而book-to-skill这个项目做的事情就是把这套流程自动化把一本 PDF 技术书丢进去它帮你把书里的知识“编译”成一个 Agent 可以随时调用的 Skill。这里需要先解释两个核心概念不然后面没法聊。什么是 Agent你可以把它理解成一个能自主执行任务的 AI 程序。它不只是聊天它能读文件、能调用工具、能按步骤完成一个复杂流程。比如你让它“帮我分析这份日志里的异常”它会自己去读文件、自己写脚本过滤、自己总结结论。什么是 SkillSkill 是 Agent 的能力单元。一个 Agent 可能有很多 Skill每个 Skill 封装了一类特定任务的知识和操作流程。比如“PDF 解析 Skill”、“代码审查 Skill”、“数据库查询 Skill”。Skill 的本质是结构化的、可执行的领域知识——它不是一段说明文字而是 Agent 能直接加载、理解、并按步骤执行的操作手册。所以 book-to-skill 的核心价值就清楚了它把一本非结构化的、面向人类阅读的 PDF 技术书转换成结构化的、面向 Agent 执行的 Skill 文件。读完就忘不存在的。因为知识不再存在你的脑子里而是存在 Agent 的 Skill 库里你需要的时候直接调用Agent 会按照书里的方法论帮你干活。这个项目在 GitHub 上拿了 15k Star说明它戳中的是一个普遍需求。适合谁来用三类人一是经常需要查阅技术手册但记不住的开发者二是想把团队内部文档、规范、SOP 转化成 Agent 能力的工程团队三是任何想让 AI 真正“学会”某本书而不是“读过”某本书的人。2. 核心设计思路拆解为什么是“编译”而不是“检索”很多人第一反应是这不就是个 RAG检索增强生成吗把 PDF 切块、向量化、存进数据库提问的时候检索相关段落喂给模型。这个思路没错但 book-to-skill 走的是另一条路而且我认为这条路更适合技术书这个场景。2.1 RAG 的局限与技术书的特殊性RAG 的本质是“检索-拼接-生成”。它的假设是知识可以被切成独立的块每块之间没有强依赖。这个假设对新闻、百科、客服问答是成立的但对技术书不成立。技术书的知识是有向图不是散点集。比如一本讲 Transformer 的书第一章讲注意力机制第二章讲多头注意力第三章讲位置编码第四章讲训练技巧。你问“怎么做多头注意力”RAG 可能检索到第二章的段落但那段话里引用了第一章的“缩放点积注意力”公式而 RAG 不会自动把第一章的内容也带进来。结果就是模型拿到了一段不完整的上下文生成的回答缺胳膊少腿。更关键的是技术书里的知识往往是过程性的不是陈述性的。陈述性知识是“是什么”过程性知识是“怎么做”。RAG 擅长检索“是什么”但对“怎么做”这种需要步骤、参数、顺序的知识检索出来的碎片很难拼成可执行的流程。2.2 “编译”思路的核心从阅读材料到执行手册book-to-skill 的做法是“编译”。这个词用得很准。编译器的输入是源代码输出是可执行程序book-to-skill 的输入是 PDF 书输出是 Agent 可执行的 Skill。编译过程分几个阶段我按自己的理解拆一下第一阶段结构解析。不是简单地把 PDF 转成文本而是要识别出书的结构——章、节、小节、代码块、图表、公式、脚注。这一步决定了后续知识组织的骨架。技术书的目录结构本身就是作者精心设计的知识地图丢掉这个结构就等于丢掉了半本书的价值。第二阶段语义抽取。在结构的基础上识别出每个知识单元的类型是概念定义、是操作步骤、是参数说明、是注意事项、还是示例代码。不同类型的知识在 Skill 里的表示方式完全不同。概念定义变成知识条目操作步骤变成执行流程参数说明变成配置表注意事项变成约束条件。第三阶段依赖分析。这是最容易被忽略但最关键的一步。技术书里的概念之间有依赖关系比如“多头注意力”依赖“缩放点积注意力”“位置编码”依赖“词嵌入”。编译过程要建立这些依赖的图结构这样 Agent 在执行某个 Skill 时如果发现前置知识缺失可以自动回溯加载。第四阶段Skill 生成。把前面三步的结果组织成 Agent 能理解的格式。这个格式通常是结构化的 Markdown 或 JSON包含元信息Skill 名称、描述、适用场景、知识主体概念、步骤、参数、依赖声明前置 Skill、示例输入输出样例。2.3 为什么这个设计更优对比一下 RAG 和 book-to-skill 在技术书场景下的表现维度RAG 方案book-to-skill 方案知识组织扁平向量库块之间无显式关系结构化 Skill显式依赖图检索方式相似度匹配可能召回不完整按 Skill 调用自动加载依赖过程性知识碎片化难以拼成步骤编译为执行流程顺序明确更新维护重新切块向量化成本高增量编译只更新变化章节Agent 使用每次都要检索拼接token 消耗大一次加载 Skill后续直接执行我实测下来的感受是RAG 适合“问答”book-to-skill 适合“干活”。你问它“什么是注意力机制”两者都能答但你让它“按照书里的方法帮我实现一个多头注意力模块”book-to-skill 生成的 Skill 能给出完整的步骤、参数、注意事项而 RAG 大概率会漏掉一些关键细节。注意book-to-skill 不是要取代 RAG两者可以互补。对于事实性查询用 RAG对于流程性任务用 Skill这是更务实的做法。3. 核心细节解析与实操要点这一部分我拆解 book-to-skill 在实现层面的几个关键环节。需要说明的是以下内容基于我对这类工具常见实现方式的合理推断结合我自己做 PDF 解析和 Agent 开发的经验补充具体实现细节请以项目实际代码为准。3.1 PDF 解析为什么这是最难的一步很多人以为 PDF 解析就是调个库把文字提取出来实际上这是整个流程里最脏最累的活。技术书的 PDF 有几个特点让解析变得困难排版复杂。技术书通常有双栏排版、代码块、图表混排、脚注、边注。简单的文本提取会把双栏读成一行把代码和正文混在一起把图表标题当成正文。代码块识别。代码块和正文的字体可能一样但缩进、颜色、背景色不同。如果解析时不能正确识别代码块后续编译出来的 Skill 就会把代码当成普通文本Agent 执行时就会出错。公式和符号。技术书里大量使用数学公式和特殊符号。PDF 里的公式往往是图片或者特殊字体直接提取会变成乱码或者丢失。页眉页脚干扰。每页都有页眉页脚提取出来会混在正文里影响后续的结构识别。我的实操建议是不要指望一个库解决所有问题。常见的做法是组合使用多个工具。比如用 PyMuPDF 做基础文本提取和版面分析用 pdfplumber 做表格提取用 OCR 处理扫描版页面。对于代码块可以通过字体、缩进、背景色等特征做启发式识别。对于公式如果书里有 LaTeX 源码最好没有的话可能需要用专门的公式识别模型。提示解析阶段一定要保留页码和版面坐标信息。后续做结构识别和依赖分析时这些信息是重要的参考依据。丢掉坐标就等于丢掉了版面结构。3.2 结构识别从目录树到知识图谱PDF 解析出来是一堆带坐标的文本块下一步是把这些文本块组织成有意义的结构。技术书通常有明确的目录这是最好的起点。利用目录做骨架。大多数技术书的 PDF 里都有书签Bookmark或者目录页。书签是结构化的直接读出来就是章节目录。如果没有书签就要从目录页做 OCR 或者文本提取然后根据页码定位到正文对应位置。章节内容归类。有了骨架之后把文本块分配到对应的章节。这里要注意跨页的问题——一个段落可能跨两页一个代码块可能跨三页。需要根据文本的连续性做合并。知识单元识别。在每个章节内部进一步识别知识单元。我的经验是技术书里的知识单元通常有固定的模式概念定义通常以“XXX 是一种...”、“所谓 XXX 是指...”开头操作步骤通常以“首先...然后...最后...”或者有序列表形式出现参数说明通常以表格或者“参数 XXX 表示...”形式出现注意事项通常以“注意”、“警告”、“小心”等词开头示例代码通常有代码块标记或者等宽字体这些模式可以用规则匹配也可以用模型做分类。规则匹配准确率高但覆盖不全模型分类覆盖全但需要标注数据。实际项目中通常是两者结合。3.3 Skill 生成Agent 能看懂才是好格式编译的最终产物是 Skill 文件。这个文件长什么样直接决定了 Agent 能不能用好。我见过一些项目把 Skill 写成纯自然语言的说明文档这其实没有发挥 Skill 的优势。Skill 应该是半结构化的——既有自然语言的描述又有结构化的字段方便 Agent 解析和执行。一个典型的 Skill 文件结构大概是这样--- name: multi-head-attention description: 实现多头注意力机制适用于 Transformer 类模型 version: 1.0 dependencies: - scaled-dot-product-attention - linear-projection tags: - transformer - attention - deep-learning --- ## 概念说明 多头注意力是将查询、键、值分别投影到多个子空间... ## 执行步骤 1. 将输入张量按头数拆分... 2. 对每个头执行缩放点积注意力... 3. 拼接所有头的输出... 4. 通过输出投影层... ## 关键参数 | 参数名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | d_model | int | 512 | 模型维度 | | num_heads | int | 8 | 注意力头数 | | dropout | float | 0.1 | dropout 概率 | ## 注意事项 - d_model 必须能被 num_heads 整除 - 拼接后的维度是 num_heads * d_k需要与输出投影层匹配 ## 示例 输入: batch_size32, seq_len128, d_model512 输出: 形状为 (32, 128, 512) 的张量这种格式的好处是Agent 可以先读元信息判断这个 Skill 是否适用然后按需加载具体内容。执行步骤是明确的参数是结构化的注意事项是显式的。Agent 不需要“理解”整本书只需要“执行”这个 Skill。注意Skill 的粒度很重要。太粗一个 Skill 包含太多内容Agent 加载和执行都吃力太细Skill 之间依赖关系复杂调用链太长。我的经验是一个 Skill 对应书里的一个小节比较合适大概 500-2000 字的内容量。4. 完整实操流程从 PDF 到可用的 Skill这一部分我按实际操作顺序把整个流程串一遍。需要提前说明的是不同项目的具体命令和配置可能不同这里给出的是通用流程和关键参数你可以根据自己的工具链做调整。4.1 环境准备与依赖安装book-to-skill 这类工具通常是 Python 项目因为 PDF 解析和 NLP 处理的生态在 Python 里最成熟。基础环境需要 Python 3.9 以上建议用虚拟环境隔离依赖。核心依赖大概分几类PDF 解析PyMuPDF、pdfplumber、pdfminer.six文本处理regex、nltk、spacy模型调用openai、anthropic 或者本地模型推理框架向量与检索sentence-transformers、faiss 或 chroma命令行click 或 typer安装的时候有个坑要注意PyMuPDF 的包名是pymupdf而不是fitz虽然导入的时候用import fitz。这个命名不一致坑过很多人。pip install pymupdf pdfplumber pdfminer.six pip install spacy nltk pip install sentence-transformers faiss-cpu pip install click typer rich如果要用模型做知识单元分类还需要下载对应的模型权重。本地模型推荐用轻量级的比如 distilbert 或者 tinybert推理速度快对硬件要求低。如果调 API需要配置 API Key注意不要把 Key 硬编码在代码里用环境变量或者配置文件。4.2 PDF 解析与预处理第一步是把 PDF 转成结构化的文本数据。我通常分三步走第一步提取原始文本和坐标。用 PyMuPDF 逐页提取每个文本块记录内容、页码、坐标x0, y0, x1, y1、字体、字号。import fitz doc fitz.open(book.pdf) blocks [] for page_num, page in enumerate(doc): for block in page.get_text(dict)[blocks]: if block[type] 0: # 文本块 for line in block[lines]: for span in line[spans]: blocks.append({ page: page_num, text: span[text], font: span[font], size: span[size], bbox: span[bbox] })第二步版面分析。根据坐标判断文本块属于哪一栏、是不是页眉页脚、是不是代码块。双栏排版的判断逻辑是如果页面中间有一条垂直空白带左右两侧的文本块分别属于两栏。页眉页脚的判断逻辑是坐标在页面顶部或底部一定范围内的文本块。第三步文本清洗。去掉页眉页脚、合并跨行段落、修复断词。技术书里经常有单词被断行的情况比如 “atten-” 和 “tion” 分在两行需要合并成 “attention”。这个用正则匹配连字符加换行的模式可以处理。提示解析完一定要人工抽查几页看看代码块有没有被正确识别公式有没有丢失双栏有没有读串。这一步偷懒后面全白干。4.3 结构识别与知识抽取有了干净的文本和版面信息下一步是识别书的结构。目录提取。先看 PDF 有没有书签。有书签的话直接读没有的话从目录页提取。目录页的识别可以用关键词匹配比如“目录”、“Contents”然后提取后面的条目和页码。章节划分。根据目录的页码把正文文本分配到对应章节。这里要注意页码偏移——PDF 的物理页码和书里印刷的页码可能不一致需要计算偏移量。知识单元抽取。在每个章节内部用规则加模型的方式识别知识单元。我常用的规则包括标题模式以数字编号开头、字号比正文大、加粗步骤模式以“首先”、“然后”、“接着”、“最后”开头或者有序列表参数模式包含“参数”、“默认值”、“取值范围”等关键词的表格注意模式以“注意”、“警告”、“小心”、“务必”开头模型分类的话可以用一个小的文本分类模型把每个段落分类到预定义的类别里。训练数据可以人工标注几百条效果通常比纯规则好。4.4 Skill 编译与依赖图构建知识单元抽取完之后就是编译成 Skill 的环节。Skill 粒度划分。我前面说过一个小节对应一个 Skill 比较合适。但有些小节内容太少可以合并有些小节内容太多可以拆分。判断标准是一个 Skill 的内容量控制在 500-2000 字执行步骤不超过 10 步。依赖关系识别。这是最需要经验的一步。依赖关系通常来自几个方面显式引用书里写“参见第 X 章”、“如前所述”概念依赖Skill A 里用到了 Skill B 定义的概念参数依赖Skill A 的输入是 Skill B 的输出显式引用可以直接从文本里提取。概念依赖和参数依赖需要做实体识别和关系抽取。我的做法是先提取每个 Skill 里的关键实体概念名、参数名、函数名然后看这些实体在哪些其他 Skill 里被定义建立依赖边。依赖图校验。建完图之后要检查有没有环。技术书里一般不会有循环依赖但如果有说明抽取有问题需要人工介入。4.5 验证与迭代编译出来的 Skill 不能直接就用需要验证。自动验证。检查每个 Skill 的格式是否合法、依赖是否都能解析、参数是否完整。可以用 JSON Schema 做格式校验。人工抽查。随机抽几个 Skill让 Agent 实际执行一下看能不能跑通。我通常会设计几个典型任务比如“用这个 Skill 实现一个功能”、“解释这个 Skill 里的某个参数”看 Agent 的回答是否准确。迭代优化。根据验证结果调整解析规则、分类模型、Skill 粒度。这个过程通常要跑几轮才能稳定。5. 常见问题与排查技巧实录这一部分是我在实际操作中踩过的坑和总结的排查方法。技术书编译成 Skill 这个流程环节多、依赖多出问题是常态关键是怎么快速定位。5.1 PDF 解析类问题问题一代码块和正文混在一起。这是最常见的问题。表现是 Skill 里的执行步骤里混入了代码片段或者代码块被拆成了普通文本。排查思路先看 PDF 里代码块的排版特征。如果代码块有背景色检查解析时有没有提取背景色信息。如果代码块用等宽字体检查字体识别是否正确。如果代码块靠缩进区分检查缩进有没有被保留。解决方法在版面分析阶段增加代码块识别规则。我的经验是组合使用字体、背景色、缩进三个特征准确率能到 90% 以上。剩下的用规则兜底比如连续多行以特定符号开头如$、、#的文本块判定为代码。问题二双栏排版读串行。表现是 Skill 里的句子读不通前后不连贯像是两段话交错在一起。排查思路打开 PDF 对应页面看是不是双栏。如果是检查解析时的坐标排序逻辑。双栏页面的正确读法是先读左栏从上到下再读右栏从上到下。如果按 y 坐标全局排序就会左右交错。解决方法在版面分析阶段做分栏检测。简单的方法是找页面中间的垂直空白带把文本块分成左右两组分别排序。复杂一点的方法是用版面分析模型比如 LayoutLM能更准确地识别分栏、表格、图片区域。问题三公式丢失或乱码。表现是 Skill 里涉及公式的地方出现乱码或者空白。排查思路看 PDF 里的公式是文本还是图片。如果是文本检查字体是否被正确识别。如果是图片检查有没有做 OCR。解决方法如果公式是文本尝试用不同的解析库交叉验证。PyMuPDF 和 pdfplumber 对公式的处理可能不同。如果公式是图片用公式识别模型做 OCR比如 Mathpix 或者开源的 LaTeX-OCR。如果书里有 LaTeX 源码那是最好的直接提取。5.2 结构识别类问题问题四章节划分错误。表现是 Skill 的内容归属不对比如第二章的内容被划到了第一章。排查思路检查目录提取的页码和正文实际页码是否对齐。PDF 的物理页码和印刷页码通常有偏移比如 PDF 第 10 页对应印刷第 1 页。解决方法计算页码偏移量。方法是找几个已知章节的起始页对比目录页码和实际页码算出偏移。然后在划分章节时统一加上偏移量。问题五知识单元分类错误。表现是操作步骤被分类成了概念定义或者注意事项被当成了正文。排查思路看分类错误的样本有什么共同特征。是规则覆盖不到还是模型训练数据不足。解决方法如果是规则问题补充规则。如果是模型问题增加训练数据或者调整分类阈值。我的经验是规则和模型结合使用效果最好——规则处理高置信度的样本模型处理边界样本。5.3 Skill 生成类问题问题六Skill 粒度不合适。表现是有的 Skill 内容太多Agent 执行时容易迷失有的 Skill 内容太少依赖关系复杂。排查思路统计每个 Skill 的字数和步骤数。字数超过 3000 或者步骤超过 15 步的考虑拆分字数少于 300 或者步骤少于 2 步的考虑合并。解决方法设定粒度阈值自动拆分或合并。拆分的时候注意保持步骤的完整性不要把一步操作拆到两个 Skill 里。合并的时候注意依赖关系不要把不相关的 Skill 硬凑在一起。问题七依赖关系缺失或错误。表现是 Agent 执行 Skill 时报错说找不到某个概念或参数的定义。排查思路检查依赖图看缺失的依赖是不是没有被识别出来。常见原因是实体识别漏了或者关系抽取错了。解决方法补充实体识别规则增加关系抽取的训练数据。另外可以在 Skill 里增加“前置知识”字段人工补充一些模型没识别出来的依赖。5.4 常见问题速查表问题现象可能原因排查方法解决方向代码块混入正文版面分析未识别代码特征检查字体、背景色、缩进增加代码块识别规则双栏读串行坐标排序未分栏检查页面是否双栏做分栏检测分别排序公式乱码公式为图片或特殊字体检查公式类型OCR 或提取 LaTeX 源码章节划分错误页码偏移未校正对比目录页码和实际页码计算并应用页码偏移知识单元分类错误规则覆盖不足或模型不准分析错误样本特征补充规则或增加训练数据Skill 粒度过大未做粒度控制统计字数和步骤数按阈值拆分Skill 粒度过小未做合并统计字数和步骤数按阈值合并依赖关系缺失实体识别或关系抽取漏了检查依赖图补充规则或人工标注提示排查问题的顺序建议从上游到下游。先确认 PDF 解析没问题再看结构识别最后看 Skill 生成。上游的问题会传导到下游如果跳过上游直接查下游很容易白忙活。6. 这套方法还能怎么扩展book-to-skill 的思路不局限于技术书。任何有结构、有流程、有依赖关系的文档都可以用类似的方法编译成 Skill。比如团队内部的运维手册。运维手册通常是“遇到 X 情况执行 Y 步骤注意 Z 事项”的结构非常适合编译成 Skill。编译之后Agent 可以在告警触发时自动加载对应的 Skill按步骤执行排查和恢复操作。再比如产品文档和 API 文档。API 文档里的每个接口都可以编译成一个 Skill包含参数说明、调用示例、错误码处理。Agent 在写代码时可以按需加载对应的 Skill而不是每次都要去翻文档。甚至非技术类的文档也可以。比如菜谱每道菜是一个 Skill包含食材、步骤、火候、注意事项。Agent 可以按 Skill 指导你做菜缺什么食材它会提醒你步骤错了它会纠正你。核心逻辑是一样的把非结构化的知识编译成结构化的、可执行的 Skill。这个思路的价值在于它让知识从“可读”变成了“可用”。读一本书你得到的是信息编译一本书你得到的是能力。我在实际操作中的体会是编译的过程本身就是一次深度阅读。为了让 Agent 能执行你必须把书里的知识拆解到足够细、足够明确的粒度。这个过程中很多你读书时忽略的细节会暴露出来很多你以为懂了其实没懂的地方会现原形。所以哪怕不考虑 Agent 的使用单纯把 book-to-skill 当作一个读书工具也是值得的。
