Skip to content

Версии и изменения ​

Версия контракта ​

Версия контракта передаётся только через _meta и никогда — через аргументы инструмента. Префикс ключей — домен продукта NORM.

ГдеКлючТипЗачем
_meta инструмента в tools/listai-norm.com/contract_versionsсписок integerЧтобы платформа знала, какие версии вызова инструмент примет без перевода.
_meta ответа initializeai-norm.com/contract_versionintegerПо ней платформа решает, нужно ли переводить вызов и ответ между версиями. Растёт только при механическом разломе.
_meta вызова tools/callai-norm.com/contract_versionintegerПо ней платформа решает, нужно ли переводить вызов и ответ между версиями. Растёт только при механическом разломе.
_meta устаревшего инструмента в tools/listai-norm.com/sunsetstring (date)Чтобы потребители успели перейти на преемника: с этой даты инструмент исключается.

Какую версию реализует инструмент, платформа определяет по первому найденному:

  1. версии в _meta инструмента;
  2. версия в _meta ответа initialize;
  3. версия, закреплённая за подключением сервера;
  4. последняя известная версия — это записывается в журнал как ошибка настройки.

Уровни изменений ​

Это правила процесса из конституции репозитория контракта (принцип V), а не часть слепка: слепок фиксирует форму контракта, уровни описывают, как её можно менять.

УровеньЧто разрешеноВерсия контрактаЧто требует CI
Добавлениенеобязательные аргументы входа с умолчанием, равным старому поведению; необязательные поля выходане меняетсяверсия пакета поднята, запись в CHANGELOG
Механический разломпереименование, перекладка структуры при том же смысле+1правило перевода между соседними версиями
Смысловой разломновый инструмент с новым именем, старый устареваетне меняетсядата заката у устаревшего инструмента
Удалениеинструмент исчезает из слепка вместе с тем, что обслуживало только его; до 1.0.0 — ещё и поле ответа без потребителяне меняетсяметка [удаление]; у удалённого истёк закат либо версия пакета ниже 1.0.0

Версия пакета и версия контракта — разные величины. Версия пакета семантическая и растёт при любом изменении слепка. Версия контракта — целое число в _meta, растёт только при механическом разломе.

Правила перевода ​

Если версия вызова и версия инструмента расходятся, платформа переводит вызов и ответ. Перевод возможен только для механических разломов и только между соседними версиями; дальние версии проходят цепочкой. Если цепочка рвётся, вызов получает ошибку tool_outdated_for_agent.

Правил пока нет: контракт существует в одной версии.

Операции перевода: rename — переименовать поле, move — переложить, default — задать умолчание, drop — убрать.