Документация Docs/ru/contributing/decisions/0003-manifest-backed-ai-documentation-delivery.md

ADR-0003: доставка документации для ИИ на основе манифеста

Статус: принято
Дата: 2026-07-15
Изменено: 2026-08-01 для локализованной доставки и владения детерминированной оценкой
Владельцы: документация, инструменты

Контекст

Документация FOnline должна служить самостоятельным источником для разработчиков игр и ИИ-систем, не создавая отдельных противоречащих друг другу корпусов. Репозиторий уже содержит канонический Markdown, сгенерированный JSON контрактов, манифест документов и исходников и маршрут GitHub Pages/Jekyll по адресу https://fonline.ru.

ИИ-клиентам всё равно требуются три поверхности обнаружения, которых не предоставляет обычная навигация по страницам:

краткая карта полезных страниц и машиночитаемых справочников;
ограниченный по размеру текстовый пакет для систем, которые не могут обойти сайт или репозиторий;
публичный каталог документов со стабильными идентификаторами, canonical/source URL, владением, provenance и хешами содержимого.

Ручное сопровождение этих поверхностей продублировало бы индекс документации и расходилось бы с ним при перемещении страниц, расширении сгенерированных справочников или появлении англо-русского зеркала.

Решение

Docs/documentation-manifest.json является единственным источником состава доставки для ИИ, стабильных идентификаторов документов, аудиторий, состояния, владения, политики локалей, URL публикации и происхождения исходников.
BuildTools/docs_ai_delivery.py детерминированно генерирует три статических файла в корне:
- llms.txt: маршрут публичных актуальных страниц, сгруппированных по виду Diataxis, с явно упорядоченным начальным разделом и ссылками на чистый Markdown, закреплёнными на source ref;
- llms-full.txt: ограниченный по размеру context bundle публичного актуального Markdown;
- docs-manifest.json: публичную машиночитаемую проекцию исходного манифеста.
llms-full.txt включает полные авторские публичные актуальные документы и index pages сгенерированных справочников. Сгенерированные detail pages исключаются, поскольку их канонические JSON-модели точнее. Проверенный список exclude_document_ids может исключить избыточную routing/index page, сохранив её в llms.txt, поиске, сайте для людей и docs-manifest.json; стартовые и неизвестные или неактуальные IDs исключать нельзя.
Лимит полного контекста объявляется в исходном манифесте и проверяется до записи результата. Превышение лимита завершает проверку ошибкой; документ никогда не обрезается молча, а лимит не повышается без review. Текущий проверенный лимит равен 2 MiB + 64 KiB (2 162 688 байт). После новых руководств по синхронизации, поиску пути и отображению полный пакет достиг 2 097 153 байт; прибавка 64 KiB сохранила целые актуальные страницы без исключения ещё одного владельца, жёсткий лимит и fail-closed проверку. Он был повышен с 1,5 MiB после того, как полный пакет, привязанный к исходникам, достиг 1 571 968 байт и обязательный runbook резервного копирования и восстановления перестал помещаться. Review сохранил включение документов целиком и выделил ограниченный запас роста вместо исключения ещё одного актуального владельца. Текущая политика исключает избыточную routing page tools после появления отдельных владеющих руководств по Mapper, viewer и particles. Она также исключает ScriptMethodsMap.md после того, как сгенерированные PUBLIC_API.md, GeneratedApiAndMetadata.md и native API index стали сопровождаемыми маршрутами контрактов и задач. BuildTools/README.md исключён после появления сгенерированных справочников CLI, helper и package, а также сопровождаемых маршрутов Docs/en/how-to/build/index.md, Docs/en/reference/cmake-and-buildtools/pipeline.md и Docs/en/how-to/release/packaging.md. Все исключённые страницы остаются доступными через llms.txt, поиск и публичный манифест.
Публичный манифест включает каждый публичный документ, в том числе видимые placeholder routes, чтобы клиенты могли отличить актуальный контракт от маршрута миграции. Внутренние планы и отчёты проверки исключаются.
Хеши документов используют нормализованное содержимое UTF-8/LF. Результаты не содержат timestamp или commit hash конкретного checkout, поэтому Windows, Linux, локальные проверки и CI создают побайтно одинаковые файлы.
Каждая запись публичного манифеста предоставляет canonical HTML URL и закреплённые на source ref markdown_url и raw_url на статическом endpoint исходного Markdown GitHub. llms.txt выбирает чистый Markdown URL как машинный маршрут и сохраняет canonical HTML как дополнительный маршрут для людей.
Опубликованный HTML и генерируемые endpoint используют существующий маршрут GitHub Pages/Jekyll. Артефакты являются обычным текстом или JSON, копируемым Jekyll; отдельный клиентский renderer, API service или второй сайт документации не вводятся.
Docs/ai-evaluation.json и его детерминированный сгенерированный отчёт измеряют актуальность retrieval и source evidence, не заявляя корректность ответов модели. Запуски семейств моделей следуют отдельно проверенному протоколу в Docs/en/contributing/documentation/ai-evaluation.md.
Английский остаётся каноническим, а проверенные русские записи сохраняют те же стабильные идентификаторы с вариантами, квалифицированными локалью, и metadata актуальности перевода. Доставка для ИИ публикует только актуальные записи локалей и никогда не выдаёт отсутствующее или устаревшее зеркало за актуальное.
Сгенерированные файлы являются поверхностями обнаружения и передачи, а не новыми нормативными владельцами. Исходный код и тесты движка, канонический Markdown и сгенерированные модели контрактов сохраняют приоритет, объявленный исходным манифестом.
Фокусные тесты, самостоятельная проверка и GitHub Actions проверяют схему, фильтры, URL, хеши, детерминированный результат, лимит размера, подключение workflow и актуальность.

Последствия

Положительные

Люди и ИИ-системы начинают навигацию из одной проверенной модели владения.
fonline.ru/llms.txt, fonline.ru/llms-full.txt и fonline.ru/docs-manifest.json остаются полезными без JavaScript или репозитория подключающей игры.
Retrieval-системы могут по хешу содержимого отклонять устаревшие кэшированные страницы и различать актуальные страницы, placeholders, сгенерированные справочники и provenance исходников.
Retrieval-системы получают Markdown, закреплённый на версии, без разбора отрендеренного HTML, а люди сохраняют canonical routes fonline.ru.
Большие сгенерированные реестры API остаются доступными как JSON, не занимая ограниченный контекст с прозой.
Исключённая из ограниченного пакета страница остаётся полноценным содержимым для людей, поиска и ИИ и явно называется в политике публичного манифеста.

Издержки

Каждая новая публичная Markdown-страница должна иметь полные metadata манифеста до включения в доставку для ИИ.
Контекстный лимит 2 MiB со временем может потребовать ещё одного проверенного повышения, новой политики пакетов или нескольких пакетов под отдельные задачи.
URL rolling master описывают текущую ревизию документации, а не стабильный выпуск движка; документация с тегами и версиями остаётся отдельной задачей политики выпусков.

Отклонённые варианты

Ручной llms.txt: отклонён, поскольку дублировал бы навигацию и владение.
Одна неограниченная конкатенация всех сгенерированных страниц: отклонена, поскольку уже превысила бы два мегабайта и смешала бы читаемое руководство с машинными реестрами.
Runtime crawling или server API: отклонены, поскольку добавляют границы доступности, развёртывания и безопасности к статической документации.
Сгенерированный HTML или отдельное дерево документации для ИИ: отклонены, поскольку Markdown и JSON, привязанный к исходникам, уже являются каноническими переносимыми форматами.
Молчаливое обрезание по лимиту: отклонено, поскольку может разрезать контракт внутри документа и сделать хеши содержимого или цитаты вводящими в заблуждение.

Проверка

python BuildTools/tests/test_docs_ai_delivery.py
python BuildTools/docs_ai_delivery.py --check
python BuildTools/tests/test_docs_validate.py
python BuildTools/docs_validate.py
совместимый с GitHub Pages рендеринг в существующем задании Build documentation site