把一本书读透越来越像一件奢侈的事。尤其是 PDF 格式的技术书几百页翻下来真正留在脑子里的可能只有几个模糊的概念。我书架上的技术书一年能读完五六本可一到写代码、配环境、排查报错的时候能快速想起来的内容不到十分之一。试过摘抄、导图、Notion 笔记最后还是回到“翻书”这条原始路径。一开始我也觉得这思路有点“离大谱”——书还能编译PDF 读完就忘不是应该靠记笔记解决吗直到我在 GitHub 上刷到 book-to-skill 这个项目想法才彻底转变过来与其逼自己记住书里的每一条命令不如把整本书“编译”成一个 Agent 可以随身携带的 Skill 包随叫随到。book-to-skill 目前在 GitHub 上已经有 1.5 万左右的 star核心思路一句话就能讲清楚输入一本 PDF 技术书输出一个结构化的 Skill 技能包。这里的 Skill 不是那种“会写诗、会画图”的提示词模板而是 Agent 生态里正在流行的一种插件化能力单元——一个 Skill 通常由一个 SKILL.md 描述文件加若干资源文件组成Agent 根据任务场景判断要不要加载这个技能一旦加载就可以按里面的指引检索、调用、执行。这个思路解决的是三个很具体的问题第一PDF 是非结构化内容直接塞给 Agent 既放不进上下文窗口也没法精准定位第二技术书里大量代码块、命令、配置项在普通摘要流程里会被丢掉而 Skill 格式允许把这些内容原样保留并分类存放第三人是会遗忘的Agent 不会——只要 Skill 包还在知识就还在。它适合两类人一是想提升日常查阅效率、让 Agent 替自己“读书”的开发者二是正在做 Agent 应用想把垂直领域手册变成 Agent 长期能力的工程师。1. 从“读完就忘”到“编译成 Skill”先搞清楚人为什么会忘1.1 技术书阅读的三个认知陷阱先说第一个陷阱线性阅读不等于结构记忆。我们读书是按页码顺序来的但在实际工作里我们是用场景触发知识的——比如写代码时遇到“通信超时”你需要的不是书里第 3 章的定义而是第 7 章的排查步骤。看书时你建立的是“章节顺序”索引用的时候需要的是“场景到方案”索引两种索引对不上就会产生“我明明读过就是想不起来”的感觉。第二个陷阱是高亮和划线的错觉。划线那一刻你会觉得“这部分我掌握了”其实你掌握的只是熟悉感。熟悉感不等于检索能力。真正到用的时候你得从记忆里把这条内容调取出来而划线只是给原文做了个标记并没有在你大脑里建立可调用的知识结构。这也是为什么很多人笔记做了三大本遇到问题还是得翻原书。第三个陷阱是技术书的信息密度太高。作者写书时习惯于“前置引用”——第一章提到的参数要到第九章才解释完整。对读者来说阅读是线性推进的但知识依赖是网状交织的。读完前面几章后面的内容还没见到读到后面时前面的细节已经下沉。人类的工作记忆就这么大指望一遍阅读构建出完整网状索引本来就违背了大脑的工作方式。1.2 Skill 到底是什么给 Agent 配一本“岗位手册”如果给“Skill”下一个简单定义我会说它是 Agent 的一个可插拔能力包。一个标准的 Skill 目录通常包含两部分SKILL.md 负责描述“这个技能是干什么的、什么时候用、怎么用”resources/ 目录里装的是实际会被检索和引用的资料比如概念表、命令清单、配置模板、排障手册。打个比方Skill 之于 Agent就像岗位手册之于刚入职的实习生。手册不会让实习生变聪明但能保证他遇到问题时按图索骥不做无谓发挥。Agent 的能力上限还是取决于底层模型但有没有 Skill决定了它在特定领域“接得住话”还是“瞎编”。主流的 Agent 工具像 Claude Code、Codex 这类编程代理已经开始原生支持 skills 目录。你把一个 Skill 放进指定目录重启会话Agent 会自动读一遍 SKILL.md 的描述。之后遇到匹配的任务它就知道该去 resources 里翻资料了。1.3 为什么是“编译”而不是摘要或者摘抄很多人第一反应是给 PDF 做个摘要不就行了吗短一点Agent 不就能读了吗问题在于摘要天然只保留“结论”丢掉过程细节。技术书最值钱的是什么是参数表、边界条件、命令用法、报错信息、作者踩过的坑。这些东西恰恰在摘要里第一个被丢掉。做纯手工摘抄也不行几百页的书靠人挑重点既慢又漏摘出来的内容还带着个人偏好。book-to-skill 的处理方式更像“编译”它把非结构化的 PDF 文档逐步转换成结构化的、可检索的、面向 Agent 的知识产物。整个过程不是一次生成而是多级流水线——先还原文档结构再抽取知识点然后按类别聚合最后按 Skill 模板组装。可以理解为摘要像是故事的简介编译像是把小说改编成剧本杀——保留人物关系、时间线、关键场景并且让玩家Agent在游戏过程中能随时翻查对应的线索。2. 设计思路与核心技术点拆解2.1 四段式流水线是怎么设计的book-to-skill 把“书变成 Skill”拆成了四个阶段顺序很讲究不能乱。第一阶段是 PDF 解析把文件变成干净的文本流、表格和图片。第二阶段是结构识别重建目录树找到每个章节的边界、标题层级、代码块位置。第三阶段是知识蒸馏把已经结构化了的文本分块送入大模型提取概念、参数、代码、注意事项。第四阶段是 Skill 编译把蒸馏结果按模板组织成 SKILL.md 与 resources 目录。为什么把“结构识别”放在“蒸馏”前面因为直接对 PDF 原始文本做大模型提取会丢掉层级信息。先重建章节树后续每个知识块都能挂到具体章节下Agent 日后检索时既能答内容也能告诉用户“这个知识点在第几章”可追溯性一下就强了。2.2 PDF 解析层文本版和扫描版是两条完全不同的路PDF 解析是整个流程的地基。地基本来就不稳后面蒸馏出来的东西全是垃圾。我实测下来第一件事不是急着跑工具而是先确认这份 PDF 有没有文本层。在 Linux 下用一句话就能测pdftotext some-book.pdf - | head -50如果输出的是空白、乱码或一堆方框说明这份 PDF 本质是图片必须走 OCR 路线。如果输出正常才进入常规解析流程。常规解析里文本提取建议用 PyMuPDF速度快对大多数排版都稳定需要精细化处理表格时用 pdfplumber 或 camelot。表格是 PDF 解析里最麻烦的东西一行文本被表格线切得七零八落顺序完全错乱。camelot 是少有的能按视觉线索重新拼表的开源工具。扫描版 PDF 就绕不开 OCR。常见选择是 Tesseract 或 PaddleOCR中文扫描件我实测 PaddleOCR 效果好很多。不过 OCR 慢一页一秒到几秒不等一本 300 页的书可能要跑十几分钟。所以我的建议是能找文字版 PDF 就优先找文字版OCR 是最后手段。2.3 内容蒸馏层从“信息”到“知识”的关键一跳解析出来的文本只是“信息”零散地躺在那里。蒸馏要做的是从里面提炼出“知识项”。我给蒸馏环节设定过一组提取目标包括概念定义、API 签名、命令用法、参数表、配置模板、示例代码、报错说明、作者标注的注意事项。蒸馏也分两个层面。第一层是文本分块按章节、小节把内容切成适合大模型处理的块块与块之间保留上下文指针。第二层是提取每块输出一份 JSON里面包括知识点类型、要点内容、原文引用、所在章节。要求带原文引用是我在实践里从教训中得来的如果不要求模型会出现“看着合理但原文里根本没有”的幻觉内容。代码块还原是另一个容易翻车的点。PDF 排版的代码经常被分页截断、带行号、被页眉干扰。book-to-skill 内部会做行号剥离、接续行合并、缩进恢复把一段段被物理拆散的代码重新拼起来。反例知识和警告提示我也会特意保留技术书里作者花大篇幅写的“这里容易出错”往往比正文还值钱。2.4 Skill 打包层产物的组织方式决定好不好用蒸馏完的中间结果是 JSON 和 Markdown但这不是 Skill。真正好用的 Skill 要满足三个要求能被 Agent 识别、能快速定位内容、能承载多种资源。SKILL.md 开头的 front-matter 是给 Agent 看的“门牌号”。name 是技能名description 写清触发场景。description 写得好不好直接决定 Agent 会不会在正确的时机加载这个技能。resources 目录里的文件则按类型拆分concepts.md 放概念定义commands.md 放命令清单code-snippets.md 放可运行代码config-templates.md 放配置模板troubleshooting.md 放排障手册。index.json 是整套资源的目录索引它会告诉 Agent 每个主题去哪查。这看起来像是把 PDF 拆成了好几个小文件实质上是一次“重排”。原来的书是按章节组织的Agent 的工作方式是按任务组织的不重排的话Agent 每次都要全量翻一遍成本太高。3. 实操把一本技术书编译成 Agent 的随身 Skill3.1 环境准备装什么、配什么我先说环境准备。book-to-skill 是基于 Python 的工具建议用 Python 3.10 以上版本。安装就一条命令pip install book-to-skill如果同时要处理 OCR再装 OCR 引擎这里以 PaddleOCR 为例pip install paddleocr然后配置大模型接口。蒸馏环节需要调用 LLMbook-to-skill 会读取环境变量里的 API Key 和模型标识配置方法在项目 README 第一屏就有。我用的是 deepseek-chat够用且便宜如果你有别的模型改环境变量就行。装完先跑一下版本验证book-to-skill --version能输出版本号就说明依赖装全了。这一步在实际操作里经常被跳过去然后卡在编译中途报缺失依赖我不建议跳。3.2 核心命令与参数选择拿我手头这本《ROS2机器人开发从入门到实践》举例编译命令长这样book-to-skill compile ./ros2-practice.pdf \ --output ./skills/ros2-practice \ --name ros2-practice \ --description ROS2机器人开发实践手册用于回答节点通信、话题/服务/动作、TF坐标、URDF建模、launch文件编写、仿真与真机部署等问题 \ --language zh \ --split-level 2 \ --model deepseek-chat \ --workers 4几个参数值得说清楚。--split-level 2表示只拆到二级标题一章内部的小节当做一个整体处理。实践证明拆得太细会丢上下文拆得太粗会让分块超长二级是大多数技术书的甜点。--workers 4是蒸馏时的并发线程数对 API 类型的模型来说并发太大会触发限流4 到 6 是一个比较稳的区间。--language zh是让蒸馏结果的提示词和输出尽量保持中文毕竟技术书原样是中文强行翻成英文再返回反而增加错误率。如果你手里的 PDF 是扫描版要在命令里强制加--ocr并指定 OCR 引擎book-to-skill compile ./scanned-book.pdf --ocr --ocr-engine paddleocr这一步会很慢耐心等。第一次编译建议先挑一个章节的 PDF 做小规模测试跑通了再编译全书免得等二十分钟后发现问题还要重来。3.3 产物长什么样目录结构与示例编译完成后--output指定的目录里会出现如下结构skills/ros2-practice/ ├── SKILL.md ├── meta.json └── resources/ ├── concepts.md ├── commands.md ├── code-snippets.md ├── config-templates.md ├── troubleshooting.md └── index.json打开 SKILL.md 你会看到类似这样的一段内容--- name: ros2-practice description: 用于回答 ROS2 开发相关的问题。当用户咨询节点通信、话题/服务/动作、TF坐标、URDF建模、launch文件编写、仿真与真机部署时优先调用此技能。 --- # ROS2 实践手册 ## 使用说明 1. 先查询 resources/index.json 定位知识条目 2. 涉及代码时读取 resources/code-snippets.md 中的可运行示例 3. 涉及参数配置时读取 resources/config-templates.md 4. 遇到报错优先查 resources/troubleshooting.md ## 注意 - 本技能由《ROS2机器人开发从入门到实践》编译生成覆盖书内内容。 - 对于书中未涉及的知识点应明确告知用户书中未涉及不要臆造。这段描述给了 Agent 一个清晰的执行路径先查索引再按主题进文件。这就是“索引思维”的落地。3.4 挂载到 Agent三步完成上线Skill 编译好不算完关键在挂载。目前支持 skills 目录的 Agent 工具挂载方式基本一致。第一步把整个ros2-practice目录复制到 Agent 的 skills 目录下。比如你用 Claude Code通常放在~/.claude/skills/下其他工具就按各自的目录规范放。第二步重启会话让 Agent 重新扫描 skill 描述。第三步用几个典型问题做验证比如“ROS2 里 topic 和 service 的区别是什么”“launch 文件里怎么设置参数服务器”“URDF 里 joint 的 type 有哪几种”。看它是否主动加载了 skill回答是否与原文一致。我实测下来挂载后第一次对话如果触发正确后续使用会相当顺手。你甚至可以在提问里显式带上技能名大多数 Agent 都支持这种手动触发方式。3.5 一键编译脚本把流程固化下来如果以后要把多本书变成 skill每次敲一大串参数会很烦。我是这样固化的#!/usr/bin/env bash set -euo pipefail BOOK_PATH$1 SKILL_NAME$2 DESCRIPTION$3 book-to-skill compile $BOOK_PATH \ --output $HOME/.claude/skills/$SKILL_NAME \ --name $SKILL_NAME \ --description $DESCRIPTION \ --split-level 2 \ --workers 6 \ --model deepseek-chat echo 编译完成$HOME/.claude/skills/$SKILL_NAME用法是./build-skill.sh ./book.pdf skill-name 技能描述。三条信息传参命令写死在脚本里以后想更新某本书的 skill改 PDF 路径重跑一遍就行。4. 常见问题与排查技巧实录4.1 PDF 解析出来一堆乱码怎么办我第一批编译就踩过一次。拿了一本带保护属性的 PDFpdftotext 输出正常但 book-to-skill 解析阶段却出来大量乱码。排查下来是部分页面的字体子集化问题某些字符映射不标准。解决方法是先用 qpdf 重新处理一道qpdf --decrypt input.pdf output.pdf再对 output.pdf 重新编译。遇到“文本层存在但解析乱码”的情况qpdf 这一招能解决七八成。如果 qpdf 处理后依然乱码基本可以判定为字体子集过深只能转 OCR 路线。另一个常见坑是表格。一份 PDF 里表格被页面切割camelot 识别出来的行列对不上。我调 camelot 的table_areas参数手动指定表格区域准确率从五成提到九成。不过这个参数需要针对具体页面调整批量处理时不必强求所有表格都完美宁可让表格原样进知识库也别让它错误地断行。4.2 蒸馏结果“正确但不完整”蒸馏阶段我遇到最多的问题不是答错而是漏。章节里一段过渡性的文字LLM 觉得“不重要”就直接过滤掉了但技术书里的过渡文字经常藏答案比如“上一章我们用了 A 方法但它在实时场景下失效所以这一章引入 B”——这种信息对于理解选型非常重要。解决办法有两个。一是调小分块粒度让模型看到更短的文本降低“概括冲动”。二是要求每条知识点都回填“来源章节和上下文”字段。这样即便模型漏了点你也能在事后检查时快速定位到原文判断是不是真漏了。我习惯在编译后随机抽三个小节对照原 PDF 逐段扫一遍半小时能换来整本 skill 质量的安心。4.3 Agent 不主动调用 Skill 怎么办Skill 编译好了Agent 也能搜到但它就是不触发。我遇到过一次后来发现是description写得有问题。原来我只写了“用于回答 ROS2 问题”太笼统Agent 无法把“topic 和 service 的区别”这种具体问题关联到这个技能上。改法是往 description 里塞触发词把“节点通信、话题/服务/动作、TF 坐标、URDF 建模、launch 文件、仿真部署”这类高频问题场景都列进去。Agent 的判断机制更像是关键词匹配加语义匹配触发词越具体命中概率越高。改完之后同样的问题重问Agent 第一轮就把 skill 加载了。4.4 编译太慢、中途卡死全本编译对时间要有预期。一本 300 页的书不含 OCR 的情况下蒸馏环节通常要调几百次模型接口几分钟到十几分钟都很正常。如果超出太多先看是不是并发参数开得太大被限流了把--workers调回 4 试试再看有没有启用缓存book-to-skill 支持把已蒸馏的章节缓存下来中断后重新运行能跳过已完成部分这个功能一定要开。要是单本书体量实在太大就按章切分。我试过把一本 900 页的运维手册拆成 5 个 PDF分别编译成 5 个 skill每个控制在 5 分钟以内。体验比一次全量编译好太多而且分出来的 skill 颗粒度也更好用。全书一个 skill 反而让 Agent 在检索时犹豫该翻哪个文件。4.5 常见问题速查表把这几个问题整理成一张表方便你遇到时快速对照。症状可能原因排查/解决解析输出乱码字体子集化或文件保护qpdf 重新处理后重试仍不行走 OCR表格行列错乱表格跨页、无边框指定 camelot table_areas或降级为纯文本蒸馏结果漏知识点分块过大调小分块要求回填来源章节Agent 不触发 Skilldescription 太泛在 description 中增加高频触发词编译卡住或限流并发过高调低 workers启用缓存分批编译回答与原文不符LLM 幻觉强制蒸馏输出带原文引用人工抽检5. 经验心得与可以继续扩展的方向5.1 我用下来最有价值的三个细节第一个细节不要执着于“全书一个 skill”。书是按章节组织的任务不是按章节发生的。把一本书拆成几个主题 skill反而贴近真实使用场景。我编译一本网络运维手册时刻意把“命令手册”“排障流程”“架构说明”拆成三个 skill用起来比一个大的顺手得多。第二个细节troubleshooting.md 一定要保留。很多技术书的精华就在“常见问题”章节。把这些内容单独抽出来Agent 面对报错类问题时能直接给出方案这是整本 skill 里被调用频率最高的文件。第三个细节知识的“来源”字段值得保留。虽然 Agent 回答时不一定展示出处但我在审查质量时全靠它定位原文。没有来源的知识是飘的有了来源skill 内部的每条结论都立得住。5.2 三个值得继续扩展的玩法我觉得这个工具的思路可以往三个方向延伸。第一个方向是把编译流程接进自动化流水线。公司内部的 PDF 规范、接口文档、运维手册每隔一段时间就更新。把 book-to-skill 编译命令封装成 CI 的一个任务文档一变更就自动重编 skill团队所有 Agent 共享的都是最新版知识。第二个方向是跨书合并。同主题的几本书各自编译后把 resources 下的文件合并、去重形成一个更全面的“专题 skill”。我试过把两本讲同款框架的书合并编译时间省一半内容覆盖面提升明显。第三个方向是“实践反哺”让 Agent 在实际使用 skill 的过程中把遇到的新问题、新案例回写到 troubleshooting.md 里。skill 就从“一本书的静态快照”变成了“会生长的知识库”这才真正解决了 PDF 读完就忘的根因——知识不再只是书里的它跟着使用场景持续演化。5.3 一点个人的坚持做了几次“书变 skill”的编译之后一个特别直观的变化是那本被我翻了无数次的《ROS2机器人开发从入门到实践》现在大部分问题我都是先问 Agent只有 Agent 答得不够仔细的时候才去翻书。Skill 替我做了一部分记忆工作而我终于能把精力放在真正需要理解的地方。如果你手里也有一批“读完就忘”的技术 PDF别急着清理书架。先用pdftotext扫一遍文本层能提取就直接交给你常用的 Agent让 book-to-skill 帮你把它变成一种可以反复调用的长期能力。这条路我替你试过了值得走。
技术书变Agent技能包：book-to-skill全解析
把一本书读透越来越像一件奢侈的事。尤其是 PDF 格式的技术书几百页翻下来真正留在脑子里的可能只有几个模糊的概念。我书架上的技术书一年能读完五六本可一到写代码、配环境、排查报错的时候能快速想起来的内容不到十分之一。试过摘抄、导图、Notion 笔记最后还是回到“翻书”这条原始路径。一开始我也觉得这思路有点“离大谱”——书还能编译PDF 读完就忘不是应该靠记笔记解决吗直到我在 GitHub 上刷到 book-to-skill 这个项目想法才彻底转变过来与其逼自己记住书里的每一条命令不如把整本书“编译”成一个 Agent 可以随身携带的 Skill 包随叫随到。book-to-skill 目前在 GitHub 上已经有 1.5 万左右的 star核心思路一句话就能讲清楚输入一本 PDF 技术书输出一个结构化的 Skill 技能包。这里的 Skill 不是那种“会写诗、会画图”的提示词模板而是 Agent 生态里正在流行的一种插件化能力单元——一个 Skill 通常由一个 SKILL.md 描述文件加若干资源文件组成Agent 根据任务场景判断要不要加载这个技能一旦加载就可以按里面的指引检索、调用、执行。这个思路解决的是三个很具体的问题第一PDF 是非结构化内容直接塞给 Agent 既放不进上下文窗口也没法精准定位第二技术书里大量代码块、命令、配置项在普通摘要流程里会被丢掉而 Skill 格式允许把这些内容原样保留并分类存放第三人是会遗忘的Agent 不会——只要 Skill 包还在知识就还在。它适合两类人一是想提升日常查阅效率、让 Agent 替自己“读书”的开发者二是正在做 Agent 应用想把垂直领域手册变成 Agent 长期能力的工程师。1. 从“读完就忘”到“编译成 Skill”先搞清楚人为什么会忘1.1 技术书阅读的三个认知陷阱先说第一个陷阱线性阅读不等于结构记忆。我们读书是按页码顺序来的但在实际工作里我们是用场景触发知识的——比如写代码时遇到“通信超时”你需要的不是书里第 3 章的定义而是第 7 章的排查步骤。看书时你建立的是“章节顺序”索引用的时候需要的是“场景到方案”索引两种索引对不上就会产生“我明明读过就是想不起来”的感觉。第二个陷阱是高亮和划线的错觉。划线那一刻你会觉得“这部分我掌握了”其实你掌握的只是熟悉感。熟悉感不等于检索能力。真正到用的时候你得从记忆里把这条内容调取出来而划线只是给原文做了个标记并没有在你大脑里建立可调用的知识结构。这也是为什么很多人笔记做了三大本遇到问题还是得翻原书。第三个陷阱是技术书的信息密度太高。作者写书时习惯于“前置引用”——第一章提到的参数要到第九章才解释完整。对读者来说阅读是线性推进的但知识依赖是网状交织的。读完前面几章后面的内容还没见到读到后面时前面的细节已经下沉。人类的工作记忆就这么大指望一遍阅读构建出完整网状索引本来就违背了大脑的工作方式。1.2 Skill 到底是什么给 Agent 配一本“岗位手册”如果给“Skill”下一个简单定义我会说它是 Agent 的一个可插拔能力包。一个标准的 Skill 目录通常包含两部分SKILL.md 负责描述“这个技能是干什么的、什么时候用、怎么用”resources/ 目录里装的是实际会被检索和引用的资料比如概念表、命令清单、配置模板、排障手册。打个比方Skill 之于 Agent就像岗位手册之于刚入职的实习生。手册不会让实习生变聪明但能保证他遇到问题时按图索骥不做无谓发挥。Agent 的能力上限还是取决于底层模型但有没有 Skill决定了它在特定领域“接得住话”还是“瞎编”。主流的 Agent 工具像 Claude Code、Codex 这类编程代理已经开始原生支持 skills 目录。你把一个 Skill 放进指定目录重启会话Agent 会自动读一遍 SKILL.md 的描述。之后遇到匹配的任务它就知道该去 resources 里翻资料了。1.3 为什么是“编译”而不是摘要或者摘抄很多人第一反应是给 PDF 做个摘要不就行了吗短一点Agent 不就能读了吗问题在于摘要天然只保留“结论”丢掉过程细节。技术书最值钱的是什么是参数表、边界条件、命令用法、报错信息、作者踩过的坑。这些东西恰恰在摘要里第一个被丢掉。做纯手工摘抄也不行几百页的书靠人挑重点既慢又漏摘出来的内容还带着个人偏好。book-to-skill 的处理方式更像“编译”它把非结构化的 PDF 文档逐步转换成结构化的、可检索的、面向 Agent 的知识产物。整个过程不是一次生成而是多级流水线——先还原文档结构再抽取知识点然后按类别聚合最后按 Skill 模板组装。可以理解为摘要像是故事的简介编译像是把小说改编成剧本杀——保留人物关系、时间线、关键场景并且让玩家Agent在游戏过程中能随时翻查对应的线索。2. 设计思路与核心技术点拆解2.1 四段式流水线是怎么设计的book-to-skill 把“书变成 Skill”拆成了四个阶段顺序很讲究不能乱。第一阶段是 PDF 解析把文件变成干净的文本流、表格和图片。第二阶段是结构识别重建目录树找到每个章节的边界、标题层级、代码块位置。第三阶段是知识蒸馏把已经结构化了的文本分块送入大模型提取概念、参数、代码、注意事项。第四阶段是 Skill 编译把蒸馏结果按模板组织成 SKILL.md 与 resources 目录。为什么把“结构识别”放在“蒸馏”前面因为直接对 PDF 原始文本做大模型提取会丢掉层级信息。先重建章节树后续每个知识块都能挂到具体章节下Agent 日后检索时既能答内容也能告诉用户“这个知识点在第几章”可追溯性一下就强了。2.2 PDF 解析层文本版和扫描版是两条完全不同的路PDF 解析是整个流程的地基。地基本来就不稳后面蒸馏出来的东西全是垃圾。我实测下来第一件事不是急着跑工具而是先确认这份 PDF 有没有文本层。在 Linux 下用一句话就能测pdftotext some-book.pdf - | head -50如果输出的是空白、乱码或一堆方框说明这份 PDF 本质是图片必须走 OCR 路线。如果输出正常才进入常规解析流程。常规解析里文本提取建议用 PyMuPDF速度快对大多数排版都稳定需要精细化处理表格时用 pdfplumber 或 camelot。表格是 PDF 解析里最麻烦的东西一行文本被表格线切得七零八落顺序完全错乱。camelot 是少有的能按视觉线索重新拼表的开源工具。扫描版 PDF 就绕不开 OCR。常见选择是 Tesseract 或 PaddleOCR中文扫描件我实测 PaddleOCR 效果好很多。不过 OCR 慢一页一秒到几秒不等一本 300 页的书可能要跑十几分钟。所以我的建议是能找文字版 PDF 就优先找文字版OCR 是最后手段。2.3 内容蒸馏层从“信息”到“知识”的关键一跳解析出来的文本只是“信息”零散地躺在那里。蒸馏要做的是从里面提炼出“知识项”。我给蒸馏环节设定过一组提取目标包括概念定义、API 签名、命令用法、参数表、配置模板、示例代码、报错说明、作者标注的注意事项。蒸馏也分两个层面。第一层是文本分块按章节、小节把内容切成适合大模型处理的块块与块之间保留上下文指针。第二层是提取每块输出一份 JSON里面包括知识点类型、要点内容、原文引用、所在章节。要求带原文引用是我在实践里从教训中得来的如果不要求模型会出现“看着合理但原文里根本没有”的幻觉内容。代码块还原是另一个容易翻车的点。PDF 排版的代码经常被分页截断、带行号、被页眉干扰。book-to-skill 内部会做行号剥离、接续行合并、缩进恢复把一段段被物理拆散的代码重新拼起来。反例知识和警告提示我也会特意保留技术书里作者花大篇幅写的“这里容易出错”往往比正文还值钱。2.4 Skill 打包层产物的组织方式决定好不好用蒸馏完的中间结果是 JSON 和 Markdown但这不是 Skill。真正好用的 Skill 要满足三个要求能被 Agent 识别、能快速定位内容、能承载多种资源。SKILL.md 开头的 front-matter 是给 Agent 看的“门牌号”。name 是技能名description 写清触发场景。description 写得好不好直接决定 Agent 会不会在正确的时机加载这个技能。resources 目录里的文件则按类型拆分concepts.md 放概念定义commands.md 放命令清单code-snippets.md 放可运行代码config-templates.md 放配置模板troubleshooting.md 放排障手册。index.json 是整套资源的目录索引它会告诉 Agent 每个主题去哪查。这看起来像是把 PDF 拆成了好几个小文件实质上是一次“重排”。原来的书是按章节组织的Agent 的工作方式是按任务组织的不重排的话Agent 每次都要全量翻一遍成本太高。3. 实操把一本技术书编译成 Agent 的随身 Skill3.1 环境准备装什么、配什么我先说环境准备。book-to-skill 是基于 Python 的工具建议用 Python 3.10 以上版本。安装就一条命令pip install book-to-skill如果同时要处理 OCR再装 OCR 引擎这里以 PaddleOCR 为例pip install paddleocr然后配置大模型接口。蒸馏环节需要调用 LLMbook-to-skill 会读取环境变量里的 API Key 和模型标识配置方法在项目 README 第一屏就有。我用的是 deepseek-chat够用且便宜如果你有别的模型改环境变量就行。装完先跑一下版本验证book-to-skill --version能输出版本号就说明依赖装全了。这一步在实际操作里经常被跳过去然后卡在编译中途报缺失依赖我不建议跳。3.2 核心命令与参数选择拿我手头这本《ROS2机器人开发从入门到实践》举例编译命令长这样book-to-skill compile ./ros2-practice.pdf \ --output ./skills/ros2-practice \ --name ros2-practice \ --description ROS2机器人开发实践手册用于回答节点通信、话题/服务/动作、TF坐标、URDF建模、launch文件编写、仿真与真机部署等问题 \ --language zh \ --split-level 2 \ --model deepseek-chat \ --workers 4几个参数值得说清楚。--split-level 2表示只拆到二级标题一章内部的小节当做一个整体处理。实践证明拆得太细会丢上下文拆得太粗会让分块超长二级是大多数技术书的甜点。--workers 4是蒸馏时的并发线程数对 API 类型的模型来说并发太大会触发限流4 到 6 是一个比较稳的区间。--language zh是让蒸馏结果的提示词和输出尽量保持中文毕竟技术书原样是中文强行翻成英文再返回反而增加错误率。如果你手里的 PDF 是扫描版要在命令里强制加--ocr并指定 OCR 引擎book-to-skill compile ./scanned-book.pdf --ocr --ocr-engine paddleocr这一步会很慢耐心等。第一次编译建议先挑一个章节的 PDF 做小规模测试跑通了再编译全书免得等二十分钟后发现问题还要重来。3.3 产物长什么样目录结构与示例编译完成后--output指定的目录里会出现如下结构skills/ros2-practice/ ├── SKILL.md ├── meta.json └── resources/ ├── concepts.md ├── commands.md ├── code-snippets.md ├── config-templates.md ├── troubleshooting.md └── index.json打开 SKILL.md 你会看到类似这样的一段内容--- name: ros2-practice description: 用于回答 ROS2 开发相关的问题。当用户咨询节点通信、话题/服务/动作、TF坐标、URDF建模、launch文件编写、仿真与真机部署时优先调用此技能。 --- # ROS2 实践手册 ## 使用说明 1. 先查询 resources/index.json 定位知识条目 2. 涉及代码时读取 resources/code-snippets.md 中的可运行示例 3. 涉及参数配置时读取 resources/config-templates.md 4. 遇到报错优先查 resources/troubleshooting.md ## 注意 - 本技能由《ROS2机器人开发从入门到实践》编译生成覆盖书内内容。 - 对于书中未涉及的知识点应明确告知用户书中未涉及不要臆造。这段描述给了 Agent 一个清晰的执行路径先查索引再按主题进文件。这就是“索引思维”的落地。3.4 挂载到 Agent三步完成上线Skill 编译好不算完关键在挂载。目前支持 skills 目录的 Agent 工具挂载方式基本一致。第一步把整个ros2-practice目录复制到 Agent 的 skills 目录下。比如你用 Claude Code通常放在~/.claude/skills/下其他工具就按各自的目录规范放。第二步重启会话让 Agent 重新扫描 skill 描述。第三步用几个典型问题做验证比如“ROS2 里 topic 和 service 的区别是什么”“launch 文件里怎么设置参数服务器”“URDF 里 joint 的 type 有哪几种”。看它是否主动加载了 skill回答是否与原文一致。我实测下来挂载后第一次对话如果触发正确后续使用会相当顺手。你甚至可以在提问里显式带上技能名大多数 Agent 都支持这种手动触发方式。3.5 一键编译脚本把流程固化下来如果以后要把多本书变成 skill每次敲一大串参数会很烦。我是这样固化的#!/usr/bin/env bash set -euo pipefail BOOK_PATH$1 SKILL_NAME$2 DESCRIPTION$3 book-to-skill compile $BOOK_PATH \ --output $HOME/.claude/skills/$SKILL_NAME \ --name $SKILL_NAME \ --description $DESCRIPTION \ --split-level 2 \ --workers 6 \ --model deepseek-chat echo 编译完成$HOME/.claude/skills/$SKILL_NAME用法是./build-skill.sh ./book.pdf skill-name 技能描述。三条信息传参命令写死在脚本里以后想更新某本书的 skill改 PDF 路径重跑一遍就行。4. 常见问题与排查技巧实录4.1 PDF 解析出来一堆乱码怎么办我第一批编译就踩过一次。拿了一本带保护属性的 PDFpdftotext 输出正常但 book-to-skill 解析阶段却出来大量乱码。排查下来是部分页面的字体子集化问题某些字符映射不标准。解决方法是先用 qpdf 重新处理一道qpdf --decrypt input.pdf output.pdf再对 output.pdf 重新编译。遇到“文本层存在但解析乱码”的情况qpdf 这一招能解决七八成。如果 qpdf 处理后依然乱码基本可以判定为字体子集过深只能转 OCR 路线。另一个常见坑是表格。一份 PDF 里表格被页面切割camelot 识别出来的行列对不上。我调 camelot 的table_areas参数手动指定表格区域准确率从五成提到九成。不过这个参数需要针对具体页面调整批量处理时不必强求所有表格都完美宁可让表格原样进知识库也别让它错误地断行。4.2 蒸馏结果“正确但不完整”蒸馏阶段我遇到最多的问题不是答错而是漏。章节里一段过渡性的文字LLM 觉得“不重要”就直接过滤掉了但技术书里的过渡文字经常藏答案比如“上一章我们用了 A 方法但它在实时场景下失效所以这一章引入 B”——这种信息对于理解选型非常重要。解决办法有两个。一是调小分块粒度让模型看到更短的文本降低“概括冲动”。二是要求每条知识点都回填“来源章节和上下文”字段。这样即便模型漏了点你也能在事后检查时快速定位到原文判断是不是真漏了。我习惯在编译后随机抽三个小节对照原 PDF 逐段扫一遍半小时能换来整本 skill 质量的安心。4.3 Agent 不主动调用 Skill 怎么办Skill 编译好了Agent 也能搜到但它就是不触发。我遇到过一次后来发现是description写得有问题。原来我只写了“用于回答 ROS2 问题”太笼统Agent 无法把“topic 和 service 的区别”这种具体问题关联到这个技能上。改法是往 description 里塞触发词把“节点通信、话题/服务/动作、TF 坐标、URDF 建模、launch 文件、仿真部署”这类高频问题场景都列进去。Agent 的判断机制更像是关键词匹配加语义匹配触发词越具体命中概率越高。改完之后同样的问题重问Agent 第一轮就把 skill 加载了。4.4 编译太慢、中途卡死全本编译对时间要有预期。一本 300 页的书不含 OCR 的情况下蒸馏环节通常要调几百次模型接口几分钟到十几分钟都很正常。如果超出太多先看是不是并发参数开得太大被限流了把--workers调回 4 试试再看有没有启用缓存book-to-skill 支持把已蒸馏的章节缓存下来中断后重新运行能跳过已完成部分这个功能一定要开。要是单本书体量实在太大就按章切分。我试过把一本 900 页的运维手册拆成 5 个 PDF分别编译成 5 个 skill每个控制在 5 分钟以内。体验比一次全量编译好太多而且分出来的 skill 颗粒度也更好用。全书一个 skill 反而让 Agent 在检索时犹豫该翻哪个文件。4.5 常见问题速查表把这几个问题整理成一张表方便你遇到时快速对照。症状可能原因排查/解决解析输出乱码字体子集化或文件保护qpdf 重新处理后重试仍不行走 OCR表格行列错乱表格跨页、无边框指定 camelot table_areas或降级为纯文本蒸馏结果漏知识点分块过大调小分块要求回填来源章节Agent 不触发 Skilldescription 太泛在 description 中增加高频触发词编译卡住或限流并发过高调低 workers启用缓存分批编译回答与原文不符LLM 幻觉强制蒸馏输出带原文引用人工抽检5. 经验心得与可以继续扩展的方向5.1 我用下来最有价值的三个细节第一个细节不要执着于“全书一个 skill”。书是按章节组织的任务不是按章节发生的。把一本书拆成几个主题 skill反而贴近真实使用场景。我编译一本网络运维手册时刻意把“命令手册”“排障流程”“架构说明”拆成三个 skill用起来比一个大的顺手得多。第二个细节troubleshooting.md 一定要保留。很多技术书的精华就在“常见问题”章节。把这些内容单独抽出来Agent 面对报错类问题时能直接给出方案这是整本 skill 里被调用频率最高的文件。第三个细节知识的“来源”字段值得保留。虽然 Agent 回答时不一定展示出处但我在审查质量时全靠它定位原文。没有来源的知识是飘的有了来源skill 内部的每条结论都立得住。5.2 三个值得继续扩展的玩法我觉得这个工具的思路可以往三个方向延伸。第一个方向是把编译流程接进自动化流水线。公司内部的 PDF 规范、接口文档、运维手册每隔一段时间就更新。把 book-to-skill 编译命令封装成 CI 的一个任务文档一变更就自动重编 skill团队所有 Agent 共享的都是最新版知识。第二个方向是跨书合并。同主题的几本书各自编译后把 resources 下的文件合并、去重形成一个更全面的“专题 skill”。我试过把两本讲同款框架的书合并编译时间省一半内容覆盖面提升明显。第三个方向是“实践反哺”让 Agent 在实际使用 skill 的过程中把遇到的新问题、新案例回写到 troubleshooting.md 里。skill 就从“一本书的静态快照”变成了“会生长的知识库”这才真正解决了 PDF 读完就忘的根因——知识不再只是书里的它跟着使用场景持续演化。5.3 一点个人的坚持做了几次“书变 skill”的编译之后一个特别直观的变化是那本被我翻了无数次的《ROS2机器人开发从入门到实践》现在大部分问题我都是先问 Agent只有 Agent 答得不够仔细的时候才去翻书。Skill 替我做了一部分记忆工作而我终于能把精力放在真正需要理解的地方。如果你手里也有一批“读完就忘”的技术 PDF别急着清理书架。先用pdftotext扫一遍文本层能提取就直接交给你常用的 Agent让 book-to-skill 帮你把它变成一种可以反复调用的长期能力。这条路我替你试过了值得走。