Тема
Версии и изменения
Версия контракта
Версия контракта передаётся только через _meta и никогда — через аргументы инструмента. Префикс ключей — домен продукта NORM.
| Где | Ключ | Тип | Что это |
|---|---|---|---|
_meta инструмента в tools/list | ai-norm.com/contract_versions | список integer | Версии контракта, которые инструмент реализует нативно; перевод для них не нужен. |
_meta ответа initialize | ai-norm.com/contract_version | integer | Целое число; растёт только при механическом разломе. |
_meta вызова tools/call | ai-norm.com/contract_version | integer | Целое число; растёт только при механическом разломе. |
_meta устаревшего инструмента в tools/list | ai-norm.com/sunset | string (date) | Календарная дата, после которой устаревший инструмент исключается. |
Какую версию реализует инструмент, платформа определяет по первому найденному:
- версии в
_metaинструмента; - версия в
_metaответаinitialize; - версия, закреплённая за подключением сервера;
- последняя известная версия — это записывается в журнал как ошибка настройки.
Уровни изменений
Это правила процесса из конституции репозитория контракта (принцип V), а не часть слепка: слепок фиксирует форму контракта, уровни описывают, как её можно менять.
| Уровень | Что разрешено | Версия контракта | Что требует CI |
|---|---|---|---|
| Добавление | необязательные аргументы входа с умолчанием, равным старому поведению; необязательные поля выхода | не меняется | версия пакета поднята, запись в CHANGELOG |
| Механический разлом | переименование, перекладка структуры при том же смысле | +1 | правило перевода между соседними версиями |
| Смысловой разлом | новый инструмент с новым именем, старый устаревает | не меняется | дата заката у устаревшего инструмента |
| Удаление | инструмент исчезает из слепка вместе с тем, что обслуживало только его | не меняется | метка [удаление]; у удалённого истёк закат либо версия пакета ниже 1.0.0 |
Версия пакета и версия контракта — разные величины. Версия пакета семантическая и растёт при любом изменении слепка. Версия контракта — целое число в _meta, растёт только при механическом разломе.
Правила перевода
Если версия вызова и версия инструмента расходятся, платформа переводит вызов и ответ. Перевод возможен только для механических разломов и только между соседними версиями; дальние версии проходят цепочкой. Если цепочка рвётся, вызов получает ошибку tool_outdated_for_agent.
Правил пока нет: контракт существует в одной версии.
Операции перевода: rename — переименовать поле, move — переложить, default — задать умолчание, drop — убрать.