年初整理硬盤的時候我有點破防三百多個技術(shù)類 PDF真正看完的不到十個能記住內(nèi)容的接近于零。技術(shù)書這個品類很奇怪——讀的時候每句話都懂合上 PDF 之后就像被格式化了。去年年底我在 GitHub 上看到一個 15k Star 的項目叫 book-to-skill干的事情很直接把技術(shù)書編譯成 Agent 能直接加載的 Skill。我當(dāng)時的反應(yīng)確實是標(biāo)題那四個字離大譜。技術(shù)書居然能被編譯而且編譯產(chǎn)物不是筆記不是摘要是一個 Agent 的隨身技能包。這篇就聊聊這個項目到底是什么、底層怎么工作、我實際用下來怎么樣。1. 為什么讀完就忘是技術(shù)人最痛的隱性成本1.1 技術(shù)書的閱讀方式和實際工作方式天然沖突得先把這個問題的根源說透。技術(shù)書的組織方式幾乎永遠(yuǎn)是線性的從第一章到最后一章前面章節(jié)給后面鋪墊每章默認(rèn)你已經(jīng)掌握了前置知識。但真實工作中遇到的問題是非線性的。你面對的往往是一個具體而微的任務(wù)比如內(nèi)網(wǎng)機器連不上外網(wǎng)網(wǎng)關(guān)怎么排查這時候你需要的是路由、防火墻、抓包工具、配置命令——它們分散在《網(wǎng)絡(luò)運維7天上崗》的第六、九、十二章里可能還跨了附錄。這就是讀完就忘的真相不是你記性差是書的順序和你的需求順序完全錯位。線性閱讀積累的知識要在非線性場景里被調(diào)用本來就需要額外的索引和檢索能力。絕大多數(shù)人沒有這個索引系統(tǒng)于是知識就停留在眼熟的層面。我也試過很多對抗遺忘的方法畫思維導(dǎo)圖、做筆記、高亮、寫技術(shù)博客。效果最好的時候也就是知道去哪查的程度。等到真上了生產(chǎn)環(huán)境照樣手忙腳亂地翻書翻筆記。原因是這些方法本質(zhì)上都是在做一個古老的索引而索引的消費方式還是人肉查找沒有解決最核心的效率瓶頸。1.2 筆記、收藏夾、知識庫都沒有跳出同一個框架市面上已經(jīng)有很多知識管理方案了。筆記軟件幫你分類收藏AI 搜索引擎幫你做摘要RAG 知識庫讓模型引用原文。但這些方案都有一個共同毛病它們返回的是資料不是操作方法。舉個例子。你把一本 ROS2 的書扔進 RAG 知識庫問怎么創(chuàng)建一個話題發(fā)布者系統(tǒng)會給你返回書里相關(guān)的兩段文字和示例代碼?？雌饋頉]問題但你要做的事是創(chuàng)建一個可編譯、可運行的節(jié)點這中間還差著工程環(huán)境的配置、依賴的安裝、編譯工具鏈的選擇。知識庫只能把原文撈出來它不會告訴你在這個版本、這個環(huán)境下應(yīng)該按什么步驟逐步做。這個差別非常關(guān)鍵。Agent 時代的技能調(diào)用的不是資料是操作序列。book-to-skill 的切入點就在這里它把書里的知識重新編譯成一份遇到什么場景、按什么順序、執(zhí)行哪些操作的指令包也就是 Skill。這比召回文檔片段離能干活近得多。1.3 把書編譯成 Skill到底改變了什么Skill 這個詞在這兩年已經(jīng)不是新概念了。很多 Agent 框架里Skill 就是一組能力描述文件告訴模型你會什么、什么時候該用、具體怎么干。book-to-skill 特殊就特殊在它把整個輸入源從零散筆記變成了一整本技術(shù)書的系統(tǒng)性編譯結(jié)果。一本技術(shù)書能被當(dāng)作編譯輸入這件事本身就很反直覺。書在大多數(shù)人眼里是一堆文字的集合但在項目作者眼里它是結(jié)構(gòu)化知識目錄是索引章節(jié)是模塊代碼和命令是接口腳注和注意項是邊界條件。把這些結(jié)構(gòu)抽出來再按 Agent 的執(zhí)行邏輯重新打包一本幾百頁的書就變成了一個可以裝上就用的能力模塊。我之前也懷疑過這會不會只是把 PDF 轉(zhuǎn)成 Markdown 再塞給 Agent深入了解之后發(fā)現(xiàn)如果只是那樣項目根本不會火到 15k Star。真正的價值在中間那幾層轉(zhuǎn)化。2. book-to-skill 的架構(gòu)拆解PDF 到 Skill 的四步流水線2.1 輸入側(cè)的寬容度先搞清楚你的 PDF 是什么類型我把項目實際跑通之后最大的感受是它把輸入解析這事做得比想象中重。很多 PDF 工具解析失敗問題往往不在解析代碼而在前置的文件體檢。這就像你讓廚師做飯得先告訴他食材是鮮肉還是凍肉。技術(shù)書 PDF 從來源上可以分為三類。第一類是文本型 PDF文字可以直接提取解析最順暢。第二類是掃描版 PDF整頁就是一張圖必須先過 OCR。第三類是從網(wǎng)頁打印生成的 PDF這類文件最陰間——書里往往帶著頁眉頁腳、超鏈接塊、分欄樣式甚至還有廣告位殘留。熱詞里大家反復(fù)搜web頁面pdf打印就是在問這類的處理辦法。book-to-skill 的處理思路是解析前先做一次文件體檢用工具快速判斷 PDF 是否含文本層、是否帶目錄書簽、每一頁大概有多少文字密度。體檢結(jié)果決定后續(xù)走純文本解析、OCR 識別、還是混合路線。這一步我后來在自己的工具鏈里也一直保留它省掉了大量無效重跑。2.2 章節(jié)結(jié)構(gòu)化目錄頁就是整本書的數(shù)據(jù)庫編譯過程里最有價值的一步是構(gòu)建章節(jié)樹。技術(shù)書幾乎都有目錄頁目錄頁里藏著全書的骨架章節(jié)標(biāo)題、層級關(guān)系、起始頁碼。book-to-skill 會把目錄頁當(dāng)作核心線索先把條目抽取出來再根據(jù)頁碼反向定位正文把每一章切出來。這個邏輯聽起來簡單實際操作坑很多。書內(nèi)的第 1 章往往從第 1 頁開始但 PDF 物理頁可能已經(jīng)翻到第 8 頁了因為前面還有封面、版權(quán)頁、序言、前言。目錄里標(biāo)注的頁碼是印刷時的邏輯頁碼不是 PDF 的物理頁碼。這個偏移量如果不算準(zhǔn)后續(xù)所有章節(jié)定位都會錯位。還有更隱蔽的問題有些書分冊導(dǎo)出的 PDF 沒有書簽?zāi)夸涰摾锏捻摯a還是冊內(nèi)頁碼需要重新拼合有些書目錄里的章節(jié)標(biāo)題和正文里的實際標(biāo)題不完全一致多了個空格或換了說法字符串匹配就斷了。項目里顯然處理了這些 dirty work因為我在實測中沒遇到章節(jié)錯亂。2.3 內(nèi)容蒸餾Agent 不需要全文需要關(guān)鍵時刻用得上的部分這是我認(rèn)為項目最核心的設(shè)計決策。一本書十五萬字Agent 的上下文窗口再大也不可能把全文常駐內(nèi)存。所以編譯過程里必須做蒸餾剔除掉敘述性的鋪墊、重復(fù)強調(diào)、文字化的過程解釋保留那些Agent 執(zhí)行時真正必須的原子信息。優(yōu)先級是這樣的命令行代碼、配置文件示例、參數(shù)表格、報錯信息、注意項、版本兼容說明是第一梯隊原理性解釋、歷史背景、橫向?qū)Ρ仁堑诙蓐犠髡叩膫€人心得和行業(yè)展望基本被壓縮成一句注解。換句話說這本書被編譯成了給一個熟練但失憶的工程師看的速查手冊而不是給初學(xué)者看的教程。這個蒸餾策略直接決定了 Skill 的實用度。我見過一些類似項目它們把書喂給大模型生成一堆這本書講了什么的摘要那種東西對 Agent 沒有用。Agent 需要的是可執(zhí)行的if-this-then-that不是感想。book-to-skill 在這一點上相當(dāng)清醒。2.4 輸出側(cè)Skill 文件的組織方式編譯產(chǎn)物不是單個大文件而是一個有結(jié)構(gòu)的目錄這是另一個值得說的設(shè)計。通常一個 Skill 文件夾里包括一個元信息文件SKILL.md里面寫清楚這個 Skill 叫什么、觸發(fā)條件、適用范圍然后按章節(jié)拆分的知識文件再配一份索引文件讓 Agent 在加載技能時能快速定位到對應(yīng)模塊。這樣的組織結(jié)構(gòu)順帶解決了 Agent 加載技能時的檢索問題。Agent 不需要每次都掃描所有章節(jié)內(nèi)容它只看索引和元信息命中之后再打開具體章節(jié)文件。這跟人類讀書的邏輯是一樣的先翻目錄再翻頁而不是從第一頁開始背。2.5 為什么是 Skill不是向量知識庫這里值得停下來做一個對比不然很容易和 RAG 方案混淆。我直接用表格說清楚兩者差異對比維度向量知識庫Skill 文件存儲形式嵌入向量語義化結(jié)構(gòu)化 Markdown指令化查詢方式相似度召回目錄索引 觸發(fā)條件返回結(jié)果相關(guān)文檔片段成套操作流程上下文損耗每次召回都要塞進對話命中后按需加載適用場景開放域問答固定任務(wù)的技能執(zhí)行兩者不是替代關(guān)系是互補關(guān)系。知識庫適合你也不知道該問什么的探索式場景Skill 適合明確要干某件事的執(zhí)行式場景。而你讀一本技術(shù)書往往就是為了獲得某種明確的執(zhí)行能力。這就是 book-to-skill 選擇 Skill 作為輸出格式的根本原因。3. 源碼級還原幾個關(guān)鍵實現(xiàn)細(xì)節(jié)與驗證3.1 表格和代碼塊是怎么保住完整性的PDF 解析的經(jīng)典難題是視覺布局被轉(zhuǎn)成文本流之后順序全亂。雙欄排版的書籍尤其嚴(yán)重按文本流提取時左欄的一行和右欄的一行會交叉拼接讀起來像加密電報。項目里對這類問題用了坐標(biāo)排序先判斷每個文本塊的坐標(biāo)位置按 x、y 重新排列還原雙欄的閱讀順序。代碼塊的保真又是另一個層次的問題。書里的代碼經(jīng)?？珥摀Q頁時會被折行甚至截斷。如果單純按段落提取一段完整的函數(shù)會被拆成兩半中間混入頁眉頁碼。book-to-skill 的做法是識別代碼塊特有的特征——縮進、關(guān)鍵字密度、特殊符號——然后把跨頁的代碼塊重新拼接起來剔除插入的干擾行。3.2 目錄頁碼偏移的修正邏輯前面提到印刷頁碼和 PDF 物理頁碼之間存在偏移。項目里對這個問題的處理可以歸納為三步。第一步從目錄頁拿到所有章節(jié)的邏輯頁碼。第二步在正文區(qū)域找第一章標(biāo)題所在位置算出它的物理頁碼。第三步用物理頁碼減去邏輯頁碼得到偏移量再把這個偏移量應(yīng)用到所有章節(jié)。這個邏輯在大多數(shù)書上都成立因為偏移量基本是一個常數(shù)。但也遇到過例外前言使用了羅馬數(shù)字編頁正文從數(shù)字 1 重新開始還有的書把附錄單獨編頁目錄里卻用了和正文連續(xù)的頁碼。項目對這類異常做了容錯最明顯的是多級回退自動定位連續(xù)兩章的實際物理頁倒推每一章的偏移而不是假設(shè)全書一個偏移量。3.3 掃描版書目和 OCR 兜底并不是所有 PDF 都有干凈的文本層。測試《ROS2機器人開發(fā)從入門到實踐》時我故意用了掃描版結(jié)果項目直接走 OCR 分支。OCR 的難點集中在中文內(nèi)容上中英文混排、代碼里的特殊符號、全半角引號識別結(jié)果經(jīng)常出現(xiàn)肉眼可見的錯誤。我的實操建議是能找文本版就找文本版OCR 是兜底方案不是優(yōu)選方案。如果不得不 OCR至少把識別結(jié)果里出現(xiàn)頻率異常的低字母數(shù)字詞單獨抽出來做人工復(fù)核尤其是命令和參數(shù)。熱詞里有人搜pdf圖片中文設(shè)置應(yīng)該就是卡在了這一步。另外注意系統(tǒng)里要裝好中文字體包不然識別結(jié)果和渲染預(yù)覽都會缺字這個是小坑。3.4 Skill 文件的內(nèi)容風(fēng)格怎么去掉AI 味熱詞里有個很扎眼的搜索詞去ai味的skill。我在翻編譯產(chǎn)物的時候也注意到這個點。同樣是總結(jié)一件事有的 Skill 寫本章講解網(wǎng)絡(luò)基礎(chǔ)概念包括 IP、路由、VLAN 等這種寫法就是純 AI 味等于什么都沒說。好的 Skill 應(yīng)該寫當(dāng)需要配置 VLAN 時執(zhí)行以下命令序列并檢查 switchport 狀態(tài)。所以在蒸餾環(huán)節(jié)項目有意識地做了操作導(dǎo)向改寫把書里的陳述句盡量改寫成祈使句和條件句。這不是簡單的文字游戲而是讓 Skill 文件在 Agent 加載后直接具備執(zhí)行力。我第一次打開編譯產(chǎn)物時看到很多章節(jié)文件的開頭是目標(biāo)...條件...步驟...當(dāng)時就明白這個項目為什么好評多。4. 實操全記錄把《網(wǎng)絡(luò)運維7天上崗》編譯成隨身 Skill4.1 環(huán)境準(zhǔn)備安裝與依賴我實際操作的流程從 clone 項目開始。為了不把這篇寫成考古報告我直接給出一份可以照抄的操作記錄。# 克隆項目到本地 git clone book-to-skill倉庫地址 cd book-to-skill # 創(chuàng)建并激活 Python 虛擬環(huán)境 python -m venv .venv source .venv/bin/activate # 安裝依賴 pip install -r requirements.txt依賴?yán)锖诵牡氖?PDF 解析庫和 OCR 組件。如果你是 macOS 或者 Linux還需要保證系統(tǒng)里裝好了對應(yīng)后端Windows 上如果 OCR 組件起不來可以先跑純文本型 PDF 的文件掃描版后置處理。我的經(jīng)驗是先用一本文字版的書跑通全流程再上掃描版否則容易分不清是項目的問題還是環(huán)境的問題。4.2 執(zhí)行編譯幾個值得關(guān)注的入?yún)⒕幾g命令不長但參數(shù)決定產(chǎn)物質(zhì)量。我這次用《網(wǎng)絡(luò)運維7天上崗》做輸入命令是這樣的python -m b2s \ --input 網(wǎng)絡(luò)運維7天上崗.pdf \ --output ./skills/network-ops \ --split-by-chapter \ --keep-images--split-by-chapter是按章輸出這個參數(shù)極力推薦。它讓每個章節(jié)文件保持在幾百行以內(nèi)Agent 加載時不需要把整本書讀進上下文。--keep-images會保留圖片并把圖片在原書中的頁碼記錄到引注里方便回溯。如果換成不帶這個參數(shù)的默認(rèn)編譯某些圖文并茂的書會丟失大量拓?fù)鋱D信息。執(zhí)行時間取決于 PDF 頁數(shù)和是否走 OCR。我這本書兩百多頁純文本版壓在一分鐘以內(nèi)掃描版的一個文件跑了快十分鐘過程中我還擔(dān)心是不是卡死了后來看日志發(fā)現(xiàn)是在逐頁 OCR。建議編譯大文件時加上--verbose至少能看到進度。4.3 編譯產(chǎn)物長什么樣編譯結(jié)束后輸出目錄的結(jié)構(gòu)和預(yù)期一致network-ops/ ├── SKILL.md ├── INDEX.md ├── 01-網(wǎng)絡(luò)基礎(chǔ).md ├── 02-路由與交換.md ├── 03-網(wǎng)絡(luò)安全.md ├── 04-故障排查.md └── assets/ ├── 011-拓?fù)鋱D01.png └── 047-抓包示例.pngSKILL.md 里寫的是元信息技能名稱、主要適用場景、觸發(fā)條件、依賴環(huán)境。INDEX.md 是索引列出各章核心知識點和對應(yīng)文件。章節(jié)文件則是蒸餾后的操作手冊。我打開03-網(wǎng)絡(luò)安全.md里面把防火墻策略配制的步驟、常用規(guī)則模板、排查命令幾個部分寫得干凈利落基本可以直接照做。4.4 把 Skill 交給 Agent 的三種加載方式有了 Skill 文件接下來就是讓 Agent 用起來。我試過三種方式都能跑通。第一種是放在 Agent 平臺的技能目錄里。很多框架包括熱詞里頻繁出現(xiàn)的 Codex、workbuddy、hermes agent都有約定的技能目錄把編譯出來的文件夾軟鏈進去Agent 重啟后就能識別。第二種是通過框架的導(dǎo)入命令把 SKILL.md 注冊為可用技能。第三種是我自己搞的把 INDEX.md 的內(nèi)容直接寫進系統(tǒng)提示詞告訴 Agent遇到相關(guān)任務(wù)去查看某個文件再用代碼解釋器讀取對應(yīng)章節(jié)。第三種方式簡陋但通用性最強適合不開放插件機制的 Agent。4.5 實測效果從翻書找答案到直接執(zhí)行指令測過一次很典型的任務(wù)用這套 Skill 完成為一個無狀態(tài)服務(wù)器配置基本安全策略。我沒有給任何具體命令只是把任務(wù)描述發(fā)給 Agent同時告訴它可以參考 network-ops Skill。結(jié)果是 Agent 自動定位到了03-網(wǎng)絡(luò)安全.md和04-故障排查.md生成了完整的防火墻規(guī)則配置序列還根據(jù) INDEX.md 里的提示主動檢查了服務(wù)端口。整個過程沒有把原書文本召回用的就是編譯產(chǎn)物里的操作指令。這個體驗讓我意識到隨身 Skill這個詞名副其實——這不再是搜索引擎加書簽而是一個裝了知識的操作員。5. 邊界與風(fēng)險這個項目解決不了什么以及我的應(yīng)對5.1 上下文窗口的賬不會憑空消失編譯再高效一本書的信息量也擺在那里。如果一本書實在太厚蒸餾后的 Skill 仍可能超過 Agent 的單次上下文。熱詞里有人搜ai agent 怎么扛并發(fā)還有人在討論上下文管理說明這是普遍痛點。我的應(yīng)對非常簡單按章拆多個 Skill或者用INDEX.md做路由。遇到具體問題時先讓 Agent 讀索引再按需加載對應(yīng)章節(jié)文件。永遠(yuǎn)不要讓模型一次性讀完整個技能包。5.2 技術(shù)書的時效性比想象中更嚴(yán)峻技術(shù)書從寫作到出版到被掃描成 PDF中間隔著時間差。網(wǎng)絡(luò)運維這類相對穩(wěn)定的領(lǐng)域還好但凡是涉及新版本框架的書編譯出來的命令可能已經(jīng)過時。我在實測 ROS2 那本書時就注意到書里有些依賴安裝命令在新版本下已經(jīng)棄用。我的建議是在 SKILL.md 里顯式記錄源書版本、適用環(huán)境、最后驗證時間。這不是技術(shù)問題是使用習(xí)慣問題但能救人一命。另外重要的高危操作比如防火墻規(guī)則、生產(chǎn)環(huán)境變更無論 Skill 怎么說都要讓 Agent 先輸出待執(zhí)行的命令人工確認(rèn)后再執(zhí)行。5.3 OCR 錯誤會滲透進命令直接引發(fā)幻覺式執(zhí)行掃描版 PDF 走 OCR 之后代碼和命令里的字符錯誤率不算低。一個典型的錯誤是把listen 443 ssl;識別成listen 443 ssl:肉眼很難發(fā)現(xiàn)Agent 執(zhí)行報錯也會懵。我在實測掃描版時吃了這個虧后來總結(jié)了兩條對策第一編譯完成后對產(chǎn)物里的命令區(qū)塊做一次語法檢查比如把 shell 命令行丟進shellcheck把 nginx 配置跑一遍nginx -t第二高危命令做人工抽查重點看容易混淆的字符。5.4 版權(quán)邊界個人技能包別做成公開分發(fā)這也是我要提醒的地方。把你自己買的正版書編譯成個人使用的技能包本質(zhì)上和做讀書筆記差不多問題不大。但要把它作為公開技能庫發(fā)布或者把原書的大量內(nèi)容重新分發(fā)到網(wǎng)盤、社區(qū)就會碰到版權(quán)問題。圈子里已經(jīng)有一些人靠XX書轉(zhuǎn)化技能包引流風(fēng)險不小。我自己的態(tài)度是只做自己需要的那幾本編譯產(chǎn)物不進公開分享渠道最多給同事演示一下流程。這是玩這個工具的安全底線。6. 從 book-to-skill 往外看Agent Skill 生態(tài)正在快速成形6.1 Skill、插件、工具、記憶到底怎么分工這個項目能火背后其實是整個 Agent 生態(tài)對能力封裝的需求在爆發(fā)。Skill、插件、工具、記憶這幾個詞經(jīng)常被混用但分工其實很清楚工具是單個動作比如發(fā)請求讀文件Skill 是按場景編排好的動作序列比如排查網(wǎng)絡(luò)故障插件是某個平臺上的完整能力包記憶是長期數(shù)據(jù)比如用戶偏好和歷史上下文。book-to-skill 做的就是把靜態(tài)知識編譯成 Skill 這個中間層讓 Agent 獲得按場景出招的能力而不是只擁有一堆零散動作。6.2 各家框架的 Skill 目錄之爭還在早期熱詞里能看到很多名字Codex 的 skill、workbuddy skill、hermes agent、豆包 skill。它們各自的加載語法和目錄結(jié)構(gòu)不完全一樣但底層思路高度一致給 Agent 一個從外部加載的、可索引的能力包。book-to-skill 選擇了跟這個趨勢適配的通用輸出結(jié)構(gòu)這也是它能拿到 15k Star 的重要原因。一個工具如果只綁定單一平臺很難有這種擴散速度。6.3 從讀一本書到建立個人技能庫實踐了一段時間之后我不再把 book-to-skill 當(dāng)成一個簡單的 PDF 工具看它其實給了技術(shù)人一種新的知識管理思路。你讀過的每本技術(shù)書都可以變成 Agent 的一個隨身能力模塊。數(shù)據(jù)庫書編成一個 Skill運維書編成一個 SkillPython 進階書編譯成另一個 Skill。用的時候按場景觸發(fā)不用的時候靜靜躺在技能目錄里不占上下文。我的個人路線是這樣先挑工作里高頻參考的兩三本書做編譯跑通流程然后寫一個小腳本把輸入 PDF、輸出 Skill、自動做語法檢查串成一條流水線最后在 Agent 的 INDEX 里把多個技能串聯(lián)起來形成能干活的完整體系。目前已經(jīng)穩(wěn)定用了一個多月最大的改變不是記住了書而是不怕忘書。最后再分享一個實用小技巧編譯的時候留意一下輸出日志里被跳過的章節(jié)。凡是日志里出現(xiàn)解析閾值低于預(yù)期的章節(jié)往往是有大圖、復(fù)雜表格或者代碼量過大的部分。這些章節(jié)值得在編譯后手動打開看一眼必要時人工補充幾個命令示例。自動化的流水線補上人工抽查這一步Skill 的可用性會從能演示提升到能交作業(yè)。