開放原始碼技能

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 檢查顯示零視覺或格式缺陷，才能交付。
• 確認頁首/頁尾、頁碼與章節過渡效果是否精緻。
• 保持中間檔案有組織，或在最終核准後移除。