Диагностика окружения в NextPDF Connect

Кратко

Перед реальной работой убедитесь, что сервер NextPDF Connect исправен и поддерживает возможности, необходимые вашему рабочему процессу. Используйте эту проверку как первый шаг в любом агентном конвейере. Согласно реестру инструментов сервера, доступны и проверены diagnostic.doctor, diagnostic.capabilities и diagnostic.verify. Реестр публикует их под протокольными именами с точками; также есть связанный инструмент diagnostic.inspect. Все они относятся к инструментам Core.

Установка

composer require nextpdf/server

Привяжите транспорт. veraPDF нужен только для необязательной проверки соответствия. Для структурной проверки внешний инструмент не требуется.

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

diagnostic.doctor возвращает базовый отчёт о состоянии окружения: версию PHP, загруженные расширения, версию сервера, активный уровень и предупреждения. Рассматривайте status как контрольную точку. Продолжайте при ok, изучайте warnings при warning и останавливайтесь при error.
diagnostic.capabilities перечисляет зарегистрированные возможности, их уровень и состояние во время выполнения (available, unavailable, degraded). Число возможностей зависит от среды выполнения и уровня, поэтому не фиксируйте их количество в коде. Проверяйте каждую возможность, которая нужна вашему рабочему процессу.
diagnostic.verify проверяет структурную целостность: заголовок PDF, маркер EOF и таблицу перекрёстных ссылок. Речь о структуре документа, достигаемой через дерево страниц (ISO 32000-2 §7.5). С параметром compliance_flavour он также запускает veraPDF.

Результат диагностики — обычный ответ в любом транспорте (PHP Standard Recommendation 18, PSR-18 §p2).

Поверхность API

Инструмент	Роль	Уровень риска
`diagnostic.doctor`	Отчёт о работоспособности окружения	Безопасный
`diagnostic.capabilities`	Перечень возможностей с состоянием	Безопасный
`diagnostic.verify`	Структурная проверка / проверка соответствия	Безопасный
`create_pdf`, `add_text`, `output_pdf`	Дымовая проверка документа	как описано отдельно

Эти имена — протокольные имена реестра. Каталог инструментов является эталонным каталогом. Установленный уровень определяет, какие инструменты и возможности доступны, поэтому никогда не задавайте фиксированное количество инструментов или возможностей.

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

diagnostic.doctor (без аргументов) → проверьте status.
diagnostic.capabilities (без аргументов) → убедитесь, что каждая нужная возможность имеет состояние available.
create_pdf, затем add_text → минимальный проверочный документ.
diagnostic.verify с document_id → структурные проверки.
При необходимости diagnostic.verify с compliance_flavour: "4" → veraPDF.
output_pdf (base64) → удалите проверочную сессию.

Пример кода — продакшен

Сделайте запуск конвейера зависимым от значения diagnostic.doctorstatus. Сопоставьте каждую зависимость рабочего процесса с конкретным идентификатором возможности и проверяйте состояние available перед запуском зависимых шагов. Рассматривайте degraded как риск для качества, требующий выборочной проверки. Всегда выполняйте структурную проверку через diagnostic.verify. Запускайте вариант с проверкой соответствия только тогда, когда она нужна. Если veraPDF отсутствует, возвращается явный результат “не найдено”, а не дефект сервера.

Граничные случаи и подводные камни

veraPDF отсутствует. Вызов проверки соответствия возвращает явный результат “не найдено”. Структурные проверки по-прежнему работают. Если вам нужна проверка соответствия, установите veraPDF и добавьте его в PATH процесса сервера.
Тайм-аут veraPDF. Большие документы могут не уложиться в тайм-аут проверки. Уменьшите размер документа или увеличьте тайм-аут в конфигурации сервера.
Возможность в состоянии degraded. Зависимость доступна лишь частично, поэтому качество вывода может снизиться. Проверьте журналы сервера, чтобы понять, какой резервный механизм используется.
Doctor возвращает error. Критическое требование не выполнено. Не продолжайте.

Производительность

Структурная проверка выполняется быстро. В режиме проверки соответствия запускается veraPDF, и выполнение ограничено тайм-аутом проверки. Увеличенный бюджет учитывает этот подпроцесс.

Замечания по безопасности

Вывод диагностики раскрывает сведения об окружении: версию PHP, расширения и уровень. Считайте, что он предназначен только для оператора, и не показывайте его недоверенным вызывающим сторонам.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Результат диагностики — это обычный ответ транспорта.	PSR-18	§p2
Структурная целостность относится к структуре, привязанной к дереву страниц.	ISO 32000-2	§7.5

Вариант с проверкой соответствия запускает veraPDF и сообщает его вердикт. NextPDF сам по себе не заявляет соответствие. Вердикт выносит валидатор.

Коммерческий контекст

Неприменимо — все инструменты диагностики относятся к Core.

Доступность по транспортам

Транспорт	Доступно	Примечания
MCP (через stdio)	Да	Результаты диагностики — это результаты инструментов.
REST	Да	Эндпоинты проверки работоспособности сопоставлены с этими инструментами.
gRPC	Да	Унарный вызов; результат содержит те же поля состояния.

Уровень риска HITL

Все три инструмента диагностики безопасны: только читают данные и не дают побочных эффектов. Они никогда не задействуют шлюз подтверждения. Проверочный output_pdf работает в режиме base64 (Review, без шлюза).

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

Диагностика никогда не задействует шлюз.

{ "allowed": true }