使用 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	打开一个文档会话	Safe
add_text	向文档中写入文本	Caution
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，服务器会以 base64 形式返回该 PDF 并销毁会话。

下面是一个最简的 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	是	每个工具是一次一元调用。

工具结果在不同传输之间是相同的；只有封帧方式不同。非成功结果仍然是一个正常响应，而非传输失败（PSR-18 §p2）。

HITL 风险层级

服务器会将每次工具调用置于一个人在回路（HITL）风险阶梯上：Safe（0）→ Caution（1）→ Review（2）→ Approval Required（3）。create_pdf 是 Safe，add_text 是 Caution。output_pdf 是 Approval Required，但在 base64 模式（无 file_path）下会降为 Review，并且无需人工确认即可运行。写入文件会使它保持在 Approval Required —— 参见 output-approval 以及 HITL 风险层级参考。

确认关卡 JSON 信封

本配方保持在 base64 模式，因此确认关卡会返回允许信封：

{ "allowed": true }

质询信封（allowed: false，包含一个 challenge 字符串和一个一次性 token）记录在 output-approval 中。

另请参阅

• 多页文档
• 图像嵌入
• 工具目录
• HITL 风险层级