pdf

name	pdf
description	当任务涉及读取、创建或审查 PDF 文件、且渲染和排版很重要时使用；优先通过渲染页面（Poppler）做视觉检查，并使用 `reportlab`、`pdfplumber` 和 `pypdf` 等 Python 工具进行生成和提取。

PDF Skill

何时使用

• 读取或审查排版和视觉重要的 PDF 内容。
• 以编程方式创建排版可靠的 PDF。
• 交付前校验最终渲染。

工作流程

1. 优先视觉审查：把 PDF 页面渲染成 PNG 并检查它们。
   • 有 pdftoppm 就用它。
   • 若不可用，安装 Poppler 或请用户在本地审查输出。
2. 创建新文档时用 reportlab 生成 PDF。
3. 用 pdfplumber（或 pypdf）做文本提取和快速检查；不要依赖它保证排版保真。
4. 每次有意义的更新后，重新渲染页面并校验对齐、间距和可读性。

临时与输出约定

• 中间文件用 tmp/pdfs/；完成后删除。
• 在本仓库工作时，把最终产物写到 output/pdf/ 下。
• 让文件名保持稳定且具描述性。

依赖（缺失则安装）

优先用 uv 管理依赖。

Python 包：

uv pip install reportlab pdfplumber pypdf

如果 uv 不可用：

python3 -m pip install reportlab pdfplumber pypdf

系统工具（用于渲染）：

# macOS (Homebrew)
brew install poppler

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

如果本环境无法安装，告诉用户缺哪个依赖以及如何在本地安装。

环境

无必需环境变量。

渲染命令

pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX

质量期望

• 保持精致的视觉设计：一致的排版、间距、页边距和板块层级。
• 避免渲染问题：文字被裁切、元素重叠、表格错乱、黑块，或不可读的字形。
• 图表、表格和图片必须清晰、对齐、标注明确。
• 只用 ASCII 连字符。避免 U+2011（不换行连字符）和其他 Unicode 破折号。
• 引用和参考必须人类可读；绝不留下工具 token 或占位字符串。

最终检查

• 在最新的 PNG 检查显示零视觉或排版缺陷之前，不要交付。
• 确认页眉/页脚、页码和板块过渡看起来精致。
• 把中间文件整理好，或在最终批准后移除它们。