在 NextPDF Connect 上執行環境診斷

概覽

開始實際工作前，請先確認 NextPDF Connect 伺服器健康狀態正常，並具備你的工作流程所需能力。這是任何代理式管線建議執行的第一步。這些工具已依伺服器工具登錄重新驗證，分別是 diagnostic.doctor、diagnostic.capabilities 與 diagnostic.verify。登錄會以點分隔的協定名稱公開它們，另有一個相關的 diagnostic.inspect。全部都屬於 Core。

安裝

composer require nextpdf/server

綁定一種傳輸。veraPDF 只在選用的合規驗證步驟中才需要。結構驗證不需要任何外部工具。

概念總覽

diagnostic.doctor 會回傳一份基準健康報告：PHP 版本、已載入的擴充功能、伺服器版本、目前啟用的層級，以及任何警告。請將 status 視為閘門。ok 時繼續，warning 時閱讀 warnings，error 時停止。
diagnostic.capabilities 會列出已註冊的能力，以及各能力的層級與執行階段狀態（available、unavailable、degraded）。能力數量取決於執行階段與層級，因此請勿寫死總數。請逐一檢查工作流程所依賴的每一項能力。
diagnostic.verify 會檢查結構完整性：PDF 標頭、EOF 標記與交叉參照表。目標是透過頁面樹抵達的文件結構（ISO 32000-2 §7.5）。搭配 compliance_flavour 時，它還會呼叫 veraPDF。

診斷結果在每一種傳輸中都屬於正常回應（PSR-18 §p2）。

API 介面

工具	角色	風險層級
`diagnostic.doctor`	環境健康報告	Safe
`diagnostic.capabilities`	能力清單與狀態	Safe
`diagnostic.verify`	結構/合規驗證	Safe
`create_pdf`、`add_text`、`output_pdf`	對文件執行冒煙測試	如其他章節所述

這些名稱是登錄中的協定名稱。工具目錄才是正式的目錄記錄。有哪些工具與能力取決於已安裝的層級，因此切勿斷言固定的工具或能力數量。

程式碼範例 — 快速上手

diagnostic.doctor（無引數）→ 讀取 status。
diagnostic.capabilities（無引數）→ 確認所需的每一項能力都是 available。
create_pdf 然後 add_text → 建立一份最小的冒煙測試文件。
帶 document_id 的 diagnostic.verify → 結構檢查。
選用：以 compliance_flavour: "4" 執行 diagnostic.verify → veraPDF。
output_pdf（base64）→ 銷毀冒煙測試工作階段。

程式碼範例 — 生產環境

以 diagnostic.doctorstatus 作為管線的閘門。將每一項工作流程依賴對應到特定的能力 id，並在執行依賴該能力的步驟之前斷言其為 available。請將 degraded 視為需要抽查的品質風險。一律執行結構性的 diagnostic.verify。僅在符合性重要之處才執行合規變體，並接受 veraPDF 不存在時會回傳明確的 not-found 結果，而非伺服器缺陷。

邊緣案例與陷阱

veraPDF 不存在。 合規呼叫會回傳明確的 not-found 結果。結構檢查仍可運作。若你需要合規驗證，請安裝 veraPDF，並將它放到伺服器處理程序的 PATH 上。
veraPDF 逾時。 大型文件可能會觸發驗證逾時。請縮減文件大小，或在伺服器設定中調高逾時時間。
degraded 能力。 某項依賴僅部分可用，因此輸出品質可能下降。請檢查伺服器日誌，以了解目前使用的後備方案。
Doctor error。 有一項關鍵需求未獲滿足。請勿繼續進行。

效能

結構驗證很快。合規路徑會衍生 veraPDF，並受驗證逾時時間所限。較寬鬆的預算反映了該子處理程序。

安全注意事項

診斷輸出會揭露環境細節：PHP 版本、擴充功能與層級。請將它視為僅供操作人員使用，且不要公開給不受信任的呼叫端。

符合性

陳述	規範	條款	reference_id
診斷結果是正常的傳輸回應。	PSR-18	§p2
結構完整性以頁面樹錨定的結構為目標。	ISO 32000-2	§7.5

合規變體會執行 veraPDF 並回報其裁定。NextPDF 本身並不斷言符合性；裁定由驗證器決定。

商業情境

不適用 — 所有診斷工具都屬於 Core。

傳輸可用性

傳輸	可用	備註
MCP（stdio）	是	診斷結果就是工具結果。
REST	是	健康端點對應到這些工具。
gRPC	是	一元（Unary）呼叫；結果攜帶相同的狀態欄位。

HITL 風險層級

三項診斷工具都屬於 Safe：唯讀、無副作用。它們絕不會觸發確認閘門。冒煙測試的 output_pdf 為 base64 模式（Review，無閘門）。

確認閘門 JSON 封套

診斷絕不設閘門。

{ "allowed": true }