Робота з проєктом Ramus: інструкція для агента

Короткий протокол правки моделі у файлах. Повний опис формату — PROJECT_FORMAT.md; тут лише порядок дій і межі.

Застосунок працює з .rsf і каталогів проєкту не відкриває: дерево файлів дістають конвертером rsfToYaml, а повертають yamlToRsf.

1. Головне правило

Правити значення — безпечно. Вигадувати ідентифікатори — ні.

Створення й видалення сутностей робить застосунок, а результат забирають конвертером. Агент уточнює вміст того, що вже існує: назви, координати, кольори, описи, текстові підписи.

Причина не в обережності заради обережності. Ідентифікатор — оборотна функція числового ключа в базі, а не довільний рядок. Вигаданий id або розбиває посилання, або тихо вказує на чужу сутність.

2. Перед першою правкою

  1. Перевірити, що це проєкт. Усередині каталогу має бути project.ramus.
  2. Звірити версію схеми. У project.ramus має бути schema: 4. Інша версія — зупинитися: механізму міграції немає, читач відмовить.
  3. Переконатися, що робоче дерево чисте. git status до правки має бути порожній, інакше перевірити результат буде нічим.
  4. Не чіпати .local/. Це стан інтерфейсу, він поза версійованою частиною.

3. Як знайти те, що правите

Що шукаєте Де
назва блока чи дії qualifiers/<назва>--<id>.yaml, elements[].values.<name-attribute>
положення й розмір той самий елемент, F_BOUNDS: x, y, width, height
колір, шрифт F_BACKGROUND, F_FOREGROUND (ціле ARGB), F_FONT
назва стрілки не у стрілці: F_SECTORS → F_SECTOR_STREAM → F_STREAMS
який атрибут назва name-attribute у файлі класифікатора
перелік атрибутів attributes.yaml

elements[].name — не те, що показується користувачу; його правити не треба.

Порядок attributes у класифікаторі значущий — це порядок стовпчиків. Порядок system-attributes і elements — ні.

4. Цикл правки

git status → чисто
   ↓
правка у файлах
   ↓
./gradlew :ramus-core-demo:yamlToRsf -Pin=<проєкт> -Prsf=/tmp/check.rsf
   ↓
git diff → у ньому лише те, що ви змінювали

Крок із yamlToRsf — перевірка без графічного інтерфейсу: конвертер читає проєкт тим самим кодом, що й застосунок. Отриманий .rsf не потрібен, важливо лише те, що збірка пройшла.

Якщо git diff показує перебудований файл там, де ви його не чіпали, — значення було записане у формі, яку читач зрозумів інакше. Це сигнал розібратися, а не переписати diff.

5. Що перевірка ловить, а що ні

Перевірено на практиці:

Помилка yamlToRsf
дублікат ключа ✅ падає, називає ключ і рядок
зламаний YAML, неправильний тип ✅ падає
чужа версія схеми ✅ відмовляється читати
підмінений або вигаданий id ❌ проходить мовчки
посилання в нікуди ❌ проходить мовчки

Останні два рядки — причина правила з розділу 1. Синтаксична перевірка не рятує від зламаних посилань: їх видно лише в застосунку, і то не завжди одразу.

Остаточна перевірка одна: прогнати проєкт yamlToRsf, а отриманий архів — rsfToYaml назад у новий каталог. Файли зведуться до канонічного вигляду, і git diff покаже правду.

6. Червоні лінії

Не робити без прямої вказівки людини:

7. Масові заміни

sed по qualifiers/*.yaml працює: рядки не переносяться й не екрануються складно. Після заміни варто прогнати проєкт конвертерами туди й назад — запис зведе файли до канонічного вигляду, і наступний diff буде чистим.

Правити руками можна вільніше, ніж пише сам конвертер: подвійні лапки, відсутність лапок там, де значення однозначне, інший порядок ключів — усе це прочитається.

8. Коли зупинитися і спитати

9. Подивитися на справжній проєкт

./gradlew :ramus-core-demo:rsfToYaml \
    -Prsf="dest/doc/en/Enterprise activity.rsf" -Pout=/tmp/Enterprise.ramus

Готові зразки моделей лежать у dest/doc/en/ і dest/doc/ru/.