企业官网建设流程全解析

book-to-skill 处理 PDF 时 technical 模式与 text 模式怎么选

【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill

用 book-to-skill 把一本 PDF 转成 agent skill 时，提取阶段（Step 1.5）会先问你一个问题：这份内容是technical（有代码块、表格、公式、图示）还是text-heavy（以散文为主，几乎没有表格和代码）。这个选择决定了提取工具链——technical 模式走 Docling（约 1.5 秒/页），text 模式走 pdftotext 及其回退链（秒级完成）——也决定了后续章节文件的结构模板和 token 预算。选错的代价是实实在在的：technical 书用 text 模式会丢掉全部表格和代码结构，散文书用 technical 模式则要白等几分钟。这篇文章按项目文档说明两种模式的判定标准、实际命令、以及提取后如何核对结果。

判定标准：什么时候选 technical，什么时候选 text

SKILL.md 的 Step 1.5 给出了原始提问文案：

"What kind of content do these sources have? This helps me choose the best extraction method.

1. Technical— has code blocks, tables, formulas, diagrams (e.g. programming books, academic papers, architecture guides)
2. Text-heavy— mostly prose, few or no tables/code (e.g. management, productivity, narrative non-fiction)
3. Not sure— I'll use the fast method and warn you if quality seems limited"

判定结果存入BOOK_TYPE：选项 1 →BOOK_TYPE=technical；选项 2 和选项 3都→BOOK_TYPE=text。也就是说，"不确定"时默认走快速的 text 模式而不是 technical 模式，之后若提取质量明显受限，agent 会主动提醒你。

docs/performance.md 的结论一句话概括："Pick text mode for prose, technical mode for code/tables."（散文选 text 模式，代码/表格选 technical 模式。）

两种模式实际会做什么：工具链与实测差异

README.md 按书籍类型给出的工具表：

注意sudo apt install poppler-utils是系统包安装（Debian/Ubuntu 源），需要相应权限；另外两条是 Python 依赖。

同一本 103 页技术书 PDF 上的实测对比（来自 docs/how-it-works.md 与 docs/performance.md，CPU only）：

这是项目文档给出的测量数据，用于说明两种模式的差异，不是每本书都会得到的固定数值。它说明的关键点：

• token 数量几乎相同（27K vs 27K+1.2%），所以模式选择买到的不是"更少的字"，而是结构保真度；
• pdftotext 即时完成但会把结构压平——技术书里的表格和代码块全部丢失（0 表格、0 代码块）；
• Docling 以约 1.5 秒/页的代价，把表格和代码保留为 markdown。

依赖缺失时的行为：docling仅在--mode technical时需要，否则回退到 text 提取链（见 book_to_skill/dependencies.py）。脚本在提取前会检查对应格式的可选依赖；缺少更优提取器时会提示并给出可用回退，非交互会话默认走回退，除非安装模式显式设为yes（可通过--install-missing ask|yes|no控制，默认ask）。

执行：从 agent 会话或独立 CLI 指定模式

主路径——agent skill 会话：

/book-to-skill ~/path/to/your-book.pdf

（~/path/to/your-book.pdf是 docs/install.md 中的示例，替换为你自己的 PDF 路径。）执行到 Step 1.5 时，agent 会按上面的文案提问；你回答 technical 时会被告知：

"📐 Technical mode selected — using Docling for structure-aware extraction (tables, code blocks, formulas preserved as markdown). This takes ~1.5s per page, so expect a few minutes for longer sources."

回答 text 时则会被告知使用最快可用提取器，PDF 在可用时走 pdftotext。随后 agent 运行提取脚本，底层命令形态为scripts/extract.py <paths…> --mode <technical|text>（见 docs/how-it-works.md 的流程图）。

可选分支——独立 CLI：通过 pip 从仓库安装的是纯提取引擎，不注册/book-to-skillagent skill（完整 skill 流程需要git clone安装，见 docs/install.md）。CLI 下模式是显式参数：

book-to-skill ~/path/to/book.pdf --mode technical book-to-skill ~/path/to/book.pdf --mode text

执行前可以先做环境预检，不处理任何文件，只报告每种格式已装了哪些提取器以及缺失项的确切安装命令：

book-to-skill --check # 或在仓库中： python3 scripts/extract.py --check

模式还会影响生成章节的结构与预算

BOOK_TYPE不止作用于提取。SKILL.md Step 7 规定章节文件按模式调整侧重点：

• technical→ 优先 "Code Examples"、"Reference Tables"、"Commands & APIs" 小节，并保留精确语法；
• text→ 优先 "Frameworks Introduced"、"Mental Models"、"Key Takeaways"，跳过空的 technical 小节。

每章 token 预算（与 Step 4 得出的DEPTH组合）：

Step 2.5 的预估算时中位数也是按模式区分的：text≈ 1,000 tokens/章，technical≈ 1,800 tokens/章。所以给一本散文书选 technical，代价不只是提取变慢，还有更大的章节文件和更高的生成成本；反之给技术书选 text，则会直接丢失代码与表格。

提取完成后如何核对结果

一次运行完成时会打印三条路径（Workdir ->、Text ->、Meta ->）。工作目录按运行隔离（<tempdir>/book_skill_work-<pid>/），并发提取不会互相覆盖，因此应从本次输出的路径取结果，不要假设固定位置。

核对步骤（来自 SKILL.md Step 2）：

1. 读本次运行的metadata.json，检查filename/source_file，或看full_text.txt首行的SOURCE:头，确认提取到的确实是你要的那份文档；
2. 如果是 technical 模式，打开full_text.txt确认表格和代码块以 markdown 形式保留——这正是上一节实测表体现的差异（那本 103 页技术书提取出 48 个表格、36 个代码块）；
3. 如果你在 Step 1.5 选了 "Not sure"（text 模式），而提取质量看起来受限，agent 会给出警告。

两个相关边界

• 扫描版 PDF（纯图片、无文字层）：无论选哪个模式都无法提取——提取器会检查前几页并立即停止并给出说明，而不是跑完全书产出一个空 skill。文档建议先自行 OCR，再转换结果：

  ocrmypdf input.pdf output.pdf

• Update / Fold-in（Mode 4）：向已有 skill 追加新文件时，Step 1.5 的类型判断会针对新来源重新执行，需要为新内容再回答一次 technical/text 问题。

核对完成后，判断标准就是上面三条：SOURCE:头指向正确文件、technical 书的表格和代码块以 markdown 存在、页数与metadata.json一致——满足即说明这次的模式选择执行正确。两种模式的完整流水线位置见 docs/how-it-works.md，更多运行方式见 docs/usage.md。

【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill