4.2 pdf：PDF 全流程

它是什么

pdf 的触发条件是：用户想对 PDF 文件做任何事情时。这句话的覆盖面极大——读取、创建、合并、拆分、提取、填表、转换，都归它。

在 19 个官方技能里，pdf 属于“装了不一定天天用，但要用时没有就很痛苦”的类型。它和 4.1 的三件套一样是目录包形态，自带处理 PDF 的参考资料，装法也完全相同——浅克隆官方仓库，只复制 pdf 一个目录：

mkdir -p ~/.dsh/skills
git clone --depth 1 https://github.com/anthropics/skills.git /tmp/anthropic-skills
cp -r /tmp/anthropic-skills/skills/pdf ~/.dsh/skills/

复制完新开一个会话，/pdf 能直调即算装好。

PDF 为什么难缠

PDF 的设计目标是视觉保真，不是数据可读。它要保证同一份文件在任何设备上看起来一模一样，代价就是把“内容是什么”藏进了坐标和绘制指令里。这带来五个特有的坑：

坑 表现 后果
无结构 一页 PDF 可能只是一张大图 没有任何文本层可提取
文本流断裂 复制出来变成“今 天 天 气 很 好” 句子被切成碎片，语序错乱
字体子集化 提取的文字缺字、乱码 连常用字都可能缺，编码映射对不上
表格无边界 看起来是表格，实际是一堆绝对坐标文本 分不清哪段文字属于哪列
表单域 填表要处理 AcroForm 字段 直接覆盖文本会破坏字段结构

前三个坑决定“能不能读到字”，后两个决定“读到之后能不能用”。一个合格的 PDF 技能必须逐个知道这些坑的存在，而不是把 PDF 当纯文本文件处理——那是新手最常犯的错：一个 read 下去，提出来一堆碎块，还以为文件坏了。

先判断类型，再决定路线

处理任何 PDF 之前，第一件事是判断它是文本型还是扫描型：

拿到一份 PDF
├─ 直接提取文本，结果有料 → 文本型 → 走文本处理路线
│      （提取、合并、拆分、填表都快）
└─ 提取结果为空、乱码或碎块 → 扫描型 → 先 OCR 再走文本路线
       （OCR 有识别错误，重要数字要抽检）

一般做法就是先尝试直接提取文本：提得出大段连续文字，是文本型；提出来的为空、乱码或大量碎块，基本是扫描型，得先过 OCR。这一步判断错了，后面全错——把扫描件当文本型处理，你会得到一份空结果还以为文件坏了；把文本型当扫描型处理，白烧一轮 OCR，还平白引入识别错误。

这个判断最好让技能自动完成，但你在提示词里点一句“如果是扫描件先做 OCR”就有用，等于给路线选择加了保险。反过来，已经确定是扫描件时，明确告诉它“这份是扫描件，直接 OCR”，能省掉一轮无用的直接提取。

给提示词的三个通用技巧

不管哪个任务，下面三条能少踩一半坑：

技巧 为什么
明确输出格式（Markdown 表格 / JSON） 让结果可直接进下一步，不被自由文本拖住
写明兜底（扫描件走 OCR） 防止路线选错后整轮作废
要求“列出做了什么 / 填了哪些字段” 交付前自检，当场发现漏项

典型任务

任务一：内容提取。

用 pdf 技能读取 contract.pdf，抽取所有条款编号与正文，
按编号整理成 Markdown 表格。如果是扫描件先做 OCR。

要点是给了输出格式（Markdown 表格）和兜底（扫描件走 OCR）——前者让结果可直接粘贴进文档，后者防路线选错。

任务二：合并与拆分。

用 pdf 技能把 reports/ 下 12 个月报按月份顺序合并成 annual.pdf，
每份报告前插入一页分隔页，页码连续。

合并类任务的坑全在细节里：顺序（按月份，不是按文件名排序）、分隔页、页码连续。这三件事不说，模型就会按默认行为做，出来一份能看但不能用的年报。

任务三：填表。

用 pdf 技能读取 form.pdf 的表单域列表，
把 applicant.json 里的值填进去，保存为 form-filled.pdf，
填完列出所有已填字段。

注意顺序：先“读取表单域列表”，再填。这正是对付 AcroForm 的正确姿势——字段名和数据源的键对不上时，先看字段清单再决定怎么映射，比盲目回填稳得多。最后“列出所有已填字段”是自查步骤，填完对一遍，能当场发现漏填。

三个任务分别对应三个高频场景：把存量 PDF 变成可编辑的数据、把多个 PDF 组装成一份、把数据填回表单。

和渲染 / 转 PDF 路线的配合

碰文档显示的技能有三个，分工明确：

需求 用谁
看某一页长什么样 office-render（渲染文档图像、检查视觉布局）
读页面里的文字和数据 pdf（本技能）
把 Office 文档转成 PDF office-export-pdf

一句话：要看样子用渲染，要拿数据用本技能，要生成 PDF 用转档技能。三者都是文件进、文件出（或图像出），可以随意串联。

与 office-export-pdf 的分工

dsh 自带技能里也有碰 PDF 的，方向和这个技能正好相反：

技能 方向 归属
office-export-pdf Office 文档 → PDF（产出） dsh 自带（第二章）
pdf 对 PDF 做各种操作（处理） Anthropic 官方（本章）

office-export-pdf 用 LibreOffice 把 Word、Excel、PPT 转成 PDF，回答的是“怎么生成”；pdf 回答的是“拿到了怎么用”。需要“Word 转 PDF 再提取文字”就两步串联：先用 office-export-pdf 转出 PDF，再用 pdf 技能读取提取。两步之间是文件交接，提示词里写清中间文件名，别让模型猜。

顺便认个脸：19 个官方技能里的 canvas-design 也会产出 .pdf，但那是视觉艺术创作，不是文档处理，和这个技能不是一条路，别混。

常见失败与排查

现象 先查什么
提取出来是碎块或乱码 多半是扫描件，加 OCR 再试
表格提取成一团 PDF 表格是坐标文本，要求按列重建，必要时转 CSV 再处理
填表后字段错位 先读表单域列表，确认字段名映射，别盲填
合并后页码不连续 合并参数里显式要求连续页码

小结

  • pdf 覆盖 PDF 的读取、创建、合并、拆分、提取、填表，触发条件是“对 PDF 做任何事情”。
  • PDF 的核心难点是视觉保真带来的无结构与扫描件，动手前先判断类型再选路线。
  • 三个典型任务：提取、合并、填表，提示词里写清输出格式和兜底。
  • 与 office-export-pdf 方向相反，可两步串联使用。

延伸阅读