pdf

PDF 文件

你已经了解 pypdf、pdfplumber 和 reportlab。本技能补充了它们不具备的功能：会检查自身输入的表单填充脚本、查看读者实际看到的页面，以及那些会悄无声息地把内容放错位置的 PDF 行为。

运行脚本

<skill> 是包含此文件的目录。从用户的工作目录使用绝对路径运行捆绑脚本，这样指向其文件的相对路径才能正常工作：

uv run <skill>/scripts/convert_pdf_to_images.py report.pdf pages

运行你编写的 Python 代码时，请声明其依赖项，可以使用 uv run --with pypdf script.py，也可以使用 PEP 723 标头。渲染页面需要 poppler（pdftoppm）；OCR 还需要 Tesseract。

选择工具

任务	使用
填充表单，无论可填写表单还是扁平表单	forms.md，务必使用。它为每个步骤都提供了脚本。
文本	使用 pdfplumber，或从命令行运行 pdftotext -layout。如果页面上明显有文本但提取不到，说明这是扫描件：请参阅 ocr.md。
表格	使用 pdfplumber：请参阅 tables.md
新建 PDF	使用 reportlab：流式文档用 Platypus，精确定位用 canvas
合并、拆分、旋转、裁剪、盖章、加密	使用 pypdf：请参阅 reference.md，了解如何在操作中保留书签、链接和方向
查看页面效果	scripts/convert_pdf_to_images.py

检查输出

每当你创建或修改 PDF，都要渲染改动过的页面并在交付前查看。检查文本是否存在且清晰易读，是否有内容被裁切或重叠，以及每个印章或数值是否位于正确位置：

uv run <skill>/scripts/convert_pdf_to_images.py out.pdf check --pages 1-3

容易悄无声息出错的问题

• 两种坐标系。 PDF 坐标以页面框左下角为原点，单位为点。pdfplumber 和页面图像则以左上角为原点。页面框的起点不一定是 (0, 0)，因此请读取 page.cropbox.left 和 .bottom。
• 旋转页面。 /Rotate 只会旋转页面的显示效果；内容和表单字段仍使用未旋转的坐标。直接缩放并翻转 y 轴会导致内容放错位置。请使用 scripts/pdf_coords.py 转换边界框，并在盖章前调用 page.transfer_rotation_to_content()。
• 新建 PDF 中的非拉丁文字。 reportlab 的内置字体会把中文、西里尔字母等文字绘制成黑色方框。请注册并嵌入 TrueType 字体；参阅 reference.md。
• 合并。 PdfWriter.append() 会保留书签和链接，而使用 add_page() 复制页面则会丢弃它们。合并后的表单若有同名字段，这些字段会合并为一个，填写一个字段会同时填入两处。
• AES 加密需要 uv run --with 'pypdf[crypto]'。如果未安装，pypdf 会在打开或加密时引发 DependencyError。

脚本

脚本	功能
check_fillable_fields.py <pdf>	指出 forms.md 中适用的表单处理方式
extract_form_field_info.py <pdf> <out.json>	列出可填写字段及其页码、边界框和可接受的值
fill_fillable_fields.py <pdf> <values.json> <out.pdf>	检查每个字段 ID、页码和值后填充字段
convert_pdf_to_images.py <pdf> <dir> [--pages] [--fields]	逐页将页面渲染为 PNG，可选绘制每个可填写字段的轮廓
check_bounding_boxes.py <fields.json> [pdf]	在填充扁平表单前查找重叠或过短的边界框
create_validation_image.py <page> <fields.json> <png> <out.png>	在页面图像上绘制这些边界框，以便目视检查
fill_pdf_form_with_annotations.py <pdf> <fields.json> <out.pdf>	用可在所有环境中呈现一致的文本填充扁平表单
flatten_form.py <pdf> <out.pdf>	将已填入的值绘制到页面中，使其无法编辑
pdf_coords.py <pdf> <page> <WxH> --to-pdf/--to-image <box>	在页面图像像素与 PDF 点之间转换边界框