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/cs/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 (Čeština)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇩🇰 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 · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

Tento soubor poskytuje pokyny pro Claude Code (claude.ai/code) při práci s kódem v tomto repozitáři.

Rychlý start

npm install                    # Nainstalujte závislosti (automaticky vygeneruje .env z .env.example)
npm run dev                    # Vývojový server na http://localhost:20128
npm run build                  # Produkční build (Next.js 16 standalone)
npm run lint                   # ESLint (0 chyb očekáváno; varování jsou předchozí)
npm run typecheck:core         # Kontrola TypeScriptu (mělo by být čisté)
npm run typecheck:noimplicit:core  # Přísná kontrola (žádné implicitní any)
npm run test:coverage          # Jednotkové testy + pokrytí (75/75/75/70 — prohlášení/řádky/funkce/větve)
npm run check                  # lint + testy dohromady
npm run check:cycles           # Detekce cyklických závislostí

Spouštění testů

# Jediný testovací soubor (nativní testovací běžec Node.js — většina testů)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Všechny sady
npm run test:all

Pro plnou testovací matici viz CONTRIBUTING.md → "Spouštění testů". Pro hlubokou architekturu viz AGENTS.md.

Projekt na první pohled

OmniRoute — jednotný AI proxy/router. Jeden koncový bod, 160+ poskytovatelů LLM, automatické zálohování.

Vrstva Umístění Účel
API Routes src/app/api/v1/ Next.js App Router — vstupní body
Handlers open-sse/handlers/ Zpracování požadavků (chat, embeddings, atd.)
Executors open-sse/executors/ HTTP dispatch specifický pro poskytovatele
Translators open-sse/translator/ Konverze formátu (OpenAI↔Claude↔Gemini)
Transformer open-sse/transformer/ API odpovědí ↔ Dokončení chatu
Services open-sse/services/ Kombinované směrování, limity rychlosti, caching, atd.
Database src/lib/db/ SQLite doménové moduly (45+ souborů, 55 migrací)
Domain/Policy src/domain/ Engin politiky, pravidla nákladů, logika zálohování
MCP Server open-sse/mcp-server/ 37 nástrojů (30 základních + 3 paměť + 4 dovednosti), 3 transporty, ~13 rozsahů
A2A Server src/lib/a2a/ JSON-RPC 2.0 agent protokol
Skills src/lib/skills/ Rozšiřitelný rámec dovedností
Memory src/lib/memory/ Trvalá konverzační paměť

Monorepo: src/ (Next.js 16 aplikace), open-sse/ (pracovní prostor streamovacího enginu), electron/ (desktopová aplikace), tests/, bin/ (CLI vstupní bod).

Pipeline požadavků

Klient → /v1/chat/completions (Next.js route)
  → CORS → Zod validace → auth? → kontrola politiky → ochrana proti injekci promptu
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → kontrola cache → limit rychlosti → combo routing?
      → resolveComboTargets() → handleSingleModel() pro každý cíl
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → opakování s backoff
    → překlad odpovědi → SSE stream nebo JSON
    → Pokud Responses API: responsesTransformer.ts TransformStream

API trasy následují konzistentní vzor: Route → CORS preflight → Zod validace těla → Volitelná autentizace (extractApiKey/isValidApiKey) → Vynucení politiky API klíče → Delegace handleru (open-sse). Žádný globální Next.js middleware — interceptace je specifická pro trasu.

Combo routing (open-sse/services/combo.ts): 14 strategií (priorita, vážené, fill-first, round-robin, P2C, náhodné, nejméně používané, optimalizované podle nákladů, reset-aware, strict-random, auto, lkgp, optimalizované podle kontextu, kontext-relay). Každý cíl volá handleSingleModel(), který obaluje handleChatCore() s chybovým zpracováním a kontrolami obvodu pro každý cíl. Viz docs/routing/AUTO-COMBO.md pro 9-faktorové hodnocení Auto-Combo a docs/architecture/RESILIENCE_GUIDE.md pro 3 vrstvy odolnosti.

Stav běhu odolnosti

OmniRoute má tři související, ale odlišné mechanismy dočasného selhání. Udržujte jejich rozsah oddělený při ladění chování routování. Viz diagram odolnosti ve 3 vrstvách (zdroj: docs/diagrams/resilience-3layers.mmd) pro rychlý přehled.

Obvod poskytovatele

Rozsah: celý poskytovatel, např. glm, openai, anthropic.

Účel: zastavit posílání provozu k poskytovateli, který opakovaně selhává na úrovni upstream/služby, aby jeden nezdravý poskytovatel nezpomalil každý požadavek.

Implementace:

  • Hlavní třída: src/shared/utils/circuitBreaker.ts
  • Chat gate/execution wiring: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • API stavu běhu: src/app/api/monitoring/health/route.ts
  • Sdílené obaly: open-sse/services/accountFallback.ts
  • Tabulka trvalého stavu: domain_circuit_breakers

Stavy:

  • CLOSED: normální provoz je povolen.
  • OPEN: poskytovatel je dočasně zablokován; volající dostanou odpověď provider-circuit-open nebo combo routing přeskočí na jiný cíl.
  • HALF_OPEN: resetovací timeout uplynul; povolit zkušební požadavek. Úspěch uzavírá obvod, selhání jej znovu otevírá.

Výchozí hodnoty (open-sse/config/constants.ts):

  • OAuth poskytovatelé: práh 3, resetovací timeout 60s.
  • API-klíč poskytovatelé: práh 5, resetovací timeout 30s.
  • Lokální poskytovatelé: práh 2, resetovací timeout 15s.

Pouze stavy selhání na úrovni poskytovatele by měly spustit obvod poskytovatele:

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

Nespouštějte obvod celého poskytovatele pro normální chyby účtu/klíče/modelu jako většina případů 401, 403 nebo 429. Ty obvykle patří do cooldownu připojení nebo uzamčení modelu. Obecný API-klíč poskytovatel 403 by měl být obnovitelný, pokud není klasifikován jako terminální chyba poskytovatele/účtu.

Obvod používá lenivou obnovu, ne pozadí časovač. Když OPEN vyprší, čtení jako getStatus(), canExecute(), a getRetryAfterMs() obnoví stav na HALF_OPEN, takže panely a stavitelé kandidátů na combo nebudou navždy vylučovat vypršeného poskytovatele.

Cooldown připojení

Rozsah: jedno připojení/účet/klíč poskytovatele.

Účel: dočasně přeskočit jeden špatný klíč/účet, zatímco ostatní připojení pro stejného poskytovatele mohou pokračovat v obsluze požadavků.

Implementace:

  • Cesta zápisu/aktualizace: src/sse/services/auth.ts::markAccountUnavailable()
  • Výběr/filtrování účtu: src/sse/services/auth.ts::getProviderCredentials...
  • Výpočet cooldownu: open-sse/services/accountFallback.ts::checkFallbackError()
  • Nastavení: src/lib/resilience/settings.ts

Důležitá pole na připojeních poskytovatele:

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

Během výběru účtu je připojení přeskočeno, pokud:

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

Cooldowny jsou také lenivé: když je rateLimitedUntil v minulosti, připojení se opět stává způsobilým. Při úspěšném použití clearAccountError() vymaže testStatus, rateLimitedUntil, chybová pole a backoffLevel.

Výchozí chování cooldownu připojení:

  • Základní cooldown OAuth: 5s.
  • Základní cooldown API-klíče: 3s.
  • API-klíč 429 by měl preferovat upstream retry hints (Retry-After, resetovací hlavičky, nebo parsovatelný reset text) když jsou k dispozici.
  • Opakované obnovitelné selhání používá exponenciální backoff:
baseCooldownMs * 2 ** failureIndex;

Ochrana proti thundering-herd zabraňuje souběžným selháním na stejném připojení v opakovaném prodlužování cooldownu nebo dvojitému zvyšování backoffLevel.

Terminální stavy nejsou cooldowny. banned, expired, a credits_exhausted jsou určeny k tomu, aby zůstaly nedostupné, dokud se nezmění pověření/nastavení nebo je operátor neobnoví. Nepřepisujte terminální stavy do přechodného stavu cooldownu.

Uzamčení modelu

Rozsah: poskytovatel + připojení + model.

Účel: vyhnout se deaktivaci celého připojení, když je k dispozici pouze jeden model nebo je omezený kvótou pro toto připojení.

Příklady:

  • Poskytovatelé s kvótou na model vracející 429.
  • Lokální poskytovatelé vracející 404 pro jeden chybějící model.
  • Chyby oprávnění specifické pro poskytovatele/model, jako jsou vybrané režimy Grok.

Uzamčení modelu žije v open-sse/services/accountFallback.ts a umožňuje stejnému připojení pokračovat v obsluze dalších modelů.

Pokyny pro ladění

  • Pokud jsou všechny klíče pro poskytovatele přeskočeny, zkontrolujte jak stav obvodu poskytovatele, tak rateLimitedUntil/testStatus každého připojení.
  • Pokud se zdá, že je poskytovatel trvale vyloučen po resetovacím okně, zkontrolujte, zda kód čte surový state místo používání getStatus()/canExecute().
  • Pokud jeden klíč poskytovatele selže, ale ostatní by měly fungovat, preferujte cooldown připojení před obvodem poskytovatele.
  • Pokud selže pouze jeden model, preferujte uzamčení modelu před cooldownem připojení.
  • Pokud by se měl stav sám obnovit, měl by mít budoucí časové razítko/resetovací timeout a čtecí cestu, která obnovuje vypršený stav. Trvalé stavy vyžadují ruční změny pověření nebo konfigurace.

Klíčové konvence

Styl kódu

  • 2 mezery, středníky, dvojité uvozovky, šířka 100 znaků, es5 koncové čárky (vynuceno lint-staged pomocí Prettier)
  • Importy: externí → interní (@/, @omniroute/open-sse) → relativní
  • Pojmenování: soubory=camelCase/kebab, komponenty=PascalCase, konstanty=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = chyba všude; no-explicit-any = varování v open-sse/ a tests/
  • TypeScript: strict: false, cíl ES2022, modul esnext, rozlišení bundler. Preferujte explicitní typy.

Databáze

  • Vždy procházejte doménovými moduly src/lib/db/ — nikdy nepíšete surové SQL v trasách nebo obslužných funkcích
  • Nikdy nepřidávejte logiku do src/lib/localDb.ts (pouze vrstva pro opětovný export)
  • Nikdy neprovádějte barrel-import z localDb.ts — místo toho importujte konkrétní moduly db/
  • DB singleton: getDbInstance() z src/lib/db/core.ts (WAL žurnálování)
  • Migrace: src/lib/db/migrations/ — verzované SQL soubory, idempotentní, prováděné v transakcích

Zpracování chyb

  • try/catch se specifickými typy chyb, logování s kontextem pino
  • Nikdy nezapomínejte na chyby ve SSE streamech — použijte signály pro zrušení pro úklid
  • Vraťte správné HTTP status kódy (4xx/5xx)

Bezpečnost

  • Nikdy nepoužívejte eval(), new Function(), nebo implicitní eval
  • Ověřte všechny vstupy pomocí Zod schémat
  • Šifrujte přihlašovací údaje v klidu (AES-256-GCM)
  • Seznam zakázaných hlaviček upstream: src/shared/constants/upstreamHeaders.ts — udržujte sanitaci, Zod schémata a jednotkové testy v souladu při úpravách
  • Veřejné přihlašovací údaje upstream (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web klíče extrahované z veřejných CLI): MUSÍ být vloženy pomocí resolvePublicCred() z open-sse/utils/publicCreds.ts — nikdy jako literály. Viz docs/security/PUBLIC_CREDS.md pro povinný vzor.
  • Odpovědi na chyby (HTTP / SSE / executor / MCP obslužná funkce): MUSÍ procházet buildErrorBody() nebo sanitizeErrorMessage() z open-sse/utils/error.ts — nikdy nevkládejte surové err.stack nebo err.message do těla odpovědi. Viz docs/security/ERROR_SANITIZATION.md.
  • Shell příkazy vytvořené z proměnných: při volání exec()/spawn() se skriptem, který potřebuje hodnoty za běhu, předávejte je pomocí možnosti env (automaticky shell-escaped) — nikdy neprovádějte interpolaci neověřených/externalních cest do těla skriptu. Odkaz: src/mitm/cert/install.ts::updateNssDatabases.
  • Knihovny zabezpečené podle výchozího nastavení (tldrsec/awesome-secure-defaults): preferujte Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink před vlastními implementacemi při přidávání nových bezpečnostně citlivých povrchů.

Běžné scénáře úprav

Přidání nového poskytovatele

  1. Zaregistrujte v src/shared/constants/providers.ts (ověřeno Zod při načítání)
  2. Přidejte executor v open-sse/executors/, pokud je potřeba vlastní logika (rozšiřte BaseExecutor)
  3. Přidejte překladač v open-sse/translator/, pokud není ve formátu OpenAI
  4. Přidejte OAuth konfiguraci v src/lib/oauth/constants/oauth.ts, pokud je založena na OAuth — pokud upstream CLI dodává veřejný client_id/secret, vložte pomocí resolvePublicCred() (viz docs/security/PUBLIC_CREDS.md), nikdy jako literál
  5. Zaregistrujte modely v open-sse/config/providerRegistry.ts
  6. Napište testy v tests/unit/ (zahrňte ověření tvaru publicCreds, pokud jste přidali nový vložený výchozí)

Přidání nové API trasy

  1. Vytvořte adresář pod src/app/api/v1/your-route/
  2. Vytvořte route.ts s obslužnými funkcemi GET/POST
  3. Dodržujte vzor: CORS → Zod ověření těla → volitelná autentizace → delegace obslužné funkce
  4. Obslužná funkce jde do open-sse/handlers/ (importujte odtud, ne inline)
  5. Odpovědi na chyby používají buildErrorBody() / errorResponse() z open-sse/utils/error.ts (automaticky sanitizováno — nikdy nevkládejte err.stack nebo err.message surově do těla). Viz docs/security/ERROR_SANITIZATION.md.
  6. Přidejte testy — včetně alespoň jednoho ověření, že odpovědi na chyby neunikají stopy (!body.error.message.includes("at /"))

Přidání nového DB modulu

  1. Vytvořte src/lib/db/yourModule.ts — importujte getDbInstance z ./core.ts
  2. Exportujte CRUD funkce pro vaše doménové tabulky
  3. Přidejte migraci v src/lib/db/migrations/, pokud jsou potřeba nové tabulky
  4. Znovu exportujte z src/lib/localDb.ts (přidejte pouze do seznamu pro opětovný export)
  5. Napište testy

Přidání nového MCP nástroje

  1. Přidejte definici nástroje v open-sse/mcp-server/tools/ s Zod vstupním schématem + asynchronní obslužnou funkcí
  2. Zaregistrujte v sadě nástrojů (propojeno pomocí createMcpServer())
  3. Přiřaďte k příslušným rozsahům
  4. Napište testy (vyvolání nástroje je zaznamenáno do tabulky mcp_audit)

Přidání nové A2A dovednosti

  1. Vytvořte dovednost v src/lib/a2a/skills/ (5 již existuje: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. Dovednost přijímá kontext úkolu (zprávy, metadata) → vrací strukturovaný výsledek
  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. Napište testy v tests/unit/
  6. Dokumentujte v docs/frameworks/A2A-SERVER.md tabulka dovedností

Přidání nového cloudového agenta

  1. Vytvořte třídu agenta v src/lib/cloudAgent/agents/ rozšiřující CloudAgentBase (3 již existují: codex-cloud, devin, jules)
  2. Implementujte createTask, getStatus, approvePlan, sendMessage, listSources
  3. Zaregistrujte v src/lib/cloudAgent/registry.ts
  4. Přidejte zpracování OAuth/přihlašovacích údajů, pokud je potřeba (src/lib/oauth/providers/)
  5. Testy + dokumentujte v docs/frameworks/CLOUD_AGENT.md

Přidání nového guardrail / eval / dovednosti / webhook události

  • Guardrail: src/lib/guardrails/ → dokumentace: docs/security/GUARDRAILS.md
  • Eval suite: src/lib/evals/ → dokumentace: docs/frameworks/EVALS.md
  • Dovednost (sandbox): src/lib/skills/ → dokumentace: docs/frameworks/SKILLS.md
  • Webhook událost: src/lib/webhookDispatcher.ts → dokumentace: docs/frameworks/WEBHOOKS.md

Referenční dokumentace

Před jakoukoli netriviální změnou si nejprve přečtěte odpovídající podrobnou analýzu:

Oblast Dokument
Navigace repozitářem docs/architecture/REPOSITORY_MAP.md
Architektura docs/architecture/ARCHITECTURE.md
Odkaz na inženýrství docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-faktorové hodnocení, 14 strategií) docs/routing/AUTO-COMBO.md
Odolnost (3 mechanismy) docs/architecture/RESILIENCE_GUIDE.md
Opakování uvažování docs/routing/REASONING_REPLAY.md
Rámec dovedností docs/frameworks/SKILLS.md
Systém paměti (FTS5 + Qdrant) docs/frameworks/MEMORY.md
Cloudoví agenti docs/frameworks/CLOUD_AGENT.md
Ochranné prvky (PII / injekce / vize) docs/security/GUARDRAILS.md
Veřejné přihlašovací údaje (Gemini atd.) docs/security/PUBLIC_CREDS.md
Sanitizace chybových zpráv docs/security/ERROR_SANITIZATION.md
Hodnocení docs/frameworks/EVALS.md
Soulad / audit docs/security/COMPLIANCE.md
Webhooky docs/frameworks/WEBHOOKS.md
Autorizační pipeline docs/architecture/AUTHZ_GUIDE.md
Stealth (TLS / otisk) docs/security/STEALTH_GUIDE.md
Protokoly agentů (A2A / ACP / Cloud) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP server docs/frameworks/MCP-SERVER.md
A2A server docs/frameworks/A2A-SERVER.md
Odkaz na API + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Katalog poskytovatelů (automaticky generovaný) docs/reference/PROVIDER_REFERENCE.md
Tok vydání docs/ops/RELEASE_CHECKLIST.md

Testování

Co Příkaz
Jednotkové testy npm run test:unit
Jediný soubor 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
Brána pokrytí npm run test:coverage (75/75/75/70 — příkazy/řádky/funkce/větve)
Zpráva o pokrytí npm run coverage:report

Pravidlo PR: Pokud změníte produkční kód v src/, open-sse/, electron/ nebo bin/, musíte zahrnout nebo aktualizovat testy ve stejném PR.

Preferovaný testovací vrstvy: jednotkové testy první → integrace (více modulů nebo stav DB) → e2e (pouze UI/workflow). Kódování reprodukcí chyb jako automatizovaných testů před nebo spolu s opravou.

Politika pokrytí Copilot: Když PR změní produkční kód a pokrytí je pod 75% (příkazy/řádky/funkce) nebo 70% (větve), nehlaste pouze — přidejte nebo aktualizujte testy, znovu spusťte bránu pokrytí a poté požádejte o potvrzení. Zahrňte provedené příkazy, změněné testovací soubory a konečný výsledek pokrytí do zprávy PR.

Git Workflow

# Nikdy neprovádějte commit přímo do main
git checkout -b feat/your-feature
git commit -m "feat: popište svou změnu"
git push -u origin feat/your-feature

Předpony větví: feat/, fix/, refactor/, docs/, test/, chore/

Formát commitu (Conventional Commits): feat(db): přidat circuit breaker — 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

Prostředí

  • Runtime: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES moduly
  • TypeScript: 5.9+, cíl ES2022, modul esnext, rozlišení bundler
  • Cestovní aliasy: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • Výchozí port: 20128 (API + dashboard na stejném portu)
  • Adresář dat: DATA_DIR env var, výchozí hodnota ~/.omniroute/
  • Klíčové env vars: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • Nastavení: cp .env.example .env poté vygenerujte JWT_SECRET (openssl rand -base64 48) a API_KEY_SECRET (openssl rand -hex 32)

Přísná pravidla

  1. Nikdy neprovádějte commit tajemství nebo přihlašovacích údajů
  2. Nikdy nepřidávejte logiku do localDb.ts
  3. Nikdy nepoužívejte eval() / new Function() / implicitní eval
  4. Nikdy neprovádějte commit přímo do main
  5. Nikdy nepíšete surový SQL v trasách — používejte moduly src/lib/db/
  6. Nikdy tiše nezachycujte chyby ve SSE streamech
  7. Vždy validujte vstupy pomocí Zod schémat
  8. Vždy zahrňte testy při změně produkčního kódu
  9. Pokrytí musí zůstat ≥75% (příkazy, řádky, funkce) / ≥70% (větve). Aktuálně měřeno: ~82%.
  10. Nikdy neobcházejte Husky hooky (--no-verify, --no-gpg-sign) bez explicitního schválení operátora.
  11. Nikdy nezahrnujte veřejné upstream OAuth client_id/secret nebo Firebase Web klíče jako řetězcové literály — vždy používejte resolvePublicCred() (open-sse/utils/publicCreds.ts). Viz docs/security/PUBLIC_CREDS.md.
  12. Nikdy nevracejte surový err.stack / err.message v HTTP / SSE / odpovědích executorů — vždy procházejte přes buildErrorBody() nebo sanitizeErrorMessage() (open-sse/utils/error.ts). Viz docs/security/ERROR_SANITIZATION.md.
  13. Nikdy neprovádějte interpolaci řetězců externích cest nebo runtime hodnot do shell skriptů předávaných do exec()/spawn() — předávejte je místo toho přes možnost env. Odkaz: src/mitm/cert/install.ts::updateNssDatabases.
  14. Nikdy neignorujte upozornění CodeQL / Secret-Scanning bez (a) nejprve zkontrolování dokumentace vzoru výše, abyste zjistili, zda se pomocník vztahuje, a (b) zaznamenání technického odůvodnění do komentáře o zamítnutí. Precedent: js/stack-trace-exposure vznesený na místech volání, která již procházejí přes sanitizeErrorMessage(), je známé omezení CodeQL (vlastní sanitizátory nejsou rozpoznány) — zamítněte jako false positive s odkazem na docs/security/ERROR_SANITIZATION.md.
  15. Nikdy nezveřejňujte trasy, které spouštějí podřízené procesy (/api/mcp/, /api/cli-tools/runtime/) bez klasifikace isLocalOnlyPath() v src/server/authz/routeGuard.ts. Vynucení loopbacku probíhá bezpodmínečně před jakýmkoli ověřením — uniklý JWT přes tunel nemůže spustit proces. Viz docs/security/ROUTE_GUARD_TIERS.md.
  16. Nikdy nezahrnujte Co-Authored-By přílohy, které připisují AI asistenta, LLM nebo automatizovaný účet (např. jména obsahující "Claude", "GPT", "Copilot", "Bot"; e-maily na anthropic.com / openai.com / adresách noreply.github.com vlastněných boty). Takové přílohy směrují přiřazení commitů na účet bota na GitHubu, čímž skrývají skutečného autora (diegosouzapw) v historii PR. Lidští spolupracovníci — včetně autorů upstream PR a hlasatelů issues přenášených do OmniRoute — MOHOU a MĚLI BY být uvedeni standardními přílohami Co-authored-by: Name <email>; upstream-port pracovní postupy (/port-upstream-features, /port-upstream-issues) na tom závisí.
Reference in New Issue View Git Blame Copy Permalink