PDF 工具組
一套具備 Acrobat 等級功能的文件引擎，透過友善代理程式的 CLI 提供服務。將工作表達為文件意圖，而非低階的 PDF 指令。
執行時約定
內建的 CLI 是自足的（無需 npm install）。它需要 Node 20+ 以及外部二進位檔：qpdf 和 poppler-utils（pdfinfo、pdftotext、pdftoppm、pdffonts、pdfimages、pdfdetach）。Ghostscript (gs) 為選用，僅用於改善壓縮效果。
務必透過 Node 執行命令，可從任何工作目錄執行：
node <skill-dir>/cli/pdf.cjs <command> [options] --json
每次工作階段第一次使用時，請先驗證環境：
node <skill-dir>/cli/pdf.cjs doctor --json
如果缺少必要的二進位檔，請安裝它們（Debian/Ubuntu 使用 apt-get install qpdf poppler-utils，macOS 使用 brew install qpdf poppler），或告知使用者缺少什麼。請勿靜默地以其他工具替代。
黃金工作流程（每次處理 PDF 工作時請遵循）
- 檢視 — 修改前務必檢視：
pdf inspect <file> --json。讀取pages、encrypted、signed、formType、pageTypes.scanned和warnings。 - 分類 — 決定工作類型（結構性 / 表單 / 範本 / 疊加 / 安全性 / 壓縮 / 擷取 / 渲染）。對於不明確的意圖，使用
pdf plan <file> --intent "..."取得結構化計劃與阻礙清單。 - 檢查限制 — 加密需要密碼；已簽署的文件會被編輯動作失效（請警告使用者）；不支援 XFA 表單；掃描頁面沒有文字圖層（擷取與基於搜尋的操作會靜默地回傳空結果 — 請明確告知）。
- 執行 — 執行操作命令。
- 驗證 — 對每個修改過的檔案執行
pdf validate <output> --json。對於視覺敏感的工作（疊加、浮水印、範本），也請使用pdf to-image渲染並檢視結果。 - 回傳 — 交回輸出檔案、摘要、警告以及驗證結果。
讀取結果
每個命令都會回傳結構化結果（使用 --json）：
{ "ok": true, "operation": "compress", "output": "...", "summary": "...",
"warnings": ["..."], "data": { }, "manifest": { "operations": [], "engine": [] } }
請將 warnings 視為第一級輸出：將其呈現給使用者。當 ok 為 false 時，結束代碼為 1。
命令對應表
| 意圖 | 命令 |
|---|---|
| 檢視文件 | inspect |
| 從自然語言規劃 | plan --intent "..." |
| 合併 / 分割 / 頁面手術 | merge、split、extract-pages、delete-pages、reorder、rotate |
| 處理真實表單欄位 | form inspect、form fill、form clear、form flatten |
| 填寫靜態（不可填寫）版面 | template inspect、template fill、template batch |
| 在座標處加入內容 | add-text、add-image、add-shape |
| 連續文字與編號 | header、footer、page-number |
| 浮水印或戳章 | watermark、stamp |
| 保護 / 解除保護 | encrypt、decrypt、permissions、sanitize |
| 縮小檔案大小 | compress |
| 取得文字或資產 | extract、extract-images、extract-attachments |
| 將頁面渲染為圖片 | to-image |
| 驗證輸出 | validate |
完整的旗標與範例：請參閱 references/commands.md。範本 JSON schema 與批次產生：請參閱 references/templates.md。一個立即可試的範例位於 assets/examples/。
避免錯誤工具的判斷規則
- 可填寫表單 vs. 靜態表單：如果
inspect回報formType: "acroform"，請使用pdf form fill。如果formType: "none"但頁面視覺上看起來像表單，那它就是靜態版面 — 請使用帶有座標對應的pdf template fill。絕對不要對靜態 PDF 使用form fill。 - 掃描頁面：當
pageTypes.scanned > 0時，文字擷取、文字搜尋和表單偵測並不適用於那些頁面。請說明需要 OCR；OCR 引擎在產品藍圖中，不在本次建置中。 - 可重複的放置：對於一次性插入，使用
add-text/add-image並從to-image渲染推斷座標。對於任何可重複的動作，請建立範本 JSON 並重複使用。 - 書籤：結構性操作不會保留大綱/書籤；當來源檔案有書籤時請發出警告。
安全規則（不可協商）
- 絕對不要嘗試破解密碼或繞過權限。
decrypt需要有效的密碼；失敗時請回報並停止。 - 偏好透過環境變數傳遞機密：
--password-env VAR或PDF_PASSWORD。絕對不要在日誌、摘要或清單中印出密碼值。 - 修改已簽署的 PDF 會使其簽章失效。在執行前請警告使用者，並將警告包含在結果中。
- 彩色矩形不等於紅利。 疊加（浮水印、白化、形狀）會讓底層文字仍可被擷取。真正的紅利是藍圖中的功能；如果被要求紅利，請直接告知，不要用黑色方塊假裝。
- 在副本上操作。永遠不要就地修改使用者的原始檔案 — 一律寫入新的
--output路徑。
座標與字型
- CLI 疊加命令（
add-text、add-image、add-shape）使用 PDF 點，左下角原點。 - 範本 JSON 使用 公釐，左上角原點（設計師慣例）。
- 內建字型（helvetica、times、courier，加上粗體/斜體）涵蓋拉丁文字以及常見標點符號。對於中日韓（CJK）或其他語言文字，請傳入
--font-file搭配 TTF/OTF 字型 — 否則命令會以FONT_REQUIRED快速失敗，而非產生亂碼文字。
已知限制（藍圖範圍，刻意設計）
MVP 後續功能 — 當請求需要其中一項時，請明確指出差距，並提供最接近的支援替代方案：
- OCR — 掃描頁面無法被搜尋或文字擷取。
- 真正內容紅利 — 請參閱安全規則；不要用疊加假裝。
- 表格/基於 schema 的擷取 —
extract回傳文字、Markdown 或逐頁 JSON；它不會將表格重建為 CSV，也不會根據 JSON schema 擷取。請提供 Markdown 文字擷取，並註明表格結構為近似值。 - 註解 — 不支援螢光筆、便利貼或評論（建立或擷取）。
- 圖片 → PDF / 其他格式 → PDF — 不支援
from-image或文件轉換；僅接受 PDF 輸入。 - 頁面插入/複製 — 沒有插入空白頁、插入 PDF 到 PDF 或複製頁面的命令（替代方案：
extract-pages+merge）。 - 圖片/標誌浮水印 —
watermark僅限文字；如需標誌，請在每頁使用add-image。 - 連結註解 —
add-shape/add-text會繪製內容，但無法建立可點擊的連結。 - PDF 比較 — 沒有
compare命令。 - 無 Ghostscript 的圖片降取樣 — 壓縮會退回到無失真模式。