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/de/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 (Deutsch)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇪🇸 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

Diese Datei bietet Anleitungen für Claude Code (claude.ai/code) beim Arbeiten mit Code in diesem Repository.

Schnellstart

npm install                    # Abhängigkeiten installieren (erstellt automatisch .env aus .env.example)
npm run dev                    # Entwicklungsserver unter http://localhost:20128
npm run build                  # Produktionsbuild (Next.js 16 standalone)
npm run lint                   # ESLint (0 Fehler erwartet; Warnungen sind bereits vorhanden)
npm run typecheck:core         # TypeScript-Überprüfung (sollte sauber sein)
npm run typecheck:noimplicit:core  # Strenge Überprüfung (kein implizites any)
npm run test:coverage          # Unit-Tests + Coverage-Gate (75/75/75/70 — Anweisungen/Zeilen/Funktionen/Zweige)
npm run check                  # lint + test kombiniert
npm run check:cycles           # Zirkuläre Abhängigkeiten erkennen

Tests Ausführen

# Einzelne Testdatei (Node.js nativer Test-Runner — die meisten Tests)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP-Server, autoCombo, Cache)
npm run test:vitest

# Alle Suiten
npm run test:all

Für die vollständige Testmatrix siehe CONTRIBUTING.md → "Tests Ausführen". Für die tiefere Architektur siehe AGENTS.md.

Projekt auf einen Blick

OmniRoute — einheitlicher KI-Proxy/Router. Ein Endpunkt, 160+ LLM-Anbieter, automatischer Fallback.

Schicht Standort Zweck
API-Routen src/app/api/v1/ Next.js App Router — Einstiegspunkte
Handler open-sse/handlers/ Anfrageverarbeitung (Chat, Embeddings usw.)
Executor open-sse/executors/ Anbieter-spezifische HTTP-Zustellung
Übersetzer open-sse/translator/ Formatkonvertierung (OpenAI↔Claude↔Gemini)
Transformator open-sse/transformer/ Antworten API ↔ Chat-Vervollständigungen
Dienste open-sse/services/ Kombinierte Routen, Ratenlimits, Caching usw.
Datenbank src/lib/db/ SQLite-Domain-Module (45+ Dateien, 55 Migrationen)
Domain/Politik src/domain/ Regel-Engine, Kostenregeln, Fallback-Logik
MCP-Server open-sse/mcp-server/ 37 Werkzeuge (30 Basis + 3 Speicher + 4 Fähigkeiten), 3 Transporte, ~13 Bereiche
A2A-Server src/lib/a2a/ JSON-RPC 2.0 Agent-Protokoll
Fähigkeiten src/lib/skills/ Erweiterbares Fähigkeitsframework
Speicher src/lib/memory/ Persistenter konversationeller Speicher

Monorepo: src/ (Next.js 16 App), open-sse/ (Streaming-Engine-Arbeitsbereich), electron/ (Desktop-App), tests/, bin/ (CLI-Einstiegspunkt).

Anfrage-Pipeline

Client → /v1/chat/completions (Next.js Route)
  → CORS → Zod-Validierung → Auth? → Richtlinienprüfung → Schutz vor Eingabeinjektion
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → Cache-Prüfung → Ratenbegrenzung → Kombinationsrouting?
      → resolveComboTargets() → handleSingleModel() pro Ziel
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → erneut versuchen mit Backoff
    → Antwortübersetzung → SSE-Stream oder JSON
    → Wenn Responses API: responsesTransformer.ts TransformStream

API-Routen folgen einem konsistenten Muster: Route → CORS Preflight → Zod Body-Validierung → Optionale Authentifizierung (extractApiKey/isValidApiKey) → Durchsetzung der API-Schlüsselrichtlinie → Handler-Delegation (open-sse). Kein globales Next.js-Middleware — die Abfangung ist routenspezifisch.

Kombinationsrouting (open-sse/services/combo.ts): 14 Strategien (Priorität, gewichtet, zuerst auffüllen, Round-Robin, P2C, zufällig, am wenigsten verwendet, kostenoptimiert, reset-bewusst, strikt-zufällig, auto, lkgp, kontextoptimiert, kontextweiterleitung). Jedes Ziel ruft handleSingleModel() auf, das handleChatCore() mit fehlerbehandelnden und Schaltkreisprüfungen pro Ziel umschließt. Siehe docs/routing/AUTO-COMBO.md für die 9-Faktor Auto-Combo-Bewertung und docs/architecture/RESILIENCE_GUIDE.md für die 3 Resilienzschichten.

Resilienz-Laufzeitstatus

OmniRoute hat drei verwandte, aber unterschiedliche Mechanismen für temporäre Fehler. Halten Sie ihren Bereich beim Debuggen des Routing-Verhaltens getrennt. Siehe das 3-Schichten-Resilienzdiagramm (Quelle: docs/diagrams/resilience-3layers.mmd) für eine Übersichtskarte.

Anbieter-Schaltkreisunterbrecher

Bereich: ganzer Anbieter, z.B. glm, openai, anthropic.

Zweck: Stoppen des Datenverkehrs zu einem Anbieter, der wiederholt auf der Upstream-/Service-Ebene ausfällt, damit ein ungesunder Anbieter nicht jede Anfrage verlangsamt.

Implementierung:

  • Kernklasse: src/shared/utils/circuitBreaker.ts
  • Chat-Gate/Ausführungsverkabelung: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • Laufzeitstatus-API: src/app/api/monitoring/health/route.ts
  • Gemeinsame Wrapper: open-sse/services/accountFallback.ts
  • Persistierte Status-Tabelle: domain_circuit_breakers

Zustände:

  • CLOSED: normaler Datenverkehr ist erlaubt.
  • OPEN: Anbieter ist vorübergehend blockiert; Anrufer erhalten eine Antwort mit Anbieter-Schaltkreis-offen oder das Kombinationsrouting überspringt zu einem anderen Ziel.
  • HALF_OPEN: Reset-Timeout ist abgelaufen; eine Probeanforderung ist erlaubt. Erfolg schließt den Schalter, Misserfolg öffnet ihn erneut.

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

  • OAuth-Anbieter: Schwellenwert 3, Reset-Timeout 60s.
  • API-Schlüssel-Anbieter: Schwellenwert 5, Reset-Timeout 30s.
  • Lokale Anbieter: Schwellenwert 2, Reset-Timeout 15s.

Nur Anbieter-spezifische Fehlerstatus sollten den Anbieter-Schalter auslösen:

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

Lösen Sie den gesamten Anbieter-Schalter nicht für normale Konto-/Schlüssel-/Modellfehler wie die meisten 401, 403 oder 429 Fälle aus. Diese gehören normalerweise zu Verbindungsabkühlung oder Modell Sperrung. Ein generischer API-Schlüssel-Anbieter 403 sollte wiederherstellbar sein, es sei denn, er wird als terminaler Anbieter/Konto-Fehler klassifiziert.

Der Schalter verwendet eine verzögerte Wiederherstellung, keinen Hintergrundtimer. Wenn OPEN abläuft, werden Lesevorgänge wie getStatus(), canExecute() und getRetryAfterMs() den Status auf HALF_OPEN aktualisieren, sodass Dashboards und Kombinationskandidatenbauer einen abgelaufenen Anbieter nicht für immer ausschließen.

Verbindungsabkühlung

Bereich: eine Anbieter-Verbindung/Konto/Schlüssel.

Zweck: vorübergehend einen schlechten Schlüssel/Konto überspringen, während andere Verbindungen für den gleichen Anbieter weiterhin Anfragen bedienen.

Implementierung:

  • Schreib-/Aktualisierungspfad: src/sse/services/auth.ts::markAccountUnavailable()
  • Kontenauswahl/-filterung: src/sse/services/auth.ts::getProviderCredentials...
  • Abkühlungsberechnung: open-sse/services/accountFallback.ts::checkFallbackError()
  • Einstellungen: src/lib/resilience/settings.ts

Wichtige Felder bei Anbieter-Verbindungen:

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

Während der Kontenauswahl wird eine Verbindung übersprungen, während:

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

Abkühlungen sind ebenfalls verzögert: Wenn rateLimitedUntil in der Vergangenheit liegt, wird die Verbindung wieder berechtigt. Bei erfolgreicher Nutzung löscht clearAccountError() testStatus, rateLimitedUntil, Fehlerfelder und backoffLevel.

Standardverhalten der Verbindungsabkühlung:

  • OAuth-Basisabkühlung: 5s.
  • API-Schlüssel-Basisabkühlung: 3s.
  • API-Schlüssel 429 sollte bevorzugt Hinweise für erneute Versuche von upstream verwenden (Retry-After, Reset-Header oder parsebaren Reset-Text), wenn verfügbar.
  • Wiederholte wiederherstellbare Fehler verwenden exponentielles Backoff:
baseCooldownMs * 2 ** failureIndex;

Der Anti-Thundering-Herd-Schutz verhindert, dass gleichzeitige Fehler bei derselben Verbindung die Abkühlung wiederholt verlängern oder backoffLevel doppelt erhöhen.

Terminalzustände sind keine Abkühlungen. banned, expired und credits_exhausted sollen unverfügbar bleiben, bis sich Anmeldeinformationen/Einstellungen ändern oder ein Betreiber sie zurücksetzt. Überschreiben Sie keine terminalen Zustände mit transienten Abkühlungszuständen.

Modell-Sperrung

Bereich: Anbieter + Verbindung + Modell.

Zweck: Vermeiden, dass eine ganze Verbindung deaktiviert wird, wenn nur ein Modell für diese Verbindung nicht verfügbar oder kontingentbeschränkt ist.

Beispiele:

  • Pro-Modell-Kontingent-Anbieter, die 429 zurückgeben.
  • Lokale Anbieter, die 404 für ein fehlendes Modell zurückgeben.
  • Anbieter-spezifische Modus-/Modellberechtigungsfehler wie ausgewählte Grok-Modi.

Die Modell-Sperrung befindet sich in open-sse/services/accountFallback.ts und ermöglicht es der gleichen Verbindung, weiterhin andere Modelle zu bedienen.

Debugging-Anleitung

  • Wenn alle Schlüssel für einen Anbieter übersprungen werden, überprüfen Sie sowohl den Status des Anbieterschalters als auch rateLimitedUntil/testStatus jeder Verbindung.
  • Wenn ein Anbieter nach dem Reset-Fenster dauerhaft ausgeschlossen erscheint, überprüfen Sie, ob der Code den Rohstatus state anstelle von getStatus()/canExecute() liest.
  • Wenn ein Anbieter-Schlüssel fehlschlägt, aber andere funktionieren sollten, bevorzugen Sie die Verbindungsabkühlung gegenüber dem Anbieter-Schalter.
  • Wenn nur ein Modell fehlschlägt, bevorzugen Sie die Modell-Sperrung gegenüber der Verbindungsabkühlung.
  • Wenn ein Zustand sich selbst wiederherstellen sollte, sollte er einen zukünftigen Zeitstempel/Reset-Timeout und einen Leseweg haben, der abgelaufene Zustände aktualisiert. Permanente Status erfordern manuelle Änderungen an Anmeldeinformationen oder Konfiguration.

Schlüsselkonventionen

Code-Stil

  • 2 Leerzeichen, Semikolons, doppelte Anführungszeichen, 100 Zeichen Breite, es5 nachgestellte Kommas (durch lint-staged über Prettier durchgesetzt)
  • Imports: extern → intern (@/, @omniroute/open-sse) → relativ
  • Benennung: Dateien=camelCase/kebab, Komponenten=PascalCase, Konstanten=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = Fehler überall; no-explicit-any = Warnung in open-sse/ und tests/
  • TypeScript: strict: false, Ziel ES2022, Modul esnext, Auflösung Bundler. Bevorzugen Sie explizite Typen.

Datenbank

  • Immer über src/lib/db/ Domänenmodule gehen — nie rohes SQL in Routen oder Handlern schreiben
  • Nie Logik zu src/lib/localDb.ts hinzufügen (nur Re-Export-Schicht)
  • Nie Barrel-Import von localDb.ts — stattdessen spezifische db/-Module importieren
  • DB-Singleton: getDbInstance() aus src/lib/db/core.ts (WAL-Journaling)
  • Migrationen: src/lib/db/migrations/ — versionierte SQL-Dateien, idempotent, in Transaktionen ausführen

Fehlerbehandlung

  • try/catch mit spezifischen Fehlertypen, protokollieren mit pino-Kontext
  • Nie Fehler in SSE-Streams unterdrücken — verwenden Sie Abbruchsignale zur Bereinigung
  • Geben Sie die richtigen HTTP-Statuscodes zurück (4xx/5xx)

Sicherheit

  • Nie eval(), new Function(), oder implizites eval verwenden
  • Validieren Sie alle Eingaben mit Zod-Schemas
  • Verschlüsseln Sie Anmeldeinformationen im Ruhezustand (AES-256-GCM)
  • Upstream-Header-Denylist: src/shared/constants/upstreamHeaders.ts — halten Sie Sanitär-, Zod-Schemas und Unit-Tests beim Bearbeiten synchron
  • Öffentliche Upstream-Anmeldeinformationen (Gemini/Antigravity/Windsurf-Stil OAuth client_id/secret + Firebase Web-Schlüssel, die aus öffentlichen CLIs extrahiert wurden): MÜSSEN über resolvePublicCred() aus open-sse/utils/publicCreds.ts eingebettet werden — nie als String-Literale. Siehe docs/security/PUBLIC_CREDS.md für das obligatorische Muster.
  • Fehlerantworten (HTTP / SSE / Executor / MCP-Handler): MÜSSEN über buildErrorBody() oder sanitizeErrorMessage() aus open-sse/utils/error.ts geleitet werden — nie rohes err.stack oder err.message in einem Antwortkörper einfügen. Siehe docs/security/ERROR_SANITIZATION.md.
  • Shell-Befehle, die aus Variablen erstellt werden: beim Aufrufen von exec()/spawn() mit einem Skript, das Laufzeitwerte benötigt, übergeben Sie diese über die env-Option (automatisch shell-escaped) — nie untrusted/externe Pfade in den Skriptkörper interpolieren. Referenz: src/mitm/cert/install.ts::updateNssDatabases.
  • Sichere Standardbibliotheken (tldrsec/awesome-secure-defaults): Bevorzugen Sie Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink gegenüber benutzerdefinierten Implementierungen, wenn Sie neue sicherheitskritische Oberflächen hinzufügen.

Häufige Änderungszenarien

Hinzufügen eines neuen Anbieters

  1. Registrieren Sie sich in src/shared/constants/providers.ts (Zod-validiert beim Laden)
  2. Fügen Sie einen Executor in open-sse/executors/ hinzu, wenn benutzerdefinierte Logik benötigt wird (erweitern Sie BaseExecutor)
  3. Fügen Sie einen Übersetzer in open-sse/translator/ hinzu, wenn es sich um ein nicht-OpenAI-Format handelt
  4. Fügen Sie die OAuth-Konfiguration in src/lib/oauth/constants/oauth.ts hinzu, wenn OAuth-basiert — wenn die Upstream-CLI eine öffentliche client_id/secret bereitstellt, betten Sie sie über resolvePublicCred() ein (siehe docs/security/PUBLIC_CREDS.md), nie als Literal
  5. Registrieren Sie Modelle in open-sse/config/providerRegistry.ts
  6. Schreiben Sie Tests in tests/unit/ (einschließlich der öffentlichen Creds-Formassertion, wenn Sie ein neues eingebettetes Standard hinzugefügt haben)

Hinzufügen einer neuen API-Route

  1. Erstellen Sie ein Verzeichnis unter src/app/api/v1/your-route/
  2. Erstellen Sie route.ts mit GET/POST-Handlern
  3. Folgen Sie dem Muster: CORS → Zod-Body-Validierung → optionale Authentifizierung → Handler-Delegation
  4. Der Handler geht in open-sse/handlers/ (von dort importieren, nicht inline)
  5. Fehlerantworten verwenden buildErrorBody() / errorResponse() aus open-sse/utils/error.ts (automatisch sanitisiert — niemals err.stack oder err.message roh im Körper einfügen). Siehe docs/security/ERROR_SANITIZATION.md.
  6. Fügen Sie Tests hinzu — einschließlich mindestens einer Assertion, dass Fehlerantworten keine Stack-Traces ausgeben (!body.error.message.includes("at /"))

Hinzufügen eines neuen DB-Moduls

  1. Erstellen Sie src/lib/db/yourModule.ts — importieren Sie getDbInstance aus ./core.ts
  2. Exportieren Sie CRUD-Funktionen für Ihre Domänentabelle(n)
  3. Fügen Sie eine Migration in src/lib/db/migrations/ hinzu, wenn neue Tabellen benötigt werden
  4. Re-Exportieren Sie aus src/lib/localDb.ts (nur zur Re-Exportliste hinzufügen)
  5. Schreiben Sie Tests

Hinzufügen eines neuen MCP-Tools

  1. Fügen Sie die Tool-Definition in open-sse/mcp-server/tools/ mit Zod-Eingabeschema + asynchronem Handler hinzu
  2. Registrieren Sie sich im Tool-Set (verkabelt durch createMcpServer())
  3. Weisen Sie die entsprechenden Bereiche zu
  4. Schreiben Sie Tests (Toolaufruf wird in der mcp_audit-Tabelle protokolliert)

Hinzufügen einer neuen A2A-Fähigkeit

  1. Erstellen Sie die Fähigkeit in src/lib/a2a/skills/ (5 existieren bereits: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. Die Fähigkeit erhält den Aufgaben-Kontext (Nachrichten, Metadaten) → gibt ein strukturiertes Ergebnis zurück
  3. Registrieren Sie sich in A2A_SKILL_HANDLERS in src/lib/a2a/taskExecution.ts
  4. Exponieren Sie in src/app/.well-known/agent.json/route.ts (Agent Card)
  5. Schreiben Sie Tests in tests/unit/
  6. Dokumentieren Sie in docs/frameworks/A2A-SERVER.md in der Fähigkeits-Tabelle

Hinzufügen eines neuen Cloud-Agenten

  1. Erstellen Sie die Agentenklasse in src/lib/cloudAgent/agents/, die CloudAgentBase erweitert (3 existieren bereits: codex-cloud, devin, jules)
  2. Implementieren Sie createTask, getStatus, approvePlan, sendMessage, listSources
  3. Registrieren Sie sich in src/lib/cloudAgent/registry.ts
  4. Fügen Sie die OAuth-/Anmeldeinformationsbehandlung hinzu, falls erforderlich (src/lib/oauth/providers/)
  5. Tests + Dokumentation in docs/frameworks/CLOUD_AGENT.md

Hinzufügen eines neuen Guardrails / Eval / Skill / Webhook-Ereignis

  • Guardrail: src/lib/guardrails/ → Dokumente: docs/security/GUARDRAILS.md
  • Eval-Suite: src/lib/evals/ → Dokumente: docs/frameworks/EVALS.md
  • Skill (Sandbox): src/lib/skills/ → Dokumente: docs/frameworks/SKILLS.md
  • Webhook-Ereignis: src/lib/webhookDispatcher.ts → Dokumente: docs/frameworks/WEBHOOKS.md

Referenzdokumentation

Für jede nicht triviale Änderung lesen Sie zuerst das entsprechende Deep-Dive:

Bereich Dokument
Repo-Navigation docs/architecture/REPOSITORY_MAP.md
Architektur docs/architecture/ARCHITECTURE.md
Ingenieureferenzen docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-Faktoren-Bewertung, 14 Strategien) docs/routing/AUTO-COMBO.md
Resilienz (3 Mechanismen) docs/architecture/RESILIENCE_GUIDE.md
Reasoning Replay docs/routing/REASONING_REPLAY.md
Fähigkeiten-Rahmen docs/frameworks/SKILLS.md
Gedächtnissystem (FTS5 + Qdrant) docs/frameworks/MEMORY.md
Cloud-Agenten docs/frameworks/CLOUD_AGENT.md
Leitplanken (PII / Injektion / Vision) docs/security/GUARDRAILS.md
Öffentliche Upstream-Anmeldeinformationen (Gemini/etc.) docs/security/PUBLIC_CREDS.md
Fehlernachrichtensanitierung docs/security/ERROR_SANITIZATION.md
Bewertungen docs/frameworks/EVALS.md
Compliance / Audit docs/security/COMPLIANCE.md
Webhooks docs/frameworks/WEBHOOKS.md
Autorisierungs-Pipeline docs/architecture/AUTHZ_GUIDE.md
Stealth (TLS / Fingerabdruck) docs/security/STEALTH_GUIDE.md
Agent-Protokolle (A2A / ACP / Cloud) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP-Server docs/frameworks/MCP-SERVER.md
A2A-Server docs/frameworks/A2A-SERVER.md
API-Referenz + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Anbieterkatalog (automatisch generiert) docs/reference/PROVIDER_REFERENCE.md
Release-Flow docs/ops/RELEASE_CHECKLIST.md

Testen

Was Befehl
Unit-Tests npm run test:unit
Einzelne Datei node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo) npm run test:vitest
E2E (Playwright) npm run test:e2e
Protokoll E2E (MCP+A2A) npm run test:protocols:e2e
Ökosystem npm run test:ecosystem
Coverage-Gate npm run test:coverage (75/75/75/70 — Anweisungen/Zeilen/Funktionen/Zweige)
Coverage-Bericht npm run coverage:report

PR-Regel: Wenn Sie Produktionscode in src/, open-sse/, electron/ oder bin/ ändern, müssen Sie Tests im selben PR einfügen oder aktualisieren.

Testschicht-Präferenz: Unit zuerst → Integration (Multi-Modul oder DB-Zustand) → E2E (UI/Workflow nur). Kodieren Sie Fehlerreproduktionen als automatisierte Tests vor oder zusammen mit der Behebung.

Copilot-Coverage-Richtlinie: Wenn ein PR Produktionscode ändert und die Abdeckung unter 75% (Anweisungen/Zeilen/Funktionen) oder 70% (Zweige) liegt, berichten Sie nicht nur — fügen Sie Tests hinzu oder aktualisieren Sie diese, führen Sie das Coverage-Gate erneut aus und bitten Sie um Bestätigung. Fügen Sie die ausgeführten Befehle, geänderten Testdateien und das endgültige Abdeckungsergebnis im PR-Bericht hinzu.

Git-Workflow

# Niemals direkt in main committen
git checkout -b feat/your-feature
git commit -m "feat: beschreibe deine Änderung"
git push -u origin feat/your-feature

Branch-Präfixe: feat/, fix/, refactor/, docs/, test/, chore/

Commit-Format (Conventional Commits): feat(db): circuit breaker hinzufügen — Scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky-Hooks:

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

Umgebung

  • Laufzeit: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES-Module
  • TypeScript: 5.9+, Ziel ES2022, Modul esnext, Auflösung Bundler
  • Pfad-Aliase: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • Standardport: 20128 (API + Dashboard am selben Port)
  • Datenverzeichnis: DATA_DIR Umgebungsvariable, standardmäßig ~/.omniroute/
  • Wichtige Umgebungsvariablen: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • Einrichtung: cp .env.example .env und dann JWT_SECRET (openssl rand -base64 48) und API_KEY_SECRET (openssl rand -hex 32) generieren

Harte Regeln

  1. Niemals Geheimnisse oder Anmeldeinformationen committen
  2. Niemals Logik in localDb.ts hinzufügen
  3. Niemals eval() / new Function() / implizites eval verwenden
  4. Niemals direkt in main committen
  5. Niemals rohes SQL in Routen schreiben — verwenden Sie src/lib/db/-Module
  6. Niemals Fehler in SSE-Streams stillschweigend unterdrücken
  7. Immer Eingaben mit Zod-Schemas validieren
  8. Immer Tests einfügen, wenn Produktionscode geändert wird
  9. Die Abdeckung muss ≥75% (Anweisungen, Zeilen, Funktionen) / ≥70% (Zweige) bleiben. Aktuell gemessen: ~82%.
  10. Niemals Husky-Hooks umgehen (--no-verify, --no-gpg-sign) ohne ausdrückliche Genehmigung des Betreibers.
  11. Niemals öffentliche Upstream OAuth client_id/secret oder Firebase Web-Schlüssel als String-Literale einbetten — immer über resolvePublicCred() (open-sse/utils/publicCreds.ts) gehen. Siehe docs/security/PUBLIC_CREDS.md.
  12. Niemals rohes err.stack / err.message in HTTP / SSE / Executor-Antworten zurückgeben — immer über buildErrorBody() oder sanitizeErrorMessage() (open-sse/utils/error.ts) leiten. Siehe docs/security/ERROR_SANITIZATION.md.
  13. Niemals externe Pfade oder Laufzeitwerte in Shell-Skripte interpolieren, die an exec()/spawn() übergeben werden — stattdessen über die env-Option übergeben. Referenz: src/mitm/cert/install.ts::updateNssDatabases.
  14. Niemals einen CodeQL / Secret-Scanning-Alarm ohne (a) vorherige Überprüfung der Musterdokumentation oben, um zu sehen, ob der Helfer anwendbar ist, und (b) die technische Begründung im Ablehnungs-Kommentar aufzeichnen. Präzedenzfall: js/stack-trace-exposure, das an Callsites ausgelöst wird, die bereits über sanitizeErrorMessage() geleitet werden, ist eine bekannte CodeQL-Einschränkung (benutzerdefinierte Sanitizer werden nicht erkannt) — als false positive abweisen mit Verweis auf docs/security/ERROR_SANITIZATION.md.
  15. Niemals Routen, die Kindprozesse erzeugen (/api/mcp/, /api/cli-tools/runtime/), ohne isLocalOnlyPath()-Klassifizierung in src/server/authz/routeGuard.ts einbeziehen. Die Loopback-Durchsetzung erfolgt bedingungslos vor jeder Authentifizierungsprüfung — ein durch Tunnel geleakter JWT kann keinen Prozessstart auslösen. Siehe docs/security/ROUTE_GUARD_TIERS.md.
  16. Niemals Co-Authored-By-Trailer einfügen, die einen KI-Assistenten, LLM oder Automatisierungskonto würdigen (z. B. Namen mit "Claude", "GPT", "Copilot", "Bot"; E-Mails unter anthropic.com / openai.com / bot-eigenen noreply.github.com-Adressen). Solche Trailer leiten die Commit-Zuordnung auf das Bot-Konto auf GitHub um und verbergen den echten Autor (diegosouzapw) in der PR-Historie. Menschliche Mitwirkende — einschließlich Upstream-PR-Autoren und Issue-Berichterstattern, die in OmniRoute portiert werden — DÜRFEN und SOLLTEN mit standardmäßigen Co-authored-by: Name <email>-Trailern gewürdigt werden; die Upstream-Port-Workflows (/port-upstream-features, /port-upstream-issues) hängen davon ab.
Reference in New Issue View Git Blame Copy Permalink