1实现原理 · 为什么它能做到

文档分层路由：SKILL.md 只放常用配方与『下一步』指针，高级库/JS 用法放 REFERENCE.md，表单填充的完整闭环放 FORMS.md——三份文档按任务分工。

skills/pdf/SKILL.md

For advanced features, JavaScript libraries, and detailed examples, see REFERENCE.md. If you need to fill out a PDF form, read FORMS.md and follow its instructions.

SKILL.md 以 'Quick Reference' 表 + 配方代码块组织（pypdf 合并/拆分/旋转/水印/加密、pdfplumber 抽取、reportlab 创建、poppler/qpdf CLI）；FORMS.md 才是『填表』这类复杂任务的完整工作流。

常规 PDF 操作=python 库 + CLI 双轨，均为本地执行：pypdf（结构操作）、pdfplumber（文本/表格）、reportlab（创建）、pdftotext/qpdf/pdftk/pdfimages（CLI 捷径）。

skills/pdf/SKILL.md

This guide covers essential PDF processing operations using Python libraries and command-line tools.

配方含规避坑：'Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉…) in ReportLab PDFs'——内嵌字体无这些字形会渲染成黑块，用 <sub>/<super> 标签替代。

表单填充是重头戏并区分两种形态：可填表单（fillable，直接写字段）与不可填表单（无字段→叠加 FreeText 文本批注），后者优先走『结构提取坐标』、失败才退化为目测估算。

skills/pdf/forms.md

If the PDF doesn't have fillable form fields, you'll add text annotations. First try to extract coordinates from the PDF structure (more accurate), then fall back to visual estimation if needed.

结构路线=extract_form_structure.py（pdfplumber 读文本坐标/横线/小矩形复选框，输出 labels/lines/checkboxes/row_boundaries JSON）；目测路线=转图后人工/视觉定位 + 缩放精修。

填充前有强制门禁：check_bounding_boxes.py 校验相交框与过小字框；填充后强制转图目检文字位置——坐标转换错误在交付前被发现。

skills/pdf/forms.md

**Always validate bounding boxes before filling:**

校验项原文：'Intersecting bounding boxes (which would cause overlapping text)' + 'Entry boxes that are too small for the specified font size'；Step 4 用 convert_pdf_to_images.py 输出图像人工核验。

坐标体系自洽转换：forms.md 规定 PDF 坐标（y=0 在页面顶部向下增），fields.json 带 pdf_width/pdf_height 或 image 尺寸信号，填充脚本自动探测坐标系统并换算。

skills/pdf/forms.md

The fill script auto-detects the coordinate system and handles conversion:

fill_pdf_form_with_annotations.py 源码含 transform_from_image_coords(bounding box…) 坐标变换函数，用 pypdf FreeText 注解叠字；fill_fillable_fields.py 走 pypdf 字段写入。

扫描件 OCR 与『可搜索化』只覆盖到文本抽取层：示例经 pdf2image→pytesseract 把每页 OCR 文本拼出来，未提供生成带文本层 PDF 的直接脚本。

skills/pdf/SKILL.md

Requires: pip install pytesseract pdf2image

此处与 description 'OCR on scanned PDFs to make them searchable' 存在措辞差：正文演示抽取文本打印，『做成可搜索 PDF』（写回文本层/索引）需宿主自行组合工具——见 verification 中该条 discrepancy。

2核心能力

01合并/拆分/旋转/加页码水印/加密解密 PDF（pypdf 配方）

02文本与表格抽取（pdfplumber，含布局保留与多页表格拼接）

03从零创建 PDF（reportlab Canvas/Platypus，含 sub/sup 字形规避）

04CLI 批量操作：pdftotext -layout、qpdf 合并拆分、pdftk、pdfimages 抽图

05表单填充完整闭环：结构提取→fields.json→框校验→填（字段/批注两法）→转图目检

06扫描件 OCR 文本抽取（pdf2image + pytesseract）

07高级参考：pypdfium2 渲染、pdf-lib（JS）复杂创建、pdfjs-dist 坐标/注解抽取

3外部依赖

Kind	Dependency / Endpoint
package	pypdf（读写/合并/旋转/加密/字段）
package	pdfplumber（文本/表格坐标级抽取）
package	reportlab（创建 PDF）
cli	pdftotext（poppler-utils）
cli	qpdf（合并/拆分/旋转/修复/加密）
cli	pdftk（若可用）与 pdfimages（poppler，抽图）
package	pytesseract + pdf2image（OCR，按需安装）
package	pypdfium2 / pdf-lib(JS) / pdfjs-dist(JS)（高级参考章节）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: 8 个自带 python 脚本（pypdf/pdfplumber/PIL/pdf2image）
本地工作目录: 文件读写与工件输出: 输出 PDF/fields.json/form_structure.json/图像（本地工作区）

审计说明： 。全本地行为：自带 python 脚本 + poppler/qpdf 系本地 CLI 读写本地 PDF，无网络外发、无凭证读取。注意点：① 解析不可信 PDF 的暴露面在 pypdf/pdfplumber 解析器层（宿主需自行评估版本）；② description 宣称 'OCR … make them searchable' 但正文仅覆盖文本抽取，生成可搜索 PDF 需宿主补工具；③ OCR 库属按需 pip 安装（官方 PyPI，条件触发）。整体为本地文档处理技能，无外联风险。

5第二遍独立确认

[ok] 填表工作流引用脚本全部存在 — forms.md 各步骤命令行（extract_form_structure/check_bounding_boxes/fill_pdf_form_with_annotations/convert_pdf_to_images/check_fillable_fields）与 scripts/ 文件一一对应。
[discrepancy] OCR『make them searchable』宣称 vs 实现 — description 声称 OCR 使扫描件可搜索，但 SKILL.md 'Extract Text from Scanned PDFs' 示例只把 pytesseract 文本拼进字符串打印/汇总；生成带文本层的可搜索 PDF 没有脚本或配方，需宿主自行组合。属轻微措辞超前（抽取是搜索化的前置），已在 risks 标注。
[ok] 库依赖与 import 一致 — 脚本实际 import pypdf/pdfplumber/PIL/pdf2image，与依赖清单一致；无隐藏第三方。
[ok] 网络/凭证零命中 — token 扫描（url/requests/urllib/env/token/secret/key）零命中；无配置文件读取。
[ok] 坐标转换逻辑存在 — fill_pdf_form_with_annotations.py 有 transform_from_image_coords 函数，forms.md 双坐标系说明与之配套。
[ok] 元数据与资产核对 — 本地 HEAD==pin；LICENSE.txt 专有条款与 frontmatter 'Proprietary' 一致；REFERENCE.md/forms.md 行数与结构如述。

6结论

任务面覆盖全：结构操作/抽取/创建/CLI 批处理/填表/OCR 均有可执行路径，且有 Quick Reference 查表。

填表是真正的坐标工程闭环（结构提取→校验→填充→目检），不是简单叠字。

本地离线可用：纯 python + poppler CLI，无网络依赖，适合敏感文档环境。

分文档组织（SKILL/REFERENCE/FORMS）避免主文档臃肿，深度任务有专门手册。

内置渲染器陷阱知识（Unicode 下标黑块、坐标方向），减少返工。

适合： 适合需要批量/程序化处理 PDF 的自动化环境：合同与报表的合并拆分、表格抽取、扫描件 OCR、以及最难的『往无字段表单里精确填字』场景（有完整闭环）；三文档分层也适合从快速任务到深度定制的渐进使用。

不适合： 不适合对视觉排版精细度要求极高、需所见即所得编辑器介入的设计型 PDF 工作；不适合要求『OCR 后直接得到可搜索 PDF』且宿主无补充工具的期望（需自行组装）；不适合无 poppler/qpdf 且无法安装的受限环境；不适合不能接受专有许可条款的组织。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload pdf.tar.gz

sha256: 8a9ce019ed1b048d…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 41bbe19d1a.