Документация 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 исключать нельзя. Каждый полный документ сохраняет ID, путь исходника и заголовок канонической ссылки URL:; краткие метки сохраняют лимит размера.

Утверждённый лимит размера задаётся в ai_delivery.full_context.max_bytes манифеста документации. Генератор проверяет его до записи. Превышение даёт fail-closed отказ: без обрезания документа или непроверенного повышения. Состав, исключения routing pages и правило generated index сохраняются. Прежние проверенные прибавки сохраняли целиком владеющие руководства:

Дата / ревизия	Байт в полном пакете	Проверенная прибавка и причина
Ранее	1 571 968	Повышение с 1,5 MiB, чтобы поместился обязательный runbook backup/recovery; полные документы вместо ещё одного исключения.
Позднее	2 097 153	+64 KiB для руководств по синхронизации, поиску пути и отображению.
Позднее	2 169 979	+32 KiB для обязательных правил обновления Engine и исчерпывающих миграций.
2026-10-05	2 197 968	+32 KiB для сохранённых пояснений по baking/тестам, миграций и сгенерированных справочников сборки.
2026-10-09, опубликованная версия 20	2 228 855; 112 полных документов	+32 KiB; превышение прежнего лимита на 631 байт. Все актуальные владельцы и обязательная история миграций сохранены.
`e1a3815ff96c7d88f47314984e9d9242e37bc585`	2 282 913	+32 KiB для необязательных компонентов, baking-lock и миграций; превышение прежнего лимита на 21 921 байт. Ёмкость уже объявлена опубликованным манифестом.
2026-10-13, отбор размещений	2 294 456 до этой строки ADR	+32 KiB для итоговых свойств размещения и обязательной миграции версии 38; превышение прежнего лимита на 696 байт. Состав и исключения не меняются.
2026-10-21, владение ресурсами и игровая политика анимаций	2 367 685 до этой строки ADR	+32 KiB до 2 392 064: сохраняются полные руководства владения и миграция версии 58; превышение прежнего лимита на 8 389 байт. Состав и исключения не меняются.

Измерение e1 оставляло 10 847 байт до соответствующей правки документации; перегенерированный результат измеряется заново. Действующие исключения сохраняют своих владельцев-заменителей: tools после отдельных руководств Mapper/viewer/particles; ScriptMethodsMap.md после сгенерированных PUBLIC_API.md, GeneratedApiAndMetadata.md и native API index; BuildTools/README.md после сгенерированных CLI/helper/package references и Docs/en/how-to/build/index.md, Docs/en/reference/cmake-and-buildtools/pipeline.md, Docs/en/how-to/release/packaging.md. Специализированная миграция script-owned-sprite-animations остаётся полной и двуязычной; на неё ссылаются включённые руководства по обновлению Engine и changelog. Все исключённые страницы остаются в 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 манифеста до включения в доставку для ИИ.
Ограниченный бюджет контекста со временем может потребовать ещё одного проверенного повышения, новой политики пакетов или нескольких пакетов под отдельные задачи.
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