Соглашения для рецептов Connect

Каждый рецепт в книге рецептов Connect следует одному контракту. Эта страница фиксирует его, чтобы читатель понимал, чего ожидать, а автор — каким требованиям должен соответствовать рецепт. Она носит описательный характер: фиксирует соглашение. Контроль соблюдения реализован в инструментарии репозитория nextpdf/server и в списке переопределений стиля документации, а не здесь.

Авторы пишут рецепты Connect в каталоге docs/public/ репозитория nextpdf/server, а агрегатор переносит их на этот сайт. Приведённые ниже соглашения применяются везде, где размещён рецепт Connect.

1. Вызовы инструментов не зависят от транспорта

Рецепт Connect использует один и тот же вызов инструмента для всех транспортов.

Рецепт показывает вызов инструмента один раз. Один и тот же вызов обращается к инструменту через Model Context Protocol (tools/call), конечную точку инструмента Representational State Transfer (REST) и службу gRPC, поскольку все три используют один и тот же исполнитель инструментов.
Авторитетная схема аргументов инструмента — та, которую работающее развёртывание возвращает из tools/list (MCP) или указывает в дескрипторе службы (gRPC). Образцы аргументов в рецепте показывают форму вызова; это не зафиксированная схема, которую рецепт переопределяет.
Рецепт никогда не заявляет фиксированное общее число инструментов. Эталонный каталог — собственный каталог инструментов сервера, на который ссылается рецепт.

2. Инструменты, зависящие от уровня, указываются явно, а не подразумеваются

Реестр инструментов сервера всегда регистрирует основные инструменты. Затем он с помощью class_exists() проверяет наличие провайдеров Pro и Enterprise и регистрирует их инструменты только тогда, когда nextpdf/premium установлен рядом с сервером.

Рецепт, зависящий от инструмента Pro или Enterprise, явно указывает эту зависимость от уровня и показывает, как подтвердить наличие инструмента в вашем развёртывании вызовом tools/list.
В развёртывании, где инструмент недоступен, вызов возвращает ошибку “неизвестный инструмент”. Рецепт описывает этот результат как предусмотренную границу уровня, а не как деградацию, и никогда не подразумевает, что инструмент с ограничением по уровню доступен всегда.

3. Модель рисков и шлюз подтверждения

Каждый инструмент объявляет один из четырёх уровней риска. Инструмент с самым высоким уровнем, approval_required, не выполняется при первом вызове.

Рецепт для инструмента, который может быть approval_required (по замыслу или из-за переопределения оператором), документирует ConfirmationGate: шлюз возвращает одноразовый токен вызова, привязанный к имени инструмента, одноразовому числу (nonce) и 300-секундному времени жизни (TTL), а не к аргументам. Вызывающая сторона ещё раз вызывает тот же инструмент с arguments._confirmation_token, ровно один раз.
Рецепт указывает, что переопределение конфигурации может только повышать уровень риска инструмента; оно никогда не может понизить уровень риска инструмента, который по замыслу является approval_required. Шлюз ведёт себя одинаково во всех транспортах.

4. Обработка ошибок отделяет транспорт от статуса

В рецепте, который обращается к удалённой службе по протоколу Hypertext Transfer Protocol (HTTP), сбой транспорта и неуспешный статус HTTP — разные случаи. Клиент PSR-18 выбрасывает типизированное клиентское исключение только тогда, когда вообще не может отправить запрос — PSR-18 §4; ответ 4xx или 5xx — обычное возвращаемое значение, которое рецепт проверяет, а не исключение, которое он перехватывает. Готовый к эксплуатации рецепт Connect обрабатывает оба случая отдельно, без пустого блока catch.

5. Граница соответствия и сертификации

Рецепт Connect описывает поддержку стандарта именно как поддержку, но никогда как соответствие или сертификацию.

Движок создаёт результат, предназначенный для соответствия стандарту (PDF/UA-2, PDF/A-4, уровню PAdES); соответствие определяет независимый валидатор по требованиям стандарта, а не программное обеспечение, создающее этот результат — PDF/A-4 §6.7.3.
Оценка готовности — сигнал готовности, а не сертификация. Аттестация не является юридической гарантией. Материал для долгосрочной проверки, присутствующий в документе, — это возможность, содержащаяся в документе, а не гарантия бессрочной действительности подписи. Такая возможность доступна только в Enterprise и отличается от более низких уровней PAdES.
Абсолютные формулировки о соответствии не используются как утверждения о движке. Лексический список блокировок, по которому проверяется рецепт, дословно состоит из токенов “certified”, затем “guaranteed”, затем двухсловной фразы “fully” + “compliant”, затем “tamper-proof”, затем “legally valid”: ни один из них нельзя заявлять как свойство вывода NextPDF, поскольку соответствие определяет независимый валидатор по требованиям стандарта, а не программное обеспечение, создающее этот вывод — PDF/A-4 §6.7.3. Рецепт, который смягчает исходное утверждение, фиксирует это смягчение в расположенном рядом сопроводительном файле с пониженными утверждениями.

6. Шлюз публикации

Каждый рецепт Connect имеет publish: false, пока не пройдёт Writing Gate. По умолчанию публикация запрещена: слияние страницы не публикует её; это делает только явное решение шлюза, записанное во front-matter. Рецепт, нормативные ссылки которого не удалось закрепить из-за реального сбоя движка соответствия, также получает маркер неразрешённой ссылки и остаётся publish: false, пока ссылку не удастся закрепить повторно. Этим маркером управляет протокол отката репозитория на случай сбоя инфраструктуры Retrieval-Augmented Generation (RAG); автор следует ему, а не выдумывает ссылку и не отбрасывает утверждение.

7. Поля происхождения заполняет агрегатор

Автор рецепта Connect не заполняет вручную четыре поля происхождения источника, которыми владеет агрегатор: source_repo, source_ref, source_hash и manifest_hash. Агрегатор заполняет их при переносе рецепта из nextpdf/server, поэтому опубликованная страница фиксирует точную ревизию, на основе которой она создана. Этот индекс и эта страница соглашений созданы непосредственно в документации, поэтому их поля происхождения по замыслу заполнены нулями, а агрегатор их не перезаписывает.

Сводка

В рецепте Connect вызовы инструментов не зависят от транспорта, зависимость от уровня указана явно, модель рисков и шлюз подтверждения задокументированы, обработка ошибок отделяет транспорт от статуса, граница соответствия обозначена честно, а значение publish: false действует по умолчанию до прохождения Writing Gate. Страница, которая соответствует всем шести требованиям, является рецептом; страница, которая соответствует меньшему числу, является черновиком.

См. также

Книга рецептов Connect — карта слагов рецептов и граница уровней и транспортов.
Соглашения по рецептам книги рецептов интеграций — общий для экосистемы контракт рецептов, который этот документ специализирует для Connect.