1. 从“读完就忘”说起技术书和 Agent 之间的那道墙你有没有过这种体验花了一周啃完一本六百页的技术书合上书的那一刻感觉自己懂了结果三天后同事问你某个具体机制怎么实现你只能含糊地说“好像有个什么模式来着”。更别提那些买来就再也没打开过的 PDF静静躺在硬盘里占着空间也占着一种说不清的愧疚感。这个痛点做 AI Agent 开发的人感受更深。我们天天在给 Agent 写提示词、搭工作流、接工具但真正让 Agent 变强的往往不是模型本身而是它能不能随时调用某个领域的“专家知识”。问题来了——你读过的书Agent 读不到你脑子里的经验Agent 用不上。知识卡在人这一侧Agent 那一侧永远是空的。book-to-skill这个项目干的就是把这道墙拆掉的事。它做的事情用一句话说清楚把一本技术书PDF 格式编译成一个 Agent 可以直接调用的 Skill。15k Star 不是白来的它踩中的正是当下 Agent 开发里最真实的一个缺口——知识供给。这篇文章我会从项目设计思路、核心原理、实操流程、踩坑经验四个维度把这个工具彻底拆开讲。不管你是刚接触 Agent 开发的新手还是已经在搭自己 Agent 框架的老手都能从里面拿到能直接用的东西。我会尽量说人话把“为什么这么设计”讲透而不是只告诉你“怎么敲命令”。2. 项目整体设计与思路拆解2.1 为什么是“编译”而不是“检索”很多人第一反应是PDF 读完就忘那我做个 RAG 不就行了把 PDF 切块、向量化、存进向量库Agent 需要的时候去检索。这条路大家都熟但它有几个绕不开的毛病。第一检索是“按需取用”不是“内化”。RAG 每次都要走一遍“查询→召回→重排→拼接”的流程延迟高而且召回质量极度依赖切块策略和嵌入模型。你问一个跨章节的综合问题切块检索经常给你拼出一堆半截话。第二RAG 给的是原文片段不是可执行的知识。技术书里真正有价值的是“怎么做”的步骤、参数、判断逻辑而原文片段往往是叙述性的Agent 拿到之后还得自己再理解一遍容易跑偏。book-to-skill的思路完全不同。它把 PDF 当成源代码把书里的知识编译成结构化的 Skill 定义。编译这个词用得很准——就像源码编译成可执行文件中间经过了词法分析、语义提取、结构重组最后产出一个 Agent 能直接“执行”的东西。这个产出物不是原文的副本而是经过提炼的、带结构的、可调用的知识单元。提示理解“编译”这个定位很关键。它决定了这个工具不是检索增强而是知识固化。你要的不是“随时能查到”而是“Agent 本来就会”。2.2 Skill 到底是什么为什么它比 Prompt 更值得投入在讲编译流程之前得先把 Skill 这个概念说清楚因为热词里agent skill、skill插件、codex skill、skill脚本满天飞但很多人其实没搞明白它和 Prompt 的区别。Prompt 是“一次性指令”你写一段话告诉模型这次要干什么对话结束就没了。Skill 是“可复用的能力单元”它包含触发条件、执行逻辑、依赖工具、输出格式是一个自包含的模块。打个比方Prompt 像是你临时跟同事口头交代一件事Skill 像是你写好的一份标准作业程序SOP谁来了都能照着做而且做得一致。Agent 的 Skill 通常包含这几个部分元信息名称、描述、适用场景Agent 靠这个判断什么时候该调用它输入定义需要哪些参数参数类型和约束执行逻辑具体步骤可能是提示词模板也可能是代码依赖声明需要哪些工具、哪些外部资源输出规范返回什么格式怎么处理异常book-to-skill的价值就在于它把一本非结构化的书自动映射成了上面这套结构。你不需要手动去写 Skill工具帮你从书里“编译”出来。2.3 整体架构从 PDF 到 Skill 的四层流水线我把这个项目的处理流程拆成四层这样你理解起来会清晰很多。第一层文档解析层。负责把 PDF 变成可处理的文本。这一步看着简单其实是整个流程里最脏最累的活。PDF 不是为机器阅读设计的格式它本质上是“打印指令的集合”文字位置、字体、分栏、图表混在一起。技术书尤其麻烦代码块、公式、表格、页眉页脚全是干扰。第二层语义提取层。把解析出来的文本识别出哪些是概念、哪些是步骤、哪些是参数、哪些是注意事项。这一步决定了编译出来的 Skill 质量高低。好的提取能抓住书里的“知识骨架”差的提取就是一堆流水账。第三层结构重组层。把提取出来的知识按照 Skill 的规范重新组织。概念归概念步骤归步骤依赖关系理清楚触发条件写明白。这一步是“编译”的核心相当于把高级语言翻译成目标代码。第四层输出封装层。把重组好的内容写成 Agent 框架能识别的 Skill 文件格式。不同框架格式不一样但核心结构是相通的。这四层里第一层和第二层是难点第三层是价值所在第四层是适配工作。下面我会逐层展开。3. 核心细节解析与实操要点3.1 PDF 解析为什么大部分工具在这一步就翻车了先说个反直觉的事实PDF 解析的质量直接决定了最终 Skill 的上限。很多人用工具的时候觉得“解析出来差不多就行”结果编译出来的 Skill 驴唇不对马嘴回头排查半天发现是解析阶段就把代码块和正文混在一起了。PDF 解析的坑主要有这么几类坑一多栏排版。技术书经常是双栏甚至三栏普通解析器会按从左到右、从上到下的顺序读结果把左栏的结尾和右栏的开头拼在一起语义完全断裂。解决办法是先用版面分析layout analysis识别出栏位再按栏分别读取。坑二代码块识别。代码块通常用等宽字体但 PDF 里字体信息不一定保留得完整。更麻烦的是代码块里的缩进、换行在 PDF 里可能只是坐标偏移解析出来缩进全丢代码就没法看了。实操中建议用带版面分析能力的解析器比如基于深度学习的文档解析模型能识别出代码区域并保留格式。坑三页眉页脚和页码。这些内容会混进正文污染语义提取。需要在解析后做一轮清洗按位置和重复模式过滤掉。坑四公式和图表。公式解析成乱码是常态图表里的文字更是重灾区。对于技术书公式和图表往往承载关键信息丢了就残缺。目前的务实做法是公式保留原始图片引用图表提取标题和说明文字正文里标注“见原书图 X”。注意不要指望一个解析器解决所有问题。实际项目里通常是“通用解析器 针对性后处理”的组合。先跑一遍通用解析再针对代码块、公式、表格做专项处理。3.2 语义提取怎么让机器看懂“这是步骤那是参数”解析出来的是文本流但 Skill 需要的是结构化的知识。语义提取这一步核心任务是给文本打标签这段是概念定义那段是操作步骤另一段是参数说明还有一段是注意事项。这里有个关键判断技术书的知识密度分布是不均匀的。一本三百页的书真正能编译成 Skill 的核心内容可能只有几十页。大部分篇幅是铺垫、举例、过渡。如果全量提取Skill 会臃肿不堪如果提取太少又丢信息。我的经验是抓三类内容定义类某个术语是什么解决什么问题适用边界在哪步骤类怎么做分几步每步的输入输出是什么约束类什么情况下不能用参数范围是多少常见错误是什么这三类内容基本构成了一个 Skill 的骨架。定义类对应 Skill 的描述和适用场景步骤类对应执行逻辑约束类对应异常处理和注意事项。提取的方法上纯规则匹配比如找“步骤如下”“注意”“参数”这些关键词能覆盖一部分但漏报误报都多。更稳的做法是“规则初筛 模型精判”先用规则把候选段落圈出来再用一个小模型判断这段到底属于哪一类。这样成本可控准确率也够用。3.3 结构重组把散落的知识拼成一个能用的 Skill提取出来的知识是散落的重组就是要把它们拼成一个自洽的整体。这一步最考验对 Skill 规范的理解。一个常见的错误是把书里的章节结构直接搬过来当 Skill 结构。书是给人读的章节是按叙事逻辑组织的Skill 是给 Agent 用的结构要按调用逻辑组织。这两者往往不一致。举个例子。一本书可能用三章分别讲“环境搭建”“核心概念”“实战案例”但编译成 Skill 的时候Agent 需要的是“当用户要做 X 的时候先检查环境再理解概念 Y然后按步骤 Z 操作”。这是按任务组织的不是按章节组织的。所以重组阶段要做一次“视角转换”从“作者怎么讲”转成“Agent 怎么用”。具体做法是先识别出书里覆盖的任务场景每个场景对应一个 Skill然后把相关的定义、步骤、约束都归到这个 Skill 下面。一个场景一个 Skill边界清晰Agent 调用的时候不容易混淆。3.4 输出封装不同 Agent 框架的适配策略最后一步是把重组好的内容写成文件。不同框架的 Skill 格式不一样但核心字段是相通的名称、描述、触发条件、输入、执行逻辑、输出。适配的时候有个原则优先保证语义完整格式差异用适配层解决。也就是说内部先用一套统一的中间表示IR描述 Skill输出的时候再根据目标框架做转换。这样换框架的时候不用重写编译逻辑只改适配层就行。热词里提到的codex skill、skill插件、workbuddy skill这些本质上都是不同框架对 Skill 的不同叫法和格式。理解了核心结构适配就是体力活。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先把环境搭起来。这个项目是命令行工具Python 生态为主依赖不算重但有几个关键库要装对版本。# 建议用虚拟环境避免污染全局 python -m venv book2skill-env source book2skill-env/bin/activate # Windows 用 book2skill-env\Scripts\activate # 核心依赖 pip install pymupdf pdfplumber pip install langchain-text-splitters pip install pydantic这里解释一下为什么选这两个 PDF 库。pymupdf也叫 fitz速度快对文字位置信息保留得好适合做版面分析pdfplumber对表格和复杂版面的处理更细适合做补充。两个一起用取长补短。pydantic是用来定义 Skill 的数据结构的这一步很关键因为 Skill 的字段约束多用 pydantic 能保证编译出来的东西结构合法。提示如果你的书里有大量扫描页图片型 PDF还需要额外装 OCR 相关的库。但 OCR 出来的文本质量普遍不如原生文本能不用尽量不用。4.2 第一步PDF 解析与文本清洗先写解析脚本。核心思路是先用 pymupdf 提取带位置信息的文本块再做版面分析最后清洗。import fitz # pymupdf def extract_blocks(pdf_path): doc fitz.open(pdf_path) all_blocks [] for page_num, page in enumerate(doc): # 获取带坐标的文本块 blocks page.get_text(dict)[blocks] for block in blocks: if block.get(type) ! 0: # 0 表示文本块 continue text for line in block.get(lines, []): for span in line.get(spans, []): text span[text] text \n all_blocks.append({ page: page_num, bbox: block[bbox], # 位置信息 text: text.strip() }) return all_blocks拿到带位置信息的文本块之后做两件事分栏识别和页眉页脚过滤。分栏识别的逻辑是统计所有文本块的 x 坐标分布如果明显聚成两簇或三簇就说明是多栏排版按 x 坐标把块分到不同栏再按栏内 y 坐标排序。页眉页脚过滤的逻辑是统计每个文本块在页面中的 y 坐标如果大量页面在相同 y 位置都有内容且内容相似比如都是页码或书名就判定为页眉页脚过滤掉。def filter_headers_footers(blocks, page_height, threshold0.08): # 页面顶部和底部 8% 区域内的内容大概率是页眉页脚 filtered [] for b in blocks: y0, y1 b[bbox][1], b[bbox][3] if y0 page_height * threshold or y1 page_height * (1 - threshold): continue filtered.append(b) return filtered这一步做完你会得到相对干净的正文文本。但代码块和公式还需要单独处理下面说。4.3 第二步代码块与公式的专项处理代码块的处理核心是识别 保格式。识别靠字体信息代码块通常用等宽字体如 Courier、Consolas、Monaco。pymupdf 的 span 信息里有字体名可以据此判断。def is_code_span(span): font span.get(font, ).lower() mono_fonts [courier, consolas, monaco, menlo, source code] return any(f in font for f in mono_fonts)识别出代码块之后要保留缩进。PDF 里缩进表现为 x 坐标的偏移可以按 x 坐标的相对位置还原缩进层级。具体做法是统计代码块内所有行的起始 x 坐标聚类成几个层级每层对应一个缩进级别。公式的处理更麻烦。务实做法是用版面分析识别出公式区域把这块区域截图保存在文本里用占位符标记比如[FORMULA: formula_001.png]。编译成 Skill 的时候公式图片作为附件引用。这样虽然不能直接让 Agent 计算但至少信息没丢需要的时候可以人工介入。注意代码块和公式的处理质量是区分“能用”和“好用”的分水岭。很多开源工具在这一步偷懒导致编译出来的 Skill 里代码全是乱的。多花点时间在这上面后面省心。4.4 第三步语义提取与知识分类文本清洗完之后进入语义提取。前面说了抓定义、步骤、约束三类内容。这里给一个规则初筛的实现思路。import re # 定义类关键词 DEF_PATTERNS [ r是指, r定义为, r是一种, r指的是, r所谓 ] # 步骤类关键词 STEP_PATTERNS [ r步骤如下, r第一步, r首先.*然后, r操作步骤, r^\d\. ] # 约束类关键词 CONSTRAINT_PATTERNS [ r注意, r警告, r不能, r禁止, r必须, r参数范围 ] def classify_paragraph(text): for p in DEF_PATTERNS: if re.search(p, text): return definition for p in STEP_PATTERNS: if re.search(p, text, re.MULTILINE): return step for p in CONSTRAINT_PATTERNS: if re.search(p, text): return constraint return other规则初筛之后用一个小模型做精判。这里不一定要用大模型一个微调过的小分类模型就够成本低、速度快。如果不想训模型用大模型的 few-shot 也能做就是成本高一些。分类完之后把同一类的内容聚在一起为下一步重组做准备。4.5 第四步Skill 结构生成与输出这是最后一步把分类好的知识组装成 Skill。先用 pydantic 定义 Skill 的结构from pydantic import BaseModel, Field from typing import List, Optional class SkillStep(BaseModel): order: int description: str input: Optional[str] None output: Optional[str] None class Skill(BaseModel): name: str description: str trigger: str # 触发条件 definitions: List[str] Field(default_factorylist) steps: List[SkillStep] Field(default_factorylist) constraints: List[str] Field(default_factorylist) dependencies: List[str] Field(default_factorylist)然后写一个组装函数把分类好的内容填进去。触发条件的生成是个难点需要从书里的任务场景反推。一个实用的技巧是看这一章/这一节解决的是什么问题把问题描述转成“当用户需要……时”的句式。def build_skill(chapter_title, classified_content): skill Skill( namechapter_title, descriptionf基于《书名》第 X 章编译覆盖 {chapter_title} 相关操作, triggerf当用户需要处理 {chapter_title} 相关任务时调用, definitionsclassified_content.get(definition, []), constraintsclassified_content.get(constraint, []), ) # 步骤按顺序组装 steps classified_content.get(step, []) for i, s in enumerate(steps, 1): skill.steps.append(SkillStep(orderi, descriptions)) return skill最后序列化成目标框架的格式。如果是通用的 JSON 格式直接skill.model_dump_json()就行如果是特定框架的 YAML 格式写个转换函数。4.6 完整流程串一遍把上面几步串起来一个完整的编译流程是这样的读取 PDF提取带位置信息的文本块版面分析分栏识别页眉页脚过滤代码块识别与格式保留公式区域截图标记文本分段规则初筛 模型精判分类为定义/步骤/约束按任务场景聚合生成 Skill 结构序列化输出适配目标 Agent 框架整个流程跑下来一本三百页的技术书大概能编译出 10 到 30 个 Skill取决于书的密度。每个 Skill 对应一个明确的任务场景Agent 调用的时候按需加载。5. 常见问题与排查技巧实录5.1 编译出来的 Skill 太臃肿怎么办这是最常见的问题。原因通常是提取阶段没做筛选把书里的铺垫、举例、过渡内容也塞进去了。解决办法是加一层信息密度过滤。具体做法对每个候选段落计算它的“知识密度”——包含定义、步骤、约束关键词的密度以及是否包含具体参数、代码、命令。密度低于阈值的段落直接丢弃。另一个技巧是去重。技术书里同一个概念经常反复讲提取出来会有大量重复。用文本相似度做一轮去重能砍掉不少冗余。5.2 代码块解析出来缩进全乱前面提过缩进在 PDF 里是坐标偏移。如果解析出来缩进丢了检查两个地方一是解析时有没有保留 span 的 bbox 信息二是还原缩进时聚类算法是否合理。一个实用的调试方法把解析出来的代码块和原书对照看缩进差了几级。如果整体差一级说明聚类阈值设错了如果局部乱说明代码块里混进了非代码内容需要重新切分。5.3 Skill 的触发条件写不准Agent 该调用的时候不调用触发条件是 Skill 的“入口”写不好 Agent 就找不到。常见问题是触发条件写得太窄或太宽。太窄只写了具体操作没写场景。比如“当用户输入 pip install 时调用”结果用户说“我想装个包”Agent 就不知道调这个 Skill。太宽写成了“当用户问技术问题时调用”结果所有技术问题都触发这个 Skill互相打架。我的经验是触发条件要包含场景 动作两个要素。比如“当用户需要在 Python 项目中安装第三方依赖时调用”场景是“Python 项目”动作是“安装第三方依赖”。这样边界清晰不容易误触发。5.4 常见问题速查表问题现象可能原因排查方向解决思路解析文本乱序多栏排版未识别检查文本块 x 坐标分布加版面分析按栏读取代码缩进丢失未保留坐标信息检查解析时是否取 bbox按 x 坐标聚类还原缩进公式变乱码公式未做特殊处理检查公式区域是否被当正文截图标记附件引用Skill 臃肿提取未做密度过滤统计段落知识密度加阈值过滤和去重触发不准触发条件太窄/太宽检查触发条件描述场景动作双要素页眉页脚混入未做位置过滤检查页面边缘内容按 y 坐标过滤章节结构错乱按书章节组织 Skill检查 Skill 边界改按任务场景组织5.5 几个踩过的坑和独家技巧坑一不要一次性编译整本书。先拿一章试跑看看效果调好参数再全量跑。整本书跑一次可能十几分钟参数不对就是白跑。坑二解析器的版本很关键。pymupdf 不同版本对字体信息的保留程度不一样遇到解析异常先检查版本。我遇到过升级后代码块识别率骤降的情况回退版本就好了。坑三中文技术书的解析难度普遍高于英文。中文没有空格分词版面分析时文本块的切分逻辑不一样需要针对性调整。如果书是中英混排更麻烦建议分开处理。技巧一用目录做锚点。PDF 的目录bookmark是天然的结构信息用它来切分章节比按页码切准得多。很多解析库支持读取目录善加利用。技巧二保留原文引用。编译出来的 Skill 里每个知识点都标注它在原书的页码。这样 Agent 用的时候如果有疑问可以回溯原文。这个功能看起来小实际用起来非常香。技巧三增量编译。书更新了或者你想补充内容不用全量重跑。记录每个 Skill 对应的原文范围只重编译变化的部分。6. 这套东西还能怎么扩展把技术书编译成 Skill只是这个思路的一个应用。同样的逻辑可以迁移到很多场景。场景一把团队内部文档编译成 Skill。很多团队的知识散落在各种 Wiki、文档、会议纪要里新人上手全靠问人。用这套流程把内部文档编译成 SkillAgent 就能回答大部分常规问题老人能省下大量重复答疑的时间。场景二把课程视频的字幕编译成 Skill。视频课程的信息密度其实很高但检索困难。把字幕提取出来走同样的编译流程就能得到一个可调用的知识库。场景三把个人笔记编译成 Skill。你自己积累的笔记是最懂你的知识。编译成 Skill 之后Agent 就带上了你的个人经验回答问题时更贴合你的习惯。热词里提到的ai备课skill、测试skill、去ai味的skill本质上都是这个思路在不同领域的应用。核心逻辑是一样的把非结构化的知识源编译成 Agent 能直接调用的结构化 Skill。我个人在实际操作中的体会是这套流程最难的不是技术实现而是判断哪些知识值得编译。书里百分之八十的内容是铺垫真正能变成 Skill 的可能只有百分之二十。把精力花在识别这百分之二十上比优化解析算法更重要。另外编译出来的 Skill 一定要实际用起来在用的过程中发现问题、迭代改进比一次性追求完美要靠谱得多。