透過 NextPDF Connect 進行人工介入式檔案輸出

概覽

人工介入（HITL）確認閘門可避免非預期的檔案系統寫入。當以 output_pdf 搭配 file_path 呼叫時，閘門會攔截該呼叫並回傳一次性挑戰碼，不會寫入檔案。經人類核准後，代理人會攜帶權杖重新呼叫，屆時檔案才會寫入。Base64 輸出（不含 file_path）不會經過閘門。

安裝

composer require nextpdf/server

綁定傳輸層。依預設，output_pdf 帶有「需要核准」風險等級。

概念總覽

閘門會評估實際生效的風險等級，也就是套用任何組態或呼叫者身分覆寫後，最終採用的等級。對於「需要核准」的工具：

• base64 模式 — output_pdf 不含 file_path 時，會降級為「審查」，且無須確認即可放行。不會產生任何檔案系統副作用。
• file 模式 — output_pdf 搭配 file_path 時，會維持「需要核准」。閘門會儲存一個綁定該工具名稱的一次性權杖，並回傳一份挑戰碼。若目標檔案已存在，挑戰碼文字會包含覆寫警告。權杖會在固定時間窗後過期。

在每一種傳輸層中，閘門結果都是正常回應。待核准代表工作流程暫停，而非傳輸失敗（PSR-18 §3；PSR-18 §p2）。

API 介面

工具	角色	風險等級
create_pdf	開啟工作階段	安全
set_font, add_text	建構內容	謹慎
output_pdf（base64）	內嵌回傳；不經閘門	審查
output_pdf（file）	寫入磁碟；會經過閘門	需要核准

工具目錄列出正式記錄的目錄；可用工具則取決於所安裝的層級。風險階梯與閘門定義於 HITL 風險等級參考。

程式碼範例 — 快速上手

1. create_pdf → 以 set_font/add_text 建構內容。
2. output_pdf 搭配 file_path → 閘門回傳一份挑戰碼信封（檔案不會被寫入）。
3. 將挑戰碼轉達給人類。
4. 核准後，以相同引數重新呼叫 output_pdf，並將 _confirmation_token 設為挑戰碼附帶的權杖 → 檔案會被寫入，且工作階段會被銷毀。

程式碼範例 — 正式環境

• 務必將挑戰碼視為一次暫停點。不要在迴圈中重試，也不要捏造權杖。
• 權杖為一次性，且綁定於工具名稱。為 output_pdf 核發的權杖無法授權另一個工具。
• 若人類拒絕，請勿重新呼叫。若要在不寫入檔案的情況下取回位元組，請改以 base64 模式呼叫 output_pdf。這需要工作階段仍然存在；因此若你預期可能需要這麼做，請在會經過閘門的嘗試中使用 destroy: false。
• 若權杖在核准前過期，閘門會核發一份新的挑戰碼。請轉達這份新的挑戰碼。

邊界情況與陷阱

• 從未提供權杖。 該操作會維持待核准狀態。人類必須核准，接著轉達權杖並重新呼叫。
• 權杖過期。 會核發一份新的挑戰碼。請重新轉達它。
• 錯誤的工具。 權杖綁定於工具。拿去重用於不同工具會失敗，並會核發一份新的挑戰碼。
• 非絕對路徑。 在進入閘門前，就會因路徑無效而被拒絕。
• 無寫入權限/磁碟已滿。 這屬於核准後的檔案寫入失敗。請明確呈現該失敗。不要盲目重試。
• 重新呼叫前工作階段已被銷毀。 若先前某次 output_pdf 使用了 destroy: true，工作階段就已消失。當你預期會有核准往返時，請使用 destroy: false。

效能

閘門會增加一次權杖儲存區查詢，以及一次人工核准往返。整體耗時主要取決於人類，而非伺服器。設定檔為 structural。

安全注意事項

閘門是代理人與伺服器檔案系統之間的邊界。它存在的原因是：檔案寫入是一種不可逆的副作用，應由人類授權。權杖為一次性、綁定於工具，且有時效限制。系統刻意不將引數雜湊進權杖，因為用戶端可能以不同的鍵順序重新序列化 JSON。因此權杖綁定的是工具 + nonce + TTL，而不是逐一比對引數。不要記錄這個權杖。請將其視為一次性密鑰。

符規性

陳述	規範	條款	reference_id
待核准屬於正常回應，而非失敗。	PSR-18	§3
無論結果為何，傳輸層都會回傳一個回應。	PSR-18	§p2

本食譜描述的是閘門機制。它並未主張閘門會讓任何操作變得「安全」。閘門的作用，是讓副作用改由人類授權。

商業背景

不適用 — 閘門與 output_pdf 皆屬於 Core。

傳輸層可用性

傳輸層	是否可用	備註
MCP (stdio)	是	挑戰碼會作為工具結果呈現給主機，供人類確認。
REST	是	挑戰碼會在回應內文中回傳；攜帶權杖重新呼叫。
gRPC	是	單向呼叫；挑戰碼就是回應訊息；攜帶權杖重新呼叫。

HITL 風險等級

風險階梯為「安全（0）→ 謹慎（1）→ 審查（2）→ 需要核准（3）」。只有「需要核准」的工具才需要人工確認。output_pdf 屬於「需要核准」。base64 模式會將其降級為「審查」並略過閘門。file 模式會維持「需要核准」並經過閘門。正式的風險階梯與政策解析請見 HITL 風險等級參考。

確認閘門 JSON 信封

閘門結果正好有兩種形式，由伺服器的確認閘門揭露：

已放行（安全/謹慎/審查，或消耗了一個有效權杖）：

{ "allowed": true }

挑戰（需要核准但未附有效權杖）：

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

當目標檔案已存在時，challenge 文字也會包含一行覆寫警告。將 _confirmation_token 設為 token 值，並重新呼叫同一個工具，會回傳 { "allowed": true }，操作隨即進行。權杖為一次性，並在挑戰碼所述的時間窗後過期。

另見

• Hello world
• 錯誤處理
• HITL 風險等級
• 工具目錄