Przejdź do głównej treści
Wysłałeś zacieśnioną politykę pii-shield w poniedziałek, kolega rozszerzył regex w środę, a teraz rzeczywisty ruch rzuca fałszywie pozytywnymi. Potrzebujesz zobaczyć, co się zmieniło, kto to zmienił, i wycofać — bez zgadywania poprzedniego JSON i bez wdrażania czegokolwiek. To jest to, co daje wersjonowanie guardrail: wiersz historii na zmianę, diff między dowolnymi dwoma i revert jednym kliknięciem. Ta strona to skupiona strona docelowa dla powierzchni wersjonowania. Po sam silnik guardrail — typy reguł, etapy, akcje — zacznij od przeglądu Guardrails lub pełnej referencji Guardrails.

​
1. Co rejestruje wersjonowanie guardrail

Każda mutacja na guardrail — utworzenie, aktualizacja, usunięcie i revert — zapisuje wiersz historii tylko do dopisywania w tej samej transakcji co zmiana. Wiersz przechwytuje migawkę widocznej dla użytkownika konfiguracji w tym momencie:
  • nazwę guardrail,
  • czy był włączony,
  • czy był domyślny przestrzeni roboczej,
  • pełne ciało rules.
Każdy wiersz niesie monotoniczny numer wersji (zaczynając od 1), operację, która go wyprodukowała, autora i znacznik czasu. Ponieważ wiersz jest zapisywany transakcyjnie z edycją, historia nigdy nie może rozjechać się z żywą polityką — jeśli edycja się commituje, to i jej wiersz historii.
Historia jest tylko do dopisywania. Revert nie cofa ani nie przepisuje przeszłych wierszy; dopisuje nową wersję (zobacz §4). Zawsze widzisz kompletną sekwencję tego, kto co zrobił, w kolejności.

​
2. Jeden konkretny przykład — znajdź złą edycję i wycofaj ją

Powiedzmy, że guardrail 42 się rozjechał. Autorujesz to wszystko z konsoli w swojej sesji — klucz relay sk-orca-... służy wyłącznie do wywołań /v1/*, nigdy do odczytu lub zmiany polityki.
1

Wylistuj historię

Otwórz History na wierszu guardrail w /console/guardrails. Strumień jest najnowsze-pierwsze. Widzisz v5 update (środa, przez kolegę), v4 update (poniedziałek, przez ciebie), v3 update i tak dalej wstecz do v1 create. Odczyt historii jest otwarty dla każdego Member przestrzeni roboczej.
2

Porównaj podejrzaną zmianę

Wybierz dwie wersje, które obejmują regresję — v4 i v5 — i zobacz diff. Ciało rules jest pokazane obok siebie, więc rozszerzony regex wyskakuje jako linia, która się zmieniła.
3

Revert

Przywróć v4. Nazwa, flaga włączenia, flaga domyślnego i reguły żywego guardrail są ustawiane z powrotem na tę migawkę, a świeży wiersz v6 revert jest dopisywany. Zmiana jest żywa przy następnym żądaniu — bez ponownego wdrożenia, bez zmiany SDK. Revert wymaga roli Developer+.
Ten sam przepływ przez REST API, wszystko w twojej sesji / tokenie dostępu (nigdy kluczu relay), w zakresie przestrzeni roboczej przez 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}'
Odpowiedź revert zwraca żywy guardrail po-revert, więc twój UI może się odświeżyć bez dodatkowego obiegu. Następne wywołanie /v1/* sprawdzane przez ten guardrail widzi przywróconą politykę.

​
3. Historia, diff i strumień wersji

GET /api/guardrail/:id/history zwraca ślad wersji, najnowsze pierwsze. Każdy wpis to jedna migawka ze swoim numerem wersji, operacją (create / update / delete / revert), autorem i znacznikiem czasu. Strumień jest w zakresie przestrzeni roboczej — wywołujący w innej przestrzeni dostaje tę samą kopertę not-found co brakujący guardrail, więc istnienie nigdy nie wycieka.
GET /api/guardrail/:id/history/:version pobiera jedną migawkę po jej numerze wersji — przydatne do inspekcji dokładnego ciała rules, które było żywe w danym momencie, zanim zdecydujesz, czy do niego wrócić.
GET /api/guardrail/:id/history/diff?from=N&to=M zwraca obie migawki — from i to — więc konsola może wyrenderować porównanie obok siebie nazwy, flag i reguł. Obie wersje muszą należeć do twojej przestrzeni roboczej, albo wywołanie zwraca jednolitą kopertę not-found.
Odczyty — lista historii, pojedyncza wersja i diff — są otwarte dla każdego Member przestrzeni roboczej. To czysta inspekcja: nic w ruchu się nie zmienia, a żadne wywołanie modelu ani dostawcy nie jest wykonywane.

​
4. Revert przywraca jako nową wersję

Revert to nie cofnięcie. POST /api/guardrail/:id/revert z ciałem to_version:
  1. Ładuje migawkę docelowej wersji.
  2. Przywraca nazwę, flagę włączenia, flagę domyślnego i reguły żywego guardrail do tej migawki — atomowo, w jednej transakcji.
  3. Dopisuje świeży wiersz historii revert przechwytujący teraz-żywy stan.
Więc revert v5 z powrotem do v4 produkuje nowe v6, którego zawartość równa się v4. Twoja historia czyta się v1 → v2 → … → v5 → v6(revert) — każdy krok zachowany, nic nie zmutowane. Wykonaj revert tej starszej migawki znów później, a dostaniesz v7 i tak dalej.
Przywrócony stan wyłączony lub niedomyślny przechodzi obieg nietknięty. Jeśli wersja, do której wracasz, miała enabled: false lub nie była domyślnym przestrzeni roboczej, revert ustawia żywy guardrail z powrotem dokładnie na to — nie trzyma po cichu polityki włączonej. Najpierw zrób diff, byś wiedział, czy revert przełączy też te flagi.
Ponieważ powiązanie żyje na bramie, revert przesuwa każdy klucz API powiązany z tym guardrail naraz — i domyślny przestrzeni roboczej, jeśli to ten — przy następnym wywołaniu. Zobacz powiąż z kluczem i domyślny przestrzeni roboczej, jak powiązanie się rozwiązuje.

​
5. Role i retencja

AkcjaTrasaRola
Listuj / czytaj wersje, diffGET …/history, …/history/diff, …/history/:versionMember
Revert do wersjiPOST …/revertDeveloper+
Wszystkie trasy historii to /api/guardrail/* i uwierzytelniają się twoją sesją / tokenem dostępu pod X-Workspace-Id — nigdy kluczem relay sk-orca-.... Revert niesie tę samą bramkę Developer+ co tworzenie lub aktualizacja guardrail, bo zmienia żywy ruch.
Historia jest zachowywana w 50 najnowszych wersjach na guardrail. Starsze wiersze są przycinane automatycznie, gdy dalej edytujesz, więc gadatliwy przepływ pętli edycji nigdy nie rozrasta śladu bez ograniczeń. Endpoint listy zwraca do najnowszych 50, najnowsze pierwsze.
Sparuj wersjonowanie z strojeniem flag-first: wyślij nową regułę jako flag, obserwuj strumień dopasowań, a jeśli się źle zachowuje, zrób diff i revert w sekundy zamiast rekonstruować starą politykę ręcznie.

​
6. Dokąd dalej

Test i eval, zanim wyślesz

Udowodnij politykę w piaskownicy i wobec korpusu, zanim stanie się wersją, którą musiałbyś wycofać.

Strojenie fałszywie pozytywnych

Pętla flag-then-promote, którą wersjonowanie czyni bezpieczną.

Akcje: block, mask, flag

Co każda reguła robi, gdy wersja jest żywa.

Referencja Guardrails

Pełny silnik — typy reguł, etapy, presety i kompletne API.
Wersjonowanie tutaj obejmuje politykę treści guardrail. Firewall ma własną powierzchnię zmian dla polityki narzędzi; jak różnią się obie warstwy egzekwowania, zobacz guardrails vs. firewall.