OmniRoute/docs/i18n/sk/CLAUDE.md

CLAUDE.md (Slovenčina)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

Tento súbor poskytuje pokyny pre Claude Code (claude.ai/code) pri práci s kódom v tomto repozitári.

Rýchly štart

npm install                    # Nainštalujte závislosti (automaticky generuje .env z .env.example)
npm run dev                    # Vývojový server na http://localhost:20128
npm run build                  # Produkčná zostava (Next.js 16 samostatne)
npm run lint                   # ESLint (očakáva sa 0 chýb; varovania sú predchádzajúce)
npm run typecheck:core         # Kontrola TypeScript (mala by byť čistá)
npm run typecheck:noimplicit:core  # Prísna kontrola (žiadne implicitné any)
npm run test:coverage          # Jednotkové testy + pokrytie (75/75/75/70 — vyhlásenia/riadky/funkcie/vetvy)
npm run check                  # kombinácia lint + test
npm run check:cycles           # Detekcia cyklických závislostí

Spúšťanie testov

# Jediný testovací súbor (nativný testovací bežec Node.js — väčšina testov)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP server, autoCombo, cache)
npm run test:vitest

# Všetky sady
npm run test:all

Pre úplnú testovaciu maticu pozrite CONTRIBUTING.md → "Spúšťanie testov". Pre hlbokú architektúru pozrite AGENTS.md.

---

Projekt na prvý pohľad

OmniRoute — unified AI proxy/router. Jeden koncový bod, 160+ poskytovateľov LLM, automatické zálohovanie.

Vrstva	Umiestnenie	Účel
API Routes	src/app/api/v1/	Next.js App Router — vstupné body
Handlers	open-sse/handlers/	Spracovanie požiadaviek (chat, embeddings, atď.)
Executors	open-sse/executors/	HTTP dispatch špecifický pre poskytovateľa
Translators	open-sse/translator/	Konverzia formátu (OpenAI↔Claude↔Gemini)
Transformer	open-sse/transformer/	API odpovedí ↔ Chat Completions
Services	open-sse/services/	Kombinované smerovanie, obmedzenia rýchlosti, caching, atď.
Database	src/lib/db/	SQLite doménové moduly (45+ súborov, 55 migrácií)
Domain/Policy	src/domain/	Engin politiky, pravidlá nákladov, logika zálohovania
MCP Server	open-sse/mcp-server/	37 nástrojov (30 základných + 3 pamäť + 4 zručnosti), 3 prenosy, ~13 rozsahov
A2A Server	src/lib/a2a/	JSON-RPC 2.0 agent protokol
Skills	src/lib/skills/	Rozšíriteľný rámec zručností
Memory	src/lib/memory/	Trvalá konverzačná pamäť

Monorepo: src/ (Next.js 16 aplikácia), open-sse/ (pracovisko streaming engine), electron/ (desktopová aplikácia), tests/, bin/ (CLI vstupný bod).

---

Žiadosť Pipeline

Klient → /v1/chat/completions (Next.js trasa)
  → CORS → Zod validácia → autentifikácia? → kontrola politiky → ochrana proti injekcii promptu
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → kontrola cache → limitovanie požiadaviek → combo routing?
      → resolveComboTargets() → handleSingleModel() pre cieľ
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → preklad odpovede → SSE stream alebo JSON
    → Ak Responses API: responsesTransformer.ts TransformStream

API trasy nasledujú konzistentný vzor: Trasa → CORS preflight → Zod validácia tela → Voliteľná autentifikácia (extractApiKey/isValidApiKey) → Vynucovanie politiky API kľúča → Delegovanie handlera (open-sse). Žiadne globálne Next.js middleware — interceptácia je špecifická pre trasu.

Combo routing (open-sse/services/combo.ts): 14 stratégií (priorita, vážené, fill-first, round-robin, P2C, náhodné, najmenej používané, optimalizované náklady, reset-aware, strict-random, auto, lkgp, optimalizované pre kontext, kontext-relay). Každý cieľ volá handleSingleModel(), ktorý obalí handleChatCore() s chybovým spracovaním pre každý cieľ a kontrolami obvodu. Pozrite sa na docs/routing/AUTO-COMBO.md pre 9-faktorové hodnotenie Auto-Combo a docs/architecture/RESILIENCE_GUIDE.md pre 3 vrstvy odolnosti.

---

Stav odolnosti v čase behu

OmniRoute má tri súvisiace, ale odlišné mechanizmy dočasného zlyhania. Udržujte ich rozsah oddelený pri ladení správania routingu. Pozrite sa na diagram odolnosti s 3 vrstvami (zdroj: docs/diagrams/resilience-3layers.mmd) pre rýchly prehľad.

Obvod poskytovateľa

Rozsah: celý poskytovateľ, napr. glm, openai, anthropic.

Účel: zastaviť posielanie prevádzky k poskytovateľovi, ktorý opakovane zlyháva na úrovni upstream/služby, aby jeden nezdravý poskytovateľ nezpomalil každú požiadavku.

Implementácia:

• Hlavná trieda: src/shared/utils/circuitBreaker.ts
• Chat gate/exekučné zapojenie: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• API stavu behu: src/app/api/monitoring/health/route.ts
• Zdieľané obaly: open-sse/services/accountFallback.ts
• Persistovaná stavová tabuľka: domain_circuit_breakers

Stavy:

• CLOSED: normálna prevádzka je povolená.
• OPEN: poskytovateľ je dočasne zablokovaný; volajúci dostanú odpoveď provider-circuit-open alebo combo routing preskočí na iný cieľ.
• HALF_OPEN: uplynul časový limit resetu; povoliť probe požiadavku. Úspech uzatvára obvod, zlyhanie ho opäť otvára.

Predvolené hodnoty (open-sse/config/constants.ts):

• OAuth poskytovatelia: prah 3, reset timeout 60s.
• API-kľúč poskytovatelia: prah 5, reset timeout 30s.
• Lokálni poskytovatelia: prah 2, reset timeout 15s.

Iba stavy zlyhania na úrovni poskytovateľa by mali spustiť obvod poskytovateľa:

(408, 500, 502, 503, 504);

Nespúšťajte obvod celého poskytovateľa pre normálne chyby účtu/kľúča/modelu ako väčšina 401, 403, alebo 429 prípadov. Tieto zvyčajne patrí do cooldown pripojenia alebo uzamknutia modelu. Generický API-kľúč poskytovateľa 403 by mal byť obnoviteľný, pokiaľ nie je klasifikovaný ako terminálna chyba poskytovateľa/účtu.

Obvod používa lenivú obnovu, nie časovač na pozadí. Keď OPEN vyprší, čítania ako getStatus(), canExecute(), a getRetryAfterMs() obnovujú stav na HALF_OPEN, takže panely a stavitelia kandidátov na combo nebudú navždy vylučovať vypršaného poskytovateľa.

Cooldown pripojenia

Rozsah: jedno pripojenie účtu/kľúča poskytovateľa.

Účel: dočasne preskočiť jeden zlý kľúč/účet, zatiaľ čo ostatné pripojenia pre rovnakého poskytovateľa môžu pokračovať v obsluhe požiadaviek.

Implementácia:

• Cesta zápisu/aktualizácie: src/sse/services/auth.ts::markAccountUnavailable()
• Výber/filtrácia účtu: src/sse/services/auth.ts::getProviderCredentials...
• Výpočet cooldownu: open-sse/services/accountFallback.ts::checkFallbackError()
• Nastavenia: src/lib/resilience/settings.ts

Dôležité polia na pripojeniach poskytovateľa:

rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;

Počas výberu účtu je pripojenie preskočené, keď:

new Date(rateLimitedUntil).getTime() > Date.now();

Cooldowny sú tiež lenivé: keď je rateLimitedUntil v minulosti, pripojenie sa opäť stáva oprávneným. Pri úspešnom použití clearAccountError() vymaže testStatus, rateLimitedUntil, chybové polia a backoffLevel.

Predvolené správanie cooldownu pripojenia:

• Základný cooldown OAuth: 5s.
• Základný cooldown API-kľúča: 3s.
• API-kľúč 429 by mal uprednostniť upstream retry hints (Retry-After, reset hlavičky, alebo analyzovateľný reset text) keď sú k dispozícii.
• Opakované obnoviteľné zlyhania používajú exponenciálne backoff:

baseCooldownMs * 2 ** failureIndex;

Ochrana proti hromadnému zlyhaniu zabraňuje súbežným zlyhaniam na rovnakom pripojení od opakovaného predlžovania cooldownu alebo dvojitého zvyšovania backoffLevel.

Terminálne stavy nie sú cooldowny. banned, expired, a credits_exhausted sú určené na to, aby zostali nedostupné, kým sa nezmenia poverenia/nastavenia alebo kým ich operátor neobnoví. Neprepisujte terminálne stavy do prechodného cooldown stavu.

Uzamknutie modelu

Rozsah: poskytovateľ + pripojenie + model.

Účel: vyhnúť sa deaktivácii celého pripojenia, keď je nedostupný iba jeden model alebo kvótovo obmedzený pre to pripojenie.

Príklady:

• Poskytovatelia s kvótou na model, ktorí vracajú 429.
• Lokálni poskytovatelia vracajúci 404 pre jeden chýbajúci model.
• Zlyhania povolenia režimu/modelu špecifické pre poskytovateľa, ako sú vybrané režimy Grok.

Uzamknutie modelu žije v open-sse/services/accountFallback.ts a umožňuje rovnakému pripojeniu pokračovať v obsluhe iných modelov.

Pokyny na ladenie

• Ak sú všetky kľúče pre poskytovateľa preskočené, skontrolujte stav obvodu poskytovateľa a každý stav rateLimitedUntil/testStatus.
• Ak sa poskytovateľ zdá byť trvalo vylúčený po resetovom okne, skontrolujte, či kód číta surový state namiesto používania getStatus()/canExecute().
• Ak jeden kľúč poskytovateľa zlyhá, ale ostatné by mali fungovať, uprednostnite cooldown pripojenia pred obvodom poskytovateľa.
• Ak zlyhá iba jeden model, uprednostnite uzamknutie modelu pred cooldownom pripojenia.
• Ak by sa mal stav sám obnoviť, mal by mať budúci časový pečiatok/reset timeout a čítaciu cestu, ktorá obnovuje vypršaný stav. Trvalé stavy vyžadujú manuálne zmeny poverení alebo konfigurácie.

Kľúčové konvencie

Štýl kódu

• 2 medzery, bodkočiarky, dvojité úvodzovky, šírka 100 znakov, es5 koncové čiarky (vynútené lint-staged cez Prettier)
• Importy: externé → interné (@/, @omniroute/open-sse) → relatívne
• Názvy: súbory=camelCase/kebab, komponenty=PascalCase, konštanty=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = chyba všade; no-explicit-any = varovanie v open-sse/ a tests/
• TypeScript: strict: false, cieľ ES2022, modul esnext, rozlíšenie bundler. Preferujte explicitné typy.

Databáza

• Vždy prechádzajte cez src/lib/db/ doménové moduly — nikdy nepíšte surové SQL v trasách alebo obslužných funkciách
• Nikdy nepridávajte logiku do src/lib/localDb.ts (iba re-exportná vrstva)
• Nikdy neimportujte z localDb.ts — namiesto toho importujte konkrétne db/ moduly
• DB singleton: getDbInstance() z src/lib/db/core.ts (WAL žurnálovanie)
• Migrácie: src/lib/db/migrations/ — verzionované SQL súbory, idempotentné, spúšťané v transakciách

Správa chýb

• try/catch so špecifickými typmi chýb, logujte s kontextom pino
• Nikdy nezahŕňajte chyby v SSE prúdoch — použite signály na zrušenie na vyčistenie
• Vráťte správne HTTP stavové kódy (4xx/5xx)

Bezpečnosť

• Nikdy nepoužívajte eval(), new Function(), alebo implicitné eval
• Validujte všetky vstupy pomocou Zod schém
• Šifrujte poverenia v pokoji (AES-256-GCM)
• Zoznam hlavičiek na zamietnutie: src/shared/constants/upstreamHeaders.ts — udržujte sanitáciu, Zod schémy a jednotkové testy v súlade pri úpravách
• Verejné upstream poverenia (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web kľúče extrahované z verejných CLI): MUSIA byť vložené cez resolvePublicCred() z open-sse/utils/publicCreds.ts — nikdy ako reťazcové literály. Pozrite docs/security/PUBLIC_CREDS.md pre povinný vzor.
• Odpovede na chyby (HTTP / SSE / executor / MCP obslužná funkcia): MUSIA prechádzať cez buildErrorBody() alebo sanitizeErrorMessage() z open-sse/utils/error.ts — nikdy nevkladajte surové err.stack alebo err.message do tela odpovede. Pozrite docs/security/ERROR_SANITIZATION.md.
• Shell príkazy vytvorené z premenných: pri volaní exec()/spawn() so skriptom, ktorý potrebuje hodnoty za behu, preneste ich cez možnosť env (automaticky shell-escaped) — nikdy neinterpolujte nespoľahlivé/externe cesty do tela skriptu. Referencia: src/mitm/cert/install.ts::updateNssDatabases.
• Knižnice zabezpečené predvolene (tldrsec/awesome-secure-defaults): uprednostnite Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink pred vlastnými implementáciami vždy, keď pridávate nové povrchy citlivé na bezpečnosť.

---

Bežné scenáre úprav

Pridanie nového poskytovateľa

1. Zaregistrujte v src/shared/constants/providers.ts (Zod-validated pri načítaní)
2. Pridajte executor v open-sse/executors/, ak je potrebná vlastná logika (rozšírte BaseExecutor)
3. Pridajte prekladateľa v open-sse/translator/, ak nie je vo formáte OpenAI
4. Pridajte OAuth konfiguráciu v src/lib/oauth/constants/oauth.ts, ak je založená na OAuth — ak upstream CLI dodáva verejný client_id/secret, vložte cez resolvePublicCred() (pozrite docs/security/PUBLIC_CREDS.md), nikdy ako literál
5. Zaregistrujte modely v open-sse/config/providerRegistry.ts
6. Napíšte testy v tests/unit/ (zahrňte asertáciu tvaru publicCreds, ak ste pridali nový vložený predvolený)

Pridanie novej API trasy

1. Vytvorte adresár pod src/app/api/v1/your-route/
2. Vytvorte route.ts s obslužnými funkciami GET/POST
3. Dodržujte vzor: CORS → Zod validácia tela → voliteľná autentifikácia → delegácia obslužnej funkcie
4. Obslužná funkcia ide do open-sse/handlers/ (importujte odtiaľ, nie inline)
5. Odpovede na chyby používajú buildErrorBody() / errorResponse() z open-sse/utils/error.ts (automaticky sanitizované — nikdy nevkladajte surové err.stack alebo err.message do tela). Pozrite docs/security/ERROR_SANITIZATION.md.
6. Pridajte testy — vrátane aspoň jednej asertácie, že odpovede na chyby neunikajú stopy zásobníka (!body.error.message.includes("at /"))

Pridanie nového DB modulu

1. Vytvorte src/lib/db/yourModule.ts — importujte getDbInstance z ./core.ts
2. Exportujte CRUD funkcie pre vaše doménové tabuľky
3. Pridajte migráciu v src/lib/db/migrations/, ak sú potrebné nové tabuľky
4. Re-exportujte z src/lib/localDb.ts (pridajte iba do zoznamu re-exportov)
5. Napíšte testy

Pridanie nového MCP nástroja

1. Pridajte definíciu nástroja v open-sse/mcp-server/tools/ so Zod vstupnou schémou + asynchrónnou obslužnou funkciou
2. Zaregistrujte v súbore nástrojov (prepojené cez createMcpServer())
3. Priraďte k príslušným rozsahom
4. Napíšte testy (vyvolanie nástroja sa zaznamenáva do tabuľky mcp_audit)

Pridanie novej A2A zručnosti

1. Vytvorte zručnosť v src/lib/a2a/skills/ (už existujú 5: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Zručnosť prijíma kontext úlohy (správy, metadata) → vracia štruktúrovaný výsledok
3. Zaregistrujte v A2A_SKILL_HANDLERS v src/lib/a2a/taskExecution.ts
4. Exponujte v src/app/.well-known/agent.json/route.ts (Agent Card)
5. Napíšte testy v tests/unit/
6. Dokumentujte v docs/frameworks/A2A-SERVER.md tabuľku zručností

Pridanie nového cloud agenta

1. Vytvorte triedu agenta v src/lib/cloudAgent/agents/ rozširujúcu CloudAgentBase (už existujú 3: codex-cloud, devin, jules)
2. Implementujte createTask, getStatus, approvePlan, sendMessage, listSources
3. Zaregistrujte v src/lib/cloudAgent/registry.ts
4. Pridajte spracovanie OAuth/poverenia, ak je to potrebné (src/lib/oauth/providers/)
5. Testy + dokumentujte v docs/frameworks/CLOUD_AGENT.md

Pridanie nového guardrailu / eval / zručnosti / webhook udalosti

• Guardrail: src/lib/guardrails/ → dokumenty: docs/security/GUARDRAILS.md
• Eval súprava: src/lib/evals/ → dokumenty: docs/frameworks/EVALS.md
• Zručnosť (sandbox): src/lib/skills/ → dokumenty: docs/frameworks/SKILLS.md
• Webhook udalosť: src/lib/webhookDispatcher.ts → dokumenty: docs/frameworks/WEBHOOKS.md

Referenčná dokumentácia

Pre akúkoľvek netriviálnu zmenu si najprv prečítajte zodpovedajúci hĺbkový pohľad:

Oblasť	Dokument
Navigácia v repozitári	docs/architecture/REPOSITORY_MAP.md
Architektúra	docs/architecture/ARCHITECTURE.md
Referencia inžinierstva	docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-faktorové hodnotenie, 14 stratégií)	docs/routing/AUTO-COMBO.md
Odolnosť (3 mechanizmy)	docs/architecture/RESILIENCE_GUIDE.md
Opakovanie uvažovania	docs/routing/REASONING_REPLAY.md
Rámec zručností	docs/frameworks/SKILLS.md
Systém pamäte (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
Cloudové agenti	docs/frameworks/CLOUD_AGENT.md
Ochranné opatrenia (PII / injekcia / vízia)	docs/security/GUARDRAILS.md
Verejné poverenia upstream (Gemini/atď.)	docs/security/PUBLIC_CREDS.md
Sanitizácia chybových hlásení	docs/security/ERROR_SANITIZATION.md
Vyhodnotenia	docs/frameworks/EVALS.md
Dodržiavanie / audit	docs/security/COMPLIANCE.md
Webhooky	docs/frameworks/WEBHOOKS.md
Autorizačný pipeline	docs/architecture/AUTHZ_GUIDE.md
Neviditeľnosť (TLS / odtlačok)	docs/security/STEALTH_GUIDE.md
Protokoly agentov (A2A / ACP / Cloud)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP server	docs/frameworks/MCP-SERVER.md
A2A server	docs/frameworks/A2A-SERVER.md
Referencia API + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Katalóg poskytovateľov (automaticky generovaný)	docs/reference/PROVIDER_REFERENCE.md
Tok vydania	docs/ops/RELEASE_CHECKLIST.md

Testovanie

Čo	Príkaz
Jednotkové testy	npm run test:unit
Jediný súbor	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
Protokol E2E (MCP+A2A)	npm run test:protocols:e2e
Ekosystém	npm run test:ecosystem
Pokrytie	npm run test:coverage (75/75/75/70 — vyhlásenia/riadky/funkcie/vetvy)
Správa pokrytia	npm run coverage:report

PR pravidlo: Ak zmeníte produkčný kód v src/, open-sse/, electron/ alebo bin/, musíte zahrnúť alebo aktualizovať testy v tej istej PR.

Preferencia testovacej vrstvy: najprv jednotkové → integrácia (multi-modulový alebo DB stav) → e2e (iba UI/workflow). Kódy reprodukcií chýb zakódujte ako automatizované testy pred alebo spolu s opravou.

Politika pokrytia Copilot: Keď PR mení produkčný kód a pokrytie je pod 75% (vyhlásenia/riadky/funkcie) alebo 70% (vetvy), nehláste len — pridajte alebo aktualizujte testy, znovu spustite pokrytie, potom požiadajte o potvrdenie. Zahrňte spustené príkazy, zmenené testovacie súbory a konečný výsledok pokrytia v správe PR.

---

Git Workflow

# Nikdy nekomitujte priamo do main
git checkout -b feat/your-feature
git commit -m "feat: popíšte svoju zmenu"
git push -u origin feat/your-feature

Prefixy vetiev: feat/, fix/, refactor/, docs/, test/, chore/

Formát commitu (Conventional Commits): feat(db): pridať obvodový spínač — rozsahy: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky hooky:

• pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
• pre-push: npm run test:unit

---

Prostredie

• Runtime: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES moduly
• TypeScript: 5.9+, cieľ ES2022, modul esnext, rozlíšenie bundler
• Cestné aliasy: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• Predvolený port: 20128 (API + dashboard na rovnakom porte)
• Adresár dát: DATA_DIR env var, predvolene ~/.omniroute/
• Kľúčové env vars: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• Nastavenie: cp .env.example .env potom vygenerujte JWT_SECRET (openssl rand -base64 48) a API_KEY_SECRET (openssl rand -hex 32)

---

Tvrdé pravidlá

1. Nikdy nekomitujte tajomstvá alebo poverenia
2. Nikdy nepridávajte logiku do localDb.ts
3. Nikdy nepoužívajte eval() / new Function() / implicitné eval
4. Nikdy nekomitujte priamo do main
5. Nikdy nepíšte surové SQL v trasách — používajte moduly src/lib/db/
6. Nikdy ticho nezachytávajte chyby v SSE prúdoch
7. Vždy validujte vstupy pomocou Zod schém
8. Vždy zahrňte testy pri zmene produkčného kódu
9. Pokrytie musí zostať ≥75% (vyhlásenia, riadky, funkcie) / ≥70% (vetvy). Aktuálne merané: ~82%.
10. Nikdy neobchádzajte Husky hooky (--no-verify, --no-gpg-sign) bez explicitného schválenia operátora.
11. Nikdy nezahŕňajte verejné upstream OAuth client_id/secret alebo Firebase Web kľúče ako reťazcové literály — vždy prechádzajte cez resolvePublicCred() (open-sse/utils/publicCreds.ts). Pozrite docs/security/PUBLIC_CREDS.md.
12. Nikdy nevracajte surové err.stack / err.message v HTTP / SSE / executor odpovediach — vždy prechádzajte cez buildErrorBody() alebo sanitizeErrorMessage() (open-sse/utils/error.ts). Pozrite docs/security/ERROR_SANITIZATION.md.
13. Nikdy neinterpolujte externé cesty alebo hodnoty runtime do shell skriptov odovzdaných do exec()/spawn() — namiesto toho ich odovzdajte cez možnosť env. Referencia: src/mitm/cert/install.ts::updateNssDatabases.
14. Nikdy neignorujte upozornenie CodeQL / Secret-Scanning bez (a) najprv skontrolovania dokumentov vzoru vyššie, aby ste zistili, či sa pomocník uplatňuje, a (b) zaznamenania technického odôvodnenia v komentári o zamietnutí. Precedens: js/stack-trace-exposure vyvolané na miestach volania, ktoré už prechádzajú cez sanitizeErrorMessage() je známa obmedzenie CodeQL (vlastné sanitizéry nie sú rozpoznané) — zamietnite ako false positive s odkazom na docs/security/ERROR_SANITIZATION.md.
15. Nikdy nezverejňujte trasy, ktoré spúšťajú podprocesy (/api/mcp/, /api/cli-tools/runtime/) bez klasifikácie isLocalOnlyPath() v src/server/authz/routeGuard.ts. Presadzovanie loopback sa deje bezpodmienečne pred akoukoľvek autentifikačnou kontrolou — uniknutý JWT cez tunel nemôže spustiť proces. Pozrite docs/security/ROUTE_GUARD_TIERS.md.
16. Nikdy nezahŕňajte prívesy Co-Authored-By, ktoré pripisujú zásluhy AI asistentovi, LLM alebo automatizačnému účtu (napr. mená obsahujúce "Claude", "GPT", "Copilot", "Bot"; e-maily na anthropic.com / openai.com / adresách noreply.github.com vlastnených botmi). Takéto prívesy smerujú atribúciu commitov k bot účtu na GitHube, čím skrývajú skutočného autora (diegosouzapw) v histórii PR. Ľudskí spolupracovníci — vrátane autorov upstream PR a hlásateľov issues portovaných do OmniRoute — MÔŽU a MALI BY byť uvedení štandardnými prívesmi Co-authored-by: Name <email>; pracovné toky upstream-port (/port-upstream-features, /port-upstream-issues) na tom závisia.