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/ro/CLAUDE.md
T
wehub-resource-sync d8dcd5f6d1 chore: import upstream snapshot with attribution
2026-07-13 13:39:12 +08:00

28 KiB
Raw Permalink Blame History

CLAUDE.md (Română)

🌐 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 · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

Acest fișier oferă îndrumări pentru Claude Code (claude.ai/code) atunci când se lucrează cu cod în acest depozit.

Începere rapidă

npm install                    # Instalează dependențele (generează automat .env din .env.example)
npm run dev                    # Server de dezvoltare la http://localhost:20128
npm run build                  # Build de producție (Next.js 16 standalone)
npm run lint                   # ESLint (0 erori așteptate; avertizările sunt preexistente)
npm run typecheck:core         # Verificare TypeScript (ar trebui să fie curat)
npm run typecheck:noimplicit:core  # Verificare strictă (fără implicit any)
npm run test:coverage          # Teste unitare + prag de acoperire (75/75/75/70 — declarații/linii/funcții/ramuri)
npm run check                  # lint + test combinate
npm run check:cycles           # Detectează dependențe circulare

Rularea Testelor

# Fișier de test unic (rulant de teste nativ Node.js — cele mai multe teste)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Toate suitele
npm run test:all

Pentru matricea completă a testelor, consultați CONTRIBUTING.md → "Rularea Testelor". Pentru arhitectură detaliată, consultați AGENTS.md.

Proiect pe scurt

OmniRoute — proxy/router AI unificat. Un endpoint, 160+ furnizori LLM, fallback automat.

Strat Locație Scop
Rute API src/app/api/v1/ Router aplicație Next.js — puncte de intrare
Handleri open-sse/handlers/ Procesarea cererilor (chat, embeddings, etc)
Executorii open-sse/executors/ Dispatch HTTP specific furnizor
Traducători open-sse/translator/ Conversie de format (OpenAI↔Claude↔Gemini)
Transformator open-sse/transformer/ API de răspunsuri ↔ Completări chat
Servicii open-sse/services/ Rutare combinată, limite de rată, caching, etc
Bază de date src/lib/db/ Module de domeniu SQLite (45+ fișiere, 55 migrații)
Domeniu/Politică src/domain/ Motor de politici, reguli de cost, logică de fallback
Server MCP open-sse/mcp-server/ 37 unelte (30 de bază + 3 memorie + 4 abilități), 3 transporturi, ~13 domenii
Server A2A src/lib/a2a/ Protocol agent JSON-RPC 2.0
Abilități src/lib/skills/ Cadru extensibil pentru abilități
Memorie src/lib/memory/ Memorie conversațională persistentă

Monorepo: src/ (aplicație Next.js 16), open-sse/ (spațiu de lucru pentru motor de streaming), electron/ (aplicație desktop), tests/, bin/ (punct de intrare CLI).

Pipeline de Cerere

Client → /v1/chat/completions (ruta Next.js)
  → CORS → validare Zod → auth? → verificare politică → protecție împotriva injecției de prompt
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → verificare cache → limită de rată → rutare combo?
      → resolveComboTargets() → handleSingleModel() per target
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → traducerea răspunsului → flux SSE sau JSON
    → Dacă Responses API: responsesTransformer.ts TransformStream

Rutele API urmează un model consistent: Ruta → CORS preflight → validare corp Zod → Auth opțional (extractApiKey/isValidApiKey) → aplicarea politicii cheii API → delegarea handler-ului (open-sse). Nu există middleware global Next.js — interceptarea este specifică rutei.

Rutare combo (open-sse/services/combo.ts): 14 strategii (prioritate, ponderată, umple-primul, rotativ, P2C, aleatorie, cel mai puțin utilizată, optimizată pentru cost, conștientă de resetare, strict-aleatorie, auto, lkgp, optimizată pentru context, relay de context). Fiecare țintă apelează handleSingleModel() care învăluie handleChatCore() cu gestionarea erorilor per țintă și verificări ale circuit breaker-ului. Consultați docs/routing/AUTO-COMBO.md pentru scorul Auto-Combo cu 9 factori și docs/architecture/RESILIENCE_GUIDE.md pentru cele 3 straturi de reziliență.

Starea de Execuție a Rezilienței

OmniRoute are trei mecanisme de eșec temporar, legate dar distincte. Mențineți domeniul lor separat atunci când depanați comportamentul rutării. Consultați diagrama rezilienței cu 3 straturi (sursa: docs/diagrams/resilience-3layers.mmd) pentru o hartă rapidă.

Circuit Breaker al Provider-ului

Domeniu: întregul provider, de exemplu glm, openai, anthropic.

Scop: opriți trimiterea traficului către un provider care eșuează repetat la nivelul upstream/serviciu, astfel încât un provider nesănătos să nu încetinească fiecare cerere.

Implementare:

  • Clasă de bază: src/shared/utils/circuitBreaker.ts
  • Conexiune gate/executare chat: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • API de stare de execuție: src/app/api/monitoring/health/route.ts
  • Wrapper-uri partajate: open-sse/services/accountFallback.ts
  • Tabel de stare persistată: domain_circuit_breakers

Stări:

  • CLOSED: traficul normal este permis.
  • OPEN: provider-ul este temporar blocat; apelanții primesc un răspuns provider-circuit-open sau rutarea combo sare la o altă țintă.
  • HALF_OPEN: timeout-ul de resetare a expirat; permite o cerere de sondaj. Succesul închide circuit breaker-ul, eșecul îl deschide din nou.

Imposturi (open-sse/config/constants.ts):

  • Provideri OAuth: prag 3, timeout de resetare 60s.
  • Provideri cu cheie API: prag 5, timeout de resetare 30s.
  • Provideri locali: prag 2, timeout de resetare 15s.

Numai stările de eșec la nivel de provider ar trebui să declanșeze circuit breaker-ul provider-ului:

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

Nu declanșa circuit breaker-ul întregului provider pentru erori normale de cont/cheie/model precum majoritatea cazurilor 401, 403, sau 429. Acestea aparțin de obicei cooldown-ul conexiunii sau blocarea modelului. O cheie API generică 403 ar trebui să fie recuperabilă, cu excepția cazului în care este clasificată ca o eroare terminală de provider/cont.

Circuit breaker-ul folosește recuperare leneșă, nu un timer de fundal. Când OPEN expiră, citirile precum getStatus(), canExecute(), și getRetryAfterMs() reîmprospătează starea la HALF_OPEN, astfel încât tablourile de bord și constructorii de candidați combo să nu continue să excludă un provider expirat pentru totdeauna.

Cooldown de Conexiune

Domeniu: o conexiune/provider/cheie.

Scop: să sară temporar o cheie/cont proastă, permițând altor conexiuni pentru același provider să continue să servească cereri.

Implementare:

  • Calea de scriere/actualizare: src/sse/services/auth.ts::markAccountUnavailable()
  • Selecția/filtrarea contului: src/sse/services/auth.ts::getProviderCredentials...
  • Calculul cooldown-ului: open-sse/services/accountFallback.ts::checkFallbackError()
  • Setări: src/lib/resilience/settings.ts

Câmpuri importante pe conexiunile provider-ului:

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

În timpul selecției contului, o conexiune este sărită în timp ce:

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

Cooldown-urile sunt de asemenea leneșe: când rateLimitedUntil este în trecut, conexiunea devine eligibilă din nou. La utilizarea cu succes, clearAccountError() șterge testStatus, rateLimitedUntil, câmpurile de eroare și backoffLevel.

Comportamentul implicit al cooldown-ului de conexiune:

  • Cooldown de bază OAuth: 5s.
  • Cooldown de bază pentru cheie API: 3s.
  • Cheia API 429 ar trebui să prefere indicii de retry upstream (Retry-After, antete de resetare, sau text de resetare parsabil) atunci când sunt disponibile.
  • Eșecurile recuperabile repetate folosesc backoff exponențial:
baseCooldownMs * 2 ** failureIndex;

Gardianul anti-thundering-herd previne eșecurile concurente pe aceeași conexiune de a extinde repetat cooldown-ul sau de a incrementa dublu backoffLevel.

Stările terminale nu sunt cooldown-uri. banned, expired, și credits_exhausted sunt destinate să rămână indisponibile până când acreditivele/setările se schimbă sau un operator le resetează. Nu suprascrieți stările terminale cu starea temporară de cooldown.

Blocarea Modelului

Domeniu: provider + conexiune + model.

Scop: evitați dezactivarea unei întregi conexiuni atunci când doar un singur model este indisponibil sau limită de cotă pentru acea conexiune.

Exemple:

  • Provideri cu cotă pe model care returnează 429.
  • Provideri locali care returnează 404 pentru un model lipsă.
  • Eșecuri de permisiune specifice provider-ului pentru mod/model, cum ar fi modurile Grok selectate.

Blocarea modelului se află în open-sse/services/accountFallback.ts și permite aceleași conexiuni să continue să servească alte modele.

Ghid de Depanare

  • Dacă toate cheile pentru un provider sunt sărite, inspectați atât starea circuit breaker-ului provider, cât și rateLimitedUntil/testStatus ale fiecărei conexiuni.
  • Dacă un provider pare permanent exclus după fereastra de resetare, verificați dacă codul citește state brut în loc să folosească getStatus()/canExecute().
  • Dacă o cheie de provider eșuează, dar altele ar trebui să funcționeze, preferați cooldown-ul conexiunii în locul circuit breaker-ului provider.
  • Dacă doar un model eșuează, preferați blocarea modelului în locul cooldown-ului conexiunii.
  • Dacă o stare ar trebui să se recupereze singură, ar trebui să aibă un timestamp/reset timeout în viitor și o cale de citire care reîmprospătează starea expirat. Stările permanente necesită modificări manuale ale acreditivelor sau configurației.

Convenții Cheie

Stil de Cod

  • 2 spații, puncte și virgule, ghilimele duble, lățime de 100 caractere, virgule de final es5 (impuse de lint-staged prin Prettier)
  • Importuri: externe → interne (@/, @omniroute/open-sse) → relative
  • Nomenclatură: fișiere=camelCase/kebab, componente=PascalCase, constante=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = eroare peste tot; no-explicit-any = avertizare în open-sse/ și tests/
  • TypeScript: strict: false, țintă ES2022, modul esnext, rezolvare bundler. Preferă tipuri explicite.

Bază de Date

  • Întotdeauna treci prin modulele de domeniu src/lib/db/ — niciodată nu scrie SQL brut în rute sau manipulatoare
  • Niciodată nu adăuga logică în src/lib/localDb.ts (doar strat de re-export)
  • Niciodată nu importa prin barrel din localDb.ts — importă module specifice db/ în schimb
  • Singleton DB: getDbInstance() din src/lib/db/core.ts (jurnalizare WAL)
  • Migrații: src/lib/db/migrations/ — fișiere SQL versionate, idempotente, rulate în tranzacții

Gestionarea Erorilor

  • try/catch cu tipuri de erori specifice, logare cu context pino
  • Niciodată nu înghiți erori în fluxurile SSE — folosește semnale de abort pentru curățare
  • Returnează coduri de stare HTTP corecte (4xx/5xx)

Securitate

  • Niciodată nu folosi eval(), new Function(), sau eval implicit
  • Validare a tuturor intrărilor cu scheme Zod
  • Criptează acreditivii în repaus (AES-256-GCM)
  • Lista de denylist pentru antete upstream: src/shared/constants/upstreamHeaders.ts — menține sanitizarea, schemele Zod și testele unitare aliniate când editezi
  • Acreditivele publice upstream (client_id/secret OAuth de tip Gemini/Antigravity/Windsurf + chei Web Firebase extrase din CLI-uri publice): TREBUIE să fie încorporate prin resolvePublicCred() din open-sse/utils/publicCreds.ts — niciodată ca litere string. Vezi docs/security/PUBLIC_CREDS.md pentru modelul obligatoriu.
  • Răspunsurile de eroare (HTTP / SSE / executor / MCP handler): TREBUIE să treacă prin buildErrorBody() sau sanitizeErrorMessage() din open-sse/utils/error.ts — niciodată nu pune err.stack sau err.message brut în corpul răspunsului. Vezi docs/security/ERROR_SANITIZATION.md.
  • Comenzi shell construite din variabile: când apelezi exec()/spawn() cu un script care are nevoie de valori de runtime, transmite-le prin opțiunea env (escapate automat) — niciodată nu interpolare stringuri de căi externe/neîncrezătoare în corpul scriptului. Referință: src/mitm/cert/install.ts::updateNssDatabases.
  • Biblioteci securizate prin default (tldrsec/awesome-secure-defaults): preferă Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink în locul implementărilor personalizate ori de câte ori adaugi noi suprafețe sensibile la securitate.

Scenarii Comune de Modificare

Adăugarea unui Nou Furnizor

  1. Înregistrează în src/shared/constants/providers.ts (validat Zod la încărcare)
  2. Adaugă executor în open-sse/executors/ dacă este necesară o logică personalizată (extinde BaseExecutor)
  3. Adaugă translator în open-sse/translator/ dacă formatul nu este OpenAI
  4. Adaugă configurația OAuth în src/lib/oauth/constants/oauth.ts dacă este bazată pe OAuth — dacă CLI-ul upstream livrează un client_id/secret public, încorporează prin resolvePublicCred() (vezi docs/security/PUBLIC_CREDS.md), niciodată ca literal
  5. Înregistrează modelele în open-sse/config/providerRegistry.ts
  6. Scrie teste în tests/unit/ (includerea aserțiunii de formă publicCreds dacă ai adăugat un nou default încorporat)

Adăugarea unei Noi Rute API

  1. Creează un director sub src/app/api/v1/your-route/
  2. Creează route.ts cu manipulatoare GET/POST
  3. Urmează modelul: CORS → validare a corpului Zod → autentificare opțională → delegare a manipulatoarelor
  4. Manipulatorul merge în open-sse/handlers/ (importă de acolo, nu inline)
  5. Răspunsurile de eroare folosesc buildErrorBody() / errorResponse() din open-sse/utils/error.ts (auto-sanitizate — niciodată nu pune err.stack sau err.message brut în corp). Vezi docs/security/ERROR_SANITIZATION.md.
  6. Adaugă teste — inclusiv cel puțin o aserțiune că răspunsurile de eroare nu scurg trasări de stivă (!body.error.message.includes("at /"))

Adăugarea unui Nou Modul DB

  1. Creează src/lib/db/yourModule.ts — importă getDbInstance din ./core.ts
  2. Exportă funcții CRUD pentru tabelul(tabelele) tale de domeniu
  3. Adaugă migrație în src/lib/db/migrations/ dacă sunt necesare tabele noi
  4. Re-exportă din src/lib/localDb.ts (adaugă doar la lista de re-export)
  5. Scrie teste

Adăugarea unui Nou Instrument MCP

  1. Adaugă definiția instrumentului în open-sse/mcp-server/tools/ cu schema de intrare Zod + manipulatoare asincrone
  2. Înregistrează în setul de instrumente (conectat prin createMcpServer())
  3. Atribuie la domeniile corespunzătoare
  4. Scrie teste (invocarea instrumentului este înregistrată în tabela mcp_audit)

Adăugarea unei Noi Abilități A2A

  1. Creează abilitate în src/lib/a2a/skills/ (5 există deja: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. Abilitatea primește contextul sarcinii (mesaje, metadate) → returnează un rezultat structurat
  3. Înregistrează în A2A_SKILL_HANDLERS în src/lib/a2a/taskExecution.ts
  4. Expune în src/app/.well-known/agent.json/route.ts (Agent Card)
  5. Scrie teste în tests/unit/
  6. Documentează în docs/frameworks/A2A-SERVER.md tabela abilităților

Adăugarea unui Nou Agent Cloud

  1. Creează clasa agentului în src/lib/cloudAgent/agents/ extinzând CloudAgentBase (3 există deja: codex-cloud, devin, jules)
  2. Implementează createTask, getStatus, approvePlan, sendMessage, listSources
  3. Înregistrează în src/lib/cloudAgent/registry.ts
  4. Adaugă gestionarea OAuth/acreditivelor dacă este necesar (src/lib/oauth/providers/)
  5. Teste + documentează în docs/frameworks/CLOUD_AGENT.md

Adăugarea unei Noi Reguli de Securitate / Eval / Abilitate / Eveniment Webhook

  • Regulă de securitate: src/lib/guardrails/ → documente: docs/security/GUARDRAILS.md
  • Suita Eval: src/lib/evals/ → documente: docs/frameworks/EVALS.md
  • Abilitate (sandbox): src/lib/skills/ → documente: docs/frameworks/SKILLS.md
  • Eveniment Webhook: src/lib/webhookDispatcher.ts → documente: docs/frameworks/WEBHOOKS.md

Documentație de Referință

Pentru orice modificare non-trivială, citiți mai întâi analiza corespunzătoare:

Domeniu Document
Navigare în repo docs/architecture/REPOSITORY_MAP.md
Arhitectură docs/architecture/ARCHITECTURE.md
Referință inginerie docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (scor 9-factori, 14 strategii) docs/routing/AUTO-COMBO.md
Reziliență (3 mecanisme) docs/architecture/RESILIENCE_GUIDE.md
Repetare raționare docs/routing/REASONING_REPLAY.md
Cadru de abilități docs/frameworks/SKILLS.md
Sistem de memorie (FTS5 + Qdrant) docs/frameworks/MEMORY.md
Agenți cloud docs/frameworks/CLOUD_AGENT.md
Ghiduri de protecție (PII / injecție / viziune) docs/security/GUARDRAILS.md
Credite publice upstream (Gemini/etc.) docs/security/PUBLIC_CREDS.md
Sanitizarea mesajelor de eroare docs/security/ERROR_SANITIZATION.md
Evaluări docs/frameworks/EVALS.md
Conformitate / audit docs/security/COMPLIANCE.md
Webhooks docs/frameworks/WEBHOOKS.md
Pipeline de autorizare docs/architecture/AUTHZ_GUIDE.md
Stealth (TLS / amprentă) docs/security/STEALTH_GUIDE.md
Protocoale agenți (A2A / ACP / Cloud) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
Server MCP docs/frameworks/MCP-SERVER.md
Server A2A docs/frameworks/A2A-SERVER.md
Referință API + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Catalog furnizori (generat automat) docs/reference/PROVIDER_REFERENCE.md
Flux de lansare docs/ops/RELEASE_CHECKLIST.md

Testare

Ce Comandă
Teste unitare npm run test:unit
Fișier unic node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo) npm run test:vitest
E2E (Playwright) npm run test:e2e
Protocol E2E (MCP+A2A) npm run test:protocols:e2e
Ecosistem npm run test:ecosystem
Poarta de acoperire npm run test:coverage (75/75/75/70 — declarații/linie/funcții/ramuri)
Raport de acoperire npm run coverage:report

Regula PR: Dacă schimbi codul de producție în src/, open-sse/, electron/, sau bin/, trebuie să incluzi sau să actualizezi teste în același PR.

Preferința pentru stratul de testare: unitate mai întâi → integrare (multi-modul sau stare DB) → e2e (doar UI/workflow). Codifică reproducerea bug-urilor ca teste automate înainte sau împreună cu soluția.

Politica de acoperire Copilot: Când un PR schimbă codul de producție și acoperirea este sub 75% (declarații/linie/funcții) sau 70% (ramuri), nu raporta doar — adaugă sau actualizează teste, rulează din nou poarta de acoperire, apoi cere confirmare. Include comenzile rulate, fișierele de test schimbate și rezultatul final al acoperirii în raportul PR.

Fluxul de lucru Git

# Nu face niciodată commit direct pe main
git checkout -b feat/your-feature
git commit -m "feat: descrie schimbarea ta"
git push -u origin feat/your-feature

Prefixe pentru ramuri: feat/, fix/, refactor/, docs/, test/, chore/

Formatul commit-ului (Conventional Commits): feat(db): adaugă circuit breaker — domenii: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Hooks Husky:

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

Mediu

  • Runtime: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, Module ES
  • TypeScript: 5.9+, target ES2022, modul esnext, rezolvare bundler
  • Aliasuri de cale: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • Port implicit: 20128 (API + dashboard pe același port)
  • Director de date: DATA_DIR variabilă de mediu, implicit ~/.omniroute/
  • Variabile de mediu cheie: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • Configurare: cp .env.example .env apoi generează JWT_SECRET (openssl rand -base64 48) și API_KEY_SECRET (openssl rand -hex 32)

Reguli stricte

  1. Nu face niciodată commit pentru secrete sau acreditive
  2. Nu adăuga niciodată logică în localDb.ts
  3. Nu folosi niciodată eval() / new Function() / eval implicit
  4. Nu face niciodată commit direct pe main
  5. Nu scrie niciodată SQL brut în rute — folosește modulele din src/lib/db/
  6. Nu ascunde niciodată în tăcere erorile în fluxurile SSE
  7. Întotdeauna validează intrările cu scheme Zod
  8. Întotdeauna include teste atunci când schimbi codul de producție
  9. Acoperirea trebuie să rămână ≥75% (declarații, linii, funcții) / ≥70% (ramuri). Măsurată în prezent: ~82%.
  10. Nu ocoli niciodată hooks-urile Husky (--no-verify, --no-gpg-sign) fără aprobarea explicită a operatorului.
  11. Nu încorpora niciodată client_id/secret public OAuth sau chei Web Firebase ca litere string — treci întotdeauna prin resolvePublicCred() (open-sse/utils/publicCreds.ts). Vezi docs/security/PUBLIC_CREDS.md.
  12. Nu returna niciodată err.stack / err.message brut în răspunsurile HTTP / SSE / executor — întotdeauna rotește prin buildErrorBody() sau sanitizeErrorMessage() (open-sse/utils/error.ts). Vezi docs/security/ERROR_SANITIZATION.md.
  13. Nu interpolare niciodată string-uri externe sau valori de runtime în scripturi shell transmise la exec()/spawn() — treci prin opțiunea env în schimb. Referință: src/mitm/cert/install.ts::updateNssDatabases.
  14. Nu ignora niciodată un alert CodeQL / Secret-Scanning fără (a) să verifici mai întâi documentele de model de mai sus pentru a vedea dacă ajutorul se aplică, și (b) să înregistrezi justificarea tehnică în comentariul de respingere. Precedent: js/stack-trace-exposure ridicat pe callsites care deja rotează prin sanitizeErrorMessage() este o limitare cunoscută CodeQL (sanitizatori personalizați nerecunoscuți) — respinge ca false positive referindu-te la docs/security/ERROR_SANITIZATION.md.
  15. Nu expune niciodată rute care generează procese copil (/api/mcp/, /api/cli-tools/runtime/) fără clasificarea isLocalOnlyPath() în src/server/authz/routeGuard.ts. Aplicarea loopback-ului se întâmplă necondiționat înainte de orice verificare de autentificare — un JWT scurs prin tunel nu poate declanșa generarea procesului. Vezi docs/security/ROUTE_GUARD_TIERS.md.
  16. Niciodată să nu includeți trailere Co-Authored-By care creditează un asistent AI, LLM sau cont de automatizare (de ex. nume conținând "Claude", "GPT", "Copilot", "Bot"; e-mailuri la anthropic.com / openai.com / adrese noreply.github.com deținute de boți). Astfel de trailere direcționează atribuirea commit-ului către contul botului pe GitHub, ascunzând autorul real (diegosouzapw) în istoricul PR. Colaboratorii umani — inclusiv autorii de PR-uri upstream și raportorii de issue portate în OmniRoute — POT și AR TREBUI să fie creditați cu trailere standard Co-authored-by: Name <email>; fluxurile de lucru upstream-port (/port-upstream-features, /port-upstream-issues) depind de aceasta.
Reference in New Issue View Git Blame Copy Permalink