# OmniRoute Codebase Documentation (Bahasa Melayu) 🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇦 [bs](../../../bs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../../de/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../../nl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../../pt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../../ro/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md) --- > **Versi:** v3.8.51 > **Kemas kini terakhir:** 2026-06-28 > **Khalayak:** Jurutera yang menyumbang kepada OmniRoute atau membina integrasi di atasnya. > > Untuk rajah seni bina peringkat tinggi dan rasional di sebalik setiap subsistem, baca > [ARCHITECTURE.md](./ARCHITECTURE.md). Untuk penerangan mendalam tentang setiap subsistem > (Auto Combo, pelayan MCP, pelayan A2A, Kemahiran, Memori, Ejen Awan, Ketahanan, > Pemampatan dan sebagainya), lihat fail khusus masing-masing dalam direktori `docs/` ini. Fail ini menerangkan **perkara yang wujud dalam repositori pada masa ini** supaya jurutera baharu boleh menavigasi pepohon, memahami pelapisan masa jalan dan mengetahui tempat untuk menambahkan kod tanpa mencipta modul baharu. --- ## 1. Tindanan Teknologi | Aspek | Pilihan | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | Kerangka web | **Next.js 16** (App Router, output kendiri, tiada perisian tengah global) | | Bahasa | **TypeScript 6.0+** — sasaran `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false` | | Masa jalan | **Node.js** `>=22.22.2 <23` atau `>=24.0.0 <27` (dikuatkuasakan melalui `engines` + `SUPPORTED_NODE_RANGE`) | | Pangkalan data | **SQLite** melalui `better-sqlite3` (tunggal, penjurnalan WAL) | | Desktop | **Electron 41** + `electron-builder` 26.10 (ruang kerja berasingan di `electron/`) | | Ujian | **Pelaksana ujian asli Node** (unit/integrasi), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e) | | Binaan | Next.js kendiri melalui `scripts/build/build-next-isolated.mjs` | | Lint/format | Konfigurasi rata ESLint + Prettier (`lint-staged` melalui pra-komit Husky) | | Sistem modul | ESM di semua tempat (`"type": "module"`) | | Ruang kerja | Ruang kerja npm — `open-sse` ialah satu-satunya subruang kerja | Alias laluan (`tsconfig.json`): - `@/*` → `src/*` - `@omniroute/open-sse` → `open-sse/index.ts` - `@omniroute/open-sse/*` → `open-sse/*` Port HTTP lalai: **`20128`** (API dan papan pemuka berkongsi proses yang sama). Direktori data ialah pemboleh ubah persekitaran `DATA_DIR`, dengan nilai lalai `~/.omniroute/`. --- ## 2. Susun Atur Repositori ``` OmniRoute/ ├── src/ Aplikasi Next.js (App Router, pustaka, domain, pelayan, dikongsi) ├── open-sse/ Ruang kerja enjin penstriman (@omniroute/open-sse) ├── electron/ Pembalut desktop (proses utama + pramuat Electron 41) ├── bin/ Titik masuk CLI (omniroute, reset-password) ├── tests/ Unit, integrasi, e2e, protocols-e2e, penterjemah, keselamatan, lekapan ├── scripts/ Skrip bantuan binaan, penyegerakan, semakan, migrasi dan masa jalan ├── docs/ Dokumentasi awam (direktori ini) ├── public/ Aset statik, manifes PWA, pekerja perkhidmatan ├── config/ Sampel konfigurasi masa jalan ├── images/ Aset pemasaran/tangkapan skrin ├── _ideia/, _references/, _mono_repo/, _tasks/ Catatan sementara / perancangan dalaman (tidak diedarkan) ├── CLAUDE.md Peraturan repositori untuk Claude Code ├── AGENTS.md Rujukan seni bina yang lebih mendalam untuk ejen ├── package.json v3.8.51, akar ruang kerja └── tsconfig.json Alias laluan + pilihan pengkompil teras ``` --- ## 3. `src/` — Aplikasi Next.js ``` src/ ├── app/ Halaman App Router + laluan API ├── lib/ Pustaka teras (DB, pengesahan, OAuth, kemahiran, memori, …) ├── domain/ Lapisan domain tulen (dasar, sandaran, kos, sekatan, …) ├── server/ Modul khusus pelayan (authz, cors, pengesahan) ├── shared/ Jenis, pemalar, pengesahan, kontrak, utiliti (selamat merentas sempadan) ├── mitm/ Pembantu proksi orang tengah untuk penyepaduan CLI ├── models/ Metadata / pengaliasan model setempat ├── sse/ Pengendali SSE legasi yang masih berada di bawah src/ (bukan open-sse/) ├── store/ Storan keadaan sisi klien ├── middleware/ Utiliti perisian tengah peringkat laluan (bukan perisian tengah global Next.js) ├── scripts/ Skrip dalam pepohon yang boleh diimport oleh kod aplikasi ├── types/ Jenis TS ambien dan dikongsi ├── i18n/ Himpunan lokal ├── instrumentation.ts Cangkuk instrumentasi Next.js ├── instrumentation-node.ts └── proxy.ts Pembantu pemula proksi peringkat atas ``` ### 3.1 `src/app/` — App Router App Router mendedahkan kedua-dua UI papan pemuka dan API HTTP awam/pengurusan. **Tiada perisian tengah global** — pemintasan dilakukan bagi setiap laluan. Segmen peringkat atas di bawah `src/app/`: | Laluan | Tujuan | | ----------------------------------------------------------------------------- | --------------------------------------------------- | | `api/` | Semua laluan API HTTP (lihat pecahan di bawah) | | `a2a/` | Titik akhir JSON-RPC 2.0 A2A (`POST /a2a`) | | `.well-known/agent.json/` | Dokumen penemuan Kad Ejen A2A | | `(dashboard)/` | UI papan pemuka (kumpulan laluan, tiada awalan URL) | | `auth/`, `login/`, `forgot-password/`, `callback/` | Aliran pengesahan | | `landing/` | Halaman pemasaran/pendaratan | | `docs/` | Pemapar dokumentasi API terbenam | | `status/`, `maintenance/`, `offline/` | Halaman operasi | | `privacy/`, `terms/` | Halaman perundangan | | `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/` | Halaman ralat statik | | `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | Sempadan ralat/pemuatan rangka kerja | | `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts` | Kerangka akar | #### 3.1.1 `src/app/(dashboard)/dashboard/` — Halaman UI `agents`, `analytics`, `api-manager`, `audit`, `auto-combo`, `batch`, `cache`, `changelog`, `cli-tools`, `cloud-agents`, `combos`, `compression`, `context`, `costs`, `endpoint`, `health`, `limits`, `logs`, `memory`, `onboarding`, `playground`, `providers`, `search-tools`, `settings`, `skills`, `system`, `translator`, `usage`, `webhooks`, serta `page.tsx`, `HomePageClient.tsx`, `BootstrapBanner.tsx` akar. #### 3.1.2 `src/app/api/` — Kumpulan API peringkat atas ``` src/app/api/ ├── a2a/{status, tasks} ├── acp/ ├── admin/ ├── analytics/ ├── assess/ ├── auth/ ├── batches/ ├── cache/ ├── cli-tools/ ├── cloud/{codex-responses-ws} ├── combos/ ├── compliance/ ├── compression/ ├── context/ ├── db/, db-backups/ ├── evals/ ├── fallback/ ├── files/ ├── health/ ├── init/ ├── internal/{concurrency} ├── keys/ ├── logs/ ├── mcp/{audit, sse, status, stream, tools} ├── memory/{health, [id]/, route.ts} ├── model-combo-mappings/ ├── models/ ├── monitoring/ ├── oauth/ ├── openapi/ ├── policies/ ├── pricing/ ├── provider-metrics/, provider-models/, provider-nodes/ ├── providers/ ├── rate-limit/, rate-limits/ ├── resilience/ ├── restart/, shutdown/ ├── search/ ├── sessions/ ├── settings/ ├── skills/{executions, [id], install, marketplace, route.ts, skillssh} ├── storage/ ├── sync/, synced-available-models/ ├── system/ ├── tags/ ├── telemetry/ ├── token-health/ ├── translator/ ├── tunnels/ ├── services/ Pengurusan perkhidmatan terbenam (9router, cliproxy) — LOCAL_ONLY ├── upstream-proxy/ ├── usage/ ├── v1/ API awam serasi OpenAI ├── v1beta/ Keserasian gaya Gemini ├── version-manager/ └── webhooks/ ``` #### 3.1.2a `src/app/api/services/` — Pengurusan Perkhidmatan Terbenam Laluan untuk memasang, memulakan, menghentikan dan memantau 9Router serta CLIProxyAPI. Semua laluan dikelaskan sebagai **LOCAL_ONLY** (gelung balik sahaja, peraturan tegas #17) kerana laluan ini boleh menjalankan `npm install` dan mencetuskan proses anak. ``` src/app/api/services/ ├── 9router/ │ ├── _lib.ts pembantu getOrInitSupervisor() │ ├── install/route.ts POST — npm install melalui execFile │ ├── start/route.ts POST — supervisor.start() │ ├── stop/route.ts POST — supervisor.stop() │ ├── restart/route.ts POST — supervisor.restart() │ ├── update/route.ts POST — npm install versi lebih baharu │ ├── rotate-key/route.ts POST — jana kunci API baharu + mulakan semula │ ├── status/route.ts GET — status langsung + DB + metadata versi │ └── auto-start/route.ts POST — togol bendera auto_start ├── cliproxy/ │ ├── _lib.ts pembantu getOrInitSupervisor() │ ├── install/route.ts POST — npm install │ ├── start/route.ts POST — supervisor.start() │ ├── stop/route.ts POST — supervisor.stop() │ ├── restart/route.ts POST — supervisor.restart() │ ├── update/route.ts POST — npm install versi lebih baharu │ ├── status/route.ts GET — status langsung + DB + metadata versi │ └── auto-start/route.ts POST — togol bendera auto_start └── [name]/ └── logs/route.ts GET — ekor log SSE (dikongsi oleh semua perkhidmatan) ``` UI papan pemuka yang sepadan: `src/app/(dashboard)/dashboard/providers/services/` — halaman dua tab (CLIProxyAPI + 9Router). Proksi songsang untuk UI terbenam 9Router: `src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts` Kupasan mendalam: `docs/frameworks/EMBEDDED-SERVICES.md` #### 3.1.3 `src/app/api/v1/` — API awam serasi OpenAI ``` v1/ ├── accounts/[id]/ carian akaun ├── agents/tasks/[id]/, agents/tasks/ titik akhir tugas bercirikan A2A ├── api/ pembantu API dalaman yang didedahkan di bawah v1/api ├── audio/{speech, transcriptions}/ TTS + STT ├── batches/[id]/{cancel}, batches/ API Kelompok OpenAI ├── chat/completions/ Pelengkapan Sembang (titik akhir utama) ├── completions/ Pelengkapan teks legasi ├── embeddings/ Pembenaman ├── files/[id]/, files/ API Fail ├── _helpers/ Pembantu laluan dikongsi (tiada URL awam) ├── images/{edits, generations}/ Penjanaan + penyuntingan imej ├── issues/ Titik akhir pembantu triage ├── management/{proxies}/ Laluan berskop pengurusan dalam v1 ├── messages/{count_tokens}/ Keserasian mesej gaya Anthropic ├── models/ Penyenaraian model (`route.ts`, `catalog.ts`) ├── moderations/ Penyederhanaan ├── music/ Penjanaan muzik ├── providers/[provider]/ Operasi mengikut penyedia ├── quotas/{check} Probe kuota ├── registered-keys/ Pentadbir kunci berdaftar ├── rerank/ Penyusunan semula kedudukan ├── responses/[...path]/ API Respons OpenAI (tangkap semua) ├── search/ Carian web ├── videos/ Penjanaan video ├── ws/ Jambatan WebSocket └── route.ts Pengendali indeks ``` Setiap fail laluan mengikut corak yang sama: ``` Laluan → Praterbang CORS → Pengesahan badan Zod → pengesahan pilihan → Penguatkuasaan dasar kunci API → delegasi pengendali (open-sse) ``` `v1beta/` ialah permukaan keserasian gaya Gemini (pembalut nipis yang menterjemah kepada saluran paip `open-sse/handlers/` yang sama). ### 3.2 `src/lib/` — Pustaka teras Sentiasa import data, penyegerakan, OAuth, kemahiran, memori dan sebagainya melalui modul ini. Jadual tersebut mengumpulkan direktori sebenar dan fail peringkat atas yang penting. | Modul | Tujuan | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `a2a/` | Pelayan protokol A2A: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 kemahiran: analisis kos, laporan kesihatan, penemuan penyedia, pengurusan kuota, penghalaan pintar, senarai keupayaan) | | `acp/` | Agent-Control-Protocol: `index.ts`, `manager.ts`, `registry.ts` | | `api/` | Pembantu API dalaman: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts` | | `auth/` | `managementPassword.ts` (penetapan semula kata laluan / pencincangan) | | `batches/` | Perkhidmatan OpenAI Batches API (`service.ts`) | | `catalog/` | Penyegerakan katalog OpenRouter (`openrouterCatalog.ts`) | | `cloudAgent/` | Daftar ejen awan: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts` | | `combos/` | Pembantu peleraian gabungan | | `compliance/` | Audit + audit penyedia: `index.ts`, `providerAudit.ts` | | `config/` | Perekat konfigurasi masa jalan | | `db/` | Modul domain SQLite (lihat §3.2.1) | | `display/` | Pembantu UI/paparan yang digunakan oleh respons API | | `embeddings/` | Daftar perkhidmatan pembenaman | | `env/` | Pemuatan + introspeksi persekitaran | | `evals/` | Masa jalan penilaian | | `guardrails/` | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts` | | `jobs/` | Tugas latar belakang (`autoUpdate.ts`, …) | | `memory/` | Memori berterusan: `store.ts`, `cache.ts`, `retrieval.ts`, `summarization.ts`, `extraction.ts`, `injection.ts`, `qdrant.ts`, `settings.ts`, `verify.ts`, `schemas.ts`, `types.ts` | | `monitoring/` | `observability.ts` | | `oauth/` | Modul penyedia OAuth/import (22): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `openference`, `qoder`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, serta `services/`, `utils/`, dan `constants/oauth.ts` | | `plugins/` | Pemuat pemalam (`index.ts`) | | `promptCache/` | `prefixAnalyzer.ts`, `index.ts` | | `providerModels/` | Kitaran hayat model terurus: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts` | | `providers/` | Pembantu penyedia: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts` | | `resilience/` | `settings.ts` — tetapan untuk pemutus litar, tempoh bertenang, penguncian | | `runtime/` | Pengesanan ciri masa jalan | | `search/` | `executeWebSearch.ts` | | `services/` | Rangka kerja perkhidmatan terbenam: `ServiceSupervisor.ts` (penyelia proses anak generik dengan kunci operasi, penimbal cincin, pemeriksa kesihatan), `bootstrap.ts` (pendaftaran peringkat proses dan permulaan automatik), `registry.ts` (peta alat → penyelia), `apiKey.ts` (storan kunci AES-256-GCM), `modelSync.ts` (penyegerakan model berkala), `ringBuffer.ts` (penimbal log bulat 5 MB), `healthCheck.ts` (prob kesihatan HTTP), `types.ts`, `embedWsProxy.ts` (proksi WebSocket), `installers/{ninerouter,cliproxy}.ts`. Lihat `docs/frameworks/EMBEDDED-SERVICES.md` | | `agentSkills/` | Katalog + penjana Kemahiran Ejen: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → menulis `skills/{id}/SKILL.md`), `openapiParser.ts` (mengekstrak titik akhir REST daripada spesifikasi OpenAPI), `cliRegistryParser.ts` (mengekstrak subperintah CLI daripada bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Digunakan oleh laluan REST (`/api/agent-skills/*`), alat MCP (`omniroute_agent_skills_*`), dan kemahiran A2A `list-capabilities`. Lihat [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). | | `skills/` | Rangka kerja kemahiran: `registry.ts`, `executor.ts`, `interception.ts`, `injection.ts`, `sandbox.ts`, `custom.ts`, `hybrid.ts`, `builtins.ts`, `a2a.ts`, `providerSettings.ts`, `schemas.ts`, `skillssh.ts`, `types.ts`, serta `builtin/browser.ts` | | `spend/` | `batchWriter.ts` (penimbal tulis-kemudian) | | `sync/` | `bundle.ts`, `tokens.ts` (Penyegerakan Awan) | | `system/` | Pembantu peringkat sistem | | `translator/` | Perekat penterjemah peringkat atas (mewakilkan kepada `open-sse/translator/`) | | `usage/` | Perakaunan penggunaan: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts` | | `versionManager/` | Kemas kini automatik + manifes versi | | `ws/` | Jambatan WebSocket | | `zed-oauth/` | Aliran OAuth editor Zed | Fail peringkat teratas dalam `src/lib/`: - Fail barrel lama `localDb.ts` telah dialih keluar — pengguna mengimport modul `src/lib/db/*` tertentu secara langsung. - `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts` - `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts` - `cloudSync.ts`, `initCloudSync.ts` - `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts` - `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts` - `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts` - `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts` - `piiSanitizer.ts`, `pricingSync.ts` - `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts` - `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts` #### 3.2.1 `src/lib/db/` Pangkalan data SQLite tunggal (`getDbInstance()` dalam `core.ts`, penjurnalan WAL). **Jangan sekali-kali menulis SQL mentah dalam laluan atau pengendali** — gunakan modul-modul ini. ![Gambaran keseluruhan skema pangkalan data (jadual teras terpilih)](../diagrams/exported/db-schema-overview.svg) > Sumber: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd) Modul domain (setiap satu mengurus satu atau lebih jadual): `apiKeys.ts`, `backup.ts`, `batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`, `commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`, `compressionCacheStats.ts`, `compressionCombos.ts`, `compressionScheduler.ts`, `contextHandoffs.ts`, `core.ts`, `creditBalance.ts`, `databaseSettings.ts`, `detailedLogs.ts`, `domainState.ts`, `encryption.ts`, `evals.ts`, `files.ts`, `healthCheck.ts`, `jsonMigration.ts`, `migrationRunner.ts`, `modelComboMappings.ts`, `models.ts`, `oneproxy.ts`, `prompts.ts`, `providers.ts`, `providerLimits.ts`, `proxies.ts`, `quotaSnapshots.ts`, `readCache.ts`, `reasoningCache.ts`, `registeredKeys.ts`, `secrets.ts`, `sessionAccountAffinity.ts`, `settings.ts`, `stateReset.ts`, `stats.ts`, `syncTokens.ts`, `tierConfig.ts`, `upstreamProxy.ts`, `versionManager.ts`, `webhooks.ts`. `migrations/` mengandungi 168 fail `.sql` berversi (idempoten, bertransaksi) dan dilaksanakan oleh `migrationRunner.ts` semasa permulaan. Jadual yang dicipta merentas migrasi (jumlah 123): `a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`, `combo_adaptation_state`, `combos`, `command_code_auth_sessions`, `compression_analytics`, `compression_cache_stats`, `compression_combo_assignments`, `compression_combos`, `context_handoffs`, `daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`, `domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`, `eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`, `key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`, `provider_connections`, `provider_key_limits`, `provider_nodes`, `proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`, `reasoning_cache`, `registered_keys`, `request_detail_logs`, `routing_decisions`, `semantic_cache`, `session_account_affinity`, `skill_executions`, `skills`, `sync_tokens`, `tier_assignments`, `tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`, `webhooks` (serta jadual maya FTS5 untuk carian memori). ### 3.3 `src/domain/` — Lapisan domain Logik perniagaan tulen, tanpa I/O. Diimport oleh laluan dan pengendali. | Fail | Tujuan | | ------------------------------------------ | -------------------------------------------------------- | | `policyEngine.ts` | Penyelesai dasar peringkat teratas | | `fallbackPolicy.ts` | Pepohon keputusan sandaran | | `costRules.ts` | Peraturan pengiraan kos | | `lockoutPolicy.ts` | Keputusan sekatan model | | `tagRouter.ts` | Penghalaan berasaskan tag | | `comboResolver.ts` | Penyelesaian kombo daripada permintaan → senarai sasaran | | `connectionModelRules.ts` | Penapis model bagi setiap sambungan | | `modelAvailability.ts` | Semakan ketersediaan model | | `degradation.ts` | Peralihan mod terdegradasi | | `providerExpiration.ts` | Pengesanan akaun/kunci yang telah tamat tempoh | | `quotaCache.ts` | Keputusan kuota yang dicache | | `responses.ts`, `omnirouteResponseMeta.ts` | Pembantu bentuk respons | | `configAudit.ts` | Audit perubahan konfigurasi | | `assessment/` | Penilaian model (mengikut RFC, dilaksanakan sebahagian) | | `types.ts` | Jenis domain dikongsi | ### 3.4 `src/server/` — Pelayan sahaja Tidak boleh diimport daripada komponen klien. ``` server/ ├── auth/loginGuard.ts ├── authz/ │ ├── classify.ts Mengelaskan laluan sebagai awam atau pengurusan │ ├── assertAuth.ts Pembantu penegasan │ ├── context.ts Konteks authz bagi setiap permintaan │ ├── headers.ts │ ├── pipeline.ts Saluran paip authz │ ├── policies/ Dasar konkrit │ └── types.ts └── cors/origins.ts Senarai asal CORS yang dibenarkan ``` ### 3.5 `src/shared/` — Selamat untuk dikongsi Dibahagikan kepada subdirektori khusus: - `constants/` — `providers.ts` (katalog penyedia yang disahkan oleh Zod), `models.ts`, `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`, `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`, `headers.ts`, `upstreamHeaders.ts` (senarai sekatan), `mcpScopes.ts`, `errorCodes.ts`, `publicApiRoutes.ts`, `batch.ts`, `batchEndpoints.ts`, `bodySize.ts`, `colors.ts`, `appConfig.ts`, `config.ts`, `sidebarVisibility.ts`, `visionBridgeDefaults.ts`. - `validation/` — `schemas.ts` (~80 skema Zod), `compressionConfigSchemas.ts`, `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`. - `contracts/` — kontrak API awam yang diterbitkan ke npm. - `types/` — jenis TS yang dikongsi. - `utils/` — `circuitBreaker.ts`, `apiAuth.ts`, `apiKey.ts`, `apiKeyPolicy.ts`, `api.ts`, `classify429.ts`, `cliCompat.ts`, `clipboard.ts`, `cloud.ts`, `cn.ts`, `cors.ts`, `featureFlags.ts`, `fetchTimeout.ts`, `formatting.ts`, `inputSanitizer.ts`, `logger.ts`, `machine.ts`, `machineId.ts`, `maskEmail.ts`, `modelCatalogSearch.ts`, `nodeRuntimeSupport.ts`, `parseApiKeys.ts`, `providerHints.ts`, `providerModelAliases.ts`, `rateLimiter.ts`, `releaseNotes.ts`, `a11yAudit.ts`, serta cangkuk/komponen papan pemuka di bawah `services/`, `network/`, `middleware/`, `schemas/`, `hooks/`, `components/`. --- ## 4. `open-sse/` — Ruang kerja enjin penstriman Ruang kerja npm berasingan yang diterbitkan sebagai `@omniroute/open-sse`. Mengendalikan pemprosesan permintaan, pelaksana, penterjemah, perkhidmatan, pengubah, dan pelayan MCP. ``` open-sse/ ├── index.ts Eksport awam ├── package.json Manifes ruang kerja ├── tsconfig.json ├── types.d.ts ├── config/ Daftar penyedia, profil pengepala, identiti, … ├── handlers/ Pengendali permintaan (sembang, pembenaman, audio, imej, …) ├── executors/ 108 pelaksana HTTP khusus penyedia ├── translator/ Penukaran format (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro) ├── transformer/ Pengubah strim Responses API ↔ Chat Completions ├── services/ 80+ modul perkhidmatan (gabungan, sandaran, kuota, identiti, …) ├── utils/ Pembantu penstriman, klien TLS, AWS SigV4, pengambilan proksi, … └── mcp-server/ Pelayan MCP (3 pengangkutan, 33 skop, 110 alat) ``` ### 4.1 `open-sse/handlers/` | Pengendali | Tujuan | | ----------------------- | ------------------------------------------------------------------------------------------ | | `chatCore.ts` | Saluran paip sembang utama (cache, had kadar, penghalaan gabungan, penghantaran pelaksana) | | `responsesHandler.ts` | Titik masuk OpenAI Responses API | | `embeddings.ts` | Pembenaman | | `imageGeneration.ts` | Penjanaan imej | | `audioSpeech.ts` | Teks kepada pertuturan | | `audioTranscription.ts` | Pertuturan kepada teks | | `videoGeneration.ts` | Penjanaan video | | `musicGeneration.ts` | Penjanaan muzik | | `rerank.ts` | Penyusunan semula kedudukan | | `moderations.ts` | Penyederhanaan | | `search.ts` | Carian web | | `sseParser.ts` | Penghurai peristiwa SSE | | `usageExtractor.ts` | Mengekstrak kiraan token daripada strim huluan | | `responseSanitizer.ts` | Membuang hingar khusus penyedia | | `responseTranslator.ts` | Penghubung antara respons penyedia dengan lapisan penterjemah | ### 4.2 `open-sse/executors/` 108 pelaksana penyedia, setiap satunya melanjutkan `BaseExecutor` (`base.ts`): `antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`, `chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`, `muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`, `pollinations`, `qoder`, `vertex`, `devin-desktop`, serta `claudeIdentity.ts` (pembantu identiti dikongsi) dan `index.ts` (daftar). > Nota: penyedia yang tidak disenaraikan di sini disediakan oleh `default.ts` menggunakan pelaksana > generik yang serasi dengan OpenAI. Katalog penyedia penuh (355 penyedia) terletak di > `src/shared/constants/providers.ts`. ### 4.3 `open-sse/translator/` Penterjemahan hab dan jejari (OpenAI ialah hab). - **9 penterjemah permintaan** (`translator/request/`): `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`, `gemini-to-openai`, `openai-responses`, `openai-to-claude`, `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`. - **9 penterjemah respons** (`translator/response/`): `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`, `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`, `openai-to-claude`. - **9 pembantu** (`translator/helpers/`): `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`, `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, serta ujian pembantu. - **Pembantu imej** (`translator/image/sizeMapper.ts`). - Peringkat atas: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`. ### 4.4 `open-sse/transformer/` - `responsesTransformer.ts` — Penukar Responses API ↔ Chat Completions berasaskan `TransformStream` (digunakan oleh tangkapan menyeluruh laluan `responses/`). ### 4.5 `open-sse/services/` Sorotan (senarai penuh di bawah `open-sse/services/`): | Perkara | Fail | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Penghalaan kombo | `combo.ts` (19 strategi), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts` | | Enjin Auto Combo | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts` | | Daya tahan | `accountFallback.ts` (tempoh bertenang + penguncian), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts` | | Kuota | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` | | Cache | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts` | | Kecerdasan penghalaan | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts` | | Pengendalian model | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts` | | Pemampatan | `compression/` — pendawaian enjin pemampatan penuh | | Token + sesi | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts` | | Tahap / manifes | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts` | | IP / rangkaian | `ipFilter.ts`, `webSearchFallback.ts` | | Kelompok | `batchProcessor.ts` | | Penggunaan | `usage.ts` | ### 4.6 `open-sse/mcp-server/` - **110 alat unik** yang disepadukan dalam `server.ts` (45 alat kanonik dalam `schemas/tools.ts` + modul memori, kemahiran, kemahiran GitHub, kumpulan, gamifikasi, pemalam, Notion, Obsidian, korpus setempat dan pemampatan — kesatuan dikira oleh `countUniqueMcpTools`). - **3 pengangkutan**: stdio, HTTP Streamable, SSE. - **33 skop** dikuatkuasakan semasa masa jalan — senarai asas dalam `src/shared/constants/mcpScopes.ts`, set penuh ialah kesatuan skop yang diisytiharkan oleh setiap modul alat. - Jadual audit: `mcp_tool_audit` (diisi oleh `audit.ts`). - Fail: `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`, `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`, `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`, serta ujian di bawah `__tests__/`. - Lihat [MCP-SERVER.md](../frameworks/MCP-SERVER.md) untuk katalog alat penuh. ### 4.7 `open-sse/config/` Daftar penyedia (`providerRegistry.ts`, `providerModels.ts`, `providerHeaderProfiles.ts`), daftar model mengikut format (`audioRegistry.ts`, `embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`, `musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`), pembantu identiti (`codexIdentity.ts`, `codexInstructions.ts`, `anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`, `cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`), pembantu kelayakan (`credentialLoader.ts`, `codexClient.ts`), dan penyesuai awan (`azureAi.ts`, `bedrock.ts`, `datarobot.ts`, `glmProvider.ts`, `maritalk.ts`, `oci.ts`, `petals.ts`, `runway.ts`, `sap.ts`, `watsonx.ts`, `ollamaModels.ts`, `errorConfig.ts`, `constants.ts`, `registryUtils.ts`). ### 4.8 `open-sse/utils/` Primitif penstriman dan pembantu penyedia: `stream.ts`, `streamHandler.ts`, `streamHelpers.ts`, `streamPayloadCollector.ts`, `streamReadiness.ts`, `sseHeartbeat.ts`, `proxyFetch.ts`, `proxyDispatcher.ts`, `tlsClient.ts`, `networkProxy.ts`, `awsSigV4.ts`, `cacheControlPolicy.ts`, `cursorChecksum.ts`, `cursorAgentProtobuf.ts`, `cursorVersionDetector.ts`, `comfyuiClient.ts`, `kieTask.ts`, `bypassHandler.ts`, `aiSdkCompat.ts`, `thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `requestLogger.ts`, `progressTracker.ts`, `cors.ts`, `error.ts`, `logger.ts`, `sleep.ts`, `ollamaTransform.ts`. --- ## 5. `electron/` — Pembalut desktop ``` electron/ ├── main.js Proses utama Electron ├── preload.js Jambatan pramuat (contextIsolation didayakan) ├── types.d.ts ├── package.json Konfigurasi electron-builder, versi 3.8.51 ├── README.md ├── assets/ Sumber binaan (ikon, kelayakan, …) ├── node_modules/ node_modules khusus (better-sqlite3, electron-updater) └── dist-electron/ Output binaan (tidak dikomit) ``` Lima skrip npm pada akar ruang kerja: `electron:dev`, `electron:build`, `electron:build:{win,mac,linux}`, `electron:smoke:packaged`. Kemas kini automatik dilakukan melalui `electron-updater` yang menghala ke suapan keluaran GitHub. --- ## 6. `bin/` — CLI ``` bin/ ├── omniroute.mjs Titik masuk CLI utama (Node ESM) ├── reset-password.mjs Tetapkan semula kata laluan pengurusan daripada CLI ├── mcp-server.mjs Pelancar pelayan MCP (stdio) ├── nodeRuntimeSupport.mjs Pengawal versi Node └── cli/ ├── program.mjs Pembina program Commander ├── runtime.mjs Pembantu withRuntime (utamakan pelayan/sandar balik DB) ├── output.mjs Pemformat output (json/jsonl/table/csv) ├── i18n.mjs Pembantu t() dengan penempatan ├── api.mjs Pembantu pengambilan API ├── data-dir.mjs ├── encryption.mjs ├── sqlite.mjs └── commands/ ├── registry.mjs Pendaftaran perintah ├── setup.mjs ├── doctor.mjs ├── providers.mjs └── ... (satu fail bagi setiap perintah/kumpulan) ``` Dua perduaan didedahkan dalam `package.json` → `bin`: - `omniroute` → `bin/omniroute.mjs` - `omniroute-reset-password` → `bin/reset-password.mjs` --- ## 7. `tests/` | Direktori | Jenis | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `tests/unit/` | Ujian unit melalui pelaksana ujian natif Node (1821 fail, serta subdirektori `api/`, `auth/`, `authz/`) | | `tests/integration/` | Ujian rentas modul + keadaan DB | | `tests/e2e/` | Ujian UI Playwright | | `tests/e2e/protocol-clients.test.ts` | E2E protokol MCP/A2A | | `tests/translator/` | Ujian khusus penterjemah | | `tests/security/` | Regresi keselamatan | | `tests/load/` | Ujian beban / tekanan | | `tests/golden-set/` | Output rujukan untuk regresi penterjemah | | `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | Sokongan | Perintah lazim: | Perintah | Perkara yang dijalankan | | -------------------------------------------------------- | --------------------------------------------------------------------------- | | `npm run test:unit` | Semua `tests/unit/*.test.ts` melalui pelaksana ujian Node (keserentakan 10) | | `npm run test:vitest` | Suit Vitest (MCP, autoCombo, cache) | | `npm run test:e2e` | Suit UI Playwright | | `npm run test:protocols:e2e` | E2E protokol MCP + A2A | | `npm run test:coverage` | Ambang liputan (≥60% baris/pernyataan/fungsi/cabang) | | `node --import tsx/esm --test tests/unit/.test.ts` | Pelaksanaan satu fail | --- ## 8. `scripts/` Disusun ke dalam 6 subfolder mengikut tujuan. - **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`, `prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`, `validate-pack-artifact.ts`, `postinstall.mjs`, `postinstallSupport.mjs`, `uninstall.mjs`, `bootstrap-env.mjs`, `runtime-env.mjs`, `native-binary-compat.mjs`. - **`scripts/dev/`** — `run-next.mjs`, `run-next-playwright.mjs`, `run-standalone.mjs`, `standalone-server-ws.mjs`, `responses-ws-proxy.mjs`, `v1-ws-bridge.mjs`, `smoke-electron-packaged.mjs`, `run-playwright-tests.mjs`, `run-ecosystem-tests.mjs`, `run-protocol-clients-tests.mjs`, `sync-env.mjs`, `healthcheck.mjs`, `system-info.mjs`. - **`scripts/check/`** — `check-cycles.mjs`, `check-docs-sync.mjs`, `check-docs-counts-sync.mjs`, `check-env-doc-sync.mjs`, `check-deprecated-versions.mjs`, `check-route-validation.mjs`, `check-t11-any-budget.mjs`, `check-pr-test-policy.mjs`, `check-supported-node-runtime.ts`, `test-report-summary.mjs`. - **`scripts/docs/`** — `generate-docs-index.mjs`, `gen-provider-reference.ts`. - **`scripts/i18n/`** — `generate-multilang.mjs`, `run-visual-qa.mjs`, `generate-qa-checklist.mjs`, `apply-priority-overrides.mjs`, `validate_translation.py`, `check_translations.py`, `i18n_autotranslate.py`, `untranslatable-keys.json`. - **`scripts/ad-hoc/`** — `cursor-tap.cjs`, `sync-cursor-models.mjs`, `migrate-env.mjs`, `dbsetup.js`. --- ## 9. Saluran Paip Permintaan (Ringkasan) ![Saluran paip permintaan (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg) > Sumber: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd) ``` Permintaan klien → /v1/chat/completions (route.ts) Semakan prapenerbangan CORS Pengesahan Zod (chatCompletionsSchema dalam shared/validation/schemas.ts) Pengesahan identiti (extractApiKey + isValidApiKey ATAU requireManagementAuth) Enjin dasar (src/server/authz/pipeline.ts) Langkah perlindungan (penopeng PII, suntikan gesaan, jambatan penglihatan) → handleChatCore() (open-sse/handlers/chatCore.ts) Semakan cache (cache semantik + cache bacaan) Had kadar (rateLimitManager, accountSemaphore) Penghalaan gabungan (jika model diselesaikan kepada gabungan) comboResolver → gelung bagi setiap sasaran → handleSingleModel() translateRequest() (open-sse/translator/request/*) getExecutor(providerId).execute() (open-sse/executors/*) ambil dari huluan → cuba semula/tunggu undur melalui accountFallback translateResponse() (open-sse/translator/response/*) Strim SSE ATAU respons JSON Jika Responses API: TransformStream melalui open-sse/transformer/responsesTransformer.ts → Audit pematuhan (src/lib/compliance/) → Respons kepada klien ``` ### Keadaan masa jalan daya tahan (tiga mekanisme) | Mekanisme | Skop | Lokasi | | -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Pemutus litar penyedia | Keseluruhan penyedia | `src/shared/utils/circuitBreaker.ts`, disimpan secara berterusan dalam `domain_circuit_breakers` | | Tempoh bertenang sambungan | Satu akaun/kunci | `markAccountUnavailable()` dalam `src/sse/services/auth.ts`; digunakan oleh `accountFallback.checkFallbackError()` | | Sekatan model | Penyedia + sambungan + model | `open-sse/services/accountFallback.ts`, disimpan secara berterusan dalam `domain_lockout_state` | Lihat [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) dan bahagian khusus dalam [CLAUDE.md](../../CLAUDE.md). --- ## 10. Cara Menyumbang ### Tambah penyedia baharu 1. Daftarkan dalam `src/shared/constants/providers.ts` (disahkan oleh Zod semasa pemuatan). 2. Tambah pelaksana dalam `open-sse/executors/` jika logik tersuai diperlukan (lanjutkan `BaseExecutor`). 3. Tambah penterjemah dalam `open-sse/translator/` jika ia tidak menggunakan format OpenAI. 4. Jika berasaskan OAuth, tambah konfigurasi di bawah `src/lib/oauth/providers/` dan `src/lib/oauth/services/`. 5. Daftarkan model dalam `open-sse/config/providerRegistry.ts` (atau pendaftaran khusus format di bawah `open-sse/config/`). 6. Tulis ujian di bawah `tests/unit/`. ### Tambah laluan API baharu 1. Cipta `src/app/api/your-route/route.ts`. 2. Ikuti corak: CORS → pengesahan isi permintaan Zod → pengesahan identiti → pengagihan kepada pengendali. 3. Jika bentuk permintaan baharu: tambah skema Zod dalam `src/shared/validation/schemas.ts`. 4. Jika untuk pengurusan sahaja: tambah laluan tersebut pada `src/shared/constants/publicApiRoutes.ts` (senarai sekatan untuk permukaan API awam). 5. Tambah ujian di bawah `tests/unit/`. 6. Kemas kini `docs/reference/API_REFERENCE.md` dan `docs/openapi.yaml`. ### Tambah modul DB baharu 1. Cipta `src/lib/db/yourModule.ts` dan import `getDbInstance()` daripada `./core.ts`. 2. Eksport fungsi CRUD untuk domain anda. 3. Jika terdapat jadual baharu: tambah migrasi di bawah `src/lib/db/migrations/`, yang dinomborkan secara berurutan, idempoten dan bertransaksi. 4. Pengimport menggunakan import langsung daripada `@/lib/db/yourModule` (tanpa barrel — lapisan eksport semula `localDb.ts` yang lama telah dialih keluar). 5. Tambah ujian di bawah `tests/unit/`. ### Tambah alat MCP baharu 1. Tambah takrif alat di bawah `open-sse/mcp-server/tools/` (atau lanjutkan `open-sse/mcp-server/schemas/tools.ts`). 2. Tetapkan skop yang sesuai dalam `src/shared/constants/mcpScopes.ts`. 3. Daftarkan alat tersebut dalam `open-sse/mcp-server/server.ts`. 4. Tambah ujian di bawah `open-sse/mcp-server/__tests__/`. 5. Kemas kini [MCP-SERVER.md](../frameworks/MCP-SERVER.md). ### Tambah kemahiran A2A baharu Lihat [A2A-SERVER.md § Menambah Kemahiran Baharu](../frameworks/A2A-SERVER.md). Kemahiran ditempatkan dalam `src/lib/a2a/skills/` dan didaftarkan melalui pengurus tugas A2A. --- ## 11. Konvensyen - **Gaya kod**: inden 2 ruang, petikan berganda, lebar 100 aksara, koma bernoktah, koma mengekor `es5` — dikuatkuasakan oleh Prettier melalui `lint-staged`. - **Import**: luaran → dalaman (`@/`, `@omniroute/open-sse`) → relatif. - **Penamaan**: fail `camelCase` atau `kebab-case`, komponen `PascalCase`, pemalar `UPPER_SNAKE`. - **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = `error` di semua tempat; `no-explicit-any` = `warn` dalam `open-sse/` dan `tests/`, ralat di tempat lain. - **TypeScript**: `strict: false` (pendekatan legasi). Utamakan jenis eksplisit berbanding inferens untuk sempadan rentas modul. - **Pangkalan data**: jangan sesekali tulis SQL mentah dalam laluan atau pengendali — sentiasa gunakan modul `src/lib/db/`. Jangan sesekali mengimport melalui barrel — gunakan modul `src/lib/db/*` tertentu secara langsung. - **Penaipan entiti DB (#3512)**: fungsi yang menulis atau membaca bentuk baris jadual DB hendaklah menerima/mengembalikan antara muka TS bernama yang mencerminkan lajur jadual tersebut secara 1:1, bukannya `any` atau jenis awanama sebaris pada titik panggilan. Letakkan antara muka bersebelahan dengan fungsi (cth. `export interface UsageEntry` dalam `src/lib/usage/usageHistory.ts` di atas `saveRequestUsage`), kekalkan setiap medan sebagai pilihan/boleh batal apabila penulis yang berbeza mengisi baris secara berperingkat, dan utamakan `unknown` berbanding `any` untuk medan yang bentuknya berbeza antara pemanggil (didokumentasikan pada medan tersebut, cth. `UsageEntry.tokens` menerima penggunaan mentah berbentuk penyedia dan juga bentuk ternormal). Setelah bilangan `any` dalam sesuatu fail mencapai sifar dengan cara ini, tambahkannya pada senarai dibenarkan `check:any-budget:t11` (`scripts/check/check-t11-any-budget.mjs`, `maxAny: 0`) supaya keadaan ini tidak merosot. Ini ialah konvensyen peringkat pertama — kerja pembersihan "tiada `any` awanama" yang lebih menyeluruh dilakukan secara berulang di seluruh pangkalan kod yang selebihnya. - **Ralat**: gunakan try/catch dengan jenis ralat khusus, dan log dengan konteks pino. Jangan sesekali mengabaikan ralat secara senyap dalam aliran SSE; gunakan isyarat pembatalan untuk pembersihan. - **Keselamatan**: jangan sesekali gunakan `eval()` / `new Function()` / eval tersirat. Sahkan semua input dengan Zod. Sulitkan bukti kelayakan semasa disimpan (AES-256-GCM). Pastikan senarai sekatan `src/shared/constants/upstreamHeaders.ts` selaras dengan lapisan sanitasi/pengesahan. - **Komit**: Conventional Commits — `feat(scope): subject`. Skop yang dibenarkan: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`. - **Cabang**: awalan `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`. Jangan sesekali membuat komit secara langsung kepada `main`. - **Husky**: prakomit menjalankan `lint-staged` + `check:docs-sync` + `check:any-budget:t11`; pratujah menjalankan `check:any-budget:t11` + `check:tracked-artifacts` (semakan pantas; tidak termasuk `test:unit`). --- ## 12. Peraturan Tegas (daripada CLAUDE.md) 1. Jangan sekali-kali melakukan commit terhadap rahsia atau kelayakan. 2. Jangan sekali-kali menggunakan import barrel — gunakan modul `src/lib/db/*` tertentu secara langsung. 3. Jangan sekali-kali menggunakan `eval()` / `new Function()` / eval tersirat. 4. Jangan sekali-kali melakukan commit secara langsung ke `main`. 5. Jangan sekali-kali menulis SQL mentah dalam laluan — sentiasa gunakan modul `src/lib/db/`. 6. Jangan sekali-kali mengabaikan ralat secara senyap dalam strim SSE. 7. Sentiasa sahkan input dengan skema Zod. 8. Sentiasa sertakan ujian apabila mengubah kod produksi. 9. Liputan mesti kekal ≥ 60% (pernyataan, baris, fungsi, cabang). --- ## 13. Lihat Juga - [ARCHITECTURE.md](./ARCHITECTURE.md) — seni bina aras tinggi dan tanggungjawab modul. - [API_REFERENCE.md](../reference/API_REFERENCE.md) — rujukan API awam + pengurusan. - [FEATURES.md](../guides/FEATURES.md) — matriks ciri dan sorotan versi. - [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — penerangan mendalam tentang pemutus litar, tempoh bertenang dan penguncian. - [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — pemarkahan dan strategi Auto Combo. - [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — katalog penuh alat MCP + pengangkutan. - [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — kemahiran dan penemuan protokol A2A. - [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — pemampatan RTK + Caveman. - [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — penyepaduan CLI. - [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (jika tersedia), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — sasaran penggunaan. - [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — isu operasi lazim. - [CONTRIBUTING.md](../../CONTRIBUTING.md) — aliran kerja penyumbang. - [CLAUDE.md](../../CLAUDE.md) — peraturan repositori untuk Claude Code (sumber rujukan utama bagi kebanyakan konvensyen di atas). - [AGENTS.md](../../AGENTS.md) — rujukan seni bina yang lebih mendalam untuk ejen.