wehub-resource-sync
412 lines
27 KiB
Markdown
412 lines
27 KiB
Markdown
# CLAUDE.md (Čeština)
|
|
|
|
🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/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)
|
|
|
|
---
|
|
|
|
Tento soubor poskytuje pokyny pro Claude Code (claude.ai/code) při práci s kódem v tomto repozitáři.
|
|
|
|
## Rychlý start
|
|
|
|
```bash
|
|
npm install # Nainstalujte závislosti (automaticky vygeneruje .env z .env.example)
|
|
npm run dev # Vývojový server na http://localhost:20128
|
|
npm run build # Produkční build (Next.js 16 standalone)
|
|
npm run lint # ESLint (0 chyb očekáváno; varování jsou předchozí)
|
|
npm run typecheck:core # Kontrola TypeScriptu (mělo by být čisté)
|
|
npm run typecheck:noimplicit:core # Přísná kontrola (žádné implicitní any)
|
|
npm run test:coverage # Jednotkové testy + pokrytí (75/75/75/70 — prohlášení/řádky/funkce/větve)
|
|
npm run check # lint + testy dohromady
|
|
npm run check:cycles # Detekce cyklických závislostí
|
|
```
|
|
|
|
### Spouštění testů
|
|
|
|
```bash
|
|
# Jediný testovací soubor (nativní testovací běžec Node.js — většina testů)
|
|
node --import tsx/esm --test tests/unit/your-file.test.ts
|
|
|
|
# Vitest (MCP server, autoCombo, cache)
|
|
npm run test:vitest
|
|
|
|
# Všechny sady
|
|
npm run test:all
|
|
```
|
|
|
|
Pro plnou testovací matici viz `CONTRIBUTING.md` → "Spouštění testů". Pro hlubokou architekturu viz `AGENTS.md`.
|
|
|
|
---
|
|
|
|
## Projekt na první pohled
|
|
|
|
**OmniRoute** — jednotný AI proxy/router. Jeden koncový bod, 160+ poskytovatelů LLM, automatické zálohování.
|
|
|
|
| Vrstva | Umístění | Účel |
|
|
| ------------- | ----------------------- | ------------------------------------------------------------------------------- |
|
|
| API Routes | `src/app/api/v1/` | Next.js App Router — vstupní body |
|
|
| Handlers | `open-sse/handlers/` | Zpracování požadavků (chat, embeddings, atd.) |
|
|
| Executors | `open-sse/executors/` | HTTP dispatch specifický pro poskytovatele |
|
|
| Translators | `open-sse/translator/` | Konverze formátu (OpenAI↔Claude↔Gemini) |
|
|
| Transformer | `open-sse/transformer/` | API odpovědí ↔ Dokončení chatu |
|
|
| Services | `open-sse/services/` | Kombinované směrování, limity rychlosti, caching, atd. |
|
|
| Database | `src/lib/db/` | SQLite doménové moduly (45+ souborů, 55 migrací) |
|
|
| Domain/Policy | `src/domain/` | Engin politiky, pravidla nákladů, logika zálohování |
|
|
| MCP Server | `open-sse/mcp-server/` | 37 nástrojů (30 základních + 3 paměť + 4 dovednosti), 3 transporty, ~13 rozsahů |
|
|
| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protokol |
|
|
| Skills | `src/lib/skills/` | Rozšiřitelný rámec dovedností |
|
|
| Memory | `src/lib/memory/` | Trvalá konverzační paměť |
|
|
|
|
Monorepo: `src/` (Next.js 16 aplikace), `open-sse/` (pracovní prostor streamovacího enginu), `electron/` (desktopová aplikace), `tests/`, `bin/` (CLI vstupní bod).
|
|
|
|
---
|
|
|
|
## Pipeline požadavků
|
|
|
|
```
|
|
Klient → /v1/chat/completions (Next.js route)
|
|
→ CORS → Zod validace → auth? → kontrola politiky → ochrana proti injekci promptu
|
|
→ handleChatCore() [open-sse/handlers/chatCore.ts]
|
|
→ kontrola cache → limit rychlosti → combo routing?
|
|
→ resolveComboTargets() → handleSingleModel() pro každý cíl
|
|
→ translateRequest() → getExecutor() → executor.execute()
|
|
→ fetch() upstream → opakování s backoff
|
|
→ překlad odpovědi → SSE stream nebo JSON
|
|
→ Pokud Responses API: responsesTransformer.ts TransformStream
|
|
```
|
|
|
|
API trasy následují konzistentní vzor: `Route → CORS preflight → Zod validace těla → Volitelná autentizace (extractApiKey/isValidApiKey) → Vynucení politiky API klíče → Delegace handleru (open-sse)`. Žádný globální Next.js middleware — interceptace je specifická pro trasu.
|
|
|
|
**Combo routing** (`open-sse/services/combo.ts`): 14 strategií (priorita, vážené, fill-first, round-robin, P2C, náhodné, nejméně používané, optimalizované podle nákladů, reset-aware, strict-random, auto, lkgp, optimalizované podle kontextu, kontext-relay). Každý cíl volá `handleSingleModel()`, který obaluje `handleChatCore()` s chybovým zpracováním a kontrolami obvodu pro každý cíl. Viz `docs/routing/AUTO-COMBO.md` pro 9-faktorové hodnocení Auto-Combo a `docs/architecture/RESILIENCE_GUIDE.md` pro 3 vrstvy odolnosti.
|
|
|
|
---
|
|
|
|
## Stav běhu odolnosti
|
|
|
|
OmniRoute má tři související, ale odlišné mechanismy dočasného selhání. Udržujte jejich rozsah oddělený při ladění chování routování. Viz
|
|
[diagram odolnosti ve 3 vrstvách](./docs/diagrams/exported/resilience-3layers.svg)
|
|
(zdroj: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
|
|
pro rychlý přehled.
|
|
|
|
### Obvod poskytovatele
|
|
|
|
**Rozsah**: celý poskytovatel, např. `glm`, `openai`, `anthropic`.
|
|
|
|
**Účel**: zastavit posílání provozu k poskytovateli, který opakovaně selhává na úrovni upstream/služby, aby jeden nezdravý poskytovatel nezpomalil každý požadavek.
|
|
|
|
**Implementace**:
|
|
|
|
- Hlavní třída: `src/shared/utils/circuitBreaker.ts`
|
|
- Chat gate/execution wiring: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
|
|
- API stavu běhu: `src/app/api/monitoring/health/route.ts`
|
|
- Sdílené obaly: `open-sse/services/accountFallback.ts`
|
|
- Tabulka trvalého stavu: `domain_circuit_breakers`
|
|
|
|
**Stavy**:
|
|
|
|
- `CLOSED`: normální provoz je povolen.
|
|
- `OPEN`: poskytovatel je dočasně zablokován; volající dostanou odpověď provider-circuit-open
|
|
nebo combo routing přeskočí na jiný cíl.
|
|
- `HALF_OPEN`: resetovací timeout uplynul; povolit zkušební požadavek. Úspěch uzavírá
|
|
obvod, selhání jej znovu otevírá.
|
|
|
|
**Výchozí hodnoty** (`open-sse/config/constants.ts`):
|
|
|
|
- OAuth poskytovatelé: práh `3`, resetovací timeout `60s`.
|
|
- API-klíč poskytovatelé: práh `5`, resetovací timeout `30s`.
|
|
- Lokální poskytovatelé: práh `2`, resetovací timeout `15s`.
|
|
|
|
Pouze stavy selhání na úrovni poskytovatele by měly spustit obvod poskytovatele:
|
|
|
|
```ts
|
|
(408, 500, 502, 503, 504);
|
|
```
|
|
|
|
Nespouštějte obvod celého poskytovatele pro normální chyby účtu/klíče/modelu jako většina
|
|
případů `401`, `403` nebo `429`. Ty obvykle patří do cooldownu připojení nebo uzamčení modelu. Obecný API-klíč poskytovatel `403` by měl být obnovitelný, pokud není klasifikován
|
|
jako terminální chyba poskytovatele/účtu.
|
|
|
|
Obvod používá lenivou obnovu, ne pozadí časovač. Když `OPEN` vyprší, čtení jako
|
|
`getStatus()`, `canExecute()`, a `getRetryAfterMs()` obnoví stav na
|
|
`HALF_OPEN`, takže panely a stavitelé kandidátů na combo nebudou navždy vylučovat vypršeného poskytovatele.
|
|
|
|
### Cooldown připojení
|
|
|
|
**Rozsah**: jedno připojení/účet/klíč poskytovatele.
|
|
|
|
**Účel**: dočasně přeskočit jeden špatný klíč/účet, zatímco ostatní připojení pro
|
|
stejného poskytovatele mohou pokračovat v obsluze požadavků.
|
|
|
|
**Implementace**:
|
|
|
|
- Cesta zápisu/aktualizace: `src/sse/services/auth.ts::markAccountUnavailable()`
|
|
- Výběr/filtrování účtu: `src/sse/services/auth.ts::getProviderCredentials...`
|
|
- Výpočet cooldownu: `open-sse/services/accountFallback.ts::checkFallbackError()`
|
|
- Nastavení: `src/lib/resilience/settings.ts`
|
|
|
|
Důležitá pole na připojeních poskytovatele:
|
|
|
|
```ts
|
|
rateLimitedUntil;
|
|
testStatus: "unavailable";
|
|
lastError;
|
|
lastErrorType;
|
|
errorCode;
|
|
backoffLevel;
|
|
```
|
|
|
|
Během výběru účtu je připojení přeskočeno, pokud:
|
|
|
|
```ts
|
|
new Date(rateLimitedUntil).getTime() > Date.now();
|
|
```
|
|
|
|
Cooldowny jsou také lenivé: když je `rateLimitedUntil` v minulosti, připojení se opět stává
|
|
způsobilým. Při úspěšném použití `clearAccountError()` vymaže `testStatus`,
|
|
`rateLimitedUntil`, chybová pole a `backoffLevel`.
|
|
|
|
Výchozí chování cooldownu připojení:
|
|
|
|
- Základní cooldown OAuth: `5s`.
|
|
- Základní cooldown API-klíče: `3s`.
|
|
- API-klíč `429` by měl preferovat upstream retry hints (`Retry-After`, resetovací hlavičky, nebo
|
|
parsovatelný reset text) když jsou k dispozici.
|
|
- Opakované obnovitelné selhání používá exponenciální backoff:
|
|
|
|
```ts
|
|
baseCooldownMs * 2 ** failureIndex;
|
|
```
|
|
|
|
Ochrana proti thundering-herd zabraňuje souběžným selháním na stejném připojení v
|
|
opakovaném prodlužování cooldownu nebo dvojitému zvyšování `backoffLevel`.
|
|
|
|
Terminální stavy nejsou cooldowny. `banned`, `expired`, a `credits_exhausted` jsou
|
|
určeny k tomu, aby zůstaly nedostupné, dokud se nezmění pověření/nastavení nebo je operátor
|
|
neobnoví. Nepřepisujte terminální stavy do přechodného stavu cooldownu.
|
|
|
|
### Uzamčení modelu
|
|
|
|
**Rozsah**: poskytovatel + připojení + model.
|
|
|
|
**Účel**: vyhnout se deaktivaci celého připojení, když je k dispozici pouze jeden model
|
|
nebo je omezený kvótou pro toto připojení.
|
|
|
|
Příklady:
|
|
|
|
- Poskytovatelé s kvótou na model vracející `429`.
|
|
- Lokální poskytovatelé vracející `404` pro jeden chybějící model.
|
|
- Chyby oprávnění specifické pro poskytovatele/model, jako jsou vybrané režimy Grok.
|
|
|
|
Uzamčení modelu žije v `open-sse/services/accountFallback.ts` a umožňuje stejnému
|
|
připojení pokračovat v obsluze dalších modelů.
|
|
|
|
### Pokyny pro ladění
|
|
|
|
- Pokud jsou všechny klíče pro poskytovatele přeskočeny, zkontrolujte jak stav obvodu poskytovatele, tak
|
|
`rateLimitedUntil`/`testStatus` každého připojení.
|
|
- Pokud se zdá, že je poskytovatel trvale vyloučen po resetovacím okně, zkontrolujte, zda kód
|
|
čte surový `state` místo používání `getStatus()`/`canExecute()`.
|
|
- Pokud jeden klíč poskytovatele selže, ale ostatní by měly fungovat, preferujte cooldown připojení před
|
|
obvodem poskytovatele.
|
|
- Pokud selže pouze jeden model, preferujte uzamčení modelu před cooldownem připojení.
|
|
- Pokud by se měl stav sám obnovit, měl by mít budoucí časové razítko/resetovací timeout a
|
|
čtecí cestu, která obnovuje vypršený stav. Trvalé stavy vyžadují ruční změny pověření
|
|
nebo konfigurace.
|
|
|
|
## Klíčové konvence
|
|
|
|
### Styl kódu
|
|
|
|
- **2 mezery**, středníky, dvojité uvozovky, šířka 100 znaků, es5 koncové čárky (vynuceno lint-staged pomocí Prettier)
|
|
- **Importy**: externí → interní (`@/`, `@omniroute/open-sse`) → relativní
|
|
- **Pojmenování**: soubory=camelCase/kebab, komponenty=PascalCase, konstanty=UPPER_SNAKE
|
|
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = chyba všude; `no-explicit-any` = varování v `open-sse/` a `tests/`
|
|
- **TypeScript**: `strict: false`, cíl ES2022, modul esnext, rozlišení bundler. Preferujte explicitní typy.
|
|
|
|
### Databáze
|
|
|
|
- **Vždy** procházejte doménovými moduly `src/lib/db/` — **nikdy** nepíšete surové SQL v trasách nebo obslužných funkcích
|
|
- **Nikdy** nepřidávejte logiku do `src/lib/localDb.ts` (pouze vrstva pro opětovný export)
|
|
- **Nikdy** neprovádějte barrel-import z `localDb.ts` — místo toho importujte konkrétní moduly `db/`
|
|
- DB singleton: `getDbInstance()` z `src/lib/db/core.ts` (WAL žurnálování)
|
|
- Migrace: `src/lib/db/migrations/` — verzované SQL soubory, idempotentní, prováděné v transakcích
|
|
|
|
### Zpracování chyb
|
|
|
|
- try/catch se specifickými typy chyb, logování s kontextem pino
|
|
- Nikdy nezapomínejte na chyby ve SSE streamech — použijte signály pro zrušení pro úklid
|
|
- Vraťte správné HTTP status kódy (4xx/5xx)
|
|
|
|
### Bezpečnost
|
|
|
|
- **Nikdy** nepoužívejte `eval()`, `new Function()`, nebo implicitní eval
|
|
- Ověřte všechny vstupy pomocí Zod schémat
|
|
- Šifrujte přihlašovací údaje v klidu (AES-256-GCM)
|
|
- Seznam zakázaných hlaviček upstream: `src/shared/constants/upstreamHeaders.ts` — udržujte sanitaci, Zod schémata a jednotkové testy v souladu při úpravách
|
|
- **Veřejné přihlašovací údaje upstream** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web klíče extrahované z veřejných CLI): **MUSÍ** být vloženy pomocí `resolvePublicCred()` z `open-sse/utils/publicCreds.ts` — **nikdy** jako literály. Viz `docs/security/PUBLIC_CREDS.md` pro povinný vzor.
|
|
- **Odpovědi na chyby** (HTTP / SSE / executor / MCP obslužná funkce): **MUSÍ** procházet `buildErrorBody()` nebo `sanitizeErrorMessage()` z `open-sse/utils/error.ts` — **nikdy** nevkládejte surové `err.stack` nebo `err.message` do těla odpovědi. Viz `docs/security/ERROR_SANITIZATION.md`.
|
|
- **Shell příkazy vytvořené z proměnných**: při volání `exec()`/`spawn()` se skriptem, který potřebuje hodnoty za běhu, předávejte je pomocí možnosti `env` (automaticky shell-escaped) — **nikdy** neprovádějte interpolaci neověřených/externalních cest do těla skriptu. Odkaz: `src/mitm/cert/install.ts::updateNssDatabases`.
|
|
- **Knihovny zabezpečené podle výchozího nastavení** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): preferujte Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink před vlastními implementacemi při přidávání nových bezpečnostně citlivých povrchů.
|
|
|
|
---
|
|
|
|
## Běžné scénáře úprav
|
|
|
|
### Přidání nového poskytovatele
|
|
|
|
1. Zaregistrujte v `src/shared/constants/providers.ts` (ověřeno Zod při načítání)
|
|
2. Přidejte executor v `open-sse/executors/`, pokud je potřeba vlastní logika (rozšiřte `BaseExecutor`)
|
|
3. Přidejte překladač v `open-sse/translator/`, pokud není ve formátu OpenAI
|
|
4. Přidejte OAuth konfiguraci v `src/lib/oauth/constants/oauth.ts`, pokud je založena na OAuth — pokud upstream CLI dodává veřejný client_id/secret, vložte pomocí `resolvePublicCred()` (viz `docs/security/PUBLIC_CREDS.md`), **nikdy** jako literál
|
|
5. Zaregistrujte modely v `open-sse/config/providerRegistry.ts`
|
|
6. Napište testy v `tests/unit/` (zahrňte ověření tvaru publicCreds, pokud jste přidali nový vložený výchozí)
|
|
|
|
### Přidání nové API trasy
|
|
|
|
1. Vytvořte adresář pod `src/app/api/v1/your-route/`
|
|
2. Vytvořte `route.ts` s obslužnými funkcemi `GET`/`POST`
|
|
3. Dodržujte vzor: CORS → Zod ověření těla → volitelná autentizace → delegace obslužné funkce
|
|
4. Obslužná funkce jde do `open-sse/handlers/` (importujte odtud, ne inline)
|
|
5. Odpovědi na chyby používají `buildErrorBody()` / `errorResponse()` z `open-sse/utils/error.ts` (automaticky sanitizováno — nikdy nevkládejte `err.stack` nebo `err.message` surově do těla). Viz `docs/security/ERROR_SANITIZATION.md`.
|
|
6. Přidejte testy — včetně alespoň jednoho ověření, že odpovědi na chyby neunikají stopy (`!body.error.message.includes("at /")`)
|
|
|
|
### Přidání nového DB modulu
|
|
|
|
1. Vytvořte `src/lib/db/yourModule.ts` — importujte `getDbInstance` z `./core.ts`
|
|
2. Exportujte CRUD funkce pro vaše doménové tabulky
|
|
3. Přidejte migraci v `src/lib/db/migrations/`, pokud jsou potřeba nové tabulky
|
|
4. Znovu exportujte z `src/lib/localDb.ts` (přidejte pouze do seznamu pro opětovný export)
|
|
5. Napište testy
|
|
|
|
### Přidání nového MCP nástroje
|
|
|
|
1. Přidejte definici nástroje v `open-sse/mcp-server/tools/` s Zod vstupním schématem + asynchronní obslužnou funkcí
|
|
2. Zaregistrujte v sadě nástrojů (propojeno pomocí `createMcpServer()`)
|
|
3. Přiřaďte k příslušným rozsahům
|
|
4. Napište testy (vyvolání nástroje je zaznamenáno do tabulky `mcp_audit`)
|
|
|
|
### Přidání nové A2A dovednosti
|
|
|
|
1. Vytvořte dovednost v `src/lib/a2a/skills/` (5 již existuje: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
|
|
2. Dovednost přijímá kontext úkolu (zprávy, metadata) → vrací strukturovaný výsledek
|
|
3. Zaregistrujte v `A2A_SKILL_HANDLERS` v `src/lib/a2a/taskExecution.ts`
|
|
4. Exponujte v `src/app/.well-known/agent.json/route.ts` (Agent Card)
|
|
5. Napište testy v `tests/unit/`
|
|
6. Dokumentujte v `docs/frameworks/A2A-SERVER.md` tabulka dovedností
|
|
|
|
### Přidání nového cloudového agenta
|
|
|
|
1. Vytvořte třídu agenta v `src/lib/cloudAgent/agents/` rozšiřující `CloudAgentBase` (3 již existují: codex-cloud, devin, jules)
|
|
2. Implementujte `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
|
|
3. Zaregistrujte v `src/lib/cloudAgent/registry.ts`
|
|
4. Přidejte zpracování OAuth/přihlašovacích údajů, pokud je potřeba (`src/lib/oauth/providers/`)
|
|
5. Testy + dokumentujte v `docs/frameworks/CLOUD_AGENT.md`
|
|
|
|
### Přidání nového guardrail / eval / dovednosti / webhook události
|
|
|
|
- Guardrail: `src/lib/guardrails/` → dokumentace: `docs/security/GUARDRAILS.md`
|
|
- Eval suite: `src/lib/evals/` → dokumentace: `docs/frameworks/EVALS.md`
|
|
- Dovednost (sandbox): `src/lib/skills/` → dokumentace: `docs/frameworks/SKILLS.md`
|
|
- Webhook událost: `src/lib/webhookDispatcher.ts` → dokumentace: `docs/frameworks/WEBHOOKS.md`
|
|
|
|
## Referenční dokumentace
|
|
|
|
Před jakoukoli netriviální změnou si nejprve přečtěte odpovídající podrobnou analýzu:
|
|
|
|
| Oblast | Dokument |
|
|
| ------------------------------------------------ | ----------------------------------------------------------------- |
|
|
| Navigace repozitářem | `docs/architecture/REPOSITORY_MAP.md` |
|
|
| Architektura | `docs/architecture/ARCHITECTURE.md` |
|
|
| Odkaz na inženýrství | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
|
|
| Auto-Combo (9-faktorové hodnocení, 14 strategií) | `docs/routing/AUTO-COMBO.md` |
|
|
| Odolnost (3 mechanismy) | `docs/architecture/RESILIENCE_GUIDE.md` |
|
|
| Opakování uvažování | `docs/routing/REASONING_REPLAY.md` |
|
|
| Rámec dovedností | `docs/frameworks/SKILLS.md` |
|
|
| Systém paměti (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` |
|
|
| Cloudoví agenti | `docs/frameworks/CLOUD_AGENT.md` |
|
|
| Ochranné prvky (PII / injekce / vize) | `docs/security/GUARDRAILS.md` |
|
|
| Veřejné přihlašovací údaje (Gemini atd.) | `docs/security/PUBLIC_CREDS.md` |
|
|
| Sanitizace chybových zpráv | `docs/security/ERROR_SANITIZATION.md` |
|
|
| Hodnocení | `docs/frameworks/EVALS.md` |
|
|
| Soulad / audit | `docs/security/COMPLIANCE.md` |
|
|
| Webhooky | `docs/frameworks/WEBHOOKS.md` |
|
|
| Autorizační pipeline | `docs/architecture/AUTHZ_GUIDE.md` |
|
|
| Stealth (TLS / otisk) | `docs/security/STEALTH_GUIDE.md` |
|
|
| Protokoly agentů (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |
|
|
| MCP server | `docs/frameworks/MCP-SERVER.md` |
|
|
| A2A server | `docs/frameworks/A2A-SERVER.md` |
|
|
| Odkaz na API + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
|
|
| Katalog poskytovatelů (automaticky generovaný) | `docs/reference/PROVIDER_REFERENCE.md` |
|
|
| Tok vydání | `docs/ops/RELEASE_CHECKLIST.md` |
|
|
|
|
## Testování
|
|
|
|
| Co | Příkaz |
|
|
| ----------------------- | ------------------------------------------------------------------ |
|
|
| Jednotkové testy | `npm run test:unit` |
|
|
| Jediný soubor | `node --import tsx/esm --test tests/unit/file.test.ts` |
|
|
| Vitest (MCP, autoCombo) | `npm run test:vitest` |
|
|
| E2E (Playwright) | `npm run test:e2e` |
|
|
| Protokol E2E (MCP+A2A) | `npm run test:protocols:e2e` |
|
|
| Ekosystém | `npm run test:ecosystem` |
|
|
| Brána pokrytí | `npm run test:coverage` (75/75/75/70 — příkazy/řádky/funkce/větve) |
|
|
| Zpráva o pokrytí | `npm run coverage:report` |
|
|
|
|
**Pravidlo PR**: Pokud změníte produkční kód v `src/`, `open-sse/`, `electron/` nebo `bin/`, musíte zahrnout nebo aktualizovat testy ve stejném PR.
|
|
|
|
**Preferovaný testovací vrstvy**: jednotkové testy první → integrace (více modulů nebo stav DB) → e2e (pouze UI/workflow). Kódování reprodukcí chyb jako automatizovaných testů před nebo spolu s opravou.
|
|
|
|
**Politika pokrytí Copilot**: Když PR změní produkční kód a pokrytí je pod 75% (příkazy/řádky/funkce) nebo 70% (větve), nehlaste pouze — přidejte nebo aktualizujte testy, znovu spusťte bránu pokrytí a poté požádejte o potvrzení. Zahrňte provedené příkazy, změněné testovací soubory a konečný výsledek pokrytí do zprávy PR.
|
|
|
|
---
|
|
|
|
## Git Workflow
|
|
|
|
```bash
|
|
# Nikdy neprovádějte commit přímo do main
|
|
git checkout -b feat/your-feature
|
|
git commit -m "feat: popište svou změnu"
|
|
git push -u origin feat/your-feature
|
|
```
|
|
|
|
**Předpony větví**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`
|
|
|
|
**Formát commitu** (Conventional Commits): `feat(db): přidat circuit breaker` — rozsahy: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`
|
|
|
|
**Husky hooky**:
|
|
|
|
- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
|
|
- **pre-push**: `npm run test:unit`
|
|
|
|
---
|
|
|
|
## Prostředí
|
|
|
|
- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES moduly
|
|
- **TypeScript**: 5.9+, cíl ES2022, modul esnext, rozlišení bundler
|
|
- **Cestovní aliasy**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
|
|
- **Výchozí port**: 20128 (API + dashboard na stejném portu)
|
|
- **Adresář dat**: `DATA_DIR` env var, výchozí hodnota `~/.omniroute/`
|
|
- **Klíčové env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
|
|
- Nastavení: `cp .env.example .env` poté vygenerujte `JWT_SECRET` (`openssl rand -base64 48`) a `API_KEY_SECRET` (`openssl rand -hex 32`)
|
|
|
|
---
|
|
|
|
## Přísná pravidla
|
|
|
|
1. Nikdy neprovádějte commit tajemství nebo přihlašovacích údajů
|
|
2. Nikdy nepřidávejte logiku do `localDb.ts`
|
|
3. Nikdy nepoužívejte `eval()` / `new Function()` / implicitní eval
|
|
4. Nikdy neprovádějte commit přímo do `main`
|
|
5. Nikdy nepíšete surový SQL v trasách — používejte moduly `src/lib/db/`
|
|
6. Nikdy tiše nezachycujte chyby ve SSE streamech
|
|
7. Vždy validujte vstupy pomocí Zod schémat
|
|
8. Vždy zahrňte testy při změně produkčního kódu
|
|
9. Pokrytí musí zůstat ≥75% (příkazy, řádky, funkce) / ≥70% (větve). Aktuálně měřeno: ~82%.
|
|
10. Nikdy neobcházejte Husky hooky (`--no-verify`, `--no-gpg-sign`) bez explicitního schválení operátora.
|
|
11. Nikdy nezahrnujte veřejné upstream OAuth client_id/secret nebo Firebase Web klíče jako řetězcové literály — vždy používejte `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). Viz `docs/security/PUBLIC_CREDS.md`.
|
|
12. Nikdy nevracejte surový `err.stack` / `err.message` v HTTP / SSE / odpovědích executorů — vždy procházejte přes `buildErrorBody()` nebo `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). Viz `docs/security/ERROR_SANITIZATION.md`.
|
|
13. Nikdy neprovádějte interpolaci řetězců externích cest nebo runtime hodnot do shell skriptů předávaných do `exec()`/`spawn()` — předávejte je místo toho přes možnost `env`. Odkaz: `src/mitm/cert/install.ts::updateNssDatabases`.
|
|
14. Nikdy neignorujte upozornění CodeQL / Secret-Scanning bez (a) nejprve zkontrolování dokumentace vzoru výše, abyste zjistili, zda se pomocník vztahuje, a (b) zaznamenání technického odůvodnění do komentáře o zamítnutí. Precedent: `js/stack-trace-exposure` vznesený na místech volání, která již procházejí přes `sanitizeErrorMessage()`, je známé omezení CodeQL (vlastní sanitizátory nejsou rozpoznány) — zamítněte jako `false positive` s odkazem na `docs/security/ERROR_SANITIZATION.md`.
|
|
15. Nikdy nezveřejňujte trasy, které spouštějí podřízené procesy (`/api/mcp/`, `/api/cli-tools/runtime/`) bez klasifikace `isLocalOnlyPath()` v `src/server/authz/routeGuard.ts`. Vynucení loopbacku probíhá bezpodmínečně před jakýmkoli ověřením — uniklý JWT přes tunel nemůže spustit proces. Viz `docs/security/ROUTE_GUARD_TIERS.md`.
|
|
16. Nikdy nezahrnujte `Co-Authored-By` přílohy, které připisují AI asistenta, LLM nebo automatizovaný účet (např. jména obsahující "Claude", "GPT", "Copilot", "Bot"; e-maily na `anthropic.com` / `openai.com` / adresách `noreply.github.com` vlastněných boty). Takové přílohy směrují přiřazení commitů na účet bota na GitHubu, čímž skrývají skutečného autora (`diegosouzapw`) v historii PR. Lidští spolupracovníci — včetně autorů upstream PR a hlasatelů issues přenášených do OmniRoute — MOHOU a MĚLI BY být uvedeni standardními přílohami `Co-authored-by: Name <email>`; upstream-port pracovní postupy (`/port-upstream-features`, `/port-upstream-issues`) na tom závisí.
|