收藏 PDF 这件事技术人多少都有点上瘾。我本地大概存了上千本什么《TCP/IP 详解》《数据密集型应用系统设计》《Rust 设计模式》当年一个个从各个渠道捞回来感觉硬盘比脑子踏实。可等到真要在项目里解决一个问题比如“TCP 连接到了 SYN_SENT 卡住怎么排查”我能做的只有打开书翻目录、再搜一遍网页脑子里那点东西早不知道扔哪去了。去年发现的这个趋势让我开始认真对待“书读不完”这件事——不是靠笔记靠把书编译成一个 Agent 能直接调用的 Skill。如果你也经常遇到“PDF 读完就忘”的处境我想聊聊一个叫 book-to-skill 的开源项目GitHub 上 star 数已经超过 15k。它不是帮你做摘要也不是做一个简单的问答机器人而是把整本技术书里的知识点、代码片段、状态机、边界条件全部重构到一个可测试、可复用的 Agent Skill 里。简单说书还是那本书但它从“躺在硬盘里等你去翻”变成了“跟着 Agent 随时待命”。这篇东西不打算写成项目说明书就按我自己的实测体验来拆它到底解决了什么、内部是怎么编译的、我亲手把一本开源手册转成 Skill 的完整过程以及把三本书转完踩过的那些坑。1. 收藏一柜子 PDF本质上是为忘记做准备而已很多人的技术阅读流程是这样的看到一本好书下载 PDF翻了几十页觉得很有道理然后关掉。过两天想用某个细节发现书里好像写过但忘了在哪一章只能重新去翻目录。我一度把这归咎于“记性差”后来发现真正的问题出在知识管理方式上。1.1 笔记是在整理内容但没法在出问题时自动出现传统笔记擅长“压缩”。你读到一个概念用自己的话写一行记录贴个标签放进笔记软件。这个过程本身没有问题问题是它的召回方式是搜索。可实际工作中你往往不知道该搜什么关键词。比如你在排查一个分布式系统里“脑裂”的问题你可能不会想到去搜索书里某个专业术语而是直接用自己模糊的、不完整的描述去找。这时候基于原书关键词的笔记系统基本帮不上忙因为你不是在读那本书而是带着一个场景在找答案。1.2 “书架占满”带来的安全感和车积灰没什么区别下载文件时产生的那点“我早晚会看”的满足感对解决问题毫无帮助。我做过一个很幼稚的统计过去一年真正翻开的 PDF 不到收藏的十分之一而其中被二次翻阅的更是不到三分之一。书的价值不是“存在”而是“在正确的时间被正确的问题触发”。可 PDF 不具备触发性它是一堆静态字节等着你去寻觅。这让我意识到知识库应该像代码库一样被设计不光有结构和注释还要有能被调用的人口。你写了个工具函数没人调用就是死代码你读完一本书没有触发入口那也是死知识。book-to-skill 打动我的第一点就在这里它把“静态的知识集合”编译成了“可被事件触发的技能包”。2. book-to-skill 的思路不是总结书而是把书编译成能运行的技能一开始我以为这类项目就是“读 PDF生成一份摘要再让 LLM 记住摘要”。实际用下来发现完全不是一回事。摘要和 Skill 是两个维度的东西。2.1 摘要回答“书里说了什么”技能回答“现在该调什么”你问“TCP 重传是怎么工作的”摘要可以给你一段漂亮的概述。但技能不一样它更像你装进 Agent 里的一个工具子模块包含触发条件什么类型的问题应该让 Agent 去查询这本书索引内容该书的关键章节、参数表、流程图状态在哪个位置响应策略拿到问题后是直接返回书里的定义还是组合几段内容还是借用代码示例演示。举个例子。我用手头的《TCP/IP 详解》转了一个 Skill里面配置了一个叫tcp_state_lookup的工具输入一个 TCP 状态名返回的是书里对该状态的全部分析、典型成因和排查路径。它不是让 Agent 去“回忆”书里写了什么而是让 Agent 按需调用一块结构化的知识。2.2 代码可以测试知识也可以变成可测试的东西很多人对“把书编译成技能”这个概念觉得玄换个角度就好理解了普通代码可以跑单元测试book-to-skill 做的事就是让“知识”也能跑评估。它把你的技术书生成一个带明确输入输出的 Skill 定义然后用一份测试集去检验这个 Skill 回答得对不对。我在后面专门有一节讲评估这里先说结论知识一旦能被测试就不再依赖某个模型当时的“心情”。配套能力的第一个小环节是“触发条件表”。我把它理解成一个代理消息里的路由表不同话题进入不同子模块。这个设计是实用的因为 Agent 本身的上下文空间有限把整本书塞进 Prompt 是不现实的。多改成动态加载是这类工具最有价值的地方。3. 管道的内部PDF 解析、数据切片、示例提取和技能打包book-to-skill 不是单点魔法它是一条流水线。我分三段来拆每一步都有容易忽略的细节。3.1 预处理把 PDF 变成可分析的结构化文档PDF 是一堆排版元素的堆叠直接丢给大模型处理效果很差。常规做法是用 pdfplumber 或者 PyMuPDF 先把版面抽出来但 book-to-skill 做得更细识别页眉页脚和水印避免把“第 73 页”“第二章”这类信息当成正文识别目录结构生成一个章节树作为后续分块的主干表格区域单独提取转成 Markdown 表格而不是纯文本代码区域用代码块的格式边界标记避免缩进被破坏。这一步我一开始没在意后来发现影响极大。技术书里大量重要的内容是表格和代码块如果解析时把它们混成普通段落最后生成的知识索引会漏洞百出。比如一个网络协议的状态迁移表转成文本后可能各列顺序全部乱掉Agent 引用的内容就全错了。3.2 技能定义文件用一份 YAML 把技能结构化预处理完成之后工具会生成一个技能定义文件这是我见过它最核心的部分。下面是一个简化后的例子name: tcp-illustrated-skill version: 1.0.0 language: zh-CN description: 基于《TCP/IP 详解 卷一》编译的技能包。 当用户询问 TCP 状态迁移、重传机制、拥塞控制、三次握手细节时 优先使用本技能的回答路径。 source: book: tcp-ip-illustrated-vol1 chapter_tree: chapters/tree.json stages: - id: identify description: 判断问题属于哪个协议子域 routes: - topic: tcp-state tool: tcp_state_lookup - topic: tcp-retransmission tool: tcp_retransmission_analysis - topic: congestion-control tool: rfc_5681_notes - id: compose description: 根据查询结果组合最终回答 style: concise-technical tests: - input: 客户端处于 SYN_SENT 状态一直不进入 ESTABLISHED可能是什么原因 expect_tool: tcp_state_lookup expect_match_source: true这份定义文件同时服务两个对象人对技能做审计、Agent 对技能做路由。它对“什么时候该用这本书”做了显式声明而不是让 Agent 自由发挥。这个设计很聪明等于在上层做了一个模块路由表避免了一个 Agent 什么都知道、什么都不精的问题。3.3 测试和评估为什么这是必不可少的一环真正让它区别于“一个高级的 PDF 解析器”的点是 pipeline 里带了一个评估环节。生成技能之后工具会用一套测试题对技能打分比如输入“TCP 的 TIME_WAIT 状态为什么要等 2MSL”输入“快速重传和超时重传触发条件有什么不同”标准是Agent 是否调用了正确的工具返回内容是否能在原书对应位置找到依据。听起来容易做起来难。实测中我见过一种典型失败技能定义里配置的触发条件太宽泛Agent 遇到几乎所有网络问题都去调用这本书导致某些应该用实际抓包数据分析的场景它却只根据书里的理论给建议。所以评估不是跑完就行还需要人工抽样看调用链。4. 动手实操把一本开源手册变成 Agent 随身技能理论说再多不如自己跑一遍。我特意挑了一本强操作性的手册来做演示因为我发现不是所有书都适合转换成技能。4.1 哪些书适合优先转成技能适合的一句话总结是“查得比读得多”的书协议文档、框架使用手册、语言标准库说明、命令参考。这类书天然有明确的问题入口和标准答案非常适合编译成技能。不太适合的是长篇论述型的技术散文书比如讨论架构哲学、团队管理的。这类书的价值在阅读过程中的思考不在快速检索。非要转的话也可以但效果远不如操作手册那么直接。4.2 完整构建命令与典型输出我用了项目提供的命令行工具过程大致是这样的# 安装 pip install book-to-skill # 编译 PDF 为技能包 book2skill compile \ --input books/rust-design-patterns-v2.pdf \ --name rust-patterns \ --lang zh \ --output-dir skills/rust-patterns # 验证技能包能否正常加载 book2skill verify --skill skills/rust-patterns # 跑内置评估 book2skill eval \ --skill skills/rust-patterns \ --seed 42 \ --fraction 0.2第一次跑完终端里输出的信息让我心里一凉[1/20] 通过可以用枚举表达可选值 工具命中option-enum [2/20] 通过状态管理模式如何选择 工具命中state-pattern ... [17/20] 失败Builder 模式和 Fluent Interface 的差异 工具命中builder-pattern第 17 题失败的原因让我排查了很久。问题不是书里没讲而是我生成的技能里把这个话题归错了章节导致 Agent 调用了builder-pattern而内容里缺少了和 Fluent Interface 对比的一小节。这类问题是编译阶段章节归属错误不是模型能力问题。手动修正技能定义里的路由规则后评估分数从 85 分提到了 96 分。4.3 参数选择切片大小的取舍实操中我最纠结的是分块大小。默认配置把每个章节按 800 字左右切一个块但技术书里的“概念定义”和“代码示例”密度不均匀固定长度切分很容易把完整语义截断。我对比了三组参数切片方式优点缺点适用场景固定长度 800 字实现简单生成快易切断关键代码块快速出原型按章节结构切语义完整块长短不一索引粒度粗章节特征明显的书混合切片兼顾语义和粒度参数调起来费时间正式使用推荐实操下来混合切片最稳先按章节树做一级划分遇到代码块和表格时强制独立成块其余位置再按段落聚合。这样既保证了语义完整又不会让某一块因为只包含一张大表格而显得臃肿。5. 有了技能之后代理行为变化有多大书转成技能后最明显的变化不在速度在“确定性”。5.1 直接问答和技能调用结果差距比想象的大我做过一组对比实验。同一本书同一个问题集合一半问题直接丢给 Agent 裸答另一半走技能调用。裸答的问题是模型很可能输出一段听起来正确但缺少边界条件的回答。比如问“事务的隔离级别”裸答可以把四种隔离级别背下来但一旦问“MySQL 默认隔离级别在哪个隔离级别下会出现幻读”模型就可能混淆不同数据库的默认值。走技能调用后Agent 会先定位到书中对应数据库章节再带出书里明确的参数层结论。第二个明显的差异是技能返回的内容通常带明确的“来源章节”和“适用条件”排查问题的时候你在哪里看到的数据一目了然不会变成一团浆糊。5.2 技能编号管理我的偏好247 还是 193我在本地测试环境里有几百个技能它们绝大多数是实验性质的装多了路由反而混乱。我的习惯是给每个技能编一个短数字 ID。比如把《TCP/IP 详解》编译结果编号为 247把《网络运维 7 天上岗》的实践类技能编号为 193。原因是顶层代理系统里我会维护一个技能启停清单按 ID 而不是名字来切换避免不同技能间命名相近导致的路由冲突。{ skill_router: { enabled: [247, 193], excluded: [088] } }这套方式本质上是在代理配置层做“技能白名单”。除非明确给某个技能分配 ID否则不会让它参与路由这样做的最大好处是减少 Agent 上下文里的噪音。一个大型 Agent 如果同时装载几百个技能光是一个推理步骤里筛选工具就要浪费很多 token。5.3 确定性从哪里来大家常问Agent 调用技能和直接读 PDF 进 context 到底差在哪答案是技能定义里显式标明了工具函数和返回内容的来源。在纯 RAG 模式里模型先检索再决定怎么答检索出来的片段是松散的。而技能模式里工具函数被固定成tcp_state_lookup(状态名)这样的接口。模型被约束在调用这个接口那么返回内容就严格来自接口背后的结构化知识库。模型可以发挥的部分是“如何组织语言”而不是“编造事实”。模型自由发挥的空间变小了答案的稳定性自然就上来了。6. 踩坑记录我把三本书编译成技能之后的教训纯看项目文档一切都是丝滑的。真把三本书编译完才知道坑都在细节里。6.1 坑一把整个章节硬塞进上下文最早我为了省事把一个章节的全部内容直接塞进技能定义。结果那本手册一个章节有 2 万多字导致加载缓慢而且 Agent 在处理具体问题时反而被大量不相关的内容干扰。正确的姿势是在技能定义里只保留“索引”和“路由”把完整内容放在外部数据文件里按需加载。用一句话类比技能应该像一个命令库不是一个文档库。6.2 坑二把原书的目录直接当技能 schema技术书的目录是给人跳读用的不是给 Agent 执行任务用的。比如《Rust 设计模式》的目录里有“附录 A版本兼容性说明”如果你把它当工具入口Agent 碰到任何和异步相关的问题时根本不会触发正确的章节。真正的触发条件应该基于用户意图比如“处理可空类型”“构建复杂对象”“限制共享资源的并发访问次数”而不是“第 3 章”。手动改路由规则是一个很费时间的活但这一步不能省。我甚至建议在编译完技能后拿一个真实问题清单过一遍看命中率和答案准确性。6.3 坑三忽视了 PDF 里的图形表格技术书不是纯文本。很多关键内容藏在架构图、流程图、状态表里。普通的 PDF 转文本流程不会保留“图 A 里那条环形箭头的含义”。book-to-skill 的表格提取相对可靠但它是基于图还是基于文字的如果书里的状态迁移图是一张位图那生成的结果大概率会缺少这条信息链路Agent 只能依赖文字部分去猜。我后来补了一个人工环节把每本书里的关键图表手动补充一段 Markdown 描述再手动绑定到对应章节的索引里效果立竿见影。如果你纯粹依赖自动流程建议在评估阶段重点检查所有“图相关”的题目。6.4 坑四不做人工抽检就把技能上线自动评估分数高不代表真实业务场景没问题。我的实测里出现过很诡异的案例评估集全部通过但实际使用时 Agent 在用户连续追问的场景下会跳错路由第一次调用书中函数第二次又切回默认大模型回答产生了两个相互矛盾的意见。原因是评估集里都是“单轮问题”缺少对“多轮对话下状态保持”的测试。自那以后我在每次技能生成后都会保留少量 golden questions再额外加一组多轮对话场景做人工抽检。这个过程有点费时间但总归比让一个一本正经的 Agent 拿着错误资料去生产环境里坑人踏实。整个流程走下来我最大的感受是book-to-skill 让我终于把一部分“知识资产”变成了“可用资产”。电子书还是那本电子书但我不再需要读完再忘、忘了再找。我只需要把适合查询的内容编译成技能交给 Agent 挂着问题来的时候它自己知道去调用哪块内容。这种方式谈不上能把所有书都变成大脑的一部分但对我这种靠查文档干活的人来说它至少让我少折腾了几百次 CtrlF。