使用 NextPDF Connect 產生你的第一份 PDF

概覽

本範例會帶你以最短路徑，從一個空白工作階段開始，完成一份由 NextPDF Connect 算繪出的 PDF。你會建立一份單頁 A4 文件，寫入一個標題與一個副標題，然後將檔案以 base64 形式回傳。三個 Core 工具即可完成所有工作：create_pdf、add_text 與 output_pdf。你不需要另外準備字型或影像，也不需要任何授權層級。

Connect 傳輸會將每一次工具呼叫當作一個請求送出，並將工具結果當作回應送回。傳輸層與工具回報的結果無關（PSR-18 §p2）。

安裝

安裝 NextPDF Server 並綁定一種傳輸方式：

composer require nextpdf/server

請依你的主機預期的傳輸方式執行伺服器：透過 stdio 的 Model Context Protocol、REST 或 gRPC。請參閱下方的傳輸可用性。本範例使用的工具全都是 Core 工具。它們隨伺服器一併提供，因此你不需要 Pro 或 Enterprise 套件。

概念總覽

Connect 工作階段是一個伺服器端文件儲存區，以 document_id 作為索引鍵。create_pdf 會開啟一個工作階段，並回傳該 id。之後每一次工具呼叫都會參照該 id。文件一開始會有一個空白頁面。頁面樹是用來抵達每一頁的結構（ISO 32000-2 §7.7.3）。output_pdf 會將工作階段算繪成一份 PDF。預設情況下，它接著會銷毀該工作階段以釋放記憶體。

當你呼叫 add_text 而未明確指定 x 或 y 時，文字會自動定位並流動：它會從目前的游標位置開始，而游標會在每次呼叫後往後移動。

API 介面

伺服器啟動時，工具登錄表會解析出下列工具。這些名稱是登錄表的協定名稱。正式目錄是合併後的工具目錄。實際可用的工具取決於已安裝的層級，但這三個在 Core 中一律都有。

工具	角色	風險層級
create_pdf	開啟一個文件工作階段	安全
add_text	將文字寫入文件	注意
output_pdf	算繪並回傳 PDF	需要核准（檔案模式）/審查（base64）

程式碼範例——快速開始

主機會發出三次工具呼叫。流程如下：

1. 呼叫 create_pdf，並傳入 page_size: "A4"、orientation: "portrait"，以及文件標題與作者。伺服器會回傳一個 document_id。
2. 呼叫 add_text，並傳入該 document_id、標題文字、一個較大的 font_size、width: 0（整個內容寬度），以及 alignment: "center"。
3. 呼叫 output_pdf，並傳入該 document_id。未提供 file_path 時，伺服器會將 PDF 以 base64 形式回傳，並銷毀該工作階段。

以下是一個最小的 create_pdf 引數物件：

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

回應會包含 document_id、頁數，以及頁面幾何資訊。請將該 id 視為一個不透明的值，不要解讀它的含義。

程式碼範例——正式環境

正式環境中的呼叫端會在下一次呼叫之前檢查每一個回應。在 output_pdf 銷毀工作階段之後，呼叫端絕不會再重複使用該 document_id。

1. create_pdf——確認回應中包含一個 document_id。如果伺服器回傳工作階段數量上限錯誤，請釋放未使用的工作階段並重試。
2. add_text（標題）——確認回應會回傳一個 position。
3. add_text（副標題）——使用較小的 font_size；游標會延續到標題下方。
4. output_pdf——讀取 base64 欄位，並將它解碼為位元組。destroyed 旗標會確認工作階段已不存在。

檔案會以行內方式（base64 模式）回傳，因此沒有任何檔案系統副作用，也沒有人工核准關卡——請參閱 HITL 風險層級。

邊界情況與陷阱

• 已銷毀的工作階段。 在 output_pdf 以預設的 destroy: true 執行之後，該 document_id 即不再有效。對它進行任何後續呼叫都會回傳未知文件錯誤。請改為建立一個新的工作階段。
• 未知的頁面尺寸。 伺服器會拒絕它不認得的 page_size，並回傳一個明確的錯誤。請使用有記載的尺寸（A3、A4、A5、A6、Letter、Legal、Tabloid）。
• 空白文字。 空白的 text 會產生一個零寬度的項目，而非錯誤。請在呼叫之前檢查你的輸入。
• 工作階段上限。 記憶體內的儲存區會限制同時執行的工作階段數量。請以 output_pdf 及時釋放工作階段。

效能

純文字的單頁可在頁面預算內順利算繪，且輸出通常為 1–3 KB。本範例在雙重算繪下的可重現性設定檔為 structural。PDF 會帶有一個 trailer /ID 以及每次執行都會改變的時間戳記，因此以結構性（正規化後）結果比較才是誠實的作法。

安全注意事項

base64 路徑沒有任何檔案系統副作用。檔案輸出路徑則確實有一個副作用，而且受到關卡控管——請參閱 HITL 章節。請將回傳的 base64 視為文件內容，而非一個受信任的通道。它本身就是這些工具所產生的位元組。

符合性

陳述	規格	條款	reference_id
傳輸會送出一個請求並接收一個回應，且與結果無關。	PSR-18	§p2
頁面可透過文件頁面樹抵達。	ISO 32000-2	§7.7.3

本範例描述伺服器產生輸出的方式。它並未主張任何設定檔符合性。

商業脈絡

不適用——這三個工具都是 Core。

傳輸可用性

傳輸方式	是否可用	備註
MCP（stdio）	是	工具呼叫對應到 MCP 的 tools/call。
REST	是	每個工具都是一個 REST 操作；其結果即為回應主體。
gRPC	是	每個工具都是一次一元（unary）呼叫。

工具結果在各種傳輸方式之間都相同；只有外層框架不同。非成功的結果仍然是一個正常的回應，而非傳輸失敗（PSR-18 §p2）。

HITL 風險層級

伺服器會將每一次工具呼叫放在一個「人在環路中（HITL）」風險階梯上：安全（0）→ 注意（1）→ 審查（2）→ 需要核准（3）。create_pdf 是安全，而 add_text 是注意。output_pdf 是需要核准，但在 base64 模式（沒有 file_path）下，它會降為審查，並在沒有人工確認的情況下執行。寫入檔案會使它維持在需要核准——請參閱 output-approval 以及 HITL 風險層級參考。

確認關卡 JSON 信封

本範例維持在 base64 模式，因此確認關卡會回傳允許信封：

{ "allowed": true }

挑戰信封（allowed: false，帶有一個 challenge 字串與一個一次性使用的 token）記載於 output-approval。

另請參閱

• 多頁文件
• 影像嵌入
• 工具目錄
• HITL 風險層級