PDF 填充工具

pdf-filler 在 PDF AcroForms 上操作：列出每个字段及其类型和当前值，然后使用 JSON 中提供的值填充 PDF。该技能调用一个小的 Python 包（oc-pdf-filler），它包装了一系列 PDF 库的回退链，以便单个 PDF 不会阻塞工作流。

何时使用此技能：

• 当用户要求检查、列出或提取 PDF 表单字段时
• 当用户要求以编程方式填写、填充或完成 PDF 表单时
• 当用户在 PDF 中提到 AcroForm、复选框、单选按钮或下拉菜单处理时
• 当用户有一个 PDF 批次需要从结构化数据（JSON）中填充时

设置（每个工作空间一次）：

• 该技能脚本调用 oc-pdf-filler Python 包。首先安装它：pip install "oc-pdf-filler[all]"
• 或者，如果从源仓库工作：pip install -e ".[all]"
• [all] 额外内容拉入 pdfrw 和 PyMuPDF 以获得完整的回退链。
• 从包管理器安装 pdftk 作为最后的手段后端（可选，但对于顽固的 PDF 很有用）。
• 验证哪些后端是活动的：python scripts/list_backends.py

步骤 1：提取字段架构

• 总是先提取，以便在构造 JSON 值文件之前知道确切的字段名称和类型。
• python scripts/extract.py /path/to/form.pdf --output /tmp/schema.json --include-values
• 每个 JSON 项都包含：

- name：AcroForm 字段名称（在填充时使用此名称作为键） - type：text、checkbox、radio、choice、signature、pushbutton 或 unknown 之一 - options：对于单选按钮和复选框，接受的导出值；对于选择，下拉选项 - value：当前值，如果表单部分填充（仅当设置 --include-values 时） - max_length、multiline、required、read_only：验证提示

• 参见 references/FIELD_TYPES.md 以获取每个字段类型的值合同。

步骤 2：构建值 JSON 文件

• 填充输入是一个平面 JSON 对象 { "FieldName": value }。
• 示例：{ "Name Verantwortlicher": "ACME GmbH", "Postleitzahl Verantwortlicher": "10115", "Beschäftigte": true, "Verarbeitungstyp": "Automatisiert" }
• 包含一个示例模板 assets/values.example.json。

步骤 3：填充 PDF

• python scripts/fill.py /path/to/form.pdf /tmp/values.json --output /tmp/filled.pdf
• 默认情况下，编排器使用 --backend auto，遍历 pypdf -> pdfrw -> PyMuPDF -> pdftk 链，并在第一个填充每个字段的后端处停止。
• 有用的标志：

- --backend pymupdf：强制使用特定的后端（例如，当自动获胜者生成的 PDF 在您的查看器中无法正确渲染时） - --best-effort：链接后端以便部分填充累积（当没有单个后端处理每个字段时使用） - --flatten：将值烘烤到 PDF 中，以便它们不能被编辑（PyMuPDF 和 pdftk 支持最佳） - --strict：如果任何请求字段丢失或无法填充，则退出非零

• 脚本打印一个 JSON 摘要，包括 winning_backend、filled、missing、failed 和每次尝试的详细信息。
• 如果填充失败，请参见 references/BACKENDS.md 以获取后端特定的故障排除提示。

从头到尾的示例

• python scripts/extract.py form.pdf -o schema.json
• ... 代理检查 schema.json，根据用户输入构建 values.json ...
• python scripts/fill.py form.pdf values.json -o filled.pdf
• 填充后，重新运行 extract.py --include-values filled.pdf 并在将 PDF 交付给用户之前确认值已粘贴。

注意事项和边缘情况

• 字段名称可能包含空格、德语重音符号或标点符号。始终从 extract.py 输出中复制它们。
• 对于单选组，设置值为所选选项的导出名称（options 中的一个字符串），而不是布尔值。
• 签名字段（type：signature）被报告但不自动填充。
• 加密的 PDF 不在范围内；工具将显示底层库错误。
• 一些 PDF 查看器缓存外观流；如果查看器在填充后显示空白字段，请尝试使用不同的查看器打开或使用 --flatten。