钳窝-PDF标准技能包

概述

ClawNest PDF

版本：1.0.0 许可证：MIT-0 版权：Copyright (c) 2026 逍遥府智能科技. All rights reserved.来源说明：基于用户提供的 clawnest-pdf 包整理、中文化并适配；原始内容的既有权利仍归其原权利人所有。

定位

这是一个轻量 PDF 技能，优先使用运行环境中已有的 Python 库和命令行工具，不捆绑虚拟环境、字体、模型或系统二进制。内置脚本重点支持 PDF 表单检测、字段提取、坐标校验、表单填写与渲染验证。

安全边界

• 把所有 PDF 视为不可信输入，只处理用户明确授权的文件。
• 不执行 PDF 内嵌脚本、附件或用户提供的任意代码。
• 不绕过未知密码，不移除用户无权处理的权限限制。
• 不自动下载字体、模型、Python 运行时或系统工具。
• 安装 Python 包或 Poppler、qpdf、Tesseract 等系统工具前，说明名称、用途、来源和命令，并取得用户明确同意。
• 输出到新文件，除非用户明确要求，否则不覆盖原始 PDF。
• 涉及签名、合同、证件、财务或法律文件时，保留原件并提醒用户复核输出。

文件定位

• 优先使用运行环境或聊天附件提供的实际文件路径。
• 用户只给文件名时，先在当前工作区和附件目录中搜索；不要硬编码某个平台的私有媒体目录。
• 存在多个同名文件时先确认目标文件。
• 输出文件使用清晰后缀，例如 _filled.pdf、_merged.pdf、_rotated.pdf。

工作流

1. 明确输入文件、目标操作、页码范围、输出格式和是否允许覆盖。
2. 检查 PDF 是否加密、页数是否合理、是否存在文字层或可填写字段。
3. 选择最小依赖方案并执行；缺少依赖时先征得用户同意。
4. 验证页数、文本、页面顺序、字段值、坐标和可打开性。
5. 返回新文件，并简要说明完成的操作、限制和需要人工复核的内容。

工具选择

常用操作

读取页数与文本

from pypdf import PdfReader

reader = PdfReader("document.pdf")
print(f"页数：{len(reader.pages)}")
text = "n".join(page.extract_text() or "" for page in reader.pages)

复杂布局或表格优先使用 pdfplumber：

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page_number, page in enumerate(pdf.pages, 1):
        print(f"第 {page_number} 页")
        print(page.extract_text() or "")
        print(page.extract_tables())

合并 PDF

from pypdf import PdfReader, PdfWriter

writer = PdfWriter()
for path in ["a.pdf", "b.pdf"]:
    reader = PdfReader(path)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)

拆分 PDF

from pypdf import PdfReader, PdfWriter

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

旋转页面

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()
for page in reader.pages:
    page.rotate(90)
    writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)

创建 PDF

from reportlab.lib.pagesizes import A4
from reportlab.pdfgen import canvas

pdf = canvas.Canvas("created.pdf", pagesize=A4)
pdf.drawString(72, 780, "Hello PDF")
pdf.save()

创建中文 PDF 时使用本机可信中文字体，并先确认字形覆盖。不要自动从未知网址下载字体。ReportLab 的标准字体不完整支持 Unicode 上下标字符；在 Paragraph 中使用 <sub> 和 <super> 标记。

扫描件与 OCR

1. 先判断页面是否没有可用文字层。
2. 优先把页面渲染成图片，再使用当前环境的多模态能力识别。
3. 只有用户明确同意后，才安装或调用额外 OCR 系统工具。
4. OCR 结果必须标明可能存在误识别；关键编号、金额、姓名和日期应人工复核。

表单处理

填写表单时必须先阅读 [references/forms.md](references/forms.md)，并按以下分支执行：

1. 运行 python scripts/check_fillable_fields.py <input.pdf>。
2. 有可填写字段：提取字段信息，准备字段值 JSON，再调用 fill_fillable_fields.py。
3. 无可填写字段：提取结构或渲染图片，建立坐标 JSON，校验后调用 fill_pdf_form_with_annotations.py。
4. 将结果再次渲染为图片，检查文字是否越界、重叠或错位。

不得猜测用户未提供的姓名、证件号、金额、签名或其他关键字段。缺少信息时先询问。

内置脚本

依赖

脚本依赖列在 requirements.txt，不要打包虚拟环境。安装前向用户说明将从 PyPI 获取以下包并取得同意：

python -m pip install -r requirements.txt

pdf2image 还需要系统提供 Poppler。缺少 Poppler 时，可优先使用环境已有的 pypdfium2 或 Poppler 命令；如需安装系统包，必须先确认。

验证清单

• 输出 PDF 能正常打开，页数与页面顺序符合要求。
• 未覆盖或损坏原始文件。
• 文本、图片、表格和表单字段没有明显丢失。
• 表单值与用户提供的数据逐项对应。
• 坐标、字体、换行和中文显示正常。
• 加密或解密操作符合用户授权。
• OCR 关键字段已经复核或明确标注风险。

进阶参考

需要更详细的渲染、JavaScript 库、命令行工具、优化修复和故障排查时，读取 [references/advanced.md](references/advanced.md)。