wehub/diegosouzapw--omniroute
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
diegosouzapw--omniroute/docs/i18n/sk/CLAUDE.md
T
wehub-resource-sync d8dcd5f6d1 chore: import upstream snapshot with attribution
2026-07-13 13:39:12 +08:00

27 KiB
Raw Permalink Blame History

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.
Reference in New Issue View Git Blame Copy Permalink