📦 Pdf Filler — 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
• 默认情况下，orchestrator 使用 --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 中的一个字符串），而不是布尔值。
• 签名字段（类型：signature）被报告但不自动填充。
• 加密的 PDF 不在范围内；工具将显示底层库错误。
• 一些 PDF 查看器缓存外观流；如果查看器在填充后显示空白字段，请尝试使用不同的查看器打开或使用 --flatten。