钳窝PDF标准处理包

你要解决什么问题

PDF 在办公流程里是个矛盾体：它版式固定、跨平台一致，但一旦需要改动就变得很难处理。表单字段怎么找、字段值填到哪里、中文字体能不能正常渲染、扫描件里的文字能不能读出来，这些判断往往散落在不同的库和命令行工具里，工程师每次都要重新摸索一遍。

更麻烦的是安全边界。PDF 是典型的不可信输入格式，内嵌 JavaScript、附件、权限限制都可能造成问题。一个负责任的处理流程不应该顺手下载字体或运行时，也不应该在未经同意的情况下安装系统组件。

这个技能怎么工作

它采用最小依赖策略：优先复用运行环境里已有的 Python 库和命令行工具，不捆绑虚拟环境、字体、模型或系统二进制。工具选择有明确分工：

• 结构级操作（合并、拆分、旋转、加解密）交给 pypdf
• 文本、表格、坐标提取用 pdfplumber，适合带文字层的 PDF
• 创建 PDF 用 reportlab，中文内容必须显式指定本机可用字体
• 页面渲染为图片可用 pypdfium2 或 pdf2image（后者依赖 Poppler）
• 优化、修复、权限处理用 qpdf，使用前确认系统已安装

表单处理是内置脚本的重点。流程分两条分支：先运行 check_fillable_fields.py 判断是否存在可填写字段。如果存在，就提取字段信息并准备字段值 JSON，再用 fill_fillable_fields.py 填写 AcroForm 字段；如果不存在，则提取文字、横线、复选框的结构，建立坐标 JSON，经 check_bounding_boxes.py 校验后调用 fill_pdf_form_with_annotations.py 通过 FreeText 注释填写。完成后必须把结果渲染成图片，检查文字是否越界、重叠或错位。

执行前会先确认输入文件、目标操作、页码范围、输出格式和是否允许覆盖，缺少依赖时会说明名称、用途、来源并征得同意。

适用边界与注意点

• 不猜测关键字段：姓名、证件号、金额、签名等信息缺失时必须先询问，不能用模型臆造
• 不覆盖原件：默认输出到新文件，用 _filled.pdf、_merged.pdf 这类清晰后缀
• OCR 有风险：扫描件识别结果必须标注可能误识别，关键编号、金额、日期应人工复核
• 敏感文件谨慎：涉及合同、证件、财务文件时保留原件并提醒用户复核输出
• 不绕过限制：不处理未知密码，不移除用户无权处理的权限限制
• 不自动下载：字体、模型、运行时一律不自动获取

验证清单要求输出文件能正常打开、页数与顺序正确、文本和字段无丢失、坐标与中文显示正常，并且原始文件未被覆盖或损坏。