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

28 KiB
Raw Permalink Blame History

CLAUDE.md (Filipino)

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

This file ay nagbibigay ng gabay sa Claude Code (claude.ai/code) kapag nagtatrabaho sa code sa repository na ito.

Mabilis na Pagsisimula

npm install                    # Mag-install ng deps (auto-generates .env mula sa .env.example)
npm run dev                    # Dev server sa http://localhost:20128
npm run build                  # Production build (Next.js 16 standalone)
npm run lint                   # ESLint (0 errors ang inaasahan; warnings ay pre-existing)
npm run typecheck:core         # TypeScript check (dapat ay malinis)
npm run typecheck:noimplicit:core  # Mahigpit na check (walang implicit any)
npm run test:coverage          # Unit tests + coverage gate (75/75/75/70 — statements/lines/functions/branches)
npm run check                  # lint + test na pinagsama
npm run check:cycles           # Tukuyin ang circular dependencies

Pagsasagawa ng Mga Pagsubok

# Isang test file (Node.js native test runner — karamihan sa mga pagsubok)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Lahat ng suites
npm run test:all

Para sa buong test matrix, tingnan ang CONTRIBUTING.md → "Pagsasagawa ng Mga Pagsubok". Para sa malalim na arkitektura, tingnan ang AGENTS.md.

Proyekto sa Isang Sulyap

OmniRoute — pinagsamang AI proxy/router. Isang endpoint, 160+ LLM providers, auto-fallback.

Layer Lokasyon Layunin
API Routes src/app/api/v1/ Next.js App Router — mga entry point
Handlers open-sse/handlers/ Pagproseso ng request (chat, embeddings, atbp)
Executors open-sse/executors/ Provider-specific HTTP dispatch
Translators open-sse/translator/ Format conversion (OpenAI↔Claude↔Gemini)
Transformer open-sse/transformer/ Responses API ↔ Chat Completions
Services open-sse/services/ Combo routing, rate limits, caching, atbp
Database src/lib/db/ SQLite domain modules (45+ files, 55 migrations)
Domain/Policy src/domain/ Policy engine, cost rules, fallback logic
MCP Server open-sse/mcp-server/ 37 tools (30 base + 3 memory + 4 skills), 3 transports, ~13 scopes
A2A Server src/lib/a2a/ JSON-RPC 2.0 agent protocol
Skills src/lib/skills/ Extensible skill framework
Memory src/lib/memory/ Persistent conversational memory

Monorepo: src/ (Next.js 16 app), open-sse/ (streaming engine workspace), electron/ (desktop app), tests/, bin/ (CLI entry point).

Request Pipeline

Client → /v1/chat/completions (Next.js route)
  → CORS → Zod validation → auth? → policy check → prompt injection guard
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → cache check → rate limit → combo routing?
      → resolveComboTargets() → handleSingleModel() per target
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → response translation → SSE stream or JSON
    → If Responses API: responsesTransformer.ts TransformStream

Ang mga API route ay sumusunod sa isang pare-parehong pattern: Route → CORS preflight → Zod body validation → Opsyonal na auth (extractApiKey/isValidApiKey) → pagpapatupad ng patakaran sa API key → Delegasyon ng Handler (open-sse). Walang global na Next.js middleware — ang interception ay tiyak sa ruta.

Combo routing (open-sse/services/combo.ts): 14 na estratehiya (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized, context-relay). Bawat target ay tumatawag sa handleSingleModel() na nagbabalot sa handleChatCore() na may per-target na error handling at circuit breaker checks. Tingnan ang docs/routing/AUTO-COMBO.md para sa 9-factor Auto-Combo scoring at docs/architecture/RESILIENCE_GUIDE.md para sa 3 resilience layers.

Resilience Runtime State

Ang OmniRoute ay may tatlong kaugnay ngunit magkakaibang mekanismo ng pansamantalang pagkabigo. Panatilihing hiwalay ang kanilang saklaw kapag nag-debug ng pag-uugali ng routing. Tingnan ang 3-layer resilience diagram (source: docs/diagrams/resilience-3layers.mmd) para sa isang mabilis na mapa.

Provider Circuit Breaker

Saklaw: buong provider, e.g. glm, openai, anthropic.

Layunin: itigil ang pagpapadala ng trapiko sa isang provider na paulit-ulit na bumabagsak sa upstream/service level, upang ang isang hindi malusog na provider ay hindi nagpapabagal sa bawat request.

Implementasyon:

  • Core class: src/shared/utils/circuitBreaker.ts
  • Chat gate/execution wiring: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • Runtime status API: src/app/api/monitoring/health/route.ts
  • Shared wrappers: open-sse/services/accountFallback.ts
  • Persisted state table: domain_circuit_breakers

Mga Estado:

  • CLOSED: pinapayagan ang normal na trapiko.
  • OPEN: pansamantalang naka-block ang provider; ang mga tumatawag ay nakakakuha ng provider-circuit-open na tugon o ang combo routing ay lumilipat sa ibang target.
  • HALF_OPEN: ang reset timeout ay lumipas na; payagan ang isang probe request. Ang tagumpay ay nagsasara sa breaker, ang pagkabigo ay muling nagbubukas dito.

Mga Default (open-sse/config/constants.ts):

  • OAuth providers: threshold 3, reset timeout 60s.
  • API-key providers: threshold 5, reset timeout 30s.
  • Local providers: threshold 2, reset timeout 15s.

Tanging mga status ng pagkabigo sa antas ng provider ang dapat mag-trigger sa provider breaker:

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

Huwag i-trigger ang buong-provider breaker para sa normal na account/key/model errors tulad ng karamihan 401, 403, o 429 na mga kaso. Karaniwan silang nabibilang sa connection cooldown o model lockout. Ang isang generic na API-key provider 403 ay dapat na ma-recover maliban kung ito ay nakategorya bilang isang terminal provider/account error.

Ang breaker ay gumagamit ng lazy recovery, hindi isang background timer. Kapag ang OPEN ay nag-expire, ang mga pagbabasa tulad ng getStatus(), canExecute(), at getRetryAfterMs() ay nag-refresh ng estado sa HALF_OPEN, upang ang mga dashboard at combo candidate builders ay hindi patuloy na nag-eexclude ng isang nag-expire na provider magpakailanman.

Connection Cooldown

Saklaw: isang provider connection/account/key.

Layunin: pansamantalang laktawan ang isang masamang key/account habang pinapayagan ang iba pang mga koneksyon para sa parehong provider na ipagpatuloy ang pagseserbisyo ng mga request.

Implementasyon:

  • Write/update path: src/sse/services/auth.ts::markAccountUnavailable()
  • Account selection/filtering: src/sse/services/auth.ts::getProviderCredentials...
  • Cooldown calculation: open-sse/services/accountFallback.ts::checkFallbackError()
  • Settings: src/lib/resilience/settings.ts

Mahalagang mga field sa provider connections:

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

Sa panahon ng pagpili ng account, isang koneksyon ang nilaktawan habang:

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

Ang mga cooldown ay lazy din: kapag ang rateLimitedUntil ay nasa nakaraan, ang koneksyon ay nagiging eligible muli. Sa matagumpay na paggamit, clearAccountError() ay naglilinis ng testStatus, rateLimitedUntil, mga field ng error, at backoffLevel.

Default na pag-uugali ng connection cooldown:

  • OAuth base cooldown: 5s.
  • API-key base cooldown: 3s.
  • API-key 429 ay dapat mas gustuhin ang upstream retry hints (Retry-After, reset headers, o parseable reset text) kapag available.
  • Ang mga paulit-ulit na ma-recover na pagkabigo ay gumagamit ng exponential backoff:
baseCooldownMs * 2 ** failureIndex;

Ang anti-thundering-herd guard ay pumipigil sa sabay-sabay na pagkabigo sa parehong koneksyon mula sa paulit-ulit na pagpapahaba ng cooldown o double-incrementing backoffLevel.

Ang mga terminal states ay hindi mga cooldown. Ang banned, expired, at credits_exhausted ay nakatakdang manatiling unavailable hanggang sa magbago ang mga kredensyal/settings o i-reset ito ng isang operator. Huwag i-overwrite ang mga terminal states gamit ang pansamantalang cooldown state.

Model Lockout

Saklaw: provider + connection + model.

Layunin: iwasan ang pag-disable ng isang buong koneksyon kapag isa lamang na modelo ang hindi available o quota-limited para sa koneksyong iyon.

Mga halimbawa:

  • Per-model quota providers na nagbabalik ng 429.
  • Local providers na nagbabalik ng 404 para sa isang nawawalang modelo.
  • Mga pagkabigo sa pahintulot ng mode/model na tiyak sa provider tulad ng napiling Grok modes.

Ang model lockout ay nasa open-sse/services/accountFallback.ts at nagpapahintulot sa parehong koneksyon na ipagpatuloy ang pagseserbisyo ng iba pang mga modelo.

Debugging Guidance

  • Kung lahat ng keys para sa isang provider ay nilaktawan, suriin ang parehong estado ng provider breaker at bawat koneksyon rateLimitedUntil/testStatus.
  • Kung ang isang provider ay tila permanenteng na-exclude pagkatapos ng reset window, suriin kung ang code ay nagbabasa ng raw state sa halip na gumagamit ng getStatus()/canExecute().
  • Kung ang isang provider key ay nabigo ngunit ang iba ay dapat gumana, mas gustuhin ang connection cooldown kaysa provider breaker.
  • Kung isa lamang na modelo ang nabigo, mas gustuhin ang model lockout kaysa sa connection cooldown.
  • Kung ang isang estado ay dapat na self-recover, dapat itong magkaroon ng hinaharap na timestamp/reset timeout at isang read path na nag-refresh ng expired state. Ang mga permanenteng status ay nangangailangan ng manu-manong pagbabago ng kredensyal o config.

Mga Pangunahing K convention

Estilo ng Code

  • 2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas (ipinapatupad ng lint-staged sa pamamagitan ng Prettier)
  • Imports: external → internal (@/, @omniroute/open-sse) → relative
  • Pangalan: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = error sa lahat ng dako; no-explicit-any = warn sa open-sse/ at tests/
  • TypeScript: strict: false, target ES2022, module esnext, resolution bundler. Mas gusto ang mga explicit types.

Database

  • Laging dumaan sa src/lib/db/ domain modules — huwag magsulat ng raw SQL sa routes o handlers
  • Huwag magdagdag ng logic sa src/lib/localDb.ts (re-export layer lamang)
  • Huwag barrel-import mula sa localDb.ts — mag-import ng tiyak na db/ modules sa halip
  • DB singleton: getDbInstance() mula sa src/lib/db/core.ts (WAL journaling)
  • Migrations: src/lib/db/migrations/ — versioned SQL files, idempotent, tumakbo sa transactions

Pag-handle ng Error

  • try/catch na may tiyak na uri ng error, log gamit ang pino context
  • Huwag isubo ang mga error sa SSE streams — gumamit ng abort signals para sa cleanup
  • Ibalik ang wastong HTTP status codes (4xx/5xx)

Seguridad

  • Huwag gumamit ng eval(), new Function(), o implied eval
  • I-validate ang lahat ng inputs gamit ang Zod schemas
  • I-encrypt ang mga kredensyal sa rest (AES-256-GCM)
  • Upstream header denylist: src/shared/constants/upstreamHeaders.ts — panatilihing sanitize, Zod schemas, at unit tests na naka-align kapag nag-edit
  • Public upstream credentials (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys na nakuha mula sa public CLIs): DAPAT na i-embed sa pamamagitan ng resolvePublicCred() mula sa open-sse/utils/publicCreds.ts — huwag bilang string literals. Tingnan ang docs/security/PUBLIC_CREDS.md para sa mandatory pattern.
  • Error responses (HTTP / SSE / executor / MCP handler): DAPAT dumaan sa buildErrorBody() o sanitizeErrorMessage() mula sa open-sse/utils/error.ts — huwag ilagay ang raw err.stack o err.message sa isang response body. Tingnan ang docs/security/ERROR_SANITIZATION.md.
  • Shell commands na binuo mula sa mga variable: kapag tinatawag ang exec()/spawn() gamit ang isang script na nangangailangan ng runtime values, ipasa ang mga ito sa pamamagitan ng env option (automatically shell-escaped) — huwag string-interpolate ang hindi mapagkakatiwalaan/external paths sa script body. Reference: src/mitm/cert/install.ts::updateNssDatabases.
  • Secure-by-default libraries (tldrsec/awesome-secure-defaults): mas gusto ang Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink sa mga custom implementations sa tuwing nagdadagdag ng bagong security-sensitive surfaces.

Karaniwang Senaryo ng Pagbabago

Pagdaragdag ng Bagong Provider

  1. Irehistro sa src/shared/constants/providers.ts (Zod-validated sa load)
  2. Magdagdag ng executor sa open-sse/executors/ kung kinakailangan ng custom logic (palawakin ang BaseExecutor)
  3. Magdagdag ng translator sa open-sse/translator/ kung hindi OpenAI format
  4. Magdagdag ng OAuth config sa src/lib/oauth/constants/oauth.ts kung batay sa OAuth — kung ang upstream CLI ay naglalabas ng public client_id/secret, i-embed sa pamamagitan ng resolvePublicCred() (tingnan ang docs/security/PUBLIC_CREDS.md), huwag bilang literal
  5. Irehistro ang mga modelo sa open-sse/config/providerRegistry.ts
  6. Sumulat ng mga tests sa tests/unit/ (isama ang publicCreds shape assertion kung nagdagdag ka ng bagong embedded default)

Pagdaragdag ng Bagong API Route

  1. Lumikha ng directory sa ilalim ng src/app/api/v1/your-route/
  2. Lumikha ng route.ts na may GET/POST handlers
  3. Sundin ang pattern: CORS → Zod body validation → optional auth → handler delegation
  4. Ang handler ay pupunta sa open-sse/handlers/ (mag-import mula doon, hindi inline)
  5. Ang mga error responses ay gumagamit ng buildErrorBody() / errorResponse() mula sa open-sse/utils/error.ts (auto-sanitized — huwag ilagay ang err.stack o err.message raw sa body). Tingnan ang docs/security/ERROR_SANITIZATION.md.
  6. Magdagdag ng mga tests — kabilang ang hindi bababa sa isang assertion na ang mga error responses ay hindi nag-leak ng stack traces (!body.error.message.includes("at /"))

Pagdaragdag ng Bagong DB Module

  1. Lumikha ng src/lib/db/yourModule.ts — mag-import ng getDbInstance mula sa ./core.ts
  2. I-export ang mga CRUD functions para sa iyong domain table(s)
  3. Magdagdag ng migration sa src/lib/db/migrations/ kung kinakailangan ng mga bagong tables
  4. I-re-export mula sa src/lib/localDb.ts (magdagdag sa re-export list lamang)
  5. Sumulat ng mga tests

Pagdaragdag ng Bagong MCP Tool

  1. Magdagdag ng tool definition sa open-sse/mcp-server/tools/ na may Zod input schema + async handler
  2. Irehistro sa tool set (wired ng createMcpServer())
  3. I-assign sa naaangkop na scope(s)
  4. Sumulat ng mga tests (tool invocation na na-log sa mcp_audit table)

Pagdaragdag ng Bagong A2A Skill

  1. Lumikha ng skill sa src/lib/a2a/skills/ (5 na umiiral na: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. Ang skill ay tumatanggap ng task context (mga mensahe, metadata) → nagbabalik ng structured result
  3. Irehistro sa A2A_SKILL_HANDLERS sa src/lib/a2a/taskExecution.ts
  4. I-expose sa src/app/.well-known/agent.json/route.ts (Agent Card)
  5. Sumulat ng mga tests sa tests/unit/
  6. I-document sa docs/frameworks/A2A-SERVER.md skill table

Pagdaragdag ng Bagong Cloud Agent

  1. Lumikha ng agent class sa src/lib/cloudAgent/agents/ na nagpapalawak ng CloudAgentBase (3 na umiiral na: codex-cloud, devin, jules)
  2. I-implement ang createTask, getStatus, approvePlan, sendMessage, listSources
  3. Irehistro sa src/lib/cloudAgent/registry.ts
  4. Magdagdag ng OAuth/credentials handling kung kinakailangan (src/lib/oauth/providers/)
  5. Mga tests + i-document sa docs/frameworks/CLOUD_AGENT.md

Pagdaragdag ng Bagong Guardrail / Eval / Skill / Webhook event

  • Guardrail: src/lib/guardrails/ → docs: docs/security/GUARDRAILS.md
  • Eval suite: src/lib/evals/ → docs: docs/frameworks/EVALS.md
  • Skill (sandbox): src/lib/skills/ → docs: docs/frameworks/SKILLS.md
  • Webhook event: src/lib/webhookDispatcher.ts → docs: docs/frameworks/WEBHOOKS.md

Dokumentasyon ng Sanggunian

Para sa anumang hindi simpleng pagbabago, basahin muna ang kaukulang malalim na pagsusuri:

Lugar Dokumento
Nabigasyon ng Repo docs/architecture/REPOSITORY_MAP.md
Arkitektura docs/architecture/ARCHITECTURE.md
Sanggunian sa engineering docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-factor scoring, 14 estratehiya) docs/routing/AUTO-COMBO.md
Resilience (3 mekanismo) docs/architecture/RESILIENCE_GUIDE.md
Reasoning replay docs/routing/REASONING_REPLAY.md
Balangkas ng kasanayan docs/frameworks/SKILLS.md
Sistema ng memorya (FTS5 + Qdrant) docs/frameworks/MEMORY.md
Mga ahente ng ulap docs/frameworks/CLOUD_AGENT.md
Mga guardrails (PII / injection / vision) docs/security/GUARDRAILS.md
Pampublikong upstream credentials (Gemini/etc.) docs/security/PUBLIC_CREDS.md
Sanitization ng mensahe ng error docs/security/ERROR_SANITIZATION.md
Evals docs/frameworks/EVALS.md
Pagsunod / audit docs/security/COMPLIANCE.md
Webhooks docs/frameworks/WEBHOOKS.md
Pipeline ng awtorisasyon docs/architecture/AUTHZ_GUIDE.md
Stealth (TLS / fingerprint) docs/security/STEALTH_GUIDE.md
Mga protocol ng ahente (A2A / ACP / Cloud) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP server docs/frameworks/MCP-SERVER.md
A2A server docs/frameworks/A2A-SERVER.md
Sanggunian ng API + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Katalogo ng provider (auto-generated) docs/reference/PROVIDER_REFERENCE.md
Daloy ng release docs/ops/RELEASE_CHECKLIST.md

Pagsubok

Ano Utos
Unit tests npm run test:unit
Isang file node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo) npm run test:vitest
E2E (Playwright) npm run test:e2e
Protocol E2E (MCP+A2A) npm run test:protocols:e2e
Ecosystem npm run test:ecosystem
Coverage gate npm run test:coverage (75/75/75/70 — pahayag/linya/fuctions/sanga)
Coverage report npm run coverage:report

PR patakaran: Kung babaguhin mo ang production code sa src/, open-sse/, electron/, o bin/, kailangan mong isama o i-update ang mga pagsubok sa parehong PR.

Pabor sa test layer: unit muna → integration (multi-module o estado ng DB) → e2e (UI/workflow lamang). I-encode ang mga bug reproductions bilang automated tests bago o kasabay ng pag-aayos.

Copilot coverage policy: Kapag ang isang PR ay nagbabago ng production code at ang coverage ay mas mababa sa 75% (pahayag/linya/fuctions) o 70% (sanga), huwag lamang i-report — magdagdag o mag-update ng mga pagsubok, muling patakbuhin ang coverage gate, pagkatapos ay humingi ng kumpirmasyon. Isama ang mga utos na pinatakbo, mga nabagong test files, at huling resulta ng coverage sa PR report.

Git Workflow

# Huwag kailanman mag-commit nang direkta sa main
git checkout -b feat/your-feature
git commit -m "feat: ilarawan ang iyong pagbabago"
git push -u origin feat/your-feature

Branch prefixes: feat/, fix/, refactor/, docs/, test/, chore/

Format ng commit (Conventional Commits): feat(db): add circuit breaker — scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky hooks:

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

Kapaligiran

  • Runtime: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
  • TypeScript: 5.9+, target ES2022, module esnext, resolution bundler
  • Path aliases: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • Default port: 20128 (API + dashboard sa parehong port)
  • Data directory: DATA_DIR env var, default sa ~/.omniroute/
  • Key env vars: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • Setup: cp .env.example .env pagkatapos ay bumuo ng JWT_SECRET (openssl rand -base64 48) at API_KEY_SECRET (openssl rand -hex 32)

Mahigpit na Mga Patakaran

  1. Huwag kailanman mag-commit ng mga lihim o kredensyal
  2. Huwag kailanman magdagdag ng lohika sa localDb.ts
  3. Huwag kailanman gumamit ng eval() / new Function() / implied eval
  4. Huwag kailanman mag-commit nang direkta sa main
  5. Huwag kailanman magsulat ng raw SQL sa mga ruta — gumamit ng src/lib/db/ modules
  6. Huwag kailanman tahimik na lunukin ang mga error sa SSE streams
  7. Palaging i-validate ang mga input gamit ang Zod schemas
  8. Palaging isama ang mga pagsubok kapag binabago ang production code
  9. Ang coverage ay dapat manatili ≥75% (pahayag, linya, functions) / ≥70% (sanga). Kasalukuyang nasusukat: ~82%.
  10. Huwag kailanman balewalain ang mga Husky hooks (--no-verify, --no-gpg-sign) nang walang tahasang pag-apruba ng operator.
  11. Huwag kailanman isama ang pampublikong upstream OAuth client_id/secret o Firebase Web keys bilang string literals — palaging dumaan sa resolvePublicCred() (open-sse/utils/publicCreds.ts). Tingnan ang docs/security/PUBLIC_CREDS.md.
  12. Huwag kailanman ibalik ang raw err.stack / err.message sa HTTP / SSE / executor responses — palaging dumaan sa buildErrorBody() o sanitizeErrorMessage() (open-sse/utils/error.ts). Tingnan ang docs/security/ERROR_SANITIZATION.md.
  13. Huwag kailanman mag-string-interpolate ng mga panlabas na landas o runtime values sa mga shell scripts na ipinasa sa exec()/spawn() — ipasa sa pamamagitan ng env option sa halip. Sanggunian: src/mitm/cert/install.ts::updateNssDatabases.
  14. Huwag kailanman balewalain ang isang CodeQL / Secret-Scanning alert nang walang (a) unang pag-check sa pattern docs sa itaas upang makita kung ang helper ay naaangkop, at (b) pag-record ng teknikal na dahilan sa dismissal comment. Precedent: js/stack-trace-exposure na itinaas sa callsites na dumaan na sa sanitizeErrorMessage() ay isang kilalang limitasyon ng CodeQL (hindi kinikilala ang mga custom sanitizers) — balewalain bilang false positive na tumutukoy sa docs/security/ERROR_SANITIZATION.md.
  15. Huwag kailanman ilantad ang mga ruta na nagbubukas ng mga child processes (/api/mcp/, /api/cli-tools/runtime/) nang walang isLocalOnlyPath() classification sa src/server/authz/routeGuard.ts. Ang enforcement ng loopback ay nangyayari nang walang kondisyon bago ang anumang auth check — ang na-leak na JWT sa pamamagitan ng tunnel ay hindi maaaring mag-trigger ng process spawning. Tingnan ang docs/security/ROUTE_GUARD_TIERS.md.
  16. Huwag kailanman isama ang Co-Authored-By trailers na nagbibigay ng kredito sa AI assistant, LLM, o automation account (hal. mga pangalan na naglalaman ng "Claude", "GPT", "Copilot", "Bot"; mga email sa anthropic.com / openai.com / noreply.github.com addresses na pag-aari ng bots). Ang ganitong trailers ay nagru-route ng commit attribution sa bot account sa GitHub, na nagtatago sa tunay na may-akda (diegosouzapw) sa PR history. Ang mga taong kolaborator — kabilang ang mga upstream PR authors at issue reporters na ini-port sa OmniRoute — ay MAAARI at DAPAT bigyan ng kredito gamit ang standard Co-authored-by: Name <email> trailers; umaasa rito ang upstream-port workflows (/port-upstream-features, /port-upstream-issues).
Reference in New Issue View Git Blame Copy Permalink