Перейти к основному содержанию
Вы зашипили более строгую политику pii-shield в понедельник, коллега расширил regex в среду, и теперь реальный трафик выдаёт ложные срабатывания. Вам нужно увидеть, что изменилось, кто изменил и откатиться — не угадывая прежний JSON и ничего не передеплоивая. Это то, что даёт вам версионирование guardrail: строка истории на изменение, diff между любыми двумя и revert в один клик. Эта страница — сфокусированная посадочная для поверхности версионирования. Сам движок guardrail — типы правил, стадии, действия — начните с обзора Guardrails или полного справочника Guardrails.

​
1. Что записывает версионирование guardrail

Каждая мутация guardrail — create, update, delete и revert — пишет append-only строку истории в той же транзакции, что и изменение. Строка фиксирует снимок видимой пользователю конфигурации в этот момент:
  • имя guardrail,
  • был ли он enabled,
  • был ли он default’ом рабочего пространства,
  • полное тело rules.
Каждая строка несёт монотонный номер версии (начиная с 1), операцию, которая её произвела, автора и временную метку. Поскольку строка пишется транзакционно с редактированием, история никогда не может рассинхронизироваться с живой политикой — если редактирование коммитится, коммитится и его строка истории.
История append-only. Revert не отматывает и не переписывает прошлые строки; он добавляет новую версию (см. §4). Вы всегда видите полную последовательность того, кто что сделал, по порядку.

​
2. Один конкретный пример — найти плохое редактирование и откатить

Скажем, guardrail 42 отклонился. Вы создаёте всё это из консоли на вашей собственной сессии — relay-ключ sk-orca-... только для вызовов /v1/*, никогда для чтения или изменения политики.
1

Перечислите историю

Откройте History в строке guardrail в /console/guardrails. Лента новые-первыми. Вы видите v5 update (среда, коллега), v4 update (понедельник, вы), v3 update и так далее назад до v1 create. Чтение истории открыто любому Member рабочего пространства.
2

Сравните подозрительное изменение

Выберите две версии, которые обрамляют регрессию — v4 и v5 — и посмотрите diff. Тело правил показано бок о бок, так что расширенный regex выскакивает как строка, которая изменилась.
3

Откатитесь

Восстановите v4. Имя живого guardrail, флаг enabled, флаг default и правила устанавливаются назад к этому снимку, и добавляется свежая строка v6 revert. Изменение живо на следующем запросе — без передеплоя, без изменения SDK. Revert требует роли Developer+.
Тот же поток по REST API, всё на вашем session / access token (никогда relay-ключ), ограничено рабочим пространством через X-Workspace-Id: 
# 1. List versions (Member)
curl https://api.orcarouter.ai/api/guardrail/42/history \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 2. Diff v4 against v5 (Member) — returns both snapshots to render side by side
curl "https://api.orcarouter.ai/api/guardrail/42/history/diff?from=4&to=5" \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 3. Revert to v4 — appends a new "revert" version (Developer+)
curl -X POST https://api.orcarouter.ai/api/guardrail/42/revert \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 4}'
Ответ revert возвращает живой guardrail после revert, так что ваш UI может обновиться без лишнего round-trip. Следующий вызов /v1/*, проверенный этим guardrail, видит восстановленную политику.

​
3. История, diff и лента версий

GET /api/guardrail/:id/history возвращает след версий, новые первыми. Каждая запись — это один снимок с его номером версии, операцией (create / update / delete / revert), автором и временной меткой. Лента ограничена рабочим пространством — вызывающий в другом рабочем пространстве получает тот же not-found конверт, что и отсутствующий guardrail, так что существование никогда не утекает.
GET /api/guardrail/:id/history/:version извлекает один снимок по его номеру версии — удобно для инспекции точного тела правил, которое было живым в момент времени, прежде чем вы решите, откатываться ли к нему.
GET /api/guardrail/:id/history/diff?from=N&to=M возвращает оба снимка — from и to — так что консоль может отрендерить сравнение бок о бок имени, флагов и правил. Обе версии должны принадлежать вашему рабочему пространству, иначе вызов возвращает единообразный not-found конверт.
Чтения — список истории, одна версия и diff — открыты любому Member рабочего пространства. Это чистая инспекция: ничего в трафике не меняется, и не делается вызов модели или вендора.

​
4. Revert восстанавливает как новую версию

Revert — не отмотка. POST /api/guardrail/:id/revert с телом to_version:
  1. Загружает снимок целевой версии.
  2. Восстанавливает имя живого guardrail, флаг enabled, флаг default и правила к этому снимку — атомарно, в одной транзакции.
  3. Добавляет свежую строку истории revert, фиксирующую теперь живое состояние.
Так что revert v5 назад к v4 производит новую v6, чьё содержимое равно v4. Ваша история читается v1 → v2 → … → v5 → v6(revert) — каждый шаг сохранён, ничего не мутировано. Откатите тот более старый снимок снова позже, и вы получите v7, и так далее.
Восстановленное disabled или non-default состояние round-trip’ит нетронутым. Если версия, к которой вы откатываетесь, имела enabled: false или не была default’ом рабочего пространства, revert устанавливает живой guardrail назад ровно к этому — он не оставляет политику включённой молча. Сравните сначала, чтобы знать, перевернёт ли revert также эти флаги.
Поскольку привязка живёт на шлюзе, revert сдвигает каждый API-ключ, привязанный к этому guardrail сразу — и default рабочего пространства, если это он — на следующем вызове. См. привязку к ключу и default рабочего пространства для того, как разрешается привязка.

​
5. Роли и хранение

ДействиеМаршрутРоль
Список / чтение версий, diffGET …/history, …/history/diff, …/history/:versionMember
Revert к версииPOST …/revertDeveloper+
Все маршруты истории — /api/guardrail/* и аутентифицируются вашим session / access token под X-Workspace-Id — никогда relay-ключом sk-orca-.... Revert несёт тот же шлюз Developer+, что и создание или обновление guardrail, поскольку он меняет живой трафик.
История хранится в 50 самых свежих версиях на guardrail. Более старые строки автоматически отсекаются по мере того, как вы продолжаете редактировать, так что болтливый цикл редактирования никогда не наращивает след без границ. Эндпоинт списка возвращает до новейших 50, новые первыми.
Сочетайте версионирование с настройкой flag-first: зашипите новое правило как flag, понаблюдайте за лентой matches, и если оно ведёт себя плохо, сравните и откатитесь за секунды вместо реконструкции старой политики вручную.

​
6. Куда двигаться дальше

Тестирование и eval перед шипом

Докажите политику в песочнице и против корпуса до того, как она станет версией, которую пришлось бы откатывать.

Настройка ложных срабатываний

Цикл flag-затем-продвинуть, который версионирование делает безопасным.

Действия: block, mask, flag

Что делает каждое правило, как только версия становится живой.

Справочник Guardrails

Полный движок — типы правил, стадии, пресеты и полный API.
Версионирование здесь покрывает контентную политику guardrail. У firewall своя поверхность изменений для политики инструментов; о том, как два слоя применения отличаются, см. guardrails vs. firewall.