Вывод файлов через NextPDF Connect с участием человека в цикле

Краткий обзор

Шлюз подтверждения с участием человека в цикле (HITL) помогает предотвратить непреднамеренную запись в файловую систему. Когда вы вызываете output_pdf с file_path, шлюз приостанавливает вызов и вместо записи файла возвращает одноразовый запрос на подтверждение. Человек одобряет запрос, агент снова вызывает метод с токеном, и только после этого файл записывается. Вывод в формате base64 (без file_path) не проходит через шлюз.

Установка

composer require nextpdf/server

Привяжите транспорт. По умолчанию output_pdf использует уровень риска Approval Required.

Концептуальный обзор

Шлюз оценивает действующий уровень риска: тот, который получается после любых переопределений через конфигурацию или идентичность вызывающей стороны. Для инструмента уровня Approval Required:

режим base64 — output_pdf без file_path понижается до уровня Review и разрешается без подтверждения. Он не вызывает побочных эффектов в файловой системе.
режим файла — output_pdf с file_path остаётся на уровне Approval Required. Шлюз сохраняет одноразовый токен, привязанный к имени инструмента, и возвращает запрос на подтверждение. Если целевой файл уже существует, текст запроса включает предупреждение о перезаписи. Срок действия токена истекает через фиксированное окно времени.

Во всех транспортах результат работы шлюза — обычный ответ. Ожидание одобрения — это пауза в рабочем процессе, а не сбой транспорта (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

Состав API

Инструмент	Роль	Уровень риска
`create_pdf`	Открытие сеанса	Safe (безопасный)
`set_font`, `add_text`	Формирование содержимого	Caution (осторожность)
`output_pdf` (base64, строка)	Прямой возврат; без шлюза	Review (проверка)
`output_pdf` (файл)	Запись на диск; через шлюз	Approval Required (требуется одобрение)

Этот каталог инструментов — источник истины; набор доступных инструментов зависит от установленного уровня поставки. В справочнике по уровням риска HITL определены лестница рисков и шлюз.

Пример кода — быстрый старт

create_pdf → сформируйте содержимое с помощью set_font/add_text.
output_pdf с file_path → шлюз возвращает конверт с запросом на подтверждение (файл не записывается).
Передайте запрос на подтверждение человеку.
После одобрения снова вызовите output_pdf с теми же аргументами плюс _confirmation_token, установленным в значение токена из запроса → файл записывается, а сеанс уничтожается.

Пример кода — рабочая среда

Всегда считайте запрос на подтверждение паузой. Не повторяйте попытку в цикле и не пытайтесь подделать токен.
Токен одноразовый и привязан к имени инструмента. Токен, выданный для output_pdf, не может авторизовать другой инструмент.
Если человек отклоняет запрос, не вызывайте метод снова. Чтобы получить байты без записи файла, вместо этого вызовите output_pdf в режиме base64. Для этого сеанс должен ещё существовать, поэтому используйте 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

Лестница рисков такова: Safe (0) → Caution (1) → Review (2) → Approval Required (3). Только инструменты уровня Approval Required требуют подтверждения человеком. output_pdf относится к уровню Approval Required. Режим base64 понижает его до уровня Review и пропускает шлюз. Режим файла сохраняет уровень Approval Required и проводит вызов через шлюз. Каноническая лестница и порядок применения политики приведены в справочнике по уровням риска HITL.

JSON-конверт шлюза подтверждения

Результат работы серверного шлюза подтверждения имеет ровно две формы:

Разрешено (Safe/Caution/Review либо при использовании действительного токена):

{ "allowed": true }

Запрос на подтверждение (Approval Required без действительного токена):

{
  "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 }, и операция продолжается. Токен одноразовый, и срок его действия истекает после окна времени, указанного в запросе на подтверждение.