awesome-claude-skills 实战：PDF 全流程处理指南——文本表格提取、创建合并拆分与表单智能填写

• AI 技能
• AI 插件
• 人工智能
• 工作流自动化

本文围绕 awesome-claude-skills 仓库中 pdf 技能 展开，系统讲解如何用 Python 库与命令行工具完成 PDF 的读取、文本与表格提取、创建、合并/拆分、加密、水印、扫描件 OCR，以及最复杂的 PDF 表单智能填写。读完本文，你将掌握一套从"打开一个 PDF"到"批量处理并精确回填表单"的完整可复用的工程化方案。

技能定位：这个 PDF Skill 能做什么

该技能在仓库 README 中被概括为"提取文本、表格、元数据，合并与标注 PDF"（见 README.md），其技能描述（frontmatter）则给出了完整定义：

Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.

即它是一个面向"大规模程序化处理、生成、分析 PDF"的综合工具包，覆盖四大能力域：

• 提取：文本、表格、元数据、图片、带坐标的结构化内容；
• 创建：用 reportlab 从零生成单页或多页 PDF；
• 编辑：合并、拆分、旋转、裁剪、加水印、加密/解密、修复损坏文件；
• 表单：检测可填写字段、抽取字段信息、回填值，或对不可填写表单做视觉定位 + 文本注释回填。

技能目录由三份文档与一组脚本构成：主文档 SKILL.md、进阶参考 reference.md、表单专项指南 forms.md，以及 scripts 目录下的 8 个 Python 脚本（含配套单元测试）。技能采用专有许可证，完整条款见 LICENSE.txt，而文中所用第三方库均为开源许可（pypdf 为 BSD、pdfplumber 为 MIT、pypdfium2 为 Apache/BSD、reportlab 为 BSD、poppler-utils 为 GPL-2、qpdf 为 Apache、pdf-lib 为 MIT、pdfjs-dist 为 Apache）。

快速上手：读取 PDF 并提取全部文本

主文档给出的最小可用示例依赖pypdf，仅需三步即可完成"打开 → 统计页数 → 逐页抽文本"：

from pypdf import PdfReader, PdfWriter # Read a PDF reader = PdfReader("document.pdf") print(f"Pages: {len(reader.pages)}") # Extract text text = "" for page in reader.pages: text += page.extract_text()

值得注意的是，pypdf的extract_text()适合快速粗提取，但对于带复杂版式的文档或结构化数据（表格、坐标），主文档与 reference.md 均建议改用 pdfplumber；对于超大文档，纯文本优先用命令行pdftotext（见后文性能章节）。

Python 库详解：三驾马车各司其职

pypdf：合并、拆分、元数据与旋转

合并多个 PDF——创建PdfWriter，遍历每个源文件的每一页写入：

from pypdf import PdfWriter, PdfReader writer = PdfWriter() for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]: reader = PdfReader(pdf_file) for page in reader.pages: writer.add_page(page) with open("merged.pdf", "wb") as output: writer.write(output)

拆分为单页文件——为每一页单独建 writer 并落盘，文件命名为page_1.pdf、page_2.pdf……：

reader = PdfReader("input.pdf") for i, page in enumerate(reader.pages): writer = PdfWriter() writer.add_page(page) with open(f"page_{i+1}.pdf", "wb") as output: writer.write(output)

提取元数据——reader.metadata返回文档属性对象，可直接读取标题、作者、主题、创建程序等字段：

reader = PdfReader("document.pdf") meta = reader.metadata print(f"Title: {meta.title}") print(f"Author: {meta.author}") print(f"Subject: {meta.subject}") print(f"Creator: {meta.creator}")

旋转页面——page.rotate(90)表示顺时针旋转 90 度，角度可为 90/180/270 的倍数：

reader = PdfReader("input.pdf") writer = PdfWriter() page = reader.pages[0] page.rotate(90) # Rotate 90 degrees clockwise writer.add_page(page) with open("rotated.pdf", "wb") as output: writer.write(output)

pdfplumber：带版式的文本与表格提取

pdfplumber 的优势是保留版面布局，page.extract_text()与page.extract_tables()是其两个核心 API：

import pdfplumber with pdfplumber.open("document.pdf") as pdf: for page in pdf.pages: text = page.extract_text() print(text)

表格提取：extract_tables()返回页内全部表格，每个表是一个二维列表（行 → 单元格）：

with pdfplumber.open("document.pdf") as pdf: for i, page in enumerate(pdf.pages): tables = page.extract_tables() for j, table in enumerate(tables): print(f"Table {j+1} on page {i+1}:") for row in table: print(row)

进阶：多表合并导出 Excel——配合 pandas，把每页每个表转为 DataFrame（首行为列名），最后合并导出：

import pandas as pd with pdfplumber.open("document.pdf") as pdf: all_tables = [] for page in pdf.pages: tables = page.extract_tables() for table in tables: if table: # Check if table is not empty df = pd.DataFrame(table[1:], columns=table[0]) all_tables.append(df) # Combine all tables if all_tables: combined_df = pd.concat(all_tables, ignore_index=True) combined_df.to_excel("extracted_tables.xlsx", index=False)

reference.md 还补充了两类更精细的场景：一是按坐标提取——page.chars含每个字符的文本与位置，page.within_bbox((left, top, right, bottom)).extract_text()可只提取指定矩形区域内的文字，适合发票、报表等固定版式；二是复杂表格定制——通过extract_tables(table_settings)传入vertical_strategy/horizontal_strategy（lines或text）、snap_tolerance、intersection_tolerance等参数控制表格线识别，并用page.to_image(resolution=150).save(...)输出可视化调试图。

reportlab：从零创建 PDF

Canvas 基础绘制——Canvas适合简单的文本、线条绘制，坐标原点在页面左下角：

from reportlab.lib.pagesizes import letter from reportlab.pdfgen import canvas c = canvas.Canvas("hello.pdf", pagesize=letter) width, height = letter # Add text c.drawString(100, height - 100, "Hello World!") c.drawString(100, height - 120, "This is a PDF created with reportlab") # Add a line c.line(100, height - 140, 400, height - 140) # Save c.save()

Platypus 多页文档流——SimpleDocTemplate配合Paragraph/Spacer/PageBreak组成 story 列表，适合生成报表、多页文档：

from reportlab.lib.pagesizes import letter from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak from reportlab.lib.styles import getSampleStyleSheet doc = SimpleDocTemplate("report.pdf", pagesize=letter) styles = getSampleStyleSheet() story = [] # Add content title = Paragraph("Report Title", styles['Title']) story.append(title) story.append(Spacer(1, 12)) body = Paragraph("This is the body of the report. " * 20, styles['Normal']) story.append(body) story.append(PageBreak()) # Page 2 story.append(Paragraph("Page 2", styles['Heading1'])) story.append(Paragraph("Content for page 2", styles['Normal'])) # Build PDF doc.build(story)

reference.md 进一步演示了专业报表：用Table组件 +TableStyle实现表头灰底白字、整表网格线、单元格对齐与内边距控制（BACKGROUND/TEXTCOLOR/ALIGN/FONTNAME/FONTSIZE/BOTTOMPADDING/GRID等样式键），足以生成商务级的季度销售报表。

命令行工具：不写代码的 PDF 处理

pdftotext（poppler-utils）

最快最稳的纯文本提取方式，-layout保留版面顺序，-f/-l限定页码范围：

# Extract text pdftotext input.pdf output.txt # Extract text preserving layout pdftotext -layout input.pdf output.txt # Extract specific pages pdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5

qpdf

面向结构性操作（合并、拆分、旋转、解密）的瑞士军刀：

# Merge PDFs qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf # Split pages qpdf input.pdf --pages . 1-5 -- pages1-5.pdf qpdf input.pdf --pages . 6-10 -- pages6-10.pdf # Rotate pages qpdf input.pdf output.pdf --rotate=+90:1 # Rotate page 1 by 90 degrees # Remove password qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

reference.md 补充了更复杂的用法：

• 复杂页范围：qpdf input.pdf --pages input.pdf 1,3-5,8,10-end -- extracted.pdf；跨文件选页合并：qpdf --empty --pages doc1.pdf 1-3 doc2.pdf 5-7 doc3.pdf 2,4 -- combined.pdf；
• 按组拆分：qpdf --split-pages=3 input.pdf output_group_%02d.pdf每 3 页一组；
• 优化与修复：--linearize生成适合流式传输的线性化 PDF；--optimize-level=all清理无用对象并压缩；--check检查损坏；--fix-qdf修复损坏结构；--show-all-pages输出完整结构用于调试；
• 高级加密：qpdf --encrypt user_pass owner_pass 256 --print=none --modify=none -- input.pdf encrypted.pdf用 256 位加密并精确控制打印/修改权限；--show-encryption查看加密状态。

pdftk（如可用）

经典工具，注意它是可选依赖（"if available"）：

# Merge pdftk file1.pdf file2.pdf cat output merged.pdf # Split pdftk input.pdf burst # Rotate pdftk input.pdf rotate 1east output rotated.pdf

常见任务实战

扫描件 OCR：pdf2image + pytesseract

对于扫描件（无文本层），先把每页转成图片，再交给 Tesseract 识别：

# Requires: pip install pytesseract pdf2image import pytesseract from pdf2image import convert_from_path # Convert PDF to images images = convert_from_path('scanned.pdf') # OCR each page text = "" for i, image in enumerate(images): text += f"Page {i+1}:\n" text += pytesseract.image_to_string(image) text += "\n\n" print(text)

添加水印

用水印 PDF 的第一页作为水印页，与目标文档每一页merge_page融合：

from pypdf import PdfReader, PdfWriter # Create watermark (or load existing) watermark = PdfReader("watermark.pdf").pages[0] # Apply to all pages reader = PdfReader("document.pdf") writer = PdfWriter() for page in reader.pages: page.merge_page(watermark) writer.add_page(page) with open("watermarked.pdf", "wb") as output: writer.write(output)

提取内嵌图片

poppler 的pdfimages是提取图片最快的方式：

# Using pdfimages (poppler-utils) pdfimages -j input.pdf output_prefix # This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.

reference.md 补充：pdfimages -list input.pdf只列图片元数据不下发；-all保留原始格式；pdfimages -j -p input.pdf out带页码前缀命名，便于按页归档。

密码保护

pypdf 的encrypt()同时支持用户密码与所有者密码：

from pypdf import PdfReader, PdfWriter reader = PdfReader("input.pdf") writer = PdfWriter() for page in reader.pages: writer.add_page(page) # Add password writer.encrypt("userpassword", "ownerpassword") with open("encrypted.pdf", "wb") as output: writer.write(output)

对应地，读取加密 PDF 时需先判断reader.is_encrypted并调用reader.decrypt("password")（见 reference.md 故障排查章节）。

批量处理与错误处理

reference.md 给出了带日志与异常隔离的批处理模式：glob收集目录内全部 PDF，按operation参数执行合并或文本提取，单个文件失败只记日志并continue，不中断整个批次。

页面裁剪

通过直接修改mediabox的四个边界（单位 point，原点在左下角）裁剪页面：

from pypdf import PdfWriter, PdfReader reader = PdfReader("input.pdf") writer = PdfWriter() # Crop page (left, bottom, right, top in points) page = reader.pages[0] page.mediabox.left = 50 page.mediabox.bottom = 50 page.mediabox.right = 550 page.mediabox.top = 750 writer.add_page(page) with open("cropped.pdf", "wb") as output: writer.write(output)

PDF 表单填写：可填写与不可填写双路径

这是整个技能最复杂也最有价值的场景，forms.md 规定了严格的有序流程：先检测表单是否可填写，再按结果走"可填写字段"或"不可填写字段"两条路径。scripts 目录下的脚本就是为这两条路径设计的（源码注释均标注"See forms.md"）。

第一步：检测表单是否可填写

运行 check_fillable_fields.py：

python scripts/check_fillable_fields.py <file.pdf>

其实现非常直接：用PdfReader(file).get_fields()判断是否存在表单字段定义——非空则输出 "This PDF has fillable form fields"，否则提示需要视觉定位。注意脚本需从document-skills/pdf/目录下运行（python scripts/...），且依赖pypdf环境。

路径 A：可填写字段

第 1 步：抽取字段信息。运行 extract_form_field_info.py：

python scripts/extract_form_field_info.py <input.pdf> <field_info.json>

输出 JSON 为字段数组，每种类型携带不同的附加属性：

[ { "field_id": "(unique ID for the field)", "page": "(page number, 1-based)", "rect": "([left, bottom, right, top] bounding box in PDF coordinates, y=0 is the bottom of the page)", "type": "(\"text\", \"checkbox\", \"radio_group\", or \"choice\")" } ]

其中rect使用 PDF 坐标系（y=0 在页面底部），这是后续与图像坐标换算的关键。各类型专属字段为：

• checkbox：含checked_value/unchecked_value，勾选即把字段设为checked_value（规范上/Off恒为未勾选值）；
• radio_group：含radio_options列表，每项{value, rect}，选中某选项即把字段设为对应value；
• choice（下拉/列表）：含choice_options列表，每项{value, text}。

从源码看，extract_form_field_info.py 的get_full_annotation_field_id会沿/Parent链回溯拼出完整字段 ID（如parent.child）；make_field_dict依据 PDF 字段类型/FT（/Tx文本、/Btn按钮、/Ch选择）映射为 JSON 类型；单选框的每个选项都有独立 annotation，脚本从/AP//N外观状态中取非/Off的激活值，并保留每个选项的rect。最终结果按"页码 → 翻转后的 Y → X"排序（PDF 坐标 y 向上增长，排序时取-rect[1]实现视觉上的自上而下）。字段若只有定义而无可定位的 annotation，会被忽略并打印警告。

第 2 步：渲染页面并理解字段语义。运行 convert_pdf_to_images.py 把每页转成 PNG，再分析图片判断每个字段的用途（务必把 PDF 坐标 bounding box 换算为图像坐标）：

python scripts/convert_pdf_to_images.py <file.pdf> <output_directory>

该脚本内部用pdf2image.convert_from_path(pdf_path, dpi=200)渲染，并限制单边最大 1000 像素（超过则等比缩小），输出page_1.png、page_2.png…… 便于 Claude 视觉理解字段位置。

第 3 步：构造field_values.json。每个条目必须引用field_info.json中的合法field_id，并携带description、page（与字段实际页码一致）与value：

[ { "field_id": "last_name", "description": "The user's last name", "page": 1, "value": "Simpson" }, { "field_id": "Checkbox12", "description": "Checkbox to be checked if the user is 18 or over", "page": 1, "value": "/On" } ]

勾选框用其checked_value；单选框用radio_options中某个选项的value。

第 4 步：回填生成新 PDF。运行 fill_fillable_fields.py：

python scripts/fill_fillable_fields.py <input pdf> <field_values.json> <output pdf>

该脚本会先做三层校验（源码）：字段 ID 是否存在、页码是否匹配、值是否符合该字段类型（checkbox 必须是 checked/unchecked 值、radio 必须属于radio_options、choice 必须属于choice_options），任何错误都打印具体信息并sys.exit(1)，指导修正后重试。校验通过后，用PdfWriter(clone_from=reader)按页分组调用update_page_form_field_values(pages, values, auto_regenerate=False)写入，并调用set_need_appearances_writer(True)让各阅读器正确渲染表单值（源码注释指出这可能导致阅读器即便无改动也提示"保存更改"）。此外脚本还针对 pypdf 5.7.0 在下拉列表字段上的已知缺陷做了 monkeypatch（修正get_inherited对Opt属性返回二维列表导致的TypeError），说明该工作流经过了真实场景的踩坑验证。

路径 B：不可填写字段（视觉定位 + 注释回填）

若 PDF 没有可填写字段，就必须"看"着页面确定数据应该落在哪里，然后以文本注释的形式填入。forms.md 规定必须按以下四步精确执行，每一步都有对应脚本支撑。

Step 1：视觉分析（必须）。同样先用convert_pdf_to_images.py生成每页 PNG。仔细检查每页，为每个需要输入文本的字段同时确定标签框与输入框两个 bounding box，且二者不得相交；输入框只覆盖真正应填写数据的区域（通常在标签的右侧、上方或下方），且必须足够高宽以容纳文字。文档给出了几类常见表单结构的目标框策略：

• 标签在框内（┌ Name: ┐）：输入区在 "Name" 右侧直至框边缘；
• 标签在线上方（Email: ____）：输入区覆盖整条下划线及其上方；
• 标签在线下方（签名、日期常见）：输入区为线上方、覆盖整条线宽；
• 标签在线上方（"Please enter any special requests:"）：输入区从标签底部延伸到线、覆盖整条线宽；
• 复选框：只瞄准小方框（□），不覆盖文字标签，且要与标签文字区分开。

Step 2：构造fields.json并生成验证图（必须）。文件含pages（每页的图像宽高，用于坐标换算）与form_fields（每个字段的页码、描述、标签框、输入框、输入文本），示例片段：

{ "pages": [ { "page_number": 1, "image_width": 1000, "image_height": 1414 } ], "form_fields": [ { "page_number": 1, "description": "The user's last name should be entered here", "field_label": "Last name", "label_bounding_box": [30, 125, 95, 142], "entry_bounding_box": [100, 125, 280, 142], "entry_text": { "text": "Johnson", "font_size": 14, "font_color": "000000" } }, { "page_number": 2, "description": "Checkbox that should be checked if the user is over 18", "entry_bounding_box": [140, 525, 155, 540], "field_label": "Yes", "label_bounding_box": [100, 525, 132, 540], "entry_text": { "text": "X" } } ] }

说明：此处 bounding box 采用图像坐标[left, top, right, bottom]（左上原点、y 向下）；font_size默认 14，font_color为 RRGGBB 十六进制、默认000000（黑色）；复选框用"X"表示勾选。

然后对每一页运行 create_validation_image.py 生成验证图——红色矩形框出输入区、蓝色矩形框出标签（源码中用PIL.ImageDraw分别以红色/蓝色 2 像素描边）：

python scripts/create_validation_image.py <page_number> <path_to_fields.json> <input_image_path> <output_image_path>

Step 3：校验 bounding box（必须）。

• 自动化相交检查：运行 check_bounding_boxes.py：

python scripts/check_bounding_boxes.py <JSON file>

该脚本做两件事（源码）：其一，O(N²) 遍历同页所有 label/entry 框，用矩形不相交判定disjoint_horizontal/vertical检查重叠，边沿相接不算相交；其二，校验每个 entry 框高度不小于entry_text.font_size（默认 14），防止文字溢出。错误信息带字段描述与坐标明细，超过 20 条即中止并提示先修框。配套的 check_bounding_boxes_test.py 用 11 个单元测试覆盖了无相交、同字段标签/输入相交、跨字段相交、不同页不判相交、框高不足、边沿相接合法、默认字号、无 entry_text 跳过、错误条数上限等边界情况，是该校验逻辑的权威行为说明。

• 人工看图复核（关键，禁止跳过）：红色矩形必须只覆盖输入区、绝不能压住文字；蓝色矩形应包住标签文字；复选框的红框必须正中方框、蓝框覆盖其文字标签。任何矩形看起来不对，就修正fields.json、重新生成验证图、再验证，直到完全准确。

Step 4：写入注释生成成品 PDF。运行 fill_pdf_form_with_annotations.py：

python scripts/fill_pdf_form_with_annotations.py <input_pdf_path> <path_to_fields.json> <output_pdf_path>

该脚本的核心是坐标变换（源码）：利用fields.json中的图像宽高与页面mediabox的真实 PDF 尺寸，按比例缩放并翻转 Y 轴（图像原点在左上、PDF 原点在左下），把图像坐标的输入框换算为 PDF 坐标；随后为每个非空字段创建pypdf.annotations.FreeText注释（字体默认 Arial、字号"14pt"、颜色默认000000），按 0-based 页码add_annotation写入。完成后输出成功信息与注解数量。源码注释亦提醒：字号/颜色在不同阅读器中渲染不一定可靠（引用了 pypdf issue #2084），这正是工作流要求先人工核对验证图的原因。

进阶渲染与前端生态

主文档指向的 reference.md 覆盖了主流程之外的三个库：

pypdfium2（Python，PDFium 绑定）——面向快速渲染与出图，可作 PyMuPDF 替代。pdfium.PdfDocument加载后，page.render(scale=2.0, rotation=0)得到 bitmap，to_pil()转 PIL Image 保存为 PNG/JPEG；也可逐页page.get_text()取文本。适合高分辨率预览图、缩略图批量生成。

pdf-lib（JavaScript，MIT）——纯 JS 创建与修改 PDF：PDFDocument.load(bytes)加载、getPageCount()取页数、addPage([w, h])增页并drawText；创建复杂文档时支持embedFont(StandardFonts.HelveticaBold)嵌入标准字体、drawRectangle画底纹、A4 尺寸[595, 842]精确排版，模拟表格用逐行drawText定位即可；合并时用copyPages跨文档拷贝（可只拷指定页索引，如[0, 2, 4]）。

pdfjs-dist（JavaScript，Apache，即 PDF.js）——浏览器端渲染：配置GlobalWorkerOptions.workerSrc后getDocument(url).promise加载，getViewport({scale})算视口，canvas 渲染；getTextContent()可拿文本及item.transform[4]/[5]坐标；getAnnotations()可遍历 annotation 的subtype、contents、rect，用于网页端表单与批注提取。

性能优化与故障排查要点

reference.md 给出的工程化经验：

• 大文件：优先流式/分块而非整载内存；用qpdf --split-pages拆分超大文件；pypdfium2 逐页独立处理；内存受限时按 chunk（如每 10 页一批）建 writer 分块落盘；
• 文本提取：纯文本用pdftotext -bbox-layout最快；结构化数据（表格）用 pdfplumber；超大文档避免pypdf.extract_text()；
• 图片提取：pdfimages远快于页面渲染；预览用低分辨率、终稿用高分辨率；
• 表单填写：pdf-lib 对表单结构保持最好；处理前先校验字段；
• 加密 PDF：reader.is_encrypted判断后decrypt("password")；
• 损坏 PDF：qpdf --check诊断、qpdf --replace-input修复；
• 文本提取失败：扫描件走 OCR 兜底（pytesseract + pdf2image 封装为extract_text_with_ocr()）。

任务速查表

主文档结尾给出的工具选型表是实战时的第一参考：

延伸阅读

• 主流程文档：document-skills/pdf/SKILL.md；
• 进阶库（pypdfium2、pdf-lib、pdfjs-dist）、高级命令行、批处理与性能优化：document-skills/pdf/reference.md；
• 表单填写完整规范与四步校验流程：document-skills/pdf/forms.md；
• 全部配套脚本与测试：document-skills/pdf/scripts/；
• 本技能在仓库中的定位与同族技能（docx、pptx、xlsx）可从 README.md 的 Document Processing 板块进入。

实践中建议按"先check_fillable_fields.py分流 → 可填写走字段抽取回填、不可填写走视觉定位四步法"的顺序执行，并在任何涉及视觉定位的环节坚持"生成验证图 → 人工复核 → 通过后再写入"的纪律，这是保证大批量表单处理不出错的关键。

• AI 技能
• AI 插件
• 人工智能
• 工作流自动化