使用方式

本頁展示常見命令模式。對於未知 PDF，先做結構化第一遍，檢查頁面 overview，再只在證據需要的地方加入版面、渲染、OCR、搜尋或視覺區域。

建議第一遍

pdfvision document.pdf --json

用它回答：

• 哪些頁面有可用的原生文字？
• 哪些頁面偏視覺、像掃描件或字形損壞？
• 哪些頁面有警告？
• 哪些頁面需要版面重建、OCR 或渲染裁切？

本機 PDF

pdfvision document.pdf

遠端 PDF

pdfvision --remote https://example.com/document.pdf --format json

遠端下載會被快取，並在擷取前驗證是否為 PDF。如果 .pdf URL 回傳 HTML、登入頁或挑戰頁，pdfvision 會在快取前失敗。

--remote 的初始 URL 僅支援 HTTP(S)，並會跟隨重新導向。如果回應本文開頭附近沒有 PDF header，pdfvision 會拒絕該回應。預設限制為 100 MB 的本文上限，以及涵蓋等待回應標頭和傳輸本文的 60 秒截止時間。

只對使用者獨立授權的目標使用 --remote。它驗證回應，但不驗證網路目標，也不會阻擋私有位址或重新導向目標。不要直接傳入不可信 URL；應使用下載元件透過允許清單驗證每個解析 IP 和重新導向節點、固定連線目標，再把本機檔案傳給 pdfvision，或把 pdfvision 的下載程序隔離在網路控制之後。詳見安全與隱私。

遠端快取按 URL 建立。如果一個穩定 URL 的內容會被原地更新，可用 --no-cache 做一次新鮮取得，或用 --clear-cache 刪除快取副本：

pdfvision --remote https://example.com/document.pdf --no-cache --format json

頁碼範圍

pdfvision document.pdf --pages 1-3
pdfvision document.pdf --pages 1,3,5 --format json

頁碼範圍使用從 1 開始的實體頁碼。逗號組合多個選擇器，範圍包含兩端，重複頁會合併到排序後的輸出中。

有效範例：

• 1
• 1-5
• 1,3,5
• 2-4,7

空片段、0、負數、5-3 這樣的降序範圍和格式錯誤的範圍都會直接報錯，而不是猜測使用者意圖。如果選擇器包含超出文件末尾的頁，但至少選中了一個真實頁，pdfvision 會擷取真實頁，並為被跳過的頁發出警告。

渲染頁面

pdfvision document.pdf --render --render-output ./images --format json

使用 --render-scale 控制影像細節：

pdfvision document.pdf --render --render-scale 3

擷取版面與視覺結構

pdfvision document.pdf --layout --image-boxes --vector-boxes --visual-regions --format json

這會加入版面區塊、影像框、向量框、視覺區域與版面警告。

適用於雙欄論文、投影片、財務報告、表格、表單、圖表、圖示，以及任何視覺位置會改變含義的頁面。

只渲染重要區域

pdfvision document.pdf --render-visual-regions --render-output ./regions --format json

當不想渲染整頁，但需要查看圖、表、表單或圖表區域時使用。

搜尋並放大

pdfvision report.pdf --search "revenue" --format json
pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json

當 pdfvision 能定位證據時，搜尋結果會包含 bbox。把該 bbox 傳給 --render-region，即可產生用於視覺驗證的小裁切圖。

當答案必須綁定到可稽核的 PDF 證據時，這個模式很有用：先搜尋術語，選擇匹配頁和 bbox，再渲染最小可用裁切。

掃描頁 OCR

pdfvision scan.pdf --ocr --ocr-lang eng --format json
pdfvision japanese-scan.pdf --ocr --ocr-lang jpn+eng --format json

OCR 結果包含文字、信心分數、語言與單字框。

OCR 會附在原生文字旁邊，不會取代 pages[].text。代理可以先比較原生擷取與 OCR，再決定信任哪個證據。

表單、連結與註解

pdfvision form.pdf --layout --form-fields --annotations --links --format json

當 PDF 包含 widget 值、核取方塊、單選群組、可見評論、連結，或含義依賴頁面位置的表單標籤時使用。

目錄、頁碼標籤與文件功能

pdfvision document.pdf -p 1 --page-labels --outline --viewer --layers --format json

當 PDF viewer 體驗有意義時，使用此指令進行探查，例如檢查不同於實體頁碼的頁碼標籤、書籤、open action、optional content layer 或 viewer preferences。這裡的 -p 1 只限制頁面擷取與輸出，並不保證只載入或解析第 1 頁，也不限制整份文件的執行時間。若未指定，文件功能選項仍會擷取所有頁面。文件層級欄位仍會回傳。頁面層級的 JavaScript actions 只針對選取的頁面回傳；如需檢查，請用相關頁面範圍重新執行 --viewer。

加密 PDF

pdfvision encrypted.pdf --password your-password --format json
printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json

當密碼不應出現在 shell 歷史或程序參數中時，優先使用 --password-stdin。

快取控制

pdfvision document.pdf --no-cache --json
pdfvision --clear-cache

pdfvision 會快取擷取結果、渲染影像、遠端下載和 OCR 資料，讓代理重複讀取同一 PDF 時更快。如果不希望快取擷取結果與遠端 PDF 位元組，請使用 --no-cache；用 --clear-cache 刪除快取資料。

當應用需要把快取放在已知位置時，請將 PDFVISION_CACHE_DIR 設為指向專用目錄的非空絕對路徑。相對路徑、~、檔案系統根目錄、主目錄、工作目錄與共享暫存目錄都會被拒絕：

PDFVISION_CACHE_DIR=/secure/pdfvision-cache pdfvision document.pdf --json

經過擁有者檢查的 .pdfvision-cache-root 標記用來授權遞迴清除。--clear-cache 絕不會採用未標記的自訂根目錄；未設定 PDFVISION_CACHE_DIR override 時，只能在權限強化前後確認舊版形狀後採用目前的歷史預設根目錄。正常使用時，所有未標記根目錄都要經過相同掃描。在 POSIX 上，具有 group/other 寫入權限的未標記根目錄會被拒絕；每個祖先也必須可讀/open、由目前使用者或 root 擁有，且不可寫或有安全的 sticky 保護。移入 quarantine 後，POSIX 清除會比較 st_dev，若不一致就拒絕遞迴刪除；原始路徑此時已經移動，且無法偵測同一 device 的 bind mount。身分檢查只在傳統 POSIX uid/mode/sticky semantics 下增強替換防護；不會檢查 ACL 或網路檔案系統權限，也無法排除最終檢查後由 root 或相同 UID 發起的替換。Windows 只能提供 best-effort 防護。清除不會與執行中的 OCR 協調；請重試被中斷的 OCR。

--no-cache 會跳過擷取快取與遠端 PDF 快取，但未指定 --render-output 的渲染 PNG 會使用獨立的作業系統暫存路徑，明確的渲染輸出仍會寫入指定位置。--ocr 仍會在經過驗證的快取根目錄下持久保存 traineddata 與 worker support files。因此，即使設定了 --no-cache，無效的 PDFVISION_CACHE_DIR 仍會導致 OCR 執行失敗。

對遠端 PDF，--no-cache 也會跳過遠端 PDF 快取，並把新下載的 bytes 直接送入擷取流程。對於私有或限時 URL，這可避免保留下載的 PDF 位元組；當同一 URL 的內容可能變動時，也會強制重新取得。但它不會讓原本未經授權的網路目標變得安全。