document-pdf

PDF 文档技能 — 快速参考

**适用范围：**如果有官方 Anthropic pdf 技能，处理简单的创建、合并／拆分、表单填写和 CLI（qpdf/pdftotext）任务时优先使用它。本技能适用于其独有的场景：无障碍访问（PDF/UA-1/UA-2、EAA）、真实涂黑及其证据门槛、元数据清理、pyHanko 签名、OCR／表格提取规范，以及 PyMuPDF/pdf-lib 的许可和维护风险。

• 欧盟合规：在对 PDF 应用 EAA 前，先明确产品／服务的范围及国家层面的实施情况。核实引用的任何协调标准是否在《官方公报》中支持具体适用的法规；仅在另一项指令下引用 EN 301 549 并不充分。加载 references/pdf-accessibility-compliance.md，完成范围界定。
• 元数据存在于多个层级：PDF Info/XMP、文件系统日期和操作系统扩展属性。清理其中一个层级后，其他层级仍然可用。

核心决策规则

• 首先判断：原生数字 PDF（可选择文本）还是扫描版 PDF（图像）。扫描版 PDF 通常需要 OCR；参见 references/pdf-extraction-patterns.md。
• 如果用户需要无障碍访问／合规性，优先从支持结构的源格式（DOCX/HTML + 正确导出）生成，而不是对未加标签的 PDF 进行“事后修复”。
• 对于确定性操作（合并／拆分／旋转／清理），优先使用 scripts/ 辅助脚本，而不是临时自行实现。
• 切勿将黑色矩形或覆盖层视为涂黑。真正的涂黑会移除内容字节：对每一页调用 PyMuPDF page.add_redact_annot(rect)，然后调用 page.apply_redactions()，最后保存。通过涂黑证据门槛进行验证。
• 密码保护：pypdf writer.encrypt(..., algorithm='AES-256')（安全处理程序 R6）。省略 algorithm 会写入 RC4-128，因此务必传入该参数；仅在明确指定的旧版阅读器场景中使用 AES-256-R5。权限标志仅供参考，不构成安全保障。参见 references/pdf-security-redaction.md。
• 表格提取具有概率性，并非确定性操作：先运行 pdfplumber，并对照源页面抽查输出；仅当列／行明显有误时才升级使用 Camelot，且务必检查 Camelot 为每个表格提供的 accuracy 分数，不要盲目信任输出。
• PyMuPDF/fitz（由 scrub_metadata.py 和下文大多数涂黑／OCR 预处理代码使用）采用双重许可：AGPL-3.0 / 商业许可。如果要将其随闭源产品或 SaaS 后端一起发布，务必提前指出这一点——AGPL 的网络使用条款可能触发源代码披露义务；请从 Artifex 获取商业许可，或在所需功能重叠的情况下改用 pypdf/pdfplumber。
• pdf-lib（Node）：依赖前先检查上游软件包的发布活动。如果该软件包已长期未更新，而你需要持续获得修复，请在确定依赖前评估有维护的分支；无论如何，都应固定依赖版本。

---

快速参考

任务	工具/库	语言	使用场景
创建 PDF	pdfkit	Node.js	报告、发票、证书
创建 PDF	ReportLab	Python	复杂布局、表格
创建 PDF	FPDF2	Python	支持 Unicode 的简单 PDF
编辑 PDF	pdf-lib	Node.js	修改现有 PDF、添加页面（请先检查上游发布活动）
解析/合并/拆分/旋转	pypdf	Python	确定性的 PDF 操作
提取文本	pdfplumber	Python	无需 OCR 的文本提取
对扫描版 PDF 进行 OCR	OCRmyPDF	Python/CLI	为扫描版 PDF 添加可搜索的文本层
自定义 OCR 流程	PyMuPDF (fitz) + Tesseract	Python	页面级 OCR 或图像密集型内容提取——PyMuPDF 采用 AGPL-3.0/商业双重许可
提取表格	pdfplumber	Python	默认表格提取；使用前请进行目视核验
提取复杂表格	Camelot (camelot-py)	Python	格线/流式边缘情况；检查已安装版本的后端，并检查 table.accuracy
填写表单	pypdf (update_page_form_field_values) / pdf-lib	Python / Node.js	表单自动化；参见 references/pdf-forms-interactive.md
签署 PDF	pyHanko	Python/CLI	数字签名和验证
HTML 转 PDF	Playwright	Node.js	忠实于浏览器的网页渲染
HTML 转带标签的 PDF	WeasyPrint	Python	语义化 HTML、面向 PDF/A 或 PDF/UA 的导出
验证 PDF/A	veraPDF	CLI/GUI	存档符合性检查
验证 PDF 无障碍性	veraPDF（PDF/UA-1、PDF/UA-2 配置）+ PAC / Acrobat Checker	CLI/GUI	在 CI 中检查可由机器验证的 PDF/UA 规则，然后进行人工检查
检查/编辑文件元数据	exiftool	CLI	审核或改写 PDF/图像文件中的内部日期、XMP、EXIF、ICC
规范化文件系统日期	touch / SetFile	CLI (macOS)	将时间戳设为发布/构建日期；切勿将记录时间回拨

默认工作流

• 创建：使用 Playwright 实现忠实于浏览器的 HTML/CSS，使用 WeasyPrint 导出语义化/带标签的 HTML，使用 ReportLab 处理以 Python 为主的布局，或使用 pdfkit 处理以 Node 为主的自定义布局。
• 提取：先将文件归类为原生数字文件或扫描件；对于扫描版 PDF，先运行 OCRmyPDF 再进行后续提取，然后使用 references/pdf-extraction-patterns.md。
• 发布：运行 assets/pdf-release-checklist.md；对于无障碍性要求较高的 PDF，添加 PAC / Acrobat 检查；对于存档符合性重要的 PDF，使用 veraPDF。

脚本与退出代码

每个脚本都需要 Python 3，以及其 --help 中指定的依赖项。

python3 scripts/merge_pdfs.py merged.pdf a.pdf b.pdf
python3 scripts/split_pdf.py in.pdf out_dir --each-page
python3 scripts/rotate_pdf.py in.pdf out.pdf --degrees 90
python3 scripts/scrub_metadata.py in.pdf out.pdf
python3 scripts/scrub_metadata.py in.pdf out.pdf --filesystem-date <publication-date> --strip-xattrs
python3 scripts/test_scrub_metadata.py

• 输入错误会以非零状态码退出；argparse 用法错误以状态码 2 退出。scrub_metadata.py 在清理或请求的文件系统操作失败时以状态码 1 退出，并在 stderr 输出错误。它会在目标文件旁暂存输出，并且仅在所有请求的操作成功后才替换目标文件，从而在失败时保留现有目标文件。输入和输出必须不同。在 macOS 上，--strip-xattrs 使用 xattr 清除所有输出属性；--filesystem-date 还需要 SetFile 来设置创建时间。其他平台仅支持访问/修改时间，并会拒绝 --strip-xattrs。
• scrub_metadata.py 会移除 Info/XMP 元数据、附件、JavaScript 和缩略图，且默认保留 OCR 文本层和链接。PyMuPDF 自带的 scrub() 会删除两者；此脚本仅在使用 --remove-hidden-text / --remove-links 时才会这样做。移除 OCR 层会使扫描版 PDF 无法搜索且无法访问。
• --strip-xattrs 会在清除属性后检查是否仍有残留属性。即使命令成功，macOS 也可能保留受保护的来源属性；此时辅助工具会拒绝发布。请确认适用的主机策略，并单独验证已发布的文件，而不要假定所有痕迹都已清除。

应做 / 避免

应做

• 将带版本的源文档（文档／幻灯片／设计文件）与 PDF 一并保存。
• 检查长文档中的链接和阅读顺序。
• 使用真正的涂黑功能，并通过复制／粘贴进行测试。
• 对扫描版 PDF 提取文本前，使用 OCRmyPDF。
• 分发前清除所有元数据层（PDF 内部元数据、文件系统日期、macOS 扩展属性）。
• 清理后使用 exiftool -all -G1 验证，检查是否残留不打算公开的用户名、路径、工具标记和日期。
• 在依赖 PyMuPDF 用于闭源代码路径或 SaaS 代码路径之前，确认其 AGPL／商业许可符合部署要求。

应避免

• 存在源文档时，将直接编辑 PDF 作为主要工作流。
• 在新工作流中默认使用 wkhtmltopdf。
• 发布带有失效链接或难以辨认图表的 PDF。
• 未经明确批准就在 PDF 中包含客户个人身份信息（PII）或机密信息。
• 只清除 PDF 内部元数据，却忽略文件系统日期和操作系统级扩展属性。
• 将文件日期或元数据日期改早，以虚报记录的创建时间（即伪造）；应将日期规范为真实发布日期。
• 未经目视抽查或准确度评分审核，就轻信 Camelot／pdfplumber 对财务或法律文档的表格输出——列错位可能不会报错。
• 未检查 AGPL 义务或预留商业许可预算，就将 PyMuPDF 捆绑到专有产品中。

为做好导出质量检查，请使用 pdftoppm -png -r 80 out.pdf page（Poppler）渲染每一页，并结合 assets/pdf-release-checklist.md 检查 page-*.png 文件。

涂黑证据门槛

针对所有可能泄露相关内容的形式证明涂黑有效：提取的文本、搜索结果、复制／粘贴内容、页面渲染、注释、表单字段、附件和元数据。在第二种解析器或查看器中重新打开最终保存的文件，搜索敏感标记及其规范化变体；高倍放大检查涂黑区域，确认没有覆盖层、文本偏移或部分字形。如果日志中需要记录用于验证的标记集或合成替代内容，请勿在日志中重现敏感值。如果涉及 OCR，请同时测试可见图像和隐藏文本层。黑框、某个查看器中搜索无结果，或仅清除元数据，都不足以证明内容已被移除。

导航

资源

• references/pdf-generation-patterns.md — 复杂布局、多页文档
• references/pdf-extraction-patterns.md — 文本、表格和图像提取
• references/extraction-stack.md — 为新的大模型/RAG 工作流选择提取工具（原生解析、Docling 或 OCR）时加载
• references/pdf-accessibility-compliance.md — 带标签的 PDF、PDF/UA、EAA 合规性
• references/pdf-forms-interactive.md — AcroForms、表单填写、数字签名
• references/pdf-security-redaction.md — 加密、权限、真正的涂黑
• data/sources.json — 库文档链接

脚本

• scripts/merge_pdfs.py — 按顺序合并 PDF
• scripts/split_pdf.py — 按页拆分，或按范围拆分
• scripts/rotate_pdf.py — 将所有页面旋转 90/180/270 度
• scripts/scrub_metadata.py — 清除 Info/XMP 元数据、附件、JavaScript 和缩略图（默认保留 OCR 文本和链接）

模板

• assets/invoice-template.md — 生成发票 PDF
• assets/report-template.md — 多页报告结构
• assets/pdf-release-checklist.md — 链接、无障碍访问、导出保真度

相关技能

• ../document-docx/SKILL.md — Word 文档生成
• ../document-xlsx/SKILL.md — Excel/电子表格工作流
• ../document-pptx/SKILL.md — PowerPoint 演示文稿

经验循环

当以往的决策或陷阱与当前任务相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要查看历史记录或它是可用的备用文件时，才使用 learnings.md。否则跳过这两个文件。

应用经验后，如果遇到值得记录的模式、值得避免的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点。不要修改 SKILL.md 本身。