PDF 技能
使用时机
- 需要读取或审阅 PDF 内容,且布局和视觉元素至关重要时。
- 需要以可靠的格式程序化创建 PDF 时。
- 在最终交付前验证渲染效果。
工作流程
- 优先进行视觉审阅:将 PDF 页面渲染为 PNG 并检查。
- 如果可用,使用
pdftoppm。 - 如果不可用,安装 Poppler 或请用户在本地审阅输出。
- 如果可用,使用
- 创建新文档时,使用
reportlab生成 PDF。 - 使用
pdfplumber(或pypdf)进行文本提取和快速检查;不要依赖它来保证布局保真度。 - 每次有意义的更新后,重新渲染页面并验证对齐、间距和可读性。
临时文件和输出规范
- 使用
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 破折号。
- 引用和参考文献必须可读;切勿保留工具令牌或占位符字符串。
最终检查
- 在最新的 PNG 检查显示没有任何视觉或格式缺陷之前,不要交付。
- 确认页眉/页脚、页码和章节过渡看起来精美。
- 保持中间文件有序,或在最终批准后将其移除。