OmniRoute/docs/i18n/ta/CLAUDE.md

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 ஐ தனிப்பயனாக்கப்பட்ட செயல்பாடுகளை விட முன்னுரிமை கொடுக்கவும்.

---

பொதுவான திருத்த நிலைகள்

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

1. src/shared/constants/providers.ts இல் பதிவு செய்யவும் (ஏற்றுமதி செய்யும் போது Zod-சரிபார்க்கப்பட்டது)
2. தனிப்பயன் தரவுகளை தேவைப்பட்டால் open-sse/executors/ இல் செயல்பாட்டைச் சேர்க்கவும் ( BaseExecutor ஐ விரிவாக்கவும்)
3. 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 உடல் சரிபார்ப்பு → விருப்ப auth → கையாளல் ஒப்படைப்பு
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. src/lib/cloudAgent/agents/ இல் CloudAgentBase ஐ விரிவாக்கும் ஏஜென்ட் வகுப்பை உருவாக்கவும் (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
பொது மேல்நிலை அங்கீகாரங்கள் (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) உருவாக்கவும்

---

கடுமையான விதிகள்

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. 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. CodeQL / Secret-Scanning எச்சரிக்கையை (a) மேலே உள்ள மாதிரி ஆவணங்களை முதலில் சரிபார்க்காமல் மற்றும் (b) நீக்கம் கருத்தில் தொழில்நுட்ப காரணத்தை பதிவு செய்யாமல் எப்போதும் மறுக்காதீர்கள். முன்னணி: js/stack-trace-exposure என்பது ஏற்கனவே sanitizeErrorMessage() மூலம் வழி நடத்தப்படும் அழைப்பிடங்களில் எழுப்பப்பட்டது என்பது ஒரு அறியப்பட்ட CodeQL வரம்பு (சாதாரண சுத்திகரிப்புகள் அடையாளம் காணப்படவில்லை) — docs/security/ERROR_SANITIZATION.md ஐ மேற்கோள் காட்டி false positive ஆக மறுக்கவும்.
15. குழந்தை செயல்முறைகளை உருவாக்கும் வழிகளை ( /api/mcp/, /api/cli-tools/runtime/) src/server/authz/routeGuard.ts இல் isLocalOnlyPath() வகைப்படுத்தலின்றி எப்போதும் வெளிப்படுத்தாதீர்கள். எந்த அங்கீகார சோதனைக்கும் முன் கட்டாயமாக லூப்பேக் அமலாக்கம் நடைபெறும் — குழாயில் ஊடுருவிய 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) இதை சார்ந்துள்ளன.