文件轉換 CLI 指令參考

指令總覽

請先從此表選擇適合工作的指令。所有指令都支援 --json，以輸出機器可讀的結果。

安裝與指令形式

安裝套件時會一併安裝 gordon-doc。可用 gordon-doc --help 或 gordon-doc <command> --help 檢視目前安裝版本接受的選項值。預設輸出簡潔的人類可讀結果；若由其他程式處理輸出，請加入 --json。

python -m pip install gordon-doc-converter
gordon-doc version
gordon-doc convert --help

環境診斷與版本

正式轉換前可先使用 doctor：它會回報偵測到的平台、是否為互動式工作階段，以及各 renderer 的可用性。engines 只列出 renderer 能力，不判定整體健康狀態。version 回傳已安裝套件版本。若沒有可用引擎，doctor 會以 exit code 3 結束。

gordon-doc doctor
gordon-doc engines --json
gordon-doc version --json

轉換單一文件

convert 接受 DOCX、ODT、PDF、HTML 與 Markdown 輸入。未指定 --to 時，DOCX、ODT、HTML、Markdown 會輸出 PDF；PDF 輸入則必須指定 --to。ODT 與 HTML 也可透過語意萃取輸出 Markdown、HTML、YAML 與 JSON，且不需要任何引擎；ODT 的逐頁圖片則會先經 LibreOffice 排版。可重複使用 --to 取得多個 artifact。--output 適用於單一檔案 artifact；省略時服務會在來源旁推導安全的輸出名稱，除非提供 --overwrite，否則不會覆寫既有檔案。DOCX 轉 HTML 時，--engine word-com 在 Windows 上透過 Word COM 排版；省略或改用 --mode server 則使用語意萃取。

gordon-doc convert report.docx --output report.pdf
gordon-doc convert report.docx --to markdown --to html --to yaml --to json
gordon-doc convert report.docx --to html --engine word-com
gordon-doc convert report.pdf --to yaml --to json
gordon-doc convert report.html --to markdown --to yaml --to json
gordon-doc convert report.odt --to docx --engine libreoffice
gordon-doc convert report.odt --to markdown --to yaml --to json
gordon-doc convert report.pdf --to images --dpi 144

轉換政策與輸出選項

--engine word-com、libreoffice 或 gotenberg 會要求使用指定的 DOCX 轉 PDF 引擎；明確指定時絕不 fallback。DOCX 轉 HTML 時，--engine word-com 透過 Word COM 排版；省略或改用 --mode server 則使用語意萃取。--mode 選擇自動政策：desktop、server、container、strict-word 或 strict-libreoffice。修訂模式可用 --revisions final、original 或 markup；註解模式可用 --comments omit、appendix 或 markup，但仍取決於引擎支援。--timeout 單位為秒。HTML 與 Markdown 可用 --orientation portrait 或 landscape 選擇 A4 版面。--gotenberg-url 為本次呼叫提供 Gotenberg base URL。

gordon-doc convert contract.docx --engine word-com --revisions final --comments appendix
gordon-doc convert report.docx --to html --engine word-com
gordon-doc convert report.html --to pdf --orientation landscape
gordon-doc convert report.docx --mode server --gotenberg-url http://renderer:3000

結構化 YAML 與 JSON Artifact

--to yaml 與 --to json 會序列化同一份具版本的語意文件。DOCX、PDF 與 HTML 來源都會產生同一份結構。Schema 1.3 保留接近 Markdown 的標題、段落、清單及表格文字，同時保存有意義的連結、圖片、修訂、註解、來源順序、metadata 與反向 locator。重複使用 --to 可只擷取一次並同時寫出兩種格式。--metadata 接受 none、basic 或 layout；沒有資料的選用值會直接省略，不會輸出 null。--json-lines 會把 JSON artifact 以換行分隔的記錄寫入 <stem>.jsonl 而非 <stem>.json：先是一筆 document 記錄，接著依來源順序輸出每個 block，最後是 asset、annotation 與 warning 記錄；每筆 block 都帶有 section_path，因此逐行資料仍可還原章節階層。此選項適用於 DOCX、PDF 與 HTML 來源，且不影響 Markdown、HTML 與 YAML 產出。--to json 產生文件 artifact；不同用途的 --json 則將 CLI 執行結果寫到 stdout。

gordon-doc convert report.docx --to yaml --to json --metadata basic
gordon-doc convert report.pdf --to yaml --to json --metadata layout
gordon-doc convert report.html --to yaml --to json --metadata basic
gordon-doc convert report.docx --to json --json-lines
gordon-doc convert report.docx --to json --json

反向定位與來源驗證

結構化 artifact 以 source.sha256 識別完全相同的輸入檔，並以 source_anchor.content_sha256 驗證每個正規化 block 或表格儲存格。DOCX anchor 使用 OOXML part 與 element path；Word 有提供時另含原生段落 ID，表格儲存格則在 path 加上 row/cell 索引。PDF anchor 使用從 1 起算的實體頁。PDF 頁內座標目前尚未提供，未來可由 layout provider 擴充。file offset 並非穩定 locator：DOCX 重新壓縮，以及 PDF 最佳化或增量儲存，都可能在可見內容不變時改變 offset。

轉換進度

convert 與 batch 在互動終端會自動顯示階段式進度。進度只寫入 stderr，因此重導向的 stdout 與機器可讀結果不會被污染。--json 會關閉自動進度；可用 --progress 強制顯示，或用 --no-progress 關閉。batch 顯示已完成檔案數／總檔案數，而非虛構的時間百分比。

gordon-doc convert report.docx --to yaml --progress
gordon-doc convert report.docx --to json --no-progress
gordon-doc batch one.docx two.docx --output-dir converted --progress

頁面影像與 HTML 範本

使用 --to images 將 PDF 來源，或由 DOCX 產生的 PDF，轉為頁面影像。--dpi 可設 1 至 600；--image-format 為 png 或 jpeg；--quality 套用於 JPEG；可重複使用 --page（從 1 起算）選擇頁面；--background 設定影像背景色。影像輸出為名為 <stem>.pages 的目錄，內含連號檔案。template 會建立可編輯的 A4 HTML 起始範本；除非提供 --overwrite，否則會保護既有檔案。

gordon-doc convert report.pdf --to images --image-format jpeg --quality 85 --page 1 --page 3
gordon-doc template report.html --orientation landscape

比較 PDF 與批次轉換

compare 會檢查 PDF 結構、字型、大小與渲染後的像素。可設定 --diff-dir 儲存不同頁面的 PNG，並以 --dpi 控制比較的點陣解析度。batch 會依序轉換一或多個 DOCX，並隔離各檔案失敗；其輸出固定為 PDF。--output-dir 將每個產生的 PDF 放進指定目錄。只要任何項目失敗，batch 的 exit code 就會是非零；--json 則保留完整的逐項結果供 CI 報告使用。

gordon-doc compare expected.pdf actual.pdf --diff-dir differences --json
gordon-doc batch one.docx two.docx --output-dir converted --mode server --json

JSON 結果與 Exit Code

所有指令均接受 --json。成功轉換的 payload 包含選用與嘗試過的引擎、artifact 路徑與中繼資料、耗時、實際採用的註解模式、warning 與 fallback 資訊。失敗結果包含穩定的錯誤碼、安全訊息、可得時的引擎名稱與 retryable 旗標。exit code 0 表示成功；2 表示輸入無效或輸出已存在；3 表示引擎／能力不可用；4 表示轉換失敗、逾時或無輸出；5 表示 PDF 驗證失敗。

gordon-doc convert report.docx --json
# PowerShell: stop a script if conversion fails
gordon-doc convert report.docx --output report.pdf
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }