PDF 处理

PDF 技能#

何时使用#

• 阅读或审查对版式和视觉效果有要求的 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 破折号。
• 引文和参考文献必须便于人阅读；绝不能留下工具标记或占位字符串。

最终检查#

• 在最新的 PNG 检查显示没有任何视觉或格式缺陷之前，不要交付。
• 确认页眉/页脚、页码和章节过渡看起来精致。
• 整理好中间文件，或在最终确认后将其删除。