在 NextPDF Connect 工作流程中處理錯誤

概覽

建立具備韌性的 Connect 工作流程。驗證每一筆工具結果，清除失敗的工作階段，並以全新狀態重試。失敗的工具會回傳結構化錯誤結果；那是一般回應，並非傳輸失敗。PSR-18 也做出相同區分：即使狀態表示錯誤，仍會回傳一筆回應（PSR-18 §3）。

安裝

composer require nextpdf/server

綁定傳輸。本範例使用 create_pdf、add_text 與 output_pdf，這些全都屬於 Core。

概念總覽

失敗的工具呼叫會回傳一筆錯誤結果。該結果帶有錯誤旗標與人類可讀的訊息，並在適用時附上代碼。成功結果不會有錯誤旗標，且會帶有該工具的一般輸出。不論是哪一種情況，傳輸都已送出請求並收到回應（PSR-18 §p2）。

防禦性迴圈很短：送出呼叫並讀取結果。如果是錯誤，就記錄、分類、套用復原策略，且不要帶著過期狀態繼續。否則，擷取你需要的欄位並繼續。

API 介面

工具	角色	風險層級
`create_pdf`	開啟工作階段	安全
`add_text`	寫入文字	謹慎
`output_pdf`	轉譯並回傳 PDF	需要核可/審查（base64）

工具目錄是工具記錄的準據目錄。可用的工具取決於已安裝的層級。

程式碼範例 — 快速開始

執行順利路徑（create_pdf → add_text → output_pdf）並檢查每一筆結果。接著，刻意在 add_text 中重用一個已被銷毀的 document_id，以觸發工作階段錯誤。透過建立新的工作階段並重播內容來復原。

程式碼範例 — 正式環境

依類別分類錯誤，並據此回應：

輸入驗證 — 具決定性。修正引數並重試相同的呼叫。範例：空白文字、無效的對齊、非正值的大小、未知的頁面大小、未知的字型家族。
工作階段 — 該 document_id 已不存在。建立新的工作階段並重播所有內容。
系統 — 伺服器資源限制，例如工作階段上限。退避後重試。
核可 — 將 output_pdf 寫入檔案時，可能會暫停以等待人工核可。這是工作流程暫停，並非失敗。轉達挑戰並等待，然後帶著確認權杖重新呼叫。

切勿假設成功；工作階段錯誤後切勿重用 document_id；在每一個內容步驟都成功之前，切勿送出 output_pdf。

邊界情況與陷阱

核可並非錯誤。 HITL 挑戰是一種暫停。不要在緊密迴圈中重試。將它轉達給人員。
伺服器重新啟動。 所有記憶體中的工作階段都會被清除，且先前的每一個 document_id 都會失效。
部分工作流程。 如果 add_text 在文件中途失敗，工作階段可能會不一致。安全的復原方式是建立全新的工作階段，而非部分修復。

效能

可忽略。本範例著重於控制流程，而非轉譯。對於任何產生的輸出，其設定檔皆為 structural。

安全注意事項

錯誤訊息是供呼叫端代理程式與操作者使用。不要將原始伺服器錯誤文字逐字回傳給不受信任的終端使用者。請改為顯示經分類且已清理的訊息。

符合性

陳述	規範	條款	reference_id
無論結果為何，傳輸都會回傳一筆回應。	PSR-18	§p2
即使在錯誤狀態下，仍會回傳一筆回應。	PSR-18	§3

商業情境

不適用 — 所有工具皆屬於 Core。

傳輸可用性

傳輸	可用	附註
MCP（stdio）	是	錯誤會以帶有錯誤旗標的工具結果形式傳回。
REST	是	非 2xx 狀態會帶有相同且經分類的錯誤主體。
gRPC	是	一個狀態碼加上一則錯誤結果訊息。

在每一種傳輸中，工具層級的錯誤都屬於需要檢查的一般回應，而非被丟棄的呼叫（PSR-18 §3）。

HITL 風險層級

create_pdf 為安全，add_text 為謹慎，而 output_pdf 為需要核可；在 base64 模式下降級為審查。待處理的檔案寫入會以核可挑戰的形式呈現，錯誤迴圈必須將其視為暫停，而非失敗（HITL 風險層級）。

確認關卡 JSON 封套

待處理的核可會回傳：

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

將 _confirmation_token 設為該權杖後，重新呼叫同一個工具，它便會回傳 { "allowed": true }。關於完整流程，請參閱 output-approval。