🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
გმადლობთ კონტრიბუციით დაინტერესებისთვის! ეს სახელმძღვანელო მოიცავს ყველაფერს, რაც დასაწყებად გჭირდებათ.
თითოეული ცვლილებისთვის განსაზღვრული ოფიციალური სამუშაო პროცესის გასაცნობად დაიწყეთ კონტრიბუციის ძირითადი გზით. ის პროვაიდერის, მარშრუტიზაციის, UI/UX-ის, i18n-ის, CLI-ის, მონაცემთა ბაზისა და აგების/განთავსების ცვლილებებს აკავშირებს მათ კონტრაქტებთან, მიზნობრივ ტესტებთან, CI-ის დაფარვასა და შეჯერების ეტაპებთან.
- Node.js
>=22.22.3 <23, ან>=24.0.0 <27(რეკომენდებულია: 24 LTS) - npm 10+
npm v11+-ის მომხმარებლები (Node 24+):
npm install-ის შემდეგ გადაამოწმეთ, რომ ნატიური მოდულები დაინსტალირდა:node -e "require('better-sqlite3')". თუ ისMODULE_NOT_FOUNDშეცდომით დასრულდება, გაუშვითnpm approve-scripts better-sqlite3 && npm install. იხილეთ პრობლემების მოგვარება.
- Git
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install# შექმენით თქვენი .env შაბლონიდან
cp .env.example .env
# დააგენერირეთ საჭირო საიდუმლო მნიშვნელობები
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .envდეველოპმენტისთვის მნიშვნელოვანი ცვლადები:
| ცვლადი | დეველოპმენტის ნაგულისხმევი მნიშვნელობა | აღწერა |
|---|---|---|
PORT |
20128 |
სერვერის პორტი |
NEXT_PUBLIC_BASE_URL |
http://localhost:20128 |
ფრონტენდის საბაზისო URL |
JWT_SECRET |
(დააგენერირეთ ზემოთ) | JWT-ის ხელმოწერის საიდუმლო |
INITIAL_PASSWORD |
CHANGEME |
პირველი შესვლის პაროლი |
APP_LOG_LEVEL |
info |
ჟურნალის დეტალიზაციის დონე |
მართვის პანელი გთავაზობთ UI გადამრთველებს იმ ფუნქციებისთვის, რომელთა კონფიგურაციაც გარემოს ცვლადებით არის შესაძლებელი:
| პარამეტრის მდებარეობა | გადამრთველი | აღწერა |
|---|---|---|
| პარამეტრები → გაფართოებული | გამართვის რეჟიმი | გამართვის მოთხოვნების ჟურნალების ჩართვა (UI) |
| პარამეტრები → ზოგადი | გვერდითი ზოლის ხილვადობა | გვერდითი ზოლის სექციების ჩვენება/დამალვა |
ეს პარამეტრები მონაცემთა ბაზაში ინახება და ხელახლა გაშვების შემდეგაც ნარჩუნდება; დაყენებისას ისინი გარემოს ცვლადების ნაგულისხმევ მნიშვნელობებს ანაცვლებს.
# დეველოპმენტის რეჟიმი (ცხელი გადატვირთვა)
npm run dev
# საწარმოო აგება
npm run build # next build → .build/next/, შემდეგ assembleStandalone → dist/
npm run start
# სწრაფი, მხოლოდ ბეკენდის/API-ის კომპილაცია კონტრიბუტორის ცვლილებებისთვის
npm run build:contributor
# რელიზის აგება (სუფთა ხელახალი აგება + HEAD sentinel — აუცილებელია განთავსებისთვის)
npm run build:release # rm -rf .build dist && აგება + წერს dist/BUILD_SHA-ს
# პორტის გავრცელებული კონფიგურაცია
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run devკონტრიბუტორის აგება მხოლოდ კომპილაციის ვალიდაციას ასრულებს: ის არ აწყობს დამოუკიდებელ დისტრიბუციას და არ აგებს არჩევით ნატიურ დაფასოებით რესურსებს. გამოიყენეთ ჩვეულებრივი საწარმოო აგება, როდესაც გასავრცელებლად მზა პაკეტის ვალიდაცია გჭირდებათ.
| დირექტორია | შიგთავსი | კონტროლდება |
|---|---|---|
src/ |
აპლიკაციის საწყისი კოდი (TypeScript / TSX) | დიახ |
.build/ |
შუალედური ფაილები — next build-ის შედეგი (gitignored, distDir = .build/next) |
არა |
dist/ |
გასავრცელებლად მზა პაკეტი — აწყობილია assembleStandalone-ის მიერ (gitignored) |
არა |
აგების კონვეიერი ერთ გავლას იყენებს:
npm run build
└─ next build → .build/next/standalone (Next.js-ის შედეგი)
└─ assembleStandalone() (აკოპირებს standalone + static + public + ნატიურ რესურსებს)
└─ შედეგი: dist/ (server.js, .next/static/, public/, node_modules/)
npm run build:release დამატებით ჯერ ორივე დირექტორიას ასუფთავებს და
განთავსების მთლიანობის sentinel-ის სახით წერს dist/BUILD_SHA-ს (= git rev-parse --short HEAD).
npm run build:contributor მხოლოდ ბეკენდის აგების პროფილს იყენებს. აგებისას ის დროებით ანაცვლებს
მართვის პანელის UI ფაილებს დროებითი ჩანაცვლებებით, ინარჩუნებს API მარშრუტების დამმუშავებლებს და აგების შემდეგ აღადგენს თავდაპირველ ფაილებს.
გამოიყენეთ npm run build იმ ცვლილებებისთვის, რომლებიც გავლენას ახდენს მართვის პანელის UI-ზე, ან რელიზის სრული
ვალიდაციისთვის; კონტრიბუტორის პროფილი რელიზის აგებას არ ანაცვლებს.
VPS-ზე განთავსების შენიშვნა: დისტანციური იმიჯის დირექტორია
/usr/lib/node_modules/omniroute/app/უცვლელია. განთავსების უნარებიdist/-ის შიგთავსს მასში rsync-ით ასინქრონებს. შეიცვალა მხოლოდ რეპოზიტორიაში არსებული აგების შედეგის გზა (app/→dist/).
ნაგულისხმევი URL-ები:
- მართვის პანელი:
http://localhost:20128/dashboard - API:
http://localhost:20128/v1
⚠️ არასოდეს შეიტანოთ commit პირდაპირmain-ში. ყოველთვის გამოიყენეთ ფუნქციური განშტოებები.PR-ის საბაზისო განშტოება: სამიზნედ მიუთითეთ აქტიური
release/vX.Y.Zგანშტოება (და არაmain). თითო გამოშვებაზე ცალკე განშტოებისა და გამოშვებისას ტეგის შექმნის მოდელის შესახებ იხილეთdocs/ops/BRANCHING_MODEL.md.
# შექმენით განშტოება აქტიური გამოშვების ბოლო წერტილიდან (მაგალითად: release/v3.8.49)
git fetch origin
git checkout -b feat/your-feature-name origin/release/v3.8.49
# ... შეიტანეთ ცვლილებები ...
git commit -m "feat: აღწერეთ თქვენი ცვლილება"
git push -u origin feat/your-feature-name
# გახსენით Pull Request, სადაც base = release/v3.8.49| პრეფიქსი | დანიშნულება |
|---|---|
feat/ |
ახალი ფუნქციები |
fix/ |
შეცდომების გამოსწორება |
refactor/ |
კოდის რესტრუქტურიზაცია |
docs/ |
დოკუმენტაციის ცვლილებები |
test/ |
ტესტების დამატება/შესწორება |
chore/ |
ინსტრუმენტები, CI, დამოკიდებულებები |
დაიცავით Conventional Commits-ის წესები:
feat: პროვაიდერის გამოძახებებისთვის circuit breaker-ის დამატება
fix: JWT საიდუმლოს ვალიდაციის განსაკუთრებული შემთხვევის მოგვარება
docs: SECURITY.md-ის განახლება PII-ის დაცვით
test: დაკვირვებადობის მოდულური ტესტების დამატება
refactor(db): სიხშირის შეზღუდვის ცხრილების გაერთიანება
არეები (v3.8): db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills, cloud-agent, guardrails, compression, auto-combo, resilience, providers, executors, translator, domain, authz.
# ყველა ტესტი (unit + vitest + ecosystem + e2e)
npm run test:all
# ერთი სატესტო ფაილი (Node.js-ის ჩაშენებული ტესტების გამშვები — ტესტების უმეტესობა ამას იყენებს)
node --import tsx/esm --test tests/unit/your-file.test.ts
# მხოლოდ თქვენი ცვლილებით დაზარალებული მოდულური ტესტები (იგივე TIA სელექტორი, რაც CI ბარიერში, #8084)
npm run test:scoped # ბოლო commit-ში (ან სამუშაო ხეში) შეტანილი ცვლილებები
npm run test:scoped:staged # მხოლოდ staged ცვლილებები — კარგად ერწყმის pre-commit გაშვებას
npm run test:scoped:full # ჯერ ხელახლა ააგეთ import-graph რუკა (ფაილების დამატების/გადაადგილების შემდეგ)
# Exit 1 + "run the full suite" ნიშნავს, რომ შეიცვალა ცენტრალური ფაილი (tsconfig, package.json, …) ან
# რუკაზე არარსებული საწყისი კოდი — სელექტორი უსაფრთხოდ ასრულებს მუშაობას შეცდომით და არასოდეს გამოტოვებს ტესტებს შეუმჩნევლად.
# Vitest (MCP სერვერი, autoCombo, cache)
npm run test:vitest
# E2E ტესტები (საჭიროებს Playwright-ს)
npm run test:e2e
# პროტოკოლის კლიენტების E2E (MCP ტრანსპორტები, A2A)
npm run test:protocols:e2e
# ეკოსისტემასთან თავსებადობის ტესტები
npm run test:ecosystem
# დაფარვის ბარიერი: დებულებების/სტრიქონების/ფუნქციების/განშტოებების 60%
npm run test:coverage
npm run coverage:report
# Lint + ფორმატირების შემოწმება
npm run lint
npm run check
# ბარიერით დაცული რეალურ upstream-ზე combo-ს smoke-ტესტი (საჭიროებს VPS-ზე წვდომას + რეალური პროვაიდერის კრედიტებს)
# მიმართავს რეალურ პროვაიდერებს — მცირე ხარჯთანაა დაკავშირებული. არასოდეს ეშვება CI-ში. ბარიერის გარეშე უპრობლემოდ გამოიტოვება.
# საჭიროა: ssh root@192.168.0.15 წვდომა (VPS-იდან იყენებს DB-ის მხოლოდ წაკითხვად snapshot-ს).
RUN_COMBO_LIVE=1 npm run test:combo:live
# მე-3 ფაზის VPS-ის ცოცხალი smoke-ტესტი — ჩვეულებრივი Node ESM სკრიპტები, რომლებიც პირდაპირ ცოცხალ .15 სერვერს მიმართავენ.
# საჭიროა: ssh root@192.168.0.15 წვდომა (combo-ები იქმნება/იშლება SSH sqlite-ის მეშვეობით).
# მიმართავს რეალურ პროვაიდერებს (მცირე ხარჯი). ქმნის/შლის მხოლოდ __live_test__* combo-ებს. არასოდეს ეშვება CI-ში.
# .15-ზე REQUIRE_API_KEY=false, ამიტომ API გასაღები საჭირო არ არის, თუმცა დაყენების შემთხვევაში ითვალისწინებს COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY-ს.
npm run test:combo:live:vps # 7 HTTP სცენარი (priority/round-robin/weighted/cost/fusion/auto + health)
npm run test:combo:live:vps:failover # ამატებს პროვაიდერებს შორის რეალურ failover სცენარს (სულ 8)დაფარვის შენიშვნები:
npm run test:coverageზომავს საწყისი კოდის დაფარვას ძირითადი მოდულური ტესტების ნაკრებისთვის, გამორიცხავსtests/**-ს და მოიცავსopen-sse/**-ს- Pull Request-ებმა დებულებების/სტრიქონების/ფუნქციების/განშტოებების დაფარვის ბარიერი 60%+-ზე უნდა შეინარჩუნონ
- თუ PR ცვლის საწარმოო კოდს
src/,open-sse/,electron/ანbin/-ში, იმავე PR-ში უნდა დაემატოს ან განახლდეს ავტომატიზებული ტესტები npm run coverage:reportბეჭდავს ბოლო დაფარვის გაშვების დეტალურ, ფაილების მიხედვით დაყოფილ ანგარიშსnpm run test:coverage:legacyისტორიული შედარებისთვის ინარჩუნებს ძველ მეტრიკას- დაფარვის ეტაპობრივი გაუმჯობესების სამოქმედო გეგმისთვის იხილეთ
docs/ops/COVERAGE_PLAN.md
PR-ის გახსნამდე გამოიყენეთ Contribution Golden Path, რათა თქვენი ცვლილებისთვის მიზნობრივი ციკლი გაუშვათ. მოდულური ტესტების სრული ნაკრები (CI-ის 4 shard), Vitest, 60%+ დაფარვის ბარიერი და საწარმოო build CI-ის პასუხისმგებლობაა — მათი ლოკალურად გაშვება არ იძლევა დამატებით ინფორმაციას, რომელსაც PR-ის შემოწმებები უკვე არ მოგაწვდით, ხოლო შედარებით სუსტ კომპიუტერებზე შეიძლება სისტემა სრულად დატვირთოს (#8084):
- გაუშვით სატესტო ფაილები, რომლებიც თქვენს ცვლილებას ფარავს:
node --import tsx/esm --test tests/unit/<file>.test.ts - გაუშვით
npm run lint - საწარმოო კოდის ცვლილებისას იმავე PR-ში დაამატეთ ან განაახლეთ ავტომატიზებული ტესტები
- საწარმოო კოდის ცვლილებისას PR-ის აღწერაში მიუთითეთ შეცვლილი ან დამატებული სატესტო ფაილები
- თუ პროექტის საიდუმლოები CI-ში კონფიგურირებულია, შეამოწმეთ PR-ის SonarQube შედეგი
ტესტების მიმდინარე სტატუსი: 122 მოდულური სატესტო ფაილი, რომლებიც ფარავს:
- პროვაიდერის ტრანსლატორებსა და ფორმატის გარდაქმნას
- სიხშირის შეზღუდვას, circuit breaker-სა და მდგრადობას
- სემანტიკურ cache-ს, idempotency-სა და პროგრესის თვალყურის დევნებას
- მონაცემთა ბაზის ოპერაციებსა და სქემას (21 DB მოდული)
- OAuth ნაკადებსა და ავთენტიფიკაციას
- API endpoint-ების ვალიდაციას (Zod v4)
- MCP სერვერის ინსტრუმენტებსა და არეების აღსრულებას
- Memory და Skills სისტემებს
- ESLint — კომიტამდე გაუშვით
npm run lint - Prettier — კომიტისას ავტომატურად ფორმატირდება
lint-staged-ის მეშვეობით (2 სივრცე, წერტილ-მძიმეები, ორმაგი ბრჭყალები, 100-სიმბოლოიანი სიგანე, es5-ის სტილის ბოლო მძიმეები) - TypeScript —
src/-ში არსებული ყველა კოდი იყენებს.ts/.tsx-ს;open-sse/იყენებს.ts/.js-ს; დოკუმენტირება მოახდინეთ TSDoc-ით (@param,@returns,@throws) eval()აკრძალულია — ESLint უზრუნველყოფსno-eval,no-implied-eval,no-new-funcწესების დაცვას- Zod-ით ვალიდაცია — API-ის ყველა შეყვანის ვალიდაციისთვის გამოიყენეთ Zod v4-ის სქემები
- დასახელება: ფაილები = camelCase/kebab-case, კომპონენტები = PascalCase, კონსტანტები = UPPER_SNAKE
არასოდეს დატოვოთ catch განმარტების გარეშე. მიაკუთვნეთ ის ორი კატეგორიიდან ერთ-ერთს (ეს პრაქტიკაში ახორციელებს მკაცრ წესს — „არასოდეს ჩაყლაპოთ შეცდომები უხმოდ SSE ნაკადებში“):
-
განზრახული (ჩვენივე მაქსიმალური ძალისხმევით შესრულებული გასუფთავება/ტელემეტრია) — აქ შეცდომა მოსალოდნელი და უვნებელია; დაამატეთ მიზეზის განმარტების ერთსტრიქონიანი კომენტარი, ლოგირების გარეშე (ეს შეთანხმება თავიდან გვაცილებს ყოველ მოთხოვნაზე ლოგირებით წარმოქმნილ ხმაურს).
} catch {} // კლიენტის გათიშვის შემდეგ უკვე დახურული კონტროლერის დახურვა მოსალოდნელია
-
უნდა დალოგირდეს (გარე/გამომძახებლის მიერ მოწოდებული კოდი, ან ჩაყლაპვა ცვლის მართვის ნაკადს) — შეინარჩუნეთ catch (არასოდეს მისცეთ მას ნაკადის დარღვევის უფლება), მაგრამ გამოიტანეთ კონტექსტური
console.debug/warn, რათა შეცდომის აღმოჩენა შესაძლებელი იყოს.} catch (e) { console.debug("[STREAM] onFailure უკუგამოძახების შეცდომა:", e); }
პრაქტიკაში გამოყენებული მაგალითებისთვის იხილეთ open-sse/utils/stream.ts და open-sse/utils/streamHandler.ts.
src/ # TypeScript (.ts / .tsx)
├── app/ # Next.js 16 App Router
│ ├── (dashboard)/ # მართვის პანელის გვერდები (23 სექცია)
│ ├── api/ # API მარშრუტები (51 დირექტორია)
│ └── login/ # ავთენტიფიკაციის გვერდები (.tsx)
├── domain/ # პოლიტიკების ძრავა (policyEngine, comboResolver, costRules და სხვ.)
├── lib/ # ძირითადი ბიზნესლოგიკა (.ts)
│ ├── a2a/ # Agent-to-Agent v0.3 პროტოკოლის სერვერი
│ ├── acp/ # Agent Communication Protocol-ის რეესტრი
│ ├── compliance/ # შესაბამისობის პოლიტიკების ძრავა
│ ├── db/ # SQLite დომენის მოდულები + 130 მიგრაცია
│ ├── memory/ # მუდმივი სასაუბრო მეხსიერება
│ ├── oauth/ # OAuth-ის მომწოდებლები, სერვისები და დამხმარე საშუალებები
│ ├── skills/ # გაფართოებადი უნარების ფრეიმვორკი
│ ├── usage/ # გამოყენების აღრიცხვა და ღირებულების გამოთვლა
│ └── localDb.ts # მხოლოდ რეექსპორტის ფენა — აქ ლოგიკა არასოდეს დაამატოთ
├── middleware/ # მოთხოვნების შუალედური პროგრამული უზრუნველყოფა (promptInjectionGuard)
├── mitm/ # MITM პროქსი (სერტიფიკატი, DNS, სამიზნის მარშრუტიზაცია)
├── shared/
│ ├── components/ # React კომპონენტები (.tsx)
│ ├── constants/ # მომწოდებლების განსაზღვრებები (329), MCP-ის ფარგლები, მარშრუტიზაციის 19 სტრატეგია
│ ├── utils/ # ავტომატური ამომრთველი, სანიტაიზერი, ავთენტიფიკაციის დამხმარე საშუალებები
│ └── validation/ # Zod v4 სქემები
└── sse/ # SSE პროქსირების კონვეიერი
open-sse/ # @omniroute/open-sse სამუშაო სივრცე
├── executors/ # შემსრულებლის იმპლემენტაციის 89 მოდული
├── handlers/ # მოთხოვნების 11 დამმუშავებელი (ჩატი, პასუხები, ემბედინგები, სურათები და სხვ.)
├── mcp-server/ # MCP სერვერი (110 უნიკალური ხელსაწყო, 3 ტრანსპორტი, 33 მოქმედების სფერო)
├── services/ # ზედა დონის 178 სერვისი (combo, autoCombo, rateLimitManager და სხვ.)
├── translator/ # ფორმატების გარდამქმნელები (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/ # Responses API-ის გარდამქმნელი
└── utils/ # 22 დამხმარე მოდული (ნაკადი, TLS, პროქსი, ლოგირება)
electron/ # Electron-ის დესკტოპ-აპლიკაცია (მრავალპლატფორმული)
tests/
├── unit/ # Node.js ტესტების გამშვები (1,574 სატესტო ფაილი)
├── integration/ # ინტეგრაციული ტესტები
├── e2e/ # Playwright-ის ტესტები
├── security/ # უსაფრთხოების ტესტები
├── translator/ # გარდამქმნელისთვის სპეციფიკური ტესტები
└── load/ # დატვირთვის ტესტები
docs/
├── adr/ # არქიტექტურული გადაწყვეტილებების ჩანაწერები
├── architecture/ # სისტემის არქიტექტურა და მდგრადობა
├── comparison/ # OmniRoute ალტერნატივებთან შედარებით
├── compression/ # შეკუმშვის სახელმძღვანელოები და წესები
├── dev/ # დეველოპმენტის სახელმძღვანელოები
├── diagrams/ # არქიტექტურული დიაგრამები
├── frameworks/ # MCP, A2A, OpenCode, მეხსიერება, უნარები
├── guides/ # მომხმარებლის სახელმძღვანელო, Docker, გამართვა, პრობლემების მოგვარება
├── i18n/ # README-ის ინტერნაციონალიზებული თარგმანები
├── marketing/ # მარკეტინგული მასალები
├── ops/ # განთავსება, პროქსი, დაფარვა, გამოშვებები
├── providers/ # მომწოდებლებისთვის სპეციფიკური დოკუმენტაცია
├── reference/ # API ცნობარი, გარემოს ცვლადები, CLI ხელსაწყოები, უფასო დონეები
├── releases/ # გამოშვების შენიშვნები
├── routing/ # ავტომატური კომბინაციების ძრავა, მსჯელობის განმეორებითი შესრულება
├── screenshots/ # მართვის პანელის ეკრანის ანაბეჭდები
├── security/ # დამცავი მექანიზმები, შესაბამისობა, ფარულობა, ტოკენები
└── specs/ # დიზაინის სპეციფიკაციები
დაამატეთ src/shared/constants/providers.ts-ში — მოდულის ჩატვირთვისას მოწმდება Zod-ის მეშვეობით.
შექმენით შემსრულებელი open-sse/executors/your-provider.ts-ში, რომელიც საბაზო შემსრულებელს გააფართოებს.
შექმენით მოთხოვნის/პასუხის ტრანსლატორები open-sse/translator/-ში.
დაამატეთ OAuth-ის ავტორიზაციის მონაცემები src/lib/oauth/constants/oauth.ts-ში, ხოლო სერვისი — src/lib/oauth/services/-ში.
თუ ზედა დონის პროვაიდერი საჯარო OAuth client_id/საიდუმლოს ან Firebase Web API გასაღებს თავის საჯარო CLI-ში / ბრაუზერის პაკეტში ავრცელებს, არ ჩასვათ ის სტრიქონულ ლიტერალად. გამოიყენეთ resolvePublicCred() ფაილიდან open-sse/utils/publicCreds.ts და დაამატეთ შენიღბული ბაიტური ჩანაწერი EMBEDDED_DEFAULTS-ში. სრული სავალდებულო სამუშაო პროცესი აღწერილია docs/security/PUBLIC_CREDS.md-ში.
დამმუშავებლებსა/შემსრულებლებში კლიენტამდე მისული შეცდომის შეტყობინებები უნდა დამუშავდეს buildErrorBody() / sanitizeErrorMessage() ფუნქციებით ფაილიდან open-sse/utils/error.ts — არასოდეს ჩასვათ დაუმუშავებელი err.stack ან err.message Response-ის სხეულში. იხილეთ docs/security/ERROR_SANITIZATION.md.
დაამატეთ მოდელების განსაზღვრებები open-sse/config/providerRegistry.ts-ში.
დაწერეთ ერთეულოვანი ტესტები tests/unit/-ში, რომლებიც მინიმუმ შემდეგს მოიცავს:
- პროვაიდერის რეგისტრაცია
- მოთხოვნის/პასუხის ტრანსლაცია
- შეცდომების დამუშავება
- ტესტები წარმატებით სრულდება (
npm test) - ლინტინგი წარმატებით სრულდება (
npm run lint) - აგება წარმატებით სრულდება (
npm run build) - ახალი საჯარო ფუნქციებისა და ინტერფეისებისთვის დამატებულია TypeScript-ის ტიპები
- არ არის მყარად გაწერილი საიდუმლოები ან სარეზერვო მნიშვნელობები
- ზედა დონის საჯარო ავტორიზაციის მონაცემები ჩაშენებულია
resolvePublicCred()-ის მეშვეობით (იხილეთdocs/security/PUBLIC_CREDS.md) და არასოდეს — ლიტერალების სახით - შეცდომის პასუხები მუშავდება
buildErrorBody()/sanitizeErrorMessage()-ის მეშვეობით — პასუხის სხეულებში არ არის დაუმუშავებელი სტეკის კვალები (იხილეთdocs/security/ERROR_SANITIZATION.md) - გარსის ბრძანებები (
exec/spawn) შესრულების დროის მნიშვნელობებს გადასცემსenv-ის მეშვეობით და არა სტრიქონული ინტერპოლაციით - ყველა შეყვანილი მონაცემი შემოწმებულია Zod-ის სქემებით
- მომხმარებლისთვის ხილული ცვლილებებისთვის ცვლილებების ჟურნალის ფრაგმენტი დამატებულია
changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md-ში (იხილეთchangelog.d/README.md) — არ დაარედაქტიროთCHANGELOG.mdპირდაპირ; ფრაგმენტები გაერთიანდება გამოშვებისას და Pull Request-ებს შორის კონფლიქტს არასოდეს წარმოქმნის - დოკუმენტაცია განახლებულია (თუ საჭიროა)
- არ არის გახსნილი CodeQL-ის / Secret-Scanning-ის ახალი გაფრთხილებები, ან თითოეული მათგანი უარყოფილია ტექნიკური დასაბუთებით, რომელიც შესაბამის
docs/security/დოკუმენტს მიუთითებს - მარშრუტები, რომლებიც შვილობილ პროცესებს უშვებს (
/api/mcp/,/api/cli-tools/runtime/), კლასიფიცირებულია როგორცisLocalOnlyPath()ფაილშიsrc/server/authz/routeGuard.ts— იხილეთ მკაცრი წესი #15 - commit-ის შეტყობინებებში არ არის
Co-Authored-Byტრეილერები — commit-ები მხოლოდ რეპოზიტორიის მფლობელის Git-ის იდენტობის ქვეშ უნდა გამოჩნდეს (მკაცრი წესი #16)
რელიზები იმართება /generate-release სამუშაო პროცესის მეშვეობით. ახალი GitHub Release-ის შექმნისას პაკეტი GitHub Actions-ის მეშვეობით ავტომატურად ქვეყნდება npm-ზე.
VPS-ზე განთავსებისთვის გამოიყენეთ npm run build:release (npm run build-ის ნაცვლად) — ის ასრულებს
სუფთა ხელახალ აგებას, კრებს პაკეტს dist/-ში და ქმნის dist/BUILD_SHA საკონტროლო ფაილს.
შემდეგ გამოიყენეთ /deploy-vps-*-cc უნარები, რომლებიც rsync-ის მეშვეობით dist/-ს დისტანციურ app/ დირექტორიაში ასინქრონებენ.
- არქიტექტურა: იხილეთ
docs/architecture/ARCHITECTURE.md - API-ის ცნობარი: იხილეთ
docs/reference/API_REFERENCE.md - უსაფრთხოების დოკუმენტაცია:
docs/security/CLI_TOKEN.md,docs/security/ROUTE_GUARD_TIERS.md,docs/security/ERROR_SANITIZATION.md,docs/security/PUBLIC_CREDS.md - ოპერაციების დოკუმენტაცია:
docs/ops/SQLITE_RUNTIME.md - საკითხები: github.com/diegosouzapw/OmniRoute/issues
- ADR-ები: არქიტექტურული გადაწყვეტილებების ჩანაწერებისთვის იხილეთ
docs/adr/