Работа с ИИ
Эта глава описывает машиночитаемые источники Framework и правила работы ИИ с проектом и с самим Framework.
Работа с ИИ
Framework применяется без чтения исходного кода: у каждого правила есть машиночитаемый источник. Поэтому ИИ-помощнику не нужно угадывать — он работает по стандартам, манифестам и журналу изменений закреплённого выпуска. Этот раздел описывает эти источники и правила для ИИ.
Машиночитаемые источники
| Источник | Где | Что даёт |
|---|---|---|
| Индекс документации | /ai.json в корне сайта документации |
Индекс в формате AI First 1.0: все опубликованные страницы и нормативные файлы с адресами, языком и sha256 (устройство — ниже) |
| Страницы документации | в папке каждой страницы: ai.md и ai.json |
Текст страницы и код демонстраций, включая JavaScript |
| Выпуск документации | /ai/framework-lock.json |
Выпуск, который описывает сам сайт документации: идентификатор выпуска в поле runtime.pair_id, ревизии и хеши поставок. Это lock-файл сайта, а не проекта. Пути в runtime.boot (core.css, core.js, smart-base.js) называют читаемые файлы; рядом в поставке лежат сжатые .min, которые подключает рабочая страница (см. Сжатые файлы). package_projections.<имя>.receipt в нём — сокращённая проекция квитанции пакета (поля schema, framework_source), а не формат квитанции package-receipt.json (см. Пакеты компонентов продуктов) |
| Стандарты | /ai/standards/<id>/<версия>/ |
Конверты стандартов, схема Standard Contract, схема манифеста, схема порта, схема описания фрагмента, схема манифеста эффекта, комплект Composition Recipe. Каждый файл лежит под изданной редакцией, например /ai/standards/simai.interface-fragment/1.0.2/standard.json, /ai/standards/simai.effect/1.1.0/standard.json, /ai/standards/interface-fragment-schema/1.2.0/descriptor.schema.json, /ai/standards/effect-schema/1.2.0/effect.schema.json |
| Порты | distr/core/contracts/ports/<порт>/<версия>/ в ui; на сайте документации — /ai/ports/<порт>/<версия>/ |
Объявление порта и его набор проверок; полный набор изданных версий — в поставке |
| Манифесты компонентов | smart.manifest.json в папке компонента: distr/smart/<папка>/ в ui, src/smart/<папка>/ в исходнике пакета продукта. Сайт документации манифесты компонентов не публикует; адрес на выпуск — https://cdn.jsdelivr.net/npm/@simai-studio/ui@5.20261019.1559/distr/smart/<папка>/smart.manifest.json, для пакета larena — components/src/smart/<папка>/smart.manifest.json в simai/larena-ui на коммите пакета из квитанции |
Контракт компонента и раздел ai_guidance |
| Справка о пакете | distr/core/contracts/packages/<имя>.package.json в ui |
Какие элементы даёт пакет и что каждому нужно от Framework |
| Журнал изменений | contracts/changes/journal.json в открытом репозитории simai/ui-source (см. Журнал изменений) |
Что переименовано, на что, когда удаляется, как заменить |
| Правила загрузки | distr/core/js/core-rules.js и distr/rule/ в ui |
Какой тег в какой папке: правило cl-<папка> перечисляет теги в поле tags, например cl-buttons → sf-button, папка distr/smart/buttons/ |
| Отчёт обновления | node scripts/sf-upgrade.mjs <проект> --json в checkout simai/ui-source на коммите исходников выпуска (см. Инструмент sf-upgrade) |
Где в проекте прежние имена и что с ними делать |
/ai/framework-lock.json и файл блокировки проекта (см. Версии: как закрепить выпуск) — разные
файлы. Выпуск проекта берётся из файла блокировки проекта. ИИ сверяет его с
полем runtime.pair_id файла /ai/framework-lock.json (например,
ui-106d5901f8c3): если выпуски разные, документация сайта описывает
другой выпуск, и ИИ сообщает об этом, а не применяет её молча.
Раздел ai_guidance манифеста содержит:
use_when— когда применять компонент;do_not— чего не делать;required_reads— что прочитать до применения;minimal_example— минимальную рабочую разметку;owner_commands— команды, которыми владелец подтверждает изменение.
Подробно — см. Указания для ИИ.
Сайт и AI-выдача строятся из одних исходников одной командой
composer docs:build. Проверка composer docs:ai:check повторно вычисляет
тексты и хеши, и изменённый или отсутствующий файл её останавливает. Экспорт
также сверяет каждый файл комплекта Recipe с закреплённым нормативным
комплектом и его общим отпечатком. Экспорт не подтверждает правильность каждой фразы: изменение
поведения требует содержательного пересмотра связанных страниц.
Где читать документацию
Постоянный публичный адрес документации —
https://ui.simai.io/. Индекс для
ИИ лежит в его корне:
https://ui.simai.io/ai.json,
файл выпуска — https://ui.simai.io/ai/framework-lock.json, а
текст любой страницы — в ai.md в её папке, например
https://ui.simai.io/ru/guide/standards/ai/ai.md.
Сайт описывает один выпуск — тот, что назван в его
/ai/framework-lock.json. Помощник сам этот адрес не найдёт: передайте его в
задании или в файле инструкций проекта (ниже). Копия сайта, собранная локально,
доступна только в вашем окружении, и внешняя система её не прочитает.
Устройство индекса
Индекс /ai.json — документ формата AI First 1.0 ("format": "ai-first",
"formatVersion": "1.0", "document": "manifest"). Он описывает ресурс
документации и ссылается на каталоги /ai/catalogs/01.json,
/ai/catalogs/02.json и далее, по сто записей в каждом, и на файл выпуска
(frameworkLock); у каждой ссылки есть sha256. Запись каталога описывает
одно знание:
| Поле | Что содержит |
|---|---|
id |
устойчивый идентификатор, например urn:simai:framework:composition-recipe:specification |
kind |
knowledge — страница или нормативный файл, contract — порт |
title, description, language |
название, описание и язык |
revision |
sha256 содержимого |
source, representations |
адрес файла; у представления — href, mediaType и sha256 |
htmlPage |
страница сайта, к которой относится знание |
Для каждой страницы есть отдельные файлы: текст в Markdown (ai.md) и
описание в JSON (ai.json) в папке страницы. Представления Markdown
содержат и код демонстраций, включая JavaScript, поэтому ИИ не угадывает
содержимое вкладок по HTML страницы. Чтобы собирать страницы по Composition
Recipe, ИИ находит в индексе знание
urn:simai:framework:composition-recipe:specification: оно ведёт к полному
описанию алгоритма, рядом лежат схемы, ограничения и контрольный пример
(Где взять спецификацию).
Источники правды по порядку
Когда источники расходятся, действует такой порядок:
- Поставка изданного выпуска, закреплённого в проекте: файлы
distr/иcontracts/репозиторияsimai/uiна коммите выпуска, а для пакета продукта — его сборка из квитанции. При любом расхождении верны эти байты. Исходники Framework (ui-source) — источник у владельца Framework; поставка собрана из них воспроизводимо (см. Воспроизводимость выпуска). - Машинные контракты этого выпуска: манифест компонента, конверты стандартов, порты, журнал изменений.
- Справочник — страница компонента, утилиты, токена.
- Руководство — этот текст и страницы стандартов.
- Примеры и Playground — как иллюстрация, а не как контракт.
Источник, не привязанный к выпуску проекта (последняя ветка, другой проект,
воспоминание о другой версии), правдой не считается. О каждом найденном
расхождении сообщают в Issues репозитория simai/ui-source: выпуск проекта, что сказано в
источнике и что делает поставка.
ИИ применяет Framework в проекте
Правила для ИИ, который пишет код проекта на SIMAI Framework:
- Узнать, какой выпуск закреплён в проекте (и квитанции пакетов продуктов, если они подключены), и работать только по документации и манифестам этих выпусков.
- Компонент пакета применять, только если проект объявил этот пакет (см. Пакеты компонентов).
- Прежде чем писать разметку, прочитать нужные страницы справочника; для
Smart-компонента — прочитать
ai_guidance.required_readsи начать сminimal_example. - Использовать только существующие классы, токены, атрибуты, значения и события. Не придумывать их по аналогии с другими библиотеками. Для каждого решения уметь назвать источник.
- Писать канонические имена (
appearance,status,kind,size,scheme; логические стороны:inline-start/inline-endв значениях и утилитах, напримерplacement="inline-start"иm-inline-start-2,start/endв именах атрибутов, напримерicon-start); прежние имена в новой разметке не использовать. - Цвета задавать токенами и ролями, стороны — логически, размеры — ступенями одной лестницы.
- Не переносить в Framework данные, права и решения проекта; не копировать
сгенерированный код
uiи собранных пакетов в проект. - Обновлять проект на новый выпуск только по журналу: сначала механические
замены
node scripts/sf-upgrade.mjs <проект> --apply, затем каждое ручное место по инструкции и примеру из его записи, без собственных догадок о соответствиях. - Проверить результат в браузере с закреплённым выпуском: загрузка, консоль, клавиатура, фокус, обе темы, мобильная ширина, пустое состояние и ошибка.
Пример задания помощнику. Он показывает, как привязать работу ИИ к выпуску проекта и потребовать источники:
Собери панель действий для проекта на SIMAI Framework (выпуск из lock-файла проекта).
Используй только классы и компоненты со страниц справочника и манифестов этого выпуска.
Для каждого решения укажи источник. Не придумывай параметры и события.
Проверь мобильную ширину, клавиатуру, обе темы и ошибки в консоли.
Обратите внимание: задание называет выпуск, ограничивает источники и перечисляет проверки — без этого помощник может опереться на другую версию или придумать параметры.
Файл инструкций для помощника. Чтобы не повторять правила в каждом
задании, положите в корень проекта файл, который читает ваш помощник
(AGENTS.md, CLAUDE.md или аналог):
# SIMAI Framework в этом проекте
- Выпуск Framework: см. файл блокировки проекта (`simai-framework.lock.json`).
- Документация: https://ui.simai.io/ (индекс для ИИ — /ai.json).
Если `runtime.pair_id` в /ai/framework-lock.json не совпадает с выпуском
проекта, сообщи об этом и не применяй документацию молча.
- Правила: https://ui.simai.io/ru/guide/standards/ai/ai.md и
https://ui.simai.io/ru/guide/smart-components/ai-development/ai.md.
- Только существующие классы, токены, атрибуты и события; для каждого решения
назови страницу или манифест.
- Обновление выпуска — только через `node scripts/sf-upgrade.mjs` и журнал
изменений.
- Готовность — после проверки в браузере: консоль, клавиатура, обе темы,
мобильная ширина.
Имя файла блокировки и пути замените своими.
ИИ развивает сам Framework
Правила для изменения Framework строже, потому что ошибка попадает во все проекты сразу.
- Сначала контракт, потом код. Манифест, схема, токен, стандарт или запись журнала меняются первыми; реализация следует за ними.
- Каждое новое правило — вместе с проверкой. Контрактный тест держит механизм, браузерная проба — результат.
- Правки только в исходниках.
uiи собранные пакеты генерируются и вручную не правятся. - Прежнее имя не удаляется сразу. Оно уходит в совместимость с записью в журнале и с датой по политике.
- Геометрия измеряется на настольной и мобильной ширине, по нарисованному результату.
- Документация обновляется в той же поставке (Гейт документации).
- Проверки читают кандидата. Перед изданием выпуска гейт и пробы запускаются против собранного кандидата.
- Проверка не пропускается молча. Пропущенная проверка называется с причиной; «не удалось запустить» не означает «прошла».
- Стандарт меняется изданием. Изданный конверт не правится; поправка — новая версия с записью причины, прежняя уходит в историю.
- Публичное имя — SIMAI Framework, технический префикс —
sf.
Правила для Smart-компонентов — см. Стандарт разработки Smart-компонентов с ИИ.
Чего ИИ не делает
- Не правит сгенерированные поставки.
- Не считает зелёный тест одного проекта доказательством общей совместимости.
- Не заявляет готовность без проверки в браузере.
- Не называет
mainили последнюю ветку релизом. - Не объявляет требования «на будущее» и не добавляет в стандарт детали реализации.
- Не выдаёт пропущенную или неправильно вызванную проверку за пройденную.
Что ИИ сдаёт по итогу
Отчёт ИИ — это доказательства, а не рассказ о проделанной работе. Отчёт содержит:
- что изменено, в каких файлах и на какой ревизии;
- какие проверки запущены, с каким результатом, против какого кандидата или какого выпуска;
- что измерено в браузере (геометрия, фокус, контраст) и на какой ширине;
- какие записи добавлены в журнал изменений и документацию;
- что пропущено и почему;
- что осталось открытым и кто должен это решить.
Доказательства проверяются отдельно от отчёта (Что гарантирует изданный выпуск).
Смотрите также
- Указания для ИИ — раздел
ai_guidanceманифеста. - Стандарт разработки Smart-компонентов с ИИ — правила ИИ для Smart-компонентов.
- Как обновить проект — обновление проекта по журналу.
- Как Framework проверяет себя, Как проект проверяет своё использование Framework — проверки Framework и проекта.
Связь с другими частями
- Закрепление выпуска, обновление и журнал — Версии: как закрепить выпуск–Как обновить проект.
- Токены, роли цвета, контраст — Дизайн-токены, Цветовые роли и Контраст.
- Лестница размеров, фокус, направления, язык — Одна лестница размеров, Фокус–Язык интерфейса; стандарт геометрии — Геометрия: стандарт и проверка.
- Composition Recipe и композиция — Макеты и композиция.
- Манифест, проверки и правила ИИ для Smart-компонентов — Манифест, Проверки и Стандарт разработки Smart-компонентов с ИИ.