Files

T

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

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

52 KiB

Raw Permalink 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 · 🇮🇳 te · 🇹🇭 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 தனித்தனி)
npm run lint                   # ESLint (0 பிழைகள் எதிர்பார்க்கப்படுகின்றன; எச்சரிக்கைகள் முன்னதாகவே உள்ளன)
npm run typecheck:core         # TypeScript சரிபார்ப்பு (சுத்தமாக இருக்க வேண்டும்)
npm run typecheck:noimplicit:core  # கடுமையான சரிபார்ப்பு (எந்த implicit 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, cache)
npm run test:vitest

# அனைத்து சோதனைகள்
npm run test:all

முழு சோதனை மேட்ரிக்ஸ் க்காக, CONTRIBUTING.md → "சோதனைகளை இயக்குதல்" ஐப் பார்க்கவும். ஆழமான கட்டமைப்பிற்காக, AGENTS.md ஐப் பார்க்கவும்.

திட்டம் ஒரு பார்வையில்

OmniRoute — ஒருங்கிணைந்த AI பிராக்சி/ரூட்டர். ஒரு முடிவிடம், 160+ LLM வழங்குநர்கள், தானாகவே fallback.

அடுக்கு	இடம்	நோக்கம்
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/`	கொள்கை இயந்திரம், செலவுக் கட்டுப்பாடுகள், fallback உள்கட்டமைப்பு
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/`	நிலையான உரையாடல் நினைவகம்

Monorepo: 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() மேல்நிலை → மீண்டும் முயற்சி w/ backoff
    → பதில்கள் மொழிபெயர்ப்பு → SSE ஓட்டம் அல்லது JSON
    → பதில்கள் API: responsesTransformer.ts TransformStream

API பாதைகள் ஒரே மாதிரியான வடிவத்தை பின்பற்றுகின்றன: Route → CORS முன்பார்வை → Zod உடல் சரிபார்ப்பு → விருப்ப அங்கீகாரம் (extractApiKey/isValidApiKey) → API விசை கொள்கை அமலாக்கம் → கைப்பற்றுதல் ஒப்படைப்பு (open-sse). உலகளாவிய Next.js மிடில்வேர் இல்லை — இடைமுகம் பாதை-சிறப்பு.

கம்போ வழிமுறை (open-sse/services/combo.ts): 14 உத்திகள் (முதன்மை, எடை, நிரப்புதல்-முதல், சுற்று-ரொபின், P2C, சீரற்ற, குறைந்த-பயன்பாடு, செலவுக்கேற்ப, மீட்டமைப்பு-அறிவு, கடுமையான-சீரற்ற, தானாக, lkgp, சூழல்-சீரமைக்கப்பட்ட, சூழல்-மாற்று). ஒவ்வொரு இலக்கமும் handleSingleModel() ஐ அழைக்கிறது, இது handleChatCore() ஐ ஒவ்வொரு இலக்கத்திற்கும் பிழை கையாளுதல் மற்றும் சுற்று முறையீட்டு சரிபார்ப்புடன் சுற்றி விடுகிறது. 9-உயர்தர Auto-Combo மதிப்பீட்டிற்கான 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 ஐ திருப்பி அனுப்புவது.
தேர்ந்தெடுக்கப்பட்ட Grok முறைகள் போன்ற வழங்குநர்-சிறப்பு முறை/மாதிரி அனுமதி தோல்விகள்.

மாதிரி பூட்டுதல் 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, தீர்வு bundler. தெளிவான வகைகளை முன்னுரிமை கொடுக்கவும்.

தரவுத்தளம்

எப்போதும் src/lib/db/ டொமைன் மாடுல்களைப் பயன்படுத்தவும் — எப்போதும் வழிகளில் அல்லது கையாளர்களில் கச்சித SQL எழுத வேண்டாம்
எப்போதும் src/lib/localDb.ts இல் தரவுத்தொகுப்புகளைச் சேர்க்க வேண்டாம் (மறு-வெளியீட்டு அடுக்கு மட்டும்)
எப்போதும் localDb.ts இல் இருந்து ப barrel-import செய்ய வேண்டாம் — குறிப்பிட்ட db/ மாடுல்களைப் பயன்படுத்தவும்
DB ஒரே மாதிரியானது: getDbInstance() src/lib/db/core.ts இல் இருந்து (WAL பதிவேற்றம்)
மைக்ரேஷன்கள்: src/lib/db/migrations/ — பதிப்பு கொண்ட SQL கோப்புகள், idempotent, பரிவர்த்தனைகளில் இயக்கவும்

பிழை கையாளுதல்

குறிப்பிட்ட பிழை வகைகளுடன் try/catch, pino சூழ்நிலையுடன் பதிவு செய்யவும்
SSE ஓட்டங்களில் பிழைகளை அடிக்கடி அடிக்க வேண்டாம் — சுத்தம் செய்ய abort சிக்னல்களைப் பயன்படுத்தவும்
சரியான HTTP நிலை குறியீடுகளை திருப்பவும் (4xx/5xx)

பாதுகாப்பு

எப்போதும் eval(), new Function(), அல்லது குறிக்கோள் மதிப்பீடு பயன்படுத்த வேண்டாம்
அனைத்து உள்ளீடுகளையும் 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 ஐ விரிவாக்கவும்)
OpenAI வடிவமைப்புக்கு அல்லாதால் 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/ இல் சோதனைகளை எழுதவும் (புதிய இணைக்கப்பட்ட அடிப்படையைச் சேர்த்தால் publicCreds வடிவமைப்பைச் சேர்க்கவும்)

புதிய API வழியைச் சேர்க்க

src/app/api/v1/your-route/ இல் அடைவை உருவாக்கவும்
GET/POST கையாளர்களுடன் route.ts உருவாக்கவும்
மாதிரியைப் பின்பற்றவும்: CORS → Zod உடல் சரிபார்ப்பு → விருப்ப auth → கையாளல் ஒப்படைப்பு
கையாளல் 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 ஏற்கனவே உள்ளன: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
திறன் பணியாளர் சூழ்நிலையைப் பெறுகிறது (செய்திகள், மெட்டாடேட்டா) → கட்டமைக்கப்பட்ட முடிவை திருப்புகிறது
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 / 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 வேலைப்பாடு

# எப்போதும் நேரடியாக முக்கியத்தில் கமிட் செய்யாதீர்கள்
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

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 Modules
TypeScript: 5.9+, இலக்கு ES2022, மாடுல் esnext, தீர்வு bundler
பாதை அலியாஸ்: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
இயல்புநிலை போர்ட்: 20128 (API + dashboard ஒரே போர்டில்)
தரவியல் அடைவு: 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%.
தெளிவான இயக்குனர் அனுமதி இல்லாமல் Husky ஹூக்குகளை ( --no-verify, --no-gpg-sign) எப்போதும் தவிர்க்காதீர்கள்.
பொதுவான மேல்நிலை OAuth client_id/secret அல்லது Firebase Web விசைகளை சரம் எழுத்துக்களாக எப்போதும் உள்ளடக்காதீர்கள் — எப்போதும் 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 ஐப் பார்க்கவும்.
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) இதை சார்ந்துள்ளன.

52 KiB Raw Permalink Blame History