Verzija 1.0.0-alpha.1najnovije
Poglavlje 2.19
Pravila koja nasljeđuje svako proširenje
Izolacija na tri osi, obrada putem sustava UNO, AI (umjetna inteligencija) putem usmjerivača, ključevi u vlasništvu organizacije i provjere licencija. Što svako pravilo znači za vaš kod i koja ga kontrolna točka provodi te zašto ga nasljeđujete umjesto da ga pišete.
Ovu je stranicu s engleskog izvornika preveo AI. Ako je išta nejasno, mjerodavna je stranica na engleskom jeziku. Pročitajte ovu stranicu na engleskom jeziku

Prvo odbijanje koje je moj dodatak za pregled anomalija ikada poslao bilo je upućeno meni. Napisao sam testni klijent koji je poslao novi pregled s ID-jem organizacije u tijelu zahtjeva, iz navike s druge platforme, a dodatak je odgovorio prije nego što se moj rukovatelj uopće pokrenuo:
{
"error": true,
"code": "TENANT_NOT_A_PARAMETER",
"message": "The request body names the organisation. Tenancy comes from the token.",
"resolved": ["tenant", "owner"],
"missing": [],
"troubleshooting": ["Remove organizationId from the body. The organisation is read from your sign-in."]
}Nisam ja napisao tu provjeru. Došla je s čuvarem opsega koji predložak SDK-a (kompleta za razvoj softvera) povezuje sa svakom /api rutom, a aktivira se čak i kada je ID u tijelu zahtjeva vlastiti ID pozivatelja. To je obrazac za cijelo ovo poglavlje: mali broj pravila, od kojih svako provodi mehanizam koji nasljeđujete, a svako ima kontrolnu točku koja ruši vašu izgradnju ako je vaš kod zaobiđe. Na Nexusu vaš dodatak nasljeđuje svoju izolaciju od platforme, a kontrolne točke je revidiraju.
Postoji pet pravila, a odjeljci u nastavku obrađuju ih redom: izolacija na tri osi; izračun koji se izvršava isključivo putem UNO otpreme; AI (umjetna inteligencija) koji prolazi isključivo kroz AI Provider Router; ključevi modela koji pripadaju organizaciji; te licencirane značajke koje se provjeravaju prema licenci. Svaki manifest također ponavlja tri od tih pravila u jednom bloku rečenica.
Pravilo 1: izolacija na tri osi, od autentificiranog zahtjeva
Svako čitanje i pisanje u proširenju ograničeno je opsegom na tri osi, baš kao i svaki poziv alata i otprema vještine.
| Os | Stupac | Odgovara na pitanje | Koliko je čvrsta granica |
|---|---|---|---|
| Zakupnik | organization_id |
Koja organizacija | Čvrsta granica, koja se prelazi samo putem zabilježenog odobrenja samo za čitanje |
| Vlasnik | owner_user_id |
Koja osoba unutar organizacije | Privatno čak i unutar jedne organizacije, za sve što je osobno |
| Jedinica | business_unit_id |
Koji dio organizacije | Opcionalna ograda unutar zakupca |
Os vlasnika je ona u kojoj početnici griješe. Poštanski sandučić je osoban, kao i spremljeni prikaz ili grafikon izveden iz podataka jedne osobe. Dva člana iste organizacije, u istoj jedinici s istom ulogom, ne vide retke onog drugog koji su ograničeni na vlasnika. Na artefaktu organizacije, primjerice odobrenju ili zapisu predmeta, vlasnik umjesto toga predstavlja podrijetlo: bilježi tko je djelovao, a čitanja su ograničena na zakupca kako bi revizijski trag ostao vidljiv osobama kojima je potreban. Vi za svaku tablicu odlučujete o kojoj je vrsti riječ, a sloj repozitorija to kodira – nikada kao poseban slučaj u ruti.
Osi dolaze iz autentificiranog zahtjeva i niotkuda drugdje. Varijabla okruženja ih ne može dostaviti, kao ni parametar upita, segment putanje, zaglavlje klijenta ili konstanta izgradnje. SDK otežava pisanje pogrešne stvari: resolveScope(identity, options) uopće nema parametar organizacije. Organizacija se nalazi unutar identity, a samo verificirani token može ga proizvesti. Nema ničega kroz što bi se mogao proslijediti ID.
Zato se tijelo zahtjeva koje navodi zakupca odbija umjesto da se ignorira. Čuvar odbija bilo koje od pet imena polja: orgId, organizationId, organization_id, tenant i tenantId. Prešutno ignorirano polje uči pozivatelja da polje radi. Prvi pozivatelj ga testira i vidi vlastite podatke; drugi šalje ID druge organizacije. Odbijanje na prvom zahtjevu jasno definira ugovor prije nego što itko išta izgradi na pogrešnom. Isto pravilo vrijedi za inputParams otpreme: ulaz vještine koji nosi ID organizacije odbija se pri otpremi.
Os jedinice se ili deklarira i provodi ili se ne koristi. Ruta koja deklarira needsUnit: true odbija zahtjev kada vjerodajnica ne razriješi jedinicu, uz unit naveden u missing[]. Nemojte sintetizirati jedinicu iz poddomene ili zaglavlja i nemojte postavljati zadanu vrijednost. Izmišljena jedinica postavlja ogradu drugačije od stvarnih jedinica organizacije i spaja retke koje ne bi smjela.
Površina koja ne može izraziti predikat odbija zahtjev
Ako ruta ne može odrediti kojem zakupcu i vlasniku pripada redak, te kojoj jedinici kada joj je potrebna, ona odbija zahtjev. Ne postoji čitanje na razini cijele organizacije kao pričuvna opcija niti postoji zamjenska vrijednost. Zamjenska vrijednost je najgora opcija, jer je zamjenska vrijednost ipak vrijednost, a vrijednosti se podudaraju s recima: usmjerivač alata koji je i zakupca i korisnika zadano postavio na niz 'unknown' posluživao je podatke cijele organizacije svakome tko ga je pozvao. Na granici zakupca, ?? 'unknown' je nedostatak.
Odbijanje ima jedan oblik posvuda na platformi i nosi dovoljno informacija da klijent može prikazati rješenje:
{
"error": true,
"code": "SCOPE_PREDICATE_MISSING",
"message": "Request cannot be scoped to a tenant from the presented credential.",
"resolved": ["tenant", "owner"],
"missing": ["unit"],
"troubleshooting": [
"The credential resolved tenant+owner; this route additionally requires a business unit.",
"Select a business unit in the client and retry — re-authentication will not change this outcome."
]
}error je uvijek true. code dolazi iz kataloga kodova platforme. resolved[] navodi osi koje su izvedene, a missing[] one koje je ruta trebala, ali ih nije mogla dobiti. troubleshooting[] govori što bi to zapravo popravilo. Golo „zabranjeno” nikoga ne uči ničemu.
Razlikujte 401 i 403, jer klijenti na njih reagiraju različito.
| Status | Značenje | Što klijent radi |
|---|---|---|
| 401 | Nije autentificiran | Ponovno se prijavljuje |
| 403 | Autentificiran, ali zahtjev se ne može ograničiti opsegom ili pozivatelju nedostaje pravo | Prestaje s ponovnim pokušajima i mijenja zahtjev |
Odbijanje opsega na koje je odgovoreno s 401 šalje klijenta u petlju prijave koju nijedna prijava ne može prekinuti: on odbacuje sesiju i ponovno se prijavljuje, ponovno pokušava i opet dobiva 401, dok osoba beskonačno gleda indikator učitavanja.
Još dva mehanizma čine odbijanje potpunim. Unutar rukovatelja, scopeOf(req) je jedini način za čitanje opsega, a on izbacuje iznimku ako se čuvar nije pokrenuo. Čuvar se pokreće nakon parsiranja tijela zahtjeva i prije bilo kojeg rukovatelja; rukovatelj koji postane dostupan bez predikata namjerno odgovara s 500 uz MIDDLEWARE_ORDERING_ERROR, tako da to završi u vašem proračunu pogrešaka umjesto u izvješću o incidentu.
Baza podataka samostalno drži istu liniju
Ograda u kodu i ograda u bazi podataka dva su mehanizma za jedan zakon, a vi dobivate oba.
Svaki izraz nad tablicom ograničenom opsegom sastavlja tenantFence(scope) iz SDK-a; predikat nikada ne pišete ručno. Svaki se izraz također izvršava unutar withScopedTx, koji veže tri osi za tu jednu transakciju putem jedne funkcije baze podataka i odbija drugo vezivanje (SCOPE_ALREADY_BOUND). Ispod toga, svaka tablica u vašoj shemi ima prisilno uključenu sigurnost na razini retka, a uloga s kojom se vaša putanja zahtjeva povezuje ne može sama promijeniti vezanog zakupca. Proces koji se povezuje kao uloga koja može zaobići sigurnost na razini retka odbija se pokrenuti uz DB_ROLE_BYPASSES_ISOLATION. Poglavlje 2.22, Izvršno okruženje dodatka, prikazuje kod; poglavlje 2.21, SDK za dodatke, pokazuje kako se uloge generiraju za vas.
Jedini prijelaz: zabilježeno odobrenje
Postoji točno jedan put preko granice zakupca. Organizacija koja drži retke bilježi odobrenje u kojem se navodi koja organizacija smije čitati koje tablice, prema kojem ugovoru i koliko dugo. Baza podataka čini to čitanje isključivo samo za čitanje, a svaki se uvid zapisuje prije samog čitanja, u obje organizacije, isključivo prema ID-ju. Pisanja nikada ne prelaze granicu; posao predan drugoj tvrtki putuje kao poruka. Uloge vlasnika i administratora uopće nikada ne čitaju preko granice, a manifest se odbija ako im pravo koje dopušta čitanje između organizacija to ne zabranjuje. Dodatak koji želi drugi put preko granice neće ga dobiti.
Pravilo 2: sva se obrada izvršava putem UNO otpreme
UNO, pogon radnih tijekova, jedina je putanja za izračun. Vaš kod nikada izravno ne dohvaća pružatelja modela ili pogon, kao ni red čekanja ili poslužitelj radnih tijekova. Šaljete jednu omotnicu na krajnju točku za otpremu i natrag dobivate 202 s identifikatorima; rezultat stiže prozivanjem (polling) ili povratnim pozivom (callback).
Iz toga proizlaze tri navike, a predložak već sadrži sve tri.
- Jedna datoteka posjeduje URL za otpremu.
UNO_DISPATCH_URLse čita jednom u učitavaču konfiguracije i mora biti adresa unutar klastera. Javna adresa se odbija pri pokretanju sustava, jer ništa ne napušta instalaciju. - Jedan zatvoreni popis dopuštenih stavki za ono što ova površina smije otpremiti. Pozadinski sustav koji će otpremiti bilo koji ID vještine koji mu preglednik preda zapravo je posrednik opće namjene za svaku vještinu u registru, uključujući vještine drugih dodataka i vještine koje troše tuđi proračun za modele. Popis je konstanta na razini modula koja sadrži vrste poslova s imenskim prostorom, a nikada varijabla okruženja. ID koji nije na popisu odbija se uz
SKILL_NOT_ALLOWED. - Ponovno provjerite ono što se vrati. Kada pročitate povratni rezultat posla, klijent SDK-a uspoređuje
organization_idvraćenog retka sa zakupcem pozivatelja na vašoj strani mrežnog poziva. Ograda koja postoji samo s druge strane poziva samo je konvencija.
Pravilo 3: sav AI prolazi kroz usmjerivač pružatelja AI-ja
Dodatak nigdje ne upućuje pozive modelu. Nema SDK-a pružatelja u package.json, nema ključa modela u okruženju i nema releja. Isključivo usmjerivač drži vjerodajnicu pružatelja organizacije i donosi konačnu odluku o pružatelju i modelu.
Ono što dodatak smije učiniti jest izraziti želje, u trenutku registracije, u retku registra za vještinu iz manifesta:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}Usmjerivač poštuje želju samo kada organizacija ima tog pružatelja omogućenog i s valjanim vjerodajnicama. U suprotnom vrši zamjenu iz vlastitog skupa organizacije. capabilityProfile nikada ne odabire; on filtrira, a njegovo polje dataResidency čvrsto je jurisdikcijsko ograničenje koje usmjerivač ili zadovoljava ili odbija. Izostavljanje svega navedenog ispravna je zadana postavka za većinu vještina: tada odlučuju vlastite dodjele uloga organizacije, a organizacija je ta koja plaća.
Vraćaju se dvije vrste odbijanja, a znače vrlo različite stvari.
| Kod | Status | Što to znači |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | Vaš je kod pokušao sam pozvati usmjerivač. Stanite: ovo je spoj koji odbija po samom dizajnu i ne može se ponovno pokušati |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Nijedan omogućeni pružatelj nema model koji zadovoljava profil. Ublažite profil ili neka organizacija omogući sposobnog pružatelja |
NO_PROVIDER_FOR_ROLE |
422 | Organizacija nije konfigurirala usmjeravanje za ovu ulogu. Prikažite osobi tekst usmjerivača za otklanjanje problema |
Drugi par pripada na zaslon, a ne u zapisnik. Nema zadanog modela i nema pričuvnog pružatelja: uloga koju organizacija nije postavila glasno zakazuje, uz rečenicu koja govori što treba konfigurirati.
Jedino čitanje koje dodatak smije izvršiti nad usmjerivačem je effectiveRoute() iz runtime/ai-route. Ono odgovara kojeg bi pružatelja i model usmjerivač odabrao za prijavljenu organizaciju bez slanja AI zahtjeva, a vraća odbijanje usmjerivača riječima kada modela nema. Poglavlje 2.22, Izvršno okruženje dodatka, to prikazuje.
Ljestvica povjerenja dodaje još jednu granicu. Samo core i verified dodaci smiju deklarirati dvije razine vještina u manifestu koje dosežu usmjerivač, tool_using i llm_only. Svi ostali posreduju u determinističkom poslu i prepuštaju platformi dio koji doseže modele.
Pravilo 4: ključevi pripadaju organizaciji
Svaka organizacija donosi vlastiti račun i ključ pružatelja te plaća vlastiti račun. Ključ se nalazi u skupu AI pružatelja organizacije, kojim upravljaju njezini vlastiti administratori iz konzole, a usmjerivač ga razrješava u trenutku poziva. Iza zakupca ne postoji dijeljeni ključ platforme, tako da nijedna organizacija ne troši tuđi proračun.
Za proširenje to znači tri stvari.
- Nikada ne držite ključ modela, bilo u kodu, konfiguraciji ili spremištu tajni. Kontrolna točka
no-credentialsruši izgradnju ako je ključ čitljiv, a učitavač konfiguracije odbija pokrenuti sustav ako je prisutan. - Nikada ne nabrajate ključeve organizacije. Ako vaš dodatak misli da to treba učiniti, zahtjev je na pogrešnom mjestu.
- Organizacija bez ključa ne dobiva nikakve AI odgovore. To je očekivano stanje sa stvarnim zaslonom. Navedite ulogu koja nedostaje i citirajte upute za otklanjanje problema, a zatim uputite osobu na njezine postavke pružatelja. Nemojte to prikazati kao prazan rezultat.
Pravilo 5: licencirane značajke provjeravaju se prema licenciji
Ono što instalacija smije koristiti iznad osnovne razine Community dolazi s jednog mjesta: iz dokumenta licence koji potpisuje Adverant, a koji se na instalaciji verificira isključivo javnim ključevima. Vaše proširenje nikada ne donosi odluke na temelju nečeg slabijeg, poput naziva plana u tokenu ili zastavice u konfiguraciji.
U dodatku je najjednostavniji način povezivanja značajke s licencom na samom pravu koje je čuva. Pravo u registru rights manifesta može imenovati značajku licence:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Tko god pozove rutu čuvanu tim pravom biva odbijen uz LICENCE_LOCKED (403), bez obzira na uloge i mjesta koja drži, kada licenca organizacije ne sadrži compliance-packs. Odbijanje navodi značajku i ono što je nosi te govori tko je može uključiti.
Stanje licence također je važno. Dok je licenca valjana ili u razdoblju upozorenja, licencirane značajke rade, a nastavljaju raditi i u počeku (grace period), pri čemu poček prikazuje obavijest LICENCE_IN_GRACE. Nakon što licenca istekne izvan počeka, ona uvodi ograničenja: poslovi u tijeku i čitanja se nastavljaju, kao i izvozi te sigurnosna ažuriranja, ali stvaranje nečeg novog pod licenciranom značajkom odbija se uz LICENCE_LOCKED. Izgradite svoje putanje za stvaranje očekujući taj odgovor.
Kada vaš dodatak pita provjeru ovlaštenja drži li organizacija određenu značajku, dobiva presudu, a nikada golu Booleovu vrijednost. „Nije dostupno” i „dostupno i ne” različite su činjenice s različitim kodovima: ENTITLEMENT_UNREACHABLE (502) i ENTITLEMENT_DENIED (403). Kratkotrajni prekid dostupnosti nikada ne smije tiho spustiti svakog korisnika na besplatnu osnovnu razinu.
MANIFEST_SCOPE_WIDENED dok se dva recenzenta i službenik za usklađenost ne slože.Manifest ponovno potvrđuje pravilo
Svaki v2 manifest nosi blok architecture s tri obavezne rečenice, a validator fiksira njihov točan tekst. U dodatku koji gradite za vlastitu instalaciju one glase:
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}Te se rečenice provjeravaju. Dodatak čiji je manifest pristao na zakone dok je njegov kod dohvaćao pružatelja modela lagao bi u vlastitom ugovoru, a kontrolne točke postoje kako bi tu laž učinile uočljivom.
Kontrolne točke koje provode svako pravilo
SDK isporučuje dvadeset i dvije kontrolne točke pridržavanja pravila kao jednu naredbu, nexus-gates. Poglavlje 2.21, SDK za dodatke, opisuje svaku od njih. Ovdje su grupirane prema pravilu koje provode.
| Pravilo | Kontrolne točke | Što ruši izgradnju |
|---|---|---|
| Izolacija u sloju ruta | scope-adherence, one-fence, rights-register, crud-adherence |
Ruta /api bez čuvara opsega, drugi ručno pisani predikat zakupca, ruta opsega bez prava, mutirajuća ruta čije pravo ne navodi ništa |
| Izolacija u SQL-u | sql-fence, no-set-config |
Izraz nad tablicom ograničenom opsegom bez ograde; kod dodatka koji sam veže postavku zakupca |
| Izolacija u bazi podataka | migrations-are-scoped, rls-present, db-role-honest |
Tablica kojoj nedostaje os ili ključ koji počinje zakupcem, tablica bez prisilne sigurnosti na razini retka, putanja zahtjeva koja se povezuje kao vlasnik ili superkorisnik |
| Jedini prijelaz | grants-declared |
Tablica odobrena u migracijama koju manifest ne deklarira ili mjesto za čitanje kojem su privilegije dodijeljene ručno |
| Izračun putem sustava UNO | no-direct-compute |
Izravno dohvaćanje pružatelja modela ili pogona, ili reda čekanja ili poslužitelja radnih tijekova; drugi čitač URL-a za otpremu |
| AI i ključevi | no-credentials |
Vjerodajnica pružatelja modela čitljiva u repozitoriju ili okruženju |
| Deklarirani ugovor | api-contract, platform-clients, declared-input |
Ruta koja je registrirana, ali nije deklarirana, ili je deklarirana, ali nije registrirana; klijent platforme koji je uvezen, ali nije naveden |
Svaka kontrolna točka ima samotestiranje koje dokazuje da pada na testnom uzorku izgrađenom da je aktivira. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test ih pokreće sve, a kontrolna točka koja je prestala padati na vlastitom testnom uzorku prestala je raditi.
Prije nego što zatražite pregled
Ovo je popis koji prolazim prije nego što zamolim kolegu da pregleda dodatak. Svaka stavka je nešto što mi je recenzent u tvrtki Corrán Orbital vratio barem jednom.
- Svaka
/apiruta registrira čuvara opsega, a jedine anonimne rute su točne putanje deklarirane kaoauth: publicuzallowAnonymous: true. - Svaka ruta koju poslužuje čuvar opsega navodi
rightiz registra manifesta, a nijedan rukovatelj ne nosi vlastitu provjeru prava. - Nijedan rukovatelj ne čita organizaciju, osobu ili jedinicu iz tijela zahtjeva, upita ili zaglavlja.
- Svaki izraz nad tablicom ograničenom opsegom prolazi kroz
tenantFenceunutarwithScopedTx, a ništa u repozitoriju ne pozivaset_config. - Svaka tablica ima tri stupca osi, primarni ključ koji počinje s
organization_idi složene strane ključeve koji nose zakupca. - URL za otpremu čita se u jednoj datoteci, a popis dopuštenih stavki za otpremu je konstanta vrsta poslova s imenskim prostorom.
- Ništa u
package.jsonne komunicira s pružateljem modela i nijedan se ključ ne nalazi u okruženju. - Svaka značajka koju nose samo neke licence navodi svoj
licencena pravu koje je čuva. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testje u zelenom, baš kao inpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.
Ako vrijedi svih devet stavki, pregled se bavi vašim proizvodom, na što bi vrijeme recenzenta i trebalo ići.
Zašto platforma provodi ova pravila
Svako gore navedeno pravilo nekoć je negdje bilo konvencija, i svaka je konvencija zakazala na isti način: rute koje su je zapamtile bile su u redu, a ona koja ju je zaboravila postala je incident. Ograda poslovne jedinice primijenjena kao opcionalni posredni sloj (middleware) zaobiđena je na šest neovisnih načina, pri čemu je svaki bio ruta koja se nikada nije uključila. Varijabla okruženja koja je prepisivala identitet zakupca poslužila je jednoj organizaciji 1.406 kontakata druge organizacije, a na pregledu je izgledala ispravno jer je bila ispravna za pod za koji je napisana.
Stoga platforma postavlja predikat tamo gdje svaka površina već prolazi kroz njega: u čuvara opsega i funkciju ograde, u omotač transakcije i prisilnu sigurnost na razini retka te u klijenta za otpremu. Kontrolna točka zatim nabraja svaku rutu, svaki izraz i svaki uvoz te ruši izgradnju kada jedan od njih dosegne tablicu ograničenu opsegom, model ili pogon za izračun bez prolaska kroz te mehanizme. Cijena takvog dizajna je osjećaj ograničenosti pri izradi vašeg prvog dodatka. Dobitak je to što je tisućiti dodatak izoliran a da njegov autor uopće ne zna da ta značajka postoji, jer ne postoji druga putanja do podataka kojom bi mogao krenuti.
Postoji iskrena granica svega ovoga. Kontrolne točke dokazuju da vaš kod prolazi kroz mehanizme; one ne mogu dokazati da je logika vašeg proizvoda ispravna. Ruta koja ispravno ograničava upit na retke vlasnika još uvijek može prikazati pogrešne retke pravom vlasniku. Komplet za testiranje izolacije u poglavlju 2.22, Izvršno okruženje dodatka, napada svaku rutu kao druga organizacija i kao kolega, uklanjajući redom svaku ogradu, i to je test koji bih pokrenuo prije nego što bih povjerovao vlastitom tumačenju bilo čega od navedenog.

