使用 NextPDF Connect 建立多頁文件

一覽

使用 NextPDF Connect 建立一份多頁文件。add_page 會附加頁面；該頁面可以繼承文件的預設幾何尺寸，也可以覆寫方向。每次呼叫 add_page 後，游標都會重設到新頁面的左上邊界。你會用到四個工具，全都屬於 Core：create_pdf、add_text、add_page 與 output_pdf。

安裝

composer require nextpdf/server

綁定任一種傳輸：MCP stdio、REST 或 gRPC。不需要任何授權層級。

概念總覽

一份文件就是一棵頁面樹。每個頁面都是透過該樹狀結構存取的節點（ISO 32000-2 §7.7.3）。頁面帶有自己的幾何屬性，包括定義可見區域的 media box（ISO 32000-2 §7.7.3.3）。create_pdf 會自動建立第一個頁面，而 add_page 會在其後附加每個頁面。省略 page_size/orientation 即可繼承文件預設值。設定 orientation: "landscape" 可將 A4 頁面旋轉為 297×210 mm。

API 介面

工具	角色	風險層級
`create_pdf`	開啟工作階段，建立第一個頁面	安全
`add_text`	在游標處寫入文字	注意
`add_page`	附加一個頁面（繼承或覆寫）	注意
`output_pdf`	算繪並回傳 PDF	需要核准/審查（base64）

工具名稱就是登錄表中的協定名稱。工具型錄是正式型錄。你可用的工具取決於已安裝的層級。

程式碼範例 — 快速上手

流程以文字描述如下：

create_pdf（A4 直向、標題、作者）→ document_id。
add_text（標題、大字型、置中），接著 add_text（引言段落、內文字型）。
add_page 只帶 document_id → 繼承 A4 直向。系統會回傳新的 page_number，且游標會重設。
add_text，用於第 2 頁的章節標題與內文。
add_page 並帶 orientation: "landscape" → 一個寬幅 A4 頁面。
add_text，用於寬幅內容。
output_pdf → base64。

程式碼範例 — 正式環境

驗證每個回應。在 add_page 之後，預期內容會從新頁面頂端開始。游標重設是預期行為，並非缺陷。追蹤 position.page（取自 add_text 回應），以偵測內容何時溢流到後續頁面。只呼叫 output_pdf 一次，然後丟棄 document_id。

邊際情況與陷阱

游標重設。 在 add_page 之後，游標位於新頁面的左上邊界。誤以為它會從前一頁延續，是最常見的錯誤。
必填的 document_id。 除了 create_pdf 以外的每個工具都需要 document_id。省略它即為錯誤。
無效的方向。 只有 "portrait" 與 "landscape" 是有效值。
在輸出之後編輯。 在以 destroy: true 呼叫 output_pdf 之後嘗試新增內容會失敗，因為工作階段已不存在。

效能

一份多頁文字文件會維持在頁面預算之內，輸出僅為數 KB。設定檔為 structural：trailer 的 /ID 與時間戳不會在各次執行間保持穩定。

安全性注意事項

base64 模式沒有副作用。檔案輸出受管制（HITL 章節）。document_id 是不透明控制代碼。請勿在多個並行請求之間共用它。

一致性

陳述	規格	條款	reference_id
頁面是透過頁面樹存取的。	ISO 32000-2	§7.7.3
頁面物件定義其自身的幾何屬性。	ISO 32000-2	§7.7.3.3

商業情境

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

傳輸可用性

傳輸	可用	備註
MCP（stdio）	是	每個工具各一次 `tools/call`。
REST	是	每個工具各一次操作。
gRPC	是	每個工具各一次單向呼叫。

HITL 風險層級

create_pdf 屬於安全；add_text 與 add_page 屬於注意；output_pdf 屬於需要核准，在 base64 模式下降級為審查。檔案輸出仍維持需要核准。請參閱 output-approval 與 HITL 風險層級。

確認關卡 JSON 信封

此處的 base64 輸出：

{ "allowed": true }

挑戰表單請見 output-approval。