OmniRoute/docs/i18n/ms/CLAUDE.md

CLAUDE.md (Bahasa Melayu)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

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

Permulaan Pantas

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

# 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, 329 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/	110 top-level SQLite domain modules, 130 migrations
Domain/Policy	src/domain/	Enjin dasar, peraturan kos, logik fallback
MCP Server	open-sse/mcp-server/	107 unique tools, 3 transports (stdio / SSE / Streamable HTTP), 32 scopes
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.

Combo routing (open-sse/services/combo.ts): 19 public strategies (priority, weighted, fill-first, round-robin, p2c, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, cache-optimized, context-relay, fusion, pipeline). Each target calls handleSingleModel(), which wraps handleChatCore() with per-target error handling and circuit-breaker checks. See docs/routing/AUTO-COMBO.md for the 13-factor Auto-Combo scoring and docs/architecture/RESILIENCE_GUIDE.md for the 3 resilience layers.

---

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 (sumber: 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:

(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:

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

Semasa pemilihan akaun, sambungan dilangkau sementara:

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:

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): 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 (13-factor scoring, 19 public strategies)	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

# 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.