pdf-processing

name	pdf-processing
description	PDF 元信息、正文/页抽取（大文件 --pages 分段）、合并拆分、页面渲染 PNG；扫描件/图片型 PDF（无文本层）需先渲染为图片走视觉模型识别（本包不做 OCR）；Word/HTML/表格类不属本 Skill（→ document-conversion / spreadsheet-analysis）。

PDF 解析与处理

When to use

• 用户上传或引用了 .pdf，需要读元信息、抽正文、按页提取、合并多份、拆分、渲染页面为图片。
• 需要把 PDF 内容交给下游（图谱、记忆、报告、表格）之前先抽取文本。
• 需要视觉核对 PDF 页面（缩略图/截图）。

不是本 Skill 的职责：.doc/.docx/.rtf/.html 的正文抽取与格式转换（→ document-conversion）；表格 .csv/.xls/.xlsx 的读取与清洗（→ spreadsheet-analysis）。本 Skill 只管 PDF。若用户目标是"把 Word 转成 PDF"，先走 document-conversion（docx → HTML → 打印），不要在本 Skill 里硬造。

决策顺序

1. 先 pdf_info.py 拿到页数/大小/加密状态，决定能否处理（加密 PDF 需先说明无法离线解密）。
2. 只要文字 → pdf_extract_text.py（可 --pages 限定范围，避免大文件超时）。
3. 合并/拆分 → pdf_merge.py / pdf_split.py（操作整份 PDF，不解密内部文本）。
4. 视觉预览 → pdf_to_png.py（按页渲染 PNG）。
5. 组合优先：pdf_extract_text → 下游；pdf_merge → pdf_to_png 做合并后核对。

脚本索引

脚本	用途
pdf_info.py	页数、尺寸、加密、标题等元信息
pdf_extract_text.py	全文/指定页文本抽取（JSON + 文本文件）
pdf_merge.py	按顺序合并多份 PDF
pdf_split.py	按页范围拆分出一份新 PDF
pdf_to_png.py	把一页渲染为 PNG（fitz）

组合路线

PDF ──pdf_info──> 元信息
PDF ──pdf_extract_text──> 正文.txt ──> 图谱/记忆/报告
PDF A + B ──pdf_merge──> 合并.pdf ──pdf_to_png──> 缩略图
PDF ──pdf_split──> 子集.pdf ──> 交付/下游

安全与限制

• 所有脚本离线运行，不联网、不执行包安装。
• 输入输出限制在沙箱工作区内；覆盖输出需 --overwrite。
• 加密（需密码）的 PDF 无法离线处理——如实说明，不猜测密码。
• 大文件：先 pdf_info 看页数，抽文本用 --pages 分段，避免 wall-time 180s 超时。

详细说明

组合配方见 references/best-combinations.md，输入/输出契约见 references/input-output-contract.md，常见失败见 references/troubleshooting.md。每个脚本的完整用法见 scripts/*.md。