如何把编程书变成 AI Agent 的专业技能？PDF → Knowledge → Skill 完整流程

结论先说：本周不要把整本 PDF 直接塞进 Skill。 先用 **第 1 天识别 PDF 类型，第 2—3 天完成文本提取或 OCR，第 4 天建立带来源的 Knowledge Base，第 5—7 天再封装 Agent Skill 并运行验收。只有内容短小、长期稳定、无需频繁检索时，才适合把资料直接写入 Skill。

这套“PDF → Knowledge → Skill”路线适合三类人：需要处理包含代码、表格和扫描页的编程 PDF 用户；正在比较全文入 Skill 与知识库检索方案的 Agent 开发者；计划批量维护多本专业资料的技术团队。

第 1 步：先判断 PDF 类型，再选择解析路线

不要一上来就 OCR，也不要默认所有 PDF 都能直接复制。第一轮检查要回答三个问题：

• 页面是否有真实文本层？
• 文本顺序是否符合正常阅读顺序？
• 代码、表格和图片是否承担了主要信息？

文本型 PDF 通常可以直接提取。使用保留块、单词坐标或字典结构的方式，比只导出一段纯文本更容易修复双栏、代码块和页眉页脚问题。PyMuPDF 官方文档说明，text、blocks、words、dict 和 rawdict 适合不同精度的提取需求；其中带坐标的块信息可用于重新判断阅读顺序。(pymupdf.readthedocs.io)

你可以把第一轮结果分成三档：

评分：第一轮解析方案怎么选

按“保留来源、代码可用性、后续维护”三项各评 1—5 分。文本提取适合文本层完整的书；OCR 适合扫描页面；布局识别更适合表格和图文混排，但需要更严格的人工抽查。

如果你需要在远程环境中准备解析工具、查看权限和文件处理方式，可以先参考 VPSSpark 帮助中心。不要把未经授权的 PDF 上传到第三方服务，也不要尝试绕过加密或版权保护。

第 2 步：文本型 PDF 保留页码、布局和代码边界

文本型 PDF 的难点不是“能不能提取”，而是提取后还能不能回到原页核对。

建议每个页面至少保留以下字段：

{
  "book_title": "书名",
  "edition": "版本或版次",
  "chapter": "章节路径",
  "page": 42,
  "element_type": "paragraph",
  "text": "正文内容",
  "source_file": "原始文件名"
}

代码块不要和解释段落混成一段纯文本。至少要保存：

• 代码所在页码和章节；
• 使用的语言；
• 运行环境和版本；
• 前置依赖；
• 预期输出或验证方式；
• 代码是否为完整示例，还是片段。

PyMuPDF 的 blocks 可返回文本块坐标，words 可返回单词位置，dict 和 rawdict 可保留更细的结构信息。这样处理后，你可以单独检查代码缩进、标题层级和双栏顺序，而不是等 Agent 生成错误答案后再追查。(pymupdf.readthedocs.io)

常见污染包括页眉反复插入正文、页脚页码混入代码、断词符号破坏类名，以及字体编码导致的乱码。处理规则应写成可重复的清洗步骤，而不是手工改一次就结束。

第 3 步：扫描 PDF 只对必要页面执行 OCR

扫描版编程书不应无差别 OCR 全部页面。先用普通提取检查每页是否为空、字符数量是否异常，或者是否只有少量不可读字符。只有满足这些条件的页面，才进入 OCR 队列。

PyMuPDF 官方文档明确建议先判断页面是否确实需要 OCR。文档还指出，OCR 速度可能约比标准文本提取慢 1000 倍，因此应避免重复识别同一页面，并复用已经生成的文本结果。(pymupdf.readthedocs.io)

OCR 后要重点抽查代码页面：

1. 检查 0、O、1、l、I 等容易混淆的字符。
2. 检查括号、引号、反斜杠、冒号和缩进。
3. 检查行号是否被误认为代码。
4. 检查双栏是否被交错拼接。
5. 将 OCR 文本与原始页面图像并排保存。

如果 PDF 含有表格，不能只保存 OCR 后的线性文本。表头、行列关系和单位必须作为独立结构保存。Unstructured 的 PDF 分区支持 fast、hi_res、ocr_only 等策略；官方文档说明，表格抽取通常需要布局识别路径，而多栏页面的元素顺序仍需要人工验证。(docs.unstructured.io)

第 4 步：把代码、解释和版本条件绑定成知识单元

代码密集型编程书最容易出现一个错误：只把代码片段存进 Knowledge Base，却丢掉“这段代码为什么存在”。

一个合格的知识单元，不应只是：

for item in items:
    process(item)

而应包含：

主题：批量处理列表
适用版本：Python 3.x
前置条件：items 已完成初始化，process 已定义
核心代码：……
预期结果：每个元素都会被处理
常见失败：空列表、异常未捕获、类型不匹配
来源：书名、章节、页码、版本

切分也不能只按固定字符数。应优先按章节、标题、概念、示例和任务边界切分；只有单个元素过长时，再进行二次切块。Unstructured 文档强调，先利用文档元素进行结构化，再在单个元素超过目标长度时做文本切分，通常比一开始机械分割更容易保持语义。(docs.unstructured.io)

LlamaIndex 的官方文档将 Document 和 Node 作为核心抽象。Node 可以代表来源文档的一段文本、图像或其他内容，并携带元数据与关系信息。你可以借鉴这种设计，把“章节关系、前置知识和原始来源”保留下来，而不是只建立一堆互不相关的向量片段。(docs.llamaindex.ai)

第 5 步：让 Knowledge Base 负责事实，让 Skill 负责动作

Knowledge Base 和 Skill 的边界，是整套方案的关键。

Knowledge Base 应保存：

• 编程概念和定义；
• 代码示例与解释；
• 适用语言、框架和版本；
• 依赖、限制与失败案例；
• 书名、章节、页码和来源文件；
• 不同书籍之间的冲突结论。

Agent Skill 应保存：

• 什么时候触发；
• 先检索哪些主题；
• 如何筛选来源；
• 是否需要调用代码执行工具；
• 如何检查结果；
• 遇到版本冲突时如何向你提问。

Agent Skills 规范要求技能目录至少包含 SKILL.md，并允许把脚本、引用资料和资源文件拆分保存。规范还建议利用渐进式加载：启动阶段只读取名称和描述，激活后再加载完整指令，需要时才读取引用资料。SKILL.md 的主体建议控制在 500 行以内，完整指令建议少于 5000 tokens；这些限制的目的，是避免每个任务都加载整本书。(agentskills.io)

一个面向编程书的 Skill 可以这样设计：

---
name: python-book-assistant
description: 根据已授权的 Python 编程资料回答问题、定位章节并验证代码。
compatibility: 需要 Python、项目依赖和隔离执行环境。
---

1. 判断用户任务属于概念解释、代码生成还是错误排查。
2. 从 Knowledge Base 检索相关章节，并优先保留版本匹配的来源。
3. 回答时给出书名、章节和页码。
4. 需要运行代码时，先创建隔离环境并限制文件、网络和进程权限。
5. 运行后检查输出、异常和依赖版本。
6. 如果来源冲突，列出差异，不自行隐藏冲突。

这里没有复制整本书，而是定义了检索、执行和验收流程。完整内容放在 references/ 或 Knowledge Base 中，Skill 只在任务需要时调用。

第 6 步：增加沙箱、权限和结果验收

只要 Skill 会运行书中的代码，就不能把“生成代码”和“直接执行代码”视为同一步。

最低限度的隔离要求包括：

• 单独的工作目录；
• 明确的依赖安装范围；
• 限制网络访问；
• 限制文件读写路径；
• 设置运行时长和进程数量；
• 保存命令、依赖版本和输出；
• 执行失败时返回原始错误，而不是让 Agent 自行编造结果。

你可以把验收分成三层：

✅ 文本验收：答案是否能回溯到书名、章节和页码。
✅ 结构验收：代码是否保留依赖、版本、输入和预期结果。
✅ 运行验收：在隔离环境中是否能完成最小示例，失败是否可解释。

如果你正在搭建长期运行的解析和执行环境，可以把文件上传、权限控制和实例管理拆开，先阅读 VPSSpark 的环境使用说明，再决定是本地运行、远程租赁还是采用其他托管方式。

第 7 步：用增量方式维护多本编程书

多本书不能简单合并成一个“超级 Skill”。更稳妥的做法是建立统一主题索引，但保留每条知识的来源差异。

例如“异步编程”这个主题，可以同时记录：

• 书籍 A：适用于某个旧版本运行时；
• 书籍 B：采用较新的 API；
• 书籍 C：只讨论概念，不提供完整可运行代码。

当新版本书籍进入系统时，不要重建全部内容。先识别受影响的章节、依赖和代码示例，再增量更新相关知识单元，并重新测试引用这些单元的 Skill。

建议为每个知识单元保存版本状态：

source_id
book_title
edition
chapter
page
language
framework
runtime_version
updated_at
status

其中 status 可以区分“已核对”“待复核”“版本冲突”和“不可运行”。这比单纯依赖向量相似度更适合技术资料，因为相似内容不代表适用版本相同。

常见问题

完整书稿适合直接写入 Skill 吗？

通常不应该。完整 PDF 体积大、检索边界不清，版本更新时还会迫使你重写 Skill。更好的方式是把 PDF 解析为带来源的 Knowledge Base，再让 Skill 规定检索顺序、引用格式和执行检查。短小且长期稳定的规范资料，才适合直接放入 Skill 的参考目录。

扫描页面中的代码怎样提取才可靠？

先判断页面是否存在文本层，只对扫描页或异常页 OCR。代码页必须保留原始页面，并人工抽查缩进、标点、大小写和行号。OCR 结果还要经过语法检查和最小运行验证，不能因为文本“看起来完整”就直接写入可执行 Skill。

两层架构分别应该保存哪些内容？

Knowledge Base 负责保存事实、代码、版本条件和来源，解决“应该检索什么”。Skill 负责触发、检索、工具调用和结果验收，解决“应该怎样完成任务”。两层分离后，书籍更新主要影响知识层，流程变化主要影响 Skill 层。

多本资料怎样避免维护成一团？

先按主题建立索引，再把每条知识绑定到书名、章节、页码和版本。不同书籍出现冲突时保留差异，并在 Skill 中定义冲突处理规则。新增版本后，只重建受影响的知识单元，再运行对应任务的回归测试。

把当前方案和 Mac 方案放在一起比较时，直接在本地电脑上处理多本 PDF，常见问题是环境依赖不一致、OCR 与布局模型安装麻烦、代码验证容易占用日常开发机资源；临时使用普通云主机又可能遇到图形化工具、文件权限和隔离执行配置不顺手。若你需要批量处理合法 PDF、临时搭建解析环境，或运行书中代码做回归验证，租赁 VPSSpark 的 Mac 环境通常更适合先完成测试，再决定是否长期自购设备。若任务涉及长期稳定重负载、物理接口或严格本地合规要求，自购 Mac 或本地部署反而更合理。