在 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。