---
name: pdf
description: >-
  只要 PDF 文件是任务的输入或输出，或者需要被打开、读取、创建、修改，就使用本 Skill。
  包括提取文字和表格、查看页面、合并拆分、旋转裁剪、加水印、填写表单、OCR，以及制作或
  交付 PDF。不用于既不读取也不产出 PDF 的普通写作或一般数据分析。
metadata:
  title: PDF 文档
  version: 2.0.0
  category_key: content-docs
  category_name: 内容与文档
  recommendation: 适合读取、创建和处理固定版式 PDF，包括页面操作与表单。
  tags:
    - pdf
    - document-reading
    - document-creation
    - document-editing
    - page-analysis
---

# PDF 文档

| 任务 | 路径 |
|---|---|
| 阅读、问答、视觉审阅 | 优先用运行时 `Read` 读取相关页面 |
| 提取表格或复杂布局 | 用 `pdfplumber`，并对照原页面 |
| 合并、拆分、旋转、裁剪、元数据、水印 | 用 `pypdf` |
| 新建 PDF | 用 ReportLab；长文档优先使用 Platypus 流式排版 |
| 填写 AcroForm | 用 `pypdf`，同时校验字段树与页面 Widget |
| 扫描件 | 先看页面图像；只有用户需要可搜索文本时才做 OCR |

## 工作契约

- 只读问题不改写或重新导出 PDF。
- 写操作保留原文件并输出新文件；已签名 PDF 默认只读，写入前说明签名会失效。
- 先直接使用当前环境。依赖导入失败且任务需要时，取得用户同意后在隔离环境安装
  `${CLAUDE_SKILL_DIR}/requirements.txt`，不要静默修改系统 Python。

## 读取

- 长文件只读取与问题相关的页面，但答案必须保留页码依据。
- 文本抽取不能证明版式、图表、签名或扫描内容；这些信息必须查看页面。
- 表格抽取后核对表头、跨页行、脚注和合并单元格，不能只相信二维数组。
- 加密、损坏或无法可靠 OCR 的文件要明确说明，不猜内容。

## 创建与编辑

- 新建前确定纸张、用途和阅读场景；中文和其他非拉丁文字注册真实可用字体，避免缺字方块。
- 可见内容使用明确的页边距、层级和分页；表格重复表头并避免行被裁断。
- PDF 适合页面级编辑，不适合可靠重排既有正文。正文大改时请求源 DOCX/PPTX 或重建新 PDF。
- 表单默认保持可交互。更新后核对 `get_fields()` 中的值、每页 `/Widget` 的有效值和 `/AP` 外观；
  只有用户明确要求静态成品时才扁平化，并确认 Widget 与 AcroForm 字段树均已移除。

## 完成条件

1. 用 `pypdf` 重新打开最终文件，确认页数、加密状态、页面顺序和表单结构符合任务。
2. 用 Poppler 渲染全部页面并逐页检查：

```bash
pdftoppm -png -r 144 "<output.pdf>" "<empty-qa-dir>/page"
```

3. 修复截字、重叠、乱码、黑方块、模糊图片、错误页码、断裂表格和意外空白页后重新渲染。
4. 缺少 `pdftoppm` 时可以继续纯文本读取；写任务要说明未完成视觉检查。
5. 最终只交付 PDF，不附带页面 PNG、构建脚本或临时叠加文件。