通过 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. 核准后，使用相同参数，并将 _confirmation_token 设置为挑战码附带的令牌，重新调用 output_pdf → 文件会被写入，且会话会被销毁。

代码范例 — 正式环境

• 务必将挑战码视为一次暂停。不要在循环中重试，也不要伪造令牌。
• 令牌为一次性，且绑定于工具名称。为 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 风险等级
• 工具目录