OmniRoute/docs/i18n/ms/CLAUDE.md

# CLAUDE.md (Bahasa Melayu)

🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [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) · 🇳🇱 [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)

---

Fail ini memberikan panduan kepada Claude Code (claude.ai/code) apabila bekerja dengan kod dalam repositori ini.

## Permulaan Pantas

```bash
npm install                    # Pasang deps (auto-generate .env dari .env.example)
npm run dev                    # Pelayan dev di http://localhost:20128
npm run build                  # Pembinaan pengeluaran (Next.js 16 standalone)
npm run lint                   # ESLint (0 ralat dijangka; amaran adalah sedia ada)
npm run typecheck:core         # Semakan TypeScript (seharusnya bersih)
npm run typecheck:noimplicit:core  # Semakan ketat (tiada implicit any)
npm run test:coverage          # Ujian unit + pintu liputan (75/75/75/70 — kenyataan/garis/fungsi/cabang)
npm run check                  # lint + ujian digabungkan
npm run check:cycles           # Mengesan kebergantungan bulat
```

### Menjalankan Ujian

```bash
# Fail ujian tunggal (penjalur ujian asli Node.js — kebanyakan ujian)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (pelayan MCP, autoCombo, cache)
npm run test:vitest

# Semua suite
npm run test:all
```

Untuk matriks ujian penuh, lihat `CONTRIBUTING.md` → "Menjalankan Ujian". Untuk seni bina mendalam, lihat `AGENTS.md`.

---

## Projek Secara Ringkas

**OmniRoute** — proksi/router AI yang bersatu. Satu titik akhir, 160+ penyedia LLM, auto-fallback.

| Lapisan       | Lokasi                  | Tujuan                                                               |
| ------------- | ----------------------- | -------------------------------------------------------------------- |
| API Routes    | `src/app/api/v1/`       | Penghala Aplikasi Next.js — titik masuk                              |
| Handlers      | `open-sse/handlers/`    | Pemprosesan permintaan (chat, embeddings, dll)                       |
| Executors     | `open-sse/executors/`   | Penghantaran HTTP khusus penyedia                                    |
| Translators   | `open-sse/translator/`  | Penukaran format (OpenAI↔Claude↔Gemini)                              |
| Transformer   | `open-sse/transformer/` | API Respons ↔ Penyelesaian Chat                                      |
| Services      | `open-sse/services/`    | Penghalaan combo, had kadar, caching, dll                            |
| Database      | `src/lib/db/`           | Modul domain SQLite (45+ fail, 55 migrasi)                           |
| Domain/Policy | `src/domain/`           | Enjin dasar, peraturan kos, logik fallback                           |
| MCP Server    | `open-sse/mcp-server/`  | 37 alat (30 asas + 3 memori + 4 kemahiran), 3 pengangkutan, ~13 skop |
| A2A Server    | `src/lib/a2a/`          | Protokol agen JSON-RPC 2.0                                           |
| Skills        | `src/lib/skills/`       | Rangka kerja kemahiran yang boleh diperluas                          |
| Memory        | `src/lib/memory/`       | Memori perbualan yang berterusan                                     |

Monorepo: `src/` (aplikasi Next.js 16), `open-sse/` (workspace enjin streaming), `electron/` (aplikasi desktop), `tests/`, `bin/` (titik masuk CLI).

---

## Saluran Permintaan

```
Klien → /v1/chat/completions (laluan Next.js)
  → CORS → pengesahan Zod → auth? → semakan polisi → pengawal suntikan prompt
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → semakan cache → had kadar → penghalaan combo?
      → resolveComboTargets() → handleSingleModel() bagi setiap sasaran
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → terjemahan respons → aliran SSE atau JSON
    → Jika API Respons: responsesTransformer.ts TransformStream
```

Laluan API mengikuti pola yang konsisten: `Laluan → CORS preflight → pengesahan badan Zod → Auth pilihan (extractApiKey/isValidApiKey) → penguatkuasaan polisi kunci API → Delegasi Pengendali (open-sse)`. Tiada middleware global Next.js — pemotongan adalah khusus untuk laluan.

**Penghalaan combo** (`open-sse/services/combo.ts`): 14 strategi (keutamaan, berat, isi dahulu, bulatan, P2C, rawak, paling kurang digunakan, dioptimumkan kos, sedar reset, rawak ketat, auto, lkgp, dioptimumkan konteks, relay konteks). Setiap sasaran memanggil `handleSingleModel()` yang membungkus `handleChatCore()` dengan pengendalian ralat per-sasaran dan semakan pemutus litar. Lihat `docs/routing/AUTO-COMBO.md` untuk penilaian Auto-Combo 9 faktor dan `docs/architecture/RESILIENCE_GUIDE.md` untuk 3 lapisan ketahanan.

---

## Keadaan Runtime Ketahanan

OmniRoute mempunyai tiga mekanisme kegagalan sementara yang berkaitan tetapi berbeza. Pastikan skop mereka terpisah semasa menyahpepijat tingkah laku penghalaan. Lihat
[rajah ketahanan 3-lapisan](./docs/diagrams/exported/resilience-3layers.svg)
(sumber: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
untuk peta ringkas.

### Pemutus Litar Penyedia

**Skop**: keseluruhan penyedia, contohnya `glm`, `openai`, `anthropic`.

**Tujuan**: menghentikan penghantaran trafik kepada penyedia yang berulang kali gagal di
peringkat upstream/perkhidmatan, supaya satu penyedia yang tidak sihat tidak melambatkan setiap permintaan.

**Pelaksanaan**:

- Kelas teras: `src/shared/utils/circuitBreaker.ts`
- Penghantaran pintu/pendawaian pelaksanaan: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- API status runtime: `src/app/api/monitoring/health/route.ts`
- Pembungkus bersama: `open-sse/services/accountFallback.ts`
- Jadual keadaan yang dipersisten: `domain_circuit_breakers`

**Keadaan**:

- `CLOSED`: trafik normal dibenarkan.
- `OPEN`: penyedia disekat sementara; pemanggil mendapat respons pemutus-litar-penyedia-terbuka
  atau penghalaan combo melangkau ke sasaran lain.
- `HALF_OPEN`: masa tamat reset telah berlalu; benarkan permintaan probe. Kejayaan menutup
  pemutus, kegagalan membukanya semula.

**Tetapan Lalai** (`open-sse/config/constants.ts`):

- Penyedia OAuth: ambang `3`, masa tamat reset `60s`.
- Penyedia kunci API: ambang `5`, masa tamat reset `30s`.
- Penyedia tempatan: ambang `2`, masa tamat reset `15s`.

Hanya status kegagalan peringkat penyedia yang seharusnya mencetuskan pemutus penyedia:

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

Jangan mencetuskan pemutus penyedia keseluruhan untuk kesalahan akaun/kunci/model normal seperti kebanyakan
kes `401`, `403`, atau `429`. Kes-kes tersebut biasanya berkaitan dengan cooldown sambungan atau penguncian model. Penyedia kunci API generik `403` seharusnya boleh dipulihkan kecuali ia diklasifikasikan
sebagai kesalahan penyedia/akaun terminal.

Pemutus menggunakan pemulihan malas, bukan pemasa latar belakang. Apabila `OPEN` tamat, bacaan seperti `getStatus()`, `canExecute()`, dan `getRetryAfterMs()` menyegarkan keadaan kepada
`HALF_OPEN`, supaya papan pemuka dan pembina calon combo tidak terus mengecualikan penyedia yang tamat selama-lamanya.

### Cooldown Sambungan

**Skop**: satu sambungan penyedia/akaun/kunci.

**Tujuan**: melangkau sementara satu kunci/akaun yang buruk sambil membenarkan sambungan lain untuk
penyedia yang sama terus memenuhi permintaan.

**Pelaksanaan**:

- Laluan tulis/kemas kini: `src/sse/services/auth.ts::markAccountUnavailable()`
- Pemilihan/pengasingan akaun: `src/sse/services/auth.ts::getProviderCredentials...`
- Pengiraan cooldown: `open-sse/services/accountFallback.ts::checkFallbackError()`
- Tetapan: `src/lib/resilience/settings.ts`

Medan penting pada sambungan penyedia:

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

Semasa pemilihan akaun, sambungan dilangkau sementara:

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

Cooldown juga malas: apabila `rateLimitedUntil` berada di masa lalu, sambungan menjadi
layak semula. Pada penggunaan yang berjaya, `clearAccountError()` membersihkan `testStatus`,
`rateLimitedUntil`, medan ralat, dan `backoffLevel`.

Tingkah laku cooldown sambungan lalai:

- Cooldown asas OAuth: `5s`.
- Cooldown asas kunci API: `3s`.
- Kunci API `429` seharusnya lebih mengutamakan petunjuk retry upstream (`Retry-After`, header reset, atau
  teks reset yang boleh dibaca) apabila tersedia.
- Kegagalan boleh dipulihkan yang berulang menggunakan backoff eksponen:

```ts
baseCooldownMs * 2 ** failureIndex;
```

Pengawal anti-thundering-herd menghalang kegagalan serentak pada sambungan yang sama daripada
berulang kali melanjutkan cooldown atau meningkatkan `backoffLevel` dua kali ganda.

Keadaan terminal bukan cooldown. `banned`, `expired`, dan `credits_exhausted` adalah
dimaksudkan untuk kekal tidak tersedia sehingga kelayakan/tetapan berubah atau seorang pengendali menetapkannya semula. Jangan menulis semula keadaan terminal dengan keadaan cooldown sementara.

### Penguncian Model

**Skop**: penyedia + sambungan + model.

**Tujuan**: mengelakkan melumpuhkan keseluruhan sambungan apabila hanya satu model tidak tersedia atau
had kuota untuk sambungan tersebut.

Contoh:

- Penyedia kuota per-model yang mengembalikan `429`.
- Penyedia tempatan yang mengembalikan `404` untuk satu model yang hilang.
- Kegagalan kebenaran mod/model khusus penyedia seperti mod Grok yang dipilih.

Penguncian model hidup dalam `open-sse/services/accountFallback.ts` dan membenarkan sambungan yang sama terus memenuhi model lain.

### Panduan Menyahpepijat

- Jika semua kunci untuk penyedia dilangkau, periksa kedua-dua keadaan pemutus penyedia dan setiap
  `rateLimitedUntil`/`testStatus` sambungan.
- Jika penyedia kelihatan kekal dikecualikan selepas tetingkap reset, semak sama ada kod
  membaca `state` mentah dan bukannya menggunakan `getStatus()`/`canExecute()`.
- Jika satu kunci penyedia gagal tetapi yang lain seharusnya berfungsi, lebih baik menggunakan cooldown sambungan daripada
  pemutus penyedia.
- Jika hanya satu model gagal, lebih baik menggunakan penguncian model daripada cooldown sambungan.
- Jika satu keadaan seharusnya pulih sendiri, ia seharusnya mempunyai cap waktu/reset masa depan dan laluan bacaan yang menyegarkan keadaan yang tamat. Status kekal memerlukan perubahan kelayakan
  atau konfigurasi secara manual.

## Konvensyen Utama

### Gaya Kod

- **2 ruang**, titik koma, petikan berganda, lebar 100 aksara, koma akhir es5 (dikuatkuasakan oleh lint-staged melalui Prettier)
- **Import**: luaran → dalaman (`@/`, `@omniroute/open-sse`) → relatif
- **Penamaan**: fail=camelCase/kebab, komponen=PascalCase, pemalar=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = ralat di mana-mana; `no-explicit-any` = amaran dalam `open-sse/` dan `tests/`
- **TypeScript**: `strict: false`, sasaran ES2022, modul esnext, resolusi bundler. Utamakan jenis eksplisit.

### Pangkalan Data

- **Sentiasa** melalui modul domain `src/lib/db/` — **jangan sekali-kali** menulis SQL mentah dalam laluan atau pengendali
- **Jangan sekali-kali** menambah logik ke dalam `src/lib/localDb.ts` (lapisan re-export sahaja)
- **Jangan sekali-kali** mengimport dari `localDb.ts` — import modul `db/` tertentu sebaliknya
- DB singleton: `getDbInstance()` dari `src/lib/db/core.ts` (penulisan jurnal WAL)
- Migrasi: `src/lib/db/migrations/` — fail SQL versi, idempotent, dijalankan dalam transaksi

### Pengendalian Ralat

- try/catch dengan jenis ralat tertentu, log dengan konteks pino
- Jangan sekali-kali menelan ralat dalam aliran SSE — gunakan isyarat abort untuk pembersihan
- Kembalikan kod status HTTP yang betul (4xx/5xx)

### Keselamatan

- **Jangan sekali-kali** menggunakan `eval()`, `new Function()`, atau eval tersirat
- Sahkan semua input dengan skema Zod
- Enkripsi kredensial dalam keadaan rehat (AES-256-GCM)
- Senarai denylist header upstream: `src/shared/constants/upstreamHeaders.ts` — pastikan sanitasi, skema Zod, dan ujian unit selaras semasa mengedit
- **Kredensial upstream awam** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + kunci Web Firebase yang diekstrak dari CLI awam): **HARUS** disematkan melalui `resolvePublicCred()` dari `open-sse/utils/publicCreds.ts` — **jangan sekali-kali** sebagai literal string. Lihat `docs/security/PUBLIC_CREDS.md` untuk pola yang wajib.
- **Respons ralat** (HTTP / SSE / pengendali executor / MCP): **HARUS** melalui `buildErrorBody()` atau `sanitizeErrorMessage()` dari `open-sse/utils/error.ts` — **jangan sekali-kali** meletakkan `err.stack` atau `err.message` mentah dalam badan respons. Lihat `docs/security/ERROR_SANITIZATION.md`.
- **Perintah shell yang dibina dari pembolehubah**: apabila memanggil `exec()`/`spawn()` dengan skrip yang memerlukan nilai runtime, hantarkan melalui pilihan `env` (automatik di-escape shell) — **jangan sekali-kali** interpolasi string laluan tidak dipercayai/luaran ke dalam badan skrip. Rujukan: `src/mitm/cert/install.ts::updateNssDatabases`.
- **Perpustakaan yang selamat secara lalai** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): utamakan Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink berbanding pelaksanaan khusus apabila menambah permukaan sensitif keselamatan yang baru.

---

## Senario Pengubahsuaian Biasa

### Menambah Penyedia Baru

1. Daftar dalam `src/shared/constants/providers.ts` (disahkan Zod semasa memuat)
2. Tambah executor dalam `open-sse/executors/` jika logik khusus diperlukan (lanjutan `BaseExecutor`)
3. Tambah penterjemah dalam `open-sse/translator/` jika format bukan OpenAI
4. Tambah konfigurasi OAuth dalam `src/lib/oauth/constants/oauth.ts` jika berasaskan OAuth — jika CLI upstream menghantar client_id/secret awam, sematkan melalui `resolvePublicCred()` (lihat `docs/security/PUBLIC_CREDS.md`), **jangan sekali-kali** sebagai literal
5. Daftar model dalam `open-sse/config/providerRegistry.ts`
6. Tulis ujian dalam `tests/unit/` (sertakan pengesahan bentuk publicCreds jika anda menambah default yang disematkan baru)

### Menambah Laluan API Baru

1. Buat direktori di bawah `src/app/api/v1/your-route/`
2. Buat `route.ts` dengan pengendali `GET`/`POST`
3. Ikuti pola: CORS → pengesahan badan Zod → pengesahan pilihan → delegasi pengendali
4. Pengendali pergi ke dalam `open-sse/handlers/` (import dari situ, bukan dalam talian)
5. Respons ralat menggunakan `buildErrorBody()` / `errorResponse()` dari `open-sse/utils/error.ts` (auto-sanitized — jangan sekali-kali meletakkan `err.stack` atau `err.message` mentah dalam badan). Lihat `docs/security/ERROR_SANITIZATION.md`.
6. Tambah ujian — termasuk sekurang-kurangnya satu pengesahan bahawa respons ralat tidak bocorkan jejak tumpukan (`!body.error.message.includes("at /")`)

### Menambah Modul DB Baru

1. Buat `src/lib/db/yourModule.ts` — import `getDbInstance` dari `./core.ts`
2. Eksport fungsi CRUD untuk jadual domain anda
3. Tambah migrasi dalam `src/lib/db/migrations/` jika jadual baru diperlukan
4. Re-export dari `src/lib/localDb.ts` (tambahkan ke senarai re-export sahaja)
5. Tulis ujian

### Menambah Alat MCP Baru

1. Tambah definisi alat dalam `open-sse/mcp-server/tools/` dengan skema input Zod + pengendali asinkron
2. Daftar dalam set alat (disambungkan oleh `createMcpServer()`)
3. Tugaskan kepada skop yang sesuai
4. Tulis ujian (panggilan alat dicatat ke dalam jadual `mcp_audit`)

### Menambah Kemahiran A2A Baru

1. Buat kemahiran dalam `src/lib/a2a/skills/` (5 sudah ada: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Kemahiran menerima konteks tugas (mesej, metadata) → mengembalikan hasil terstruktur
3. Daftar dalam `A2A_SKILL_HANDLERS` dalam `src/lib/a2a/taskExecution.ts`
4. Dedahkan dalam `src/app/.well-known/agent.json/route.ts` (Kad Ejen)
5. Tulis ujian dalam `tests/unit/`
6. Dokumentasikan dalam jadual kemahiran `docs/frameworks/A2A-SERVER.md`

### Menambah Ejen Cloud Baru

1. Buat kelas ejen dalam `src/lib/cloudAgent/agents/` yang memperluas `CloudAgentBase` (3 sudah ada: codex-cloud, devin, jules)
2. Laksanakan `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
3. Daftar dalam `src/lib/cloudAgent/registry.ts`
4. Tambah pengendalian OAuth/kredensial jika perlu (`src/lib/oauth/providers/`)
5. Ujian + dokumentasikan dalam `docs/frameworks/CLOUD_AGENT.md`

### Menambah Garis Panduan / Eval / Kemahiran / Acara Webhook Baru

- Garis panduan: `src/lib/guardrails/` → dokumen: `docs/security/GUARDRAILS.md`
- Suite Eval: `src/lib/evals/` → dokumen: `docs/frameworks/EVALS.md`
- Kemahiran (sandbox): `src/lib/skills/` → dokumen: `docs/frameworks/SKILLS.md`
- Acara Webhook: `src/lib/webhookDispatcher.ts` → dokumen: `docs/frameworks/WEBHOOKS.md`

## Dokumentasi Rujukan

Untuk sebarang perubahan yang tidak remeh, baca analisis mendalam yang sepadan terlebih dahulu:

| Kawasan                                        | Dokumen                                                           |
| ---------------------------------------------- | ----------------------------------------------------------------- |
| Navigasi repo                                  | `docs/architecture/REPOSITORY_MAP.md`                             |
| Seni bina                                      | `docs/architecture/ARCHITECTURE.md`                               |
| Rujukan kejuruteraan                           | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| Auto-Combo (penilaian 9 faktor, 14 strategi)   | `docs/routing/AUTO-COMBO.md`                                      |
| Ketahanan (3 mekanisme)                        | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| Ulangan penaakulan                             | `docs/routing/REASONING_REPLAY.md`                                |
| Rangka kerja kemahiran                         | `docs/frameworks/SKILLS.md`                                       |
| Sistem memori (FTS5 + Qdrant)                  | `docs/frameworks/MEMORY.md`                                       |
| Ejen awan                                      | `docs/frameworks/CLOUD_AGENT.md`                                  |
| Garis panduan (PII / suntikan / visi)          | `docs/security/GUARDRAILS.md`                                     |
| Kelayakan awam hulu (Gemini/dll.)              | `docs/security/PUBLIC_CREDS.md`                                   |
| Pembersihan mesej ralat                        | `docs/security/ERROR_SANITIZATION.md`                             |
| Penilaian                                      | `docs/frameworks/EVALS.md`                                        |
| Pematuhan / audit                              | `docs/security/COMPLIANCE.md`                                     |
| Webhook                                        | `docs/frameworks/WEBHOOKS.md`                                     |
| Saluran pengesahan                             | `docs/architecture/AUTHZ_GUIDE.md`                                |
| Stealth (TLS / cap jari)                       | `docs/security/STEALTH_GUIDE.md`                                  |
| Protokol ejen (A2A / ACP / Awan)               | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| Pelayan MCP                                    | `docs/frameworks/MCP-SERVER.md`                                   |
| Pelayan A2A                                    | `docs/frameworks/A2A-SERVER.md`                                   |
| Rujukan API + OpenAPI                          | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| Katalog penyedia (dihasilkan secara automatik) | `docs/reference/PROVIDER_REFERENCE.md`                            |
| Aliran pelepasan                               | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## Ujian

| Apa                     | Perintah                                                               |
| ----------------------- | ---------------------------------------------------------------------- |
| Ujian unit              | `npm run test:unit`                                                    |
| Fail tunggal            | `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`                                           |
| Ekosistem               | `npm run test:ecosystem`                                               |
| Pintu liputan           | `npm run test:coverage` (75/75/75/70 — pernyataan/garis/fungsi/cabang) |
| Laporan liputan         | `npm run coverage:report`                                              |

**Peraturan PR**: Jika anda mengubah kod pengeluaran dalam `src/`, `open-sse/`, `electron/`, atau `bin/`, anda mesti menyertakan atau mengemas kini ujian dalam PR yang sama.

**Keutamaan lapisan ujian**: unit pertama → integrasi (multi-modul atau keadaan DB) → e2e (UI/aliran sahaja). Kodkan pengulangan pepijat sebagai ujian automatik sebelum atau bersama dengan pembetulan.

**Dasar liputan Copilot**: Apabila PR mengubah kod pengeluaran dan liputan berada di bawah 75% (pernyataan/garis/fungsi) atau 70% (cabang), jangan hanya laporkan — tambah atau kemas kini ujian, jalankan semula pintu liputan, kemudian minta pengesahan. Sertakan perintah yang dijalankan, fail ujian yang diubah, dan hasil liputan akhir dalam laporan PR.

---

## Aliran Kerja Git

```bash
# Jangan pernah komit terus ke main
git checkout -b feat/your-feature
git commit -m "feat: terangkan perubahan anda"
git push -u origin feat/your-feature
```

**Awalan cawangan**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**Format komit** (Komit Konvensional): `feat(db): tambah pemutus litar` — skop: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Pautan Husky**:

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

---

## Persekitaran

- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, Modul ES
- **TypeScript**: 5.9+, sasaran ES2022, modul esnext, resolusi bundler
- **Alias laluan**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **Port lalai**: 20128 (API + papan pemuka pada port yang sama)
- **Direktori data**: `DATA_DIR` env var, lalai kepada `~/.omniroute/`
- **Variabel env utama**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- Persediaan: `cp .env.example .env` kemudian hasilkan `JWT_SECRET` (`openssl rand -base64 48`) dan `API_KEY_SECRET` (`openssl rand -hex 32`)

---

## Peraturan Ketat

1. Jangan pernah komit rahsia atau kelayakan
2. Jangan pernah tambah logik ke `localDb.ts`
3. Jangan pernah gunakan `eval()` / `new Function()` / eval tersirat
4. Jangan pernah komit terus ke `main`
5. Jangan pernah menulis SQL mentah dalam laluan — gunakan modul `src/lib/db/`
6. Jangan pernah menelan ralat secara senyap dalam aliran SSE
7. Sentiasa sahkan input dengan skema Zod
8. Sentiasa sertakan ujian apabila mengubah kod pengeluaran
9. Liputan mesti kekal ≥75% (pernyataan, garis, fungsi) / ≥70% (cabang). Ukuran semasa: ~82%.
10. Jangan pernah mengabaikan pautan Husky (`--no-verify`, `--no-gpg-sign`) tanpa kelulusan pengendali yang jelas.
11. Jangan pernah menyematkan client_id/secret OAuth awam atau kunci Web Firebase sebagai literal rentetan — sentiasa melalui `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). Lihat `docs/security/PUBLIC_CREDS.md`.
12. Jangan pernah mengembalikan `err.stack` / `err.message` mentah dalam HTTP / SSE / respons pelaksana — sentiasa lalui `buildErrorBody()` atau `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). Lihat `docs/security/ERROR_SANITIZATION.md`.
13. Jangan pernah interpolasi rentetan laluan luaran atau nilai runtime ke dalam skrip shell yang dihantar kepada `exec()`/`spawn()` — hantarkan melalui pilihan `env` sebaliknya. Rujukan: `src/mitm/cert/install.ts::updateNssDatabases`.
14. Jangan pernah menolak amaran CodeQL / Pengimbasan Rahsia tanpa (a) terlebih dahulu memeriksa dokumen pola di atas untuk melihat jika pembantu terpakai, dan (b) merekodkan justifikasi teknikal dalam komen penolakan. Preseden: `js/stack-trace-exposure` yang dibangkitkan pada callsites yang sudah lalui `sanitizeErrorMessage()` adalah batasan CodeQL yang diketahui (pembersih khusus tidak dikenali) — tolak sebagai `false positive` merujuk kepada `docs/security/ERROR_SANITIZATION.md`.
15. Jangan pernah mendedahkan laluan yang memulakan proses anak (`/api/mcp/`, `/api/cli-tools/runtime/`) tanpa klasifikasi `isLocalOnlyPath()` dalam `src/server/authz/routeGuard.ts`. Penguatkuasaan loopback berlaku tanpa syarat sebelum sebarang semakan pengesahan — JWT yang bocor melalui terowong tidak boleh mencetuskan pemulaan proses. Lihat `docs/security/ROUTE_GUARD_TIERS.md`.
16. Jangan sekali-kali sertakan trailer `Co-Authored-By` yang mengkreditkan pembantu AI, LLM, atau akaun automasi (cth. nama yang mengandungi "Claude", "GPT", "Copilot", "Bot"; emel di `anthropic.com` / `openai.com` / alamat `noreply.github.com` milik bot). Trailer sebegitu mengarahkan atribusi commit kepada akaun bot di GitHub, menyembunyikan penulis sebenar (`diegosouzapw`) dalam sejarah PR. Penyumbang manusia — termasuk penulis PR upstream dan pelapor issue yang diport ke OmniRoute — BOLEH dan SEPATUTNYA dikreditkan dengan trailer standard `Co-authored-by: Name <email>`; aliran kerja upstream-port (`/port-upstream-features`, `/port-upstream-issues`) bergantung pada ini.