Документация 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:.
Полный пакет не имеет лимита размера в байтах. Генератор выводит каждый выбранный документ целиком и никогда не усекает содержимое. Состав документов, исключения routing pages и правило generated index сохраняются.

Действующие исключения сохраняют своих владельцев-заменителей: 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