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 检查确认不存在任何视觉或格式缺陷后，才能交付。
• 确认页眉/页脚、页码和章节过渡效果精致。
• 整理好中间文件，或在最终批准后将其删除。