wehub/diegosouzapw--omniroute
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
diegosouzapw--omniroute/docs/i18n/ms/CLAUDE.md
T
wehub-resource-sync d8dcd5f6d1 chore: import upstream snapshot with attribution
2026-07-13 13:39:12 +08:00

26 KiB
Raw Permalink Blame History

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

# 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.
Reference in New Issue View Git Blame Copy Permalink