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/pl/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 (Polski)

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

Ten plik zawiera wskazówki dla Claude Code (claude.ai/code) podczas pracy z kodem w tym repozytorium.

Szybki Start

npm install                    # Instalacja zależności (automatyczne generowanie .env z .env.example)
npm run dev                    # Serwer deweloperski na http://localhost:20128
npm run build                  # Budowa produkcyjna (Next.js 16 standalone)
npm run lint                   # ESLint (0 błędów oczekiwanych; ostrzeżenia są już istniejące)
npm run typecheck:core         # Sprawdzenie TypeScript (powinno być czyste)
npm run typecheck:noimplicit:core  # Ścisłe sprawdzenie (brak implicit any)
npm run test:coverage          # Testy jednostkowe + bramka pokrycia (75/75/75/70 — instrukcje/linie/funkcje/gałęzie)
npm run check                  # lint + testy połączone
npm run check:cycles           # Wykrywanie cyklicznych zależności

Uruchamianie Testów

# Pojedynczy plik testowy (wbudowany runner testów Node.js — większość testów)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Wszystkie zestawy
npm run test:all

Aby zobaczyć pełną macierz testów, zapoznaj się z CONTRIBUTING.md → "Uruchamianie Testów". Aby zobaczyć głęboką architekturę, zapoznaj się z AGENTS.md.

Projekt w Skrócie

OmniRoute — zjednoczony proxy/router AI. Jeden punkt końcowy, 160+ dostawców LLM, automatyczne przełączanie.

Warstwa Lokalizacja Cel
API Routes src/app/api/v1/ Router aplikacji Next.js — punkty wejścia
Handlers open-sse/handlers/ Przetwarzanie żądań (czat, osadzenia itp.)
Executors open-sse/executors/ Specyficzne dla dostawcy wysyłanie HTTP
Translators open-sse/translator/ Konwersja formatów (OpenAI↔Claude↔Gemini)
Transformer open-sse/transformer/ API odpowiedzi ↔ Uzupełnienia czatu
Services open-sse/services/ Routing combo, limity prędkości, cache itp.
Database src/lib/db/ Moduły domeny SQLite (45+ plików, 55 migracji)
Domain/Policy src/domain/ Silnik polityki, zasady kosztów, logika przełączania
MCP Server open-sse/mcp-server/ 37 narzędzi (30 bazowych + 3 pamięci + 4 umiejętności), 3 transporty, ~13 zakresów
A2A Server src/lib/a2a/ Protokół agenta JSON-RPC 2.0
Skills src/lib/skills/ Rozszerzalna struktura umiejętności
Memory src/lib/memory/ Trwała pamięć konwersacyjna

Monorepo: src/ (aplikacja Next.js 16), open-sse/ (workspace silnika strumieniowego), electron/ (aplikacja desktopowa), tests/, bin/ (punkt wejścia CLI).

Pipeline Żądań

Klient → /v1/chat/completions (trasa Next.js)
  → CORS → walidacja Zod → autoryzacja? → sprawdzenie polityki → ochrona przed wstrzyknięciem promptu
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → sprawdzenie pamięci podręcznej → limit szybkości → routowanie combo?
      → resolveComboTargets() → handleSingleModel() dla każdego celu
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → ponów z opóźnieniem
    → tłumaczenie odpowiedzi → strumień SSE lub JSON
    → Jeśli API Odpowiedzi: responsesTransformer.ts TransformStream

Trasy API podążają za spójnym wzorem: Trasa → wstępne zapytanie CORS → walidacja ciała Zod → Opcjonalna autoryzacja (extractApiKey/isValidApiKey) → egzekwowanie polityki klucza API → delegacja obsługi (open-sse). Brak globalnego middleware Next.js — przechwytywanie jest specyficzne dla trasy.

Routowanie combo (open-sse/services/combo.ts): 14 strategii (priorytet, ważony, fill-first, round-robin, P2C, losowy, najmniej używany, zoptymalizowany kosztowo, świadomy resetu, ścisły losowy, auto, lkgp, zoptymalizowany kontekstowo, relay kontekstowy). Każdy cel wywołuje handleSingleModel(), który owija handleChatCore() z obsługą błędów dla każdego celu i sprawdzeniami wyłącznika obwodu. Zobacz docs/routing/AUTO-COMBO.md dla 9-czynnikowego punktowania Auto-Combo i docs/architecture/RESILIENCE_GUIDE.md dla 3 warstw odporności.

Stan Czasu Wykonania Odporności

OmniRoute ma trzy powiązane, ale odrębne mechanizmy tymczasowej awarii. Zachowaj ich zakres oddzielnie podczas debugowania zachowania routingu. Zobacz diagram odporności 3-warstwowej (źródło: docs/diagrams/resilience-3layers.mmd) dla szybkiej mapy.

Wyłącznik Obwodu Dostawcy

Zakres: cały dostawca, np. glm, openai, anthropic.

Cel: zatrzymać wysyłanie ruchu do dostawcy, który wielokrotnie zawodzi na poziomie upstream/usługi, aby jeden niezdrowy dostawca nie spowalniał każdego żądania.

Implementacja:

  • Klasa główna: src/shared/utils/circuitBreaker.ts
  • Połączenie bramki czatu/wykonania: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • API statusu czasu wykonania: src/app/api/monitoring/health/route.ts
  • Wspólne opakowania: open-sse/services/accountFallback.ts
  • Tabela stanu utrwalanego: domain_circuit_breakers

Stany:

  • CLOSED: normalny ruch jest dozwolony.
  • OPEN: dostawca jest tymczasowo zablokowany; dzwoniący otrzymują odpowiedź provider-circuit-open lub routowanie combo pomija inny cel.
  • HALF_OPEN: czas resetu upłynął; zezwól na żądanie próbne. Sukces zamyka wyłącznik, niepowodzenie ponownie go otwiera.

Domyślne (open-sse/config/constants.ts):

  • Dostawcy OAuth: próg 3, czas resetu 60s.
  • Dostawcy kluczy API: próg 5, czas resetu 30s.
  • Dostawcy lokalni: próg 2, czas resetu 15s.

Tylko statusy awarii na poziomie dostawcy powinny uruchamiać wyłącznik dostawcy:

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

Nie uruchamiaj wyłącznika całego dostawcy dla normalnych błędów konta/klucza/modelu, takich jak większość 401, 403 lub 429. Zwykle należą one do cooldownu połączenia lub zablokowania modelu. Ogólny błąd dostawcy klucza API 403 powinien być możliwy do odzyskania, chyba że zostanie sklasyfikowany jako terminalny błąd dostawcy/konta.

Wyłącznik używa leniwego odzyskiwania, a nie tła. Gdy OPEN wygasa, odczyty takie jak getStatus(), canExecute(), i getRetryAfterMs() odświeżają stan do HALF_OPEN, aby pulpity nawigacyjne i budowniczy kandydatów combo nie wykluczali wygasłego dostawcy na zawsze.

Cooldown Połączenia

Zakres: jedno połączenie dostawcy/konto/klucz.

Cel: tymczasowo pominąć jeden zły klucz/konto, pozwalając innym połączeniom dla tego samego dostawcy kontynuować obsługę żądań.

Implementacja:

  • Ścieżka zapisu/aktualizacji: src/sse/services/auth.ts::markAccountUnavailable()
  • Wybór/filtracja konta: src/sse/services/auth.ts::getProviderCredentials...
  • Obliczanie cooldownu: open-sse/services/accountFallback.ts::checkFallbackError()
  • Ustawienia: src/lib/resilience/settings.ts

Ważne pola w połączeniach dostawcy:

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

Podczas wyboru konta, połączenie jest pomijane, gdy:

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

Cooldowny są również leniwe: gdy rateLimitedUntil jest w przeszłości, połączenie staje się ponownie kwalifikowalne. Po udanym użyciu, clearAccountError() czyści testStatus, rateLimitedUntil, pola błędów i backoffLevel.

Domyślne zachowanie cooldownu połączenia:

  • Podstawowy cooldown OAuth: 5s.
  • Podstawowy cooldown klucza API: 3s.
  • Klucz API 429 powinien preferować wskazówki ponownego próbowania upstream (Retry-After, nagłówki resetu lub tekst resetu do analizy) gdy są dostępne.
  • Powtarzające się odzyskiwalne błędy używają wykładniczego opóźnienia:
baseCooldownMs * 2 ** failureIndex;

Ochrona przed zjawiskiem "thundering herd" zapobiega równoczesnym awariom na tym samym połączeniu, które wielokrotnie wydłużają cooldown lub podwajają backoffLevel.

Stany terminalne nie są cooldownami. banned, expired, i credits_exhausted mają pozostać niedostępne, aż zmienią się dane uwierzytelniające/ustawienia lub operator je zresetuje. Nie nadpisuj stanów terminalnych stanem cooldownu.

Zablokowanie Modelu

Zakres: dostawca + połączenie + model.

Cel: unikać wyłączania całego połączenia, gdy tylko jeden model jest niedostępny lub ograniczony kwotowo dla tego połączenia.

Przykłady:

  • Dostawcy z kwotą na model zwracający 429.
  • Dostawcy lokalni zwracający 404 dla jednego brakującego modelu.
  • Specyficzne dla dostawcy błędy uprawnień trybu/modelu, takie jak wybrane tryby Grok.

Zablokowanie modelu znajduje się w open-sse/services/accountFallback.ts i pozwala temu samemu połączeniu kontynuować obsługę innych modeli.

Wskazówki Debuggingowe

  • Jeśli wszystkie klucze dla dostawcy są pomijane, sprawdź zarówno stan wyłącznika dostawcy, jak i rateLimitedUntil/testStatus każdego połączenia.
  • Jeśli dostawca wydaje się na stałe wykluczony po oknie resetu, sprawdź, czy kod odczytuje surowy state zamiast używać getStatus()/canExecute().
  • Jeśli jeden klucz dostawcy zawodzi, ale inne powinny działać, preferuj cooldown połączenia nad wyłącznikiem dostawcy.
  • Jeśli tylko jeden model zawodzi, preferuj zablokowanie modelu nad cooldownem połączenia.
  • Jeśli stan powinien samodzielnie się odzyskać, powinien mieć przyszły znacznik czasu/czas resetu i ścieżkę odczytu, która odświeża wygasły stan. Statusy permanentne wymagają ręcznych zmian danych uwierzytelniających lub konfiguracji.

Kluczowe Konwencje

Styl Kodowania

  • 2 spacje, średniki, podwójne cudzysłowy, szerokość 100 znaków, es5 przecinki na końcu (egzekwowane przez lint-staged za pomocą Prettier)
  • Importy: zewnętrzne → wewnętrzne (@/, @omniroute/open-sse) → względne
  • Nazewnictwo: pliki=camelCase/kebab, komponenty=PascalCase, stałe=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = błąd wszędzie; no-explicit-any = ostrzeżenie w open-sse/ i tests/
  • TypeScript: strict: false, cel ES2022, moduł esnext, rozdzielczość bundler. Preferuj jawne typy.

Baza Danych

  • Zawsze korzystaj z modułów domenowych w src/lib/db/ — nigdy nie pisz surowego SQL w trasach lub handlerach
  • Nigdy nie dodawaj logiki do src/lib/localDb.ts (tylko warstwa re-exportu)
  • Nigdy nie importuj z localDb.ts w sposób barrel-import — zamiast tego importuj konkretne moduły db/
  • Singleton DB: getDbInstance() z src/lib/db/core.ts (dziennik WAL)
  • Migracje: src/lib/db/migrations/ — wersjonowane pliki SQL, idempotentne, uruchamiane w transakcjach

Obsługa Błędów

  • try/catch z konkretnymi typami błędów, loguj z kontekstem pino
  • Nigdy nie ignoruj błędów w strumieniach SSE — używaj sygnałów przerywających do czyszczenia
  • Zwracaj odpowiednie kody statusu HTTP (4xx/5xx)

Bezpieczeństwo

  • Nigdy nie używaj eval(), new Function(), ani implikowanego eval
  • Waliduj wszystkie dane wejściowe za pomocą schematów Zod
  • Szyfruj dane uwierzytelniające w spoczynku (AES-256-GCM)
  • Lista nagłówków denylist: src/shared/constants/upstreamHeaders.ts — utrzymuj sanitizację, schematy Zod i testy jednostkowe w zgodzie podczas edytowania
  • Publiczne dane uwierzytelniające upstream (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + klucze Firebase Web wyciągnięte z publicznych CLI): MUSZĄ być osadzone za pomocą resolvePublicCred() z open-sse/utils/publicCreds.ts — nigdy jako literały stringowe. Zobacz docs/security/PUBLIC_CREDS.md dla obowiązkowego wzoru.
  • Odpowiedzi błędów (HTTP / SSE / executor / MCP handler): MUSZĄ przechodzić przez buildErrorBody() lub sanitizeErrorMessage() z open-sse/utils/error.ts — nigdy nie umieszczaj surowego err.stack lub err.message w ciele odpowiedzi. Zobacz docs/security/ERROR_SANITIZATION.md.
  • Polecenia powłoki budowane z zmiennych: podczas wywoływania exec()/spawn() z skryptem, który potrzebuje wartości w czasie wykonywania, przekaż je za pomocą opcji env (automatycznie escapowane w powłoce) — nigdy nie interpoluj nieufnych/zewnętrznych ścieżek do ciała skryptu. Odniesienie: src/mitm/cert/install.ts::updateNssDatabases.
  • Biblioteki zabezpieczone domyślnie (tldrsec/awesome-secure-defaults): preferuj Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink zamiast własnych implementacji, gdy dodajesz nowe powierzchnie wrażliwe na bezpieczeństwo.

Typowe Scenariusze Modyfikacji

Dodawanie Nowego Dostawcy

  1. Zarejestruj w src/shared/constants/providers.ts (walidowane przez Zod przy ładowaniu)
  2. Dodaj executor w open-sse/executors/, jeśli potrzebna jest logika niestandardowa (rozszerz BaseExecutor)
  3. Dodaj translator w open-sse/translator/, jeśli format nie jest OpenAI
  4. Dodaj konfigurację OAuth w src/lib/oauth/constants/oauth.ts, jeśli oparta na OAuth — jeśli upstream CLI dostarcza publiczny client_id/secret, osadź za pomocą resolvePublicCred() (zobacz docs/security/PUBLIC_CREDS.md), nigdy jako literał
  5. Zarejestruj modele w open-sse/config/providerRegistry.ts
  6. Napisz testy w tests/unit/ (dołącz asercję kształtu publicCreds, jeśli dodałeś nowy osadzony domyślny)

Dodawanie Nowej Trasy API

  1. Utwórz katalog pod src/app/api/v1/your-route/
  2. Utwórz route.ts z handlerami GET/POST
  3. Postępuj zgodnie ze wzorem: CORS → walidacja ciała Zod → opcjonalna autoryzacja → delegacja handlera
  4. Handler umieść w open-sse/handlers/ (importuj stamtąd, nie inline)
  5. Odpowiedzi błędów używają buildErrorBody() / errorResponse() z open-sse/utils/error.ts (automatycznie sanitizowane — nigdy nie umieszczaj surowego err.stack lub err.message w ciele). Zobacz docs/security/ERROR_SANITIZATION.md.
  6. Dodaj testy — w tym przynajmniej jedną asercję, że odpowiedzi błędów nie ujawniają śladów stosu (!body.error.message.includes("at /"))

Dodawanie Nowego Modułu DB

  1. Utwórz src/lib/db/yourModule.ts — importuj getDbInstance z ./core.ts
  2. Eksportuj funkcje CRUD dla swojej tabeli domenowej
  3. Dodaj migrację w src/lib/db/migrations/, jeśli potrzebne są nowe tabele
  4. Re-exportuj z src/lib/localDb.ts (dodaj tylko do listy re-exportu)
  5. Napisz testy

Dodawanie Nowego Narzędzia MCP

  1. Dodaj definicję narzędzia w open-sse/mcp-server/tools/ z schematem wejściowym Zod + asynchronicznym handlerem
  2. Zarejestruj w zestawie narzędzi (połączone przez createMcpServer())
  3. Przypisz do odpowiednich zakresów
  4. Napisz testy (wywołanie narzędzia logowane do tabeli mcp_audit)

Dodawanie Nowej Umiejętności A2A

  1. Utwórz umiejętność w src/lib/a2a/skills/ (istnieje już 5: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. Umiejętność otrzymuje kontekst zadania (wiadomości, metadane) → zwraca uporządkowany wynik
  3. Zarejestruj w A2A_SKILL_HANDLERS w src/lib/a2a/taskExecution.ts
  4. Udostępnij w src/app/.well-known/agent.json/route.ts (Agent Card)
  5. Napisz testy w tests/unit/
  6. Udokumentuj w tabeli umiejętności w docs/frameworks/A2A-SERVER.md

Dodawanie Nowego Agenta Chmurowego

  1. Utwórz klasę agenta w src/lib/cloudAgent/agents/, rozszerzając CloudAgentBase (istnieją już 3: codex-cloud, devin, jules)
  2. Zaimplementuj createTask, getStatus, approvePlan, sendMessage, listSources
  3. Zarejestruj w src/lib/cloudAgent/registry.ts
  4. Dodaj obsługę OAuth/danych uwierzytelniających, jeśli to konieczne (src/lib/oauth/providers/)
  5. Testy + dokumentacja w docs/frameworks/CLOUD_AGENT.md

Dodawanie Nowego Guardrail / Eval / Skill / Wydarzenia Webhook

  • Guardrail: src/lib/guardrails/ → dokumentacja: docs/security/GUARDRAILS.md
  • Zestaw Eval: src/lib/evals/ → dokumentacja: docs/frameworks/EVALS.md
  • Umiejętność (sandbox): src/lib/skills/ → dokumentacja: docs/frameworks/SKILLS.md
  • Wydarzenie Webhook: src/lib/webhookDispatcher.ts → dokumentacja: docs/frameworks/WEBHOOKS.md

Dokumentacja referencyjna

Dla każdej niebanalnej zmiany, najpierw przeczytaj odpowiedni szczegółowy dokument:

Obszar Dokument
Nawigacja repozytoriów docs/architecture/REPOSITORY_MAP.md
Architektura docs/architecture/ARCHITECTURE.md
Dokumentacja inżynieryjna docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-czynnikowe ocenianie, 14 strategii) docs/routing/AUTO-COMBO.md
Odporność (3 mechanizmy) docs/architecture/RESILIENCE_GUIDE.md
Odtwarzanie rozumowania docs/routing/REASONING_REPLAY.md
Ramy umiejętności docs/frameworks/SKILLS.md
System pamięci (FTS5 + Qdrant) docs/frameworks/MEMORY.md
Agenci chmurowi docs/frameworks/CLOUD_AGENT.md
Zasady bezpieczeństwa (PII / wstrzykiwanie / wizja) docs/security/GUARDRAILS.md
Publiczne dane uwierzytelniające (Gemini/itd.) docs/security/PUBLIC_CREDS.md
Sanityzacja komunikatów o błędach docs/security/ERROR_SANITIZATION.md
Oceny docs/frameworks/EVALS.md
Zgodność / audyt docs/security/COMPLIANCE.md
Webhooki docs/frameworks/WEBHOOKS.md
Pipeline autoryzacji docs/architecture/AUTHZ_GUIDE.md
Stealth (TLS / odcisk palca) docs/security/STEALTH_GUIDE.md
Protokoły agentów (A2A / ACP / Cloud) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
Serwer MCP docs/frameworks/MCP-SERVER.md
Serwer A2A docs/frameworks/A2A-SERVER.md
Referencja API + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Katalog dostawców (automatycznie generowany) docs/reference/PROVIDER_REFERENCE.md
Proces wydania docs/ops/RELEASE_CHECKLIST.md

Testowanie

Co Komenda
Testy jednostkowe npm run test:unit
Pojedynczy plik node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo) npm run test:vitest
E2E (Playwright) npm run test:e2e
Protokół E2E (MCP+A2A) npm run test:protocols:e2e
Ekosystem npm run test:ecosystem
Brama pokrycia npm run test:coverage (75/75/75/70 — instrukcje/linie/funkcje/gałęzie)
Raport pokrycia npm run coverage:report

Zasada PR: Jeśli zmieniasz kod produkcyjny w src/, open-sse/, electron/, lub bin/, musisz dodać lub zaktualizować testy w tym samym PR.

Preferencje warstwy testów: najpierw jednostkowe → integracyjne (wielomodułowe lub stan DB) → e2e (tylko UI/flow). Zakoduj reprodukcje błędów jako automatyczne testy przed lub równolegle z poprawką.

Polityka pokrycia Copilot: Gdy PR zmienia kod produkcyjny, a pokrycie jest poniżej 75% (instrukcje/linie/funkcje) lub 70% (gałęzie), nie tylko zgłaszaj — dodaj lub zaktualizuj testy, uruchom ponownie bramę pokrycia, a następnie poproś o potwierdzenie. Dołącz uruchomione komendy, zmienione pliki testowe i ostateczny wynik pokrycia w raporcie PR.

Workflow Git

# Nigdy nie commituj bezpośrednio do main
git checkout -b feat/your-feature
git commit -m "feat: opisz swoją zmianę"
git push -u origin feat/your-feature

Prefiksy gałęzi: feat/, fix/, refactor/, docs/, test/, chore/

Format commitów (Conventional Commits): feat(db): dodaj circuit breaker — zakresy: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Haki Husky:

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

Środowisko

  • Czas działania: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
  • TypeScript: 5.9+, cel ES2022, moduł esnext, rozdzielczość bundler
  • Alias ścieżek: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • Domyślny port: 20128 (API + dashboard na tym samym porcie)
  • Katalog danych: zmienna środowiskowa DATA_DIR, domyślnie ~/.omniroute/
  • Kluczowe zmienne środowiskowe: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • Konfiguracja: cp .env.example .env, a następnie wygeneruj JWT_SECRET (openssl rand -base64 48) i API_KEY_SECRET (openssl rand -hex 32)

Twarde zasady

  1. Nigdy nie commituj sekretów ani poświadczeń
  2. Nigdy nie dodawaj logiki do localDb.ts
  3. Nigdy nie używaj eval() / new Function() / domyślnego eval
  4. Nigdy nie commituj bezpośrednio do main
  5. Nigdy nie pisz surowego SQL w trasach — używaj modułów src/lib/db/
  6. Nigdy nie ignoruj błędów w strumieniach SSE
  7. Zawsze waliduj dane wejściowe za pomocą schematów Zod
  8. Zawsze dołączaj testy przy zmianie kodu produkcyjnego
  9. Pokrycie musi wynosić ≥75% (instrukcje, linie, funkcje) / ≥70% (gałęzie). Aktualnie zmierzone: ~82%.
  10. Nigdy nie omijaj haków Husky (--no-verify, --no-gpg-sign) bez wyraźnej zgody operatora.
  11. Nigdy nie osadzaj publicznych upstream OAuth client_id/secret ani kluczy Firebase Web jako literałów stringowych — zawsze korzystaj z resolvePublicCred() (open-sse/utils/publicCreds.ts). Zobacz docs/security/PUBLIC_CREDS.md.
  12. Nigdy nie zwracaj surowego err.stack / err.message w odpowiedziach HTTP / SSE / executor — zawsze kieruj przez buildErrorBody() lub sanitizeErrorMessage() (open-sse/utils/error.ts). Zobacz docs/security/ERROR_SANITIZATION.md.
  13. Nigdy nie interpoluj zewnętrznych ścieżek ani wartości czasu wykonania do skryptów powłoki przekazywanych do exec()/spawn() — przekazuj przez opcję env. Odniesienie: src/mitm/cert/install.ts::updateNssDatabases.
  14. Nigdy nie ignoruj alertu CodeQL / Secret-Scanning bez (a) najpierw sprawdzenia dokumentacji wzorców powyżej, aby zobaczyć, czy pomocnik ma zastosowanie, oraz (b) zapisania uzasadnienia technicznego w komentarzu o odrzuceniu. Precedens: js/stack-trace-exposure zgłoszone w miejscach wywołania, które już kierują przez sanitizeErrorMessage(), jest znanym ograniczeniem CodeQL (niestandardowe sanitizery nie są rozpoznawane) — odrzuć jako fałszywy pozytyw, odnosząc się do docs/security/ERROR_SANITIZATION.md.
  15. Nigdy nie udostępniaj tras, które uruchamiają procesy podrzędne (/api/mcp/, /api/cli-tools/runtime/) bez klasyfikacji isLocalOnlyPath() w src/server/authz/routeGuard.ts. Egzekucja loopback odbywa się bezwarunkowo przed jakąkolwiek kontrolą autoryzacji — wyciekający JWT przez tunel nie może uruchomić procesów. Zobacz docs/security/ROUTE_GUARD_TIERS.md.
  16. Nigdy nie dołączaj nagłówków Co-Authored-By, które przypisują zasługi asystentowi AI, LLM lub kontu automatyzacji (np. nazwy zawierające "Claude", "GPT", "Copilot", "Bot"; e-maile w anthropic.com / openai.com / adresach noreply.github.com należących do botów). Takie nagłówki kierują atrybucję commitów do konta bota na GitHubie, ukrywając prawdziwego autora (diegosouzapw) w historii PR. Współpracownicy ludzcy — w tym autorzy upstream PR i zgłaszający issues portowanych do OmniRoute — MOGĄ i POWINNI być uznawani standardowymi nagłówkami Co-authored-by: Name <email>; przepływy pracy upstream-port (/port-upstream-features, /port-upstream-issues) zależą od tego.
Reference in New Issue View Git Blame Copy Permalink