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
2d321e1f52ec00d16ad016edf59cd406cd031f98
OmniRoute/docs/i18n/fa/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

35 KiB
Raw Blame History

CLAUDE.md (فارسی)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇫🇮 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 · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

این فایل راهنمایی برای Claude Code (claude.ai/code) هنگام کار با کد در این مخزن ارائه می‌دهد.

شروع سریع

npm install                    # نصب وابستگی‌ها (به‌طور خودکار .env را از .env.example تولید می‌کند)
npm run dev                    # سرور توسعه در http://localhost:20128
npm run build                  # ساخت تولید (نسخه مستقل Next.js 16)
npm run lint                   # ESLint (انتظار می‌رود 0 خطا؛ هشدارها از قبل وجود دارند)
npm run typecheck:core         # بررسی TypeScript (باید تمیز باشد)
npm run typecheck:noimplicit:core  # بررسی سخت‌گیرانه (بدون any ضمنی)
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 Routes src/app/api/v1/ روتر برنامه Next.js — نقاط ورودی
Handlers open-sse/handlers/ پردازش درخواست (چت، جاسازی‌ها و غیره)
Executors open-sse/executors/ ارسال HTTP خاص ارائه‌دهنده
Translators open-sse/translator/ تبدیل فرمت (OpenAI↔Claude↔Gemini)
Transformer open-sse/transformer/ API پاسخ‌ها ↔ تکمیل‌های چت
Services open-sse/services/ مسیریابی ترکیبی، محدودیت‌های نرخ، کش و غیره
Database src/lib/db/ ماژول‌های دامنه SQLite (بیش از 45 فایل، 55 مهاجرت)
Domain/Policy src/domain/ موتور سیاست، قوانین هزینه، منطق بازگشت
MCP Server open-sse/mcp-server/ 37 ابزار (30 پایه + 3 حافظه + 4 مهارت)، 3 حمل و نقل، ~13 دامنه
A2A Server src/lib/a2a/ پروتکل عامل JSON-RPC 2.0
Skills src/lib/skills/ چارچوب مهارت قابل گسترش
Memory src/lib/memory/ حافظه گفتگوی پایدار

مونوریپو: src/ (برنامه Next.js 16)، open-sse/ (فضای کار موتور استریمینگ)، electron/ (برنامه دسکتاپ)، tests/، bin/ (نقطه ورودی CLI).

خط لوله درخواست

Client → /v1/chat/completions (مسیر Next.js)
  → CORS → اعتبارسنجی Zod → احراز هویت؟ → بررسی سیاست → محافظت در برابر تزریق پرامپت
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → بررسی کش → محدودیت نرخ → مسیریابی ترکیبی؟
      → resolveComboTargets() → handleSingleModel() برای هر هدف
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → ترجمه پاسخ → جریان SSE یا JSON
    → اگر API Responses: responsesTransformer.ts TransformStream

مسیرهای API الگوی ثابتی را دنبال می‌کنند: Route → CORS preflight → اعتبارسنجی بدنه Zod → احراز هویت اختیاری (extractApiKey/isValidApiKey) → اجرای سیاست کلید API → واگذاری Handler (open-sse). هیچ middleware جهانی Next.js وجود ندارد — قطع ارتباط خاص مسیر است.

مسیریابی ترکیبی (open-sse/services/combo.ts): 14 استراتژی (اولویت، وزن‌دار، پر کردن اول، گردشی، P2C، تصادفی، کمترین استفاده، بهینه‌سازی هزینه، آگاه به بازنشانی، تصادفی سخت، خودکار، lkgp، بهینه‌سازی زمینه، انتقال زمینه). هر هدف handleSingleModel() را فراخوانی می‌کند که handleChatCore() را با مدیریت خطا برای هر هدف و بررسی‌های مدار شکن احاطه می‌کند. برای نمره‌دهی Auto-Combo با 9 عامل به docs/routing/AUTO-COMBO.md و برای 3 لایه تاب‌آوری به docs/architecture/RESILIENCE_GUIDE.md مراجعه کنید.

وضعیت زمان اجرای تاب‌آوری

OmniRoute سه مکانیزم موقت شکست مرتبط اما متمایز دارد. دامنه آن‌ها را هنگام اشکال‌زدایی رفتار مسیریابی جدا نگه دارید. برای یک نمای کلی، به نقشه تاب‌آوری 3 لایه (منبع: docs/diagrams/resilience-3layers.mmd) مراجعه کنید.

مدار شکن ارائه‌دهنده

دامنه: کل ارائه‌دهنده، به عنوان مثال glm، openai، anthropic.

هدف: متوقف کردن ارسال ترافیک به یک ارائه‌دهنده که به طور مکرر در سطح upstream/service شکست می‌خورد، تا یک ارائه‌دهنده ناسالم باعث کند شدن هر درخواست نشود.

پیاده‌سازی:

  • کلاس اصلی: 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 باید در صورت موجود بودن، به نشانه‌های تلاش مجدد upstream (Retry-After، هدرهای بازنشانی، یا متن بازنشانی قابل تجزیه) ترجیح داده شود.
  • شکست‌های قابل بازیابی مکرر از بازگشت نمایی استفاده می‌کنند:
baseCooldownMs * 2 ** failureIndex;

محافظ ضد جمع‌آوری همزمان از شکست‌های همزمان در یک اتصال جلوگیری می‌کند که به طور مکرر خنک‌سازی را تمدید یا backoffLevel را دو برابر کند.

وضعیت‌های نهایی خنک‌سازی نیستند. banned، expired و credits_exhausted به طور خاص برای عدم دسترسی تا زمانی که اعتبارنامه‌ها/تنظیمات تغییر کنند یا یک اپراتور آن‌ها را بازنشانی کند، طراحی شده‌اند. وضعیت‌های نهایی را با وضعیت خنک‌سازی موقتی بازنویسی نکنید.

قفل مدل

دامنه: ارائه‌دهنده + اتصال + مدل.

هدف: جلوگیری از غیرفعال کردن یک اتصال کامل زمانی که فقط یک مدل در دسترس نیست یا برای آن اتصال محدودیت سهمیه دارد.

مثال‌ها:

  • ارائه‌دهندگان سهمیه به ازای مدل که 429 برمی‌گردانند.
  • ارائه‌دهندگان محلی که برای یک مدل گم‌شده 404 برمی‌گردانند.
  • شکست‌های مجوز مدل/حالت خاص ارائه‌دهنده مانند حالت‌های Grok انتخاب شده.

قفل مدل در open-sse/services/accountFallback.ts زندگی می‌کند و به همان اتصال اجازه می‌دهد تا به خدمت‌رسانی به مدل‌های دیگر ادامه دهد.

راهنمای اشکال‌زدایی

  • اگر همه کلیدها برای یک ارائه‌دهنده رد شده‌اند، وضعیت مدار شکن ارائه‌دهنده و rateLimitedUntil/testStatus هر اتصال را بررسی کنید.
  • اگر یک ارائه‌دهنده پس از پنجره بازنشانی به طور دائمی حذف شده به نظر می‌رسد، بررسی کنید که آیا کد به جای استفاده از getStatus()/canExecute()، state خام را می‌خواند.
  • اگر یک کلید ارائه‌دهنده شکست بخورد اما دیگران باید کار کنند، خنک‌سازی اتصال را به مدار شکن ارائه‌دهنده ترجیح دهید.
  • اگر فقط یک مدل شکست بخورد، قفل مدل را به خنک‌سازی اتصال ترجیح دهید.
  • اگر یک وضعیت باید خود را بازیابی کند، باید یک زمان‌سنج آینده/زمان بازنشانی و یک مسیر خواندن داشته باشد که وضعیت منقضی شده را تازه کند. وضعیت‌های دائمی نیاز به تغییرات دستی در اعتبارنامه یا پیکربندی دارند.

کنوانسیون‌های کلیدی

سبک کد

  • ۲ فاصله، نقطه‌ویرگول‌ها، نقل‌قول‌های دوتایی، عرض ۱۰۰ کاراکتر، کاماهای انتهایی 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، رزولوشن bundler. نوع‌های صریح را ترجیح دهید.

پایگاه داده

  • همیشه از ماژول‌های دامنه src/lib/db/ عبور کنید — هرگز SQL خام در مسیرها یا هندلرها ننویسید
  • هرگز منطق را به src/lib/localDb.ts اضافه نکنید (فقط لایه‌ی مجدد صادرات)
  • هرگز از localDb.ts به صورت بارل وارد نکنید — به جای آن ماژول‌های خاص db/ را وارد کنید
  • DB singleton: getDbInstance() از src/lib/db/core.ts (ثبت‌نام WAL)
  • مهاجرت‌ها: src/lib/db/migrations/ — فایل‌های SQL نسخه‌بندی شده، ایپیدموت، اجرا در تراکنش‌ها

مدیریت خطا

  • try/catch با نوع‌های خطای خاص، ثبت با زمینه pino
  • هرگز خطاها را در جریان‌های SSE نبلعید — از سیگنال‌های ابطال برای تمیزکاری استفاده کنید
  • کدهای وضعیت HTTP مناسب را برگردانید (۴xx/۵xx)

امنیت

  • هرگز از eval()، new Function()، یا eval ضمنی استفاده نکنید
  • تمام ورودی‌ها را با طرح‌های Zod اعتبارسنجی کنید
  • اعتبارنامه‌ها را در حالت استراحت رمزگذاری کنید (AES-256-GCM)
  • لیست رد هدرهای upstream: src/shared/constants/upstreamHeaders.ts — هنگام ویرایش، sanitize، طرح‌های Zod و تست‌های واحد را هم‌راستا نگه دارید
  • اعتبارنامه‌های عمومی upstream (client_id/secret OAuth به سبک Gemini/Antigravity/Windsurf + کلیدهای وب Firebase استخراج شده از CLI‌های عمومی): باید از طریق resolvePublicCred() از open-sse/utils/publicCreds.ts جاسازی شوند — هرگز به عنوان رشته‌های ادبی. به docs/security/PUBLIC_CREDS.md برای الگوی الزامی مراجعه کنید.
  • پاسخ‌های خطا (HTTP / SSE / executor / MCP handler): باید از طریق buildErrorBody() یا sanitizeErrorMessage() از open-sse/utils/error.ts مسیریابی شوند — هرگز err.stack یا err.message خام را در بدنه پاسخ قرار ندهید. به docs/security/ERROR_SANITIZATION.md مراجعه کنید.
  • دستورات شل ساخته شده از متغیرها: هنگام فراخوانی 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/ اگر منطق سفارشی نیاز است، executor اضافه کنید (از BaseExecutor گسترش دهید)
  3. در open-sse/translator/ اگر فرمت غیر OpenAI است، مترجم اضافه کنید
  4. در src/lib/oauth/constants/oauth.ts اگر مبتنی بر OAuth است، پیکربندی OAuth را اضافه کنید — اگر CLI upstream یک 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. route.ts را با هندلرهای GET/POST ایجاد کنید
  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 را ایجاد کنید — getDbInstance را از ./core.ts وارد کنید
  2. توابع CRUD را برای جدول(های) دامنه خود صادر کنید
  3. در src/lib/db/migrations/ اگر جداول جدید نیاز است، مهاجرت اضافه کنید
  4. از src/lib/localDb.ts مجدداً صادرات کنید (فقط به لیست مجدد صادرات اضافه کنید)
  5. تست بنویسید

افزودن یک ابزار MCP جدید

  1. تعریف ابزار را در open-sse/mcp-server/tools/ با طرح ورودی Zod + هندلر async اضافه کنید
  2. در مجموعه ابزار ثبت‌نام کنید (از طریق createMcpServer() متصل شده)
  3. به دامنه(های) مناسب اختصاص دهید
  4. تست بنویسید (فراخوانی ابزار در جدول mcp_audit ثبت می‌شود)

افزودن یک مهارت A2A جدید

  1. مهارت را در src/lib/a2a/skills/ ایجاد کنید (۵ مورد قبلاً وجود دارد: smart-routing، quota-management، provider-discovery، cost-analysis، health-report)
  2. مهارت زمینه وظیفه را دریافت می‌کند (پیام‌ها، متاداده) → نتیجه ساختاری را برمی‌گرداند
  3. در A2A_SKILL_HANDLERS در src/lib/a2a/taskExecution.ts ثبت‌نام کنید
  4. در src/app/.well-known/agent.json/route.ts (کارت عامل) نمایان کنید
  5. در tests/unit/ تست بنویسید
  6. در جدول مهارت در docs/frameworks/A2A-SERVER.md مستند کنید

افزودن یک عامل ابری جدید

  1. کلاس عامل را در src/lib/cloudAgent/agents/ ایجاد کنید که از CloudAgentBase گسترش یافته باشد (۳ مورد قبلاً وجود دارد: 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

افزودن یک Guardrail / Eval / Skill / رویداد Webhook جدید

  • Guardrail: src/lib/guardrails/ → مستندات: docs/security/GUARDRAILS.md
  • مجموعه Eval: src/lib/evals/ → مستندات: docs/frameworks/EVALS.md
  • مهارت (sandbox): src/lib/skills/ → مستندات: docs/frameworks/SKILLS.md
  • رویداد Webhook: src/lib/webhookDispatcher.ts → مستندات: docs/frameworks/WEBHOOKS.md

مستندات مرجع

برای هر تغییر غیر جزئی، ابتدا عمیقاً به مستندات مربوطه مراجعه کنید:

حوزه مستند
ناوبری مخزن docs/architecture/REPOSITORY_MAP.md
معماری docs/architecture/ARCHITECTURE.md
مرجع مهندسی docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (امتیازدهی 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
اعتبارنامه‌های عمومی بالادستی (Gemini/etc.) 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 / Cloud) 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
Vitest (MCP، autoCombo) npm run test:vitest
E2E (Playwright) 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/جریان کار). تولید باگ‌ها را به عنوان تست‌های خودکار قبل یا همزمان با رفع مشکل کدگذاری کنید.

سیاست پوشش Copilot: وقتی یک PR کد تولید را تغییر می‌دهد و پوشش زیر 75% (بیانیه‌ها/خطوط/توابع) یا 70% (شاخه‌ها) است، فقط گزارش ندهید — تست‌ها را اضافه یا به‌روزرسانی کنید، دروازه پوشش را دوباره اجرا کنید، سپس درخواست تأیید کنید. دستورات اجرا شده، فایل‌های تست تغییر یافته و نتیجه نهایی پوشش را در گزارش PR شامل کنید.

جریان کار Git

# هرگز مستقیماً به main کامیت نکنید
git checkout -b feat/your-feature
git commit -m "feat: تغییرات خود را توصیف کنید"
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

هوک‌های Husky:

  • pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
  • pre-push: 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، به طور پیش‌فرض به ~/.omniroute/
  • متغیرهای کلیدی محیط: 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. هرگز هوک‌های Husky را بدون تأیید صریح اپراتور دور نزنید (--no-verify, --no-gpg-sign).
  11. هرگز کلیدهای عمومی OAuth client_id/secret یا کلیدهای Firebase Web را به عنوان رشته‌های ادبی جاسازی نکنید — همیشه از resolvePublicCred() (open-sse/utils/publicCreds.ts) استفاده کنید. به docs/security/PUBLIC_CREDS.md مراجعه کنید.
  12. هرگز err.stack / err.message خام را در پاسخ‌های HTTP / SSE / executor برنگردانید — همیشه از buildErrorBody() یا sanitizeErrorMessage() (open-sse/utils/error.ts) استفاده کنید. به docs/security/ERROR_SANITIZATION.md مراجعه کنید.
  13. هرگز مسیرهای خارجی یا مقادیر زمان اجرا را به صورت رشته‌ای در اسکریپت‌های شل که به exec()/spawn() منتقل می‌شوند، جاسازی نکنید — به جای آن از گزینه env استفاده کنید. مرجع: src/mitm/cert/install.ts::updateNssDatabases.
  14. هرگز یک هشدار CodeQL / Secret-Scanning را بدون (الف) بررسی الگوهای مستندات بالا برای دیدن اینکه آیا کمک‌کننده اعمال می‌شود و (ب) ثبت توجیه فنی در نظر dismissal نادیده نگیرید. سابقه: js/stack-trace-exposure که در callsites که قبلاً از sanitizeErrorMessage() عبور کرده‌اند، یک محدودیت شناخته شده CodeQL است (sanitizers سفارشی شناسایی نمی‌شوند) — به عنوان false positive با اشاره به docs/security/ERROR_SANITIZATION.md نادیده بگیرید.
  15. هرگز مسیرهایی که فرایندهای فرزند را ایجاد می‌کنند (/api/mcp/, /api/cli-tools/runtime/) را بدون طبقه‌بندی isLocalOnlyPath() در src/server/authz/routeGuard.ts افشا نکنید. اجرای loopback بدون قید و شرط قبل از هر بررسی احراز هویت انجام می‌شود — JWT نشت شده از طریق تونل نمی‌تواند فرایند را ایجاد کند. به docs/security/ROUTE_GUARD_TIERS.md مراجعه کنید.
  16. هرگز ملحقات Co-Authored-By که به دستیار هوش مصنوعی، LLM یا حساب خودکار اعتبار می‌دهد را اضافه نکنید (مثلاً نام‌های شامل "Claude"، "GPT"، "Copilot"، "Bot"؛ ایمیل‌های anthropic.com / openai.com / آدرس‌های noreply.github.com متعلق به بات‌ها). چنین ملحقاتی انتساب commit را به حساب بات در GitHub هدایت می‌کنند و نویسنده واقعی (diegosouzapw) را در تاریخچه PR پنهان می‌کنند. همکاران انسانی — از جمله نویسندگان PR upstream و گزارش‌دهندگان issue که به OmniRoute پورت می‌شوند — می‌توانند و باید با ملحقات استاندارد Co-authored-by: Name <email> اعتبار داده شوند؛ گردش‌کارهای upstream-port (/port-upstream-features، /port-upstream-issues) به این بستگی دارد.
Reference in New Issue View Git Blame Copy Permalink