Files

T

wehub-resource-sync d8dcd5f6d1 chore: import upstream snapshot with attribution

2026-07-13 13:39:12 +08:00

43 KiB

Raw Permalink Blame History

CLAUDE.md (ગુજરાતી)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇱 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.ai/code સાથે કોડ પર કામ કરતી વખતે માર્ગદર્શન પ્રદાન કરે છે.

ઝડપી શરૂઆત

npm install                    # deps સ્થાપિત કરો (.auto-generates .env from .env.example)
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 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 માન્યતા → auth? → નીતિ ચકાસણી → પ્રોમ્પ્ટ ઇન્જેક્શન ગાર્ડ
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → કેશ ચકાસણી → દર મર્યાદા → કોમ્બો રૂટિંગ?
      → resolveComboTargets() → handleSingleModel() પ્રતિ લક્ષ્ય
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → પ્રતિસાદ અનુવાદ → SSE સ્ટ્રીમ અથવા JSON
    → જો Responses API: responsesTransformer.ts TransformStream

API માર્ગો એક સંગ્રહિત પેટર્નનું પાલન કરે છે: Route → CORS preflight → Zod body validation → વૈકલ્પિક auth (extractApiKey/isValidApiKey) → API કી નીતિ અમલ → Handler delegation (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.

ઉદ્દેશ: એક પ્રદાતા તરફ ટ્રાફિક મોકલવાનું રોકવું જે વારંવાર 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ને પ્રમાણપત્રો/સેટિંગ્સ બદલાય ત્યાં સુધી ઉપલબ્ધ રહેવું જોઈએ અથવા એક ઓપરેટર તેમને ફરીથી સેટ કરે છે. ટર્મિનલ સ્થિતિઓને તાત્કાલિક કૂલડાઉન સ્થિતિ સાથેOverwrite ન કરો.

મોડલ લોકઆઉટ

વ્યાપ: પ્રદાતા + કનેક્શન + મોડલ.

ઉદ્દેશ: જ્યારે માત્ર એક મોડલ ઉપલબ્ધ નથી અથવા તે ક્વોટા-મર્યાદિત છે ત્યારે સમગ્ર કનેક્શનને બંધ કરવાનું ટાળવું.

ઉદાહરણો:

પ્રતિ-મોડલ ક્વોટા પ્રદાતા 429 પાછા આપે છે.
સ્થાનિક પ્રદાતા એક ગુમ થયેલ મોડલ માટે 404 પાછા આપે છે.
પ્રદાતા-વિશિષ્ટ મોડ/મોડલ પરવાનગીની નિષ્ફળતાઓ જેમ કે પસંદ કરેલ ગ્રોક મોડ્સ.

મોડલ લોકઆઉટ open-sse/services/accountFallback.ts માં રહે છે અને સમાન કનેક્શનને અન્ય મોડલ સેવા આપવા દે છે.

ડિબગિંગ માર્ગદર્શન

જો પ્રદાતા માટે તમામ કી છોડી દેવામાં આવે છે, તો પ્રદાતા બ્રેકર સ્થિતિ અને દરેક કનેક્શનના rateLimitedUntil/testStatusને તપાસો.
જો એક પ્રદાતા પુનઃસેટ વિન્ડો પછી કાયમીExcluded લાગે છે, તો તપાસો કે શું કોડ કાચા stateને વાંચી રહ્યું છે તેના બદલે getStatus()/canExecute() નો ઉપયોગ કરી રહ્યું છે.
જો એક પ્રદાતા કી નિષ્ફળ જાય પરંતુ અન્ય કાર્ય કરવા જોઈએ, તો પ્રદાતા બ્રેકર કરતાં કનેક્શન કૂલડાઉનને પસંદ કરો.
જો માત્ર એક મોડલ નિષ્ફળ જાય, તો કનેક્શન કૂલડાઉન કરતાં મોડલ લોકઆઉટને પસંદ કરો.
જો એક રાજ્ય સ્વયં-પુનઃપ્રાપ્તિ કરવું જોઈએ, તો તેમાં ભવિષ્યની ટાઇમસ્ટેમ્પ/રીસેટ ટાઇમઆઉટ અને એક વાંચન પાથ હોવો જોઈએ જે સમાપ્ત રાજ્યને રિફ્રેશ કરે. કાયમી સ્થિતિઓ માટે મેન્યુઅલ પ્રમાણપત્ર અથવા કન્ફિગ ફેરફારોની જરૂર છે.

મુખ્ય પરંપરાઓ

કોડ શૈલી

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, રિઝોલ્યુશન bundler. સ્પષ્ટ પ્રકારોને પ્રાથમિકતા આપો.

ડેટાબેસ

હંમેશા 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 સ્ટ્રીમમાં ભૂલો ક્યારેય ન છુપાવો — સફાઈ માટે abort સંકેતોનો ઉપયોગ કરો
યોગ્ય HTTP સ્થિતિ કોડ્સ પરત કરો (4xx/5xx)

સુરક્ષા

ક્યારેય eval(), new Function(), અથવા IMPLIED eval નો ઉપયોગ ન કરો
Zod સ્કીમા સાથે તમામ ઇનપુટને માન્ય બનાવો
આરામ પર ક્રેડેંશિયલ્સને એન્ક્રિપ્ટ કરો (AES-256-GCM)
અપસ્ટ્રીમ હેડર ડિનાયલિસ્ટ: src/shared/constants/upstreamHeaders.ts — સંપાદન કરતી વખતે સાફ, Zod સ્કીમા, અને યુનિટ ટેસ્ટને સમન્વયિત રાખો
જાહેર અપસ્ટ્રીમ ક્રેડેંશિયલ્સ (Gemini/Antigravity/Windsurf-શૈલી OAuth client_id/secret + Firebase વેબ કી જાહેર CLIsમાંથી કાઢી લેવામાં આવી): જરૂરી છે resolvePublicCred() દ્વારા એમ્બેડ કરવું open-sse/utils/publicCreds.ts માં — ક્યારેય સ્ટ્રિંગ લિટરલ તરીકે નહીં. ફરજિયાત પેટર્ન માટે docs/security/PUBLIC_CREDS.md જુઓ.
ભૂલ પ્રતિસાદ (HTTP / SSE / executor / MCP હેન્ડલર): જરૂરી છે 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ને પ્રાથમિકતા આપો.

સામાન્ય ફેરફાર પરિસ્થિતિઓ

નવા પ્રદાતા ઉમેરવો

src/shared/constants/providers.ts માં નોંધણી કરો (લોડ પર Zod-માન્ય)
જો કસ્ટમ લોજિકની જરૂર હોય તો open-sse/executors/ માં એક્ઝિક્યુટર ઉમેરો ( BaseExecutor ને વિસ્તૃત કરો)
જો નોન-ઓપનએઆઈ ફોર્મેટ હોય તો open-sse/translator/ માં અનુવાદક ઉમેરો
જો OAuth આધારિત હોય તો src/lib/oauth/constants/oauth.ts માં OAuth કન્ફિગ ઉમેરો — જો અપસ્ટ્રીમ CLI જાહેર client_id/secret મોકલે, તો resolvePublicCred() દ્વારા એમ્બેડ કરો (જુઓ docs/security/PUBLIC_CREDS.md), ક્યારેય લિટરલ તરીકે નહીં
open-sse/config/providerRegistry.ts માં મોડલ્સ નોંધણી કરો
tests/unit/ માં ટેસ્ટ લખો (જો તમે નવા એમ્બેડેડ ડિફોલ્ટ ઉમેર્યા હોય તો જાહેરCreds આકારની પુષ્ટિનો સમાવેશ કરો)

નવા API માર્ગ ઉમેરવો

src/app/api/v1/your-route/ હેઠળ ડિરેક્ટરી બનાવો
GET/POST હેન્ડલર્સ સાથે route.ts બનાવો
પેટર્ન અનુસરો: CORS → Zod શરીર માન્યતા → વૈકલ્પિક ઓથ → હેન્ડલર ડેલિગેશન
હેન્ડલર open-sse/handlers/ માં જાય છે (ત્યાંથી આયાત કરો, ઇનલાઇન નહીં)
ભૂલ પ્રતિસાદો buildErrorBody() / errorResponse() નો ઉપયોગ કરે છે open-sse/utils/error.ts માં (સ્વચાલિત રીતે સાફ — ક્યારેય err.stack અથવા err.message કાચા શરીરમાં ન મૂકો). docs/security/ERROR_SANITIZATION.md જુઓ.
ટેસ્ટ ઉમેરો — જેમાં ઓછામાં ઓછું એક પુષ્ટિ છે કે ભૂલ પ્રતિસાદ સ્ટેક ટ્રેસને લીક નથી કરતી (!body.error.message.includes("at /"))

નવા DB મોડ્યુલ ઉમેરવો

src/lib/db/yourModule.ts બનાવો — ./core.ts માંથી getDbInstance આયાત કરો
તમારા ડોમેન ટેબલ માટે CRUD ફંક્શન નિકાસ કરો
જો નવી ટેબલની જરૂર હોય તો src/lib/db/migrations/ માં માઇગ્રેશન ઉમેરો
src/lib/localDb.ts માંથી પુનઃ-નિકાસ કરો (ફક્ત પુનઃ-નિકાસ યાદીમાં ઉમેરો)
ટેસ્ટ લખો

નવા MCP ટૂલ ઉમેરવો

Zod ઇનપુટ સ્કીમા + અસિંક હેન્ડલર સાથે open-sse/mcp-server/tools/ માં ટૂલ વ્યાખ્યા ઉમેરો
ટૂલ સેટમાં નોંધણી કરો ( createMcpServer() દ્વારા વાયરડ)
યોગ્ય સ્કોપ(ઓ)ને સોંપો
ટેસ્ટ લખો (ટૂલ કૉલને mcp_audit ટેબલમાં લોગ કરવામાં આવે છે)

નવા A2A સ્કિલ ઉમેરવો

src/lib/a2a/skills/ માં સ્કિલ બનાવો (5 પહેલાથી જ છે: સ્માર્ટ-રાઉટિંગ, ક્વોટા-મૅનેજમેન્ટ, પ્રદાતા-ખોજ, ખર્ચ-વિશ્લેષણ, આરોગ્ય-રિપોર્ટ)
સ્કિલ કાર્ય સંદર્ભ (સંદેશા, મેટાડેટા) પ્રાપ્ત કરે છે → રચિત પરિણામ પરત કરે છે
src/lib/a2a/taskExecution.ts માં A2A_SKILL_HANDLERS માં નોંધણી કરો
src/app/.well-known/agent.json/route.ts માં બહાર પાડો (એજન્ટ કાર્ડ)
tests/unit/ માં ટેસ્ટ લખો
docs/frameworks/A2A-SERVER.md સ્કિલ ટેબલમાં દસ્તાવેજ કરો

નવા ક્લાઉડ એજન્ટ ઉમેરવો

src/lib/cloudAgent/agents/ માં CloudAgentBase ને વિસ્તૃત કરતી એજન્ટ ક્લાસ બનાવો (3 પહેલાથી જ છે: codex-cloud, devin, jules)
createTask, getStatus, approvePlan, sendMessage, listSources અમલમાં લાવો
src/lib/cloudAgent/registry.ts માં નોંધણી કરો
જો જરૂર હોય તો OAuth/ક્રેડેંશિયલ્સ સંભાળવું (src/lib/oauth/providers/)
ટેસ્ટ + 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`
જાહેર અપસ્ટ્રીમ ક્રેડેન્શિયલ્સ (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 / ક્લાઉડ)	`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 વર્કફ્લો

# ક્યારેય સીધા મુખ્યમાં કમિટ ન કરો
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): સર્કિટ બ્રેકર ઉમેરો — સ્કોપ્સ: 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 Modules
ટાઇપસ્ક્રિપ્ટ: 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) જનરેટ કરો

કઠોર નિયમો

ક્યારેય ગુપ્તતા અથવા પ્રમાણપત્રો કમિટ ન કરો
ક્યારેય localDb.ts માં લોજિક ઉમેરો ન કરો
ક્યારેય eval() / new Function() / સૂચિત eval નો ઉપયોગ ન કરો
ક્યારેય સીધા main માં કમિટ ન કરો
ક્યારેય રૂટમાં કાચા SQL ન લખો — src/lib/db/ મોડ્યુલનો ઉપયોગ કરો
ક્યારેય SSE સ્ટ્રીમમાં ભૂલને મૌન રીતે નાશ ન કરો
હંમેશા Zod સ્કીમા સાથે ઇનપુટને માન્ય બનાવો
ઉત્પાદન કોડ બદલતા સમયે હંમેશા પરીક્ષણો સામેલ કરો
કવરેજ ≥75% (નિવેદનો, લાઇન, ફંક્શન) / ≥70% (શાખાઓ) રહેવું જોઈએ. વર્તમાન માપવામાં આવેલ: ~82%.
સ્પષ્ટ ઓપરેટર મંજૂરી વિના હસ્કી હૂક્સ (--no-verify, --no-gpg-sign) ને ક્યારેય બાયપાસ ન કરો.
ક્યારેય જાહેર અપસ્ટ્રીમ OAuth client_id/secret અથવા Firebase વેબ કી ને સ્ટ્રિંગ લિટરલ તરીકે એમ્બેડ ન કરો — હંમેશા resolvePublicCred() (open-sse/utils/publicCreds.ts) દ્વારા જાઓ. જુઓ docs/security/PUBLIC_CREDS.md.
ક્યારેય HTTP / SSE / એક્ઝિક્યુટર પ્રતિસાદોમાં કાચા err.stack / err.message પાછા ન કરો — હંમેશા buildErrorBody() અથવા sanitizeErrorMessage() (open-sse/utils/error.ts) મારફતે રૂટ કરો. જુઓ docs/security/ERROR_SANITIZATION.md.
ક્યારેય બાહ્ય પાથ અથવા રનટાઇમ મૂલ્યોને exec()/spawn() ને પસાર કરવામાં આવેલા શેલ સ્ક્રિપ્ટોમાં સ્ટ્રિંગ-ઇન્ટરપોલેટ ન કરો — તેના બદલે env વિકલ્પ મારફતે પસાર કરો. સંદર્ભ: src/mitm/cert/install.ts::updateNssDatabases.
ક્યારેય CodeQL / Secret-Scanning એલર્ટને (a) પ્રથમ ઉપર દર્શાવેલ પેટર્ન દસ્તાવેજો તપાસ્યા વિના નકારી નાંખો કે શું સહાયક લાગુ પડે છે, અને (b) નકારી નાખવાના ટિપ્પણમાં ટેકનિકલ ન્યાયને નોંધો. નમૂનો: js/stack-trace-exposure જે કૉલસાઇટ્સ પર ઉઠાવવામાં આવ્યું છે જે પહેલાથી જ sanitizeErrorMessage() મારફતે રૂટ કરે છે તે એક જાણીતી CodeQL મર્યાદા છે (કસ્ટમ સેનિટાઇઝર્સ માન્ય નથી) — docs/security/ERROR_SANITIZATION.md ને સંદર્ભિત કરીને false positive તરીકે નકારી નાખો.
ક્યારેય બાળકોની પ્રક્રિયાઓને શરૂ કરતી રૂટ્સને ( /api/mcp/, /api/cli-tools/runtime/) src/server/authz/routeGuard.ts માં isLocalOnlyPath() વર્ગીકરણ વિના સામેલ ન કરો. લૂપબેક અમલમાં કોઈપણ ઓથ ચેક પહેલાં શરત વિના થાય છે — ટનલ દ્વારા લીક થયેલ JWT પ્રક્રિયા શરૂ કરવા માટે પ્રેરણા આપી શકતું નથી. જુઓ docs/security/ROUTE_GUARD_TIERS.md.
ક્યારેય Co-Authored-By ટ્રેલર્સને સામેલ ન કરો જે AI સહાયક, LLM અથવા સ્વચાલિત ખાતાને શ્રેય આપે છે (દા.ત. "Claude", "GPT", "Copilot", "Bot" ધરાવતા નામો; anthropic.com / openai.com / બોટની માલિકીના noreply.github.com સરનામા પરના ઈમેઈલો). આવા ટ્રેલર્સ GitHub પર બોટ ખાતામાં કમિટ એટ્રિબ્યુશન રૂટ કરે છે, PR ઇતિહાસમાં વાસ્તવિક લેખકને (diegosouzapw) છુપાવે છે. માનવ સહયોગીઓ — upstream PR લેખકો અને OmniRoute પર પોર્ટ થતા issue રિપોર્ટરો સહિત — પ્રમાણભૂત Co-authored-by: Name <email> ટ્રેલર્સ સાથે શ્રેય મેળવી શકે છે અને જોઈએ; upstream-port વર્કફ્લો (/port-upstream-features, /port-upstream-issues) આના પર નિર્ભર છે.

43 KiB Raw Permalink Blame History