AI Agent

把技术书变成 AI Agent 技能：book-to-skill 与 Docling 实战

如何用 book-to-skill 与 Docling 将技术书和 PDF 整理成可按需调用的 AI Agent 技能？解析文件结构、两阶段处理、离线模型与质量检查。

AI 生成配图：技术书、文档解析与 Agent 技能文件。

编者说明：本文根据 Alain Airom (Ayrom) 的文章《Turning Books into Actionable Agent Skills》撰写中文解读。原文中的项目实现、实验与截图归原作者所有；本文补充了使用时值得注意的边界。完整代码请见文末链接。

一本技术书读完后，最容易消失的不是知识，而是在需要时找到并用上它的能力。把整本 PDF 塞进模型上下文，成本高、定位慢；只用关键词搜索，又可能漏掉贯穿多个章节的决策原则。book-to-skill 提出另一种组织方式：先把资料整理成 Agent 能按需加载的技能，再在工作中调用相关章节。

一本书怎样变成一个技能？

这个开源项目接受技术书籍、文档目录或多份资料。它生成的核心不是一篇长摘要，而是一组分工明确的文件：

SKILL.md 是入口，写明技能用途、核心框架与何时读取其他文件。
chapters/ 保存各章要点，只有问题涉及该章节时才加载。
glossary.md、patterns.md 和 cheatsheet.md 分别整理术语、方法模式与快速决策规则。

这样设计的价值在于把整理成本支付一次，而不是每次提问都让 Agent 重新翻书。项目在其测试资料中报告，按问题加载相关内容，相比每次把整本书放入上下文，可减少约 24 至 51 倍的输入 token。这个数字取决于书籍、问题和比较方法，不能直接当成所有场景的节省保证。真正有用的原则是：让检索范围跟问题相关，而不是跟整本书一样大。

Docling 为什么重要？

技术 PDF 往往不是连续的文字。表格、代码块、公式与多栏排版一旦被抽取成错乱的纯文本，后面的模型再强，也只能在破碎的材料上工作。Docling 的作用是尽量保留这些结构，把文档转换成更适合后续处理的内容。

book-to-skill 会按资料类型选择提取器：普通、文字为主的 PDF 可以使用速度更快的文本提取方式；包含代码和复杂表格的技术 PDF 则可选 Docling。扫描版 PDF 还需要先做 OCR。换句话说，解析质量是技能质量的上限：生成前值得抽查目录、表格和代码是否已经正确提取。

原作者怎样把命令行工具做成应用？

Airom 的实践重点，是在原项目外面增加一个本地 Web 界面和 FastAPI 后端。用户选择文件、处理模式与技能名称后，应用分两阶段运行：

提取：后端为每个任务建立独立目录，用异步子进程调用提取脚本，保存原始文本和元数据。
生成：提取成功后，线程池调用配置好的 LLM，分别生成章节摘要、术语表、模式、速查表和主 SKILL.md。

前端持续查询任务状态，展示提取结果和技能文件。这个分段设计让耗时的 PDF 解析与模型推理不阻塞界面，也方便定位错误究竟发生在提取、模型连接，还是文件生成阶段。

作者还为重启后的状态恢复做了处理：如果内存里的任务记录丢失，但磁盘上的技能文件仍在，应用可以扫描输出目录并重新识别结果。这比单纯显示一次“完成”更贴近实际使用，因为用户需要在关掉应用后仍能拿到文件。

离线模型、占位文件与质量检查

这个 Web 包装层支持兼容 OpenAI 接口的模型服务，原作者给出了本地 Ollama、llama.cpp 等配置示例。使用本地模型可以让私有文档尽量留在本机；改用远程服务时，应先确认资料是否允许上传到该提供商。

有一个容易误判的细节：模型不可达时，应用仍可能生成占位的技能文件，以便流水线继续结束。因此，看见 SKILL.md 并不等于它已经包含由模型提炼出的有用知识。检查界面或结果中的 llm_available，再打开几章确认内容是否具体、准确且有出处。若 Ollama 明明在运行却显示离线，还应核对配置里的模型名称与 ollama list 完全一致。