PDF

PDF 读取、创建、编辑、审查以及基于视觉的内容提取。该技能涵盖 PDF 文档的完整生命周期 — 从使用 reportlab 生成新文件，到使用 pdfplumber 提取文本，使用 Poppler 将页面渲染为图片，以及在每次编辑后执行视觉质量验证。

Reference AI & Media

参考技能： pdf 默认未启用。使用 jaw skill install pdf 安装，或在聊天中输入"PDF 스킬 설치해줘"。启用后，该技能会注入系统提示词，当检测到 PDF 相关任务时，智能体会自动遵循其工作流程。

快速参考

技能名称	`pdf`
分类	AI 与媒体
默认启用	否 — 需要执行 `jaw skill install pdf`
SKILL.md 路径	`~/.cli-jaw/skills/pdf/SKILL.md`（已激活）或 `~/.cli-jaw/skills_ref/pdf/SKILL.md`（参考）
Python 包	`reportlab`、`pdfplumber`、`pypdf`
系统工具	`pdftoppm`（来自 Poppler）
临时目录	`tmp/pdfs/`
输出目录	`output/pdf/`
相关技能	`pdf-vision`、`docx`、`pptx`、`xlsx`

工作流程

当 pdf 技能处于激活状态时，智能体会对每个 PDF 任务严格遵循四步工作流程：

步骤	操作	使用的工具
1. 渲染	将 PDF 页面渲染为 PNG 图片以供视觉审查	`pdftoppm`（Poppler）。如果 Poppler 不可用，则回退为提示用户安装。
2. 生成	创建新的 PDF 或编辑现有 PDF	`reportlab` 用于创建；`pypdf` 用于合并/拆分；`nano-pdf` 用于自然语言页面编辑
3. 提取	从 PDF 文件中提取文本和数据	`pdfplumber` 或 `pypdf` 用于文本提取（注意：布局保真度可能不可靠）
4. 验证	在每次有意义的更新后重新渲染并进行视觉确认	`pdftoppm` + 对齐、间距和可读性的视觉检查

编辑后验证循环： 该技能要求在每次有意义的更改后重新渲染。智能体在确认最新 PNG 渲染无视觉缺陷之前，不会交付 PDF。这是该技能中最重要的规则。

依赖项

该技能会自动检测缺失的依赖项并尝试安装。如果安装被阻止（权限问题、网络问题），智能体会准确告知您缺少哪些依赖项以及如何手动安装。

reportlab uv pip install reportlab

PDF 生成：布局、文本、表格、图片和矢量图形

pdfplumber uv pip install pdfplumber

带位置数据的文本提取、表格检测和页面几何信息

pypdf uv pip install pypdf

PDF 操作：合并、拆分、旋转、加密和元数据编辑

Poppler (pdftoppm) brew install poppler

将 PDF 页面渲染为高质量 PNG 图片，用于视觉验证

该技能优先使用 uv 管理 Python 依赖。如果 uv 不可用，则回退到 python3 -m pip install。

完整安装命令

# Python 包（推荐：uv）
uv pip install reportlab pdfplumber pypdf

# Python 包（备选：pip）
python3 -m pip install reportlab pdfplumber pypdf

# 系统工具：macOS (Homebrew)
brew install poppler

# 系统工具：Ubuntu/Debian
sudo apt-get install -y poppler-utils

渲染命令

核心渲染命令将 PDF 页面转换为 PNG 图片：

pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX

该命令会生成类似 $OUTPUT_PREFIX-1.png、$OUTPUT_PREFIX-2.png 等文件 — 每页一个 PNG。智能体通过读取这些图片来验证布局质量，然后再交付最终 PDF。

文件约定

目录	用途	生命周期
`tmp/pdfs/`	中间渲染文件、草稿 PDF、PNG 预览	任务完成后删除
`output/pdf/`	最终交付的 PDF 文件	持久保存；使用稳定的描述性文件名

文件名稳定性： 该技能在多次编辑中保持文件名稳定且具有描述性。最终输出名称中应避免使用随机后缀或时间戳。请使用清晰的名称，例如 quarterly-report-2026-Q1.pdf 或 invoice-0042.pdf。

质量规则

该技能强制执行严格的视觉和排版标准。每个生成的 PDF 必须通过以下检查：

规则	详情
排版	整个文档中字体、字号和字重保持一致。除非有意为之，否则不混用字体。
间距与边距	统一的边距、行间距和段落间距。内容不得过于拥挤或溢出。
章节层级	标题、子标题和正文之间应有清晰的视觉区分。
无渲染缺陷	不得出现文本裁剪、元素重叠、表格损坏、黑色方块或不可读字符。
图表与表格	渲染清晰，对齐正确，坐标轴和表头标注明确。
图片	不得模糊，保持正确的宽高比，在布局中正确定位。
仅使用 ASCII 连字符	使用标准 ASCII 连字符（`-`）。Unicode 短划线（如 U+2011 不间断连字符）在某些 PDF 阅读器中会导致渲染问题。
引用与参考	仅使用人类可读的文本。不得包含工具令牌、占位符标记或原始 ID。

最终交付检查清单

在将 PDF 任务标记为完成之前，智能体会逐项完成以下检查清单：

验证最新 PNG 渲染无视觉缺陷。
确认页眉和页脚在每一页上正确显示。
验证页码连续且位置正确。
检查章节过渡 — 无孤立标题或孤行段落。
在用户确认后清理 tmp/pdfs/ 中的中间文件。

DOCX 转 PDF

该技能还支持使用 LibreOffice 将 Word 文档转换为 PDF：

# 通过 soffice（LibreOffice 无头模式）将 DOCX 转换为 PDF
soffice --headless --convert-to pdf input.docx --outdir output/pdf/

当源材料是 Word 文档而最终交付物必须是 PDF 时，此功能非常有用。智能体仍会对转换后的输出执行完整的渲染后验证循环。

功能概览

功能	工具	备注
创建新 PDF	`reportlab`	完全控制布局、字体、表格、图片和矢量图形
读取/提取文本	`pdfplumber`、`pypdf`	文本提取；布局保真度是近似的，非像素级精确
编辑现有 PDF	`nano-pdf`	对现有 PDF 内容进行自然语言页面编辑
合并/拆分	`pypdf`	合并多个 PDF 或提取页面范围
渲染为图片	`pdftoppm`	高质量 PNG 渲染，用于视觉质量检查
DOCX 转换	`soffice`	LibreOffice 无头模式 Word 转 PDF
视觉质量检查	智能体视觉	智能体读取渲染的 PNG 以验证质量

"~해줘" 使用示例

以下是用自然语言调用 PDF 任务的实际示例。韩语和英语均可使用。

"이 보고서 PDF로 만들어줘 — 표지, 목차, 본문 3장"

使用 reportlab 创建包含封面、目录和 3 页正文内容的新 PDF 文档。智能体会将每页渲染为 PNG 并在交付前验证布局。

"이 PDF에서 텍스트 추출해줘 — 표 데이터도 포함해서"

使用 pdfplumber 从给定 PDF 中提取所有文本和表格数据。返回保留表格行的结构化文本。如果特定文档的布局保真度不可靠，会发出警告。

"이 두 PDF 합쳐줘 — report-part1.pdf랑 report-part2.pdf"

使用 pypdf 将两个 PDF 文件合并为一个文档。保留页码和书签。输出保存到 output/pdf/。

"이 계약서 PDF 2페이지 날짜 수정해줘"

使用 nano-pdf（自然语言编辑）编辑现有合同 PDF 的第 2 页。编辑完成后，智能体会重新渲染该页面，视觉验证日期修改是否正确且其他内容未发生偏移。

"Word 파일 PDF로 변환해줘 — proposal.docx"

使用 LibreOffice 无头模式（soffice --headless --convert-to pdf）将 DOCX 文件转换为 PDF。随后智能体会将输出渲染为 PNG，检查转换过程中是否引入了格式问题。

与 pdf-vision 的对比

CLI-JAW 提供两个 PDF 相关技能。它们是互补的，而非冗余的：

	`pdf`	`pdf-vision`
侧重点	创建、编辑、提取和合并 PDF	基于视觉分析现有 PDF
最适用于	生成报告、编辑文档、提取文本	扫描文档 OCR、布局理解、从图片提取表格
工具	reportlab、pdfplumber、pypdf、pdftoppm	视觉模型、OCR 流水线
何时同时使用	当您需要从扫描 PDF 中提取数据（`pdf-vision`），然后根据这些数据生成新的整洁 PDF（`pdf`）时。

提示： 使用 jaw skill install pdf pdf-vision 同时安装两者，或输入"PDF 스킬이랑 pdf-vision 둘 다 설치해줘"。当两者都处于激活状态时，它们可以无缝协作。

故障排除

找不到 Poppler

如果智能体报告 pdftoppm 不可用，请安装 Poppler：

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install -y poppler-utils

# 验证
pdftoppm -v

Unicode 短划线渲染问题

如果在连字符和短划线处看到乱码或缺失字符，源数据可能包含 Unicode 短划线（U+2011、U+2013、U+2014）。该技能强制使用 ASCII 连字符（-）以避免阅读器兼容性问题。智能体在生成过程中会自动替换这些字符。

布局保真度警告

pdfplumber 和 pypdf 基于字符位置而非视觉布局提取文本。复杂的多栏布局、重叠的文本框和旋转文本可能无法正确提取。对于这些情况，建议使用 pdf-vision，它采用视觉分析而非文本流解析。

未安装 LibreOffice

DOCX 转 PDF 需要 LibreOffice。如果找不到 soffice：

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
sudo apt-get install -y libreoffice

安装

# CLI
jaw skill install pdf

# 聊天中（韩语）
"PDF 스킬 설치해줘"

# 聊天中（英语）
"Install the PDF skill"

# 验证安装
jaw skill info pdf

# jaw skill info pdf 的预期输出：
#   Name:     pdf
#   Status:   active
#   Category: AI & Media
#   Path:     ~/.cli-jaw/skills/pdf/SKILL.md
#   Description: PDF creation, reading, editing, merging, and text extraction

AI 与媒体技能 PDF Vision