pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-01 12:52:11 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
8c11acaa33d0becc2add80b063d2a94de202f981
OmniRoute/docs/i18n/te/CLAUDE.md
Diego Rodrigues de Sa e Souza f59f8daa94 Release v3.8.6 (#2804) 
* fix(gemini): preserve structured tool calls for antigravity

* fix(gemini): parse prefixed textual tool calls

* fix(antigravity): preserve textual SSE tool calls

* fix(stream): normalize textual passthrough tool calls

* fix(stream): normalize split textual tool calls

* fix(stream): suppress malformed textual tool calls

* fix(stream): suppress compact malformed tool calls

* fix(stream): emit structured textual tool calls

* fix(stream): suppress unknown textual tool calls

* fix(stream): normalize responses textual tool calls

* chore: ignore .claude/settings.local.json (per-user Claude Code permissions)

* fix(opencode-go): route qwen3.x via claude messages + repair fixMissingToolResponses for Claude-shape upstreams (#2791)

Integrated into release/v3.8.6

* fix: resolve npm install warnings — remove dead deps, relax engine constraint (#2792)

Integrated into release/v3.8.6

* fix: register missing web-cookie validators (claude-web, gemini-web, copilot-web, t3-web) (#2793)

Integrated into release/v3.8.6

* fix: Error: Unable to inspect existing database #2771 (#2795)

Integrated into release/v3.8.6

* fix(oauth): repair Google loopback callback flow (#2796)

Integrated into release/v3.8.6

* feat(logs): add clean history button (#2799)

Integrated into release/v3.8.6

* [codex] home: restore settings-driven home layout and quota auto-refresh (#2800)

Integrated into release/v3.8.6

* fix(gemini): emit signaturelessToolCallMode:text for GEMINI format models (#2801)

Integrated into release/v3.8.6

* feat(modelSpecs): align opencode-go family with upstream provider limits (#2802)

Integrated into release/v3.8.6

* chore: apply unit test fixes, polyfills, and environment precedence fixes

* docs(agents): atualiza fluxos de release e triagem

Expande os workflows de release para incluir auditoria de segurança,
CHANGELOG completo por commits, quality gate obrigatório, homologação em
VPS local, publicação oficial, deploy em Akamai e validação de artefatos.

Reorganiza a triagem de features com arquivos permanentes por bucket,
suporte a itens em andamento, regra de reclaim após 15 dias e novo
tratamento para ideias viáveis catalogadas.

Corrige a orientação de revisão de discussões para usar a ordem
cronológica real dos comentários e respostas ao identificar a última
atividade.

* fix(lockout): classify Gemini Antigravity resource exhaustion as quota_exhausted

* fix(reasoning): gate replay by interleaved field

* docs(rule-16): permit human Co-authored-by, restrict only AI/bot trailers

Rule #16 previously banned all `Co-Authored-By` trailers absolutely.
That blocked the upstream-port workflows (`/port-upstream-features` and
`/port-upstream-issues`), which must credit human upstream PR authors
and issue reporters in OmniRoute commits.

Refine the rule to ban only AI/bot-attributed trailers (Claude, GPT,
Copilot, Bot; anthropic.com / openai.com / bot-owned noreply.github.com
emails) while allowing standard human `Co-authored-by: Name <email>`
attribution.

Sync the rule across the source CLAUDE.md, the E2E shakedown doc note,
and 41 i18n translations.

* fix(gitlawb): add specialty validators for connection test — bypass /models probe

GitLawB OpenGateway API (xiaomi-mimo compatible) does not expose a /models
endpoint, causing validateOpenAILikeProvider to 404 on the initial probe
and report 'Provider validation endpoint not supported'.

Add specialty validators for both gitlawb and gitlawb-gmi that follow the
same pattern as the existing xiaomi-mimo validator: skip GET /models,
validate directly via POST /chat/completions with a minimal test message.
Any 401/403 response means an invalid key; all other responses mean auth
is OK.

Fixes test-connection returning 404 for GitLawB providers.

* test(gitlawb): add 12 unit tests for gitlawb and gitlawb-gmi specialty validators

Covers success, auth failure (401/403), non-auth acceptance (400/422/429),
network errors, and custom baseUrl overrides for both providers.

* feat(gitlawb): serve models from static registry without API-unavailable warning

GitLawB's OpenGateway API does not expose a /models endpoint per
provider-path. Previously the models route fell through to the generic
fallback which returned static catalog models with the misleading
'API unavailable — using local catalog' warning.

Now gitlawb and gitlawb-gmi are handled as static model providers
(same pattern as reka and qwen OAuth) — models are served from the
provider registry without any warning, since all registered models
are functional via POST /chat/completions.

* refactor(gitlawb): extract shared opengateway validator factory, fix docs path in test

- Extract gitlawb/gitlawb-gmi validators into buildOpengatewayValidator factory
- Fix dockerignore-docs-coverage test: update stale docs/AUTO-COMBO.md -> docs/routing/AUTO-COMBO.md

* fix(reasoning): guard interleaved capability lookup

* feat(gitlawb): dynamic model fetch with gmi-cloud fallback

Hybrid approach:
- gitlawb (xiaomi-mimo): dynamic /models endpoint → 356 models
- gitlawb-gmi (gmi-cloud): 404 fallback → local catalog gracefully
Mimics Gitlawb/openclaude's model-routing pattern

* i18n(pt-BR): complete missing translations and sync with en.json

* feat(build): nix multi-OS package manager install (#2806)

Integrated into release/v3.8.6

* fix(i18n): translate 144 new __MISSING__ pt-BR strings (#2816)

Integrated into release/v3.8.6

* chore(docs): set coverage gate to 40/40/40/40 in CLAUDE.md

Aligns the documented coverage gate with the v3.8.6 release decision
(lowered from 75/75/75/70). Matches the threshold already set in
package.json by the large feature PRs (planos 11-22).

* fix(cli): respect PORT env var in serve command (#2845)

Integrated into release/v3.8.6.

* fix(deepseek-web): return 400 when client sends tools[] - chat.deepseek.com has no tool support (#2854)

Integrated into release/v3.8.6.

* fix(qoder): reject invalid/expired PATs returning Cosy 500 error (#2860)

Integrated into release/v3.8.6.

* fix(cli): register openclaw in tool-detector (#2833) (#2850)

Integrated into release/v3.8.6.

* fix(api): include noAuth providers in /v1/models catalog (#2798) (#2814)

Integrated into release/v3.8.6.

* fix(combo): resolve custom provider targets via combo name (#2778) (#2812)

Integrated into release/v3.8.6.

* fix(translator): strip safety_identifier in openai-responses cleanup (#2770) (#2809)

Integrated into release/v3.8.6.

* fix(quota): honor explicit per-connection preflight opt-out (#2831) (#2844)

Integrated into release/v3.8.6.

* fix(usage): un-invert GitHub Copilot Free/limited quota — limited_user_quotas is remaining (#2876) (#2881)

Integrated into release/v3.8.6.

* fix(nous-research): correct baseUrl to include /chat/completions (#2826) (#2835)

Integrated into release/v3.8.6.

* fix(opencode): qwen3.x max/plus models lack vision support (#2822) (#2836)

Integrated into release/v3.8.6.

* fix(translator): pass-through tool_search built-in tool type (#2766) (#2811)

Integrated into release/v3.8.6.

* fix(github): route claude-opus-4.6 via chat completions (#2821)

Integrated into release/v3.8.6.

* docs(oauth): add Windsurf login fix design (Phase 1 hotfix + Phase 2 Firebase OAuth)

Two-phase plan to fix the broken Windsurf OAuth flow:
- Phase 1: drop the dead app.devin.ai/editor/signin PKCE path, promote
  import-token from windsurf.com/show-auth-token as the primary path
- Phase 2: port Firebase OAuth + RegisterUser flow from
  fendoushaonian/WindSurf-gRPC-API for full browser-based automation

Spec only - no code changes yet.

* docs(plan): Phase 1 windsurf login hotfix implementation plan

10 tasks covering:
- TDD assertions for flowType + 410 Gone responses
- Provider switch to import_token
- Route handler retiring authorize/start-callback-server/poll-callback
- OAuthModal UI override
- i18n sync
- Verification + PR steps

* fix(cli): replace cli-table3 with hand-rolled formatter (#2752) (#2813)

Integrated into release/v3.8.6.

* fix(skills): skip interception for unregistered client-native tools (#2815) (#2817)

Integrated into release/v3.8.6.

* feat(sse): add RTK filters for kubectl, docker-build, composer, gh (#2824)

Integrated into release/v3.8.6.

* fix(geminiHelper): support rec.image content shape + warn on dropped remote URLs (refs #2807) (#2855)

Integrated into release/v3.8.6.

* fix(cli): allow nullable/optional apiKey in cliMitmStartSchema (#2857)

Integrated into release/v3.8.6.

* fix(combo): preserve system messages during context handoff summary generation (#2865)

Integrated into release/v3.8.6.

* fix: wire CLIProxyAPI fallback settings into chatCore routing engine (#2866)

Integrated into release/v3.8.6.

* fix(usage): add opencode quota fetcher (#2852) (#2867)

Integrated into release/v3.8.6.

* feat(claude): default xhigh support for newer Opus models (#2874)

Integrated into release/v3.8.6.

* fix(cli): restore omniroute logs command stream (#2756) (#2810)

Integrated into release/v3.8.6.

* fix(combo): normalize upstream Headers for Node 24 undici interop (#2751) (#2823)

Integrated into release/v3.8.6.

* Rename proxy log Public IP to Client IP (#2880)

Integrated into release/v3.8.6.

* fix(claude): preserve max effort for supported models (#2875)

Integrated into release/v3.8.6.

* fix(oauth): switch windsurf provider to import_token flow

The PKCE auth URL targeting app.devin.ai/editor/signin returns 404
post-rebrand. Until Phase 2 ports Firebase OAuth + RegisterUser, the
only supported path is import-token via windsurf.com/show-auth-token.

- windsurf.ts: drop buildAuthUrl, set flowType=import_token
- generateAuthData returns supported:false + helpful error for windsurf/devin-cli
- tests: assert flowType + disabled stub

* fix(oauth): return 410 Gone for retired windsurf/devin-cli PKCE actions

start-callback-server, authorize, and poll-callback (GET + POST) now
return 410 Gone with a pointer to /import-token. The 410 short-circuit
runs before auth so the response is honest about the action being
permanently gone, not gated. Codex PKCE flow unchanged.

Tests: 5 new assertions cover GET + POST 410 paths and a Codex
regression check.

* refactor(oauth): annotate retired PKCE fields in WINDSURF_CONFIG

No behaviour change - comment-only update documenting that authorizeUrl,
codeChallengeMethod, callbackPort, callbackPath, apiServerUrl, and
exchangePath are no longer consumed. Active fields (inferenceUrl,
showAuthTokenUrl, firebaseApiKey, ideName) called out separately.

* fix(cli,docs): use requireCliToolsAuth in logs route + document OPENCODE quota env

Post-merge contract fixes for v3.8.6:
- src/app/api/cli-tools/logs/route.ts (#2810) now uses the shared
  requireCliToolsAuth guard (param renamed req->request) to satisfy the
  cli-tools-auth-hardening contract test.
- Document OMNIROUTE_OPENCODE_QUOTA_URL (#2867) in docs/reference/ENVIRONMENT.md
  to satisfy the env/docs sync contract.

* fix(dashboard): force import-token panel for windsurf/devin-cli

Phase 1 hotfix: hide the 'Browser Login' tab and start in Paste API Key
mode. Removes windsurf/devin-cli from PKCE_CALLBACK_SERVER_PROVIDERS so
no callback server is started for them. Codex still uses the PKCE flow.

The 'Get token' link continues to point at windsurf.com/show-auth-token
via the existing supportsTokenPaste form copy.

* fix(oauth): windsurf import-token mapTokens signature mismatch

The route at `src/app/api/oauth/[provider]/[action]/route.ts` invokes
`providerData.mapTokens({ accessToken: token })` (object), matching the
cursor/kiro signature. The windsurf provider was declared with
`mapTokens(token: string)` instead, so the entire object was stored as
`accessToken`. When the connection record reached the SQLite layer it
crashed with:

  SQLite3 can only bind numbers, strings, bigints, buffers, and null

Fix by aligning windsurf's `mapTokens` signature with the route caller
and the cursor/kiro convention. Also dedupe a copy-pasted second
`if (action === "import-token")` block in the route handler — the
second block was unreachable but identical to the first.

Adds two regression tests asserting that
`provider.mapTokens({ accessToken })` returns a string `accessToken` for
both windsurf and devin-cli, so a future signature drift trips the gate
instead of the SQLite bind error in production.

* feat(compression): expand pt-BR pack with troglodita rules (15 → 49) (#2818)

Integrated into release/v3.8.6

* fix(sse): repair RTK engine defaults so dedup and direct calls work (#2825)

Integrated into release/v3.8.6

* fix(mcp): redirect console.log/warn to stderr in --mcp stdio mode (#2840)

Integrated into release/v3.8.6

* fix(gemini-cli): prefer real project IDs over default-project (#2841)

Integrated into release/v3.8.6

* fix(opencode-go): add provider limits quota fetcher (#2861)

Integrated into release/v3.8.6

* Audit & add web cookie providers: fix 4 missing registry entries + DuckDuckGo (#2862)

Integrated into release/v3.8.6

* fix(antigravity): harden signatureless tool history (#2878)

Integrated into release/v3.8.6

* fix: provider model sync pruning and dynamic antigravity MITM proxy mappings (#2886)

Integrated into release/v3.8.6

* feat(usage): per-API-key token limits scoped to model/provider/global (#2888)

Integrated into release/v3.8.6

* fix(audio): build multipart body manually to preserve Content-Type (#2842)

Integrated into release/v3.8.6

* refactor: remove agent skill documentation files and streamline maintenance workflows

* test(stabilization): resolve unit test failures in blackbox-web, schema-coercion, translator-helper-branches, usage-service-hardening, and audio-transcription

* fix(security): mitigate Socket.dev supply-chain findings + secrets opt-in + minimal build profile (#2863) (#2871)

Two real security gaps closed and four cosmetic Socket.dev fingerprints removed.
See docs/security/SOCKET_DEV_FINDINGS.md for the per-finding maintainer
attestation.

Real bugs fixed:
- cloudSync: HMAC verification of `X-Cloud-Sig` + opt-in
  `OMNIROUTE_CLOUD_SYNC_SECRETS=true` before overwriting `accessToken` /
  `refreshToken` / `providerSpecificData` from a remote response. Closes the
  silent-credential-swap surface (a misconfigured or hostile CLOUD_URL could
  previously replace local tokens unverified).
- Zed import: split into 2-step `/discover` + `/import` flow. `/import` now
  requires `confirmedAccounts: [{ service, account, fingerprint }]` and
  re-reads the keychain server-side to filter by fingerprint, so a tampered
  discover response cannot trick the endpoint into saving an unrelated token.

Cosmetic Socket.dev mitigations:
- runElevatedPowerShell writes the elevated payload to a per-call temp `.ps1`
  file (mode 0o600) and references it via `-File`. Removes the textbook
  `-EncodedCommand <base64utf16le>` pattern flagged as malware by Socket's AI
  classifier.
- Maintainer attestation `SECURITY-AUDITOR-NOTE:` blocks added at every
  flagged call site pointing to `docs/security/SOCKET_DEV_FINDINGS.md`.

Build-time hardening:
- `OMNIROUTE_BUILD_PROFILE=minimal` (`npm run build:secure`) physically
  removes the four sensitive modules from the standalone bundle via webpack
  `NormalModuleReplacementPlugin`. Stubs throw `FeatureDisabledError` at
  runtime. Intended for the `omniroute-secure` artifact.

Tests:
- 24 new unit tests in `tests/unit/security/` covering the wrapper builder,
  HMAC verification (4 cases), credential fingerprint determinism (5 cases),
  confirmedAccounts validation + fingerprint filtering (6 cases), and the
  minimal-build stubs (5 cases).

Docs:
- New `docs/security/SOCKET_DEV_FINDINGS.md` — per-finding attestation.
- New `socket.yml` — Socket.dev v2 config pointing at the attestation.
- Updated `SECURITY.md` — supply-chain scanner section.
- Updated `.env.example` — three new env vars documented.

Backwards compatibility:
- Cloud sync token overwrite is OFF by default. Users who relied on
  it must set `OMNIROUTE_CLOUD_SYNC_SECRETS=true`. Breaking change documented
  in CHANGELOG.
- Zed import 2-step is the new default; legacy 1-step preserved behind
  `OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP=true` and will be removed in v3.9.

Closes #2863

* fix(security): redact public Firebase Web key from windsurf spec; doc SHA-256 cache-key rationale (#2894)

Two security-scanning findings on release/v3.8.6:

- Secret-scanning alert 7 (google_api_key): the windsurf login-fix design spec
  embedded the literal public Firebase Web API key on two lines. Firebase Web
  API keys are non-sensitive by design (they identify the project; access is
  gated by Firebase Security Rules + key restrictions), but the literal trips
  secret scanning. Redacted to a placeholder; the embedded default still goes
  through resolvePublicCred per rule #11.

- Code-scanning alert 261 (js/insufficient-password-hash): tokenCacheKey() uses
  SHA-256 to derive an in-memory cache key from the session token, not for
  password-at-rest storage. Added a comment documenting why CWE-916 KDFs do not
  apply (false positive).

* fix(ci): resolve release/v3.8.6 gate failures (docs-sync, any-budget, pack-artifact) (#2895)

* fix(ci): resolve release/v3.8.6 gate failures (docs-sync, any-budget, pack-artifact)

Three CI gates failed on release/v3.8.6 (run 26630300877):

- docs-sync: CHANGELOG had a spurious "## [3.8.6-patch]" section above
  "## [3.8.6]", so the latest release no longer matched package.json (3.8.6)
  and the 41 i18n CHANGELOG mirrors were flagged as missing that section.
  Fold the lone #2752 entry into [3.8.6] and drop the patch heading.
- any-budget:t11: open-sse/handlers/chatCore.ts regressed to 1 explicit `any`
  (budget 0). Type the persist callback arg as Record<string, unknown>, which
  matches runWithOnPersist's RefreshPersistFn contract exactly.
- pack-artifact: open-sse/utils/setupPolyfill.ts ships via package.json "files"
  (bin/omniroute.mjs imports it at startup) but was missing from the pack
  policy allowlist. Allow it and add a regression test.

* fix(security): redact public Firebase Web key from windsurf spec

Redact the literal public Firebase Web API key (secret-scanning #7) to a
placeholder, mirroring the redaction on release/v3.8.6 (PR #2894) and the
windsurf fix branch. Non-sensitive public Web key; trips secret scanning.

* feat(combo): Zero-Latency Combos (Hedging, Proactive Compression, Predictive TTFT) (#2868)

* feat(combo): implement zero-latency combo optimizations (hedging, proactive compression, predictive TTFT)

* fix(combo): fix predictive TTFT skip logic and unhandled promise rejections

---------

Co-authored-by: Automation <automation@omniroute>

* feat: implement automated skill workflows and update system configuration and validation schemas

* test: eliminate dynamic cast warnings in cloud-sync unit test

* test: isolate services-branch-hardening database directory to avoid concurrency issues

* feat(providers): add 7 new web-cookie providers + research catalog + discovery tool

New providers:
- huggingchat: free LLM chat via huggingface.co/chat (no subscription)
- phind: free dev-focused AI chat via phind.com/api/agent
- poe-web: multi-model chat via poe.com GraphQL (p-b cookie)
- venice-web: privacy-focused AI chat via venice.ai (session cookie)
- v0-vercel-web: Vercel v0 code gen via v0.dev (session cookie)
- kimi-web: Moonshot Kimi chat via kimi.moonshot.cn (session cookie)
- doubao-web: ByteDance Doubao chat via doubao.com (session cookie)

Additional:
- Research catalog: docs/research/UNLIMITED_LLM_ACCESS.md
- Discovery tool design + stub: src/lib/discovery/ + migration 073
- Unit tests: 33 tests for all 7 providers
- Shared helpers consolidated in error.ts (slop cleanup)
- All registered in WEB_COOKIE_PROVIDERS + providerRegistry + webSessionCredentials

Closes #2885

* fix(typecheck): resolve typecheck errors in combo spec and compression modules

* feat(api,oauth): add `agy` (Antigravity CLI) standalone provider with CLI token import (#2899)

Add a standalone OAuth provider `agy` (Antigravity CLI) next to gemini-cli/antigravity.
It reuses the antigravity inference backend (identical Google client_id +
daily-cloudcode-pa.googleapis.com endpoint, executor and token-refresh) but ships its own
model catalog — including the Claude models the backend exposes (claude-opus-4-6-thinking,
claude-sonnet-4-6) — its own account pool, and four ways to connect:

- token-file import (paste/upload the agy oauth token JSON)
- auto-detect a local CLI login (~/.gemini/antigravity-cli/antigravity-oauth-token)
- browser OAuth (via the shared OAuthModal Google loopback flow)
- bulk / ZIP import

New routes: POST /api/providers/agy-auth/{import,import-bulk,zip-extract,apply-local}.
Catalog pinned from the live :fetchAvailableModels endpoint. Docs (openapi.yaml,
ENVIRONMENT.md, .env.example, CHANGELOG) updated; new unit tests for registration,
the token parser, and route auth-hardening.

* fix(security): redact public Firebase Web key from windsurf spec (#2896)

Redact the literal public Firebase Web API key (secret-scanning #7) to a
placeholder. Firebase Web API keys are non-sensitive by design but the literal
trips GitHub secret scanning. Mirrors the redaction landed on release/v3.8.6
(PR #2894). Embedded default still flows through resolvePublicCred (rule #11).

* Pr 2871 (#2897)

* fix(security): mitigate Socket.dev supply-chain findings + secrets opt-in + minimal build profile (#2863)

Two real security gaps closed and four cosmetic Socket.dev fingerprints removed.
See docs/security/SOCKET_DEV_FINDINGS.md for the per-finding maintainer
attestation.

Real bugs fixed:
- cloudSync: HMAC verification of `X-Cloud-Sig` + opt-in
  `OMNIROUTE_CLOUD_SYNC_SECRETS=true` before overwriting `accessToken` /
  `refreshToken` / `providerSpecificData` from a remote response. Closes the
  silent-credential-swap surface (a misconfigured or hostile CLOUD_URL could
  previously replace local tokens unverified).
- Zed import: split into 2-step `/discover` + `/import` flow. `/import` now
  requires `confirmedAccounts: [{ service, account, fingerprint }]` and
  re-reads the keychain server-side to filter by fingerprint, so a tampered
  discover response cannot trick the endpoint into saving an unrelated token.

Cosmetic Socket.dev mitigations:
- runElevatedPowerShell writes the elevated payload to a per-call temp `.ps1`
  file (mode 0o600) and references it via `-File`. Removes the textbook
  `-EncodedCommand <base64utf16le>` pattern flagged as malware by Socket's AI
  classifier.
- Maintainer attestation `SECURITY-AUDITOR-NOTE:` blocks added at every
  flagged call site pointing to `docs/security/SOCKET_DEV_FINDINGS.md`.

Build-time hardening:
- `OMNIROUTE_BUILD_PROFILE=minimal` (`npm run build:secure`) physically
  removes the four sensitive modules from the standalone bundle via webpack
  `NormalModuleReplacementPlugin`. Stubs throw `FeatureDisabledError` at
  runtime. Intended for the `omniroute-secure` artifact.

Tests:
- 24 new unit tests in `tests/unit/security/` covering the wrapper builder,
  HMAC verification (4 cases), credential fingerprint determinism (5 cases),
  confirmedAccounts validation + fingerprint filtering (6 cases), and the
  minimal-build stubs (5 cases).

Docs:
- New `docs/security/SOCKET_DEV_FINDINGS.md` — per-finding attestation.
- New `socket.yml` — Socket.dev v2 config pointing at the attestation.
- Updated `SECURITY.md` — supply-chain scanner section.
- Updated `.env.example` — three new env vars documented.

Backwards compatibility:
- Cloud sync token overwrite is OFF by default. Users who relied on
  it must set `OMNIROUTE_CLOUD_SYNC_SECRETS=true`. Breaking change documented
  in CHANGELOG.
- Zed import 2-step is the new default; legacy 1-step preserved behind
  `OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP=true` and will be removed in v3.9.

Closes #2863

* feat: implement automated skill workflows and update system configuration and validation schemas

* test: eliminate dynamic cast warnings in cloud-sync unit test

* test: isolate services-branch-hardening database directory to avoid concurrency issues

* chore(docs): refresh generated docs collection index

Update the generated Fumadocs browser collection mapping to keep
documentation imports in sync with the current docs structure.

* docs: update generated browser docs collection manifest

Refresh the generated Fumadocs browser collection mapping so the docs site can resolve the current documentation files correctly.

---------

Co-authored-by: OpenClaw <openclaw@kuzhomesrv.local>
Co-authored-by: Dmitry Kuznetsov <139351986+dmitry@users.noreply.local>
Co-authored-by: KuzyaBot <kuzya@local>
Co-authored-by: JeferssonLemes <jeferssondev@gmail.com>
Co-authored-by: Paijo <14921983+oyi77@users.noreply.github.com>
Co-authored-by: Markus Hartung <mail@hartmark.se>
Co-authored-by: akarray <akarray@users.noreply.github.com>
Co-authored-by: Apostol Apostolov <theapoapostolov@gmail.com>
Co-authored-by: Hernan Javier Ardila Sanchez <hjasgr@gmail.com>
Co-authored-by: Dmitry Kuznetsov <dmitry@kuznetsov.me>
Co-authored-by: Nikolay Alafuzov <alafuzov_nn@rusklimat.ru>
Co-authored-by: oyi77 <oyi77@users.noreply.github.com>
Co-authored-by: Ronaldo Davi <alltomatos@users.noreply.github.com>
Co-authored-by: levonk <277861+levonk@users.noreply.github.com>
Co-authored-by: Lenine Júnior <lenine@engrene.com.br>
Co-authored-by: Annas Alghoffar <aag.annas@gmail.com>
Co-authored-by: Tushar Agarwal <76201310+Tushar49@users.noreply.github.com>
Co-authored-by: GreatLiu <eurasiaxz@qq.com>
Co-authored-by: yuna amelia <230527278+yunaamelia@users.noreply.github.com>
Co-authored-by: Randi <55005611+rdself@users.noreply.github.com>
Co-authored-by: Container <78986709+disonjer@users.noreply.github.com>
Co-authored-by: nickwizard <35692452+nickwizard@users.noreply.github.com>
Co-authored-by: Rajvardhan Patil <rajvardhanpatil7890@gmail.com>
Co-authored-by: Raxxoor <manker_lol@hotmail.com>
Co-authored-by: Muhammad Mugni Hadi <mugnimaestra3@gmail.com>
Co-authored-by: mi <123757457+soyelmismo@users.noreply.github.com>
Co-authored-by: Automation <automation@omniroute>
2026-05-29 12:44:29 -03:00

49 KiB
Raw Blame History

CLAUDE.md (తెలుగు)

🌐 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 · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

ఈ ఫైల్ ఈ రిపోజిటరీలో కోడ్‌తో పనిచేసేటప్పుడు Claude Code (claude.ai/code) కు మార్గదర్శకత్వం అందిస్తుంది.

తక్షణ ప్రారంభం

npm install                    # డిపెండెన్సీలు ఇన్‌స్టాల్ చేయండి (.env.example నుండి .env ఆటో-జనరేట్ చేస్తుంది)
npm run dev                    # http://localhost:20128 వద్ద డెవ్ సర్వర్
npm run build                  # ఉత్పత్తి నిర్మాణం (Next.js 16 standalone)
npm run lint                   # ESLint (0 తప్పులు ఆశించబడుతున్నాయి; హెచ్చరికలు ముందుగా ఉన్నాయి)
npm run typecheck:core         # TypeScript తనిఖీ (స్వచ్ఛంగా ఉండాలి)
npm run typecheck:noimplicit:core  # కఠినమైన తనిఖీ (ఏదైనా అర్థం లేకుండా లేదు)
npm run test:coverage          # యూనిట్ పరీక్షలు + కవరేజ్ గేట్ (75/75/75/70 — స్టేట్‌మెంట్‌లు/లైన్లు/ఫంక్షన్‌లు/శాఖలు)
npm run check                  # lint + పరీక్షలు కలిపి
npm run check:cycles           # చక్రాకార ఆధారాలను గుర్తించండి

పరీక్షలను నడపడం

# ఒకే పరీక్ష ఫైల్ (Node.js స్థానిక పరీక్ష రన్నర్ — ఎక్కువ పరీక్షలు)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP సర్వర్, autoCombo, కాష్)
npm run test:vitest

# అన్ని సూట్లు
npm run test:all

పూర్తి పరీక్ష మ్యాట్రిక్స్ కోసం, CONTRIBUTING.md → "పరీక్షలను నడపడం" చూడండి. లోతైన నిర్మాణం కోసం, AGENTS.md చూడండి.

ప్రాజెక్ట్ ఒక చూపులో

OmniRoute — ఏకీకృత AI ప్రాక్సీ/రౌటర్. ఒక ఎండ్‌పాయింట్, 160+ LLM ప్రొవైడర్లు, ఆటో-ఫాల్బ్యాక్.

పొర స్థానం ఉద్దేశ్యం
API రూట్లు src/app/api/v1/ Next.js యాప్ రౌటర్ — ప్రవేశ బిందువులు
హ్యాండ్లర్లు open-sse/handlers/ అభ్యర్థన ప్రాసెసింగ్ (చాట్, ఎంబెడింగ్స్, మొదలైనవి)
ఎగ్జిక్యూటర్లు open-sse/executors/ ప్రొవైడర్-స్పెసిఫిక్ HTTP డిస్పాచ్
అనువాదకులు open-sse/translator/ ఫార్మాట్ మార్పిడి (OpenAI↔Claude↔Gemini)
ట్రాన్స్‌ఫార్మర్ open-sse/transformer/ స్పందనలు API ↔ చాట్ పూర్తి చేయడం
సేవలు open-sse/services/ కాంబో రౌటింగ్, రేటు పరిమితులు, కాషింగ్, మొదలైనవి
డేటాబేస్ src/lib/db/ SQLite డొమైన్ మాడ్యూల్స్ (45+ ఫైళ్లు, 55 మైగ్రేషన్స్)
డొమైన్/పాలసీ src/domain/ పాలసీ ఇంజిన్, ఖర్చు నియమాలు, ఫాల్బ్యాక్ లాజిక్
MCP సర్వర్ open-sse/mcp-server/ 37 టూల్స్ (30 బేస్ + 3 మెమరీ + 4 నైపుణ్యాలు), 3 ట్రాన్స్‌పోర్ట్‌లు, ~13 స్కోప్స్
A2A సర్వర్ src/lib/a2a/ JSON-RPC 2.0 ఏజెంట్ ప్రోటోకాల్
నైపుణ్యాలు src/lib/skills/ విస్తరించదగిన నైపుణ్య ఫ్రేమ్‌వర్క్
మెమరీ src/lib/memory/ స్థిరమైన సంభాషణ మెమరీ

Monorepo: src/ (Next.js 16 యాప్), open-sse/ (స్ట్రీమింగ్ ఇంజిన్ వర్క్‌స్పేస్), electron/ (డెస్క్‌టాప్ యాప్), tests/, bin/ (CLI ప్రవేశ బిందువు).

అభ్యర్థన పైప్‌లైన్

Client → /v1/chat/completions (Next.js మార్గం)
  → CORS → Zod ధృవీకరణ → auth? → విధానం తనిఖీ → ప్రాంప్ట్ ఇంజెక్షన్ గార్డ్
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → కాష్ తనిఖీ → రేటు పరిమితి → కాంబో రూటింగ్?
      → resolveComboTargets() → handleSingleModel() ప్రతి లక్ష్యానికి
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() అప్‌స్ట్రీమ్ → తిరిగి ప్రయత్నించండి w/ బ్యాకాఫ్
    → స్పందన అనువాదం → SSE స్ట్రీమ్ లేదా JSON
    → If Responses API: responsesTransformer.ts TransformStream

API మార్గాలు ఒక సుసంగత నమూనాను అనుసరిస్తాయి: Route → CORS ప్రీఫ్లైట్ → Zod శరీర ధృవీకరణ → ఐచ్ఛిక auth (extractApiKey/isValidApiKey) → API కీ విధానం అమలు → హ్యాండ్లర్ డెలిగేషన్ (open-sse). ఏ గ్లోబల్ Next.js మిడ్‌లెయిర్ లేదు — అంతరాయము మార్గానికి ప్రత్యేకంగా ఉంటుంది.

కాంబో రూటింగ్ (open-sse/services/combo.ts): 14 వ్యూహాలు (ప్రాధమికత, బరువైన, ఫిల్-ఫస్ట్, రౌండ్-రాబిన్, P2C, యాదృచ్ఛిక, తక్కువ-ఉపయోగించిన, ఖర్చు-ఆప్టిమైజ్డ్, రీసెట్-అవేర్, కఠిన-యాదృచ్ఛిక, ఆటో, lkgp, సందర్భం-ఆప్టిమైజ్డ్, సందర్భం-రిలే). ప్రతి లక్ష్యం handleSingleModel()ను పిలుస్తుంది, ఇది handleChatCore()ను లక్ష్యానికి ప్రత్యేకమైన పొరపాటు నిర్వహణ మరియు సర్క్యూట్ బ్రేకర్ తనిఖీలతో చుట్టిస్తుంది. 9-ఫ్యాక్టర్ ఆటో-కాంబో స్కోరింగ్ కోసం docs/routing/AUTO-COMBO.mdను మరియు 3 స్థిరత్వ పొరల కోసం docs/architecture/RESILIENCE_GUIDE.mdను చూడండి.

స్థిరత్వం రన్‌టైమ్ స్థితి

OmniRouteకు మూడు సంబంధిత కానీ ప్రత్యేక తాత్కాలిక-పరాజయ యంత్రాంగాలు ఉన్నాయి. రూటింగ్ ప్రవర్తనను డీబగ్ చేస్తూ వాటి పరిధిని వేరుగా ఉంచండి. ఒక తక్షణ-చిత్రం మ్యాప్ కోసం 3-పొర స్థిరత్వం చిత్రాన్ని చూడండి (మూలం: docs/diagrams/resilience-3layers.mmd).

ప్రొవైడర్ సర్క్యూట్ బ్రేకర్

పరిధి: మొత్తం ప్రొవైడర్, ఉదా: glm, openai, anthropic.

ఉద్దేశ్యం: అప్‌స్ట్రీమ్/సేవ స్థాయిలో పునరావృతంగా విఫలమవుతున్న ప్రొవైడర్‌కు ట్రాఫిక్ పంపడం ఆపడం, కాబట్టి ఒక అనారోగ్య ప్రొవైడర్ ప్రతి అభ్యర్థనను నెమ్మదిగా చేయదు.

అమలు:

  • కోర్ క్లాస్: src/shared/utils/circuitBreaker.ts
  • చాట్ గేట్/అమలు వైరింగ్: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • రన్‌టైమ్ స్థితి API: src/app/api/monitoring/health/route.ts
  • పంచుకున్న రాపర్లు: open-sse/services/accountFallback.ts
  • నిల్వ చేసిన స్థితి పట్టిక: domain_circuit_breakers

స్థితులు:

  • CLOSED: సాధారణ ట్రాఫిక్ అనుమతించబడింది.
  • OPEN: ప్రొవైడర్ తాత్కాలికంగా బ్లాక్ చేయబడింది; కాలర్‌లు ప్రొవైడర్-సర్క్యూట్-ఓపెన్ స్పందన పొందుతారు లేదా కాంబో రూటింగ్ మరో లక్ష్యానికి దాటిస్తుంది.
  • HALF_OPEN: రీసెట్ టైమ్‌ఔట్ ముగిసింది; ఒక ప్రోబ్ అభ్యర్థనను అనుమతించండి. విజయవంతం అయితే బ్రేకర్ మూసివేస్తుంది, విఫలమైతే మళ్లీ తెరుస్తుంది.

డిఫాల్ట్స్ (open-sse/config/constants.ts):

  • OAuth ప్రొవైడర్లు: థ్రెషోల్డ్ 3, రీసెట్ టైమ్‌ఔట్ 60s.
  • API-కీ ప్రొవైడర్లు: థ్రెషోల్డ్ 5, రీసెట్ టైమ్‌ఔట్ 30s.
  • స్థానిక ప్రొవైడర్లు: థ్రెషోల్డ్ 2, రీసెట్ టైమ్‌ఔట్ 15s.

ప్రొవైడర్-స్థాయి విఫలమైన స్థితులు మాత్రమే ప్రొవైడర్ బ్రేకర్‌ను ట్రిప్ చేయాలి:

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

సాధారణ ఖాతా/కీ/మోడల్ పొరపాట్ల కోసం మొత్తం-ప్రొవైడర్ బ్రేకర్‌ను ట్రిప్ చేయవద్దు, ఉదా: 401, 403, లేదా 429 కేసులు. అవి సాధారణంగా కనెక్షన్ కూల్‌డౌన్ లేదా మోడల్ లాక్‌ఔట్‌కు చెందుతాయి. ఒక సాధారణ API-కీ ప్రొవైడర్ 403 పునరావృతంగా పునరుద్ధరించబడాలి, ఇది ఒక టర్మినల్ ప్రొవైడర్/ఖాతా పొరపాటు అని వర్గీకరించబడకపోతే.

బ్రేకర్ ఆలస్య పునరుద్ధరణను ఉపయోగిస్తుంది, బ్యాక్‌గ్రౌండ్ టైమర్ కాదు. OPEN కాలం ముగిసినప్పుడు, getStatus(), canExecute(), మరియు getRetryAfterMs() వంటి చదువులు స్థితిని HALF_OPENగా పునరుద్ధరిస్తాయి, కాబట్టి డాష్‌బోర్డులు మరియు కాంబో అభ్యర్థన నిర్మాణాలు ఒక కాలం ముగిసిన ప్రొవైడర్‌ను ఎప్పటికీ మినహాయించవు.

కనెక్షన్ కూల్‌డౌన్

పరిధి: ఒక ప్రొవైడర్ కనెక్షన్/ఖాతా/కీ.

ఉద్దేశ్యం: ఒక చెడు కీ/ఖాతాను తాత్కాలికంగా మినహాయించడం, అదే ప్రొవైడర్ కోసం ఇతర కనెక్షన్లు అభ్యర్థనలను కొనసాగించడానికి అనుమతించడం.

అమలు:

  • రాయండి/అప్‌డేట్ మార్గం: src/sse/services/auth.ts::markAccountUnavailable()
  • ఖాతా ఎంపిక/ఫిల్టరింగ్: src/sse/services/auth.ts::getProviderCredentials...
  • కూల్‌డౌన్ లెక్కింపు: open-sse/services/accountFallback.ts::checkFallbackError()
  • సెట్టింగులు: src/lib/resilience/settings.ts

ప్రొవైడర్ కనెక్షన్లపై ముఖ్యమైన ఫీల్డ్స్:

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

ఖాతా ఎంపిక సమయంలో, ఒక కనెక్షన్ మినహాయించబడుతుంది:

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

కూల్‌డౌన్లు కూడా ఆలస్యంగా ఉంటాయి: rateLimitedUntil గతంలో ఉన్నప్పుడు, కనెక్షన్ మళ్లీ అర్హత పొందుతుంది. విజయవంతమైన ఉపయోగంలో, clearAccountError() testStatus, rateLimitedUntil, పొరపాటు ఫీల్డ్స్, మరియు backoffLevelను క్లియర్ చేస్తుంది.

డిఫాల్ట్ కనెక్షన్ కూల్‌డౌన్ ప్రవర్తన:

  • OAuth ప్రాథమిక కూల్‌డౌన్: 5s.
  • API-కీ ప్రాథమిక కూల్‌డౌన్: 3s.
  • API-కీ 429 అందుబాటులో ఉన్నప్పుడు అప్‌స్ట్రీమ్ తిరిగి ప్రయత్నం సూచనలను ( Retry-After, రీసెట్ హెడ్డర్లు, లేదా పార్సబుల్ రీసెట్ టెక్స్ట్) ప్రాధాన్యం ఇవ్వాలి.
  • పునరావృత పునరుద్ధరణ విఫలమైతే ఎక్స్‌పోనెన్షియల్ బ్యాకాఫ్‌ను ఉపయోగిస్తుంది:
baseCooldownMs * 2 ** failureIndex;

యాంటీ-థండరింగ్-హెర్డ్ గార్డ్ ఒకే కనెక్షన్‌పై సమకాలిక విఫలాలను కూల్‌డౌన్‌ను పునరావృతంగా పొడిగించడం లేదా backoffLevelను డబుల్-ఇంక్రిమెంట్ చేయడం నుండి నివారిస్తుంది.

టర్మినల్ స్థితులు కూల్‌డౌన్‌లు కాదు. banned, expired, మరియు credits_exhausted క్రెడెన్షియల్స్/సెట్టింగ్స్ మారడం లేదా ఒక ఆపరేటర్ వాటిని రీసెట్ చేయడం వరకు అందుబాటులో ఉండకూడదు. తాత్కాలిక కూల్‌డౌన్ స్థితితో టర్మినల్ స్థితులను మళ్లీ రాయవద్దు.

మోడల్ లాక్‌ఔట్

పరిధి: ప్రొవైడర్ + కనెక్షన్ + మోడల్.

ఉద్దేశ్యం: ఒక మోడల్ అందుబాటులో లేకపోతే లేదా ఆ కనెక్షన్ కోసం క్వోటా-పరిమితమైనప్పుడు మొత్తం కనెక్షన్‌ను అచ్ఛాదించడం నివారించండి.

ఉదాహరణలు:

  • ప్రతి-మోడల్ క్వోటా ప్రొవైడర్లు 429ను తిరిగి ఇస్తున్నాయి.
  • ఒక మిస్సింగ్ మోడల్ కోసం 404ను తిరిగి ఇస్తున్న స్థానిక ప్రొవైడర్లు.
  • ఎంపిక చేసిన గ్రోక్ మోడ్స్ వంటి ప్రొవైడర్-స్పెసిఫిక్ మోడ్/మోడల్ అనుమతి విఫలమవుతాయి.

మోడల్ లాక్‌ఔట్ open-sse/services/accountFallback.tsలో ఉంటుంది మరియు అదే కనెక్షన్ ఇతర మోడళ్లను కొనసాగించడానికి అనుమతిస్తుంది.

డీబగ్ మార్గదర్శకత్వం

  • ఒక ప్రొవైడర్ కోసం అన్ని కీలు మినహాయించబడితే, ప్రొవైడర్ బ్రేకర్ స్థితి మరియు ప్రతి కనెక్షన్ యొక్క rateLimitedUntil/testStatusను పరిశీలించండి.
  • రీసెట్ విండో తర్వాత ఒక ప్రొవైడర్ శాశ్వతంగా మినహాయించబడినట్లు కనిపిస్తే, కోడ్ getStatus()/canExecute()ను ఉపయోగించకుండా కచ్చితమైన stateను చదువుతున్నదా అని తనిఖీ చేయండి.
  • ఒక ప్రొవైడర్ కీ విఫలమైతే కానీ ఇతరులు పనిచేయాలి, ప్రొవైడర్ బ్రేకర్ కంటే కనెక్షన్ కూల్‌డౌన్‌ను ప్రాధాన్యం ఇవ్వండి.
  • ఒకే మోడల్ విఫలమైతే, కనెక్షన్ కూల్‌డౌన్ కంటే మోడల్ లాక్‌ఔట్‌ను ప్రాధాన్యం ఇవ్వండి.
  • ఒక స్థితి స్వీయ-పునరుద్ధరించాలి అంటే, దానికి భవిష్యత్తు టైమ్‌స్టాంప్/రీసెట్ టైమ్‌ఔట్ మరియు కాలం ముగిసిన స్థితిని పునరుద్ధరించే చదువు మార్గం ఉండాలి. శాశ్వత స్థితులు మాన్యువల్ క్రెడెన్షియల్ లేదా కాన్ఫిగరేషన్ మార్పులు అవసరం.

కీలక సంప్రదాయాలు

కోడ్ శైలి

  • 2 స్థలాలు, సెమికోలన్‌లు, డబుల్ కోట్స్, 100 అక్షరాల వెడల్పు, es5 ట్రైలింగ్ కమీలు (lint-staged ద్వారా Prettier ద్వారా అమలు చేయబడింది)
  • ఇంపోర్ట్స్: బాహ్య → అంతర్గత (@/, @omniroute/open-sse) → సంబంధిత
  • నామకరణం: ఫైళ్లు=camelCase/kebab, భాగాలు=PascalCase, స్థిరాంకాలు=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = ఎక్కడైనా పొరపాటు; no-explicit-any = open-sse/ మరియు tests/ లో హెచ్చరిక
  • TypeScript: strict: false, లక్ష్యం ES2022, మాడ్యూల్ esnext, రిజల్యూషన్ బండ్లర్. స్పష్టమైన రకాలపై ప్రాధాన్యత ఇవ్వండి.

డేటాబేస్

  • ఎప్పుడూ src/lib/db/ డొమైన్ మాడ్యూల్‌ల ద్వారా వెళ్లండి — ఎప్పుడూ మార్గాలు లేదా హ్యాండ్లర్‌లలో కచ్చితమైన SQL రాయవద్దు
  • ఎప్పుడూ src/lib/localDb.ts లో లాజిక్ జోడించవద్దు (మరలా-ఎక్స్‌పోర్ట్ పొర మాత్రమే)
  • ఎప్పుడూ localDb.ts నుండి బారెల్-ఇంపోర్ట్ చేయవద్దు — ప్రత్యేక db/ మాడ్యూల్‌లను ఇంపోర్ట్ చేయండి
  • DB సింగ్ల్టన్: getDbInstance() నుండి src/lib/db/core.ts (WAL జర్నలింగ్)
  • మైగ్రేషన్స్: src/lib/db/migrations/ — వెర్షన్డ్ SQL ఫైళ్లు, ఐడెంపొటెంట్, లావాదేవీలలో నడుస్తాయి

పొరపాట్ల నిర్వహణ

  • ప్రత్యేక పొరపాట్ల రకాలతో try/catch, pino కాంటెక్స్ట్‌తో లాగ్ చేయండి
  • SSE స్ట్రీమ్స్‌లో పొరపాట్లను ఎప్పుడూ మింగవద్దు — శుభ్రపరచడానికి అబార్ట్ సంకేతాలను ఉపయోగించండి
  • సరైన HTTP స్థితి కోడ్‌లను తిరిగి ఇవ్వండి (4xx/5xx)

భద్రత

  • ఎప్పుడూ eval(), new Function(), లేదా సూచించిన eval ఉపయోగించవద్దు
  • Zod స్కీమాలతో అన్ని ఇన్‌పుట్‌లను ధృవీకరించండి
  • విశ్రాంతిలో క్రెడెన్షియల్స్‌ను ఎన్‌క్రిప్ట్ చేయండి (AES-256-GCM)
  • అప్‌స్ట్రీమ్ హెడ్డర్ డెనైల్‌స్టు: src/shared/constants/upstreamHeaders.ts — సానిటైజ్, Zod స్కీమాలు, మరియు యూనిట్ పరీక్షలను సవరించినప్పుడు సమానంగా ఉంచండి
  • ప్రజా అప్‌స్ట్రీమ్ క్రెడెన్షియల్స్ (Gemini/Antigravity/Windsurf-శైలీ OAuth client_id/secret + Firebase వెబ్ కీలు ప్రజా CLIs నుండి తీసుకోబడినవి): MUST resolvePublicCred() ద్వారా ఎంబెడ్ చేయాలి open-sse/utils/publicCreds.ts — ఎప్పుడూ స్ట్రింగ్ లిటరల్స్‌గా కాదు. తప్పనిసరిగా నమూనా కోసం docs/security/PUBLIC_CREDS.md చూడండి.
  • పొరపాటు ప్రతిస్పందనలు (HTTP / SSE / executor / MCP హ్యాండ్లర్): MUST buildErrorBody() లేదా sanitizeErrorMessage() ద్వారా మార్గం చేయాలి open-sse/utils/error.ts — ఎప్పుడూ కచ్చితమైన err.stack లేదా err.message ను ప్రతిస్పందన శరీరంలో ఉంచవద్దు. docs/security/ERROR_SANITIZATION.md చూడండి.
  • చర shell కమాండ్లు వేరియబుల్స్ నుండి నిర్మించబడినవి: exec()/spawn() ను కాల్ చేసినప్పుడు, రన్‌టైమ్ విలువలను అవసరమైన స్క్రిప్ట్‌తో, env ఎంపిక ద్వారా పంపండి (సెల్-ఎస్కేప్ ఆటోమేటిక్‌గా) — ఎప్పుడూ అనుమానాస్పద/బాహ్య మార్గాలను స్క్రిప్ట్ శరీరంలో స్ట్రింగ్-ఇంటర్‌పోలేట్ చేయవద్దు. సూచన: src/mitm/cert/install.ts::updateNssDatabases.
  • సురక్షిత-ద్వారా-డిఫాల్ట్ లైబ్రరీలు (tldrsec/awesome-secure-defaults): కొత్త భద్రత-సున్నితమైన ఉపరితలాలను జోడించినప్పుడు Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink పై ప్రాధాన్యత ఇవ్వండి.

సాధారణ సవరణ దృశ్యాలు

కొత్త ప్రొవైడర్‌ను జోడించడం

  1. src/shared/constants/providers.ts లో నమోదు చేయండి (లోడ్ సమయంలో Zod-ధృవీకరించబడింది)
  2. కస్టమ్ లాజిక్ అవసరమైతే open-sse/executors/ లో ఎక్సిక్యూటర్‌ను జోడించండి ( BaseExecutor ను విస్తరించండి)
  3. non-OpenAI ఫార్మాట్ అయితే open-sse/translator/ లో అనువాదకుడిని జోడించండి
  4. OAuth ఆధారిత అయితే src/lib/oauth/constants/oauth.ts లో OAuth కాన్ఫిగరేషన్‌ను జోడించండి — అప్‌స్ట్రీమ్ CLI ప్రజా client_id/secret ను పంపిస్తే, resolvePublicCred() ద్వారా ఎంబెడ్ చేయండి ( docs/security/PUBLIC_CREDS.md చూడండి), ఎప్పుడూ లిటరల్‌గా కాదు
  5. open-sse/config/providerRegistry.ts లో మోడల్‌లను నమోదు చేయండి
  6. tests/unit/ లో పరీక్షలు రాయండి (మీరు కొత్త ఎంబెడెడ్ డిఫాల్ట్‌ను జోడించినట్లయితే publicCreds ఆకారాన్ని ధృవీకరించండి)

కొత్త API మార్గాన్ని జోడించడం

  1. src/app/api/v1/your-route/ కింద డైరెక్టరీని సృష్టించండి
  2. GET/POST హ్యాండ్లర్‌లతో route.ts సృష్టించండి
  3. నమూనాను అనుసరించండి: CORS → Zod శరీర ధృవీకరణ → ఐచ్ఛిక ఆథ్ → హ్యాండ్లర్ డెలిగేషన్
  4. హ్యాండ్లర్ open-sse/handlers/ లో ఉంటుంది (అక్కడ నుండి ఇంపోర్ట్ చేయండి, ఇన్‌లైన్‌లో కాదు)
  5. పొరపాటు ప్రతిస్పందనలు buildErrorBody() / errorResponse() ను ఉపయోగిస్తాయి open-sse/utils/error.ts (ఆటో-సానిటైజ్డ్ — ఎప్పుడూ err.stack లేదా err.message ను శరీరంలో కచ్చితంగా ఉంచవద్దు). docs/security/ERROR_SANITIZATION.md చూడండి.
  6. పరీక్షలను జోడించండి — పొరపాటు ప్రతిస్పందనలు స్టాక్ ట్రేస్‌లను లీక్ చేయవద్దు అని కనీసం ఒక ధృవీకరణను కలిగి ఉండాలి (!body.error.message.includes("at /"))

కొత్త DB మాడ్యూల్‌ను జోడించడం

  1. src/lib/db/yourModule.ts ను సృష్టించండి — ./core.ts నుండి getDbInstance ను ఇంపోర్ట్ చేయండి
  2. మీ డొమైన్ పట్టిక(లు) కోసం CRUD ఫంక్షన్‌లను ఎక్స్‌పోర్ట్ చేయండి
  3. కొత్త పట్టికలు అవసరమైతే src/lib/db/migrations/ లో మైగ్రేషన్‌ను జోడించండి
  4. src/lib/localDb.ts నుండి మళ్లీ-ఎక్స్‌పోర్ట్ చేయండి (మళ్లీ-ఎక్స్‌పోర్ట్ జాబితాలో మాత్రమే జోడించండి)
  5. పరీక్షలు రాయండి

కొత్త MCP టూల్‌ను జోడించడం

  1. Zod ఇన్‌పుట్ స్కీమా + అసింక్ హ్యాండ్లర్‌తో open-sse/mcp-server/tools/ లో టూల్ నిర్వచనాన్ని జోడించండి
  2. టూల్ సెట్‌లో నమోదు చేయండి ( createMcpServer() ద్వారా వైర్ చేయబడింది)
  3. సరైన స్కోప్‌లకు కేటాయించండి
  4. పరీక్షలు రాయండి (టూల్ ఆహ్వానం mcp_audit పట్టికకు లాగ్ చేయబడింది)

కొత్త A2A నైపుణ్యాన్ని జోడించడం

  1. src/lib/a2a/skills/ లో నైపుణ్యాన్ని సృష్టించండి (5 ఇప్పటికే ఉన్నాయి: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. నైపుణ్యం పని సందర్భాన్ని (సందేశాలు, మెటాడేటా) పొందుతుంది → నిర్మిత ఫలితాన్ని తిరిగి ఇస్తుంది
  3. src/lib/a2a/taskExecution.ts లో A2A_SKILL_HANDLERS లో నమోదు చేయండి
  4. src/app/.well-known/agent.json/route.ts లో ఎక్స్‌పోజ్ చేయండి (ఏజెంట్ కార్డ్)
  5. tests/unit/ లో పరీక్షలు రాయండి
  6. docs/frameworks/A2A-SERVER.md నైపుణ్య పట్టికలో డాక్యుమెంట్ చేయండి

కొత్త క్లౌడ్ ఏజెంట్‌ను జోడించడం

  1. CloudAgentBase ను విస్తరించే src/lib/cloudAgent/agents/ లో ఏజెంట్ క్లాస్‌ను సృష్టించండి (3 ఇప్పటికే ఉన్నాయి: codex-cloud, devin, jules)
  2. createTask, getStatus, approvePlan, sendMessage, listSources ను అమలు చేయండి
  3. src/lib/cloudAgent/registry.ts లో నమోదు చేయండి
  4. అవసరమైతే OAuth/క్రెడెన్షియల్స్ నిర్వహణను జోడించండి (src/lib/oauth/providers/)
  5. పరీక్షలు + docs/frameworks/CLOUD_AGENT.md లో డాక్యుమెంట్ చేయండి

కొత్త గార్డ్రెయిల్ / ఎవాల్ / నైపుణ్యం / వెబ్‌హుక్ ఈవెంట్‌ను జోడించడం

  • గార్డ్రెయిల్: src/lib/guardrails/ → డాక్స్: docs/security/GUARDRAILS.md
  • ఎవాల్ సూట్: src/lib/evals/ → డాక్స్: docs/frameworks/EVALS.md
  • నైపుణ్యం (సాండ్‌బాక్స్): src/lib/skills/ → డాక్స్: docs/frameworks/SKILLS.md
  • వెబ్‌హుక్ ఈవెంట్: src/lib/webhookDispatcher.ts → డాక్స్: docs/frameworks/WEBHOOKS.md

సూచన డాక్యుమెంటేషన్

ఏదైనా అసాధారణ మార్పు కోసం, మొదట సరిపోయే లోతైన పరిశీలనను చదవండి:

ప్రాంతం డాక్యుమెంట్
రెపో నావిగేషన్ docs/architecture/REPOSITORY_MAP.md
నిర్మాణం docs/architecture/ARCHITECTURE.md
ఇంజనీరింగ్ సూచిక docs/architecture/CODEBASE_DOCUMENTATION.md
ఆటో-కాంబో (9-ఫ్యాక్టర్ స్కోరింగ్, 14 వ్యూహాలు) docs/routing/AUTO-COMBO.md
ప్రతిఘటన (3 యంత్రాలు) docs/architecture/RESILIENCE_GUIDE.md
కారణం పునరావృతం docs/routing/REASONING_REPLAY.md
నైపుణ్యాల ఫ్రేమ్‌వర్క్ docs/frameworks/SKILLS.md
మెమరీ సిస్టమ్ (FTS5 + Qdrant) docs/frameworks/MEMORY.md
క్లౌడ్ ఏజెంట్లు docs/frameworks/CLOUD_AGENT.md
గార్డ్రైల్స్ (PII / ఇంజెక్షన్ / విజన్) docs/security/GUARDRAILS.md
పబ్లిక్ అప్‌స్ట్రీమ్ క్రెడెన్షియల్స్ (జెమినీ/ఇతరాలు) docs/security/PUBLIC_CREDS.md
పొరపాటు సందేశం శుభ్రపరచడం docs/security/ERROR_SANITIZATION.md
ఇవాల్స్ docs/frameworks/EVALS.md
అనుగుణత / ఆడిట్ docs/security/COMPLIANCE.md
వెబ్‌హుక్‌లు docs/frameworks/WEBHOOKS.md
అనుమతి పైప్‌లైన్ docs/architecture/AUTHZ_GUIDE.md
స్టెల్త్ (TLS / ఫింగర్‌ప్రింట్) docs/security/STEALTH_GUIDE.md
ఏజెంట్ ప్రోటోకాల్‌లు (A2A / ACP / క్లౌడ్) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP సర్వర్ docs/frameworks/MCP-SERVER.md
A2A సర్వర్ docs/frameworks/A2A-SERVER.md
API సూచిక + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
ప్రొవైడర్ కాటలాగ్ (ఆటో-జనరేటెడ్) docs/reference/PROVIDER_REFERENCE.md
విడుదల ప్రవాహం docs/ops/RELEASE_CHECKLIST.md

పరీక్ష

ఏమిటి ఆదేశం
యూనిట్ పరీక్షలు npm run test:unit
ఒక్క ఫైల్ node --import tsx/esm --test tests/unit/file.test.ts
విటెస్ట్ (MCP, autoCombo) npm run test:vitest
E2E (ప్లేవ్రైట్) npm run test:e2e
ప్రోటోకాల్ E2E (MCP+A2A) npm run test:protocols:e2e
పర్యావరణం npm run test:ecosystem
కవర్ గేట్ npm run test:coverage (75/75/75/70 — స్టేట్మెంట్స్/లైన్స్/ఫంక్షన్స్/బ్రాంచెస్)
కవర్ నివేదిక npm run coverage:report

PR నియమం: మీరు src/, open-sse/, electron/, లేదా bin/ లో ఉత్పత్తి కోడ్ మార్చినట్లయితే, మీరు అదే PR లో పరీక్షలను చేర్చాలి లేదా నవీకరించాలి.

పరీక్షా పొర ప్రాధాన్యత: యూనిట్ మొదట → సమగ్రత (బహుళ-మాడ్యూల్ లేదా DB స్థితి) → e2e (UI/కార్యప్రవాహం మాత్రమే). బగ్ పునరావృతాలను స్వయంచాలక పరీక్షలుగా కోడ్ చేయండి, ఫిక్స్ కు ముందు లేదా దాని పక్కన.

కోపిలాట్ కవర్ విధానం: PR ఉత్పత్తి కోడ్ మార్చినప్పుడు మరియు కవర్ 75% (స్టేట్మెంట్స్/లైన్స్/ఫంక్షన్స్) లేదా 70% (బ్రాంచెస్) కంటే తక్కువగా ఉంటే, కేవలం నివేదించకండి — పరీక్షలను చేర్చండి లేదా నవీకరించండి, కవర్ గేట్ ను మళ్లీ నడపండి, తరువాత ధృవీకరణ కోసం అడగండి. PR నివేదికలో నడిపించిన ఆదేశాలు, మారిన పరీక్ష ఫైళ్లు, మరియు తుది కవర్ ఫలితం చేర్చండి.

గిట్ వర్క్‌ఫ్లో

# ప్రధానానికి నేరుగా కమీట్ చేయకండి
git checkout -b feat/your-feature
git commit -m "feat: describe your change"
git push -u origin feat/your-feature

బ్రాంచ్ ప్రిఫిక్స్‌లు: feat/, fix/, refactor/, docs/, test/, chore/

కమీట్ ఫార్మాట్ (సాంప్రదాయ కమీట్లు): feat(db): add circuit breaker — స్కోప్స్: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

హస్కీ హుక్స్:

  • ప్రి-కమీట్: lint-staged + check-docs-sync + check:any-budget:t11
  • ప్రి-పుష్: npm run test:unit

పరిసరాలు

  • రన్‌టైమ్: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES మాడ్యూల్స్
  • TypeScript: 5.9+, లక్ష్యం ES2022, మాడ్యూల్ esnext, రిజల్యూషన్ బండ్లర్
  • పాత్ అలియాసులు: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • డిఫాల్ట్ పోర్ట్: 20128 (API + డాష్‌బోర్డ్ ఒకే పోర్ట్‌లో)
  • డేటా డైరెక్టరీ: DATA_DIR env var, డిఫాల్ట్ గా ~/.omniroute/
  • కీ env vars: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • సెటప్: cp .env.example .env తరువాత JWT_SECRET (openssl rand -base64 48) మరియు API_KEY_SECRET (openssl rand -hex 32) ను ఉత్పత్తి చేయండి

కఠిన నియమాలు

  1. రహస్యాలు లేదా క్రెడెన్షియల్స్‌ను ఎప్పుడూ కమీట్ చేయకండి
  2. localDb.ts లో లాజిక్‌ను ఎప్పుడూ చేర్చకండి
  3. eval() / new Function() / సూచించిన eval ను ఎప్పుడూ ఉపయోగించకండి
  4. main కు నేరుగా కమీట్ చేయకండి
  5. మార్గాలలో ముడి SQL ను ఎప్పుడూ రాయకండి — src/lib/db/ మాడ్యూల్స్‌ను ఉపయోగించండి
  6. SSE స్ట్రీమ్స్‌లో పొరపాట్లను ఎప్పుడూ మౌనంగా ఆమోదించకండి
  7. ఎప్పుడూ Zod స్కీమాలతో ఇన్‌పుట్‌లను ధృవీకరించండి
  8. ఉత్పత్తి కోడ్ మార్చినప్పుడు ఎప్పుడూ పరీక్షలను చేర్చండి
  9. కవర్ ≥75% (స్టేట్మెంట్స్, లైన్స్, ఫంక్షన్స్) / ≥70% (బ్రాంచెస్) గా ఉండాలి. ప్రస్తుత కొలత: ~82%.
  10. స్పష్టమైన ఆపరేటర్ ఆమోదం లేకుండా హస్కీ హుక్స్‌ను ఎప్పుడూ దాటించకండి (--no-verify, --no-gpg-sign).
  11. పబ్లిక్ అప్‌స్ట్రీమ్ OAuth client_id/secret లేదా Firebase వెబ్ కీలు స్ట్రింగ్ లిటరల్స్‌గా ఎప్పుడూ ఎంబెడ్ చేయకండి — ఎప్పుడూ resolvePublicCred() ద్వారా వెళ్లండి (open-sse/utils/publicCreds.ts). చూడండి docs/security/PUBLIC_CREDS.md.
  12. HTTP / SSE / ఎగ్జిక్యూటర్ ప్రతిస్పందనల్లో ముడి err.stack / err.message ను ఎప్పుడూ తిరిగి ఇవ్వకండి — ఎప్పుడూ buildErrorBody() లేదా sanitizeErrorMessage() ద్వారా మార్గం చేయండి (open-sse/utils/error.ts). చూడండి docs/security/ERROR_SANITIZATION.md.
  13. exec()/spawn() కు పంపబడిన షెల్ స్క్రిప్ట్స్‌లో బాహ్య పాత్‌లు లేదా రన్‌టైమ్ విలువలను ఎప్పుడూ స్ట్రింగ్-ఇంటర్‌పోలేట్ చేయకండి — బదులుగా env ఎంపిక ద్వారా పంపండి. సూచన: src/mitm/cert/install.ts::updateNssDatabases.
  14. కోడ్‌QL / సీక్రెట్-స్కానింగ్ అలర్ట్‌ను ఎప్పుడూ విస్మరించకండి (a) పై ప్యాటర్న్ డాక్స్‌ను మొదట తనిఖీ చేయడం ద్వారా సహాయాన్ని చూడండి, మరియు (b) విస్మరణ వ్యాఖ్యలో సాంకేతిక న్యాయాన్ని నమోదు చేయండి. ప్రీసిడెంట్: js/stack-trace-exposure ఇప్పటికే sanitizeErrorMessage() ద్వారా మార్గం చేయబడిన కాల్‌సైట్‌లపై లేవనెత్తబడింది ఇది ఒక తెలిసిన కోడ్‌QL పరిమితి (అనుకూల శుభ్రతలు గుర్తించబడలేదు) — docs/security/ERROR_SANITIZATION.md ను సూచిస్తూ false positive గా విస్మరించండి.
  15. isLocalOnlyPath() వర్గీకరణ లేకుండా పిల్ల ప్రాసెస్‌లను స్పాన్ చేసే మార్గాలను ఎప్పుడూ ప్రదర్శించకండి (/api/mcp/, /api/cli-tools/runtime/) src/server/authz/routeGuard.ts లో. లూప్‌బ్యాక్ అమలు ఏదైనా ఆథ్ తనిఖీకి ముందు నిర్దిష్టంగా జరుగుతుంది — టన్నెల్ ద్వారా లీకైన JWT ప్రాసెస్ స్పాన్‌ను ప్రేరేపించలదు. చూడండి docs/security/ROUTE_GUARD_TIERS.md.
  16. AI అసిస్టెంట్, LLM లేదా ఆటోమేషన్ ఖాతాకు క్రెడిట్ ఇచ్చే Co-Authored-By ట్రెయిలర్‌లను commit సందేశాలలో ఎప్పటికీ చేర్చకండి (ఉదా. "Claude", "GPT", "Copilot", "Bot" కలిగిన పేర్లు; anthropic.com / openai.com / bot-యాజమాన్యం గల noreply.github.com చిరునామాల వద్ద ఇమెయిల్‌లు). ఇటువంటి ట్రెయిలర్‌లు GitHub లో bot ఖాతాకు commit attribution ను రూట్ చేస్తాయి, PR చరిత్రలో నిజమైన రచయిత (diegosouzapw) ను దాస్తాయి. మానవ సహకారులు — upstream PR రచయితలు మరియు OmniRoute కు port అవుతున్న issue రిపోర్టర్‌లతో సహా — ప్రామాణిక Co-authored-by: Name <email> ట్రెయిలర్‌లతో క్రెడిట్ పొందవచ్చు మరియు పొందాలి; upstream-port పనిప్రవాహాలు (/port-upstream-features, /port-upstream-issues) దీనిపై ఆధారపడి ఉన్నాయి.
Reference in New Issue View Git Blame Copy Permalink