DeepChat PDF 处理技能实战指南：从文本提取、文档合并到表单填写的全流程工具箱

DeepChat PDF 处理技能实战指南从文本提取、文档合并到表单填写的全流程工具箱【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat导读resources/skills/pdf/SKILL.md是 DeepChat 内置的 PDF 处理技能Skill入口文档它定义了一套Python 库 命令行工具双轨并行的 PDF 操作工具箱覆盖文本与表格提取、PDF 创建、合并/拆分、页面旋转、OCR、水印、加密以及表单填写等高频场景。阅读本文后你将掌握如何在 DeepChat 的 Agent 会话中按标准流程处理各类 PDF 文档——从读取一页文本开始到批量合并拆分再到精确填写可编辑或扫描版 PDF 表单并获得仓库内配套脚本与参考文档的完整操作路径。技能定位与适用场景该技能文件以 YAML frontmatter 声明元信息name: pdf description: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. license: Proprietary. LICENSE.txt has complete terms它面向程序化、规模化地处理 PDF的场景批量抽取文本与表格、程序生成 PDF、合并与拆分文档、处理表单。技能的核心指令组织为三层主指南SKILL.md日常操作的完整教程含 Python 库与命令行工具的入门用法进阶参考reference.md高级特性、JavaScript 库pdf-lib、pdfjs-dist、pypdfium2 渲染、复杂工作流、性能优化与故障排查表单专项forms.md填写 PDF 表单的强制流程配合scripts/目录下 8 个可执行脚本使用。从源码结构看这类SKILL.md文件会被 DeepChat 的技能系统识别与加载技能发现逻辑在 discoveryWorker.ts 中通过查找名为SKILL.md的入口文件来枚举技能用户插件的打包逻辑在 userPluginPackage.ts 中会检查技能根目录是否存在SKILL.md超过 1 MiB 会报错Agent 侧的系统提示词生成器 systemPromptBuilder.ts 明确约定查看技能根目录的SKILL.md即激活该技能用于当前消息/工具循环。因此这个 PDF 技能文件是可以在 DeepChat 会话中直接触发、按规范执行的实战指令集。快速开始读取 PDF 并提取文本最小的可用示例基于pypdfBSD 许可覆盖打开文档 → 统计页数 → 逐页抽取文本三步from pypdf import PdfReader, PdfWriter # Read a PDF reader PdfReader(document.pdf) print(fPages: {len(reader.pages)}) # Extract text text for page in reader.pages: text page.extract_text()需要说明的是extract_text()对于排版简单的文档效果良好但面对复杂布局或扫描件时并不总是理想——这正是后续pdfplumber保留布局与 OCR 流程存在的意义。Python 库详解技能文档把 Python 侧的能力划分为三个互补的库pypdf基础操作、pdfplumber文本与表格提取、reportlabPDF 生成。pypdf合并、拆分、元数据与旋转合并多个 PDF——把多个文件的所有页面依次加入同一个PdfWriterfrom pypdf import PdfWriter, PdfReader writer PdfWriter() for pdf_file in [doc1.pdf, doc2.pdf, doc3.pdf]: reader PdfReader(pdf_file) for page in reader.pages: writer.add_page(page) with open(merged.pdf, wb) as output: writer.write(output)拆分 PDF——每页独立写成一个文件适合按页分发reader PdfReader(input.pdf) for i, page in enumerate(reader.pages): writer PdfWriter() writer.add_page(page) with open(fpage_{i1}.pdf, wb) as output: writer.write(output)提取元数据——标题、作者、主题、创建者等信息可直接从reader.metadata读取reader PdfReader(document.pdf) meta reader.metadata print(fTitle: {meta.title}) print(fAuthor: {meta.author}) print(fSubject: {meta.subject}) print(fCreator: {meta.creator})旋转页面——rotate()的参数以度为单位正值顺时针reader PdfReader(input.pdf) writer PdfWriter() page reader.pages[0] page.rotate(90) # Rotate 90 degrees clockwise writer.add_page(page) with open(rotated.pdf, wb) as output: writer.write(output)此外pypdf 还支持通过page.mediabox各边界left/bottom/right/top单位为 point裁剪页面这在进阶参考 reference.md 中有完整示例。pdfplumber保留布局的文本与表格提取pdfplumberMIT 许可适合需要版面感知的提取任务。带布局的文本提取import pdfplumber with pdfplumber.open(document.pdf) as pdf: for page in pdf.pages: text page.extract_text() print(text)基础表格提取——extract_tables()返回列表的列表逐行打印with pdfplumber.open(document.pdf) as pdf: for i, page in enumerate(pdf.pages): tables page.extract_tables() for j, table in enumerate(tables): print(fTable {j1} on page {i1}:) for row in table: print(row)进阶表格提取 Excel 导出——把首行当列名转成DataFrame再合并所有页的表格导出为 xlsximport pandas as pd with pdfplumber.open(document.pdf) as pdf: all_tables [] for page in pdf.pages: tables page.extract_tables() for table in tables: if table: # Check if table is not empty df pd.DataFrame(table[1:], columnstable[0]) all_tables.append(df) # Combine all tables if all_tables: combined_df pd.concat(all_tables, ignore_indexTrue) combined_df.to_excel(extracted_tables.xlsx, indexFalse)对于复杂排版的表格reference.md 还给出了自定义提取设置通过vertical_strategy/horizontal_strategy如lines控制表格线检测策略并用snap_tolerance、intersection_tolerance调节对齐容差同时支持page.chars逐字符读取坐标x0、y0以及用page.within_bbox((left, top, right, bottom))按包围盒截取局部文本。reportlab从零创建 PDFreportlabBSD 许可负责生成侧的能力提供两种风格。Canvas 风格——适合简单页面信纸尺寸 Letterfrom reportlab.lib.pagesizes import letter from reportlab.pdfgen import canvas c canvas.Canvas(hello.pdf, pagesizeletter) width, height letter # Add text c.drawString(100, height - 100, Hello World!) c.drawString(100, height - 120, This is a PDF created with reportlab) # Add a line c.line(100, height - 140, 400, height - 140) # Save c.save()Platypus 风格——适合多页结构化文档标题、正文、分页符通过SimpleDocTemplate与story元素流构建from reportlab.lib.pagesizes import letter from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak from reportlab.lib.styles import getSampleStyleSheet doc SimpleDocTemplate(report.pdf, pagesizeletter) styles getSampleStyleSheet() story [] # Add content title Paragraph(Report Title, styles[Title]) story.append(title) story.append(Spacer(1, 12)) body Paragraph(This is the body of the report. * 20, styles[Normal]) story.append(body) story.append(PageBreak()) # Page 2 story.append(Paragraph(Page 2, styles[Heading1])) story.append(Paragraph(Content for page 2, styles[Normal])) # Build PDF doc.build(story)reference.md 在此基础上补充了TableTableStyle生成带表头底色、斑马纹与网格线的专业报表可用于季度销售报告等场景。命令行工具当处理超大文件、需要极致速度或要利用系统级工具时命令行工具是 Python 库之外的第二条路线。pdftotextpoppler-utils# Extract text pdftotext input.pdf output.txt # Extract text preserving layout pdftotext -layout input.pdf output.txt # Extract specific pages pdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5进阶用法见 reference.md包括pdftotext -bbox-layout输出带精确坐标的 XML结构化数据提取的关键以及pdftoppm按分辨率与页范围转 PNG/JPEGpdftoppm -png -r 300 document.pdf output_prefix pdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages pdftoppm -jpeg -jpegopt quality85 -r 200 document.pdf jpeg_outputqpdf# Merge PDFs qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf # Split pages qpdf input.pdf --pages . 1-5 -- pages1-5.pdf qpdf input.pdf --pages . 6-10 -- pages6-10.pdf # Rotate pages qpdf input.pdf output.pdf --rotate90:1 # Rotate page 1 by 90 degrees # Remove password qpdf --passwordmypassword --decrypt encrypted.pdf decrypted.pdfqpdf 的进阶能力reference.md非常值得关注复杂页操作qpdf --split-pages3按组拆分--pages input.pdf 1,3-5,8,10-end抽取任意页组合跨文件混排合并优化与修复--linearize生成适合流式传输的线性化 PDF--optimize-levelall压缩冗余对象--check检查损坏结构、--fix-qdf尝试修复加密qpdf --encrypt user_pass owner_pass 256 --printnone --modifynone -- input.pdf encrypted.pdf按 256 位 AES 加密并限定权限--show-encryption查看加密状态。pdftk如果可用# Merge pdftk file1.pdf file2.pdf cat output merged.pdf # Split pdftk input.pdf burst # Rotate pdftk input.pdf rotate 1east output rotated.pdf常见任务速查从扫描版 PDF 提取文本OCR扫描件没有文本层需要转图片 → OCR两步依赖pip install pytesseract pdf2image# Requires: pip install pytesseract pdf2image import pytesseract from pdf2image import convert_from_path # Convert PDF to images images convert_from_path(scanned.pdf) # OCR each page text for i, image in enumerate(images): text fPage {i1}:\n text pytesseract.image_to_string(image) text \n\n print(text)该思路也是 reference.md 中文本提取失败时回退 OCR的故障排查手段。添加水印复用已有水印 PDF 的第一页逐页merge_pagefrom pypdf import PdfReader, PdfWriter # Create watermark (or load existing) watermark PdfReader(watermark.pdf).pages[0] # Apply to all pages reader PdfReader(document.pdf) writer PdfWriter() for page in reader.pages: page.merge_page(watermark) writer.add_page(page) with open(watermarked.pdf, wb) as output: writer.write(output)提取内嵌图片# Using pdfimages (poppler-utils) pdfimages -j input.pdf output_prefix # This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.进阶用法见 reference.mdpdfimages -all保留原始格式导出pdfimages -list只列元信息需要更精细的图形抽取时可用 pypdfium2 高分渲染页面再以图像处理如 numpy 非白区域检测定位图形区域。密码保护writer.encrypt()可同时设置用户密码打开密码与所有者密码权限密码from pypdf import PdfReader, PdfWriter reader PdfReader(input.pdf) writer PdfWriter() for page in reader.pages: writer.add_page(page) # Add password writer.encrypt(userpassword, ownerpassword) with open(encrypted.pdf, wb) as output: writer.write(output)读取加密 PDF 时pypdf 需要先判断reader.is_encrypted再调用reader.decrypt(password)完整示例见 reference.md 的Encrypted PDFs小节。PDF 表单填写完整实战流程这是本技能最有价值的专项能力完整流程记录在 forms.md 中且必须严格按步骤顺序执行。所有脚本都从resources/skills/pdf/scripts/目录运行并配套了自动化测试如 check_bounding_boxes_test.py保证可靠性。第一步判断表单是否可填写首先运行 check_fillable_fields.pypython scripts/check_fillable_fields file.pdf脚本基于pypdf的reader.get_fields()判断存在表单字段则输出 This PDF has fillable form fields否则提示需要视觉定位填写位置。之后根据结果进入可填写字段或不可填写字段两条流程。流程 A可填写字段原生表单域A1. 提取字段信息。运行 extract_form_field_info.py 生成字段清单 JSONpython scripts/extract_form_field_info.py input.pdf field_info.json输出格式如下rect为 PDF 坐标系下的[left, bottom, right, top]包围盒y0 在页面底部[ { field_id: last_name, page: 1, rect: [30, 700, 300, 720], type: text }, { field_id: Checkbox12, page: 1, type: checkbox, checked_value: /On, unchecked_value: /Off }, { field_id: gender, page: 2, type: radio_group, radio_options: [ { value: /Male, rect: [100, 500, 115, 515] } ] }, { field_id: country, page: 2, type: choice, choice_options: [ { value: CN, text: China } ] } ]其中复选框带有checked_value/unchecked_value单选组带radio_options列表下拉选择带choice_optionsvalue 为提交值、text 为显示文本。从源码看脚本会沿/Parent链拼接完整字段 ID如a.b.c通过/FT区分字段类型/Tx文本、/Btn按钮、/Ch选择并跳过无对应注解、无法定位的字段见 extract_form_field_info.py 中的get_full_annotation_field_id与make_field_dict。A2. 渲染页面做视觉分析。运行 convert_pdf_to_images.py 把每页转成 PNGdpi200超出 1000px 自动缩放用于理解每个字段的用途python scripts/convert_pdf_to_images.py file.pdf output_directoryA3. 编写field_values.json。field_id必须与 A1 输出的field_id严格一致page必须匹配复选框用其checked_value勾选、单选组用radio_options中的value[ { field_id: last_name, description: The users last name, page: 1, value: Simpson }, { field_id: Checkbox12, description: Checkbox to be checked if the user is 18 or over, page: 1, value: /On } ]A4. 填充并输出。运行 fill_fillable_fields.pypython scripts/fill_fillable_fields.py input pdf field_values.json output pdf该脚本会严格校验字段 ID 不存在、页码不匹配、复选框/单选/下拉取值非法都会打印 ERROR 并退出码 1需要修正后重试。校验逻辑位于validation_error_for_field_value见 fill_fillable_fields.py。填充通过writer.update_page_form_field_values()按页写入并调用set_need_appearances_writer(True)确保大多数 PDF 阅读器能正确渲染表单值。值得留意的是源码中针对 pypdf 5.7.0 下拉列表selection list的已知 bug 做了 monkey-patchmonkeypatch_pydpf_method把get_inherited返回的[[value1,Text 1],...]修正为字符串列表这是该流程能可靠工作的底层细节。流程 B不可填写字段扫描件/无表单域当 PDF 没有原生表单域时需要视觉定位 文本注解四步完成且每一步都强制要求Step 1视觉分析必需。先转 PNG同 A2然后逐页识别所有填写区域。关键规则标签框与输入框不得相交输入框只覆盖应录入数据的区域通常在标签的右侧、上方或下方输入框要足够高宽容纳文字。文档给出了几类常见结构的目标定位法框内标签如┌── Name: ──┐输入区从 Name 标签右侧延伸到框边缘标签在线上方如Email: ________输入区在横线上方并覆盖其全部宽度标签在线下方如签名/日期行输入区在横线上方并覆盖整条线宽标签在线上方的大段说明如特殊请求输入区从标签底部延伸至横线、覆盖整条线宽复选框如Yes □ No □目标是小方框本身而非文字标签输入框只覆盖小方框。Step 2创建fields.json与验证图必需。格式如下包围盒为图像像素坐标[left, top, right, bottom]{ pages: [ { page_number: 1, image_width: 1200, image_height: 1600 } ], form_fields: [ { page_number: 1, description: The users last name should be entered here, field_label: Last name, label_bounding_box: [30, 125, 95, 142], entry_bounding_box: [100, 125, 280, 142], entry_text: { text: Johnson, font_size: 14, font_color: 000000 } }, { page_number: 2, description: Checkbox that should be checked if the user is over 18, entry_bounding_box: [140, 525, 155, 540], field_label: Yes, label_bounding_box: [100, 525, 132, 540], entry_text: { text: X } } ] }其中entry_text.font_size默认 14font_color为 RRGGBB 格式默认000000黑勾选复选框用文本 X。随后对每一页运行 create_validation_image.py 生成验证图——红色矩形标出输入区、蓝色矩形盖住标签文字python scripts/create_validation_image.py page_number path_to_fields.json input_image_path output_image_pathStep 3校验包围盒必需。先做自动化检查运行 check_bounding_boxes.pypython scripts/check_bounding_boxes.py JSON file脚本执行两件事其一两两检测同页内所有 label/entry 包围盒是否相交相交即 FAILURE 并列出涉及的字段描述其二检查每个 entry 框高度是否足以容纳其font_size文本高度 字号即报错。全部通过时输出 SUCCESS: All bounding boxes are valid。随后必须人工目检验证图红色矩形只能覆盖输入区且不得包含任何文字蓝色矩形应覆盖标签文字复选框的红色矩形必须对准方框中心。发现偏差就修正fields.json、重新生成验证图、再验证迭代至完全准确。Step 4写入注解生成成品。运行 fill_pdf_form_with_annotations.pypython scripts/fill_pdf_form_with_annotations.py input_pdf_path path_to_fields.json output_pdf_path该脚本的核心在于坐标系变换transform_coordinates把图像坐标系原点在左上、y 向下的包围盒换算为 PDF 坐标系原点在左下、y 向上再以FreeText注解支持 font、font_size、font_color边框与背景可设为 None按页写入。脚本会跳过entry_text缺失或文本为空的字段最终打印成功信息与写入的注解数量。源码注释还提醒字体大小/颜色在不同阅读器间渲染并不完全一致关联 pypdf issue #2084因此最终结果最好在目标查看器中复核。进阶能力速览reference.mdreference.md 是本技能的超集值得按需查阅pypdfium2Apache/BSD 许可Chromium PDFium 的 Python 绑定主打快速渲染。PdfDocumentpage.render(scale2.0)高分渲染转 PIL 图片或page.get_text()抽取文本是 PyMuPDF 的轻量替代pdf-libMIT 许可JavaScript 端创建/修改 PDFPDFDocument.load/create、copyPages实现跨文档页复制与选择性合并、内嵌 Helvetica 等标准字体绘制富文本页面pdfjs-distApache 许可Mozilla 的浏览器端渲染库getDocument加载、page.render绘制到 Canvas、getTextContent提取带坐标文本item.transform[4]/[5]、getAnnotations读取注解与表单批量处理batch_process_pdfs示例展示了带 logging 与异常续跑损坏文件跳过的目录级批量合并/文本抽取性能优化大文件优先流式与qpdf --split-pages纯文本抽取首选pdftotext -bbox-layout结构化表格用 pdfplumber图片提取用pdfimages远快于页面渲染超大文档按页分块chunk处理以控制内存。快速参考表任务首选工具命令/代码合并 PDFpypdfwriter.add_page(page)拆分 PDFpypdf每页一个文件提取文本pdfplumberpage.extract_text()提取表格pdfplumberpage.extract_tables()创建 PDFreportlabCanvas 或 Platypus命令行合并qpdfqpdf --empty --pages ...OCR 扫描件pytesseract先转图片再识别填充 PDF 表单pdf-lib 或 pypdf按 forms.md 流程下一步阅读技能目录完整结构如下按需取用主指南resources/skills/pdf/SKILL.md进阶参考pypdfium2 / pdf-lib / pdfjs-dist / 高级命令行 / 性能与排障resources/skills/pdf/reference.md表单填写专项流程resources/skills/pdf/forms.md配套脚本8 个含自动化测试resources/skills/pdf/scripts/许可条款resources/skills/pdf/LICENSE.txt需要填写 PDF 表单时务必先读 forms.md 并严格遵循其步骤顺序——先判定是否可填写再选择对应的填充流程复杂布局或故障排查问题则回到 reference.md 查找对应章节。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考