# Contributing to OmniRoute (Deutsch) 🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇪🇹 [am](../am/CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇦🇿 [az](../az/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇧🇩 [bn](../bn/CONTRIBUTING.md) · 🇧🇦 [bs](../bs/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇬🇷 [el](../el/CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇪🇪 [et](../et/CONTRIBUTING.md) · 🇮🇷 [fa](../fa/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇮🇪 [ga](../ga/CONTRIBUTING.md) · 🇮🇳 [gu](../gu/CONTRIBUTING.md) · 🇳🇬 [ha](../ha/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇭🇷 [hr](../hr/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇦🇲 [hy](../hy/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇳🇬 [ig](../ig/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇬🇪 [ka](../ka/CONTRIBUTING.md) · 🇰🇭 [km](../km/CONTRIBUTING.md) · 🇮🇳 [kn](../kn/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇱🇹 [lt](../lt/CONTRIBUTING.md) · 🇱🇻 [lv](../lv/CONTRIBUTING.md) · 🇮🇳 [ml](../ml/CONTRIBUTING.md) · 🇮🇳 [mr](../mr/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇲🇹 [mt](../mt/CONTRIBUTING.md) · 🇲🇲 [my](../my/CONTRIBUTING.md) · 🇳🇵 [ne](../ne/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇮🇳 [or](../or/CONTRIBUTING.md) · 🇮🇳 [pa](../pa/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇱🇰 [si](../si/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇸🇮 [sl](../sl/CONTRIBUTING.md) · 🇷🇸 [sr](../sr/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇰🇪 [sw](../sw/CONTRIBUTING.md) · 🇮🇳 [ta](../ta/CONTRIBUTING.md) · 🇮🇳 [te](../te/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇵🇰 [ur](../ur/CONTRIBUTING.md) · 🇺🇿 [uz](../uz/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇳🇬 [yo](../yo/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md) · 🇹🇼 [zh-TW](../zh-TW/CONTRIBUTING.md) --- Thank you for your interest in contributing! This guide covers everything you need to get started. --- ## Entwicklungssetup ### Voraussetzungen - **Node.js** `>=22.22.2 <23` oder `>=24.0.0 <27` (empfohlen: 24 LTS) - **npm** 10+ > **Windows mit Node 24:** Verwenden Sie das aktuelle 24-LTS-Patch-Release (mindestens 24.20.0). > Frühere Releases können nach erfolgreichen Tests abbrechen, wenn `--test-force-exit` den > Prozess schließt. Node's [Windows-libuv-Fix](https://github.com/nodejs/node/pull/61999) behebt > diesen Laufzeitabsturz. Lassen Sie die Testassertions und die Exit-Prüfungen des Runners aktiviert. > **Nutzer von npm v11+ (Node 24+):** Überprüfen Sie nach `npm install`, ob native Module installiert wurden: > `node -e "require('better-sqlite3')"`. Falls der Befehl mit `MODULE_NOT_FOUND` fehlschlägt, > führen Sie `npm approve-scripts better-sqlite3 && npm install` aus. Siehe > [Fehlerbehebung](docs/guides/TROUBLESHOOTING.md#npm-v11-better-sqlite3-not-installed-cannot-find-module). - **Git** ### Klonen und Installieren ```bash git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute npm install ``` ### Umgebungsvariablen ```bash # Ihre .env aus der Vorlage erstellen cp .env.example .env # Erforderliche Geheimnisse generieren echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env ``` Wichtige Variablen für die Entwicklung: | Variable | Entwicklungsstandardwert | Beschreibung | | ---------------------- | ------------------------ | ---------------------------------------- | | `PORT` | `20128` | Serverport | | `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Basis-URL für das Frontend | | `JWT_SECRET` | (oben generieren) | Geheimnis zum Signieren von JWTs | | `INITIAL_PASSWORD` | `CHANGEME` | Passwort für die erste Anmeldung | | `APP_LOG_LEVEL` | `info` | Ausführlichkeitsgrad der Protokollierung | ### Dashboard-Einstellungen Das Dashboard bietet UI-Schalter für Funktionen, die auch über Umgebungsvariablen konfiguriert werden können: | Einstellungsort | Schalter | Beschreibung | | ------------------------- | ----------------------------- | ----------------------------------------- | | Einstellungen → Erweitert | Debug-Modus | Debug-Anfrageprotokolle aktivieren (UI) | | Einstellungen → Allgemein | Sichtbarkeit der Seitenleiste | Seitenleistenbereiche anzeigen/ausblenden | Diese Einstellungen werden in der Datenbank gespeichert und bleiben über Neustarts hinweg erhalten. Wenn sie gesetzt sind, überschreiben sie die Standardwerte der Umgebungsvariablen. ### Lokal ausführen ```bash # Entwicklungsmodus (Hot Reload) npm run dev # Produktions-Build npm run build # next build → .build/next/ und anschließend assembleStandalone → dist/ npm run start # Schnelle Backend-/API-only-Kompilierung für Änderungen von Mitwirkenden npm run build:contributor # Release-Build (sauberer Neuaufbau + HEAD-Marker — für das Deployment erforderlich) npm run build:release # rm -rf .build dist && build + schreibt dist/BUILD_SHA # Allgemeine Portkonfiguration PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev ``` Der Contributor-Build führt ausschließlich eine Kompilierungsvalidierung durch: Er erstellt weder die Standalone-Distribution noch optionale native Paketierungs-Assets. Verwenden Sie den regulären Produktions-Build, wenn Sie das auslieferbare Bundle validieren möchten. ### Struktur der Build-Ausgabe | Verzeichnis | Inhalt | Nachverfolgt | | ----------- | ------------------------------------------------------------------------------- | ------------ | | `src/` | Anwendungscode (TypeScript / TSX) | Ja | | `.build/` | Zwischenstände — Ausgabe von `next build` (gitignored, `distDir = .build/next`) | Nein | | `dist/` | Auslieferbares Bundle — von `assembleStandalone` zusammengestellt (gitignored) | Nein | Die Build-Pipeline besteht aus einem einzigen Durchlauf: ``` npm run build └─ next build → .build/next/standalone (Next.js-Ausgabe) └─ assembleStandalone() (kopiert Standalone-, statische, öffentliche und native Assets) └─ Ausgabe: dist/ (server.js, .next/static/, public/, node_modules/) ``` `npm run build:release` bereinigt zusätzlich zunächst beide Verzeichnisse und schreibt `dist/BUILD_SHA` (= `git rev-parse --short HEAD`) als Integritätsmarker für das Deployment. `npm run build:contributor` verwendet das Backend-only-Build-Profil. Während des Builds werden Dashboard-UI-Dateien vorübergehend durch Platzhalter ersetzt, API-Route-Handler bleiben erhalten, und die ursprünglichen Dateien werden nach dem Build wiederhergestellt. Verwenden Sie `npm run build` für Änderungen, die sich auf die Dashboard-UI auswirken, oder für eine vollständige Release-Validierung. Das Contributor-Profil ist kein Ersatz für den Release-Build. > **Hinweis zum VPS-Deployment:** Das entfernte Image-Verzeichnis `/usr/lib/node_modules/omniroute/app/` > bleibt unverändert. Die Deployment-Skills synchronisieren den Inhalt von `dist/` per rsync dorthin. > Nur der Build-Ausgabepfad innerhalb des Repositorys wurde verschoben (`app/` → `dist/`). Standard-URLs: - **Dashboard**: `http://localhost:20128/dashboard` - **API**: `http://localhost:20128/v1` --- ## Git-Workflow > ⚠️ **NIEMALS direkt in `main` committen.** Verwende immer Feature-Branches. > > **PR-Basis:** Verwende den aktiven `release/vX.Y.Z`-Branch als Ziel (nicht `main`). Siehe > [`docs/ops/BRANCHING_MODEL.md`](docs/ops/BRANCHING_MODEL.md) für das Modell > „ein Branch pro Release“ mit Tagging bei der Veröffentlichung. ```bash # Vom aktuellen Stand des aktiven Release-Branches abzweigen (Beispiel: release/v3.8.49) git fetch origin git checkout -b feat/your-feature-name origin/release/v3.8.49 # ... Änderungen vornehmen ... git commit -m "feat: describe your change" git push -u origin feat/your-feature-name # Einen Pull Request mit base = release/v3.8.49 öffnen ``` ### Branch-Benennung | Präfix | Zweck | | ----------- | --------------------------------- | | `feat/` | Neue Funktionen | | `fix/` | Fehlerbehebungen | | `refactor/` | Umstrukturierung des Codes | | `docs/` | Änderungen an der Dokumentation | | `test/` | Ergänzungen/Korrekturen von Tests | | `chore/` | Tooling, CI, Abhängigkeiten | ### Commit-Nachrichten Befolge [Conventional Commits](https://www.conventionalcommits.org/): ``` feat: add circuit breaker for provider calls fix: resolve JWT secret validation edge case docs: update SECURITY.md with PII protection test: add observability unit tests refactor(db): consolidate rate limit tables ``` Scopes (v3.8): `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`, `cloud-agent`, `guardrails`, `compression`, `auto-combo`, `resilience`, `providers`, `executors`, `translator`, `domain`, `authz`. --- ## Tests ausführen ```bash # Alle Tests (Unit + Vitest + Ökosystem + E2E) npm run test:all # Einzelne Testdatei (nativer Node.js-Test-Runner — die meisten Tests verwenden diesen) node --import tsx/esm --test tests/unit/your-file.test.ts # Nur die von Ihrer Änderung betroffenen Unit-Tests (derselbe TIA-Selektor wie im CI-Gate, #8084) npm run test:scoped # Änderungen im letzten Commit (oder im Arbeitsverzeichnis) npm run test:scoped:staged # nur vorgemerkte Änderungen — gut für einen Pre-Commit-Lauf geeignet npm run test:scoped:full # zuerst die Import-Graph-Zuordnung neu erstellen (nach dem Hinzufügen/Verschieben von Dateien) # Exit 1 + „vollständige Suite ausführen“ bedeutet, dass eine zentrale Datei (tsconfig, package.json, …) oder eine # nicht zugeordnete Quelldatei geändert wurde — der Selektor bricht sicher ab und überspringt niemals unbemerkt Tests. # Vitest (MCP-Server, autoCombo, Cache) npm run test:vitest # E2E-Tests (erfordert Playwright) npm run test:e2e # E2E für Protokoll-Clients (MCP-Transporte, A2A) npm run test:protocols:e2e # Kompatibilitätstests für das Ökosystem npm run test:ecosystem # Coverage-Gate: 60 % Anweisungen/Zeilen/Funktionen/Verzweigungen npm run test:coverage npm run coverage:report # Lint- und Formatierungsprüfung npm run lint npm run check # Abgesicherter Combo-Smoke-Test mit echten Upstream-Diensten (erfordert VPS-Zugriff und echtes Provider-Guthaben) # Greift auf ECHTE Provider zu — verursacht geringe Kosten. Wird NIEMALS in CI ausgeführt. Wird ohne aktiviertes Gate sauber übersprungen. # Erfordert: Zugriff per ssh root@192.168.0.15 (bezieht einen schreibgeschützten DB-Snapshot vom VPS). RUN_COMBO_LIVE=1 npm run test:combo:live # Phase-3-Live-Smoke-Test auf dem VPS — einfache Node-ESM-Skripte, die direkt auf den Live-Server .15 zugreifen. # Erfordert: Zugriff per ssh root@192.168.0.15 (Combos werden über SSH und sqlite erstellt/entfernt). # Greift auf ECHTE Provider zu (geringe Kosten). Erstellt/löscht nur __live_test__*-Combos. Wird NIEMALS in CI ausgeführt. # REQUIRE_API_KEY=false auf .15, daher ist kein API-Schlüssel erforderlich; COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY werden jedoch berücksichtigt, wenn sie gesetzt sind. npm run test:combo:live:vps # 7 HTTP-Szenarien (Priorität/Round-Robin/gewichtet/Kosten/Fusion/automatisch + Zustand) npm run test:combo:live:vps:failover # fügt ein echtes providerübergreifendes Failover-Szenario hinzu (insgesamt 8) ``` Hinweise zur Coverage: - `npm run test:coverage` misst die Quellcode-Coverage für die primäre Unit-Test-Suite, schließt `tests/**` aus und bezieht `open-sse/**` ein - Pull Requests müssen das Coverage-Gate bei **60 % oder mehr** für Anweisungen/Zeilen/Funktionen/Verzweigungen halten - Wenn ein PR Produktionscode in `src/`, `open-sse/`, `electron/` oder `bin/` ändert, müssen im selben PR automatisierte Tests hinzugefügt oder aktualisiert werden - `npm run coverage:report` gibt den detaillierten Bericht für jede einzelne Datei aus dem letzten Coverage-Lauf aus - `npm run test:coverage:legacy` behält die ältere Metrik für historische Vergleiche bei - Siehe `docs/ops/COVERAGE_PLAN.md` für den schrittweisen Plan zur Verbesserung der Coverage ### Anforderungen an Pull Requests Verwenden Sie vor dem Öffnen eines PR den [bewährten Beitragsablauf](docs/ops/CONTRIBUTION_GOLDEN_PATH.md), um die fokussierte Schleife für Ihre Änderungen auszuführen. Die vollständige Unit-Test-Suite (4 CI-Shards), Vitest, das Coverage-Gate von **60 % oder mehr** und der Produktions-Build liegen in der Verantwortung von CI — ihre lokale Ausführung liefert keine zusätzlichen Erkenntnisse, die nicht bereits durch die PR-Prüfungen bereitgestellt werden, und kann auf kleineren Rechnern den Host überlasten (#8084): - Führen Sie die Testdateien aus, die Ihre Änderung abdecken: `node --import tsx/esm --test tests/unit/.test.ts` - Führen Sie `npm run lint` aus - Fügen Sie im selben PR automatisierte Tests hinzu oder aktualisieren Sie diese, wenn Produktionscode geändert wird - Platzieren Sie in `node:test`-Dateien jedes `await` auf oberster Ebene (wie `await import(...)`) vor dem ersten `test()` / `describe()`: Unter `--test-force-exit` können danach registrierte Tests unbemerkt überhaupt nicht ausgeführt werden (#18045; erzwungen durch `npm run check:test-tla-order`) - Führen Sie die geänderten oder hinzugefügten Testdateien in der PR-Beschreibung auf, wenn Produktionscode geändert wurde - Prüfen Sie das SonarQube-Ergebnis für den PR, wenn die Projekt-Secrets in CI konfiguriert sind Aktueller Teststatus: **122 Unit-Testdateien** für: - Provider-Übersetzer und Formatkonvertierung - Ratenbegrenzung, Circuit Breaker und Resilienz - Semantischen Cache, Idempotenz und Fortschrittsverfolgung - Datenbankoperationen und -schema (21 DB-Module) - OAuth-Abläufe und Authentifizierung - Validierung von API-Endpunkten (Zod v4) - MCP-Server-Tools und Durchsetzung von Geltungsbereichen - Speicher- und Skills-Systeme --- ## Codestil - **ESLint** — Vor dem Commit `npm run lint` ausführen - **Prettier** — Beim Commit automatisch über `lint-staged` formatiert (2 Leerzeichen, Semikolons, doppelte Anführungszeichen, 100 Zeichen Zeilenbreite, nachgestellte Kommas gemäß es5) - **TypeScript** — Der gesamte Code unter `src/` verwendet `.ts`/`.tsx`; `open-sse/` verwendet `.ts`/`.js`; mit TSDoc dokumentieren (`@param`, `@returns`, `@throws`) - **Kein `eval()`** — ESLint erzwingt `no-eval`, `no-implied-eval`, `no-new-func` - **Zod-Validierung** — Zod-v4-Schemas für die Validierung aller API-Eingaben verwenden - **Benennung**: Dateien = camelCase/kebab-case, Komponenten = PascalCase, Konstanten = UPPER_SNAKE ### Fehlerbehandlung / leere catch-Blöcke Ein `catch` darf niemals unerklärt bleiben. Ordne es einer von zwei Kategorien zu (dies setzt die strikte Regel „Fehler in SSE-Streams niemals stillschweigend verschlucken“ praktisch um): - **Beabsichtigt (eigene Best-Effort-Bereinigung/Telemetrie)** — ein Fehler ist hier zu erwarten und harmlos; füge einen einzeiligen Kommentar zur Begründung hinzu, ohne Logging (diese Konvention vermeidet störende Log-Ausgaben bei jeder Anfrage). ```ts } catch {} // das Schließen eines bereits geschlossenen Controllers nach einem Client-Verbindungsabbruch ist zu erwarten ``` - **Sollte protokolliert werden (externer/vom Aufrufer bereitgestellter Code oder das Verschlucken ändert den Kontrollfluss)** — behalte den catch-Block bei (der Stream darf dadurch niemals unterbrochen werden), gib aber eine kontextbezogene `console.debug`-/`warn`-Meldung aus, damit der Fehler auffindbar ist. ```ts } catch (e) { console.debug("[STREAM] Fehler im onFailure-Callback:", e); } ``` Anwendungsbeispiele findest du unter `open-sse/utils/stream.ts` und `open-sse/utils/streamHandler.ts`. --- ## Projektstruktur ``` src/ # TypeScript (.ts / .tsx) ├── app/ # Next.js 16 App Router │ ├── (dashboard)/ # Dashboard-Seiten (23 Abschnitte) │ ├── api/ # API-Routen (51 Verzeichnisse) │ └── login/ # Authentifizierungsseiten (.tsx) ├── domain/ # Richtlinien-Engine (policyEngine, comboResolver, costRules usw.) ├── lib/ # Zentrale Geschäftslogik (.ts) │ ├── a2a/ # Server für das Agent-to-Agent-v0.3-Protokoll │ ├── acp/ # Registry für das Agent Communication Protocol │ ├── compliance/ # Engine für Compliance-Richtlinien │ ├── db/ # SQLite-Domänenmodule + 130 Migrationen │ ├── memory/ # Persistenter Konversationsspeicher │ ├── oauth/ # OAuth-Anbieter, -Dienste und -Hilfsprogramme │ ├── skills/ # Erweiterbares Skill-Framework │ ├── usage/ # Nutzungsverfolgung und Kostenberechnung │ └── localDb.ts # Nur Reexport-Schicht — hier niemals Logik hinzufügen ├── middleware/ # Anfrage-Middleware (promptInjectionGuard) ├── mitm/ # MITM-Proxy (Zertifikate, DNS, Ziel-Routing) ├── shared/ │ ├── components/ # React-Komponenten (.tsx) │ ├── constants/ # Anbieterdefinitionen (329), MCP-Berechtigungsbereiche, 20 Routing-Strategien │ ├── utils/ # Circuit Breaker, Bereinigung, Authentifizierungshilfen │ └── validation/ # Zod-v4-Schemas └── sse/ # SSE-Proxy-Pipeline open-sse/ # @omniroute/open-sse-Workspace ├── executors/ # 150 Executor-Module (Executor-Klassen + anbieterspezifische Hilfsfunktionen) ├── handlers/ # 11 Anfrage-Handler (Chat, Antworten, Einbettungen, Bilder usw.) ├── mcp-server/ # MCP-Server (110 eindeutige Tools, 3 Transporte, 33 Berechtigungsbereiche) ├── services/ # 178 Dienste der obersten Ebene (combo, autoCombo, rateLimitManager usw.) ├── translator/ # Formatübersetzer (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama) ├── transformer/ # Responses-API-Transformer └── utils/ # 22 Hilfsprogrammmodule (Streams, TLS, Proxy, Protokollierung) electron/ # Plattformübergreifende Electron-Desktop-App tests/ ├── unit/ # Node.js-Test-Runner (1.574 Testdateien) ├── integration/ # Integrationstests ├── e2e/ # Playwright-Tests ├── security/ # Sicherheitstests ├── translator/ # Übersetzerspezifische Tests └── load/ # Lasttests docs/ ├── adr/ # Aufzeichnungen zu Architekturentscheidungen ├── architecture/ # Systemarchitektur und Resilienz ├── comparison/ # OmniRoute im Vergleich zu Alternativen ├── compression/ # Komprimierungsleitfäden und -regeln ├── dev/ # Entwicklungsleitfäden ├── diagrams/ # Architekturdiagramme ├── frameworks/ # MCP, A2A, OpenCode, Memory, Skills ├── guides/ # Benutzerhandbuch, Docker, Einrichtung, Fehlerbehebung ├── i18n/ # Internationalisierte README-Übersetzungen ├── marketing/ # Marketingmaterialien ├── ops/ # Bereitstellung, Proxy, Abdeckung, Releases ├── providers/ # Anbieterspezifische Dokumentation ├── reference/ # API-Referenz, Umgebungsvariablen, CLI-Tools, kostenlose Kontingente ├── releases/ # Versionshinweise ├── routing/ # Auto-Combo-Engine, Wiedergabe von Schlussfolgerungen ├── screenshots/ # Dashboard-Screenshots ├── security/ # Schutzmechanismen, Compliance, Tarnung, Tokens └── specs/ # Designspezifikationen ``` --- ## Hinzufügen eines neuen Providers ### Schritt 1: Provider-Konstanten registrieren Zu `src/shared/constants/providers.ts` hinzufügen — wird beim Laden des Moduls mit Zod validiert. ### Schritt 2: Executor hinzufügen (falls benutzerdefinierte Logik erforderlich ist) Einen Executor in `open-sse/executors/your-provider.ts` erstellen, der den Basis-Executor erweitert. ### Schritt 3: Translator hinzufügen (falls kein OpenAI-Format verwendet wird) Request-/Response-Translator in `open-sse/translator/` erstellen. ### Schritt 4: OAuth-Konfiguration hinzufügen (falls OAuth-basiert) OAuth-Anmeldedaten in `src/lib/oauth/constants/oauth.ts` und den Service in `src/lib/oauth/services/` hinzufügen. Wenn der Upstream-Provider eine öffentliche OAuth-client_id/ein öffentliches OAuth-Secret oder einen Firebase-Web-API-Schlüssel innerhalb seiner öffentlichen CLI bzw. seines Browser-Bundles bereitstellt, darf dieser **nicht** als Stringliteral eingebettet werden. `resolvePublicCred()` aus `open-sse/utils/publicCreds.ts` verwenden und einen maskierten Byte-Eintrag zu `EMBEDDED_DEFAULTS` hinzufügen. Der vollständige verpflichtende Workflow ist in [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md) dokumentiert. In Handlern/Executors müssen Fehlermeldungen, die den Client erreichen, über `buildErrorBody()` / `sanitizeErrorMessage()` aus `open-sse/utils/error.ts` verarbeitet werden — niemals unverarbeitete Werte aus `err.stack` oder `err.message` in einen Response-Body einfügen. Siehe [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md). ### Schritt 5: Modelle registrieren Modelldefinitionen in `open-sse/config/providerRegistry.ts` hinzufügen. ### Schritt 6: Tests hinzufügen Unit-Tests in `tests/unit/` schreiben, die mindestens Folgendes abdecken: - Provider-Registrierung - Request-/Response-Übersetzung - Fehlerbehandlung --- ## Pull-Request-Checkliste - [ ] Tests sind erfolgreich (`npm test`) - [ ] Linting ist erfolgreich (`npm run lint`) - [ ] Build ist erfolgreich (`npm run build`) - [ ] TypeScript-Typen für neue öffentliche Funktionen und Schnittstellen hinzugefügt - [ ] Keine hartcodierten Geheimnisse oder Fallback-Werte - [ ] Öffentliche Zugangsdaten von Upstream-Diensten über `resolvePublicCred()` eingebettet (siehe [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)), niemals als Literale - [ ] Fehlerantworten werden über `buildErrorBody()` / `sanitizeErrorMessage()` geleitet — keine unbearbeiteten Stacktraces in Antwortinhalten (siehe [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md)) - [ ] Shell-Befehle (`exec` / `spawn`) übergeben Laufzeitwerte über `env`, nicht über String-Interpolation - [ ] Alle Eingaben mit Zod-Schemas validiert - [ ] Changelog-**Fragment** für benutzersichtbare Änderungen unter `changelog.d/{features|fixes|maintenance}/-.md` hinzugefügt (siehe [`changelog.d/README.md`](./changelog.d/README.md)) — `CHANGELOG.md` **nicht** direkt bearbeiten; Fragmente werden zum Veröffentlichungszeitpunkt zusammengeführt und verursachen niemals Konflikte zwischen PRs - [ ] Dokumentation aktualisiert (falls zutreffend) - [ ] Keine neuen CodeQL-/Secret-Scanning-Warnungen ausgelöst oder jede Warnung mit einer technischen Begründung unter Verweis auf das relevante Dokument unter `docs/security/` verworfen - [ ] Routen, die untergeordnete Prozesse starten (`/api/mcp/`, `/api/cli-tools/runtime/`), in `src/server/authz/routeGuard.ts` als `isLocalOnlyPath()` klassifiziert — siehe [Strikte Regel Nr. 15](docs/security/ROUTE_GUARD_TIERS.md) - [ ] Keine `Co-authored-by`-Trailer für KI/Bots in Commit-Nachrichten (strikte Regel Nr. 16) — menschliche Mitwirkende, deren Arbeit wiederverwendet wird, werden mit standardmäßigen `Co-authored-by: Name `-Trailern gewürdigt --- ## Veröffentlichung Veröffentlichungen werden über den Workflow `/generate-release` verwaltet. Wenn ein neues GitHub Release erstellt wird, wird das Paket über GitHub Actions **automatisch auf npm veröffentlicht**. Verwenden Sie für VPS-Deployments `npm run build:release` (nicht `npm run build`) — dieser Befehl führt einen sauberen Neuaufbau durch, stellt das Bundle in `dist/` zusammen und schreibt die Sentinel-Datei `dist/BUILD_SHA`. Verwenden Sie anschließend die Skills `/deploy-vps-*-cc`, die `dist/` per rsync mit dem Remote-Verzeichnis `app/` synchronisieren. --- ## Hilfe erhalten - **Architektur**: Siehe [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) - **API-Referenz**: Siehe [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) - **Sicherheitsdokumentation**: [`docs/security/CLI_TOKEN.md`](docs/security/CLI_TOKEN.md), [`docs/security/ROUTE_GUARD_TIERS.md`](docs/security/ROUTE_GUARD_TIERS.md), [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md), [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md) - **Betriebsdokumentation**: [`docs/ops/SQLITE_RUNTIME.md`](docs/ops/SQLITE_RUNTIME.md) - **Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)