# CLAUDE.md (Deutsch) 🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md) --- Diese Datei bietet Anleitungen für Claude Code (claude.ai/code) beim Arbeiten mit Code in diesem Repository. ## Schnellstart ```bash 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 ```bash # 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](./docs/diagrams/exported/resilience-3layers.svg) (Quelle: [docs/diagrams/resilience-3layers.mmd](./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: ```ts (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: ```ts rateLimitedUntil; testStatus: "unavailable"; lastError; lastErrorType; errorCode; backoffLevel; ``` Während der Kontenauswahl wird eine Verbindung übersprungen, während: ```ts 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: ```ts 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](https://github.com/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 ```bash # 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 `-Trailern gewürdigt werden; die Upstream-Port-Workflows (`/port-upstream-features`, `/port-upstream-issues`) hängen davon ab.