pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-19 13:23:50 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): mirror every docs/ page in all 65 locales (#14106)

Browse Source 
* feat(docs): mirror every docs/ page in all 65 locales

Extends the documentation mirrors from the 22-page core set (#13940) to
every Markdown page under docs/: 152 sources x 65 locales = 9,880 mirrors
(6,208 new), language bars rewritten for the full locale list, state
adopted so the blocking drift gate now covers all 152 pages.

run-translation.mjs: an oversized block made only of table rows or list
items (PROVIDER_REFERENCE.md 244-row table, FREE_TIERS.md 71-item list) is
cut at item boundaries and rejoined without a blank line — the single
16-40 KB request outlived the backend socket for verbose scripts. 48
older mirrors whose tables had lost rows were retranslated with --force.

* docs(i18n): refresh mirrors for the sources the base changed since the branch cut

Section-level retranslation of the 29 docs (and README.md) whose source
or mirrors moved on release/v3.8.51 during the run, then state adoption;
the drift gate is green again on the merged tree.
This commit is contained in:
Diego Rodrigues de Sa e Souza
2026-09-18 13:16:46 -03:00
committed by GitHub
parent c059b77823
commit 8feea123bb
9014 changed files with 2438195 additions and 38940 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138830
.i18n-state.json
View File

File diff suppressed because it is too large Load Diff

1
changelog.d/features/0000-i18n-docs-full-coverage.md Normal file
View File

@@ -0,0 +1 @@
- **feat(docs):** every Markdown page under `docs/` is now mirrored in all 65 dashboard locales, not only the 22-page core set — 152 sources × 65 locales = 9,880 mirrors (6,208 new), with the 🌐 language bar of every mirror rewritten for the full locale list. The docs drift gate (`npm run i18n:check`, blocking in CI) derives its scope from the tree, so it now guards all 152 pages. Found and fixed by the run in `scripts/i18n/run-translation.mjs`: a markdown table or tight bullet list with no blank line inside it (PROVIDER_REFERENCE.md's 244-row table, FREE_TIERS.md's 71-item list) was sent as one 16–40 KB request that outlived the backend socket for verbose scripts (Greek, Amharic); oversized runs of table rows or list items are now cut at item boundaries and rejoined without a blank line, so no chunk exceeds 6 KB across the docs tree. 48 older mirrors whose tables had lost rows were retranslated with the fixed chunker.

233
docs/i18n/am/README.md
View File

@@ -6,30 +6,30 @@
<div align="center">
<img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute ዳሽቦርድ" width="820"/>
<img src="./docs/screenshots/MainOmniRoute.png" alt="የOmniRoute ዳሽቦርድ" width="820"/>
<br/>
<br/>
# 🚀 OmniRoute — ነፃው የAI መግቢያ
# 🚀 OmniRoute — ነፃው የAI ጌትዌይ
<img src="./docs/diagrams/readme-hero.svg" width="100%" alt="OmniRoute — ኮድ መጻፍዎን ፈጽሞ አያቁሙ። እያንዳንዱ የAI መሣሪያ → 359 አቅራቢዎች — 150+ ነፃ — በአንድ endpoint በኩል። Claude Code፣ Codex፣ Cursor፣ Cline፣ Copilot እና Antigravity ከነፃ Claude / GPT / Gemini ጋር፣ በራስ-ሰር ወደ ተለዋጭ አቅራቢ የመቀየር ችሎታ። RTK + Caveman የተደራራቢ ማመቂያ 15–95% ቶከኖችን (~89% በአማካይ) ይቆጥባል — ገደቦችን ፈጽሞ አይድረሱ። 359 የAI አቅራቢዎች · 150+ ነፃ ደረጃዎች · ~1.47B ነፃ ቶከኖች/ወር · 19 የማስተላለፊያ ስልቶች · ለመጀመር $0።"/>
<img src="./docs/diagrams/readme-hero.svg" width="100%" alt="OmniRoute — ኮድ መጻፍዎን ፈጽሞ አያቁሙ። እያንዳንዱ የAI መሣሪያ → 359 አቅራቢዎች — 150+ ነፃ — በአንድ መዳረሻ። Claude Code፣ Codex፣ Cursor፣ Cline፣ Copilot እና Antigravity ወደ ነፃ Claude / GPT / Gemini ከራስ-ሰር ምትክ ሽግግር ጋር። የRTK + Caveman የተደራረበ ማመቂያ 15–95% ቶከኖችን (~89% በአማካይ) ይቆጥባል — ገደቦች ላይ ፈጽሞ አይድረሱ። 359 የAI አቅራቢዎች · 150+ ነፃ ደረጃዎች · ~1.62B ነፃ ቶከኖች/በወር · 19 የማዘዋወሪያ ስልቶች · ለመጀመር $0።"/>
</div>
<div align="center">
## 💰 በወር ~1.47B ነፃ ቶከኖች
## 💰 በወር ~1.62B ነፃ ቶከኖች
</div>
> ነፃ ደረጃዎችን በእጅ ማጣመር አስቸጋሪ ነው — በደርዘን የሚቆጠሩ SDKዎች፣ በደርዘን የሚቆጠሩ የፍጥነት ገደቦች፣ እና በእርግጥ ምን ያህል እንዳለዎት የማወቂያ መንገድ የለም። OmniRoute **በ34 ተደጋጋሚ pool keys ውስጥ 452 የነፃ ደረጃ ግቤቶችን** ይዘረዝራል፤ የቶከን ዋና ቁጥሩንም **ይፋ የተደረገ አዎንታዊ ወርሃዊ በጀት ካላቸው 16 pools እና ከአምስት በሞዴል የGroq ገደቦች** ያሰላል፤ በጋራ pool የተደጋገሙትንም ያስወግዳል። ከክልላዊ የማንነት ማረጋገጫ በኋላ ብቻ የሚከፈቱ ኮታዎች (በአሁኑ ጊዜ፦ ModelScope) ለብቻቸው ይታያሉ፤ +~6M ከክልላዊ የማንነት ማረጋገጫ ጀርባ ናቸው፣ እና በዋናው ቁጥር ውስጥ ፈጽሞ አይደመሩም። ውጤቱ በዳሽቦርዱ (`/dashboard/free-tiers`) ላይ እንዲታይ ይቆያል።
> ነፃ ደረጃዎችን በእጅ ማደራጀት አስቸጋሪ ነው — በደርዘን የሚቆጠሩ SDKዎች፣ በደርዘን የሚቆጠሩ የፍጥነት ገደቦች፣ እና በእውነት ምን ያህል እንዳለዎት የማወቂያ መንገድ የለም። OmniRoute **በ35 ተደጋጋሚ የpool ቁልፎች ውስጥ 491 የነፃ ደረጃ ግቤቶችን** ይመዘግባል፣ እና የቶከን ዋና ቁጥሩን **ይፋ የሆነ አዎንታዊ ወርሃዊ በጀት ካላቸው 17 poolዎች እና አምስት በሞዴል የተወሰኑ የGroq ገደቦች** ያሰላል፤ በጋራ pool የሚጋሩትንም አንድ ጊዜ ብቻ ይቆጥራል። ከክልላዊ ማንነት ማረጋገጫ በኋላ ብቻ የሚከፈቱ ኮታዎች (በአሁኑ ጊዜ፦ ModelScope) ለየት ብለው ይታያሉ፤ +~6M ከክልላዊ ማንነት ማረጋገጫ በስተጀርባ ይገኛሉ፣ እና በዋናው ቁጥር ውስጥ ፈጽሞ አይደመሩም። ውጤቱ በዳሽቦርዱ (`/dashboard/free-tiers`) ላይ ሁልጊዜ ይታያል።
<img src="./docs/diagrams/free-tier-budget.svg" width="100%" alt="የOmniRoute ነፃ ደረጃ በጀት ካርድ፦ በቋሚነት በወር ~1.47B ነፃ ቶከኖች፣ ከምዝገባ ክሬዲቶች ጋር በመጀመሪያው ወር እስከ ~2.07B፤ በአንድ endpoint ጀርባ 452 የተዘረዘሩ የነፃ ደረጃ ግቤቶችን ከሚሸፍኑ 34 በሰነድ የተቀመጡ ተደጋጋሚ pool keys የተገኘ። ታማኝ በpool የተደጋገሙትን ያስወገደ ስሌት — እያንዳንዱ የጋራ pool አንድ ጊዜ ብቻ ይቆጠራል፤ ይህም ይፋ የተደረገ አዎንታዊ ወርሃዊ የቶከን በጀት ያላቸውን 16 ተደጋጋሚ pools እና አምስት በሞዴል የGroq ገደቦችን ያካትታል፤ እርስዎ እንዲወስኑ 13 አቅራቢዎች በውሎች-ስጋት ዝርዝር ውስጥ እንዲወገዱ ምልክት ተደርጎባቸዋል። የበጀት አሞሌው Mistral 1B፣ Nara 210M፣ LLM7 150M፣ Groq 30M (አምስት በሞዴል ገደቦች) እና አነስተኛ pools ያካትታል፤ እንዲሁም የመጀመሪያ ወር የምዝገባ ክሬዲቶችና በቋሚነት ነፃ የሆኑ የቶከን ገደብ የሌላቸው አቅራቢዎች ዋናውን ቁጥር ፈጽሞ እንዳያጋንኑ ለብቻቸው ይታያሉ። በ`/dashboard/free-tiers` ላይ የቀጥታ ጥቅም ላይ የዋለ/የቀረ።"/>
<img src="./docs/diagrams/free-tier-budget.svg" width="100%" alt="የOmniRoute ነፃ ደረጃ በጀት ካርድ፦ በወር ~1.62B ነፃ ቶከኖች በቋሚነት፣ በመጀመሪያው ወር ከምዝገባ ክሬዲቶች ጋር እስከ ~2.22B፤ ከአንድ endpoint በስተጀርባ 491 የተመዘገቡ የነፃ ደረጃ ግቤቶችን ከሚሸፍኑ 35 በሰነድ የተገለጹ ተደጋጋሚ የpool ቁልፎች። ታማኝ፣ የpool ድግግሞሽን ያስወገደ ስሌት — እያንዳንዱ የጋራ pool አንድ ጊዜ ብቻ ይቆጠራል፤ ይህም ይፋ የሆነ አዎንታዊ ወርሃዊ የቶከን በጀት ያላቸውን 17 ተደጋጋሚ poolዎች እና አምስት በሞዴል የተወሰኑ የGroq ገደቦችን ያካትታል፤ 13 አቅራቢዎች በውል-ስጋት ካታሎጉ ውስጥ እንዲወገዱ ምልክት ተደርጎባቸዋል፣ ስለዚህ እርስዎ ይወስናሉ። የበጀት አሞሌው Mistral 1B፣ Nara 210M፣ LLM7 150M፣ xKiro 150M፣ Groq 30M (አምስት በሞዴል የተወሰኑ ገደቦች) እና አነስተኛ poolዎችን ያካትታል፤ በተጨማሪም የመጀመሪያ ወር የምዝገባ ክሬዲቶች እና በቋሚነት ነፃ የሆኑ የቶከን ገደብ የሌላቸው አቅራቢዎች ዋናውን ቁጥር እንዳያጋንኑ ለየት ብለው ይታያሉ። የቀጥታ ጥቅም ላይ የዋለ/የቀረ መጠን በ /dashboard/free-tiers።"/>
> የቀጥታው `/dashboard/free-tiers` ገጽ እነማዊ ማጠቃለያ። ሙሉ ዘዴው (የpool ተደጋጋሚነት ማስወገድ፣ የክሬዲት ደረጃዎች፣ የአቅራቢ ውሎች)፦ **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**።
> የቀጥታው `/dashboard/free-tiers` ገጽ እነማዊ ማጠቃለያ። ሙሉ ዘዴው (የpool ድግግሞሽ ማስወገድ፣ የክሬዲት ደረጃዎች፣ የአቅራቢ ውሎች)፦ **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**።
>
> <sub>እነዚህ ቁጥሮች በየሁለት ሳምንቱ ከቀጥታው ዝርዝር ጋር እንደገና ኦዲት ይደረግባቸዋል፣ እና **በሁለቱም አቅጣጫ ይንቀሳቀሳሉ** — አንድ አቅራቢ ነፃ ደረጃውን ሲያቆም ቁጥሩ ይቀንሳል፤ አዲስ ሲጨመር ደግሞ ይጨምራል። ዝርዝሩ በእርግጥ የሚያሰላውን እናትማለን፤ ወደ ላይ የተጠጋጋ ምርጥ ሁኔታን ፈጽሞ አናትምም።</sub>
> <sub>እነዚህ ቁጥሮች በየሁለት ሳምንቱ ከቀጥታው ካታሎግ ጋር እንደገና ኦዲት ይደረግባቸዋል፣ እና **ወደ ሁለቱም አቅጣጫዎች ይንቀሳቀሳሉ** — አንድ አቅራቢ ነፃ ደረጃውን ሲያቆም ቁጥሩ ይቀንሳል፤ አዲስ ሲጨመር ደግሞ ይጨምራል። የምናትመው ካታሎጉ በእውነት የሚያሰላውን ነው፤ ወደ ላይ የተጠጋጋ ምርጥ ሁኔታን ፈጽሞ አናትምም።</sub>
<br/>
@@ -37,29 +37,29 @@
<h3>
⭐ OMNIROUTE ገንዘብ እንዲቆጥቡ እና ሥራዎን እንዲያቀልሉ ከረዳዎት repoውን Star ያድርጉ።
⭐ OMNIROUTE ገንዘብ እንዲቆጥቡ እና ሥራዎን እንዲያቀሉ ከረዳዎት repoውን Star ያድርጉ።
</h3>
[![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)
[![ኮከቦች](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)
<a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
[![Star History Rank](https://api.star-history.com/badge?repo=diegosouzapw/OmniRoute&theme=dark)](https://www.star-history.com/diegosouzapw/omniroute)
[![የStar ታሪክ ደረጃ](https://api.star-history.com/badge?repo=diegosouzapw/OmniRoute&theme=dark)](https://www.star-history.com/diegosouzapw/omniroute)
[![olud.ai](https://olud.ai/badge.php?tool=diegosouzapw-omniroute)](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 ማህበረሰቡን ይቀላቀሉ
**👋 ተንከባካቢውን ይከተሉ — ስለ አዳዲስ አቅራቢዎች፣ releases እና ጠቃሚ ምክሮች ቀድመው ይወቁ፦**
**👋 ጠብቃውን ይከተሉ — ስለ አዳዲስ አቅራቢዎች፣ ልቀቶች እና ጠቃሚ ምክሮች ቀድመው ይወቁ፦**
[![Diegoን በLinkedIn ይከተሉ](https://img.shields.io/badge/Follow_Diego_on-LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/diegosouzapw/)
[![@diegosouzapwን በGitHub ይከተሉ](https://img.shields.io/github/followers/diegosouzapw?style=for-the-badge&logo=github&logoColor=white&label=Follow%20on%20GitHub&color=181717)](https://github.com/diegosouzapw)
[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/U47eFqAXCn)
[![Telegram](https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/omnirouteOficial)
[![WhatsApp Global](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4)
[![WhatsApp Brasil](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4)
[![ድረ-ገጽ](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
[![ዓለም አቀፍ WhatsApp](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4)
[![WhatsApp ብራዚል](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4)
[![ድረ ገጽ](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
**ጥያቄዎች፣ የአቅራቢ ምክሮች፣ የወደፊት ዕቅድ እና ድጋፍ → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 ዓለም አቀፍ](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4) / [🇧🇷 ብራዚል](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4) / [ፖርታል](https://portal.sthub.com.br/communities/groups/st-hub/channels/Omniroute-World-8kRjmK)**
**ጥያቄዎች፣ የአቅራቢ ምክሮች፣ የልማት እቅድ እና ድጋፍ → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 ዓለም አቀፍ](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4) / [🇧🇷 ብራዚል](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4) / [ፖርታል](https://portal.sthub.com.br/communities/groups/st-hub/channels/Omniroute-World-8kRjmK)**
<br/>
@@ -67,64 +67,64 @@
<div align="center">
| | v3.8.49 | **v3.8.50** | `v3.8.51+` |
| --------------------- | :-----: | :----------------: | :----------: |
| 🌐 አቅራቢዎች | 290 | **352** | ተጨማሪ በወረፋ ላይ |
| 🧠 ልዩ የውይይት ሞዴል መለያዎች | 1185 | **1312** | — |
| 🖼️ የሞዳሊቲ ድልድይ | — | 🆕 ምስል + ድምፅ + ቪዲዮ | — |
| 📡 የራዳር ነፃ ካታሎግ | — | 🆕 በፈቃድ የሚነቃ | — |
| ⚖️ ኮታን ያገናዘበ መርሐግብር | — | 🆕 Quota-Share | — |
| 📊 የኮታ ቴሌሜትሪ | — | 🆕 ቀጥታ | — |
| | v3.8.49 | **v3.8.50** | `v3.8.51+` |
| ------------------- | :-----: | :----------------: | :---------: |
| 🌐 አቅራቢዎች | 290 | **357** | ተጨማሪ ወረፋ ላይ |
| 🧠 ልዩ የውይይት ሞዴል IDs | 1185 | **1312** | — |
| 🖼️ የሞዳሊቲ ድልድይ | — | 🆕 ምስል + ድምፅ + ቪዲዮ | — |
| 📡 ነፃ የRadar ካታሎግ | — | 🆕 በምርጫ የሚነቃ | — |
| ⚖️ ኮታን ያገናዘበ መርሐግብር | — | 🆕 Quota-Share | — |
| 📊 የኮታ ቴሌሜትሪ | — | 🆕 ቀጥታ | — |
**→ [የወደፊት ዕቅድ](ROADMAP.md) — ወደ `v3.9.0 LTS` በፍጥነት በመጓዝ ላይ**
**→ [የእድገት ዕቅድ](ROADMAP.md) — ወደ `v3.9.0 LTS` በመጓዝ ላይ**
</div>
<br/>
## 🧩 ይገኛል
## 🧩 የሚገኝ
[![የnpm ስሪት](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
[![npm ስሪት](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
![ወርሃዊ NPM](https://img.shields.io/npm/dm/omniroute?label=npm/month&color=cb3837&logo=npm)
[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
[![ፈቃድ፦ MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
![የDocker ማውረዶች](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?label=docker%20pulls&logo=docker&color=2496ED)
![የElectron ማውረዶች](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=electron%20downloads&logo=electron&color=47848F)
![Docker ማውረዶች](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?label=docker%20pulls&logo=docker&color=2496ED)
![Electron ማውረዶች](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=electron%20downloads&logo=electron&color=47848F)
<table>
<tr>
<td align="right"><b>🚀 ጀምር</b></td>
<td align="right"><b>🚀 ይጀምሩ</b></td>
<td align="center"><a href="#-quick-start">🚀 ፈጣን ጅምር</a></td>
<td align="center"><a href="#-more-install-methods--docker-source-pnpm-arch">📦 ጫን</a></td>
<td align="center"><a href="#-works-the-second-you-install-it--no-keys-no-config">🆓 ምንም ውቅር አያስፈልግም</a></td>
<td align="center"><a href="#-more-install-methods--docker-source-pnpm-arch">📦 ይጫኑ</a></td>
<td align="center"><a href="#-works-the-second-you-install-it--no-keys-no-config">🆓 ያለ ውቅር</a></td>
</tr>
<tr>
<td align="right"><b>💡 ተማር</b></td>
<td align="right"><b>💡 ይማሩ</b></td>
<td align="center"><a href="#-the-promise">💥 ቃል ኪዳኑ</a></td>
<td align="center"><a href="#-why-omniroute">🤔 OmniRoute ለምን?</a></td>
<td align="center"><a href="#-why-omniroute">🤔 OmniRoute ለምን</a></td>
<td align="center"><a href="#-what-sets-omniroute-apart">🏆 ልዩ የሚያደርገው</a></td>
</tr>
<tr>
<td align="right"><b>⚙️ ባህሪያት</b></td>
<td align="center"><a href="#-combos--the-flagship">🎯 ጥምረቶች</a></td>
<td align="center"><a href="#-352-ai-providers--154-catalog-marked-free">🌐 አቅራቢዎች</a></td>
<td align="center"><a href="#-full-cli--a2a--mcp">🔌 CLI &amp; MCP</a></td>
<td align="center"><a href="#-357-ai-providers--152-catalog-marked-free">🌐 አቅራቢዎች</a></td>
<td align="center"><a href="#-full-cli--a2a--mcp">🔌 CLI እና MCP</a></td>
</tr>
<tr>
<td align="right"></td>
<td align="center"><a href="#%EF%B8%8F-save-1595-tokens--automatically">🗜️ መጭመቅ</a></td>
<td align="center"><a href="#%EF%B8%8F-where-omniroute-runs--anywhere">🖥️ የሚሠራበት ቦታ</a></td>
<td align="center"><a href="#%EF%B8%8F-save-1595-tokens--automatically">🗜️ ማመቅ</a></td>
<td align="center"><a href="#%EF%B8%8F-where-omniroute-runs--anywhere">🖥️ የሚሰራበት ቦታ</a></td>
<td align="center"><a href="#-private--local-first">🔒 የግል</a></td>
</tr>
<tr>
<td align="right"><b>👀 ይመልከቱት</b></td>
<td align="center"><a href="#-omniroute-in-action">🎬 በተግባር</a></td>
<td align="center"><a href="#-whats-new">✨ አዲስ ነገር</a></td>
<td align="center"><a href="#-compatible-clis--coding-agents">🤖 ተኳኋኝ CLIs</a></td>
<td align="center"><a href="#-compatible-clis--coding-agents">🤖 ተኳዃኝ CLIዎች</a></td>
</tr>
<tr>
<td align="right"><b>💚 ድጋፍ</b></td>
<td align="center"><a href="#-support-omniroute">💚 ድጋፍ / ልገሳ</a></td>
<td align="center"><a href="#-support-omniroute">💚 ይደግፉ / ይለግሱ</a></td>
<td align="center"><a href="#-community--help">💬 ማህበረሰብ</a></td>
<td align="center"><a href="#-sponsors">💖 ስፖንሰሮች</a></td>
</tr>
@@ -139,7 +139,7 @@
</div>
<div align="center">
<b>🌐 በ62 ቋንቋዎች</b>
<b>🌐 በ66 ቋንቋዎች</b>
<br/><br/>
<a href="README.md"><img src="docs/assets/flags/us.svg" width="30" alt="እንግሊዝኛ (en)" title="እንግሊዝኛ (en)"></a>
<a href="docs/i18n/pt-BR/README.md"><img src="docs/assets/flags/br.svg" width="30" alt="ፖርቱጋልኛ — ብራዚል (pt-BR)" title="ፖርቱጋልኛ — ብራዚል (pt-BR)"></a>
@@ -148,7 +148,7 @@
<a href="docs/i18n/fr/README.md"><img src="docs/assets/flags/fr.svg" width="30" alt="ፈረንሳይኛ (fr)" title="ፈረንሳይኛ (fr)"></a>
<a href="docs/i18n/it/README.md"><img src="docs/assets/flags/it.svg" width="30" alt="ጣሊያንኛ (it)" title="ጣሊያንኛ (it)"></a>
<a href="docs/i18n/de/README.md"><img src="docs/assets/flags/de.svg" width="30" alt="ጀርመንኛ (de)" title="ጀርመንኛ (de)"></a>
<a href="docs/i18n/nl/README.md"><img src="docs/assets/flags/nl.svg" width="30" alt="ደች (nl)" title="ደች (nl)"></a>
<a href="docs/i18n/nl/README.md"><img src="docs/assets/flags/nl.svg" width="30" alt="ደችኛ (nl)" title="ደችኛ (nl)"></a>
<a href="docs/i18n/ru/README.md"><img src="docs/assets/flags/ru.svg" width="30" alt="ሩሲያኛ (ru)" title="ሩሲያኛ (ru)"></a>
<a href="docs/i18n/uk-UA/README.md"><img src="docs/assets/flags/ua.svg" width="30" alt="ዩክሬንኛ (uk-UA)" title="ዩክሬንኛ (uk-UA)"></a>
<a href="docs/i18n/pl/README.md"><img src="docs/assets/flags/pl.svg" width="30" alt="ፖላንድኛ (pl)" title="ፖላንድኛ (pl)"></a>
@@ -174,10 +174,10 @@
<a href="docs/i18n/gu/README.md"><img src="docs/assets/flags/in.svg" width="30" alt="ጉጃራቲ (gu)" title="ጉጃራቲ (gu)"></a>
<a href="docs/i18n/mr/README.md"><img src="docs/assets/flags/in.svg" width="30" alt="ማራቲ (mr)" title="ማራቲ (mr)"></a>
<a href="docs/i18n/ta/README.md"><img src="docs/assets/flags/in.svg" width="30" alt="ታሚል (ta)" title="ታሚል (ta)"></a>
<a href="docs/i18n/te/README.md"><img src="docs/assets/flags/in.svg" width="30" alt="ተሉጉ (te)" title="ተሉጉ (te)"></a>
<a href="docs/i18n/te/README.md"><img src="docs/assets/flags/in.svg" width="30" alt="ቴሉጉ (te)" title="ቴሉጉ (te)"></a>
<a href="docs/i18n/bn/README.md"><img src="docs/assets/flags/bd.svg" width="30" alt="ቤንጋሊ (bn)" title="ቤንጋሊ (bn)"></a>
<a href="docs/i18n/ur/README.md"><img src="docs/assets/flags/pk.svg" width="30" alt="ኡርዱ (ur)" title="ኡርዱ (ur)"></a>
<a href="docs/i18n/fa/README.md"><img src="docs/assets/flags/ir.svg" width="30" alt="ፋርስኛ (fa)" title="ፋርስኛ (fa)"></a>
<a href="docs/i18n/fa/README.md"><img src="docs/assets/flags/ir.svg" width="30" alt="ፋርሲ (fa)" title="ፋርሲ (fa)"></a>
<a href="docs/i18n/ar/README.md"><img src="docs/assets/flags/sa.svg" width="30" alt="ዓረብኛ (ar)" title="ዓረብኛ (ar)"></a>
<a href="docs/i18n/he/README.md"><img src="docs/assets/flags/il.svg" width="30" alt="ዕብራይስጥ (he)" title="ዕብራይስጥ (he)"></a>
<a href="docs/i18n/tr/README.md"><img src="docs/assets/flags/tr.svg" width="30" alt="ቱርክኛ (tr)" title="ቱርክኛ (tr)"></a>
@@ -189,7 +189,7 @@
<a href="docs/i18n/lt/README.md"><img src="docs/assets/flags/lt.svg" width="30" alt="ሊቱዌኒያኛ (lt)" title="ሊቱዌኒያኛ (lt)"></a>
<a href="docs/i18n/et/README.md"><img src="docs/assets/flags/ee.svg" width="30" alt="ኢስቶኒያኛ (et)" title="ኢስቶኒያኛ (et)"></a>
<a href="docs/i18n/lv/README.md"><img src="docs/assets/flags/lv.svg" width="30" alt="ላትቪያኛ (lv)" title="ላትቪያኛ (lv)"></a>
<a href="docs/i18n/sl/README.md"><img src="docs/assets/flags/si.svg" width="30" alt="ስሎቬኒያኛ (sl)" title="ስሎቬኒያኛ (sl)"></a>
<a href="docs/i18n/sl/README.md"><img src="docs/assets/flags/si.svg" width="30" alt="ስሎቬንያኛ (sl)" title="ስሎቬንያኛ (sl)"></a>
<a href="docs/i18n/mt/README.md"><img src="docs/assets/flags/mt.svg" width="30" alt="ማልትኛ (mt)" title="ማልትኛ (mt)"></a>
<a href="docs/i18n/ga/README.md"><img src="docs/assets/flags/ie.svg" width="30" alt="አይሪሽ (ga)" title="አይሪሽ (ga)"></a>
<a href="docs/i18n/kn/README.md"><img src="docs/assets/flags/in.svg" width="30" alt="ካናዳ (kn)" title="ካናዳ (kn)"></a>
@@ -203,6 +203,10 @@
<a href="docs/i18n/ha/README.md"><img src="docs/assets/flags/ng.svg" width="30" alt="ሃውሳ (ha)" title="ሃውሳ (ha)"></a>
<a href="docs/i18n/yo/README.md"><img src="docs/assets/flags/ng.svg" width="30" alt="ዮሩባ (yo)" title="ዮሩባ (yo)"></a>
<a href="docs/i18n/ig/README.md"><img src="docs/assets/flags/ng.svg" width="30" alt="ኢግቦ (ig)" title="ኢግቦ (ig)"></a>
<a href="docs/i18n/am/README.md"><img src="docs/assets/flags/et.svg" width="30" alt="አማርኛ (am)" title="አማርኛ (am)"></a>
<a href="docs/i18n/uz/README.md"><img src="docs/assets/flags/uz.svg" width="30" alt="ኡዝቤክኛ (uz)" title="ኡዝቤክኛ (uz)"></a>
<a href="docs/i18n/ka/README.md"><img src="docs/assets/flags/ge.svg" width="30" alt="ጆርጂያኛ (ka)" title="ጆርጂያኛ (ka)"></a>
<a href="docs/i18n/hy/README.md"><img src="docs/assets/flags/am.svg" width="30" alt="አርመንኛ (hy)" title="አርመንኛ (hy)"></a>
</div>
<br/>
@@ -210,32 +214,32 @@
<div align="center">
## 🆓 እንደጫኑት ወዲያውኑ ይሰራል — ቁልፍ አያስፈልግም፣ ውቅር አያስፈልግም
## 🆓 እንደጫኑት ወዲያውኑ ይሰራል — ቁልፎች የሉም፣ ውቅር የለም
</div>
<img src="./docs/diagrams/works-zero-config.svg" width="100%" alt="እንደጫኑት ወዲያውኑ ይሰራል — ምንም ውቅር አያስፈልግም። ሦስት ደረጃዎች፦ 1. ይጫኑ — npm i -g omniroute፣ ሰርቨሩ በ localhost:20128 ላይ ይነሳል። 2. መሣሪያዎን ወደ http://localhost:20128/v1 ያመልክቱ — ማንኛውም ከOpenAI ጋር ተኳሃኝ የሆነ መሣሪያ (Claude Code፣ Cursor፣ Cline)። 3. ምላሽ ይሰጣል — ያለ API ቁልፍ፣ ያለ ምዝገባ እና ያለ ውቅር ፈጣን ምላሽ ለማግኘት auto ሞዴልን ይጥሩ። ቁልፍ የማይፈልገው OpenCode Free አቅራቢ አስቀድሞ ከauto ጥምረት ጋር ተያይዟል፣ ስለዚህ አዲስ ጭነት ወዲያውኑ ምላሽ ይሰጣል።"/>
<img src="./docs/diagrams/works-zero-config.svg" width="100%" alt="እንደጫኑት ወዲያውኑ ይሰራል — ምንም ውቅር አያስፈልግም። ሦስት ደረጃዎች፦ 1. ይጫኑ — npm i -g omniroute፣ አገልጋዩ localhost:20128 ላይ ይነሳል። 2. መሣሪያዎን ወደ http://localhost:20128/v1 ያመልክቱ — ማንኛውም ከOpenAI ጋር ተኳሃኝ የሆነ መሣሪያ (Claude Code, Cursor, Cline)። 3. መልስ ይሰጣል — የAPI ቁልፍ፣ ምዝገባ ወይም ውቅር ሳያስፈልግ ፈጣን ምላሽ ለማግኘት model autoን ይጥሩ። ቁልፍ የማይፈልገው አቅራቢ OpenCode Free ከauto ጥምረት ጋር አስቀድሞ ተገናኝቷል፤ ስለዚህ አዲስ ጭነት ወዲያውኑ ምላሽ ይሰጣል።"/>
```bash
# አዲስ ጭነት፣ ምንም የመግቢያ ማረጋገጫ አያስፈልግም — `auto` አስቀድሞ ይሰራል፦
# አዲስ ጭነት፣ ምንም የመግቢያ ማረጋገጫ የለም — `auto` አስቀድሞ ይሰራል፦
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
<sub>የተወሰነ ነፃ ባክኤንድ ይመርጣሉ? `oc/…`ን (OpenCode Free) በቀጥታ ይጥሩ። ከዚያ `auto`ን ይጠቀሙ እና OmniRoute እንዲመርጥ ይፍቀዱለት።</sub>
<sub>የተወሰነ ነፃ backend ይመርጣሉ? `oc/…` (OpenCode Free)ን በቀጥታ ይጥሩ። ከዚያ `auto`ን ይጠቀሙና OmniRoute እንዲመርጥ ይፍቀዱ።</sub>
<sub>📦 ለ**Python, Node.js, PHP, እና cURL** በቀጥታ ቀድተው የሚለጥፏቸው ፈጣን መጀመሪያ ስክሪፕቶች → [`examples/quickstart/`](examples/quickstart/)</sub>
<sub>📦 ለ**Python, Node.js, PHP, እና cURL** ቀድተው የሚለጥፏቸው ፈጣን መጀመሪያ ስክሪፕቶች → [`examples/quickstart/`](examples/quickstart/)</sub>
<br/>
<div align="center">
# 💥 የምንገባው ቃል
# 💥 ቃል የተገባው
</div>
<img src="./docs/diagrams/promise-pillars.svg" width="100%" alt="የምንገባው ቃል — አንድ የመዳረሻ ነጥብ እና 359 አቅራቢዎች። ሌላ ጤናማ ዒላማ እስካለ ድረስ ራስ-ሰር የመጠባበቂያ ሽግግር ማስተላለፉን ይቀጥላል። ስድስት ምሰሶዎች፦ በ359 አቅራቢዎች ላይ የሚሰራ ጠንካራ የመጠባበቂያ ሽግግር · ብቁ በሆኑ የሥራ ጫናዎች ላይ እስከ 95% የቶከን ቁጠባ · በ150+ ነፃ ደረጃዎች እና 53 ተደጋጋሚ/ቁልፍ አልባ ለዘላለም ነፃ አቅራቢዎች በ$0 መጀመር · በአንድ ውቅር 36 CLI/ኤጀንት ውህደቶች · በ/v1 ላይ የOpenAI፣ Claude፣ Gemini እና Responses API ተኳሃኝነት · የሰርኪዩት ብሬከሮችን፣ TLS ስውርነትን፣ MCP 110 መሣሪያዎችን፣ A2Aን፣ ማህደረ ትውስታን፣ የጥበቃ ደንቦችን፣ ግምገማዎችን እና በ5,100+ ቁጥጥር ስር ባሉ የሙከራ ፋይሎች ውስጥ 39,000+ ቋሚ የሙከራ መግለጫዎችን የሚያካትቱ የምርት አካባቢ መቆጣጠሪያዎች።"/>
<img src="./docs/diagrams/promise-pillars.svg" width="100%" alt="ቃል የተገባው — አንድ endpoint እና 359 አቅራቢዎች። ሌላ ጤናማ ዒላማ እስካለ ድረስ ራስ-ሰር fallback ማዘዋወሩን ይቀጥላል። ስድስት ምሰሶዎች፦ በ359 አቅራቢዎች ውስጥ ጠንካራ fallback · ብቁ በሆኑ የሥራ ጫናዎች ላይ እስከ 95% የtoken ቁጠባ · 150+ ነፃ tiers እና 54 ተደጋጋሚ/ቁልፍ የማይፈልጉ ለዘላለም ነፃ አቅራቢዎችን በመጠቀም በ$0 መጀመር · በአንድ ውቅር 36 CLI/agent ውህደቶች · በ/v1 ላይ ከOpenAI, Claude, Gemini እና Responses API ጋር ተኳሃኝነት · circuit breakers፣ TLS stealth፣ MCP 110 መሣሪያዎች፣ A2A፣ memory፣ guardrails፣ evals እና በ5,100+ ክትትል የሚደረግባቸው የሙከራ ፋይሎች ውስጥ 39,000+ የማይለዋወጡ የሙከራ መግለጫዎችን ያካተቱ የproduction መቆጣጠሪያዎች።"/>
<br/>
<br/>
@@ -246,11 +250,11 @@ curl http://localhost:20128/v1/chat/completions \
</div>
<img src="./docs/diagrams/why-pain-fix.svg" width="100%" alt="OmniRoute ለምን — 10 ዳሽቦርዶችን፣ የማይሰሩ API ቁልፎችን እና ድንገተኛ ክፍያዎችን ማስተዳደር ያቁሙ። አሥር ዕለታዊ ችግኝቶች እና መፍትሔዎቻቸው፦ ኮታው ጥቅም ላይ ሳይውል ጊዜው ማለቅ → ከደንበኝነት ምዝገባዎች ከፍተኛውን ጥቅም ማግኘት፤ በኮድ ጽሑፍ መካከል የፍጥነት ገደብ ላይ መድረስ → ባለ4-ደረጃ ራስ-ሰር መጠባበቂያ ሽግግር (ደንበኝነት ምዝገባ → API → ርካሽ → ነፃ)፤ የመሣሪያ ውጤቶች ቶከኖችን ማባከን → RTK + Caveman መጭመቅ (15–95%)፤ ውድ APIs → በወጪ የተመቻቸ ማስተላለፍ፤ እያንዳንዱ መሣሪያ የራሱን ቅንብር መፈለግ → አንድ የመዳረሻ ነጥብ፣ አንድ ዳሽቦርድ፤ AI መታገድ → ባለ3-ደረጃ ፕሮክሲ + TLS ስውርነት፤ የማይሰሩ ቁልፎች → ባለ3-ንብርብር ጽናት (ሰርኪዩት ብሬከሮች፣ የቁልፍ ማቀዝቀዣ ጊዜ፣ የሞዴል መቆለፊያ)፤ አንድ የደንበኝነት ምዝገባ የሚጋራ ቡድን → ፍትሐዊ የኮታ ድርሻ ያላቸው የቁልፍ ስብስቦች፤ ፕሮምፕቶች በሌላ ሰው ደመና ውስጥ ማለፍ → በAES-256-GCM የተመሰጠሩ ቁልፎችን የያዘ አካባቢያዊ-ቅድሚያ አቀራረብ፤ የወጪ ታይነት አለመኖር → የቀጥታ ትንታኔዎች (አጠቃቀም፣ ኮታ፣ ቁጠባ፣ p95 መዘግየት)።"/>
<img src="./docs/diagrams/why-pain-fix.svg" width="100%" alt="OmniRoute ለምን — 10 dashboards፣ የማይሰሩ API ቁልፎች እና ድንገተኛ ክፍያዎችን ማስተዳደር ያቁሙ። አሥር ዕለታዊ ችግሮች እና መፍትሔዎቻቸው፦ ጥቅም ላይ ሳይውል የሚያበቃ quota → subscriptionsን በከፍተኛው ይጠቀሙ፤ በኮድ ሥራ መካከል የሚያጋጥሙ rate limits → ባለ4-tier auto-fallback (Subscription → API → Cheap → Free)፤ tokensን የሚያባክኑ የመሣሪያ ውጤቶች → RTK + Caveman compression (15–95%)፤ ውድ APIs → በወጪ የተመቻቸ routing፤ እያንዳንዱ መሣሪያ የራሱ ውቅር ይፈልጋል → አንድ endpoint፣ አንድ dashboard፤ AI ታግዷል → ባለ3-ደረጃ proxy + TLS stealth፤ የማይሰሩ ቁልፎች → ባለ3-ንብርብር ጽናት (circuit breakers፣ key cooldown፣ model lockout)፤ አንድ subscriptionን የሚጋራ ቡድን → ፍትሐዊ ድርሻ quotas ያላቸው key pools፤ በሌላ ሰው cloud በኩል የሚያልፉ prompts → AES-256-GCM በተመሰጠሩ ቁልፎች local-first፤ የወጪ ታይነት የለም → ቀጥታ analytics (አጠቃቀም፣ quota፣ ቁጠባ፣ p95 latency)።"/>
<div align="center">
<img src="./docs/diagrams/tier-cascade.svg" width="100%" alt="የOmniRoute ጥያቄ ፍሰት፦ IDE ወይም CLIዎ (Claude Code፣ Cursor፣ Cline…) አንድ አካባቢያዊ የመዳረሻ ነጥብን (http://localhost:20128/v1) ይጠራል፤ OmniRoute Smart Router (RTK + Caveman መጭመቅ፣ 19 የማስተላለፊያ ስልቶች፣ ሰርኪዩት ብሬከሮች፣ TLS ስውርነት፣ MCP፣ A2A፣ የጥበቃ ደንቦች) ብቁ እና ጤናማ ዒላማ እስካለ ድረስ በ4 የአቅራቢ ደረጃዎች መካከል ወደ መጠባበቂያ መሸጋገር ይችላል — ደረጃ 1 ደንበኝነት ምዝገባ፣ ደረጃ 2 API ቁልፍ፣ ደረጃ 3 ርካሽ እና ደረጃ 4 ነፃ።"/>
<img src="./docs/diagrams/tier-cascade.svg" width="100%" alt="የOmniRoute ጥያቄ ፍሰት፦ የእርስዎ IDE ወይም CLI (Claude Code, Cursor, Cline…) አንድ local endpointን (http://localhost:20128/v1) ይጠራል፤ OmniRoute Smart Router (RTK + Caveman compression፣ 19 routing strategies፣ circuit breakers፣ TLS stealth፣ MCP፣ A2A፣ guardrails) ብቁ እና ጤናማ ዒላማ እስካለ ድረስ በ4 የአቅራቢ tiers ውስጥ fallback ማድረግ ይችላል — Tier 1 Subscription፣ Tier 2 API Key፣ Tier 3 Cheap እና Tier 4 Free።"/>
</div>
@@ -544,18 +548,11 @@ OmniRoute በMIT ፈቃድ የተለቀቀ ሲሆን በግልጽነት ይጠ
## 📡 OmniRoute Radar
ዋናው የነፃ ደረጃ መጠን፣ ከላይ በሰነድ የተገለጸውን በጋራ ስብስብ ውስጥ ድግግሞሽ የተወገደለትን ካታሎግ በመጠቀም፣ **~1.47B ቶከኖች/በወር** ሆኖ ይቆያል። ጊዜያዊ የአቅራቢዎች የምዝገባ ክሬዲቶች በተናጠል የመጀመሪያውን
ወር ወደ **~2.10B** ሊያሳድጉት ይችላሉ። Radar፣ በOmniRoute ልቀቶች መካከል ይበልጥ ወቅታዊ የነፃ ሞዴሎች ተደራሽነትን ለሚፈልጉ ሰዎች የተዘጋጀ፣ አማራጭ እና ዲጂታል ፊርማ ያለው የካታሎግ ተደራቢ ነው፤ የማህበረሰቡ ካታሎግ እና ሁሉም ነባር ነፃ
ባህሪያት ነፃ ሆነው ይቀጥላሉ።
ከላይ በሰነድ ከተገለጸው፣ የጋራ ስብስብ ድግግሞሽ ከተወገደለት ካታሎግ የሚገኘው ዋናው የነፃ ደረጃ መጠን **~1.62B ቶከኖች/በወር** ሆኖ ይቆያል። ጊዜያዊ የአቅራቢዎች ምዝገባ ክሬዲቶች የመጀመሪያውን ወር መጠን በተናጠል ወደ **~2.22B** ሊያሳድጉት ይችላሉ። Radar በOmniRoute ልቀቶች መካከል ይበልጥ ወቅታዊ የሆነ የነፃ ሞዴሎች ተደራሽነት ለሚፈልጉ ሰዎች፣ እንደ አማራጭ የሚቀርብ እና በዲጂታል ፊርማ የተረጋገጠ የካታሎግ ተደራቢ ነው፤ የማህበረሰቡ ካታሎግ እና ሁሉም ነባር ነፃ ባህሪያት ነፃ ሆነው ይቀጥላሉ።
ደጋፊዎች በቀጥታ የሚዘመነውን ካታሎግ እና ተጨማሪ የአቅራቢዎች ዕድሎችን ማግኘት ይችላሉ። የተለየውና
ሊለወጥ የሚችለው ከፍተኛ ገደቡ፣ እንደ አቅራቢዎች ተደራሽነት፣ **ቢበዛ በግምት 3B ቶከኖች/በወር** ነው።
ይህ ከፍተኛ ገደብ ዋስትና አይደለም፦ አቅራቢዎች ኮታዎችን፣ ብቁነትን፣ ሞዴሎችን ወይም ክልሎችን በማንኛውም
ጊዜ ሊቀይሩ ይችላሉ።
ደጋፊዎች ቀጥታ የሚዘምነውን ካታሎግ እና ተጨማሪ የአቅራቢዎች ዕድሎችን ሊያገኙ ይችላሉ። የተለየውና ሊለወጥ የሚችለው ከፍተኛ ገደቡ፣ እንደ አቅራቢዎች ተደራሽነት፣ **ቢበዛ በግምት 3B ቶከኖች/በወር** ነው። ይህ ከፍተኛ ገደብ ዋስትና አይደለም፦ አቅራቢዎች ኮታዎችን፣ ብቁነትን፣ ሞዴሎችን ወይም ክልሎችን በማንኛውም ጊዜ ሊለውጡ ይችላሉ።
Radar በምርጫ የሚነቃ እና GET ብቻ የሚጠቀም ነው። የOmniRoute ደንበኛ ፕሮምፕቶችን፣ ትራፊክን፣ የአቅራቢ
ውቅርን፣ የአጠቃቀም ቴሌሜትሪን ወይም የማስታወቂያ ስንብት የአካባቢ ሁኔታን አይሰቅልም። ስለ ብቁነት እና
ስለ ወቅታዊው ካታሎግ በ **[radar.omniroute.online/planos](https://radar.omniroute.online/planos)** ይወቁ።
Radar በምርጫ የሚነቃ ሲሆን GET ጥያቄዎችን ብቻ ይጠቀማል። የOmniRoute ደንበኛ ፕሮግራም ፕሮምፕቶችን፣ ትራፊክን፣ የአቅራቢ ውቅርን፣ የአጠቃቀም ቴሌሜትሪን ወይም በአካባቢው የተቀመጠውን የማስታወቂያ ውድቅ ማድረጊያ ሁኔታ አይሰቅልም። ስለ ብቁነት እና ስለ ወቅታዊው ካታሎግ በ**[radar.omniroute.online/planos](https://radar.omniroute.online/planos)** ይወቁ።
<br/>
@@ -668,15 +665,15 @@ omniroute configure codex # እነዚህንም ይደግፋል፦ claud
<div align="center">
## 🌐 352 AI አቅራቢዎች — 152 በካታሎግ ነፃ ተብለው የተመለከቱ
## 🌐 357 የAI አቅራቢዎች — 152 በካታሎግ ነፃ ተብለው የተመለከቱ
</div>
> በመደበኛዎቹ የውይይት፣ ሚዲያ፣ ፍለጋ፣ አካባቢያዊ፣ የደመና ወኪል እና የስርዓት ስብስቦች ውስጥ **352 የተመዘገቡ አቅራቢዎች** አሉ፤ ከእነዚህም **152ቱ `hasFree: true` የማግኛ ሜታዳታ ይዘዋል**። የውይይት ሞዴል መዝገቡ **229 አቅራቢዎችን / 2,554 የተለያዩ የአቅራቢ-ሞዴል ጥንዶችን / 1,283 ጥሬ የሞዴል መለያዎችን** ይሸፍናል፤ የተለየው የነፃ በጀት ካታሎግ ደግሞ **443 በእያንዳንዱ ሞዴል የተደራጁ ረድፎች**፣ **34 ተደጋጋሚ ማከማቻዎች** እና **53 ተደጋጋሚ/ቁልፍ የማያስፈልጋቸው ለዘላለም ነፃ አቅራቢዎች** አሉት። እነዚህ በዓላማ የተለያዩ መነሻ ድምሮች ናቸው፤ ትርጓሜዎቹ እና የተደጋጋሚ ማከማቻዎችን ያስወገዱ ስሌቶች በ[የአቅራቢ ማጣቀሻ](docs/reference/PROVIDER_REFERENCE.md) እና [ነፃ ደረጃዎች](docs/reference/FREE_TIERS.md) ውስጥ ይገኛሉ።
> በመደበኛዎቹ የውይይት፣ ሚዲያ፣ ፍለጋ፣ አካባቢያዊ፣ የደመና-ወኪል እና የስርዓት ስብስቦች ውስጥ **357 የተመዘገቡ አቅራቢዎች** ሲኖሩ፣ ከእነዚህም **152ቱ `hasFree: true` የግኝት ሜታዳታ ይዘዋል**። የውይይት ሞዴል መዝገቡ **229 አቅራቢዎችን / 2,554 የተለያዩ የአቅራቢ-ሞዴል ጥንዶችን / 1,283 ጥሬ የሞዴል IDsን** ያካትታል፤ የተለየው የነፃ በጀት ካታሎግ ደግሞ **491 የእያንዳንዱ ሞዴል ረድፎች**፣ **35 ተደጋጋሚ ስብስቦች** እና **54 ተደጋጋሚ/ቁልፍ-አልባ ለዘላለም ነፃ አቅራቢዎች** አሉት። እነዚህ በንድፍ የተለያዩ መለኪያዎች ናቸው፤ ትርጓሜዎችና ተመሳሳይ ስብስቦችን ያስወገዱ ስሌቶች በ[የአቅራቢዎች ማጣቀሻ](docs/reference/PROVIDER_REFERENCE.md) እና [ነፃ ደረጃዎች](docs/reference/FREE_TIERS.md) ውስጥ ይገኛሉ።
<div align="center">
### 🏢 ሁሉም ዋና ላቦራቶሪዎች — በአንድ መገናኛ ነጥብ
### 🏢 ሁሉም ዋና ላቦራቶሪዎች — በአንድ የመገናኛ ነጥብ
<table>
<tr>
@@ -705,7 +702,7 @@ omniroute configure codex # እነዚህንም ይደግፋል፦ claud
</tr>
</table>
<sub>…እና 330+ ተጨማሪ — እያንዳንዱ አዶ ከዳሽቦርዱ የአቅራቢዎች ካታሎግ በቀጥታ ይጫናል። 📖 [የአቅራቢ ማጣቀሻ](docs/reference/PROVIDER_REFERENCE.md)</sub>
<sub>…እና ሌሎች 330+ — እያንዳንዱ አዶ ከዳሽቦርዱ የአቅራቢዎች ካታሎግ በቀጥታ ይጫናል። 📖 [የአቅራቢዎች ማጣቀሻ](docs/reference/PROVIDER_REFERENCE.md)</sub>
<br/>
@@ -721,16 +718,16 @@ omniroute configure codex # እነዚህንም ይደግፋል፦ claud
<td align="center" width="150"><img src="./public/providers/baidu.svg" width="42" alt="Baidu ERNIE"/><br/><b>Baidu ERNIE</b><br/><sub>ERNIE 4.0<br/>ለዘላለም ነፃ</sub></td>
</tr>
<tr>
<td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/qoder-color.svg" width="42" alt="Qoder AI"/><br/><b>Qoder AI</b><br/><sub>Qwen3-Max, Kimi-K2<br/>ገደብ የሌለው ነፃ አገልግሎት</sub></td>
<td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/qoder-color.svg" width="42" alt="Qoder AI"/><br/><b>Qoder AI</b><br/><sub>Qwen3-Max, Kimi-K2<br/>ያልተገደበ ነፃ አገልግሎት</sub></td>
<td align="center" width="150"><img src="./public/providers/pollinations.svg" width="42" alt="Pollinations"/><br/><b>Pollinations</b><br/><sub>GPT, Llama, Claude<br/>ቁልፍ አያስፈልግም</sub></td>
<td align="center" width="150"><img src="./public/providers/cloudflare.svg" width="42" alt="Cloudflare AI"/><br/><b>Cloudflare AI</b><br/><sub>50+ ሞዴሎች<br/>10K ነርቮች/ቀን</sub></td>
<td align="center" width="150"><img src="./public/providers/cloudflare.svg" width="42" alt="Cloudflare AI"/><br/><b>Cloudflare AI</b><br/><sub>50+ ሞዴሎች<br/>10K ኒውሮኖች/ቀን</sub></td>
<td align="center" width="150"><img src="./public/providers/nvidia.svg" width="42" alt="NVIDIA NIM"/><br/><b>NVIDIA NIM</b><br/><sub>GLM, MiniMax<br/>~40 RPM በነፃ</sub></td>
<td align="center" width="150"><img src="./public/providers/cerebras.svg" width="42" alt="Cerebras"/><br/><b>Cerebras</b><br/><sub>GLM 4.7, GPT-OSS<br/>1M ቶከኖች/ቀን</sub></td>
<td align="center" width="150"><img src="./public/providers/openrouter.svg" width="42" alt="OpenRouter"/><br/><b>OpenRouter</b><br/><sub>:free ሞዴሎች<br/>+$10 → ከፍተኛ RPM</sub></td>
</tr>
</table>
📖 ሙሉ በማሽን የሚነበብ ካታሎግ → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
📖 ሙሉ በማሽን ሊነበብ የሚችል ካታሎግ → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
<br/>
</div>
@@ -1295,44 +1292,44 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
<table>
<tr><th align="left">ሰነድ</th><th align="left">መግለጫ</th></tr>
<tr><td nowrap><b><a href="docs/guides/USER_GUIDE.md">የተጠቃሚ መመሪያ</a></b></td><td>አቅራቢዎች፣ ጥምረቶች፣ የCLI ውህደት፣ ስምሪት</td></tr>
<tr><td nowrap><b><a href="docs/guides/SETUP_GUIDE.md">የማዋቀሪያ መመሪያ</a></b></td><td>ሙሉ የመጫኛ ዘዴዎች፣ የCLI መሣሪያ ውቅሮች፣ የፕሮቶኮል ማዋቀር፣ የጊዜ ገደብ ማስተካከያ</td></tr>
<tr><td nowrap><b><a href="docs/reference/CLI-TOOLS.md">የCLI መሣሪያዎች መመሪያ</a></b></td><td>ለClaude Code፣ Codex፣ Cursor፣ Cline፣ OpenClaw፣ Kilo፣ Copilot የየመሣሪያው ማዋቀሪያ</td></tr>
<tr><td nowrap><b><a href="docs/guides/REMOTE-MODE.md">የርቀት ሁነታ</a></b></td><td>የተወሰነ ወሰን ባላቸው የመዳረሻ ቶከኖች በላፕቶፕዎ CLI በኩል የርቀት OmniRoute (VPS) ያስተዳድሩ</td></tr>
<tr><td nowrap><b><a href="docs/guides/CLAUDE-CODE-CONFIGURATION.md">የClaude Code ውቅር</a></b></td><td>Claude Codeን ወደ OmniRoute (አካባቢያዊ/የርቀት) በ<code>launch</code> + በየሞዴሉ መገለጫዎች ያመልክቱ</td></tr>
<tr><td nowrap><b><a href="README.md#-quick-start">ፈጣን ጅምር</a></b></td><td>ባለ3-ደረጃ ጭነት → ግንኙነት → ውቅር</td></tr>
<tr><td nowrap><b><a href="docs/guides/USER_GUIDE.md">የተጠቃሚ መመሪያ</a></b></td><td>አቅራቢዎች፣ ጥምረቶች፣ የCLI ውህደት፣ ማሰማራት</td></tr>
<tr><td nowrap><b><a href="docs/guides/SETUP_GUIDE.md">የማዋቀር መመሪያ</a></b></td><td>ሙሉ የመጫኛ ዘዴዎች፣ የCLI መሣሪያ ውቅሮች፣ የፕሮቶኮል ማዋቀር፣ የጊዜ ገደብ ማስተካከያ</td></tr>
<tr><td nowrap><b><a href="docs/reference/CLI-TOOLS.md">የCLI መሣሪያዎች መመሪያ</a></b></td><td>ለClaude Code፣ Codex፣ Cursor፣ Cline፣ OpenClaw፣ Kilo፣ Copilot የየመሣሪያው ማዋቀር</td></tr>
<tr><td nowrap><b><a href="docs/guides/REMOTE-MODE.md">የርቀት ሁነታ</a></b></td><td>የተገደበ ወሰን ባላቸው የመዳረሻ ቶከኖች አማካኝነት ከላፕቶፕዎ CLI የርቀት OmniRoute (VPS)ን ያስተዳድሩ</td></tr>
<tr><td nowrap><b><a href="docs/guides/CLAUDE-CODE-CONFIGURATION.md">የClaude Code ውቅር</a></b></td><td>በ<code>launch</code> + ለእያንዳንዱ ሞዴል መገለጫዎች Claude Codeን ወደ OmniRoute (አካባቢያዊ/የርቀት) ያመልክቱ</td></tr>
<tr><td nowrap><b><a href="README.md#-quick-start">ፈጣን ጅምር</a></b></td><td>ባለ3-ደረጃ መጫን → ማገናኘት → ማዋቀር</td></tr>
</table>
### 🔧 ክወናዎች እና ስምሪት
### 🔧 ክዋኔዎች እና ማሰማራት
<table>
<tr><th align="left">ሰነድ</th><th align="left">መግለጫ</th></tr>
<tr><td nowrap><b><a href="docs/guides/DOCKER_GUIDE.md">የDocker መመሪያ</a></b></td><td>Docker run፣ Compose መገለጫዎች፣ Caddy HTTPS፣ መተላለፊያዎች፣ የimage መለያዎች</td></tr>
<tr><td nowrap><b><a href="docs/guides/DOCKER_GUIDE.md">የDocker መመሪያ</a></b></td><td>Docker run፣ Compose መገለጫዎች፣ Caddy HTTPS፣ ቱነሎች፣ የምስል መለያዎች</td></tr>
<tr><td nowrap><b><a href="contrib/podman/README.md">የPodman መመሪያ</a></b></td><td>የQuadlet systemd ውህደት፣ podman-compose፣ SELinux</td></tr>
<tr><td nowrap><b><a href="docs/ops/VM_DEPLOYMENT_GUIDE.md">የVM ስምሪት</a></b></td><td>የተሟላ መመሪያ፦ VM + nginx + Cloudflare ማዋቀሪያ</td></tr>
<tr><td nowrap><b><a href="docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md">የFly.io ስምሪት</a></b></td><td>በቋሚ ማከማቻ ወደ Fly.io ያሰማሩ</td></tr>
<tr><td nowrap><b><a href="docs/guides/TERMUX_GUIDE.md">የTermux መመሪያ</a></b></td><td>OmniRouteን በTermux በኩል በAndroid ላይ ያስኪዱ</td></tr>
<tr><td nowrap><b><a href="docs/guides/PWA_GUIDE.md">የPWA መመሪያ</a></b></td><td>የProgressive Web App ጭነት፣ መሸጎጫ፣ አርክቴክቸር</td></tr>
<tr><td nowrap><b><a href="docs/guides/UNINSTALL.md">የማራገፊያ መመሪያ</a></b></td><td>ለሁሉም የመጫኛ ዘዴዎች ንጹሕ ማስወገጃ</td></tr>
<tr><td nowrap><b><a href="docs/ops/VM_DEPLOYMENT_GUIDE.md">የVM ማሰማራት</a></b></td><td>ሙሉ መመሪያ፦ VM + nginx + Cloudflare ማዋቀር</td></tr>
<tr><td nowrap><b><a href="docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md">የFly.io ማሰማራት</a></b></td><td>በቋሚ ማከማቻ Fly.io ላይ ያሰማሩ</td></tr>
<tr><td nowrap><b><a href="docs/guides/TERMUX_GUIDE.md">የTermux መመሪያ</a></b></td><td>OmniRouteን በTermux በኩል Android ላይ ያስኪዱ</td></tr>
<tr><td nowrap><b><a href="docs/guides/PWA_GUIDE.md">የPWA መመሪያ</a></b></td><td>የProgressive Web App መጫን፣ መሸጎጥ፣ ሥነ ሕንፃ</td></tr>
<tr><td nowrap><b><a href="docs/guides/UNINSTALL.md">የማራገፍ መመሪያ</a></b></td><td>ለሁሉም የመጫኛ ዘዴዎች ንጹሕ ማስወገድ</td></tr>
<tr><td nowrap><b><a href="docs/reference/ENVIRONMENT.md">የአካባቢ ውቅር</a></b></td><td>ሙሉ የ<code>.env</code> ተለዋዋጮች እና ማጣቀሻዎች</td></tr>
</table>
### 🧠 ባህሪያት እና አርክቴክቸር
### 🧠 ባህሪያት እና ሥነ ሕንፃ
<table>
<tr><th align="left">ሰነድ</th><th align="left">መግለጫ</th></tr>
<tr><td nowrap><b><a href="docs/architecture/ARCHITECTURE.md">አርክቴክቸር</a></b></td><td>የሥርዓት አርክቴክቸር፣ የውሂብ ፍሰት እና ውስጣዊ አሠራር</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_GUIDE.md">የመጭመቂያ መመሪያ</a></b></td><td>ባለ7-አማራጭ የሂደት መስመር፦ ጠፍቷል / ቀላል / መደበኛ / ኃይለኛ / እጅግ ከፍተኛ / RTK / የተደራረበ</td></tr>
<tr><td nowrap><b><a href="docs/compression/RTK_COMPRESSION.md">የRTK መጭመቂያ</a></b></td><td>የትዕዛዝ-ውፅዓት መጭመቂያ፣ ማጣሪያዎች፣ እምነት፣ ማረጋገጫ፣ የጥሬ-ውፅዓት መልሶ ማግኛ</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_ENGINES.md">የመጭመቂያ ሞተሮች</a></b></td><td>Caveman፣ RTK፣ የተደራረቡ የሂደት መስመሮች፣ የdashboard/API/MCP በይነገጾች</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_RULES_FORMAT.md">የመጭመቂያ ደንቦች ቅርጸት</a></b></td><td>ለCaveman እና RTK ማጣሪያዎች የJSON የደንብ-ጥቅል ንድፎች</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_LANGUAGE_PACKS.md">የመጭመቂያ ቋንቋ ጥቅሎች</a></b></td><td>ቋንቋን ለይቶ ማወቅ እና የCaveman የደንብ-ጥቅል ዝግጅት</td></tr>
<tr><td nowrap><b><a href="docs/architecture/RESILIENCE_GUIDE.md">የጽናት መመሪያ</a></b></td><td>የወረዳ ቆራጮች፣ የማቀዝቀዣ ጊዜዎች፣ ወረፋ፣ የተንጎዳጎደ መንጋ መከላከያ፣ የTLS ማስመሰል</td></tr>
<tr><td nowrap><b><a href="docs/routing/AUTO-COMBO.md">የራስ-ጥምረት ሞተር</a></b></td><td>ባለ16-ምክንያት ውጤት አሰጣጥ፣ የሁነታ ጥቅሎች፣ ራስን ማዳን</td></tr>
<tr><td nowrap><b><a href="docs/ops/PROXY_GUIDE.md">የProxy መመሪያ</a></b></td><td>ባለ3-ደረጃ የproxy ሥርዓት፣ የ1proxy የገበያ ቦታ፣ የመዝገብ CRUD</td></tr>
<tr><td nowrap><b><a href="docs/reference/FREE_TIERS.md">ነፃ ደረጃዎች</a></b></td><td>የተጠቃለለ ማውጫ፦ 34 በሰነድ የተቀመጡ ተደጋጋሚ ስብስቦች / 452 በካታሎግ የተመዘገቡ የነፃ-ደረጃ ግቤቶች</td></tr>
<tr><td nowrap><b><a href="docs/guides/FEATURES.md">የባህሪያት ማዕከለ-ስዕላት</a></b></td><td>ከቅጽበታዊ ገጽ ምስሎች ጋር የdashboard ምስላዊ ጉብኝት</td></tr>
<tr><td nowrap><b><a href="docs/architecture/CODEBASE_DOCUMENTATION.md">የኮድ መሠረት ሰነዶች</a></b></td><td>ለጀማሪዎች ምቹ የኮድ መሠረት ዝርዝር ጉብኝት</td></tr>
<tr><td nowrap><b><a href="docs/architecture/ARCHITECTURE.md">ሥነ ሕንፃ</a></b></td><td>የሥርዓት ሥነ ሕንፃ፣ የውሂብ ፍሰት እና ውስጣዊ አሠራሮች</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_GUIDE.md">የማመቅ መመሪያ</a></b></td><td>ባለ7-አማራጭ ቧንቧ፦ ጠፍቷል / ቀላል / መደበኛ / ኃይለኛ / እጅግ ከፍተኛ / RTK / የተደራረበ</td></tr>
<tr><td nowrap><b><a href="docs/compression/RTK_COMPRESSION.md">የRTK ማመቅ</a></b></td><td>የትዕዛዝ ውጤት ማመቅ፣ ማጣሪያዎች፣ መተማመን፣ ማረጋገጥ፣ ያልተሠራበትን ውጤት መልሶ ማግኘት</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_ENGINES.md">የማመቅ ሞተሮች</a></b></td><td>Caveman፣ RTK፣ የተደራረቡ ቧንቧዎች፣ የዳሽቦርድ/API/MCP በይነገጾች</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_RULES_FORMAT.md">የማመቅ ደንቦች ቅርጸት</a></b></td><td>ለCaveman እና RTK ማጣሪያዎች የJSON የደንብ-ጥቅል ንድፎች</td></tr>
<tr><td nowrap><b><a href="docs/compression/COMPRESSION_LANGUAGE_PACKS.md">የማመቅ ቋንቋ ጥቅሎች</a></b></td><td>ቋንቋን መለየት እና የCaveman የደንብ-ጥቅል ዝግጅት</td></tr>
<tr><td nowrap><b><a href="docs/architecture/RESILIENCE_GUIDE.md">የጽናት መመሪያ</a></b></td><td>የወረዳ ቆራጮች፣ የማቀዝቀዣ ጊዜያት፣ ወረፋ፣ ድንገተኛ የጋራ ጥያቄ መከላከያ፣ የTLS ማስመሰል</td></tr>
<tr><td nowrap><b><a href="docs/routing/AUTO-COMBO.md">የራስ-ሰር ጥምረት ሞተር</a></b></td><td>ባለ16-መስፈርት ነጥብ አሰጣጥ፣ የሁነታ ጥቅሎች፣ ራስን ማዳን</td></tr>
<tr><td nowrap><b><a href="docs/ops/PROXY_GUIDE.md">የProxy መመሪያ</a></b></td><td>ባለ3-ደረጃ የproxy ሥርዓት፣ የ1proxy ገበያ፣ የመዝገብ CRUD</td></tr>
<tr><td nowrap><b><a href="docs/reference/FREE_TIERS.md">ነፃ ደረጃዎች</a></b></td><td>የተጠናከረ ማውጫ፦ 35 በሰነድ የተመዘገቡ ተደጋጋሚ ስብስቦች / 491 በካታሎግ የተመዘገቡ የነፃ-ደረጃ ግቤቶች</td></tr>
<tr><td nowrap><b><a href="docs/guides/FEATURES.md">የባህሪያት ማዕከለ ስዕላት</a></b></td><td>ከቅጽበተ ማያ ገጾች ጋር የሚቀርብ ምስላዊ የዳሽቦርድ ጉብኝት</td></tr>
<tr><td nowrap><b><a href="docs/architecture/CODEBASE_DOCUMENTATION.md">የኮድ ማከማቻ ሰነድ</a></b></td><td>ለጀማሪዎች ምቹ የኮድ ማከማቻ ዝርዝር መመሪያ</td></tr>
</table>
### 🤖 ፕሮቶኮሎች እና APIዎች
@@ -1341,23 +1338,23 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
<tr><th align="left">ሰነድ</th><th align="left">መግለጫ</th></tr>
<tr><td nowrap><b><a href="docs/reference/API_REFERENCE.md">የAPI ማጣቀሻ</a></b></td><td>ሁሉም የመጨረሻ ነጥቦች ከምሳሌዎች ጋር</td></tr>
<tr><td nowrap><b><a href="docs/openapi.yaml">የOpenAPI ዝርዝር መግለጫ</a></b></td><td>የOpenAPI 3.0 ዝርዝር መግለጫ</td></tr>
<tr><td nowrap><b><a href="open-sse/mcp-server/README.md">የMCP አገልጋይ</a></b></td><td>110 የMCP መሣሪያዎች፣ የIDE ውቅሮች፣ የPython/TS/Go ደንበኞች</td></tr>
<tr><td nowrap><b><a href="docs/frameworks/MCP-SERVER.md">የMCP አገልጋይ መመሪያ</a></b></td><td>የMCP ጭነት፣ ማጓጓዣዎች እና የመሣሪያ ማጣቀሻ</td></tr>
<tr><td nowrap><b><a href="src/lib/a2a/README.md">የA2A አገልጋይ</a></b></td><td>የJSON-RPC 2.0 ፕሮቶኮል፣ ክህሎቶች፣ ተከታታይ ስርጭት፣ የተግባር አስተዳደር</td></tr>
<tr><td nowrap><b><a href="docs/frameworks/A2A-SERVER.md">የA2A አገልጋይ መመሪያ</a></b></td><td>የA2A ወኪል ካርድ፣ ተግባራት፣ ክህሎቶች እና ተከታታይ ስርጭት</td></tr>
<tr><td nowrap><b><a href="open-sse/mcp-server/README.md">MCP አገልጋይ</a></b></td><td>110 የMCP መሣሪያዎች፣ የIDE ውቅሮች፣ Python/TS/Go ደንበኞች</td></tr>
<tr><td nowrap><b><a href="docs/frameworks/MCP-SERVER.md">የMCP አገልጋይ መመሪያ</a></b></td><td>የMCP መጫን፣ ማጓጓዣዎች እና የመሣሪያ ማጣቀሻ</td></tr>
<tr><td nowrap><b><a href="src/lib/a2a/README.md">A2A አገልጋይ</a></b></td><td>የJSON-RPC 2.0 ፕሮቶኮል፣ ክህሎቶች፣ ዥረት ማስተላለፍ፣ የተግባር አስተዳደር</td></tr>
<tr><td nowrap><b><a href="docs/frameworks/A2A-SERVER.md">የA2A አገልጋይ መመሪያ</a></b></td><td>የA2A ወኪል ካርድ፣ ተግባራት፣ ክህሎቶች እና ዥረት ማስተላለፍ</td></tr>
</table>
### 📋 ፕሮጀክት እና ጥራት
<table>
<tr><th align="left">ሰነድ</th><th align="left">መግለጫ</th></tr>
<tr><td nowrap><b><a href="CONTRIBUTING.md">አስተዋጽኦ ማድረግ</a></b></td><td>የልማት ዝግጅት እና መመሪያዎች</td></tr>
<tr><td nowrap><b><a href="docs/ops/BRANCHING_MODEL.md">የቅርንጫፍ እና ልቀት ሞዴል</a></b></td><td>PRs የሚያነጣጥሩበት (<code>release/*</code>)፣ <code>main</code> እና መለያዎች ምን እንደሚያመለክቱ</td></tr>
<tr><td nowrap><b><a href="CHANGELOG.md">የለውጥ መዝገብ</a></b></td><td>ሙሉ የየስሪቱ የልቀት ታሪክ</td></tr>
<tr><td nowrap><b><a href="SECURITY.md">የደህንነት ፖሊሲ</a></b></td><td>የተጋላጭነት ሪፖርት ማድረግ እና የደህንነት ልምዶች</td></tr>
<tr><td nowrap><b><a href="docs/guides/I18N.md">የi18n መመሪያ</a></b></td><td>የ42 ቋንቋዎች ድጋፍ፣ የትርጉም የሥራ ሂደት፣ RTL</td></tr>
<tr><td nowrap><b><a href="docs/ops/RELEASE_CHECKLIST.md">የልቀት ማረጋገጫ ዝርዝር</a></b></td><td>ከልቀት በፊት የማረጋገጫ ደረጃዎች</td></tr>
<tr><td nowrap><b><a href="docs/ops/COVERAGE_PLAN.md">የሽፋን ዕቅድ</a></b></td><td>በ5,100+ ክትትል በሚደረግባቸው የሙከራ ፋይሎች ውስጥ ለ39,000+ የማይለወጡ የሙከራ መግለጫዎች የሙከራ ሽፋን ስትራቴጂ</td></tr>
<tr><td nowrap><b><a href="CONTRIBUTING.md">አስተዋጽኦ ማድረግ</a></b></td><td>የልማት ማዋቀሪያ እና መመሪያዎች</td></tr>
<tr><td nowrap><b><a href="docs/ops/BRANCHING_MODEL.md">የቅርንጫፍ እና የልቀት ሞዴል</a></b></td><td>PR-ዎች የሚያነጣጥሩበት (<code>release/*</code>)፣ <code>main</code> እና መለያዎች ምን እንደሚያመለክቱ</td></tr>
<tr><td nowrap><b><a href="CHANGELOG.md">የለውጦች መዝገብ</a></b></td><td>ሙሉ የየስሪቱ የልቀት ታሪክ</td></tr>
<tr><td nowrap><b><a href="SECURITY.md">የደህንነት ፖሊሲ</a></b></td><td>የተጋላጭነት ሪፖርት አደራረግ እና የደህንነት ልምዶች</td></tr>
<tr><td nowrap><b><a href="docs/guides/I18N.md">የi18n መመሪያ</a></b></td><td>የ42 ቋንቋዎች ድጋፍ፣ የትርጉም የሥራ ፍሰት፣ RTL</td></tr>
<tr><td nowrap><b><a href="docs/ops/RELEASE_CHECKLIST.md">የልቀት ማረጋገጫ ዝርዝር</a></b></td><td>ከልቀት በፊት የሚከናወኑ የማረጋገጫ ደረጃዎች</td></tr>
<tr><td nowrap><b><a href="docs/ops/COVERAGE_PLAN.md">የሽፋን ዕቅድ</a></b></td><td>በ5,100+ ክትትል በሚደረግባቸው የሙከራ ፋይሎች ውስጥ ላሉ 39,000+ የማይለወጡ የሙከራ መግለጫዎች የሙከራ ሽፋን ስትራቴጂ</td></tr>
</table>
<br/>
@@ -1366,12 +1363,12 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
# ⭐ ከፍተኛ አስተዋጽኦ አድራጊዎች
> OmniRoute በቁርጠኛ ክፍት-ምንጭ ማህበረሰብ የተቀረጸ ነው። እነዚህ ግለሰቦች በፕሮጀክቱ ጥራት፣ መረጋጋት እና ተደራሽነት ላይ ቀጥተኛ ተጽዕኖ ያላቸው ልዩ አስተዋጽኦዎችን አድርገዋል። **እናመሰግናለን።**
> OmniRoute በትጋት በሚሳተፍ ክፍት ምንጭ ማህበረሰብ የተቀረጸ ነው። እነዚህ ግለሰቦች በፕሮጀክቱ ጥራት፣ መረጋጋት እና ተደራሽነት ላይ ቀጥተኛ ተጽዕኖ ያላቸውን ልዩ አስተዋጽኦዎች አድርገዋል። **እናመሰግናለን።**
### በተዋሃዱ pull requests ብዛት የተደረደሩ ውጫዊ አስተዋጽኦ አድራጊዎች
### በተዋሃዱ pull request-ዎች ብዛት የተደረደሩ ውጫዊ አስተዋጽኦ አድራጊዎች
<table>
<tr><th align="center">ደረጃ</th><th align="left">አስተዋጽኦ አድራጊ</th><th align="center">የተዋሃዱ PRs</th><th align="right">~የተቀየሩ መስመሮች</th></tr>
<tr><th align="center">ደረጃ</th><th align="left">አስተዋጽኦ አድራጊ</th><th align="center">የተዋሃዱ PR-ዎች</th><th align="right">~የተለወጡ መስመሮች</th></tr>
<tr><td align="center">1</td><td align="left"><a href="https://github.com/backryun"><b>backryun</b></a></td><td align="center">190</td><td align="right">227,977</td></tr>
<tr><td align="center">2</td><td align="left"><a href="https://github.com/oyi77"><b>oyi77</b></a></td><td align="center">180</td><td align="right">407,678</td></tr>
<tr><td align="center">3</td><td align="left"><a href="https://github.com/rdself"><b>rdself</b></a></td><td align="center">145</td><td align="right">80,663</td></tr>
@@ -1395,7 +1392,7 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
<tr><td align="center">20</td><td align="left"><a href="https://github.com/Prudhvivuda"><b>Prudhvivuda</b></a></td><td align="center">24</td><td align="right">6,312</td></tr>
</table>
<sub>በቀጥታ ስርጭት ላይ ባለው <code>release/v3.8.50</code> ጫፍ <code>dafb4ae808</code> ላይ፣ እስከ 2026-08-24 05:26:03 UTC ድረስ ባሉ ውህደቶች ታስሯል። በገጽ የተከፋፈለው የGitHub GraphQL ቆጠራ 5,911 የተዋሃዱ PRs ይዟል፦ 2,707 በማከማቻው ባለቤት፣ 179 በDependabot እና <b>3,025 ውጫዊ PRs ከ535 የተለያዩ አስተዋጽኦ አድራጊዎች</b>። “የተቀየሩ መስመሮች” ማለት የGitHub ጭማሪዎች + ስረዛዎች ሲሆን፣ የተፈጠሩ ፋይሎችን፣ lockfiles፣ ካታሎጎችን፣ ትርጉሞችን እና ሰነዶችን ያካትታል፤ ይህ የለውጥ መጠን እንጂ በጸሐፊ የተጻፉ LOC አይደሉም። በመቁረጫው ነጥብ ላይ ያሉ እኩል ውጤቶች ተጠብቀዋል።</sub>
<sub>በቀጥታ ባለው <code>release/v3.8.50</code> የመጨረሻ ነጥብ <code>dafb4ae808</code> ላይ፣ እስከ 2026-08-24 05:26:03 UTC ባሉ ውህደቶች ተወስኗል። በገጾች የተከፋፈለው የGitHub GraphQL ቆጠራ 5,911 የተዋሃዱ PR-ዎችን ይዟል፤ 2,707 በማከማቻው ባለቤት፣ 179 በDependabot፣ እና <b>3,025 ውጫዊ PR-ዎች ከ535 የተለያዩ አስተዋጽኦ አድራጊዎች</b>። “የተለወጡ መስመሮች” የGitHub ጭማሪዎችን + ስረዛዎችን ያመለክታል፣ እንዲሁም የመነጩ ፋይሎችን፣ lockfile-ዎችን፣ ካታሎጎችን፣ ትርጉሞችን እና ሰነዶችን ያካትታል፤ ይህ የለውጥ መጠን እንጂ በደራሲ የተጻፉ LOC አይደሉም። በመቁረጫ ነጥቡ ላይ ያሉ እኩል ውጤቶች ተጠብቀዋል።</sub>
### በGitHub የተመደቡ commits
@@ -1441,7 +1438,7 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
<img src="https://github.com/hartmark.png" width="40" style="border-radius:50%" alt="Markus Hartung"/><br/>
<b>Markus Hartung</b>
</a><br/>
<sub>🏅 69 በGitHub የተመዘገቡ commits · በጋራ #6</sub>
<sub>🏅 69 በGitHub የተመዘገቡ commits · በ#6 እኩል</sub>
</td>
</tr>
<tr>
@@ -1450,7 +1447,7 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
<img src="https://github.com/maxmad64bis.png" width="40" style="border-radius:50%" alt="Dizzle"/><br/>
<b>Dizzle</b>
</a><br/>
<sub>🏅 69 በGitHub የተመዘገቡ commits · በጋራ #6</sub>
<sub>🏅 69 በGitHub የተመዘገቡ commits · በ#6 እኩል</sub>
</td>
<td align="center" width="160">
<a href="https://github.com/JxnLexn">
@@ -1471,21 +1468,21 @@ OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1ም ይዘለዋ
<img src="https://github.com/HouMinXi.png" width="40" style="border-radius:50%" alt="Bob.Hou"/><br/>
<b>Bob.Hou</b>
</a><br/>
<sub>🏅 51 በGitHub የተመዘገቡ commits · በጋራ #10</sub>
<sub>🏅 51 በGitHub የተመዘገቡ commits · በ#10 እኩል</sub>
</td>
<td align="center" width="160">
<a href="https://github.com/xz-dev">
<img src="https://github.com/xz-dev.png" width="40" style="border-radius:50%" alt="Xiangzhe"/><br/>
<b>Xiangzhe</b>
</a><br/>
<sub>🏅 51 በGitHub የተመዘገቡ commits · በጋራ #10</sub>
<sub>🏅 51 በGitHub የተመዘገቡ commits · በ#10 እኩል</sub>
</td>
</tr>
</table>
<sub>በ2026-08-24 06:14:31 UTC እንደገና ተፈትሿል፦ ለ<code>release/v3.8.50</code> ነባሪ branch በrepository Contributors API የተዘገቡ በGitHub የተመዘገቡ commits። APIው 525 ማንነቶችን (415 ተጠቃሚዎች፣ 2 bots፣ 108 ስም-አልባ) መልሷል፤ ይህ ሰንጠረዥ ጠባቂውን፣ botsን እና ስም-አልባ ማንነቶችን አያካትትም፣ እኩል የውድድር ደረጃዎችንም ያቆያል። ይህ ከላይ ካለው የተዋሃዱ PRዎች ደረጃ እና ከታች ካለው የ639 ሰዎች Git-metadata ቆጠራ ሁለቱም የተለየ ነው።</sub>
<sub>በ2026-08-24 06:14:31 UTC እንደገና ተረጋግጧል፦ ለ<code>release/v3.8.50</code> ነባሪ branch በማከማቻው Contributors API የተዘገቡ በGitHub የተመዘገቡ commits። APIው 525 ማንነቶችን (415 ተጠቃሚዎች፣ 2 bots፣ 108 ስም-አልባ) መልሷል፤ ይህ ሰንጠረዥ ጠባቂውን፣ botsን እና ስም-አልባ ማንነቶችን አያካትትም፣ የውድድር እኩልነቶችንም እንዳሉ ያቆያል። ይህም ከላይ ካለው የተዋሃዱ PRዎች ደረጃ አሰጣጥ እና ከታች ካለው የ639 ሰዎች Git-metadata ቆጠራ ሁለቱም የተለየ ነው።</sub>
> 🙏 የእነዚህ አስተዋፅዖ አበርካቾች ባህሪያት፣ የስህተት ማስተካከያዎች እና የመሠረተ ልማት ማሻሻያዎች OmniRouteን አስተማማኝ እና በባህሪያት የበለፀገ ከሚያደርጉት ነገሮች **ዋና ክፍል** ናቸው። እያንዳንዱ pull request፣ እያንዳንዱ test case እና እያንዳንዱ የi18n ትርጉም ፋይል ወሳኝ ነው። Open source የሚገነባው እንደእነርሱ ባሉ ሰዎች ነው።
> 🙏 የእነዚህ አስተዋጽዖ አድራጊዎች ባህሪያት፣ የሳንካ ማስተካከያዎች እና የመሠረተ ልማት ማሻሻያዎች OmniRouteን አስተማማኝና በባህሪያት የበለፀገ ከሚያደርጉት ነገሮች **ዋና ክፍል** ናቸው። እያንዳንዱ pull request፣ እያንዳንዱ የሙከራ ጉዳይ እና እያንዳንዱ የi18n ትርጉም ፋይል አስፈላጊ ነው። ክፍት ምንጭ እንደ እነርሱ ባሉ ሰዎች ይገነባል።
</div>

33
docs/i18n/am/docs/DEVELOPER-ENVIRONMENT.md Normal file
View File

@@ -0,0 +1,33 @@
# Developer environment notes (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../DEVELOPER-ENVIRONMENT.md) · 🇸🇦 [ar](../../ar/docs/DEVELOPER-ENVIRONMENT.md) · 🇦🇿 [az](../../az/docs/DEVELOPER-ENVIRONMENT.md) · 🇧🇬 [bg](../../bg/docs/DEVELOPER-ENVIRONMENT.md) · 🇧🇩 [bn](../../bn/docs/DEVELOPER-ENVIRONMENT.md) · 🇨🇿 [cs](../../cs/docs/DEVELOPER-ENVIRONMENT.md) · 🇩🇰 [da](../../da/docs/DEVELOPER-ENVIRONMENT.md) · 🇩🇪 [de](../../de/docs/DEVELOPER-ENVIRONMENT.md) · 🇬🇷 [el](../../el/docs/DEVELOPER-ENVIRONMENT.md) · 🇪🇸 [es](../../es/docs/DEVELOPER-ENVIRONMENT.md) · 🇪🇪 [et](../../et/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇷 [fa](../../fa/docs/DEVELOPER-ENVIRONMENT.md) · 🇫🇮 [fi](../../fi/docs/DEVELOPER-ENVIRONMENT.md) · 🇫🇷 [fr](../../fr/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇪 [ga](../../ga/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [gu](../../gu/docs/DEVELOPER-ENVIRONMENT.md) · 🇳🇬 [ha](../../ha/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇱 [he](../../he/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [hi](../../hi/docs/DEVELOPER-ENVIRONMENT.md) · 🇭🇷 [hr](../../hr/docs/DEVELOPER-ENVIRONMENT.md) · 🇭🇺 [hu](../../hu/docs/DEVELOPER-ENVIRONMENT.md) · 🇦🇲 [hy](../../hy/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇩 [id](../../id/docs/DEVELOPER-ENVIRONMENT.md) · 🇳🇬 [ig](../../ig/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇹 [it](../../it/docs/DEVELOPER-ENVIRONMENT.md) · 🇯🇵 [ja](../../ja/docs/DEVELOPER-ENVIRONMENT.md) · 🇬🇪 [ka](../../ka/docs/DEVELOPER-ENVIRONMENT.md) · 🇰🇭 [km](../../km/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [kn](../../kn/docs/DEVELOPER-ENVIRONMENT.md) · 🇰🇷 [ko](../../ko/docs/DEVELOPER-ENVIRONMENT.md) · 🇱🇹 [lt](../../lt/docs/DEVELOPER-ENVIRONMENT.md) · 🇱🇻 [lv](../../lv/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [ml](../../ml/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [mr](../../mr/docs/DEVELOPER-ENVIRONMENT.md) · 🇲🇾 [ms](../../ms/docs/DEVELOPER-ENVIRONMENT.md) · 🇲🇹 [mt](../../mt/docs/DEVELOPER-ENVIRONMENT.md) · 🇲🇲 [my](../../my/docs/DEVELOPER-ENVIRONMENT.md) · 🇳🇵 [ne](../../ne/docs/DEVELOPER-ENVIRONMENT.md) · 🇳🇱 [nl](../../nl/docs/DEVELOPER-ENVIRONMENT.md) · 🇳🇴 [no](../../no/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [or](../../or/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [pa](../../pa/docs/DEVELOPER-ENVIRONMENT.md) · 🇵🇭 [phi](../../phi/docs/DEVELOPER-ENVIRONMENT.md) · 🇵🇱 [pl](../../pl/docs/DEVELOPER-ENVIRONMENT.md) · 🇵🇹 [pt](../../pt/docs/DEVELOPER-ENVIRONMENT.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/DEVELOPER-ENVIRONMENT.md) · 🇷🇴 [ro](../../ro/docs/DEVELOPER-ENVIRONMENT.md) · 🇷🇺 [ru](../../ru/docs/DEVELOPER-ENVIRONMENT.md) · 🇱🇰 [si](../../si/docs/DEVELOPER-ENVIRONMENT.md) · 🇸🇰 [sk](../../sk/docs/DEVELOPER-ENVIRONMENT.md) · 🇸🇮 [sl](../../sl/docs/DEVELOPER-ENVIRONMENT.md) · 🇷🇸 [sr](../../sr/docs/DEVELOPER-ENVIRONMENT.md) · 🇸🇪 [sv](../../sv/docs/DEVELOPER-ENVIRONMENT.md) · 🇰🇪 [sw](../../sw/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [ta](../../ta/docs/DEVELOPER-ENVIRONMENT.md) · 🇮🇳 [te](../../te/docs/DEVELOPER-ENVIRONMENT.md) · 🇹🇭 [th](../../th/docs/DEVELOPER-ENVIRONMENT.md) · 🇹🇷 [tr](../../tr/docs/DEVELOPER-ENVIRONMENT.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/DEVELOPER-ENVIRONMENT.md) · 🇵🇰 [ur](../../ur/docs/DEVELOPER-ENVIRONMENT.md) · 🇺🇿 [uz](../../uz/docs/DEVELOPER-ENVIRONMENT.md) · 🇻🇳 [vi](../../vi/docs/DEVELOPER-ENVIRONMENT.md) · 🇳🇬 [yo](../../yo/docs/DEVELOPER-ENVIRONMENT.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/DEVELOPER-ENVIRONMENT.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/DEVELOPER-ENVIRONMENT.md)
---
ይህ ገጽ የፕሮጀክቱን የአካባቢ `.env` ባህሪ እና OmniRouteን በማበልጸግ ጊዜ የአካባቢ ፋይሎችንና ሚስጥሮችን እንዴት መያዝ እንደሚገባ ያብራራል።
## የ.env postinstall ባህሪ
ፕሮጀክቱ ለገንቢዎች ምቾት በ`npm install` / `postinstall` ወቅት የአካባቢ `.env` ፋይል ሊፈጥር ይችላል። ይህ ፋይል ለአካባቢያዊ ልማትና ሙከራ ብቻ የታሰበ ሲሆን በፍጹም ወደ ስሪት ቁጥጥር መጨመር የለበትም።
ቁልፍ ነጥቦች፦
- የማከማቻ ስፍራው `.gitignore` አስቀድሞ `.env*` ፋይሎችን ችላ ይላል (`.gitignore` ግቤቱን ይመልከቱ)። አንድ የተወሰነ የምሳሌ ፋይል ለመጨመር ሆን ብለው ካላሰቡ እና ለዚህም በሰነድ የተደገፈ ሂደት ከሌለዎት፣ ያንን ደንብ አያስወግዱ ወይም አይቀይሩ።
- እውነተኛ ሚስጥር በአጋጣሚ ወደ repo ከተጨመረ፣ ማረጋገጫውን ወዲያውኑ ያድሱ/ይሰርዙ እና ከማከማቻ ስፍራው ታሪክ ያስወግዱት (ለምሳሌ፣ `git filter-repo`ን ወይም ተመጣጣኝ የማስተካከያ የሥራ ሂደት በመጠቀም)። እርዳታ ከፈለጉ የደህንነት/የዕውቂያ ኃላፊውን ያነጋግሩ።
- ለCI እና ለምርት አካባቢ፣ ሚስጥሮችን ወደ ፋይሎች ከመጨመር ይልቅ የCI ሚስጥሮችን ወይም የሚስጥር አስተዳዳሪን (GitHub Actions Secrets፣ Azure Key Vault፣ HashiCorp Vault፣ ወዘተ) ይጠቀሙ።
## የሚመከር የአካባቢ የሥራ ሂደት
- `.env`ን በአካባቢያዊ የሥራ ቦታዎ ውስጥ ብቻ ያቆዩ። የሚያስፈልጉ ተለዋዋጮችን እና ተቀባይነት ያላቸውን የምሳሌ እሴቶች ለመመዝገብ `.env.example`ን (አስቀድሞ በክትትል ላይ ያለ) ይጠቀሙ።
- ሚስጥር መሰል እሴቶችን የሚፈልጉ ሙከራዎችን በአካባቢዎ ሲያስኬዱ፣ ከእውነተኛ ማረጋገጫዎች ይልቅ ሰው ሠራሽ ቦታ ያዢዎችን ወይም በአሂድ ጊዜ የሚፈጠሩ ጊዜያዊ ቁልፎችን ይምረጡ።
- ገምጋሚዎች የሙከራ ውሂቡ ሰው ሠራሽ መሆኑን እንዲረዱ፣ ቦታ ያዢዎችን በሚጠቀሙ ሙከራዎች ውስጥ አጭር አስተያየት ያክሉ።
## የስካነር ማስታወሻዎች
- አንዳንድ የተቀናበሩ ወይም ሁለትዮሽ ሀብቶች (ለምሳሌ፣ የተካተቱ base64 WASM የውሂብ ስብስቦች) ማረጋገጫዎችን የሚመስሉ የASCII ንዑስ ሕብረቁምፊዎችን ሊይዙ እና በጽሑፍ ላይ የተመሠረቱ የሚስጥር ስካነሮችን ሊቀሰቅሱ ይችላሉ። እነዚህ ሀብቶች ሕጋዊ ከሆኑ፣ በስካነሩ የተፈቀዱ ዝርዝር ውስጥ ምልክት ያድርጉባቸው ወይም ማውጫዎቹን በስካነሩ ውቅር ውስጥ አያካትቱ።
## ፍንጣቂ ካገኙ
1. ቁልፉን ወዲያውኑ ያድሱ/ይሰርዙ።
2. ሚስጥሩን ከታሪኩ ያስወግዱ እና አስፈላጊ ከሆነ የጸዳውን branch በግዳጅ ይግፉ።
3. ጠባቂዎችን ያሳውቁ እና የድርጅትዎን የክስተት ምላሽ ማረጋገጫ ዝርዝር ይከተሉ።

184
docs/i18n/am/docs/DEVIN_CLAUDE_BRIDGE.md Normal file
View File

@@ -0,0 +1,184 @@
# Devin Claude Bridge (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../DEVIN_CLAUDE_BRIDGE.md) · 🇸🇦 [ar](../../ar/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇦🇿 [az](../../az/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇧🇬 [bg](../../bg/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇧🇩 [bn](../../bn/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇨🇿 [cs](../../cs/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇩🇰 [da](../../da/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇩🇪 [de](../../de/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇬🇷 [el](../../el/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇪🇸 [es](../../es/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇪🇪 [et](../../et/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇷 [fa](../../fa/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇫🇮 [fi](../../fi/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇫🇷 [fr](../../fr/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇪 [ga](../../ga/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [gu](../../gu/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇳🇬 [ha](../../ha/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇱 [he](../../he/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [hi](../../hi/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇭🇷 [hr](../../hr/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇭🇺 [hu](../../hu/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇦🇲 [hy](../../hy/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇩 [id](../../id/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇳🇬 [ig](../../ig/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇹 [it](../../it/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇯🇵 [ja](../../ja/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇬🇪 [ka](../../ka/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇰🇭 [km](../../km/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [kn](../../kn/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇰🇷 [ko](../../ko/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇱🇹 [lt](../../lt/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇱🇻 [lv](../../lv/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [ml](../../ml/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [mr](../../mr/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇲🇾 [ms](../../ms/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇲🇹 [mt](../../mt/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇲🇲 [my](../../my/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇳🇵 [ne](../../ne/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇳🇱 [nl](../../nl/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇳🇴 [no](../../no/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [or](../../or/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [pa](../../pa/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇵🇭 [phi](../../phi/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇵🇱 [pl](../../pl/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇵🇹 [pt](../../pt/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇷🇴 [ro](../../ro/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇷🇺 [ru](../../ru/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇱🇰 [si](../../si/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇸🇰 [sk](../../sk/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇸🇮 [sl](../../sl/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇷🇸 [sr](../../sr/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇸🇪 [sv](../../sv/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇰🇪 [sw](../../sw/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [ta](../../ta/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇮🇳 [te](../../te/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇹🇭 [th](../../th/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇹🇷 [tr](../../tr/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇵🇰 [ur](../../ur/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇺🇿 [uz](../../uz/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇻🇳 [vi](../../vi/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇳🇬 [yo](../../yo/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/DEVIN_CLAUDE_BRIDGE.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/DEVIN_CLAUDE_BRIDGE.md)
---
`devin-cli-agentic` እውነተኛው Claude Code runtime የOmniRouteን አካባቢያዊ Anthropic
Messages endpoint እንዲጠቀም ሲያስችል፣ ይፋዊው Devin CLI የሞዴል ምላሾችን በACP stdio ያቀርባል። ይህም
ነባሮቹን Anthropic፣ Claude OAuth፣ Claude Web ወይም `devin-cli` አቅራቢዎች አይለውጥም።
> **የአሁኑ ሁኔታ፦ Claude Code `2.1.258` ላይ ተወስኗል፤ የከመስመር ውጭ እና የቀጥታ ማረጋገጫ ለመጨረሻ ጊዜ
> በ`2.1.220` ላይ ተመዝግቧል።** የ`2.1.220` የተወሰነ ስሪት በDevin CLI
> `3000.2.17` እና በሞዴል `swe-1-7-lightning` አማካኝነት ሦስት የተነጣጠሉ ሁኔታዎችን አጠናቋል፤ ያ የመጨረሻው የቀጥታ ሙከራ በደንበኛው የሚተዳደሩ `Read`፣
> `Edit` እና `Bash` ዙሮችን፣ የተሳኩ `npm test` ውጤቶችን፣ የፕሮጀክት ትዕዛዝ እና ክህሎት
> ማግኘትን፣ የDevin ብቻ ማዞሪያን እና ምንም የClaude ወጪ ትራፊክ አለመኖሩን አረጋግጧል። ከዚያም የተወሰነው ስሪት ወደ `2.1.258`
> (የOmniRoute Claude ማንነት የሚመስለው የCLI ትውልድ፣ እንዲሁም
> የFable 5.1 ደረጃን በተፈጥሮ ያካተተ የመጀመሪያው መስመር) ከፍ ተደርጓል። በአዲሱ የተወሰነ ስሪት ላይ የመጫኛ ንብርብሩ እና `claude --version`
> በተወሰነው መሠረታዊ ምስል ላይ ተረጋግጠዋል፣ እንዲሁም የbridge ዩኒት ሙከራ ስብስብ፣ `compose config` እና
> የማይንቀሳቀስ የማግለል ማረጋገጫው ያልፋሉ — ነገር ግን የከመስመር ውጭ የማስመሰል ሁኔታው እና የቀጥታ ሦስት-ሁኔታ
> ሙከራ ስብስብ ገና ዳግም አልተካሄዱም። bridgeን በዚህ የተወሰነ ስሪት ከመጠቀምዎ በፊት እነዚህን ዳግም ያስኪዱ
> ("Updating pinned tools"ን ይመልከቱ)።
## አርክቴክቸር
```text
Claude Code 2.1.258 (በተነጠለ non-root Linux container ውስጥ)
-> http://omniroute:20128/v1/messages
-> devin-cli-agentic (Claude-format፣ no-auth provider)
-> devin acp --agent-type summarizer (ይፋዊ ACP stdio፣ ያለ Devin tools)
-> በተለየው devin-auth volume ውስጥ ያለ Devin account
```
የይፋዊው CLI ነባሪ ACP agent የራሱን tools ማስኬድ ስለሚችል፣ ይህ bridge
አይጠቀምበትም። በይፋዊው CLI ሁነታ ምንም tools የሌሉትን ቋሚ `summarizer` ACP agent ያስጀምራል፣ እና
በተከታታይ የተቀመጠውን Anthropic ጥያቄ እንደ ማስፈጸሚያ ዱካ ያቀናብራል። በClaude የሚተዳደር ሌላ
እርምጃ ሲያስፈልግ፣ ምላሹ በትክክል አንድ የደንበኛ tool envelope መያዝ አለበት። ማንኛውም ACP
`tool_call` ወይም `tool_call_update` ምላሹ የተሳካ ተብሎ ከመዘገቡ በፊት ውድቅ ይደረጋል።
በ`open-sse/executors/devin-agentic/serializer.ts` ውስጥ ያለው serializer `system`፣
`text`፣ `tool_use`፣ `tool_result`፣ `thinking`፣ `redacted_thinking`፣ `tool_choice` እና
በClaude Code የቀረቡትን tools እንዳሉ ይጠብቃል። ምስሎች እና ያልታወቁ blocks በግልጽ ሁኔታ እንዲያልፉ አይደረግም። ትላልቅ tool results
የሚታይ የመቁረጥ ምልክት ይጠቀማሉ።
parserው በእያንዳንዱ የሞዴል ዙር አንድ ለብቻው የቆመ `<tool>{...}</tool>` envelope ይቀበላል። ስሙን
ከጥያቄው tool ዝርዝር ጋር ያረጋግጣል፣ argumentsን ከዚያ tool JSON
Schema ጋር ያረጋግጣል፣ የተቀላቀለ ትረካ/እርምጃዎችን ውድቅ ያደርጋል፣ እና አንድ የተገደበ ጥገና ይፈቅዳል። ከዚያ Claude Code
የተገኘውን Anthropic `tool_use` በአካባቢው ያስኬዳል እና `tool_result`ን በOmniRoute በኩል
መልሶ ይልካል።
## ማግለል እና የስጋት ሞዴል
የአስተናጋጁ Claude ጭነት፣ account እና ውቅር ከወሰን ውጭ ሲሆኑ
እንደ የተከለከሉ ይቆጠራሉ። የCompose services፦
- እንደ UID/GID `10001:10001` ይሰራሉ፣ root filesystem ለንባብ ብቻ ነው፣ capabilities ተወግደዋል፣ እና
`no-new-privileges` ተዋቅሯል፤
- የግል `/home/bridge`፣ የተለየ Claude config volume፣ የተነጠለ OmniRoute data፣
እና የተለየ `devin-auth` volume ይጠቀማሉ፤
- የሚጫኑት ሊወገዱ የሚችሉ `.sandbox` workspaces/evidenceን ብቻ ነው፤
- የአስተናጋጁን home፣ Keychain፣ SSH፣ cloud credentials ወይም Docker socket አይጭኑም፤
- ግልጽ environments ይገነባሉ እና Anthropic API/OAuth/routing variablesን ያስወግዳሉ፤
- የClaude Code inferenceን በአካባቢ-ብቻ key ወደ `http://omniroute:20128` ብቻ ይመራሉ።
የከመስመር ውጭ profileው ውስጣዊ network ይጠቀማል። በቀጥታ profile ውስጥ OmniRoute ወደ
ይፋዊዎቹ Devin endpoints የሚደርሰው በ`network-guard` በኩል ብቻ ነው፤ ያልተዛመዱ destinations ይከለከላሉ።
Claude Code የተለየ ሁሉንም የወጪ ትራፊክ የሚከለክል guard አለው፣ እና በ`NO_PROXY` በኩል የአካባቢውን OmniRoute
service ብቻ ማግኘት ይችላል። የGuard audit files የሚጫኑት በየguard processያቸው ብቻ ነው።
scriptsዎቹ token-free evidenceን ወደ ውጭ ከመላካቸው በፊት የፋይል ownership፣ mode፣ link count እና እያንዳንዱን decision
ያረጋግጣሉ።
የማግለል ማረጋገጫውን ለብቻው ያስኪዱ፦
```bash
./scripts/devin-bridge/verify-anthropic-isolation
```
ይህ topologyን፣ named mountsን፣ non-root/read-only settingsን፣ ግልጽ local routingን፣
sensitive environment variables አለመኖራቸውን፣ Docker socket አለመኖሩን፣ ወደ
`api.anthropic.com` እና `claude.ai` የታገደ accessን፣ Devin-only provider selectionን፣ እና
ACP backend በማይገኝበት ጊዜ ግልጽ failureን ያረጋግጣል።
## የመጀመሪያ ጊዜ ማዋቀር እና መደበኛ አጠቃቀም
የተወሰነውን ኢሜጅ ይገንቡ፦
```bash
./scripts/devin-bridge/build
```
የተገለለውን Devin volume ብቻ ያረጋግጡ፦
```bash
ENABLE_LIVE_DEVIN_TESTS=1 ./scripts/devin-bridge/login-devin
```
የመግቢያ ትዕዛዙ ለርቀት/container አካባቢዎች የታሰበውን ይፋዊ የmanual-token ሂደት
ይጠቀማል። እሴቱ በቀጥታ ወደ CLI ጥያቄው ይገባል፤ እንደ process
argument አይተላለፍም፣ ወደ Git አይጻፍም፣ ወይም ከhost አይቀዳም።
የተገለለውን Claude Code runtime ያስጀምሩ፦
```bash
./scripts/devin-bridge/launch
```
`launch` containerized Claude Codeን ከማስጀመሩ በፊት መገለሉን፣ የDevin ማረጋገጫን እና
የmodel ፍለጋን እንደገና ይፈትሻል። የhostን Claude executable ፈጽሞ አያስኬድም።
የmodel aliases በ`.env.devin-bridge` ውስጥ ሊዘጋጁ ይችላሉ፤ እያንዳንዱ የተዋቀረ እሴት
የ`devin-cli-agentic/` prefixን መያዝ አለበት።
## የማረጋገጫ ትዕዛዞች
እንደገና ሊደገም የሚችለው offline መንገድ የDevin መለያ አያስፈልገውም፣ በruntimeም Internet የለውም፦
```bash
./scripts/devin-bridge/test-unit
./scripts/devin-bridge/test-contract
./scripts/devin-bridge/test-e2e-mock
./scripts/devin-bridge/verify-anthropic-isolation
```
ማረጋገጫ የሚፈልገው opt-in live መንገድ ይህ ነው፦
```bash
ENABLE_LIVE_DEVIN_TESTS=1 ./scripts/devin-bridge/test-live-devin
```
የlive runner የACP sessionsን በአንድ ጊዜ በብዛት እንዳይከፍት በscenarios መካከል ይጠብቃል፣
እና ጽሑፋዊ ማረጋገጫዎችን ከማመን ይልቅ የተዋቀሩ Claude stream eventsን ያረጋግጣል።
ሦስቱ scenarios የሚከተሉትን ያረጋግጣሉ፦
1. ቀጥተኛ የproject ንባቦች እና የጉድለት ትንተና፤
2. ትክክለኛ `Edit`፣ በclient ባለቤትነት የሚካሄድ `Bash` `npm test`፣ እና የመጨረሻ ውጤት፤
3. `/bridge-check` ከ`bridge-proof` ፍለጋ ጋር፣ የproject ንባቦች፣ ሌላ የተሳካ
በclient ባለቤትነት የሚካሄድ `npm test`፣ እና ተጠባባቂ ሥራ ሳይኖር መጠናቀቅ።
የመጨረሻው gate የDevin network auditንም ይፈትሻል፣ እና የClaude egress audit ባዶ ሆኖ
እንዲቆይ ይጠይቃል።
## የተወሰኑ toolsን ማዘመን
ኢሜጁ Nodeን፣ Claude Codeን እና Devin CLIን በ
`docker/devin-bridge/Dockerfile` ውስጥ በተወሰኑ ስሪቶች ያስቀምጣል። ለማዘመን፦
1. በግልጽ የተጠቀሱትን ስሪቶች ይቀይሩ፤
2. ሁለቱንም architecture-specific Devin archive checksums ለይፋዊው
artifact በሚሆኑ እሴቶች ይተኩ፤
3. እንደገና ይገንቡ እና እያንዳንዱን offline የማረጋገጫ ትዕዛዝ ያስኪዱ፤
4. በኢሜጁ ውስጥ ያሉትን ስሪቶች ያረጋግጡ፤
5. ማረጋገጫ የሚፈልገውን የሦስት-scenario live suite እንደገና ያስኪዱ።
ከሁለቱም CLIዎች አንዱንም በhost ላይ globally አይጫኑ፣ ወይም checksum verificationን
ባልተረጋገጠ download አይተኩ።
## ምርመራ እና ማጽዳት
- `docker compose -f docker/devin-bridge/compose.yml --profile offline logs omniroute`
የአካባቢያዊ routing እና የጸዱ executor errorsን ያሳያል።
- `.sandbox/evidence/mock-acp.jsonl` deterministic mock ACP actionsን ይመዘግባል።
- `.sandbox/evidence/claude-stream.jsonl` ትክክለኛውን የClaude Code offline run ይመዘግባል።
- `.sandbox/evidence/live-*.jsonl` ሦስቱን የተረጋገጡ live streams ይመዘግባል።
- `.sandbox/evidence/egress.jsonl` እና `.sandbox/evidence/claude-egress.jsonl` የተረጋገጡ፣
token የሌላቸው የguard audits ቅጂዎች ናቸው።
የlogin/config volumesን በመጠበቅ በbridge ባለቤትነት የተያዙ containersን እና networksን ያቁሙ፦
```bash
./scripts/devin-bridge/clean
```
named volumesን ጨምሮ በbridge ባለቤትነት የተያዘውን ሙሉ environment ያስወግዱ፦
```bash
./scripts/devin-bridge/clean --all
```
## ገደቦች
- Devin CLI `3000.2.17` ገለልተኛ መሣሪያ-አልባ ACP agent ስለማያቀርብ፣ bridge ቋሚውን መሣሪያ-አልባ `summarizer` role ይጠቀማል። adapter ማጠቃለያ ቅርጽ ያላቸውን መካከለኛ ምላሾች ያስተካክላል፣ ነገር ግን አንድ የተወሰነ repair አሁንም በግልጽ ሊሳካ ይችላል።
- የቀጥታ ACP ጥሪዎች ጊዜያዊ `502`/`504` ምላሾችን ሊመልሱ ይችላሉ። harness ሁኔታዎችን በጊዜ ያራርቃል፤ ቀጣይነት ያለው ውድቀት fail-closed ሆኖ ይቀራል እና ሌላ provider ፈጽሞ አይመርጥም።
- የ ACP context ከእያንዳንዱ Anthropic ጥያቄ እንደገና ይገነባል፤ የ process/session affinity የለም።
- በእያንዳንዱ model ምላሽ አንድ tool call ይደገፋል፤ ትይዩ ጥሪዎች ውድቅ ይደረጋሉ።
- ምስሎች እንደማይደገፉ በግልጽ ተገልጿል። Vision፣ thinking output፣ effort controls እና የ1M context window አይተዋወቁም።
- SSE ትክክለኛ የ Anthropic lifecycle events ይጠቀማል፣ ነገር ግን የተወሰነው ACP turn ከተሰበሰበ በኋላ ይላካል፤ የ ACP chunks በቅጽበት አይተላለፉም።

13
docs/i18n/am/docs/OMNIROUTE_ALLOCATION_HANDOFF.md Normal file
View File

@@ -0,0 +1,13 @@
# OmniRoute Allocation Handoff (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇸🇦 [ar](../../ar/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇦🇿 [az](../../az/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇧🇬 [bg](../../bg/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇧🇩 [bn](../../bn/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇨🇿 [cs](../../cs/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇩🇰 [da](../../da/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇩🇪 [de](../../de/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇬🇷 [el](../../el/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇪🇸 [es](../../es/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇪🇪 [et](../../et/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇷 [fa](../../fa/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇫🇮 [fi](../../fi/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇫🇷 [fr](../../fr/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇪 [ga](../../ga/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [gu](../../gu/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇳🇬 [ha](../../ha/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇱 [he](../../he/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [hi](../../hi/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇭🇷 [hr](../../hr/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇭🇺 [hu](../../hu/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇦🇲 [hy](../../hy/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇩 [id](../../id/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇳🇬 [ig](../../ig/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇹 [it](../../it/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇯🇵 [ja](../../ja/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇬🇪 [ka](../../ka/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇰🇭 [km](../../km/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [kn](../../kn/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇰🇷 [ko](../../ko/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇱🇹 [lt](../../lt/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇱🇻 [lv](../../lv/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [ml](../../ml/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [mr](../../mr/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇲🇾 [ms](../../ms/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇲🇹 [mt](../../mt/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇲🇲 [my](../../my/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇳🇵 [ne](../../ne/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇳🇱 [nl](../../nl/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇳🇴 [no](../../no/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [or](../../or/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [pa](../../pa/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇵🇭 [phi](../../phi/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇵🇱 [pl](../../pl/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇵🇹 [pt](../../pt/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇷🇴 [ro](../../ro/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇷🇺 [ru](../../ru/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇱🇰 [si](../../si/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇸🇰 [sk](../../sk/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇸🇮 [sl](../../sl/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇷🇸 [sr](../../sr/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇸🇪 [sv](../../sv/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇰🇪 [sw](../../sw/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [ta](../../ta/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇮🇳 [te](../../te/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇹🇭 [th](../../th/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇹🇷 [tr](../../tr/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇵🇰 [ur](../../ur/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇺🇿 [uz](../../uz/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇻🇳 [vi](../../vi/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇳🇬 [yo](../../yo/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/OMNIROUTE_ALLOCATION_HANDOFF.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/OMNIROUTE_ALLOCATION_HANDOFF.md)
---
ምደባ የአቅራቢ ኮታ አይደለም።
የኮታ ገንዳዎች የትኞቹ API ቁልፎች የአቅራቢ ገንዳን መጠቀም እንደሚችሉ እና ጥብቅ፣ ለስላሳ ወይም ድንገተኛ ጭማሪን የሚፈቅዱ ፖሊሲዎች እንዴት ተግባራዊ እንደሚሆኑ ይወስናሉ። የአቅራቢ ኮታ በአቅራቢ የሚገለጽ ውጫዊ አቅም ወይም በግልጽ ከተዋቀረ ምንጭ የሚገኝ አቅም ነው። የGhostlight ውስጣዊ በጀቶች በአስተዳዳሪው የሚወሰኑ የአስተዳደር ገደቦች ናቸው።
የ`ensurePool` ክዋኔ idempotent ነው፦ ተመሳሳይ ገንዳ ሳይቀየር ይቀራል፣ የተቀየረ ምደባ ይዘምናል፣ እና የሌለ ገንዳ ይፈጠራል። ይህ ለአውቶሜሽን እና ጥሪዎቻቸው የተገደቡ API ደዋዮች የታሰበ ነው።
የተነባቢ-ብቻ ሁኔታ መጨረሻ ነጥብ `GET /api/omniroute/status` ነው። የማረጋገጫ ትዕዛዙ `npm run omniroute:verify` ነው፤ ወደ ቀጥታ ሞዴል ምንም ጥያቄ አያቀርብም።

13
docs/i18n/am/docs/OMNIROUTE_PROVIDER_FAILOVER.md Normal file
View File

@@ -0,0 +1,13 @@
# OmniRoute Provider Failover (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../OMNIROUTE_PROVIDER_FAILOVER.md) · 🇸🇦 [ar](../../ar/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇦🇿 [az](../../az/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇧🇬 [bg](../../bg/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇧🇩 [bn](../../bn/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇨🇿 [cs](../../cs/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇩🇰 [da](../../da/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇩🇪 [de](../../de/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇬🇷 [el](../../el/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇪🇸 [es](../../es/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇪🇪 [et](../../et/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇷 [fa](../../fa/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇫🇮 [fi](../../fi/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇫🇷 [fr](../../fr/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇪 [ga](../../ga/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [gu](../../gu/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇳🇬 [ha](../../ha/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇱 [he](../../he/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [hi](../../hi/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇭🇷 [hr](../../hr/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇭🇺 [hu](../../hu/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇦🇲 [hy](../../hy/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇩 [id](../../id/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇳🇬 [ig](../../ig/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇹 [it](../../it/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇯🇵 [ja](../../ja/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇬🇪 [ka](../../ka/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇰🇭 [km](../../km/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [kn](../../kn/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇰🇷 [ko](../../ko/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇱🇹 [lt](../../lt/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇱🇻 [lv](../../lv/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [ml](../../ml/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [mr](../../mr/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇲🇾 [ms](../../ms/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇲🇹 [mt](../../mt/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇲🇲 [my](../../my/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇳🇵 [ne](../../ne/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇳🇱 [nl](../../nl/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇳🇴 [no](../../no/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [or](../../or/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [pa](../../pa/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇵🇭 [phi](../../phi/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇵🇱 [pl](../../pl/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇵🇹 [pt](../../pt/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇷🇴 [ro](../../ro/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇷🇺 [ru](../../ru/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇱🇰 [si](../../si/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇸🇰 [sk](../../sk/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇸🇮 [sl](../../sl/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇷🇸 [sr](../../sr/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇸🇪 [sv](../../sv/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇰🇪 [sw](../../sw/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [ta](../../ta/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇮🇳 [te](../../te/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇹🇭 [th](../../th/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇹🇷 [tr](../../tr/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇵🇰 [ur](../../ur/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇺🇿 [uz](../../uz/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇻🇳 [vi](../../vi/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇳🇬 [yo](../../yo/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/OMNIROUTE_PROVIDER_FAILOVER.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/OMNIROUTE_PROVIDER_FAILOVER.md)
---
እንደገና ለመሞከር ውሳኔዎች ከመደረጋቸው በፊት ውድቀቶች ይመደባሉ።
እንደ ጊዜ ማለፍ፣ የአውታረ መረብ ስህተቶች፣ የጥያቄ መጠን ገደቦች እና የአቅራቢ 5xx ምላሾች ያሉ ጊዜያዊ ውድቀቶች ወደ ሌላ አቅራቢ እንዲዞሩ ሊያደርጉ ይችላሉ። የማረጋገጫ ስህተቶች፣ የፈቃድ ስህተቶች፣ ልክ ያልሆኑ ጥያቄዎች፣ የማይገኙ ሞዴሎች እና ያልታወቁ ውድቀቶች ያለ ልዩነት እንደገና አይሞከሩም።
ነባሪው የአቅራቢዎች-ተሻጋሪ ፖሊሲ እስከ ሦስት የአቅራቢ ሙከራዎችን ይፈቅዳል፣ የጥያቄ መጠን ገደቦችን እና የጊዜ ማለፎችን እንደገና ይሞክራል፣ እንዲሁም አስተዳደራዊ ማሰናከልን ከጊዜያዊ የወረዳ ሁኔታ ለይቶ ያቆያል።
የወረዳ ሁኔታዎች `closed`፣ `open` እና `half_open` ናቸው። የማቀዝቀዣ ጊዜ የተገደበ የፍተሻ ሙከራን ያቅዳል፤ የተሳካ የፍተሻ ሙከራ ወረዳውን ይዘጋል፣ ያልተሳካ የፍተሻ ሙከራ ደግሞ እንደገና ይከፍተዋል።

21
docs/i18n/am/docs/OMNIROUTE_QUOTA_TELEMETRY.md Normal file
View File

@@ -0,0 +1,21 @@
# OmniRoute Quota Telemetry (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../OMNIROUTE_QUOTA_TELEMETRY.md) · 🇸🇦 [ar](../../ar/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇦🇿 [az](../../az/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇧🇬 [bg](../../bg/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇧🇩 [bn](../../bn/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇨🇿 [cs](../../cs/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇩🇰 [da](../../da/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇩🇪 [de](../../de/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇬🇷 [el](../../el/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇪🇸 [es](../../es/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇪🇪 [et](../../et/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇷 [fa](../../fa/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇫🇮 [fi](../../fi/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇫🇷 [fr](../../fr/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇪 [ga](../../ga/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [gu](../../gu/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇳🇬 [ha](../../ha/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇱 [he](../../he/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [hi](../../hi/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇭🇷 [hr](../../hr/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇭🇺 [hu](../../hu/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇦🇲 [hy](../../hy/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇩 [id](../../id/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇳🇬 [ig](../../ig/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇹 [it](../../it/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇯🇵 [ja](../../ja/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇬🇪 [ka](../../ka/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇰🇭 [km](../../km/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [kn](../../kn/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇰🇷 [ko](../../ko/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇱🇹 [lt](../../lt/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇱🇻 [lv](../../lv/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [ml](../../ml/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [mr](../../mr/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇲🇾 [ms](../../ms/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇲🇹 [mt](../../mt/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇲🇲 [my](../../my/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇳🇵 [ne](../../ne/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇳🇱 [nl](../../nl/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇳🇴 [no](../../no/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [or](../../or/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [pa](../../pa/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇵🇭 [phi](../../phi/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇵🇱 [pl](../../pl/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇵🇹 [pt](../../pt/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇷🇴 [ro](../../ro/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇷🇺 [ru](../../ru/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇱🇰 [si](../../si/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇸🇰 [sk](../../sk/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇸🇮 [sl](../../sl/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇷🇸 [sr](../../sr/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇸🇪 [sv](../../sv/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇰🇪 [sw](../../sw/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [ta](../../ta/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇮🇳 [te](../../te/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇹🇭 [th](../../th/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇹🇷 [tr](../../tr/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇵🇰 [ur](../../ur/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇺🇿 [uz](../../uz/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇻🇳 [vi](../../vi/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇳🇬 [yo](../../yo/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/OMNIROUTE_QUOTA_TELEMETRY.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/OMNIROUTE_QUOTA_TELEMETRY.md)
---
OmniRoute የአቅራቢዎችን ኮታ ቴሌሜትሪ ከGhostlight ሒሳብ አያያዝ ይለያል።
## እውነተኛ ሁኔታዎች
- `healthy` ማለት አንድ ምንጭ ጥቅም ላይ ሊውል የሚችል ቀሪ አቅም እንዳለ ሪፖርት አድርጓል ማለት ነው።
- `approaching_limit` ማለት አንድ ምንጭ ቀሪው አቅም ከተዋቀረው ገደብ ጋር እኩል ወይም ከዚያ በታች መሆኑን ሪፖርት አድርጓል ማለት ነው።
- `exhausted` የሚወጣው አንድ ምንጭ ዜሮ አቅም እንዳለው ወይም አጠቃቀሙ ገደቡ ላይ እንደደረሰ ሪፖርት ሲያደርግ ብቻ ነው።
- `unavailable` ማለት የሚደገፍ ምንጭ ውሂብ ማስመለስ አልቻለም ማለት ነው።
- `unknown` ማለት ምንም የሚደገፍ ምንጭ የለም ወይም ምንም የታወቀ የአቅራቢ ገደብ የለም ማለት ነው።
ያልታወቀ ማለት ያለቀ ማለት አይደለም፤ አቅራቢንም አያሰናክልም።
ምንጮች በዚህ ቅደም ተከተል ቅድሚያ ይሰጣቸዋል፦ ይፋዊ የአቅራቢ API፣ የማንነት ማረጋገጫ ያለው የአጠቃቀም API፣ በግልጽ የተመደቡ የምላሽ ራስጌዎች፣ የአስተዳዳሪ ውቅር፣ አካባቢያዊ ግምቶች፣ ያልታወቀ። አካባቢያዊ ግምቶች እንደ የአቅራቢ የክፍያ መረጃ ፈጽሞ አይቀርቡም።
የምላሽ ራስጌዎች የሚተነተኑት በግልጽ በተወሰነ የአቅራቢ ማመሳሰያ በኩል ብቻ ነው። አጠቃላይ የራስጌ ስሞች በዓለም አቀፍ ደረጃ በነባሪ አይታሰቡም።

15
docs/i18n/am/docs/OMNIROUTE_ROUTING_POLICY.md Normal file
View File

@@ -0,0 +1,15 @@
# OmniRoute Routing Policy (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../OMNIROUTE_ROUTING_POLICY.md) · 🇸🇦 [ar](../../ar/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇦🇿 [az](../../az/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇧🇬 [bg](../../bg/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇧🇩 [bn](../../bn/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇨🇿 [cs](../../cs/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇩🇰 [da](../../da/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇩🇪 [de](../../de/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇬🇷 [el](../../el/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇪🇸 [es](../../es/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇪🇪 [et](../../et/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇷 [fa](../../fa/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇫🇮 [fi](../../fi/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇫🇷 [fr](../../fr/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇪 [ga](../../ga/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [gu](../../gu/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇳🇬 [ha](../../ha/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇱 [he](../../he/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [hi](../../hi/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇭🇷 [hr](../../hr/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇭🇺 [hu](../../hu/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇦🇲 [hy](../../hy/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇩 [id](../../id/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇳🇬 [ig](../../ig/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇹 [it](../../it/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇯🇵 [ja](../../ja/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇬🇪 [ka](../../ka/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇰🇭 [km](../../km/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [kn](../../kn/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇰🇷 [ko](../../ko/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇱🇹 [lt](../../lt/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇱🇻 [lv](../../lv/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [ml](../../ml/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [mr](../../mr/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇲🇾 [ms](../../ms/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇲🇹 [mt](../../mt/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇲🇲 [my](../../my/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇳🇵 [ne](../../ne/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇳🇱 [nl](../../nl/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇳🇴 [no](../../no/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [or](../../or/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [pa](../../pa/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇵🇭 [phi](../../phi/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇵🇱 [pl](../../pl/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇵🇹 [pt](../../pt/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇷🇴 [ro](../../ro/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇷🇺 [ru](../../ru/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇱🇰 [si](../../si/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇸🇰 [sk](../../sk/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇸🇮 [sl](../../sl/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇷🇸 [sr](../../sr/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇸🇪 [sv](../../sv/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇰🇪 [sw](../../sw/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [ta](../../ta/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇮🇳 [te](../../te/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇹🇭 [th](../../th/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇹🇷 [tr](../../tr/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇵🇰 [ur](../../ur/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇺🇿 [uz](../../uz/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇻🇳 [vi](../../vi/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇳🇬 [yo](../../yo/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/OMNIROUTE_ROUTING_POLICY.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/OMNIROUTE_ROUTING_POLICY.md)
---
ራውቲንግ ነባሩን የችሎታ እና የጥምር ምርጫ አመክንዮ ይጠብቃል፤ ከዚያም የምደባ፣ የጤንነት፣ የወረዳ፣ የኮታ፣ የመዘግየት ጊዜ፣ የአስተማማኝነት፣ የሞዴል ምርጫ እና የወጪ ምርጫ ምክንያቶችን ይተገብራል።
የሚላመደው ውጤት ሊብራራ የሚችል ሲሆን፣ የተመረጠውን እጩ እና ሁሉንም በደረጃ የተቀመጡ እጩዎች ይመልሳል። ኮታቸው ያለቀ፣ ምደባቸው የተከለከለ እና ወረዳቸው ክፍት የሆኑ ብቁ አይደሉም። ያልታወቀ ኮታ በገለልተኛ የኮታ ምክንያት ብቁ ሆኖ ይቆያል።
የራውት ቅድመ-ዕይታው ውጤቱ የማይለዋወጥ ሲሆን፣ ወደ ላይኛው የሞዴል አገልግሎት ምንም ጥያቄ አያደርግም፦
`POST /api/omniroute/route/preview`
ምላሹ የእጩዎችን ውጤቶች፣ ምክንያቶች፣ የውሳኔ ማብራሪያዎች፣ የተመረጠውን አቅራቢ እና `liveRequestExecuted: false` ያካትታል።

351
docs/i18n/am/docs/architecture/ADAPTIVE_ROUTING.md Normal file
View File

@@ -0,0 +1,351 @@
# Adaptive Routing: Routing Events, Quality Feedback & Explainability (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ADAPTIVE_ROUTING.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ADAPTIVE_ROUTING.md) · 🇦🇿 [az](../../../az/docs/architecture/ADAPTIVE_ROUTING.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ADAPTIVE_ROUTING.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ADAPTIVE_ROUTING.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ADAPTIVE_ROUTING.md) · 🇩🇰 [da](../../../da/docs/architecture/ADAPTIVE_ROUTING.md) · 🇩🇪 [de](../../../de/docs/architecture/ADAPTIVE_ROUTING.md) · 🇬🇷 [el](../../../el/docs/architecture/ADAPTIVE_ROUTING.md) · 🇪🇸 [es](../../../es/docs/architecture/ADAPTIVE_ROUTING.md) · 🇪🇪 [et](../../../et/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ADAPTIVE_ROUTING.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ADAPTIVE_ROUTING.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ADAPTIVE_ROUTING.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇱 [he](../../../he/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ADAPTIVE_ROUTING.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ADAPTIVE_ROUTING.md) · 🇭🇺 [hu](../../../hu/docs/architecture/ADAPTIVE_ROUTING.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇩 [id](../../../id/docs/architecture/ADAPTIVE_ROUTING.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇹 [it](../../../it/docs/architecture/ADAPTIVE_ROUTING.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ADAPTIVE_ROUTING.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ADAPTIVE_ROUTING.md) · 🇰🇭 [km](../../../km/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ADAPTIVE_ROUTING.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ADAPTIVE_ROUTING.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ADAPTIVE_ROUTING.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ADAPTIVE_ROUTING.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ADAPTIVE_ROUTING.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ADAPTIVE_ROUTING.md) · 🇲🇲 [my](../../../my/docs/architecture/ADAPTIVE_ROUTING.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ADAPTIVE_ROUTING.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ADAPTIVE_ROUTING.md) · 🇳🇴 [no](../../../no/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [or](../../../or/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ADAPTIVE_ROUTING.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ADAPTIVE_ROUTING.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ADAPTIVE_ROUTING.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ADAPTIVE_ROUTING.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ADAPTIVE_ROUTING.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ADAPTIVE_ROUTING.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ADAPTIVE_ROUTING.md) · 🇱🇰 [si](../../../si/docs/architecture/ADAPTIVE_ROUTING.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ADAPTIVE_ROUTING.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ADAPTIVE_ROUTING.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ADAPTIVE_ROUTING.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ADAPTIVE_ROUTING.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ADAPTIVE_ROUTING.md) · 🇮🇳 [te](../../../te/docs/architecture/ADAPTIVE_ROUTING.md) · 🇹🇭 [th](../../../th/docs/architecture/ADAPTIVE_ROUTING.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ADAPTIVE_ROUTING.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ADAPTIVE_ROUTING.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ADAPTIVE_ROUTING.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ADAPTIVE_ROUTING.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ADAPTIVE_ROUTING.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ADAPTIVE_ROUTING.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ADAPTIVE_ROUTING.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ADAPTIVE_ROUTING.md)
---
ይህ ሰነድ ወደ OmniRoute የታከለውን በግብረመልስ የሚመራ መላመድ የሚችል የማዘዋወር መሠረት ይገልጻል።
ሆን ተብሎ አነስተኛ እንዲሆን ተደርጓል፦ ዓይነቱ የተገለጸ የማዘዋወር ውጤት
ቻናል፣ ነባሩን የauto-combo ነጥብ ሰጪ የሚመግብ ቀጣይነት ያለው የጥራት ምልክት፣
አማራጭ OpenTelemetry ላኪ እና የማብራሪያ መጨረሻ ነጥብ ያስተዋውቃል። ነባሩን
የመቋቋም ስብስብ (circuit breaker፣ connection cooldown፣
model lockout፣ health matrix፣ autopilot) **አይተካም** — ያሟላዋል።
## 1. የሥነ ሕንፃ አውድ
OmniRoute **የጥያቄ ፈጣን መንገድ** እና **የቁጥጥር/ብልህነት
ፕሌን** ያለው የውሂብ ፕሌን ነው። ፈጣን መንገዱ ፈጣን፣ በማስታወሻ አጠቃቀም ቆጣቢ፣ አልተመሳሰለ፣ ተቋቋሚ እና
ሊገመት የሚችል ሆኖ መቆየት አለበት። ግምገማ፣ የጥራት ነጥብ አሰጣጥ፣ ሙከራዎች እና ታሪካዊ ትንተና
የቁጥጥር ፕሌኑ አካል ናቸው።
```
AI Agent / IDE
│
▼
┌─────────────────────┐
│ OmniRoute │ የውሂብ ፕሌን (ፈጣን፣ የተመሳሰለ፣ በማስታወሻ ውስጥ)
│ ማዘዋወር / failover │
│ ጤና / guardrail │
│ cache / streaming │
└──────────┬──────────┘
│ RoutingEvent (ልኮ መርሳት፣ ~0.2µs)
▼
┌─────────────────────┐
│ የግብረመልስ sinks │ የቁጥጥር ፕሌን (ያልተመሳሰለ፣ በተቻለ መጠን)
│ የጥራት tracker │
│ OTel exporter │
│ explain store │
└──────────┬──────────┘
▼ የጥራት ነጥብ
auto-combo scorer
```
### አስቀድሞ የነበረው (የተመረመረ፣ ያልተደገመ)
| ጽንሰ-ሐሳብ | ነባር ትግበራ |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| የመገኘት አቅም (ትራፊክ መላክ እንችላለን?) | Circuit breaker (CLOSED/DEGRADED/OPEN/HALF_OPEN፣ በDB የተከማቸ)፣ connection cooldown፣ model lockout |
| የጤና ሪፖርት | `providerHealthMatrix.ts`፣ `providerHealthAutopilot.ts` |
| የጥላ ትራፊክ | `open-sse/services/combo/shadowRouting.ts` |
| Guardrails | `src/lib/guardrails/` (የቅድመ/ድህረ hooks) |
| ትክክለኛ cache | `src/lib/semanticCache.ts` (በsignature ላይ የተመሠረተ) |
| ገምጋሚዎች / በግምገማ የሚመራ ማዘዋወር | `src/lib/evals/`፣ `open-sse/services/evalRouting.ts` |
| የCombo ውሳኔ ማብራሪያ | `open-sse/services/combo/decisionTrace.ts` |
| የDashboard ቅጽበታዊ ክስተቶች | `src/lib/events/eventBus.ts` (የUI ማሳወቂያ ቻናል፣ `unknown` payloads፣ የ100 ግቤቶች ታሪክ) |
የማዘዋወር ክስተት ንብርብሩ የ`eventBus` ዳግም ትግበራ **አይደለም**፦ ያ ባስ
የdashboard ቅጽበታዊ ማሳወቂያ ቻናል ነው (ዓይነታቸው የተገለጸ _የክስተት ስሞች_፣ ውስጣቸው የማይታይ
payloads፣ የUI ተጠቃሚዎች)። `RoutingEvent` በቁጥጥር ፕሌኑ
የግብረመልስ sinks (የጥራት tracker፣ OTel exporter፣ explain store) የሚጠቀሙበት፣ ዓይነቱ የተገለጸ _ውጤት_ struct
(latency/tokens/cost/outcome/finish-reason) ነው።
### የጎደለው (እዚህ የታከለ)
1. **ዓይነቱ የተገለጸ የማዘዋወር ውጤት ክስተት + sink abstraction** (`RoutingEvent` /
`RoutingEventSink`)። `decisionTrace` በcombo ላይ የተወሰነ እና በማስታወሻ ውስጥ ብቻ ነው፤
`comboMetrics` ድምር ቆጣሪዎች ናቸው፤ `call_logs` ጥሬ ያልተመሳሰለ ማከማቻ ነው።
አንዳቸውም የጥራት tracker፣ OTel
exporter ወይም Future-AGI-ቅጥ ገምጋሚ ሊመዘገብበት የሚችል፣ ዓይነቱ የተገለጸ በsink ላይ የተመሠረተ የውጤት ቻናል አይደለም።
2. ለውጤት ጥራት **ቀጣይነት ያለው የጥራት ምልክት** (EWMA) — ነጥብ ሰጪው ከዚህ በፊት
"ጥራትን" በቋሚ የተግባር ተስማሚነት እና በፈቃድ በሚነቁ የግምገማ ማለፊያ ምጣኔዎች ብቻ በተዘዋዋሪ ይወክል ነበር።
3. የGenAI semantic conventionsን የሚጠቀም **አማራጭ፣ ከጥገኝነት ነጻ የሆነ OTel exporter**።
4. ትክክለኛዎቹን የማዘዋወር ውሳኔዎች + የጥራት ሁኔታ የሚመልስ **የማብራሪያ መጨረሻ ነጥብ**።
## 2. የራውቲንግ ክስተቶች (የግብረመልስ መሠረት)
ፋይሎች፦ `open-sse/services/routing/events.ts`፣ `.../index.ts`
አንድ `RoutingEvent` የሚይዘው የራውቲንግ ሜታዳታን ብቻ ነው፦
```ts
interface RoutingEvent {
requestId: string;
provider: string;
model: string;
strategy: string; // "auto" | "priority" | "direct" | ...
latencyMs: number;
ttftMs: number | null;
inputTokens: number | null;
outputTokens: number | null;
cost: number | null;
retries: number;
fallbackUsed: boolean;
outcome: RoutingOutcome; // በተፈቀደላቸው ዝርዝር የተገደበ union
status: number | null;
finishReason: string | null;
connectionId: string | null;
ts: number;
}
```
`RoutingEventSink` በTypeScript ውስጥ `Send+Sync`-ዓይነት trait ነው፦
```ts
interface RoutingEventSink {
readonly name: string;
record(event: RoutingEvent): void; // O(1) መሆን አለበት፣ sync I/O የለም
}
```
hot path ለእያንዳንዱ የተጠናቀቀ ጥያቄ `emitRoutingEvent(event)`ን አንድ ጊዜ ይጠራል
(የstreaming ማጠናቀቂያ callback፣ streaming ያልሆነው የስኬት መንገድ፣ እና
በ`handleChatCore` ውስጥ ያለው malformed-200 የውድቀት መንገድ)። Dispatch ወደ
ተመዘገቡ sinks በማመሳሰል fan-out ያደርጋል፣ ነገር ግን እያንዳንዱ sink
በማስታወሻ ውስጥ ያለን ሁኔታ ወደ ወረፋ ያስገባል/ያዘምናል ብቻ። **በhot path ላይ
የተመሳሰሉ የውሂብ ጎታ ጽሑፎች ወይም የአውታረ መረብ I/O የሉም።**
ነባሪ sinks፦
- `MemoryRoutingEventStore` — የተገደበ (500) ring buffer፣ አዲሶቹን በመጀመሪያ
የሚያሳይ፣ ለexplain endpoint።
- `QualityTracker` consumer — የEWMA የጥራት ግምትን ያዘምናል።
- `OtlpHttpsEventSink` — አማራጭ፣ `OMNIROUTE_OTEL_ENDPOINT`
(ወይም `OTEL_EXPORTER_OTLP_ENDPOINT`) ሲዋቀር ብቻ የነቃ።
### የተለካ ተጨማሪ ወጪ (ታማኝ ንጽጽር)
በዚህ workstation ላይ `npm run bench:routing-events` (100k ድግግሞሾች፤ sub-µs ops
በእያንዳንዱ op ያሉ percentiles ከ`performance.now()` timer resolution በታች
ስለሆኑ እንደ aggregate µs/op ተለክተዋል)፦
| ሁኔታ | µs/op | ops/s |
| --------------------------------- | ------ | ------ |
| baseline (scoring ብቻ) | ~0.045 | ~22 M |
| baseline + RoutingEvent (2 sinks) | ~0.168 | ~5.9 M |
| baseline + event + OTel enqueue | ~0.163 | ~6.1 M |
| concurrent (8 interleaved bursts) | ~0.18 | — |
ከbaseline scoring በላይ ያለው የevent-dispatch ልዩነት ~0.12 µs/request ነው፤ OTel sink
ወደ ወረፋ የሚያስገባው ብቻ ሲሆን (O(1) buffer push)፣ ሊለካ የሚችል ምንም ነገር
አይጨምርም። እነዚህ ቁጥሮች ለማሽኑ የተለዩ እና አንጻራዊ ናቸው — የproduction
ዋስትና አይደሉም። የv1 "~0.2 µs" ቁጥር ድምር ግምት ነበር፤ ይህ methodology
የscoring baselineን ከevent-dispatch ወጪ ይለያል።
## 3. የጥራት ምልክት (በግብረመልስ የሚመራ የprovider ሁኔታ)
ፋይሎች፦ `open-sse/services/routing/quality.ts`
v2 **የአሠራር** ጥራትን ከ**ትርጉማዊ** ጥራት ይለያል፦
- **የአሠራር** — ከrouting hot path የሚመነጭ (HTTP 4xx/5xx፣ የconnection
ውድቀቶች፣ 429s፣ malformed responses፣ የstream መቋረጦች፣ `finish_reason=length`፣
ዜሮ-output ስኬቶች፣ latency/TTFT EWMA)። 200 እንደ ትርጉማዊ ጥራት
**አይቆጠርም**።
- **ትርጉማዊ** — የተፈጠረው ውጤት ትክክለኛ እሴት። የሚፈጠረው
በevaluator በኩል `setSemanticQuality()`ን በመጠቀም **ብቻ** ነው። አንድ
evaluator እስኪያቀርበው ድረስ `null` ሆኖ ይቆያል፣ እና ወደ operational score
ፈጽሞ አይገባም።
የእያንዳንዱ (provider, model) ሁኔታ (EWMA + የተገደቡ counters)፦
- `successEwma` — የውጤት ስኬት EWMA (α=0.2)።
- `latencyEwma` / `ttftEwma` — የlatency EWMA (α=0.1)።
- `samples`, `anomalies`, `rateLimited`, `semantic`, `semanticConfidence`።
- `recencyMs` — model ለመጨረሻ ጊዜ ከታየበት ጊዜ አንስቶ ያለፈው ጊዜ።
### የእርግጠኝነት / sample ግንዛቤ
`confidence = clamp01(samples / 50)`፣ እና ወደ scorer የሚመለሰው score
ወደ ገለልተኛው መካከለኛ ነጥብ ይዋሃዳል፦
```
score = 0.5 + confidence * (operational - 0.5)
```
ውጤቶች (በtests የተረጋገጡ)፦
- አዲስ provider (0 samples) **0.5** ያስመዘግባል — ያለአግባብ አይቀጣም፣ ነገር
ግን በሺዎች የሚቆጠሩ ጠንካራ ምልከታዎች ያሉትን provider ማሸነፍ አይችልም።
- 7 እድለኛ ስኬቶች ያሉት provider ወደ 0.5 ይሳባል (በተስፈኛ
initialization ምክንያት ፈጽሞ የበላይ አይሆንም)።
- 50+ samples ያሉት provider ወደ እውነተኛው operational score ይቀርባል።
- መበላሸት እና ማገገም ቀስ በቀስ ናቸው (EWMA)፣ እና አንድ የተነጠለ ውድቀት
ጤናማ providerን አያወድም።
`ProviderQuality` `{ operational, semantic, confidence, samples, anomalies,
rateLimited, successEwma, latencyEwmaMs, ttftEwmaMs, recencyMs }`ን ያቀርባል።
ይህ እንደ `quality` scoring factor ሆኖ auto-combo scorerን ይመግባል፦
- `ScoringFactors.quality` / `ScoringWeights.quality` በ
`open-sse/services/autoCombo/scoring.ts` ውስጥ።
- `DEFAULT_WEIGHTS`፦ `health` 0.1905 → 0.1605፣ `quality` 0.03። ድምሩ 1.0 ሆኖ
ይቆያል።
- `buildAutoCandidates` `candidate.quality`ን ከtracker ይሞላል፤ ውሂብ የሌላቸው
candidates በነባሪ ገለልተኛውን **0.5** ይወስዳሉ (አዲስ candidate አይጠናከርምም
አይቀጣምም)።
ዝግ ዑደቱ፦
```
RoutingEvent → QualityTracker → getQualityScore → auto-combo quality factor
↑ │
└────── የጥያቄ ውጤት (handleChatCore) ←──────────────┘
```
### ጠንካራ ማግለል እና ለስላሳ ቅጣት
የጥራት ምልክቱ **ለስላሳ ተለዋዋጭ ምርጫ** ብቻ ነው። ጠንካራ ማግለል
በነባሩ resilience stack ይቆያል፦ circuit breaker OPEN፣ quota ያለቀ፣
auth failure፣ model lockout — ከእነዚህ አንዳቸውም በquality score አይነኩም።
quality score ለጊዜው የቀነሰበት provider ቅድሚያው ይቀነሳል እንጂ
ፈጽሞ hard-disabled አይደረግም።
## 3b. መደበኛ የዥረት ጊዜ መለኪያ (TTFT / ITL)
ፋይሎች፦ `open-sse/utils/streamTiming.ts`
`createStreamTiming()` ለዥረት መንገዱ ብቸኛው የመለኪያ ማያያዣ ሲሆን፣
በ`createSSEStream` (`open-sse/utils/stream.ts`) ውስጥ ተገናኝቷል፦
- `markByte()` — የመጀመሪያው ከላይኛው ምንጭ የመጣ ቁራጭ ደረሰ።
- `markForward()` — ወደ ደንበኛው የተላለፈ የመጀመሪያ ቁራጭ (ለTTFT ጥቅም ላይ የሚውል)።
- `markInterrupted()` — በንጹሕ ሁኔታ ከመጠናቀቁ በፊት የዥረት ጊዜ ማለፍ/ማቋረጥ/ስህተት።
- `ttft()` = የመጀመሪያው የተላለፈ የSSE ቁራጭ መዘግየት። **ይህ የቶከን ደረጃ TTFT አይደለም** —
አንድ የSSE ቁራጭ ዜሮ/አንድ/ብዙ ቶከኖችን ሊይዝ ይችላል። በትክክል ተመዝግቧል።
- `avgItlMs()` = አማካይ የቁራጮች መካከል ክፍተት (ለITL የቁራጭ መዘግየት ግምታዊ መለኪያ)።
TTFT/ITL/የመቋረጥ መረጃ ወደ `RoutingEvent` (`ttftMs`, `itlMs`) ይገባል፣ እንዲሁም
በOTel sink እንደ GenAI/OmniRoute span ባህሪያት ይላካል።
## 4. OpenTelemetry / GenAI ታዛቢነት
ፋይሎች፦ `open-sse/services/routing/otel.ts`
- ከጥገኝነት ነጻ የOTLP/HTTP JSON ላኪ (global `fetch`ን ይጠቀማል፤
`@opentelemetry/*` SDK አይጠቀምም)።
- Spans የGenAI ትርጉማዊ ስምምነቶችን (`gen_ai.provider.name`,
`gen_ai.request.model`, `gen_ai.usage.input_tokens/output_tokens`,
`gen_ai.completion.finish_reason`, `gen_ai.system`) እና የOmniRoute ማዘዋወሪያ
ባህሪያትን (ውጤት፣ ሁኔታ፣ ttft፣ ድጋሚ ሙከራዎች፣ ተተኪ) ይከተላሉ።
- `record()` ወደ ውስን ቋት ብቻ ያሰልፋል (O(1))፤ የጀርባ ጊዜ ቆጣሪ
`POST {endpoint}/v1/traces`ን በመጠቀም ያለመመሳሰል ሁኔታ ይልካል። ከአቅም በላይ ጫና ሲኖር
በጣም የቆዩ ክስተቶች ይጣላሉ (`dropped` ቆጣሪ) — በውሂብ
መስመሩ ላይ ፈጽሞ የኋላ ግፊት አይፈጠርም።
- **ካልተዋቀረ የተሰናከለ ነው።** `OMNIROUTE_OTEL_ENDPOINT` (ወይም
`OTEL_EXPORTER_OTLP_ENDPOINT`) መዋቀር አለበት፤ ካልሆነ sink አይመዘገብም
እና ምንም የOTel ኮድ አይሠራም።
## 5. ሊብራራ የሚችልነት
- `GET /v1/explain/routing` የቅርብ ጊዜ `RoutingEvent`sን (እውነተኛዎቹን
ውሳኔዎች፣ አዲሱን በቅድሚያ) እና የእያንዳንዱ አቅራቢ/ሞዴል የጥራት ቅጽበታዊ ገጽታን ይመልሳል።
- ማረጋገጫው `/v1/combos`ን ይከተላል (Bearer API key ወይም dashboard session፤
`REQUIRE_API_KEY=false` በሆነባቸው የአንድ ተጠቃሚ አካባቢያዊ ማሰማሪያዎች ላይ ስም-አልባ)።
- የcombo ደረጃ የእያንዳንዱ ጥሪ መከታተያዎች አሁንም ባለው
`decisionTrace.ts` (header `X-OmniRoute-Combo-Trace`) በኩል ይገኛሉ።
- ደህንነት፦ ክስተቶች የሚይዙት የማዘዋወሪያ ሜታዳታን ብቻ ነው፤ prompts/bodies/credentialsን ፈጽሞ አይይዙም።
## 6. የግምገማ መስመር ውህደት (ለFuture AGI ዝግጁነት)
OmniRoute Future AGIን (ወይም ማንኛውንም evaluator) እንደ **ሊሆን የሚችል
የብልህነት/ግምገማ backend እንጂ እንደ ጥገኝነት አይመለከተውም**። የማያያዣ ነጥቦቹ፦
- `RoutingEventSink` ክስተቶችን ያለመመሳሰል ሁኔታ ወደ evaluator ሊያስተላልፍ ይችላል።
- `MemoryRoutingEventStore` + የጥራት ቅጽበታዊ ገጽታ evaluatorን ጥሬውን
የውሳኔ ዥረት ይሰጡታል።
- ወደፊት የሚኖር `Evaluator` (ወሳኝ፣ አካባቢያዊ ዳኛ፣ HTTP፣ WASM) ክስተቶችን/መከታተያዎችን
ይጠቀማል እና ወደዚያው `getQualityScore`/የጥራት-ምክንያት መንገድ
የሚገባ `QualityScore` ይመልሳል።
- አሁን ያለው በeval የሚመራ ማዘዋወር (`open-sse/services/evalRouting.ts`) ሲነቃ
የcombo ዒላማዎችን በ`eval_runs` የማለፍ መጠኖች መሠረት አስቀድሞ እንደገና ያደራጃል።
ምንም ግምገማ በጥያቄው መንገድ ላይ በተመሳሳይ ጊዜ አይሠራም፣ እና gateway ያለ evaluator
ሙሉ በሙሉ ይሠራል።
## 7. የመጨረሻ የሥነ ሕንፃ ግምገማ
1. **በተመሳሳይ ጊዜ በሚሠራው ወሳኝ መንገድ ላይ ምን ቀርቷል?** ማዘዋወር/ነጥብ መስጠት፣ የguardrail
ቅድመ-ምርመራዎች፣ የcache ፍለጋ እና አንድ `emitRoutingEvent` ወደ
ውስጠ-ማህደረ ትውስታ sinks የሚደረግ ማከፋፈል (ከመሠረታዊ ነጥብ አሰጣጥ በላይ ~0.12 µs)።
2. **ወደ ያለመመሳሰል ሂደት ምን ተዛወረ?** OTel export (timer + fetch)፣
`call_logs`/የአጠቃቀም ማከማቻ፣ semantic-cache ጽሑፎች፤ ጥራት በውስጠ-ማህደረ ትውስታ
የሚቀመጥ እና O(1) ነው (ያለመመሳሰል ሂደት አያስፈልገውም)።
3. **የማዘዋወሪያ ውጤት እንዴት ግብረመልስ ይሆናል?** `handleChatCore`
`RoutingEvent`ን ያወጣል → `QualityTracker` የEWMA ሁኔታን ያዘምናል → `getQualityScore`
ለauto-combo `quality` ምክንያት ግብዓት ይሆናል።
4. **ጥራት በወደፊት ማዘዋወር ላይ እንዴት ተጽዕኖ ያሳድራል?** ዝቅተኛ የጥራት ነጥብ
በ`scoreAutoTargets` ውስጥ የዚያን አቅራቢ/ሞዴል ክብደት የተሰጠውን ነጥብ ይቀንሳል፤ ስለዚህ ጥራታቸው የቀነሰ
ሞዴሎች ቀስ በቀስ ቅድሚያ ማግኘታቸው ይቀንሳል፣ EWMAቸው ሲሻሻልም ያገግማሉ።
5. **Future AGI ጥገኝነት ሳይሆን እንዴት ሊዋሃድ ይችላል?** በ
`RoutingEventSink` interface / ወደፊት በሚኖር `Evaluator` adapter በኩል — በቋሚነት የተጻፈ
ጥገኝነት የለም።
6. **evaluator በማይገኝበት ጊዜ ምን ይከሰታል?** ማዘዋወሩ አይነካም፤
የታየ ምልክት ለሌላቸው ሞዴሎች ጥራት ወደ ገለልተኛ ነጥብ (1.0) ይመለሳል።
7. **telemetry በማይገኝበት ጊዜ ምን ይከሰታል?** OTel sink በቀላሉ
አይመዘገብም፤ የተቀረው የማዘዋወሪያ ንብርብር ሳይለወጥ ይሠራል።
8. **ከአቅም በላይ ጫና ሲኖር ምን ይከሰታል?** የOTel ቋት በጣም የቆዩ ክስተቶችን ይጥላል፤ ጥራት
እና ring buffer በአወቃቀራቸው የተወሰኑ ናቸው፤ የኋላ ግፊት የለም።
9. **ከጥራት መቀነስ በኋላ የአቅራቢው ሁኔታ እንዴት ያገግማል?** ስኬቶች
እየተከማቹ ሲሄዱ EWMA እንደገና ይጣጣማል፤ warmup አዲስ ሞዴሎችን ገለልተኛ ያደርጋል፤ circuit breaker
በተናጥል በHALF_OPEN ምርመራዎች ያገግማል።
10. **ከታቀዱት ባህሪያት ሆን ተብሎ ያልተተገበረው የትኛው ነው፣ ለምንስ?**
- Shadow traffic / experiments — አስቀድሞ ተተግብሯል
(`combo/shadowRouting.ts`)፤ እንደገና አልተገነባም።
- Guardrails — አስቀድሞ ተተግብረዋል (`src/lib/guardrails/`)፤ አልተደገሙም።
- Semantic cache — አስቀድሞ ተተግብሯል (`src/lib/semanticCache.ts`)፤
አልተደገመም።
- ሙሉ የexperiment-management platform፣ dataset tooling፣ prompt-optimization
platform፣ vector DB ወይም አስገዳጅ ውጫዊ የOTel መሠረተ ልማት — ለቀላል የውሂብ መስመር
ከወሰን ውጭ ናቸው።
- የRust `RoutingEvent` struct — የውሂብ መስመሩ TypeScript ነው፤ የTS type
የተስማማ አቻው ነው።
## 8. የውቅር ማጣቀሻ
| ተለዋዋጭ | ነባሪ | ተፅዕኖ |
| ----------------------------- | ----------- | ------------------------------------------------------------- |
| `OMNIROUTE_OTEL_ENDPOINT` | አልተዋቀረም | ሲዋቀር የOTLP/HTTP ዱካዎች ላኪን ያነቃል (ለምሳሌ `http://collector:4318`)። |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | አልተዋቀረም | ለOTLP መጨረሻ ነጥብ ተተኪ ተለዋጭ ስም። |
| `OTEL_SERVICE_NAME` | `omniroute` | የ`service.name` ሀብት ባህሪ። |
## 9. ሙከራዎች
- `tests/unit/routing-events.test.ts` — የክስተት ደረጃ ማስተካከያ፣ የሁኔታ
ምደባ፣ የተገደበ የቀለበት ቋት፣ የመቀበያ ነጥብ ስርጭት + ማግለል።
- `tests/unit/routing-quality.test.ts` — የEWMA ማሟሟቂያ፣ ከውድቀት/ስኬት ማገገም፣
የአለመደበኛነት ቅጣቶች፣ የ429 ጊዜያዊ አያያዝ፣ ቅጽበታዊ ገጽታ፣ ዳግም ማስጀመር።
- `tests/unit/routing-scoring-quality.test.ts` — የክብደት ትክክለኛነት፣ ገለልተኛ
ነባሪ፣ የጥራት ምክንያት ደረጃ አሰጣጥ።
- `tests/unit/routing-otel.test.ts` — የማንቃት መግቢያ ቁጥጥር፣ የGenAI ስፋት ውሂብ፣ አልተመሳሰለም
ማፍሰስ፣ በከባድ ጭነት ጊዜ መጣል።
- `tests/unit/routing-events-concurrency.test.ts` — በሺዎች የሚቆጠሩ ክስተቶች፣ የቀለበት
ቋት ገደብ፣ ስህተት የሚያስነሳ የመቀበያ ነጥብ ማግለል፣ የተጠላለፉ አልተመሳሰሉ ድንገተኛ ፍሰቶች፣
በማስገባት ወቅት ዳግም ማስጀመር።
- `tests/unit/routing-adaptive-e2e.test.ts` — በእውነተኛው
`scoreAutoTargets` ነጥብ ሰጪ በኩል የሚካሄድ ወጥ የጫፍ-እስከ-ጫፍ ዑደት፦ ጤናማ → መበላሸት → ማገገም → ጊዜያዊ መዛባት፣ በተጨማሪም
የመጀመሪያ ማስነሻ እና የዕድለኛ-ቀዝቃዛ-አቅራቢ ሁኔታዎች።
- `tests/unit/stream-timing.test.ts` — TTFT (መጀመሪያ የተላለፈ ቁራጭ)፣ ITL፣
የመጀመሪያ ባይት ከመጀመሪያ ማስተላለፍ ጋር ሲነጻጸር፣ መቋረጥ፣ የተበላሸ/ባዶ ቁራጭ ደህንነት።
## 10. ቀድሞ የነበሩ ችግሮች ሁኔታ (ደረጃ 18)
| ችግር | ሁኔታ | ማስታወሻዎች |
| ------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| የ`omniglyph` ወደ ውጭ መላክ አለመጣጣም | **ተስተካክሏል (የአካባቢ)** | `node_modules` ከ`package-lock.json` ጋር አልተመሳሰለም ነበር (የተጫነው 1.3.1 ሲሆን የተቆለፈው 1.4.0 ነበር)። `npm install omniglyph@1.4.0` ማስኬድ የተቆለፈውን ስሪት መልሷል፤ የዓይነት ስህተቶች ወደ 0 ወርደዋል። መግለጫ ፋይሎች አልተቀየሩም። |
| ጊዜ ያለፈባቸው የ`getKnownContextOverflow` ሙከራዎች | **የታወቀ — አልተስተካከለም** | `combo-context-overflow-compression-probe.test.ts` በ`open-sse/services/combo.ts` ውስጥ ከእንግዲህ የሌለ ፈንክሽን ያስመጣል (የሚጠቅሱት አስተያየቶች ብቻ ናቸው)። ማስተካከሉ ዳግም መተግበርን ወይም እነዚያን ሙከራዎች እንደገና መጻፍን ይጠይቃል — ተዛማጅነት የሌለው የአርክቴክቸር ለውጥ። |
| የ`combo-runtime-unit-concurrency.test.ts` DB ማግለል | **የታወቀ — አልተስተካከለም** | በቀጥታ ሲሄድ የሙከራ ማዕቀፉ የSQLite ማግለል ማረጋገጫ ይወድቃል፤ በመሠረታዊው ቅርንጫፍ ላይም በተመሳሳይ መንገድ ይወድቃል። |
| የi18n `llm.txt` ልዩነት | **የታወቀ — አልተስተካከለም** | `docs/i18n/*/llm.txt` ከስር ማውጫው ፋይል ይለያሉ፤ ቀድሞ የነበረ ሲሆን ከመመዝገብ በፊት ያለውን የሰነዶች-ማመሳሰል መግቢያ ይከለክላል። |
የአካባቢ እና የኮድ ችግሮች ተለያይተው ይቀመጣሉ፤ ምንም ያልተዛመዱ ውድቀቶች
ከተቀየሩ የሙከራ ማጣሪያዎች ጀርባ አይደበቁም።

2
docs/i18n/am/docs/architecture/ARCHITECTURE.md
View File

@@ -4,7 +4,7 @@
---
🌐 **ቋንቋዎች:** 🇺🇸 [እንግሊዝኛ](./ARCHITECTURE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/architecture/ARCHITECTURE.md) | 🇸🇦 [العربية](../i18n/ar/docs/architecture/ARCHITECTURE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/architecture/ARCHITECTURE.md) | 🇧🇬 [Български](../i18n/bg/docs/architecture/ARCHITECTURE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/architecture/ARCHITECTURE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/architecture/ARCHITECTURE.md) | 🇩🇰 [Dansk](../i18n/da/docs/architecture/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/architecture/ARCHITECTURE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/architecture/ARCHITECTURE.md) | 🇪🇸 [Español](../i18n/es/docs/architecture/ARCHITECTURE.md) | 🇪🇪 [Eesti](../i18n/et/docs/architecture/ARCHITECTURE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/architecture/ARCHITECTURE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/architecture/ARCHITECTURE.md) | 🇫🇷 [Français](../i18n/fr/docs/architecture/ARCHITECTURE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/architecture/ARCHITECTURE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/architecture/ARCHITECTURE.md) | 🇮🇱 [עברית](../i18n/he/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/architecture/ARCHITECTURE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/architecture/ARCHITECTURE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/architecture/ARCHITECTURE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/architecture/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/architecture/ARCHITECTURE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/architecture/ARCHITECTURE.md) | 🇮🇹 [Italiano](../i18n/it/docs/architecture/ARCHITECTURE.md) | 🇯🇵 [日本語](../i18n/ja/docs/architecture/ARCHITECTURE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/architecture/ARCHITECTURE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/architecture/ARCHITECTURE.md) | 🇰🇷 [한국어](../i18n/ko/docs/architecture/ARCHITECTURE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/architecture/ARCHITECTURE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/architecture/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/architecture/ARCHITECTURE.md) | 🇲🇹 [Malti](../i18n/mt/docs/architecture/ARCHITECTURE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/architecture/ARCHITECTURE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/architecture/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/architecture/ARCHITECTURE.md) | 🇳🇴 [Norsk](../i18n/no/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/architecture/ARCHITECTURE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/architecture/ARCHITECTURE.md) | 🇵🇱 [Polski](../i18n/pl/docs/architecture/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/architecture/ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/architecture/ARCHITECTURE.md) | 🇷🇴 [Română](../i18n/ro/docs/architecture/ARCHITECTURE.md) | 🇷🇺 [Русский](../i18n/ru/docs/architecture/ARCHITECTURE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/architecture/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/architecture/ARCHITECTURE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/architecture/ARCHITECTURE.md) | 🇷🇸 [Српски](../i18n/sr/docs/architecture/ARCHITECTURE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/architecture/ARCHITECTURE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/architecture/ARCHITECTURE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/architecture/ARCHITECTURE.md) | 🇹🇭 [ไทย](../i18n/th/docs/architecture/ARCHITECTURE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/architecture/ARCHITECTURE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/architecture/ARCHITECTURE.md) | 🇵🇰 [اردو](../i18n/ur/docs/architecture/ARCHITECTURE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/architecture/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/architecture/ARCHITECTURE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/architecture/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/architecture/ARCHITECTURE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/architecture/ARCHITECTURE.md)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ARCHITECTURE.md) · 🇦🇿 [az](../../../az/docs/architecture/ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/architecture/ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/architecture/ARCHITECTURE.md) · 🇬🇷 [el](../../../el/docs/architecture/ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/architecture/ARCHITECTURE.md) · 🇪🇪 [et](../../../et/docs/architecture/ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ARCHITECTURE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ARCHITECTURE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ARCHITECTURE.md) · 🇭🇺 [hu](../../../hu/docs/architecture/ARCHITECTURE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/architecture/ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ARCHITECTURE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ARCHITECTURE.md) · 🇰🇭 [km](../../../km/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ARCHITECTURE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ARCHITECTURE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ARCHITECTURE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ARCHITECTURE.md) · 🇲🇲 [my](../../../my/docs/architecture/ARCHITECTURE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [or](../../../or/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ARCHITECTURE.md) · 🇱🇰 [si](../../../si/docs/architecture/ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ARCHITECTURE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ARCHITECTURE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/architecture/ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/architecture/ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ARCHITECTURE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ARCHITECTURE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ARCHITECTURE.md)
_መጨረሻ የተዘመነው: 2026-06-28_

273
docs/i18n/am/docs/architecture/AUTHZ_GUIDE.md Normal file
View File

@@ -0,0 +1,273 @@
# Authorization Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/AUTHZ_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/AUTHZ_GUIDE.md) · 🇦🇿 [az](../../../az/docs/architecture/AUTHZ_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/AUTHZ_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/AUTHZ_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/AUTHZ_GUIDE.md) · 🇩🇰 [da](../../../da/docs/architecture/AUTHZ_GUIDE.md) · 🇩🇪 [de](../../../de/docs/architecture/AUTHZ_GUIDE.md) · 🇬🇷 [el](../../../el/docs/architecture/AUTHZ_GUIDE.md) · 🇪🇸 [es](../../../es/docs/architecture/AUTHZ_GUIDE.md) · 🇪🇪 [et](../../../et/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/AUTHZ_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/AUTHZ_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/AUTHZ_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇱 [he](../../../he/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/AUTHZ_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/AUTHZ_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/architecture/AUTHZ_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇩 [id](../../../id/docs/architecture/AUTHZ_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇹 [it](../../../it/docs/architecture/AUTHZ_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/AUTHZ_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/AUTHZ_GUIDE.md) · 🇰🇭 [km](../../../km/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/AUTHZ_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/AUTHZ_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/AUTHZ_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/AUTHZ_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/AUTHZ_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/AUTHZ_GUIDE.md) · 🇲🇲 [my](../../../my/docs/architecture/AUTHZ_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/AUTHZ_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/AUTHZ_GUIDE.md) · 🇳🇴 [no](../../../no/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [or](../../../or/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/AUTHZ_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/AUTHZ_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/AUTHZ_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/AUTHZ_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/AUTHZ_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/AUTHZ_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/AUTHZ_GUIDE.md) · 🇱🇰 [si](../../../si/docs/architecture/AUTHZ_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/AUTHZ_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/AUTHZ_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/AUTHZ_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/AUTHZ_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/AUTHZ_GUIDE.md) · 🇮🇳 [te](../../../te/docs/architecture/AUTHZ_GUIDE.md) · 🇹🇭 [th](../../../th/docs/architecture/AUTHZ_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/AUTHZ_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/AUTHZ_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/AUTHZ_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/AUTHZ_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/AUTHZ_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/AUTHZ_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/AUTHZ_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/AUTHZ_GUIDE.md)
---
> **ዋና የእውነት ምንጭ:** `src/server/authz/`, `src/shared/constants/publicApiRoutes.ts`, `src/lib/api/requireManagementAuth.ts`, `src/shared/utils/apiAuth.ts`
> **ለመጨረሻ ጊዜ የተዘመነው:** 2026-06-28 — v3.8.40
OmniRoute እያንዳንዱን የAPI ጥያቄ የሚቆጣጠር፣ መስመርን የሚያውቅ የፈቃድ መስጫ ቧንቧ መስመር አለው። ምደባው **ቆራጥ** እና **በስህተት ጊዜ ዝግ** ነው — ሊመደብ የማይችል ማንኛውም ነገር `MANAGEMENT` ሆኖ ያበቃል፣ እንዲሁም ክፍለ-ጊዜ ወይም የአስተዳደር ደረጃ ያለው ቶከን ይጠይቃል። ይህ ገጽ መስመሮችን ለሚንከባከቡ ወይም አዳዲስ መዳረሻዎችን ለሚነድፉ መሐንዲሶች ሞዴሉን ያብራራል።
![የAuthZ ቧንቧ መስመር (3 የመስመር ክፍሎች + የፖሊሲ ግምገማ)](../diagrams/exported/authz-pipeline.svg)
> ምንጭ፦ [diagrams/authz-pipeline.mmd](../diagrams/authz-pipeline.mmd)
## ሁለት የማረጋገጫ ሁነታዎች
### 1. API ቁልፍ (Bearer)
ከOpenAI/Anthropic/Gemini ጋር ተኳዃኝ ለሆኑ የደንበኛ APIዎች፣ እንዲሁም ቁልፉ `manage` ወሰን ሲኖረው ለጥቂት የአስተዳደር መስመሮች ይጠቅማል።
```
Authorization: Bearer <api-key>
```
በ`src/sse/services/auth.ts` ውስጥ ባሉት `isValidApiKey()` / `extractApiKey()` የሚረጋገጥ ሲሆን፣ በ`src/shared/utils/apiAuth.ts` በኩል እንደገና ወደ ውጭ ይላካል። አረጋጋጩ `OMNIROUTE_API_KEY` / `ROUTER_API_KEY` የአካባቢ ተለዋዋጮችንም እንደ ቋሚ የማሳለፊያ ቁልፎች ይቀበላል (ጉዳይ #1350)።
### 2. የዳሽቦርድ ክፍለ-ጊዜ (auth_token ኩኪ)
ለዳሽቦርድ ገጾች እና ለአስተዳዳሪ ክዋኔዎች።
```
Cookie: auth_token=<JWT signed with JWT_SECRET>
```
JWTው ሲረጋገጥ **እና** `authenticated: true` ሲይዝ ብቻ ኩኪው ክፍለ-ጊዜ ይሆናል
(`src/shared/utils/dashboardSessionToken.ts` → `verifyDashboardSessionToken`)። ኩኪውን
የሚጠቀም እያንዳንዱ አካል (የመስመር ጠባቂ፣ የauthz ቧንቧ መስመር ማደስ፣ የWebSocket መጨባበጥ፣ ቀጥታ
አገልጋይ፣ `/api/settings/require-login`፣ `/api/auth/status`) በዚያ አጋዥ በኩል ያልፋል።
በ`JWT_SECRET` የተፈረሙ ሌሎች JWTዎች አሉ — የCursor CLI ማሳለፊያው ለቁልፍ ባለቤቶች
`iss "omniroute" / aud "cursor-cli"` ቶከኖችን ይፈጥራል — እና እነዚህ በፍጹም ክፍለ-ጊዜዎች አይደሉም
(#13298)።
በ`src/shared/utils/apiAuth.ts` ውስጥ ባለው `isDashboardSessionAuthenticated()` ይረጋገጣል። ቧንቧ መስመሩ JWTው ከ30 ቀናት የዕድሜ ገደቡ ውስጥ ከ7 ቀናት ያነሰ ጊዜ ሲቀረው በራስ-ሰር ያድሰዋል።
አንዳንድ የአስተዳደር መስመሮች **ከሁለቱ አንዱን** ሁነታ ይቀበላሉ፦ ኩኪ ወይም የAPI ቁልፉ `manage` (ወይም `admin`) ወሰን ሲኖረው `Bearer <key>`። በv3.8 የታከለውን «በAPI ጥሪዎች ሊዋቀር የሚችል» የስራ ፍሰት የሚያስችለው ይህ ነው።
#### አማራጭ የOIDC መግቢያ በር (#6973)
የዳሽቦርድ አስተዳዳሪ መግቢያው ከነባሪው የይለፍ ቃል መግቢያ ጎን ለጎን **በምርጫ የሚነቃ** የOIDC (OpenID Connect) ፍሰትንም
ይደግፋል — የይለፍ ቃል መግቢያው በፍጹም አይወገድም፣ የሚደረገው መጨመር ብቻ
ነው፦
- `settings.oidcEnabled === true` ካልሆነ **እና** `oidcIssuer` /
`oidcClientId` / `oidcClientSecret` ሁሉም ካልተዋቀሩ በስተቀር የተሰናከለ ነው (Settings → Auth)።
ካልሆነ `GET /api/auth/oidc/login` `400` ይመልሳል።
- `GET /api/auth/oidc/login` `authorization_endpoint`ን ከአውጪው
`/.well-known/openid-configuration` ይፈልጋል (`<issuer>/authorize`ን
እንደ አማራጭ ይጠቀማል)፣ የመልሶ ማዞሪያ URIውን ከገቢው ጥያቄ
(`x-forwarded-proto`ን የሚያውቅ) ይገነባል፣ እና በ`httpOnly` `oidc_state` ኩኪ ውስጥ
በተከማቸ የዘፈቀደ `state` ወደ IdPው መልሶ ያዞራል።
- `GET /api/auth/oidc/callback` `state`ን ያረጋግጣል፣ የፈቃድ
ኮዱን ይለዋወጣል፣ እና የID ቶከኑን ፊርማ በአውጪው JWKS
(የ`jose` `createRemoteJWKSet`፣ በእያንዳንዱ JWKS URI የሚሸጎጥ) ከ`issuer`/`audience`
ማረጋገጫዎች ጋር ያረጋግጣል። አማራጭ የ`oidcAllowedSubjects` የተፈቀዱ ዝርዝር ከቶከኑ
`sub` ይገባኛል ወይም ከ`email` ይገባኛል ጋር ያዛምዳል — የኢሜይል ይገባኛል የሚከበረው
`email_verified === true` ሲሆን ብቻ ነው፤ ስለዚህ በIdPው ላይ ያልተረጋገጠ ኢሜይል በፍጹም
በበሩ ማለፍ አይችልም።
- ሲሳካ፣ የይለፍ ቃል መግቢያው የሚያወጣውን **በትክክል ተመሳሳይ** የ30 ቀናት `auth_token` JWT
(`src/app/api/auth/login/route.ts`) ይፈጥራል፤ በመሆኑም የተቀረው
የዳሽቦርድ ክፍለ-ጊዜ ቧንቧ መስመር (ራስ-ሰር ማደስ፣ የኩኪ ጠቋሚዎች) ሳይለወጥ ይቆያል —
OIDC የሚተካው ኩኪው የሚፈጠርበትን መንገድ ብቻ ነው፣ ኩኪው የሚሰጠውን ፈቃድ አይደለም።
## የRoute ክፍሎች
`src/server/authz/types.ts` ሦስት ክፍሎችን ይገልጻል፤ በወሳኝ ሁኔታ ሊመደብ የማይችል ማንኛውም route ወደ `MANAGEMENT` ይመለሳል።
| ክፍል | መግለጫ | የሚያስፈልግ ማረጋገጫ |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `PUBLIC` | በግልጽ ደህንነታቸው የተረጋገጠ routes — መግቢያ፣ መውጫ፣ ሁኔታ፣ ማስጀመሪያ፣ ጤና እና onboarding bootstrap። | ምንም |
| `CLIENT_API` | ሞዴል ማቅረቢያ endpoints — `/api/v1/*`፣ `/api/v1beta/*`፣ እንዲሁም aliases `/v1/*`፣ `/v1beta/*`፣ `/chat/completions`፣ `/responses`፣ `/models`፣ `/codex/*`። | ውጤታማው `REQUIRE_API_KEY` feature flag ሲነቃ Bearer key |
| `MANAGEMENT` | የDashboard ገጾች፣ ቅንብሮች፣ providers፣ keys፣ admin እና የምርመራ endpoints። | የDashboard session ወይም `manage` scope ያለው Bearer |
## Pipeline
```
የሚመጣ request → src/proxy.ts
→ runAuthzPipeline() በ src/server/authz/pipeline.ts
1. የታመኑ internal headersን አስወግድ (x-omniroute-auth-*, x-omniroute-route-class)
2. request id ፍጠር፣ routeን በ classifyRoute() መድብ
3. pathname == "/" ከሆነ → ወደ /dashboard redirect አድርግ
4. draining (graceful shutdown) ላይ ከሆነ እና /api/* ከሆነ → 503
5. GET ያልሆነ /api/* ከሆነ → checkBodySize() guardን ፈትሽ
6. OPTIONS ከሆነ → CORS preflight 204
7. options.enforce == false ከሆነ → ከroute-class headers ጋር እንዲያልፍ አድርግ
8. አለበለዚያ፦ POLICIES[routeClass].evaluate(ctx)
- allow → x-omniroute-auth-{kind,id,label,scopes} አክል → NextResponse.next()
- reject → የJSON ስህተት ከ correlation_id ጋር (የdashboard ገጾች → 302 /login)
```
የታመኑ internal headers (በ`src/server/authz/headers.ts` የተገለጹ) ከመመደባቸው በፊት **ከሚመጡ requests ይወገዳሉ** — clients አንድን subject ለማስመሰል `x-omniroute-auth-*`ን አስቀድመው መሙላት አይችሉም።
### የPolicy ውሎች
እያንዳንዱ የroute ክፍል በ`src/server/authz/policies/` ውስጥ policy አለው፦
- **`publicPolicy`** (`policies/public.ts`) — ሁልጊዜ `allow({ kind: "anonymous", id: "anonymous" })` ይመልሳል።
- **`clientApiPolicy`** (`policies/clientApi.ts`) — Bearerን አውጥቶ በ`validateApiKey()` ያረጋግጣል። ወደ anonymous የሚያልፈው ውጤታማው `REQUIRE_API_KEY` feature flag ሲሰናከል ብቻ ነው። ውጤታማው flag በ`isRequireApiKeyEnabled()` (`DB feature flag override > process.env.REQUIRE_API_KEY > default`) በኩል ይወሰናል፤ በዚህም የDashboard Feature Flags እና environment variables `/api/v1/*`፣ `/api/v1beta/*` እና aliasesን በወጥነት ይቆጣጠራሉ፤ የresolver ውድቀቶች መዳረሻን ይዘጋሉ። በclient API routes ላይ የDashboard-session requestsን ይፈቅዳል (በdashboard model catalog የሚጠቀሙበትን `/api/v1/models` ጨምሮ)።
- **`managementPolicy`** (`policies/management.ts`) — የDashboard session፣ internal model-sync requests (`/api/providers/[name]/(sync-models|models)` ጋር የሚዛመዱ) ይቀበላል፣ ወይም `isAuthRequired()` false ከመለሰ ሙሉ በሙሉ ይዘለዋል። Bearer token ካለ ነገር ግን invalid ከሆነ 403 (`AUTH_001`)፣ አለበለዚያ 401 ይመልሳል። ከማንኛውም auth branch በፊት የroute-guard tiersን (LOCAL_ONLY / ALWAYS_PROTECTED) ያስገድዳል — [የRoute Guard Tiers](../security/ROUTE_GUARD_TIERS.md)ን ይመልከቱ። በ`LOCAL_ONLY_MANAGE_SCOPE_BYPASS_PREFIXES` ውስጥ ያሉ LOCAL_ONLY paths (በአሁኑ ጊዜ፦ `/api/mcp/`) Bearer keyው `manage` scopeን ከያዘ ከnon-loopback ላይ ሊደረስባቸው ይችላል፤ ሌሎች ሁሉም LOCAL_ONLY paths scope ምንም ይሁን ምን strict-loopback ሆነው ይቆያሉ።
የተሳካ policy `kind ∈ { client_api_key, dashboard_session, management_key, anonymous }` ያለውን `AuthSubject` ይመልሳል። Downstream handlers የauth logicን እንደገና ከማስኬድ ይልቅ በ`src/server/authz/assertAuth.ts` ውስጥ ባለው `assertAuth(request, "CLIENT_API")` በኩል ሊያነቡት ይችላሉ።
## የይፋዊ መስመሮች ዝርዝር
`src/shared/constants/publicApiRoutes.ts` ግልጽ የፈቃድ ዝርዝሩ ነው፦
ዝርዝሩ በ**ቅርጽ** የተከፈለ ሲሆን፣ ይህ ክፍፍል ለደህንነት ወሳኝ ነው (GHSA-74g9-q8f6-793h)፦ prefix በ`startsWith()` ስለሚዛመድ፣ ተመሳሳይ መሪ ቁምፊዎችን የሚጋራ እያንዳንዱን አጎራባች pathም ያዛምዳል።
`/api/usage/om-usage` እንደ prefix ሲጠቀም `/api/usage/om-usage<anything>`ን PUBLIC አድርጎ ምልክት አድርጎት ነበር፤ Next ደግሞ ይህንን ወደ `/api/usage/[connectionId]` ይፈታዋል — የራሱ auth የሌለው handler።
```ts
// እውነተኛ ንዑስ ዛፎች። እያንዳንዱ ግቤት በ"/" መጨረስ አለበት (በunit test የተረጋገጠ)።
PUBLIC_API_ROUTE_PREFIXES = [
"/api/auth/oidc/",
"/api/v1/", // በclassify ውስጥ እንደ CLIENT_API ይቆጠራል፣ እንደ "auth የማያስፈልገው ይፋዊ" አይደለም
"/api/oauth/",
"/api/codex/connect/",
"/api/telegram/",
"/api/cursor-cli/",
];
// በትክክል የሚዛመዱ ነጠላ መስመሮች (በመጨረሻ slash ያላቸውም ሆነ የሌላቸው)።
PUBLIC_API_ROUTES_EXACT = new Set([
"/api/auth/login",
"/api/auth/logout",
"/api/auth/status",
"/api/init",
"/api/sync/bundle",
"/api/cli/connect",
"/api/usage/om-usage",
"/api/skills/collect/chaos",
]);
// የCORS origin ማላላትንም የሚቀበሉ ለንባብ-ብቻ የሆኑ ነጠላ መስመሮች።
PUBLIC_READONLY_CORS_API_ROUTES = [
"/api/health/ping",
"/api/monitoring/health",
"/api/settings/require-login",
];
// የCORS ማላላት የሌለው ለንባብ-ብቻ የሆነ ነጠላ መስመር።
PUBLIC_READONLY_API_ROUTES_EXACT = new Set(["/api/health"]);
PUBLIC_READONLY_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
```
ለንባብ-ብቻ የሆኑ መስመሮች ይፋዊ የሚሆኑት **ለደህንነታቸው አስተማማኝ** methods ብቻ ነው። ማስታወሻ፦ `classifyRoute()` `/api/v1/*`ን እና `/api/v1beta/*`ን ከPUBLIC fall-through ያስወጣቸዋል — የBearer-key ፖሊሲው አሁንም እንዲተገበር እነዚህ ሁልጊዜ `CLIENT_API` ናቸው።
## አዲስ መስመር ማከል
### ንድፍ 1 — ይፋዊ የclient API endpoint (Bearer-auth)
በ`/api/v1/` እና `/api/v1beta/` ስር ያሉ መስመሮች በራስ-ሰር `CLIENT_API` ተብለው ይመደባሉ። middlewareው የBearer ማረጋገጫውን ያስገድዳል፤ route handlers ይህንን እንደገና ማከናወን አያስፈልጋቸውም፣ ነገር ግን ጠቃሚ ከሆነ subjectን ማንበብ ይችላሉ።
```typescript
// src/app/api/v1/your-route/route.ts
import { NextRequest, NextResponse } from "next/server";
import { assertAuth } from "@/server/authz/assertAuth";
export async function POST(req: NextRequest) {
const subject = assertAuth(req, "CLIENT_API");
// subject.kind === "client_api_key" | "anonymous" | "dashboard_session"
// ... የhandler አመክንዮ
}
```
### ንድፍ 2 — የአስተዳደር endpoint (session ወይም Bearer + manage)
ከ`src/lib/api/requireManagementAuth.ts` የሚገኘውን `requireManagementAuth()` ይጠቀሙ፦
```typescript
import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
export async function POST(request: Request) {
const rejection = await requireManagementAuth(request);
if (rejection) return rejection;
// ... የhandler አመክንዮ
}
```
`requireManagementAuth()` ሲሳካ `null`ን፣ ካልሆነ ደግሞ የJSON ስህተት `Response`ን ይመልሳል፦
- 401 `AUTH_001` "ማረጋገጫ ያስፈልጋል" — ምንም credentials የሉም
- 403 — ልክ ያልሆነ Bearer **ወይም** Bearer አለ፣ ነገር ግን keyው የ`manage` / `admin` scope የለውም
`hasManageScope(scopes)` ለ`"manage"` ወይም `"admin"` true ይመልሳል።
### ንድፍ 3 — ወደ ይፋዊ የፈቃድ ዝርዝሩ ማከል
setን በቅርጹ መሠረት ይምረጡ፣ በአመቺነት መሠረት አይደለም። አንድ መስመር ወደ `PUBLIC_API_ROUTES_EXACT` ይገባል (ወይም GET-only ከሆነ ወደ `PUBLIC_READONLY_CORS_API_ROUTES`)፤ ወደ `PUBLIC_API_ROUTE_PREFIXES` የሚገባው እውነተኛ ንዑስ ዛፍ ብቻ ነው፣ እና **በ`/` መጨረስ አለበት**። ነጠላ መስመርን በprefix ዝርዝሩ ውስጥ ማስቀመጥ፣ ተመሳሳይ መሪ ቁምፊዎችን የሚጋሩ ሁሉንም አጎራባች paths ይፋዊ ያደርጋል — ይህም በኋላ የሚታከሉ dynamic-segment siblingsን ይጨምራል (GHSA-74g9-q8f6-793h)። በ`tests/unit/public-api-routes.test.ts`፣ `tests/unit/authz/public-route-exact-match.test.ts` እና `tests/unit/authz/classify.test.ts` ያሉ unit testsን ያዘምኑ።
## የተደራሽነት ወሰኖች
የAPI ቁልፎች የ`scopes` ድርድር ይይዛሉ (እንደ JSON በ`api_keys.scopes` ውስጥ ይቀመጣል፤ `src/lib/db/apiKeys.ts`ን ይመልከቱ)።
### የአስተዳደር ወሰን
- `manage` / `admin` — ቁልፉ እንደ Bearer ሲላክ የአስተዳደር API መጨረሻ ነጥቦችን እንዲደርስ ፈቃድ ይሰጠዋል።
### MCP ወሰኖች (`src/shared/constants/mcpScopes.ts`)
እያንዳንዱ MCP መሣሪያ በ`MCP_TOOL_SCOPES` በኩል የተወሰኑ ወሰኖችን ይፈልጋል። ሙሉ ዝርዝሩ (`MCP_SCOPE_LIST`)፦
```
read:health, read:combos, write:combos, read:quota, read:usage,
read:models, execute:completions, execute:search, write:budget,
write:resilience, pricing:write, read:cache, write:cache,
read:compression, write:compression, read:proxies
```
በ`open-sse/mcp-server/server.ts` ውስጥ ያለው የወሰን ማስፈጸሚያ፣ `resolveCallerScopeContext()` ወሰኖችን ከMCP የማረጋገጫ መረጃ፣
ከጥያቄ ሜታዳታ ወይም ከ`OMNIROUTE_MCP_SCOPES` ከፈታ በኋላ የእያንዳንዱን መሣሪያ የወሰን ዝርዝር ወደ
`evaluateToolScopes()` ያስተላልፋል።
## ማረጋገጫ ያስፈልጋል መቀያየሪያ
በ`src/shared/utils/apiAuth.ts` ውስጥ ያለው `isAuthRequired()` ለአንድ ጥያቄ **ማንኛውም** ማረጋገጫ ተፈጻሚ መሆን አለበት ወይስ የለበትም ብሎ ይወስናል፦
- `settings.requireLogin === false` → ማረጋገጫ በዓለም አቀፍ ደረጃ ተሰናክሏል።
- ምንም የይለፍ ቃል ካልተዋቀረ **እና** የ`INITIAL_PASSWORD` የአካባቢ ተለዋዋጭ ከሌለ → የማስነሻ ሁነታ የመጀመሪያ ማዋቀሪያ አዋቂውን እና loopback ጥያቄዎችን ይፈቅዳል፤ ነገር ግን ለአውታረ መረብ የተጋለጡ ጥያቄዎች አሁንም የማረጋገጫ መረጃ ያስፈልጋቸዋል።
- ማንኛውም የDB ስህተት → መዳረሻውን ዘግቶ ያቆማል (በነባሪነት ደህንነቱ የተጠበቀ)።
የደንበኛ API ቁልፍ ማስፈጸሚያ በ`src/shared/utils/featureFlags.ts` ውስጥ ያለውን `isRequireApiKeyEnabled()` ይጠቀማል፤ `process.env.REQUIRE_API_KEY`ን በቀጥታ አያነብም። ይህ ለተሰማሩ ኢንስታንሶች አስፈላጊ ነው፦ በDashboard → Feature Flags ውስጥ `REQUIRE_API_KEY`ን መቀያየር የDB ተተኪ ቅንብርን ያከማቻል፣ እናም ወዲያውኑ `/v1/*`፣ `/v1beta/*`፣ `/models`፣ `/responses`፣ `/chat/completions`፣ `/codex/*` እና ይህን ረዳት የሚጋሩ ሌሎች የደንበኛ-API ማረጋገጫዎች ላይ ተጽዕኖ ያሳድራል። የባህሪ ምልክት ማከማቻው ሊነበብ ካልቻለ፣ የደንበኛ API ማረጋገጫ መዳረሻውን ዘግቶ ያቆማል እና ቁልፍ ይፈልጋል።
## ተኳሃኝነትን የሚያፈርስ ለውጥ — v3.8.0
የ`/api/v1/agents/tasks/*` እና `/api/resilience/model-cooldowns` መጨረሻ ነጥቦች **አሁን የአስተዳደር ማረጋገጫ ይፈልጋሉ** (commit `588a0333`)። ከዚህ በፊት የ`manage` ወሰን የሌለውን መደበኛ API ቁልፍ ይልኩ የነበሩ ደንበኞች `403` ይቀበላሉ። ፍልሰት፦ በAPI Keys dashboard ውስጥ ለቁልፉ የ`manage` ወሰንን ይስጡ፣ ወይም የገቡበትን dashboard ክፍለ ጊዜ ይጠቀሙ።
## የባህሪ ለውጥ — v3.8.2
`/api/mcp/*` (የርቀት MCP አገልጋዩ) አሁንም በነባሪ LOCAL_ONLY ነው፤ ሆኖም የ`Authorization: Bearer <api-key>` ራስጌው የ`manage` ወሰንን ሲይዝ አሁን loopback ያልሆኑ ጥያቄዎችን ይቀበላል። ይህ ልዩ ማስቀረት በ`src/server/authz/routeGuard.ts` ውስጥ ባለው `LOCAL_ONLY_MANAGE_SCOPE_BYPASS_PREFIXES` በኩል ለእያንዳንዱ ዱካ በግልጽ ሁኔታ የሚቆጣጠር ነው፤ የወንድም LOCAL_ONLY ቅድመ ቅጥያ `/api/cli-tools/runtime/*` ማናቸውንም ንዑስ ሂደቶች ሊያስነሳ ስለሚችል ሆን ተብሎ ሊታለፍ የማይችል ተደርጓል። loopback ካልሆነ ምንጭ ወደ `/api/mcp/*` የሚላኩ ስም-አልባ ጥያቄዎች `403 LOCAL_ONLY`ን መመለሳቸውን ይቀጥላሉ — ለማንኛውም አዲስ LOCAL_ONLY ዱካ ነባሪው ጥብቅ-loopback ሆኖ ይቀጥላል። [የRoute Guard ደረጃዎች](../security/ROUTE_GUARD_TIERS.md#manage-scope-carve-out)ን ይመልከቱ።
## ሙከራ
- የክፍል ሙከራዎች፦ `tests/unit/authz/` — `classify.test.ts`፣ `pipeline.test.ts`፣ `client-api-policy.test.ts`፣ `management-policy.test.ts`፣ `public-policy.test.ts`።
- የሕዝብ ፍቃድ ዝርዝር፦ `tests/unit/public-api-routes.test.ts`።
- ያተኮረ ሙከራን ያሂዱ፦ `node --import tsx/esm --test tests/unit/authz/classify.test.ts`።
## ማረም
ፓይፕላይኑ ሁልጊዜ ምላሾችን በሚከተሉት ራስጌዎች ያትማል፦
```
x-request-id: <correlation id, echoed in error bodies>
x-omniroute-route-class: PUBLIC | CLIENT_API | MANAGEMENT
```
ማንነት ለተረጋገጠባቸው ጥያቄዎች፣ ወደላይኛው አገልግሎት የሚላኩት (በhandler በኩል ያሉ) የጥያቄ ራስጌዎች የሚከተሉትንም ያካትታሉ፦
```
x-omniroute-auth-kind: client_api_key | dashboard_session | management_key | anonymous
x-omniroute-auth-id: key_<last-4> | "dashboard" | "anonymous"
x-omniroute-auth-label: (optional)
x-omniroute-auth-scopes: comma-separated list
```
በhandler ውስጥ `assertAuth(req, expectedClass)`ን ይጠቀሙ — middlewareው ከተዘለለ፣ `AUTHZ_NOT_INITIALIZED` ኮድ ያለውን `AuthzAssertionError` ይጥላል (ይህም በሙከራዎች ውስጥ የውቅር ወደኋላ መመለሶችን ለመለየት ጠቃሚ ነው)።
## ተጨማሪ ይመልከቱ
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — ለእያንዳንዱ endpoint የማንነት ማረጋገጫ ምልክት
- [COMPLIANCE.md](../security/COMPLIANCE.md) — ለማንነት ማረጋገጫ ክስተቶች የኦዲት መዝገብ
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — የMCP scope ማስፈጸሚያ ዝርዝሮች
- ምንጭ፦ `src/server/authz/`, `src/lib/api/requireManagementAuth.ts`

114
docs/i18n/am/docs/architecture/CODEBASE_DOCUMENTATION.md
View File

@@ -433,60 +433,60 @@ server/
---
## 4. `open-sse/` — የዥረት ሞተር የሥራ ቦታ
## 4. `open-sse/` — የስትሪሚንግ ሞተር የሥራ ቦታ
እንደ `@omniroute/open-sse` የሚታተም የተለየ npm የሥራ ቦታ። የጥያቄ
ሂደት፣ አስፈጻሚዎች፣ ተርጓሚዎች፣ አገልግሎቶች፣ ቀያሪው እና MCP አገልጋዩን ይይዛል።
እንደ `@omniroute/open-sse` የሚታተም የተለየ npm የሥራ ቦታ። የጥያቄ ሂደትን፣
አስፈጻሚዎችን፣ ተርጓሚዎችን፣ አገልግሎቶችን፣ ቀያሪውን እና MCP አገልጋዩን ይይዛል።
```
open-sse/
├── index.ts ይፋዊ ወደ ውጭ የሚቀርቡ ነገሮች
├── package.json የሥራ ቦታ ማኒፌስት
├── index.ts ይፋዊ ወደ ውጭ የሚላኩ አካላት
├── package.json የሥራ ቦታ መግለጫ
├── tsconfig.json
├── types.d.ts
├── config/ የአቅራቢ መዝገቦች፣ የራስጌ መገለጫዎች፣ ማንነት፣ …
├── handlers/ የጥያቄ አስተናጋጆች (ውይይት፣ ኢምቤዲንጎች፣ ድምፅ፣ ምስል፣ …)
├── executors/ 108 ለአቅራቢ-ተኮር የHTTP አስፈጻሚዎች
├── executors/ 108 ለአቅራቢ የተለዩ HTTP አስፈጻሚዎች
├── translator/ የቅርጸት ልወጣ (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/ Responses API ↔ Chat Completions የዥረት ቀያሪ
├── services/ 80+ የአገልግሎት ሞጁሎች (ጥምረቶች፣ አማራጭ መመለሻ፣ ኮታዎች፣ ማንነት፣ …)
├── utils/ የዥረት ረዳቶች፣ TLS ደንበኛ፣ AWS SigV4፣ የፕሮክሲ ሰርስሮ ማምጣት፣ …
├── transformer/ Responses API ↔ Chat Completions የስትሪም ቀያሪ
├── services/ 80+ የአገልግሎት ሞጁሎች (ጥምረቶች፣ ተተኪ፣ ኮታዎች፣ ማንነት፣ …)
├── utils/ የስትሪሚንግ ረዳቶች፣ TLS ደንበኛ፣ AWS SigV4፣ የፕሮክሲ ሰርስሮ ማምጣት፣ …
└── mcp-server/ MCP አገልጋይ (3 ማጓጓዣዎች፣ 33 ወሰኖች፣ 110 መሣሪያዎች)
```
### 4.1 `open-sse/handlers/`
| አስተናጋጅ | ዓላማ |
| ----------------------- | ------------------------------------------------------------- |
| `chatCore.ts` | ዋና የውይይት ቧንቧ መስመር (መሸጎጫ፣ የመጠን ገደብ፣ የጥምረት ማዘዋወር፣ ወደ አስፈጻሚ መላክ) |
| `responsesHandler.ts` | የOpenAI Responses API መግቢያ ነጥብ |
| `embeddings.ts` | ኢምቤዲንጎች |
| `imageGeneration.ts` | ምስል ማመንጨት |
| `audioSpeech.ts` | ጽሑፍን ወደ ንግግር መቀየር |
| `audioTranscription.ts` | ንግግርን ወደ ጽሑፍ መቀየር |
| `videoGeneration.ts` | ቪዲዮ ማመንጨት |
| `musicGeneration.ts` | ሙዚቃ ማመንጨት |
| `rerank.ts` | ደረጃን እንደገና ማስተካከል |
| `moderations.ts` | ይዘት ማስተካከያ |
| `search.ts` | የድር ፍለጋ |
| `sseParser.ts` | የSSE ክስተት ተንታኝ |
| `usageExtractor.ts` | ከላይኛው የውሂብ ዥረት የቶከን ብዛቶችን ማውጣት |
| `responseSanitizer.ts` | ለአቅራቢ-ተኮር የሆነ አላስፈላጊ መረጃን ማስወገድ |
| `responseTranslator.ts` | በአቅራቢው ምላሽ እና በትርጉም ንብርብሩ መካከል ያለ ማገናኛ |
| አስተናጋጅ | ዓላማ |
| ----------------------- | ----------------------------------------------------------- |
| `chatCore.ts` | ዋናው የውይይት ፓይፕላይን (መሸጎጫ፣ የፍጥነት ገደብ፣ የጥምረት ማዘዋወር፣ የአስፈጻሚ መላክ) |
| `responsesHandler.ts` | የOpenAI Responses API መግቢያ ነጥብ |
| `embeddings.ts` | ኢምቤዲንጎች |
| `imageGeneration.ts` | ምስል ማመንጨት |
| `audioSpeech.ts` | ጽሑፍን ወደ ንግግር መቀየር |
| `audioTranscription.ts` | ንግግርን ወደ ጽሑፍ መቀየር |
| `videoGeneration.ts` | ቪዲዮ ማመንጨት |
| `musicGeneration.ts` | ሙዚቃ ማመንጨት |
| `rerank.ts` | ዳግም ደረጃ መስጠት |
| `moderations.ts` | የይዘት ቁጥጥር |
| `search.ts` | የድር ፍለጋ |
| `sseParser.ts` | የSSE ክስተት ተንታኝ |
| `usageExtractor.ts` | ከላይኛው የስትሪም ፍሰቶች የቶከን ብዛቶችን ማውጣት |
| `responseSanitizer.ts` | ለአቅራቢ የተለዩ አላስፈላጊ መረጃዎችን ማስወገድ |
| `responseTranslator.ts` | በአቅራቢው ምላሽ እና በትርጉም ንብርብሩ መካከል ያለ ማገናኛ |
### 4.2 `open-sse/executors/`
108 የአቅራቢ አስፈጻሚዎች፣ እያንዳንዳቸው `BaseExecutor` (`base.ts`)ን የሚያስፋፉ፦
108 የአቅራቢ አስፈጻሚዎች፤ እያንዳንዳቸው `BaseExecutor` (`base.ts`)ን ያራዝማሉ፦
`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `devin-desktop`፣ በተጨማሪም `claudeIdentity.ts`
`pollinations`, `qoder`, `vertex`, `devin-desktop`፣ እንዲሁም `claudeIdentity.ts`
(የጋራ የማንነት ረዳት) እና `index.ts` (መዝገብ)።
> ማስታወሻ፦ እዚህ ያልተዘረዘሩ አቅራቢዎች ከOpenAI ጋር ተኳሃኙን አጠቃላይ
> አስፈጻሚ በመጠቀም በ`default.ts` ይስተናገዳሉ። ሙሉው የአቅራቢዎች ካታሎግ (355 አቅራቢዎች) በ
> `src/shared/constants/providers.ts` ውስጥ ይገኛል።
> ማስታወሻ፦ እዚህ ያልተዘረዘሩ አቅራቢዎች አጠቃላይ
> ከOpenAI ጋር ተኳሃኝ የሆነውን አስፈጻሚ በመጠቀም በ`default.ts` ይቀርባሉ። ሙሉው የአቅራቢዎች ካታሎግ (355 አቅራቢዎች)
> በ`src/shared/constants/providers.ts` ውስጥ ይገኛል።
### 4.3 `open-sse/translator/`
@@ -502,30 +502,30 @@ open-sse/
`openai-to-claude`.
- **9 ረዳቶች** (`translator/helpers/`)፦
`claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
`openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`፣ በተጨማሪም
`openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`፣ እንዲሁም
የረዳት ሙከራዎች።
- **የምስል ረዳቶች** (`translator/image/sizeMapper.ts`)።
- ከፍተኛ ደረጃ፦ `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`።
- ከፍተኛ ደረጃ፦ `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.
### 4.4 `open-sse/transformer/`
- `responsesTransformer.ts` — በ`TransformStream` ላይ የተመሠረተ Responses API ↔ Chat
Completions ቀያሪ (በ`responses/` መስመር ሁሉን-ያዥ የሚጠቀምበት)።
Completions ቀያሪ (በ`responses/` መስመር ሁሉን-አቀፍ መያዣ ጥቅም ላይ ይውላል)።
### 4.5 `open-sse/services/`
ዋና ዋና ነጥቦች (ሙሉው ዝርዝር በ`open-sse/services/` ሥር ይገኛል)፦
ዋና ዋና ክፍሎች (ሙሉው ዝርዝር በ`open-sse/services/` ስር ይገኛል)፦
| ጉዳይ | ፋይሎች |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| የCombo ማዘዋወር | `combo.ts` (19 ስልቶች)፣ `comboConfig.ts`፣ `comboMetrics.ts`፣ `comboManifestMetrics.ts`፣ `comboAgentMiddleware.ts` |
| ራስ-ሰር Combo ሞተር | `autoCombo/` — `engine.ts`፣ `scoring.ts`፣ `taskFitness.ts`፣ `virtualFactory.ts`፣ `modePacks.ts`፣ `autoPrefix.ts`፣ `persistence.ts`፣ `providerDiversity.ts`፣ `providerRegistryAccessor.ts`፣ `routerStrategy.ts`፣ `selfHealing.ts`፣ `index.ts` |
| የመቋቋም አቅም | `accountFallback.ts` (የማቀዝቀዣ ጊዜ + መቆለፍ)፣ `errorClassifier.ts`፣ `emergencyFallback.ts`፣ `rateLimitManager.ts`፣ `rateLimitSemaphore.ts`፣ `accountSemaphore.ts`፣ `accountSelector.ts` |
| የመቋቋም አቅም | `accountFallback.ts` (የማቀዝቀዣ ጊዜ + መቆለፍ)፣ `errorClassifier.ts`፣ `requestRejectedStreak.ts`፣ `emergencyFallback.ts`፣ `rateLimitManager.ts`፣ `rateLimitSemaphore.ts`፣ `accountSemaphore.ts`፣ `accountSelector.ts` |
| ኮታዎች | `quotaMonitor.ts`፣ `quotaPreflight.ts`፣ `bailianQuotaFetcher.ts`፣ `codexQuotaFetcher.ts`፣ `deepseekQuotaFetcher.ts`፣ `openrouterQuotaFetcher.ts`፣ `openrouterFreeWindow.ts`፣ `crofUsageFetcher.ts`፣ `antigravityCredits.ts` |
| መሸጎጫ | `reasoningCache.ts`፣ `searchCache.ts`፣ `signatureCache.ts`፣ `requestDedup.ts` |
| መሸጎጥ | `reasoningCache.ts`፣ `searchCache.ts`፣ `signatureCache.ts`፣ `requestDedup.ts` |
| የማዘዋወር ብልህነት | `intentClassifier.ts`፣ `taskAwareRouter.ts`፣ `backgroundTaskDetector.ts`፣ `volumeDetector.ts`፣ `wildcardRouter.ts`፣ `workflowFSM.ts`፣ `specificityDetector.ts`፣ `specificityRules.ts`፣ `specificityTypes.ts` |
| የሞዴል አያያዝ | `modelCapabilities.ts`፣ `modelDeprecation.ts`፣ `modelFamilyFallback.ts`፣ `modelStrip.ts`፣ `model.ts`፣ `provider.ts`፣ `providerRequestDefaults.ts`፣ `providerCostData.ts`፣ `payloadRules.ts` |
| መጭመቅ | `compression/` — የሙሉ የመጭመቂያ ሞተር ሽቦ አገናኘት |
| የሞዴል አስተዳደር | `modelCapabilities.ts`፣ `modelDeprecation.ts`፣ `modelFamilyFallback.ts`፣ `modelStrip.ts`፣ `model.ts`፣ `provider.ts`፣ `providerRequestDefaults.ts`፣ `providerCostData.ts`፣ `payloadRules.ts` |
| ማመቅ | `compression/` — የተሟላ የማመቂያ ሞተር ሽቦ-አገናኝ |
| ቶከን + ክፍለ-ጊዜ | `tokenRefresh.ts`፣ `sessionManager.ts`፣ `apiKeyRotator.ts`፣ `contextManager.ts`፣ `contextHandoff.ts`፣ `systemPrompt.ts`፣ `roleNormalizer.ts`፣ `responsesInputSanitizer.ts`፣ `toolSchemaSanitizer.ts`፣ `toolLimitDetector.ts`፣ `thinkingBudget.ts` |
| ደረጃ / ማኒፌስት | `tierResolver.ts`፣ `tierConfig.ts`፣ `tierDefaults.json`፣ `tierTypes.ts`፣ `manifestAdapter.ts` |
| IP / አውታረ መረብ | `ipFilter.ts`፣ `webSearchFallback.ts` |
@@ -534,43 +534,43 @@ open-sse/
### 4.6 `open-sse/mcp-server/`
- **110 ልዩ መሳሪያዎች** በ`server.ts` ውስጥ ተገናኝተዋል (45 መደበኛ መሳሪያዎች በ`schemas/tools.ts` +
የማህደረ ትውስታ፣ ክህሎቶች፣ GitHub-ክህሎቶች፣ ፑል፣ የጨዋታ አቀራረብ፣ ተሰኪ፣ Notion፣ Obsidian፣
የአካባቢ-ኮርፐስ እና የመጭመቂያ ሞጁሎች — ህብረቱ በ`countUniqueMcpTools` ተቆጥሯል)።
- **110 ልዩ መሣሪያዎች** በ`server.ts` ውስጥ ተገናኝተዋል (`schemas/tools.ts` ውስጥ 45 መደበኛ መሣሪያዎች +
የማህደረ ትውስታ፣ ክህሎቶች፣ GitHub-ክህሎቶች፣ ፑል፣ ጌሚፊኬሽን፣ ተሰኪ፣ Notion፣ Obsidian፣
የአካባቢያዊ-ኮርፐስ እና የማመቂያ ሞጁሎች — ውህዱ በ`countUniqueMcpTools` ተቆጥሯል)።
- **3 ማጓጓዣዎች**፦ stdio፣ HTTP Streamable፣ SSE።
- **33 ወሰኖች** በአሂድ ጊዜ ተፈጻሚ ይሆናሉ — መሠረታዊ ዝርዝሩ በ`src/shared/constants/mcpScopes.ts` ውስጥ ሲሆን፣ ሙሉው ስብስብ በእያንዳንዱ የመሳሪያ ሞጁል የታወጁት ወሰኖች ህብረት ነው።
- **33 ወሰኖች** በአሂድ ጊዜ ይተገበራሉ — መሠረታዊው ዝርዝር በ`src/shared/constants/mcpScopes.ts` ውስጥ ሲሆን፣ ሙሉው ስብስብ በእያንዳንዱ የመሣሪያ ሞጁል የተገለጹት ወሰኖች ውህድ ነው።
- የኦዲት ሰንጠረዥ፦ `mcp_tool_audit` (በ`audit.ts` የሚሞላ)።
- ፋይሎች፦ `server.ts`፣ `index.ts`፣ `httpTransport.ts`፣ `audit.ts`፣ `scopeEnforcement.ts`፣
`runtimeHeartbeat.ts`፣ `descriptionCompressor.ts`፣ `schemas/{tools, a2a, audit, index}.ts`፣
`tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`፣
እንዲሁም በ`__tests__/` ስር ያሉ ሙከራዎች።
- ሙሉውን የመሳሪያዎች ካታሎግ ለማየት [MCP-SERVER.md](../frameworks/MCP-SERVER.md)ን ይመልከቱ።
- ሙሉውን የመሣሪያ ካታሎግ ለማየት [MCP-SERVER.md](../frameworks/MCP-SERVER.md)ን ይመልከቱ።
### 4.7 `open-sse/config/`
የአቅራቢ መዝገቦች (`providerRegistry.ts`፣ `providerModels.ts`፣
`providerHeaderProfiles.ts`)፣ በቅርጸት የተለዩ የሞዴል መዝገቦች (`audioRegistry.ts`፣
`providerHeaderProfiles.ts`)፣ በቅርጸት የተከፋፈሉ የሞዴል መዝገቦች (`audioRegistry.ts`፣
`embeddingRegistry.ts`፣ `imageRegistry.ts`፣ `moderationRegistry.ts`፣
`musicRegistry.ts`፣ `rerankRegistry.ts`፣ `searchRegistry.ts`፣ `videoRegistry.ts`)፣
የማንነት ረዳቶች (`codexIdentity.ts`፣ `codexInstructions.ts`፣
የማንነት አጋዥ መሣሪያዎች (`codexIdentity.ts`፣ `codexInstructions.ts`፣
`anthropicHeaders.ts`፣ `antigravityUpstream.ts`፣ `antigravityModelAliases.ts`፣
`cliFingerprints.ts`፣ `toolCloaking.ts`፣ `defaultThinkingSignature.ts`)፣
የማረጋገጫ መረጃ ረዳቶች (`credentialLoader.ts`፣ `codexClient.ts`)፣ እና የደመና
የማረጋገጫ መረጃ አጋዥ መሣሪያዎች (`credentialLoader.ts`፣ `codexClient.ts`)፣ እና የደመና
አስማሚዎች (`azureAi.ts`፣ `bedrock.ts`፣ `datarobot.ts`፣ `glmProvider.ts`፣
`maritalk.ts`፣ `oci.ts`፣ `petals.ts`፣ `runway.ts`፣ `sap.ts`፣ `watsonx.ts`፣
`ollamaModels.ts`፣ `errorConfig.ts`፣ `constants.ts`፣ `registryUtils.ts`)።
### 4.8 `open-sse/utils/`
የዥረት መሠረታዊ አካላት እና የአቅራቢ አጋዥ መሣሪያዎች፦ `stream.ts`, `streamHandler.ts`,
`streamHelpers.ts`, `streamPayloadCollector.ts`, `streamReadiness.ts`,
`sseHeartbeat.ts`, `proxyFetch.ts`, `proxyDispatcher.ts`, `tlsClient.ts`,
`networkProxy.ts`, `awsSigV4.ts`, `cacheControlPolicy.ts`,
`cursorChecksum.ts`, `cursorAgentProtobuf.ts`, `cursorVersionDetector.ts`,
`comfyuiClient.ts`, `kieTask.ts`, `bypassHandler.ts`, `aiSdkCompat.ts`,
`thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `requestLogger.ts`,
`progressTracker.ts`, `cors.ts`, `error.ts`, `logger.ts`, `sleep.ts`,
`ollamaTransform.ts`.
የዥረት መሠረታዊ አካላት እና የአቅራቢ ረዳቶች፦ `stream.ts`፣ `streamHandler.ts`፣
`streamHelpers.ts`፣ `streamPayloadCollector.ts`፣ `streamReadiness.ts`፣
`sseHeartbeat.ts`፣ `proxyFetch.ts`፣ `proxyDispatcher.ts`፣ `tlsClient.ts`፣
`networkProxy.ts`፣ `awsSigV4.ts`፣ `cacheControlPolicy.ts`፣
`cursorChecksum.ts`፣ `cursorAgentProtobuf.ts`፣ `cursorVersionDetector.ts`፣
`comfyuiClient.ts`፣ `kieTask.ts`፣ `bypassHandler.ts`፣ `aiSdkCompat.ts`፣
`thinkTagParser.ts`፣ `urlSanitize.ts`፣ `usageTracking.ts`፣ `requestLogger.ts`፣
`progressTracker.ts`፣ `cors.ts`፣ `error.ts`፣ `logger.ts`፣ `sleep.ts`፣
`ollamaTransform.ts`።
---
@@ -655,7 +655,7 @@ bin/
## 8. `scripts/`
በዓላማ መሠረት በ6 ንዑስ አቃፊዎች ተደራጅቷል።
እንደ ዓላማቸው በ6 ንዑስ አቃፊዎች የተደራጁ ናቸው።
- **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`,
`prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`,

231
docs/i18n/am/docs/architecture/DESIGN_SYSTEM.md Normal file
View File

@@ -0,0 +1,231 @@
# OmniRoute — Design System & Visual Identity (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/DESIGN_SYSTEM.md) · 🇸🇦 [ar](../../../ar/docs/architecture/DESIGN_SYSTEM.md) · 🇦🇿 [az](../../../az/docs/architecture/DESIGN_SYSTEM.md) · 🇧🇬 [bg](../../../bg/docs/architecture/DESIGN_SYSTEM.md) · 🇧🇩 [bn](../../../bn/docs/architecture/DESIGN_SYSTEM.md) · 🇨🇿 [cs](../../../cs/docs/architecture/DESIGN_SYSTEM.md) · 🇩🇰 [da](../../../da/docs/architecture/DESIGN_SYSTEM.md) · 🇩🇪 [de](../../../de/docs/architecture/DESIGN_SYSTEM.md) · 🇬🇷 [el](../../../el/docs/architecture/DESIGN_SYSTEM.md) · 🇪🇸 [es](../../../es/docs/architecture/DESIGN_SYSTEM.md) · 🇪🇪 [et](../../../et/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇷 [fa](../../../fa/docs/architecture/DESIGN_SYSTEM.md) · 🇫🇮 [fi](../../../fi/docs/architecture/DESIGN_SYSTEM.md) · 🇫🇷 [fr](../../../fr/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇪 [ga](../../../ga/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [gu](../../../gu/docs/architecture/DESIGN_SYSTEM.md) · 🇳🇬 [ha](../../../ha/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇱 [he](../../../he/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [hi](../../../hi/docs/architecture/DESIGN_SYSTEM.md) · 🇭🇷 [hr](../../../hr/docs/architecture/DESIGN_SYSTEM.md) · 🇭🇺 [hu](../../../hu/docs/architecture/DESIGN_SYSTEM.md) · 🇦🇲 [hy](../../../hy/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇩 [id](../../../id/docs/architecture/DESIGN_SYSTEM.md) · 🇳🇬 [ig](../../../ig/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇹 [it](../../../it/docs/architecture/DESIGN_SYSTEM.md) · 🇯🇵 [ja](../../../ja/docs/architecture/DESIGN_SYSTEM.md) · 🇬🇪 [ka](../../../ka/docs/architecture/DESIGN_SYSTEM.md) · 🇰🇭 [km](../../../km/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [kn](../../../kn/docs/architecture/DESIGN_SYSTEM.md) · 🇰🇷 [ko](../../../ko/docs/architecture/DESIGN_SYSTEM.md) · 🇱🇹 [lt](../../../lt/docs/architecture/DESIGN_SYSTEM.md) · 🇱🇻 [lv](../../../lv/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [ml](../../../ml/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [mr](../../../mr/docs/architecture/DESIGN_SYSTEM.md) · 🇲🇾 [ms](../../../ms/docs/architecture/DESIGN_SYSTEM.md) · 🇲🇹 [mt](../../../mt/docs/architecture/DESIGN_SYSTEM.md) · 🇲🇲 [my](../../../my/docs/architecture/DESIGN_SYSTEM.md) · 🇳🇵 [ne](../../../ne/docs/architecture/DESIGN_SYSTEM.md) · 🇳🇱 [nl](../../../nl/docs/architecture/DESIGN_SYSTEM.md) · 🇳🇴 [no](../../../no/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [or](../../../or/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [pa](../../../pa/docs/architecture/DESIGN_SYSTEM.md) · 🇵🇭 [phi](../../../phi/docs/architecture/DESIGN_SYSTEM.md) · 🇵🇱 [pl](../../../pl/docs/architecture/DESIGN_SYSTEM.md) · 🇵🇹 [pt](../../../pt/docs/architecture/DESIGN_SYSTEM.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/DESIGN_SYSTEM.md) · 🇷🇴 [ro](../../../ro/docs/architecture/DESIGN_SYSTEM.md) · 🇷🇺 [ru](../../../ru/docs/architecture/DESIGN_SYSTEM.md) · 🇱🇰 [si](../../../si/docs/architecture/DESIGN_SYSTEM.md) · 🇸🇰 [sk](../../../sk/docs/architecture/DESIGN_SYSTEM.md) · 🇸🇮 [sl](../../../sl/docs/architecture/DESIGN_SYSTEM.md) · 🇷🇸 [sr](../../../sr/docs/architecture/DESIGN_SYSTEM.md) · 🇸🇪 [sv](../../../sv/docs/architecture/DESIGN_SYSTEM.md) · 🇰🇪 [sw](../../../sw/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [ta](../../../ta/docs/architecture/DESIGN_SYSTEM.md) · 🇮🇳 [te](../../../te/docs/architecture/DESIGN_SYSTEM.md) · 🇹🇭 [th](../../../th/docs/architecture/DESIGN_SYSTEM.md) · 🇹🇷 [tr](../../../tr/docs/architecture/DESIGN_SYSTEM.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/DESIGN_SYSTEM.md) · 🇵🇰 [ur](../../../ur/docs/architecture/DESIGN_SYSTEM.md) · 🇺🇿 [uz](../../../uz/docs/architecture/DESIGN_SYSTEM.md) · 🇻🇳 [vi](../../../vi/docs/architecture/DESIGN_SYSTEM.md) · 🇳🇬 [yo](../../../yo/docs/architecture/DESIGN_SYSTEM.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/DESIGN_SYSTEM.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/DESIGN_SYSTEM.md)
---
> **ሁኔታ:** ማጣቀሻ — እዚህ የተገለጸው ደረጃ ማውጣት **ተግባራዊ ሆኗል** (ደረጃዎች 1–6፦ የፍርግርግ ልጣፍ፣ መሠረታዊ አካላት፣ የሁኔታ-ቀለም ማዕከላዊነት፣ mono token፣ የDataTable token ፍልሰት፣ focus-ring → accent፣ Checkbox/Textarea መሠረታዊ አካላት፣ `cn()` → tailwind-merge፣ በእያንዳንዱ ራሱን በቻለ ማያ ገጽ ላይ ፍርግርግ፣ ፈሳሽ የ4K ይዘት shell፣ ድፍን የውሂብ-ሰንጠረዥ ገጽታዎች)። ይህ ሰነድ የዳሽቦርዱን የንድፍ tokens፣ ክፍሎች እና ልማዶች የሚገልጽ ዋና ማጣቀሻ ነው፤ ከታች ያለው በደረጃዎች የተዋቀረ አቀራረብ ለእያንዳንዱ ውሳኔ እንደ ምክንያታዊ መሠረት ተጠብቆ ቆይቷል።
> **ወሰን:** የOmniRoute ዳሽቦርድ (`src/`) እና የግብይት ጣቢያው (`_mono_repo/omnirouteSite/`) **አንድ የእይታ ማንነት** ይጋራሉ — ተመሳሳይ የግራፍ-ወረቀት ፍርግርግ ዳራ (32px)፣ ተመሳሳይ የቀለም tokens፣ ደረጃውን የጠበቁ ክፍሎች።
>
> ለጥገና አድራጊዎች ተግባራዊ ማስታወሻዎች፦
>
> - አሁንም የቀሩ በቀጥታ የተጻፉ hex እሴቶች አንዳንዶቹ **ሆን ተብለው** የተቀመጡ ናቸው (ሁልጊዜ-ጨለማ የሆነ የኮንሶል ተርሚናል፣ ReactFlow SVG strokes) እና ወደ tokens **መዛወር የለባቸውም**።
> - በሥራ ላይ ባለ ኢንስታንስ ላይ የሚታይ "ትልቅ" ፍርግርግ ጊዜው ያለፈበት build ነው እንጂ ኮድ አይደለም — የፍርግርጉ መጠን 32px ሲሆን ከጣቢያው ጋር ፍጹም ተመሳሳይ ነው።
> - የጨለማ ገጽታ `--table-*` እሴቶች ከፍልሰቱ በፊት በቀጥታ ከተጻፉት rgba እሴቶች ጋር በባይት ደረጃ ተመሳሳይ ናቸው፤ የብርሃን ገጽታው ተስተካክሏል (በማይሠሩ `var()` fallbacks ምክንያት ሁልጊዜ-ጨለማ የሆነ ስህተት ነበረበት)።
---
## 1. ዓላማ
የግብይት ጣቢያው (`viral.omniroute.online`፣ `why.omniroute.online`፣ `omniroute.online`) እና የምርቱ ዳሽቦርድ **አንድ ምርት** መስለው መታየት አለባቸው። ጣቢያው አስቀድሞ የቀለም ስብስቡን ከዳሽቦርዱ ወስዷል — የእሱ `css/tokens.css` እንኳን _"የቀለም ስብስቡ የOmniRoute ዳሽቦርድን (src/app/globals.css) ያንጸባርቃል"_ ይላል። ስለዚህ ሁለቱ በቀለም ደረጃ አስቀድመው ~80% ተመሳስለዋል። በዳሽቦርዱ ላይ የጎደለው፦
1. ጣቢያው በእያንዳንዱ ገጽ ላይ የሚጠቀምበት **የግራፍ-ወረቀት ፍርግርግ ልጣፍ**።
2. ጣቢያው ያሉት ነገር ግን ዳሽቦርዱ የሌሉት ጥቂት **የጋራ የንድፍ tokens** (የradius መለኪያ፣ የምርት ምልክት gradient፣ `surface-2`፣ mono font)።
3. **በክፍል ደረጃ ያለ ወጥነት** — በርካታ የዳሽቦርድ ክፍሎች በቀጥታ የተጻፉ hex/rgba እሴቶችን በመጠቀም የገጽታ tokensን ያልፋሉ።
ይህ ሰነድ ትንታኔው እና ዕቅዱ ነው።
---
## 2. መርሆዎች
- **አንድ የእውነት ምንጭ = `src/app/globals.css`።** ጣቢያው ዳሽቦርዱን ያንጸባርቃል፤ ዳሽቦርዱ ጣቢያውን አያንጸባርቅም። አዲስ tokens መጀመሪያ `globals.css` ውስጥ ይገባሉ።
- **ሁልጊዜ tokens፣ literals በፍጹም አይደሉም።** ክፍሎች ትርጉማዊ tokensን (`bg-surface`፣ `text-primary`፣ `border-border`) ይጠቀማሉ እንጂ ጥሬ `#hex`ን አይጠቀሙም።
- **ስውር፣ ጎልቶ የማይታይ።** ፍርግርጉ ከይዘቱ ጀርባ የሚቀመጥ ደብዛዛ ልጣፍ ነው — የጽሑፍን ንፅፅር መቀነስ ወይም ከUIው ጋር መፎካከር የለበትም።
- **ከገጽታው ጋር የሚላመድ።** ሁሉም ነገር በ`.dark` (የምርቱ መለያ ገጽታ) እና በብርሃን ገጽታ ውስጥ ይሠራል።
- **በጥንቃቄ የሚከናወን ልቀት።** መጀመሪያ ፍርግርጉን + tokensን ለቅቅ (ዝቅተኛ ስጋት፣ ከፍተኛ ታይነት)፣ ከዚያ የክፍሎችን ማጽዳት በየዙሩ አከናውን።
---
## 3. የአሁኑ ሁኔታ — አስቀድሞ የተጣጣመው እና ያልተጣጣመው
### 3.1 ቀለሞች — አስቀድመው የተዋሐዱ ✅
እያንዳንዱ የምርት ምልክት ቀለም እና ገጽታ ከጣቢያው ጋር **በእሴት** አስቀድሞ ይዛመዳል (የሚለያዩት ስሞቹ ብቻ ናቸው — ዳሽቦርዱ `--color-` ቅድመ ቅጥያ ይጨምራል)። በ`src/app/globals.css:30-128` ውስጥ ተረጋግጧል፦
| ጽንሰ-ሐሳብ | የጣቢያ token (`tokens.css`) | የዳሽቦርድ token (`globals.css`) | መዛመድ |
| -------------------- | ------------------------------------------- | ------------------------------- | ---------------- |
| ዋና | `--primary #e54d5e` | `--color-primary #e54d5e` | ✅ |
| ዋና-hover | `--primary-hover #c93d4e` | `--color-primary-hover #c93d4e` | ✅ |
| አጽንዖት | `--accent #6366f1` | `--color-accent #6366f1` | ✅ |
| አጽንዖት-2 | `--accent-2 #8b5cf6` | `--color-accent-hover #8b5cf6` | ✅ (እንደገና የተሰየመ) |
| አጽንዖት-3 | `--accent-3 #a855f7` | `--color-accent-light #a855f7` | ✅ (እንደገና የተሰየመ) |
| ስኬት / ማስጠንቀቂያ / ስህተት | `#22c55e / #f59e0b / #ef4444` | ተመሳሳይ | ✅ |
| የትራፊክ መብራቶች | `#ff5f56 / #ffbd2e / #27c93f` | ተመሳሳይ | ✅ |
| ጨለማ bg / ገጽታ / ድንበር | `#0b0e14 / #161b22 / rgba(255,255,255,.08)` | ተመሳሳይ | ✅ |
| ብርሃን bg / ገጽታ / ጽሑፍ | `#f9f9fb / #fff / #1a1a2e` | ተመሳሳይ | ✅ |
**መደምደሚያ:** መከናወን ያለበት የቀለም ፍልሰት የለም። ማንነቱ አስቀድሞ የጋራ ነው፤ እኛ እየሠራን ያለነው እንደገና መገንባት ሳይሆን _ማጠናቀቅ_ ነው።
### 3.2 ክፍተቶች — ዳሽቦርዱ የጎደለው
| ክፍተት | በድረ ገጹ ላይ ያለ | Dashboard | እርምጃ |
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------- |
| **የፍርግርግ ዳራ** | `body::before` የግራፍ ወረቀት፣ `--grid-line`፣ `--grid-size 32px`፣ `--section-alt` | **✅ ታክሏል (ደረጃ 1)** | **ክፍል A** |
| **የራዲየስ መለኪያ** | `--radius 14px`፣ `--radius-sm 9px` | `--radius 14px` ታክሏል፤ `-sm` + የኮምፖነንት ዳግም ማመላከት ይጠብቃል | **ክፍል B / ደረጃ 2** |
| **የብራንድ ግራዲየንት** | `--grad-brand 135deg primary→accent-3` | **✅ ቶከን ታክሏል (ደረጃ 1)**፤ በደረጃ 2 ጥቅም ላይ ይውላል | **ክፍል B** |
| **የተዋረደ ገጽታ** | `--surface-2 #1c2230` | **✅ ታክሏል (ደረጃ 1)** | **ክፍል B** |
| **ሞኖ ቅርጸ ቁምፊ** | `--font-mono` (የui-monospace ቁልል) | ይጠብቃል (ደረጃ 4፣ ከተጠቃሚዎቹ ጋር) | **ክፍል B** |
| **`text-muted` (ጨለማ)** | `#8b8b9e` | `#a1a1aa` (zinc-400) | ማጣጣም — **ክፍል B** |
### 3.3 የገጽታ ማስተካከያ አሠራር (ምንም ነገር እንዳናበላሽ)
- **Tailwind v4፣ CSS-first** (`tailwind.config.*` የለም)። ቶከኖች በ`:root`/`.dark` ውስጥ ይገለጻሉ፣ እና በ`@theme inline` (`globals.css:130-179`) በኩል ለመገልገያዎች ይቀርባሉ።
- **የጨለማ ገጽታ በ`.dark` ክፍል በኩል** በ`<html>` ላይ (`@custom-variant dark` በ`globals.css:22`)፣ በብጁ Zustand store (`src/store/themeStore.ts`) ይቀያየራል፤ ነባሪ ገጽታ = `system` (`src/shared/constants/appConfig.ts:11`)። ድረ ገጹ በምትኩ `html[data-theme="light"]` ይጠቀማል — **አሠራሮቹ የተለያዩ ቢሆኑም ፈጽሞ አይገናኙም** (የተለያዩ መነሻዎች)፣ ስለዚህ ግጭት የለም። የDashboardን `.dark` አሠራር እንደጠበቅነው እንቀጥላለን።
- **በአሂድ ጊዜ የprimary ማሻሻያ** አለ (`themeStore.ts:85-97`፣ ቅድመ-ቅንብሮች በ`COLOR_THEMES`) — ተጠቃሚዎች `--color-primary`ን መቀየር ይችላሉ። `--color-primary`ን የሚጠቅስ ማንኛውም አዲስ ቶከን (ግራዲየንት፣ ወዘተ) እነዚያን ማሻሻያዎች ያለተጨማሪ ሥራ ይወርሳል። ✅
- **የTailwind v4 የተያዙ የራዲየስ ስሞች፦** `--radius-sm/md/lg/...` ለ`rounded-*` መገልገያዎች መሠረት ናቸው። እነሱን እንደገና መግለጽ ያሉትን `rounded-*` ሁሉ በኋላ ተመልሶ ይቀይራል (ለምሳሌ፣ `rounded-sm` በ12 ፋይሎች ውስጥ ጥቅም ላይ ውሏል)። ስለዚህ የትንሹ ራዲየስ እሴት እና የኮምፖነንት ዳግም ማመላከት ሆን ተብለው ወደ ደረጃ 2 ተላልፈዋል፣ በዚያም ተጠቃሚዎቹ አብረው ይቀየራሉ።
---
## 4. ክፍል A — የግራፍ-ወረቀት ፍርግርግ ዳራ (ዋናው ጥያቄ) — ተግባራዊ ሆኗል (ደረጃ 1)
### 4.1 ምን እንደሆነ
ከጣቢያው (`_mono_repo/omnirouteSite/css/base.css`) የተወሰደው ትክክለኛ አሠራር፦ ሁለት የ1px መስመር ቅልመቶችን የሚስል፣ **ቋሚ፣ ሙሉ-መመልከቻ-ክፍል pseudo-element** ሲሆን፣ ከሁሉም ይዘት ጀርባ `z-index:-1` ላይ ይቀመጣል።
```css
body::before {
content: "";
position: fixed;
inset: 0;
z-index: -1;
pointer-events: none;
background-image:
linear-gradient(to right, var(--grid-line) 1px, transparent 1px),
linear-gradient(to bottom, var(--grid-line) 1px, transparent 1px);
background-size: var(--grid-size) var(--grid-size);
}
```
**`body` ደብዛዛ ያልሆነ `background-color` ቢኖረውም ይህ ለምን እንደሚሠራ፦** `z-index:-1` ያለው `::before` ከኤለመንቱ ራሱ ዳራ _በላይ_ ነገር ግን በመደበኛ ፍሰቱ ውስጥ ካለው ይዘት _በታች_ ይሳላል። ስለዚህ `--color-bg` መሠረታዊ ሙሌት ሲሆን፣ ፍርግርጉ በእሱ ላይ በንብርብር ይቀመጣል፣ መተግበሪያውም ከፍርግርጉ በላይ ይታያል።
### 4.2 ቀድሞውኑ በኮድ መሠረቱ ውስጥ ያለ አብነት
`src/app/landing/page.tsx:16-26` **ቀድሞውኑ ይህንኑ ፍርግርግ በእያንዳንዱ ገጽ ደረጃ ተግባራዊ ያደርጋል** — ነገር ግን በ50px ርቀት፣ **ቀይ** መስመሮችን (`#E54D5E`፣ opacity `0.06`) እና እነማ ያላቸውን ክቦች ይጠቀማል። ስለዚህ ይህ ንድፍ በምርቱ ውስጥ የተረጋገጠ ነው፤ ይህ ሥራ ወደ **ዓለም አቀፍ፣ ገጽታን የሚያውቅ** የዳራ ምስል ከፍ ያደርገዋል።
### 4.3 የተጨመሩ ቶከኖች (በ`globals.css` ውስጥ)
```css
:root {
/* ብርሃናማ — በብዙ ነገሮች በተሞላው ዳሽቦርድ ላይ የዳራ ምስሉ በእርግጥ
እንዲታይ፣ የፍርግርጉ opacity ከጣቢያው 0.045 ከፍ ተደርጓል (ካርዶች/chrome አብዛኛውን የመመልከቻ ክፍል ይሸፍናሉ) */
--grid-line: rgba(0, 0, 0, 0.07);
--grid-size: 32px;
--section-alt: rgba(0, 0, 0, 0.022);
}
.dark {
/* ጨለማ — በተመሳሳይ ምክንያት ከ0.035 ከፍ ተደርጓል */
--grid-line: rgba(255, 255, 255, 0.06);
--section-alt: rgba(255, 255, 255, 0.018);
}
```
### 4.4 ብቸኛው እንቅፋት — ተወግዷል
ፍርግርጉ በአወቃቀሩ ዓለም አቀፋዊ ነው (ፓነሉን፣ `auth`/`login`ን፣ የስህተት ገጾችን — ሁሉንም route በአንድ ጊዜ — ይሸፍናል)። በፓነሉ ውስጥ የደበቀው በትክክል **አንድ** ኤለመንት ነበር፦
- `src/shared/components/layouts/DashboardLayout.tsx` — ውጫዊው wrapper ደብዛዛ ያልሆነ `bg-bg` ይስል ነበር። ከእሱ በታች ያሉት ነገሮች በሙሉ ቀድሞውኑ ግልጽ ናቸው (`<main>`፣ የማሸብለያ መያዣው፣ የውስጡ `max-w-7xl`)፤ ስለዚህ **`bg-bg`ን ማስወገድ** የbody ፍርግርግ በይዘት አካባቢው በኩል እንዲታይ ያደርጋል (የbody `--color-bg` መሠረታዊ ሙሌት ሆኖ ይቀጥላል)።
```diff
- <div className="flex h-dvh min-h-0 w-full overflow-hidden bg-bg">
+ <div className="flex h-dvh min-h-0 w-full overflow-hidden">
```
### 4.5 ከchrome ጋር ያለው መስተጋብር (sidebar / header)
- `Header` (`Header.tsx:207`, `bg-bg`) እና `Sidebar` (`Sidebar.tsx:430`, `bg-sidebar`) **ደብዛዛ ያልሆኑ** ሆነው ይቀጥላሉ → ፍርግርጉ የሚታየው **በይዘት አካባቢው ብቻ** ሲሆን፣ ዙሪያውን ጠጣር chrome ይከበዋል። ይህ ረጋ ያለ ነባሪ ነው፣ እንዲሁም ጣቢያው chromeን ከcanvas ከሚለይበት መንገድ ጋር ይዛመዳል (ውሳኔ D3 = ጠጣር)።
### 4.6 የLogin / auth / ስህተት ገጾች
እነዚህ በቀጥታ ከ`<body>` ሥር ይታያሉ (የፓነል chrome የላቸውም)፣ ስለዚህ ዓለም አቀፋዊው ፍርግርግ በራስ-ሰር ከጀርባቸው መታየት አለበት። **ደረጃ 5 — ተጠናቋል፦** ራሳቸውን የቻሉት ሙሉ-ማያ wrapperዎች በእርግጥ ደብዛዛ ያልሆኑ ነበሩ (`min-h-screen … bg-bg`፣ በዚህም `bg-bg` ከ`<body>` ጋር ተመሳሳይ ጠጣር ሙሌት ነው)፤ ይህም ፍርግርጉን በሁሉም ከዳሽቦርድ ውጭ ባሉ ማያዎች ላይ ይደብቀው ነበር — በlogin ላይ ብቻ አይደለም። የጋራው የዳራ ምስል በእነሱ በኩል እንዲታይ፣ ሁሉም አሁን ግልጽ ተደርገዋል፦ `login`፣ `forgot-password`፣ `callback`፣ `maintenance`፣ `offline`፣ `status`፣ `terms`፣ `privacy`፣ `onboarding` እና `ErrorPageScaffold` (`400`/`401`ን ይሸፍናል)። ይህ **D4**ን ይዘጋል (ከlogin ብቻ ወደ ሁሉም ራሳቸውን ወደቻሉ ማያዎች ተስፋፍቷል)። በ`tests/unit/design-grid-background.test.ts` ጥበቃ ተደርጎለታል።
### 4.7 የማረፊያ ገጽ
`landing/page.tsx` ይበልጥ የበለጸገውን እነማ ያለው ዳራውን (ክቦች + vignette) ይዞ ይቀጥላል — የራሱ የግብይት መግቢያ ማሳያ ነው (ውሳኔ D5 = እንዳለ መተው)።
---
## 5. ክፍል B — የቶከን ውህደት
ደረጃ 1 ምንም ተጽዕኖ የሌላቸውንና ከግጭት ነጻ የሆኑ የመለያ ቶከኖችን (`--surface-2`/`--color-surface-2`፣ `--grad-brand`፣ `--radius`) ይጨምራል። ደረጃ 2 የራዲየስ ልኬቱን ከTailwind ጋር ያገናኛል እና ኮምፖነንቶችን ወደ እሱ እንዲጠቁሙ ያደርጋል፤ ደረጃ 4 `--font-mono`ን ከተጠቃሚዎቹ ጋር ይጨምራል።
| ቶከን | ምክንያት | ደረጃ |
| -------------------------- | --------------------------------------------- | --------------------------------- |
| `--radius` / `--radius-sm` | በዘፈቀደ ከተወሰኑ 6/8/12 ይልቅ አንድ የራዲየስ ልኬት (14/9) | 1 (እሴት) / 2 (ማገናኘት + እንደገና ማመልከት) |
| `--grad-brand` | ከጣቢያው ጋር የሚጣጣም ለዋና CTAዎች የብራንድ ቅልመት (ቀይ→ቫዮሌት) | 1 (ቶከን) / 2 (Button) |
| `--surface-2` | ውስጣዊ ፓነሎች / የሰንጠረዥ ራስጌዎች / ወደ ውስጥ የገቡ ረድፎች | 1 |
| `--font-mono` | የኮድ ብሎኮች፣ ተርሚናል፣ IDዎች፣ endpoints | 4 |
| `--text-muted` ማስማማት | በጣቢያ↔ፓነል መካከል አንድ እሴት ይምረጡ (`#a1a1aa` ይመከራል) | 2 |
**D2 (text-muted):** ጣቢያ `#8b8b9e` እና dashboard `#a1a1aa`። **የdashboardን `#a1a1aa`** እንዲቆይ እና _ጣቢያው_ ከእሱ ጋር እንዲጣጣም እንዲዘምን እንመክራለን። የመልክ ማሻሻያ ብቻ ነው።
---
## 6. ክፍል C — የኮምፖነንት ደረጃ ማስተካከያ (ደረጃዎች 2–4)
ብጁ ኮምፖነንቶች (shadcn/Radix የሉም)፣ Tailwind v4፣ የትርጉም ቶከኖች **በአብዛኛው** ጥቅም ላይ ውለዋል (195 ፋይሎች የጋራ barrelን import ያደርጋሉ)። ስራው **ማለፊያዎቹን** ማስወገድ ነው። መነሻ፦ `src/shared/components/`።
| # | ንጥል | ፋይል(ሎች) | ችግር → ዒላማ | ደረጃ |
| --- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --- |
| C1 | **የራዲየስ ማስተካከያ** | `Button.tsx:14-18`, `Card.tsx:39`, `Modal.tsx`, `Input.tsx`, `Select.tsx` | የተቀላቀሉ 6/8/12px → `--radius`/`--radius-sm` (14/9) | 2 |
| C2 | **የButton ቅልመት + `accent` variant** | `Button.tsx:5-12` | primary ቀጥ ያለ ቀይ→ቀይ ነው፤ ከ`--grad-brand` ጋር ያስተካክሉ፤ የጎደለውን `accent` variant ያክሉ። ~195 importers — ከፍተኛው ታይነት | 2 |
| C3 | **ሰንጠረዦች** | `DataTable.tsx:122-176`, `logTableStyles.ts`, `globals.css:405-414` | 100% inline በhardcode የተደረገ rgba + የማይኖሩ vars፤ ወደ ቶከኖች ያዛውሩ፣ የማይጣጣሙ ቅጦችን ከአገልግሎት ያውጡ | 3 |
| C4 | **የሁኔታ ቀለሞችን ማዕከላዊ ማድረግ** | `flow/edgeStyles.ts`, `TokenHealthBadge.tsx`, `DegradationBadge.tsx`, `ProviderCascadeNode.tsx`, `Badge.tsx` + 5 helpers | የተመሳሳይ hex 6+ ቅጂዎች → በ`--color-success/warning/error` ላይ የተመሠረተ አንድ module | 3 |
| C5 | **የCard ድንበር** | `Card.tsx:39` | `border-white/5` → brand `/8` | 2 |
| C6 | **የFocus ring ማስማማት** ✅ ተጠናቋል | `globals.css` `--focus-ring` (accent) እና የform controls `ring-primary/30` | ከglobal ring ጋር እንዲጣጣም እና ከቀዩ error ring እንዲለይ **accent (ቫዮሌት)** ላይ አንድ ወጥ ሆኗል፤ error ቀይ ሆኖ ይቆያል | 4 |
| C7 | **`Checkbox` + `Textarea` ማከል** | raw `<input>`/`<textarea>` ከinline `accentColor:#6366f1` ጋር | በቶከን የሚመሩ primitives | 4 |
| C8 | **የHardcoded-hex ፍተሻ** | `ConsoleLogViewer.tsx:240`, `ComboLiveStudio.tsx:306`, Modal dots, ~14 chart files | literals → tokens | 4 |
| C9 | **`cn()` → clsx + tailwind-merge** | `src/shared/utils/cn.ts` | የሚጋጩ classes ይደራረባሉ፤ ለC1 overrides ያስፈልጋል | 2 |
**አስቀድሞ ከብራንዱ ጋር የሚጣጣሙ (በቶከን የሚመሩ፣ ራዲየስ ብቻ ያስፈልጋቸዋል)፦** `Badge`, `Toggle`, `SegmentedControl`, `Input`, `Select`.
---
## 7. የማሰማራት ዕቅድ
- **ደረጃ 1 — ፍርግርግ + የማንነት ቶከኖች (ይህ PR)።** የ`globals.css` ፍርግርግ + `--surface-2`/`--grad-brand`/`--radius` ቶከኖች፤ `body::before` ልጣፍ፤ የ`bg-bg` እንቅፋትን ማስወገድ፤ ቋሚ የመከላከያ ሙከራ። አነስተኛ ስጋት ያለውና በአንድ commit መቀልበስ የሚቻል።
- **ደረጃ 2 — መሠረታዊ ክፍሎች (C1, C2, C5) — በዚህ PR ውስጥ ተጠናቋል።** የትርጉም ያላቸው የራዲየስ ዩቲሊቲዎች `rounded-card` (14px) / `rounded-control` (9px) በ`@theme` በኩል ታክለዋል (ብጁ ስሞች ስለሆኑ፣ ነባሪዎቹ `rounded-sm/md/lg/xl` ሳይነኩ ይቀራሉ — 400 ፋይሎችን የሚያካትት ለውጥ የለም)፤ Card/Modal → 14px፣ Button/Input/Select → 9px፤ ዋና Button → `--grad-brand` (ቀይ→ቫዮሌት) + አዲስ `accent` ተለዋጭ፤ የCard ድንበሮች → የ`border-border` ቶከን (0.08)። **ለሌላ ጊዜ የተላለፈ:** `cn()`→tailwind-merge (C9) አዳዲስ deps ያስፈልገዋል፤ መሠረታዊ ክፍሎቹ የወለሉን አብዛኛውን ስለሚሸፍኑ፣ ጊዜያዊ የ`rounded-lg` ማስተካከያ (326 ፋይሎች) እንዳለ ተትቷል።
- **ደረጃ 3 — የሁኔታ ቀለሞች + ሰንጠረዦች (C3, C4) — በዚህ PR ውስጥ ተጠናቋል።** ✅ **C4** (`src/shared/constants/statusColors.ts` — `STATUS_HEX` ብቸኛ ምንጭ፤ `flow/edgeStyles.ts` + `TokenHealthBadge` ወደዚያ እንዲጠቁሙ ተደርገዋል፣ ተመሳሳዩን hex በትክክል ይዘዋል)። ✅ **`--font-mono`** ቶከን። ✅ **C3 (DataTable)** — እያንዳንዱ inline rgba እና ጥቅም ላይ የማይውሉት `var(--bg-table-header)` / `var(--text-secondary)` fallbacks በ`--table-*` የቶከን ስብስብ (`--table-header-bg/-row-zebra/-row-hover/-cell-border/-row-selected`) ተተክተዋል፤ **የጨለማ እሴቶቹ ከቀድሞዎቹ hardcoded rgba ጋር ፍጹም እኩል ናቸው** (dark ባይት-በ-ባይት ተመሳሳይ ነው)፣ የብርሃን እሴቶቹ ደግሞ ቀደም ሲል ሁልጊዜ ጨለማ የነበረውን የብርሃን ገጽታ ያስተካክላሉ። የራስጌ ድንበር → `--color-border`፣ ሁለተኛ ደረጃ ጽሑፍ → `--color-text-muted`። **ከመዋሃዱ በፊት የእይታ ፍተሻ ያስፈልገዋል።** (ያልተነኩ፦ `logTableStyles.ts` እና የቆዩት Ant `.ant-table` ደንቦች — የተለዩና ዝቅተኛ ቅድሚያ ያላቸው።)
- **ደረጃ 4 — ማጽዳት (C6, C7, C9 ተጠናቀዋል፤ C8 ይጠብቃል)።** ✅ **C9** `cn()` → `twMerge(clsx(...))` (clsx + tailwind-merge እንደ deps ታክለዋል) — አሁን የጠሪው `className` ከመሠረታዊ ክፍሉ ጋር የሚጋጭን class ከመደራረብ ይልቅ በትክክል _ይተካል_። ✅ **C7** አዲስ `Checkbox` + `Textarea` መሠረታዊ ክፍሎች (በቶከን የሚመሩ፣ ከbarrel የሚላኩ፤ ተጨማሪ ብቻ ናቸው — 32ቱን ጥሬ checkboxes / 41ዱን ጥሬ textareas መቀበል በደረጃ ሊቀጥል ይችላል)። ✅ **C6** የfocus-ring ማስማማት — የቅጽ መቆጣጠሪያዎቹ (`Input`/`Select`/`Textarea`/`Toggle`/`Checkbox`) አሁን ከዓለም አቀፉ `--focus-ring` ጋር እንዲዛመዱና ከቀዩ የስህተት ቀለበት ጋር እንዳይጋጩ በ**accent (ቫዮሌት)** ቀለበት focus ያደርጋሉ፤ ቀዩ የስህተት ሁኔታ አልተለወጠም። ⏳ **የC8 hex ማጣራት ዓይነ ስውር find/replace አይደለም** — _ሆን ተብለው_ የተደረጉና መቆየት ያለባቸው የተረጋገጡ አጋጣሚዎች፦ `ConsoleLogViewer.tsx:240` (ሁልጊዜ-ጨለማ terminal)፣ የ`TokenHealthBadge` popover፣ ReactFlow SVG strokes። ወደ ገጽታው እንዲስማሙ በእውነት የታሰቡ hex ብቻ ይዛወሩ።
እያንዳንዱ ደረጃ፦ `npm run lint` + `npm run typecheck:core` + የእይታ ፍተሻ።
---
## 8. ክፍት ውሳኔዎች (ምክረ ሐሳቦች)
- **D1 — ዋና Button፦** ቀይ→ቀይ ይቆይ ወይስ ወደ **ቀይ→ቫዮሌት `--grad-brand`** ይቀየር? ምክር፦ **ቀይ→ቫዮሌት** (ደረጃ 2)።
- **D2 — የፍርግርግ መስመር ቀለም፦** **ገለልተኛ** (የጣቢያው ቅጥ) — ተመርጧል — ከbrand-red ጋር ሲነጻጸር። መጠን **32px** (በባለቤቱ ግብረ መልስ መሠረት ከመጀመሪያው 46px በ~30% ቀንሷል — 46px ሕዋሶች በdashboard አቀማመጥ ላይ በጣም ትልቅ ይመስሉ ነበር)።
- **D3 — የChrome ጥርትነት፦** sidebar/header **ድፍን** — ተመርጧል።
- **D4 — የAuth/login ፍርግርግ፦** ✅ **ተጠናቋል (ደረጃ 5)** — ግልጽነት የሌለው `bg-bg` ከሁሉም ራሳቸውን ከቻሉ ሙሉ-ማያ መጠቅለያዎች (ከlogin ብቻ ሳይሆን) ተወግዷል፣ ስለዚህ ፍርግርጉ በሁሉም ማያዎች ላይ ይታያል። §4.6ን ይመልከቱ።
- **D5 — የማረፊያ ገጽ፦** እነማ ያለው splash እንዳለ ይቆይ። ተመርጧል።
- **D6 — 14/9 ራዲየስ በምርቱ በሙሉ፦** ምክር፦ አዎ (ደረጃ 2)።
- **D7 — ደረጃ 1 መጀመሪያ ይለቀቃል፦** ተመርጧል።
- **D8 — የአቀማመጥ ስፋት (ደረጃ 5)፦** የdashboard ይዘት shell በ`max-w-7xl` (1280px) ተገድቦ ነበር፣ ይህም በትላልቅ monitors ላይ ሰፊ ባዶ የጎን ክፍተቶችን በመተው ይዘቱን መሃል ያደርገው ነበር። ✅ **ተጠናቋል** — ወደ ተለዋዋጭ `max-w-[3840px]` (እውነተኛ 4K) ከፍ ብሏል፦ አሁን ይዘቱ እስከ ~4K ድረስ viewportን ይከተላል፣ ከዚያ በላይ ብቻ መሃል ይሆናል (`DashboardLayout.tsx`)። ሆን ተብለው ጠባብ የተደረጉ ገጾች በንድፍ ጠባብ ሆነው ይቆያሉ (`ProviderOnboardingWizard` max-w-5xl፣ `Rtk`/`CavemanContextPageClient` max-w-6xl)።
- **D9 — ግልጽነት የሌላቸው የውሂብ ሰንጠረዦች (ደረጃ 6)፦** የdashboard ይዘት ቦታ አሁን ግልጽ በመሆኑ (የፍርግርግ ልጣፉ እንዲታይ፣ ደረጃ 5)፣ መያዣቸው ግልጽነት የሌለው surface ያልነበረ የውሂብ ሰንጠረዦች ፍርግርጉ በግልጽ even-rows / ዝቅተኛ-alpha zebra በኩል እንዲታይ ያደርጉ ነበር። ✅ **ተጠናቋል** — እያንዳንዱ Card የሌለው ሰንጠረዥ አሁን `bg-surface`ን ይስላል (ወይም ለ`<DataTable>` መሠረታዊ ክፍል፣ በscroll መያዣው ላይ `background: var(--color-surface)`)። የተስተካከሉ፦ `DataTable` (መሠረታዊ ክፍል)፣ `ProxyLogger`/`RequestLoggerV2` (የእነሱ `<Card>` `bg-black/5 dark:bg-black/20` tint በtailwind-merge በኩል ከCard `bg-surface` በላይ እያሸነፈ ነበር → ~95% ግልጽ)፣ `BatchListTab`/`FilesListTab`/`CacheEntriesTab`/`ReasoningCacheTab`/`cache page`/`FreePoolTab`/`ModelMappingTable`/`HeaderTable`፣ እንዲሁም በcache እይታዎች ውስጥ ያሉት ሁለቱ CSS-grid “ሰንጠረዦች” (`bg-surface/35` → `bg-surface`)። ቀድሞውኑ በ`<Card>`/Modal ውስጥ ያሉ ሰንጠረዦች ግልጽነት እንደሌላቸው ተረጋግጦ፣ ሆን ተብለው ሳይነኩ ቀርተዋል (በዚያ ያለው bg-surface የማያስፈልግ no-op ነው)። ፍርግርጉ ራሱ **ምንም ለውጥ አላስፈለገውም** — የdashboard `body::before` ከጣቢያው ጋር ባይት-በ-ባይት ተመሳሳይ ነው (`--grid-size: 32px`)፤ በሚሰራ instance ላይ የሚታይ ማንኛውም “ትልቅ ፍርግርግ” ጊዜ ያለፈበት ከ`#4143` በፊት ያለ build ነው እንጂ code አይደለም። በ`tests/unit/design-grid-background.test.ts` (የደረጃ 6 block) ተጠብቋል።
---
## 9. ከወሰን ውጭ / ስጋቶች
- **የቀለም ስብስብ ለውጥ የለም** — ቀለሞቹ አስቀድመው ይዛመዳሉ፤ እኛ የምንጨምረው የጎደሉ ቶከኖችን ብቻ ነው። የምርቱን ቀለም የመቀየር ስጋት የለም።
- **የገጽታ ሞተር ለውጥ የለም** — `.dark` + Zustand store እንዳለ ይቆይ።
- **የራዲየስ ለውጥ (ደረጃ 2) ሰፊ ነው** — እያንዳንዱን ካርድ/አዝራር/ግቤት ይነካል፤ ከማዋሃድ በፊት ብዙ ይዘት ያላቸውን ማያ ገጾች (ሰንጠረዦች፣ ሞዳሎች) በዓይን ይፈትሹ።
- **ሰንጠረዦች (C3)** አብዛኛውን በቀጥታ የተቀመጠ ቅጥ እና ከፍተኛውን የዳግም ስህተት ስጋት ይይዛሉ — በራሳቸው PR ውስጥ ይለዩዋቸው።
---
## 10. የማጣቀሻ ማውጫ
| ክፍል | ዱካ |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| የዳሽቦርድ ቶከኖች | `src/app/globals.css` (`:root`, `.dark`, `@theme inline`, `body`, `body::before`) |
| የገጽታ store | `src/store/themeStore.ts`, `src/shared/components/ThemeProvider.tsx`, `src/shared/constants/appConfig.ts:9-11` |
| የፓነል shell (grid እዚህ ተከፍቷል) | `src/shared/components/layouts/DashboardLayout.tsx` |
| Chrome | `src/shared/components/Header.tsx:207`, `src/shared/components/Sidebar.tsx:430` |
| የGrid ቀዳሚ ምሳሌ | `src/app/landing/page.tsx:16-26` |
| መሠረታዊ አካላት | `src/shared/components/{Button,Card,Input,Select,Badge,Modal,Toggle,SegmentedControl,Loading,Tooltip,DataTable}.tsx` |
| የሁኔታ-ቀለም ምንጮች | `flow/edgeStyles.ts`, `TokenHealthBadge.tsx`, `DegradationBadge.tsx`, `logTableStyles.ts` |
| `cn` util | `src/shared/utils/cn.ts` |
| የደረጃ 1 መከላከያ ሙከራ | `tests/unit/design-grid-background.test.ts` |
| የጣቢያ ማጣቀሻ | `_mono_repo/omnirouteSite/css/tokens.css`, `css/base.css` |

145
docs/i18n/am/docs/architecture/MONITORING_SECTIONS.md Normal file
View File

@@ -0,0 +1,145 @@
# Monitoring & Costs — Navigation Structure (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/MONITORING_SECTIONS.md) · 🇸🇦 [ar](../../../ar/docs/architecture/MONITORING_SECTIONS.md) · 🇦🇿 [az](../../../az/docs/architecture/MONITORING_SECTIONS.md) · 🇧🇬 [bg](../../../bg/docs/architecture/MONITORING_SECTIONS.md) · 🇧🇩 [bn](../../../bn/docs/architecture/MONITORING_SECTIONS.md) · 🇨🇿 [cs](../../../cs/docs/architecture/MONITORING_SECTIONS.md) · 🇩🇰 [da](../../../da/docs/architecture/MONITORING_SECTIONS.md) · 🇩🇪 [de](../../../de/docs/architecture/MONITORING_SECTIONS.md) · 🇬🇷 [el](../../../el/docs/architecture/MONITORING_SECTIONS.md) · 🇪🇸 [es](../../../es/docs/architecture/MONITORING_SECTIONS.md) · 🇪🇪 [et](../../../et/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇷 [fa](../../../fa/docs/architecture/MONITORING_SECTIONS.md) · 🇫🇮 [fi](../../../fi/docs/architecture/MONITORING_SECTIONS.md) · 🇫🇷 [fr](../../../fr/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇪 [ga](../../../ga/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [gu](../../../gu/docs/architecture/MONITORING_SECTIONS.md) · 🇳🇬 [ha](../../../ha/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇱 [he](../../../he/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [hi](../../../hi/docs/architecture/MONITORING_SECTIONS.md) · 🇭🇷 [hr](../../../hr/docs/architecture/MONITORING_SECTIONS.md) · 🇭🇺 [hu](../../../hu/docs/architecture/MONITORING_SECTIONS.md) · 🇦🇲 [hy](../../../hy/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇩 [id](../../../id/docs/architecture/MONITORING_SECTIONS.md) · 🇳🇬 [ig](../../../ig/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇹 [it](../../../it/docs/architecture/MONITORING_SECTIONS.md) · 🇯🇵 [ja](../../../ja/docs/architecture/MONITORING_SECTIONS.md) · 🇬🇪 [ka](../../../ka/docs/architecture/MONITORING_SECTIONS.md) · 🇰🇭 [km](../../../km/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [kn](../../../kn/docs/architecture/MONITORING_SECTIONS.md) · 🇰🇷 [ko](../../../ko/docs/architecture/MONITORING_SECTIONS.md) · 🇱🇹 [lt](../../../lt/docs/architecture/MONITORING_SECTIONS.md) · 🇱🇻 [lv](../../../lv/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [ml](../../../ml/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [mr](../../../mr/docs/architecture/MONITORING_SECTIONS.md) · 🇲🇾 [ms](../../../ms/docs/architecture/MONITORING_SECTIONS.md) · 🇲🇹 [mt](../../../mt/docs/architecture/MONITORING_SECTIONS.md) · 🇲🇲 [my](../../../my/docs/architecture/MONITORING_SECTIONS.md) · 🇳🇵 [ne](../../../ne/docs/architecture/MONITORING_SECTIONS.md) · 🇳🇱 [nl](../../../nl/docs/architecture/MONITORING_SECTIONS.md) · 🇳🇴 [no](../../../no/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [or](../../../or/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [pa](../../../pa/docs/architecture/MONITORING_SECTIONS.md) · 🇵🇭 [phi](../../../phi/docs/architecture/MONITORING_SECTIONS.md) · 🇵🇱 [pl](../../../pl/docs/architecture/MONITORING_SECTIONS.md) · 🇵🇹 [pt](../../../pt/docs/architecture/MONITORING_SECTIONS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/MONITORING_SECTIONS.md) · 🇷🇴 [ro](../../../ro/docs/architecture/MONITORING_SECTIONS.md) · 🇷🇺 [ru](../../../ru/docs/architecture/MONITORING_SECTIONS.md) · 🇱🇰 [si](../../../si/docs/architecture/MONITORING_SECTIONS.md) · 🇸🇰 [sk](../../../sk/docs/architecture/MONITORING_SECTIONS.md) · 🇸🇮 [sl](../../../sl/docs/architecture/MONITORING_SECTIONS.md) · 🇷🇸 [sr](../../../sr/docs/architecture/MONITORING_SECTIONS.md) · 🇸🇪 [sv](../../../sv/docs/architecture/MONITORING_SECTIONS.md) · 🇰🇪 [sw](../../../sw/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [ta](../../../ta/docs/architecture/MONITORING_SECTIONS.md) · 🇮🇳 [te](../../../te/docs/architecture/MONITORING_SECTIONS.md) · 🇹🇭 [th](../../../th/docs/architecture/MONITORING_SECTIONS.md) · 🇹🇷 [tr](../../../tr/docs/architecture/MONITORING_SECTIONS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/MONITORING_SECTIONS.md) · 🇵🇰 [ur](../../../ur/docs/architecture/MONITORING_SECTIONS.md) · 🇺🇿 [uz](../../../uz/docs/architecture/MONITORING_SECTIONS.md) · 🇻🇳 [vi](../../../vi/docs/architecture/MONITORING_SECTIONS.md) · 🇳🇬 [yo](../../../yo/docs/architecture/MONITORING_SECTIONS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/MONITORING_SECTIONS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/MONITORING_SECTIONS.md)
---
> በGroup B (plan 16) ውስጥ ተተግብሯል። `src/shared/constants/sidebarVisibility.ts`ን ይመልከቱ።
---
## ከፍተኛ-ደረጃ አሰሳ
የዳሽቦርዱ የጎን አሞሌ (ከGroup B በኋላ) የሚከተሉትን ከፍተኛ-ደረጃ ክፍሎች በቅደም ተከተል ይዟል፦
```
መነሻ
አቅራቢዎች
ጥምረቶች
API ቁልፎች
ቅንብሮች
ትንታኔዎች
ወጪዎች ← አዲስ (Group B, plan 16)
ክትትል ← እንደገና የተደራጀ (Group B, plan 16)
...
```
---
## የወጪዎች ክፍል (አዲስ፣ ደረጃ 1)
የዱካ ቅድመ ቅጥያ፦ `/dashboard/costs/`
| ንጥል | URL | መግለጫ |
| --------- | ------------------------------------ | -------------------------------- |
| አጠቃላይ እይታ | `/dashboard/costs` | የተጠቃለለ የወጪ ዳሽቦርድ (ከትንታኔዎች የተዛወረ) |
| ዋጋ አወሳሰን | `/dashboard/costs/pricing` | የእያንዳንዱ ሞዴል የዋጋ ሰንጠረዥ |
| በጀት | `/dashboard/costs/budget` | የበጀት ገደቦች + ማንቂያዎች |
| የኮታ መጋራት | `/dashboard/costs/quota-share` | የኮታ መጋሪያ ገንዳዎች + አጠቃቀም |
| የዕቅድ ውቅር | `/dashboard/costs/quota-share/plans` | የእያንዳንዱ አቅራቢ ዕቅድ ማሻሻያዎች |
**ምክንያታዊ መሠረት**፦ የዋጋ አወሳሰን፣ በጀት እና የኮታ መጋራት ከዚህ ቀደም
`Monitoring > Costs Parameters` ሥር ነበሩ። ወደ ተለየ ከፍተኛ-ደረጃ ክፍል
ማዛወራቸው በታዛቢነት መሣሪያዎች ውስጥ ሳይዘዋወሩ እንዲገኟቸው ያደርጋል።
---
## የክትትል ክፍል (እንደገና የተደራጀ)
የክትትል ክፍሉ አሁን **እንቅስቃሴን ከላይ** እና ቀጥሎ **3 ንዑስ ቡድኖችን** ይዟል፦
```
ክትትል
├── እንቅስቃሴ ← የጊዜ መስመር ዥረት (ከፍተኛ-ደረጃ ንጥል)
├── የምዝግብ ማስታወሻዎች ቡድን
│ ├── የምዝግብ ማስታወሻዎች (ሁሉም)
│ ├── የፕሮክሲ ምዝግብ ማስታወሻዎች
│ └── የኮንሶል ምዝግብ ማስታወሻዎች
├── የኦዲት ቡድን
│ ├── የኦዲት ምዝግብ ማስታወሻ
│ ├── MCP ኦዲት
│ └── A2A ኦዲት
└── የስርዓት ቡድን
├── ጤና
└── የአፈጻጸም ጊዜ
```
### ከድሮው መዋቅር የተለወጠው
| በፊት | በኋላ |
| -------------------------------------------------------------------------------------- | ----------------------------------------- |
| እንቅስቃሴ = የኦዲት ምዝግብ ማስታወሻውን የሚያሳይ በምዝግብ ማስታወሻዎች ውስጥ ያለ ትር | እንቅስቃሴ = የተለየ ዥረት (`/dashboard/activity`) |
| በክትትል ውስጥ የወጪዎች መለኪያዎች ቡድን | ወደ ወጪዎች ክፍል ተዛውሯል |
| ጠፍጣፋ ዝርዝር፦ ምዝግብ ማስታወሻዎች፣ እንቅስቃሴ (ምዝግብ ማስታወሻዎች)፣ ኦዲት፣ ጤና፣ የአፈጻጸም ጊዜ፣ የዋጋ አወሳሰን፣ በጀት፣ ኮታ | የተዋቀሩ 3 ቡድኖች + የተለየ የወጪዎች ክፍል |
---
## እንቅስቃሴ እና የኦዲት ምዝግብ ማስታወሻ
እነዚህ ሁለቱ አሁን የተለያዩ ናቸው፦
| መለኪያ | እንቅስቃሴ (`/dashboard/activity`) | የኦዲት ምዝግብ ማስታወሻ (`/dashboard/audit`) |
| -------------- | -------------------------------------------- | ----------------------------------------- |
| **ዓላማ** | ለተጠቃሚ የሚታይ የክስተት ዥረት ("በቅርቡ ምን ተከሰተ") | የተገዢነት / ደህንነት ምዝግብ ማስታወሻ |
| **የውሂብ ምንጭ** | `GET /api/compliance/audit-log?level=high` | `GET /api/compliance/audit-log?level=all` |
| **ቅርጸት** | በቀን የተቧደነ የጊዜ መስመር፣ ለሰው ሊነበቡ የሚችሉ ግሶች + አዶዎች | ጥቅጥቅ ያለ በገጾች የተከፈለ ሰንጠረዥ፣ 50/ገጽ |
| **ማጣሪያዎች** | የክስተት ዓይነት ምድብ | እርምጃ፣ የክብደት ደረጃ፣ ፈጻሚ፣ የቀን ክልል |
| **ወደ ውጭ መላክ** | አይገኝም | ወደ JSON መላክ |
| **የፈጻሚ ማጣሪያ** | ተፈጻሚ አይደለም | በፈጻሚ ሊጣራ ይችላል |
| **የሚታዩ ክስተቶች** | ከፍተኛ-ደረጃ እርምጃዎች ብቻ (የፈቃድ ዝርዝር) | ሁሉም የኦዲት ክስተቶች |
### የከፍተኛ-ደረጃ እርምጃዎች የፈቃድ ዝርዝር
በ`src/lib/audit/highLevelActions.ts` ውስጥ ተገልጿል። በእንቅስቃሴ
ዥረቱ ውስጥ የትኞቹ ክስተቶች እንደሚታዩ ይቆጣጠራል። የፈቃድ ዝርዝሩ የሚከተሉትን ያካትታል፦
- አቅራቢን የመጨመር/የማስወገድ/የመሞከር ክስተቶች
- ጥምረት መፍጠር/ማዘመን/መሰረዝ
- የAPI ቁልፍ የሕይወት ዑደት (መፍጠር፣ መሻር፣ ማዞር)
- የበጀት ገደብ ላይ መድረስ
- የማረጋገጫ መግባት/መውጣት
- የደመና ወኪል ክፍለ ጊዜ መፍጠር
- የMCP መሣሪያ ምዝገባ
- Webhook መፍጠር/መሰረዝ
- የኮታ ገንዳ/ዕቅድ ለውጦች (`quota.*` እርምጃዎች፣ Group B)
- የመድረክ ክስተቶች (ማዘመን፣ ማሰማራት)
- ክህሎት መጫን/ማስወገድ
በዚህ ዝርዝር ውስጥ የሌሉ ክስተቶች በኦዲት ምዝግብ ማስታወሻው ውስጥ ብቻ ይታያሉ።
### አዲስ ከፍተኛ-ደረጃ እርምጃ ማከል
`src/lib/audit/highLevelActions.ts`ን ያርትዑ እና የእርምጃውን ሕብረቁምፊ ወደ
`HIGH_LEVEL_ACTIONS` ያክሉ። ይህ PR ይፈልጋል (ዝርዝሩ ኮድ እንጂ በDB ሊዋቀር የሚችል አይደለም)።
ተዛማጁን አዶ ወደ `src/lib/audit/activityIcons.ts` ማከል ይቻላል።
---
## ማዘዋወር፦ `/dashboard/logs/activity`
የድሮው ዱካ `/dashboard/logs/activity` በ
`src/app/(dashboard)/dashboard/logs/activity/page.tsx` ውስጥ `permanentRedirect()`ን በመጠቀም በቋሚነት (HTTP 308) ወደ
`/dashboard/activity` ይዘዋወራል።
የድሮው የጎን አሞሌ ID `logs-activity`፣
የድሮውን ID የሚጠቅሱ የተጠቃሚ ቅድመ-ቅንብሮች እንዳይበላሹ፣ በ`HIDEABLE_SIDEBAR_ITEM_IDS`
ውስጥ ተጠብቋል (ነገር ግን ከ`SIDEBAR_DEFINITIONS` ተወግዷል)።
---
## i18n
በGroup B የታከሉ የስም ክልሎች፦
| የስም ክልል ቁልፍ | የሚሸፍነው |
| ----------------------- | -------------------------------------------------- |
| `sidebar.costsSection` | የወጪዎች ክፍል መለያ |
| `sidebar.activity` | የእንቅስቃሴ የጎን አሞሌ ንጥል |
| `sidebar.logsGroup` | የምዝግብ ማስታወሻዎች ንዑስ ቡድን መለያ |
| `sidebar.systemGroup` | የስርዓት ንዑስ ቡድን መለያ |
| `sidebar.costsOverview` | የወጪዎች አጠቃላይ እይታ ንጥል |
| `activity.*` | ሁሉም የእንቅስቃሴ ገጽ ሕብረቁምፊዎች (ርዕስ፣ ግሶች፣ ማጣሪያዎች፣ ባዶ ሁኔታ) |
የእውነት ምንጭ የሆኑ አካባቢያዊ ቋንቋዎች፦ `pt-BR` እና `en`። ሌሎቹ 40 አካባቢያዊ ቋንቋዎች
በ`next-intl` የመጠባበቂያ ዘዴ (በ`src/i18n/config.ts` ውስጥ የተዋቀረ) አማካኝነት ወደ
እንግሊዝኛ ይመለሳሉ።

600
docs/i18n/am/docs/architecture/QUALITY_GATES.md Normal file
View File

@@ -0,0 +1,600 @@
# Quality Gates Reference (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/QUALITY_GATES.md) · 🇸🇦 [ar](../../../ar/docs/architecture/QUALITY_GATES.md) · 🇦🇿 [az](../../../az/docs/architecture/QUALITY_GATES.md) · 🇧🇬 [bg](../../../bg/docs/architecture/QUALITY_GATES.md) · 🇧🇩 [bn](../../../bn/docs/architecture/QUALITY_GATES.md) · 🇨🇿 [cs](../../../cs/docs/architecture/QUALITY_GATES.md) · 🇩🇰 [da](../../../da/docs/architecture/QUALITY_GATES.md) · 🇩🇪 [de](../../../de/docs/architecture/QUALITY_GATES.md) · 🇬🇷 [el](../../../el/docs/architecture/QUALITY_GATES.md) · 🇪🇸 [es](../../../es/docs/architecture/QUALITY_GATES.md) · 🇪🇪 [et](../../../et/docs/architecture/QUALITY_GATES.md) · 🇮🇷 [fa](../../../fa/docs/architecture/QUALITY_GATES.md) · 🇫🇮 [fi](../../../fi/docs/architecture/QUALITY_GATES.md) · 🇫🇷 [fr](../../../fr/docs/architecture/QUALITY_GATES.md) · 🇮🇪 [ga](../../../ga/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [gu](../../../gu/docs/architecture/QUALITY_GATES.md) · 🇳🇬 [ha](../../../ha/docs/architecture/QUALITY_GATES.md) · 🇮🇱 [he](../../../he/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [hi](../../../hi/docs/architecture/QUALITY_GATES.md) · 🇭🇷 [hr](../../../hr/docs/architecture/QUALITY_GATES.md) · 🇭🇺 [hu](../../../hu/docs/architecture/QUALITY_GATES.md) · 🇦🇲 [hy](../../../hy/docs/architecture/QUALITY_GATES.md) · 🇮🇩 [id](../../../id/docs/architecture/QUALITY_GATES.md) · 🇳🇬 [ig](../../../ig/docs/architecture/QUALITY_GATES.md) · 🇮🇹 [it](../../../it/docs/architecture/QUALITY_GATES.md) · 🇯🇵 [ja](../../../ja/docs/architecture/QUALITY_GATES.md) · 🇬🇪 [ka](../../../ka/docs/architecture/QUALITY_GATES.md) · 🇰🇭 [km](../../../km/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [kn](../../../kn/docs/architecture/QUALITY_GATES.md) · 🇰🇷 [ko](../../../ko/docs/architecture/QUALITY_GATES.md) · 🇱🇹 [lt](../../../lt/docs/architecture/QUALITY_GATES.md) · 🇱🇻 [lv](../../../lv/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [ml](../../../ml/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [mr](../../../mr/docs/architecture/QUALITY_GATES.md) · 🇲🇾 [ms](../../../ms/docs/architecture/QUALITY_GATES.md) · 🇲🇹 [mt](../../../mt/docs/architecture/QUALITY_GATES.md) · 🇲🇲 [my](../../../my/docs/architecture/QUALITY_GATES.md) · 🇳🇵 [ne](../../../ne/docs/architecture/QUALITY_GATES.md) · 🇳🇱 [nl](../../../nl/docs/architecture/QUALITY_GATES.md) · 🇳🇴 [no](../../../no/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [or](../../../or/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [pa](../../../pa/docs/architecture/QUALITY_GATES.md) · 🇵🇭 [phi](../../../phi/docs/architecture/QUALITY_GATES.md) · 🇵🇱 [pl](../../../pl/docs/architecture/QUALITY_GATES.md) · 🇵🇹 [pt](../../../pt/docs/architecture/QUALITY_GATES.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/QUALITY_GATES.md) · 🇷🇴 [ro](../../../ro/docs/architecture/QUALITY_GATES.md) · 🇷🇺 [ru](../../../ru/docs/architecture/QUALITY_GATES.md) · 🇱🇰 [si](../../../si/docs/architecture/QUALITY_GATES.md) · 🇸🇰 [sk](../../../sk/docs/architecture/QUALITY_GATES.md) · 🇸🇮 [sl](../../../sl/docs/architecture/QUALITY_GATES.md) · 🇷🇸 [sr](../../../sr/docs/architecture/QUALITY_GATES.md) · 🇸🇪 [sv](../../../sv/docs/architecture/QUALITY_GATES.md) · 🇰🇪 [sw](../../../sw/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [ta](../../../ta/docs/architecture/QUALITY_GATES.md) · 🇮🇳 [te](../../../te/docs/architecture/QUALITY_GATES.md) · 🇹🇭 [th](../../../th/docs/architecture/QUALITY_GATES.md) · 🇹🇷 [tr](../../../tr/docs/architecture/QUALITY_GATES.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/QUALITY_GATES.md) · 🇵🇰 [ur](../../../ur/docs/architecture/QUALITY_GATES.md) · 🇺🇿 [uz](../../../uz/docs/architecture/QUALITY_GATES.md) · 🇻🇳 [vi](../../../vi/docs/architecture/QUALITY_GATES.md) · 🇳🇬 [yo](../../../yo/docs/architecture/QUALITY_GATES.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/QUALITY_GATES.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/QUALITY_GATES.md)
---
ይህ ሰነድ በOmniRoute ውስጥ ላሉ ሁሉም የCI ጥራት መግቢያዎች ዋና ማጣቀሻ ነው።
እያንዳንዱን መግቢያ፣ ምን እንደሚያረጋግጥ፣ በየትኛው የCI ሥራ ውስጥ እንደሚሠራ፣
የratchet መነሻ መስመር ወይም የማለፍ/የመውደቅ ፖሊሲ ይጠቀም እንደሆነ፣ እንዲሁም ግንባታውን የሚያግድ ወይም የምክር ብቻ እንደሆነ ይገልጻል።
ለአጭር ማጠቃለያ እና ለፈቃድ ዝርዝር ፖሊሲው፣ በ`AGENTS.md` ውስጥ ያለውን "የጥራት መግቢያዎች እና Ratchets" ክፍል ይመልከቱ።
ለወሳኝ ግምገማው፣ ለብስለት ምደባው፣ እና ከመሣሪያ ነፃ ለሆነው
የተመሳሳይ ሥርዓት ድግግሞሽ ዕቅድ፣
[የጥራት መግቢያ መመሪያ](../ops/QUALITY_GATE_PLAYBOOK.md)ን ይመልከቱ።
---
## የጌቶች ዝርዝር (~90 ስክሪፕቶች)
ስክሪፕቶቹ በ`scripts/check/` (የፖሊሲ ጌቶች) እና በ`scripts/quality/` (የratchet ሞተር) ስር ይገኛሉ።
የCI ዋና የእውነት ምንጭ `.github/workflows/ci.yml` ነው።
### የልቀት PR ፈጣን መንገድ (`quality.yml`)
`.github/workflows/quality.yml` ወደ `release/**` ያነጣጠሩ PRዎች ላይ ይሰራል። በዱካ የተጣሩ ፈጣን ጌቶችን በመጠቀም የአስተዋጽዖ አድራጊዎች ቅርንጫፎች እንዲቀጥሉ ያደርጋል፤ በተጨማሪም ለኮድ
ለውጦች አንድ የምክር ምርት-ግንባታ ምልክት ይሰጣል፦
| ሥራ | ወሰን | አጋጅ |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `Build (advisory)` | ረቂቅ ያልሆኑ የኮድ PRዎች እና የMergify ወረፋ ቅርንጫፎች፤ Node 24፣ `npm-ci-retry`፣ `check:node-runtime`፣ `OMNIROUTE_USE_TURBOPACK=1` ያለው `npm run build`፤ ምንም የታችኛው የጥራት ሥራ ስለማይጠቀምበት artifact አይሰቀልም | **ምክር ሰጪ** (`continue-on-error: true`፤ ከአንድ ሳምንት የተረጋጋ የልቀት-PR ሂደቶች በኋላ ያስወግዱት) |
| `Docs Gates (fast-path)` | የሰነድ/ኮድ PRዎች፤ የAPI ሰነዶች ማጣቀሻዎች እና docs-all | አዎ |
| `Fast Quality Gates` | የኮድ PRዎች፤ የማይለወጡ ፍተሻዎች፣ typecheck፣ የdashboard typecheck፣ ተጽዕኖ ያረፈባቸው የunit ፈተናዎች | አዎ |
| `Forgotten sibling tests` | የኮድ PRዎች፤ የተቀየሩ ሞጁሎች ወደ የማይለወጡ ተጠቃሚዎች እና ዕጩ sibling ፈተናዎች ይከታተላሉ፤ የbarrel እና የdynamic-import ዱካዎች እንደ ምክር ሰጪ ምርመራዎች ይዘገባሉ፣ ከተጠቀሱ የallowlist ልዩ ሁኔታዎች ጋር | **ምክር ሰጪ** |
| `Vitest (fast-path)` | የኮድ PRዎች፤ ፈጣን የvitest ስብስብ | አዎ |
| `Unit Tests fast-path` | የኮድ PRዎች፤ ባለ4-shard የunit ስብስብ | አዎ |
| `No new ESLint warnings` | የኮድ PRዎች፤ suppressionsን የሚያውቅ lint ጥበቃ | ከራስ ምንጭ ለሆኑ አዎ፣ ለforks ምክር ሰጪ |
| `Merge integrity (changelog + generated skills)` | ረቂቅ ያልሆኑ PRዎች፤ changelog እና የተፈጠሩ skill ማመሳሰል | ከራስ ምንጭ ለሆኑ አዎ፣ ለforks ምክር ሰጪ |
#### የተረሱ sibling ፈተናዎች ሪፖርት
`npm run check:forgotten-sibling-tests` ከፈተና-ተጽዕኖ ካርታው ጀርባ ያለውን import resolver እንደገና ይጠቀማል።
ለእያንዳንዱ የተቀየረ የምርት ሞጁል፣ ዕጩው
ፈተና በpull-request diff ውስጥ ከሌለ የተወሰኑ
`changed module/symbol -> static consumer -> candidate sibling test` ሰንሰለቶችን ይዘግባል። የMarkdown ማጠቃለያው እና የJSON ውጤቱ ማንኛውም አጋጅ ማሰማራት ከመጀመሩ በፊት ለመለካት እንደ
`forgotten-sibling-tests` workflow artifact ይቀመጣሉ።
የBarrel re-exports እና dynamic imports የresolution ምርመራዎች ብቻ ናቸው፤ በፍጹም
አጋጅ ግኝት አይፈጥሩም። የተገመገሙ ልዩ ሁኔታዎች በ
`config/quality/forgotten-sibling-allowlist.json` ውስጥ ይገኛሉ። እያንዳንዱ ግቤት consumerን እና ዕጩ
ፈተናውን መጥቀስ፣ የተወሰነ ምክንያት መስጠት እና ወደ GitHub issue ወይም pull request ማገናኘት አለበት። በስህተት የተቀረጹ ግቤቶች
በዝግ ሁኔታ ይከሽፋሉ። ልዩ ሁኔታዎች የተሰረዘ ዕጩ ፈተናን ወይም `.skip`/`.todo` የሚጨምር diffን ማፈን አይችሉም፤
የassertion ማዳከም እና ሌሎች masking በተናጥል አጋጅ በሆነው
`check:test-masking` ጌት ስር ይቆያሉ።
### ሥራ፦ `lint`
ወደ `main` በሚቀርብ እያንዳንዱ PR ላይ ይሰራል። ከከሸፈ mergeን ያግዳል።
| ስክሪፕት (`npm run ...`) | የሚያረጋግጠው | አጋጅ |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `check:node-runtime` | የNode.js ስሪት በሚደገፈው ክልል ውስጥ መሆኑን | አዎ |
| `check:cycles` | ዑደታዊ ኢምፖርቶችን — ሁሉንም `src/` + `open-sse/` ሞጁሎች | አዎ |
| `check:route-validation:t06` | በሁሉም ራውቶች ላይ የZod ስኪማዎች መኖራቸውን (Tier 6 ፖሊሲ) | አዎ |
| `check:any-budget:t11` | የ`@ts-expect-error // any` ብዛት ከተመደበው ገደብ እንደማያልፍ (Tier 11 catraca) | አዎ |
| `check:provider-consistency` | `providers.ts` ውስጥ ያለው እያንዳንዱ provider `providerRegistry.ts` ውስጥ ተዛማጅ ግቤት አለው (እና በተቃራኒውም፣ በ allowlist ውስጥ) | አዎ |
| `check:model-lifecycle` | በእጅ የሚያዙት ሦስቱ የ routing tables ከተመዘገበው lifecycle snapshot (#11503) ጋር ወጥነታቸውን ይጠብቃሉ፦ `FITNESS_TABLE` (`taskFitness.ts`)፣ `REGISTRY` ሊያስተላልፈው ለሚችለው ከአገልግሎት የወጣ id ነጥብ አይሰጥም፤ እያንዳንዱ የ`BUILT_IN_ALIASES` target በ`REGISTRY` ውስጥ ይገኛል እና ከ retired-id snapshot ውስጥ የለም፤ አሁንም በ`REGISTRY` ውስጥ ያለ እያንዳንዱ retired id ወደ ሌላ ይተላለፋል ወይም በ`allowedRetiredInCatalog` ውስጥ ተዘርዝሯል፤ እንዲሁም የ`DEFAULT_DEGRADATION_MAP` source ወይም target በዚያ snapshot ውስጥ retired ሆኖ አይታይም። ይህ፣ model በአሁኑ ጊዜ በቀጥታ በሚሰራ upstream እየቀረበ መሆኑን አያረጋግጥም። Offline — በእጅ እና በ`npm run quality:refresh-model-lifecycle` (network፤ ከCI ጋር አልተገናኘም) ከሚታደሰው `config/quality/model-lifecycle.json` ጋር ያነጻጽራል። `allowedRetiredInCatalog` ቀስ በቀስ የሚቀንስ ratchet ነው፦ ግቤት የሚጨመረው የመከታተያ issue ካለው ብቻ ነው። | አዎ |
| `check:fetch-targets` | በclient-side `src/` ውስጥ ያለው እያንዳንዱ `fetch("/api/...")` ወደ እውነተኛ `route.ts` ይዛመዳል | አዎ |
| `check:deps` | በrepo ውስጥ ባሉ ሁሉም `package.json` ፋይሎች ውስጥ በ`npm install` ሊጫኑ የሚችሉ deps በ`dependency-allowlist.json` ውስጥ ይገኛሉ፤ አዲስ ያልተሰኩ ወይም slopsquatted packages ምልክት ይደረግባቸዋል | አዎ |
| `audit:deps` | `npm audit` (root + electron) — ከፍተኛ/ወሳኝ advisories የሉም (ከosv `check:vuln-ratchet` ጋር ይደራረባል፤ Rationalization Backlogን ይመልከቱ) | አዎ |
| `check:lockfile` | የ`package-lock.json` integrity — https registry፣ integrity hashes፣ የhost overrides የሉም | አዎ |
| `check:licenses` | ለproduction dependencies የSPDX license የተፈቀዱ ዝርዝር | አዎ |
| `check:tracked-artifacts` | build artifacts / commit የተደረጉ `node_modules` symlinks አይኖሩም (በhusky pre-commit ውስጥም ይሰራል፤ pre-push ሆን ተብሎ ቀላል ተደርጓል — #6716) | አዎ |
| `check:vitest-exclusions` | እያንዳንዱ የVitest exclusion የtracking issue ስም ይጠቅሳል እና በ`config/quality/vitest-exclusions.json` ውስጥ ይገኛል (#13204) | አዎ |
| `check:file-size` | ምንም source file በextension የተወሰነውን ከፍተኛ መጠን አያልፍም (ratchet፦ የታገዱ ትልልቅ files በ`frozen` list ውስጥ) | አዎ |
| `check:error-helper` | በexecutors/handlers ውስጥ ያሉ error responses `buildErrorBody()` / `sanitizeErrorMessage()` ይጠቀማሉ (Hard Rule #12) | አዎ |
| `check:migration-numbering` | Migration SQL files ያለ ክፍተት ወይም ድግግሞሽ በቅደም ተከተል ቁጥር ተሰጥቷቸዋል | አዎ |
| `check:public-creds` | ከ`publicCreds.ts` ውጭ ቀጥተኛ OAuth `client_id`/`client_secret` ወይም Firebase Web ቁልፎች የሉም (ጥብቅ ደንብ #11) | አዎ |
| `check:db-rules` | ከ`src/lib/db/` ሞጁሎች ውጭ ጥሬ SQL የለም፤ ከ`localDb.ts` የሚደረጉ barrel-imports የሉም (ጥብቅ ደንቦች #2/#5) | አዎ |
| `check:known-symbols` | በdispatch ሰንጠረዦቻቸው ውስጥ የተመዘገቡ provider executors፣ routing strategies እና translators በዲስክ ላይ ካሉት ፋይሎች ጋር ይዛመዳሉ — ወላጅ-አልባ ወይም ያልታወጁ symbols የሉም | አዎ |
| `check:route-guard-membership` | child process የሚያስጀምር እያንዳንዱ route በ`isLocalOnlyPath()` ይመደባል (ጥብቅ ደንቦች #15/#17) | አዎ |
| `check:test-discovery` | በrepo ውስጥ ያለ እያንዳንዱ `*.test.ts` / `*.spec.ts` ፋይል ቢያንስ በአንድ test runner ይሰበሰባል (ratchet፦ በ`test-discovery-baseline.json` ውስጥ ያለው የወላጅ-አልባ ፋይሎች ዝርዝር መቀነስ ብቻ ይችላል) | አዎ |
| `check:agent-skills-sync` | የተመነጩ agent-skills artifacts ከምንጭ catalog ጋር ይዛመዳሉ (መዛባት የለም) |
| `check:provider-asset-provenance` | የprovider አርማዎች/assets የተመዘገበ provenance entry አላቸው |
| `lint:json` | የJSON ውቅር ፋይሎች ያለችግር መተንተናቸውን እና የማከማቻውን lint ደንቦች ማሟላታቸውን ያረጋግጣል |
| `typecheck:core` | ያለስህተት የTypeScript ማጠናቀር (የምክር ማስጠንቀቂያዎች ብቻ) | አዎ |
| `typecheck:noimplicit:core` | ጥብቅ `noImplicitAny` — ወደፊትን ያማከለ፤ ቀድሞ የነበሩ ብዙ የጥሪ ቦታዎች አሁንም ማብራሪያዎችን ይፈልጋሉ | **የምክር** (`continue-on-error: true`) |
| `check:dashboard-typecheck` | ለ`src/app/(dashboard)/**` የተወሰነ `tsc` (#7033) — የ`typecheck:core` በጥንቃቄ የተመረጠው የ27 ፋይሎች የፈቃድ ዝርዝር ምንም የዳሽቦርድ TSX አያካትትም፣ እንዲሁም `next build` በፍጹም የአይነት ማረጋገጫ አያደርግለትም (`next.config.mjs` `ignoreBuildErrors: true` ያቀናብራል)፤ ስለዚህ በዚያ ያሉ የተገለሉ መለያ ማገገሚያዎች (#6625/#6909) ለCI የማይታዩ ነበሩ። ልዩነቶችን ከተወሰነ የእያንዳንዱ ፋይል/የእያንዳንዱ TS ኮድ ብዛት መነሻ (`config/quality/dashboard-typecheck-baseline.json`፣ ከ`check:known-symbols` ጋር ተመሳሳይ የጊዜ ያለፈበትን የማስፈጸም ንድፍ) ጋር ያነጻጽራል — ከመነሻው ብዛት በላይ ያሉ አዲስ ስህተቶች ብቻ መግቢያውን ያሳንፋሉ፤ ቀድሞ የነበረ ስህተት ሲስተካከል በ`--update` መነሻውን ዝቅ ያድርጉ። | አዎ |
### ሥራ፦ `quality-gate`
ከ`test-coverage` በኋላ ይሰራል። ካልተሳካ ውህደትን ያግዳል።
| ስክሪፕት | የሚያረጋግጠው | አጋጅ |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `quality:collect` | `quality-metrics.json`ን ያወጣል (የESLint ማስጠንቀቂያዎች ብዛት፣ ከተዋሃደው shard ሪፖርት የተገኘ ሽፋን) | አዎ (ከratchet በፊት የሚሰራ) |
| `quality:ratchet` | በ`quality-baseline.json` ውስጥ ያለው እያንዳንዱ መለኪያ ወደኋላ አለመሄዱን ያረጋግጣል (የESLint ማስጠንቀቂያዎች ≤ መነሻ፤ ሽፋን ≥ መነሻ) | አዎ |
| `check:duplication` | የኮድ ድግግሞሽ (jscpd@4) በ`quality-baseline.json` ውስጥ ካለው መነሻ አይበልጥም | አዎ |
| `check:complexity` | የፋይል ደረጃ የዙራዊ ውስብስብነት ከገደቡ አይበልጥም (ዋና ESLint `complexity` + `max-lines-per-function`) | አዎ |
| `check:cognitive-complexity` | የግንዛቤ ውስብስብነት ratchet (`eslint-plugin-sonarjs`) — የተለየ የESLint ሂደት፤ CI ሁለቱንም አዋህዶ እንደ አንድ `check:complexity-ratchets` ደረጃ ያስኬዳል | አዎ |
| `check:dead-code` | ጥቅም ላይ ያልዋሉ ወደ ውጭ የሚላኩ ክፍሎች / ፋይሎች ratchet (knip) ከመነሻው አንጻር ወደኋላ አይሄድም | አዎ |
| `check:compression-budget` | የመጭመቂያ መለኪያ በጀት — የእያንዳንዱ ሞተር ዝቅተኛ የቶከን ቁጠባ ወደኋላ መሄድ የለበትም | አዎ |
| `check:type-coverage` | በአይነት የተገለጸው መቶኛ ratchet (`type-coverage`) ወደኋላ አይሄድም፤ `typecheck:noimplicit:core`ን በአብዛኛው ይሸፍናል | አዎ |
| `check:codeql-ratchet` | ክፍት የCodeQL ማንቂያዎች ብዛት ወደኋላ አይሄድም (በ`gh api` ያነባል፤ ቶከን ከሌለ በአግባቡ ይዘላል) — የማደሻ ድግግሞሽ እና በእጅ ማስጀመሪያ፦ ከታች ያለውን "CodeQL ratchet" ይመልከቱ | አዎ |
### ሥራ፦ `quality-extended`
መላው ሥራ የምክር ደረጃ ነው (`continue-on-error: true`)። በ-npm ላይ የተመሠረቱ የደረጃ መቆጣጠሪያዎች በተጨባጭ ይሰራሉ፤ ውጫዊ ስካነሮቹ በ`gh release download` በኩል ይጫናሉ፣ እና ባይነሪው አሁንም ከሌለ ራሳቸውን ይዘላሉ (በ0 ይወጣሉ)።
| ስክሪፕት | የሚያረጋግጠው | አጋጅ |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `check:circular-deps` | ዑደታዊ ጥገኛነቶች አለመኖራቸውን (dpdm) | **ምክር ሰጪ** |
| `check:bundle-size` | የጥቅሉ መጠን ከተቀመጠው ከፍተኛ ገደብ እንደማያልፍ | **ምክር ሰጪ** |
| `check:secrets` | የሚስጥር መረጃ ቅኝት (gitleaks) — ባይነሪው ከሌለ ይዘለላል | **ምክር ሰጪ** |
| `check:vuln-ratchet` | የጥገኛ ጥቅሎች ተጋላጭነቶች (osv-scanner) እንዳይባባሱ — ባይነሪው ከሌለ ይዘለላል | **ምክር ሰጪ** |
| `check:workflows` | የየሥራ ፍሰት ቅርጸት ምርመራ (actionlint + zizmor) — ባይነሪዎቹ ከሌሉ ይዘለላል | **ምክር ሰጪ** |
| `check:openapi-breaking` | የሕዝባዊ API ውል (`openapi.yaml`) ከመሠረታዊው ቅርንጫፍ (oasdiff) ጋር ሲነጻጸር ሰባሪ ለውጦች — `openapiBreaking=N` ያወጣል፤ oasdiff ከሌለ ወይም የመሠረቱ ዝርዝር መፍታት ካልተቻለ ይዘለላል | **ምክር ሰጪ** |
### ሥራ፦ `docs-sync-strict`
ወደ `main` በሚቀርብ እያንዳንዱ PR ላይ ይሰራል። ካልተሳካ ውህደትን ያግዳል።
| ስክሪፕት | የሚያረጋግጠው | አጋጅ |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `check:docs-all` | ከታች ያሉትን 6 ንዑስ መግቢያዎች በቅደም ተከተል የሚያስኬድ ዋና መግቢያ | አዎ |
| ↳ `check:docs-sync` | የCHANGELOG / OpenAPI / llm.txt ስሪት ወጥነት | አዎ |
| ↳ `check:docs-counts` | በጽሑፍ ውስጥ ያሉ ቁጥሮች (የአቅራቢዎች ብዛት፣ የፍልሰት ብዛት፣ ወዘተ) ከእውነተኛዎቹ ቁጥሮች የደረጃ መቆጣጠሪያ ክልል ውስጥ መሆናቸውን | አዎ |
| ↳ `check:env-doc-sync` | በ`.env.example` ውስጥ ያለ እያንዳንዱ የአካባቢ ተለዋዋጭ በሰነዶች ሰንጠረዥ ውስጥ መመዝገቡን፣ እና በተቃራኒውም | አዎ |
| ↳ `check:deprecated-versions` | በሰነዶች ውስጥ የተቋረጡ የስሪት ሕብረቁምፊዎች አለመኖራቸውን | አዎ |
| ↳ `check:doc-links` | በሰነዶች ውስጥ ያሉ ውስጣዊ የmarkdown አገናኞች ወደ እውነተኛ ፋይሎች መፍታታቸውን (`[text]`/`(path)` ቅርጽ) | አዎ |
| ↳ `check:fabricated-docs` | በሰነዶች ውስጥ የተጠቀሱ መስመሮች፣ የአካባቢ ተለዋዋጮች፣ የCLI ትዕዛዞች፣ የhook ስሞች እና የፋይል ዱካዎች በኮድ መዝገቡ ውስጥ መኖራቸውን። በ`--strict` በኩል ጥብቅ መግቢያ፤ ያለ ጠቋሚው ለስላሳ ውድቀት። | አዎ (በCI ውስጥ በ`--strict` በኩል) |
| `check:cli-i18n` | የCLI ትዕዛዝ ሕብረቁምፊዎች በሁሉም የi18n አካባቢ ፋይሎች ውስጥ መኖራቸውን | አዎ |
| `check:openapi-coverage` | የOpenAPI ዝርዝር ቢያንስ በደረጃ መቆጣጠሪያው የተወሰነውን ዝቅተኛ የእውነተኛ መስመሮች ሽፋን መሸፈኑን | አዎ |
| `check:openapi-security-tiers` | በ`openapi.yaml` ውስጥ ያሉ የደህንነት ደረጃ ማብራሪያዎች ከ`routeGuard.ts` ምደባዎች ጋር ወጥነት እንዳላቸው | **ምክር ሰጪ** |
| `check:openapi-routes` | በ`openapi.yaml` ውስጥ ያለ እያንዳንዱ ዱካ ወደ እውነተኛ `route.ts` መፍታቱን (የተፈበረከ መረጃን ለመከላከል) | አዎ |
| `check:docs-symbols` | በ`docs/**/*.md` ውስጥ ያለ እያንዳንዱ `/api/...` ማጣቀሻ ወደ እውነተኛ `route.ts` መፍታቱን (የተፈበረከ መረጃን ለመከላከል) | አዎ |
| `i18n translation drift` | በi18n አካባቢ ፋይሎች ውስጥ ያልተተረጎሙ ቁልፎች — ማስጠንቀቂያ ብቻ | **ምክር ሰጪ** |
### ሥራ፦ `i18n-ui-coverage`
| ስክሪፕት | የሚያረጋግጠው | አጋጅ |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `check-ui-keys-coverage` (ውስጠ-መስመር) | የUI i18n ቁልፍ ሽፋን ≥ 65% ነው | አዎ |
| `check-ui-value-drift` (ውስጠ-መስመር) | እንደገና የተጻፈ የእንግሊዝኛ **እሴት** ያረጀ ትርጉም እንደማይተው | አዎ |
| `check-new-key-coverage` (ውስጠ-መስመር) | **አዲስ** የእንግሊዝኛ ቁልፍ በእያንዳንዱ locale መተርጎሙን — የ`__MISSING__:` ምልክት ውድቅ ይደረጋል | አዎ |
| `check-translation-ratio` | በእያንዳንዱ locale ያለው የእውነተኛ ትርጉም ምጣኔ (ከእንግሊዝኛው ጋር ተመሳሳይ / ቦታ ያዥ / ከፈቃድ ዝርዝሩ ውጭ የጎደሉ ቅጠሎች) `config/quality/i18n-translation-baseline.json` + ትርፍን ማለፍ የለበትም | **አማካሪ** |
`fetch-depth: 0` ያስፈልገዋል — የvalue-drift መግቢያው `en.json`ን ከmerge base ጋር diff ያደርጋል።
#### `check-ui-value-drift` — ያረጀ-ትርጉም መግቢያ
ሌሎቹ መግቢያዎች በመዋቅራዊ ሁኔታ ሊያዩት የማይችሉትን አንድ የi18n ወደኋላ-መመለስ ይይዛል፦ አንድ የእንግሊዝኛ እሴት
እንደገና ሲጻፍ፣ ከ_ቀድሞው_ እንግሊዝኛ የተወሰዱት ትርጉሞች ሳይቀየሩ ይቀራሉ፤ ስለዚህ
እንግሊዝኛ ያልሆኑ ተጠቃሚዎች በእርግጠኝነት የተጻፈ፣ አሁን ግን የተሳሳተ ጽሑፍ ማንበባቸውን ይቀጥላሉ።
ይህ በእውነት ወደ ምርት ተልኳል። የAntigravity
የመግቢያ አጋዥ ሲጨመር (#5203) `oauthModal.googleOAuthWarning` እንደገና ተጽፏል፤ **ከ43 locales 39ኙ**
ኦፕሬተሮችን «ሙሉውን URL ቅዳና ከታች ለጥፍ» የሚል ጽሑፍ እንዲያነቡ አድርገው ቀሩ — ለዚያ provider ሊጠናቀቅ የማይችል ፍሰት ነው። ይህ
እስከ #8463 ድረስ ሳይስተዋል የቀረው፦
- `sync-ui-keys` የሚሞላው **የሌሉ** ቁልፎችን ብቻ እንጂ **ያረጁትን** ፈጽሞ አይደለም፤
- `check-ui-keys-coverage` የቁልፍ _መኖርን_ ስለሚቆጥር፣ ያረጀ ትርጉም እንደተሸፈነ ይቆጠራል፤
- `check-translation-drift` የ`docs/i18n/<locale>/**.md` ሰነድ መስተዋቶችን ይከታተላል —
`src/i18n/messages/*.json`ን ፈጽሞ አያነብም። ከ2026-09 ዳግም-ማመሳሰል ጀምሮ በjob `docs-sync-strict` ውስጥ አጋጅ ነው፦ ዋና ሰነድን ያርትዑ → `npm run i18n:run -- --files=<doc>` (በክፍል ደረጃ፣ ዝቅተኛ ወጪ)።
**Diffን የሚያገናዝብ እንጂ baselineን የተመሠረተ አይደለም።** በmerge base ላይ ያለውን `en.json` ከworking tree ጋር ያወዳድራል፤
የእንግሊዝኛ እሴቱ ለተቀየረበት ለእያንዳንዱ ቁልፍ፣ ሳይነካ የቀረ ትርጉም የያዘ ማንኛውም locale
ያረጀ ነው። ይህ ሆን ብሎ **ከዚህ በፊት የነበረውን እዳ ያስቀራል** — አንድ diff ለረጅም ጊዜ የኖረ ትርጉም
ከየትኛው የድሮ እንግሊዝኛ እንደመጣ ሊገልጽ ስለማይችል፣ መግቢያው የሚመዝነው
የአሁኑ ለውጥ የነካውን ብቻ ነው። አማራጩ (ለእያንዳንዱ ቁልፍ hash baseline) ~600 KB የሚያህል የሚመነጭ ፋይል፣
ከነባር ትልቁ baseline 3× የሚበልጥ፣ እና በእያንዳንዱ i18n PR የሚቀያየር ይሆናል።
እሱን ለማሟላት ሁለት መንገዶች አሉ፦
1. የተጎዱትን ትርጉሞች ያዘምኑ፣ ወይም
2. ወደ `__MISSING__:<new english>` ያቀናብሯቸው — runtime ከዚያ ትክክለኛውን እንግሊዝኛ
(`src/i18n/request.ts::deepMergeFallback`, #7258) ያቀርባል፣ ቁልፉም ለትርጉም ወረፋ ይይዛል።
የሕብረቁምፊው **ትርጉም** ከተቀየረ፣ **ቁልፉን እንደገና መሰየምን** ይምረጡ፦ አዲስ ቁልፍ
ያረጀ ትርጉም ሊወርስ አይችልም። #8463 የተጠቀመው ንድፍ ይህ ነው።
```bash
npm run i18n:check-value-drift # ጥብቅ (CI የሚያስኬደው)
npm run i18n:check-value-drift:warn # ሪፖርት ብቻ
BASE_REF=origin/release/vX.Y.Z npm run i18n:check-value-drift
```
የመሠረቱ catalog ሊነበብ በማይችልበት ጊዜ (base ref የሌለው shallow
clone) `check-openapi-breaking`ን በመከተል፣ `SKIP reason=base-unresolved` በማሳየት በ0 ይወጣል።
### Job፦ `i18n`
ሙሉ የi18n ማረጋገጫ matrix (ለእያንዳንዱ locale አንድ job)። መላው job አማካሪ ነው።
| ስክሪፕት | የሚያረጋግጠው | አጋጅ |
| ------------------------------- | ------------------------- | ------------------------------------------------ |
| `validate_translation.py quick` | በእያንዳንዱ locale የትርጉም ሙሉነት | **አማካሪ** (`continue-on-error: true` በመላው job ላይ) |
### Job፦ `pr-test-policy`
በpull requests ላይ ብቻ ይሰራል።
| ስክሪፕት | የሚያረጋግጠው | አጋጅ |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- |
| `check:pr-test-policy` | በ`src/`፣ `open-sse/`፣ `electron/`፣ ወይም `bin/` ውስጥ ያለ production code የሚቀይሩ PRዎች ፈተናዎችን ማካተት ወይም ማዘመን አለባቸው (ጥብቅ ደንብ #8) | አዎ |
| `check:test-masking` | የተቀየሩ የፈተና ፋይሎች ጠቅላላ የassert ብዛትን እንደማይቀንሱ ወይም የ`assert.ok(true)` tautologies እንደማይጨምሩ | አዎ |
| `check:pr-evidence` | የPR body ለለውጡ የtest/VPS ማስረጃ መጥቀሱን (የPR ጽሑፍን grep በማድረግ ጥብቅ ደንብ #18ን በራስ-ሰር ያስፈጽማል — ተሰባሪ ነው፣ Backlogን ይመልከቱ) | አዎ |
### Job፦ `test-vitest`
ከ`build` በኋላ ይሰራል። ካልተሳካ mergeን ያግዳል።
| ስብስብ | የሚያረጋግጠው | አጋጅ |
| ---------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `test:vitest` | MCP አገልጋይ (110 መሣሪያዎች)፣ autoCombo፣ መሸጎጫ — vitest አስኬጅ | አዎ |
| `test:vitest:ui` | የUI ክፍል ሙከራዎች — vitest አስኬጅ | **አጋጅ** — ቀድሞ የነበሩ ውድቀቶች በ`vitest.config.ts` ውስጥ በግልጽ ተገልለዋል፤ አዳዲስ ውድቀቶች ስራውን ያወድቃሉ |
### የምሽት የስራ ፍሰቶች (በጊዜ ሰሌዳ የሚከናወኑ፣ አማካሪ)
እነዚህ በcron የጊዜ ሰሌዳ (እና `workflow_dispatch`) ይሰራሉ፤ በPRዎች ላይ ፈጽሞ አይሰሩም። ሁሉም አማካሪ ናቸው።
| የስራ ፍሰት | የሚያረጋግጠው | አጋጅነት |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `nightly-property` | የfast-check ባህሪ ሙከራዎች በዘፈቀደ ዘር + ከፍተኛ የአስኬጅ ብዛት | **አማካሪ** |
| `nightly-resilience` | የheap ዕድገት መግቢያ፣ የብልሽት መርፌ ትርምስ፣ የk6 ጭነት/የረጅም ጊዜ ጭነት ሙከራ | **አማካሪ** |
| `nightly-llm-security` | የpromptfoo መርፌ መከላከያ (የማገድ ሁነታ) + የgarak መመርመሪያዎች (የአቅራቢ ምስጢር ከሌለ ይዘለላሉ) | **አማካሪ** |
| `nightly-schemathesis` | `docs/openapi.yaml`ን በመጠቀም በቀጥታ በሚሰራ OmniRoute ላይ የOpenAPI ውል ፈዘዝ ሙከራ (schemathesis) — የዝርዝር መግለጫ ጥሰቶችን / ያልተያዙ 500 ስህተቶችን ያጋልጣል (ደረጃ 8 B.4) | **አማካሪ** |
| `nightly-mutation` | በፈጣኑ የዩኒት መስመር ላይ የStryker ሚውቴሽን ሙከራ ውጤት — በሕይወት የሚተርፉ ሚውታንቶች ደካማ ማረጋገጫዎችን ያጋልጣሉ | **አማካሪ** |
| `nightly-compat` | በሚደገፉት `engines.node` ክልሎች ላይ የNode ሞተር ተኳኋኝነት ማትሪክስ | **አማካሪ** |
---
## የፍጥነት ምዕራፍ (2026-08-30 → v4.0 LTS): እያንዳንዱ መነሻ መስፈርት በ20% ላላ
የባለቤቱ ውሳኔ (2026-08-30)፦ እስከ v4.0 ሞዱላራይዜሽን ድረስ፣ የቴክኒክ ዕዳውን ገደብ
ከመጠበቅ ይልቅ የማድረስ ፍጥነት የበለጠ አስፈላጊ ነው። እያንዳንዱ **ቁጥራዊ** የራቼት መነሻ መስፈርት
ኦዲት ሊደረግበት በሚችል አንድ ዙር በ20% ላልቷል፣ እና ምዕራፉ በ`config/quality/quality-baseline.json`
ውስጥ ታውጇል፦
```json
"_policy": { "phase": "velocity", "since": "2026-08-30", "until": "4.0.0",
"relaxPct": 20, "requireTighten": false }
```
| የተለወጠው | ቦታ |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `metrics.*.value` — ዝቅተኛ መሆን የሚሻላቸው ቆጠራዎች ×1.2፣ ከፍተኛ መሆን የሚሻላቸው መቶኛዎች ÷1.2 (የሽፋን ዝቅተኛ ወለል 60 እንዳለ ተጠብቋል፣ `eslintErrors` 0 ሆኖ ይቆያል፣ `eslintWarnings` 0 → ከተቀዘቀዘው የማፈኛ ቆጠራ 20%) | `quality-baseline.json` (`_relax_velocity_2026_08_30` ማስታወሻ እያንዳንዱን ከበፊት → በኋላ ይዘረዝራል) |
| `count` ×1.2 / `percentage` ×1.2 | `complexity-baseline.json`, `duplication-baseline.json` |
| `cap`፣ `testCap`፣ እያንዳንዱ `frozen[*]` / `testFrozen[*]` የመስመር ገደብ ×1.2 | `file-size-baseline.json` |
| የእያንዳንዱ ፋይል / የእያንዳንዱ TS ኮድ ቆጠራዎች ×1.2 | `api-typecheck-baseline.json`, `dashboard-typecheck-baseline.json`, `open-sse-typecheck-baseline.json` |
| `THRESHOLD` 36 → 30 | `scripts/check/check-openapi-coverage.mjs` |
| `_policy.requireTighten === false` በሚሆንበት ጊዜ `--require-tighten` አማካሪ ይሆናል | `scripts/quality/check-quality-ratchet.mjs` |
| የሌሊቱ `bank-ratchet-shrinks` ባለበት ይቆማል (የተለካውን መቀነስ እንደ ክምችት በመመዝገብ ተጨማሪውን ክፍተት ይሽረው ነበር) | `.github/workflows/nightly-release-green.yml` |
የፈቃድ ዝርዝሮች (`eslint-suppressions.json`, `test-masking-allowlist.json`, `test-discovery-baseline.json`,
…) በጀቶች **አይደሉም** እና አልተነኩም። የማለፍ/የመውደቅ ፖሊሲ በሮች (ምስጢሮች፣ የSQL ደንቦች፣
የሰነዶች/አካባቢ ውል፣ የi18n እኩልነት፣ የዩኒት ሙከራዎች) አልተለወጡም — የወደቀ ሙከራ አሁንም የወደቀ ሙከራ ነው።
**መሣሪያዎች**
- `npm run quality:relax-baselines -- --pct 20 --note velocity_YYYY_MM_DD [--dry-run]` — የአንድ ጊዜ
ማላላት (`scripts/quality/relax-baselines.mjs`)፤ በተመሳሳይ ማስታወሻ ሁለት ጊዜ መሄድን አይፈቅድም።
- `npm run quality:headroom [-- --only deadExports,fileSize] [--json out.json --md out.md]` —
CI በሚለካበት መንገድ እያንዳንዱን ቁጥራዊ በር ይለካል እና ለእያንዳንዱ በር የቀረውን ክፍተት
ያትማል (`scripts/quality/baseline-headroom.mjs`)። የሌሊቱ `baseline-headroom` ሥራ ሰንጠረዡን
በቀጣይነት በሚዘመነው **📈 የመነሻ መስፈርት ክፍተት (የፍጥነት ምዕራፍ)** ጉዳይ ላይ ይለጥፋል፣ እና ማንኛውም በር
ከገደቡ በ10% ውስጥ ከሆነ ወይም ገደቡን ካለፈ `headroom-alert` መለያን ያክላል። ይህ ጉዳይ
የቅድሚያ ማስጠንቀቂያ ነው፦ በቀናት ውስጥ የሚሞላ በጀት ማለት ማላላቱን እየተጠቀመ ያለው
መላው ቡድን ሳይሆን ጥቂት PRs ናቸው — የችግሩን በር `_rebaseline_*` ማስታወሻዎች ይመልከቱ።
**የአዲስ ኮድ ሁነታ (በምትጽፉበት ጊዜ ያጽዱ) — ከ2026-08-30 ጀምሮ፣ ለPR ፈጣን መንገድ ብቻ**
በ`pull_request` ክስተቶች ላይ `quality.yml` `--base-ref <PR base SHA>`ን ወደ `check:file-size`፣
`check:complexity-ratchets` እና `check:dead-code` ያስተላልፋል። በዚያ ሁነታ በሩ HEADን ከ
merge-base ጋር **PR በነካቸው ፋይሎች ብቻ በመገደብ** ያነጻጽራል (`scripts/check/newCodeMode.mjs`፦
merge-base በጊዜያዊ `git worktree` ውስጥ ይፈጠራል፣ ESLint/knip በዚያ እና በHEAD ላይ ይሰራሉ፣
ከዚያም የእያንዳንዱ ፋይል ቆጠራዎች ልዩነት ይሰላል)፦
- **አጋጅ** — PRው በቀየራቸው ፋይሎች ውስጥ የሳይክሎማቲክ/ኮግኒቲቭ ጥሰቶችን ወይም ጥቅም ላይ ያልዋሉ exportsን ጨምሯል
(`complexityNewCode=`፣ `cognitiveComplexityNewCode=`፣ `deadExportsNewCode=` በሎጉ ውስጥ)፤
- **አማካሪ** — ዓለም አቀፉ ጠቅላላ ከተቀዘቀዘው መነሻ መስፈርት ጋር። በውርስ የመጣ ልዩነት ንጹሕ PRን ፈጽሞ
አያስወድቅም፤ ልዩነቱ በልቀት ማስታረቂያ ጊዜ እንደገና ይቀዘቅዛል እና በክፍተት ሥራው ይከታተላል።
`workflow_dispatch` አሂዶች፣ የrelease-green ሙሉ ፍተሻ እና የሌሊቱ የክፍተት ሥራ የPR መነሻ
የላቸውም፣ እና ፍጹም (ዓለም አቀፍ) ንጽጽሩን ይጠብቃሉ። ሽፋን፣ ድግግሞሽ እና የዓይነት ሽፋን ለአሁኑ
ዓለም አቀፍ ሆነው ይቆያሉ (መሣሪያዎቻቸው የእያንዳንዱን ፋይል ልዩነት በቀላሉ አያመነጩም) — ተመሳሳይ አያያዝ ሊደረግላቸው የሚችሉ እጩዎች ናቸው።
**ምዕራፉን በv4.0 መዝጋት (LTS = ከበፊቱ የበለጠ ጥብቅ፣ "ወደ መደበኛው መመለስ" አይደለም)**
1. በንጹህ `release/v4.0.0` የመጨረሻ ኮሚት ላይ፦ ለመዝገብ `npm run quality:headroom --json`ን ያስኪዱ፤ ከዚያ
`npm run quality:ratchet -- --update`፣ `check:file-size --update`፣
`check:complexity-ratchets --update`፣ `check:dead-code --update` እና የእያንዳንዱ typecheck ጌት
`--update` — እያንዳንዱ baseline ወደ ተለካው እሴት ዝቅ ይላል።
2. `_policy`ን ከ`quality-baseline.json` ይሰርዙ (`--require-tighten`ን እና የማታውን
ማጠራቀም እንደገና ያነቃል)፤ በ`check-openapi-coverage.mjs` ውስጥ `THRESHOLD = 36`ን (ወይም ከዚያ በላይ) ይመልሱ።
3. ሞዱላራይዜሽኑ ውጤት ባስገኘባቸው ቦታዎች ከተለካው እሴት በላይ ያጥብቁ፦ የፋይል መጠን `cap`ን ወደ 1000
(ወይም 800) ይመልሱ፣ የcoverage ዝቅተኛ ገደቦችን +5 ያድርጉ፣ እና ሞዱላራይዝ ለተደረጉት packages የdead exports ብዛትን 0 ያድርጉ።
## የRatchet መነሻ መስመር (`quality-baseline.json`)
የratchet ሞተሩ (`scripts/quality/check-quality-ratchet.mjs`) `quality-baseline.json`ን
በማንበብ አዲስ ከተሰበሰበው `quality-metrics.json` ጋር ያነጻጽረዋል። ከየራሱ epsilon
በላይ የሚያሽቆለቁል ማንኛውም መለኪያ buildን እንዲወድቅ ያደርጋል።
በአሁኑ ጊዜ ክትትል የሚደረግባቸው መለኪያዎች፦
| መለኪያ | አቅጣጫ | ትርጉም |
| --------------------- | ------ | -------------------------------- |
| `eslintWarnings` | `down` | የESLint ማስጠንቀቂያዎች ብዛት መጨመር የለበትም |
| `coverage.statements` | `up` | የstatement coverage መቀነስ የለበትም |
| `coverage.lines` | `up` | የline coverage መቀነስ የለበትም |
| `coverage.functions` | `up` | የfunction coverage መቀነስ የለበትም |
| `coverage.branches` | `up` | የbranch coverage መቀነስ የለበትም |
እውነተኛ ማሻሻያ ከተደረገ በኋላ መነሻ መስመሩን ለማዘመን፦
```bash
npm run quality:ratchet -- --update
git add quality-baseline.json
```
የ`--update` flag አሁን የተለኩትን እሴቶች ወደ `quality-baseline.json` ይጽፋል።
ይህን ፋይል መለኪያውን ካሻሻለው ለውጥ ጋር አብረው commit ያድርጉ። መነሻ መስመሩን
ሳያዘምን መለኪያን የሚያሻሽል PR በ`--require-tighten` ይያዛል (ደረጃ 6A.5፣
ትግበራው በመጠባበቅ ላይ ነው)።
### የCodeQL ratchet፦ የማደሻ ድግግሞሽ እና በእጅ ማስጀመር
`check:codeql-ratchet` **በጊዜ ሰሌዳ የሚታደሰውን የrepo ሁኔታ እንጂ በእያንዳንዱ PR የሚታደሰውን አያነብም።**
`gh api repos/diegosouzapw/OmniRoute/code-scanning/default-setup`
`state: configured`፣ `schedule: weekly` የሚል ውጤት ይሰጣል፦ ይህ የGitHub default-setup scan እንጂ
በእያንዳንዱ push የሚካሄድ analysis አይደለም። ውጤቱም፦ alertsን የሚያስተካክል PR merge ከተደረገ በኋላ፣
ቀጣዩ በጊዜ ሰሌዳ የተያዘ scan እስኪካሄድ ድረስ ratchet የቆየውን ከፍተኛ ብዛት ማንበቡን ይቀጥላል፤
ስለዚህ scanው እስኪያዘምን ድረስ በሁሉም ክፍት PR ላይ፣ የማስተካከያው PR ተከታይ ለውጦችንም ጨምሮ፣
ወደኋላ መመለስ እንዳለ ያሳያል።
**በእጅ ማደስ**፦ `gh workflow run codeql.yml --ref release/vX.Y.Z` analysisን እንደገና
ያስኬድና alertsን በደቂቃዎች ውስጥ እንደገና ያትማል። መጀመሪያ `.github/workflows/codeql.yml`ን
ያንብቡ፤ ራስጌው `workflow_dispatch`-ብቻ የሆነው **ከGitHub "default setup" ጋር ስለሚጋጭ**
መሆኑን ያብራራል (`CodeQL analyses from advanced configurations cannot be
processed when the default setup is enabled`)። የ`push`/`pull_request`/
`schedule` triggersን መልሶ ማስጀመር በመጀመሪያ **የowner እርምጃ** ይፈልጋል፦ Settings → Code security →
CodeQL: Default → Advanced። ያንን ለውጥ ሳያደርጉ `schedule:` trigger አይጨምሩ፤
ውድቀት የሚያጋጥማቸውን runs ብቻ ይፈጥራል።
**ብዛቱ ከቀነሰ በኋላ መነሻ መስመሩን ያጥብቁ**፦ `node scripts/check/check-codeql-ratchet.mjs
--update` አዲሱን የተለካ ብዛት ወደ `quality-baseline.json` →
`metrics.codeqlAlerts.value` ይጽፋል፤ በዚህም ratchet እንደገና ወደ ቀድሞው ከፍተኛ ገደብ
የሚደረግን ወደኋላ መመለስ በዝምታ እንዳይፈቅድ ያደርጋል። የተሰራ ምሳሌ (2026-09-02/03)፦ PR #12502
7 እውነተኛ alertsን አስተካክሏል (13 → 6 የተለኩ ክፍት alerts)፤ PR #12530 ከዚህ ጋር እንዲዛመድ
የቀዘቀዘውን መነሻ መስመር ከ11 → 6 አጥብቋል፤ ቀሪዎቹ 6 alerts ከዚያ በኋላ ለእያንዳንዱ alert
ምክንያት በመመዝገብ እስከ 0 ክፍት alerts ድረስ dismiss ተደርገዋል።
**Dismissals የoperator ውሳኔ ናቸው (ጥብቅ ደንብ #14)**፦ በdismissal አስተያየቱ ውስጥ ቴክኒካዊ
ምክንያቱን ሳይመዘግቡ የCodeQL alertን በፍጹም dismiss አያድርጉ፦ ለupstream-protocol መስፈርት `won't fix`፣
ለtest fixture `used in tests`፣ CodeQL ማየት ለማይችለው sanitizer `false positive`
(ቀዳሚ ምሳሌ፦ `docs/security/ERROR_SANITIZATION.md`)።
---
## የሙከራ ድጋሚ ማስኬጃ ፖሊሲ (WS5.4, v3.8.49)
ድጋሚ ማስኬድ ለእያንዳንዱ runner የተለየ እንጂ አጠቃላይ የሚሸፍን አይደለም — አጠቃላይ ድጋሚ ማስኬድ እውነተኛ የኋሊት መመለሶችን
ወደማይታዩ አልፎ አልፎ የሚከሰቱ ውድቀቶች ይቀይራቸዋል፦
| Runner | ፖሊሲ | ምክንያቱ |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Playwright (e2e) | በCI ውስጥ ብቻ `retries: 1`፣ ከ`trace: on-first-retry` ጋር | የአሳሽ/አውታረ መረብ ጊዜ በእውነት የማይወሰን ነው፤ አንድ ድጋሚ ማስኬድ ከtrace ጋር አልፎ አልፎ የሚከሰት ውድቀትን ሊመረመር ወደሚችል artifact ይቀይረዋል |
| Vitest | አጠቃላይ ድጋሚ ማስኬድ የለም። አልፎ አልፎ እንደሚወድቅ የተረጋገጠ ሙከራ ግልጽ የሆነ ለሙከራው-ብቻ ድጋሚ ማስኬጃ ያገኛል (በdiff ውስጥ የሚታይ፣ በPR የሚገመገም) | የለይቶ ማቆያ ዝርዝሩን በrepo ውስጥ ያቆየዋል፣ በፍጹም ድብቅ አይሆንም |
| node:test (unit) | በፍጹም ድጋሚ ማስኬድ የለም | አልፎ አልፎ የሚወድቅ unit test በሙከራው ውስጥ ያለ bug ነው — ያስተካክሉት፣ እንደገና በዕድል አያስኬዱት |
የአልፎ አልፎ ውድቀት telemetry ከተተገበረ በኋላ የሚፈለጉ SLOs (WS5.2/5.3)፦ ለእያንዳንዱ ሙከራ <1% የአልፎ አልፎ ውድቀት መጠን
("አሁን አስተካክል" ገደብ)፣ ለእያንዳንዱ pipeline ≥95% የማለፍ መጠን። የኢንዱስትሪ ማጣቀሻ እሴቶች —
በራሳችን መለኪያዎች መሠረት እንደገና ይስተካከሉ።
## በልቀት ደረጃ የRatchet መዛባት (WS5.5, v3.8.49)
አንድ ratchet (የፋይል መጠን፣ ውስብስብነት፣ eslint ማስጠንቀቂያዎች) በንጹሕ የልቀት
ጫፍ ላይ ወደኋላ ሲመለስ — ማለትም የmergeዎች **ጥምረት** ወደኋላ እንዲመለስ አድርጎታል፣ እና የትኛውም ነጠላ PR በራሱ branch ላይ
የኋሊት መመለሱን አያስከስተውም — ማስተካከያው የ**release captain ሲሆን፣ አንድ ጊዜ፣ በ
release branch ላይ** መደረግ አለበት፦ extraction/refactorን ይምረጡ፤ rebaseline ማድረግ ያለበት በሰነድ የተመዘገበ
የማስረጃ ግቤት ካለ ብቻ ነው። የጥምረት መዛባትን በአበርካች PR ላይ በፍጹም አይጫኑ፣ እና
ለእያንዳንዱ PR rebaseline በፍጹም አያድርጉ (ያ እውነተኛ የኋሊት መመለሶችን ይደብቃል)። መጀመሪያ ለይተው ይወቁ፦ PRዎ እንዳስከተለው ከመገመትዎ በፊት በprobe worktree ውስጥ
በንጹሑ ጫፍ ላይ ቀዩን ውጤት እንደገና ያስከስቱ።
## የRatchet መቀነሶችን ማከማቸት — ወደታች ያለው አቅጣጫ (#8584)
ratchet በግማሽ ብቻ አውቶማቲክ ነው፣ እሱም የተሳሳተው ግማሽ ነው። capን **ማሳደግ**
አሥር ሰከንድ የሚወስድ በእጅ የሚደረግ JSON አርትዖት ሲሆን ቀይ PRን ለመክፈት ፈጣኑ መንገድ ነው።
አንዱን **መቀነስ** ግን አንድ ሰው `--update`ን አስኪዶ ውጤቱን commit እንዲያደርግ ይጠይቃል — እና
የ`bank-ratchet-shrinks` job እስኪተገበር ድረስ ይህን የሚያስኬድ workflow አልነበረም። የተለካው ውጤት
(2026-07-25)፦ 18 frozen ፋይሎች አስቀድመው ከ800-line የአዲስ ፋይል cap ጋር እኩል ወይም ከዚያ በታች ሲሆኑ፣ ከሁሉ የከፋው
በ132× (`src/shared/validation/schemas.ts`፣ 19 መስመሮች 2,523 capን የተሸከሙ) ነበር፤
የውስብስብነት ጣሪያው በ~37 rebaseline ማስታወሻዎች ውስጥ `1794 → 2169` ከፍ አለ፣ በትክክል አንድ
መቀነስ (−1) ብቻ ነበረው፤ እና "በቀጣዩ ዙር በ`--update` አጥብቅ" 31 ጊዜ ተጽፎ አንድ ጊዜ
ብቻ ተከበረ። ያስገኘው ኮድ ከጠፋ በኋላም የሚቆይ cap እያንዳንዱን የተጠናቀቀ decomposition በጸጥታ
ቀጥሎ ፋይሉን ለሚያርትዕ ሰው የዕድገት ፈቃድ ያደርገዋል።
`nightly-release-green.yml` → job **`bank-ratchet-shrinks`** ያንን ዑደት ይዘጋል፦
| | |
| -------- | ---------------------------------------------------------------------------------------------- |
| የሚሰራበት | `schedule` (3×/day) + `workflow_dispatch` — ሆን ተብሎ **`push` አይደለም** |
| የሚለካው | ከፍተኛውን `release/vX.Y.Z`፣ ከ`release-green` ጋር ተመሳሳይ resolution + injection guard |
| የሚጽፈው | `check:file-size --update` እና `check:complexity-ratchets --update` (ሁለቱም በአወቃቀራቸው መቀነስ-ብቻ ናቸው) |
| የሚያረጋግጠው | `npm run check:ratchet-bank` (`scripts/quality/verify-ratchet-bank.mjs`) |
| የሚልከው | አንድ ሁልጊዜ-ወቅታዊ PR ወደ release branch — በግድ የሚዘምን፣ በፍጹም spam የማይደረግ |
ማከማቸቱ ለእያንዳንዱ push ከመሆን ይልቅ በቡድን ይከናወናል፤ ምክንያቱም የlatency መስፈርት የለውም (በ8h ውስጥ
የተከማቸ መቀነስ በቂ ነው)፣ ለእያንዳንዱ merge ማስኬድ ግን በmerge ዘመቻዎች ወቅት PR branchን ደጋግሞ
እንደገና ይገነባ እና በእያንዳንዱ ጊዜ ለሙሉ ESLint ማለፊያ ወጪ ይከፍላል። ማግኘቱ በ
push (`release-green`) ላይ ይቆያል፤ በቡድን የሚከናወነው ማከማቸቱ ብቻ ነው።
### የደህንነት አረጋጋጭ
jobው ያለ ክትትል ወደ baselines ይጽፋል፣ ስለዚህ `verify-ratchet-bank.mjs` ይህን
ተቀባይነት ያለው ያደርገዋል። ከ`--update` በኋላ ያለውን tree ከ`HEAD` ጋር diff ያደርጋል፣ እና እያንዳንዱ ለውጥ
ከሚከተሉት አንዱ ካልሆነ **ምንም commit ከመኖሩ በፊት jobውን ያቋርጣል** — ምንም PR አይከፍትም፦
- የ`frozen` / `testFrozen` ቁጥራዊ ግቤት **የተቀነሰ** ወይም **የተወገደ**
- `complexity-baseline.json` → `count` **የተቀነሰ**
- `quality-baseline.json` → `metrics.cognitiveComplexity.value` **የተቀነሰ**
ሌላ ማንኛውም ነገር ያወድቃል፦ ቁጥር ማሳደግ፣ ግቤት መጨመር፣ `cap`/`testCap`ን መቀየር፣ ወይም
የ`_rebaseline_*` ማስታወሻን መሰረዝ/እንደገና መጻፍ (እነዚያ ማስታወሻዎች እያንዳንዱ ጣሪያ ለምን
እንደሚኖር የሚገልጹ የኦዲት ዱካዎች ሲሆኑ ከፋይል ግቤቶቹ ጋር በተመሳሳዩ `frozen` object ውስጥ ይቀመጣሉ)።
capን ማሳደግ የሚችል bot ከአሁኑ ሁኔታ በእጅጉ የከፋ ይሆናል። የኋሊት መመለስ
መከላከያ፦ `tests/unit/verify-ratchet-bank.test.ts`።
jobው ወደ `release/*` በፍጹም push አያደርግም — PRን የሚያዋህደው ሰው ነው፣ ስለዚህ የተሳሳተ መለኪያ
ሳይገመገም ሊገባ አይችልም።
## የAllowlist ፖሊሲ
ቀድሞ በነበሩ ጥሰቶች ምክንያት ሊወድቅ የማይችል እያንዳንዱ gate የተወሰነ allowlist
ይጠቀማል (ለምሳሌ፣ `KNOWN_STALE_DOC_REFS`፣ `KNOWN_MISSING`፣ `KNOWN_RAW_SQL`)። ፖሊሲው፦
**ዋናውን መንስኤ ያስተካክሉ፤ allowlistን ጥሰቱ ቀድሞ የነበረ እና
በዚያው PR ውስጥ ሊስተካከል የማይችል ከሆነ ብቻ ይጠቀሙ።**
ወደ allowlist ግቤት ሲጨምሩ፦
1. ምክንያቱን የሚያብራራ አስተያየት ያካትቱ።
2. የክትትል issueውን ይጥቀሱ (ለምሳሌ፣ `// #3498 — የደረጃ 2 ባህሪ፣ እስካሁን አልተተገበረም`)።
3. ጥሰቱን በሚያስተካክለው PR ውስጥ ግቤቱንም ያስወግዱ — ንቁ ጥሰትን ከእንግዲህ
የማይገታ ያረጀ ግቤት በራሱ ጉድለት ነው (6A.3 stale-enforcement ከተተገበረ በኋላ
ባለቤት በሌለው allowlist ግቤት ምክንያት gateውን ያሳክታል)።
ሙከራዎችን በፍጥነት ለማሳለፍ የallowlist ግቤቶችን **አይጨምሩ**። እያደገ ያለ allowlist ያለው
አረንጓዴ gate ስለ ጥራት የተሳሳተ እምነት ይፈጥራል።
### በእርስዎ PR ላይ gate ሲወድቅ
1. **የgateውን ውጤት በጥንቃቄ ያንብቡ** — ደንቡን የጣሰው የትኛው ፋይል ወይም symbol እንደሆነ
በትክክል ይነግርዎታል።
2. **ጥሰቱን ያስተካክሉ** — አብዛኞቹ gates ኮዱ ትክክል እንደሆነ
የሚያልፉ ተወስነው የሚሠሩ የfilesystem ፍተሻዎች ናቸው።
3. **ጥሰቱ ቀድሞ የነበረ ከሆነ** (ማለትም፣ እርስዎ ያላስገቡት ነገር ግን gateው አሁን
የሚሸፍነው ከሆነ)፦ የምክንያት አስተያየት እና የክትትል issue ያለው የallowlist ግቤት ያክሉ።
4. **gateው ratchet ከሆነ** (coverage፣ ESLint warnings፣ duplication፣ complexity)፦
ለውጥዎ መለኪያውን አባብሶታል። መሠረታዊውን ችግር ያስተካክሉ፣ ወይም (አልፎ አልፎ) ለውጡ
ሆን ተብሎ የተደረገ እና የመለኪያው መቀነስ ተቀባይነት ያለው ከሆነ
`npm run quality:ratchet -- --update`ን ያስኪዱ — ነገር ግን ምክንያቱን በPR መግለጫው ውስጥ ይመዝግቡ።
5. **የምክር gates** (`continue-on-error: true`) ለመረጃ ብቻ ናቸው — mergeን አያግዱም፣
ነገር ግን በCI ማጠቃለያው ውስጥ ይታያሉ። ሆኖም ያስተካክሏቸው።
---
## አዲስ Gate ማከል
1. `scripts/check/check-<name>.mjs`ን (ወይም `.ts`) ይፍጠሩ። የፖሊሲ gates በ0/1 ይወጣሉ።
Ratchet-style gates `collect-metrics.mjs`ን በመጠቀም መለኪያን ወደ `quality-metrics.json` ያስገባሉ።
2. `"check:<name>": "node scripts/check/check-<name>.mjs"`ን ወደ `package.json` ያክሉ።
3. በተገቢው job ስር በ`.github/workflows/ci.yml` ውስጥ ያገናኙት
(policy → `lint` ወይም `docs-sync-strict`፤ ratchet → `quality-gate`)።
4. allowlist ካለው፣ ያረጁ ግቤቶች በራስ-ሰር እንዲገኙ
`reportStaleEntries()`ን ከ`scripts/check/lib/allowlist.mjs` ይተግብሩ።
5. የgateውን የማግኘት ሎጂክ የሚሸፍን ሙከራ በ`tests/unit/build/` ውስጥ ይጻፉ።
6. ይህን ሰነድ ያዘምኑ (ወደ ተገቢው የjob ሰንጠረዥ አንድ ረድፍ ያክሉ)።
---
## የAgent መሣሪያዎች፦ LSP-in-the-loop (opt-in)
ከCI gates በተጨማሪ፣ OmniRoute **opt-in** የሆነ `agent-lsp` scaffold
(በፕሮጀክት ደረጃ ያለ `.mcp.json`፣ Fase 7 Task 15) ይዞ ይመጣል። TypeScript language serverን ለcoding agents ለማጋለጥ `.mcp.json`ን
ይፍጠሩ፤ ይህም ኮድ ከመጻፋቸው **በፊት** symbols /
diagnosticsን እንዲፈቱ ያደርጋል — የ"የተፈጠረ symbol" ስህተቶችን ከመነሻቸው የሚቀንስ፣
ከ`typecheck:core` ጋር የሚሠራ compile-before-claim አጋዥ ነው። ሆን ተብሎ
በራስ-ሰር እንዳይጫን ተደርጓል (የMCP↔LSP bridgeን እርስዎ ይመርጣሉ እና ያረጋግጣሉ)፤ የተበላሸ ግቤት የግንኙነት
ስህተትን ብቻ ይመዘግባል እንጂ sessionsን ፈጽሞ አያቋርጥም።
---
## የማቀላጠፍ የኋላ ቀር ሥራዎች (የROI ግምገማ — ደረጃ 9 ሞገድ 3)
ይህ ዝርዝር በ2026-06-17 ከ`ci.yml` ጋር ተመሳክሯል (ቀዳሚው ስሪት
`audit:deps`፣ `check:tracked-artifacts`፣ `check:lockfile`፣ `check:licenses`፣
`check:dead-code`፣ `check:cognitive-complexity`፣ `check:type-coverage`፣
`check:codeql-ratchet`፣ `check:pr-evidence`ን አላካተተም ነበር)። በተመሳከረው ስብስብ ላይ የተደረገ የROI ግምገማ
የሚከተሉትን የማቀላጠፍ እጩዎች ለይቷል። **ውህደቶቹ ሜካኒካዊ የCI
ለውጦች ናቸው፤ ማስገደጃ ለውጦቹ/ማስወገዶቹ ለኦፕሬተሩ የተተዉ የፖሊሲ ውሳኔዎች ናቸው።** ከታች ያለው ምንም ነገር
እስካሁን አልተተገበረም።
**ከላይ ያልተመዘገቡ ተጨማሪ ነገሮች** (አማካሪ፣ ዝቅተኛ ምልክት ያላቸው)፦ የ`docs-lint` ሥራ
(markdownlint + Vale፣ ሙሉው ሥራ `continue-on-error`) እና ራሳቸውን የቻሉት የስካነር የሥራ ፍሰቶች
`semgrep.yml` / `codeql.yml` / `scorecard.yml`። `semgrepFindings: 0` በ
`quality-baseline.json` ውስጥ አለ፣ ነገር ግን በ`ci.yml` ውስጥ ከአጋጅ ራቸት ጋር አልተገናኘም — መለኪያው
በአሁኑ ጊዜ ወላጅ አልባ ነው።
### ማዋሃድ / ድግግሞሽን ማስወገድ (ሜካኒካዊ፣ ዝቅተኛ ስጋት)
እያንዳንዱ እጩ በ2026-06-17 በነበረው ቀጥታ የጌት ሁኔታ ላይ ተረጋግጧል (እመን-ግን-አረጋግጥ)፤
ብዙ “ግልጽ” የሚመስሉ ውህደቶች እዳን የሚደብቁ ሆነው ተገኝተዋል እና **ያለ ችግር በቀጥታ የሚተኩ አይደሉም**።
- **`check:docs-sync` ሁለት ጊዜ ይሠራል** — በ`lint` ሥራ ውስጥ ራሱን ችሎ እና እንደገና በ`check:docs-all` (`docs-sync-strict`) እና በhusky pre-commit hook ውስጥ። ✅ **ተጠናቋል** — ራሱን የቻለው የ`lint` ጥሪ ተወግዷል።
- **የCVE ቅኝት** — ❌ **ንጹሕ ውህደት አይደለም።** `audit:deps` በማንኛውም ከፍተኛ/ወሳኝ CVE ላይ በጥብቅ ይወድቃል፤ `check:vuln-ratchet` (osv) የሚወድቀው ከመነሻ መስመሩ ጋር ሲነጻጸር _ማሽቆልቆል_ ሲኖር ብቻ ነው (በአሁኑ ጊዜ 1 MODERATE)። የተለያየ ትርጉም አላቸው — `audit:deps`ን ማስወገድ ፍጹሙን የከፍተኛ/ወሳኝ ጌት ያስቀራል። ሁለቱንም ያቆዩ።
- **የዑደት ማወቂያ** — ❌ **ንጹሕ ውህደት አይደለም።** `check:circular-deps` (dpdm) **91 ዑደቶችን** ያሳውቃል (አማካሪ የሆነውም ለዚህ ነው)፤ መጀመሪያ እነሱን ሳይፈታ ወደ አጋጅነት ማሳደግ አይቻልም፣ እንዲሁም አረንጓዴ ከሆነውና በጥንቃቄ ከተመረጠው `check:cycles` የበለጠ ሰፊ ወሰን አለው። `check:cycles`ን አጋጅ አድርገው ያቆዩ፤ 91ዱን የdpdm ዑደቶች መፍታት የራሱ የኋላ ቀር ሥራ ነው።
- **ውስብስብነት** — ✅ **ተጠናቋል** (`check:complexity-ratchets` / `eslint.complexity-ratchets.config.mjs`)፦ አንድ የESLint ዳሰሳ፣ በruleId ይቆጥራል፣ ስለዚህ የcyclomatic+max-lines እና cognitive መነሻ መስመሮች ተለያይተው ይቆያሉ፤ ነጠላዎቹ `check:complexity` / `check:cognitive-complexity` ለአካባቢያዊ `--update` ይቆያሉ።
- **የ`/api` ፀረ-ቅዠት** — ✅ **ተጠናቋል** (`check:api-docs-refs` + `scripts/check/lib/apiRoutes.mjs`)፦ አንድ የ`src/app/api` FS ቆጠራ፣ openapi-routes + docs-symbols አሁንም ራሳቸውን ችለው ሪፖርት ያደርጋሉ፤ ነጠላዎቹ ለአካባቢያዊ ማስኬዶች ይቆያሉ።
- **`check:node-runtime` በ11 ሥራዎች ውስጥ ይሠራል** — ⚠️ **ዝቅተኛ ROI።** እያንዳንዱ የተለየ runner ነው፣ እና ምርመራው <1s ነው፤ አጠቃላይ ቁጠባው ~10s ሲሆን፣ በእያንዳንዱ ሥራ ያለውን ርካሽ መከላከያ ማጣትን አያካክስም። ለዚህ ለውጥ የሚደረገው ጥረት ዋጋ የለውም።
- **በCI lint ላይ `typecheck:noimplicit:core`** — ✅ **ከlint ሥራ ተወግዷል** (አማካሪ `continue-on-error` ነበር)፤ አጋጁ የዓይነት ወሰን `typecheck:core` + `check:type-coverage` ነው። አካባቢያዊው ስክሪፕት ተይዟል።
### ማስገደጃን መቀየር / መወሰን (የኦፕሬተር ፖሊሲ)
- `check:openapi-security-tiers` (አማካሪ) — ❌ **በንጽሕና ወደ አጋጅነት ሊቀየር አይችልም።** በ0 ይወጣል፣ ነገር ግን በ`LOCAL_ONLY_API_PREFIXES` ስር ያሉ በርካታ የ`traffic-inspector` መንገዶች የ`x-loopback-only: true` ማብራሪያ እንደሌላቸው ያስጠነቅቃል። ማስገደድ በመጀመሪያ እነዚያን ማብራሪያዎች ወደ`openapi.yaml` ማከልን ይጠይቃል።
- `typecheck:noimplicit:core` (አማካሪ) — በአብዛኛው በአጋጁ `check:type-coverage` ራቸት ተሸፍኗል። ወደ ራቸት ይቀይሩት ወይም ተደጋጋሚውን ሁለተኛ የ`tsc` ማስኬድ ያስወግዱ።
- `test:vitest:ui` (አሁን **አጋጅ**) — ቀድሞ የነበሩ ውድቀቶች በ`vitest.config.ts` ውስጥ በ`// #8618` የክትትል አስተያየቶች በግልጽ ተገልለዋል፤ አዳዲስ ውድቀቶች ሥራውን ያወድቃሉ።
- `check:secrets` (gitleaks፣ በ3 በሰነድ የተመዘገቡ የሐሰት-አዎንታዊ ውጤቶች ላይ የቀዘቀዘ አጋጅ ራቸት) — 0 ላይ ለመድረስ 3ቱን allowlist ያድርጉ፣ ወይም ወደ አማካሪነት ዝቅ ያድርጉት። ከGitHub ቤተኛ secret-scanning + `check:public-creds` ጋር ይደራረባል።
- `check:pr-evidence` (አጋጅ፣ የPR-body ጽሑፍን በgrep ይፈልጋል) — ከፍተኛ የሐሰት-አዎንታዊ ስጋት አለው፤ ከተወገደ የHard Rule #18 ማስፈጸሚያን ያዳክማል፣ ስለዚህ ይህ እውነተኛ የፖሊሲ ውሳኔ ነው።
- `semgrep` (ራሱን የቻለ አማካሪ) — ለOWASP ምድቦች ከCodeQL ጋር ይደራረባል፤ መነሻ መስመሩን ከራቸት ጋር ያገናኙ ወይም ያስወግዱት።
---
## ተዛማጅ ሰነዶች
- የአቅርቦት ሰንሰለት (provenance፣ SBOM፣ Trivy፣ Scorecard)፦ [`docs/security/SUPPLY_CHAIN.md`](../security/SUPPLY_CHAIN.md)
#### `check-key-completeness` — የቁልፍ-ስብስብ እኩልነት መቆጣጠሪያ
`scripts/i18n/check-key-completeness.mjs` (`npm run i18n:check-keys`፣ job `i18n-ui-coverage`)።
የእያንዳንዱን `src/i18n/messages/<locale>.json` የመጨረሻ ደረጃ ቁልፍ ስብስብ ከ`en.json` ጋር ያነጻጽራል፣ እና
ቁልፉ መቼ እንደታከለ ሳይመለከት በማንኛውም የጎደለ ወይም ተጨማሪ የመጨረሻ ደረጃ ቁልፍ ላይ ይወድቃል። `__MISSING__:` ቦታ-ያዥ ምልክቶች
እንዳሉ ይቆጠራሉ (ይዘታቸው የሬሾ መቆጣጠሪያው ጉዳይ ነው)። ይህ በልዩነት/መቶኛ ላይ የተመሠረቱትን
ሁለት መቆጣጠሪያዎች ሙሉ በሙሉ ያሟላል፦ `check-ui-keys-coverage` ለእያንዳንዱ
locale የ80 % ዝቅተኛ ገደብ ያስፈጽማል (ከ~13,000 ውስጥ 43 ቁልፎች ቢጎድሉም አሁንም 99.7 % ይነበባል)፣ እና `check-new-key-coverage`
PR ወደ `en.json` የሚያክላቸውን ቁልፎች ብቻ ይገመግማል። የlocale ቡድን ቅርንጫፉ በተፈጠረበት ቀን ካለው `en.json`
የሚመነጭ ሲሆን፣ base አዳዲስ ቁልፎችን ማከሉን ሲቀጥል ለቀናት ትርጉም ያከናውናል፤ የቡድኑ PR ራሱ
ምንም ቁልፍ አይጨምርም፣ ስለዚህ batch 1 (#13044) በዘጠኝ locales 43 ቁልፎች ጎድለውት
እና batch 2 (#13660) በስምንት locales 10 ቁልፎች ጎድለውት ሲዋሃዱ (2026-09-15) ሁለቱም ተዛማጅ መቆጣጠሪያዎች ዝም ብለው ቀርተዋል። ቀይ ስህተትን በ
`node scripts/i18n/sync-ui-keys.mjs --locale=<codes> --translate-markers` ያስተካክሉ፤ `extra` የመጨረሻ ደረጃ ቁልፍ
ምንጩ እንዳስወገደው ያመለክታል — ከlocale ይሰርዙት። `--warn` ሳያወድቅ ሪፖርት ያደርጋል።
`--catalog=cli` በ`bin/cli/locales` ላይ ተመሳሳዩን ንጽጽር ያካሂዳል (`npm run i18n:check-keys:cli`)፤
ሁለቱም ደረጃዎች በjob `i18n-ui-coverage` ውስጥ ይገኛሉ።
#### `check-new-key-coverage` — የአዲስ-ቁልፍ i18n መቆጣጠሪያ
የ`check-ui-value-drift` ተዛማጅ መቆጣጠሪያ ነው። ያኛው፣ ትርጉሞቹ ሳይዘምኑ የቀረ የእንግሊዝኛ እሴት **እንደገና ሲጻፍ**
ይለያል፤ ይህኛው ደግሞ አንዳንድ locales ሳይቀበሉት የቀረ የእንግሊዝኛ ቁልፍ **ሲታከል**
ይለያል።
`check-ui-keys-coverage` ይህን ዓይነት ማየት አይችልም፦ ለእያንዳንዱ locale የመቶኛ ዝቅተኛ ገደብ ያስፈጽማል፣ እና
ከ~13,000 የመጨረሻ ደረጃ ቁልፎች ውስጥ አሥራ አንዱ ቢጎድል ሽፋኑ 99.9% ሆኖ ይቀራል። የእያንዳንዱ ቋንቋ መቶኛ
“ይህ ባህሪ ሳይተረጎም ተለቀቀ” የሚለውን መግለጽ አይችልም — አንድ ሙሉ ባህሪ ምንም
ጽሑፍ ሳይኖረው በአዲስ locale ውስጥ ሊገባ እና ቁጥሩን ፈጽሞ ላይቀይር ይችላል።
ይህ የሚወክለው ክስተት፦ የOrchestration Canvas Phase 3 አሥራ አንዱን ቁልፎች በወቅቱ
በነበሩት 42 locales ተርጉሟል። ከሰዓታት በኋላ የEU-ቋንቋ ቡድን (#13044) repoውን
ወደ 51 locales አሳደገ፣ እና ዘጠኙ አዲስ ገቢዎች (`el`፣ `et`፣ `ga`፣ `hr`፣ `lt`፣ `lv`፣ `mt`፣ `sl`፣ `sr`)
እነዚህን ፈጽሞ አልተቀበሉም። `deepMergeFallback` በጎደለ ቁልፍ ምትክ እንግሊዝኛን ያስገባል፣ ስለዚህ የብልሽቱ ሁኔታ
ባዶ UI ሳይሆን ያልተተረጎመ UI ነበር — እውነተኛ፣ እና በአወቃቀሩ ምክንያት ዝምተኛ።
እንደ ተዛማጅ መቆጣጠሪያው ይህም **ልዩነትን የሚያውቅ** ነው፤ በmerge base ላይ ያለውን እንግሊዝኛ ከworking
tree ጋር ያነጻጽራል፣ ስለዚህ ቀድሞ የነበሩ ክፍተቶች ባሉበት ይቆያሉ እና መቆጣጠሪያውን ለማብራት ምንም migration አላስፈለገም።
**የ`__MISSING__:<english>` ምልክት መስፈርቱን አያሟላም (ከ2026-09-17 ጀምሮ)።** ቀደም ሲል በሰነድ የተገለጸው
የማዘግየት ዘዴ ነበር — runtimeው ወደ ትክክለኛው እንግሊዝኛ ይመለሳል — ነገር ግን በ
2026-09-16 ስምንት የባህሪ PRs 61 ቁልፎችን አክለው ከመተርጎም ይልቅ ምልክቱን በሁሉም 65 locales ውስጥ
አስገብተዋል፦ ይህ መቆጣጠሪያ ሁሉንም ተቀብሏል፣ PRsን ምንም ነገር አላገዳቸውም፣ እና ማገጃው የእውነተኛ-ትርጉም ሬሾ መቆጣጠሪያ
በመቀጠል በrelease tip ላይ ለሁሉም ወደቀ (pt-BR 3.2 % > 2.5 % + 0.5)። አሁን ምልክት
እንደጎደለ ትርጉም ይቆጠራል። ቀይ ስህተትን በ
`node scripts/i18n/sync-ui-keys.mjs --locale=<codes> --translate-markers --batch-size=40`፣ ወይም
ሁሉንም locales በአንድ ጊዜ በ`npm run i18n:translate-new-keys` (`scripts/i18n/translate-new-keys.sh`፣
detached-safe፣ ያለ `OMNIROUTE_TRANSLATION_*` env መጀመርን የሚከለክል) ያስተካክሉ። በእንግሊዝኛ መቆየት ያለበት
ቁልፍ (የተወሰነ የምርት/engine/flag ስም) በ`scripts/i18n/untranslatable-keys.json` ውስጥ መኖር አለበት፣
ከምልክት ጀርባ ፈጽሞ መሆን የለበትም። `vi` ምልክቶችን ሙሉ በሙሉ ይከለክላል (`tests/unit/i18n-vi-completeness.test.ts`)።
#### `check-vitest-exclusions` — የታገዱ-ፈተናዎች መቆጣጠሪያ
በ`vitest.config.ts` `exclude` ዝርዝር ውስጥ ያለ ፋይል የማይሠራ ፈተና ነው፣ እና treeውን ለሚያነብ ሰው
ሽፋን ያለ ይመስላል። ስልሳ ሁለት ፋይሎች
`// #8618 — ቀድሞ የነበረ ውድቀት፤ ሲስተካከል ይህን exclusion ያስወግዱ` ከሚለው አስተያየት ጀርባ ተከማቹ። Issue #8618 በ
2026-08-11 ተዘግቷል፣ እሱ የሚከታተለው ዝርዝር ግን ከ45 ግቤቶች ወደ 62 አደገ፤ እያንዳንዱ አዲስ ግቤት
ወደተዘጋ issue የሚያመለክት አስተያየት ወርሷል። በመጨረሻ ዝርዝሩ ፋይል በፋይል ሲለካ (#13204)፣ **ከ62ቱ 51ዱ
ምንም የsource ለውጥ ሳይደረግ በአሁኑ tree ላይ አልፈዋል**።
መቆጣጠሪያው ወደ እውነተኛ ፋይል የሚያመለክት እያንዳንዱ exclusion (a) የመከታተያ issue እንዲጠቅስ እና
(b) ከተለካው ሁኔታው ጋር በ`config/quality/vitest-exclusions.json` ውስጥ እንዲታይ ይጠይቃል፤ ስለዚህ አንድ መጨመር
በ60-ግቤት array ውስጥ ሌላ አንድ መስመር ከመሆን ይልቅ በተለየ ፋይል ውስጥ ሊገመገም የሚችል diff ይሆናል። ሆን ብሎ
የተገለሉትን ፈተናዎች እንደገና አያስኬድም — ይህ ~10 ደቂቃዎችን ይወስዳል እና በየጊዜው በሚሠራ job ውስጥ መከናወን አለበት፤
inventoryው እያንዳንዱ ለመጨረሻ ጊዜ መቼ እንደተለካ ይመዘግባል።

580
docs/i18n/am/docs/architecture/REPOSITORY_MAP.md Normal file
View File

@@ -0,0 +1,580 @@
# Repository Map (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/REPOSITORY_MAP.md) · 🇸🇦 [ar](../../../ar/docs/architecture/REPOSITORY_MAP.md) · 🇦🇿 [az](../../../az/docs/architecture/REPOSITORY_MAP.md) · 🇧🇬 [bg](../../../bg/docs/architecture/REPOSITORY_MAP.md) · 🇧🇩 [bn](../../../bn/docs/architecture/REPOSITORY_MAP.md) · 🇨🇿 [cs](../../../cs/docs/architecture/REPOSITORY_MAP.md) · 🇩🇰 [da](../../../da/docs/architecture/REPOSITORY_MAP.md) · 🇩🇪 [de](../../../de/docs/architecture/REPOSITORY_MAP.md) · 🇬🇷 [el](../../../el/docs/architecture/REPOSITORY_MAP.md) · 🇪🇸 [es](../../../es/docs/architecture/REPOSITORY_MAP.md) · 🇪🇪 [et](../../../et/docs/architecture/REPOSITORY_MAP.md) · 🇮🇷 [fa](../../../fa/docs/architecture/REPOSITORY_MAP.md) · 🇫🇮 [fi](../../../fi/docs/architecture/REPOSITORY_MAP.md) · 🇫🇷 [fr](../../../fr/docs/architecture/REPOSITORY_MAP.md) · 🇮🇪 [ga](../../../ga/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [gu](../../../gu/docs/architecture/REPOSITORY_MAP.md) · 🇳🇬 [ha](../../../ha/docs/architecture/REPOSITORY_MAP.md) · 🇮🇱 [he](../../../he/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [hi](../../../hi/docs/architecture/REPOSITORY_MAP.md) · 🇭🇷 [hr](../../../hr/docs/architecture/REPOSITORY_MAP.md) · 🇭🇺 [hu](../../../hu/docs/architecture/REPOSITORY_MAP.md) · 🇦🇲 [hy](../../../hy/docs/architecture/REPOSITORY_MAP.md) · 🇮🇩 [id](../../../id/docs/architecture/REPOSITORY_MAP.md) · 🇳🇬 [ig](../../../ig/docs/architecture/REPOSITORY_MAP.md) · 🇮🇹 [it](../../../it/docs/architecture/REPOSITORY_MAP.md) · 🇯🇵 [ja](../../../ja/docs/architecture/REPOSITORY_MAP.md) · 🇬🇪 [ka](../../../ka/docs/architecture/REPOSITORY_MAP.md) · 🇰🇭 [km](../../../km/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [kn](../../../kn/docs/architecture/REPOSITORY_MAP.md) · 🇰🇷 [ko](../../../ko/docs/architecture/REPOSITORY_MAP.md) · 🇱🇹 [lt](../../../lt/docs/architecture/REPOSITORY_MAP.md) · 🇱🇻 [lv](../../../lv/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [ml](../../../ml/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [mr](../../../mr/docs/architecture/REPOSITORY_MAP.md) · 🇲🇾 [ms](../../../ms/docs/architecture/REPOSITORY_MAP.md) · 🇲🇹 [mt](../../../mt/docs/architecture/REPOSITORY_MAP.md) · 🇲🇲 [my](../../../my/docs/architecture/REPOSITORY_MAP.md) · 🇳🇵 [ne](../../../ne/docs/architecture/REPOSITORY_MAP.md) · 🇳🇱 [nl](../../../nl/docs/architecture/REPOSITORY_MAP.md) · 🇳🇴 [no](../../../no/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [or](../../../or/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [pa](../../../pa/docs/architecture/REPOSITORY_MAP.md) · 🇵🇭 [phi](../../../phi/docs/architecture/REPOSITORY_MAP.md) · 🇵🇱 [pl](../../../pl/docs/architecture/REPOSITORY_MAP.md) · 🇵🇹 [pt](../../../pt/docs/architecture/REPOSITORY_MAP.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/REPOSITORY_MAP.md) · 🇷🇴 [ro](../../../ro/docs/architecture/REPOSITORY_MAP.md) · 🇷🇺 [ru](../../../ru/docs/architecture/REPOSITORY_MAP.md) · 🇱🇰 [si](../../../si/docs/architecture/REPOSITORY_MAP.md) · 🇸🇰 [sk](../../../sk/docs/architecture/REPOSITORY_MAP.md) · 🇸🇮 [sl](../../../sl/docs/architecture/REPOSITORY_MAP.md) · 🇷🇸 [sr](../../../sr/docs/architecture/REPOSITORY_MAP.md) · 🇸🇪 [sv](../../../sv/docs/architecture/REPOSITORY_MAP.md) · 🇰🇪 [sw](../../../sw/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [ta](../../../ta/docs/architecture/REPOSITORY_MAP.md) · 🇮🇳 [te](../../../te/docs/architecture/REPOSITORY_MAP.md) · 🇹🇭 [th](../../../th/docs/architecture/REPOSITORY_MAP.md) · 🇹🇷 [tr](../../../tr/docs/architecture/REPOSITORY_MAP.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/REPOSITORY_MAP.md) · 🇵🇰 [ur](../../../ur/docs/architecture/REPOSITORY_MAP.md) · 🇺🇿 [uz](../../../uz/docs/architecture/REPOSITORY_MAP.md) · 🇻🇳 [vi](../../../vi/docs/architecture/REPOSITORY_MAP.md) · 🇳🇬 [yo](../../../yo/docs/architecture/REPOSITORY_MAP.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/REPOSITORY_MAP.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/REPOSITORY_MAP.md)
---
> **ለእያንዳንዱ ማውጫ እና ስርወ ፋይል የአንድ መስመር መግለጫ።**
> መጨረሻ የተዘመነው፦ 2026-06-28 — OmniRoute v3.8.40
>
> በኮድ ማከማቻው ውስጥ በፍጥነት ለመዘዋወር ይህን ካርታ ይጠቀሙ። ዝርዝር መረጃ ለማግኘት፣ ወደ ተለዩ ሰነዶች የሚወስዱትን አገናኞች ይከተሉ።
## ከፍተኛ-ደረጃ የማውጫ ዛፍ
```
OmniRoute/
├── src/ # Next.js 16 መተግበሪያ (UI + API መስመሮች + ላይብረሪዎች + ዶሜይን + አገልጋይ)
├── open-sse/ # የዥረት ሞተር የሥራ ቦታ (ተቆጣጣሪዎች፣ አስፈጻሚዎች፣ ተርጓሚ፣ MCP አገልጋይ)
├── electron/ # የዴስክቶፕ መጠቅለያ (Electron 41 + electron-builder 26.10)
├── bin/ # የCLI መግቢያ ነጥብ እና የትዕዛዝ ተቆጣጣሪዎች
├── scripts/ # የግንባታ፣ የማረጋገጫ፣ የማመሳሰል እና የአንድ ጊዜ ስክሪፕቶች
├── docs/ # ይፋዊ ሰነዶች (እዚህ ይገኛሉ)
├── tests/ # ሁሉም የሙከራ ስብስቦች (አሃድ፣ ውህደት፣ e2e፣ የፕሮቶኮል ደንበኞች)
├── public/ # የNext.js የማይንቀሳቀሱ ንብረቶች፣ PWA manifest፣ service worker፣ አዶዎች
├── config/ # የማይንቀሳቀስ ውቅር + የጥራት መቆጣጠሪያ ሁኔታ (i18n፣ payloadRules፣ quality/)
├── images/ # የግብይት / README ምስል ንብረቶች
├── @omniroute/ # ሊታተሙ የሚችሉ አጋር ጥቅሎች (opencode-plugin፣ opencode-provider)
├── skills/ # የCLI/ወኪል ክህሎት ጥቅሎች (cli-* + omni-* + config-codex-cli)
├── examples/ # የናሙና ፕለጊኖች + omniroute-cmd-hello ማስጀመሪያ
├── contrib/ # የማህበረሰብ አስተዋጽኦዎች (podman/)
├── .source/ # የFumadocs ምንጭ ውቅር (source.config.mjs + server/browser/dynamic)
├── .github/ # የGitHub Actions የሥራ ፍሰቶች + የጉዳይ አብነቶች + የPR አብነት
├── .husky/ # የGit መንጠቆዎች (pre-commit፣ pre-push)
├── .claude/ # የClaude Code የስላሽ ትዕዛዞች (በፕሮጀክት የተወሰኑ)
├── .agents/ # የCodex / አጠቃላይ ወኪል የሥራ ፍሰቶች + ክህሎቶች (የ .claude/ ቅጂ)
├── .vscode/ # የVS Code የሥራ ቦታ ቅንብሮች
├── _ideia/ # የዕቅድ ማስታወሻዎች (መደበኛ ያልሆኑ፤ አብረው አይላኩም)
├── _mono_repo/ # ታሪካዊ ንዑስ ፕሮጀክቶች (cloud፣ site፣ vscode-extension)
├── _references/ # ከተዛማጅ OSS ፕሮጀክቶች የተወሰዱ ለንባብ ብቻ የሚያገለግሉ ቅጂዎች
├── _tasks/ # የእያንዳንዱ ልቀት ተግባር መከታተያ ፋይሎች (መደበኛ ያልሆኑ)
├── .build/ .worktrees/ dist/ # የአካባቢ ግንባታ / git-worktree / የግንባታ ውጤት ጊዜያዊ ማከማቻ (gitignored)
├── .issues/ # የአካባቢ ጉዳይ መሸጎጫ (gitignored)
├── .playwright-mcp/ # የPlaywright MCP ሙከራ ቅርሶች
├── coverage/ # የc8 ሽፋን ውጤት (gitignored)
├── logs/ # የአሂድ ጊዜ ምዝግብ ማስታወሻዎች (gitignored)
├── node_modules/ # ጥገኞች (gitignored)
├── package/ # የnpm pack ዝግጅት ቦታ (የግንባታ ቅርስ)
├── .next/ # የNext.js ግንባታ ውጤት (gitignored)
└── (ስርወ ፋይሎች — ከታች ይመልከቱ)
```
---
## ስርወ ፋይሎች
| ፋይል | ዓላማ |
| ------------------------------------------- | ---------------------------------------------------------------------------------- |
| **README.md** | የግብይት ማረፊያ ገጽ + ፈጣን መጀመሪያ + የባህሪያት ማትሪክስ (`llm.txt`ንም ይመልከቱ) |
| **CHANGELOG.md** | የእያንዳንዱ ልቀት የለውጥ መዝገብ (በ`/version-bump-cc` skill በራስ-ሰር የሚመነጭ) |
| **LICENSE** | የMIT ፈቃድ ጽሑፍ |
| **CLAUDE.md** | ለClaude Code agents የፕሮጀክቱ ደንቦች (ጥብቅ ደንቦች፣ ስምምነቶች፣ ሁኔታዎች) |
| **AGENTS.md** | ከCLAUDE.md ጋር ተመሳሳይ፣ ነገር ግን Claude ላልሆኑ AI agents (Codex፣ Cursor፣ ወዘተ) |
| **GEMINI.md** | በGemini ላይ ለተመሠረቱ agents አጭር ደንቦች (የCLAUDE.md ንዑስ ስብስብ) |
| **CONTRIBUTING.md** | የአስተዋጽኦ አድራጊዎች መመሪያ፦ ማዋቀር፣ conventional commits፣ ሙከራ፣ የPR ፍሰት |
| **SECURITY.md** | የተጋላጭነት ሪፖርት ማድረጊያ ፖሊሲ፣ የሚደገፉ ስሪቶች፣ የስጋት ሞዴል |
| **CODE_OF_CONDUCT.md** | Contributor Covenant — ከማህበረሰቡ የሚጠበቁ የባህሪ መመሪያዎች |
| **llm.txt** | ለLLM crawlers የተመቻቸ ግልጽ ጽሑፍ ማረፊያ ገጽ (SEO ለAI assistants) |
| **package.json** | npm manifest፣ scripts፣ dependencies፣ engines፣ c8 coverage gate |
| **package-lock.json** | የተቆለፈ የdependency ዛፍ |
| **tsconfig.json** | ዋናው የTypeScript config |
| **tsconfig.typecheck-core.json** | ለ`src/` core የtypecheck config |
| **tsconfig.typecheck-noimplicit-core.json** | ጥብቅ (`noImplicitAny`) typecheck |
| **tsconfig.tsbuildinfo** | የTS ጭማሪያዊ build cache (gitignored) |
| **next.config.mjs** | የNext.js 16 build configuration (standalone output) |
| **next-env.d.ts** | በNext.js በራስ-ሰር የሚመነጩ የenv types |
| **eslint.config.mjs** | የESLint flat config (ለእያንዳንዱ የፕሮጀክት ክፍል ደንቦች) |
| **prettier.config.mjs** | የPrettier ቅርጸት ማስያዣ ደንቦች |
| **postcss.config.mjs** | ለTailwind/CSS pipeline የPostCSS config |
| **playwright.config.ts** | የPlaywright E2E ሙከራ config |
| **vitest.config.ts** | የVitest config (ነባሪ suite) |
| **vitest.mcp.config.ts** | ለMCP server / autoCombo / cache suites የVitest config |
| **sonar-project.properties** | የSonarQube/SonarCloud config (የኮድ ጥራት) |
| **Dockerfile** | ባለብዙ-ደረጃ Docker build (builder → runner-base → runner-cli) |
| **docker-compose.yml** | ባለ4 profiles (base፣ cli፣ host፣ cliproxyapi) እና redis sidecar የልማት compose |
| **docker-compose.prod.yml** | የproduction compose (port 20130፣ redis፣ named volumes) |
| **.dockerignore** | ከDocker context የተገለሉ ፋይሎች |
| **fly.toml** | የFly.io deployment config (region `sin`፣ port 20128፣ /data volume) |
| **.env.example** | የenv ፋይል አብነት (በመጀመሪያ ጭነት ወደ `.env` በራስ-ሰር የሚቀዳ) |
| **.gitignore** | የGit ignore ቅጦች |
| **.npmignore** | የnpm publish ማግለያ ዝርዝር |
| **.npmrc** | የnpm config (registry፣ lockfile policy) |
| **.node-version** | የNode ስሪት መቆለፊያ (ከnvm ጋር ተኳሃኝ በሆኑ መሣሪያዎች የሚጠቀም) |
| **.nvmrc** | ለnvm የNode ስሪት መቆለፊያ |
| **eslint.complexity.config.mjs** | ለcomplexity ratchet የESLint config (`scripts/check/check-complexity.mjs --config`) |
| **eslint.sonarjs.config.mjs** | ለSonarJS ደንቦች የESLint config (cognitive complexity / duplication) |
| **source.config.ts** | የFumadocs `defineDocs` source config (`.source/`ን የሚመግብ) |
| **knip.json** | የKnip config — ጥቅም ላይ ያልዋሉ files/exports/deps (dead-code gateን የሚመግብ) |
| **stryker.conf.json** | የStryker mutation-testing config |
| **.size-limit.json** | የsize-limit bundle budget config |
| **promptfooconfig.yaml** | የpromptfoo eval config |
| **.gitleaks.toml** | የgitleaks secret-scan ruleset |
| **.zizmor.yml** | የzizmor GitHub-Actions security-lint config |
| **socket.yml** | የSocket.dev supply-chain config |
| **news.json** | አካባቢያዊ የተደረገ v2 announcement feed፤ የRadar ማስጀመሪያ ንጥል እንደቦዘነ ይላካል |
| **flake.nix** / **flake.lock** | የNix dev-shell definition + lock |
| **.env** | የአካባቢ ምስጢሮች (gitignored — ከ`.env.example` የሚመነጭ) |
> **በv3.8.26 ከroot ውጭ ተዛውሯል (ማስተካከያ):**
>
> - **→ `config/quality/`:** `quality-baseline.json`፣ `complexity-baseline.json`፣ `duplication-baseline.json`፣ `file-size-baseline.json`፣ `test-discovery-baseline.json`፣ `dependency-allowlist.json`፣ `.license-allowlist.json`፣ እና የሚመነጨው `quality-metrics.json` (በgitignored የተደረገ)። [`## config/`](#config--static-configs--quality-gate-state)ን ይመልከቱ።
---
## `src/` — Next.js መተግበሪያ
```
src/
├── app/ # App Router (ገጾች + API መስመሮች + የሁኔታ ገጾች + ማረፊያ ገጽ)
├── lib/ # ዋና ቤተ-መጻሕፍት / የጎራ ሞጁሎች (80 ንዑስ ማውጫዎች + ~70 ከፍተኛ-ደረጃ ፋይሎች)
├── domain/ # ንጹሕ የጎራ ሎጂክ (የፖሊሲ ሞተር፣ አማራጭ ዘዴ፣ ወጪ፣ መቆለፍ፣ comboResolver፣ ግምገማ)
├── server/ # የአገልጋይ-ብቻ ሞጁሎች (የፈቃድ መስመር፣ cors፣ የማረጋገጫ middleware) — ከደንበኛ ሊመጣ አይችልም
├── shared/ # ደህንነቱ በተጠበቀ ቦታ በአገልጋይና በደንበኛ መካከል የሚጋራ (ቋሚዎች፣ አይነቶች፣ ማረጋገጫ፣ ውሎች፣ መገልገያዎች)
├── i18n/ # next-intl ውቅር + ለእያንዳንዱ አካባቢ የመልዕክት JSON (42 አካባቢዎች)
├── middleware/ # Next.js middleware (የጥያቄ ማበልጸጊያ፣ የአካባቢ ማወቂያ)
├── mitm/ # የMITM ፕሮክሲ ዋና ክፍል፦ የምስክር ወረቀት ማመንጨት/መጫን፣ አስተናጋጆች፣ ዒላማዎች፣ መርማሪ፣ ጭምብሎች፣ ቀጥታ ማሳለፊያ
│ ├── handlers/ # MitmHandlerBaseን የሚያስፋፉ 9 የIDE-agent አስተናጋጅ ክፍሎች (antigravity, kiro, copilot, codex, cursor, zed, claudeCode, openCode, trae)
│ └── inspector/ # የትራፊክ ቀረጻ ንብርብር፦ buffer (በማህደረ ትውስታ ውስጥ ያለ ቀለበታዊ ቋት)፣ sseMerger፣ conversationNormalizer፣ kindDetector፣ contextKey፣ httpProxyServer፣ systemProxyConfig
├── models/ # የሞዴል አስማሚ ማገናኛ (የቆየ shim)
├── scripts/ # በዛፉ ውስጥ ያሉ የጥገና ስክሪፕቶች (ለምሳሌ፣ backfillAggregation)
├── sse/ # የቆዩ SSE አስተናጋጆች/አገልግሎቶች (chat.ts, chatHelpers.ts, services/auth.ts)
├── store/ # የቆየ በማህደረ ትውስታ ውስጥ ያለ ማከማቻ (ለsrc/lib/db ቀስ በቀስ እየተተካ)
├── types/ # የጋራ TS አይነት ፋይሎች
├── instrumentation.ts # የNext.js ቴሌሜትሪ hook (አሳሽ + edge)
├── instrumentation-node.ts # የNode-ብቻ መሣሪያ ክትትል
└── proxy.ts # የHTTP-proxy መግቢያ shim
```
### `src/app/` — App Router (Next.js 16)
| ዱካ | ዓላማ |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app/api/v1/` | ይፋዊ OpenAI-ተኳሃኝ API (~25 ንዑስ-መንገዶች፦ ውይይት፣ ማጠናቀቂያዎች፣ embeddings፣ ፋይሎች፣ batches፣ ኦዲዮ፣ ምስሎች፣ ቪዲዮዎች፣ ሙዚቃ፣ rerank፣ moderations፣ ፍለጋ፣ ws፣ agents፣ accounts፣ providers፣ ወዘተ) |
| `app/api/v1beta/` | የGemini-ቅጥ API endpoints |
| `app/api/playground/` | የPlayground Studio መንገዶች፦ `improve-prompt/` (POST — የLLM prompt ዳግም ጸሐፊ)፣ `presets/` (GET ዝርዝር / POST መፍጠር)፣ `presets/[id]/` (GET / PUT / DELETE) — `docs/frameworks/PLAYGROUND_STUDIO.md`ን ይመልከቱ |
| `app/api/` (non-v1) | የአስተዳደር/የአስተዳዳሪ መንገዶች (~60 ማውጫዎች፦ providers፣ combos፣ settings፣ mcp፣ a2a፣ evals፣ memory፣ skills፣ webhooks፣ compliance፣ resilience፣ monitoring፣ tunnels፣ cli-tools፣ ወዘተ) |
| `app/api/tools/agent-bridge/` | AgentBridge REST API — 12 መንገዶች (የserver ቁጥጥር፣ የagent state/DNS/mappings፣ bypass፣ cert፣ upstream-CA)። LOCAL_ONLY + SPAWN_CAPABLE። `docs/frameworks/AGENTBRIDGE.md §7`ን ይመልከቱ። |
| `app/api/tools/traffic-inspector/` | Traffic Inspector REST + WS API — 16+ መንገዶች (requests፣ sessions፣ hosts፣ capture-modes፣ export፣ ws)። LOCAL_ONLY + SPAWN_CAPABLE። `docs/frameworks/TRAFFIC_INSPECTOR.md §8`ን ይመልከቱ። |
| `app/a2a/` | የA2A JSON-RPC 2.0 መግቢያ ነጥብ (`POST /a2a`) |
| `app/.well-known/agent.json/` | A2A Agent Card (ማግኛ) |
| `app/(dashboard)/dashboard/` | የDashboard UI ገጾች (50+ ክፍሎች፣ ~118 page.tsx ፋይሎች፦ providers፣ combos፣ settings፣ memory፣ skills፣ webhooks፣ evals፣ audit፣ batch፣ cache፣ costs፣ health፣ system፣ activity፣ ወዘተ) |
| `app/(dashboard)/dashboard/search-tools/` | የSearch Tools Studio UI (3 ትሮች፦ Search/Scrape/Compare + SearchConceptCard + ProviderCatalog) — `docs/frameworks/SEARCH_TOOLS_STUDIO.md`ን ይመልከቱ |
| `app/(dashboard)/dashboard/memory/` | Memory Studio (ዕቅድ 21)፦ `page.tsx` (ባለ3-ትር ዛጎል)፣ `components/` (MemoryConceptCard፣ MemoryEngineStatus፣ EmbeddingSourceSelector፣ EditMemoryModal፣ RetrievePreview፣ QdrantConfigCard፣ RerankConfigCard)፣ `components/tabs/` (MemoriesTab፣ PlaygroundTab፣ EngineTab)፣ `hooks/` (useEngineStatus፣ useMemorySettings) |
| `app/(dashboard)/dashboard/tools/agent-bridge/` | የAgentBridge dashboard ገጽ — የserver ካርድ፣ 9 የagent ካርዶች፣ የማዋቀር wizard፣ የmodel mapping፣ የbypass ዝርዝር። i18n PT-BR + EN። `docs/frameworks/AGENTBRIDGE.md`ን ይመልከቱ። |
| `app/(dashboard)/dashboard/tools/traffic-inspector/` | የTraffic Inspector dashboard ገጽ — DevTools split፣ 7 የዝርዝር ትሮች፣ 4 የcapture mode toggles፣ session recorder፣ context colorization። i18n PT-BR + EN። `docs/frameworks/TRAFFIC_INSPECTOR.md`ን ይመልከቱ። |
| `app/(dashboard)/dashboard/activity/` | የእንቅስቃሴ feed ገጽ (ቡድን B)፦ `page.tsx` (server) + `ActivityFeedClient.tsx` + `components/{ActivityFeed,ActivityItem,DayHeader,EventTypeFilter}.tsx` — `docs/architecture/MONITORING_SECTIONS.md`ን ይመልከቱ |
| `app/(dashboard)/dashboard/costs/quota-share/` | የQuota Sharing ገጽ (ቡድን B)፦ `QuotaSharePageClient.tsx` + `components/{PoolCard,DimensionBar,AllocationTable,BurnRateChart,QuotaConceptCard,CreatePoolModal,EditAllocationsModal}.tsx` + `hooks/{usePools,usePoolUsage,useLocalStoragePoolMigration}.ts` |
| `app/(dashboard)/dashboard/costs/quota-share/plans/` | የProvider plan config ገጽ (ቡድን B)፦ `page.tsx` + `ProviderPlanConfigClient.tsx` — ለእያንዳንዱ connection override የquota dimensions |
| `app/docs/` | የተካተተ የሰነድ መመልከቻ (`docs/*.md`ን ያቀርባል) |
| `app/landing/` | የግብይት ማረፊያ ገጽ |
| `app/login/`, `forgot-password/`, `forbidden/` | ከማረጋገጫ ጋር የተያያዙ ገጾች |
| `app/{400,401,403,408,429,500,502,503}/` | የHTTP ስህተት ገጾች |
| `app/maintenance/`, `offline/`, `status/`, `privacy/`, `terms/`, `callback/` | የማይንቀሳቀሱ/የሁኔታ ገጾች |
| `app/layout.tsx`, `page.tsx`, `manifest.ts`, `globals.css` | ዋና layout፣ መነሻ፣ PWA manifest፣ ዓለም አቀፍ CSS |
| `app/error.tsx`, `global-error.tsx`, `not-found.tsx`, `loading.tsx` | የስህተት ወሰኖች |
### `src/lib/` — ዋና ላይብረሪዎች (~50 ሞጁሎች)
| ሞጁል | ዓላማ |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `a2a/` | የA2A ፕሮቶኮል ተግባር አስተዳዳሪ፣ ክህሎቶች (5)፣ ዥረት |
| `acp/` | የCLI Agent Registry (የአካባቢያዊ CLI ፍለጋ — `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`ን ይመልከቱ) |
| `api/` | የጋራ API አጋዥ ተግባራት (`requireManagementAuth`፣ ማረጋገጫ) |
| `auth/` | ክፍለ ጊዜ፣ የይለፍ ቃል ሃሺንግ፣ የቶከን ማረጋገጫ |
| `batches/` | የOpenAI Batches API አስተናጋጆች |
| `catalog/` | የአቅራቢ ካታሎግ Zod ማረጋገጫ + የችሎታ መፍትሔ |
| `cloudAgent/` | Cloud Agents (Codex Cloud፣ Devin፣ Jules) — `docs/frameworks/CLOUD_AGENT.md`ን ይመልከቱ |
| `combos/` | የCombo መፍትሔ + እንደገና የማዘዝ አጋዥ ተግባራት |
| `audit/` | የእንቅስቃሴ ምግብ አጋዥ ተግባራት፦ `highLevelActions.ts` (የተፈቀዱ ዝርዝር + `isHighLevelAction()`), `activityIcons.ts` (ድርጊት → የአዶ/ግስ ካርታ)፣ `timeline.ts` (groupByDay/relativeTime) — `docs/architecture/MONITORING_SECTIONS.md`ን ይመልከቱ |
| `compliance/` | የኦዲት ምዝግብ + የአቅራቢ ኦዲት — `docs/security/COMPLIANCE.md`ን ይመልከቱ |
| `compression/` | የማመቂያ ሞተር ማገናኛ (ሞተሮቹ በ`open-sse/services/compression/` ውስጥ ይገኛሉ) |
| `config/` | የአሂድ ጊዜ ውቅረት አጋዥ ተግባራት |
| `db/` | 120+ የጎራ DB ሞጁሎች + 168 ስደቶች (ለSQLite ሁልጊዜ በዚህ በኩል ይለፉ) |
| `quota/` | የQuota Sharing Engine፦ `dimensions.ts` (ዓይነቶች/Zod)፣ `types.ts` (የQuotaStore በይነገጽ)፣ `sqliteQuotaStore.ts`፣ `redisQuotaStore.ts`፣ `storeFactory.ts`፣ `fairShare.ts`፣ `burnRate.ts`፣ `planResolver.ts`፣ `planRegistry.ts`፣ `saturationSignals.ts`፣ `enforce.ts`፣ `spendRecorder.ts` — `docs/routing/QUOTA_SHARE.md`ን ይመልከቱ |
| `radar/` | የRadar ነፃ-ሞዴል ካታሎግ ደንበኛ፦ `feedSchema.ts`፣ `pinnedKeys.ts`፣ `verify.ts`፣ `sync.ts`፣ `applyFeed.ts`፣ `index.ts` (`getRadarCatalog()`) — `docs/frameworks/RADAR.md`ን ይመልከቱ |
| `display/` | የUI ቅርጸት ማስያዣ አጋዥ ተግባራት (ወጪ፣ መዘግየት፣ ወዘተ) |
| `embeddings/` | የEmbeddings አገልግሎት አጋዥ ተግባራት |
| `env/` | የEnv ተለዋዋጭ ትንተና + ማረጋገጫ |
| `evals/` | የEval ማዕቀፍ (ስብስቦች፣ አስኪያጅ፣ አሂድ ጊዜ) — `docs/frameworks/EVALS.md`ን ይመልከቱ |
| `guardrails/` | የPII መደበቂያ፣ የጥያቄ መርፌ ጥቃት መከላከያ፣ የራዕይ ድልድይ — `docs/security/GUARDRAILS.md`ን ይመልከቱ |
| `jobs/` | የበስተጀርባ ሥራዎች (cron-መሰል) |
| `memory/` | የውይይት ማህደረ ትውስታ (SQLite FTS5 + sqlite-vec ድብልቅ RRF + Qdrant ደረጃ 2) — `docs/frameworks/MEMORY.md`ን ይመልከቱ |
| `memory/embedding/` | የብዙ-ምንጭ embedding ንብርብር፦ `index.ts` (መፍትሔ ሰጪ)፣ `remote.ts`፣ `staticPotion.ts`፣ `transformersLocal.ts`፣ `cache.ts`፣ `types.ts` (ዕቅድ 21) |
| `memory/vectorStore.ts` | የsqlite-vec v0.1.9 መጠቅለያ — KNN ጉልበት-ጥቃት + ድብልቅ RRF (FTS5 + ቬክተር፣ k=60)። ዘግይቶ ይነሳል፣ sqlite-vec በማይገኝበት ጊዜ ያለችግር ይቀንሳል። (ዕቅድ 21) |
| `memory/reindex.ts` | `runReindexBatch()` — `needs_reindex=1` ያላቸውን ማህደረ ትውስታዎች በበስተጀርባ ያስኬዳል፤ በ`POST /api/memory/reindex` እና በዘግይቶ-ሙላ መንገድ ይጠራል። (ዕቅድ 21) |
| `monitoring/` | የጤና ፍተሻዎች፣ የመለኪያዎች ልቀት |
| `oauth/` | ለ22 የአቅራቢ ሞጁሎች የOAuth/ማስመጣት ፍሰቶች (agy፣ antigravity፣ claude፣ cline፣ codebuddy-cn፣ codex፣ cursor፣ devin-desktop፣ ghe-copilot፣ github፣ gitlab-duo፣ grok-cli-oauth፣ grok-cli፣ kilocode፣ kimi-coding፣ kiro፣ openference፣ qoder፣ trae፣ xai-oauth፣ zed-hosted፣ zed) |
| `plugins/` | የፕለጊን መዝገብ |
| `promptCache/` | የAnthropic-ቅጥ የጥያቄ መሸጎጫ መግቻ ነጥቦች |
| `skills/` | የክህሎቶች ማዕቀፍ (አብሮገነብ + የገበያ ቦታ + SkillsSH) — `docs/frameworks/SKILLS.md`ን ይመልከቱ |
| `playground/` | የPlayground Studio የጋራ አጋዥ ተግባራት፦ `codeExport.ts` (curl/Python/TS አመንጪ)፣ `promptImprover.ts` (የሜታ-ጥያቄ ገንቢ)፣ `streamMetrics.ts` (ንጹህ TTFT/TPS)፣ `types.ts` (የዋጋ ሰንጠረዥ) — `docs/frameworks/PLAYGROUND_STUDIO.md`ን ይመልከቱ |
| `webhookDispatcher.ts` | የHMAC webhook ማድረስ — `docs/frameworks/WEBHOOKS.md`ን ይመልከቱ |
| `cloudflaredTunnel.ts`, `ngrokTunnel.ts` | የቱነል አስተዳዳሪዎች — `docs/ops/TUNNELS_GUIDE.md`ን ይመልከቱ |
| `cloudSync.ts`, `initCloudSync.ts` | አማራጭ የሁኔታ የደመና ማመሳሰል |
| `localDb.ts` | ለdb ሞጁሎች እንደገና የመላኪያ በርሜል (ምንም ሎጂክ የለም — እንደገና መላክ ብቻ) |
| `cacheLayer.ts`, `idempotencyLayer.ts` | የጥያቄ መሸጎጫ + የድጋሚ አፈጻጸም ወጥነት |
| (~30 ተጨማሪ ከፍተኛ-ደረጃ ፋይሎች) | ልዩ አጋዥ ተግባራት (logEnv፣ modelsDevSync፣ piiSanitizer፣ ወዘተ) |
### `src/lib/db/` — የውሂብ ጎታ (122 ሞጁሎች + 168 ማይግሬሽኖች)
| ንዑስ ማውጫ | ዓላማ |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `db/core.ts` | WAL ጆርናሊንግ ያለው `getDbInstance()` singleton |
| `db/migrations/` | በስሪት የተደራጁ SQL ፋይሎች (idempotent፣ transactional)። `073_memory_vec.sql` የ`memory_vec_meta` + `needs_reindex` ዓምድን ይጨምራል (ዕቅድ 21)። |
| `db/playgroundPresets.ts` | ለPlayground Studio ቅድመ-ቅንብሮች CRUD ሞጁል (`listPlaygroundPresets`, `getPlaygroundPreset`, `createPlaygroundPreset`, `updatePlaygroundPreset`, `deletePlaygroundPreset`) |
| `db/memoryVec.ts` | ለ`memory_vec_meta` CRUD (active_dim, embedding_signature, last_reset_at, vec_loaded) + `markMemoryNeedsReindex`፣ `getMemoryReindexQueue`፣ ወዘተ (ዕቅድ 21) |
| `db/<domain>.ts` | ለእያንዳንዱ ጎራ አንድ ሞጁል፦ providers፣ combos፣ apiKeys፣ users፣ sessions፣ usage፣ audit*log፣ webhooks፣ skills፣ memory_entries፣ cloud_agent_tasks፣ evals*\*፣ reasoning_cache፣ ወዘተ። |
### `src/domain/`
| ሞጁል | ዓላማ |
| ---------------------- | -------------------------------------- |
| `policy.ts` | የፖሊሲ ሞተር |
| `fallbackPolicy.ts` | የአማራጭ ውሳኔ ዛፍ |
| `costRules.ts` | የወጪ ስሌት ደንቦች |
| `lockoutPolicy.ts` | የሞዴል/ግንኙነት መቆለፊያ ፖሊሲ |
| `tagRouter.ts` | በመለያ ላይ የተመሠረተ ማስተላለፍ |
| `comboResolver.ts` | የኮምቦ መፍታት (በኮምቦ ሞተሩ ጥቅም ላይ የሚውል) |
| `modelAvailability.ts` | የእያንዳንዱ ሞዴል ተገኝነት ማረጋገጫ |
| `assessment/` | የሞዴል ግምገማ (የRFC-AUTO-ASSESSMENT ደረጃ 1) |
### `src/server/`
| ሞጁል | ዓላማ |
| -------- | ------------------------------------------------------------------------------------------------ |
| `authz/` | የፈቃድ መስጫ ፓይፕላይን፦ `classify` → `policies` → `enforce` — `docs/architecture/AUTHZ_GUIDE.md`ን ይመልከቱ |
| `cors/` | የCORS ውቅር |
| `auth/` | የክፍለ-ጊዜ middleware |
### `src/shared/`
| ሞጁል | ዓላማ |
| -------------------------------- | -------------------------------------------------------------------------- |
| `constants/providers.ts` | በZod ማረጋገጫ የተደገፉ **355 providers** (ብቸኛው የእውነት ምንጭ) |
| `constants/cliTools.ts` | የውጫ CLI መሣሪያዎች መዝገብ |
| `constants/routingStrategies.ts` | ቅድሚያዎች ያላቸው **19 የማስተላለፊያ ስልቶች** |
| `constants/publicApiRoutes.ts` | Bearer ማረጋገጫን (ከአስተዳደር ማረጋገጫ በተቃራኒ) የሚፈልጉ መስመሮች |
| `constants/upstreamHeaders.ts` | ወደ upstream ለሚላኩ ጥያቄዎች የራስጌ ክልክል ዝርዝር |
| `validation/schemas.ts` | ~80 Zod schemas (ለAPI ውሎች ብቸኛው የእውነት ምንጭ) |
| `validation/helpers.ts` | የZod ማረጋገጫ ረዳቶች (`validateBody`፣ ወዘተ) |
| `types/` | የጋራ TS ዓይነቶች |
| `contracts/` | የወል API ውሎች (በ`package.json` ውስጥ ባለው `files:` የሚጠቀሙባቸው) |
| `utils/circuitBreaker.ts` | የprovider circuit breaker (`docs/architecture/RESILIENCE_GUIDE.md`ን ይመልከቱ) |
| `utils/apiAuth.ts` | የAPI ቁልፍ ማረጋገጫ፣ የscope ማጣራት |
| `utils/fetchTimeout.ts` | ለupstream fetch የጊዜ ገደብ/ማቋረጥ wrappers |
| `utils/releaseNotes.ts` | የተዘጋ v2/legacy ማስታወቂያ parser፣ አካባቢያዊነት እና የID ማሰናበት |
---
## `open-sse/` — የStreaming Engine Workspace
የተለየ npm workspace (`@omniroute/open-sse`)። የጥያቄ ሂደትን + የprovider አፈጻጸምን ያስተናግዳል።
```
open-sse/
├── handlers/ # 16 ፋይሎች (12 handlers + 4 helpers)፦ chatCore, responsesHandler, embeddings, audio, image, video, music, rerank, moderations, search, ወዘተ።
├── executors/ # 67 provider-specific executors (BaseExecutorን ያስፋፋሉ)
├── translator/ # የቅርጸት መቀየሪያዎች (9 request, 9 response, 9 helpers)
├── transformer/ # Responses API ↔ Chat Completions (TransformStream)
├── services/ # ~80+ የservice modules (combo, accountFallback, autoCombo, reasoningCache, claude code/chatgpt stealth, modelDeprecation, taskAwareRouter, workflowFSM, ወዘተ።)
├── mcp-server/ # MCP server (110 tools, 3 transports, 33 scopes)
├── config/ # የProvider/model registries፣ የheader config፣ የmodel aliases
├── utils/ # TLS client፣ proxy fetch/dispatcher፣ የnetwork helpers
├── index.ts # የWorkspace መግቢያ
├── package.json # የWorkspace manifest
├── tsconfig.json # የWorkspace TS config
└── types.d.ts # የWorkspace type declarations
```
### `open-sse/mcp-server/`
| ዱካ | ዓላማ |
| --------------------------- | ------------------------------------------------------------------------------ |
| `server.ts` | የMCP server lifecycle (stdio + HTTP transports) |
| `httpTransport.ts` | HTTP Streamable + SSE transports (`/api/mcp/sse`, `/api/mcp/stream`) |
| `audit.ts` | Audit logging ወደ `mcp_tool_audit` table |
| `scopeEnforcement.ts` | ለእያንዳንዱ tool የscope validation |
| `runtimeHeartbeat.ts` | የHealth heartbeat ወደ `DATA_DIR/runtime/mcp-heartbeat.json` |
| `descriptionCompressor.ts` | contextን ለመቆጠብ የtool description metadataን ይጨምቃል |
| `schemas/tools.ts` | 36 መሠረታዊ የtool definitions + scopes |
| `tools/advancedTools.ts` | የላቁ tool implementations |
| `tools/memoryTools.ts` | 3 የmemory tools (search/add/clear) |
| `tools/skillTools.ts` | 4 የskill tools (list/enable/execute/executions) |
| `tools/compressionTools.ts` | 5 የcompression tools |
| `README.md` | ውስጣዊ የMCP server README (ከ`docs/frameworks/MCP-SERVER.md` ጋር በተሻጋሪ አገናኝ የተገናኘ) |
---
## `electron/` — የDesktop Wrapper
| ፋይል | ዓላማ |
| ---------------- | ----------------------------------------------------------------------------- |
| `main.js` | የElectron ዋና process (BrowserWindow፣ የተካተተ Next.js server፣ tray፣ auto-update) |
| `preload.js` | IPC bridge (contextBridge → `window.omniroute`) |
| `package.json` | electron-builder config + Electron 41 + electron-builder 26.10 deps |
| `assets/` | የመተግበሪያ አዶዎች (Windows .ico፣ macOS .icns፣ Linux .png) |
| `dist-electron/` | የBuild output (gitignored) |
| `types.d.ts` | የrenderer bridge type declarations |
| `README.md` | ውስጣዊ የElectron README (`docs/guides/ELECTRON_GUIDE.md`ንም ይመልከቱ) |
---
## `bin/` — CLI
| ፋይል | ዓላማ |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `omniroute.mjs` | ዋናው የCLI መግቢያ — `omniroute serve`፣ `omniroute setup`፣ `omniroute doctor`፣ `omniroute providers`፣ `omniroute combos`፣ ወዘተ። |
| `reset-password.mjs` | ራሱን የቻለ የይለፍ ቃል ዳግም ማስጀመሪያ CLI |
| `cli/commands/setup.mjs` | በይነተገናኝ + በይነተገናኝ ያልሆነ የማዋቀሪያ አዋቂ |
| `cli/commands/doctor.mjs` | የስርዓት ጤንነት ምርመራዎች (8+ ፍተሻዎች) |
| `cli/commands/providers.mjs` | የአቅራቢዎች ዝርዝር/ሙከራ/ማረጋገጫ |
| `cli/{args,data-dir,encryption,io,provider-catalog,provider-store,provider-test,settings-store,sqlite}.mjs` | የCLI ረዳት ሞጁሎች |
| `cli/tray/tray.ts` | ከስርዓት ትሪ ጋር ውህደት (ተሻጋሪ-መድረክ፦ NotifyIcon በWindows ላይ፣ systray2 በmacOS/Linux ላይ) |
| `cli/tray/tray.ps1` | የPowerShell NotifyIcon ተተኪ ስርዓት (Windows፣ ምንም አዲስ ሁለትዮሽ ፋይሎች የሉም) |
| `cli/tray/autostart.ts` | ተሻጋሪ-መድረክ ራስ-ሰር ማስጀመሪያ (LaunchAgent / .desktop / registry) |
| `cli/runtime/sqliteRuntime.mjs` | ባለ5-ደረጃ የSQLite ነጂ መፍቻ ሰንሰለት (bundled → runtime → lazy-install → node:sqlite → sql.js) |
| `cli/runtime/magicBytes.mjs` | የሁለትዮሽ magic-byte ማረጋገጫ (ELF / Mach-O / Mach-O fat / PE) |
| `cli/runtime/index.mjs` | `warmUpRuntimes()` — በpostinstall / በመጀመሪያ ጅምር ላይ ነጂዎችን አስቀድሞ ይፈታል |
| `nodeRuntimeSupport.mjs` | በመጫን ጊዜ የሚደገፈውን የNode.js ስሪት ማረጋገጥ |
---
## `skills/` — ይፋዊ የኤጀንት ክህሎቶች
| ፋይል | ዓላማ |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `skills/omniroute*/SKILL.md` | ለውጫዊ AI ኤጀንቶች (Claude Desktop, ChatGPT, Cursor, Cline) የሚያገለግሉ 10 የክህሎት መግለጫዎች |
---
## `scripts/` — የግንባታ እና የፍተሻ ስክሪፕቶች
| ስክሪፕት | ዓላማ |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| `run-next.mjs` | የአካባቢ ተለዋዋጮችን በመሙላት የልማት/ማስጀመሪያ አስኬጅ |
| `build-next-isolated.mjs` | ራሱን የቻለ ግንባታ (Next.js 16 standalone) |
| `prepublish.ts` | ከ`npm pack` በፊት የጥቅል ዝግጅት |
| `postinstall.mjs` | በመጀመሪያው ጭነት `.env`ን ከ`.env.example` በራስ-ሰር መፍጠር |
| `sync-env.mjs` | የ`.env` ቁልፎችን ከ`.env.example` ጋር እንደገና ማመሳሰል |
| `check-cycles.mjs` | ዑደታዊ ጥገኝነቶችን ማግኘት |
| `check-route-validation.mjs` | ሁሉም API መስመሮች የZod ማረጋገጫ እንዳላቸው ማረጋገጥ |
| `check-t11-any-budget.mjs` | ለእያንዳንዱ ፋይል ግልጽ የ`any` በጀትን ተፈጻሚ ማድረግ |
| `check-docs-sync.mjs` | የሰነዶች ስሪት መመሳሰልን ማረጋገጥ (ነባር pre-commit) |
| **`check-env-doc-sync.mjs`** | አዲስ፦ በኮድ፣ `.env.example` እና `ENVIRONMENT.md` ውስጥ ያሉ የአካባቢ ተለዋዋጮችን በማነጻጸር ማረጋገጥ |
| **`check-docs-counts-sync.mjs`** | አዲስ፦ ቆጠራዎች (አስፈጻሚዎች፣ ስልቶች፣ OAuth፣ A2A ክህሎቶች) ከሰነዶች ጋር መዛመዳቸውን ማረጋገጥ |
| **`check-deprecated-versions.mjs`** | አዲስ፦ በሰነዶች ውስጥ ጊዜ ያለፈባቸውን ስሪቶች/ቀኖች ምልክት ማድረግ |
| `check-supported-node-runtime.ts` | የአሁኑ Node ስሪት የሚደገፍ መሆኑን ማረጋገጥ |
| `check-pr-test-policy.mjs` | በምርት ኮድ ለውጦች ላይ የ"ሙከራዎች ያስፈልጋሉ" ደንብን ተፈጻሚ ማድረግ |
| **`gen-provider-reference.ts`** | አዲስ፦ `docs/reference/PROVIDER_REFERENCE.md`ን ከካታሎግ በራስ-ሰር ማመንጨት |
| `i18n/generate-multilang.mjs` | የUI ሕብረቁምፊዎችን እና ሰነዶችን በGoogle Translate መተርጎም |
| `i18n_autotranslate.py` | በLLM ላይ የተመሠረተ የሰነድ ትርጉም ሂደት |
| `validate_translation.py` | ለእያንዳንዱ locale የትርጉም ማረጋገጫ |
| `check_translations.py` | በኮድ በኩል የi18n ቁልፍ ፍተሻ |
| `run-playwright-tests.mjs` | የPlaywright E2E ሙከራ አስኬጅ |
| `run-protocol-clients-tests.mjs` | የMCP/A2A E2E ሙከራ አስኬጅ |
| `run-ecosystem-tests.mjs` | የሥነ-ምህዳር (የአቅራቢ ውህደት) ሙከራዎች |
| `test-report-summary.mjs` | የሽፋን ማጠቃለያ markdown ማመንጨት |
| `smoke-electron-packaged.mjs` | በጥቅል የቀረበውን Electron ግንባታ የጭስ ሙከራ ማድረግ |
| `native-binary-compat.mjs` | ቤተኛ ጥገኞች (`better-sqlite3`) ከElectron Node ጋር መዛመዳቸውን ማረጋገጥ |
| `validate-pack-artifact.ts` | የnpm pack ውጤትን ማረጋገጥ |
| `responses-ws-proxy.mjs` | ለCodex Responses API የWebSocket ድልድይ |
| `v1-ws-bridge.mjs` | ለ`/api/v1/ws` መጨረሻ ነጥብ የWebSocket ድልድይ |
| `standalone-server-ws.mjs` | ራሱን የቻለ የWS አገልጋይ አስኬጅ |
| `system-info.mjs` | ለድጋፍ የስርዓት/የአሂድ ጊዜ መረጃን ማተም |
| `healthcheck.mjs` | የአንድ ጊዜ የጤና ፍተሻ (በDocker HEALTHCHECK የሚጠቀም) |
| `uninstall.mjs` | ንጹህ የማራገፊያ ስክሪፕት |
---
## `docs/` — ይፋዊ ሰነዶች (7 ዋና ፋይሎች + 17 ንዑስ ማውጫዎች)
### ዋና መመሪያዎች
| ሰነድ | ዓላማ |
| --------------------------- | ---------------------------------------------------------------------------------- |
| `ARCHITECTURE.md` | ከፍተኛ-ደረጃ አርክቴክቸር፣ የንዑስ ሥርዓቶች ካርታ፣ የዳሽቦርድ ገጽታ |
| `CODEBASE_DOCUMENTATION.md` | የምህንድስና ማጣቀሻ፦ ማውጫዎች፣ ሞጁሎች፣ ስምምነቶች |
| `FEATURES.md` | የv3.8 ዋና ማሻሻያዎችን ያካተተ የባህሪያት ማትሪክስ |
| `USER_GUIDE.md` | የዋና ተጠቃሚ መመሪያ (ማዋቀር፣ ሞዴሎች፣ ጥምረቶች፣ CLIዎች፣ ድምፅ፣ ወዘተ) |
| `API_REFERENCE.md` | የማረጋገጫ ሞዴልን ያካተተ የAPI መጨረሻ ነጥቦች ማጣቀሻ |
| `openapi.yaml` | OpenAPI 3.0 ዝርዝር መግለጫ (121 መንገዶች) |
| `SETUP_GUIDE.md` | የመጫኛ ዘዴዎች (npm፣ npx፣ Docker፣ Electron፣ Termux፣ የምንጭ ኮድ) |
| `ENVIRONMENT.md` | ሁሉም የአካባቢ ተለዋዋጮች (~800 የተሰነዱ፣ ~3,050 የ`.env.example` መስመሮች) |
| `TROUBLESHOOTING.md` | የተለመዱ ስህተቶች + የv3.8.0 የታወቁ ችግሮች |
| `RELEASE_CHECKLIST.md` | ሙሉ የልቀት ሂደት (ክህሎቶች፣ husky፣ መደበኛ ኮሚቶች፣ ማሰማራት) |
| `COVERAGE_PLAN.md` | የሽፋን ግቦች እና የአሁኑ ሁኔታ |
| `FREE_TIERS.md` | በጥንቃቄ የተመረጡ የነፃ-ደረጃ አቅራቢዎች (48+ ነፃ + 11 OAuth) |
| `CLI-TOOLS.md` | የውጭ CLI ውህደቶች + ውስጣዊ OmniRoute CLI |
| `I18N.md` | የi18n አርክቴክቸር፣ ቋንቋ ማከል፣ 42 የአካባቢ ቅንብሮች |
| `UNINSTALL.md` | ንጹህ የማራገፊያ ደረጃዎች |
| `PROVIDER_REFERENCE.md` | **በራስ-ሰር የተፈጠረ** የ355 አቅራቢዎች ካታሎግ (እንደገና ለማመንጨት፦ `npm run gen:provider-reference`) |
### የንዑስ ሥርዓቶች ጥልቅ ዳሰሳዎች
| ሰነድ | ዓላማ |
| ------------------------------------------ | ------------------------------------------------------------ |
| `MCP-SERVER.md` | MCP ሰርቨር፦ 110 መሣሪያዎች፣ 3 ማጓጓዣዎች፣ 33 ወሰኖች፣ REST መጨረሻ ነጥቦች |
| `A2A-SERVER.md` | A2A v0.3፦ JSON-RPC፣ 6 ክህሎቶች፣ REST አጋዥ መሣሪያዎች፣ የወኪል ካርድ |
| `AGENT_PROTOCOLS_GUIDE.md` | የተዋሃደ መመሪያ፦ A2A ከ ACP እና Cloud Agents ጋር |
| `CLOUD_AGENT.md` | Codex Cloud / Devin / Jules ኦርኬስትሬሽን |
| `SKILLS.md` | የክህሎቶች ማዕቀፍ (አብሮገነብ + የገበያ ቦታ + SkillsSH + ማጠሪያ) |
| `RADAR.md` | የRadar ነፃ-ሞዴል ካታሎግ ተደራቢ (`RADAR_ENABLED`፣ በነባሪ ጠፍቷል) |
| `MEMORY.md` | የማስታወሻ ሥርዓት (SQLite FTS5 + Qdrant) |
| `EVALS.md` | የግምገማ ማዕቀፍ (ስብስቦች፣ አሂዶች፣ የውጤት መስፈርቶች) |
| `GUARDRAILS.md` | PII መሸፈኛ፣ የጥያቄ መርፌ ጥቃት፣ የምስል ድልድይ |
| `COMPLIANCE.md` | የኦዲት መዝገብ፣ የማቆያ ጊዜ፣ የnoLog አለመሳተፊያ |
| `WEBHOOKS.md` | በHMAC የተፈረመ የwebhook ማድረስ |
| `REASONING_REPLAY.md` | ለ`reasoning_content` ድብልቅ ማስታወሻ/SQLite መሸጎጫ |
| `AUTHZ_GUIDE.md` | የፈቃድ አሰጣጥ መስመር (`classify` → `policies` → `enforce`) |
| `RESILIENCE_GUIDE.md` | የወረዳ መግቻ + የማቀዝቀዣ ጊዜ + የሞዴል መቆለፊያ |
| `docs/security/STEALTH_GUIDE.md` (በgit ብቻ) | TLS አሻራ ማውጣት (JA3/JA4)፣ Claude Code CCH፣ MITM ሰርተፊኬት |
| `AUTO-COMBO.md` | Auto Combo ሞተር (ባለ16-ምክንያት ነጥብ አሰጣጥ፣ 6 የሁነታ ጥቅሎች፣ ምናባዊ ፋብሪካ) |
### መጭመቅ
| ሰነድ | ዓላማ |
| ------------------------------- | ---------------------------------- |
| `COMPRESSION_GUIDE.md` | የመጭመቂያ ሁነታዎች አጠቃላይ እይታ + የመንገድ ካርታ |
| `COMPRESSION_ENGINES.md` | Caveman + RTK ሞተሮች፣ የመዝገብ ቤት ውል |
| `COMPRESSION_RULES_FORMAT.md` | የCaveman ደንብ ጥቅል JSON ንድፍ |
| `COMPRESSION_LANGUAGE_PACKS.md` | ለእያንዳንዱ ቋንቋ የደንብ ጥቅሎች ዝርዝር |
| `RTK_COMPRESSION.md` | RTK ገላጭ የሂደት መስመር (49 ማጣሪያዎች) |
### ማሰማራት
| ሰነድ | ዓላማ |
| ---------------------------- | -------------------------------------------------------------- |
| `DOCKER_GUIDE.md` | Docker ግንባታ፣ መገለጫዎች (base/cli/host/cliproxyapi)፣ Redis የጎን መያዣ |
| `VM_DEPLOYMENT_GUIDE.md` | አጠቃላይ VM/VPS ማሰማራት (Ubuntu/Debian + nginx + systemd) |
| `FLY_IO_DEPLOYMENT_GUIDE.md` | Fly.io ማሰማራት (በአሁኑ ጊዜ በቻይንኛ ብቻ) |
| `TERMUX_GUIDE.md` | ማሳያ-አልባ Android በTermux በኩል |
| `PWA_GUIDE.md` | የProgressive Web App ጭነት + የአገልግሎት ሠራተኛ |
| `ELECTRON_GUIDE.md` | የዴስክቶፕ መተግበሪያ ግንባታ + መፈረም + ማሰራጨት |
| `TUNNELS_GUIDE.md` | Cloudflared + ngrok + Tailscale Funnel |
| `PROXY_GUIDE.md` | ባለ4-ደረጃ ወደ ውጭ የሚወጣ ፕሮክሲ + 1proxy የገበያ ቦታ |
### ንዑስ ማውጫዎች
| ንዑስ ማውጫ | ዓላማ |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs/i18n/` | የተተረጎሙ የሰነድ ትርጉሞች (41 የአካባቢ ቅንብሮች) |
| `docs/screenshots/` | ለመመሪያዎች የሚያገለግሉ የምስል ሀብቶች |
| `_tasks/superpowers/` | ከ superpowers (`writing-plans`/`brainstorming`) የተገኙ ዕቅዶች/ዝርዝር መግለጫዎች + ምርምር — ተነጥሎ የተቀመጠ፣ ለየት ብሎ ስሪት የሚቆጣጠር ማከማቻ፤ በዋናው ዛፍ በ git ችላ የተባለ። CLAUDE.md → "የዕቅድ እና የምርምር ቅርሶች"ን ይመልከቱ። |
---
## `tests/` — የሙከራ ስብስቦች
| ንዑስ ማውጫ | ዓይነት | ማስኬጃ |
| ------------------------------------ | ----------------------------- | ----------------------------- |
| `tests/unit/` | የክፍል ሙከራዎች (~4,800 ፋይሎች፣ ፈጣኑ) | የNode ቤተኛ የሙከራ ማስኬጃ |
| `tests/integration/` | የብዙ ሞጁሎች + DB ውህደት ሙከራዎች | የNode ቤተኛ የሙከራ ማስኬጃ (ትይዩነት 1) |
| `tests/e2e/` | UI + የሥራ ፍሰት E2E | Playwright |
| `tests/e2e/protocol-clients.test.ts` | MCP + A2A የእውነተኛ ደንበኛ E2E | ብጁ የፕሮቶኮል ደንበኞች |
| `tests/e2e/ecosystem.test.ts` | የአቅራቢ ውህደት (ኔትወርክን የሚጠቀም) | የNode ቤተኛ የሙከራ ማስኬጃ |
---
## `public/` — የማይለወጡ ሀብቶች
| ዱካ | ዓላማ |
| ------------------- | ---------------------------------------------------------- |
| `public/` (ሥር) | Favicons፣ robots.txt፣ manifest፣ service worker፣ የግብይት ምስሎች |
| `public/providers/` | የአቅራቢ አርማ PNG/SVG (በዳሽቦርድ ውስጥ ጥቅም ላይ የሚውል) |
---
## `config/` — የማይለወጡ ውቅሮች + የጥራት መግቢያ-በር ሁኔታ
ከማከማቻው ሥር በv3.8.26 ወደዚህ የተዘዋወሩ፣ ከምርቱ ጋር የሚሰጡ የውቅር አብነቶች እና ቁርጥ የጥራት መግቢያ-በር መነሻዎች
(ይህም ሥሩን ቀላል ለማድረግ ነው)።
| ዱካ | ዓላማ |
| --------------------------------------------- | ----------------------------------------------------------------- |
| `config/i18n.json` | የቋንቋ ክልል ዝርዝር + ሜታዳታ (ለ42 የቋንቋ ክልሎች ብዛት ቀኖናዊ ምንጭ) |
| `config/i18n-schema.json` | `i18n.json`ን የሚያረጋግጥ JSON schema |
| `config/payloadRules.json` | የላይኛው ምንጭ payload ማጽጃ ደንቦች |
| `config/quality/quality-baseline.json` | የብዙ-መለኪያ ራቼት መነሻ (`scripts/quality/check-quality-ratchet.mjs`) |
| `config/quality/complexity-baseline.json` | የታሰረ የESLint-ውስብስብነት መነሻ (`check-complexity.mjs`) |
| `config/quality/duplication-baseline.json` | የታሰረ የjscpd ድግግሞሽ መነሻ (`check-duplication.mjs`) |
| `config/quality/file-size-baseline.json` | የታሰረ የእያንዳንዱ ፋይል መጠን መነሻ (`check-file-size.mjs`) |
| `config/quality/test-discovery-baseline.json` | የታሰረ የወላጅ-አልባ ሙከራ መነሻ (`check-test-discovery.mjs`) |
| `config/quality/dependency-allowlist.json` | የጸደቁ ጥገኝነቶች የፍቃድ ዝርዝር (`check-deps.mjs`) |
| `config/quality/.license-allowlist.json` | የSPDX ፈቃድ የፍቃድ ዝርዝር (`check-licenses.mjs`) |
| `config/quality/quality-metrics.json` | ጊዜያዊ የተሰበሰቡ መለኪያዎች (በ`collect-metrics.mjs` የሚፈጠሩ፤ **gitignored**) |
---
## `.github/` — የGitHub ውህደት
| ዱካ | ዓላማ |
| ---------------------------------- | ---------------------------------------------------- |
| `.github/workflows/` | የGitHub Actions CI/CD የሥራ ፍሰቶች (lint፣ ሙከራ፣ ሽፋን፣ ልቀት) |
| `.github/ISSUE_TEMPLATE/` | የሳንካ/ባህሪ ጉዳይ አብነቶች |
| `.github/pull_request_template.md` | የPR አብነት |
| `.github/dependabot.yml` | የጥገኝነት ማዘመኛ ውቅር |
---
## `.husky/` — የGit Hooks
| ፋይል | ዓላማ |
| ------------ | -------------------------------------------------------------- |
| `pre-commit` | `lint-staged + check-docs-sync + check:any-budget:t11`ን ያስኬዳል |
| `pre-push` | በአሁኑ ጊዜ ተሰናክሏል (በአስተያየት ተዘግቷል)። `npm run test:unit`ን በእጅ ያስኪዱ። |
| `_/` | የHusky ውስጣዊ ክፍሎች |
---
## `.claude/` — የClaude Code Slash Commands
| ፋይል | ዓላማ |
| --------------------------------------------------- | ------------------------------------------------ |
| `commands/version-bump-cc.md` | `/version-bump-cc` — ስሪት ማሳደግ + ራስ-ሰር የለውጥ ማስታወሻ |
| `commands/generate-release-cc.md` | `/generate-release-cc` — ሙሉ የልቀት የሥራ ፍሰት |
| `commands/deploy-vps-{local,akamai,both}-cc.md` | ወደ VPS ማሰማራት |
| `commands/capture-release-evidences-cc.md` | አዳዲስ ባህሪያትን በአሳሽ WebP አድርጎ መቅዳት |
| `commands/review-{prs,discussions}-cc.md` | የGitHub PRs/ውይይቶችን መለየትና ቅድሚያ መስጠት |
| `commands/{review-issues,implement-features}-cc.md` | የጉዳይ የሥራ ፍሰቶች |
| `settings.local.json` | ለእያንዳንዱ ፕሮጀክት የClaude Code ቅንብሮች |
---
## `.agents/` — አጠቃላይ የAgent የሥራ ፍሰቶች (Codex / Cursor / ወዘተ)
| ዱካ | ዓላማ |
| ------------------------ | ------------------------------------------- |
| `workflows/*-ag.md` | 11 የሥራ ፍሰት ትርጓሜዎች (የ`.claude/commands/` ቅጂ) |
| `skills/<name>/SKILL.md` | Codex Execution Notes ያላቸው 9 የክህሎት ትርጓሜዎች |
> **ማስታወሻ፦** የሥራ ፍሰቶቹና ትዕዛዞቹ በአሁኑ ጊዜ ባይት በባይት አንድ ናቸው። `.agents/` የተለየ የAgent ማስኬጃን (Codex) ለማነጣጠር የታሰበ ከሆነ፣ ልዩነቶቹ ትርጉም ባለው መልኩ መለያየት አለባቸው።
---
## `_ideia/`, `_mono_repo/`, `_references/`, `_tasks/` — ከዋናው ዛፍ ውጭ
እነዚህ በስርዝ የሚጀምሩ ማውጫዎች ለማሰራጨት ያልታሰበ ይዘት ይይዛሉ፦
- **`_ideia/`** — የንድፍ ማስታወሻዎች (defer / notfit / viable ምድቦች)
- **`_mono_repo/`** — ታሪካዊ ንዑስ ፕሮጀክቶች (omnirouteCloud፣ omnirouteSite፣ vscode-extension)
- **`_references/`** — በልማት ወቅት ለማጣቀሻነት የተዘጋጁ የተዛማጅ OSS ፕሮጀክቶች (LiteLLM፣ 9router፣ ClawRouter፣ CLIProxyAPI፣ modelrelay፣ new-api፣ ወዘተ) ንባብ-ብቻ ቅጂዎች
- **`_tasks/`** — ለእያንዳንዱ ልቀት የተግባር ክትትል ፋይሎች (መደበኛ ያልሆኑ)
በ`npm pack` ውጤት ውስጥ አይካተቱም። `.npmignore`ን ይመልከቱ።
---
## የሚፈጠሩ / በGit ችላ የሚባሉ
| ዱካ | ዓላማ |
| ---------------------- | ------------------------ |
| `node_modules/` | የnpm ጥገኞች |
| `.next/` | የNext.js ግንባታ ውጤት |
| `coverage/` | የc8 ሽፋን ሪፖርቶች |
| `logs/` | የአፈጻጸም ጊዜ ምዝግቦች |
| `package/` | የnpm pack ማዘጋጃ ቦታ |
| `.playwright-mcp/` | የPlaywright MCP ሙከራ ቅርሶች |
| `.issues/` | የአካባቢያዊ ጉዳዮች መሸጎጫ |
| `tsconfig.tsbuildinfo` | የTS ጭማሪያዊ መሸጎጫ |
---
## የአሰሳ ምክሮች
- **አዲስ አስተዋጽዖ አድራጊ ነዎት?** `CONTRIBUTING.md` → `CLAUDE.md` → `docs/architecture/ARCHITECTURE.md` → `docs/architecture/CODEBASE_DOCUMENTATION.md` ያንብቡ።
- **አቅራቢ እያከሉ ነው?** `docs/architecture/ARCHITECTURE.md § Adding a New Provider`ን ይከተሉ + ከ`docs/reference/PROVIDER_REFERENCE.md` ጋር ያመሳክሩ።
- **መስመር እያከሉ ነው?** `docs/architecture/ARCHITECTURE.md § Adding a New API Route` + `src/shared/validation/schemas.ts`።
- **የMCP መሣሪያ እያከሉ ነው?** `docs/frameworks/MCP-SERVER.md § Adding a Tool`።
- **የA2A ክህሎት እያከሉ ነው?** `docs/frameworks/A2A-SERVER.md § Adding a New Skill`።
- **በአካባቢዎ እያስኬዱ ነው?** `docs/guides/SETUP_GUIDE.md`።
- **ሥምሪት እያደረጉ ነው?** `docs/guides/DOCKER_GUIDE.md` / `docs/ops/VM_DEPLOYMENT_GUIDE.md` / `docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md`።
- **ልቀት እያደረጉ ነው?** `docs/ops/RELEASE_CHECKLIST.md` (እና `/generate-release-cc` የClaude Code ክህሎት)።

665
docs/i18n/am/docs/architecture/RESILIENCE_GUIDE.md Normal file
View File

@@ -0,0 +1,665 @@
# Resilience Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/RESILIENCE_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/RESILIENCE_GUIDE.md) · 🇦🇿 [az](../../../az/docs/architecture/RESILIENCE_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/RESILIENCE_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/RESILIENCE_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/RESILIENCE_GUIDE.md) · 🇩🇰 [da](../../../da/docs/architecture/RESILIENCE_GUIDE.md) · 🇩🇪 [de](../../../de/docs/architecture/RESILIENCE_GUIDE.md) · 🇬🇷 [el](../../../el/docs/architecture/RESILIENCE_GUIDE.md) · 🇪🇸 [es](../../../es/docs/architecture/RESILIENCE_GUIDE.md) · 🇪🇪 [et](../../../et/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/RESILIENCE_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/RESILIENCE_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/RESILIENCE_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇱 [he](../../../he/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/RESILIENCE_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/RESILIENCE_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/architecture/RESILIENCE_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇩 [id](../../../id/docs/architecture/RESILIENCE_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇹 [it](../../../it/docs/architecture/RESILIENCE_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/RESILIENCE_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/RESILIENCE_GUIDE.md) · 🇰🇭 [km](../../../km/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/RESILIENCE_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/RESILIENCE_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/RESILIENCE_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/RESILIENCE_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/RESILIENCE_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/RESILIENCE_GUIDE.md) · 🇲🇲 [my](../../../my/docs/architecture/RESILIENCE_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/RESILIENCE_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/RESILIENCE_GUIDE.md) · 🇳🇴 [no](../../../no/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [or](../../../or/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/RESILIENCE_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/RESILIENCE_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/RESILIENCE_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/RESILIENCE_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/RESILIENCE_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/RESILIENCE_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/RESILIENCE_GUIDE.md) · 🇱🇰 [si](../../../si/docs/architecture/RESILIENCE_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/RESILIENCE_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/RESILIENCE_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/RESILIENCE_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/RESILIENCE_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/RESILIENCE_GUIDE.md) · 🇮🇳 [te](../../../te/docs/architecture/RESILIENCE_GUIDE.md) · 🇹🇭 [th](../../../th/docs/architecture/RESILIENCE_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/RESILIENCE_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/RESILIENCE_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/RESILIENCE_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/RESILIENCE_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/RESILIENCE_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/RESILIENCE_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/RESILIENCE_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/RESILIENCE_GUIDE.md)
---
OmniRoute ሦስት የተለያዩ ግን ተዛማጅ የመቋቋም ዘዴዎች አሉት። እያንዳንዳቸው የተለየ ወሰንና ዓላማ አላቸው። የማዞሪያ ባህሪን ሲያርሙ እነዚህን ለያይተው ይያዙ።
![ባለ 3-ንብርብር የመቋቋም ሞዴል](../diagrams/exported/resilience-3layers.svg)
> ምንጭ፦ [diagrams/resilience-3layers.mmd](../diagrams/resilience-3layers.mmd)
## 1. የአቅራቢ ሰርኪት መቋረጫ
**ወሰን፦** ሙሉው አቅራቢ (ለምሳሌ፣ `glm`፣ `openai`፣ `anthropic`)።
**ዓላማ፦** በላይኛው ዥረት/አገልግሎት ደረጃ በተደጋጋሚ ውድቀት ለሚያጋጥመው አቅራቢ ትራፊክ መላክን ማቆም።
**አተገባበር፦**
- ዋና ክፍል፦ `src/shared/utils/circuitBreaker.ts`
- ማገናኘት፦ `src/sse/handlers/chatHelpers.ts`፣ `src/sse/handlers/chat.ts`
- የሁኔታ API፦ `GET /api/monitoring/health`
- የዳግም ማስጀመሪያ API፦ `POST /api/resilience/reset`
- መጠቅለያዎች፦ `open-sse/services/accountFallback.ts`
- የውሂብ ጎታ ሰንጠረዥ፦ `domain_circuit_breakers`
**ሁኔታዎች፦**
- `CLOSED` — መደበኛ ትራፊክ ተፈቅዷል
- `DEGRADED` — ትራፊክ አሁንም ተፈቅዷል፣ ነገር ግን የጨመሩ የአቅራቢ ውድቀቶች ክትትል ይደረግባቸዋል
- `OPEN` — አቅራቢው ለጊዜው ታግዷል፤ የጥምር ማዞሪያው ይዘለዋል
- `HALF_OPEN` — የዳግም ማስጀመሪያ የጊዜ ገደቡ አልፏል፤ የመፈተሻ ጥያቄ ተፈቅዷል
**ሊዋቀሩ የሚችሉ ነባሪዎች (`open-sse/config/constants.ts`፣ በDashboard → Settings → Resilience ላይ የሚታዩ)፦**
| ክፍል | ወደ የተዳከመ ሁኔታ የሚገባው | የሚከፈተው | የዳግም ማስጀመሪያ የጊዜ ገደብ |
| ------- | ------------------ | -------- | ------------------- |
| OAuth | 5 ውድቀቶች | 8 ውድቀቶች | 60s |
| API ቁልፍ | 7 ውድቀቶች | 12 ውድቀቶች | 30s |
| አካባቢያዊ | የሚሰላ | 2 ውድቀቶች | 15s |
`degradationThreshold` አንድ አቅራቢ መቼ ወደ `DEGRADED` እንደሚገባ ይቆጣጠራል፤ `failureThreshold` ደግሞ መቼ እንደሚከፈትና እንደሚዘለል ይቆጣጠራል። የአካባቢያዊ አቅራቢ መገለጫዎች እስካሁን በResilience ቅንብሮች ገጽ ላይ አይታዩም።
**የማቋረጫ ኮዶች፦** የአቅራቢ ደረጃ ሁኔታዎችን `[408, 500, 502, 503, 504]` ብቻ። በመለያ ደረጃ ለሚከሰቱ ስህተቶች (አብዛኞቹ 401/403/429 — እነዚህ በማቀዝቀዣ ጊዜ ወይም በመቆለፍ ሥር ይካተታሉ) ማቋረጫውን አያስነሱ።
**በፍላጎት ጊዜ መልሶ ማግኘት፦** `OPEN` ሲያበቃ፣ `getStatus()`፣ `canExecute()`፣ `getRetryAfterMs()` ሁኔታውን ወደ `HALF_OPEN` ያድሳሉ። የበስተጀርባ ሰዓት ቆጣሪ አያስፈልግም።
---
### በምርጫ የሚነቃ ዓለም አቀፍ የአቅራቢ ማቀዝቀዣ ጊዜ (የጊዜ መስኮት መግቢያ)
አራተኛው፣ **በምርጫ የሚነቃ** ንብርብር (`PROVIDER_COOLDOWN_ENABLED`፣ በነባሪ **የጠፋ**) ውድቀት
ያጋጠማቸውን አቅራቢዎች በጥያቄዎች መካከል የሚቆይ ማህደረ ትውስታ በ
`open-sse/services/providerCooldownTracker.ts` ውስጥ ይይዛል፤ ይህም በጥምር ዒላማ
ማግኛ ሂደት ይመከርበታል፣ ስለዚህ ተከታታይ የጥምር ጥያቄዎች በቅርቡ
ውድቀት ያጋጠመውን አቅራቢ እንደገና ማሰስ ያቆማሉ። የአቅራቢ ደረጃ ግቤቶች የ`PROVIDER_PROFILES` የጊዜ መስኮት መግቢያን ያከብራሉ፦
| መገለጫ | የሚነሳው ከ (`providerFailureThreshold`) በኋላ | በ (`providerFailureWindowMs`) ውስጥ | ለ (`providerCooldownMs`) ይቀዘቅዛል |
| ------- | ---------------------------------------: | --------------------------------: | ------------------------------: |
| OAuth | `10` | `15min` | `5min` |
| API ቁልፍ | `15` | `30min` | `10min` |
ከገደቡ በታች አቅራቢው በማቀዝቀዝ ላይ እንዳለ **አይቆጠርም**፤ ስኬታማ ምላሽ
የጊዜ መስኮቱን ያጸዳል። የግንኙነት ደረጃ ግቤቶች (`provider:connectionId`) በምትኩ
እየጨመረ የሚሄደውን `minRetryCooldownMs → maxRetryCooldownMs` የድጋሚ ሙከራ መዘግየት ይጠብቃሉ። ማሻሻያዎች፦
`OMNIROUTE_PROVIDER_BREAKER_{OAUTH,API_KEY}_{FAILURE_THRESHOLD,FAILURE_WINDOW_MS,COOLDOWN_MS}`።
የድግግሞሽ ስህተት መከላከያ፦ `tests/unit/provider-cooldown-window-gate.test.ts`።
## 2. የግንኙነት ማቀዝቀዣ ጊዜ
**ወሰን:** አንድ የአቅራቢ ግንኙነት/መለያ/ቁልፍ።
**ዓላማ:** ሌሎች የዚያው አቅራቢ ግንኙነቶች አገልግሎት መስጠታቸውን ሲቀጥሉ አንድ ችግር ያለበትን ቁልፍ ማለፍ።
**አተገባበር:**
- እንደማይገኝ ምልክት ማድረግ: `src/sse/services/auth.ts::markAccountUnavailable()`
- ምርጫ: በዚያው ፋይል ውስጥ `getProviderCredentials*`
- የማቀዝቀዣ ጊዜ ስሌት: `open-sse/services/accountFallback.ts::checkFallbackError()`
- ቅንብሮች: `src/lib/resilience/settings.ts`
**በእያንዳንዱ ግንኙነት የሚኖሩ መስኮች:**
- `rateLimitedUntil` — የማቀዝቀዣ ጊዜው እስኪያበቃ ያለው የጊዜ ማህተም
- `testStatus: "unavailable"`
- `lastError`, `lastErrorType`, `errorCode`
- `backoffLevel` — የኤክስፖነንሻል ማፈግፈግ ቆጣሪ
**ነባሪ የማቀዝቀዣ ጊዜያት:**
- የOAuth መሠረት: 5s
- የAPI ቁልፍ መሠረት: 3s
- የAPI ቁልፍ 429: ከላይኛው አገልግሎት የሚመጡ `Retry-After`/ዳግም ማስጀመሪያ ራስጌዎችን/ሊተነተን የሚችል የዳግም ማስጀመሪያ ጽሑፍን ይመርጣል
- ማፈግፈግ: `baseCooldownMs * 2 ** failureIndex`
**የተመሳሳይ ጊዜ ከፍተኛ ጥያቄ መከላከያ:** በተመሳሳይ ጊዜ የሚከሰቱ ውድቀቶች የማቀዝቀዣ ጊዜውን ከመጠን በላይ እንዳያራዝሙ ወይም `backoffLevel`ን ሁለት ጊዜ እንዳይጨምሩ ይከላከላል።
**የመጨረሻ ሁኔታዎች (የማቀዝቀዣ ጊዜያት አይደሉም):**
- `banned` — በታገደ ቁልፍ ቃል / የመለያ እገዳ ማወቂያ ([BAN_DETECTION](../security/BAN_DETECTION.md)ን ይመልከቱ)፣ እንዲሁም በአንድ ጥያቄ ደረጃ ከላይኛው አገልግሎት በተከታታይ በሚደርሱ ሦስት እምቢታዎች (`request_rejected`፣ ለምሳሌ Anthropic OAuth 403 "Request not allowed" — `open-sse/services/requestRejectedStreak.ts`) ይቀናበራል፤ አንድ እምቢታ ብቻ ግንኙነቱን ለማቀዝቀዣ ጊዜ ብቻ ያስገባዋል
- `expired` (ከተወሰኑ ዳግም ሙከራዎች በኋላ ወደ መጨረሻ ሁኔታ ይሸጋገራል — ከኤክስፖነንሻል ማፈግፈግ ጋር `EXPIRED_RETRY_MAX = 3` — ስለዚህ ጊዜያዊ የOAuth ስህተቶች መለያው ለዘለቄታው ከመሰናከሉ በፊት ራሳቸውን ማስተካከል ይችላሉ)
- `credits_exhausted`
እነዚህ የማረጋገጫ መረጃዎች እስኪቀየሩ ወይም ኦፕሬተር ዳግም እስኪያስጀምራቸው ድረስ ይቆያሉ። የመጨረሻ ሁኔታዎችን በጊዜያዊ የማቀዝቀዣ ሁኔታ አይተኩ።
**ሰነፍ መልሶ ማግኛ:** `rateLimitedUntil` ካለፈ በኋላ ግንኙነቱ እንደገና ለምርጫ ብቁ ይሆናል። በተሳካ ሁኔታ ጥቅም ላይ ሲውል `clearAccountError()` ሁሉንም የስህተት መስኮች ያጸዳል።
### የክፍለ ጊዜ ትስስር (#7274)
**ወሰን:** አንድ የደንበኛ ክፍለ ጊዜ (`X-Session-Id` / `x-codex-session-id` / `x-omniroute-session` ራስጌ) ለ**ማንኛውም** አቅራቢ ከአንድ ግንኙነት ጋር ይያያዛል።
**ዓላማ:** ባለብዙ-ዙር ወኪልን (Claude Code፣ aider፣ ብጁ ወኪሎች) በተለያዩ ጥያቄዎች ላይ በተመሳሳዩ መለያ እንዲቆይ ማድረግ፤ ይህም በመለያዎች መካከል የአውድ መጥፋትን እና በእያንዳንዱ መለያ የክፍለ ጊዜ ሁኔታ ባላቸው አቅራቢዎች ላይ ተደጋጋሚ የመጀመሪያ ማስጀመሪያ 429ዎችን ይቀንሳል።
**አተገባበር:**
- የTTL ውሳኔ: `src/sse/services/sessionAffinityPin.ts::resolveSessionAffinityTtlMs()`
- የማያያዣ ምርጫ/ፈጠራ: `src/sse/services/sessionAffinityPin.ts::selectSessionAffinityConnection()`
- የራስጌ ማውጣት (አጠቃላይ፣ ለማንኛውም አቅራቢ): `src/sse/services/auth.ts::extractSessionAffinityKey()`
- ቋሚ የማያያዣ ሰንጠረዥ: `sessionAccountAffinity` (`src/lib/db/sessionAccountAffinity.ts`)
- ቅንብር: `sessionAffinityTtlMs` (በms የሚለካ ዓለም አቀፍ TTL፣ `0` ያሰናክለዋል) — `src/lib/db/settings.ts`። ከCodex-ብቻ `codexSessionAffinityTtlMs` በፍልሰት `124_generic_session_affinity_ttl.sql` ስሙ ተቀይሯል፤ ይህም ከዚህ በፊት የተዋቀረውን ማንኛውንም የCodex TTL እንደ አዲሱ ነባሪ ያስተላልፋል።
ከ#7274 በፊት፣ `resolveSessionAffinityTtlMs()` ከ`codex` በስተቀር ለሁሉም አቅራቢዎች ወዲያውኑ `0` በመመለስ ይቋረጥ ነበር፤ ስለዚህ የማያያዝ ዘዴው እና የራስጌ ማውጣቱ ቀድሞውኑ ከአቅራቢ ነፃ ቢሆኑም የTTL ቅንብሩ (እና የክፍለ ጊዜ ራስጌዎቹ) በሌላ ቦታ ምንም ተጽዕኖ አልነበራቸውም። ማስተካከያው ያንን ቀደምት መመለስ አስወግዷል፤ TTLው ከላይ በዓለም አቀፍ ደረጃ ከ`0` በላይ ከተቀናበረ በኋላ አሁን ለእያንዳንዱ አቅራቢ በእኩል ይተገበራል።
ሦስቱ የክፍለ ጊዜ ትስስር ራስጌዎች ወደ ላይኛው አገልግሎት ፈጽሞ አይተላለፉም — አስፈጻሚዎች የደንበኛ ራስጌዎችን በቀጥታ ከማሳለፍ ይልቅ የራሳቸውን የላይኛው አገልግሎት ራስጌዎች ከባዶ ይገነባሉ፤ ስለዚህ ይህ የውስጥ ማዛመጃ id ብቻ ሆኖ ይቆያል።
### ብቸኛ የሚተዳደሩ የክፍለ ጊዜ ግንኙነት ኪራዮች
**ወሰን:** አንድ ንቁ የሚተዳደር HTTP ደንበኛ/ክፍለ ጊዜ አንድ ብቁ የOmniRoute ግንኙነት ይይዛል።
**ዓላማ:** በተለያዩ ጥያቄዎች መካከል ጥብቅ የማዞሪያ
ድንበር ለሚያስፈልጋቸው ደንበኞች ዘላቂ ብቸኛ የግንኙነት ባለቤትነትን መስጠት። ይህ ለስላሳ የቀጣይነት ምርጫ ከሆነው የክፍለ ጊዜ ትስስር ይለያል፦
ብቸኛ ኪራይ የሕይወት ዑደት ሁኔታን በSQLite ውስጥ በቋሚነት ያስቀምጣል፣ ዓለም አቀፋዊ የንቁ-ባለቤት እና
የንቁ-ግንኙነት ልዩነትን ያስገድዳል፣ እና ወደ አቅራቢው ከመላኩ በፊት ጊዜ ያለፈበትን ትውልድ ውድቅ ያደርጋል።
ባህሪው ለእያንዳንዱ API ቁልፍ በምርጫ የሚነቃ ነው። የሚተዳደር ቁልፍ `lease:exclusive` ወሰን እና
በግልጽ የተቀመጠ ባዶ ያልሆነ `allowedConnections` ዝርዝር ሊኖረው ይገባል። ማንኛውም HTTP ደንበኛ የሕይወት ዑደት መጨረሻ ነጥቡን መጠቀም ይችላል፤
የደንበኛ ስም፣ የተጠቃሚ ወኪል፣ አቅራቢ፣ የOAuth ዘዴ ወይም ሞዴል አያስፈልግም። ኪራዩ የሚይዘው ግንኙነት እንጂ
ሞዴል አይደለም፤ ስለዚህ ግንኙነቱ በመደበኛነት ብቁ ሆኖ እስከቆየ ድረስ የሞዴል ለውጥ ትስስሩን ይዞ ይቆያል።
መደበኛ የሞዴል፣ የኮታ፣ የጤና፣ የማቀዝቀዣ ጊዜ እና የፈቃድ ዝርዝር ደንቦች ወሳኝ ሆነው ይቀጥላሉ፣ እና
ተመሳሳዩን ትውልድ ወደ ሌላ ነፃ ብቁ ግንኙነት ሊያሸጋግሩ ይችላሉ።
የሕይወት ዑደቱ `POST /api/v1/session-leases` ሲሆን የJSON ድርጊቶቹ `acquire`፣ `renew` እና `release` ናቸው።
የሚተዳደሩ የግምት ጥያቄዎች ግልጽ ያልሆነውን `X-OmniRoute-Lease-Owner` እሴት እና ትክክለኛውን
`X-OmniRoute-Lease-Generation` ያቀርባሉ። ባለቤቱ `vlo_`ን በ43 base64url ቁምፊዎች ያስከትላል፤
የሚቀመጠው የእሱ SHA-256 ሃሽ ብቻ ነው። እያንዳንዱ የመጨረሻ የመላኪያ ድንበር የተረጋገጠውን የAPI ቁልፍ ID እና
የንቁ ግንኙነት IDንም ያስተሳስራል። የኪራይ መቆጣጠሪያ ራስጌዎች ከምዝግቦች፣ ተጠብቀው ከሚቆዩ የጥያቄ ቅጽበተ-ምስሎች እና
ከላይኛው አገልግሎት አስፈጻሚ ራስጌዎች ይወገዳሉ።
መደበኛ ማዞሪያ ብቁ የሚተዳደሩ እጩዎች ካሉት፣ ነገር ግን እያንዳንዱ ነፃ እጩ በሌላ
ንቁ ኪራይ የተያዘ ከሆነ፣ OmniRoute HTTP `429`፣ lease-capacity-unavailable ኮድ፣
አቅምን-የመጠበቅ ሁኔታ እና በቀደመው ተዛማጅ የማብቂያ ጊዜ ላይ የተመሠረተ የተገደበ `Retry-After` ይመልሳል።
መደበኛ ባዶ ብቁነት የኪራይ ፉክክር አይደለም፣ እና ነባሩን የማዞሪያ ስህተት ትርጉም ይዞ ይቆያል።
ተዛማጅ ዘዴዎች ተለያይተው ይቆያሉ፦
- የOAuth ክፍለ ጊዜ ይዞታ ለOAuth መለያዎች በሂደት ውስጥ ብቻ የሚኖር ለስላሳ ስርጭት ነው።
- የመለያ ሴማፎሮች የጥያቄ-በተመሳሳይ-ጊዜ ፈቃዶችን ይሰጣሉ፣ እና ጥያቄው ሲጠናቀቅ ያበቃሉ።
- ብቸኛ የሚተዳደሩ የክፍለ ጊዜ ኪራዮች የትውልድ ድንበር ያለው ዘላቂ የሕይወት ዑደት ባለቤትነት ናቸው።
---
## 3. የሞዴል መቆለፊያ
**ወሰን:** አቅራቢ + ግንኙነት + ሞዴል ሦስትዮሽ።
**የቁልፍ ወሰን በሁኔታ ኮድ:** የመቆለፊያ ሁኔታው መቆለፊያው በየትኛው ቁልፍ ላይ
እንደሚጻፍ ይወስናል (`resolveLockoutScope()` በ `open-sse/services/accountFallback/exactModelLock.ts` ውስጥ):
- `429` / `403` / `402` — የኮታ ወይም የመብት ምልክት — **የኮታ ቤተሰቡን** ይቆልፋሉ:
ለ codex ሙሉውን `codex` / `spark` ወሰን (የግንኙነቱን እያንዳንዱን
`gpt-5*` ሞዴል)፣ ለሌሎች አቅራቢዎች `getQuotaScopedModelForProvider()`።
- `404` መሠረታዊውን ሞዴል ይቆልፋል (`getModelLockKey()` `not_found`ን ያጠባል)።
- ማንኛውም ሌላ ሁኔታ — የ`5xx` ማጓጓዣ/አገልጋይ ውድቀቶች እና OmniRoute ራሱ
ከጥራት ማረጋገጫ የሚያመነጨው `502` — ትክክለኛውን
የአቅራቢ/ግንኙነት/ሞዴል ጥምረት ብቻ ይቆልፋል። በአንድ ሞዴል ላይ ያለ መጥፎ ዥረት
ስለ መለያው ኮታ ማስረጃ አይደለም፤ ከዚህ ደንብ በፊት በ
`codex/gpt-5.6-luna` ላይ ያለ አንድ ባዶ ምላሽ የዚያን ግንኙነት እያንዳንዱን `gpt-5*` ሞዴል
ከማዘዋወር ለ2–30 ደቂቃ (እየጨመረ) ያስወግድ ነበር፣ ኮታው ግን ሳይነካ ይቀር ነበር።
- የጠሪው ግልጽ `scope` አማራጭ ሁልጊዜ ቅድሚያ ያገኛል (Antigravity `"exact"`ን ያስተላልፋል)።
**ዓላማ:** አንድ ሞዴል ብቻ በማይገኝበት ወይም ኮታው በተገደበበት ጊዜ ሙሉ ግንኙነትን ከማሰናከል መቆጠብ።
**ምሳሌዎች:**
- የ429 ምላሽ የሚመልሱ በየሞዴሉ ኮታ ያላቸው አቅራቢዎች
- ላልተገኘ አንድ ሞዴል 404 የሚመልሱ አካባቢያዊ አቅራቢዎች
- ለአቅራቢው የተለዩ የሁነታ/ሞዴል ፈቃድ ውድቀቶች (ለምሳሌ፣ Grok ሁነታዎች)
**ትግበራ:** `open-sse/services/accountFallback.ts` — `lockModel()`፣ `clearModelLock()`፣ `getAllModelLockouts()`።
### የሞዴል ማቀዝቀዣዎች ዳሽቦርድ (v3.8.0)
የተጠቃሚ በይነገጽ: ቅንብሮች → የሞዴል ማቀዝቀዣዎች (`src/app/(dashboard)/dashboard/settings/components/ModelCooldownsCard.tsx`)
ንቁ መቆለፊያዎችን ከሚከተሉት ጋር ይዘረዝራል: አቅራቢ፣ ግንኙነት፣ ሞዴል፣ ምክንያት፣ expiresAt። ኦፕሬተሮች ከካርዱ ላይ ሞዴልን በእጅ ዳግም ማንቃት ይችላሉ።
**REST API:**
- `GET /api/resilience/model-cooldowns` — ንቁ መቆለፊያዎችን ይዘረዝራል
- `DELETE /api/resilience/model-cooldowns` — በእጅ ዳግም ማንቃት። የጥያቄ ይዘት: `{provider, connection, model}`። ማረጋገጫ: አስተዳደር።
### የመቆለፊያ ቅንብሮች የተጠቃሚ በይነገጽ + በስኬት-መቀነስ የሚደረግ መልሶ ማገገም (v3.8.23)
የሞዴል መቆለፊያ ሁልጊዜ ከሚሠራ በኮድ ውስጥ በቀጥታ ከተቀመጠ ባህሪ ወደ ሙሉ በሙሉ ሊዋቀር የሚችል፣
በምርጫ የሚነቃ ባህሪ፣ የራሱ የቅንብሮች ካርድ እና ራሱን የሚያስተካክል የመልሶ ማገገሚያ መንገድ ወዳለው ተቀይሯል።
**የቅንብሮች ካርድ:** ቅንብሮች → የሞዴል መቆለፊያ
(`src/app/(dashboard)/dashboard/settings/components/ModelLockoutCard.tsx`)።
ይህ ከላይ ካለው ለንባብ ብቻ ከሆነው `ModelCooldownsCard` (**ንቁ መቆለፊያዎችን
_ብቻ ከሚዘረዝር_) የተለየ ነው — አዲሱ ካርድ _መለኪያዎቹን ያዋቅራል_። ነባሪዎቹ
በ `DEFAULT_MODEL_LOCKOUT_SETTINGS`
(`src/lib/resilience/modelLockoutSettings.ts`) ውስጥ ይገኛሉ:
| ቅንብር | ነባሪ | ትርጉም |
| ----------------------- | -------------------------------- | ------------------------------------------------- |
| `enabled` | `false` | ዋና ማብሪያ/ማጥፊያ — የሞዴል መቆለፊያ **በነባሪ ጠፍቷል**። |
| `errorCodes` | `[403, 404, 429, 502, 503, 504]` | በሞዴል ወሰን ውስጥ እንደ ውድቀት የሚቆጠሩ የላይኛው ምንጭ ሁኔታዎች። |
| `baseCooldownMs` | `120_000` (120 ሰከንድ) | ለመጀመሪያው ውድቀት የመነሻ መቆለፊያ ቆይታ። |
| `maxCooldownMs` | `1_800_000` (30 ደቂቃ) | እየጨመረ በሚሄደው የማቀዝቀዣ ጊዜ ላይ የተቀመጠ ከፍተኛ ገደብ። |
| `maxBackoffSteps` | `10` | ከፍተኛው የኤክስፖነንሻል-መዘግየት መጨመሪያ ደረጃዎች ብዛት። |
| `useExponentialBackoff` | `true` | ተደጋጋሚ ውድቀቶች የማቀዝቀዣ ጊዜውን በኤክስፖነንሻል ሁኔታ ያሳድጉ እንደሆነ። |
ቅንብሮች በመደበኛው የቅንብሮች ማከማቻ በኩል በቋሚነት ይቀመጣሉ እና በ
የጽናት ቅንብሮች ንድፍ በኩል ይረጋገጣሉ፤ ካርዱ `baseCooldownMs`/`maxCooldownMs`ን
(`maxCooldownMs ≥ baseCooldownMs` በሆነ መልኩ) እና `maxBackoffSteps`ን በወሰን ውስጥ ያደርጋል።
**በስኬት-መቀነስ የሚደረግ መልሶ ማገገም:** መልሶ ማገገም የሰዓት ቆጣሪው በማለቁ **ብቻ** አይደለም። ጤናማ
ምላሽ የሞዴሉን የውድቀት ብዛት ቀስ በቀስ ወደ ታች ይመልሰዋል፣ በዚህም በጊዜ መስኮቱ መካከል ያገገመ ሞዴል
የሰዓት ቆጣሪው ከማለቁ በፊት መጨመሩን ያቆማል (እና ይጸዳል)። በተሳካ የጥምረት
ዒላማ ላይ፣ `open-sse/services/combo.ts` `decayModelFailureCount()`ን
(`open-sse/services/accountFallback.ts`) ይጠራል፤ ይህም የተከማቸውን
`failureCount` **በግማሽ ይቀንሳል** (`Math.floor(failureCount / 2)`)፤ ወደ `0` ሲደርስ የመቆለፊያ
መዝገቡ ሙሉ በሙሉ ይሰረዛል። ተጓዳኙ `recordModelLockoutFailure()`
በመጨመሪያ ጊዜ መስኮቱ ውስጥ ውድቀቶች ሲከሰቱ ብዛቱን ይጨምራል (እና የማቀዝቀዣ ጊዜውን ያሳድጋል)።
ይህ በስኬት-መቀነስ የሚደረግ መልሶ ማገገም ከመደበኛው የሰዓት ቆጣሪ ማብቃት በተጨማሪ ነው —
ከሁለቱ ማንኛውም መንገድ ሞዴልን ዳግም ማንቃት ይችላል።
**ሁኔታ:** መቆለፊያዎች **በማህደረ ትውስታ ውስጥ** ይያዛሉ (በእያንዳንዱ ሂደት `Map`ዎች፣
በ `provider:connectionId:model` የተቆለፉ `ModelLockoutEntry`፣ ትክክለኛ-ወሰን መቆለፊያዎች በ
`provider:connectionId:exact:model` የተቆለፉ)፣ በ
DB ውስጥ በቋሚነት አይቀመጡም — ዳግም ሲነሳ ይጠፋሉ። _ቅንብሮቹ_ በቋሚነት ይቀመጣሉ፤ ንቁው
የመቆለፊያ _ሁኔታ_ ጊዜያዊ ነው።
---
## 4. የኮታ-መጋራት ተመሳሳይ-ጊዜ መቆጣጠሪያ (v3.8.36)
የደንበኝነት ምዝገባ መለያዎች (GLM፣ MiniMax፣ ወዘተ.) ብዙውን ጊዜ በተመሳሳይ ጊዜ ~1–3 ጥያቄዎችን ብቻ ይቀበላሉ፤ ይህን ማለፍ 429 ስህተቶችን እና የማቀዝቀዣ ጊዜዎችን ያስነሳል። ይህ በተለይ
በ**quota-share** (`qtSd/…`) ጥምረቶች ሥር ከባድ ነው፤ በዚያም በርካታ API ቁልፎች አንድ upstream
መለያ ይጋራሉ። ሦስት ንብርብሮች የጋራ መለያው በጥያቄዎች እንዳይጥለቀለቅ ያደርጋሉ።
### የእያንዳንዱ ግንኙነት ተመሳሳይ-ጊዜ ገደብ (`max_concurrent`)
እያንዳንዱ የአቅራቢ ግንኙነት የ`max_concurrent` ጣሪያ ሊያውጅ ይችላል
(`provider_connections.max_concurrent`፣ በግንኙነት modal / API / DB ውስጥ የሚዋቀር)።
ገደብ እንዳይኖር ባዶውን ይተዉት። ይህ ከታች ያለውን የተከታታይ አፈጻጸም
ንብርብር የሚቆጣጠረው ብቸኛ ቅንብር ነው — ወደ መለያው ትክክለኛ የተመሳሳይ-ጊዜ አቅም ያዋቅሩት (ለምሳሌ GLM ~1፣ MiniMax ~2)።
### የኮታ-መጋራት ጥያቄዎችን በተከታታይ ማስኬድ
የquota-share ማሰራጨት አዎንታዊ `max_concurrent` ያወጀ ግንኙነትን ሲያነጣጥር፣ ወደዚያ **መለያ** የሚላኩ ተመሳሳይ-ጊዜ ጥያቄዎች በየግንኙነቱ semaphore (ቁልፍ `qsconn:<connectionId>`) በኩል በተከታታይ ይሰራሉ፦ ትርፍ ጥያቄዎች መለያውን ከማጥለቅለቅ ይልቅ **በወረፋው ውስጥ ይጠብቃሉ**። ይህ **fail-open** ነው — የተሞላ ወረፋ ወይም timeout ሊሰራጭ የሚችልን ጥያቄ ከመከልከል ይልቅ ያለ slot እንዲቀጥል ያደርጋል። በ**Settings → Resilience → Quota-share per-connection concurrency**
(`resilienceSettings.quotaShareConcurrencyLimit.enabled`፣ በነባሪ በርቷል) ውስጥ ያብሩት ወይም ያጥፉት። ያለ `max_concurrent` ገደብ ባህሪው አይለወጥም።
> የquota-share ማስተላለፊያ በር (`selectQuotaShareTarget`፣ DRR + P2C) ራሱ
> fail-open ሲሆን፣ ገደቡ ላይ ያለን ግንኙነት _ቅድሚያውን ብቻ ይቀንሳል_ — አንድ ግንኙነት ብቻ ባለው pool ውስጥ ጥብቅ ገደብ ማድረግ አይችልም፤ ስለዚህ ጎርፉን በተግባር የሚቆጣጠረው ይህ semaphore ነው።
### የCombo cooldown ንቁ ዳግም ሙከራ
ለእያንዳንዱ combo ስትራቴጂ (ሲነቃ)፣ ለአጭር ጊዜያዊ cooldown የ429 ስህተትን የሚያረጋግጥ ጥያቄ 429ን ከመመለስ ይልቅ የcooldown ጊዜው እስኪያልፍ ይጠብቅና እንደገና ይሰራጫል — ይህ በባለብዙ-model combos ላይ ያሉ Gemini-class TPM/RPM መስኮቶችን (~60s retry-after) ይሸፍናል፤ ለምሳሌ የ2-model combo ሁለቱም ዒላማዎች በእያንዳንዱ model የፍጥነት ገደብ ላይ ሲደርሱ። ይህ በ**Settings → Resilience** ውስጥ ባለው `comboCooldownWait` (`enabled`፣ `maxWaitMs`፣ `maxAttempts`፣ `budgetMs`) የተገደበ ነው። ለ`quota_exhausted` (እስከ እኩለ ሌሊት የተቆለፈ) ወይም ከauth/not-found ጋር የተያያዙ ምክንያቶች ፈጽሞ አይጠብቅም።
---
## 5. የጥያቄ ወረፋ መግቢያ ቁጥጥር (v3.8.49 · issue #6593)
**ወሰን**፦ የአካባቢው በየአቅራቢው+ግንኙነቱ የፍጥነት ገደብ ወረፋ (`open-sse/services/rateLimitManager.ts`፣
በBottleneck የሚደገፍ)፣ ከላይ ካሉት ሦስት ዘዴዎች አንድ ንብርብር በታች።
**`maxWaitMs` ለአፈጻጸም ማብቂያ የቆየ ቋሚ ስም ነው።**
`resilienceSettings.requestQueue.maxWaitMs` እንደ job `expiration` ወደ Bottleneck ይተላለፋል፤ timer የሚጀምረውም ከማሰራጨት በኋላ ብቻ ነው። ስለዚህ ይህ በአካባቢው ወረፋ ውስጥ የሚጠፋውን ጊዜ ሳይሆን በlimiter የሚተዳደረውን አፈጻጸም ይገድባል። Expiration እንደ ታማኝ የአካባቢ `code: "RATE_LIMIT_EXECUTION_TIMEOUT"` (HTTP 504) ይቀርባል፤ የቀድሞው የqueue-timeout code ስም የሚቀበለው ለታማኝ ውስጣዊ የኋላ ተኳኋኝነት ብቻ ነው። ነባሪው 15000ms ነው፤ በ`RATE_LIMIT_MAX_WAIT_MS` (env) ወይም በdashboard (**Settings → Resilience**፣
1–30000ms UI ጣሪያ) በኩል ይቀይሩት። በወረፋ ውስጥ ለሚቆይበት ጊዜ የጊዜ ገደብ የለውም፤ ወረፋ የያዙ ጠሪዎችን ለመገደብ ከታች ያለውን `maxQueueDepth` ይጠቀሙ።
**`maxQueueDepth` — በምርጫ የሚነቃ የመግቢያ ገደብ (አዲስ)።** `resilienceSettings.requestQueue.maxQueueDepth`
ለአንድ provider+connection በአንድ ጊዜ ምን ያህል ጥያቄዎች በወረፋ ውስጥ (ገና ሳይሰራጩ) መቀመጥ እንደሚችሉ ይገድባል። ወረፋው አስቀድሞ `maxQueueDepth` ጥያቄዎችን ከያዘ፣ አዲስ ጥያቄ ወደ `limiter.schedule()` ከመድረሱ **በፊት** በtyped `code: "RATE_LIMIT_QUEUE_FULL"` ስህተት በፍጥነት ውድቅ ይደረጋል — ስለዚህ ውድቅ ማድረጉ አነስተኛ ወጪ ያለው ሲሆን ለዚያ ጥያቄ ማንኛውም downstream prompt-compression / translation ሥራ ከመከናወኑ በፊት ይፈጸማል። ነባሪ `0` =
የተሰናከለ፣ ነባሩን ያልተገደበ የወረፋ ባህሪ የሚጠብቅ፤ የተፈቀደው ወሰን 0–100000 ነው።
በ`RATE_LIMIT_MAX_QUEUE_DEPTH` (env) ወይም
`resilienceSettings.requestQueue.maxQueueDepth` (dashboard/API patch) በኩል ይቀይሩት።
የመግቢያ ማረጋገጫው ራሱ pure function ነው
(`open-sse/services/rateLimitManager/admission.ts::checkQueueAdmission`)፤ ስለዚህ እውነተኛ Bottleneck limiter ሳያስፈልግ unit-test ሊደረግ ይችላል።
> #6593ን የከፈተው RFC የ`bypassCompressionOnRateLimit`
> flagንም ሐሳብ አቅርቦ ነበር። የዚህ repo `open-sse/services/compression/` pipeline
> በoutbound LLM ጥያቄ ላይ የprompt/context compression ነው (`chatCore.ts`፣
> በ`resolveCompressionSettings`/`selectCompressionStrategy` block አካባቢ)፤
> በተፈጠሩ 429 bodies ላይ የHTTP response compression አይደለም — ለቀጥተኛ bypass flag የሚዛመድ የcode path የለም። ያ የprompt-compression ደረጃም በአሁኑ ጊዜ በጥያቄ pipeline ውስጥ ከ`withRateLimit()` _በፊት_ ይሰራል፤ ስለዚህ queue-full rejection ሲኖር እሱን ለመዝለል ቅደም ተከተሉን እንደገና ማደራጀት ከዚህ issue ወሰን የተለየና የበለጠ ትልቅ ለውጥ ነው፤ እዚህ ላይ ሆን ተብሎ **አልተተገበረም**፣ እና CPUን ከመቆጠብ የሚገኘው ጥቅም የቅደም ተከተል ለውጡን አደጋ የሚያዋጣ ከሆነ ለቀጣይ ሥራ ተትቷል።
---
## 6. የዝግተኛ ዥረት የውጤት መጠን ተቆጣጣሪ (#9709)
አማራጭ የሆነው `resilienceSettings.streamRecovery.throughputWatchdog` ጥበቃ፣
አሁንም chunks እየላከ ነገር ግን ከተዋቀረው ጠቃሚ የውጤት መጠን በታች የረዳት ውጤት
እያመነጨ ያለ upstream ይለያል። ይህ ሆን ተብሎ ከidle timeout የተለየ ነው፦
heartbeats እና metadata የትኛውንም timer ዳግም አያስጀምሩም፣ እንደ እድገትም
አይቆጠሩም። የውጤት ጥራት ምንም ይሁን ምን ፍጹም የደህንነት ጣሪያ ሆኖ
ከሚቆየው hard attempt deadline (#9153) ጋርም የተለየ ነው።
watchdog ማቋረጥ ከመቻሉ በፊት የማሟሟቂያ ጊዜ እና ከዚያ በኋላ ሙሉ rolling window
ያስፈልገዋል። ከChat Completions እና Responses API የውጤት ክስተቶች የሚመጡ
የጽሑፍ deltas ይቆጥራል (ጥንቃቄ የተደረገበት የUTF-8 byte ግምታዊ መለኪያ)፣
usage-only እና ባዶ ክስተቶችን ችላ ይላል፣ እንዲሁም tool-call ወይም reasoning
ክስተቶች በሂደት ላይ ሳሉ ግምገማውን ያቆማል። በነባሪነት ተሰናክሏል እና
በ`STREAM_THROUGHPUT_WATCHDOG_ENABLED=true` ማንቃት ይቻላል፤ window፣
warm-up፣ ዝቅተኛው rate እና ሊለካ የሚችለው ዝቅተኛ ውጤት በመደበኛው
resilience-settings normalization layer ገደብ ውስጥ ይቀመጣሉ።
ሲነቃ፣ የwatchdog ማቋረጥ ተግባራዊ የሚሆነው ንቁ በሆነው upstream attempt ላይ
ብቻ ነው። ማንኛውም client-visible bytes ከመላካቸው በፊት፣ ነባሩ
same-account early-recovery path attemptን እንደገና ሊከፍት ይችላል። commit ከተደረገ
በኋላ ዥረቱ ያለጥንቃቄ በድጋሚ አይጫወትም፤ suffixን ማገናኘት የሚችለው ነባሩ
ደህንነቱ የተጠበቀ mid-stream continuation contract ብቻ ነው። Finalization
አንድ ጊዜ ብቻ የሚከናወን ሆኖ ይቀጥላል፣ ስለዚህ usage accounting እና semaphore
release አይደጋገሙም።
---
## 7. የUpstream ሁኔታ ዳግም መግለጫ (በስህተት የተገለጹ የኮታ ስህተቶች)
**ወሰን፦** ጊዜያዊ የኮታ መሟጠጥን በተሳሳተ HTTP status የሚዘግብ አንድ upstream gateway።
**ዓላማ፦** downstream ተጠቃሚዎች (fallback engine፣ combo aggregation፣ ለclient የሚታየው response) የውድቀቱን እውነተኛ እንደገና ሊሞከር የሚችል ባህሪ እንዲያዩ፣ ከclassification በፊት አሳሳች statusን ማረም።
አንዳንድ gateways ጊዜያዊ የኮታ መሟጠጥን እንደገና ሊሞከር በማይችል HTTP
status ያመለክታሉ። `agentrouter.org` ከመደበኛው `429` ይልቅ `403` (አንዳንድ ጊዜ
`400`) ከቻይንኛ body (`用户额度不足` / `额度不足`) ጋር ይመልሳል። እንደ Claude
Code ያሉ clients `403`ን እንደ ቋሚ ውድቀት በመቁጠር sessionን ያቋርጣሉ፣ እና
እርማት ከሌለ fallback engine እንደ የኮታ ክስተት ሳይሆን እንደ `AUTH_ERROR`
ይመድበዋል።
**አተገባበር፦**
- Registry + matcher፦ `open-sse/config/upstreamStatusRestatement.ts` — ለእያንዳንዱ
provider የሚዘጋጅ የሕጎች ዝርዝር (`{id, fromStatuses, toStatus, textMarkers,
excludeMarkers, defaultRetryAfterMs}`)፣ በ`applyStatusRestatement()` በኩል የሚዛመድ።
- የጥሪ ቦታ፦ በ`open-sse/handlers/chatCore.ts` ውስጥ ያለው `providerFailure:` block
(በመስመር 3654 አካባቢ)፣ `parseUpstreamError()` የerror HTTP status ያለውን upstream
response (`!providerResponse.ok`) ከተነተነ ወዲያውኑ እና ማንኛውም
classification ከመካሄዱ በፊት፣ ይህም እያንዳንዱ downstream ተጠቃሚ የታረመውን
status እንዲያይ ያደርጋል። በ`200` SSE stream ውስጥ የተካተቱ ስህተቶች የተለየ፣
በኋላ የሚከናወን stream-parsing pathን ይከተላሉ እና በአሁኑ ጊዜ በዚህ hook
**አይሸፈኑም** — ይህ የታወቀ ገደብ ነው፣ ነገር ግን እንደ error HTTP status
ለሚታየው የagentrouter misstatus እስካሁን አላስፈለገም።
- እንደገና የመሞከር ብቁነት፦ `429` በ`RETRY_AFTER_ELIGIBLE_STATUSES`
(`open-sse/services/combo/unavailableRetryGate.ts`) ውስጥ ስላለ፣ እንደገና የተገለጸ
error እንደ የማይሰራ `403` ከመታየት ይልቅ እውነተኛ የretry window ይይዛል።
- ሰው ሠራሹ `60s` `defaultRetryAfterMs` (`upstreamStatusRestatement.ts`)
እንደገና የተገለጸው response ለ**client** የሚነግረው ብቻ ነው፤ ይህ ራሱ
የconnectionው ውስጣዊ cooldown/lockout ጊዜ አይደለም — ያንን የሚወስነው
እንደገና የተገለጸውን error በተግባር የሚያስተናግደው የተለየ mechanism ነው
(የConnection Cooldown እየጨመረ የሚሄድ backoff፣ §2፣ ለAPI-key providers
መሠረታዊ `3s`፤ ወይም እንደ agentrouter ላሉ per-model-quota providers የModel
Lockout፣ §3)። router ለclient ከሚያሳውቀው የ60s window ቀደም ብሎ በውስጥ
እንደገና ለመሞከር ብቁ ሊሆን ይችላል — ይህ ሆን ተብሎ የተቀመጠ headroom ነው
እንጂ bug አይደለም።
ቋሚ ስህተቶች (የagentrouter `无权访问模型` — ይህን ሞዴል የመድረስ ፈቃድ የለም)
በፍጹም እንደገና አይገለጹም፦ `textMarkers` ቢዛመዱም `excludeMarkers` ሕጉን
ውድቅ ያደርገዋል፣ ስለዚህ error የመጀመሪያ statusን ይዞ ይቆያል እና ምንም ነገር
ለዘላለም እንደገና አይሞክረውም። የሚዛመደው provider classification rule
(`agentrouter-model-access-denied` በ`open-sse/config/providerErrorRules.ts` ውስጥ፦
`reason: "auth_error"`፣ `scope: "model"`፣ የታወጀ `6h` base cooldown)
በ`checkFallbackError` (`open-sse/services/accountFallback.ts`) የሚፈተሸው
ከአጠቃላይ apikey-category `FORBIDDEN` early-return _በፊት_ ሲሆን፣
በ`honorsRuleLockScope(provider)` የተገደበ ነው (#10334 — በአሁኑ ጊዜ
በ`providerErrorRules.ts` ውስጥ ባለው `HONORS_RULE_LOCK_SCOPE_PROVIDERS` allowlist
አማካኝነት ለagentrouter ብቻ የተወሰነ)። ሕጉ ያወጀው የ6h cooldown
እንደ `fallbackResult.baseCooldownMs` ሙሉ በሙሉ ይተላለፋል፣ ነገር ግን አሁንም
ቀድሞ የነበረውን per-model-quota lockout path (`lockModelIfPerModelQuota()` /
`recordModelLockoutFailure()`፣ ከcooldown source በስተቀር በ#10334 ያልተለወጠ)
ይጠቀማል፦ እንደ ማንኛውም ሌላ model lockout ወደ operatorው
`mlSettings.maxCooldownMs` (ነባሪ `1_800_000ms` / 30min) ዝቅ ተደርጎ ይገደባል፣
እና _የሚቀመጠው lockout reason_ የሕጉ `"auth_error"` ሳይሆን ቀድሞ የነበረው
hardcoded `"forbidden"` ሆኖ ይቆያል — ከጫፍ እስከ ጫፍ የሚከበረው የcooldown
ቆይታ ብቻ ነው፣ reason string አይደለም። connectionው ራሱ ንቁ ሆኖ ይቆያል፤
በተመሳሳይ connection ላይ ያሉ sibling models አይጎዱም።
በድጋሚ የተገለጹ የኮታ ስህተቶች (`额度不足`) በምርት አካባቢ የአቅራቢ ደንብ ላይ ይደርሳሉ
(`agentrouter-user-quota-exhausted`: `reason: "quota_exhausted"`, `scope:
"connection"`፣ የራሱ የሆነ የተገለጸ የማቀዝቀዣ ጊዜ የለውም — የማከማቻ ንብርብሩ
ተመጣጣኝ የbackoff ነባሪ ቅንብር ተግባራዊ ይሆናል)። ከ#10334 ጀምሮ፣ በ
`ProviderErrorRuleMatch` ላይ ያለው `scope` ከጫፍ እስከ ጫፍ ጥቅም ላይ ይውላል፣ ነገር ግን **በ**
`HONORS_RULE_LOCK_SCOPE_PROVIDERS` ፈቃድ ዝርዝር ውስጥ ላሉ አቅራቢዎች ብቻ ነው
(`providerErrorRules.ts` — በአሁኑ ጊዜ `"agentrouter"` ብቻ፣ በ
`honorsRuleLockScope()` የተገደበ)። ለሌሎች አቅራቢዎች በሙሉ
`scope` ልክ ከ#10334 በፊት እንደነበረው መረጃ ሰጪ ብቻ ሆኖ ይቀራል።
`checkFallbackError` የተዛመደውን ደንብ ወሰን እንደ
`fallbackResult.ruleScope` ያቀርባል፤ `isAgentrouterConnectionQuotaScope()`
(`src/sse/services/auth.ts`) አንድ `ruleScope` በእውነት በግንኙነት ደረጃ
ተፈጻሚ እና ራሱን የሚያገግም ምልክት እንደሆነ ማክበር ደህንነቱ የተጠበቀ
መሆኑን የሚያረጋግጥ የጋራ guard ነው (`scope` `"connection"`፣ reason
`quota_exhausted`፣ ፈጽሞ `permanent` ያልሆነ፣ ፈጽሞ `creditsExhausted`
ያልሆነ — ወደፊት አንድ ደንብ `scope` `"connection"`ን ከቋሚ የመለያ ሁኔታ
ጋር እንዳያጣምር መከላከያ ነው)። ሁለት ተጠቃሚዎች ይጠሩታል፦
- **ማከማቻ** (`markAccountUnavailable()`, `src/sse/services/auth.ts`)፦
ወደ passthrough-provider **በእያንዳንዱ ሞዴል** የመቆለፊያ
ቅርንጫፍ ከመውደቅ ይልቅ (agentrouter `passthroughModels: true` ነው → `hasPerModelQuota()`
`true` ይመልሳል)፣ **ጊዜያዊ የግንኙነት ማቀዝቀዣ ጊዜ** ተግባራዊ ያደርጋል —
`testStatus: "unavailable"` + `rateLimitedUntil`፣ ፈጽሞ የመጨረሻ ሁኔታ
(`credits_exhausted`/`banned`/`expired`) አይደለም — ስለዚህ ግንኙነቱ
በእጅ የማረጋገጫ መረጃ ዳግም እንዲቀናበር ሳያስፈልገው የማቀዝቀዣው ጊዜ
ሲያበቃ በራሱ ያገግማል። `disableCooling: true` ላላቸው ግንኙነቶች
ይዘለላል (#2997)፦ ያ የመርጦ መውጣት በምትኩ ወደ በእያንዳንዱ ሞዴል
መቆለፊያ ይወርዳል (በሰነድ የተገለጸ የጥቅምና ጉዳት ሚዛን ነው —
ከቅርንጫፉ በላይ ያለውን የኮድ አስተያየት ይመልከቱ)።
- **በተመሳሳይ ጥያቄ ውስጥ የcombo ማስተላለፊያ** (`applyComboTargetExhaustion()`,
`open-sse/services/combo/targetExhaustion.ts`)፦ ያው guard ግንኙነቱን
`${provider}:${connectionId}` ቁልፍ ተጠቅሞ በማህደረ ትውስታ ውስጥ ባለው
`exhaustedConnections` set ላይ ምልክት ያደርግበታል። ይህ የሚዘለው ቀሪ
የተመሳሳይ-ጥያቄ ዒላማ፣ _ዒላማው ራሱ ያንኑ `connectionId` በራሱ_
የዒላማ ነገር ላይ አስቀድሞ የያዘ ከሆነ ብቻ ነው (`getExhaustedTargetSkipReason()`,
`open-sse/services/combo/comboPredicates.ts`፣ ከ`exhaustedConnections`
lookup በፊት `if (provider &&
connectionId)`) — የተለመደ የሞዴል-ዝርዝር combo፣ ወንድም ዒላማዎቹ የራሳቸው የተሰካ
`connectionId` የሌላቸውበት እና አንዱ ከምላሹ
`X-OmniRoute-Selected-Connection-Id` header በእያንዳንዱ dispatch ወቅት ብቻ
የሚወሰንበት፣ ያንን የቁልፍ መዛመድ ፈጽሞ አያገኝም። ለዚያ የተለመደ
ሁኔታ፣ አንድ ቀሪ leg አሁን ያለቀበትን መለያ እንዳይጠቀም የሚያደርገው
እውነተኛ ጥበቃ ይህ Set **አይደለም** — ከላይ ያለው የማከማቻ ንብርብር
(የግንኙነቱ `rateLimitedUntil` አሁን ወደፊት ላይ ነው) ከዚሁ guard ጋር
ተጣምሮ ለውድቀቱ `transientRateLimitedProviders`ን መጨቆኑ ነው
("ባለሁለት-ደረጃ ንድፍ" እና በ`targetExhaustion.ts` ውስጥ ባለው
`isAgentrouterConnectionQuotaScope` ቅርንጫፍ ላይ ያለውን የኮድ አስተያየት
ይመልከቱ)፦ ያ Set ምልክት ሳይደረግበት ሲቀር፣ የ`combo.ts`
`allowRateLimitedConnection` የግዳጅ-ፍቀድ (`open-sse/services/combo.ts:1005-1013`,
`:2734-2738`) ለቀሪዎቹ የአቅራቢው legs **አይ**ነሳም፣ ስለዚህ የማረጋገጫ
መረጃ ምርጫው `rateLimitedUntil` filter (`src/sse/services/auth.ts:1238`)
በተለመደው ሁኔታ ይከበራል፣ እና ቀሪው leg የተለየ፣ አሁንም ብቁ የሆነ
agentrouter ግንኙነት ይመርጣል ወይም ምንም የማረጋገጫ መረጃ ሳይገኝ
ይወድቃል — ይህ ቅርንጫፍ አሁን ወደ አቀዘቀዘው ግንኙነት በግድ
ተመልሶ አይገባም።
### ባለሁለት-ደረጃ ንድፍ፦ የሁኔታ ዳግም መግለጫ፣ ከዚያም ምደባ
የሁኔታ ዳግም መግለጫ (`upstreamStatusRestatement.ts`) እና የአቅራቢ
ምደባ ደንቦች (`open-sse/config/providerErrorRules.ts`,
`providerRuleRegistry`) ሁለቱም በአቅራቢ id እና በጽሑፍ ምልክቶች ቁልፍ
የሚያደርጉ የተለያዩ registries ናቸው፣ ነገር ግን በተለያዩ ቦታዎች
ይሰራሉ እና የተለያዩ ዓላማዎችን ያገለግላሉ፦ restatement በ`chatCore.ts`
ውስጥ ቀደም ብሎ የHTTP ሁኔታውን እንደገና ይጽፋል፤ የምደባ ደንቦች
ደግሞ በ`checkFallbackError()` ውስጥ የfallback `reason`ን እና የመቆለፊያ
`scope`ን (`model` / `provider` / `connection`) ይመርጣሉ
(`open-sse/services/accountFallback.ts`)።
የምደባ ደንቦች ሙሉ የስህተት **ጽሑፍ**ን (እንደ `额度不足` ያሉ
የbody ምልክቶችን ለማዛመድ የሚያስፈልገው) የሚያዩት በ
`providerErrorRules.ts` ውስጥ ባለው `FULL_TEXT_RULE_PROVIDERS`
ፈቃድ ዝርዝር ውስጥ ላሉ አቅራቢዎች ብቻ ነው — በአሁኑ ጊዜ
`"agentrouter"` ብቻ። ለሁሉም ሌሎች **አብሮገነብ ካታሎግ** አቅራቢዎች፣
`checkFallbackError` ለ`getProviderErrorRuleMatch` የሚያስተላልፈው
የተዋቀረውን ስህተት (`{code, type}`) ብቻ ነው፣ ይህም በ
header/status/code ላይ ለተመሰረቱ ደንቦች በቂ ቢሆንም የbody-ጽሑፍ
ምልክቶችን ማየት አይችልም። `resolveRuleMatchBody()` helper ይህን ምርጫ
ያከናውናል፦ በፈቃድ ዝርዝሩ ውስጥ ላሉ አቅራቢዎች ሙሉ የስህተት
ጽሑፍ፣ ካልሆነ የተዋቀረው ስህተት። አንድ **አብሮገነብ** አቅራቢን ወደ
`FULL_TEXT_RULE_PROVIDERS` ማከል ግልጽ የበእያንዳንዱ-አቅራቢ opt-in
ነው — ይህ የሚኖረው በዝርዝሩ ላይ ላልሆነ እያንዳንዱ አቅራቢ
ነባሪው መንገድ ባይት-በ-ባይት ሳይቀየር እንዲቆይ ነው።
የአንድ ደንብ `scope` (`model` / `provider` / `connection`) ከ
`FULL_TEXT_RULE_PROVIDERS` የተለየ opt-in ነው፦ `checkFallbackError`
ይህን እንደ `fallbackResult.ruleScope` ብቻ ያቀርበዋል፣ እና downstream
ተጠቃሚዎች በዚሁ ፋይል ውስጥ ባለው
`HONORS_RULE_LOCK_SCOPE_PROVIDERS` ፈቃድ ዝርዝር ውስጥ ላሉ አቅራቢዎች
ብቻ፣ ከመረጃ ሰጪ መለያ የተለየ ነገር እንደሆነ ያከብሩታል (`በ
honorsRuleLockScope()` የተገደበ — በአሁኑ ጊዜ `"agentrouter"` ብቻ)።
አንድ አቅራቢ በዚያ ፈቃድ ዝርዝር ላይ ከገባ በኋላ የ
`scope: "connection"` መዛመድ በትክክል ምን እንደሚያደርግ ለማየት
ከላይ ያለውን "በድጋሚ የተገለጹ የኮታ ስህተቶች" ይመልከቱ።
**#11104 — በኦፕሬተር የታወጁ ደንቦች ሁለቱንም የፍቃድ ዝርዝሮች ያልፋሉ።** አንድ ኦፕሬተር
ይህን ፋይል ሳያርትዕ በሩጫ ጊዜ በ`settings.providerErrorRules`
(`open-sse/config/providerErrorRules.ts::setOperatorProviderErrorRules`)
አማካኝነት ለእያንዳንዱ አቅራቢ ደንብ ማወጅ ይችላል። የኦፕሬተር ደንብን በ
`FULL_TEXT_RULE_PROVIDERS`/`HONORS_RULE_LOCK_SCOPE_PROVIDERS` — አብሮ የተሰሩ
የካታሎግ ደንቦችን **ነባሪ** ባህሪ ለመጠበቅ በታሰቡ የፍቃድ ዝርዝሮች —
ጀርባ መገደብ፣ ደንቡን ማወጅ ራሱ የኦፕሬተሩ ግልጽ የመርጦ መግባት
ውሳኔ ስለሆነ፣ ቀድሞውኑ በዚያ ከተዘረዘሩት በስተቀር ለሁሉም
አቅራቢዎች የቅንብሮቹን ስልት የማይሰራ ያደርገዋል። `resolveRuleMatchBody()`
እና `honorsRuleLockScope()` ሁለቱም መጀመሪያ
`hasOperatorRuleForProvider()`ን ይፈትሻሉ፦ የኦፕሬተር ደንብ ያለው
አቅራቢ፣ በሁለቱ የፍቃድ ዝርዝሮች ውስጥ ቢኖርም ባይኖርም፣
ጥሬውን የስህተት ጽሑፍ ያገኛል እና ያወጀው `scope` ይከበርለታል።
**የሚታወቅ ክፍተት — `providerRuleRegistry` ለHTTP 400 ፈጽሞ አይመከርም።**
የ`checkFallbackError` `BAD_REQUEST` ቅርንጫፍ ሁኔታ 400ን ሙሉ በሙሉ
በራሱ የስርዓተ-ጥለት ድርድሮች (`MODEL_ACCESS_DENIED_PATTERNS`,
`CONTEXT_OVERFLOW_PATTERNS`፣ ወዘተ በ`accountFallback.ts`) ይመድባል፣ እና
ከእሱ በላይ ያለው የ`configuredRule`/`getProviderErrorRuleMatch` ቅርንጫፍ
ከመድረሱ በፊት ይመለሳል። `status: 400` ያለው አብሮ የተሰራ የካታሎግ
ደንብ (ወይም የኦፕሬተር ደንብ) በአገባብ ትክክለኛ ቢሆንም ፈጽሞ
አይተገበርም። በአሁኑ ጊዜ 400ን የሚያነጣጥር ነባር ደንብ የለም፣
ስለዚህ በምርት አካባቢ ምንም ነገር አልተጎዳም — ነገር ግን ወደፊት
የሚጨመር የ400 ደንብ በመጀመሪያ ይህ ቅርንጫፍ እንዲሻሻል ይፈልጋል፤
ይህም ደንብ ከመጨመር የሚበልጥ ለውጥ ነው (ቀድሞውኑ በስርዓተ-ጥለት
ድርድር ባህሪ ላይ ለሚመረኮዝ እያንዳንዱ አቅራቢ 400ን እንደገና
ይመድባል)፣ እና ለአንድ አቅራቢ ብቻ የደንብ ጭማሪ ከተወሰነው ወሰን
ውጭ ነው።
### ኮታን በተሳሳተ መንገድ የሚገልጽ አዲስ መግቢያ በር ማከል
1. በ`statusRestatementRegistry`
(`open-sse/config/upstreamStatusRestatement.ts`) ውስጥ አንድ የደንብ ድርድር
ይመዝግቡ። `textMarkers`ን ለአቅራቢው የተለየ አድርገው ያቆዩ፤
ከ`CREDITS_EXHAUSTED_SIGNALS` (`open-sse/services/accountFallback.ts`) ጋር
የሚጋጩ አጠቃላይ የእንግሊዝኛ ሐረጎችን ፈጽሞ ዳግም አይጠቀሙ።
2. ትክክለኛውን የመቆለፊያ ወሰን (`connection` ለመለያው በሙሉ የሚመለከት
ኮታ፣ `model` ደግሞ ለእያንዳንዱ ሞዴል ስህተቶች) ለመምረጥ፣ እንደ
አማራጭ በ`open-sse/config/providerErrorRules.ts`
(`providerRuleRegistry`) ውስጥ የምደባ ደንቦችን ይመዝግቡ። ይህ ደረጃ
ሙሉውን የስህተት ጽሑፍ (የይዘት ምልክቶች) ለሚፈልጉ ደንቦች በምርት
አካባቢ ተግባራዊ የሚሆነው ለተወሰኑ አቅራቢዎች ብቻ ነው፦ የአቅራቢውን
id በዚያው ፋይል ወደ `FULL_TEXT_RULE_PROVIDERS` ያክሉ — ካልሆነ
`checkFallbackError` ለደንቡ የሚያስተላልፈው የተዋቀረውን
`{code, type}` ስህተት ብቻ ስለሆነ፣ የይዘት-ጽሑፍ ደንብ ከቀጥታ
ትራፊክ ጋር ፈጽሞ አይዛመድም። በ`status`/`headers` ላይ ብቻ የሚዛመዱ
ደንቦች (እንደ Opencode ወይም Minimax) ይህን መርጦ መግባት
አያስፈልጋቸውም። በተናጠል፣ ደንቡ `scope: "connection"` ካወጀ እና
የታሰበው እውነተኛ የግንኙነት-አቀፍ ማቀዝቀዣ ከተመሳሳይ ጥያቄ
የጥምር መዝለል ጋር ከሆነ (የመረጃ መለያ ብቻ ካልሆነ)፣ የአቅራቢውን
id በዚያው ፋይል ውስጥ ወደ `HONORS_RULE_LOCK_SCOPE_PROVIDERS` ያክሉ —
ይህ በ`markAccountUnavailable()` (`src/sse/services/auth.ts`) እና
`applyComboTargetExhaustion()`
(`open-sse/services/combo/targetExhaustion.ts`) ውስጥ እንደ
`isAgentrouterConnectionQuotaScope()` ያለ ፍጆታን የሚገድበው ነው፤
ያለዚህ `scope` አሁንም በ`fallbackResult.ruleScope` በኩል ይተላለፋል፣
ነገር ግን ምንም ነገር በእሱ መሠረት አይሰራም።
3. `tests/unit/upstream-status-restatement.test.ts` እና
`tests/unit/agentrouter-error-rules.test.ts`ን የሚያንጸባርቁ የክፍል
ሙከራዎችን ያክሉ (የnot-permanent / not-creditsExhausted መከላከያዎችን
ጨምሮ፣ እና — አቅራቢው የፍቃድ ዝርዝሩን ከፈለገ — `resolveRuleMatchBody()`
ሙሉውን ጽሑፍ ለዚያ አቅራቢ ብቻ እንደሚመልስ የሚያረጋግጥ ሙከራ)።
በ`chatCore.ts`፣ `classifyError` ወይም combo ላይ ምንም ለውጥ አያስፈልግም።
#### በወጪ ትራፊክ ባልዲ የተከፋፈለ መቆለፊያ (#10880)
በ`EGRESS_BUCKETED_LOCK_PROVIDERS` (የopencode ቤተሰብ) ውስጥ ያሉ
አቅራቢዎች በIP የተከፋፈለ የላይኛው ስርዓት ተደርገው ይወሰዳሉ
(የopencode ነጻ ደረጃ በIP የተከፋፈለ እንጂ በመለያ የተከፋፈለ
አይደለም — #9611ን ይመልከቱ)፦ `quota_exhausted` **ወይም**
`rate_limit_exceeded` ተብሎ የተመደበ ሁኔታ-429፣ ማዞሪያው ሊሞክራቸው
ከመቻሉ በፊት፣ የመጨረሻ የታወቀ የወጪ ትራፊክ IP አድራሻቸው
ከከሸፈው ግንኙነት ጋር የሚዛመድ እያንዳንዱን በፍቃድ ዝርዝር
የተካተተ የቤተሰቡ ግንኙነት ያቀዘቅዛል
— ይህም N-1 መክሸፋቸው አይቀሬ የሆኑ የላይኛው ስርዓት ጥሪዎችን
ይከላከላል (ከ#10460/#10525 ጋር ተመሳሳይ ቅርጽ)።
`rate_limit_exceeded` ሆን ተብሎ ተካቷል፦ በ`markAccountUnavailable`
መንገድ ላይ ለopencode የተለዩት ደንቦች ፈጽሞ አይዛመዱም (ምንም
headers/body ወደ `checkFallbackError` አይተላለፍም፣ opencode በ
`FULL_TEXT_RULE_PROVIDERS` ውስጥ የለም)፣ ስለዚህ bodyው የደንበኝነት
ምዝገባ ኮታ ጽሑፍን ("monthly usage limit reached") የያዘ 429፣
የ`status_429` ደንብ ከመድረሱ በፊት በኮታ-ጽሑፍ ምትክ
(`buildSubscriptionQuotaFallback`, `accountFallback.ts`; 1h ማቀዝቀዣ)
እንደ `quota_exhausted` ይመደባል — ከኮታ-ጽሑፍ ነጻ የሆነ 429
(ተራ የፍጥነት ገደብ) ግን በ`status_429` ደንብ አማካኝነት እንደ
`rate_limit_exceeded` ይመደባል፣ እና አሁንም የIP ቤተሰቡን ያቀዘቅዛል።
በፍቃድ ዝርዝሩ ለተካተተ አቅራቢ፣ በIP የተከፋፈለ የፍጥነት ገደብ
ከተሟጠጠ ኮታ ጋር ተመሳሳይ ምልክት ነው። ግልጽ ገደቦች፦
- **በተቻለ መጠን**: መቆለፊያው የግንኙነቱን የመጨረሻ የታወቀ `egress_ip`
ከ`proxy_logs` ይፈታል (የ24h መስኮት፣ የተመሳሰለ፣ ያለ መሸጎጫ)። ቀዝቃዛ መሸጎጫ (የወጪ
IP ፈጽሞ ካልተፈተሸ) ወይም ረድፍ ከሌለ → ያልተሳካው ግንኙነት አሁንም በቅርንጫፉ
ይቀዘቅዛል (እንደ አሁኑ ይመዘገባል)፣ የሚቆለፍ ተመሳሳይ ግንኙነት ብቻ አይኖርም።
- **ፈጽሞ ቋሚ አይደለም**: የማቀዝቀዣ ጊዜው የሚታደስ የኮታ መስኮት ነው
(`testStatus: "unavailable"`)፤ ቋሚ ሁኔታ ከIP-ደረጃ ምልክት ፈጽሞ አይወሰድም።
`disableCooling` ያላቸው ግንኙነቶች ቅርንጫፉን ሙሉ በሙሉ ያልፋሉ።
- **ለተፈቀደለት ቤተሰብ የመቆለፊያ ጥራጥሬነት ይለወጣል**: ይህ የወሰን
ለውጥ እንጂ የተመሳሳይ ግንኙነት ማመቻቸት ብቻ አይደለም። opencode የ
`passthroughModels` አቅራቢ ነው፣ ስለዚህ ከዚህ ቅርንጫፍ በፊት 429 በእያንዳንዱ-MODEL
ደረጃ መቆለፍን ያስከትል ነበር፤ አሁን ግን የግንኙነት ማቀዝቀዣን ያስከትላል —
ምንም ተመሳሳይ ግንኙነት ሳይኖረው አንድ ግንኙነት ብቻ ለሚያስኬድ ኦፕሬተርም ጭምር።
የopencode ደንብ ሰንጠረዥ ትክክለኛ እንደሆነ አስቀድሞ የሚገልጸው ጥራጥሬነት ይህ ነው
(`scope: "connection"`፣ `providerErrorRules.ts`)፤ opencode በ
`HONORS_RULE_LOCK_SCOPE_PROVIDERS` ውስጥ ስለሌለ እስካሁን ፈጽሞ አልተከበረም።
ቅርንጫፉ በግንኙነት-ወሰን ያለውን የagentrouter ቅርንጫፍ በመኮረጅ ያልተሳካውን
የግንኙነት ማቀዝቀዣ + `backoffLevel` ራሱ ይጽፋል፣ ከዚያም ይመለሳል —
በእያንዳንዱ-ሞዴል ያለው እገዳና ከታች ያለው አጠቃላይ መንገድ ፈጽሞ አይደረስባቸውም።
- **Combo ተካትቷል**: እንደ agentrouter ቅርንጫፍ፣ ወሰኑ አንድ combo ጠሪ
በ429 ላይ የሚተገብረውን የ`persistUnavailableState`/`isCombo` ደረጃ ቅናሽ ሆን ብሎ
ችላ ይላል። በእያንዳንዱ-ሞዴል የሚደረግ መቆለፍ የዚህ ወሰን ደካማ ቅርጽ አይደለም፤
የተሳሳተ አሃድ ነው፤ ስለተሟጠጠው IP ምንም አይናገርም፣ ስለዚህ የcombo
ማዞሪያው በእያንዳንዱ ተመሳሳይ ግንኙነት አንድ መሳካቱ የማይቀር ጥሪን ማባከኑን ይቀጥላል።
- **የተመሳሳይ ግንኙነት ደህንነት**: አስቀድሞ ቋሚ ሁኔታ ላይ ያለ ተመሳሳይ ግንኙነት
(banned/credits_exhausted) ወይም አስቀድሞ ረዘም ያለ የማቀዝቀዣ ጊዜ ያለው
ፈጽሞ አይተካም።
- **የተወሰነ የፍቃድ ዝርዝር**: `EGRESS_BUCKETED_LOCK_PROVIDERS`ን ማስፋት
ግልጽ የባለቤት ውሳኔ ነው፤ አጠቃላይ ሽቦ ማገናኘት የለም (pattern #10334/#10419)።
የተመሳሳይ ግንኙነት መጠይቁ ያንኑ የፍቃድ ዝርዝር እንደ SQL
ቃል-በቃል ከመድገም ይልቅ ያስራል፣ ስለዚህ ማስፋቱ የአንድ-መስመር ለውጥ ሆኖ ይቆያል።
- **የወጪ IP ማዞር፣ በሁለቱም አቅጣጫዎች**: የፍለጋ መስኮቱ (24h) ከወጪ-IP
መሸጎጫ TTL (5 min) እጅግ የሰፋ ነው፣ ስለዚህ "የመጨረሻ የታወቀ IP" ታሪክ እንጂ
የአሁን ሁኔታ አይደለም። የአንድ ግንኙነት proxy በመስኮቱ ውስጥ ከተዘዋወረ
መቆለፊያው በእውነት የሚጋራ IPን **ሊያመልጠው** ይችላል (የተመዘገበው IP አዲሱ፣
ያልተሟጠጠው ነው) — በተመሳሳይም ሁኔታ ከተሟጠጠው IP ርቆ የተዘዋወረን
**ተመሳሳይ ግንኙነት ሊያቀዘቅዝ** ይችላል። ሁለተኛው ሁኔታ ያንን ተመሳሳይ ግንኙነት
አንድ የማቀዝቀዣ መስኮት ያስከፍለዋል፤ ሁለቱም በታሪክ ላይ የተመሠረተ ፍለጋ
የሚያስከትላቸው ተቀባይነት ያላቸው የበተቻለ መጠን ገደቦች ናቸው።
- **ወጪ**: ሁለት የተገደቡ የ`proxy_logs` ቅኝቶች (በ
`idx_pl_timestamp` በኩል በመስኮቱ የተጣሩ)፣ በ429 ድግግሞሽ ጊዜ ብቻ። አዲስ
index የለም (migration 134 YAGNI)። መካከለኛ መጠን ባለው የእውነተኛ-ትራፊክ DB
ቅጂ ላይ ተለክቷል፤ ከፍተኛ-የውሂብ-ፍሰት instance በተመሳሳይ መስኮት ውስጥ
በተመጣጣኝ ሁኔታ ተጨማሪ ረድፎችን ይይዛል።
---
## ሌሎች የጽናት ባህሪያት
- **19 የማዘዋወሪያ ስልቶች** (ቅድሚያ፣ ክብደት ያለው፣ ተራ-በተራ፣ የዐውድ ማስተላለፊያ፣ መጀመሪያ-ሙላ፣ p2c፣ የዘፈቀደ፣ በትንሹ-ጥቅም-ላይ-የዋለ፣ ወጪ-የተመቻቸ፣ ዳግም-ማስጀመርን-የሚያውቅ፣ የዳግም-ማስጀመሪያ-ጊዜ-መስኮት፣ ትርፍ-አቅም፣ ጥብቅ-የዘፈቀደ፣ ራስ-ሰር፣ lkgp፣ ዐውድ-የተመቻቸ፣ መሸጎጫ-የተመቻቸ፣ ውህደት፣ ቧንቧ-መስመር) — [AUTO-COMBO.md](../routing/AUTO-COMBO.md)ን ይመልከቱ።
- **ዳግም ማስጀመርን የሚያውቅ ማዘዋወር** (v3.8.0) — ግንኙነቶችን በኮታ ዳግም ማስጀመሪያ ጊዜ መሠረት ቅድሚያ ይሰጣል።
- **የበስተጀርባ ሁነታ ማውረድ** — Responses API `background: true` ከማስጠንቀቂያ ጋር ወደ የተመሳሰለ ሁነታ ዝቅ ይደረጋል።
- **ተለዋዋጭ የመሣሪያ ገደብ ማወቂያ** — የመሣሪያ ብዛት ገደቦች ሲደረሱ አቅራቢዎችን ወደ ኋላ ያፈገፍጋል።
- **የድንገተኛ ጊዜ አማራጭ** — በ`OMNIROUTE_EMERGENCY_FALLBACK` ይቆጣጠራል፤ ኦፕሬተሮች ዳግም ሳያስጀምሩ ከባህሪ ጥቆማዎች ገጽ ሊተኩት ይችላሉ።
---
## ማረም
- ክብደት ያለው combo `503 all_targets_cooling_down` ምላሽ ከሰጠ (`Retry-After` ተቀናብሯል፣ `diagnostics.excluded` ደግሞ እያንዳንዱን ዒላማ ከ`model_lockout` / `circuit_open` / `provider_cooldown` / `unavailable` ጋር ይዘረዝራል) → pool-ው ተዋቅሯል እና ተገናኝቷል፤ እያንዳንዱ ዒላማ በresilience timer ምክንያት ብቻ ተገልሏል። የ`[COMBO] Weighted selection: every target excluded before dispatch — …` ማስጠንቀቂያ ምክንያቶቹን እና የቀሩትን ሰከንዶች ይጠቅሳል። ከተመሳሳዩ combo የሚመጣ `404 no_executable_targets` ማለት ምንም resilience timer አልተሳተፈም ማለት ነው (የሚሰራ ምንም ነገር የለም፣ ወይም ሁሉም መለያዎች የavailability probe-ውን አላለፉም)። ይህም በ`targetResolution.ts` ውስጥ ከተሰበሰቡት ማግለሎች በ`open-sse/services/combo/pinRecovery.ts` ውስጥ ተገንብቷል።
- የአንድ provider ሁሉም keys ከታለፉ → የcircuit breaker ሁኔታን እና የእያንዳንዱ connection `rateLimitedUntil`/`testStatus`ን ሁለቱንም ያረጋግጡ።
- ከreset window በኋላ provider በቋሚነት ከተገለለ → ኮዱ `getStatus()`/`canExecute()`ን ከመጠቀም ይልቅ ጥሬ `state`ን እያነበበ ነው።
- አንድ key ከወደቀ፣ ሌሎቹ መስራት አለባቸው → ከcircuit breaker ይልቅ connection cooldownን ይምረጡ።
- አንድ model ብቻ ከወደቀ → ከconnection cooldown ይልቅ model lockoutን ይምረጡ።
- State ራሱን መልሶ ማገገም ሲገባው ካላገገመ → የወደፊት timestamp መኖሩን እና ጊዜው ያለፈበትን state የሚያድስ read path መኖሩን ያረጋግጡ። ቋሚ statuses በእጅ ለውጦችን ይፈልጋሉ።
---
## TLS የጣት አሻራ መለየት እና ስውርነት
ለአቅራቢ የተወሰነ ስውርነት (JA3/JA4፣ CCH፣ ማደበዝ) በተናጠል ተመዝግቧል — `docs/security/STEALTH_GUIDE.md`ን ይመልከቱ (git፤ ወደ `/docs` አልተቀናበረም)።
---
## የጽናት ሙከራ (ደረጃ 8 · ክፍል C)
ከጽናት አመክንዮ የአሃድ ሙከራዎች በተጨማሪ፣ ሦስት ሙከራዎች በእውነተኛ
የጭንቀት/ውድቀት ሁኔታዎች የአሂድ ጊዜውን ይፈትሻሉ (ሁሉም ውህደት/የምሽት ናቸው — PRsን የሚያግድ የለም)፦
| ሙከራ | ምን | ማስኬጃ |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| ትርምስ | አስመሳይ የላይኛው ዥረት ኖድ እውነተኛ መዘግየት/ዳግም ማስጀመር/የጊዜ ማብቂያ/503ን ያስገባል፤ የወረዳ ቆራጩ መከፈቱን/መመለሱን እና `checkFallbackError` 503ን እንደ ሊመለስ የሚችል አማራጭ መመደቡን ያረጋግጣል። | `RUN_CHAOS_INT=1 npm run test:chaos` |
| የሂፕ-እድገት | በ`--expose-gc` ስር ለእያንዳንዱ `createSSEStream` ~500 ዥረቶች፤ ሂፑ ከጣሪያው በላይ ካደገ ይወድቃል (የOOM መከላከያ #3069)። | `npm run test:heap` |
| k6 የረጅም ጊዜ ጭነት | በ`/api/monitoring/health` ላይ ዘላቂ ጭነት፤ የp95/ስህተት ገደቦች። | `k6 run tests/load/k6-soak.js` (በምሽት) |
በ`.github/workflows/nightly-resilience.yml` (cron + dispatch) ይቀናበራል። በነባሪው
`test:integration` ውስጥ፣ የትርምስ እና የሂፕ ሙከራዎች ራሳቸውን ይዘላሉ (`RUN_CHAOS_INT`/`--expose-gc` ከሌለ)።
---
## ተጨማሪ ይመልከቱ
- [የሥነ ሕንፃ መመሪያ](./ARCHITECTURE.md) — የስርዓት ሥነ ሕንፃ እና ውስጣዊ አሠራሮች
- [የተጠቃሚ መመሪያ](../guides/USER_GUIDE.md) — አቅራቢዎች፣ ጥምረቶች፣ የCLI ውህደት
- [ራስ-ሰር ጥምረት ሞተር](../routing/AUTO-COMBO.md) — ባለ16-ምክንያት ውጤት አሰጣጥ፣ የሁነታ ጥቅሎች

139
docs/i18n/am/docs/architecture/ROUTER_BACKENDS.md Normal file
View File

@@ -0,0 +1,139 @@
# Router Backends & Embedded Services — architecture contract (ADR) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ROUTER_BACKENDS.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ROUTER_BACKENDS.md) · 🇦🇿 [az](../../../az/docs/architecture/ROUTER_BACKENDS.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ROUTER_BACKENDS.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ROUTER_BACKENDS.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ROUTER_BACKENDS.md) · 🇩🇰 [da](../../../da/docs/architecture/ROUTER_BACKENDS.md) · 🇩🇪 [de](../../../de/docs/architecture/ROUTER_BACKENDS.md) · 🇬🇷 [el](../../../el/docs/architecture/ROUTER_BACKENDS.md) · 🇪🇸 [es](../../../es/docs/architecture/ROUTER_BACKENDS.md) · 🇪🇪 [et](../../../et/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ROUTER_BACKENDS.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ROUTER_BACKENDS.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ROUTER_BACKENDS.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇱 [he](../../../he/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ROUTER_BACKENDS.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ROUTER_BACKENDS.md) · 🇭🇺 [hu](../../../hu/docs/architecture/ROUTER_BACKENDS.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇩 [id](../../../id/docs/architecture/ROUTER_BACKENDS.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇹 [it](../../../it/docs/architecture/ROUTER_BACKENDS.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ROUTER_BACKENDS.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ROUTER_BACKENDS.md) · 🇰🇭 [km](../../../km/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ROUTER_BACKENDS.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ROUTER_BACKENDS.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ROUTER_BACKENDS.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ROUTER_BACKENDS.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ROUTER_BACKENDS.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ROUTER_BACKENDS.md) · 🇲🇲 [my](../../../my/docs/architecture/ROUTER_BACKENDS.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ROUTER_BACKENDS.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ROUTER_BACKENDS.md) · 🇳🇴 [no](../../../no/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [or](../../../or/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ROUTER_BACKENDS.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ROUTER_BACKENDS.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ROUTER_BACKENDS.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ROUTER_BACKENDS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ROUTER_BACKENDS.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ROUTER_BACKENDS.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ROUTER_BACKENDS.md) · 🇱🇰 [si](../../../si/docs/architecture/ROUTER_BACKENDS.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ROUTER_BACKENDS.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ROUTER_BACKENDS.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ROUTER_BACKENDS.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ROUTER_BACKENDS.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ROUTER_BACKENDS.md) · 🇮🇳 [te](../../../te/docs/architecture/ROUTER_BACKENDS.md) · 🇹🇭 [th](../../../th/docs/architecture/ROUTER_BACKENDS.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ROUTER_BACKENDS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ROUTER_BACKENDS.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ROUTER_BACKENDS.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ROUTER_BACKENDS.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ROUTER_BACKENDS.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ROUTER_BACKENDS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ROUTER_BACKENDS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ROUTER_BACKENDS.md)
---
> **ሁኔታ:** ተቀባይነት ያገኘ · **ዐውድ:** [#5670](https://github.com/diegosouzapw/OmniRoute/issues/5670),
> [#5603](https://github.com/diegosouzapw/OmniRoute/issues/5603) · **ውል:** `domain/routing/routerBackends.ts`
> (በዓይነት የተወሰነ መዝገብ — ኮዱ ከ[#5868](https://github.com/diegosouzapw/OmniRoute/pull/5868) ጋር ይገባል)
ይህ ADR `ts` (ቤተኛ)፣ `bifrost`፣ `cliproxy`፣ `9router` እና
ከVibeProxy ጋር ተኳሃኝ የሆኑ ሞተሮች እርስ በርስ እንዴት እንደሚዛመዱ በግልጽ ይወስናል፤ በዚህም አስተዋጽዖ አድራጊዎች በአርክቴክቸር ደረጃ የተለዩ ሁለት ነገሮችን ማደባለቃቸውን ያቆማሉ። በrouter-backend-registry ሥራ የተዋወቀውን በዓይነት የተወሰነ
መዝገብ ለዚያ ሞዴል ብቸኛው የእውነት ምንጭ አድርጎ ይመዘግባል።
## ዋናው ልዩነት — ሁለት እርስ በርስ ነጻ የሆኑ ዘንጎች
የአንድ ሞተር ሚና በመዝገቡ `RouterBackendDefinition` ውስጥ አብረው በተቀመጡ **ሁለት ነጻ ዘንጎች** ይገለጻል፦
1. **የሕይወት ዑደት** (`RouterBackendLifecycle`) — _ሞተሩ እንዴት እንደሚሠራ_፦
- `in-process` — በOmniRoute Node ሂደት ውስጥ ይሠራል (ቤተኛው TS የማቀናበሪያ መስመር)።
- `supervised` — OmniRoute በ`ServiceSupervisor` በኩል የሚጭነው/የሚጀምረው/የሚያቆመው/ጤንነቱን የሚፈትሸው፣ ከዚያም እንደ አቅራቢ ግንኙነት የሚጠቀምበት አካባቢያዊ ልጅ ሂደት።
- `external` — OmniRoute ጥያቄዎችን የሚልክለት ነገር ግን **የማያስተዳድረው**
የHTTP መዳረሻ (በenv መሠረታዊ URL የሚዋቀር)።
- `disabled` — የተመዘገበ ነገር ግን ሊመረጥ የማይችል።
2. **የምርጫ ዘንግ** (የrelay ማዞሪያ backend) — _relay ጥያቄዎችን ወደ እሱ ይልክ እንደሆነ_፦
`RelayRoutingBackend = "ts" | "bifrost" | "auto"` በ
`src/app/api/v1/relay/chat/completions/routingBackend.ts` ውስጥ።
መወገድ ያለበት ስህተት፦ "የተካተተ አገልግሎት" እና "የማዞሪያ backend" እንደ አንድ
ዝርዝር መቁጠር። አንድ አይደሉም። `supervised` ሞተር (9router/cliproxy) **በቤተኛው የማቀናበሪያ መስመር ጥቅም ላይ የሚውል የአቅራቢ
ግንኙነት** እንጂ አማራጭ የrelay መላኪያ
backend አይደለም። `bifrost` ደግሞ ተቃራኒው ነው — (በታሪካዊ ሁኔታ)
`external`-ብቻ የነበረ የrelay መላኪያ backend ነው።
## መዝገቡ — ብቸኛው የእውነት ምንጭ
የ`domain/routing/routerBackends.ts` ውል (ኮዱ ከ
[#5868](https://github.com/diegosouzapw/OmniRoute/pull/5868) ጋር ይገባል) እያንዳንዱን ሞተር ከሕይወት ዑደቱ፣ ችሎታዎቹ፣ የአገልግሎት ማንነቱ፣ ነባሪ ወደቡ፣ የጤንነት ውቅሩ እና
የቴሌሜትሪ ድጋፉ ጋር አንድ ጊዜ ያውጃል። ተጠቃሚዎች ለእያንዳንዱ sidecar ልዩ ሁኔታ ከመጻፍ ይልቅ፣ ሞተሮችን በ`getRouterBackend(id)`፣
`listRouterBackends()` እና `listRouterBackendsByCapability(cap)` በኩል ይፈልጋሉ።
| Backend | የሕይወት ዑደት | አገልግሎት (ዘንግ A) | Relay backend (ዘንግ B) | ጤንነት | ነባሪ ወደብ |
| ----------- | ------------ | -------------- | --------------------- | ------------- | ------- |
| `ts` | `in-process` | — | `ts` (ቤተኛ) | — | — |
| `bifrost` | `external`¹ | —¹ | `bifrost` / `auto` | `/health` | — |
| `cliproxy` | `supervised` | `cliproxy` | — (አቅራቢ) | `/v1/models` | 8317 |
| `9router` | `supervised` | `9router` | — (አቅራቢ) | `/api/health` | 20130 |
| `vibeproxy` | `external` | — | — (የአቅራቢ አስማሚ) | `/v1/models` | — |
¹ Bifrost ወደ `supervised` የተካተተ አገልግሎት (ከ`/api/services/bifrost/` ሊጫን/ሊጀመር የሚችል) እንዲያድግ የሚደረገው ሥራ በ
[#5817](https://github.com/diegosouzapw/OmniRoute/pull/5817) ይከታተላል፤ እስኪዋሃድ ድረስ፣
Bifrost `external`-ብቻ ነው (በ`BIFROST_BASE_URL` በኩል ብቻ ተደራሽ ነው)።
`capabilities` (`chat`፣ `responses`፣ `streaming`፣ `tools`፣ `vision`፣
`oauth-backed`፣ `dashboard-embed`፣ `model-sync`፣ `native-hot-path`) ጠሪዎች ለእያንዳንዱ id የተለየ ቅርንጫፍ በቋሚነት ከመጻፍ ይልቅ፣ አንድ ሞተር በእርግጥ ማድረግ በሚችለው መሠረት እንዲያጣሩ ያስችላቸዋል።
## ዘንግ A — የተካተቱ አገልግሎቶች (ቁጥጥር የሚደረግበት የፕሮሰስ ወገን)
- **ቁጥጥር የሚደረግባቸው ፕሮሰሶች መዝገብ:** `src/lib/services/bootstrap.ts` `SERVICES[]`
(በአሁኑ ጊዜ፦ `9router`፣ `cliproxy`)።
- **የሕይወት ዑደት ባለቤት:** `src/lib/services/ServiceSupervisor.ts` — `start()` ልጅ
ፕሮሰሱን ይፈጥራል፣ በ`waitForHealthy()` ላይ ያግዳል፣ stdout/stderrን ወደ ring buffer
ያስገባል፤ `stop()` SIGTERM→SIGKILL፤ ሁሉም በlock ሥር በተከታታይ ይከናወናሉ።
- **የሁኔታ union** (`src/lib/services/types.ts`)፦
`not_installed | stopped | starting | running | stopping | error`፣ እንዲሁም ከእነዚህ
ነጻ የሆነ `HealthState = healthy | unhealthy | unknown`።
- **ለምን የተለየ ፕሮሰስ (in-proc SDK ሳይሆን)?** የፕሮሰስ ማግለል ነው ለእያንዳንዱ
sidecar install/start/stop/health/logsን በተናጠል ለመቆጣጠር የሚያስችለው፣ እንዲሁም
የloopback spawn-guard ተግባራዊ እንዲሆን የሚያደርገው። የin-proc adapter ሞዴል ማድረግ
የወደፊት ሥራ ነው — ይህ የሚገለጸው በ`native-hot-path` capability flag ነው።
### የሕይወት ዑደት route ውል (`/api/services/<tool>/…`)
የሁኔታ ኮዶች **ሆን ተብሎ ለstate/verb/path የተለዩ ናቸው** — ይህ ውሉ ነው፣
ወጥነት ማጣት አይደለም፦
| ጥሪ | ሁኔታ | የሁኔታ ኮድ |
| ---------------------------- | ------------------------------ | ------------------------------------ |
| `POST .../start` | አገልግሎቱ `not_installed` ነው | **409** (ቅድመ ሁኔታ) |
| `POST .../stop` | አስቀድሞ ቆሟል | **200** (ተደጋጋሚ ጥሪ ምንም አያደርግም) |
| `GET .../status` | ችግር የለም | **200** (`live ?? row ?? "unknown"`) |
| `POST .../start` | የspawn አለመሳካት | **503** (ጊዜያዊ) |
| `GET .../status`, `.../stop` | ያልተያዘ ስህተት | **500** |
| `GET /api/services/<x>/logs` | ያልታወቀ tool `<x>` | **404** `Service '<x>' not found` |
| `GET .../status?reveal=key` | `X-Reveal-Confirm: yes` የለም | **403** (ለ9router ብቻ) |
| **ማንኛውም** `/api/services/*` | ጠሪው loopback/private-LAN አይደለም | **403 LOCAL_ONLY** |
ሁሉም የስህተት bodyዎች በ`createErrorResponse()` →
`{ error: { message, type }, requestId }` ቅርጽ ይዘጋጃሉ፤ እዚህ `type` ከሁኔታ ኮዱ
የሚመነጭ ሲሆን (`500→server_error`፣ `404→not_found`፣ `409→conflict`፣ ካልሆነ
`invalid_request`) በማሽን ሊተገበርበት የሚችል መለያ ነው። መልዕክቶች አስቀድመው
ይጸዳሉ (`sanitizeErrorMessage()`፣ ጥብቅ ደንብ #12)።
**የloopback guard** በብዛት `403` የሚያስከትለው ምክንያት ነው፦ `/api/services/`
በ`LOCAL_ONLY_API_PREFIXES` (`src/server/authz/routeGuard.ts`) ውስጥ ይገኛል፣ እና
`src/server/authz/policies/management.ts` ማንኛውንም loopback / private-LAN ያልሆነ
ጠሪ **ከauth በፊት** ውድቅ ያደርጋል፤ ምክንያቱም እነዚህ routes ልጅ ፕሮሰሶችን
ይፈጥራሉ (ጥብቅ ደንቦች 15 እና 17)። በpublic tunnel በኩል እነሱን መድረስ
ሆን ተብሎ `403` እንዲሆን ተደርጓል።
## ዘንግ B — የrelay routing backend (የdispatch ወገን)
dispatch backendን የሚመርጠው የrelay proxy path `/api/v1/relay/chat/completions` ብቻ ነው፤
ዋናው `/api/v1/chat/completions` surface ፈጽሞ `routingBackend.ts`ን አያማክርም።
- **ምርጫ** (`resolveRelayRoutingBackend`)፦ አንድ አጠቃላይ env toggle —
`OMNIROUTE_RELAY_BACKEND` / `RELAY_ROUTING_BACKEND` ∈ {`ts`, `bifrost`, `auto`}።
ካልተዋቀረ፣ Bifrost configured+enabled ከሆነ `auto`፣ ካልሆነ `ts` ይሆናል።
- **ባህሪ፦**
- `bifrost` (በግድ)፦ የBifrost አለመሳካት → ቀጥተኛ `502`፣ fallback የለም።
- `auto`፦ Bifrostን ይሞክራል፤ ሲከሽፍ/cooldown ላይ ሲሆን ያለማሳወቅ ወደ native ይሻገራል።
- `ts` / ከfallback በኋላ፦ native `open-sse` translator/executor pipeline።
- **Cooldown፦** በ`bifrostCooldown.ts` ውስጥ ለእያንዳንዱ `baseUrl` የአለመሳካት cooldown።
በአሁኑ ጊዜ ምርጫው በrelay ደረጃ **ሙሉ በሙሉ ወይም ምንም** ነው — በ`release/v3.8.43`
ላይ ለእያንዳንዱ provider ወይም request የengine ቅያሬ የለም። የእያንዳንዱ request gate
በsidecar-manifest ሥራ እየታከለ ነው
([#5869](https://github.com/diegosouzapw/OmniRoute/pull/5869) manifest +
[#5870](https://github.com/diegosouzapw/OmniRoute/pull/5870) `shouldTryBifrostForRequest`)፣
ይህም `auto` በmanifest ብቁ የሆኑ providersን ብቻ በBifrost በኩል route እንዲያደርግ ያስችለዋል።
## የዳሽቦርድ ውህደት
የአገልግሎቶች ዳሽቦርድ በየ5 ሰከንዱ `GET /api/services/<tool>/status`ን በ
`src/app/(dashboard)/dashboard/providers/services/hooks/useServiceStatus.ts`
በኩል ይጠይቃል፤ `{ tool, state, pid, port, health, installedVersion, latestVersion,
updateAvailable, autoStart, … }`ን ይመልሳል። የጋራ የተገኝነት-አውድ አቅራቢ የለም —
እያንዳንዱ ኮምፖነንት ለእያንዳንዱ መሣሪያ hookን ይጠራል። `!res.ok` ሲሆን hook በአሁኑ ጊዜ
ተጨማሪ መረጃ የሌለውን `HTTP <status>` ያሳያል፤ የ`error.type` መስክን ከሰው ሊረዳው ከሚችል ማብራሪያ ጋር ማዛመድ
ክትትል የሚደረግበት የUX ማሻሻያ እንጂ የውል ለውጥ አይደለም።
## ውጤቶች
- አዳዲስ ኤንጂኖች በ`ROUTER_BACKENDS` ውስጥ አንድ ጊዜ ይመዘገባሉ፤ ተጠቃሚዎች አዳዲስ በid የተለዩ የሁኔታ ቅርንጫፎችን
ሳያስፈልጋቸው በችሎታ መጠይቆች በኩል ያገኟቸዋል።
- "ይህ አገልግሎት ነው ወይስ የራውቲንግ ባክኤንድ?" የሚለው ጥያቄ የሚመለሰው በ`lifecycle` መስክ እንጂ
አንድ id በአጋጣሚ በታየበት ዝርዝር አይደለም።
- የBifrost ቁጥጥር (#5817) እና ወደ ኔቲቭ ፈጣን መንገድ የማዛወር ሥራ (#5670) እያንዳንዱን
sidecar ለየብቻ ከማስተናገድ ይልቅ በዚህ የጋራ ውል ላይ ይገነባሉ።

135
docs/i18n/am/docs/architecture/admission-lanes.md Normal file
View File

@@ -0,0 +1,135 @@
# Admission lanes (#9654) — two lane systems, what gates each, where each reports (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/admission-lanes.md) · 🇸🇦 [ar](../../../ar/docs/architecture/admission-lanes.md) · 🇦🇿 [az](../../../az/docs/architecture/admission-lanes.md) · 🇧🇬 [bg](../../../bg/docs/architecture/admission-lanes.md) · 🇧🇩 [bn](../../../bn/docs/architecture/admission-lanes.md) · 🇨🇿 [cs](../../../cs/docs/architecture/admission-lanes.md) · 🇩🇰 [da](../../../da/docs/architecture/admission-lanes.md) · 🇩🇪 [de](../../../de/docs/architecture/admission-lanes.md) · 🇬🇷 [el](../../../el/docs/architecture/admission-lanes.md) · 🇪🇸 [es](../../../es/docs/architecture/admission-lanes.md) · 🇪🇪 [et](../../../et/docs/architecture/admission-lanes.md) · 🇮🇷 [fa](../../../fa/docs/architecture/admission-lanes.md) · 🇫🇮 [fi](../../../fi/docs/architecture/admission-lanes.md) · 🇫🇷 [fr](../../../fr/docs/architecture/admission-lanes.md) · 🇮🇪 [ga](../../../ga/docs/architecture/admission-lanes.md) · 🇮🇳 [gu](../../../gu/docs/architecture/admission-lanes.md) · 🇳🇬 [ha](../../../ha/docs/architecture/admission-lanes.md) · 🇮🇱 [he](../../../he/docs/architecture/admission-lanes.md) · 🇮🇳 [hi](../../../hi/docs/architecture/admission-lanes.md) · 🇭🇷 [hr](../../../hr/docs/architecture/admission-lanes.md) · 🇭🇺 [hu](../../../hu/docs/architecture/admission-lanes.md) · 🇦🇲 [hy](../../../hy/docs/architecture/admission-lanes.md) · 🇮🇩 [id](../../../id/docs/architecture/admission-lanes.md) · 🇳🇬 [ig](../../../ig/docs/architecture/admission-lanes.md) · 🇮🇹 [it](../../../it/docs/architecture/admission-lanes.md) · 🇯🇵 [ja](../../../ja/docs/architecture/admission-lanes.md) · 🇬🇪 [ka](../../../ka/docs/architecture/admission-lanes.md) · 🇰🇭 [km](../../../km/docs/architecture/admission-lanes.md) · 🇮🇳 [kn](../../../kn/docs/architecture/admission-lanes.md) · 🇰🇷 [ko](../../../ko/docs/architecture/admission-lanes.md) · 🇱🇹 [lt](../../../lt/docs/architecture/admission-lanes.md) · 🇱🇻 [lv](../../../lv/docs/architecture/admission-lanes.md) · 🇮🇳 [ml](../../../ml/docs/architecture/admission-lanes.md) · 🇮🇳 [mr](../../../mr/docs/architecture/admission-lanes.md) · 🇲🇾 [ms](../../../ms/docs/architecture/admission-lanes.md) · 🇲🇹 [mt](../../../mt/docs/architecture/admission-lanes.md) · 🇲🇲 [my](../../../my/docs/architecture/admission-lanes.md) · 🇳🇵 [ne](../../../ne/docs/architecture/admission-lanes.md) · 🇳🇱 [nl](../../../nl/docs/architecture/admission-lanes.md) · 🇳🇴 [no](../../../no/docs/architecture/admission-lanes.md) · 🇮🇳 [or](../../../or/docs/architecture/admission-lanes.md) · 🇮🇳 [pa](../../../pa/docs/architecture/admission-lanes.md) · 🇵🇭 [phi](../../../phi/docs/architecture/admission-lanes.md) · 🇵🇱 [pl](../../../pl/docs/architecture/admission-lanes.md) · 🇵🇹 [pt](../../../pt/docs/architecture/admission-lanes.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/admission-lanes.md) · 🇷🇴 [ro](../../../ro/docs/architecture/admission-lanes.md) · 🇷🇺 [ru](../../../ru/docs/architecture/admission-lanes.md) · 🇱🇰 [si](../../../si/docs/architecture/admission-lanes.md) · 🇸🇰 [sk](../../../sk/docs/architecture/admission-lanes.md) · 🇸🇮 [sl](../../../sl/docs/architecture/admission-lanes.md) · 🇷🇸 [sr](../../../sr/docs/architecture/admission-lanes.md) · 🇸🇪 [sv](../../../sv/docs/architecture/admission-lanes.md) · 🇰🇪 [sw](../../../sw/docs/architecture/admission-lanes.md) · 🇮🇳 [ta](../../../ta/docs/architecture/admission-lanes.md) · 🇮🇳 [te](../../../te/docs/architecture/admission-lanes.md) · 🇹🇭 [th](../../../th/docs/architecture/admission-lanes.md) · 🇹🇷 [tr](../../../tr/docs/architecture/admission-lanes.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/admission-lanes.md) · 🇵🇰 [ur](../../../ur/docs/architecture/admission-lanes.md) · 🇺🇿 [uz](../../../uz/docs/architecture/admission-lanes.md) · 🇻🇳 [vi](../../../vi/docs/architecture/admission-lanes.md) · 🇳🇬 [yo](../../../yo/docs/architecture/admission-lanes.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/admission-lanes.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/admission-lanes.md)
---
OmniRoute የተለያዩ ወሰኖች ያሏቸው በሂደት ውስጥ ብቻ የሚሰሩ **ሁለት** የመስመር ሥርዓቶች አሉት። እነዚህ
እርስ በርሳቸው የሚደጋገፉ ናቸው፤ ኦፕሬተሮች የትኛውን እየተመለከቱ እንደሆነ ማወቅ አለባቸው።
## 1. በባይት ደረጃ በጠቅላላው ሂደት ላይ የሚተገበር የመቀበያ ቁጥጥር (`chatBodyAdmission.ts`)
- **ወሰን፦** ለ`POST /v1/chat/completions`፣
`/v1/messages`፣ `/v1/responses` እና ሌሎች የውይይት ቅርጽ ላላቸው መንገዶች የተከማቸ-የጥያቄ-ይዘት/heap መስመር።
በትላልቅ የኮድ አዘጋጅ ወኪሎች የጥያቄ ይዘቶች ምክንያት የሚፈጠርን የheap ማባዛት ይከላከላል (#4380)።
- **አንድ የሂደቱ ዓለም አቀፍ መቆጣጠሪያ እንጂ ለእያንዳንዱ ቁልፍ የተለዩ መስመሮች አይደሉም (#10110)።** እያንዳንዱ የAPI ቁልፍ
(hash የተደረገ) ወይም `anonymous` ክፍለ ጊዜ በ**ተመሳሳዩ** የጋራ በጀት መሠረት ይቀበላል —
hash የተደረገው የክፍለ ጊዜ መለያ ለፍትሐዊነት መርሐግብር ቁልፍ (በተጠባባቂዎች መካከል ተራ በተራ
ለማሰራጨት) **ብቻ** ጥቅም ላይ ይውላል፤ በፍጹም እንደ የአቅም ክፍፍል አያገለግልም። የዚህ ሰነድ ቀደምት ስሪት
ራሳቸውን የቻሉ አቅሞች ያሏቸውን ለእያንዳንዱ ቁልፍ የተለዩ መስመሮች የሚገልጽ ነበር፤ ያልተረጋገጡ የውሸት ማረጋገጫዎች
የሂደቱን አጠቃላይ ገደብ ማባዛት ስለሚያስችሉ #10110 ላይ ይህ ሞዴል ተወግዷል።
- **በር (#503-fanout)፦ በራስ-ሰር የሚወሰን የግብዓት BYTE በጀት እንጂ ቋሚ የጥያቄ
ብዛት አይደለም።** የቀድሞው `CHAT_MAX_HEAVY_IN_FLIGHT` የጥያቄ-ብዛት ገደብ (ከዚህ ማስተካከያ በፊት ነባሪው `1`
ነበር) የኮድ አዘጋጅ ወኪሎችን የስራ ስርጭት (በርካታ ንዑስ ወኪሎች/CLIs፣
በመደበኛነት > 256 KB የሆኑ የጥያቄ ይዘቶች) ውጤታማ የትይዩነት መጠን ~1 እንዲሆን በማድረግ ያጠብ ነበር፤ ይህም
ሙሉ በሙሉ መደበኛ በሆነ ጭነት ውስጥ 503 እንዲመለስ ያደርግ ነበር። አሁን ይህ ገደብ የሚተገበረው ኦፕሬተር
`OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT`ን በግልጽ ሁኔታ ሲያዘጋጅ ብቻ ነው። ሳይዘጋጅ ሲቀር፣ መቀበሉ በምትኩ
በ`OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` ይገደባል — ይህም ከሂደቱ ትክክለኛ የማህደረ ትውስታ ጣሪያ
(`src/shared/middleware/admissionBudget.ts`) በራስ-ሰር የሚወሰን በጀት ነው፦
ከV8 heap ገደብ እና ከማንኛውም የcgroup/container ገደብ ይበልጥ ጥብቅ የሆነውን 25%፣
ለ8x ጊዜያዊ የማባዛት ሁኔታ ተካፍሎ፣ በ8 MiB እና
2 GiB መካከል የተገደበ። ግልጽ የሆኑ ተተኪ ቅንብሮችም ተመሳሳይ ገደቦችን ይጠቀማሉ። ይህም ምንም የenv ማስተካከያ ሳያስፈልገው
ከ512 MB container እስከ 32 GB desktop ድረስ ራሱን ያስተካክላል። በተግባር ላይ ባለው በጀት ውስጥ
ሊገባ የማይችል የጥያቄ ይዘት ወዲያውኑ በ`413 body_exceeds_budget` ይከሽፋል፤
በተናጠል ሊስተናገዱ በሚችሉ የጥያቄ ይዘቶች መካከል ያለ ፉክክር ብቻ ገደብ ወዳለው
ፍትሐዊነት ወረፋ ይገባል። በቀጥታ የሚሰራ ባለብዙ-ምልክት የሀብት-ጫና መከታተያ (የV8 heap ጥምርታ፣
cgroup፣ PSI፣ OOM ክስተቶች — `open-sse/utils/resourcePressurePolicy.ts`) በ`high` ጫና
ጊዜ የተገደበውን የጥበቃ ጊዜ ያሳጥራል፣ በ`critical` ጫና ጊዜ ደግሞ አንድም ባይት
ከመግባቱ በፊት በ`503 resource_pressure` ወዲያውኑ ጭነትን ይቀንሳል።
- **ማስተካከያ፦**
- `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` — በራስ-ሰር ለሚወሰነው የባይት በጀት ተተኪ ቅንብር
- `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` — የቀድሞ የጥያቄ-ብዛት ገደብ፣ በምርጫ ብቻ የሚነቃ
- `OMNIROUTE_CHAT_ADMISSION_QUEUE_MS` — 503 ከመመለሱ በፊት ያለ የወረፋ ጥበቃ (ነባሪው 2000)
- `OMNIROUTE_CHAT_ADMISSION_MAX_QUEUED_BYTES` — በወረፋ ያሉ ባይቶችን የሚቆጣጠር የheap ቫልቭ (ነባሪው 4 MB)
- `OMNIROUTE_CHAT_VIRTUAL_TTL_MS` / `OMNIROUTE_CHAT_VIRTUAL_MAX_SESSIONS` — ከ#10110 ጀምሮ የተተዉ
ምንም ተግባር የሌላቸው ቅንብሮች (ለውቅር ተኳሃኝነት ሲባል ይቀበላሉ፣ ግን ችላ ይባላሉ)
- **ሪፖርቶች፦** `GET /api/monitoring/health` → `chatAdmission` (#11244) — የ#503-fanout ተጨማሪዎችን
`inflightBytes`፣ `maxInflightBytes`፣ `budgetSource`
(`v8_heap` | `cgroup` | `override`)፣ `pressureSeverity` እና `countCapEnabled`ን ጨምሮ
(በነባሪ ስርጭት ላይ false ነው — በትክክል ገደብ እየጣለ ያለው የባይት በጀቱ እንጂ የቀድሞው
የብዛት ገደብ አለመሆኑን ያረጋግጣል)።
## 2. ተስማሚ የአሂድ ጊዜ ምናባዊ መስመሮች (`open-sse/services/admission`)
- **ወሰን፦** ለአቅራቢ መላክ በተከራይ ቁልፍ የሚደረግ የመቀበያ ቁጥጥር — የወረፋ ወጪ፣ በመዘግየት የሚመራ
የገደብ ማስተካከያ፣ የመስመር ወረፋ እና የመስመር መለኪያዎች።
- **ማብሪያ፦** **በምርጫ የሚነቃ።** `OMNIROUTE_CHAT_VIRTUAL_LANES=true` ካልሆነ ተሰናክሏል። ያለዚህ፣
ተስማሚው ተቆጣጣሪ የጋራ ወረፋውን ባህሪ እንደነበረ ያቆያል (የ#9654 መስፈርት 1 የሚሟላው
ኦፕሬተር መስመሮቹን ካነቃ በኋላ ብቻ ነው)።
- **ማስተካከያ፦** `OMNIROUTE_CHAT_VIRTUAL_LANES` + ተስማሚ ውቅር (`maxQueueCount`,
`maxQueueCost`, `defaultMaxWaitMs`, …)።
- **ሪፖርቶች፦** `GET /api/monitoring/health` → `adaptiveAdmission` → `laneCount`,
`laneQueuedCount`, `laneQueuedCost`, `laneTenants` (ይዘታቸው የተደበቀ የመስመር መታወቂያዎች፤ ጥሬ
ቁልፎች ፈጽሞ አይታዩም)፣ እና `virtualLanes` — በቅጽበታዊ ማጠቃለያው ውስጥ «መስመሮቹ ነቅተዋል» የሚለውን በይፋ የሚያረጋግጥ ጠቋሚ።
## 3. የFan-out መመርመሪያዎች — ለcombo/fusion በዒላማ የመቀበያ ቁጥጥር (#9654 Wave 2)
Combo (ቅድሚያ / ተራ-በ-ተራ) እና fusion በአንድ ዋና
ጥያቄ ሥር N የሞዴል ዒላማዎችን ወደ ብዙ አቅጣጫዎች ያሰራጫሉ። ከ#9654 Wave 2 ጀምሮ፣ **እያንዳንዱ የfan-out ዒላማ ከመላኩ በፊት የመቀበያ ቁጥጥር ይደረግበታል**፤
ይህም በዒላማ መመርመሪያ (`PerTargetAdmissionHook`፣ በ`createPerTargetAdmissionHook` የሚገነባ)
ከ**ዋናው** የተከራይ መስመር አንጻር ይከናወናል።
- **ወሰን፦** በcombo፣ fusion እና chaos engine የሚላክ እያንዳንዱ የfan-out ዒላማ።
System 1 (በባይት ደረጃ) ተጽዕኖ አይደርስበትም — የfan-out ዒላማዎችን ፈጽሞ አይመረምርም።
- **ማብሪያ፦** **ከsystem 2 ጋር በምርጫ የሚነቃ።** `OMNIROUTE_CHAT_VIRTUAL_LANES`
ካልተዋቀረ ምንም አያደርግም — በዚያ ሁነታ ዋናው ጥያቄ አስቀድሞ የጋራ ወረፋውን ፈቃድ ይዟል፤
ስለዚህ መመርመር ወጪውን ሁለት ጊዜ በመቁጠር የcombo ዒላማዎችን ውድቅ ያደርጋል።
- **የአሠራር ትርጉም፦**
- **በጥብቅ የማያግድ — ይዝለል፣ ፈጽሞ ወረፋ አይጠብቅ።** `maxWaitMs 0`፦ የተሞላ መስመር
ዒላማውን ይዘላል፣ እናም በምትኩ የcombo ተለዋጭ አሠራር (ወይም የfusion ቀሪ
ፓነል) ያገለግላል። ይህ ሆን ተብሎ የተደረገ ነው፦ የfan-out ዒላማ ተደጋጋሚ
ሥራ ነው፣ እና ወረፋ ማስጠበቅ መስመሮቹ ሊያስቆሙት በተዘጋጁት ትክክለኛ የመጨናነቅ ቦታዎች ላይ
ተጨማሪ ጫና ይከምራል። ስለዚህ `defaultMaxWaitMs` የሚሠራው **በዋናው ጥያቄ ላይ ብቻ** ነው፤
የfan-out መመርመሪያዎች ፈጽሞ አይጠብቁም፣ እንዲጠብቁም የሚያደርግ **ምንም ማስተካከያ የለም**።
(የችግሩ ታሪክ የመጠበቂያ ማስተካከያዎች #9654 የሚከላከለውን የጅምላ-502/504 ዓይነት ችግር
እንደፈጠሩ ያሳያል — ኦፕሬተር የተዘለሉ የfan-out ዒላማዎች የምላሽ ጥራትን
እየጎዱ መሆኑን ሪፖርት ካደረገ ብቻ እንደገና ይገምገም)።
- **ሲፈቀድ መልቀቅ።** የተፈቀደለት መመርመሪያ ፈቃዱን ወዲያውኑ ይለቃል፦ ይህ
የአቅም በር እንጂ የሚቆይ ይዞታ አይደለም። የዋናው ጥያቄ ፈቃድ fan-outን ይሸፍናል፤ ተጨማሪ N
ፈቃዶችን መያዝ የጋራውን ንቁ ወጪ ከእውነቱ በላይ በማሳየት ሌሎች ተከራዮችን ውድቅ ያደርጋል።
የተቻለውን ያህል ብቻ የሚሠራ እንጂ ቦታ ማስያዣ አይደለም፦ በመመርመር እና በመላክ መካከል መስመሩ እንደገና ሊሞላ ይችላል፤ ስለዚህ
ከባድ ፉክክር ሲኖር በሩ፣ ዒላማው በሚላክበት ጊዜ እንደገና ወደተሞላ መስመር
እንዲገባ ሊፈቅድ ይችላል።
- **ዋጋው ከእውነተኛው የfan-out አካል ይሰላል።** መመርመሪያው ወጪን ከዒላማው
እውነተኛ አካል ይገምታል — ልክ እንደ ዋናው መንገድ ከ`stream` ጠቋሚው የሚወሰነውን የጥያቄ ክፍል ጨምሮ — ስለዚህ የfusion ፓነል አባላት (`stream: false`)
በእውነት በሚጠቀሙበት ያለ-ዥረት ክፍል ዋጋ ይሰጣቸዋል፣ የpriority/RR
ዒላማዎች ደግሞ ተጠቃሚው በጠየቀው መሠረት ዋጋ ይሰጣቸዋል።
- **ሪፖርቶች፦** ከመጀመሪያው ዒላማ በኋላ የሚከሰት የመመርመሪያ ዝለል የcomboን የእያንዳንዱ-ጥያቄ
`fallbackCount` ይጨምራል (ያለውን የተለዋጭ አሠራር ትርጉም በመከተል፤ በcombo
ምዝግቦች ውስጥ ይታያል)፤ ሁሉም የፓነል አባላት ከተዘለሉ fusion 503 ይመልሳል። በአሁኑ ጊዜ
በቅጽበታዊ ማጠቃለያው ላይ **ምንም የተጠቃለለ ቆጣሪ የለም** (ለምሳሌ `virtualFanoutSkipped`) —
ኦፕሬተር የመስመር በሩ የfan-out ዒላማዎችን ምን ያህል ጊዜ እንደሚዘል ማወቅ አልቻልኩም ብሎ
ሪፖርት ካደረገ፣ ይህ ቆጣሪውን ለመጨመር ምክንያት ይሆናል።
## በዳሽቦርድ ላይ የሚታየው የትኛው ነው
- `adaptiveAdmission.laneCount` / `laneTenants` → **አስማሚ ምናባዊ መስመሮች** (ስርዓት 2)።
- `adaptiveAdmission.virtualLanes === true` → የክፍል 3 fan-out probes
እንዲሁም ንቁ ናቸው። `virtualLanes` የሌለው ወይም `false` የሆነ payload ማለት
`OMNIROUTE_CHAT_VIRTUAL_LANES` አልተዋቀረም ማለት ነው — የባይት-ደረጃ መስመሮች (ስርዓት 1)
አሁንም ንቁ ናቸው፣ ነገር ግን እስኪነቃ ድረስ በ`adaptiveAdmission` ስር ያለ ምንም ነገር
(እንዲሁም ምንም fan-out gating) ተግባራዊ አይሆንም።
## ሁለቱም ለምን እንዳሉ
የባይት-ደረጃ መስመሮች ከፍተኛ ማህደረ ትውስታ የሚጠቀመውን የመተንተን/የማመቅ መንገድ ይገድባሉ፤ አስማሚ መስመሮች ደግሞ
ለእያንዳንዱ tenant የdispatch ወጪን ይገድባሉ። የ#9654 መስፈርት 1 ("የአንድ session ድንገተኛ ጭማሪ ሌላውን 503 እንዲያገኝ
አያደርግም") በስርዓት 1 ያለምንም ቅድመ ሁኔታ፣ እና opt-in ከነቃ በኋላ በስርዓት 2 ይተገበራል።
## 4. ባለአንድ-ሂደት ረጅም `/v1/responses` (healthy-headroom)
[#10437](https://github.com/diegosouzapw/OmniRoute/pull/10437)
heap ከ`OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO` በታች ሲሆን ሁለተኛ ከባድ መዋቅር ያለው ጥያቄ
እንዲፈቀድ `tryAcquireHealthyHeadroom`ን ጨምሯል። `admitChatRequest` የሚጠቀምበት BYTE
መንገድ (bodies ≥ `OMNIROUTE_CHAT_LARGE_BODY_BYTES`፣
ነባሪው 256 KiB፣ `POST /v1/responses`ን ጨምሮ) **ተመሳሳዩን** ማምለጫ ይጠቀማል።
ይህ ከሁለት በላይ በአንድ ጊዜ የሚሄዱ ረጅም
SSE `/v1/responses` ለማስተናገድ የሚደገፈው **ባለአንድ-ሂደት** አሰራር ነው፦ ዋናውን + healthy-headroomን heap
እና የሂደቱ-አቀፍ inflight-byte በጀት (`OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES`
/ #10110) እስከሚፈቅዱት መጠን ብቻ ከፍ ያድርጉ። በአስር የሚቆጠሩ ረጅም SSE clients (40–50) ያንን የማህደረ ትውስታ-በጀት
ጥያቄ የሚመለከት ነው፣ ጠንካራ የ“ከፍተኛው 2” የምርት ገደብ አይደለም። ጫና ያለበት heap አሁንም
#7849 እንዳይመለስ እንደገና ሊሞከር በሚችል `503` ጥያቄዎችን ይቀንሳል።
**heapsን ለማባዛት**፣ N ነጻ `DATA_DIR`s (#11024) ያሂዱ። በአንድ SQLite ፋይል ላይ
`replicas > 1`ን በፍጹም አያሂዱ (#10350)። ይህ ክፍል የDATA_DIR scale-out አሰራርን እንደገና የሚከፍት አይደለም።

99
docs/i18n/am/docs/architecture/cluster-decisions.md Normal file
View File

@@ -0,0 +1,99 @@
# Cluster Decisions — Optional Sidecar Profiles (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/cluster-decisions.md) · 🇸🇦 [ar](../../../ar/docs/architecture/cluster-decisions.md) · 🇦🇿 [az](../../../az/docs/architecture/cluster-decisions.md) · 🇧🇬 [bg](../../../bg/docs/architecture/cluster-decisions.md) · 🇧🇩 [bn](../../../bn/docs/architecture/cluster-decisions.md) · 🇨🇿 [cs](../../../cs/docs/architecture/cluster-decisions.md) · 🇩🇰 [da](../../../da/docs/architecture/cluster-decisions.md) · 🇩🇪 [de](../../../de/docs/architecture/cluster-decisions.md) · 🇬🇷 [el](../../../el/docs/architecture/cluster-decisions.md) · 🇪🇸 [es](../../../es/docs/architecture/cluster-decisions.md) · 🇪🇪 [et](../../../et/docs/architecture/cluster-decisions.md) · 🇮🇷 [fa](../../../fa/docs/architecture/cluster-decisions.md) · 🇫🇮 [fi](../../../fi/docs/architecture/cluster-decisions.md) · 🇫🇷 [fr](../../../fr/docs/architecture/cluster-decisions.md) · 🇮🇪 [ga](../../../ga/docs/architecture/cluster-decisions.md) · 🇮🇳 [gu](../../../gu/docs/architecture/cluster-decisions.md) · 🇳🇬 [ha](../../../ha/docs/architecture/cluster-decisions.md) · 🇮🇱 [he](../../../he/docs/architecture/cluster-decisions.md) · 🇮🇳 [hi](../../../hi/docs/architecture/cluster-decisions.md) · 🇭🇷 [hr](../../../hr/docs/architecture/cluster-decisions.md) · 🇭🇺 [hu](../../../hu/docs/architecture/cluster-decisions.md) · 🇦🇲 [hy](../../../hy/docs/architecture/cluster-decisions.md) · 🇮🇩 [id](../../../id/docs/architecture/cluster-decisions.md) · 🇳🇬 [ig](../../../ig/docs/architecture/cluster-decisions.md) · 🇮🇹 [it](../../../it/docs/architecture/cluster-decisions.md) · 🇯🇵 [ja](../../../ja/docs/architecture/cluster-decisions.md) · 🇬🇪 [ka](../../../ka/docs/architecture/cluster-decisions.md) · 🇰🇭 [km](../../../km/docs/architecture/cluster-decisions.md) · 🇮🇳 [kn](../../../kn/docs/architecture/cluster-decisions.md) · 🇰🇷 [ko](../../../ko/docs/architecture/cluster-decisions.md) · 🇱🇹 [lt](../../../lt/docs/architecture/cluster-decisions.md) · 🇱🇻 [lv](../../../lv/docs/architecture/cluster-decisions.md) · 🇮🇳 [ml](../../../ml/docs/architecture/cluster-decisions.md) · 🇮🇳 [mr](../../../mr/docs/architecture/cluster-decisions.md) · 🇲🇾 [ms](../../../ms/docs/architecture/cluster-decisions.md) · 🇲🇹 [mt](../../../mt/docs/architecture/cluster-decisions.md) · 🇲🇲 [my](../../../my/docs/architecture/cluster-decisions.md) · 🇳🇵 [ne](../../../ne/docs/architecture/cluster-decisions.md) · 🇳🇱 [nl](../../../nl/docs/architecture/cluster-decisions.md) · 🇳🇴 [no](../../../no/docs/architecture/cluster-decisions.md) · 🇮🇳 [or](../../../or/docs/architecture/cluster-decisions.md) · 🇮🇳 [pa](../../../pa/docs/architecture/cluster-decisions.md) · 🇵🇭 [phi](../../../phi/docs/architecture/cluster-decisions.md) · 🇵🇱 [pl](../../../pl/docs/architecture/cluster-decisions.md) · 🇵🇹 [pt](../../../pt/docs/architecture/cluster-decisions.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/cluster-decisions.md) · 🇷🇴 [ro](../../../ro/docs/architecture/cluster-decisions.md) · 🇷🇺 [ru](../../../ru/docs/architecture/cluster-decisions.md) · 🇱🇰 [si](../../../si/docs/architecture/cluster-decisions.md) · 🇸🇰 [sk](../../../sk/docs/architecture/cluster-decisions.md) · 🇸🇮 [sl](../../../sl/docs/architecture/cluster-decisions.md) · 🇷🇸 [sr](../../../sr/docs/architecture/cluster-decisions.md) · 🇸🇪 [sv](../../../sv/docs/architecture/cluster-decisions.md) · 🇰🇪 [sw](../../../sw/docs/architecture/cluster-decisions.md) · 🇮🇳 [ta](../../../ta/docs/architecture/cluster-decisions.md) · 🇮🇳 [te](../../../te/docs/architecture/cluster-decisions.md) · 🇹🇭 [th](../../../th/docs/architecture/cluster-decisions.md) · 🇹🇷 [tr](../../../tr/docs/architecture/cluster-decisions.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/cluster-decisions.md) · 🇵🇰 [ur](../../../ur/docs/architecture/cluster-decisions.md) · 🇺🇿 [uz](../../../uz/docs/architecture/cluster-decisions.md) · 🇻🇳 [vi](../../../vi/docs/architecture/cluster-decisions.md) · 🇳🇬 [yo](../../../yo/docs/architecture/cluster-decisions.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/cluster-decisions.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/cluster-decisions.md)
---
**ሁኔታ:** ሃሳብ (@diegosouzapw ግምገማን በመጠባበቅ ላይ)
**ቀን:** 2026-06-20
**ማጣቀሻዎች:** [#3932](https://github.com/diegosouzapw/OmniRoute/issues/3932), PR #4381
## በአጭሩ
በ[`docker-compose.yml`](../../docker-compose.yml) ውስጥ ላለው ነባር ባለ8-አገልግሎት ማሰማራት፣ ሁለት በምርጫ የሚነቁ compose መገለጫዎች (`memory`፣ `bifrost`)። ነባሪው የማስነሻ ባህሪ **አልተቀየረም**፦ 3 × `omniroute` replicas + Caddy + Redis + CliproxyAPI። ሁለቱ አዲስ መገለጫዎች Qdrant እና Bifrostን እንደ አማራጭ sidecars ያክላሉ፤ የሚነቁትም በ`docker compose --profile <name> up` ነው። **ምንም ነባር አገልግሎት አይወገድም ወይም አይተካም።**
## ይህ ለምን ጥንቃቄ የተሞላበት ነው
የOmniRoute ነባር የማሰማራት አወቃቀር ቀድሞውኑ ቀላልና የተረጋገጠ ነው፦
- **`redis:7-alpine`** በምርት ልኬት የrate-limit/cache የሥራ ጫናን ያስተናግዳል።
- **SQLite + sqlite-vec + FTS5** አካባቢያዊ ማህደረ ትውስታን + vectorን + የጽሑፍ ፍለጋን ይሸፍናሉ ([`src/lib/memory/vectorStore.ts:108`](../../src/lib/memory/vectorStore.ts) ይመልከቱ)።
- **Caddy** ቀድሞውኑ LB + TLS terminator ነው ([`docker-compose.yml`](../../docker-compose.yml))።
- **Bifrost** ቀድሞውኑ በ[`src/app/api/v1/relay/chat/completions/bifrost/route.ts`](../../src/app/api/v1/relay/chat/completions/bifrost/route.ts) ውስጥ እንደ Tier-1 router ተዋህዷል (`BIFROST_ENABLED` env varን በመጠቀም kill switch ያለው sidecar proxy — sidecarን ለማለፍ እና ወደ TS መንገድ ለመመለስ `=0` ያድርጉ)።
እዚህ ያሉት ሁለቱ መገለጫዎች **የSQLite አቅም ገደብ ላይ ለደረሱ ማሰማራቶች የማስፋፊያ አማራጮች** ናቸው — migrations አይደሉም። ሁለቱም በነባሪ የተሰናከሉ ናቸው።
## ሁለቱ መገለጫዎች
### `memory` — Qdrant Vector Memory Sidecar
**መቼ እንደሚነቃ፦**
- > በአንድ ማሰማራት ከ1M embeddings በላይ (sqlite-vec በከፍተኛ ልኬት መዘግየት ይጀምራል)።
- በ`omniroute-1/2/3` መካከል የጋራ vector state የሚፈልግ multi-replica ማሰማራት።
- ቀድሞውኑ ውጫዊ Qdrant cluster (Qdrant Cloud፣ on-prem) ካለዎት።
**የሚያክለው፦**
| አገልግሎት | Image | Ports | ማስታወሻዎች |
| -------- | ----------------------- | ----------- | ----------------------------------------------------- |
| `qdrant` | `qdrant/qdrant:v1.12.4` | `6333` HTTP | HNSW index፤ persistent volume `omniroute_qdrant_data` |
**ማንቃት፦** በSettings UI ውስጥ `qdrantEnabled = true` ያድርጉ **ወይም** `QDRANT_HOST=qdrant` env ያቀናብሩ። ስለ precedence ደንቦቹ (settings table → env var → default) [`src/lib/memory/qdrant.ts:60`](../../src/lib/memory/qdrant.ts)ን ይመልከቱ።
**Env vars:** `QDRANT_HOST`, `QDRANT_PORT`, `QDRANT_API_KEY`, `QDRANT_COLLECTION`, `QDRANT_VECTOR_SIZE`, `QDRANT_HNSW_EF_CONSTRUCT` (`.env.example` መስመሮች 1672-1683ን ይመልከቱ)።
### `bifrost` — Bifrost Tier-1 Router Sidecar
**መቼ እንደሚነቃ፦**
- ≥3 `omniroute` replicas የሚያስኬዱ እና provider rotationን በአንድ Go process ውስጥ ማዕከላዊ ማድረግ የሚፈልጉ ከሆነ።
- በሁሉም replicas ላይ ለupstream-provider ጥያቄዎች አንድ audit/logging surface ከፈለጉ።
- የTier-1 routing layerን ከOmniRoute replicas ነፃ በሆነ መልኩ በአግድም ማስፋት ከፈለጉ።
**የሚያክለው፦**
| አገልግሎት | Image | Ports | ማስታወሻዎች |
| --------- | --------------------------------- | ------ | ---------------------------------------------------------------------------- |
| `bifrost` | `ghcr.io/maximhq/bifrost:v1.6.11` | `8080` | በGo ላይ የተመሠረተ Tier-1 router፤ persistent logs volume `omniroute_bifrost_logs` |
**ማንቃት፦** በ`.env.example` ውስጥ `BIFROST_BASE_URL=http://bifrost:8080` ያቀናብሩ። በ[`src/app/api/v1/relay/chat/completions/bifrost/route.ts`](../../src/app/api/v1/relay/chat/completions/bifrost/route.ts) ያለው ነባር sidecar proxy route (በPR #4381 የታከለ) ይህን በራስ-ሰር ይጠቀማል።
**Env vars:** `BIFROST_BASE_URL`, `BIFROST_API_KEY`, `BIFROST_STREAMING_ENABLED`, `BIFROST_TIMEOUT_MS` (`.env.example` መስመሮች 1685-1695ን ይመልከቱ)።
## ይህ PR በግልጽ የማያደርጋቸው ነገሮች
የመጀመሪያው የጉዳይ ውይይት ሰፋ ያለ የክላስተር ዳግም ግንባታ ሃሳብ አቅርቦ ነበር። ትክክለኛውን የሥራ ጫና ቅርጽ ከተገመገመ በኋላ፣ የሚከተሉት በተሰጡት ምክንያቶች **ውድቅ ተደርገዋል**፦
| ክፍለ አካል | ውሳኔ | ምክንያት |
| ------------------------------------ | --------- | ---------------------------------------------------------------------------------------- |
| **Dragonfly** | **አስወግድ** | `redis:7-alpine` በምርት ደረጃ ላለው የፍጥነት ገደብ ሥራ ጫና ቀድሞውኑ በቂ ነው፤ ሊሻገር የሚገባ ጣሪያ የለም። |
| **NATS** | **አስወግድ** | እያንዳንዱ `omniroute` ቅጂ አንድ Node.js ሂደት ነው፤ ባለብዙ-ሂደት pub/sub የሥራ ጫና የለም። |
| **PostgreSQL** | **አስወግድ** | SQLite + sqlite-vec + FTS5 ሦስቱንም የአጠቃቀም ሁኔታዎች ይሸፍናሉ፤ 97 ፍልሰቶች + Electron ማሸግ ፍልሰቱን ያግዳሉ። |
| **Neo4j** | **አስወግድ** | ማስተላለፍ የ5-ሰንጠረዥ join ነው፤ በSQLite ላይ recursive CTE በቂ ነው። |
| **MinIO** | **አስወግድ** | ባለብዙ-MB blob የሥራ ጫና የለም፤ ምስሎች/ድምፅ ቀጥታ ማሳለፊያ ፕሮክሲዎች ናቸው። |
| **pgvector / pg_ai / pg_textsearch** | **አስወግድ** | ከPostgreSQL ጋር ተመሳሳይ የSQLite ጣሪያ ምክንያት ነው፤ የpgvector ስነ-ምህዳር የተበታተነ ነው። |
| **HAProxy / Envoy** | **አስወግድ** | Caddy ቀድሞውኑ LB + TLS ያከናውናል፤ ሁለቱም እንደ Tier-1 ራውተሮች በግልጽ ውድቅ ተደርገዋል (`AGENTS.md`ን ይመልከቱ)። |
ወደፊት የሚኖር የአጠቃቀም ሁኔታ ከእነዚህ አንዱን ተገቢ መሆኑን ካረጋገጠ፣ ይህ ሰነድ ማሻሻያው የሚደረግበት ቦታ ነው።
## የ4-ሳምንት ሥራ ላይ ማዋል (ከጸደቀ)
1. **ሳምንት 1** — ይህን PR ማዋሃድ + በ3-ቅጂ compose stack ላይ በምርጫ የሚነቁ መገለጫዎችን ማረጋገጥ።
2. **ሳምንት 2** — በ[`src/app/api/v1/relay/chat/completions/bifrost/route.ts`](../../src/app/api/v1/relay/chat/completions/bifrost/route.ts) ላይ ያለውን የsidecar ፕሮክሲ መስመር በመጠቀም ለOpenAI/Claude/Gemini/Ollama (ከ14+ አቅራቢዎች 4ቱ) Bifrostን ሙሉ በሙሉ ማንቃት (በ`BIFROST_ENABLED` የተገደበ፣ በሥራ ላይ እያለ በkill-switch ሊጠፋ የሚችል)።
3. **ሳምንት 3** — በአንድ የሙከራ ማሰማሪያ ውስጥ የQdrant ማህደረ ትውስታ መገለጫን ማንቃት፤ ከsqlite-vec ጋር ሲነጻጸር የመዘግየት ልዩነቱን መለካት።
4. **ሳምንት 4** — የታዛቢነት የጤና ፍተሻዎች (`docker compose ps` የመውጫ ኮዶች + `wget` የጭስ ሙከራዎች)፤ በADR-041 መሠረት የ71-ምሰሶ እድሳት።
## በዚህ PR ውስጥ የተቀየሩ ፋይሎች
| ፋይል | ለውጥ |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docker-compose.yml` | +30 መስመሮች፦ `memory` መገለጫ (Qdrant)፣ `bifrost` መገለጫ (Bifrost)፣ ቋሚ የማከማቻ ጥራዞች፣ የጤና ፍተሻዎች። |
| `.env.example` | +24 መስመሮች፦ `QDRANT_*` (6 ተለዋዋጮች)፣ `BIFROST_*` (4 ተለዋዋጮች)። |
| `docs/reference/ENVIRONMENT.md` | በክፍል 25 ውስጥ ለ`QDRANT_*` የአካባቢ ተለዋዋጮች +6 ረድፎች። |
| `src/lib/memory/qdrant.ts` | +33 መስመሮች፦ ለ`QDRANT_HOST`/`QDRANT_PORT`/`QDRANT_API_KEY`/`QDRANT_COLLECTION`/`QDRANT_VECTOR_SIZE`/`QDRANT_HNSW_EF_CONSTRUCT`/`QDRANT_EMBEDDING_MODEL` የአካባቢ-ተለዋዋጭ የfallback ሰንሰለት (ቅንብሮች → አካባቢ → ነባሪ)። |
| `src/lib/memory/__tests__/qdrant-wiring.test.ts` | +88 መስመሮች፦ የአካባቢ-ተለዋዋጭ fallback ቅድሚያን የሚያረጋግጡ 9 አዲስ የሙከራ ጉዳዮች። |
| `docs/architecture/cluster-decisions.md` (ይህ ፋይል) | አዲስ — በምርጫ ለሚነቁ መገለጫዎች የውሳኔ መዝገብ። |
| `AGENTS.md` | +1 መስመር፦ በማጣቀሻ ሰነዶች ሰንጠረዥ ውስጥ ወደዚህ ሰነድ የሚያመለክት ጠቋሚ። |
**በጠቅላላ የተነካ ኮድ፦** 4 የምርት ፋይሎች (`docker-compose.yml`፣ `qdrant.ts`፣ `.env.example`፣ `ENVIRONMENT.md`)፣ 1 የሙከራ ፋይል (`qdrant-wiring.test.ts`)፣ 2 የሰነድ ፋይሎች (`cluster-decisions.md`፣ `AGENTS.md`)።

195
docs/i18n/am/docs/architecture/persistence-backend-boundary.md Normal file
View File

File diff suppressed because one or more lines are too long

68
docs/i18n/am/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md Normal file
View File

@@ -0,0 +1,68 @@
# OmniRoute vs Alternatives (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇸🇦 [ar](../../../ar/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇦🇿 [az](../../../az/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇧🇬 [bg](../../../bg/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇧🇩 [bn](../../../bn/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇨🇿 [cs](../../../cs/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇩🇰 [da](../../../da/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇩🇪 [de](../../../de/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇬🇷 [el](../../../el/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇪🇸 [es](../../../es/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇪🇪 [et](../../../et/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇷 [fa](../../../fa/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇫🇮 [fi](../../../fi/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇫🇷 [fr](../../../fr/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇪 [ga](../../../ga/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [gu](../../../gu/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇳🇬 [ha](../../../ha/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇱 [he](../../../he/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [hi](../../../hi/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇭🇷 [hr](../../../hr/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇭🇺 [hu](../../../hu/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇦🇲 [hy](../../../hy/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇩 [id](../../../id/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇳🇬 [ig](../../../ig/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇹 [it](../../../it/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇯🇵 [ja](../../../ja/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇬🇪 [ka](../../../ka/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇰🇭 [km](../../../km/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [kn](../../../kn/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇰🇷 [ko](../../../ko/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇱🇹 [lt](../../../lt/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇱🇻 [lv](../../../lv/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [ml](../../../ml/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [mr](../../../mr/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇲🇾 [ms](../../../ms/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇲🇹 [mt](../../../mt/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇲🇲 [my](../../../my/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇳🇵 [ne](../../../ne/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇳🇱 [nl](../../../nl/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇳🇴 [no](../../../no/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [or](../../../or/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [pa](../../../pa/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇵🇭 [phi](../../../phi/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇵🇱 [pl](../../../pl/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇵🇹 [pt](../../../pt/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇷🇴 [ro](../../../ro/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇷🇺 [ru](../../../ru/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇱🇰 [si](../../../si/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇸🇰 [sk](../../../sk/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇸🇮 [sl](../../../sl/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇷🇸 [sr](../../../sr/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇸🇪 [sv](../../../sv/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇰🇪 [sw](../../../sw/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [ta](../../../ta/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇮🇳 [te](../../../te/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇹🇭 [th](../../../th/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇹🇷 [tr](../../../tr/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇵🇰 [ur](../../../ur/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇺🇿 [uz](../../../uz/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇻🇳 [vi](../../../vi/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇳🇬 [yo](../../../yo/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
---
ከታዋቂ ክፍት ምንጭ AI ራውተሮች ጋር የባህሪያት ተጨባጭ ንጽጽር።
> **ዘዴ**: ይፋዊ ማከማቻዎች በ2026-Q2 ኦዲት ተደርገዋል። ስሪቶቹ እንደተዘረዘሩት ናቸው።
> እርማቶችን በPR ያስገቡ — ይህ ትክክለኛ እንዲሆን እንፈልጋለን።
| ባህሪ | OmniRoute 3.8 | LiteLLM 1.x | OpenRouter (SaaS) | Portkey |
| -------------------------------------------- | :-------------------------------------: | :---------: | :---------------: | :--------: |
| **አቅራቢዎች** | **329** | ~100 | ~50 | ~30 |
| **ነፃ/ማረጋገጫ የማይፈልጉ የካታሎግ ግቤቶች** | **155** | n/a | ቀጥታ ማስተላለፍ | n/a |
| **በራስ ሰርቨር ላይ ማስተናገድ የሚቻል** | ✅ | ✅ | ❌ | ⚠ የሚከፈልበት |
| **OAuth የካታሎግ ግቤቶች** | **23** | ከፊል | ❌ | ❌ |
| **ራስ-ሰር የመጠባበቂያ ጥምረቶች** | **19 ስልቶች** | ቅድሚያ-ተኮር | ደረጃ-ተኮር | ክብደት-ተኮር |
| **Fusion (ትይዩ ፓነል + የዳኛ ውህደት)** | ✅ | ❌ | ❌ | ❌ |
| **የTier 1/2/3 መጠባበቂያ (ደንበኝነት→ርካሽ→ነፃ)** | ✅ + UI | በእጅ | n/a | በእጅ |
| **የቶከን መጭመቅ** | 12-ሞተር ስብስብ (RTK + Caveman + LLMLingua) | የለም | የለም | የለም |
| **ባለብዙ ሞዳሊቲ ማመንጨት (ንግግር/ሙዚቃ/ቪዲዮ)** | ✅ | ❌ | ቀጥታ ማስተላለፍ | ❌ |
| **አብሮገነብ MCP ሰርቨር** | ✅ 110 መሣሪያዎች፣ 33 ወሰኖች | ❌ | ❌ | ❌ |
| **A2A ፕሮቶኮል** | ✅ 6 ክህሎቶች | ❌ | ❌ | ❌ |
| **ማህደረ ትውስታ (FTS5 + ቬክተር)** | ✅ | ❌ | ❌ | ❌ |
| **የደኅንነት ገደቦች (PII፣ injection፣ vision)** | ✅ | ከፊል | ❌ | ✅ የሚከፈልበት |
| **የደመና ኤጀንት ውህደቶች** | Codex, Cursor, Devin, Jules | ❌ | ❌ | ❌ |
| **ለእያንዳንዱ አቅራቢ የወረዳ መቋረጫ** | ✅ 3-ሁኔታ፣ ዘገምተኛ መልሶ ማግኛ | መሠረታዊ | ❌ | ✅ |
| **የTLS አሻራ ስውርነት (JA3/JA4)** | ✅ wreq-js | ❌ | ❌ | ❌ |
| **የግምገማ ማዕቀፍ** | ✅ አብሮገነብ | ❌ | ❌ | ⚠ የሚከፈልበት |
| **MITM ፕሮክሲ (Cursor/Antigravityን የሚያቋርጥ)** | ✅ ሁለገብ-መድረክ | ❌ | ❌ | ❌ |
| **CLI ከሲስተም ትሬይ ጋር (Electron የሌለው)** | ✅ | ❌ | n/a | n/a |
| **CLI በማሽን-ID ራስ-ሰር ማረጋገጫ** | ✅ | ❌ | n/a | n/a |
| **ዳሽቦርድ** | Next.js 16 | መሠረታዊ | የባለቤትነት | የባለቤትነት |
| **i18n** | **42 አካባቢያዊ ቅንብሮች** | ❌ | ❌ | ⚠ |
| **ይፋዊ የኤጀንት ክህሎቶች (SKILL.md)** | ✅ 45 | ❌ | ❌ | ❌ |
| **የቱነል ድጋፍ (Cloudflared, Tailscale, Ngrok)** | ✅ | ❌ | n/a | n/a |
| **ፈቃድ** | MIT | MIT | የባለቤትነት | የባለቤትነት |
## OmniRouteን መቼ መምረጥ እንዳለብዎት
- በራስዎ ሰርቨር ያስተናግዳሉ እና **ከፍተኛውን የአቅራቢ ሽፋን** ይፈልጋሉ (329 አቅራቢዎች፣ 155 ነፃ/ማረጋገጫ የማይፈልጉ የካታሎግ ግቤቶች)
- **አብሮገነብ MCP ሰርቨር** ያስፈልግዎታል (LLM መሣሪያዎች፣ ማህደረ ትውስታ እና ክህሎቶች እንደ መሣሪያዎች የቀረቡ)
- ለኤጀንት-ወደ-ኤጀንት የሥራ ፍሰቶች **A2A ፕሮቶኮል** ያስፈልግዎታል
- በመነሻ አገልግሎቶች CAPTCHA እንዳይለዩ **የአሻራ ስውርነት** (JA3/JA4) ይፈልጋሉ
- የSaaS ክፍያ ሳይኖር **የድርጅት ባህሪያት** (የደኅንነት ገደቦች፣ ግምገማዎች፣ የኦዲት መዝገብ) ያስፈልግዎታል
## LiteLLMን መቼ መምረጥ እንዳለብዎት
- **Python-ተኮር** ነዎት እና ከ`litellm.completion()` ጋር ጥብቅ ውህደት ያስፈልግዎታል
- **በሳል የምርት ማሰማሪያ መመሪያዎች** (k8s፣ Helm charts) ያስፈልጉዎታል
- ቡድንዎ ቀድሞውኑ Python ማይክሮሰርቪሶችን ያስኬዳል
## OpenRouter (SaaS)ን መቼ መምረጥ እንዳለብዎት
- በራስዎ ሰርቨር ማስተናገድ አይፈልጉም
- በSaaS ተጨማሪ ዋጋ ለእያንዳንዱ ቶከን መክፈል ችግር የለብዎትም
- በሁሉም አቅራቢዎች ላይ **አንድ የክፍያ ዘዴ** ያስፈልግዎታል
## Portkeyን መቼ መምረጥ እንዳለብዎት
- የሥራ ጊዜ ዋስትናዎች ያሉት **የንግድ SLA** ያስፈልግዎታል
- የኦፕሬሽን ጫና የሌለበትን **የሚተዳደር ዳሽቦርድ** ይመርጣሉ
- ወዲያውኑ ዝግጁ የሆኑ **የድርጅት ተገዢነት** ባህሪያት ያስፈልግዎታል
---
_ለመጨረሻ ጊዜ የዘመነው፦ 2026-08-02። ይህን ሰንጠረዥ ትክክለኛ ለማድረግ እርማቶችን በPR ያስገቡ።_

382
docs/i18n/am/docs/compression/COMPRESSION_ENGINES.md Normal file
View File

@@ -0,0 +1,382 @@
# Compression Engines (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../compression/COMPRESSION_ENGINES.md) · 🇸🇦 [ar](../../../ar/docs/compression/COMPRESSION_ENGINES.md) · 🇦🇿 [az](../../../az/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇬 [bg](../../../bg/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇩 [bn](../../../bn/docs/compression/COMPRESSION_ENGINES.md) · 🇨🇿 [cs](../../../cs/docs/compression/COMPRESSION_ENGINES.md) · 🇩🇰 [da](../../../da/docs/compression/COMPRESSION_ENGINES.md) · 🇩🇪 [de](../../../de/docs/compression/COMPRESSION_ENGINES.md) · 🇬🇷 [el](../../../el/docs/compression/COMPRESSION_ENGINES.md) · 🇪🇸 [es](../../../es/docs/compression/COMPRESSION_ENGINES.md) · 🇪🇪 [et](../../../et/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇷 [fa](../../../fa/docs/compression/COMPRESSION_ENGINES.md) · 🇫🇮 [fi](../../../fi/docs/compression/COMPRESSION_ENGINES.md) · 🇫🇷 [fr](../../../fr/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇪 [ga](../../../ga/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [gu](../../../gu/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇬 [ha](../../../ha/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇱 [he](../../../he/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [hi](../../../hi/docs/compression/COMPRESSION_ENGINES.md) · 🇭🇷 [hr](../../../hr/docs/compression/COMPRESSION_ENGINES.md) · 🇭🇺 [hu](../../../hu/docs/compression/COMPRESSION_ENGINES.md) · 🇦🇲 [hy](../../../hy/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇩 [id](../../../id/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇬 [ig](../../../ig/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇹 [it](../../../it/docs/compression/COMPRESSION_ENGINES.md) · 🇯🇵 [ja](../../../ja/docs/compression/COMPRESSION_ENGINES.md) · 🇬🇪 [ka](../../../ka/docs/compression/COMPRESSION_ENGINES.md) · 🇰🇭 [km](../../../km/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [kn](../../../kn/docs/compression/COMPRESSION_ENGINES.md) · 🇰🇷 [ko](../../../ko/docs/compression/COMPRESSION_ENGINES.md) · 🇱🇹 [lt](../../../lt/docs/compression/COMPRESSION_ENGINES.md) · 🇱🇻 [lv](../../../lv/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [ml](../../../ml/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [mr](../../../mr/docs/compression/COMPRESSION_ENGINES.md) · 🇲🇾 [ms](../../../ms/docs/compression/COMPRESSION_ENGINES.md) · 🇲🇹 [mt](../../../mt/docs/compression/COMPRESSION_ENGINES.md) · 🇲🇲 [my](../../../my/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇵 [ne](../../../ne/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇱 [nl](../../../nl/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇴 [no](../../../no/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [or](../../../or/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [pa](../../../pa/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇭 [phi](../../../phi/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇱 [pl](../../../pl/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇹 [pt](../../../pt/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/COMPRESSION_ENGINES.md) · 🇷🇴 [ro](../../../ro/docs/compression/COMPRESSION_ENGINES.md) · 🇷🇺 [ru](../../../ru/docs/compression/COMPRESSION_ENGINES.md) · 🇱🇰 [si](../../../si/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇰 [sk](../../../sk/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇮 [sl](../../../sl/docs/compression/COMPRESSION_ENGINES.md) · 🇷🇸 [sr](../../../sr/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇪 [sv](../../../sv/docs/compression/COMPRESSION_ENGINES.md) · 🇰🇪 [sw](../../../sw/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [ta](../../../ta/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [te](../../../te/docs/compression/COMPRESSION_ENGINES.md) · 🇹🇭 [th](../../../th/docs/compression/COMPRESSION_ENGINES.md) · 🇹🇷 [tr](../../../tr/docs/compression/COMPRESSION_ENGINES.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇰 [ur](../../../ur/docs/compression/COMPRESSION_ENGINES.md) · 🇺🇿 [uz](../../../uz/docs/compression/COMPRESSION_ENGINES.md) · 🇻🇳 [vi](../../../vi/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇬 [yo](../../../yo/docs/compression/COMPRESSION_ENGINES.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/COMPRESSION_ENGINES.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/COMPRESSION_ENGINES.md)
---
OmniRoute መጭመቅ በሞተር ውሎች ዙሪያ የተገነባ ነው። አንድ ሁነታ አንድን ሞተር በቀጥታ
(`caveman` ወይም `rtk`) ወይም ብዙ ሞተሮችን በቅደም ተከተል የሚያስኬድ ቆራጥ የተደራረበ የማስኬጃ መስመር ሊያስኬድ ይችላል።
## ሁነታዎች
| ሁነታ | የሞተር መንገድ | የታሰበ ግብዓት |
| ------------ | -------------------------------- | -------------------------------------- |
| `off` | የለም | የጥያቄውን ትክክለኛ ቅርጽ መጠበቅ |
| `lite` | Caveman lite ረዳቶች | ዝቅተኛ ስጋት ያለው ሁልጊዜ ንቁ ማጽዳት |
| `standard` | Caveman | በተፈጥሯዊ ቋንቋ የተጻፈ ጥያቄን ማጠቃለል |
| `aggressive` | Caveman + የታሪክ/መሣሪያ ማጠቃለያዎች | ረጅም የውይይት ክፍለ ጊዜዎች |
| `ultra` | Caveman + የመከርከሚያ ረዳቶች | ከአውድ ገደብ ማገገም |
| `rtk` | RTK | የተርሚናል፣ shell፣ build፣ test እና git ውጤት |
| `omniglyph` | OmniGlyph | በቤተኛው የአቅራቢ ግንኙነት ላይ አውድን እንደ ምስል መጠቀም |
| `stacked` | የማስኬጃ መስመር፣ ነባሩ `rtk -> caveman` | የተቀላቀሉ የመሣሪያ ምዝግቦች እና ስድ ጽሑፍ፣ ከፍተኛ ቁጠባ |
### OmniGlyph የመጭመቂያ መገለጫዎች
የ`omniglyph` ሞተር (ጥቅል `omniglyph`፣ 1.4.0+) በመጭመቂያ ቅንብሮች ውስጥ
በ`omniglyph.profile` አማካይነት በአጠቃላይ፣ ወይም በተደራረበው የማስኬጃ መስመር የደረጃ ውቅር አማካይነት
ለእያንዳንዱ ደረጃ የሚዘጋጅ በስም የተሰየመ የፍቺ መገለጫ ይቀበላል፦
| መገለጫ | ወሰን |
| ------------- | -------------------------------------------------------------------------- |
| `aggressive` | ነባሪ። የታተሙት ደረሰኞች የለኩት መመሪያ — የስርዓት፣ የመሣሪያ ሰነዶች እና ጥቅጥቅ ያለ ታሪክ ምስሎች |
| `balanced` | ንቁ ሁኔታን በቤተኛ ቅርጹ ያቆያል፣ የመጨረሻዎቹን 8 ዙሮች ይጠብቃል፣ የቆየ የተዘጋ ታሪክን ይሰብስባል |
| `coding-safe` | ሥልጣንን፣ የመሣሪያ ንድፎችን እና ንቁ የመሣሪያ ውጤትን በቤተኛ ቅርጻቸው ያቆያል፣ የመጨረሻዎቹን 12 ዙሮች ይጠብቃል |
| `passthrough` | ሳይለውጥ ያስተላልፋል፤ ሞተሩ ይዘለላል |
መገለጫው **ጣሪያ እንጂ ወለል አይደለም**፦ በጥቅሉ ውስጥ ያለው `mergeCompressionProfileOptions`
የጠሪው ሽረዛ መገለጫው የዘጋውን መረጃ-አጥፊ መስመር እንደገና እንዲከፍት አይፈቅድም፤ ስለዚህ የእያንዳንዱ ደረጃ
`preserveSystemPrompt: false` በ`coding-safe` ስር የስርዓት መጭመቅን እንደገና ማንቃት አይችልም።
በዚህ የኮድ መሠረት ላይ እንደተለካው፦ `coding-safe` እና `balanced` `minCompressChars`ን ወደ
ከፍተኛው ያሳድጋሉ፣ እንዲሁም ስርዓቱን፣ የመሣሪያ ንድፎችን እና የመሣሪያ ውጤቶችን በቤተኛ ቅርጻቸው ያቆያሉ፤ ስለዚህ ገና
ታሪክ ያልሰበሰበ ክፍለ ጊዜ በ`below_min_chars` ላይ ይቆማል፣ ሞተሩም ምንም ነገር አይለውጥም። ነባሩ
ከሁሉ ደህንነቱ የተጠበቀው መገለጫ ሳይሆን `aggressive` የሆነው ለዚህ ነው።
ጥቅሉ የራሱን የሞዴል ወሰን እና መገለጫ ከአካባቢ ውቅሩ ይወስናል።
OmniRoute ውሳኔውን ፈጽሞ አይወክልም፦ አስማሚው የሞዴል መግቢያውን በጥቅሉ
እጅግ ገዳቢ በሆነው ወሰን ላይ ይቆልፋል፤ ስለዚህ የአስተናጋጅ አካባቢ ቅንብሮች የተፈቀዱ ዝርዝሩን ማጥበብ ብቻ ይችላሉ እንጂ
ከOmniRoute የተለኩ ደረሰኞች በላይ ማስፋት ፈጽሞ አይችሉም።
## የኤንጂን ሬጅስትሪ
ሬጅስትሪው በ`open-sse/services/compression/engines/registry.ts` ውስጥ ይገኛል። ኤንጂኖቹ የጋራ ውል ያቀርባሉ፦
- `id`፦ እንደ `caveman` ወይም `rtk` ያለ የማይለዋወጥ የኤንጂን መለያ
- `apply(text, config)`፦ በተደራራቢ ፓይፕላይኖች ጥቅም ላይ የሚውል የቀድሞ የማስኬጃ መንገድ
- `compress(input, config)`፦ ጽሑፍ + ስታቲስቲክስ የሚመልስ ዋና የማስኬጃ መንገድ
- `getConfigSchema()`፦ የሚሰራ ውቅር JSON-Schema-መሰል ቅርጽን ይመልሳል
- `validateConfig(config)`፦ `{ valid, errors[] }`ን ይመልሳል
ምዝገባ `registerCompressionEngine(engine)`ን (ወይም ለላቁ አጋጣሚዎች `registerEngine`ን) ይጠቀማል፤ ይህም ተቀባይነት ከመስጠቱ በፊት `assertValidEngine()`ን እና `validateConfig(defaultConfig)`ን ይጠራል።
በሂደት ላይ ሳለ ኤንጂንን ለማስወገድ `unregisterCompressionEngine(id)`ን ይጠቀሙ።
`strategySelector.ts` መጭመቅ ከመካሄዱ በፊት አብረው የተካተቱትን ኤንጂኖች ይመዘግባል። ይህም ቅድመ-ዕይታ፣ የአሂድ-ጊዜ መጭመቅ፣ የተደራራቢ ሁነታ፣ ሙከራዎች እና የወደፊት ኤንጂኖች ተመሳሳይ የማስኬጃ መንገድን እንዲጠቀሙ ያስችላል።
### የMCP መግለጫ መጭመቅ (ተዛማጅ)
የተለየ ሬጅስትሪ የMCP መሣሪያ መግለጫ ሜታዳታን በሬጅስትሪ ደረጃ ይጨምቃል — `open-sse/mcp-server/descriptionCompressor.ts`ን እና [MCP-SERVER.md](../frameworks/MCP-SERVER.md)ን ይመልከቱ። የCaveman ደንቦችን እንደገና ይጠቀማል፣ ነገር ግን የሚሠራው በመሣሪያ ሜታዳታ ላይ እንጂ በጥያቄ ፔይሎዶች ላይ አይደለም።
### ተጨማሪ አብረው የተካተቱ ኤንጂኖች
ከCaveman፣ RTK እና LLMLingua-2 በተጨማሪ፣ ሬጅስትሪው በርካታ ልዩ መረጃ-አልባ ያልሆኑ /
መዋቅራዊ ኤንጂኖችን ይዞ ይመጣል (በተደራራቢ ፓይፕላይኖች፣ በመሞከሪያ ስፍራው እና በሙከራዎች ጥቅም ላይ የሚውሉ)፦
| ኤንጂን | መለያ | የሚሠራው |
| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| CCR | `ccr` | Content-Compress-Retrieve (H4)፦ ትላልቅ ተከታታይ የጽሑፍ ብሎኮችን በይዘት-አድራሻ ማጣቀሻዎች ይተካል፤ ስለዚህ ተደጋጋሚ/ትላልቅ ብሎኮች አንድ ጊዜ ብቻ ተልከው ከዚያ በኋላ በማጣቀሻ ይጠቀሳሉ። |
| headroom | `headroom` | SmartCrusher (H3 + N5)፦ ተመሳሳይ-አይነት የJSON-ድርድር ፔይሎዶችን ወደ አምዳዊ `[N rows]` ቅርጽ መረጃ-አልባ ሳይሆን በሰንጠረዥ መጠቅለል። |
| ionizer | `ionizer` | በጣም ትላልቅ ተመሳሳይ-አይነት ብሎኮችን ከመጀመሪያ/መሃል/መጨረሻ የረድፍ ናሙና መውሰድ፣ የተወገደውን መሃል እንደ CCR ይዘት-አድራሻ ማጣቀሻ በማከማቸት። |
| session-dedup | `session-dedup` | ይዘት-አድራሻ ያለው ተራ-አቋራጭ ድግግሞሽ ማስወገድ (በTokenMizer የተነሳሳ)፦ በተመሳሳይ ክፍለ ጊዜ ቀደምት ተራዎች ላይ አስቀድሞ የታየን ጽሑፍ ያስቀራል። |
**የCCR መልሶ-ማግኛ-ፕሮቶኮል መመሪያ (#8033)፦** CCR በአንድ
ጥያቄ ውስጥ ≥1 ብሎክን ለመጀመሪያ ጊዜ ሲተካ፣ ኤንጂኑ ምልክት → መሣሪያ ውልን ለጠሪው የሚያስተምር፣ አንድ ብቻ የሆነ እና በድጋሚ ሲተገበር ውጤቱ የማይለወጥ `system` መልዕክትን (በ
`[CCR protocol]` መለያ የሚጀምር) ከፊት ያክላል፦ የ
`[CCR retrieve hash=<24hex> chars=N]` ምልክት ምን ማለት እንደሆነ፣ hash እንዳለ መገልበጥ እንዳለበት
(ሁሉም 24 ሄክስ ቁምፊዎች — በተሳሳተ መንገድ የተገለበጡ hash-ዎች የ"block not found"
ስህተቶች መንስኤ የመሆን እድላቸው ከፍተኛ ነው)፣ እንዲሁም የ`[dedup:ref sha=...]` ምልክት "ወደ ታሪክ ተመልሰህ ተመልከት" ማለት እንጂ "መሣሪያውን ጥራ"
ማለት እንዳልሆነ። ማስታወሻው የሚገባው **ጠሪው ያስታወቀው `tools[]` በእርግጥ
`omniroute_ccr_retrieve`ን ማግኘት እንደሚችል ሲያረጋግጥ ብቻ ነው** (`callerSupportsCcrRetrieve()` በ
`open-sse/services/compression/engines/ccr/protocolInstruction.ts`) — ያ መሣሪያ የሌለው መደበኛ
OpenAI-ተኳሃኝ ጠሪ ሊያገኘው የማይችለውን ነገር እንዲጠራ የሚነግር መመሪያ ፈጽሞ አይደርሰውም። የድጋሚ ተግባር ውጤት እንዳይለወጥ የሚደረገው ከማስገባት በፊት የመልዕክት ታሪኩን ለመለያው በመቃኘት ነው፤
ስለዚህ ባለብዙ-ተራ ጥያቄዎች (የቀደሙ መልዕክቶችን ደግመው የሚያቀርቡ) በእያንዳንዱ ተራ ማስታወሻውን ደራርበው አያስገቡም።
## Caveman
Caveman ሁነታ መደበኛ ጽሑፍን በትርጉም ላይ ተመስርቶ በማጠቃለል ላይ ያተኩራል፦
- የኮድ ብሎኮችን፣ URLs፣ JSON፣ ዱካዎችን እና የተዋቀረ ውሂብን ይጠብቃል
- አላስፈላጊ ቃላትን፣ ማመንታትን፣ የተደጋገመ ዐውድን እና የተንዛዛ አያያዥ አገላለጽን ያስወግዳል
- በ`open-sse/services/compression/rules/` ውስጥ ቋንቋን የሚያገናዝቡ የፋይል ደንብ ጥቅሎችን ይደግፋል
- በቀድሞዎቹ `standard`፣ `aggressive` እና `ultra` ሁነታዎች በኩል መጠቀም ይቻላል
የዳሽቦርዱ መገኛ `Dashboard -> Context & Cache -> Caveman` ነው።
የCaveman ዋና ፕሮጀክት `~75%` ያነሱ የውጤት ቶከኖች፣ በቤንችማርኮች በአማካይ `65%` የውጤት ቁጠባ፣
ከ`22-87%` ክልል ጋር፣ እንዲሁም `~46%` የግብዓት መጭመቂያ መሣሪያ እንዳለው ዘግቧል። OmniRoute የተደራረቡ የፕሮምፕት/ዐውድ ቁጠባዎችን ሲመዘግብ የCaveman የግብዓት-ወገን ቁጥርን ይጠቀማል፤ የCaveman የውጤት ሁነታ ግን የተለየ የምላሽ-ባህሪ ባህሪ ሆኖ ይቆያል።
## RTK
RTK ሁነታ በትዕዛዝ እና በመሣሪያ ውጤት ላይ ያተኩራል፦
- እንደ `git status`፣ `git branch`፣ `git diff`፣ Vitest/Jest/Pytest፣
Cargo/Go ሙከራዎች፣ TypeScript/Vite/Webpack ግንባታዎች፣ ESLint፣ npm audit/installs፣ Docker ምዝግቦች፣
የshell `find`/`grep`፣ stack traces እና አጠቃላይ ምዝግቦች ያሉ የውጤት ምድቦችን ይለያል
- ከ`open-sse/services/compression/engines/rtk/filters/` 49 JSON ማጣሪያዎችን ይተገብራል
- የRTK-ዘይቤ መግለጫዊ የሂደት ቧንቧን ይደግፋል፦ ANSI ማስወገድ፣ መተካት፣ ውጤትን ሲዛመድ አጭር-ዙር ማድረግ፣
መስመሮችን ማስወገድ/ማቆየት፣ በእያንዳንዱ መስመር መቁረጥ፣ የመጀመሪያ/የመጨረሻ/ከፍተኛ-መስመር መቁረጥ እና ባዶ ሲሆን አማራጭ ውጤት
- በ`.rtk/filters.json` ውስጥ በእምነት ቁጥጥር የተገደቡ የፕሮጀክት ማጣሪያዎችን እና በ
`DATA_DIR/rtk/filters.json` ውስጥ ዓለም አቀፍ ማጣሪያዎችን ይደግፋል
- ANSI ቅደም ተከተሎችን፣ የሂደት ጫጫታን፣ የተደጋገሙ መስመሮችን እና የማይጠቅም ተደጋጋሚ ጽሑፍን ያስወግዳል
- እርምጃ ሊወሰድባቸው የሚችሉ ውድቀቶችን፣ ማስጠንቀቂያዎችን፣ ማጠቃለያዎችን፣ የተቀየሩ ፋይሎችን እና የመጨረሻ ዐውድን ይጠብቃል
- በማረጋገጫ በተጠበቁ የአስተዳደር መስመሮች በኩል ለመልሶ ማግኘት/ማረም የተሸፈነ ጥሬ ውጤትን በአማራጭ ማቆየት ይችላል
የዳሽቦርዱ መገኛ `Dashboard -> Context & Cache -> RTK` ነው።
ለብጁ ማጣሪያዎች፣ እምነት፣ ማረጋገጥ እና ጥሬ-ውጤት መልሶ ማግኘት የሚያስፈልጉ የአሠራር ዝርዝሮች በ
[`RTK_COMPRESSION.md`](./RTK_COMPRESSION.md) ውስጥ ይገኛሉ።
የRTK ዋና ፕሮጀክት ለትዕዛዝ-ውጤት መጭመቅ `60-90%` ቁጠባ እንዳለ ዘግቧል። የREADME ምሳሌው
የ30-ደቂቃ Claude Code ክፍለ ጊዜ ከ`~118,000` ቶከኖች ወደ `~23,900` ሲቀንስ፣ ወይም `79.7%` ሲቆጠብ ያሳያል።
## LLMLingua-2 (የትርጉም መከርከም)
LLMLingua-2 ሁነታ አነስተኛ ONNX የቶከን መደብ አውጪን በመጠቀም በጽሑፍ ላይ **የትርጉም ቶከን መከርከም** ያከናውናል፣ በዚህም በደንብ ላይ የተመሠረቱትን Caveman እና RTK ሞተሮች ያሟላል፦
- በsystem ያልሆኑ መልዕክቶች ውስጥ ያለ ጽሑፍን ብቻ ይጭመቃል፤ fenced የኮድ ብሎኮች እና ሌሎች የሚጠበቁ አወቃቀሮች ፈጽሞ አይቀየሩም
- የ`@atjsh/llmlingua-2` backendን (ONNX በ`@huggingface/transformers` በኩል) በworker thread ውስጥ ያስኬዳል፤ ስለዚህ የሞዴል inference የጥያቄ event loopን ፈጽሞ አያግድም
- **ሊደራረብ ይችላል** (`stackPriority` 35)፦ በተደራረበ የሂደት ቧንቧ ውስጥ ከመዋቅራዊ ሞተሮች (CCR፣ session-dedup፣ headroom፣ Caveman) በኋላ ነገር ግን ከ`ultra` በፊት ይሰራል፤ ምክንያቱም የትርጉም መከርከም አስቀድሞ በመዋቅር በተጨመቀ ጽሑፍ ላይ የበለጠ ውጤታማ ነው — ለምሳሌ
`rtk -> caveman -> llmlingua`
- **በማንኛውም ስህተት ጊዜ ክፍት ሆኖ ይቀጥላል** (የጎደሉ optional deps፣ worker spawn፣ model load፣ inference፣
ወይም timeout) → የመጀመሪያው ጽሑፍ ሳይቀየር ይመለሳል፣ ስህተት ፈጽሞ አይመለስም
የሞተሩ መገኛ፦ `open-sse/services/compression/engines/llmlingua/`። የዳሽቦርዱ መገኛ
`Dashboard -> Context & Cache -> LLMLingua` ነው።
### ሞዴሎች
ነባሪው ሞዴል **TinyBERT** (`atjsh/llmlingua-2-js-tinybert-meetingbank`፣ ~57 MB፣
ፈጣን) ነው። ከፍተኛ-ትክክለኛነት ያለው **BERT-base** ሞዴል (`Arcoldd/llmlingua4j-bert-base-onnx`፣
~710 MB) በሞተሩ ውቅር `model` መስክ በኩል ይገኛል። `@huggingface/transformers`
የተመረጠውን ሞዴል በመጀመሪያው ጥሪ (`modelStore.ts`) ጊዜ ከHuggingFace Hub ወደ
`${DATA_DIR}/models/llmlingua` በሚያስፈልግበት ጊዜ ያወርዳል፤ የ`modelPath` ውቅር
መሻር በምትኩ ወደ አካባቢያዊ ቅጂ ይጠቁማል (ከመስመር ውጭ / ከአውታረ መረብ የተነጠሉ ጭነቶች)።
### አማራጭ ጥገኞች እና በፍላጎት ጊዜ መጫን
ሊከረከም የሚችለው የLLMLingua runtime peer stack **አማራጭ** ነው። ሁለት ጥቅሎች በ
`package.json` ውስጥ እንደ `optionalDependencies` ተገልጸዋል፣ እና በproduction build በ**ውጭ** ተይዘዋል
(`scripts/build/prepublish.ts` አያጠቃልላቸውም)፦
| ጥቅል | ስሪት (የተቆለፈ) | ማስታወሻዎች |
| -------------------- | ----------- | ---------------------------- |
| `@atjsh/llmlingua-2` | `2.0.5` | ዋና ጥቅል፤ ሌሎቹን እንደ peers ይገልጻል |
| `js-tiktoken` | `^1.0.20` | ቶከን አውጪ |
`@huggingface/transformers` በ`^4.2.0` ላይ ተቆልፏል (ከአካባቢያዊው embeddings ዱካ ጋር የሚጋራ እና
ወደ standalone bundleም የሚካተት)፤ `@atjsh/llmlingua-2@2.0.5` በ
`"^3.5.2 || ^4.0.0"` ላይ peer ጥገኝነት አለው፣ ስለዚህ ሁለቱም Transformers.js v3 እና v4 ይደገፋሉ። ከ2.0.4 ጀምሮ፣
`@atjsh/llmlingua-2` ከእንግዲህ `@tensorflow/tfjs`ን አይፈልግም፤ ይህም ከSLM stack ውስጥ ትልቁን ነጠላ
አስተዋጽኦ አድራጊ (TensorFlow.js) አስወግዷል። ከላይ ያሉት ሁለት ጥቅሎች ብቻ ሊከረከሙ የሚችሉ SLM
peers ናቸው። መደበኛ `npm install` (dev)፣ አማራጭ ጥገኞች ካልተወገዱ በስተቀር፣ አማራጭ stackን በራስ-ሰር ይጭናል።
**ለምን በፍላጎት ጊዜ፦** በnpm የታተመው ጥቅል፣ standalone bundle እና Docker image
መጠናቸውን አነስተኛ ለማድረግ እነዚህን deps **ሳያካትቱ** ይላካሉ። እነሱ በማይኖሩበት ጊዜ፣ የworker ጥገኝነት
በር (`@atjsh/llmlingua-2` resolve probe በ`worker.ts` ውስጥ) ይወድቃል እና ሞተሩ
**ያለምንም ድምፅ ክፍት ሆኖ ይቀጥላል** — LLMLinguaን መምረጥ ምንም ተግባር አይኖረውም (ጽሑፉ ሳይቀየር ይመለሳል፣
ምንም ስህተት አይመዘገብም)። በተከረከመ አካባቢ ውስጥ ለማግበር፣ አማራጭ stackን ይጫኑ፦
```bash
# በpackage.json optionalDependencies ውስጥ የተገለጹትን ስሪቶች ይጠቀሙ
npm install @atjsh/llmlingua-2@2.0.5 js-tiktoken
```
የ`@tensorflow/tfjs` መወገድ (2.0.4+) ከዚህ ቀደም አብዛኛውን የያዘውን ~800 MB
አስተዋጽኦ ያስወግዳል — የቀረው መጠን transformers.js + onnxruntime-node runtimes፣
በመጀመሪያ አጠቃቀም ጊዜ የሚወርደው TinyBERT ሞዴል (~57 MB) ጋር ነው (በnpm በኩል አይደለም)።
በእያንዳንዱ አካባቢ፦
- **Dev / `npm install`** — `--omit=optional` ካላስተላለፉ በስተቀር በራስ-ሰር ይጫናል
(ወይም `--no-optional`)። ምንም እርምጃ አያስፈልግም።
- **Global npm (`npm i -g omniroute`) / ራሱን የቻለ** — ከላይ ያለውን የመጫኛ ትዕዛዝ በተጫነው
package ማውጫ ውስጥ ያስኪዱ፣ ወይም አማራጭ dependenciesን ሳያስቀሩ እንደገና ይጫኑ።
- **Docker** — የመጫኛ ትዕዛዙን ከእሱ በተዘጋጀ የimage ንብርብር ውስጥ ያክሉ፤ የታተመው image
ሆን ተብሎ ቀለል ተደርጎ ይቀርባል።
- **VPS (PM2)** — በመተግበሪያው `node_modules` ውስጥ ይጫኑ፣ ከዚያም worker የgateን ሁኔታ
እንደገና እንዲፈትሽ ሂደቱን ዳግም ያስጀምሩ።
- **Raw Next standalone (`npm run build` → `.build/next/standalone/server.js`)** — የstandalone
trace workerንም ሆነ አማራጭ dependenciesን አያካትትም፤ ስለዚህ engine ያለማስጠንቀቂያ ክፍት ሆኖ ውድቀቱን ያልፋል። `scripts/build/colocate-standalone.mjs` ሁለቱንም (worker esbuild +
የአማራጭ dependency ሙሉ ስብስብን ወደ standalone tree) እንደገና ያክላል፤ ከእያንዳንዱ build በኋላ በ
`postbuild` npm hook በኩል በራስ-ሰር ይሰራል። ደጋግሞ ሲሰራ ተመሳሳይ ውጤት ያለው ሲሆን፣ dependencies ከሌሉ ችግር ሳያስከትል ያልፋል።
**ንቁ መሆኑን ያረጋግጡ:** LLMLingua ሲመረጥ እውነተኛ ጽሑፍ በትክክል ያጥራል (engine
ውድቀቱን ክፍት ሆኖ ማለፍ ያቆማል)፣ እና የመጀመሪያው ጥያቄ modelን ወደ
`${DATA_DIR}/models/llmlingua` እንዲወርድ ያደርጋል። gate ሆን ብሎ `@atjsh/llmlingua-2`ን ብቻ ይፈትሻል —
ሌሎቹ peers ESM-only ናቸው፣ እና በሚገኙበት ጊዜም `require.resolve` በእነሱ ላይ ስህተት ይጥላል — ስለዚህ
በ`import()` ጊዜ ከpeers መካከል አንዱ በእውነት ከጎደለ worker አሁንም ውድቀቱን ክፍት ሆኖ ያልፋል።
## የተደራረቡ ፓይፕላይኖች
የተደራረበ ሁነታ የፓይፕላይን ደረጃዎችን በቅደም ተከተል ያስኬዳል። ነባሪው፦
```txt
rtk -> caveman
```
አንድ መጠየቂያ የትዕዛዝ ውጤትን ከሰው ወይም ከረዳት ስድ ንባብ ጋር ለሚያጣምርባቸው የኮድ አዘጋጅ ወኪል ክፍለ ጊዜዎች ይህን ይጠቀሙ። RTK በመጀመሪያ ጫጫታ የበዛባቸውን የመሣሪያ ምዝግቦች ይቀንሳል፣ ከዚያም Caveman የቀረውን ተፈጥሯዊ ቋንቋ ይጨምቃል።
የፓይፕላይን ደረጃዎች በመጭመቂያ ቅንብሮች ውስጥ ባለው `stackedPipeline` ወይም በመጭመቂያ ጥምረቶች በኩል ይዋቀራሉ።
ሁለቱም ሞተሮች ተመሳሳዩን ብቁ የውሂብ ጭነት ሲቀንሱ፣ ቁጠባዎቹ ይደራረባሉ፦
```txt
combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
average = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
range = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```
## የMCP ተደራሽነት ዛፍ ማጣሪያ
የMCP ተደራሽነት ዛፍ ብልህ ማጣሪያ፣ በመጠየቂያዎች ወይም በዐውድ ላይ ሳይሆን በMCP **የመሣሪያ ውጤቶች** ላይ የሚሠራ ከአፈጻጸም በኋላ የሚተገበር የመጭመቂያ ንብርብር ነው። እንደ Playwright፣ computer-use እና browser-automation MCP አገልጋዮች ባሉ መሣሪያዎች የሚመለሱትን ዝርዝር የተደራሽነት ዛፍ እና የአሳሽ ቅጽበታዊ ምስል የውሂብ ጭነቶችን ያነጣጥራል።
### የሚያከናውነው
1. **ጫጫታን ማስወገድ** — ባዶ አጠቃላይ/የጽሑፍ ግቤቶችን (`- generic:`፣ `- text: ""`) ያስወግዳል
2. **ተመሳሳይ ደረጃ ያላቸውን ማጠቃለል** — ≥ `collapseThreshold` (ነባሪ 30) ተከታታይ መስመሮች የመዋቅር ድግግሞሾች ሲሆኑ፣ ወደ መጀመሪያዎቹ `collapseKeepHead` (ነባሪ 10) መስመሮች + የብዛት ማጠቃለያ + የመጨረሻዎቹ `collapseKeepTail` (ነባሪ 5) መስመሮች ያጠቃልላቸዋል
3. **የማጣቀሻ ጥበቃ** — በPlaywright/computer-use የሚፈለጉ `[ref=eXX]` መልሕቆች ፈጽሞ አይነኩም
4. **ጠንካራ መቁረጥ** — ጽሑፉ ከተጠቃለለ በኋላ አሁንም `maxTextChars`ን (ነባሪ 50,000) የሚያልፍ ከሆነ፣ ወኪሉ ሥራውን እንዲቀጥል በሚያስችል የዳሰሳ ፍንጭ ይቆርጠዋል
### የሞተሩ አካባቢ
```txt
open-sse/services/compression/engines/mcpAccessibility/
index.ts ← የsmartFilterText() መግቢያ ነጥብ
collapseRepeated.ts ← ተመሳሳይ ደረጃ ያላቸውን የማጠቃለል ስልተ ቀመር
constants.ts ← DEFAULT_MCP_ACCESSIBILITY_CONFIG
```
### ውቅር
በዓለም አቀፍ ቅንብሮች (ፍልሰት 056) ውስጥ ባለው `compression.mcpAccessibility` ይቆጣጠራል። ነባሪ ውቅር፦
```json
{
"enabled": true,
"maxTextChars": 50000,
"collapseThreshold": 30,
"collapseKeepHead": 10,
"collapseKeepTail": 5,
"minLengthToProcess": 2000
}
```
ማጣሪያው የሚተገበረው `type`ቸው `"text"` በሆነ እና ርዝመታቸው `minLengthToProcess`ን በሚያልፍ የመሣሪያ ውጤት የውሂብ ጭነቶች ላይ ብቻ ነው። የመጠየቂያ መጭመቂያን ወይም የጥያቄ የውሂብ ጭነቶችን አይነካም።
### የሚጠበቁ ቁጠባዎች
እንደ ገጹ ውስብስብነት፣ በአሳሽ ቅጽበታዊ ምስል መሣሪያ ውጤቶች ላይ 60–80%። የማጠቃለያ ስልተ ቀመሩ በመስመር ብዛት O(n) ሲሆን፣ እምብዛም የማይባል መዘግየት ይጨምራል።
### ይህ ማጣሪያ ከላይ ካሉት የመጭመቂያ ሞተሮች ጋር ሲነጻጸር
| ገጽታ | Caveman / RTK / Stacked | MCP ተደራሽነት ማጣሪያ |
| ----------- | ----------------------- | -------------------------------------- |
| ዒላማ | የጥያቄ መጠየቂያዎች / ዐውድ | የMCP መሣሪያ ውጤቶች |
| ቀስቃሽ | የመጭመቂያ ሁነታ ቅንብር | `compression.mcpAccessibility.enabled` |
| ወሰን | ሁሉም የSSE መልዕክቶች | የመሣሪያ ውጤቶች ብቻ |
| የማጣቀሻ መልሕቆች | አይመለከተውም | ያለምንም ቅድመ ሁኔታ የተጠበቁ |
---
## የጨመቃ ጥምረቶች
የጨመቃ ጥምረቶች ለማዘዋወሪያ ጥምረቶች ሊመደቡ የሚችሉ ስም ያላቸው የጨመቃ መገለጫዎች ናቸው፦
- `compression_combos`፦ ሁነታን፣ pipelineን፣ የRTK ውቅርን፣ የቋንቋ ውቅርን እና ነባሪ ምልክትን ያከማቻል
- `compression_combo_assignments`፦ የጨመቃ ጥምረትን ከማዘዋወሪያ ጥምረት ጋር ያዛምዳል
- የruntime ውህደቱ ከአጠቃላይ የጥምረት ሽረቶች በፊት የተመደበውን የጨመቃ ጥምረት ይፈታል
- analytics `compression_combo_id` እና `engine`ን ያካትታል
የDashboard መገኛ፦ `Dashboard -> Context & Cache -> Compression Combos`።
## የAPI በይነገጽ
| Route | ዓላማ |
| -------------------------------------- | -------------------------------------------------- |
| `/api/settings/compression` | ዓለም አቀፍ የጨመቃ ቅንብሮች (`mcpAccessibility` ውቅርን ያካትታል) |
| `/api/compression/preview` | ማንኛውንም የጨመቃ ሁነታ ቅድመ-እይታ ማድረግ |
| `/api/compression/language-packs` | የሚገኙ የCaveman ቋንቋ ጥቅሎችን መዘርዘር |
| `/api/context/caveman/config` | የCaveman ቅንብሮች ተለዋጭ ስም |
| `/api/context/rtk/config` | የRTK ነባሪዎች እና ቅንብሮች |
| `/api/context/rtk/filters` | የRTK ማጣሪያ ካታሎግ |
| `/api/context/rtk/test` | የRTK ቅድመ-እይታ/ሙከራ endpoint |
| `/api/context/rtk/raw-output/[id]` | ማንነት የተረጋገጠ፣ ሚስጥራዊ መረጃው የተሰወረ raw-output መልሶ ማግኘት |
| `/api/context/combos` | የጨመቃ ጥምረት CRUD |
| `/api/context/combos/[id]/assignments` | የማዘዋወሪያ ጥምረት ምደባ CRUD |
| `/api/context/analytics` | የጨመቃ analytics ተለዋጭ ስም |
የአስተዳደር routes የአስተዳደር ማንነት ማረጋገጫ ወይም የAPI-key ፖሊሲ ፍተሻዎችን ይፈልጋሉ።
## የMCP መሣሪያዎች
ጨመቃ አምስት የMCP መሣሪያዎችን ያቀርባል፦
| Tool | Scope | ዓላማ |
| ----------------------------------- | ------------------- | -------------------------------- |
| `omniroute_compression_status` | `read:compression` | ቅንብሮች፣ analytics፣ የcache ስታቲስቲክስ |
| `omniroute_compression_configure` | `write:compression` | ዓለም አቀፍ ቅንብሮችን ማዘመን |
| `omniroute_set_compression_engine` | `write:compression` | ሁነታን እና አማራጭ pipelineን ማዘጋጀት |
| `omniroute_list_compression_combos` | `read:compression` | የጨመቃ ጥምረቶችን መዘርዘር |
| `omniroute_compression_combo_stats` | `read:compression` | የጥምረት/engine analyticsን ማንበብ |
## ወሰን እና ማግለያዎች
**Embeddings በፍጹም አይጨመቁም።** `open-sse/handlers/embeddings.ts` ምንም
የጨመቃ engine አይጠራም — የrequest/response bodies ሳይነኩ በቀጥታ ወደ executor ያልፋሉ።
ይህ በአሁኑ ጊዜ መዋቅራዊ ነው (embeddings እና chat completions የተለያዩ handlers ናቸው)፣
የruntime ፍተሻ አይደለም፤ ነገር ግን ይህ በ#8034 ያለው የvector-distortion ስጋት
በembeddings path ውስጥ የተጋላጭነት መገኛ እንደሌለው ያሳያል።
**የእያንዳንዱ-model/endpoint ማግለያ ማጣሪያ (#8034)።** ለchat completions፣ operator
ፈጽሞ መጨመቅ የሌለባቸውን model ids / `provider/model` targets መጥቀስ ይችላል — ይህ
ወደፊት ጨመቃ ከembeddings አጠገብ ካለ path ጋር ይበልጥ በቅርብ ቢገናኝ ጠቃሚ የሆነ guardrail ሲሆን፣
ትክክለኛው byte-for-byte prompt አስፈላጊ ለሆነበት ማንኛውም model (deterministic evals፣ cache-sensitive
prefixes፣ ወዘተ) በአጠቃላይ ጠቃሚ ነው።
- የቅንብሮች field፦ በዓለም አቀፍ የጨመቃ config ላይ `exclusions?: string[]`
(`GET`/`PUT /api/settings/compression`)፣ ባለው `key_value` የጨመቃ
namespace (`src/lib/db/compression.ts`) በኩል ይቀመጣል — አዲስ table የለም።
- የDashboard tab፦ **Dashboard → Compression → Exclusions**
(`/dashboard/compression/exclusions`)።
- የpattern syntax፦ `*` ብቸኛው wildcard ነው። በpattern ውስጥ ያሉ ሌሎች ሁሉም regex metacharacters
ከማዛመድ በፊት escaped ይደረጋሉ፤ ስለዚህ `gpt-5.6` ከliteral string ጋር ብቻ ይዛመዳል፣
ከ`gpt-5x6` ጋር ፈጽሞ አይዛመድም (ReDoS-safe፣ bounded፣ nested quantifiers የሉም)። Patterns
ከbare model id እና ከ`provider/model` composite ሁለቱም ጋር case-insensitive በሆነ መንገድ
ይዛመዳሉ — `gpt-5-6`፣ `openai/gpt-5-6` እና `openai/*` ሁሉም ይሰራሉ፣ እንዲሁም `*`
ብቻውን ሁሉንም model ያገላል።
- ማዛመድ፦ `open-sse/services/compression/exclusions.ts` ውስጥ
`isCompressionExcluded()` / `normalizeCompressionExclusions()`። `chatCore.ts` የጨመቃ ቅንብሮችን
ከፈታ በኋላ፣ **ማንኛውም engine ከመስራቱ በፊት**፣ የተገለለውን target ይፈትሻል፣ እና ማዛመድን
ልክ ጨመቃ በዓለም አቀፍ ደረጃ disabled እንደሆነ ይይዘዋል — የrequest body በማስረጃ
byte-identical ነው። መዝለሉ ለanalytics ታይነት በ`writeCompressionSkip(..., "excluded")`
በኩል ይመዘገባል።
- ነባሪ (ባዶ/የሌለ list)፦ ከ#8034 በፊት ከነበረው behavior ጋር ተመሳሳይ ነው — ምንም ነገር አይገለልም።
## የታወቁ ገደቦች
- **LLMLingua-2 (SLM) አማራጭ ጥገኞች በአንድ ቦታ እንዲገኙ ይፈልጋል።** worker-ው በ
production build ውስጥ የሚሠራው `@atjsh/llmlingua-2` + peers ወደ
`dist/node_modules` በአንድ ቦታ ሲቀመጡ ብቻ ነው (`scripts/build/colocateOptionals.mjs`ን፣ #4286ን ይመልከቱ)። እነዚህ ከሌሉ
engine-ው በfail-open ሁኔታ ይሠራል (ዋናውን ጽሑፍ ይመልሳል)። የworker resolution ከእንግዲህ በ
`import.meta.url` ላይ አይመሠረትም (በstandalone bundle ውስጥ አይሠራም) — በruntime
cwd / `argv[1]` ላይ ይመሠረታል።
- **የCaveman ቋንቋ packs `de` / `fr` / `ja` ከፊል ናቸው።** `context` +
`filler` + `structural` ደንቦችን ይዘው ይመጣሉ፣ ነገር ግን `dedup` / `ultra` packs የላቸውም፤ ስለዚህ `ultra` intensity
ለእነዚያ ቋንቋዎች ከ`full` የበለጠ ጠንካራ አይደለም (የራሳቸውን ደንቦች ብቻ ይጠቀማሉ — የውጭ ቋንቋ ጽሑፍን ሊያበላሹ የሚችሉትን
የእንግሊዝኛ `dedup`/`ultra` ደንቦች በድብቅ አይጠቀሙም)።
`en` / `es` / `id` / `pt-BR` የተሟሉ ናቸው። ለከፊል packs የ`dedup.json` + `ultra.json`
አስተዋጽኦዎች በደስታ ይቀበላሉ።
- **የተደራረበ telemetry የሚዘረዝረው ጨመቃ ያከናወኑ enginesን ብቻ ነው።** engine-ው
የሠራበት ነገር ግን 0 % ቅነሳ ያስገኘው የstacked-pipeline ደረጃ `stats:null`ን ይመልሳል፣ ስለዚህም በ
`engineBreakdown` ውስጥ አይታይም — ከተዘለለ ደረጃ ለመለየት አይቻልም።
"ሠርቷል፣ 0 %"ን ከ"ተዘሏል" መለየት የbreakdown-model ለውጥን የሚፈልግ ሲሆን ለወደፊት ተላልፏል።
## ማረጋገጫ
ለዚህ ክፍል የተመረጡት gates እነዚህ ናቸው፦
```bash
node --import tsx/esm --test tests/unit/compression/rtk-*.test.ts tests/unit/compression/pipeline-integration.test.ts tests/unit/compression/context-compression-api.test.ts
node --import tsx/esm --test tests/unit/compression/*.test.ts tests/golden-set/*.test.ts tests/integration/compression-pipeline.test.ts tests/unit/api/compression/compression-api.test.ts
node --import tsx/esm --test tests/unit/compression/mcpAccessibility*.test.ts
npm run typecheck:core
```

581
docs/i18n/am/docs/compression/COMPRESSION_GUIDE.md Normal file
View File

@@ -0,0 +1,581 @@
# 🗜️ Prompt Compression Guide — OmniRoute (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../compression/COMPRESSION_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/compression/COMPRESSION_GUIDE.md) · 🇦🇿 [az](../../../az/docs/compression/COMPRESSION_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/compression/COMPRESSION_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/compression/COMPRESSION_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/compression/COMPRESSION_GUIDE.md) · 🇩🇰 [da](../../../da/docs/compression/COMPRESSION_GUIDE.md) · 🇩🇪 [de](../../../de/docs/compression/COMPRESSION_GUIDE.md) · 🇬🇷 [el](../../../el/docs/compression/COMPRESSION_GUIDE.md) · 🇪🇸 [es](../../../es/docs/compression/COMPRESSION_GUIDE.md) · 🇪🇪 [et](../../../et/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/compression/COMPRESSION_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/compression/COMPRESSION_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/compression/COMPRESSION_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇱 [he](../../../he/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/compression/COMPRESSION_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/compression/COMPRESSION_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/compression/COMPRESSION_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇩 [id](../../../id/docs/compression/COMPRESSION_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇹 [it](../../../it/docs/compression/COMPRESSION_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/compression/COMPRESSION_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/compression/COMPRESSION_GUIDE.md) · 🇰🇭 [km](../../../km/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/compression/COMPRESSION_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/compression/COMPRESSION_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/compression/COMPRESSION_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/compression/COMPRESSION_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/compression/COMPRESSION_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/compression/COMPRESSION_GUIDE.md) · 🇲🇲 [my](../../../my/docs/compression/COMPRESSION_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/compression/COMPRESSION_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/compression/COMPRESSION_GUIDE.md) · 🇳🇴 [no](../../../no/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [or](../../../or/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/compression/COMPRESSION_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/compression/COMPRESSION_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/compression/COMPRESSION_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/compression/COMPRESSION_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/COMPRESSION_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/compression/COMPRESSION_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/compression/COMPRESSION_GUIDE.md) · 🇱🇰 [si](../../../si/docs/compression/COMPRESSION_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/compression/COMPRESSION_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/compression/COMPRESSION_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/compression/COMPRESSION_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/compression/COMPRESSION_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/compression/COMPRESSION_GUIDE.md) · 🇮🇳 [te](../../../te/docs/compression/COMPRESSION_GUIDE.md) · 🇹🇭 [th](../../../th/docs/compression/COMPRESSION_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/compression/COMPRESSION_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/COMPRESSION_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/compression/COMPRESSION_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/compression/COMPRESSION_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/compression/COMPRESSION_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/compression/COMPRESSION_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/COMPRESSION_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/COMPRESSION_GUIDE.md)
---
> ብቁ በሆነ ኮንቴክስት ላይ 15-95% በራስ-ሰር ይቆጥቡ። ለፈጣን አጠቃላይ እይታ፣ የ[README የማመቅ ክፍልን](../README.md#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically) ይመልከቱ።
## አጠቃላይ እይታ
OmniRoute ጥያቄዎች ወደ upstream አቅራቢዎች ከመድረሳቸው በፊት **አስቀድሞ** የሚሠራ ሞዱላር የፕሮምፕት ማመቂያ pipeline ይተገብራል። ይህም የቶከን ቁጠባዎ በማይታይ ሁኔታ እንዲከናወን ያደርጋል — በየዕለት የሥራ ሂደትዎ ላይ ምንም ለውጥ አያስፈልግም።
```
የደንበኛ ጥያቄ
→ የማመቂያ ስልት መራጭ
→ Combo ማሻሻያ አለ? → የcombo ቅንብሩን ተጠቀም
→ የራስ-ሰር ማስጀመሪያ ገደብ ደርሷል? → ራስ-ሰር ሁነታን ተጠቀም
→ ነባሪ ሁነታ? → አጠቃላይ ቅንብሩን ተጠቀም
→ ጠፍቷል? → ማመቅን ዝለል
→ የተመረጠው የማመቂያ ሁነታ
→ ጠፍቷል፦ ምንም ማመቅ የለም
→ Lite፦ አስተማማኝ የክፍተት/ቅርጸት ማጽዳት (~15%)
→ Standard፦ የቀላል-ንግግር ትርፍ ቃላትን ማስወገድ (~30%)
→ Aggressive፦ የታሪክ ማርጀት + ማጠቃለል (~50%)
→ Ultra፦ ሂዩሪስቲክ መመንጠር + የኮድ ብሎክ ማቅጠን (~75%)
→ RTK፦ ትዕዛዝን የሚገነዘብ የተርሚናል/መሣሪያ-ውጤት ማጣሪያ (60-90% upstream ክልል)
→ Stacked፦ በቅደም ተከተል የሚሠራ ባለብዙ-engine pipeline፣ ብዙውን ጊዜ RTK ከዚያ Caveman (78-95% ብቁ ክልል)
→ የታመቀ ጥያቄ → አቅራቢ
```
---
## የማመቂያ ሁነታዎች
### Off
ምንም ማመቅ አይተገበርም። ሁሉም መልዕክቶች ሳይለወጡ ያልፋሉ።
### Lite ሁነታ (~15% ቁጠባ፣ <1ms መዘግየት)
በጣም አስተማማኙ ሁነታ — ምንም የፍቺ ለውጥ የለም፣ የቅርጸት ማጽዳት ብቻ፦
| ቴክኒክ | መግለጫ |
| ------------------------ | ------------------------------------------ |
| `collapseWhitespace` | ተከታታይ ባዶ መስመሮችንና በመስመር መጨረሻ ያሉ ክፍተቶችን አዋህድ |
| `dedupSystemPrompt` | የተባዙ የsystem መልዕክቶችን አስወግድ |
| `compressToolResults` | ዝርዝር የtool/function ውጤቶችን አምቅ |
| `removeRedundantContent` | የተደጋገሙ መመሪያዎችን አስወግድ |
| `replaceImageUrls` | የbase64 ምስል ውሂብ URIዎችን አሳጥር |
**ለሚከተለው ይመከራል፦** ሁልጊዜ በርቶ የሚቆይ አጠቃቀም፣ ደህንነት-ወሳኝ የሥራ ሂደቶች።
### Standard ሁነታ (~30% ቁጠባ)
በ[Caveman](https://github.com/JuliusBrussee/caveman) የተነሳሳ — ትርጉሙን በመጠበቅ ትርፍ ቃላትንና ረዥም አገላለጾችን ያስወግዳል፦
- ትርፍ ቃላትን ("እባክዎ", "እኔ እንደማስበው", "በመሠረቱ", "በእርግጥ") ያስወግዳል
- ረዥም ሐረጎችን ያሳጥራል ("ለማድረግ ሲባል" → "ለማድረግ"፣ "በዚህ ምክንያት" → "ምክንያቱም")
- ጨዋነት የተሞላባቸውን አገላለጾች ያስወግዳል ("ቢያደርጉ ይቸግርዎታል...", "ከቻሉ...")
- ለኮዲንግ ፕሮምፕቶች የተስተካከሉ ከ30 በላይ የregex ደንቦች
**ለሚከተለው ይመከራል፦** ዕለታዊ የኮዲንግ የሥራ ሂደቶች፣ ወጪን የሚያገናዝቡ ቡድኖች።
### Aggressive ሁነታ (~50% ቁጠባ)
ለረጅም ክፍለ ጊዜዎች ብልህ የታሪክ አስተዳደር፦
- **የመልዕክት ማርጀት** — የቆዩ መልዕክቶች ቀስ በቀስ የበለጠ ይታመቃሉ
- **የመሣሪያ ውጤት ማጠቃለያ** — ረዥም የመሣሪያ ውጤቶች በማጠቃለያዎች ይተካሉ
- **የመዋቅራዊ ወጥነት ጥበቃዎች** — የ`tool_use` + `tool_result` ጥንዶች ወጥነታቸውን እንዲጠብቁ ያረጋግጣል
- **የኮንቴክስት መስኮት ግንዛቤ** — የእያንዳንዱን model የቶከን ገደቦች ያከብራል
**ለሚከተለው ይመከራል፦** የተራዘሙ የስህተት ማረም ክፍለ ጊዜዎች፣ ትላልቅ የኮድ ማከማቻዎች።
### Ultra ሁነታ (~75% ቁጠባ)
ቶከን ወሳኝ ለሆነባቸው ሁኔታዎች ከፍተኛ ማመቅ፦
- **ሂዩሪስቲክ መመንጠር** — ከአግባብነት ገደቡ በታች ያሉ መልዕክቶችን ያስወግዳል
- **የኮድ ብሎክ ማቅጠን** — ተደጋጋሚ የኮድ ምሳሌዎችን ያመቃል
- **የሁለትዮሽ ፍለጋ መቁረጥ** — ለኮንቴክስት መስኮቱ ምርጥ የመቁረጫ ነጥብን ያገኛል
- ሁሉም የAggressive ሁነታ ባህሪያት ተካትተዋል
**ለሚከተለው ይመከራል፦** የኮንቴክስት ገደቦችን በተደጋጋሚ ሲደርሱ።
### RTK ሁነታ (60-90% upstream ክልል)
RTK ሁነታ በኮዲንግ-agent ክፍለ ጊዜዎች ውስጥ ለሚታዩ ዝርዝር የመሣሪያ ውጤቶች የተመቻቸ ነው፦
- እንደ `git status`፣ `git diff`፣ `git log`፣ የፈተና አስኪያጆች፣
TypeScript/Vite/Webpack ግንባታዎች፣ ESLint/Biome/Prettier፣ npm ኦዲት/ጭነቶች፣ Docker ሎጎች፣ የinfra
ውጤት እና አጠቃላይ የshell ውጤት ያሉ የትዕዛዝ/ውጤት ምድቦችን ይለያል
- ከ`open-sse/services/compression/engines/rtk/filters/` የJSON ማጣሪያ ጥቅሎችን ይተገብራል
- ከፕሮጀክት ወይም ከአጠቃላይ `filters.toml` ፋይሎች የRTK TOML schema v1 ማጣሪያዎችን ያስመጣል፤ የinline-test
ማረጋገጫ እና ለፕሮጀክት ፋይሎች በእምነት ላይ የተመሠረተ መቆጣጠሪያ አለው
- 49 አብሮገነብ ማጣሪያዎችን ከinline የማረጋገጫ ናሙናዎች ጋር ይዟል
- የANSI መቆጣጠሪያ ቅደም ተከተሎችን፣ የሂደት አሞሌዎችን፣ የተደጋገሙ መስመሮችን እና እርምጃ የማይወሰድባቸውን ድምፆች ያስወግዳል
- ውድቀቶችን፣ ስህተቶችን፣ ማስጠንቀቂያዎችን፣ የተለወጡ ፋይሎችን፣ ማጠቃለያዎችን እና የረዥም ውጤትን የመጨረሻ ክፍል ይጠብቃል
- በእምነት ላይ የተመሠረቱ የፕሮጀክት ማጣሪያዎችን፣ አጠቃላይ ማጣሪያዎችን እና አማራጭ የተደበቀ ጥሬ-ውጤት መልሶ ማግኘትን ይደግፋል
**ለሚከተለው ይመከራል፦** shell፣ build፣ test፣ git፣ grep እና የፋይል-ውጤት ቃለ ጉባኤዎችን የያዙ የagent ክፍለ ጊዜዎች።
### Stacked ሁነታ (78-95% ብቁ ክልል)
Stacked ሁነታ በተወሰነ ቅደም ተከተል በርካታ የማመቂያ engineዎችን ያስኬዳል። ነባሪው pipeline፦
```txt
RTK -> Caveman
```
ይህ ቅደም ተከተል በመጀመሪያ የተርሚናል/መሣሪያ ውጤትን የታመቀ አድርጎ ያቆያል፤ ከዚያም በቀረው የተፈጥሮ ቋንቋ ፕሮምፕት ላይ የCaveman የፍቺ ማጠርን ይተገብራል። Stacked pipelines በአጠቃላይ ወይም ለrouting combos በተመደቡ የማመቂያ combos በኩል ሊዋቀሩ ይችላሉ።
**ለሚከተለው ይመከራል፦** ትላልቅ የመሣሪያ ሎጎችን ከሰው መመሪያዎች ወይም ከassistant ማጠቃለያዎች ጋር ለያዘ ድብልቅ ኮንቴክስት።
---
## የላይኛው ምንጭ ቁጠባ ስሌት
OmniRoute የመጭመቂያ ቁጠባን ከሁለት ምንጮች ይመዘግባል፦ የላይኛው ምንጭ ፕሮጀክት የአፈጻጸም መለኪያዎች እና
የOmniRoute የራሱ የኤንጂን ጥምረት።
| ምንጭ | እዚህ ጥቅም ላይ የዋለው የላይኛው ምንጭ README ቁጥር |
| ------- | --------------------------------------------------------------------------------------------- |
| Caveman | `~75%` ያነሱ የውጤት ቶከኖች፣ `65%` የአፈጻጸም መለኪያ አማካይ የውጤት ቁጠባ፣ `22-87%` ክልል እና `~46%` የግቤት መጭመቂያ መሣሪያ |
| RTK | `60-90%` የትዕዛዝ ውጤት ቁጠባ፤ የናሙና ክፍለ ጊዜ `~118,000 -> ~23,900` ቶከኖች፣ ወይም `79.7%` ቁጠባ (`~80%`) |
እርስ በርስ ለሚደራረቡ የመሣሪያ/ዐውድ ውሂቦች፣ ነባሪው የOmniRoute ጥምረት ኤንጂኖቹን በተከታታይ ያዋህዳል፦
```txt
RTK -> Caveman
```
ጥምር ቁጠባው በማባዛት የሚሰላ እንጂ በመደመር አይደለም፦
```txt
combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
average = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
range = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```
ያ `78-95%` ቁጥር RTK እና Caveman ሁለቱም ተመሳሳዩን የግቤት/ዐውድ ውሂብ መቀነስ ሲችሉ ተፈጻሚ ይሆናል።
የCaveman የምላሽ ውጤት ሁነታ የተለየ ነው፦ ሲነቃ የCavemanን የራሱ የውጤት ቁጠባዎች (`65%`
አማካይ፣ `~75%` ዋና አኃዝ፣ `22-87%` ክልል) ይጠቀሙ። አጠቃላይ የክፍያ ቁጠባው በጥያቄ/ውጤት ቅይጥዎ ላይ ይወሰናል።
### "ብቁ" ማለት በትክክል ምን ማለት ነው
የ15-95% ዋና ክልል ትክክለኛ ነው፣ ነገር ግን ተፈጻሚ የሚሆነው **ለተደጋገመ ወይም ከመጠን በላይ ዝርዝር** ይዘት ብቻ ነው — ተደጋጋሚ
የስህተት መስመሮች፣ ተመሳሳዩን ማስጠንቀቂያ ደጋግሞ የሚያወጣ የግንባታ ምዝግብ፣ ከመጠን ያለፈ `grep`/የፋይል-ንባብ ውጤት። ይህ
እያንዳንዱ ጥያቄ ያን ያህል ቁጠባ ያስገኛል ማለት **አይደለም**።
በተግባር ተረጋግጧል (`tests/unit/compression/stacked-compression-tool-result-savings.test.ts`)፦ 300 ተመሳሳይ
የስህተት መስመሮችን የያዘ የAnthropic-ቅርጽ `tool_result` ብሎክ ላይ የተካሄደ `stacked` (RTK + Caveman) ሂደት
**95.93% የቶከን ቁጠባ / 96.26% የቁምፊ ቁጠባ** አስገኝቷል — ይህም በታወጀው
ክልል ውስጥ በትክክል ይገኛል። ሆኖም ተመሳሳዩ ሂደት በመደበኛ፣ ያልተደጋገመ የመሣሪያ ውጤት (ንጹህ የ`grep` ተዛማጅ ዝርዝር፣
አጭር የፋይል ንባብ፣ መደበኛ የውይይት ጽሑፍ) ላይ ሲካሄድ **ወደ ዜሮ የቀረበ ቁጠባ** በትክክል ያስገኛል፤ ምክንያቱም
የሚወገድ ተደጋጋሚ ነገር የለም፣ እና `validateCompression()` (`validation.ts`) የኮድ ብሎኮችን፣ URLs፣ ርዕሶችን፣ ስሪቶችን ወይም ሁሉም-በአቢይ-ፊደል የተጻፉ ቋሚ ለዪዎችን የሚያስወግድ ወይም የሚቀይር
ዳግም ጽሑፍ እንዳይላክ ይከለክላል።
ይህ የሚጠበቅ እና ደህንነቱ የተጠበቀ ባህሪ ነው፣ ሳንካ አይደለም፦ በአብዛኛው ንጹህ ፋይሎችን የሚያነብ/በ`grep` የሚፈልግ የኮድ አጻጻፍ ክፍለ ጊዜ
መጭመቂያው ሙሉ በሙሉ ቢነቃም መጠነኛ አጠቃላይ ቁጠባ ያሳያል፤ የከሸፈ
ዙር ወይም ብዙ ውጤት የሚያወጣ linter ያጋጠመው ክፍለ ጊዜ ግን በዚያ ትራፊክ ላይ ሙሉውን የ78-95% ክልል ያሳያል። የአንድን ክፍለ ጊዜ
ዝቅተኛ ድምር የቁጠባ መቶኛ መጭመቂያው በስህተት እንደተዋቀረ ማስረጃ አድርገው አይጠቀሙ — በመጀመሪያ ዋናው
የመሣሪያ ውጤት በእርግጥ ተደጋጋሚ እንደነበር ያረጋግጡ።
---
## የቶከን ቁጠባ ምስላዊ ማሳያ
```
ያለ መጭመቂያ፦ 47K ቶከኖች ወደ LLM ተልከዋል
በLite፦ 40K ቶከኖች ተልከዋል (15% ተቆጥቧል — ደህንነቱ የተጠበቀ፣ ሁልጊዜ የነቃ)
በStandard፦ 33K ቶከኖች ተልከዋል (30% ተቆጥቧል — የcaveman-speak ደንቦች)
በAggressive፦ 24K ቶከኖች ተልከዋል (50% ተቆጥቧል — ማርጀት + ማጠቃለያ)
በUltra፦ 12K ቶከኖች ተልከዋል (75% ተቆጥቧል — ሂዩሪስቲክ ማስወገድ)
በRTK፦ 19K-5K ቶከኖች ተልከዋል (በትዕዛዝ/መሣሪያ ውጤት ላይ 60-90% ተቆጥቧል)
በStacked፦ 10K-2.5K ቶከኖች ተልከዋል (ብቁ የRTK+Caveman ክልል 78-95%)
```
---
## ውቅር
### ዳሽቦርድ
ወደ `Dashboard → Context & Cache` ይሂዱ፦
- **Caveman** — የሁነታ ምርጫ፣ የቋንቋ ጥቅሎች፣ ቅድመ-እይታ እና ዓለም አቀፍ ነባሪዎች
- **RTK** — የትዕዛዝ-ማጣሪያ ቅድመ-እይታ፣ የRTK ደህንነት ቅንብሮች እና የማጣሪያ ካታሎግ
- **Compression Combos** — ለማዘዋወሪያ ጥምረቶች የተመደቡ ስም ያላቸው የሞተር ቧንቧ መስመሮች
- **Auto-Trigger Threshold** — የቶከን ብዛት ከገደቡ ሲያልፍ መጭመቅን በራስ-ሰር ያስጀምራል
### የየጥምረቱ መሻሪያ
በ`Dashboard → Context & Cache → Compression Combos` ውስጥ ለአንድ የማዘዋወሪያ ጥምረት የመጭመቂያ ጥምረት ይመድቡ፦
```txt
ጥምረት: "free-tier-fallback"
የመጭመቂያ ጥምረት: "coding-agent-stack"
የቧንቧ መስመር: RTK -> Caveman
ኢላማዎች:
1. if/kimi-k2.7-code
2. if/qwen3.8-max-preview
```
ይህ፣ በሚከፈልባቸው የደንበኝነት ምዝገባዎች ላይ ቀላል ሁነታን እንደያዙ፣ በነፃ/የኮድ አቅራቢዎች ላይ ተደራራቢ መጭመቅን እንዲጠቀሙ ያስችልዎታል።
ይህ የ"የየጥምረቱ መሻሪያ" ምደባ ከ**የማዘዋወሪያ-ጥምረት መጭመቂያ ሁነታ** መሻሪያ (Default/Off/Lite/Standard/Aggressive/Ultra) የተለየ መቆጣጠሪያ ነው — ያ መሻሪያ ስም ያለውን የመጭመቂያ-ጥምረት ቧንቧ መስመር አይመርጥም፤ በ`resolveCompressionPlan` የሚመከረውን `compressionMode` መስክ ብቻ ያዘጋጃል። ይህን በጥምረቱ ካርድ (`Dashboard → Combos`) ላይ ወይም፣ ከ#6760 ጀምሮ፣ ከላይ ከተመዘገበው የቧንቧ መስመር ምደባ ምልክት ሳጥን አጠገብ በ`Dashboard → Context & Cache → Compression Combos` ውስጥ ባለው የ"Assign to routing" ዝርዝር ላይ ለእያንዳንዱ የማዘዋወሪያ ጥምረት ማዘጋጀት ይቻላል። ሁለቱም በይነገጾች በተመሳሳዩ `PUT /api/combos/{id}` መጨረሻ ነጥብ በኩል ውቅሩን ያስቀምጣሉ።
### የየጥያቄው መሻሪያ
ለአንድ ጥያቄ ብቻ የመጭመቂያ ዕቅዱን ለመሻር የ`x-omniroute-compression` ጥያቄ ራስጌን ይላኩ። ይህ ከፍተኛው ቅድሚያ አለው — የማዘዋወሪያ-ጥምረት መሻሪያን፣ ንቁውን መገለጫ፣ ራስ-ሰር ማስጀመሪያን እና የፓነሉን Default ይበልጣል። ያልታወቁ እሴቶች ችላ ይባላሉ (ጥያቄው ፈጽሞ ውድቅ አይደረግም)፣ እና ዓለም አቀፉ ዋና ማብሪያ አሁንም ሁሉንም ነገር ይቆጣጠራል፦ መጭመቅ በዓለም አቀፍ ደረጃ ጠፍቶ ሲሆን ራስጌው ሊያበራው አይችልም። እሴቶች፦
| እሴት | ውጤት |
| ------------- | -------------------------------------------------------- |
| `off` | ለዚህ ጥያቄ ምንም መጭመቅ የለም። |
| `default` | ከፓነሉ የተገኘው Default መገለጫ (ንቁውን መገለጫ ችላ ይላል)። |
| `engine:<id>` | ሲነቃ አንድ ነጠላ ሞተር፣ ለምሳሌ `engine:rtk`። |
| `<combo>` | በመጀመሪያ በስም (የፊደል መጠንን ሳይለይ)፣ ከዚያም በid የሚዛመድ ስም ያለው ጥምረት። |
የተተገበረው ዕቅድ በ`X-OmniRoute-Compression: <mode>; source=<source>` ምላሽ ራስጌ ውስጥ ተመልሶ ይታያል፤ በዚህም `<source>` ከ`request-header`፣ `routing-override`፣ `active-profile`፣ `auto-trigger`፣ `default` ወይም `off` አንዱ ነው።
### API
```bash
# የመጭመቂያ ቅንብሮችን ያግኙ
curl http://localhost:20128/api/settings/compression
# የመጭመቂያ ቅንብሮችን ያዘምኑ
curl -X PUT http://localhost:20128/api/settings/compression \
-H "Content-Type: application/json" \
-d '{"defaultMode":"stacked","autoTriggerMode":"stacked","autoTriggerTokens":32000}'
# የተወሰነ RTK/stacked payload ቅድመ-እይታ
curl -X POST http://localhost:20128/api/compression/preview \
-H "Content-Type: application/json" \
-d '{"mode":"rtk","messages":[{"role":"tool","content":"npm test output here"}]}'
# የRTK ማጣሪያ ጥቅሎችን ዘርዝሩ
curl http://localhost:20128/api/context/rtk/filters
# ከአማራጭ የትዕዛዝ ሜታዳታ ጋር RTKን በቀጥታ ይፈትሹ
curl -X POST http://localhost:20128/api/context/rtk/test \
-H "Content-Type: application/json" \
-d '{"command":"npm test","text":"FAIL tests/example.test.ts\nError: boom"}'
```
---
## ምን ይጠበቃል
የማመቂያ ሞተሩ **ሁልጊዜ የሚከተሉትን ይጠብቃል፦**
- ✅ የኮድ ብሎኮች (የታጠሩ እና በመስመር ውስጥ ያሉ)
- ✅ URLs እና የፋይል ዱካዎች
- ✅ JSON መዋቅሮች እና የተዋቀረ ውሂብ
- ✅ መለያዎች እና የተጠበቁ ቴክኒካዊ ቶከኖች
- ✅ የሒሳብ አገላለጾች
- ✅ የመሣሪያ/ፈንክሽን ጥሪ ትርጓሜዎች
- ✅ የስርዓት መመሪያዎች (በlite ሁነታ)
የRTK ጥሬ-ውጤት መልሶ ማግኛ ማንኛውም ነገር ከመቀመጡ በፊት የተለመዱ API ቁልፎችን፣ bearer ቶከኖችን፣ Slack ቶከኖችን፣ AWS የመዳረሻ ቁልፎችን፣
የይለፍ ቃሎችን፣ ቶከኖችን እና ሚስጥሮችን ይሸፍናል።
---
## የማመቂያ ስታቲስቲክስ
እያንዳንዱ የታመቀ ጥያቄ በአገልጋይ ሎጎች ውስጥ ስታቲስቲክስን ያካትታል፦
```json
{
"originalTokens": 47200,
"compressedTokens": 40120,
"savingsPercent": 15.0,
"techniquesUsed": ["collapseWhitespace", "dedupSystemPrompt"],
"mode": "lite",
"engine": "caveman",
"compressionComboId": "coding-agent-stack",
"durationMs": 0.8,
"rtkRawOutputPointers": []
}
```
---
## የደረጃዎች ፍኖተ ካርታ
| ደረጃ | ሁነታዎች | ሁኔታ |
| ------ | ----------------------------------------------------------------------------------------------------------------------- | ------- |
| ደረጃ 1 | Off, Lite | ✅ ተለቋል |
| ደረጃ 2 | Standard, Aggressive, Ultra | ✅ ተለቋል |
| ደረጃ 3 | RTK, Stacked, Compression Combos | ✅ ተለቋል |
| ደረጃ 4 | Output Styles, SLM-tier Ultra, eval harness | ✅ ተለቋል |
| ደረጃ 4C | ተስማሚ የአውድ-በጀት ("dial") — የስሌት ሞተር + API (`contextBudget` በ`PUT /api/settings/compression` ላይ) + የዳሽቦርድ ሁነታ/ፖሊሲ መቆጣጠሪያዎች | ✅ ተለቋል |
---
## ምስጋናዎች
የStandard ሁነታ የማመቂያ ደንቦች በ**[JuliusBrussee](https://github.com/JuliusBrussee)** ከተሠራው **[Caveman](https://github.com/JuliusBrussee/caveman)** (⭐ 51K+) — በስፋት ከተሰራጨው "ጥቂት ቶከን ሥራውን ሲያከናውን ለምን ብዙ ቶከን ይጠቀማሉ" ፕሮጀክት — ተነሳስተዋል። Caveman `~75%` ያነሱ የውጤት ቶከኖች፣ በቤንችማርክ አማካይ `65%` የውጤት ቁጠባ፣ `22-87%` የውጤት ክልል እና `~46%` የግቤት-ማመቂያ መሣሪያ እንዳለው ዘግቧል።
የRTK ሁነታ በ**[RTK AI](https://github.com/rtk-ai)** ከተሠራው **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** — ለተርሚናል፣ build፣ test፣ git እና የመሣሪያ-ውጤት ማጣሪያ የተዘጋጀው ከፍተኛ አፈጻጸም ያለው የትዕዛዝ-ውጤት ማመቂያ ፕሮጀክት — ተነሳስቷል። RTK `60-90%` ቁጠባ እንዳለው ዘግቧል፣ በREADME ውስጥ ያለው የናሙና ክፍለ ጊዜም `~80%` መቆጠቡን ያሳያል።
---
## የላቁ የማመቂያ ስርዓቶች
ከ7ቱ መደበኛ ሁነታዎች በተጨማሪ፣ OmniRoute በአውድ ላይ ተመስርተው በራስ-ሰር
የሚሠሩ በርካታ የላቁ የማመቂያ ስርዓቶችን ያካትታል።
### መሸጎጫን ያገናዘበ ማመቂያ
አንዳንድ አቅራቢዎች (ለምሳሌ Anthropic ከprompt caching ጋር) **prompt caching**ን ይደግፋሉ፤
ይህም ወጪን እና መዘግየትን ለመቀነስ የመመሪያውን ክፍሎች በመሸጎጫ እንዲያስቀምጡ ያስችላቸዋል። መሸጎጫ
ሲነቃ፣ ኃይለኛ ማመቂያ የተሸጎጡትን ቶከኖች በመቀየር መሸጎጫውን ስለሚያሳጣ፣ አፈጻጸሙን በእርግጥ **ሊጎዳ** ይችላል።
የ`cachingAware.ts` ሞጁል **የመሸጎጫ አውድን በመለየት** እና
በዚሁ መሠረት **የማመቂያ ስልቱን በማስተካከል** ይህን ችግኝ ይፈታል።
#### እንዴት እንደሚሠራ
1. **የመሸጎጫ አውድን ይለያል** — የጥያቄውን body ለ`cache_control` ምልክቶች ይቃኛል
2. **የመሸጎጫ አቅራቢዎችን ይለያል** — ዒላማው አቅራቢ መሸጎጥን ይደግፍ እንደሆነ ያረጋግጣል
3. **ስልቱን ያስተካክላል** — ለመሸጎጫ አቅራቢዎች `aggressive`/`ultra`ን ወደ `standard` ዝቅ ያደርጋል
4. **የስርዓት መመሪያውን ይዘላል** — የስርዓት መመሪያዎች አብዛኛውን ጊዜ ይሸጎጣሉ፣ ስለዚህ አያምቃቸው
5. **ቆራጥ ለውጦችን ይጠቀማል** — ወጥ የሆነ ውጤት የሚያመነጩ ለውጦችን ብቻ ይጠቀማል
#### የኮድ ምሳሌ
```ts
import {
detectCachingContext,
getCacheAwareStrategy,
} from "@omniroute/open-sse/services/compression/cachingAware";
const body = {
model: "anthropic/claude-sonnet-4.5",
messages: [{ role: "user", content: "Hello" }],
cache_control: { type: "ephemeral" }, // ← የመሸጎጫ ምልክት
};
const ctx = detectCachingContext(body, { provider: "anthropic" });
// → { hasCacheControl: true, provider: "anthropic", isCachingProvider: true }
const strategy = getCacheAwareStrategy("aggressive", ctx);
// → { strategy: "standard", skipSystemPrompt: true, deterministicOnly: true }
```
#### መቼ መጠቀም እንዳለብዎ
መሸጎጫን ያገናዘበ ማመቂያ **ሁልጊዜ ንቁ ነው** — ምንም ውቅር አያስፈልግም። የሚጀምረው
የሚከተሉት ሲሟሉ ብቻ ነው፦
- ጥያቄው `cache_control` ምልክቶች ሲኖሩት
- ዒላማው አቅራቢ prompt cachingን ሲደግፍ (Anthropic፣ OpenAI፣ ወዘተ)
### ተራማጅ እርጅና
ረጅም ውይይቶች ብዙ የመልዕክት ተራዎችን ያከማቻሉ፣ ነገር ግን የቆዩ ተራዎች ከጊዜ ወደ ጊዜ
አግባብነታቸው ይቀንሳል። የ`progressiveAging.ts` ሞጁል **መልዕክቶችን በተራ ርቀት መሠረት በደረጃ ይቀንሳል**፦
- **የቅርብ ተራዎች (0-3)**፦ ቃል በቃል ይቀመጣሉ (ሙሉ ዝርዝር)
- **መካከለኛ ተራዎች (4-8)**፦ Lite ማመቂያ (ነጭ ቦታ፣ የቅርጸት ማጽዳት)
- **የቆዩ ተራዎች (9+)**፦ Caveman ማመቂያ (ማሟያ ቃላትን ማስወገድ፣ ማጠቃለል)
- **በጣም የቆዩ ተራዎች (20+)**፦ በከፍተኛ ደረጃ ይጠቃለላሉ ወይም ይወገዳሉ
#### የኮድ ምሳሌ
```ts
import { applyAging } from "@omniroute/open-sse/services/compression/progressiveAging";
const messages = [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is 2+2?" },
{ role: "assistant", content: "4" },
// ... 50 ተጨማሪ ተራዎች ...
];
const { messages: aged, saved } = applyAging(messages, {
verbatim: 3, // የመጀመሪያዎቹ 3 ተራዎች፦ ቃል በቃል
light: 8, // ተራዎች 4-8፦ Lite ማመቂያ
moderate: 20, // ተራዎች 9-20፦ Caveman ማመቂያ
// ተራዎች 21+፦ ከፍተኛ ማጠቃለያ
});
// saved = የተቆጠቡ ቶከኖች ብዛት
```
#### መቼ መጠቀም እንዳለብዎ
ተራማጅ ማርጀት ለ`aggressive` እና `ultra` ሁነታዎች **ሁልጊዜ እንደነቃ ነው**። በተለይ
ለሚከተሉት ውጤታማ ነው፦
- ለረጅም ጊዜ የሚቆዩ የኮድ ጽሑፍ ክፍለ-ጊዜዎች
- ለብዙ ቀናት የሚቆዩ ውይይቶች
- ብዙ የመሣሪያ ጥሪዎች ያሏቸው ወኪላዊ የሥራ ፍሰቶች
### የCaveman ውጤት ሁነታ
የ`outputMode.ts` ሞጁል ሞዴሉ ራሱ የታመቀና አጭር ውጤት (“የዋሻ ሰው” ዘይቤ)
እንዲያወጣ **የስርዓት ፕሮምፕት መመሪያዎችን** ያስገባል።
#### እንዴት እንደሚሠራ
ግቤቱን ከመጭመቅ ይልቅ፣ ይህ ሁነታ እንደሚከተለው ያለ የስርዓት ፕሮምፕት ያክላል፦
> "በትንሹ ቃላት መልስ። የጨዋነት ሐረጎችን ዝለል። አጭር ዓረፍተ ነገሮችን ተጠቀም።"
ይህ በተለይ ለሚከተሉት ጥሩ ውጤት ይሰጣል፦
- ኮድ ማመንጨት (አጭር ውጤት = ያነሱ ቶከኖች)
- ፈጣን ጥያቄና መልስ (ዝርዝር ማብራሪያ አያስፈልግም)
- ባች ማቀናበር (የማስኬድ አቅምን ከፍ ማድረግ)
#### መቼ መጠቀም እንዳለብዎት
የCaveman ውጤት ሁነታ **በምርጫ የሚነቃ** ነው — በጥምር ውቅሩ በኩል ያቀናብሩት፦
```json
{
"strategy": "auto",
"config": {
"auto": {
"outputMode": "caveman"
}
}
}
```
### የውጤት ቅጦች (ካታሎግ)
ከላይ ያለው የCaveman ውጤት ሁነታ **የቆየው ነጠላ-ቅጥ መንገድ** ነው። Phase 4 ይህን
ወደ ተጣማሪ የውጤት ቅጦች ካታሎግ አጠቃለለው፦ በ
`open-sse/services/compression/outputStyles/catalog.ts` ውስጥ ያለው `OUTPUT_STYLE_CATALOG`። እያንዳንዱ ቅጥ ሞዴሉ ራሱ
ወጪው አነስተኛ የሆነ ውጤት እንዲያወጣ የሚያደርግ የስርዓት-ፕሮምፕት መመሪያ ነው፤ ቅጦች በአንድነት
ሊነቁ ይችላሉ፣ እና በካታሎግ ቅደም ተከተል ይገባሉ።
| ቅጥ | `id` | የሚያደርገው | የመመሪያ ቋንቋዎች |
| --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| አጭር ስድ ንባብ | `terse-prose` | አላስፈላጊ ቃላትን/መስተዋድዶችን/ማመንታትን ያስወግዳል፤ ቴክኒካዊ ይዘቱን በትክክል ይጠብቃል። ከቆየው የCaveman ውጤት ሁነታ ጋር ተመሳሳይ ጽሑፍ ነው (እንደገና ያልተጻፈ፣ በማጣቀሻ የተጠቀሰ)። | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| ያነሰ ኮድ | `less-code` | የYAGNI ደረጃ፦ አነስተኛው የሚሠራ ለውጥ፣ ያልተጠየቁ ረቂቅ አወቃቀሮች የሉም። | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Ponytail (ሰነፍ ከፍተኛ ደረጃ ገንቢ) | `ponytail` | "ምርጡ ኮድ ፈጽሞ ያልተጻፈው ኮድ ነው"፦ እንደገና መጠቀም > እንደገና መጻፍ፣ ዋና ምክንያት > ምልክት፣ አጭሩ የሚሠራ diff። | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| ADHD አለብኝ (ድርጊት-ቀዳሚ) | `i-have-adhd` | መጀመሪያ ድርጊት (ከስድ ንባብ በፊት ትዕዛዝ/ዱካ/ቅንጭብ)፣ ቁጥር የተሰጣቸውና የተገደቡ ደረጃዎች፣ አንድ ግልጽ ቀጣይ ደረጃ፣ መግቢያ/ድጋሚ ማጠቃለያ/መዝጊያ የለም። ከ[ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT) የተስማማ። | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| አጭር CJK (文言) | `terse-cjk` | እጅግ አጭር የጥንታዊ ቻይንኛ ቅጥ። | zh (በlocale የተገደበ፦ የተፈታው ቋንቋ `zh` ሲሆን ብቻ ይቀርባል) |
እያንዳንዱ ቅጥ ሦስት የጥንካሬ ደረጃዎችን — `lite`፣ `full`፣ `ultra` — ይዞ ይመጣል፣ እና እያንዳንዱ ደረጃ
በጋራ የድንበሮች አንቀጽ ያበቃል፤ ይህም የኮድ ብሎኮችን፣ የፋይል ዱካዎችን፣ ትዕዛዞችን፣
የስህተት ሕብረቁምፊዎችን፣ URLs እና identifiers ሳይለወጡ ይጠብቃል።
#### ማስገባቱ እንዴት እንደሚሠራ
`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`) ምርጫውን
ከካታሎጉ ጋር ያመሳስላል (ያልታወቁ ids እና ከlocale ጋር የማይዛመዱ ቅጦች
ይተዋሉ፤ ፈጽሞ እንደ ስህተት አይቆጠሩም)፣ የተመረጡትን መመሪያዎች በካታሎግ ቅደም ተከተል ያጣምራል፣
የድንበሮች አንቀጹን **አንድ ጊዜ** ያክላል፣ እና ውጤቱን ከአንድ idempotency marker
(`[OmniRoute Output Styles]`) ጀርባ በስርዓት ፕሮምፕቱ መጀመሪያ ላይ ያስገባል — እንደገና መተግበር
ምንም ለውጥ አያመጣም። የተገኘው የጥያቄ ቋንቋ ትርጉም ሲኖረው፣ በእንግሊዝኛው
ፋንታ አካባቢያዊ የተደረገው መመሪያ ይገባል።
#### እንዴት ማንቃት እንደሚቻል
በዳሽቦርዱ ውስጥ፦ **Context → Settings → Compression** — ለእያንዳንዱ ቅጥ አንድ ረድፍ፣
የማብራት/ማጥፋት መቀየሪያ እና የደረጃ መራጭ ያለው። በፕሮግራም ሲደረግ፣ የመጭመቂያ ውቅሩ
ምርጫውን እንደሚከተለው ያስቀምጣል፦
```json
{
"outputStyles": [
{ "id": "i-have-adhd", "level": "full" },
{ "id": "less-code", "level": "lite" }
]
}
```
ከቀድሞ ስሪቶች ጋር ተኳኋኝነት፦ የቆየው `outputMode: "caveman"` የጥምር ቅንብር አሁንም ይሠራል እና ወደ
`terse-prose` ይመደባል፤ በእያንዳንዱ የቆየ ቋንቋ ከአሮጌው ማስገባት ጋር byte-identical ነው።
የቋንቋ ምርጫ፦ `languageConfig.enabled` ሲበራ፣ `autoDetect` የቅርብ ጊዜውን
የተጠቃሚ መልዕክት ቋንቋ ይመርጣል (ከግቤት ሞተሮቹ ጋር ተመሳሳይ detector)፤
`autoDetect`ን ማጥፋት `defaultLanguage`ን ይቆልፋል። ጠፍቷል → እንግሊዝኛ።
የቅጥ × ቋንቋ ማትሪክስ በ
`tests/unit/compression/output-styles-i18n-matrix.test.ts` ተወስኗል፦ አዲስ ቅጥ ቢያንስ pt-BR ትርጉም
(ወይም በግልጽ የተከታተለ ልዩ ሁኔታ) ሳይኖረው ሊለቀቅ አይችልም፣ እና ነባር
ቅጥ localeን በዝምታ ሊያጣ አይችልም። ቅጥ ለመጨመር፣
[EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md#adding-an-output-style)ን ይመልከቱ።
### የመሣሪያ ውጤት መጭመቂያ
የ`toolResultCompressor.ts` ሞጁል ለመሣሪያ ውጤቶች (የፈንክሽን ጥሪዎች፣ የወኪል ውጤቶች፣ የፍለጋ ውጤቶች፣ ወዘተ)
**5 ልዩ የመጭመቂያ ስልቶችን** ይሰጣል፦
1. **የፍለጋ ውጤት መጭመቂያ** — ተደጋጋሚ ውጤቶችን ያስወግዳል፣ ከፍተኛ-Nን ያቆያል
2. **የፋይል ንባብ መጭመቂያ** — ትላልቅ ፋይሎችን ይቆርጣል፣ headers/importsን ይጠብቃል
3. **የኮድ አፈጻጸም መጭመቂያ** — አስፈላጊውን stdout/stderr ብቻ ያቆያል
4. **የውሂብ ጎታ መጠይቅ መጭመቂያ** — ረድፎችን ይገድባል፣ ዝርዝር metadataን ያስወግዳል
5. **የAPI ምላሽ መጭመቂያ** — null መስኮችን ያስወግዳል፣ arraysን ያጠቃልላል
#### መቼ መጠቀም እንዳለብዎት
የመሣሪያ ውጤት መጭመቂያ የመሣሪያ ጥሪዎች ባሉበት ጊዜ **ሁልጊዜ እንደነቃ ነው**።
ምንም ውቅር አያስፈልግም።
### የተደራረበ Pipeline
የተደራረበው ሁነታ **ብዙ ሞተሮችን በቅደም ተከተል** ያስኬዳል — ብዙውን ጊዜ መጀመሪያ RTK
(በመሣሪያ ውጤት ላይ 60-90% ቅነሳ)፣ ከዚያ Caveman (በቀሪው ጽሑፍ ላይ ተጨማሪ
30% ቅነሳ)። ይህ **በጠቅላላ 78-95% ቅነሳ** ያስገኛል።
#### እንዴት እንደሚሠራ
```
ግቤት (1000 ቶከኖች)
→ RTK (ትዕዛዝን የሚያውቅ ማጣሪያ) → 200 ቶከኖች
→ Caveman (አላስፈላጊ ቃላትን ማስወገድ) → 140 ቶከኖች
→ ውጤት (140 ቶከኖች፣ 86% ቅነሳ)
```
#### መቼ መጠቀም እንዳለብዎት
የተደራረበ ሁነታን ለሚከተሉት ይጠቀሙ፦
- መሣሪያ-ከባድ የሥራ ፍሰቶች (ወኪላዊ ኮድ ጽሑፍ፣ ምርምር)
- ለወጪ ትኩረት የሚሰጥ ባች ማቀናበር
- ከፍተኛውን የቶከን ቅነሳ ሲፈልጉ
በጥምር ውቅር በኩል ያቀናብሩ፦
```json
{
"strategy": "auto",
"config": {
"auto": {
"modePack": "stacked"
}
}
}
```
---
## የኮምፕሬሽን ኮምቦ ማሻሻያዎች
ለተለያዩ የአጠቃቀም ሁኔታዎች ባህሪውን በዝርዝር ለማስተካከል፣ አጠቃላይ የኮምፕሬሽን ሁነታውን **ለእያንዳንዱ ኮምቦ** ማሻሻል ይችላሉ፦
```json
{
"id": "coding-combo",
"strategy": "priority",
"config": {
"auto": {
"weights": { "taskFit": 0.5 },
"modePack": "quality-first"
}
},
"compressionOverride": {
"mode": "aggressive",
"stackedPipelines": ["rtk", "caveman"],
"preserveToolDefinitions": true
}
}
```
ይህ ለሚከተሉት ጠቃሚ ነው፦
- **የኮዲንግ ኮምቦዎች**፦ ለረጅም ክፍለ ጊዜዎች `aggressive` ሁነታን ይጠቀሙ
- **ፈጣን የጥያቄና መልስ ኮምቦዎች**፦ ለፈጣን ምላሾች `lite` ሁነታን ይጠቀሙ
- **ብዙ መሣሪያዎችን የሚጠቀሙ ኮምቦዎች**፦ ከፍተኛውን ቁጠባ ለማግኘት `stacked` ሁነታን ይጠቀሙ
- **የምርት ኮምቦዎች**፦ ለካሽ አቅራቢዎች `cache-aware` ሁነታን ይጠቀሙ
---
## በተጨማሪ ይመልከቱ
- [የአካባቢ ውቅር](../reference/ENVIRONMENT.md) — የኮምፕሬሽን የአካባቢ ተለዋዋጮች
- [የአርክቴክቸር መመሪያ](../architecture/ARCHITECTURE.md) — የኮምፕሬሽን ፓይፕላይን ውስጣዊ አሠራር
- [የተጠቃሚ መመሪያ](../guides/USER_GUIDE.md) — ኮምፕሬሽንን መጠቀም ለመጀመር
- [RTK ኮምፕሬሽን](./RTK_COMPRESSION.md) — የRTK ማጣሪያዎች፣ የእምነት ሞዴል፣ የማረጋገጫ በር፣ የጥሬ ውጤት መልሶ ማግኘት
- [የኮምፕሬሽን ሞተሮች](./COMPRESSION_ENGINES.md) — Caveman፣ RTK፣ stacked፣ APIs፣ MCP፣ ዳሽቦርድ
- [የኮምፕሬሽን ደንቦች ቅርጸት](./COMPRESSION_RULES_FORMAT.md) — የJSON የደንብ-ጥቅል ቅርጸት
- [የኮምፕሬሽን ቋንቋ ጥቅሎች](./COMPRESSION_LANGUAGE_PACKS.md) — ቋንቋ-ተኮር የCaveman ደንቦች

150
docs/i18n/am/docs/compression/COMPRESSION_LANGUAGE_PACKS.md Normal file
View File

File diff suppressed because one or more lines are too long

193
docs/i18n/am/docs/compression/COMPRESSION_RULES_FORMAT.md Normal file
View File

@@ -0,0 +1,193 @@
# Compression Rules Format (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../compression/COMPRESSION_RULES_FORMAT.md) · 🇸🇦 [ar](../../../ar/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇦🇿 [az](../../../az/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇧🇬 [bg](../../../bg/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇧🇩 [bn](../../../bn/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇨🇿 [cs](../../../cs/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇩🇰 [da](../../../da/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇩🇪 [de](../../../de/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇬🇷 [el](../../../el/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇪🇸 [es](../../../es/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇪🇪 [et](../../../et/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇷 [fa](../../../fa/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇫🇮 [fi](../../../fi/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇫🇷 [fr](../../../fr/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇪 [ga](../../../ga/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [gu](../../../gu/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇳🇬 [ha](../../../ha/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇱 [he](../../../he/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [hi](../../../hi/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇭🇷 [hr](../../../hr/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇭🇺 [hu](../../../hu/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇦🇲 [hy](../../../hy/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇩 [id](../../../id/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇳🇬 [ig](../../../ig/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇹 [it](../../../it/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇯🇵 [ja](../../../ja/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇬🇪 [ka](../../../ka/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇰🇭 [km](../../../km/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [kn](../../../kn/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇰🇷 [ko](../../../ko/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇱🇹 [lt](../../../lt/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇱🇻 [lv](../../../lv/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [ml](../../../ml/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [mr](../../../mr/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇲🇾 [ms](../../../ms/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇲🇹 [mt](../../../mt/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇲🇲 [my](../../../my/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇳🇵 [ne](../../../ne/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇳🇱 [nl](../../../nl/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇳🇴 [no](../../../no/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [or](../../../or/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [pa](../../../pa/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇵🇭 [phi](../../../phi/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇵🇱 [pl](../../../pl/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇵🇹 [pt](../../../pt/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇷🇴 [ro](../../../ro/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇷🇺 [ru](../../../ru/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇱🇰 [si](../../../si/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇸🇰 [sk](../../../sk/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇸🇮 [sl](../../../sl/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇷🇸 [sr](../../../sr/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇸🇪 [sv](../../../sv/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇰🇪 [sw](../../../sw/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [ta](../../../ta/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇮🇳 [te](../../../te/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇹🇭 [th](../../../th/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇹🇷 [tr](../../../tr/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇵🇰 [ur](../../../ur/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇺🇿 [uz](../../../uz/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇻🇳 [vi](../../../vi/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇳🇬 [yo](../../../yo/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/COMPRESSION_RULES_FORMAT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/COMPRESSION_RULES_FORMAT.md)
---
የማመቅ ደንቦች በአሂድ ጊዜ የሚጫኑ JSON ፋይሎች ናቸው። አዲስ የቋንቋ ጥቅሎችን እና የRTK ትዕዛዝ ማጣሪያዎችን የሞተሩን ኮድ ሳይቀይሩ መገምገም እንዲቻል ሆን ተብለው ውሂብ-ብቻ እንዲሆኑ ተደርገዋል።
> **ቀኖናዊ መርሃግብር (የእውነት ምንጭ):** [`open-sse/services/compression/rules/_schema.json`](../../open-sse/services/compression/rules/_schema.json) (JSON Schema draft 2020-12)።
> ከታች ያሉት ምሳሌዎች ለማብራሪያ ብቻ ናቸው — ጥርጣሬ ሲኖርዎት ጥቅልዎን ከ`_schema.json` ጋር ያረጋግጡ።
## የCaveman ደንብ ጥቅሎች
የCaveman ደንብ ጥቅሎች በሚከተለው ሥር ይገኛሉ፦
```txt
open-sse/services/compression/rules/<language>/<pack>.json
```
እያንዳንዱ ጥቅል የተጠበቁ ክልሎች ከተለዩ በኋላ በመደበኛ ጽሑፍ ላይ የሚተገበሩ ተተኪዎችን ይይዛል።
```json
{
"language": "en",
"category": "filler",
"rules": [
{
"name": "question_to_directive",
"pattern": "\\b(?:Can you explain why|Could you show me how)\\b\\s*",
"replacement": "Explain why ",
"replacementMap": {
"can you explain why": "Explain why ",
"could you show me how": "Show how "
},
"flags": "gi",
"context": "all",
"category": "context",
"minIntensity": "lite",
"description": "Convert verbose questions into direct requests."
}
]
}
```
### የCaveman መስኮች
| መስክ | አስፈላጊ | መግለጫ |
| ------------------------ | ----- | --------------------------------------------------------------- |
| `language` | አዎ | እንደ `en`፣ `pt-BR`፣ `es` ያለ BCP-47-መሰል የቋንቋ ቁልፍ |
| `category` | አዎ | የጥቅል ምድብ ፋይል ስም/ምድብ፣ ለምሳሌ `filler` ወይም `dedup` |
| `rules` | አዎ | የregex ተተኪ ደንቦች ድርድር |
| `rules[].name` | አዎ | የማይለዋወጥ የደንብ ስም |
| `rules[].pattern` | አዎ | የJavaScript regex ምንጭ |
| `rules[].flags` | አይ | የJavaScript regex ምልክቶች፤ ነባሪው `gi` ነው |
| `rules[].replacement` | አይ | የተተኪ ሕብረቁምፊ ወይም `replacementMap` ሲያጣ የሚያገለግል አማራጭ |
| `rules[].replacementMap` | አይ | በተደበኛ መልክ በተስማማው ጽሑፍ የተቆለፉ፣ ለእያንዳንዱ ተዛማጅ የተለዩ ተተኪዎች |
| `rules[].context` | አይ | `all`፣ `user`፣ `assistant` ወይም `system`፤ ነባሪው `all` ነው |
| `rules[].category` | አይ | `filler`፣ `context`፣ `structural`፣ `dedup`፣ `terse` ወይም `ultra` |
| `rules[].minIntensity` | አይ | `lite`፣ `full` ወይም `ultra`፤ ነባሪው `lite` ነው |
| `rules[].description` | አይ | ለሰው ሊነበብ የሚችል የደንቡ ማጠቃለያ |
የፊደል መጠንን የሚለይ ማዛመድ አስፈላጊ ሲሆን `flags`ን ይጠቀሙ፤ ለምሳሌ፣ `the OpenAI API`ን ሳያስወግዱ በትንሽ ፊደል ከተጻፈ ጽሑፍ በፊት ያለን መስተዋድድ ለማስወገድ። አንድ regex የተለያዩ ውጤቶችን የሚፈልጉ በርካታ አማራጮች ሲኖሩት `replacementMap`ን ይጠቀሙ፤ ይህም የበለጸጉትን አብሮ የተካተቱ የTypeScript ተተኪ ተግባራት ባህሪ እየጠበቀ፣ የJSON ደንብ ጥቅሎች ውሂብ-ብቻ ሆነው እንዲቆዩ ያደርጋል።
## RTK የማጣሪያ ጥቅሎች
RTK ማጣሪያዎች በሚከተለው ስር ይገኛሉ፦
```txt
open-sse/services/compression/engines/rtk/filters/<filter>.json
```
እያንዳንዱ ማጣሪያ አንድን የትዕዛዝ ውጤት ስብስብ እንዴት መለየትና መጭመቅ እንደሚቻል ይገልጻል።
```json
{
"id": "test-vitest",
"label": "Vitest output",
"category": "test",
"priority": 92,
"match": {
"outputTypes": ["test-vitest"],
"commands": ["vitest", "npm test", "npm run test"],
"patterns": ["\\bFAIL\\b", "\\bPASS\\b", "\\bTest Files\\b"]
},
"rules": {
"stripAnsi": true,
"replace": [{ "pattern": "\\s+\\[[0-9]+ms\\]", "replacement": "" }],
"matchOutput": [
{
"pattern": "All tests passed",
"message": "vitest: ok",
"unless": "FAIL|Error:"
}
],
"includePatterns": ["FAIL", "Error:", "Test Files", "Tests"],
"dropPatterns": ["^\\s*$", "Duration\\s+\\d+"],
"collapsePatterns": ["^\\s+at "],
"deduplicate": true,
"truncateLineAt": 240,
"maxLines": 160,
"headLines": 24,
"tailLines": 40,
"onEmpty": "vitest: ok",
"filterStderr": false
},
"preserve": {
"errorPatterns": ["FAIL", "Error:", "AssertionError"],
"summaryPatterns": ["Test Files", "Tests", "Snapshots"]
},
"tests": [
{
"name": "keeps failing tests",
"command": "vitest",
"input": "FAIL test/a.test.ts\\nError: boom\\nTest Files 1 failed",
"expected": "FAIL test/a.test.ts\\nError: boom\\nTest Files 1 failed"
}
]
}
```
### የRTK መስኮች
| መስክ | አስፈላጊ | መግለጫ |
| -------------------------- | ----- | --------------------------------------------------------------------------- |
| `id` | አዎ | የማይለወጥ የማጣሪያ መለያ |
| `label` | አዎ | በዳሽቦርድ ላይ ሊነበብ የሚችል ስም |
| `category` | አዎ | የማጣሪያ ስብስብ፦ git, test, build, shell, docker, package, infra, cloud, generic |
| `priority` | አይ | ብዙ ማጣሪያዎች ሲዛመዱ ከፍተኛ ቅድሚያ ያለው ያሸንፋል |
| `match.outputTypes` | አይ | ይህን ማጣሪያ የሚመርጡ የመለያ ሰጪው የውጤት መለያዎች |
| `match.commands` | አይ | ይህን ማጣሪያ የሚመርጡ የትዕዛዝ ቶከኖች |
| `match.patterns` | አይ | ከውጤት ጽሑፍ ይህን ማጣሪያ የሚመርጡ የRegex ስርዓተ ጥለቶች |
| `rules.stripAnsi` | አይ | ከRegex ደረጃዎች በፊት የANSI ማምለጫ ቅደም ተከተሎችን ያስወግዳል |
| `rules.replace` | አይ | በየመስመሩ በቅደም ተከተል የሚተገበሩ የRegex ምትኮች |
| `rules.matchOutput` | አይ | አማራጭ `unless` ጠባቂ ያላቸው የውጤት አቋራጭ ደንቦች |
| `rules.includePatterns` | አይ | እንዲጠበቁ ቅድሚያ የሚሰጣቸው መስመሮች |
| `rules.dropPatterns` | አይ | እንደ አላስፈላጊ ይዘት የሚወገዱ መስመሮች |
| `rules.collapsePatterns` | አይ | ሊጠቃለሉ የሚችሉ ተደጋጋሚ ተዛማጅ መስመሮች |
| `rules.deduplicate` | አይ | የተደጋገሙ መደበኛ የተደረጉ መስመሮችን ያጠቃልላል |
| `rules.truncateLineAt` | አይ | Unicode-ደህንነቱ የተጠበቀ የእያንዳንዱ መስመር የቁምፊ ገደብ |
| `rules.maxLines` | አይ | የመጨረሻ መስመሮች ከመጠበቃቸው በፊት የሚቀመጡ ከፍተኛው የመስመሮች ብዛት |
| `rules.headLines` | አይ | በመቁረጥ ጊዜ የሚቀመጡ የመጀመሪያ መስመሮች |
| `rules.tailLines` | አይ | የቅርብ ጊዜ አውድን ለመጠበቅ የሚቀመጡ የመጨረሻ መስመሮች |
| `rules.onEmpty` | አይ | ማጣራቱ ሁሉንም ይዘት ሲያስወግድ የሚታይ ተተኪ መልዕክት |
| `rules.filterStderr` | አይ | ከቀጣዮቹ የማጣራት ደረጃዎች በፊት የተለመዱ የstderr ቅድመ ቅጥያዎችን መደበኛ ያደርጋል |
| `preserve.errorPatterns` | አይ | ከመቁረጥ በኋላም ሊቆዩ የሚገባቸው የስህተት መስመሮች |
| `preserve.summaryPatterns` | አይ | ከመቁረጥ በኋላም ሊቆዩ የሚገባቸው የማጠቃለያ መስመሮች |
| `tests[]` | አይ | በRTK ማረጋገጫ በር የሚጠቀሙ ውስጠ-መስመር የማረጋገጫ ናሙናዎች |
RTK መግለጫዊ ደረጃዎቹን በዚህ ቅደም ተከተል ይተገብራል፦ `stripAnsi`, `filterStderr`, `replace`,
`matchOutput`, `dropPatterns`/`includePatterns`, `truncateLineAt`, `headLines`/`tailLines`,
`maxLines`, እና `onEmpty`።
ብጁ ማጣሪያዎች ከሚከተሉት ሊጫኑ ይችላሉ፦
1. የፕሮጀክት `.rtk/filters.json` ፋይሎች፤ እነዚህ የሚጫኑት ተዛማጅ `.rtk/trust.json` hash ከተገኘ በኋላ ወይም
`trustProjectFilters` ከነቃ ብቻ ነው።
2. ዓለም አቀፍ `DATA_DIR/rtk/filters.json`።
3. አብሮገነብ ማጣሪያዎች።
የፕሮጀክት/ዓለም አቀፍ ብጁ ፋይሎች አንድ የማጣሪያ ኦብጀክት ወይም የማጣሪያ ኦብጀክቶች ድርድር ሊይዙ ይችላሉ። ልክ ያልሆኑ
ብጁ ማጣሪያዎች ከምርመራ መረጃዎች ጋር ይዘለላሉ፤ ልክ ያልሆኑ አብሮገነብ ማጣሪያዎች ግን ማረጋገጡን ያሳክታሉ።
የፕሮጀክት እምነት ፋይል፦
```json
{
"filtersSha256": "0123456789abcdef..."
}
```
የአካባቢ ለውጥ `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1` ያለ hash የፕሮጀክት ማጣሪያዎችን የታመኑ አድርጎ
ይቆጥራል፤ አጠቃቀሙም ቁጥጥር ባለበት የአካባቢ ልማት ብቻ ሊገደብ ይገባል።
## የደህንነት ደንቦች
- ደንቦችን ተደጋጋሚ አፈጻጸምን በሚቋቋም መልኩ ያቆዩ፦ ተመሳሳዩን ማጣሪያ ሁለት ጊዜ ማስኬድ ውጤቱን ማበላሸት የለበትም።
- በተቻለ መጠን ትክክለኛውን የስህተት ጽሑፍ፣ የፋይል ዱካዎችን፣ የመስመር ቁጥሮችን እና የትዕዛዝ ማጠቃለያዎችን ሳይቀይሩ ያቆዩ።
- የኮድ ብሎኮችን፣ JSON ይዘቶችን፣ URLs ወይም ሚስጥሮችን የሚቀይሩ ደንቦችን ያስወግዱ።
- በፈላጊ/ማጣሪያ ሙከራዎች ውስጥ ለአዲስ የትዕዛዝ ስብስቦች የአሃድ ሙከራ ሽፋን ያክሉ።
- ለእያንዳንዱ አብሮገነብ ማጣሪያ እና ለጋራ ብጁ ማጣሪያዎች `tests[]` ናሙናዎችን ያክሉ።
## ማረጋገጫ
የደንብ ጥቅሎች ከጥቅም ላይ ከመዋላቸው በፊት ይረጋገጣሉ። አብሮገነብ Caveman ጥቅሎች እና አብሮገነብ RTK ማጣሪያዎች
የተበላሹ የልቀት ሀብቶች ከመላካቸው በፊት እንዲገኙ በማረጋገጫ ጊዜ ወዲያውኑ ይሳናሉ። ብጁ RTK ማጣሪያዎች
የመተንተን ወይም የታማኝነት ማረጋገጫ ሲሳካ ከምርመራ መረጃዎች ጋር ይዘለላሉ።
ያተኮረ ማረጋገጫ፦
```bash
node --import tsx/esm --test tests/unit/compression/rule-loader.test.ts tests/unit/compression/language-packs.test.ts
node --import tsx/esm --test tests/unit/compression/rtk-verify.test.ts tests/unit/compression/rtk-dsl-pipeline.test.ts
```

192
docs/i18n/am/docs/compression/CONTEXT_EDITING.md Normal file
View File

@@ -0,0 +1,192 @@
# Delegated Context Editing (Anthropic) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../compression/CONTEXT_EDITING.md) · 🇸🇦 [ar](../../../ar/docs/compression/CONTEXT_EDITING.md) · 🇦🇿 [az](../../../az/docs/compression/CONTEXT_EDITING.md) · 🇧🇬 [bg](../../../bg/docs/compression/CONTEXT_EDITING.md) · 🇧🇩 [bn](../../../bn/docs/compression/CONTEXT_EDITING.md) · 🇨🇿 [cs](../../../cs/docs/compression/CONTEXT_EDITING.md) · 🇩🇰 [da](../../../da/docs/compression/CONTEXT_EDITING.md) · 🇩🇪 [de](../../../de/docs/compression/CONTEXT_EDITING.md) · 🇬🇷 [el](../../../el/docs/compression/CONTEXT_EDITING.md) · 🇪🇸 [es](../../../es/docs/compression/CONTEXT_EDITING.md) · 🇪🇪 [et](../../../et/docs/compression/CONTEXT_EDITING.md) · 🇮🇷 [fa](../../../fa/docs/compression/CONTEXT_EDITING.md) · 🇫🇮 [fi](../../../fi/docs/compression/CONTEXT_EDITING.md) · 🇫🇷 [fr](../../../fr/docs/compression/CONTEXT_EDITING.md) · 🇮🇪 [ga](../../../ga/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [gu](../../../gu/docs/compression/CONTEXT_EDITING.md) · 🇳🇬 [ha](../../../ha/docs/compression/CONTEXT_EDITING.md) · 🇮🇱 [he](../../../he/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [hi](../../../hi/docs/compression/CONTEXT_EDITING.md) · 🇭🇷 [hr](../../../hr/docs/compression/CONTEXT_EDITING.md) · 🇭🇺 [hu](../../../hu/docs/compression/CONTEXT_EDITING.md) · 🇦🇲 [hy](../../../hy/docs/compression/CONTEXT_EDITING.md) · 🇮🇩 [id](../../../id/docs/compression/CONTEXT_EDITING.md) · 🇳🇬 [ig](../../../ig/docs/compression/CONTEXT_EDITING.md) · 🇮🇹 [it](../../../it/docs/compression/CONTEXT_EDITING.md) · 🇯🇵 [ja](../../../ja/docs/compression/CONTEXT_EDITING.md) · 🇬🇪 [ka](../../../ka/docs/compression/CONTEXT_EDITING.md) · 🇰🇭 [km](../../../km/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [kn](../../../kn/docs/compression/CONTEXT_EDITING.md) · 🇰🇷 [ko](../../../ko/docs/compression/CONTEXT_EDITING.md) · 🇱🇹 [lt](../../../lt/docs/compression/CONTEXT_EDITING.md) · 🇱🇻 [lv](../../../lv/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [ml](../../../ml/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [mr](../../../mr/docs/compression/CONTEXT_EDITING.md) · 🇲🇾 [ms](../../../ms/docs/compression/CONTEXT_EDITING.md) · 🇲🇹 [mt](../../../mt/docs/compression/CONTEXT_EDITING.md) · 🇲🇲 [my](../../../my/docs/compression/CONTEXT_EDITING.md) · 🇳🇵 [ne](../../../ne/docs/compression/CONTEXT_EDITING.md) · 🇳🇱 [nl](../../../nl/docs/compression/CONTEXT_EDITING.md) · 🇳🇴 [no](../../../no/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [or](../../../or/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [pa](../../../pa/docs/compression/CONTEXT_EDITING.md) · 🇵🇭 [phi](../../../phi/docs/compression/CONTEXT_EDITING.md) · 🇵🇱 [pl](../../../pl/docs/compression/CONTEXT_EDITING.md) · 🇵🇹 [pt](../../../pt/docs/compression/CONTEXT_EDITING.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/CONTEXT_EDITING.md) · 🇷🇴 [ro](../../../ro/docs/compression/CONTEXT_EDITING.md) · 🇷🇺 [ru](../../../ru/docs/compression/CONTEXT_EDITING.md) · 🇱🇰 [si](../../../si/docs/compression/CONTEXT_EDITING.md) · 🇸🇰 [sk](../../../sk/docs/compression/CONTEXT_EDITING.md) · 🇸🇮 [sl](../../../sl/docs/compression/CONTEXT_EDITING.md) · 🇷🇸 [sr](../../../sr/docs/compression/CONTEXT_EDITING.md) · 🇸🇪 [sv](../../../sv/docs/compression/CONTEXT_EDITING.md) · 🇰🇪 [sw](../../../sw/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [ta](../../../ta/docs/compression/CONTEXT_EDITING.md) · 🇮🇳 [te](../../../te/docs/compression/CONTEXT_EDITING.md) · 🇹🇭 [th](../../../th/docs/compression/CONTEXT_EDITING.md) · 🇹🇷 [tr](../../../tr/docs/compression/CONTEXT_EDITING.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/CONTEXT_EDITING.md) · 🇵🇰 [ur](../../../ur/docs/compression/CONTEXT_EDITING.md) · 🇺🇿 [uz](../../../uz/docs/compression/CONTEXT_EDITING.md) · 🇻🇳 [vi](../../../vi/docs/compression/CONTEXT_EDITING.md) · 🇳🇬 [yo](../../../yo/docs/compression/CONTEXT_EDITING.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/CONTEXT_EDITING.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/CONTEXT_EDITING.md)
---
የተወከለ **የአውድ አርትዖት** ለClaude ብቻ የተዘጋጀ የአውድ አስተዳደር ባህሪ ነው። የOmniRoute አካባቢያዊ
የማመቅ ሞተሮች (Caveman, RTK, LLMLingua, የተደራረቡ የሂደት ሰንሰለቶች) የጥያቄውን ይዘት
ከፕሮክሲው ከመውጣቱ _በፊት_ እንደገና ከሚጽፉት በተለየ፣ የአውድ አርትዖት **አቅራቢውን**
ጊዜ ያለፈባቸውን የመሣሪያ-አጠቃቀም / የመሣሪያ-ውጤት ብሎኮች ከራሱ ቀጣይነት ካለው የአውድ መስኮት እንዲያጸዳ ይጠይቃል። OmniRoute የሚያክለው
የይዘት መለኪያ (`context_management.edits[]`) ብቻ ነው፤ ትክክለኛውን ማጽዳት Claude በራሱ tokenizer ላይ ያከናውናል።
ይህ በባህሪው የተወከለ ችሎታ ነው፦ ሌሎች አቅራቢዎች መለኪያውን ውድቅ ያደርጋሉ፣ ስለዚህ OmniRoute
ወሰኑን በጥብቅ ለClaude እና Claude-Code-ተኳኋኝ ማስተላለፊያዎች ብቻ ያደርጋል።
ዋና የመረጃ ምንጭ፦ `open-sse/config/contextEditing.ts` (የስትራቴጂ መለያዎች፣ የይዘት ማስገባት፣ የtelemetry
ማውጣት)፣ `open-sse/executors/base.ts` (የማስገባት መግቢያ + የ400 ተተኪ አሠራር)፣ እና
`open-sse/services/compression/types.ts` (የውቅር ቅርጽ + ነባሪ)።
## `clear_tool_uses` ምን ያደርጋል
OmniRoute ወደ ውጭ በሚላከው Anthropic Messages ይዘት ውስጥ አንድ አርትዖት ያስገባል፦
```json
{
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": { "type": "input_tokens", "value": 100000 },
"keep": { "type": "tool_uses", "value": 3 }
}
]
}
}
```
- `type: "clear_tool_uses_20250919"` — ቀን የተጨመረበት የAnthropic ስትራቴጂ መለያ (`CLEAR_TOOL_USES_STRATEGY`)።
- `trigger.value: 100000` — የጥያቄው input tokens ከዚህ ገደብ ካለፉ በኋላ፣ Claude የቆዩ
የመሣሪያ-አጠቃቀም/ውጤት ጥንዶችን ማጽዳት ይጀምራል (`CONTEXT_EDITING_DEFAULT_TRIGGER_TOKENS`፣ የAnthropic ነባሪ)።
- `keep.value: 3` — በጣም የቅርብ ጊዜዎቹ N የመሣሪያ-አጠቃቀም/ውጤት ጥንዶች ሳይነኩ ይቀመጣሉ
(`CONTEXT_EDITING_DEFAULT_KEEP_TOOL_USES`)።
ቤታው `anthropic-beta: context-management-2025-06-27` በሚለው ራስጌ በኩል ይገለጻል፣ ይህንንም
OmniRoute አስቀድሞ በClaude ጥያቄዎች ላይ ይልካል።
ማስገባቱ በ`applyContextEditingToBody()` ይከናወናል እና **idempotent** ነው፦ የ`clear_tool_uses`
አርትዖት አስቀድሞ በይዘቱ ላይ ካለ (በቀደመ ጥሪ የተጨመረ ወይም በደንበኛው የቀረበ)፣ ይዘቱ
እንዳለ ይተዋል። የ`clear_thinking_20251015` አርትዖትም ካለ፣ OmniRoute የ`clear_thinking`
አርትዖቱን ቅደም ተከተሉን ሳያዛባ ወደ ፊት ያደርገዋል፤ ምክንያቱም Anthropic በ`edits[]` ድርድር ውስጥ `clear_thinking` ከ
`clear_tool_uses` እንዲቀድም ይጠይቃል።
## የእያንዳንዱ ጥምረት የማንቃት መቀያየሪያ
የአውድ አርትዖት **በነባሪ ጠፍቷል** እና በምርጫ የሚነቃ ነው። መቀያየሪያው በማመቂያ ውቅሩ ውስጥ የሚያዝ አንድ boolean ነው፦
- የቅንብር ቁልፍ፦ `contextEditing.enabled` (camelCase — `context_editing` / `context-editing` **አይደለም**)።
- ዓይነት፦ `ContextEditingConfig { enabled: boolean }` በ
`open-sse/services/compression/types.ts` ውስጥ።
- ነባሪ፦ `DEFAULT_CONTEXT_EDITING_CONFIG = { enabled: false }`።
- Zod schema፦ `contextEditingConfigSchema` በ`src/shared/validation/compressionConfigSchemas.ts` ውስጥ።
- ማከማቻ፦ ከቀሩት የማመቂያ ቅንብሮች ጋር በቋሚነት ይቀመጣል (በ
`src/lib/db/compression.ts` ውስጥ መደበኛ ቅርጽ ይሰጠዋል)።
በዳሽቦርዱ ውስጥ መቀያየሪያው በማመቂያ ማዕከሉ
(`src/app/(dashboard)/dashboard/context/combos/CompressionHub.tsx`) ውስጥ ይገኛል፣ እና
`{ contextEditing: { enabled: … } }`ን በ`saveSettings()` በኩል መልሶ ይጽፋል። በ
compression-settings ኦብጀክት ላይ ስለሚጓዝ፣ ሙሉ በሙሉ ራሱን የቻለ ገጽታ ከመሆን ይልቅ ከእያንዳንዱ ጥምረት የማመቂያ መገለጫ ጋር
አብሮ ይሠራል — ውቅሩ የሚይዘው የማብራት/ማጥፋት ምልክቱን ብቻ ነው፤ ሁሉም ገደቦች (`trigger`,
`keep`) ከላይ የተመዘገቡት ቋሚ እሴቶች ናቸው።
## Claude-ብቻ ማገጃ
መርፌው የሚከናወነው ለእውነተኛ Claude ወይም Claude-Code-ተኳኋኝ ሪሌዎች ብቻ ነው። በ
`open-sse/executors/base.ts` ውስጥ ያለው ማገጃ ይህ ነው፦
```ts
if (
(this.provider === "claude" || isClaudeCodeCompatible(this.provider)) &&
contextEditing?.enabled &&
!contextEditingDisabled
) {
applyContextEditingToBody(transformedBody, { enabled: true });
}
```
- `this.provider === "claude"` — እውነተኛ Anthropic ቁልፍ/OAuth።
- `isClaudeCodeCompatible(this.provider)` — የአቅራቢ መለያቸው በ
`anthropic-compatible-cc-` ቅድመ ቅጥያ የሚጀምር ሪሌዎች (Claude Code ተኳኋኝነትን ያስታውቃሉ፤ ስለዚህ betaውን
የመቀበል ዕድላቸው ከፍተኛ የሆኑ ሪሌዎች ናቸው)። `open-sse/services/provider.ts`ን ይመልከቱ።
ሆን ተብለው **የተገለሉ**፦
- `claude-web` — `context_management`ን ፈጽሞ የማያይ `create_conversation_params` የጥያቄ ቅርጽ ያለው የአሳሽ ሪሌይ።
- አጠቃላይ `anthropic-compatible-*` ሪሌዎች (`-cc-` ቅድመ ቅጥያ የሌላቸው) — የbeta ድጋፋቸው
እርግጠኛ ያልሆነ የሶስተኛ ወገን መጨረሻ ነጥቦች።
መቀያየሪያው በርቶ ቢሆንም Claude ያልሆኑ አቅራቢዎች `context_management` መለኪያን ፈጽሞ አይቀበሉም።
## የ400 የመጠባበቂያ ሂደት / የሪሌይ ሽፋን
Claude-ተኳኋኝ ሪሌይ betaውን ሊያስታውቅ ይችላል፣ ነገር ግን `context_management` መለኪያን
በHTTP 400 ሊከለክል ይችላል። ጥያቄውን ከማሳካት ይልቅ በለሰለሰ ሁኔታ ወደ አማራጭ ለመውረድ፣ አስፈጻሚው መለኪያውን ያስወግድና ያንኑ URL **አንድ ጊዜ** እንደገና ይሞክራል፦
```ts
if (
response.status === HTTP_STATUS.BAD_REQUEST &&
contextEditing?.enabled &&
!contextEditingDisabled &&
transformedBody?.context_management !== undefined
) {
const errText = await response
.clone()
.text()
.catch(() => "");
if (/context[_-]management|context editing/i.test(errText)) {
contextEditingDisabled = true;
delete transformedBody.context_management;
let retryBody = JSON.stringify(transformedBody);
if (isClaudeCodeCompatible(this.provider) || this.provider === "claude") {
retryBody = await signRequestBody(retryBody);
}
response = await fetch(url, { ...fetchOptions, body: retryBody });
}
}
```
ባህሪ፦
1. የአውድ አርትዖት በርቶ ሳለ እና የጥያቄው አካል በእርግጥ
`context_management`ን ሲይዝ፣ በ`400` ላይ ብቻ ይነሳል።
2. በማይዛመደው መንገድ ላይ ዋናው ምላሽ ሳይነካ እንዲቆይ፣ የ400 አካል በ`clone()` በኩል ይነበባል።
3. የስህተቱ ጽሑፍ ከ`/context[_-]management|context editing/i` ጋር መዛመድ አለበት — ያልተዛመደ 400 (ለምሳሌ
`max_tokens must be >= 1`) የመጠባበቂያ ሂደቱን **አያስጀምርም**፤ ዋናው ስህተት ይተላለፋል።
4. ሲዛመድ `contextEditingDisabled = true` ያደርጋል (ይህም ለዳግም ሙከራ/የመጠባበቂያ URL አዲስ
`transformedBody` በኋላ ቢገነባ ዳግም መርፌን ይከላከላል)፣ `context_management`ን ይሰርዛል፣
ለClaude / Claude-Code-ተኳኋኝ ሪሌዎች አካሉን እንደገና ይፈርማል (`signRequestBody`)፣ እና ያንኑ
URL አንድ ጊዜ እንደገና ይሞክራል።
እውነተኛ Claude betaውን በ`ANTHROPIC_BETA_BASE` ውስጥ ይይዛል፣ እና ይህን የመጠባበቂያ መንገድ አይጠቀምም።
## `applied_edits` ቴሌሜትሪ
ከClaude ምላሽ በኋላ፣ OmniRoute አቅራቢው በእርግጥ ምን ያህል አውድ እንዳጸዳ ይመዘግባል። ይህ
**በዥረት አይተላለፍም** — ከዥረት-አልባው የምላሽ አካል በተቻለ መጠን ይወጣል፣ እና
ምላሹን ፈጽሞ አይነካም (የቴሌሜትሪ ውድቀቶች ችላ ይባላሉ)።
- ማውጣት፦ `extractContextEditingTelemetry(responseBody)` በ`open-sse/config/contextEditing.ts` ውስጥ።
የምላሽ ቅርጹን በጥንቃቄ ለመያዝ `applied_edits`ን በሦስት ቦታዎች ይፈትሻል፦
- `context_management.applied_edits`
- `usage.context_management.applied_edits`
- `usage.applied_edits`
- ከእያንዳንዱ ግቤት የሚነበቡ የአርትዖት መስኮች፦ `cleared_input_tokens` እና `cleared_tool_uses`
(snake_case፣ የAnthropic ተወላጅ)፣ ከ`clearedInputTokens` / `clearedToolUses` camelCase አማራጮች ጋር።
- ምንም የ`applied_edits` ድርድር ካልተገኘ ወይም በእርግጥ ምንም ካልተጸዳ `null`ን ይመልሳል።
የደረሰኙ ቅርጽ `ContextEditingTelemetry { editCount, clearedInputTokens, clearedToolUses }` ነው።
ምዝገባው በ`open-sse/handlers/chatCore.ts` ውስጥ (ለ`provider === "claude"` ብቻ ተገድቦ) በ
`recordContextEditingTelemetry()` (`src/lib/db/compressionAnalytics.ts`) በኩል ይከናወናል፤ ይህም በሚከተለው ሁኔታ መለያ የተሰጠውን የመጭመቂያ
ትንታኔ ረድፍ ይጽፋል፦
- `mode: "context-editing"`
- `engine: "context-editing"`
- `tokens_saved` / `original_tokens` = የጸዳው የግቤት-ቶከን ብዛት
- `request_id` በ`::context-editing` የተጨረሰ
ስለዚህ ውክልና የተሰጠው ማጽዳት ከአካባቢያዊ ሞተሮች ጋር በመጭመቂያ ትንታኔ ውስጥ፣ በ
`context-editing` የሞተር መለያ ስር ይታያል፣ እና ከRTK/Caveman/LLMLingua ቁጠባዎች ሊለይ ይችላል።
## ከአካባቢያዊ የማመቂያ ሞተሮች ጋር ያለው ግንኙነት
| ገጽታ | አካባቢያዊ ሞተሮች (Caveman / RTK / LLMLingua / stacked) | የተወከለ የአውድ አርትዖት |
| ---------- | ------------------------------------------------- | ----------------------------------------- |
| የሚሰራበት ቦታ | በOmniRoute ውስጥ፣ ጥያቄው ፕሮክሲውን ከመልቀቁ በፊት | በአቅራቢው (Claude) ውስጥ፣ በሰርቨር በኩል |
| የሚያርተው | የጥያቄ / የአውድ / የመሣሪያ-ውጤት ጽሑፍ | የቆዩ የመሣሪያ-አጠቃቀም / የመሣሪያ-ውጤት ብሎኮች |
| የአቅራቢ ወሰን | ሁሉም አቅራቢዎች | `claude` + `anthropic-compatible-cc-*` ብቻ |
| ማብሪያ/ማጥፊያ | የማመቂያ ሁነታ ቅንብሮች | `contextEditing.enabled` |
| የውድቀት ሁነታ | ሲወድቅ ዋናውን ጽሑፍ መጠቀም | የ400 አማራጭ፦ መለኪያውን አስወግዶ አንድ ጊዜ እንደገና መሞከር |
| የቁጠባ ቴሌሜትሪ | `engine: <engine id>` | `engine: "context-editing"` |
ሁለቱ እርስ በርስ የሚደጋገፉ ናቸው፦ አካባቢያዊ ሞተሮች OmniRoute የሚልካቸውን ባይቶች ያመቃሉ፤ የአውድ አርትዖት ደግሞ
Claude በተከታታይ ዙሮች ውስጥ እየተራዘመ ያለውን አውድ እንዲቀንስ ያስችለዋል። ሁለቱም በአንድነት ሊነቁ ይችላሉ።
## ተጨማሪ ይመልከቱ
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — የሞተር መዝገብ እና አካባቢያዊ የማመቂያ
ሞተሮች
- [RTK_COMPRESSION.md](./RTK_COMPRESSION.md) — የትእዛዝ/የመሣሪያ-ውጤት ማመቂያ
- [../frameworks/MCP-SERVER.md](../frameworks/MCP-SERVER.md) — የMCP መግለጫ ማመቂያ እና
የመሣሪያ ብዛት መቀነስ
- ምንጭ፦ `open-sse/config/contextEditing.ts`, `open-sse/executors/base.ts`,
`open-sse/services/compression/types.ts`, `src/lib/db/compressionAnalytics.ts`

633
docs/i18n/am/docs/compression/EXTENDING_COMPRESSION.md Normal file
View File

@@ -0,0 +1,633 @@
# Extending the Compression Pipeline (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../compression/EXTENDING_COMPRESSION.md) · 🇸🇦 [ar](../../../ar/docs/compression/EXTENDING_COMPRESSION.md) · 🇦🇿 [az](../../../az/docs/compression/EXTENDING_COMPRESSION.md) · 🇧🇬 [bg](../../../bg/docs/compression/EXTENDING_COMPRESSION.md) · 🇧🇩 [bn](../../../bn/docs/compression/EXTENDING_COMPRESSION.md) · 🇨🇿 [cs](../../../cs/docs/compression/EXTENDING_COMPRESSION.md) · 🇩🇰 [da](../../../da/docs/compression/EXTENDING_COMPRESSION.md) · 🇩🇪 [de](../../../de/docs/compression/EXTENDING_COMPRESSION.md) · 🇬🇷 [el](../../../el/docs/compression/EXTENDING_COMPRESSION.md) · 🇪🇸 [es](../../../es/docs/compression/EXTENDING_COMPRESSION.md) · 🇪🇪 [et](../../../et/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇷 [fa](../../../fa/docs/compression/EXTENDING_COMPRESSION.md) · 🇫🇮 [fi](../../../fi/docs/compression/EXTENDING_COMPRESSION.md) · 🇫🇷 [fr](../../../fr/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇪 [ga](../../../ga/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [gu](../../../gu/docs/compression/EXTENDING_COMPRESSION.md) · 🇳🇬 [ha](../../../ha/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇱 [he](../../../he/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [hi](../../../hi/docs/compression/EXTENDING_COMPRESSION.md) · 🇭🇷 [hr](../../../hr/docs/compression/EXTENDING_COMPRESSION.md) · 🇭🇺 [hu](../../../hu/docs/compression/EXTENDING_COMPRESSION.md) · 🇦🇲 [hy](../../../hy/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇩 [id](../../../id/docs/compression/EXTENDING_COMPRESSION.md) · 🇳🇬 [ig](../../../ig/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇹 [it](../../../it/docs/compression/EXTENDING_COMPRESSION.md) · 🇯🇵 [ja](../../../ja/docs/compression/EXTENDING_COMPRESSION.md) · 🇬🇪 [ka](../../../ka/docs/compression/EXTENDING_COMPRESSION.md) · 🇰🇭 [km](../../../km/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [kn](../../../kn/docs/compression/EXTENDING_COMPRESSION.md) · 🇰🇷 [ko](../../../ko/docs/compression/EXTENDING_COMPRESSION.md) · 🇱🇹 [lt](../../../lt/docs/compression/EXTENDING_COMPRESSION.md) · 🇱🇻 [lv](../../../lv/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [ml](../../../ml/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [mr](../../../mr/docs/compression/EXTENDING_COMPRESSION.md) · 🇲🇾 [ms](../../../ms/docs/compression/EXTENDING_COMPRESSION.md) · 🇲🇹 [mt](../../../mt/docs/compression/EXTENDING_COMPRESSION.md) · 🇲🇲 [my](../../../my/docs/compression/EXTENDING_COMPRESSION.md) · 🇳🇵 [ne](../../../ne/docs/compression/EXTENDING_COMPRESSION.md) · 🇳🇱 [nl](../../../nl/docs/compression/EXTENDING_COMPRESSION.md) · 🇳🇴 [no](../../../no/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [or](../../../or/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [pa](../../../pa/docs/compression/EXTENDING_COMPRESSION.md) · 🇵🇭 [phi](../../../phi/docs/compression/EXTENDING_COMPRESSION.md) · 🇵🇱 [pl](../../../pl/docs/compression/EXTENDING_COMPRESSION.md) · 🇵🇹 [pt](../../../pt/docs/compression/EXTENDING_COMPRESSION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/EXTENDING_COMPRESSION.md) · 🇷🇴 [ro](../../../ro/docs/compression/EXTENDING_COMPRESSION.md) · 🇷🇺 [ru](../../../ru/docs/compression/EXTENDING_COMPRESSION.md) · 🇱🇰 [si](../../../si/docs/compression/EXTENDING_COMPRESSION.md) · 🇸🇰 [sk](../../../sk/docs/compression/EXTENDING_COMPRESSION.md) · 🇸🇮 [sl](../../../sl/docs/compression/EXTENDING_COMPRESSION.md) · 🇷🇸 [sr](../../../sr/docs/compression/EXTENDING_COMPRESSION.md) · 🇸🇪 [sv](../../../sv/docs/compression/EXTENDING_COMPRESSION.md) · 🇰🇪 [sw](../../../sw/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [ta](../../../ta/docs/compression/EXTENDING_COMPRESSION.md) · 🇮🇳 [te](../../../te/docs/compression/EXTENDING_COMPRESSION.md) · 🇹🇭 [th](../../../th/docs/compression/EXTENDING_COMPRESSION.md) · 🇹🇷 [tr](../../../tr/docs/compression/EXTENDING_COMPRESSION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/EXTENDING_COMPRESSION.md) · 🇵🇰 [ur](../../../ur/docs/compression/EXTENDING_COMPRESSION.md) · 🇺🇿 [uz](../../../uz/docs/compression/EXTENDING_COMPRESSION.md) · 🇻🇳 [vi](../../../vi/docs/compression/EXTENDING_COMPRESSION.md) · 🇳🇬 [yo](../../../yo/docs/compression/EXTENDING_COMPRESSION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/EXTENDING_COMPRESSION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/EXTENDING_COMPRESSION.md)
---
> **በአጭሩ**: የOmniRoute የማመቅ ሞተር **ሊሰካ የሚችል** ነው — ብጁ ሞተሮችን መመዝገብ፣ ለአዳዲስ ቋንቋዎች የቋንቋ ጥቅሎችን ማቅረብ እና የተደራረቡ የሂደት መስመሮችን ማቀናጀት ይችላሉ። ይህ መመሪያ እንዴት እንደሚደረግ ያሳያል።
**ተዛማጅ መመሪያዎች፦**
- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — የሙሉ የሂደት መስመሩ አጠቃላይ እይታ
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — የሞተር መዝገብ እና አብረው የተካተቱ ሞተሮች
- [RTK_COMPRESSION.md](./RTK_COMPRESSION.md) — የRTK ሞተር እና ብጁ ማጣሪያዎች
- [COMPRESSION_RULES_FORMAT.md](./COMPRESSION_RULES_FORMAT.md) — የደንብ ጥቅል ቅርጸት ማጣቀሻ
---
## አጠቃላይ እይታ
የማመቅ ስርዓቱ **3 የማስፋፊያ ነጥቦች** አሉት፦
| የማስፋፊያ ነጥብ | የአጠቃቀም ሁኔታ | የአስቸጋሪነት ደረጃ |
| -------------------- | ----------------------------------------------------------- | ------------ |
| **ብጁ ሞተር** | ሙሉ በሙሉ አዲስ የማመቅ አልጎሪዝም ማከል (ለምሳሌ፣ ለተወሰነ ዘርፍ የተዘጋጀ ማጠቃለያ ሰጪ) | ከፍተኛ |
| **የቋንቋ ጥቅል** | ለአዲስ የተፈጥሮ ቋንቋ ድጋፍ ማከል (ለምሳሌ፣ ሂንዲ፣ ዓረብኛ) | መካከለኛ |
| **የተደራረበ የሂደት መስመር** | ነባር ሞተሮችን በብጁ ቅደም ተከተል ማቀናጀት | ጀማሪ |
```
┌─────────────────────────────────────────────────────────────┐
│ የማመቅ ስትራቴጂ │
│ │
│ የግቤት መልዕክቶች ──▶ getEffectiveMode() ──▶ mode │
│ │ │
│ ┌───────────────────────┼──────────┐ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │ │
│ "rtk" "lite" "standard" "stacked" │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │ │
│ RTK Lite Caveman engines[] │
│ ሞተር ሞተር ሞተር በሰንሰለት │
│ │ │ │ │ │ │
│ └─────────┴─────────┴─────────┘ │ │
│ │ │
│ ▼ │
│ የታመቀ ውጤት │
└─────────────────────────────────────────────────────────────┘
የስትራቴጂው መራጭ በMODE ላይ የተመሰረተ ነው፦ እያንዳንዱ ጥያቄ አንድ mode ይመርጣል
(rtk / lite / standard / aggressive / ultra / stacked / off)።
ብዙ ሞተሮችን በቅደም ተከተል የሚያገናኘው "stacked" mode ብቻ ነው።
ነባሪው በራስ-ሰር የሚጀምር mode "lite" ነው (ባለ3-ደረጃ የቅድሚያ ሰንሰለት አይደለም)።
```
---
## ብጁ የማመቅ ሞተር መጻፍ
የሞተሩ በይነገጽ (`open-sse/services/compression/engines/types.ts`) እያንዳንዱ ሞተር ሊያሟላው የሚገባ ውል ነው። 5 አስፈላጊ ሜቶዶች አሉት።
### የ`CompressionEngine` በይነገጽ
```ts
interface CompressionEngine {
id: string; // ልዩ የሞተር ID
name: string; // የማሳያ ስም
description: string; // አጭር መግለጫ
icon: string; // አዶ (ኢሞጂ ወይም URL)
targets: CompressionEngineTarget[]; // ["messages", "tool_results", "code_blocks"]
stackable: boolean; // በተደራረበ የሂደት መስመር ውስጥ መጠቀም ይቻላል
stackPriority: number; // በተደራረቡ የሂደት መስመሮች ውስጥ ያለው ቅደም ተከተል (ዝቅተኛ = ቀደም ያለ)
metadata: CompressionEngineMetadata;
apply(body, options?): CompressionResult;
compress(body, config?): CompressionResult;
getConfigSchema(): EngineConfigField[];
validateConfig(config): EngineValidationResult;
}
```
### አነስተኛ ምሳሌ፦ የነጭ ቦታ ሞተር
በጣም ቀላሉ ሞተር — ከመልዕክቶች ውስጥ ተጨማሪ ነጭ ቦታን ያስወግዳል።
````ts
import type { CompressionEngine } from "omniroute/compression/engines/types";
import { registerCompressionEngine } from "omniroute/compression/engines/registry";
function preserveCodeBlocks(text: string): string {
// በኮድ ብሎክ ምልክቶች ይከፋፍሉ እና በውስጣቸው ያለውን ክፍተት ይጠብቁ
const parts = text.split(/(```[\s\S]*?```)/);
return parts
.map((part) => {
if (part.startsWith("```")) {
return part; // የኮድ ብሎኮችን አያሻሽሉ
}
return part.replace(/\n{3,}/g, "\n\n"); // በጽሑፍ ላይ ብቻ ይተግብሩ
})
.join("");
}
const whitespaceEngine: CompressionEngine = {
id: "whitespace",
name: "Whitespace Stripper",
description: "Removes extra whitespace and blank lines",
icon: "📝",
targets: ["messages", "tool_results"],
stackable: true,
stackPriority: 100, // ከcaveman/rtk በኋላ ያሂዱ
metadata: {
id: "whitespace",
name: "Whitespace Stripper",
description: "Removes extra whitespace and blank lines",
inputScope: "messages",
targetLatencyMs: 5,
supportsPreview: true,
stable: true,
},
apply(body, options) {
return this.compress(body, options?.config);
},
compress(body, config = {}) {
let originalLength = 0;
let compressedLength = 0;
// የመልዕክቶችን ድርድር ያቋርጡ — ሕብረቁምፊ እና ባለብዙ ክፍል ይዘትን ይያዙ
const compressedBody = (body.messages || []).map((msg) => {
if (typeof msg.content === "string") {
originalLength += msg.content.length;
let compressed = msg.content
.replace(/[ \t]+/g, " ")
.replace(/\n{3,}/g, "\n\n")
.replace(/^\s+|\s+$/gm, "");
compressedLength += compressed.length;
return { ...msg, content: compressed };
}
// ባለብዙ ክፍል ይዘት፦ ክፍሎቹን ያቋርጡ፣ የጽሑፍ ክፍሎችን ብቻ ይጨምቁ
if (Array.isArray(msg.content)) {
const newParts = msg.content.map((part) => {
if (part.type === "text" && typeof part.text === "string") {
originalLength += part.text.length;
let compressed = part.text
.replace(/[ \t]+/g, " ")
.replace(/\n{3,}/g, "\n\n")
.replace(/^\s+|\s+$/gm, "");
compressedLength += compressed.length;
return { ...part, text: compressed };
}
return part; // image_url፣ tool_use፣ ወዘተ ይጠብቁ።
});
return { ...msg, content: newParts };
}
return msg;
});
return {
body: { ...body, messages: compressedBody },
stats: {
originalTokens: Math.ceil(originalLength / 4),
compressedTokens: Math.ceil(compressedLength / 4),
savingsPercent: originalLength > 0 ? 100 * (1 - compressedLength / originalLength) : 0,
techniques: ["whitespace-collapse"],
engineId: "whitespace",
},
};
},
getConfigSchema() {
return [
{
key: "preserveCodeBlocks",
type: "boolean",
label: "Preserve code blocks",
defaultValue: true,
description: "Don't touch whitespace inside ```code``` blocks",
},
];
},
validateConfig(config) {
if (config.preserveCodeBlocks !== undefined && typeof config.preserveCodeBlocks !== "boolean") {
return { valid: false, errors: ["preserveCodeBlocks must be a boolean"] };
}
return { valid: true, errors: [] };
},
};
// በዓለም አቀፍ ደረጃ ይመዝገቡ
registerCompressionEngine(whitespaceEngine);
````
### ብጁ ሞተሮችን የሚያስቀምጡበት ቦታ
```
~/.omniroute/compression/engines/my-engine.ts # የተጠቃሚ ደረጃ
<project>/compression-engines/my-engine.ts # የፕሮጀክት ደረጃ (ሲጀመር የሚጫን)
```
ወይም ከፕለጊን በፕሮግራም ይጫኑ፦
```ts
// በፕለጊንዎ ውስጥ
import {
registerCompressionEngine,
unregisterCompressionEngine,
} from "@omniroute/open-sse/services/compression/engines/registry";
import { myEngine } from "./engines/my-engine";
export default definePlugin({
name: "my-compression-plugin",
// የፕለጊኑ SDK የonRequest / onResponse / onError ማያያዣዎችን ያቀርባል።
// የፕለጊኑ ሞጁል ሲጫን (ወይም በመጀመሪያው onRequest) ሞተሩን ይመዝግቡ፤
// ከራስዎ የማፍረሻ መንገድ ደግሞ ምዝገባውን ይሰርዙ።
onRequest: async (ctx) => {
registerCompressionEngine(myEngine);
},
});
// በማፍረስ ጊዜ፦
// unregisterCompressionEngine("my-engine");
```
### ሞተርዎን መፈተሽ
ሞተርዎን በፕለጊን ወይም በማስጀመሪያ ፋንክሽን ውስጥ ይመዝግቡ። አንዴ ከተመዘገበ፣ ሞተሩ በ`id` አማካኝነት በስትራቴጂ መምረጫው ውስጥ ይገኛል። በተደራራቢ የማስኬጃ መስመር ውስጥ በማቀናበር ውህደቱን ይፈትሹ፦
---
## የቋንቋ ጥቅሎችን መፍጠር
የCaveman ቅጥ መጭመቅ በእያንዳንዱ ተፈጥሯዊ ቋንቋ ውስጥ ሙሌት ቃላትን፣ አሻሚ አገላለጾችን እና ረዥም የአጻጻፍ ንድፎችን ለመቆጣጠር **ለቋንቋው የተወሰኑ የደንብ ጥቅሎችን** ይጠቀማል። OmniRoute ከ**6 የቋንቋ ጥቅሎች** ጋር ይቀርባል፦ `en`፣ `es`፣ `fr`፣ `de`፣ `ja`፣ `pt-BR`።
### የጥቅል መዋቅር
የቋንቋ ጥቅል በ`open-sse/services/compression/rules/<language>/` ስር ያሉ **JSON ፋይሎች** ማውጫ ነው፦
```
open-sse/services/compression/rules/
├── en/
│ ├── filler.json # ሰላምታዎች፣ አሻሚ አገላለጾች፣ ጨዋነት
│ ├── context.json # ዐውድን የሚቀንሱ ደንቦች
│ ├── dedup.json # ብዜትን የማስወገድ ደንቦች
│ ├── structural.json # ሥርዓተ ነጥብ፣ ቅርጸት
│ └── ultra.json # ኃይለኛ የመጭመቅ ደንቦች
├── es/ (ተመሳሳይ መዋቅር)
├── fr/ (ተመሳሳይ መዋቅር)
├── de/ (ተመሳሳይ መዋቅር)
├── ja/ (ተመሳሳይ መዋቅር)
└── pt-BR/ (ተመሳሳይ መዋቅር)
```
### የደንብ አወቃቀር
እያንዳንዱ ደንብ ይህን ቅርጽ አለው (ከ`open-sse/services/compression/ruleLoader.ts`)፦
```ts
interface FileRule {
name: string; // ለሰው የሚነበብ ስም (kebab-case)
pattern: string; // JavaScript regex ንድፍ
replacement?: string; // ተዛማጁ የሚተካበት ይዘት
replacementMap?: Record<string, string>; // ወይም የቁልፍ→ምትክ ካርታ
flags?: string; // Regex ሰንደቆች (በተለምዶ "gi")
context?: "all" | "user" | "system" | "assistant";
category?: "filler" | "context" | "structural" | "dedup" | "terse" | "ultra";
minIntensity?: "lite" | "full" | "ultra"; // ከዚህ የጥንካሬ ደረጃ በታች ከሆነ ዝለል
description?: string; // ሰነድ
}
```
### ምሳሌ፦ የሂንዲ ሙሌት ደንቦችን መጨመር
```json
{
"language": "hi",
"category": "filler",
"rules": [
{
"name": "polite_opener",
"pattern": "\\b(?:नमस्ते|नमस्कार|आदरणीय)\\b[,!\\s]*",
"replacement": "",
"context": "all",
"category": "filler",
"minIntensity": "lite",
"description": "እንደ 'नमस्ते' ያሉ የጨዋነት መክፈቻዎችን አስወግድ"
},
{
"name": "filler_actually",
"pattern": "\\b(?:असल में|वास्तव में|दरअसल)\\b\\s*",
"replacement": "",
"context": "all",
"category": "filler",
"minIntensity": "lite",
"description": "የ'actually' ሙሌት ቃላትን አስወግድ"
},
{
"name": "verbose_plea",
"pattern": "\\b(?:कृपया|कृपया आप|अनुरोध है कि आप)\\b\\s*",
"replacement": "",
"context": "all",
"category": "filler",
"minIntensity": "full",
"description": "በሂንዲ ውስጥ 'please'ን አስወግድ"
}
]
}
```
### ማረጋገጫ
የደንብ ጥቅሎች በሚጫኑበት ጊዜ ከ`_schema.json` ጋር ይረጋገጣሉ። የተሳሳተ መዋቅር ያለው ጥቅል መጫን ይሳነዋል እና ስህተት ይመዘገባል፦
```
RULE_LOADER: የ"hi/filler.json" ጥቅል ማረጋገጫው አልተሳካም፦
- rules.0.pattern: ልክ ያልሆነ regex
- rules.1.context: ከ[all, user, system, assistant] አንዱ መሆን አለበት
```
ማረጋገጫው ጥቅል ሲጫን (ከ`_schema.json` ጋር) በራስ-ሰር ይከናወናል፤
ልክ ያልሆነ ጥቅል ውድቅ ይደረጋል እና ከላይ ያለው ስህተት ይመዘገባል። ለጥቅል
ማረጋገጫ የተለየ `npm run` ስክሪፕት የለም—ጥቅሉን ይጫኑ (ለምሳሌ፣ ሰርቨሩን ያስጀምሩ ወይም
የመጭመቂያ መንገዱን ያስኬዱ) እና መዝገቦቹን ይከታተሉ።
### ብጁ የቋንቋ ጥቅል መጫን
```ts
import { loadRulePack } from "omniroute/compression/ruleLoader";
await loadRulePack("./my-custom-rules/hi/filler.json");
```
ወይም ዕውቅና ባለው ቦታ ያስቀምጡት፦
```
~/.omniroute/compression/rules/hi/filler.json # የተጠቃሚ ደረጃ
<project>/.compression/rules/hi/filler.json # የፕሮጀክት ደረጃ
```
### ለቋንቋ ጥቅሎች ምርጥ ልምዶች
1. **በ`filler` ይጀምሩ**—እነዚህ ከፍተኛው ተፅዕኖ ያላቸው ደንቦች ናቸው
2. **ኃይለኛ ደንቦችን ለመገደብ `minIntensity`ን ይጠቀሙ**—ከመጠን በላይ መጭመቅን ይከላከላል
3. **የሙከራ ኬዞችን ያካትቱ**—ባህሪውን ለማረጋገጥ በJSON ውስጥ `tests[]` ድርድር ይጨምሩ
4. **ቅደም ተከተል አስፈላጊ ነው**—ቀደም ያሉ ደንቦች መጀመሪያ ይተገበራሉ፤ ከፍተኛ ተፅዕኖ ያላቸውን ደንቦች መጀመሪያ ያስቀምጡ
5. **`replacement`ን በጥንቃቄ ይጠቀሙ**—ባዶ ሕብረቁምፊ በአብዛኛው ትክክለኛ ነው፤ በፍጹም አዲስ ይዘት አያስገቡ
### የትርጉም ስትራቴጂ
የደንብ ጥቅሎችን ለአዲስ ቋንቋ ሲያካባቢያዊ ያደርጉ፦
1. **የደንብ ስሞቹን ይተርጉሙ**—በdebug ውጤት ውስጥ ይታያሉ
2. **የregex ንድፎቹን ያስማሙ**—ቀጥተኛ ትርጉም ብዙ ጊዜ አይሰራም (የቃላት ወሰኖች ይለያያሉ)
3. **በእውነተኛ ውይይቶች ይፈትኑ**—ጥቅሉ በተጨባጭ ግብዓት ላይ ደህንነቱ የተጠበቀ መሆን አለበት
4. **ከባህላዊ ልማዶች ጋር ያዛምዱ**—ለምሳሌ፣ የጃፓንኛ ጥቅሎች ከእንግሊዝኛ የበለጠ የክብር መግለጫ ሙሌቶች አሏቸው
---
## የተደራረቡ ፓይፕላይኖች
**የተደራረበ ፓይፕላይን** በርካታ ኤንጂኖችን በቅደም ተከተል ያስኬዳል፤ የእያንዳንዱ ኤንጂን ውጤትም ለቀጣዩ ግብዓት ይሆናል። `mode: stacked` በውስጣዊ አሠራሩ የሚሰራው በዚህ መንገድ ነው።
### መደራረብ እንዴት እንደሚሰራ
```
ግብዓት (10,000 ቶከኖች)
│
▼
┌──────────┐
│ ኤንጂን │ ቅድሚያ 10
│ A │ ──▶ ውጤት: 6,000 ቶከኖች (-40%)
└────┬─────┘
▼
┌──────────┐
│ ኤንጂን │ ቅድሚያ 50
│ B │ ──▶ ውጤት: 2,400 ቶከኖች (-60%)
└────┬─────┘
▼
┌──────────┐
│ ኤንጂን │ ቅድሚያ 100
│ C │ ──▶ ውጤት: 1,200 ቶከኖች (-80%)
└────┬─────┘
│
▼
የመጨረሻ ውጤት (1,200 ቶከኖች፣ በድምሩ ~88% ቁጠባ)
```
`mode: "stacked"` ሲመረጥ፣ ኤንጂኖቹ በ`pipeline` ድርድር ውስጥ በተገለጸው ቅደም ተከተል አንድ በአንድ ይፈጸማሉ።
የኤንጂን N ውጤት የኤንጂን N+1 ግብዓት ይሆናል።
### የመጭመቂያ ሁነታዎች
OmniRoute በውቅር፣ ራስ-ሰር ማስጀመሪያ ገደቦች እና የጥምር ለውጦች መሠረት **ለእያንዳንዱ ጥያቄ አንድ ሁነታ** ይመርጣል።
የሚገኙት ሁነታዎች በ`open-sse/services/compression/types.ts` (`CompressionMode` ዓይነት) ውስጥ ተገልጸዋል፦
| ሁነታ | ኤንጂኖች | የአጠቃቀም ሁኔታ |
| ------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `off` | ምንም | ሁሉንም መጭመቅ ያሰናክሉ |
| `rtk` | RTK ብቻ | የትዕዛዝ ውጤት የበዛባቸው ክፍለ ጊዜዎች (80%+ ቁጠባ) |
| `lite` | Lite ብቻ | ጥንቃቄ የተሞላበት መጭመቅ (ፈጣን፣ አስተማማኝ) |
| `standard` | Caveman | ከቋንቋ ጥቅሎች ጋር የጽሑፍ መጭመቅ |
| `aggressive` | Caveman + Aggressive | ከፍተኛ የጽሑፍ መጭመቅ + ከፍተኛ የመጨረሻ ዙር |
| `ultra` | Ultra | ከፍተኛው መጭመቅ (መረጃ ሊያጠፋ የሚችል፣ እንደ የመጨረሻ አማራጭ)። `ultra.modelPath` ሲዋቀር፣ እንደ አማራጭ በ**LLMLingua-2** SLM ኤንጂን በኩል ይመራል (ሞዴሉ ከሌለ ወደ በደንብ-ላይ-የተመሠረተው መንገድ ይመለሳል)። |
| `stacked` | ብጁ ፓይፕላይን | ኤንጂኖችን በማንኛውም ቅደም ተከተል ያቀናብሩ (ከታች ይመልከቱ) |
> ከላይ ከተጠቀሱት የሁነታ ኤንጂኖች በተጨማሪ፣ መዝገቡ ሊደራረቡ የሚችሉ ልዩ ኤንጂኖችንም ያካትታል —
> **CCR**፣ **headroom**፣ **ionizer** እና **session-dedup** — እነዚህም በ
> [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md#additional-built-in-engines) ውስጥ ተመዝግበዋል።
የሁነታ ምርጫ የሚወሰነው በ`open-sse/services/compression/strategySelector.ts` ውስጥ ባለው `getEffectiveMode()` ነው፦
1. መጭመቅ ከተሰናከለ፦ `"off"`
2. የጥምር ለውጥ ካለ፦ ለውጡን ይጠቀሙ
3. የራስ-ሰር ማስጀመሪያ ገደብ ከታለፈ፦ `autoTriggerMode`ን ይጠቀሙ (ነባሪ፦ `"lite"`)
4. ካልሆነ፦ `defaultMode`ን ይጠቀሙ
### ነባሪው የተደራረበ ፓይፕላይን
`mode: "stacked"` በግልጽ ሲዋቀር፣ ነባሪው ፓይፕላይን የሚከተሉትን ያቀናብራል፦
1. **RTK** — የትዕዛዝ ውጤት ጫጫታን ያስወግዳል (በተርሚናል ውጤት ላይ ~80% ቁጠባ)
2. **Caveman** — አላስፈላጊ ቃላትን ያስወግዳል፣ ጽሑፉን አጭር ያደርጋል (ከቀረው ጽሑፍ ~46%)
3. **Lite** — የመጨረሻ ነጭ ቦታ + ድግግሞሽ ማስወገጃ ዙር
ይህ ጥምረት ብዙ መሣሪያዎች በሚጠቀሙ ክፍለ ጊዜዎች ላይ **78-95% ቁጠባ** ያስገኛል።
### የተደራረቡ ፓይፕላይኖችን ማዋቀር
በጥምር ውቅር ውስጥ፦
```json
{
"compression": {
"mode": "stacked",
"pipeline": [
{ "engine": "rtk", "config": { "intensity": "aggressive" } },
{ "engine": "caveman", "config": { "intensity": "full" } },
{ "engine": "lite", "config": {} }
]
}
}
```
ኤንጂኖችን መተው፣ ብጁ ኤንጂኖችን ማከል ወይም ቅደም ተከተላቸውን መለወጥ ይችላሉ።
### ሁኔታን ማስተላለፍ
ኤንጂኖች ከጥያቄው አውድ (በ`options` ውስጥ) ሜታዳታን ማንበብ ይችላሉ፦
```ts
compress(body, config) {
// ከቀደሙት ኤንጂኖች ሜታዳታን ያንብቡ
const original = options?.compressionComboId; // "my-coding-combo"
// ...
}
```
ሜታዳታው **ለንባብ ብቻ** ነው — ኤንጂኖች የጥያቄውን አውድ መቀየር አይችሉም፤ የራሳቸውን የይዘት ውጤት ብቻ መቀየር ይችላሉ።
### የአፈጻጸም ቅደም ተከተል ላይ ሊያጋጥሙ የሚችሉ ችግሮች
| የኤንጂን ቅደም ተከተል | ውጤት |
| ----------------------------------------- | ------------------------------------------------------------------- |
| RTK → Caveman → Lite | **የሚመከር** (በመጀመሪያ ጫጫታን፣ ቀጥሎ ቋንቋን፣ ከዚያም ነጭ ቦታን ያስወግዳል) |
| Lite → RTK → Caveman | መጥፎ — Lite ከጥሬ ውጤት ነጭ ቦታን ስለሚያስወግድ የRTK የስርዓተ-ጥለት ማዛመድ እንዳይሰራ ያደርጋል |
| Caveman → RTK | መጥፎ — Caveman ጽሑፉን RTK ሊያውቀው በማይችልበት መንገድ እንደገና ሊጽፈው ይችላል |
| `tool_results` በመጀመሪያ ያለበት ማንኛውም ቅደም ተከተል | የተሻለ — የመሣሪያ ውጤት ከሁሉም የበለጠ ጫጫታ ያለው ይዘት ነው |
### መቼ መደራረብ እንደሌለበት
መደራረብ ሁልጊዜ የተሻለ አይደለም፦
- **ቀላል መልዕክቶች** (የመሣሪያ ውጤት የሌላቸው) — Caveman ወይም Lite ብቻ በቂ ነው
- **ወጪን የሚያስቀድሙ** — እያንዳንዱ ኤንጂን ~5-50ms መዘግየት ይጨምራል
- **የተወሰኑ መሣሪያዎች** — ለሼል ውጤት ብዙውን ጊዜ RTK ብቻ በቂ ነው
### ብጁ ፓይፕላይን መገንባት
የተሰየመ የpipeline መዝገብ የለም። stacked pipeline ማለት ለ`applyStackedCompression()` (ከ`@omniroute/open-sse/services/compression/strategySelector` የሚላክ) የሚተላለፍ **inline የደረጃዎች array** ብቻ ነው፦
```ts
import { applyStackedCompression } from "@omniroute/open-sse/services/compression/strategySelector";
const result = applyStackedCompression(body, [
{ engine: "rtk", intensity: "aggressive" },
{ engine: "caveman", intensity: "full" },
]);
```
pipeline ካላስተላለፉ፣ በነባሪ `rtk(standard) → caveman(full)` ይጠቀማል።
ከውቅር ለመቆጣጠር፣ `mode: "stacked"` ያዘጋጁ እና የደረጃዎቹን array በ`stackedPipeline` ስር ያቅርቡ (ከ`config.stackedPipeline` ይነበባል)፦
```json
{
"compression": {
"mode": "stacked",
"stackedPipeline": [
{ "engine": "rtk", "intensity": "aggressive" },
{ "engine": "caveman", "intensity": "full" }
]
}
}
```
---
## የዋና ምንጭ ማመሳሰል ፖሊሲ
የOmniRoute ማመቂያ ሞተሮች README ውስጥ ለበርካታ የዋና ምንጭ ፕሮጀክቶች
ዕውቅና ይሰጣሉ
("በRTK፣ Caveman፣ LLMLingua-2፣ Troglodita የተነሳሳ")። አበርካቾች በተደጋጋሚ
የሚጠይቁት ጥያቄ፦ **ዋናው RTK አዲስ የመሣሪያ ማጣሪያ ሲጨምር ወይም Caveman የደንብ
ጥቅል ሲጨምር፣ ያ ወደ OmniRoute እንዴት ይደርሳል?** ይህ ክፍል በጉዳዩ ላይ ሥልጣን ያለው መልስ ነው።
### በፕሮጀክቱ ውስጥ የተካተቱ ቅጂዎች ከገለልተኛ ትግበራዎች ጋር ሲነጻጸሩ
| ሞተር | ከዋናው ምንጭ ጋር ያለው ግንኙነት | አካባቢ |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| **RTK** | **ገለልተኛ ዳግም ትግበራ** (በእሱ የተነሳሳ እንጂ ቅጂ አይደለም) | `open-sse/services/compression/engines/rtk/` |
| **Caveman** | **ገለልተኛ ዳግም ትግበራ** (በእሱ የተነሳሳ) | `open-sse/services/compression/engines/cavemanAdapter.ts` |
| **Headroom** | በአብዛኛው ውስጣዊ ነው፤ ከ`gcf-typescript` **በእውነት የተካተተው** የ`gcf/` ኮዴክ ብቻ ነው (MIT፣ SPDX ምልክት የተደረገበት፣ አጠቃላይ መገለጫ ብቻ) | `open-sse/services/compression/engines/headroom/gcf/` |
| **LLMLingua-2 / Troglodita** | በእነሱ የተነሳሳ (የ`llmlingua` + `session-dedup` ሞተሮችን ያንቀሳቅሳሉ) | `open-sse/services/compression/engines/llmlingua/`, `session-dedup` |
ዋናው ነጥብ፦ **RTK እና Caveman የ_ሐሳቦቹ\_ (የማጣሪያ ደንቦች፣ የደንብ ጥቅሎች)
ከባዶ የተገነቡ TypeScript ትግበራዎች ናቸው እንጂ በፕሮጀክቱ ውስጥ የተካተቱ የምንጭ ዛፎች አይደሉም።** `git pull` ማድረግ
የሚቻልበት የዋና ምንጭ ቅጂ የለም — README "bundled" ከማለት ይልቅ
"inspired by" የሚለውም በትክክል ለዚህ ነው።
### የዋና ምንጭ ማሻሻያዎች እንዴት እንደሚዋሃዱ
**ራስ-ሰር የዋና ምንጭ ልቀት ክትትል እና `compression-sync`
መለያ የለም** — ይህም ሆን ተብሎ ነው። ሞተሮቹ ዳግም ትግበራዎች ስለሆኑ፣ የዋናው RTK
ማጣሪያ ወይም የCaveman ደንብ ጥቅል እንደ ኮድ አይዋሃድም፤ ይልቁንም **በOmniRoute የራሱ ቅርጸት እንደ አዲስ
ደንብ/ማጣሪያ ዳግም ይገለጻል** ([COMPRESSION_RULES_FORMAT.md](./COMPRESSION_RULES_FORMAT.md)ን ይመልከቱ) እና
በመደበኛ PR በየአጋጣሚው ይገባል። ከላይ ያሉት የማስፋፊያ ነጥቦች (ብጁ ሞተር፣ የቋንቋ ጥቅል፣ RTK ማጣሪያ)
አንድን ለማበርከት የተፈቀደው መንገድ ናቸው።
ይህንን ፍሰት በትክክል የሚያሳዩ የቅርብ ጊዜ ምሳሌዎች፦
- ለGradle እና `dotnet` የግንባታ ውፅዓት RTK ማጣሪያዎች (v3.8.42)
- ለkubectl / docker-build / composer / gh RTK ማጣሪያዎች (#2824)
- የCaveman የኢንዶኔዥያ ቋንቋ ጥቅል (#3975)፣ እንዲሁም የጀርመንኛ / ፈረንሳይኛ / ጃፓንኛ / ቻይንኛ ጥቅሎች
### Headroom (የግቤት ማመቂያ ፕሮክሲ)
Headroom **ሙሉ በሙሉ ውስጣዊ ነው** — በአንድ ስሪት ላይ የተቆለፈ የ`gcf` ኮዴክ ቅጽበተ-ቅጂ እና
የOmniRoute የራሱ `smartcrusher` / `toon` / `tabular` ንብርብሮች። ከተካተተው ቅጂ ባሻገር
ለመከታተል የቀጥታ ዋና ምንጭ የለም፤ ኮዴኩ ሲቀየር የ`gcf` ዝማኔዎች በእጅ ይታደሳሉ
እና ከማመቂያ በጀት መግቢያ (`check:compression-budget`) ጋር እንደገና ይረጋገጣሉ።
### በዋና ምንጭ የተነሳሳ ማሻሻያ ማቅረብ
1. **በፕሮጀክቱ ውስጥ ቅጂውን አታካትቱ** — የዋናውን ምንጭ ደንብ/ማጣሪያ በOmniRoute ቅርጸት ዳግም ይግለጹ።
2. ከታች ባለው ተዛማጅ የማስፋፊያ ነጥብ (የቋንቋ ጥቅል፣ RTK ማጣሪያ ወይም
ብጁ ሞተር) በኩል ያክሉት።
3. ፈቃድ የያዘውን ምንጭ ከመቅዳት ይልቅ በPR መግለጫው ውስጥ የዋናውን ምንጭ ፕሮጀክት ይጥቀሱ (ዕውቅና)።
4. ሙከራዎችን ያካትቱ እና የ`check:compression-budget` መግቢያ አሁንም እንደሚያልፍ ያረጋግጡ።
---
## የውጤት ቅጥ ማከል
የውጤት ቅጦች (የ[መመሪያውን የካታሎግ ሰንጠረዥ](./COMPRESSION_GUIDE.md#output-styles-catalog) ይመልከቱ)
የግብዓት ሞተሮች በምላሽ በኩል ያላቸው አቻ ናቸው፦ እርስዎ የሚልኩትን ከመጭመቅ ይልቅ፣ ሞዴሉ ወጪው ዝቅተኛ የሆነ ውጤት እንዲያመነጭ ያዝዛሉ። መዝገቡ
`OUTPUT_STYLE_CATALOG` ሲሆን በ`open-sse/services/compression/outputStyles/catalog.ts` ውስጥ ይገኛል፣ እና
**አንድ የካታሎግ ግቤት ሙሉውን ባህሪ ይወክላል**፦ አስገቢው፣ የዳሽቦርድ ቅንብሮች ፓነሉ፣
ዘላቂ ማከማቻው እና ቴሌሜትሪው ሁሉም ካታሎጉን ይዘረዝራሉ — ማዘመን የሚያስፈልገው ሌላ ዝርዝር የለም።
1. **ወደ `OUTPUT_STYLE_CATALOG` አንድ ግቤት ያክሉ**፤ `id`፣ `label`፣ `description` እና
ሦስቱን የእንግሊዝኛ `levels` (`lite`፣ `full`፣ `ultra`) ያካትቱ። ኮድ፣ ዱካዎች፣ ትዕዛዞች፣ ስህተቶች እና URLs ሳይቀየሩ እንዲቆዩ እያንዳንዱ ደረጃ በ
`${SHARED_BOUNDARIES}` መጨረስ አለበት።
የመመሪያው ጽሑፍ ለእያንዳንዱ
`(id, level, language)` **ቋሚ እና የማይለዋወጥ** መሆን አለበት — የሚፈቀደው ብቸኛ ማስገባት `${SHARED_BOUNDARIES}` ነው።
2. **ይተርጉሙት።** ቢያንስ በ`i18n` ስር የ`pt-BR` ብሎክ ያቅርቡ፤ `ponytail` እና
`i-have-adhd` (en፣ pt-BR፣ es፣ de፣ fr፣ it፣ ru፣ zh፣ ja፣ id፣ vi) የማጣቀሻ ቅርጽ ናቸው። ሆን ብሎ ለአንድ ቋንቋ ብቻ የተዘጋጀ ቅጥ በምትኩ `locale` ያቀናብራል (እንደ `terse-cjk` → `zh`)፣ ከዚያም በዚያ አካባቢያዊ ቋንቋ ስር ብቻ ይቀርባል።
3. **የማትሪክስ ጥበቃውን ያዘምኑ** — የቅጡን ቋንቋዎች በ
`tests/unit/compression/output-styles-i18n-matrix.test.ts` ውስጥ ወዳለው `BASELINE_LANGUAGES` ያክሉ። ግልጽ የሆነ፣ የመከታተያ ጉዳይ ያለው
`KNOWN_ENGLISH_ONLY` ግቤት ካልያዘ፣ መግቢያ በአካባቢያዊ ቋንቋ ያልተገደበ እና አስፈላጊዎቹ ትርጉሞች የሌሉት ማንኛውም አዲስ ቅጥ ጌቱን እንዳያልፍ ያደርጋል።
4. **ለእያንዳንዱ ቅጥ ሙከራ ያክሉ**፤
`tests/unit/compression/i-have-adhd-catalog.test.ts`ን እንደ አብነት ይጠቀሙ፦ የካታሎግ ቅርጽ፣ በእያንዳንዱ ደረጃ የድንበር አንቀጽ፣ እና እያንዳንዱ ትርጉም ከእንግሊዝኛ ከመቅዳት ይልቅ በራሱ ቋንቋ መጻፉን የሚያረጋግጥ መልህቅ።
5. **ምንጭ መጥቀስ**፦ ቅጡ ከሌላ የላይኛው ፕሮጀክት የተወሰደ ከሆነ፣ በግቤቱ ላይ ባለ የምንጭ አስተያየት ውስጥ እውቅና ይስጡ (ለምሳሌ፦ `i-have-adhd` → ayghri/i-have-adhd, MIT) — ከላይ ካለው "Proposing an upstream-inspired improvement" ጋር ተመሳሳይ ደንብ ነው።
ምንም የUI፣ የስኪማ ወይም የቴሌሜትሪ ለውጥ አያስፈልግም — እነዚያ ገጽታዎች ከካታሎጉ ይቀርባሉ።
---
## ምርጥ ልምዶች
### የሞተር ልማት
1. **ሁልጊዜ `validateConfig`ን ይተግብሩ** — ማረጋገጫ የሌላቸው ሞተሮች በዝምታ ውድቀቶችን ያስከትላሉ
2. **ተጨባጭ `targetLatencyMs` ያዘጋጁ** — ሞተሮችን ለመምረጥ በስትራቴጂ መራጩ ይጠቀምበታል
3. **ለዳሽቦርዱ `getConfigSchema`ን ይጠቀሙ** — ውቅረትን ከተጠቃሚዎች ፈጽሞ አይደብቁ
4. **ሞተርዎ ንጹሕ ከሆነ `stackable: true`ን ይደግፉ** — የጎንዮሽ ተጽዕኖ ያላቸው ሞተሮች መደራረብ የለባቸውም
5. **የመስመር ውስጥ ሙከራዎችን ይጻፉ** — ሞተሮች በ<1s ውስጥ ሊረጋገጡ ይገባል
### የቋንቋ ጥቅል ልማት
1. **በ`lite` የጥንካሬ ደረጃ ይጀምሩ** — ደንቦችዎ በዝቅተኛው ቅንብር ደህንነታቸው የተጠበቀ መሆን አለባቸው
2. **ደንቦችን ለመወሰን `context`ን ይጠቀሙ** — `user` ብቻ የሆኑ ደንቦች በድንገት የስርዓት መመሪያዎችን ሊነኩ አይችሉም
3. **የJSON ቁልፎችን ከመያዝ ይቆጠቡ** — `\\bword\\b` በJSON ውስጥ ሊዛመድ እና የተዋቀረ ውሂብን ሊያበላሽ ይችላል
4. **በጠርዝ ሁኔታዎች ይሞክሩ** — ባዶ ግብዓት፣ unicode፣ RTL ጽሑፍ፣ ኢሞጂዎች
5. **ነባር ጥቅሎችን እንደ አብነት ይጠቀሙ** — `en/filler.json` እጅግ የበለጸገው ምሳሌ ነው
### የፓይፕላይን ንድፍ
1. **ከማመቻቸትዎ በፊት መገለጫ ያዘጋጁ** — መጀመሪያ በ`compression_stats` ይለኩ
2. **ዳግም ከመተግበር ይልቅ ማቀናበርን ይምረጡ** — አዲስ ሞተር ከመጻፍዎ በፊት የCaveman ደንቦችን ያስፋፉ
3. **የቅደም ተከተሉን ምክንያት ይመዝግቡ** — ሞተር A ከሞተር B በፊት ለምን እንደሚመጣ አስተያየት ይጻፉ
4. **በሦስቱም የጥንካሬ ደረጃዎች ይሞክሩ** — `lite` ፈጣን ነው ግን መረጃ ሊያጣ ይችላል፣ `ultra` ዘገምተኛ ነው ግን ትክክለኛ ነው
---
## ማጣቀሻ፦ አብሮገነብ ሞተሮች
| የሞተር ID | ተደራራቢ | ነባሪ stackPriority | ዒላማዎች |
| -------------------- | ----- | ----------------- | ---------------------------- |
| `lite` | አዎ | 5 | መልዕክቶች፣ የመሣሪያ ውጤቶች |
| `rtk` | አዎ | 10 | የመሣሪያ ውጤቶች |
| `standard` (caveman) | አዎ | 20 | መልዕክቶች፣ የመሣሪያ ውጤቶች፣ የኮድ ብሎኮች |
| `aggressive` | አዎ | 30 | መልዕክቶች |
| `ultra` | አዎ | 40 | መልዕክቶች፣ የኮድ ብሎኮች |
### በተጨማሪ ይመልከቱ
- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — የሂደት መስመሩ አጠቃላይ እይታ
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — የሞተር መዝገብ ማጣቀሻ
- [COMPRESSION_RULES_FORMAT.md](./COMPRESSION_RULES_FORMAT.md) — የደንብ ቅርጸት ዝርዝር መግለጫ
- [COMPRESSION_LANGUAGE_PACKS.md](./COMPRESSION_LANGUAGE_PACKS.md) — የቋንቋ ጥቅል ዝርዝሮች
- [RTK_COMPRESSION.md](./RTK_COMPRESSION.md) — RTK ሞተር እና ብጁ ማጣሪያዎች
- ምንጭ፦ `open-sse/services/compression/` (117 ፋይሎች፣ ~250KB)

698
docs/i18n/am/docs/compression/RTK_COMPRESSION.md Normal file
View File

@@ -0,0 +1,698 @@
# RTK Compression (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../compression/RTK_COMPRESSION.md) · 🇸🇦 [ar](../../../ar/docs/compression/RTK_COMPRESSION.md) · 🇦🇿 [az](../../../az/docs/compression/RTK_COMPRESSION.md) · 🇧🇬 [bg](../../../bg/docs/compression/RTK_COMPRESSION.md) · 🇧🇩 [bn](../../../bn/docs/compression/RTK_COMPRESSION.md) · 🇨🇿 [cs](../../../cs/docs/compression/RTK_COMPRESSION.md) · 🇩🇰 [da](../../../da/docs/compression/RTK_COMPRESSION.md) · 🇩🇪 [de](../../../de/docs/compression/RTK_COMPRESSION.md) · 🇬🇷 [el](../../../el/docs/compression/RTK_COMPRESSION.md) · 🇪🇸 [es](../../../es/docs/compression/RTK_COMPRESSION.md) · 🇪🇪 [et](../../../et/docs/compression/RTK_COMPRESSION.md) · 🇮🇷 [fa](../../../fa/docs/compression/RTK_COMPRESSION.md) · 🇫🇮 [fi](../../../fi/docs/compression/RTK_COMPRESSION.md) · 🇫🇷 [fr](../../../fr/docs/compression/RTK_COMPRESSION.md) · 🇮🇪 [ga](../../../ga/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [gu](../../../gu/docs/compression/RTK_COMPRESSION.md) · 🇳🇬 [ha](../../../ha/docs/compression/RTK_COMPRESSION.md) · 🇮🇱 [he](../../../he/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [hi](../../../hi/docs/compression/RTK_COMPRESSION.md) · 🇭🇷 [hr](../../../hr/docs/compression/RTK_COMPRESSION.md) · 🇭🇺 [hu](../../../hu/docs/compression/RTK_COMPRESSION.md) · 🇦🇲 [hy](../../../hy/docs/compression/RTK_COMPRESSION.md) · 🇮🇩 [id](../../../id/docs/compression/RTK_COMPRESSION.md) · 🇳🇬 [ig](../../../ig/docs/compression/RTK_COMPRESSION.md) · 🇮🇹 [it](../../../it/docs/compression/RTK_COMPRESSION.md) · 🇯🇵 [ja](../../../ja/docs/compression/RTK_COMPRESSION.md) · 🇬🇪 [ka](../../../ka/docs/compression/RTK_COMPRESSION.md) · 🇰🇭 [km](../../../km/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [kn](../../../kn/docs/compression/RTK_COMPRESSION.md) · 🇰🇷 [ko](../../../ko/docs/compression/RTK_COMPRESSION.md) · 🇱🇹 [lt](../../../lt/docs/compression/RTK_COMPRESSION.md) · 🇱🇻 [lv](../../../lv/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [ml](../../../ml/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [mr](../../../mr/docs/compression/RTK_COMPRESSION.md) · 🇲🇾 [ms](../../../ms/docs/compression/RTK_COMPRESSION.md) · 🇲🇹 [mt](../../../mt/docs/compression/RTK_COMPRESSION.md) · 🇲🇲 [my](../../../my/docs/compression/RTK_COMPRESSION.md) · 🇳🇵 [ne](../../../ne/docs/compression/RTK_COMPRESSION.md) · 🇳🇱 [nl](../../../nl/docs/compression/RTK_COMPRESSION.md) · 🇳🇴 [no](../../../no/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [or](../../../or/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [pa](../../../pa/docs/compression/RTK_COMPRESSION.md) · 🇵🇭 [phi](../../../phi/docs/compression/RTK_COMPRESSION.md) · 🇵🇱 [pl](../../../pl/docs/compression/RTK_COMPRESSION.md) · 🇵🇹 [pt](../../../pt/docs/compression/RTK_COMPRESSION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/RTK_COMPRESSION.md) · 🇷🇴 [ro](../../../ro/docs/compression/RTK_COMPRESSION.md) · 🇷🇺 [ru](../../../ru/docs/compression/RTK_COMPRESSION.md) · 🇱🇰 [si](../../../si/docs/compression/RTK_COMPRESSION.md) · 🇸🇰 [sk](../../../sk/docs/compression/RTK_COMPRESSION.md) · 🇸🇮 [sl](../../../sl/docs/compression/RTK_COMPRESSION.md) · 🇷🇸 [sr](../../../sr/docs/compression/RTK_COMPRESSION.md) · 🇸🇪 [sv](../../../sv/docs/compression/RTK_COMPRESSION.md) · 🇰🇪 [sw](../../../sw/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [ta](../../../ta/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [te](../../../te/docs/compression/RTK_COMPRESSION.md) · 🇹🇭 [th](../../../th/docs/compression/RTK_COMPRESSION.md) · 🇹🇷 [tr](../../../tr/docs/compression/RTK_COMPRESSION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/RTK_COMPRESSION.md) · 🇵🇰 [ur](../../../ur/docs/compression/RTK_COMPRESSION.md) · 🇺🇿 [uz](../../../uz/docs/compression/RTK_COMPRESSION.md) · 🇻🇳 [vi](../../../vi/docs/compression/RTK_COMPRESSION.md) · 🇳🇬 [yo](../../../yo/docs/compression/RTK_COMPRESSION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/RTK_COMPRESSION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/RTK_COMPRESSION.md)
---
RTK compression ለተርሚናል እና ለመሣሪያ ውጤት የተዘጋጀ የOmniRoute ትዕዛዝ-ተኮር የማመቅ ሞተር ነው። አብዛኛው የአውድ እድገት ከሙከራ ምዝግቦች፣ ከግንባታ ውጤት፣ ከፓኬጅ አስተዳዳሪ የተትረፈረፈ ውጤት፣ ከሼል ግልባጮች፣ ከDocker ውጤት፣ ከgit ውጤት እና ከቁልል ዱካዎች ለሚመጣባቸው የኮዲንግ-ወኪል ክፍለ ጊዜዎች የተነደፈ ነው።
RTK በቀጥታ በ`defaultMode: "rtk"` ወይም በተደራራቢ ቧንቧ መስመር ውስጥ እንደ መጀመሪያው ደረጃ ሊሠራ ይችላል፤ በተለምዶ፦
```txt
rtk -> caveman
```
ይህ ቅደም ተከተል በመጀመሪያ የተትረፈረፈውን የማሽን ውጤት ያመቃል፣ ከዚያም Caveman የቀረውን ጽሑፍ እንዲያጠቃልል ያስችለዋል።
የላይኛው ምንጭ RTK በትዕዛዝ ውጤት ላይ `60-90%` ቁጠባ እንዳለ ዘግቧል። በREADME ውስጥ ያለው የናሙና ክፍለ ጊዜ ከ`~118,000` መደበኛ ቶከኖች ወደ `~23,900` RTK ቶከኖች ይቀንሳል፤ ይህም `79.7%` ቁጠባ (`~80%`) ነው። OmniRoute ያንን የላይኛው ምንጭ አማካይ ከCaveman የግቤት ማመቅ ጋር ለተደራራቢው የቁጠባ ስሌት ይጠቀማል፦
```txt
የRTK አማካይ፦ 80% ተቆጥቧል
የCaveman ግቤት፦ 46% ተቆጥቧል
የተደራረበ፦ 1 - (1 - 0.80) * (1 - 0.46) = 89.2% ተቆጥቧል
ክልል፦ 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```
## የሚያመቃቸው ነገሮች
አብሮገነቡ ካታሎግ በአሁኑ ጊዜ በእነዚህ ምድቦች ውስጥ 49 ማጣሪያዎችን ይዟል፦
| ምድብ | ምሳሌዎች |
| --------- | ------------------------------------------------------------- |
| `git` | `git status`፣ `git branch`፣ `git diff`፣ `git log` |
| `test` | Vitest፣ Jest፣ Pytest፣ Playwright፣ የGo ሙከራዎች፣ የCargo ሙከራዎች |
| `build` | TypeScript፣ ESLint፣ Biome፣ Prettier፣ Vite፣ Webpack፣ Turbo፣ Nx |
| `package` | `npm install`፣ `npm audit`፣ `pip`፣ `uv sync`፣ Poetry፣ Bundler |
| `shell` | `ls`፣ `find`፣ `grep`፣ አጠቃላይ የሼል ምዝግቦች |
| `docker` | `docker ps`፣ የDocker ምዝግቦች |
| `infra` | Terraform፣ OpenTofu፣ `systemctl status` |
| `generic` | የJSON ውጤት፣ የቁልል ዱካዎች፣ የአጠቃላይ ውጤት ምትክ |
በ`open-sse/services/compression/engines/rtk/commandDetector.ts` ውስጥ ያለው ፈላጊ ማጣሪያ ከመመረጡ በፊት ውጤቱን ይመድባል። የትዕዛዝ ክፍል ብቻውን በቂ በማይሆንበት ጊዜ ማጣሪያዎች በትዕዛዝ ንድፍ ወይም በውጤት regex መሠረትም ማዛመድ ይችላሉ።
## የማጣሪያ መፍትሔ ሂደት
RTK ማጣሪያዎችን በዚህ ቅደም ተከተል ይጭናል፦
1. የፕሮጀክት ማጣሪያዎች ከ`.rtk/filters.toml` እና `.rtk/filters.json`፣ የታመኑ ሲሆኑ ብቻ።
2. ዓለም አቀፍ ማጣሪያዎች ከ`DATA_DIR/rtk/filters.toml` እና `DATA_DIR/rtk/filters.json`።
3. አብሮገነብ ማጣሪያዎች ከ`open-sse/services/compression/engines/rtk/filters/`።
በተመሳሳይ ወሰን ውስጥ፣ የRTK TOML schema v1 ማጣሪያዎች ከOmniRoute JSON ማጣሪያዎች ቅድሚያ ያገኛሉ። ከውጭ የመጣ ትዕዛዝ-ተኮር ማጣሪያ በዚያ ወሰን ውስጥ ያለን ይበልጥ ሰፊ ማጣሪያ እንዲተካ፣ የTOML `match_command` አገላለጾች ከትዕዛዝ-ዓይነት ማዛመድ በፊት ይፈተሻሉ። የፕሮጀክት ወሰን የፋይል ቅርጸቱ ምንም ይሁን ምን ከዓለም አቀፍ ወሰን ቅድሚያ ያገኛል።
የregex ማጣሪያዎች የመሣሪያ ውጤት ለወኪሎች የሚታይበትን መንገድ ሊቀይሩ ስለሚችሉ፣ የፕሮጀክት ማጣሪያዎች ሆን ተብሎ በእምነት ማረጋገጫ ተገድበዋል። ከእነዚህ አንዱ እውነት ሲሆን የፕሮጀክት ማጣሪያ ፋይል ተቀባይነት ያገኛል፦
- `rtkConfig.trustProjectFilters` `true` ነው።
- `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1` ተቀናብሯል።
- `.rtk/trust.json` ለፕሮጀክቱ ማጣሪያ ፋይል ተዛማጅ የSHA-256 hash ይዟል።
የእምነት ፋይል ምሳሌ፦
```json
{
"filtersSha256": "0123456789abcdef...",
"filtersTomlSha256": "fedcba9876543210..."
}
```
hash-ዎቹ የተለያዩ ናቸው፦ `filtersSha256` `.rtk/filters.json`ን ያምናል፣ `filtersTomlSha256` ደግሞ `.rtk/filters.toml`ን ያምናል። ከሁለቱ ፋይሎች አንዱን ማርትዕ የራሱን የእምነት ግቤት ብቻ ዋጋ ያሳጣል። ዓለም አቀፍ ፋይሎች በአስተዳዳሪ የተጫኑ ሲሆኑ ነባሩን የዓለም አቀፍ ማጣሪያ የእምነት ባህሪ ይጠቀማሉ።
ብጁ ማጣሪያዎች አንድ የማጣሪያ ነገር ወይም የማጣሪያ ነገሮች ድርድር ሊሆኑ ይችላሉ። ልክ ያልሆኑ ብጁ ማጣሪያዎች ይዘለላሉ እና በ`/api/context/rtk/filters` ምርመራዎች ሪፖርት ይደረጋሉ። ልክ ያልሆኑ አብሮገነብ ማጣሪያዎች ወዲያውኑ እንዲቋረጥ ያደርጋሉ።
## RTK TOML schema v1 ተኳኋኝነት
OmniRoute RTK TOML schema v1ን የሚጠቀሙ መግለጫዊ የማጣሪያ ፋይሎችን መተንተን፣ ማረጋገጥ፣ መፈተሽ እና መጫን ይችላል።
የሚደገፉት መስኮች `description`፣ `match_command`፣ `strip_ansi`፣ `filter_stderr`፣
`strip_lines_matching`፣ `keep_lines_matching`፣ `replace`፣ `match_output`፣ `truncate_lines_at`፣
`head_lines`፣ `tail_lines`፣ `max_lines`፣ `on_empty` እና `[[tests.<filter>]]` የውስጥ መስመር ፈተናዎች ናቸው።
ያልታወቁ መስኮች፣ ልክ ያልሆኑ ወይም ደህንነታቸው ያልተጠበቀ መደበኛ አገላለጾች፣ በአንድ ጊዜ የሚገለጹ የማስወገጃ/ማቆያ ደንቦች፣
ከ1 MiB በላይ የሆኑ ፋይሎች እና ያልታወቁ ማጣሪያዎችን የሚጠቅሱ ማጣቀሻዎች ውድቅ ይደረጋሉ። የውስጥ መስመር ፈተናዎቹ ያልተሳኩበት ፋይል ለምርመራ
ሊረጋገጥ ይችላል፣ ነገር ግን ሊጫን ወይም ወደ ስርዓቱ ሊገባ አይችልም። ብጁ ፋይልን ወደ ስርዓቱ ማስገባት ሲሳነው
ሁኔታው fail-open ሆኖ ይቀጥላል፦ ልክ ያልሆነው ፋይል ይዘለላል፣ ቀሪዎቹ ማጣሪያዎችም መስራታቸውን ይቀጥላሉ።
OmniRoute የመሣሪያውን ውፅዓት የሚቀበለው ደንበኛው አስቀድሞ ከያዘው በኋላ ስለሆነ፣ `filter_stderr = true`
የሂደቱን መያዝ ሊለውጥ አይችልም። መስኩ ምንም እርምጃ እንደማይወስድ ሆኖ ተቀባይነት ያገኛል፣ ማረጋገጡም ማስጠንቀቂያ ይመልሳል።
ይህ ሆን ተብሎ **RTK TOML schema v1 ተኳኋኝነት** ተብሎ ይገለጻል፤ ከRTK አስፈጻሚ ፋይል፣ shell hooks፣ Rust የትዕዛዝ ትግበራዎች ወይም የtrust-store አቀማመጡ ጋር ሙሉ ተኳኋኝነት እንዳለው አይገልጽም።
የዳሽቦርዱ የላቀ RTK እይታ የተለጠፈ ወይም የተሰቀለ TOML ይቀበላል። ማረጋገጡ ለንባብ ብቻ ነው።
መጫኑ `DATA_DIR/rtk/filters.toml`ን በጥብቅ ፈቃዶች በአቶሚክ መንገድ ይጽፋል፣ እንደገና ማስጀመር ሳያስፈልግም
ቀጥታ የሚሰራውን የማጣሪያ ካታሎግ ያድሳል። ነባር ፋይልን ለመተካት ግልጽ የ`overwrite`
ማረጋገጫ ያስፈልጋል፣ እንዲሁም በመጀመሪያ `DATA_DIR/rtk/filters.toml.bak`ን ይፈጥራል።
## የማጣሪያ DSL
ማጣሪያዎች በ[Compression Rules Format](./COMPRESSION_RULES_FORMAT.md) የተገለጸውን JSON schema ይጠቀማሉ።
runtime እነዚህን ደረጃዎች በቅደም ተከተል ይተገብራል፦
```txt
stripAnsi -> filterStderr -> replace -> matchOutput -> drop/include lines
-> truncateLineAt -> head/tail/maxLines -> onEmpty
```
አስፈላጊ መስኮች፦
| መስክ | ዓላማ |
| ---------------------------- | ------------------------------------------------ |
| `rules.stripAnsi` | ከማዛመድ በፊት የተርሚናል ቀለም/መቆጣጠሪያ ተከታታዮችን ማስወገድ |
| `rules.filterStderr` | ከማዛመድ/ማጣራት በፊት የተለመዱ stderr ቅድመ ቅጥያዎችን ወጥ ማድረግ |
| `rules.replace` | በቅደም ተከተል የተቀመጡ የregex ምትክ ለውጦችን መተግበር |
| `rules.matchOutput` | ውፅዓቱ ከታወቀ ሁኔታ ጋር ሲዛመድ የታመቀ ማጠቃለያ መመለስ |
| `rules.matchOutput[].unless` | የስህተት/ውድቀት ጥለት ሲኖር አቋራጩን መዝለል |
| `rules.dropPatterns` | ጫጫታ የበዛባቸውን መስመሮች ማስወገድ |
| `rules.includePatterns` | ተግባራዊ እርምጃ ሊወሰድባቸው ለሚችሉ መስመሮች ቅድሚያ መስጠት |
| `rules.collapsePatterns` | ተደጋጋሚ የሚዛመዱ መስመሮችን ማጠቃለል |
| `rules.deduplicate` | ለእያንዳንዱ ማጣሪያ በተናጠል የሚነቃ፦ ተከታታይ የተባዙ መስመሮችን ማጠቃለል |
| `rules.truncateLineAt` | Unicodeን በማይጎዳ መንገድ እያንዳንዱን መስመር መቁረጥ |
| `rules.onEmpty` | ሁሉም መስመሮች ከተጣሩ የሚታይ አማራጭ መልዕክት |
| `tests[]` | በማረጋገጫ ደረጃው የሚጠቀሙ የውስጥ መስመር ናሙናዎች |
አብረው የተካተቱ ማጣሪያዎች የውስጥ መስመር `tests[]` ናሙናዎችን እንዲያካትቱ ይጠበቃል። ብጁ ማጣሪያዎችም
እነዚህን ማካተት አለባቸው፣ በተለይም በተለያዩ ፕሮጀክቶች መካከል ሲጋሩ።
## የመስመር ብዜት ማስወገድ (ሁለት ደረጃዎች)
RTK የተደጋገሙ መስመሮችን በሁለት እርስ በርሳቸው ነጻ በሆኑ ደረጃዎች ያጣምራል፦
1. **በእያንዳንዱ ማጣሪያ `deduplicate` (በምርጫ የሚነቃ፣ ነባሪው `false`)።** አንድ ማጣሪያ `rules.deduplicate: true`
በማዘጋጀት፣ ከመቆረጡ በፊት _ከዚያ ማጣሪያ ጋር በተዛመደው ውጤት ውስጥ_ ያሉ ተከታታይ የተባዙ መስመሮችን ማጣመር ይችላል።
ይህ በ`lineFilter.ts` ውስጥ ይከናወናል። ለቀድሞ ማጣሪያዎች፣ ማጣሪያው
`collapsePatterns` ን ሲገልጽ በራስ-ሰር ይነቃል። መርሃግብር፦ `deduplicate: z.boolean().default(false)` በ
`open-sse/services/compression/engines/rtk/filterSchema.ts` ውስጥ።
2. **የመተግበሪያ ሞተሩ አጠቃላይ `deduplicateThreshold` (ነባሪው `3`)።** ሁሉም ማጣሪያዎች ከተከናወኑ በኋላ፣ ሞተሩ
በጠቅላላው ውጤት ውስጥ `>= deduplicateThreshold` ተመሳሳይ ተከታታይ መስመሮች ያሉበትን
ማንኛውንም ተከታታይ ስብስብ ያጣምራል
(`deduplicateRepeatedLines`፣ በ`engines/rtk/index.ts` ውስጥ የሚተገበር)። በመደበኛነት ሲዋቀር እሴቱ ከ2–100 ባለው ክልል ይገደባል።
የእያንዳንዱ ማጣሪያ ሂደት መጀመሪያ ይከናወናል (በማጣሪያው ውስጥ)፣ የመተግበሪያ ሞተሩ አጠቃላይ ሂደት ደግሞ መጨረሻ ይከናወናል (በተቀላቀለው
ውጤት ላይ)፤ ስለዚህ ሁለቱ ድርብ ቆጠራ ሳይፈጥሩ ተደራርበው ይሰራሉ።
## የመስመር ማቧደን (`enableGrouping`)
`rtkConfig.enableGrouping` `true` ሲሆን (ነባሪው `false`)፣ RTK ከብዜት ማስወገድ በኋላ ባለው ውጤት ላይ ተጨማሪ
`groupSimilarLines` ሂደትን ያከናውናል፤ ይህም _እጅግ ተቀራራቢ_ (በባይት ደረጃ ፍጹም ተመሳሳይ ያልሆኑ)
ተከታታይ መስመሮችን ያጣምራል። `rtkConfig.groupingThreshold` (ነባሪው `3`) ማቧደንን ለማስጀመር
የሚያስፈልገው ዝቅተኛው ተከታታይ መስመሮች ብዛት ነው። ይህ የ`deduplicateThreshold` መዋቅራዊ አቻ ነው፦ ብዜት ማስወገድ ፍጹም ተመሳሳይ ድግግሞሾችን ያስተናግዳል፣
ማቧደን ደግሞ "ተመሳሳይ ቅርጽ ያላቸው ጥቃቅን ልዩነቶች" ያሉባቸውን ያስተናግዳል። ሁለቱም ማመልከቻዎች በ`key_value` ሰንጠረዥ ውስጥ የሚቀመጠው
የ`rtkConfig` JSON አካል ናቸው (ከላይ ያለውን ውቅር ይመልከቱ)፤ ስለዚህ ቅንብሩ ዳግም ከተጀመረ በኋላም ይቆያል።
## የኮድ አስተያየቶችን ማስወገድ (`stripCodeComments` / `preserveDocstrings`)
`rtkConfig.applyToCodeBlocks` ሲነቃ፣ RTK በአጥር ከተከበቡ የኮድ ብሎኮች ውስጥ ያሉ አስተያየቶችንም ማስወገድ ይችላል፦
- `stripCodeComments` (ነባሪው `false`) — በምርጫ የሚነቃ። `true` ሲሆን፣ RTK በJavaScript
እና TypeScript የኮድ ብሎኮች ውስጥ ያሉ አስተያየቶችን ያስወግዳል። ከታሪክ አንጻር ማመልከቻው ይነበብ ነበር እንጂ ተግባራዊ አልነበረም፤ ስለዚህ በምርት አካባቢ ያለማሳወቅ ለውጥ እንዳይኖር
ነባሪው "ማቆየት" ሆኖ ይቀጥላል።
- `preserveDocstrings` (ነባሪው `true`) — አስተያየቶችን በሚያስወግድበት ጊዜ፣ የJSDoc/`/** … */` ብሎክ አስተያየቶች
ይቀመጣሉ (ከሚወስዱት ባይቶች የበለጠ ዋጋ ያለው የAPI ሰነድ ይይዛሉ)። እነዚያንም ለማስወገድ
`false` ያድርጉት።
አስተያየት ማስወገድ በ`open-sse/services/compression/engines/rtk/codeStripper.ts` ውስጥ ተግባራዊ ተደርጓል። የጽሑፍ፣ የአብነት እና የመደበኛ አገላለጽ ሊተራሎች በስህተት እንደ
አስተያየት እንዳይወሰዱ **የTypeScript ተንታኝን** (መደበኛ አገላለጽን ሳይሆን) ይጠቀማል፤ እንዲሁም JSX ሲገኝ ሂደቱን ሙሉ በሙሉ ያቋርጣል (በዚህም በJSX የአገላለጽ ማስቀመጫዎች ውስጥ ያሉ አስተያየቶች
ፈጽሞ አይበላሹም)። በአሁኑ ጊዜ አስተያየት ማስወገድ የሚተገበረው **በJavaScript እና TypeScript ላይ ብቻ** ነው — በማስወገጃው `CodeLanguage` ስብስብ ውስጥ ያሉ ሌሎች
ቋንቋዎች (Python፣ Rust፣ Go፣ Ruby፣ Java) ባዶ መስመሮችን እና
ነጭ ቦታዎችን ማጣመር ይደረግባቸዋል፣ ነገር ግን አስተያየቶች አይወገዱም። የተወገደው ብሎክ ሂደት በ`rulesApplied` ውስጥ `rtk:code-strip` የሚል መለያ ይሰጠዋል።
> **ማስታወሻ — GCF / ሰንጠረዣዊ ኢንኮዲንግ የተለየ ሞተር ነው።** RTK የ"GCF"
> (Graph Compact Format) ሰንጠረዣዊ/አምዳዊ JSON ኢንኮደርን **አያካትትም**። ያ ኢንኮደር — የቀድሞውን
> `omni-tabular` ኢንኮደር የተካው — በ**headroom** ሞተር ውስጥ ይገኛል
> (`open-sse/services/compression/engines/headroom/`፣ አብሮ የተካተተው ኮዴክ ደግሞ በ
> `headroom/gcf/` ስር ይገኛል)። እዚህ ከተመዘገበው የRTK ማጣሪያ ሂደት ጋር ግንኙነት የለውም።
## ውቅር
አጠቃላይ ቅንብሮች በ `/api/settings/compression` በኩል ይገኛሉ። ለ-RTK የተለዩ ቅንብሮችም
በ `/api/context/rtk/config` በኩል ይገኛሉ።
```json
{
"defaultMode": "stacked",
"autoTriggerMode": "stacked",
"autoTriggerTokens": 32000,
"stackedPipeline": [
{ "engine": "rtk", "intensity": "standard" },
{ "engine": "caveman", "intensity": "full" }
],
"rtkConfig": {
"enabled": true,
"intensity": "standard",
"applyToToolResults": true,
"applyToCodeBlocks": false,
"applyToAssistantMessages": false,
"enabledFilters": [],
"disabledFilters": [],
"maxLinesPerResult": 120,
"maxCharsPerResult": 12000,
"deduplicateThreshold": 3,
"customFiltersEnabled": true,
"trustProjectFilters": false,
"rawOutputRetention": "never",
"rawOutputMaxBytes": 1048576,
"enableGrouping": false,
"groupingThreshold": 3,
"stripCodeComments": false,
"preserveDocstrings": true
}
}
```
`enabledFilters` እና `disabledFilters` እንደ `test-vitest` ወይም `git-diff` ያሉ የማጣሪያ መለያዎችን ይጠቀማሉ።
ሙሉው የ `rtkConfig` አወቃቀር በ
`open-sse/services/compression/types.ts` ውስጥ ባሉት `RtkConfig` / `DEFAULT_RTK_CONFIG` ይገለጻል። ሙሉው ኦብጀክት በ
SQLite `key_value` ሰንጠረዥ ውስጥ በ `namespace = "compression"`፣ `key = "rtkConfig"`
(`src/lib/db/compression.ts`) ስር እንደ አንድ JSON እሴት በቋሚነት ይቀመጣል፣ እና ሲነበብ በ `normalizeRtkConfig` ደረጃውን የጠበቀ ይደረጋል። ስለዚህ ከታች ያለው እያንዳንዱ መስክ
— `enableGrouping`፣ `groupingThreshold`፣ `stripCodeComments` እና `preserveDocstrings`ን ጨምሮ —
በተመሳሳዩ ማከማቻ በኩል ተጽፎ እንደገና ይነበባል፣ እንዲሁም ዳግም ከተጀመረ በኋላም ይቆያል።
| ቁልፍ | ነባሪ | ዓላማ |
| ---------------------- | ------- | ---------------------------------------------------------------------- |
| `deduplicateThreshold` | `3` | በመላው ሞተሩ፦ ለማጠቃለል የሚያስፈልጉ በተከታታይ ያሉ ተመሳሳይ መስመሮች ዝቅተኛ ብዛት (በ2–100 የተገደበ) |
| `enableGrouping` | `false` | በምርጫ የሚነቃ፦ በተከታታይ ያሉ በጣም ተመሳሳይ መስመሮችን ማጠቃለል |
| `groupingThreshold` | `3` | ማቧደንን የሚያስጀምር የተከታታይ ተመሳሳይ መስመሮች ዝቅተኛ ብዛት |
| `stripCodeComments` | `false` | በምርጫ የሚነቃ፦ ከታጠሩ የኮድ ብሎኮች አስተያየቶችን ማስወገድ (`applyToCodeBlocks` ያስፈልገዋል) |
| `preserveDocstrings` | `true` | አስተያየቶችን ሲያስወግድ፣ የJSDoc/`/** … */` ብሎኮችን ማቆየት |
## API
| መስመር | ዘዴ | ዓላማ |
| ---------------------------------- | ---- | --------------------------------------- |
| `/api/context/rtk/config` | GET | የRTK ውቅርን ማንበብ |
| `/api/context/rtk/config` | PUT | የRTK ውቅርን ማዘመን |
| `/api/context/rtk/filters` | GET | የማጣሪያ ካታሎግን እና የመጫን ምርመራ መረጃን መዘርዘር |
| `/api/context/rtk/import` | POST | የRTK TOML schema v1 ፋይሎችን ማረጋገጥ ወይም መጫን |
| `/api/context/rtk/test` | POST | ለአንድ የጽሑፍ ውሂብ የRTK መጭመቅን ቅድመ ዕይታ ማሳየት |
| `/api/context/rtk/raw-output/[id]` | GET | ተይዞ የቆየ ስሱ መረጃው የተሸፈነ ጥሬ ውጤትን ማንበብ |
| `/api/compression/preview` | POST | ማንኛውንም የመጭመቅ ሁነታ ቅድመ ዕይታ ማሳየት |
የRTK ሙከራ ውሂብ፦
```json
{
"command": "npm test",
"text": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed",
"config": {
"intensity": "standard"
}
}
```
የመጭመቅ ቅድመ ዕይታ ውሂብ፦
```json
{
"mode": "stacked",
"messages": [
{
"role": "tool",
"content": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed"
}
],
"config": {
"rtkConfig": {
"rawOutputRetention": "failures"
}
}
}
```
የአስተዳደር መስመሮች የዳሽቦርድ አስተዳደር ማረጋገጫ ወይም ተዛማጅ የAPI ቁልፍ ፖሊሲ ያስፈልጋቸዋል።
የRTK TOML ማረጋገጫ ውሂብ፦
```json
{
"action": "validate",
"content": "schema_version = 1\n\n[filters.my-tool]\nmatch_command = \"^my-tool\\\\b\"\nmax_lines = 20\n"
}
```
የተረጋገጠውን ፋይል በሁሉም ቦታ ለመጫን `"action": "install"`ን ይጠቀሙ። ነባር አጠቃላይ ፋይል መተካቱን
ከገመገሙና ካረጋገጡ በኋላ ብቻ `"overwrite": true`ን ያክሉ።
## ጥሬ ውጤትን መልሶ ማግኘት
RTK በመደበኛነት የታመቀ ጽሑፍን ብቻ ይመልሳል። ለማረም፣ `rawOutputRetention` የተሸሸገ
ጥሬ ውጤትን ሊያቆይ ይችላል፦
| እሴት | ባህሪ |
| ---------- | -------------------------------------- |
| `never` | ጥሬ ውጤትን አታቆይ |
| `failures` | የመክሸፍ ዕድሉ ያለውን ውጤት ብቻ አቆይ |
| `always` | ከመሸሸግ በኋላ እያንዳንዱን የታመቀ የRTK ጥሬ ውጤት አቆይ |
የተቀመጡ ፋይሎች በሚከተለው ስር ይጻፋሉ፦
```txt
DATA_DIR/rtk/raw-output/
```
ሚስጥሮች በቋሚነት ከመቀመጣቸው በፊት ይሸሸጋሉ፤ ይህም የተለመዱ bearer tokens፣ API keys፣ Slack tokens፣
AWS access keys፣ እና በምደባ ቅርጽ የተጻፉ `token=...`፣ `secret=...`፣ `password=...` እሴቶችን ያካትታል። ትንታኔዎች
የማመሳከሪያ id፣ መጠን እና hash metadata ብቻ ያከማቻሉ።
## የማረጋገጫ በር
የተመረጠው የማረጋገጫ በር ወደ ውጫዊ ትዕዛዞች ሳይወጣ አብረው የተካተቱ የinline filter ሙከራዎችን ያስኬዳል፦
```bash
node --import tsx/esm --test tests/unit/compression/rtk-verify.test.ts
```
ሰፋ ያለው የRTK በር፦
```bash
node --import tsx/esm --test \
tests/unit/compression/rtk-*.test.ts \
tests/unit/compression/pipeline-integration.test.ts \
tests/unit/compression/context-compression-api.test.ts
```
ከመልቀቅዎ በፊት ሰፊውን የማመቂያ በር ያስኪዱ፦
```bash
node --import tsx/esm --test \
tests/unit/compression/*.test.ts \
tests/golden-set/*.test.ts \
tests/integration/compression-pipeline.test.ts \
tests/unit/api/compression/compression-api.test.ts
```
## RTKን ማስፋት
1. የfilter JSON ፋይል ያክሉ ወይም ያዘምኑ።
2. አስፈላጊውን ባህሪ የሚያረጋግጥ ቢያንስ አንድ `tests[]` ናሙና ያካትቱ።
3. ለአዳዲስ የትዕዛዝ ቤተሰቦች በ`tests/unit/compression/fixtures/rtk/` ስር fixture ያክሉ።
4. አዲስ የውጤት ምድብ ሲያስገቡ የትዕዛዝ ማወቂያ ሽፋን ያክሉ።
5. የማረጋገጫውን እና ሰፊውን የRTK በሮች ያስኪዱ።
6. filterው ለፕሮጀክቱ ብቻ የሚውል ከሆነ፣ `.rtk/filters.json`ን commit ያድርጉ እና `.rtk/trust.json`ን ከግምገማ በኋላ ብቻ ያድሱ።
---
## የጥንካሬ ደረጃዎች (v3.8.16+)
RTK በ**ማመቅ ጥብቅነት** እና **ደህንነት** መካከል ሚዛን የሚጠብቁ **3 የጥንካሬ ደረጃዎችን** ይደግፋል። ደረጃው በengine config ውስጥ ባለው `config.intensity` በኩል ይዘጋጃል።
### 3ቱ ደረጃዎች
| ደረጃ | የመቁረጫ ገደብ | የtoken ቁጠባ | አደጋ | በጣም የሚመችበት |
| ---------------- | ------------- | ---------- | -------- | -------------------------- |
| `minimal` | በክፍል 24 መስመሮች | ~20-40% | በጣም ዝቅተኛ | ወሳኝ context ያለው production |
| `standard` (ነባሪ) | በክፍል 24 መስመሮች | ~50-70% | ዝቅተኛ | ዕለታዊ የኮድ አጻጻፍ sessions |
| `aggressive` | በክፍል 16 መስመሮች | ~70-90% | መካከለኛ | ረጅም sessions፣ ከፍተኛ ቁጠባ |
### መቁረጡ የሚከሰትበት ቦታ
የመቁረጫ ገደቡ `lineFilter.ts`ን ይነካል፦
```ts
// ከ open-sse/services/compression/engines/rtk/index.ts:329-330
config.intensity === "aggressive" ? 16 : 24,
config.intensity === "aggressive" ? 16 : 24,
```
የእያንዳንዱ ክፍል **መጀመሪያ** እና **መጨረሻ** ሁለቱም ይጠበቃሉ፤ መቁረጡ ሲጀምር መካከለኛው ይዘት ይወገዳል።
### የሚቀረው እና የሚቆረጠው
| ይዘት | minimal | standard | aggressive |
| -------------------- | -------- | -------- | ---------- |
| ስህተቶች / stack traces | ✅ ይጠበቃል | ✅ ይጠበቃል | ✅ ይጠበቃል |
| የሙከራ ውድቀቶች | ✅ ይጠበቃል | ✅ ይጠበቃል | ✅ ይጠበቃል |
| የbuild ስህተቶች | ✅ ይጠበቃል | ✅ ይጠበቃል | ✅ ይጠበቃል |
| የተሳኩ ሙከራዎች (ዝርዝር) | ✅ ይጠበቃል | 🟡 ይታመቃል | 🟡 ይታመቃል |
| መደበኛ ውጤት (info logs) | 🟡 ይታመቃል | 🟡 ይታመቃል | ❌ ይወገዳል |
| የሂደት አሞሌዎች | 🟡 ይታመቃል | ❌ ይወገዳል | ❌ ይወገዳል |
| Banner / ASCII art | 🟡 ይታመቃል | ❌ ይወገዳል | ❌ ይወገዳል |
### ትክክለኛውን ጥንካሬ መምረጥ
```
contextን ማጣት አስከፊ ነው?
│
┌───────────┼───────────┐
│ │ │
አዎ አይ እርግጠኛ አይደለሁም
│ │ │
▼ │ │
minimal │ │
│ │ │
│ ▼ ▼
│ throughput መጀመሪያ `standard`ን
│ ምን ያህል ወሳኝ ነው? ይሞክሩ (ለ80%
│ │ ሁኔታዎች ይሰራል)
│ ┌────┴────┐
│ │ │
│ ዝቅተኛ ከፍተኛ
│ │ │
│ ▼ ▼
│ standard aggressive
│ │ │
└──────┴─────────┘
```
### ጥንካሬን ማዋቀር
**ለእያንዳንዱ combo** (በcombo config ውስጥ)፦
```json
{
"combo": "my-coding-combo",
"routing": {/* ... */},
"compression": {
"engine": "rtk",
"intensity": "aggressive"
}
}
```
**በፕሮግራም**፦
`rtkEngine` (`@omniroute/open-sse/services/compression/engines/rtk`)
`CompressionEngine` ነው እና `updateConfig` method የለውም። የengineውን config
በምትኩ በregistry helper በኩል ያዘምኑ፦
```ts
import { updateEngineConfig } from "@omniroute/open-sse/services/compression/engines/registry";
updateEngineConfig("rtk", { intensity: "aggressive" });
```
### ውጤቱን ማረጋገጥ
filterዎ በመረጡት ጥንካሬ ደህንነቱ የተጠበቀ መሆኑን ለማረጋገጥ **የማረጋገጫ በር**ን (ከታች ይመልከቱ) ይጠቀሙ፦
```ts
import { runRtkFilterTests } from "omniroute/compression/engines/rtk/verify";
const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
console.error("Filters failed at aggressive intensity");
}
```
---
## ብጁ ማጣሪያ ማበልጸግ (v3.8.16+)
የ`engines/rtk/filters/` ማውጫ **49+ አብሮገነብ የማጣሪያ JSON ፋይሎችን** ይዟል። በነባሪዎቹ ያልተሸፈኑ ብጁ መሣሪያዎች ውጤትን ለመጭመቅ የራስዎን ማከል ይችላሉ።
### የማጣሪያ መዋቅር (Zod)
```ts
{
"id": "string", // ያስፈልጋል። የማጣሪያ መለያ (kebab-case፣ ለምሳሌ፦ "python-traceback")
"label": "string", // ያስፈልጋል። ለሰው በቀላሉ የሚነበብ የማጣሪያ ስም
"description": "string", // አማራጭ (ነባሪ፦ "")። ማጣሪያው ምን እንደሚያደርግ አጭር መግለጫ
"category": "git|test|build|shell|docker|package|infra|cloud|generic",
"priority": number, // አማራጭ (0-100፣ ነባሪ፦ 50)። የአፈጻጸም ቅደም ተከተል (ከፍተኛው = መጀመሪያ)
"match": {
"commands": ["string"], // የሚዛመዱ የትዕዛዝ ስሞች (ለምሳሌ፦ "python"፣ "pytest")
"patterns": ["string"], // ከውጤት ጋር የሚዛመዱ የRegex ስርዓተ ጥለቶች
"outputTypes": ["string"] // የተገኙ የውጤት ክፍሎች (ለምሳሌ፦ "test-failure")
},
"rules": {
"stripAnsi": boolean, // አማራጭ (ነባሪ፦ false)። የANSI ቀለም ኮዶችን ያስወግዳል
"replace": [ // የፈልግና-ተካ ደንቦች (ነባሪ፦ [])
{ "pattern": "regex", "replacement": "..." }
],
"matchOutput": [ // ስርዓተ ጥለቱ ሲዛመድ ወዲያውኑ ያቋርጣል (ነባሪ፦ [])
{
"pattern": "regex",
"message": "short summary",
"unless": "regex" // ይህ ስርዓተ ጥለት ከተዛመደ ይዝለለዋል
}
],
"includePatterns": ["string"], // የሚቀመጡ መስመሮች (የRegex ስርዓተ ጥለቶች፣ ነባሪ፦ [])
"dropPatterns": ["string"], // የሚወገዱ መስመሮች (የRegex ስርዓተ ጥለቶች፣ ነባሪ፦ [])
"collapsePatterns": ["string"], // ወደ አንድ ጊዜ መከሰት የሚጠቃለሉ መስመሮች (ነባሪ፦ [])
"deduplicate": boolean, // አማራጭ (ነባሪ፦ false)። የተደጋገሙ መስመሮችን ያስወግዳል
"truncateLineAt": number, // አማራጭ (ነባሪ፦ 0)። መስመሮችን እስከ ከፍተኛው የቁምፊ ብዛት ይቆርጣል
"maxLines": number, // አማራጭ (ነባሪ፦ 0)። በጠቅላላ የመስመሮች ብዛት ላይ ጥብቅ ገደብ
"headLines": number, // አማራጭ (ነባሪ፦ 20)። ከተዛመደው ውጤት የመጀመሪያዎቹን N መስመሮች ያቆያል
"tailLines": number, // አማራጭ (ነባሪ፦ 20)። ከተዛመደው ውጤት የመጨረሻዎቹን N መስመሮች ያቆያል
"onEmpty": "string", // አማራጭ (ነባሪ፦ "")። ሁሉም መስመሮች ከተጣሩ የሚታይ ተተኪ መልዕክት
"filterStderr": boolean // አማራጭ (ነባሪ፦ false)። የstderr ውጤትንም ያጣራል
},
"preserve": {
"errorPatterns": ["string"], // ሁልጊዜ መቀመጥ ያለባቸው ስርዓተ ጥለቶች (ነባሪ፦ [])
"summaryPatterns": ["string"] // ለመጨረሻው የማጠቃለያ መስመር የሚያገለግሉ ስርዓተ ጥለቶች (ነባሪ፦ [])
},
"tests": [ // ለማረጋገጫ በውስጡ የተካተቱ ሙከራዎች (ነባሪ፦ [])
{
"name": "string", // ያስፈልጋል። የሙከራ ስም
"input": "sample output", // ያስፈልጋል። የናሙና ግቤት ጽሑፍ
"expected": "expected output", // ያስፈልጋል። የሚጠበቀው የተጨመቀ ውጤት
"command": "optional command" // አማራጭ። የትዕዛዝ አውድ
}
]
}
```
### ምሳሌ፦ የPython Traceback ማጣሪያ
```json
{
"id": "python-traceback",
"label": "Python Traceback Filter",
"description": "Compresses Python tracebacks to essential file/line locations and error type",
"category": "test",
"priority": 60,
"match": {
"commands": ["python", "python3", "pytest", "uv", "poetry"],
"patterns": ["Traceback \\(most recent call last\\)", "Error", "Exception"],
"outputTypes": ["error-traceback"]
},
"rules": {
"stripAnsi": true,
"includePatterns": [
"Traceback \\(most recent call last\\)",
"^\\s*File \".+\", line \\d+",
"^\\s*[A-Z][a-zA-Z]+Error:",
"^\\s*[A-Z][a-zA-Z]+Exception"
],
"dropPatterns": ["site-packages/", "^\\s+[a-z_]+\\([^)]*\\)$"],
"headLines": 5,
"tailLines": 3,
"maxLines": 25,
"filterStderr": true
},
"preserve": {
"errorPatterns": ["Error:", "Exception:", "Traceback"],
"summaryPatterns": ["^[A-Z][a-zA-Z]+(?:Error|Exception):"]
},
"tests": [
{
"name": "preserves-error-type-and-location",
"input": "Traceback (most recent call last):\n File \"app.py\", line 42, in main\n do_thing()\n File \"lib/utils.py\", line 17, in helper\n return 1 / 0\nZeroDivisionError: division by zero",
"expected": "Traceback (most recent call last):\n File \"app.py\", line 42, in main\n File \"lib/utils.py\", line 17, in helper\nZeroDivisionError: division by zero",
"command": "python app.py"
}
]
}
```
### ብጁ ማጣሪያዎችን መጫን
ፋይሉን በታወቀ አካባቢ ያስቀምጡ፦
```
~/.omniroute/rtk/filters/my-filter.json # የተጠቃሚ ደረጃ
<project>/.rtk/filters/my-filter.json # የፕሮጀክት ደረጃ
```
ማጣሪያዎች ሲጀመር በ`open-sse/services/compression/engines/rtk/filterLoader.ts` ውስጥ ባለው `loadRtkFilters()` በኩል በራስ-ሰር ይጫናሉ። ጫኚው ማጣሪያዎችን ከሚከተሉት ቦታዎች ያገኛል፦
- አብሮገነብ ካታሎግ፦ `open-sse/services/compression/engines/rtk/filters/`
- የተጠቃሚ ማውጫ፦ `~/.omniroute/rtk/filters/`
- የፕሮጀክት ማውጫ፦ `<project>/.rtk/filters/`
ማጣሪያዎችን በፕሮግራም ለመጫን፦
```ts
import { loadRtkFilters } from "@omniroute/open-sse/services/compression/engines/rtk/filterLoader";
// አማራጮች፦ customFiltersEnabled (የተጠቃሚ/ፕሮጀክት ማጣሪያዎችን ይጫናል፣ በነባሪ ክፍት ነው)፣
// trustProjectFilters፣ refresh።
const filters = loadRtkFilters({ customFiltersEnabled: true });
```
### ማረጋገጫ
ማጣሪያዎች በሚጫኑበት ጊዜ ከZod መዋቅር ጋር እንዲጣጣሙ ይረጋገጣሉ። መዋቅሩ የተሳሳተ ማጣሪያ መጫን ይሳነዋል እና ስህተት ይመዘገባል፦
```
RTK_FILTER_LOADER: የ"my-filter" ማጣሪያ ማረጋገጫውን አላለፈም፦
- rules.replace.0.pattern: ልክ ያልሆነ regex
- match.commands: ባዶ መሆን የለበትም
```
ሁሉንም የተጫኑ ማጣሪያዎች ለማረጋገጥ፣ ከ`open-sse/services/compression/engines/rtk/verify.ts` የሚላከውን `runRtkFilterTests()` ይጥሩ።
### ምርጥ ልምዶች
1. **ሁልጊዜ `tests[]`ን ያካትቱ** — ማጣሪያዎ እንደሚሠራ ያረጋግጣሉ፣ የቀድሞ ችግሮች ዳግም እንዳይከሰቱም ይከላከላሉ
2. **ለአጭር ማቋረጫዎች `matchOutput`ን ይጠቀሙ** — አንድ መስመር ብቻ ሁኔታውን በቂ ሁኔታ የሚገልጽ ከሆነ፣ ሙሉውን ብሎክ ይተኩ
3. **ከ`strip` ይልቅ `keep`ን ይምረጡ** — ግልጽ የሆኑ “ሁልጊዜ አቆይ” ደንቦች ከ“ሁልጊዜ አስወግድ” ደንቦች የበለጠ ደኅንነታቸው የተጠበቀ ነው
4. **በሁሉም 3 የጥንካሬ ደረጃዎች ይፈትሹ** — `minimal` ምንም ለውጥ ማድረግ የለበትም፤ `aggressive`ም አሁንም ስህተቶችን መጠበቅ አለበት
5. **የ`unless` መስኩን ይጠቀሙ** — አጭር ማቋረጫዎችን “X ካለ እንዳይነሳሱ” በሚል ቅድመ ሁኔታ ይጠብቁ
---
## ጥሬ ውጤትን መልሶ ማግኘት እና የማረጋገጫ በር
RTK ውጤትን በከፍተኛ ደረጃ ሲጨምቅ፣ ለማረም፣ ለኦዲት ወይም እንደገና ለማጫወት **ዋናውን ጽሑፍ መልሰው ማግኘት** ይችላሉ።
### ጥሬ ውጤትን መልሶ ማግኘት እንዴት እንደሚሠራ
```
ዋናው ውጤት (10K ቶከኖች)
│
▼
RTK መጭመቅ (rawOutput.enabled=true በማድረግ)
│
├─▶ የተጨመቀ ውጤት (2K ቶከኖች) ──▶ ወደ LLM
│
└─▶ ዋናው ውጤት (10K ቶከኖች) ──▶ በDB ውስጥ ይከማቻል
(በrequest_id የተገናኘ)
```
### ጥሬ ውጤት ማከማቻን ማንቃት
**በእያንዳንዱ ጥያቄ** (በcombo ውቅር ውስጥ)፦
```json
{
"compression": {
"engine": "rtk",
"intensity": "aggressive",
"rawOutput": {
"enabled": true,
"maxBytes": 1048576 // የ1MB ገደብ
}
}
}
```
**ነባሪ**፦ `rawOutput.enabled: false` (የማከማቻ ቦታን ይቆጥባል)።
### የማከማቻ ወጪ
| በእያንዳንዱ ጥያቄ | የ1MB ገደብ | የ10MB ገደብ |
| ------------------ | ----------- | ------------ |
| አማካይ የተጨመቀ ውጤት | ~5KB | ~5KB |
| የተከማቸ ጥሬ ውጤት | ~50-500KB | ~500KB-5MB |
| በቀን 1000 ጥያቄዎች ሲኖሩ | 50-500MB/ቀን | 500MB-5GB/ቀን |
> **ምክር**፦ ጥሬ ውጤትን ሁልጊዜ ከማንቃት ይልቅ ለ**ማረሚያ ክፍለ ጊዜዎች** ወይም **በናሙና ለሚደረግ ኦዲት** ብቻ ያንቁት።
### ዋናውን ውጤት መልሶ ማግኘት
```ts
import { readRtkRawOutput } from "omniroute/compression/engines/rtk/rawOutput";
const raw = readRtkRawOutput(pointerId); // ከመጭመቂያ ስታቲስቲክስ የተገኘ pointerId
if (raw) {
console.log("Original output:", raw);
}
```
`pointerId` ከመጭመቅ በኋላ በ`CompressionStats.rtkRawOutputPointers[]` ውስጥ ይመለሳል።
ለፈንክሽኑ ፊርማ `open-sse/services/compression/engines/rtk/rawOutput.ts:102`ን ይመልከቱ።
### የማረጋገጫ በር
**የRTK ማጣሪያ ማረጋገጫ** (`open-sse/services/compression/engines/rtk/verify.ts`) ሁሉንም ማጣሪያዎች በ`tests[]` ላይ በመመርኮዝ ያረጋግጣል፣ እንዲሁም ባህሪያቸው በሁሉም 3 የጥንካሬ ደረጃዎች ትክክለኛ መሆኑን ያረጋግጣል።
ማረጋገጫውን ለማስኬድ **`runRtkFilterTests()`ን ይጥሩ**፦
```ts
import { runRtkFilterTests } from "open-sse/services/compression/engines/rtk/verify";
const result = runRtkFilterTests();
console.log(`Passed: ${result.outcomes.filter((o) => o.passed).length}`);
console.log(`Failed: ${result.outcomes.filter((o) => !o.passed).length}`);
if (!result.passed) {
console.error("Filters failed verification");
result.outcomes
.filter((o) => !o.passed)
.forEach((o) => {
console.error(
` - ${o.filterId} / ${o.testName}: expected "${o.expected}", got "${o.actual}"`
);
});
}
```
**የሚያረጋግጣቸው ነገሮች**፦
1. እያንዳንዱ ማጣሪያ ይጫናል እና የschema ማረጋገጫውን ያልፋል
2. እያንዳንዱ የ`tests[]` ግቤት የሚጠበቀውን ውጤት ያመነጫል
3. የ`minimal` ጥንካሬ ምንም ለውጥ አያደርግም (ዋናውን ይጠብቃል፣ መዋቅራዊ ማጣሪያዎችን ብቻ ይተገብራል)
4. የ`aggressive` ጥንካሬ ስህተቶችን፣ ያልተሳኩ ሙከራዎችን እና የstack traceዎችን ይጠብቃል
5. የተጨመቀው ውጤት ከዋናው ግብዓት ፈጽሞ አይበልጥም
- ምንጭ፦ `open-sse/services/compression/engines/rtk/` (63 ፋይሎች፣ ~70KB)
- **የማጣሪያ ለውጥን ከማዋሃድዎ በፊት** — ሙከራዎቹ ሁልጊዜ ማለፋቸውን ያረጋግጡ
- **የRTK engineን ካሻሻሉ በኋላ** — schemaው ተለውጦ ሊሆን ይችላል
- **በክትትል ወቅት በየጊዜው** — በሙከራ መሣሪያዎች ላይ ከሚከሰት መዛባት ይከላከላል
- **አዲስ የመሣሪያ/ትዕዛዝ ቤተሰብ ሲጨምሩ** — አዲሱ ማጣሪያ እንደሚሠራ ያረጋግጣል
---
## በተጨማሪ ይመልከቱ
- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — የሙሉ የማመቅ ሂደት አጠቃላይ እይታ
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — የኤንጂን መዝገብ እና አብረው የተካተቱ ኤንጂኖች
- [EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md) — ብጁ ኤንጂኖች፣ የቋንቋ ጥቅሎች፣ በተደራረቡ የሂደት መስመሮች
- ምንጭ፦ `open-sse/services/compression/engines/rtk/` (63 ፋይሎች፣ ~70KB)

558
docs/i18n/am/docs/frameworks/ACP.md Normal file
View File

@@ -0,0 +1,558 @@
# ACP (Agent Client Protocol) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/ACP.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/ACP.md) · 🇦🇿 [az](../../../az/docs/frameworks/ACP.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/ACP.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/ACP.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/ACP.md) · 🇩🇰 [da](../../../da/docs/frameworks/ACP.md) · 🇩🇪 [de](../../../de/docs/frameworks/ACP.md) · 🇬🇷 [el](../../../el/docs/frameworks/ACP.md) · 🇪🇸 [es](../../../es/docs/frameworks/ACP.md) · 🇪🇪 [et](../../../et/docs/frameworks/ACP.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/ACP.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/ACP.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/ACP.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/ACP.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/ACP.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/ACP.md) · 🇮🇱 [he](../../../he/docs/frameworks/ACP.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/ACP.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/ACP.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/ACP.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/ACP.md) · 🇮🇩 [id](../../../id/docs/frameworks/ACP.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/ACP.md) · 🇮🇹 [it](../../../it/docs/frameworks/ACP.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/ACP.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/ACP.md) · 🇰🇭 [km](../../../km/docs/frameworks/ACP.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/ACP.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/ACP.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/ACP.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/ACP.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/ACP.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/ACP.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/ACP.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/ACP.md) · 🇲🇲 [my](../../../my/docs/frameworks/ACP.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/ACP.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/ACP.md) · 🇳🇴 [no](../../../no/docs/frameworks/ACP.md) · 🇮🇳 [or](../../../or/docs/frameworks/ACP.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/ACP.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/ACP.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/ACP.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/ACP.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/ACP.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/ACP.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/ACP.md) · 🇱🇰 [si](../../../si/docs/frameworks/ACP.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/ACP.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/ACP.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/ACP.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/ACP.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/ACP.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/ACP.md) · 🇮🇳 [te](../../../te/docs/frameworks/ACP.md) · 🇹🇭 [th](../../../th/docs/frameworks/ACP.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/ACP.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/ACP.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/ACP.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/ACP.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/ACP.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/ACP.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/ACP.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/ACP.md)
---
> **በአጭሩ**: ACP OmniRoute HTTP APIዎችን ከመጠቀም ይልቅ CLI ወኪሎችን (እንደ Claude Code፣ Codex) እንደ ንዑስ ሂደቶች እንዲያስጀምር ያስችለዋል። ይህ የ"CLI-as-backend" ማጓጓዣን ይሰጥዎታል።
---
## ACP ምንድን ነው?
ACP (Agent Client Protocol) ለOmniRoute የሚያገለግል **የ"CLI-as-backend" ማጓጓዣ** ነው። ወደ AI አቅራቢዎች የሚደረጉ HTTP API ጥሪዎችን ከመጥለፍ ይልቅ፣ ACP **CLI ወኪሎችን እንደ ንዑስ ሂደቶች ያስጀምራል** እና ጥያቄዎችን በእያንዳንዳቸው ቤተኛ በይነገጽ በኩል ያስተላልፋል።
### ACPን ለምን ይጠቀሙ?
| ጥቅም | መግለጫ |
| -------------------- | ------------------------------------ |
| **API ቁልፎች አያስፈልጉም** | ነባሩን የCLI ማረጋገጫዎን ይጠቀማል |
| **ቤተኛ ፕሮቶኮል** | የእያንዳንዱን CLI ቤተኛ የግቤት/ውጤት ቅርጸት ይጠቀማል |
| **ራስ-ሰር ፍለጋ** | በስርዓትዎ ላይ የተጫኑ CLIዎችን ይለያል |
| **15 አብሮገነብ ወኪሎች** | ለታዋቂ CLI መሣሪያዎች አስቀድሞ የተዋቀረ |
| **ብጁ ወኪሎች** | በቅንብሮች በኩል የራስዎን CLI መሣሪያዎች ያክሉ |
| **የሂደት አስተዳደር** | የሂወት ዑደቱን (ማስጀመር፣ መላክ፣ ማቋረጥ) ያስተዳድራል |
---
## የሚደገፉ CLI ወኪሎች
ACP በነባሪ **15 አብሮገነብ CLI ወኪሎችን** ይደግፋል፦
| የወኪል ID | የማሳያ ስም | ሁለትዮሽ ፋይል | ፕሮቶኮል |
| ------------- | ------------------ | ------------- | ----- |
| `codex` | OpenAI Codex CLI | `codex` | stdio |
| `claude` | Claude Code CLI | `claude` | stdio |
| `goose` | Goose CLI | `goose` | stdio |
| `openclaw` | OpenClaw | `openclaw` | stdio |
| `aider` | Aider | `aider` | stdio |
| `opencode` | OpenCode | `opencode` | stdio |
| `cline` | Cline | `cline` | stdio |
| `qwen` | Qwen Code | `qwen --acp` | stdio |
| `forge` | ForgeCode | `forge` | stdio |
| `amazon-q` | Amazon Q Developer | `q` | stdio |
| `interpreter` | Open Interpreter | `interpreter` | stdio |
| `cursor-cli` | Cursor CLI | `cursor` | stdio |
| `warp` | Warp AI | `warp` | stdio |
| `gemini` | Gemini CLI | `gemini` | stdio |
| `zcode` | ZCode | `zcode` | stdio |
### ብጁ ወኪሎች
በቅንብሮች በኩል የራስዎን CLI ወኪሎች ማከል ይችላሉ። ብጁ ወኪሎች ከአብሮገነብ ወኪሎች ጋር ተመሳሳይ ባህሪያትን ይደግፋሉ።
---
## ፈጣን ጅምር
### ደረጃ 1፦ CLI ወኪል ይጫኑ
```bash
# ምሳሌ፦ Claude Code CLIን ይጫኑ
npm install -g @anthropic-ai/claude-code
# መጫኑን ያረጋግጡ
claude --version
```
### ደረጃ 2፦ የACP ራስ-ሰር ማወቂያ
ACP በስርዓትዎ ላይ የተጫኑ CLI ወኪሎችን በራስ-ሰር ይለያል። ምንም ውቅር አያስፈልግም!
### ደረጃ 3፦ የACP ማጓጓዣን ይጠቀሙ
አንዴ ከተለየ፣ ACP ለማንኛውም የሚደገፍ አቅራቢ እንደ ማጓጓዣ መጠቀም ይቻላል። CLIው በሚገኝበት ጊዜ OmniRoute ACPን በራስ-ሰር ይጠቀማል።
---
## ACP እንዴት ይሰራል?
### አወቃቀር
```
┌─────────────────┐
│ OmniRoute │
│ (HTTP ተኪ) │
└────────┬────────┘
│
│ spawn()
▼
┌─────────────────┐
│ ንዑስ ሂደት │
│ (CLI ወኪል) │
│ │
│ stdin ◄──────┤ ጥያቄ ይላኩ
│ stdout ──────►│ ምላሽ ይቀበሉ
│ stderr ──────►│ ስህተቶችን ይቀበሉ
└─────────────────┘
```
### የሂደት የሂወት ዑደት
1. **ማስጀመር** — ACP ለCLI ወኪሉ ንዑስ ሂደት ይፈጥራል
2. **መላክ** — ACP ጥያቄዎችን ወደ ሂደቱ stdin ይጽፋል
3. **መቀበል** — ACP ምላሾችን ከstdout/stderr ያነባል
4. **የስራ ፈት ሁኔታ ማወቂያ** — ACP ምላሹ እንደተጠናቀቀ ከመቁጠሩ በፊት ለ2 ሰከንዶች ምንም እንቅስቃሴ እንዳይኖር ይጠብቃል
5. **ማቋረጥ** — ACP ሂደቱን ያቋርጣል (SIGTERM፣ ከዚያም ከ5s በኋላ SIGKILL)
### የግንኙነት ፕሮቶኮል
ACP ከCLI ወኪሎች ጋር ለመገናኘት **stdio** (መደበኛ ግቤት/ውጤት) ይጠቀማል። ፕሮቶኮሉ የሚከተለው ነው፦
1. **ጥያቄ መላክ** — ከአዲስ መስመር ጋር ወደ stdin ይጻፉ
2. **ምላሽ መጠበቅ** — እስኪያርፍ ድረስ ከstdout ያንብቡ (ለ2s ምንም ውጤት ካልኖረ)
3. **የጊዜ ገደብ** — ነባሪው 120 ሰከንዶች ነው (ሊዋቀር ይችላል)
---
## የAPI ማጣቀሻ
### የመዝገብ ተግባራት
#### `detectInstalledAgents()`
በስርዓቱ ላይ የተጫኑትን ሁሉንም የCLI ወኪሎች ይለያል። ውጤቶቹ ለ60 ሰከንዶች በመሸጎጫ ውስጥ ይቀመጣሉ።
```typescript
import { detectInstalledAgents } from "@/lib/acp";
const agents = detectInstalledAgents();
// የሚመልሰው፦ CliAgentInfo[]
interface CliAgentInfo {
id: string; // ለምሳሌ፣ "codex", "claude"
name: string; // የማሳያ ስም
binary: string; // የሚጀመረው የባይነሪ ስም
versionCommand: string; // የስሪት ማወቂያ ትዕዛዝ
version: string | null; // የተገኘው ስሪት (ካልተጫነ null)
installed: boolean; // ወኪሉ መጫኑን ወይም አለመጫኑን
providerAlias: string; // በOmniRoute ውስጥ ያለው የአቅራቢ መለያ
spawnArgs: string[]; // ሲጀመር የሚተላለፉ ነጋሪ እሴቶች
protocol: "stdio" | "http"; // የግንኙነት ፕሮቶኮል
isCustom?: boolean; // ይህ በተጠቃሚው የተገለጸ ብጁ ወኪል መሆኑን ወይም አለመሆኑን
}
```
#### `getAvailableAgents()`
የተጫኑና ለACP ዝግጁ የሆኑትን ወኪሎች ብቻ ያገኛል።
```typescript
import { getAvailableAgents } from "@/lib/acp";
const available = getAvailableAgents();
// የሚመልሰው፦ CliAgentInfo[] (የተጫኑ ወኪሎችን ብቻ)
```
#### `getAgentById(id)`
አንድን የተወሰነ ወኪል በመለያው ያገኛል።
```typescript
import { getAgentById } from "@/lib/acp";
const agent = getAgentById("claude");
// የሚመልሰው፦ CliAgentInfo | undefined
```
#### `setCustomAgents(agents)`
ከቅንብሮች የተገኙ የብጁ ወኪል መግለጫዎችን ያዘጋጃል።
```typescript
import { setCustomAgents } from "@/lib/acp";
setCustomAgents([
{
id: "my-custom-cli",
name: "My Custom CLI",
binary: "mycli",
versionCommand: "mycli --version",
providerAlias: "my-provider",
spawnArgs: [],
protocol: "stdio",
},
]);
```
### የአስተዳዳሪ ተግባራት
#### `acpManager.spawn(agentId, binary, args, env)`
አዲስ የCLI ወኪል ሂደት ይጀምራል።
```typescript
import { acpManager } from "@/lib/acp";
const session = acpManager.spawn("claude", "claude", ["--print", "--output-format", "json"], {
/* ብጁ የአካባቢ ተለዋዋጮች */
});
// የሚመልሰው፦ AcpSession
```
**የተፈቀዱ የወኪል መለያዎች**፦ `["claude", "codex", "gemini", "qwen"]`
#### `acpManager.sendPrompt(sessionId, prompt, timeoutMs)`
ወደ CLI ወኪል ጥያቄ ይልካል እና ምላሹን ይሰበስባል።
```typescript
import { acpManager } from "@/lib/acp";
const response = await acpManager.sendPrompt(
"acp-claude-1234567890-abc123",
"What is 2+2?",
120000 // የ2 ደቂቃ የጊዜ ገደብ
);
// የሚመልሰው፦ Promise<string>
```
#### `acpManager.kill(sessionId)`
ክፍለ ጊዜን ያቋርጣል እና ያጸዳል።
```typescript
import { acpManager } from "@/lib/acp";
const killed = acpManager.kill("acp-claude-1234567890-abc123");
// የሚመልሰው፦ boolean
```
#### `acpManager.getActiveSessions()`
ሁሉንም ንቁ ክፍለ ጊዜዎች ያገኛል።
```typescript
import { acpManager } from "@/lib/acp";
const sessions = acpManager.getActiveSessions();
// የሚመልሰው፦ AcpSession[]
```
#### `acpManager.killAll()`
ሁሉንም ክፍለ ጊዜዎች ያቋርጣል።
```typescript
import { acpManager } from "@/lib/acp";
acpManager.killAll();
```
### የክፍለ ጊዜ በይነገጽ
```typescript
interface AcpSession {
id: string; // ልዩ የክፍለ ጊዜ መለያ
agentId: string; // የወኪል መለያ (ለምሳሌ፣ "claude")
process: ChildProcess; // የንዑስ ሂደት መያዣ
alive: boolean; // ሂደቱ ንቁ መሆኑን ወይም አለመሆኑን
stdoutBuffer: string; // የተጠራቀመ stdout ቋት
stderrBuffer: string; // የተጠራቀመ stderr ቋት
createdAt: Date; // የተፈጠረበት የጊዜ ማህተም
}
```
### ክስተቶች
`AcpManager` `EventEmitter`ን ያስፋፋል እና የሚከተሉትን ክስተቶች ያሰራጫል፦
#### `stdout`
የCLI ወኪሉ ወደ stdout ሲጽፍ ይሰራጫል።
```typescript
acpManager.on("stdout", ({ sessionId, data }) => {
console.log(`[${sessionId}] stdout: ${data}`);
});
```
#### `stderr`
የCLI ወኪሉ ወደ stderr ሲጽፍ ይሰራጫል።
```typescript
acpManager.on("stderr", ({ sessionId, data }) => {
console.error(`[${sessionId}] stderr: ${data}`);
});
```
#### `exit`
የCLI ወኪሉ ሂደት ሲወጣ ይሰራጫል።
```typescript
acpManager.on("exit", ({ sessionId, code, signal }) => {
console.log(`[${sessionId}] exited with code ${code}, signal ${signal}`);
});
```
#### `error`
በCLI ወኪሉ ሂደት ላይ ስህተት ሲከሰት ይሰራጫል።
```typescript
acpManager.on("error", ({ sessionId, error }) => {
console.error(`[${sessionId}] error: ${error}`);
});
```
---
## ውቅር
### የአካባቢ ተለዋዋጮች
ACP ሁሉንም የአካባቢ ተለዋዋጮች ከወላጅ ሂደቱ ይወርሳል፣ እንዲሁም በብጁ የአካባቢ ተለዋዋጮች ሊስፋፋ ይችላል፦
```typescript
acpManager.spawn("claude", "claude", [], {
ANTHROPIC_API_KEY: "sk-...",
DEBUG: "true",
});
```
### የማስጀመሪያ ነጋሪ እሴቶች
እያንዳንዱ ወኪል በመዝገቡ ውስጥ የተገለጹ ነባሪ የማስጀመሪያ ነጋሪ እሴቶች አሉት። እነዚህን መተካት ይችላሉ፦
```typescript
acpManager.spawn("claude", "claude", ["--print", "--verbose"], {});
```
### የጊዜ ገደቦች
ነባሪው የጥያቄ ጊዜ ገደብ **120 ሰከንዶች** (2 ደቂቃዎች) ነው። ይህን መተካት ይችላሉ፦
```typescript
await acpManager.sendPrompt(sessionId, prompt, 300000); // 5 ደቂቃዎች
```
### የማግኛ መሸጎጫ
ውድ የፋይል ስርዓት ፍተሻዎችን ለማስቀረት የወኪል ማግኘት ለ**60 ሰከንዶች** በመሸጎጫ ይቀመጣል። በግድ ለማደስ፦
```typescript
import { refreshAgentCache } from "@/lib/acp";
refreshAgentCache();
```
---
## ደህንነት
### የትዕዛዝ ማስገባት ጥቃት መከላከል
ACP የትዕዛዝ ማስገባት ጥቃቶችን ለመከላከል የስሪት ትዕዛዞችን ያረጋግጣል፦
```typescript
const DISALLOWED_VERSION_COMMAND_CHARS = /[;&|<>`$\r\n]/;
```
እነዚህን ቁምፊዎች የያዙ የስሪት ትዕዛዞች ውድቅ ይደረጋሉ፦
- `;` — የትዕዛዝ መለያ
- `&` — የበስተጀርባ ሂደት
- `|` — ቧንቧ
- `<`, `>` — አቅጣጫ መቀየር
- `` ` `` — የትዕዛዝ መተካት
- `$` — የተለዋዋጭ ማስፋፋት
- `\r`, `\n` — የመስመር መጨረሻዎች
### የሁለትዮሽ ፋይል ስም ማረጋገጥ
ACP የስሪት ትዕዛዙ ሁለትዮሽ ፋይል ከሚጠበቀው የሁለትዮሽ ፋይል ስም ጋር እንደሚዛመድ ያረጋግጣል (ብጁ ወኪል ካልሆነ በስተቀር)።
### የሂደት ማግለል
እያንዳንዱ የACP ክፍለ ጊዜ በራሱ ንዑስ ሂደት ውስጥ ይሠራል። ክፍለ ጊዜው ሲያበቃ ወይም የጊዜ ገደቡ ሲያልፍ ሂደቱ ይቋረጣል።
---
## አፈጻጸም
### የማግኛ አፈጻጸም
- **የመጀመሪያ ጥሪ**፦ ~50-200ms (ለእያንዳንዱ ወኪል `version` ትዕዛዝን ያስኬዳል)
- **በመሸጎጫ የተቀመጡ ጥሪዎች**፦ <1ms (ከመሸጎጫው ይመልሳል)
- **የመሸጎጫ TTL**፦ 60 ሰከንዶች
### የጥያቄ አፈጻጸም
- **ማስጀመር**፦ ~50-100ms
- **ጥያቄ መላክ**፦ ~10-50ms
- **ምላሽ መጠበቅ**፦ በCLI ወኪሉ ላይ ይመሰረታል (በተለምዶ 1-30 ሰከንዶች)
- **ማቋረጥ**፦ ~5 ሰከንዶች (SIGTERM) + ወዲያውኑ (SIGKILL)
### የሀብት አጠቃቀም
- **በእያንዳንዱ ክፍለ ጊዜ የማህደረ ትውስታ አጠቃቀም**፦ ~10-50MB (በCLI ወኪሉ ላይ ይመሰረታል)
- **CPU**፦ አነስተኛ (በI/O የተገደበ)
- **ዲስክ**፦ ምንም
---
## መላ መፈለግ
### "Unknown agent" ስህተት
**ችግር**፦ `acpManager.spawn()` `Unknown agent: <id>` የሚል ስህተት ይጥላል
**መፍትሔ**፦ በ`spawn()` ውስጥ የተፈቀዱት እነዚህ ወኪሎች ብቻ ናቸው፦
- `claude`
- `codex`
- `gemini`
- `qwen`
ሌሎች ወኪሎች በእጅ ወይም በብጁ የወኪል መግለጫዎች አማካኝነት መጀመር አለባቸው።
### "Session not alive" ስህተት
**ችግር**፦ `acpManager.sendPrompt()` `Session ${sessionId} is not alive` የሚል ስህተት ይጥላል
**መፍትሔ**፦ ክፍለ ጊዜው ወጥቶ ወይም ተቋርጦ ሊሆን ይችላል። የክፍለ ጊዜውን ሁኔታ ይፈትሹ፦
```typescript
const session = acpManager.getSession(sessionId);
if (!session?.alive) {
// ክፍለ ጊዜውን እንደገና ያስጀምሩ
acpManager.spawn("claude", "claude", [], {});
}
```
### "ACP timeout" ስህተት
**ችግር**፦ `acpManager.sendPrompt()` `ACP timeout after 120000ms` የሚል ስህተት ይጥላል
**መፍትሔ**፦ የጊዜ ገደቡን ይጨምሩ፦
```typescript
await acpManager.sendPrompt(sessionId, prompt, 300000); // 5 ደቂቃዎች
```
### CLI አልተገኘም
**ችግር**፦ `detectInstalledAgents()` የእርስዎን CLI አያገኝም
**መፍትሔዎች**፦
1. **PATHን ይፈትሹ**፦ CLIው በስርዓትዎ PATH ውስጥ መኖሩን ያረጋግጡ
2. **የስሪት ትዕዛዙን ይፈትሹ**፦ `claude --version`ን በእጅ ያስኪዱ
3. **ፈቃዶችን ይፈትሹ**፦ CLIው ሊተገበር የሚችል መሆኑን ያረጋግጡ
4. **ብጁ ወኪል**፦ መደበኛ ላልሆኑ CLIዎች ብጁ የወኪል መግለጫ ያክሉ
### ፈቃድ ተከልክሏል
**ችግር**፦ ACP CLIውን ማስኬድ አይችልም
**መፍትሔዎች**፦
1. **የፋይል ፈቃዶችን ይፈትሹ**፦ `chmod +x /usr/local/bin/claude`
2. **ባለቤትነትን ይፈትሹ**፦ OmniRoute የማንበብ/የማስኬድ ፈቃዶች እንዳሉት ያረጋግጡ
3. **SELinux/AppArmorን ይፈትሹ**፦ የሂደት ማስጀመርን ሊያግድ ይችላል
---
## ምሳሌዎች
### ምሳሌ 1፦ Claude Codeን ማስጀመር እና መጠቀም
```typescript
import { acpManager, detectInstalledAgents } from "@/lib/acp";
// የተጫኑ ወኪሎችን ፈልግ
const agents = detectInstalledAgents();
const claude = agents.find((a) => a.id === "claude");
if (claude?.installed) {
// አዲስ ክፍለ ጊዜ አስጀምር
const session = acpManager.spawn("claude", claude.binary, ["--print", "--output-format", "json"]);
// ጥያቄ ላክ
const response = await acpManager.sendPrompt(session.id, "ኳንተም ኮምፒውቲንግን በ100 ቃላት አብራራ");
console.log("የClaude ምላሽ፦", response);
// ሀብቶችን አጽዳ
acpManager.kill(session.id);
}
```
### ምሳሌ 2፦ ምትክ ያለው ራስ-ሰር ፍለጋ
```typescript
import { acpManager, getAvailableAgents } from "@/lib/acp";
const available = getAvailableAgents();
// በመጀመሪያ Claudeን ሞክር፣ ካልተገኘ Codexን እንደ ምትክ ተጠቀም
let agentId = "claude";
if (!available.find((a) => a.id === "claude")) {
if (available.find((a) => a.id === "codex")) {
agentId = "codex";
} else {
throw new Error("ከACP ጋር ተኳሃኝ የሆነ CLI ወኪል አልተገኘም");
}
}
const agent = available.find((a) => a.id === agentId)!;
const session = acpManager.spawn(agentId, agent.binary, agent.spawnArgs);
const response = await acpManager.sendPrompt(session.id, "ሰላም!");
acpManager.kill(session.id);
```
### ምሳሌ 3፦ ብጁ ወኪል
```typescript
import { setCustomAgents, detectInstalledAgents } from "@/lib/acp";
// ብጁ CLI ወኪል መዝግብ
setCustomAgents([
{
id: "my-llm-cli",
name: "My LLM CLI",
binary: "myllm",
versionCommand: "myllm --version",
providerAlias: "my-llm-provider",
spawnArgs: ["--format", "json"],
protocol: "stdio",
},
]);
// አሁን detectInstalledAgents() "my-llm-cli"ን ያካትታል
const agents = detectInstalledAgents();
```
---
## ቀጥሎ ምን አለ?
- **[የAPI ማጣቀሻ](../reference/API_REFERENCE.md)** — የREST API መዳረሻ ነጥቦች
- **[የአቅራቢዎች ማጣቀሻ](../reference/PROVIDER_REFERENCE.md)** — ሁሉም 352 አቅራቢዎች
- **[MCP አገልጋይ](./MCP-SERVER.md)** — የModel Context Protocol ውህደት
- **[A2A አገልጋይ](./A2A-SERVER.md)** — ከወኪል-ወደ-ወኪል ፕሮቶኮል
- **[የደመና ወኪል](./CLOUD_AGENT.md)** — በደመና ላይ የተመሠረቱ ወኪሎች
---
## ማጣቀሻ
- [AionUi ፕሮጀክት](https://github.com/iOfficeAI/AionUi) — ለACP ራስ-ሰር ፍለጋ የመነሻ ሐሳብ
- [የACP ምንጭ ኮድ](../../src/lib/acp/) — የትግበራ ዝርዝሮች
- `manager.ts` — የሂደት የሕይወት ዑደት አስተዳደር
- `registry.ts` — የወኪል ፍለጋ እና ምዝገባ
- `index.ts` — ይፋዊ የAPI ወደ ውጭ ማውጫዎች

317
docs/i18n/am/docs/frameworks/AGENT-SKILLS.md Normal file
View File

@@ -0,0 +1,317 @@
# OmniRoute Agent Skills Catalog (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/AGENT-SKILLS.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/AGENT-SKILLS.md) · 🇦🇿 [az](../../../az/docs/frameworks/AGENT-SKILLS.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/AGENT-SKILLS.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/AGENT-SKILLS.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/AGENT-SKILLS.md) · 🇩🇰 [da](../../../da/docs/frameworks/AGENT-SKILLS.md) · 🇩🇪 [de](../../../de/docs/frameworks/AGENT-SKILLS.md) · 🇬🇷 [el](../../../el/docs/frameworks/AGENT-SKILLS.md) · 🇪🇸 [es](../../../es/docs/frameworks/AGENT-SKILLS.md) · 🇪🇪 [et](../../../et/docs/frameworks/AGENT-SKILLS.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/AGENT-SKILLS.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/AGENT-SKILLS.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/AGENT-SKILLS.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/AGENT-SKILLS.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/AGENT-SKILLS.md) · 🇮🇱 [he](../../../he/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/AGENT-SKILLS.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/AGENT-SKILLS.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/AGENT-SKILLS.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/AGENT-SKILLS.md) · 🇮🇩 [id](../../../id/docs/frameworks/AGENT-SKILLS.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/AGENT-SKILLS.md) · 🇮🇹 [it](../../../it/docs/frameworks/AGENT-SKILLS.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/AGENT-SKILLS.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/AGENT-SKILLS.md) · 🇰🇭 [km](../../../km/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/AGENT-SKILLS.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/AGENT-SKILLS.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/AGENT-SKILLS.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/AGENT-SKILLS.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/AGENT-SKILLS.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/AGENT-SKILLS.md) · 🇲🇲 [my](../../../my/docs/frameworks/AGENT-SKILLS.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/AGENT-SKILLS.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/AGENT-SKILLS.md) · 🇳🇴 [no](../../../no/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [or](../../../or/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/AGENT-SKILLS.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/AGENT-SKILLS.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/AGENT-SKILLS.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/AGENT-SKILLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/AGENT-SKILLS.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/AGENT-SKILLS.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/AGENT-SKILLS.md) · 🇱🇰 [si](../../../si/docs/frameworks/AGENT-SKILLS.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/AGENT-SKILLS.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/AGENT-SKILLS.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/AGENT-SKILLS.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/AGENT-SKILLS.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/AGENT-SKILLS.md) · 🇮🇳 [te](../../../te/docs/frameworks/AGENT-SKILLS.md) · 🇹🇭 [th](../../../th/docs/frameworks/AGENT-SKILLS.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/AGENT-SKILLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/AGENT-SKILLS.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/AGENT-SKILLS.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/AGENT-SKILLS.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/AGENT-SKILLS.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/AGENT-SKILLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/AGENT-SKILLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/AGENT-SKILLS.md)
---
> **የእውነት ምንጭ:** `src/lib/agentSkills/` (ካታሎግ፣ ጀነሬተር፣ ፓርሰሮች) + `skills/` ማውጫ (SKILL.md ፋይሎች)
> **መጨረሻ የተዘመነው:** 2026-08-02 — v3.8.50
Agent Skills ውጫዊ ኤጀንቶችን፣ MCP ደንበኞችን እና A2A ኦርኬስትሬተሮችን የOmniRouteን REST API እና CLI እንዴት መጠቀም እንደሚችሉ የሚያስተምሩ የተዋቀሩ SKILL.md ፋይሎች ናቸው። በOmniRoute ውስጥ ከሚፈጸሙ የLLM መሣሪያ ትርጓሜዎች ከሆኑት [Omni Skills](./SKILLS.md) በተለየ፣ Agent Skills _የሰነድ ካታሎግ_ ናቸው — በቀጥታ ወደ ኤጀንት አውድ ሊገባ የሚችል የማይለወጥ markdown።
---
## አጠቃላይ እይታ
ካታሎጉ **45 Agent Skills** (23 REST API + 21 CLI + 1 የውቅር የሥራ ፍሰት) ይዟል። እያንዳንዱ ክህሎት የሚከተሉት አሉት፦
- **መደበኛ ID** (`omni-auth`፣ `cli-serve`፣ ወዘተ)
- በ`skills/{id}/SKILL.md` ውስጥ YAML frontmatter (`name`፣ `description`) + ዝርዝር markdown ይዘት ያለው **SKILL.md** ፋይል
- ከOpenAPI ዝርዝር መግለጫ እና ከCLI መዝገብ የተወሰዱ **REST መጨረሻ ነጥቦች** (የAPI ክህሎቶች) ወይም **CLI ንዑስ ትዕዛዞች** (የCLI ክህሎቶች)
- በቀጥታ ለማምጣት **GitHub raw URL**፦ `https://raw.githubusercontent.com/diegosouzapw/OmniRoute/refs/heads/main/skills/{id}/SKILL.md`
---
## አርክቴክቸር
```
src/shared/constants/agentSkills.ts — በጥንቃቄ የተመረጠ 45-ግቤት ዝርዝር (ስም/መግለጫ/ምድብ/አካባቢ/አዶ)
src/lib/agentSkills/
catalog.ts — getCatalog(), getSkillById(), filterCatalog(), computeCoverage()
generator.ts — generateAgentSkills() SKILL.mdን ወደ skills/{id}/ ይጽፋል
openapiParser.ts — ከdocs/openapi.yaml የREST መጨረሻ ነጥቦችን ያወጣል
cliRegistryParser.ts — ከbin/cli-registry.ts የCLI ንዑስ ትዕዛዞችን ያወጣል
schemas.ts — የZod መርሃግብሮች፦ AgentSkillSchema, SkillCoverageSchema, ወዘተ
types.ts — የTypeScript በይነገጾች፦ AgentSkill, SkillCoverage, ወዘተ
skills/{id}/SKILL.md — የተመነጩ + በጥንቃቄ የተዘጋጁ markdown ፋይሎች (በድምሩ 45)
src/app/api/agent-skills/
route.ts — GET /api/agent-skills
[id]/route.ts — GET /api/agent-skills/{id}
[id]/raw/route.ts — GET /api/agent-skills/{id}/raw (text/markdown)
coverage/route.ts — GET /api/agent-skills/coverage
generate/route.ts — POST /api/agent-skills/generate (ማረጋገጫ ያስፈልጋል)
open-sse/mcp-server/tools/agentSkillTools.ts — 3 የMCP መሣሪያዎች (ዝርዝር፣ ማግኘት፣ ሽፋን)
src/lib/a2a/skills/listCapabilities.ts — የA2A ክህሎት፦ list-capabilities
```
---
## የSKILL.md ቅርጸት
```markdown
---
name: omni-providers
description: "የአቅራቢ ግንኙነቶችን ያስተዳድሩ፦ ምስክርነቶችን ያክሉ፣ ይፈትሹ፣ ያዙሩ እና ያስወግዱ።"
---
<!-- በsrc/lib/agentSkills/generator.ts የተመነጨ፤ በእጅ የተደረጉ ለውጦች ይተካሉ -->
## አጠቃላይ እይታ
...
## ማረጋገጫ
...
## መጨረሻ ነጥቦች
...
<!-- skill:custom-start -->
## ብጁ ክፍል (እንደገና በሚመነጭበት ጊዜ ይጠበቃል)
...
<!-- skill:custom-end -->
```
ጀነሬተሩ እንደገና በሚያመነጭበት ጊዜ በ`<!-- skill:custom-start -->` እና `<!-- skill:custom-end -->` መካከል ያለውን ይዘት ይጠብቃል። አሥር ክህሎቶች በጥንቃቄ የተዘጋጁ ብጁ ብሎኮች አሏቸው፦
`omni-mcp`, `omni-compression`, `cli-providers`, `cli-eval`, `omni-agents-a2a`, `omni-combos-routing`, `omni-auth`, `omni-resilience`, `omni-inference`, `cli-serve`.
---
## የREST API ማግኛ
| መጨረሻ ነጥብ | ዘዴ | መግለጫ | ማረጋገጫ |
| :--------------------------- | :--- | :---------------------------------------------------------- | :----- |
| `/api/agent-skills` | GET | ካታሎግን ይዘርዝሩ (አማራጭ `?category=api\|cli\|config&area=<area>`) | የለም |
| `/api/agent-skills/{id}` | GET | የአንድ ክህሎት ሜታዳታን ያግኙ | የለም |
| `/api/agent-skills/{id}/raw` | GET | SKILL.mdን እንደ `text/markdown` ያምጡ | የለም |
| `/api/agent-skills/coverage` | GET | የሽፋን ስታቲስቲክስ (ምን ያህል የSKILL.md ፋይሎች እንዳሉ) | የለም |
| `/api/agent-skills/generate` | POST | አመንጪውን ያስነሱ (dryRun/prune/onlyIds) | አስተዳደር |
ምሳሌ — ሁሉንም የAPI ክህሎቶች ይዘርዝሩ፦
```bash
curl "http://localhost:20128/api/agent-skills?category=api"
```
ምሳሌ — አንድ SKILL.md ያምጡ፦
```bash
curl -H "Accept: text/markdown" "http://localhost:20128/api/agent-skills/omni-providers/raw"
```
---
## የMCP ማግኛ
ሦስት የMCP መሣሪያዎች በ`read:catalog` ወሰን ስር ተመዝግበዋል፦
| መሣሪያ | መግለጫ |
| :-------------------------------- | :--------------------------------------------- |
| `omniroute_agent_skills_list` | ክህሎቶችን ይዘርዝሩ (አማራጭ `category` / `area` ማጣሪያዎች) |
| `omniroute_agent_skills_get` | ለአንድ ክህሎት በ`id` ሜታዳታ + SKILL.md ያግኙ |
| `omniroute_agent_skills_coverage` | የሽፋን ስታቲስቲክስ (API/CLI ያሉ/ጠቅላላ) |
ለወሰን ማገናኘት እና ማረጋገጫ [MCP-SERVER.md](./MCP-SERVER.md)ን ይመልከቱ።
---
## የA2A ማግኛ
የA2A ክህሎት `list-capabilities` ሙሉውን የ45 ክህሎቶች ካታሎግ እንደ markdown ሠንጠረዥ አርቲፋክት ይመልሳል። ውጫዊ ኦርኬስትሬተሮች በሚከተለው መንገድ ሊጠሩት ይችላሉ፦
```json
{
"jsonrpc": "2.0",
"id": "1",
"method": "message/send",
"params": {
"skill": "list-capabilities",
"messages": [{ "role": "user", "content": "List all capabilities" }]
}
}
```
ለፕሮቶኮል ዝርዝሮች [A2A-SERVER.md](./A2A-SERVER.md)ን ይመልከቱ።
---
## ካታሎግ — 45 የክህሎት IDዎች
### የAPI ክህሎቶች (23)
| ID | ክፍል | መግቢያ ነጥብ |
| :--------------------- | :-------------- | :-------------------------------- |
| `omni-auth` | auth | ማረጋገጫ + የክፍለ-ጊዜ አስተዳደር |
| `omni-providers` | providers | የአቅራቢ ግንኙነት አስተዳደር |
| `omni-models` | models | የሞዴል ካታሎግ እና ችሎታዎች |
| `omni-combos-routing` | combos-routing | የጥምር ማዘዋወሪያ ስልቶች |
| `omni-api-keys` | api-keys | የAPI ቁልፍ አስተዳደር |
| `omni-usage-logs` | usage-logs | የአጠቃቀም እና ወጪ ምዝግቦች |
| `omni-budget` | budget | የበጀት ጥበቃዎች |
| `omni-settings` | settings | ዓለም አቀፍ ቅንብሮች |
| `omni-proxies` | proxies | የፕሮክሲ ስብስብ አስተዳደር |
| `omni-cache` | cache | የፍቺ + የጥያቄ መሸጎጫ |
| `omni-compression` | compression | የዐውድ መጭመቂያ ሞተሮች |
| `omni-context-rtk` | context-rtk | RTK መጭመቅ |
| `omni-resilience` | resilience | የወረዳ ሰባሪዎች + የማቀዝቀዣ ጊዜዎች |
| `omni-cli-tools` | cli-tools | የCLI መሣሪያዎች REST ፕሮክሲ |
| `omni-tunnels` | tunnels | የቱነል አስተዳደር |
| `omni-sync-cloud` | sync-cloud | የደመና ማመሳሰል |
| `omni-db-backups` | db-backups | የውሂብ ጎታ ምትኬዎች |
| `omni-webhooks` | webhooks | የWebhook ክስተት አሰራጭ |
| `omni-mcp` | mcp | የMCP አገልጋይ (110 መሣሪያዎች፣ 3 ማጓጓዣዎች) |
| `omni-agents-a2a` | agents-a2a | የA2A ወኪል ፕሮቶኮል |
| `omni-version-manager` | version-manager | የስሪት እና ዝማኔ አስተዳደር |
| `omni-inference` | inference | ቀጥተኛ ኢንፈረንስ / ማጠናቀቂያዎች |
### የCLI ክህሎቶች (21)
| ID | ክፍል | የCLI ትዕዛዝ ሥር |
| :-------------------- | :----------------- | :---------------------- |
| `cli-serve` | cli-serve | `omniroute serve` |
| `cli-health` | cli-health | `omniroute health` |
| `cli-providers` | cli-providers | `omniroute providers` |
| `cli-keys` | cli-keys | `omniroute keys` |
| `cli-models` | cli-models | `omniroute models` |
| `cli-chat` | cli-chat | `omniroute chat` |
| `cli-routing` | cli-routing | `omniroute routing` |
| `cli-resilience` | cli-resilience | `omniroute resilience` |
| `cli-compression` | cli-compression | `omniroute compression` |
| `cli-contexts` | cli-contexts | `omniroute contexts` |
| `cli-cost-usage` | cli-cost-usage | `omniroute cost` |
| `cli-mcp` | cli-mcp | `omniroute mcp` |
| `cli-a2a` | cli-a2a | `omniroute a2a` |
| `cli-tunnel` | cli-tunnel | `omniroute tunnel` |
| `cli-backup-sync` | cli-backup-sync | `omniroute backup` |
| `cli-policy-audit` | cli-policy-audit | `omniroute policy` |
| `cli-batches` | cli-batches | `omniroute batch` |
| `cli-eval` | cli-eval | `omniroute eval` |
| `cli-plugins-skills` | cli-plugins-skills | `omniroute plugins` |
| `cli-setup` | cli-setup | `omniroute setup` |
| `cli-skill-collector` | cli-setup | `omniroute skills` |
### የውቅረት የሥራ ፍሰት (1)
| ID | ክፍል | መግቢያ ነጥብ |
| :----------------- | :--------------- | :--------------------- |
| `config-codex-cli` | config-codex-cli | የCodex CLI ውቅር የሥራ ፍሰት |
---
## ውጫዊ ኤጀንቶች Skillsን እንዴት እንደሚጠቀሙ
### 1. በ REST በኩል ማግኘት
```bash
# ሙሉውን ካታሎግ ያግኙ
curl "http://your-omniroute/api/agent-skills" | jq '.skills[] | {id, name, category}'
# ወደ አውድ ለማስገባት SKILL.mdን ያግኙ
curl "http://your-omniroute/api/agent-skills/omni-providers/raw" > omni-providers.md
```
### 2. በ MCP በኩል ማግኘት
```typescript
// በ Claude Desktop / Cursor MCP ደንበኛ ውስጥ፦
const result = await client.callTool("omniroute_agent_skills_list", {
category: "api",
});
// result.skills → ለእያንዳንዱ rawUrl ያለው የ AgentSkill ድርድር
```
### 3. በ A2A በኩል ማግኘት
```python
import requests
resp = requests.post("http://your-omniroute/a2a", json={
"jsonrpc": "2.0", "id": "1",
"method": "message/send",
"params": {"skill": "list-capabilities", "messages": [{"role": "user", "content": "list"}]}
})
table = resp.json()["result"]["artifacts"][0]["content"]
# table ሁሉንም 45 የ skill IDዎች + rawUrl ዓምዶች የያዘ የ markdown ሰንጠረዥ ነው
```
### 4. በቀጥታ ከ GitHub raw ማምጣት (ሰርቨር አያስፈልግም)
```bash
BASE="https://raw.githubusercontent.com/diegosouzapw/OmniRoute/refs/heads/main/skills"
curl "${BASE}/omni-providers/SKILL.md"
```
---
## ማመንጫ
ማመንጫው የተመረጠውን ካታሎግ + OpenAPI ዝርዝር መግለጫ + CLI መዝገብ በማንበብ፣ ለእያንዳንዱ ግቤት `skills/{id}/SKILL.md`ን ይጽፋል፦
```bash
# ቅድመ እይታ (የሙከራ አሂድ፣ ምንም አይጻፍም)
curl -X POST http://localhost:20128/api/agent-skills/generate \
-H "Authorization: Bearer <admin-key>" \
-H "Content-Type: application/json" \
-d '{"dryRun":true}'
# ሙሉ ዳግም ማመንጨት
curl -X POST http://localhost:20128/api/agent-skills/generate \
-H "Authorization: Bearer <admin-key>" \
-H "Content-Type: application/json" \
-d '{"dryRun":false,"prune":false}'
# የተወሰኑ IDዎችን ዳግም ማመንጨት
curl -X POST http://localhost:20128/api/agent-skills/generate \
-H "Authorization: Bearer <admin-key>" \
-H "Content-Type: application/json" \
-d '{"dryRun":false,"onlyIds":["omni-providers","cli-serve"]}'
```
የማመንጫው ምላሽ `GeneratorReport` ነው፦
```json
{
"generated": ["omni-providers", "cli-serve"],
"unchanged": [],
"pruned": [],
"orphansDetected": [],
"errors": []
}
```
---
## የሽፋን API
```bash
curl "http://localhost:20128/api/agent-skills/coverage"
```
```json
{
"api": { "have": 23, "total": 23 },
"cli": { "have": 21, "total": 21 },
"config": { "have": 1, "total": 1 },
"totalSkills": 45,
"generatedAt": "2026-08-02T00:00:00.000Z"
}
```
---
## ተዛማጅ
- [SKILLS.md](./SKILLS.md) — የ Omni Skills ማዕቀፍ (የ LLM መሣሪያ ማስገባት + የገበያ ቦታ)
- [MCP-SERVER.md](./MCP-SERVER.md) — የ MCP መሣሪያ ካታሎግ (`omniroute_agent_skills_*` መሣሪያዎች)
- [A2A-SERVER.md](./A2A-SERVER.md) — የ A2A ፕሮቶኮል (`list-capabilities` skill)
- `src/lib/agentSkills/` — ካታሎግ፣ ማመንጫ፣ ተንታኞች
- `skills/` — የተመነጩ SKILL.md ፋይሎች (45 ግቤቶች)

558
docs/i18n/am/docs/frameworks/AGENTBRIDGE.md Normal file
View File

@@ -0,0 +1,558 @@
# AgentBridge (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/AGENTBRIDGE.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/AGENTBRIDGE.md) · 🇦🇿 [az](../../../az/docs/frameworks/AGENTBRIDGE.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/AGENTBRIDGE.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/AGENTBRIDGE.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/AGENTBRIDGE.md) · 🇩🇰 [da](../../../da/docs/frameworks/AGENTBRIDGE.md) · 🇩🇪 [de](../../../de/docs/frameworks/AGENTBRIDGE.md) · 🇬🇷 [el](../../../el/docs/frameworks/AGENTBRIDGE.md) · 🇪🇸 [es](../../../es/docs/frameworks/AGENTBRIDGE.md) · 🇪🇪 [et](../../../et/docs/frameworks/AGENTBRIDGE.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/AGENTBRIDGE.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/AGENTBRIDGE.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/AGENTBRIDGE.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/AGENTBRIDGE.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/AGENTBRIDGE.md) · 🇮🇱 [he](../../../he/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/AGENTBRIDGE.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/AGENTBRIDGE.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/AGENTBRIDGE.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/AGENTBRIDGE.md) · 🇮🇩 [id](../../../id/docs/frameworks/AGENTBRIDGE.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/AGENTBRIDGE.md) · 🇮🇹 [it](../../../it/docs/frameworks/AGENTBRIDGE.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/AGENTBRIDGE.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/AGENTBRIDGE.md) · 🇰🇭 [km](../../../km/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/AGENTBRIDGE.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/AGENTBRIDGE.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/AGENTBRIDGE.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/AGENTBRIDGE.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/AGENTBRIDGE.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/AGENTBRIDGE.md) · 🇲🇲 [my](../../../my/docs/frameworks/AGENTBRIDGE.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/AGENTBRIDGE.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/AGENTBRIDGE.md) · 🇳🇴 [no](../../../no/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [or](../../../or/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/AGENTBRIDGE.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/AGENTBRIDGE.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/AGENTBRIDGE.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/AGENTBRIDGE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/AGENTBRIDGE.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/AGENTBRIDGE.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/AGENTBRIDGE.md) · 🇱🇰 [si](../../../si/docs/frameworks/AGENTBRIDGE.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/AGENTBRIDGE.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/AGENTBRIDGE.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/AGENTBRIDGE.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/AGENTBRIDGE.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/AGENTBRIDGE.md) · 🇮🇳 [te](../../../te/docs/frameworks/AGENTBRIDGE.md) · 🇹🇭 [th](../../../th/docs/frameworks/AGENTBRIDGE.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/AGENTBRIDGE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/AGENTBRIDGE.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/AGENTBRIDGE.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/AGENTBRIDGE.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/AGENTBRIDGE.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/AGENTBRIDGE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/AGENTBRIDGE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/AGENTBRIDGE.md)
---
AgentBridge የOmniRoute MITM (Man-in-the-Middle) ፕሮክሲ ሲሆን፣ ከIDE AI ወኪሎች የሚመጣውን HTTPS ትራፊክ በመጥለፍ በOmniRoute የተዋሃደ የማዘዋወሪያ ሞተር በኩል እንደገና ያዞረዋል። **10 IDE ወኪሎችን** — Antigravity፣ Kiro፣ GitHub Copilot፣ GHE Copilot፣ OpenAI Codex፣ Cursor፣ Zed፣ Claude Code፣ Open Code እና Trae (በምርመራ ላይ) — ይደግፋል፤ ይህም OmniRouteን በገበያው ላይ ለAI ኮድ ረዳቶች እጅግ ሰፊ ሽፋን ያለው MITM ፕሮክሲ ያደርገዋል።
**የዳሽቦርድ መገኛ:** `/dashboard/tools/agent-bridge`
**የጎን አሞሌ ቡድን:** Tools (ከCloud Agents በኋላ)
**እንዲሁም ይመልከቱ:** [`TRAFFIC_INSPECTOR.md`](./TRAFFIC_INSPECTOR.md) — ሁሉንም የተጠለፈ ትራፊክ በቅጽበት ይከታተሉ፤ `docs/security/MITM-TPROXY-DECRYPT.md` (git፤ ወደ `/docs` አልተጠናቀረም) — በ`/api/tools/agent-bridge/tproxy` መስመር የሚተዳደረው የLinux TPROXY ግልጽ-ዲክሪፕት ቀረጻ ሁነታ።
---
## §1 አጠቃላይ እይታ
### AgentBridge ምንድን ነው?
አንድ IDE ወኪል (ለምሳሌ፣ GitHub Copilot፣ Cursor፣ Claude Code) የAPI ጥሪ ሲያደርግ፣ በቀጥታ ከላይኛው AI አቅራቢ (OpenAI፣ Anthropic፣ ወዘተ) ጋር ይገናኛል። AgentBridge ምንም የወኪል ውቅረት ለውጥ ሳያስፈልግ ይህን ግንኙነት በTLS ደረጃ በግልጽ ሁኔታ በመጥለፍ ጥያቄውን በOmniRoute በኩል እንደገና ይጽፈዋል።
ይህም የሚከተሉትን እንድታደርጉ ያስችላችኋል፦
- **ማንኛውንም ወኪል ወደ ማንኛውም አቅራቢ እንደገና ማዘዋወር**: Copilot ከOpenAI ጋር እየተገናኘ ነው? ወደ Anthropic Claude፣ Gemini ወይም ከOmniRoute 352 አቅራቢዎች ወደ ማንኛውም አቅራቢ ያዙሩት።
- **የሞዴል ማመሳሰያዎችን መተግበር**: `gemini-3-flash` → `claude-sonnet-4.7` በአስተናጋጅ ደረጃ በግልጽ ሁኔታ።
- **ሁሉንም የወኪል ትራፊክ መመልከት**: እያንዳንዱ የተጠለፈ ጥያቄ ወደ [ትራፊክ መርማሪ](./TRAFFIC_INSPECTOR.md) ይታተማል።
- **የOmniRoute የመቋቋም ችሎታን መተግበር**: ጥምር ማዘዋወር፣ የወረዳ መቆራረጫዎች፣ ተተኪዎች እና የወጪ ክትትል ለIDE ወኪል ትራፊክም ይሰራሉ።
### ከገበያው አንጻር ያለው አቀማመጥ
| ባህሪ | 9router | anti-api | llm-interceptor | **OmniRoute AgentBridge** |
| ------------------ | :-----: | :------: | :-------------: | :-----------------------: |
| Antigravity | ✓ | ✓ | — | ✓ |
| GitHub Copilot | ✓ | ✓ | — | ✓ |
| Kiro (AWS) | ✓ | ✓ | — | ✓ |
| OpenAI Codex | — | ✓ | — | ✓ |
| Cursor IDE | ✓ | ✓ | — | ✓ |
| Zed Industries | — | ✓ | — | ✓ |
| Claude Code | — | — | ✓ | ✓ |
| Open Code | — | — | ✓ | ✓ |
| Trae | — | — | — | 🔍 በምርመራ ላይ |
| የዳሽቦርድ UI | ✓ | ✗ | ✗ | ✓ |
| ትራፊክ መርማሪ | ✗ | ✗ | ✓ | ✓ |
| OmniRoute ማዘዋወር | ✗ | ✗ | ✗ | ✓ |
| የሞዴል ማመሳሰያ UI | ✗ | ✗ | ✗ | ✓ |
| የማለፊያ ዝርዝር | ✗ | ✗ | ✓ | ✓ |
| የላይኛው CA ምስክር ወረቀት | ✗ | ✗ | ✓ | ✓ |
---
## §2 አርክቴክቸር
### 2.1 የአካላት አጠቃላይ እይታ
```
IDE ወኪል (VS Code / Cursor / ወዘተ)
│ HTTPS (ወደብ 443)
▼
/etc/hosts — 127.0.0.1 api.githubcopilot.com ← DNS ማዘዋወሪያ
│
▼
src/mitm/server.cjs (ወደብ 443፣ CJS ልጅ ሂደት)
│ ዒላማውን በ Host header SNI ይወስናል
│ በ AgentBridge CA የተፈረመ ለእያንዳንዱ SNI የTLS ሰርቲፊኬት ያመነጫል
├── ከማለፊያ ዝርዝሩ ጋር ይዛመዳል? → TCP ቀጥታ ማሳለፊያ (ዲክሪፕት አይደረግም)
├── ከዒላማ ጋር ይዛመዳል? → fetch → OmniRoute ራውተር (ወደብ 20128)
│ └── handler.intercept() — TypeScript
│ ├── maskSecrets() በጥያቄ አካል/headers ላይ
│ ├── TrafficBuffer.push() — ወደ Traffic Inspector ያትማል
│ └── fetchRouter() → /v1/chat/completions
└── ምንም ተዛማጅ የለም? → TCP ቀጥታ ማሳለፊያ (ዲክሪፕት አይደረግም)
```
### 2.2 MITM አገልጋይ (`src/mitm/server.cjs`)
ዋናው MITM አገልጋይ እንደ Node.js CJS ልጅ ሂደት ይሰራል (ያለውን CJS ኮድቤዝ እንደገና ከመጻፍ ለመቆጠብ)። የሚከተሉትን ያከናውናል፦
- ወደብ 443 ላይ ያዳምጣል (ልዩ ፈቃድ ወይም `authbind`/`setcap` ያስፈልገዋል)
- ከስርዓተ ክወናው CONNECT tunnels ይቀበላል (በ`/etc/hosts` DNS ማዘዋወሪያ በኩል)
- በ AgentBridge CA (`DATA_DIR/mitm/ca.crt`) የተፈረሙ ለእያንዳንዱ SNI የTLS ሰርቲፊኬቶችን ያመነጫል
- የዒላማውን ወኪል በ Host header አማካኝነት በ`targets/index.ts` መዝገብ ይወስናል
- ወደ `http://127.0.0.1:20128` በHTTP በኩል ወደ TypeScript handler ንብርብር ያስተላልፋል
`TARGET_HOSTS` ከ`DATA_DIR/mitm/targets.json` (በመነሳት ጊዜ በ`targets/index.ts` የሚጻፍ) ይጫናል፤ ይህም CJS አገልጋዩን እንደገና ሳያስጀምሩ ተለዋዋጭ ማዘመኖችን ይፈቅዳል።
> **Root-CA ሞዴል (#6684)።** ከላይ የተገለጸው በአንድ CA የተፈረመ ለእያንዳንዱ SNI ሰርቲፊኬት
> በ#6684 የታከለው ቋሚ root-CA ሞዴል ነው (`src/mitm/cert/rootCa.ts` +
> `src/mitm/_internal/rootCaShim.cjs`፣ ቀደም ሲል ለTPROXY በ
> `src/mitm/tproxy/dynamicCert.ts` ውስጥ የተረጋገጠውን CA/leaf ክሪፕቶ እንደገና በመጠቀም) — በዲስክ ላይ
> ያለ `server.crt`/`server.key` ጥንድ የሚያመለክተውን አሮጌውን ነጠላ ቋሚ በራሱ የተፈረመ leaf
> (`src/mitm/cert/generate.ts`፣ አሁንም ለantigravity hosts ብቻ
> የተወሰነ) ይተካል። **የፍልሰት ባህሪ**፦ አዲስ ጭነት (የቀድሞ
> `server.crt` የሌለው) root-CA ሞዴሉን በራስ-ሰር ያገኛል፤ አሮጌውን ቋሚ leaf
> አስቀድሞ ያመነ ጭነት ኦፕሬተሩ
> `MITM_ROOT_CA_ENABLED=true` አዘጋጅቶ bridge እስኪያስጀምር ድረስ እሱን መጠቀሙን ይቀጥላል (`src/mitm/cert/migration.ts`
> ንጹሕ የውሳኔ ፋንክሽን ነው — ለ
> **ማንኛውም** host leaf መፈረም የሚችል የታመነ MITM CA ከአሮጌው fixed-SAN leaf በእጅጉ የበለጠ ኃይል ስላለው፣
> አስቀድሞ ለታመነ ጭነት ሽግግሩ በጭራሽ በጸጥታ አይከናወንም)። የCA ሰርቲፊኬቱ
> አሮጌው leaf በተጠቀመበት ተመሳሳይ `omniroute-mitm.crt` trust-store slot ውስጥ ይጫናል
> (`cert/install.ts::installCaCert`) — ድርብ እምነትን ማጽዳት አያስፈልግም።
### 2.3 Handler መሠረት (`src/mitm/handlers/base.ts`)
ሁሉም የወኪል handlers `MitmHandlerBase`ን ይዘረጋሉ፦
```ts
export abstract class MitmHandlerBase {
abstract readonly agentId: AgentId;
abstract intercept(
req: IncomingMessage,
res: ServerResponse,
body: Buffer,
mappedModel: string
): Promise<void>;
// የተጠበቁ ረዳቶች፦ fetchRouter, pipeSSE, hookBufferStart, hookBufferUpdate
}
```
እያንዳንዱ handler proxy ከማድረጉ በፊት `hookBufferStart()`ን፣ ሲጠናቀቅም `hookBufferUpdate()`ን ይጠራል። እነዚህ `InterceptedRequest` ግቤቶችን ወደ `globalTrafficBuffer` ይገፋሉ ([Traffic Inspector](./TRAFFIC_INSPECTOR.md) §4ን ይመልከቱ)።
### 2.4 የዒላማዎች መዝገብ (`src/mitm/targets/`)
እያንዳንዱ ወኪል መግለጫዊ የዒላማ ፋይል አለው፦
```ts
// src/mitm/targets/copilot.ts
export const COPILOT_TARGET: MitmTarget = {
id: "copilot",
name: "GitHub Copilot",
hosts: ["api.githubcopilot.com", "copilot-proxy.githubusercontent.com"],
port: 443,
endpointPatterns: ["/chat/completions", "/v1/chat/completions"],
defaultModels: [{ id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" }],
handler: () => import("../handlers/copilot"),
riskNoticeKey: "providers.riskNotice.oauth",
};
```
መዝገቡ (`targets/index.ts`) `ALL_TARGETS`ን export ያደርጋል እና በመነሳት ጊዜ `DATA_DIR/mitm/targets.json`ን ያመነጫል።
### 2.5 ቀጥታ ማሳለፊያ እና የማለፊያ ዝርዝር (`src/mitm/passthrough.ts`)
**የማለፊያ ዝርዝር** (መጀመሪያ ይፈተሻል፣ ከዒላማ ማዛመድ በላይ ቅድሚያ አለው)፦
- ነባሪ ስርዓተ ጥለቶች፦ የባንክ hosts፣ `.gov.`፣ OAuth/SSO providers (Okta፣ Auth0)፣ ወዘተ
- የተጠቃሚ ስርዓተ ጥለቶች፦ በDB table `agent_bridge_bypass` ውስጥ ይከማቻሉ
- የሚታለፉ hosts ግልጽ TCP tunnel ያገኛሉ — TLS **በፍጹም ዲክሪፕት አይደረግም**
**የቀጥታ ማሳለፊያ ነባሪ** (ከዒላማ ጋር ሳይዛመድ እና በማለፊያ ዝርዝሩ ውስጥ ሳይሆን)፦
- እንዲሁም TCP tunnel ይቀበላል — ግንኙነቶች ፈጽሞ አይቋረጡም
- AgentBridge አጠቃላይ የስርዓቱን HTTPS ትራፊክ እንዳያውክ ይከላከላል
የማዞሪያ ቅድሚያ፦
```
የማለፊያ ዝርዝር → ከዒላማ ጋር ማዛመድ → ቀጥታ ማሳለፊያ
```
### 2.6 Upstream CA ሰርቲፊኬት (`src/mitm/upstreamTrust.ts`)
ብጁ CA ላላቸው የድርጅት አውታረ መረብ አካባቢዎች፦
```bash
AGENTBRIDGE_UPSTREAM_CA_CERT=/path/to/corporate-ca.pem
```
ሲዘጋጅ፣ የ`undici`ን ዓለም አቀፋዊ dispatcher ተጨማሪውን CA ሰርቲፊኬት እንዲጠቀም ያዋቅራል፤ ይህም AgentBridge በድርጅታዊ TLS termination proxies በኩል upstream providersን እንዲደርስ ያስችለዋል።
### 2.7 ሚስጥር መሸፈኛ (`src/mitm/maskSecrets.ts`)
ገለልተኛው clean-room scanner የጥያቄ አካላት እና የማረጋገጫ headers ወደ Traffic Inspector buffer ወይም ወደ ማንኛውም log ከመግባታቸው
**በፊት** በእነሱ ላይ ይተገበራል። አንድ መስመራዊ ቅኝት ያከናውናል፦
- በ`sk-` / `ak-` / `pk-` የሚጀምሩ tokens (የOpenAI/Anthropic ዓይነት)
- RFC 6750 `Authorization: Bearer <token>` ማረጋገጫዎች፣ ለሙሉ token ቅድሚያ በመስጠት
- አጠቃላይ ረጅም ግልጽ ያልሆኑ tokens (≥40 ቁምፊዎች)፣ ነጥብ ያላቸውን እና padding ያላቸውን ቅርጾች ጨምሮ
`sanitizeHeaders()` የቀሩትን ስሞች ወደ lowercase ይቀይራል፣ የarray እሴቶችን በተወሰነ ቅደም ተከተል ያገናኛል፣
የጋራውን hop-by-hop/framing denylist (የproxy ማረጋገጫን ጨምሮ) ይጥላል፣ `cookie` እና
`set-cookie`ን ሙሉ በሙሉ ይሰውራል፣ እና የማረጋገጫ እሴቶችን ወደ scanner ያስተላልፋል።
---
## §3 ማዋቀር
### 3.1 የMITM አገልጋዩን ማስጀመር/ማቆም
በ`/dashboard/tools/agent-bridge` የሚገኘውን AgentBridge Server Card ይጠቀሙ፦
| ድርጊት | መግለጫ |
| ------------------ | --------------------------------------------------------- |
| አገልጋይ አስጀምር | `src/mitm/server.cjs`ን በport 443 ላይ ያስነሳል |
| አገልጋይ አቁም | የልጅ ሂደቱን በሥርዓት ያቋርጣል |
| አገልጋይ ዳግም አስጀምር | ማቆም + ማስጀመር (የዒላማ ለውጦችን ተግባራዊ ያደርጋል) |
| የምስክር ወረቀትን እመን | `DATA_DIR/mitm/ca.crt`ን በOS የታመኑ ምስክር ወረቀቶች ማከማቻ ውስጥ ይጭናል |
| የምስክር ወረቀት አውርድ | በእጅ ለመጫን `ca.crt`ን ያወርዳል |
| የምስክር ወረቀት ዳግም ፍጠር | አዲስ የCA ቁልፍ ጥንድ ይፈጥራል (ሁሉም ነባር የወኪል ምስክር ወረቀቶች ዋጋ ያጣሉ) |
### 3.2 የምስክር ወረቀቱን ማመን
IDEs የMITM ግንኙነቱን ከመቀበላቸው በፊት የAgentBridge CA ምስክር ወረቀት በOS የታመነ መሆን አለበት።
**Linux (NSS — Chrome/Firefox):**
```bash
certutil -A -d sql:$HOME/.pki/nssdb -n "OmniRoute AgentBridge" -t CT,, -i ~/.omniroute/mitm/ca.crt
```
**macOS (Keychain):**
```bash
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain ~/.omniroute/mitm/ca.crt
```
**Windows (certmgr):**
```powershell
certutil -addstore -f Root $env:USERPROFILE\.omniroute\mitm\ca.crt
```
ወይም በዳሽቦርዱ ውስጥ ያለውን "Trust Cert" አዝራር ይጠቀሙ (ለOSዎ ተገቢውን ትዕዛዝ ያስኬዳል፤ ካስፈለገም የsudo ጥያቄ ያሳያል)።
#### በElectron ላይ የተመሠረቱ IDEs የOS የታመኑ ምስክር ወረቀቶች ማከማቻን ችላ ይላሉ (`NODE_EXTRA_CA_CERTS`)
አንዳንድ IDEs — በተለይም **Antigravity IDE** እና ሌሎች ከElectron / VS Code የተወረሱ መተግበሪያዎች —
ለወጪ `fetch`/HTTPS የOS የታመኑ ምስክር ወረቀቶች ማከማቻን **የማይመለከት**
የራሳቸውን Node.js runtime አብረው ይይዛሉ። CAውን በOS/NSS ደረጃ ማመን ለIDEው ቤተኛ **backend**
(ለምሳሌ፣ የOS CA bundleን የሚጠቀም Go language server) በቂ ነው፤ ነገር ግን **Electron frontend** አሁንም
TLSን ማስኬድ ይሳነዋል — ይህም መተግበሪያው _ከመለያ እንደወጣ_ ወይም _"connection error"_
እንደሚያሳይ ሆኖ ይገለጣል፤ የMITM ምዝግብ ማስታወሻው የbackend bootstrap ጥሪዎች `200` እየመለሱ መሆኑን
ቢያሳይም። ሁለት ደረጃዎች ያስፈልጋሉ፣ ሁለቱም አስፈላጊ ናቸው፦
1. runtimeን በቀጥታ ወደ CAው ያመልክቱ፦
```bash
export NODE_EXTRA_CA_CERTS=/path/to/omniroute-agentbridge-ca.crt
```
2. **IDEውን ከዚያ shell ውስጥ ያስጀምሩ።** ከዴስክቶፕ አዶ / Dock / Start menu ማስጀመር
የshell exportsን **አይወርስም**፤ እንዲሁም `~/.config/environment.d/*.conf` ተግባራዊ የሚሆነው
ከአዲስ ግራፊካዊ መግቢያ በኋላ ብቻ ነው። መጀመሪያ IDEውን ሙሉ በሙሉ ይዝጉ — የElectron singleton lock ማለት ሁለተኛ
ማስጀመር ነባሩን ሂደት ብቻ ትኩረት ያደርግበታል፣ አዲሱም environment ችላ ይባላል።
ከላይ ያለው የOS እምነት + NSS ደረጃ አሁንም አስፈላጊ ነው (በአንዳንድ የማረጋገጫ ፍሰቶች የሚጠቀሙበት
የChromium አውታረ መረብ stack የእያንዳንዱን ተጠቃሚ NSS store ያነባል፤ እንዲሁም በአካባቢው
የታመነ CA የሚሽራቸው ለ`*.googleapis.com` የራሱ static pins አሉት)። `NODE_EXTRA_CA_CERTS` በተጨማሪ የNode `fetch` መንገድን ይሸፍናል።
### 3.3 የDNS ማዘዋወር
ለመጥለፍ ለሚፈልጉት ለእያንዳንዱ ወኪል፣ የAPI host(ዎቹ) ወደ `127.0.0.1` resolve መሆን አለባቸው። በSetup Wizard ውስጥ ለአንድ ወኪል DNSን ሲቀያይሩ AgentBridge የ`/etc/hosts` ግቤቶችን በራስ-ሰር ያስተዳድራል።
ለGitHub Copilot የ`/etc/hosts` ግቤቶች ምሳሌ፦
```
127.0.0.1 api.githubcopilot.com
127.0.0.1 copilot-proxy.githubusercontent.com
```
### 3.4 የሞዴል ማዛመድ
የምንጭ → ዒላማ ማዛመጃዎችን ለመወሰን በእያንዳንዱ የወኪል ካርድ ውስጥ ያለውን Model Mapping Table ይጠቀሙ፦
| የምንጭ ሞዴል (የወኪሉ ቤተኛ) | የዒላማ ሞዴል (OmniRoute) |
| ------------------- | -------------------- |
| `gpt-4o` | `claude-sonnet-4.7` |
| `*` (wildcard) | `claude-haiku-4.7` |
Wildcard `*` ማንኛውንም ያልታወቀ ሞዴል ወደተገለጸው ዒላማ ያዛምዳል። በ`agent_bridge_mappings` ሰንጠረዥ ውስጥ ይቀመጣል።
> **ጠቃሚ ምክር — የወኪሉን እውነተኛ የሞዴል IDs ያግኙ።** አንድ IDE ከUI መለያዎቹ የሚለዩ እና
> በዋና ስሪቶች መካከል የሚለወጡ የሞዴል ስሞችን ሊልክ ይችላል። ለምሳሌ፣ **Antigravity 2**
> `gemini-3.1-pro-low`፣ `gemini-pro-agent` እና `gemini-3.1-flash-lite`ን በኔትወርኩ ላይ ይልካል — በአሮጌ ሰነዶች
> የሚታየውን `gemini-2.5-pro` አይደለም። ተዛማጅ ማዛመጃ ሳይኖር አንድ chat ይላኩ፦ MITM
> ትክክለኛውን ገቢ `model:` በምዝግብ ማስታወሻ ይመዘግባል እና ጥያቄውን እንዲያልፍ ያደርጋል። ያንን ቀጥተኛ እሴት ያዛምዱ፤ ከዚያም
> ቀጣዩ ጥያቄ ተጠልፎ ወደ ዒላማዎ ይዘዋወራል።
### 3.5 የአደጋ ማስታወቂያ
AgentBridge፣ IDEው ከዋና አቅራቢዎች ጋር ራሱን ለማረጋገጥ የሚጠቀምባቸውን ማረጋገጫዎች (OAuth tokens፣ API keys) ይጠልፋል። እነዚህ **በምዝግብ ማስታወሻ ከመመዝገባቸው በፊት ይሸፈናሉ** (§2.7ን ይመልከቱ)፤ ነገር ግን ለOmniRoute MITM layer ይታያሉ። የእያንዳንዱ ወኪል የመጀመሪያ ማግበር ሊዘጋ የሚችል የአደጋ ማስታወቂያ modal ያሳያል።
### 3.6 ጥገና እና ምርመራዎች
ዳሽቦርዱ ከዚህ በፊት UI ያልነበራቸውን የMITM ክዋኔ መንገዶች የሚያሳይ **Maintenance & Diagnostics** ካርድ (`AgentBridgeMaintenanceCard`፣ በ`src/app/(dashboard)/dashboard/tools/agent-bridge/components/` ውስጥ) ያቀርባል። ንዑስ ርዕሱ፦ _"የመያዝ ሂደቱን በራስ-ሰር ይፈትሹ፣ የቀረውን የስርዓት ሁኔታ ይቀልብሱ፣ እና ማዋቀርዎን በማሽኖች መካከል ያንቀሳቅሱ።"_ የካርዱ የclient helpers በ`src/lib/inspector/agentBridgeMaintenanceApi.ts` ውስጥ ይገኛሉ።
| አዝራር | መስመር | የሚያከናውነው |
| ------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ምርመራ** | `GET /api/tools/agent-bridge/diagnose` | የመቅረጽ ሂደቱን ራስ-ሙከራ ያካሂዳል፣ እንዲሁም ለእያንዳንዱ ፍተሻ ሪፖርት ያሳያል (✓/✗ + የማስተካከያ ፍንጭ)። |
| **ጥገና** | `POST /api/tools/agent-bridge/repair` | በብልሽት ወይም በSIGKILL ምክንያት የተረፈውን ባለቤት-አልባ የMITM ስርዓት ሁኔታ (የDNS ማጭበርበሪያ ግቤቶች፣ root CA፣ የስርዓት proxy) ይቀለብሳል። Idempotent ነው — ሁኔታው ንጹሕ ሲሆን "የሚጠገን ነገር የለም" ብሎ ሪፖርት ያደርጋል። |
| **CAን አስወግድ** | `DELETE /api/tools/agent-bridge/cert` | የMITM root CAን ከOS የእምነት ማከማቻ ያስወግዳል፣ እምነቱንም ይሰርዛል (ግልጽ፣ idempotent)። CAው በአሁኑ ጊዜ የታመነ ሲሆን ብቻ ይታያል፤ በቦታው ላይ "CAን አስወግድ?" የሚል ማረጋገጫ ያስፈልገዋል። |
| **ውቅር ላክ** | `GET /api/tools/agent-bridge/config` | ተንቀሳቃሹን የውቅር JSON ያወርዳል (§3.7ን ይመልከቱ)። |
| **ውቅር አስገባ** | `POST /api/tools/agent-bridge/config` | ከዚህ በፊት ወደ ውጭ የተላከ የውቅር JSON ይሰቅላል (§3.7ን ይመልከቱ)። |
**የምርመራ ፍተሻዎች** (`summarizeDiagnostics()` በ`src/mitm/inspector/diagnostics.ts` ውስጥ)። መስመሩ ለእያንዳንዱ ፍተሻ ውጤት ያለውን probe ያስኬዳል፣ እና booleansን ወደ pure summarizer ያስገባል፤ አንድ `healthy` ውሳኔ ከእያንዳንዱ ውድቀት ፍንጭ ጋር ይመለሳል፦
| የፍተሻ ስም | የሚያረጋግጠው | በውድቀት ጊዜ የሚሰጥ ፍንጭ |
| ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `server-running` | የMITM server ሂደት ንቁ ነው | "የMITM server እየሰራ አይደለም። ከAgentBridge ትር ያስጀምሩት።" |
| `server-reachable` | የMITM server በportው ላይ ግንኙነቶችን ይቀበላል (TCP probe) | "የMITM server በportው ላይ ግንኙነቶችን እየተቀበለ አይደለም። portው ነጻ መሆኑንና ከእሱ ጋር bind ለማድረግ ፈቃድ እንዳለዎት ያረጋግጡ።" |
| `cert-exists` | የMITM certificate በዲስክ ላይ ተፈጥሯል | "እስካሁን ምንም የMITM certificate አልተፈጠረም። ከAgentBridge ትር አንድ ይፍጠሩ።" |
| `cert-trusted` | የMITM root CA በOS የእምነት ማከማቻ ውስጥ አለ | "የMITM root CA በOS ማከማቻ አልታመነም፣ ስለዚህ የTLS ጣልቃ ገብነት አይሳካም። certificateን ከAgentBridge ትር ያመኑት።" |
| `dns-configured` | የታለሙ hostnameዎች በ`/etc/hosts` ውስጥ ተጭበርብረዋል | "የታለሙ hostnameዎች በ/etc/hosts ውስጥ አልተጭበረበሩም፣ ስለዚህ traffic ወደ proxyው ፈጽሞ አይደርስም። መቅረጽ ለሚፈልጉት agent(ዎች) DNSን ያንቁ።" |
**የባለቤት-አልባ ሁኔታ ሰንደቅ፦** ገጹ በብልሽት ምክንያት የቀረ ሁኔታን (DNS spoof / CA / system proxy) ሲያገኝ፣ ካርዱ የአምበር ቀለም ሰንደቅ ያሳያል — _"አንድ ቀዳሚ session የስርዓት ሁኔታን (DNS spoof፣ CA ወይም system proxy) ትቶ ሄዷል። ለማጽዳት ጥገናን ያስኪዱ።"_ — እና **ጥገና** አዝራሩን አጉልቶ ያሳያል። `Repair` የProxyBridge `--cleanup` flag የመተግበሪያ-ንብርብር አቻ ነው (`repairMitm()`ን በ`src/mitm/manager.ts` ውስጥ ይወክላል)።
> ተደጋጋሚ የsudo ጥያቄዎችን ለማስወገድ የMITM root CA በማቆም/ማስጀመር መካከል እንደተጫነ
> ይቆያል (ከmitmproxy/Charles ጋር ተመሳሳይ ባህሪ)፣ ስለዚህ ማስወገዱ በማቆም ጊዜ በራስ-ሰር
> ከሚከሰት ነገር ይልቅ ግልጽ የ**CAን አስወግድ** እርምጃ ነው።
### 3.7 ተንቀሳቃሽ ውቅር ማስገባት/መላክ
AgentBridge **በኦፕሬተሩ ሊስተካከል የሚችለውን** ሁኔታ ስሪት ወዳለው JSON blob serialize ማድረግ ይችላል፣ በዚህም አንድ setup በተለያዩ ማሽኖች ላይ እንዲደገም ያስችላል። serializerው `src/lib/inspector/configPortability.ts` (`exportConfig()` / `importConfig()`) ሲሆን፣ በ`AgentBridgeConfigSchema` ይረጋገጣል።
ወደ ውጭ የሚላከው በትክክል ሦስት ክፍሎችን ያካትታል (አብሮገነብ ነባሪዎች ሆን ተብለው **አይላኩም**፣ ስለዚህ ማስገባት በፍጹም እነሱን አያባዛም ወይም ከእነሱ ጋር አይጋጭም)፦
| መስክ | ምንጭ | ማስታወሻዎች |
| ---------------- | ----------------------------------------------------------- | --------------------------------------------------------------- |
| `bypassPatterns` | በተጠቃሚ የተገለጹ bypass patternዎች (`agent_bridge_bypass`) | ነባሪ bank/gov/okta patternዎች አይካተቱም |
| `customHosts` | የTraffic Inspector custom hostዎች (`inspector_custom_hosts`) | እያንዳንዱ፦ `{ host, kind: "llm"\|"app"\|"custom", label? }` |
| `agentMappings` | ለእያንዳንዱ agent የmodel mappingዎች (`agent_bridge_mappings`) | mappingዎች ላሉት ሁሉም agentዎች `{ [agentId]: [{ source, target }] }` |
```jsonc
// GET /api/tools/agent-bridge/config
{
"version": 1,
"bypassPatterns": ["*.internal.example.com"],
"customHosts": [{ "host": "api.example.com", "kind": "llm", "label": null }],
"agentMappings": {
"copilot": [{ "source": "gpt-4o", "target": "claude-sonnet-4.7" }],
},
}
```
**የማስገባት ባህሪ** (`POST /api/tools/agent-bridge/config`)፦ bypass patternዎች እና የእያንዳንዱ agent mappingዎች **ሙሉ በሙሉ ይተካሉ**፤ custom hostዎች **በidempotent መንገድ** ይጨመራሉ (`INSERT OR IGNORE`)። ምላሹ ከእያንዳንዱ ስንት እንደተተገበሩ ሪፖርት ያደርጋል፦
```jsonc
{ "ok": true, "bypassPatterns": 1, "customHosts": 1, "agents": 1 }
```
በውቅሩ ውስጥ **የማይካተቱት**፦ የሰርቨሩ የመስራት ሁኔታ፣ የምስክር ወረቀት ዱካዎች፣ የእያንዳንዱ ወኪል DNS ሁኔታ፣ የላይኛው CA ዱካ እና የTPROXY ቅንብሮች ናቸው—እነዚህ ተንቀሳቃሽ ምርጫዎች ሳይሆኑ የአስተናጋጅ/የአሂድ-ጊዜ ሁኔታዎች ናቸው።
---
## §4 የእያንዳንዱ ኤጀንት ማጣቀሻ
| # | ኤጀንት | ሁኔታ | የሚጠለፉ አስተናጋጆች | የማረጋገጫ አይነት |
| --- | ------------------ | ----------- | ------------------------------------------------------------------ | -------------- |
| 1 | **Antigravity** | ✅ የሚደገፍ | `daily-cloudcode-pa.googleapis.com`, `cloudcode-pa.googleapis.com` | Firebase OAuth |
| 2 | **Kiro (AWS)** | ✅ የሚደገፍ | `prod.kiro.aws`, `dev.kiro.aws` | AWS SigV4 |
| 3 | **GitHub Copilot** | ✅ የሚደገፍ | `api.githubcopilot.com`, `copilot-proxy.githubusercontent.com` | GitHub OAuth |
| 4 | **OpenAI Codex** | ✅ የሚደገፍ | `api.openai.com` (የCodex ዱካዎች), `chatgpt.com` | OpenAI ቁልፍ |
| 5 | **Cursor IDE** | ✅ የሚደገፍ | `api2.cursor.sh`, `api.cursor.sh` | Cursor OAuth |
| 6 | **Zed Industries** | ✅ የሚደገፍ | `api.zed.dev`, `llm.zed.dev` | Zed OAuth |
| 7 | **Claude Code** | ✅ የሚደገፍ | `api.anthropic.com` (በምርጫ የሚነቃ) | Anthropic ቁልፍ |
| 8 | **Open Code** | ✅ የሚደገፍ | `openrouter.ai`, `api.openai.com` (የzen ዱካዎች) | API ቁልፍ |
| 9 | **Trae** | 🔍 በምርመራ ላይ | ገና አልተወሰነም — §8ን ይመልከቱ | ገና አልተወሰነም |
### የማዋቀሪያ አዋቂ ደረጃዎች (ለእያንዳንዱ ኤጀንት)
እያንዳንዱ የኤጀንት ካርድ ባለ3-ደረጃ የማዋቀሪያ አዋቂ አለው፦
1. **ቅድመ ሁኔታዎችን ያረጋግጡ** — አገልጋዩ እየሰራ ነው? ሰርተፍኬቱ የታመነ ነው? IDE ተጭኗል (በራስ-ሰር የተገኘ)?
2. **DNSን ያንቁ** — የ`/etc/hosts` ግቤቶችን ያክላል (sudo ያስፈልጋል)። የትኞቹ መስመሮች እንደሚጨመሩ በትክክል ያሳያል።
3. **ሞዴሎችን ያዛምዱ** — አማራጭ የሞዴል ማዛመጃ ሰንጠረዥ። ሁሉን አቀፍ ምልክቶች ተቀባይነት አላቸው።
### ኤጀንትን ማግኘት
ለኤጀንቶች 1–8፣ AgentBridge የIDE ጭነትን በራስ-ሰር ለማግኘት ይሞክራል፦
```ts
export async function detectAgent(agentId: AgentId): Promise<DetectionResult>;
// ይመልሳል፦ { installed: boolean, version?: string, path?: string }
```
ማግኘቱ ለOS የተለዩ ዱካዎችን እና የሁለትዮሽ ፋይል ማረጋገጫዎችን ይጠቀማል (ለምሳሌ፣ ለCopilot `code --list-extensions | grep github.copilot`፣ ለAntigravity `~/.config/antigravity/`)።
---
## §5 ደህንነት
### የተተገበሩ ጥብቅ ደንቦች
| ደንብ | አተገባበር |
| --------------------------------- | ------------------------------------------------------------------------------------ |
| **#12** `sanitizeErrorMessage` | ሁሉም የተቆጣጣሪ ስህተቶች ምላሽ ከመሰጠታቸው ወይም ወደ ቋት ከመግባታቸው በፊት ይጸዳሉ |
| **#13** የShell env ማስተላለፍ | የ`/etc/hosts` አርትዖቶች የ`env` አማራጭን ይጠቀማሉ — የዱካዎች የሕብረቁምፊ ማስገባት የለም |
| **#15 + #17** `isLocalOnlyPath()` | `/api/tools/agent-bridge/` LOCAL_ONLY + SPAWN_CAPABLE ነው — ከማረጋገጫ በፊት loopback ይገደዳል |
### ለስሱ አስተናጋጆች የማለፊያ ዝርዝር
የማለፊያ ዝርዝሩ የፋይናንስ ተቋማት፣ OAuth/SSO አቅራቢዎች እና ሌሎች ለስሱ አስተናጋጆች **ፈጽሞ ዲክሪፕት እንዳይደረጉ** ያረጋግጣል። የእነሱ TLS ትራፊክ እንደ ግልጽ TCP ቦይ ያልፋል — OmniRoute የተፈታውን ጽሑፍ ፈጽሞ አያይም።
ነባሪ የማለፊያ ንድፎች የሚከተሉትን ያካትታሉ፦
- `*.bank.*`, `*.gov.*` (ፋይናንስ/መንግሥት)
- `*.okta.com`, `*.auth0.com`, `*.microsoft.com` (SSO/ማንነት)
- `*.apple.com`, `*.icloud.com` (የApple ስርዓት አገልግሎቶች)
በተጠቃሚ የተጨመሩ የማለፊያ ንድፎች በ`agent_bridge_bypass` ሰንጠረዥ ውስጥ ይከማቻሉ እና ከሁሉም ነገር ቅድሚያ ያገኛሉ።
### ሚስጥርን መሸፈን
ከ`src/mitm/maskSecrets.ts` የሚገኘው `maskSecrets()` ይተገበራል፦
- ከ`TrafficBuffer.push()` በፊት በእያንዳንዱ የጥያቄ አካል ላይ
- ከመመዝገብ ወይም ከማሰራጨት በፊት በእያንዳንዱ ራስጌ ላይ
ንድፎች፦ `sk-`/`ak-`/`pk-` ቅድመ ቅጥያ ያላቸው ቶከኖች፣ `Bearer` ቶከኖች፣ እና 40 ወይም ከዚያ በላይ ቁምፊዎች ያሏቸው አጠቃላይ ቶከኖች።
### የUpstream CA ሰርተፍኬት
`AGENTBRIDGE_UPSTREAM_CA_CERT` ሲዘጋጅ፣ ፋይሉ ሲጀመር ይነበባል። ዱካው ካለ ነገር ግን ፋይሉ ሊነበብ የማይችል ከሆነ፣ AgentBridge ግልጽ ስህተት ይመዘግባል እና መጀመርን ይከለክላል (በድርጅታዊ አካባቢዎች ውስጥ ዝም ያሉ የTLS አለመሳካቶችን ይከላከላል)።
### የሚታወቁ ገደቦች
- **Port 443 ልዩ ፈቃድ ያስፈልገዋል**፦ በLinux ላይ፣ AgentBridge በNode ሁለትዮሽ ፋይል ላይ `setcap 'cap_net_bind_service=+ep'` ያስፈልገዋል፣ ወይም በ`authbind` በኩል መስራት አለበት። የማዋቀሪያ አዋቂው ለOS የተለዩ መመሪያዎችን ያሳያል።
- **IDEን እንደገና ማስጀመር ያስፈልጋል**፦ ከDNS ማዞሪያ በኋላ፣ አዲሱ የአስተናጋጅ መፍትሔ ተግባራዊ እንዲሆን IDEው እንደገና መጀመር አለበት።
- **በቋሚነት የተቀመጡ OAuth ቶከኖች**፦ አንዳንድ ኤጀንቶች (Kiro፣ Antigravity) የOAuth ማደሻ ቶከኖችን በአካባቢው ያከማቻሉ። እነዚህ ለAgentBridge ግልጽ ናቸው — በእያንዳንዱ ጥያቄ ውስጥ ያለውን Bearer ቶከን ያያል፣ ይህም ከመመዝገቡ በፊት ይሸፈናል።
- **የElectron የፊት ገጽ `NODE_EXTRA_CA_CERTS` ያስፈልገዋል**፦ የፊት ገጻቸው በአብሮ በተጠቃለለ Node/Electron runtime ላይ የሚሰራ IDEዎች የOS/NSS የእምነት ማከማቻን ችላ ይላሉ እና `NODE_EXTRA_CA_CERTS` ተዘጋጅቶ ከshell መጀመር አለባቸው (§3.2ን ይመልከቱ)። ሲጎድል የሚታየው ምልክት፦ የIDE backend ማረጋገጫውን ያልፋል (MITM `200`ዎችን ያሳያል) ነገር ግን UIው እንደወጣ ይቆያል።
- **የአንድ IDE ብዙ ጭነቶች እርስ በርሳቸው ነጻ ናቸው**፦ የስርዓት ጭነት (ለምሳሌ፣ `/usr/share/antigravity/antigravity`) እና በተጠቃሚ አካባቢ ያለ "Full" ጭነት (ለምሳሌ፣ `~/AntigravityIDE_Full/antigravity-ide`) የራሳቸው runtimes ያላቸው የተለያዩ ሂደቶች ናቸው — እያንዳንዳቸው CAው ተጨምሮባቸው እንደገና መጀመር አለባቸው። እንደገና ከማስጀመርዎ በፊት የትኛው እየሰራ እንደሆነ በሁለትዮሽ ፋይሉ ዱካ ይለዩ።
- **ማንነት የሚወሰነው በኤጀንቱ የስርዓት ጥያቄ እንጂ በተዛወረው ሞዴል አይደለም**፦ የኤጀንትን ሞዴል ወደ ሌላ አቅራቢ ሲያዛምዱ፣ IDEው ያንን ወደ ስርዓት ጥያቄው ስለሚያስገባ ምላሹ አሁንም የኤጀንቱን ቤተኛ ማንነት ይገልጻል (ለምሳሌ፣ Antigravity "የሚያንቀሳቅሰኝ Gemini ነው" ብሎ ይመልሳል)። ሞዴሉን ማን እንደሆነ በመጠየቅ ሳይሆን ትክክለኛውን backend በ`call_logs` / `proxy_logs` (`provider`, `model`, `target_format`) ውስጥ ያረጋግጡ።
---
## §6 ችግር አፈታት
### የፖርት 443 ግጭት
ሌላ ሂደት አስቀድሞ ፖርት 443 ላይ እያዳመጠ ከሆነ (የድር አገልጋይ፣ VPN፣ ወዘተ)፦
```bash
lsof -i :443 # ሂደቱን ያግኙ
sudo fuser -k 443/tcp # በግድ ያቋርጡ (በጥንቃቄ ይጠቀሙ)
```
እንደ አማራጭ፣ በAgentBridge ቅንብሮች ውስጥ ልዩ ፈቃድ የማይፈልግ ፖርት ያዋቅሩ እና የ`iptables` / `pf` ማዘዋወሪያ ደንቦችን ያዘጋጁ።
### ሰርተፍኬቱ የታመነ አይደለም
AgentBridgeን ካስጀመሩ በኋላ IDEው የTLS ስህተቶችን ካሳየ፦
1. ሰርተፍኬቱ መጫኑን ያረጋግጡ፦ `security find-certificate -c "OmniRoute AgentBridge"` (macOS) ወይም `certutil -L -d sql:$HOME/.pki/nssdb` (Linux/NSS)
2. አንዳንድ መተግበሪያዎች የራሳቸውን የታመኑ ሰርተፍኬቶች ማከማቻ ይይዛሉ (Firefox፣ Chrome በLinux ላይ)። "Trust Cert"ን እንደገና ያስኪዱ እና ለNSS/Firefox የተለየውን የሰርተፍኬት ማከማቻ ያረጋግጡ።
3. እምነት ከሰጡ በኋላ IDEውን እንደገና ያስጀምሩ — በሂደት ላይ ያሉ የTLS ክፍለ ጊዜዎች የድሮውን የእምነት ሁኔታ ይጠቀማሉ።
### የታመነ CA ቢኖርም IDEው ከመለያ ወጥቷል / "connection error"
ምልክት፦ DNSን ካዘዋወሩ እና ለCAው እምነት ከሰጡ በኋላ፣ Electronን መሠረት ያደረገ IDE (ለምሳሌ Antigravity)
**ከመለያ የወጣ** ሆኖ ይከፈታል ወይም የማረጋገጫ/ግንኙነት ስህተት ያሳያል፤ ሆኖም የMITM ምዝግብ
የማስነሻ ጥሪዎቹ (`loadCodeAssist`፣ `fetchAvailableModels`፣ …) `200` እየመለሱ መሆናቸውን ያሳያል።
ምክንያት፦ ከIDEው ጋር የታሸገው **የNode/Electron አሂድ አካባቢ የስርዓተ ክወናውን የታመኑ ሰርተፍኬቶች ማከማቻ ችላ ይላል**። ነባሪው
የጀርባ ክፍል (የGo ቋንቋ አገልጋይ) የስርዓተ ክወናውን CA ያምናል እና ማረጋገጫ ያከናውናል፣ ነገር ግን የElectron የፊት ክፍል
አያምነውም — ስለዚህ UIው ከመስመር ውጭ እንደሆነ ያስባል።
መፍትሔ (ሁለቱም ደረጃዎች)፦ `NODE_EXTRA_CA_CERTS=<ca.crt>`ን export ያድርጉ **እና IDEውን ከዚያ
shell እንደገና ያስጀምሩት**፤ ከዴስክቶፕ አዶው አይደለም። በመጀመሪያ IDEውን ሙሉ በሙሉ ይዝጉ — የElectron singleton lock
ማለት ሁለተኛው ማስጀመር ነባሩን ሂደት ብቻ ወደ ትኩረት ያመጣል፣ አዲሱ አካባቢም ችላ ይባላል። §3.2ን ይመልከቱ።
ይህ ራሱን የቻለ ኤጀንት በMITM በኩል የሚሠራ ሲሆን የIDEው ልዩነት ግን
በተመሳሳይ ውቅር ላይ እንደማይሠራ ከሚገልጽ ክፍት የዋና ምንጭ ሪፖርት ጋር ይመሳሰላል።
### DNS አልተሰራጨም
`/etc/hosts` መዘመኑን ያረጋግጡ፦
```bash
grep "omniroute\|127.0.0.1.*github\|127.0.0.1.*cursor" /etc/hosts
```
የDNS መሸጎጫውን ያጽዱ፦
```bash
# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
# Linux (systemd-resolved)
sudo systemctl restart systemd-resolved
# Windows
ipconfig /flushdns
```
### IDEው አልተገኘም
ራስ-ሰር ማግኘቱ የተለመዱ የመጫኛ ዱካዎችን ይጠቀማል። IDEው ተጭኖ እያለ ማግኘቱ ካልተሳካ፦
- የIDEው binary መደበኛ ባልሆነ ቦታ ውስጥ መኖሩን ያረጋግጡ
- Setup Wizard አሁንም ይሠራል — የማግኘት አለመሳካት ማለት badgeው የመጫኛ ዱካውን አያሳይም ማለት ብቻ ነው
### የhandler ስህተቶች (የupstream ሰርስሮ ማምጣት አይሳካም)
AgentBridge ጥያቄዎቹን ቢያቋርጥም ሁሉም ጥያቄዎች ካልተሳኩ፦
1. ቢያንስ አንድ provider በ`/dashboard/providers` ላይ መገናኘቱን ያረጋግጡ
2. የOmniRoute አገልጋይ ምዝግቦችን ያረጋግጡ፦ `APP_LOG_LEVEL=debug` በ`.env` ውስጥ
3. `OMNIROUTE_BASE_URL` ወደ ትክክለኛው የrouter መጨረሻ ነጥብ ማመልከቱን ያረጋግጡ (ነባሪ፦ `http://127.0.0.1:20128`)
---
## §7 የAPI ማጣቀሻ
ሁሉም መስመሮች `LOCAL_ONLY` (ለloopback ብቻ፣ ከማረጋገጫ በፊት የሚያስገድድ) እና `SPAWN_CAPABLE` ናቸው። `src/server/authz/routeGuard.ts`ን ይመልከቱ።
መሠረታዊ ዱካ፦ `/api/tools/agent-bridge/`
| ዘዴ | መንገድ | መግለጫ |
| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| GET | `/api/tools/agent-bridge/state` | የአገልጋዩ አጠቃላይ ሁኔታ + የእያንዳንዱ agent ማወቂያ/ሁኔታ |
| GET | `/api/tools/agent-bridge/agents` | የተመዘገቡ agents ዝርዝር (id፣ ስም፣ hosts፣ አዋጭነት፣ ሁኔታ) |
| GET | `/api/tools/agent-bridge/agents/{id}` | የአንድ agent ሁኔታ (የዒላማ ውቅር + ማወቂያ + የተከማቸ ሁኔታ) |
| PATCH | `/api/tools/agent-bridge/agents/{id}` | ለagent `setup_completed`ን ያዘምኑ |
| GET | `/api/tools/agent-bridge/agents/{id}/detect` | ለagent የማወቂያ ምርመራ ያከናውኑ (`installed`፣ `version?`፣ `path?`) |
| POST | `/api/tools/agent-bridge/agents/{id}/dns` | ለagent DNSን ያንቁ/ያሰናክሉ (`{enabled: boolean}`) |
| GET | `/api/tools/agent-bridge/agents/{id}/mappings` | የagent ሞዴል ማዛመጃዎች |
| PUT | `/api/tools/agent-bridge/agents/{id}/mappings` | የሞዴል ማዛመጃዎችን ይተኩ |
| POST | `/api/tools/agent-bridge/server` | አገልጋዩን ያስጀምሩ/ያቁሙ/እንደገና ያስጀምሩ (`action: "start"\|"stop"\|"restart"\|"trust-cert"\|"regenerate-cert"`) |
| GET | `/api/tools/agent-bridge/cert` | የምስክር ወረቀት ሁኔታ (`exists`፣ `trusted`፣ `path`) |
| POST | `/api/tools/agent-bridge/cert` | የMITM root CAን እምነት ይስጡ (ይጫኑ) |
| DELETE | `/api/tools/agent-bridge/cert` | ከMITM root CA እምነት ያንሱ (ያስወግዱ) — ተደጋግሞ ሲፈጸም ውጤቱ አይለወጥም (§3.6ን ይመልከቱ) |
| POST | `/api/tools/agent-bridge/cert/regenerate` | በራስ የተፈረመውን MITM ምስክር ወረቀት እንደገና ያመንጩ |
| GET | `/api/tools/agent-bridge/cert/download` | የPEM ምስክር ወረቀቱን ለማውረድ በዥረት ይላኩ |
| GET | `/api/tools/agent-bridge/bypass` | የማለፊያ ስርዓተ-ጥለቶችን ይዘርዝሩ (`default` + `user`) |
| POST | `/api/tools/agent-bridge/bypass` | በተጠቃሚ የተገለጹ የማለፊያ ስርዓተ-ጥለቶችን ሙሉ በሙሉ ይተኩ |
| DELETE | `/api/tools/agent-bridge/bypass?pattern=...` | በተጠቃሚ የተገለጸ አንድ የማለፊያ ስርዓተ-ጥለት ያስወግዱ |
| GET | `/api/tools/agent-bridge/diagnose` | የመያዣ ፓይፕላይን ራስ-ምርመራ (§3.6ን ይመልከቱ) |
| POST | `/api/tools/agent-bridge/repair` | ባለቤት አልባ የMITM ስርዓት ሁኔታን ይቀልብሱ (§3.6ን ይመልከቱ) |
| GET | `/api/tools/agent-bridge/config` | ተንቀሳቃሽ የውቅር JSONን ወደ ውጭ ይላኩ (§3.7ን ይመልከቱ) |
| POST | `/api/tools/agent-bridge/config` | ተንቀሳቃሽ የውቅር JSONን ወደ ውስጥ ያስገቡ (§3.7ን ይመልከቱ) |
| GET | `/api/tools/agent-bridge/upstream-ca` | የተዋቀረውን የupstream CA መንገድ ያግኙ |
| POST | `/api/tools/agent-bridge/upstream-ca` | የupstream CA መንገድን ያረጋግጡ + በቋሚነት ያስቀምጡ |
| POST | `/api/tools/agent-bridge/upstream-ca/test` | የupstream CA መንገድን ብቻ ያረጋግጡ (dry-run) — በቋሚነት አያስቀምጥም |
| GET / POST / DELETE | `/api/tools/agent-bridge/tproxy` | TPROXY ግልጽ-ዲክሪፕት የመያዣ ሁነታ — `docs/security/MITM-TPROXY-DECRYPT.md`ን ይመልከቱ (git፤ ወደ `/docs` አልተካተተም) |
ሙሉ የOpenAPI schemas፦ `docs/openapi.yaml` → መለያ `AgentBridge`።
---
## §8 የወደፊት ዕቅድ
### የTrae ምርመራ
Trae በአንጻራዊነት አዲስ የAI ኮድ ማጎልበቻ ረዳት ነው። ማስተናገጃ ከመተግበርዎ በፊት፦
1. በVS Code / JetBrains የመተግበሪያ ገበያዎች ውስጥ ወይም ራሱን የቻለ መተግበሪያ ከሆነ ባይነሪውን/ቅጥያውን ይለዩ
2. የAPI አስተናጋጆችን እና የመግቢያ ነጥቦችን ቅርጽ ለማወቅ ትራፊኩን በmitmproxy ይቅረጹ
3. የማረጋገጫ ዘዴውን ይወስኑ
4. በTOS እና በAPI ተገኝነት ላይ በመመርኮዝ ለመቀጠል/ላለመቀጠል ይገምግሙ
ምርመራው እስኪጠናቀቅ ድረስ፣ በዳሽቦርዱ ውስጥ ያለው የTrae ካርድ የ"በምርመራ ላይ" ባጅ ከ"የአዋጭነት ሪፖርት ያድርጉ" አገናኝ ጋር ያሳያል። `src/mitm/handlers/trae.ts` ላይ ያለው የማስተናገጃ አጽም የተዋቀረ `ገና አልተተገበረም` ስህተት ይጥላል።
### በወረፋ ላይ ያሉ ወኪሎች (MITM ያስፈልጋል — ብጁ base URL ድጋፍ የለም)
የሚከተሉት መሳሪያዎች አሁን ባሉት ስሪቶቻቸው ብጁ base URL አይደግፉም፤ ይህም MITMን ብቸኛው የመጥለፍ መንገድ ያደርገዋል። የአዋጭነት ግምገማ በመጠባበቅ ላይ ነው፦
- **Windsurf** (Codeium/Cognition)
- **Amp** (Sourcegraph)
- **Amazon Q / Kiro CLI** (AWS Bedrock — ከKiro IDE የተለየ)
- **Cowork** (Anthropic desktop)
ማስታወሻ፦ GitHub Copilot CLI ≥v1.0.19 `COPILOT_PROVIDER_BASE_URL`ን ይደግፋል — ለዚያ መሳሪያ MITMን ከመጠቀም ይልቅ ቀጥተኛ ውቅረትን ይጠቀሙ።

284
docs/i18n/am/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md Normal file
View File

@@ -0,0 +1,284 @@
# Agent Protocols Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇦🇿 [az](../../../az/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇩🇰 [da](../../../da/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇩🇪 [de](../../../de/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇬🇷 [el](../../../el/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇪🇸 [es](../../../es/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇪🇪 [et](../../../et/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇱 [he](../../../he/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇩 [id](../../../id/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇹 [it](../../../it/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇰🇭 [km](../../../km/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇲🇲 [my](../../../my/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇳🇴 [no](../../../no/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [or](../../../or/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇱🇰 [si](../../../si/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇮🇳 [te](../../../te/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇹🇭 [th](../../../th/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)
---
> **ምንጭ፦** `src/lib/{a2a,acp,cloudAgent}/`, `src/app/api/{a2a,acp,cloud}/`, `src/app/api/v1/agents/`
> **መጨረሻ የተዘመነው፦** 2026-06-28 — v3.8.40
OmniRoute ከወኪሎች ጋር የተያያዙ ሦስት የተለያዩ በይነገጾችን ያቀርባል። በመጀመሪያ እይታ ተመሳሳይ ቢመስሉም፣ የተለያዩ ችግሮችን ይፈታሉ። ትክክለኛውን ለመምረጥ ይህን ገጽ ይጠቀሙ።
## ባጭሩ
| በይነገጽ | ተስማሚ የሆነው ለ | ማጓጓዣ | መስፈርት |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------------- |
| **A2A — ከወኪል ወደ ወኪል** | የA2A ፕሮቶኮልን ከሚጠቀሙ አቻ ወኪሎች ጋር የወኪል-ተሻጋሪ ትብብር | JSON-RPC 2.0 በHTTP ላይ | A2A v0.3 (ክፍት መስፈርት) |
| **ACP — የCLI ወኪሎች መዝገብ** | በተጠቃሚው ማሽን ላይ የተጫኑ የCLI ኮድ ማበልጸጊያ ወኪሎችን መለየት / መመዝገብ / ማስጀመር (Cursor, Cline, Codex CLI, Claude Code, Aider, ወዘተ) | HTTP REST | ለOmniRoute የተለየ |
| **የደመና ወኪሎች** | ረጅም ጊዜ የሚወስዱ የኮድ ማበልጸጊያ ተግባራትን ወደ ውጫዊ የደመና አገልግሎቶች መላክ (Codex Cloud, Devin, Jules, Cursor Cloud) | HTTP REST + በDB የሚደገፉ ተግባራት | ለOmniRoute የተለየ |
ሦስቱም እርስ በርስ ገለልተኛ ናቸው — የፈለጉትን ንዑስ ስብስብ ይምረጡ።
## የውሳኔ ዛፍ
```
ከዚህ ማሽን ውጭ ሥራ እንዲሠራ የደመና አገልግሎት ያስፈልግዎታል (Codex Cloud / Cursor Cloud / Devin / Jules)?
├─ አዎ → የደመና ወኪሎች (POST /api/v1/agents/tasks)
└─ አይ → ይቀጥሉ
│
A2Aን የሚጠቀምና መተባበር የሚፈልግ አቻ ወኪል አለዎት?
├─ አዎ → A2A (POST /a2a)
└─ አይ → ይቀጥሉ
│
በአካባቢው የተጫኑ የCLI ኮድ ማበልጸጊያ ወኪሎችን መዘርዘር / ማዋቀር ያስፈልግዎታል?
├─ አዎ → ACP (GET /api/acp/agents)
└─ አይ → መደበኛውን /v1/chat/completions ይጠቀሙ
```
## 1. A2A — ከወኪል ወደ ወኪል
**መስፈርት፦** [A2A v0.3](https://a2a-protocol.org)
**የOmniRoute መዳረሻ፦** `POST /a2a` (JSON-RPC 2.0)
**የወኪል ካርድ፦** `GET /.well-known/agent.json`
### መቼ መጠቀም እንዳለብዎት
- OmniRoute ከአቻዎቹ አንዱ የሆነበትን ባለብዙ-ወኪል ሥርዓት ሲገነቡ
- የOmniRouteን የማስተላለፊያ ብልህነት (ብልህ ማስተላለፊያ፣ የኮታ አስተዳደር፣ ወዘተ) Google ADKን በመሳሰሉ ማዕቀፎች ወይም አጠቃላይ የወኪል መረቦች ውስጥ ላሉ ወኪሎች ሲያቀርቡ
- OmniRouteን በመደበኛ የፍለጋ + የጥሪ በይነገጽ ኋላ ሲያቀናጁ
### ስልቶች
- `message/send` — መልዕክት ያስገቡ፣ የተመሳሰለ ምላሽ ይቀበሉ
- `message/stream` — ያስገቡ + በSSE የሚለቀቁ የሂደት ክስተቶችን ይቀበሉ
- `tasks/get` — ተግባሩን በID ያንብቡ
- `tasks/cancel` — በመሠራት ላይ ያለን ተግባር ይሰርዙ
### አብረው የተካተቱ ክህሎቶች (6)
- `smart-routing` — ጥያቄን በምርጥ ጥምረት በኩል ያስተላልፉ
- `quota-management` — የእያንዳንዱን አቅራቢ የኮታ ሁኔታ ሪፖርት ያድርጉ
- `provider-discovery` — የተጫኑ አቅራቢዎችን ከችሎታዎቻቸው ጋር ይዘርዝሩ
- `cost-analysis` — የጥያቄ/ውይይት ወጪን ይገምቱ
- `health-report` — የእያንዳንዱን አቅራቢ breaker/cooldown/lockout ሁኔታ ያጠቃልሉ
- `list-capabilities` — የወኪሉን የሚገኙ ክህሎቶችና ሜታዳታ ይዘርዝሩ
### ዝርዝር ማብራሪያ
ስለ ማጓጓዣ ዝርዝሮች፣ የወኪል ካርድ መዋቅር፣ የተግባር TTL ውቅር እና አዳዲስ ክህሎቶችን ለመጨመር የሚያገለግለው አብነት [A2A-SERVER.md](./A2A-SERVER.md)ን ይመልከቱ።
## 2. ACP — የCLI ወኪሎች መዝገብ
**የOmniRoute መዳረሻ:** `GET /api/acp/agents`
**ምንጭ:** `src/lib/acp/{index,manager,registry}.ts`
### ምንድን ነው
ACP የOmniRoute **የአካባቢ CLI ወኪሎች ዝርዝር** ነው። በአስተናጋጁ ላይ የትኞቹ የኮድ ማዘጋጃ CLI-ዎች እንደተጫኑ (Cursor፣ Cline፣ Claude Code፣ Codex CLI፣ Continue፣ ወዘተ) ይለያል፣ ስሪቶቻቸውን ያጣራል፣ እና ተጠቃሚው እያንዳንዱን CLI ወደ OmniRoute እንዲያመለክት ማዋቀር እንዲችል በዳሽቦርዱ ላይ ያሳያቸዋል።
ይህ ውጫዊ ፕሮቶኮል አይደለም — የ"CLI Tools" የተጠቃሚ በይነገጽን እና የCLI አሻራ ክትትልን የሚያንቀሳቅስ ውስጣዊ መዝገብ ነው ([CLI-TOOLS.md](../reference/CLI-TOOLS.md)ን ይመልከቱ)።
### ምን ያደርጋል
- የተጫኑ የCLI ሁለትዮሽ ፋይሎችን ለማግኘት አስተናጋጁን ይመረምራል (እንደ OS-ው `which` / `where` ይጠቀማል)
- የእያንዳንዱን CLI ስሪት ያነባል (`<bin> --version`ን ይጠራል)
- እንደ አማራጭ በተጠቃሚ የተወሰኑ ብጁ ወኪሎችን ይቀበላል (የሁለትዮሽ ፋይል ዱካ + የስሪት ምርመራ + የማስጀመሪያ ነጋሪ እሴቶች)
- ብጁ ወኪሎችን በቅንብሮች ውስጥ ያስቀምጣል
- የተዋሃደውን ዝርዝር ወደ ዳሽቦርዱ ይመልሳል
### REST API
| መዳረሻ | ዘዴ | መግለጫ | ማረጋገጫ |
| ----------------- | ---- | -------------------------------------------------- | ------- |
| `/api/acp/agents` | GET | የተገኙ + ብጁ ወኪሎችን ይዘረዝራል (የተጫኑ/ጠቅላላ ብዛቶች) | API ቁልፍ |
| `/api/acp/agents` | POST | ብጁ ወኪል ያክላል/ያዘምናል/ያስወግዳል (የድርጊት መለያ በጥያቄው ይዘት ውስጥ) | API ቁልፍ |
የPOST ጥያቄ ይዘት ቅርጽ (`customAgentBodySchema` በ`src/app/api/acp/agents/route.ts` ውስጥ):
```json
{
"action": "add|update|remove",
"id": "cursor",
"name": "Cursor",
"binary": "/usr/local/bin/cursor",
"versionCommand": "--version",
"providerAlias": "cursor",
"spawnArgs": ["--api-base", "http://localhost:20128"],
"protocol": "stdio"
}
```
### የአጠቃቀም ሁኔታዎች
- የዳሽቦርዱ "CLI Tools" ገጽ የተጫኑትን ይዘረዝራል እና እያንዳንዱን ወደ OmniRoute እንዲያመለክት ለማዋቀር ያግዝዎታል
- ብጁ ወኪሎች የላቁ ተጠቃሚዎች OmniRoute በነባሪነት የማያውቃቸውን ውስጣዊ/የባለቤትነት CLI-ዎች እንዲመዘግቡ ያስችላሉ
- የማወቂያ ውጤቱ የ`cli-tools` አሻራ ማትሪክስን ያቀርባል
### ACPን መጠቀም የሌለብዎት ጊዜ
- ACP ተግባራትን _አያስኬድም_። CLI-ዎችን የሚለየው እና የሚያዋቅረው ብቻ ነው። CLIን በተግባር ለመጥራት፣ OmniRoute በሚያቀርባቸው የአካባቢ ተለዋዋጮች (`OPENAI_BASE_URL`፣ `OPENAI_API_KEY`፣ ወዘተ) ራስዎ ያስጀምሩት።
## 3. የደመና ወኪሎች
**የOmniRoute መዳረሻዎች:** `/api/v1/agents/tasks/*` (የሕይወት ዑደት) + `/api/cloud/*` (መሠረታዊ ግንኙነቶች)
**ምንጭ:** `src/lib/cloudAgent/`
### ምንድን ነው
በሦስተኛ ወገን የደመና ኮድ ማዘጋጃ ወኪሎች ላይ ወጥ የሆነ በይነገጽ ነው። መመሪያ + የማከማቻ ዩአርኤል ያስገባሉ፣ OmniRoute ወደ ትክክለኛው የደመና ወኪል ይልካል፣ ሁኔታውን በየጊዜው ይፈትሻል፣ ውጤቶችንም ይመልሳል።
### የሚደገፉ ወኪሎች (4፣ ሁሉም በ`src/lib/cloudAgent/agents/` ውስጥ የተረጋገጡ)
- `codex-cloud` — OpenAI Codex Cloud
- `devin` — Cognition Devin
- `jules` — Google Jules
### የሕይወት ዑደት
```
POST /api/v1/agents/tasks
→ BaseAgent.createTask() ለእያንዳንዱ የወኪል ክፍል
→ ውጫዊ አገልግሎቱ ሥራውን ይጀምራል
→ የተግባር ረድፍ በDB ውስጥ ይፈጠራል (cloud_agent_tasks)
↓
GET /api/v1/agents/tasks/[id]
→ ከአቅራቢው የዘገየ የሁኔታ ማመሳሰል
→ የአሁኑን ሁኔታ + ዕቅድ + የእንቅስቃሴ ምዝግብ ይመልሳል
↓
POST /api/v1/agents/tasks/[id] (action: "approve" | "message" | "cancel")
→ ወደ አቅራቢው ያስተላልፋል (ወይም በአካባቢው እንደተሰረዘ ምልክት ያደርጋል)
↓
DELETE /api/v1/agents/tasks/[id]
→ በአካባቢው ይሰርዛል
```
### ማረጋገጫ
⚠️ **ሁሉም የ`/api/v1/agents/tasks/*` መዳረሻዎች የአስተዳደር ማረጋገጫ ይፈልጋሉ** (commit `588a0333`)። Bearer ብቻ የሚጠቀሙ ጠሪዎች ከv3.8.0 ጀምሮ 401 ይቀበላሉ።
### ጥልቅ ማብራሪያ
ስለ `CloudAgentBase` ውል፣ የእያንዳንዱ ወኪል ዝርዝሮች፣ የመርሃግብር ዝርዝሮች እና የማረጋገጫ መረጃ ግንኙነት መዳረሻዎች [CLOUD_AGENT.md](./CLOUD_AGENT.md)ን ይመልከቱ።
## ንጽጽር፦ A2A ከ Cloud Agents ጋር
ሁለቱም "ረጅም ጊዜ የሚወስዱ ተግባራት" አሏቸው፣ ነገር ግን በተለያዩ ንብርብሮች ላይ ነው፦
| ገጽታ | A2A | Cloud Agents |
| ------------ | ----------------------------------------------------------------------------- | ----------------------------------------- |
| መስፈርት | Open A2A v0.3 | ለOmniRoute የተለየ |
| ስሌቱ የሚከናወንበት | በOmniRoute ውስጥ (የተዋቀሩ ጥምረቶችን ይጠቀማል) | ውጫዊ (Codex / Devin / Jules አገልጋዮች) |
| የተግባር ቆይታ | ነባሪ TTL 5 ደቂቃ (በ`TaskManager` ውስጥ ሊዋቀር ይችላል) | ከደቂቃዎች እስከ ሰዓታት |
| Repoን የሚያውቅ | አይደለም (ጥያቄዎችን ብቻ ያስተላልፋል) | አዎ (የrepo URL + branch) |
| የአጠቃቀም ሁኔታ | በወኪሎች መካከል ትብብር፣ ብልህ ማዘዋወር እንደ አገልግሎት | "ባህሪ Xን በrepo Y ውስጥ ተግብር" የሚለውን ውክልና መስጠት |
| ማረጋገጫ | አማራጭ `OMNIROUTE_API_KEY` ለ`/a2a`፤ ለ`/api/a2a/*` REST አጋዥ መሣሪያዎች የአስተዳደር ማረጋገጫ | ሁልጊዜ የአስተዳደር ማረጋገጫ |
## የውህደት ምሳሌዎች
### የOmniRouteን A2A ችሎታዎች ያግኙ
```bash
curl http://localhost:20128/.well-known/agent.json
```
ሁሉንም 6 ክህሎቶች፣ ማጓጓዣዎች እና ስሪት የያዘውን Agent Card ይመልሳል።
### OmniRouteን እንደ A2A ወኪል ይጥሩ
```bash
curl -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"messages": [{"role": "user", "content": "Route this prompt"}],
"skill": "smart-routing"
},
"id": 1
}'
```
### በACP በኩል የተጫኑ CLI ወኪሎችን ይዘርዝሩ
```bash
curl http://localhost:20128/api/acp/agents \
-H "Authorization: Bearer <api-key>"
```
### ብጁ CLI ወኪል ያክሉ
```bash
curl -X POST http://localhost:20128/api/acp/agents \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{
"action": "add",
"id": "my-custom-cli",
"name": "My Custom CLI",
"binary": "/opt/mycli/bin/mycli",
"versionCommand": "--version",
"providerAlias": "openai"
}'
```
### የCloud Agent ተግባር ያስገቡ
```bash
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{
"providerId": "devin",
"prompt": "Implement feature X in repo Y",
"source": {
"repoName": "user/repo",
"repoUrl": "https://github.com/user/repo",
"branch": "main"
}
}'
```
### የCloud ተግባርን ሁኔታ በየጊዜው ይፈትሹ
```bash
curl http://localhost:20128/api/v1/agents/tasks/<task-id> \
-H "Cookie: auth_token=..."
```
## የትኛውን መቼ መጠቀም እንዳለብዎ
- **Chatbot / copilot የፊት ገጽ** → `/v1/chat/completions` (ከOpenAI ጋር ተኳሃኝ — የወኪል ፕሮቶኮል አይደለም)
- **የበርካታ ወኪሎች ትብብር** → A2A
- **በዳሽቦርዱ ውስጥ የአካባቢ CLIዎችን መዘርዘር** → ACP
- **ረጅም ጊዜ የሚወስዱ የኮድ ሥራዎችን ለCloud አገልግሎቶች በውክልና መስጠት** → Cloud Agents
## ውስጣዊ አርክቴክቸር
```
┌─────────────────────┐
│ OmniRoute ኮር │
└─────────────────────┘
↑ ↑ ↑
┌─────────┘ │ └─────────┐
│ │ │
┌───────┐ ┌─────────┐ ┌────────────┐
│ A2A │ │ ACP │ │ የደመና │
│ (/a2a)│ │ (/acp) │ │ ወኪሎች │
└───────┘ └─────────┘ │ (/v1/agents│
│ │ │ /tasks) │
↓ ↓ └────────────┘
A2A v0.3ን በአስተናጋጁ ላይ │
የሚጠቀሙ ውጫዊ ያሉ አካባቢያዊ CLI ↓
አቻ ወኪሎች ሁለትዮሽ ፋይሎች Codex Cloud, Cursor,
Devin, Jules
```
## በተጨማሪ ይመልከቱ
- [A2A-SERVER.md](./A2A-SERVER.md) — ስለ A2A ዝርዝር ማብራሪያ
- [CLOUD_AGENT.md](./CLOUD_AGENT.md) — ስለ የደመና ወኪሎች ዝርዝር ማብራሪያ
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — የውጫዊ CLI ውህደቶች (ACPን ይጠቀማል)
- [SKILLS.md](./SKILLS.md) — የክህሎቶች ማዕቀፍ (ከA2A ክህሎቶች የተለየ — የአካባቢያዊ ማስፈጸሚያ ማግለያ)
- [API_REFERENCE.md](../reference/API_REFERENCE.md#agents-protocol) — የመዳረሻ ነጥብ ማጣቀሻ
- ምንጭ፦ `src/lib/{a2a,acp,cloudAgent}/`

387
docs/i18n/am/docs/frameworks/CLOUD_AGENT.md Normal file
View File

@@ -0,0 +1,387 @@
# Cloud Agents (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/CLOUD_AGENT.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/CLOUD_AGENT.md) · 🇦🇿 [az](../../../az/docs/frameworks/CLOUD_AGENT.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/CLOUD_AGENT.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/CLOUD_AGENT.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/CLOUD_AGENT.md) · 🇩🇰 [da](../../../da/docs/frameworks/CLOUD_AGENT.md) · 🇩🇪 [de](../../../de/docs/frameworks/CLOUD_AGENT.md) · 🇬🇷 [el](../../../el/docs/frameworks/CLOUD_AGENT.md) · 🇪🇸 [es](../../../es/docs/frameworks/CLOUD_AGENT.md) · 🇪🇪 [et](../../../et/docs/frameworks/CLOUD_AGENT.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/CLOUD_AGENT.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/CLOUD_AGENT.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/CLOUD_AGENT.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/CLOUD_AGENT.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/CLOUD_AGENT.md) · 🇮🇱 [he](../../../he/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/CLOUD_AGENT.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/CLOUD_AGENT.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/CLOUD_AGENT.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/CLOUD_AGENT.md) · 🇮🇩 [id](../../../id/docs/frameworks/CLOUD_AGENT.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/CLOUD_AGENT.md) · 🇮🇹 [it](../../../it/docs/frameworks/CLOUD_AGENT.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/CLOUD_AGENT.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/CLOUD_AGENT.md) · 🇰🇭 [km](../../../km/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/CLOUD_AGENT.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/CLOUD_AGENT.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/CLOUD_AGENT.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/CLOUD_AGENT.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/CLOUD_AGENT.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/CLOUD_AGENT.md) · 🇲🇲 [my](../../../my/docs/frameworks/CLOUD_AGENT.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/CLOUD_AGENT.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/CLOUD_AGENT.md) · 🇳🇴 [no](../../../no/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [or](../../../or/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/CLOUD_AGENT.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/CLOUD_AGENT.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/CLOUD_AGENT.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/CLOUD_AGENT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/CLOUD_AGENT.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/CLOUD_AGENT.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/CLOUD_AGENT.md) · 🇱🇰 [si](../../../si/docs/frameworks/CLOUD_AGENT.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/CLOUD_AGENT.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/CLOUD_AGENT.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/CLOUD_AGENT.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/CLOUD_AGENT.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/CLOUD_AGENT.md) · 🇮🇳 [te](../../../te/docs/frameworks/CLOUD_AGENT.md) · 🇹🇭 [th](../../../th/docs/frameworks/CLOUD_AGENT.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/CLOUD_AGENT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/CLOUD_AGENT.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/CLOUD_AGENT.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/CLOUD_AGENT.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/CLOUD_AGENT.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/CLOUD_AGENT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/CLOUD_AGENT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/CLOUD_AGENT.md)
---
> **የእውነት ምንጭ፦** `src/lib/cloudAgent/` እና `src/app/api/v1/agents/tasks/`
> **ለመጨረሻ ጊዜ የዘመነው፦** 2026-06-28 — v3.8.40 (የfrontmatter ማደስ፤ cursor-cloudን ጨምሮ 4 ወኪሎች)
OmniRoute በሶስተኛ ወገን ደመና የሚስተናገዱ የኮድ ሥራ ወኪሎችን (Codex Cloud፣ Cursor፣
Devin፣ Jules) እንደ ረጅም ጊዜ የሚከናወኑ ተግባራት ያቀናጃል። ደንበኞች ከአቅራቢ-ተኮር
APIዎች ጋር ሳይገናኙ ጥያቄ + የማከማቻ URL እንዲያስገቡ እና ውጤቶችን እንዲቀበሉ፣
እያንዳንዱ ወኪል በወጥ በይነገጽ ይጠቀለላል።
የCloud Agent ተግባር መደበኛ የውይይት ማጠናቀቂያ **አይደለም**። ከደቂቃዎች እስከ
ሰዓታት ሊወስድ የሚችል፣ Pull Requestን እንደ ውጤት ሊያመነጭ የሚችል እና
የክትትል መልዕክቶችን እንዲሁም (በአንዳንድ አቅራቢዎች) የዕቅድ ማጽደቂያ መግቢያዎችን
የሚደግፍ ዘላቂ፣ ባለብዙ-ደረጃ የሥራ አሃድ ነው።
![የCloud Agent ተግባር የሕይወት ዑደት](../diagrams/exported/cloud-agent-flow.svg)
> ምንጭ፦ [diagrams/cloud-agent-flow.mmd](../diagrams/cloud-agent-flow.mmd)
## የሚደገፉ ወኪሎች
| የአቅራቢ ID | ክፍል | ምንጭ | የላይኛው ስርዓት መሠረታዊ URL | የዕቅድ ማጽደቂያ |
| -------------- | ------------------ | ------------------------------------- | --------------------------------------- | ---------- |
| `jules` | `JulesAgent` | `src/lib/cloudAgent/agents/jules.ts` | `https://jules.googleapis.com/v1alpha` | አዎ |
| `devin` | `DevinAgent` | `src/lib/cloudAgent/agents/devin.ts` | `https://api.devin.ai/v1` | አዎ |
| `codex-cloud` | `CodexCloudAgent` | `src/lib/cloudAgent/agents/codex.ts` | `https://api.openai.com/v1/codex/cloud` | አይ (ራስ-ሰር) |
| `cursor-cloud` | `CursorCloudAgent` | `src/lib/cloudAgent/agents/cursor.ts` | `https://api.cursor.com/v0` | አይ (ራስ-ሰር) |
መዝገብ፦ `src/lib/cloudAgent/registry.ts` — `getAgent(providerId)`፣
`getAvailableAgents()` እና `isCloudAgentProvider(providerId)`ን ወደ ውጭ ይልካል። መዝገቡ
ሞጁሉ ሲጫን የሚሞላ ቀላል የውስጠ-ማህደረ ትውስታ `Record<string, CloudAgentBase>` ነው።
## አወቃቀር
```
ደንበኛ (ዳሽቦርድ / CLI / API)
→ POST /api/v1/agents/tasks (የአስተዳደር ማረጋገጫ ያስፈልጋል)
→ የCreateCloudAgentTaskSchema ማረጋገጫ (Zod)
→ registry.getAgent(providerId)
→ getCloudAgentCredentials(providerId)
└─ ከgetProviderConnections({ provider, isActive: true }) ይወስዳል
(apiKey በመጀመሪያ፣ ካልተገኘ accessTokenን ይጠቀማል)
→ agent.createTask({ prompt, source, options }, credentials)
└─ HTTP POST ወደ የላይኛው አቅራቢ API
└─ CloudAgentTaskን ከውስጣዊ id + externalId ጋር ይመልሳል
→ insertCloudAgentTask(...) ወደ cloud_agent_tasks (SQLite)
ሁኔታን በየጊዜው መፈተሽ (በማንበብ ጊዜ ሰነፍ ማመሳሰል):
GET /api/v1/agents/tasks/[id]
→ getCloudAgentTaskById(id)
→ agent.getStatus(externalId, credentials) // ሁኔታውን + እንቅስቃሴዎችን ያድሳል
→ updateCloudAgentTask(...) በአዲሱ ሁኔታ፣ ውጤት፣ completed_at
→ ተከታታይ ቅርጽ የተሰጠውን ተግባር ይመልሳል
መስተጋብሮች:
POST /api/v1/agents/tasks/[id] ይዘት: { action: "approve" | "message" | "cancel" }
→ agent.approvePlan(externalId, credentials) ለ"approve"
→ agent.sendMessage(externalId, message, credentials) ለ"message"
→ ሁኔታው ወደ "cancelled" ይቀየራል ለ"cancel" (አካባቢያዊ-ብቻ)
```
ማመሳሰሉ **ሰነፍ** ነው፦ በእያንዳንዱ `GET /tasks/[id]` ጊዜ ሁኔታው ከላይኛው ስርዓት
ይታደሳል። ከበስተጀርባ ሁኔታን በየጊዜው የሚፈትሽ ሂደት የለም። የዘመነ ሁኔታ
የሚፈልጉ ዳሽቦርዶች የGET መጨረሻ ነጥቡን በተገቢ የጊዜ ልዩነት መጠየቅ አለባቸው።
## `CloudAgentBase` በይነገጽ
ምንጭ፦ `src/lib/cloudAgent/baseAgent.ts`
```typescript
export interface AgentCredentials {
apiKey: string;
baseUrl?: string;
}
export interface CreateTaskParams {
prompt: string;
source: CloudAgentSource;
options: {
autoCreatePr?: boolean;
planApprovalRequired?: boolean;
environment?: Record<string, string>;
};
}
export interface GetStatusResult {
status: CloudAgentStatus;
externalId?: string;
result?: CloudAgentResult;
activities: CloudAgentActivity[];
error?: string;
}
export abstract class CloudAgentBase {
abstract readonly providerId: string;
abstract readonly baseUrl: string;
abstract createTask(p: CreateTaskParams, c: AgentCredentials): Promise<CloudAgentTask>;
abstract getStatus(externalId: string, c: AgentCredentials): Promise<GetStatusResult>;
abstract approvePlan(externalId: string, c: AgentCredentials): Promise<void>;
abstract sendMessage(
externalId: string,
message: string,
c: AgentCredentials
): Promise<CloudAgentActivity>;
abstract listSources(
c: AgentCredentials
): Promise<{ name: string; url: string; branch?: string }[]>;
protected mapStatus(raw: string): CloudAgentStatus; // በግምት የሚሰራ የውጭ ስርዓት ሕብረቁምፊ → enum
protected generateTaskId(): string; // `task_<ts>_<rand>`
protected generateActivityId(): string; // `act_<ts>_<rand>`
}
```
`CodexCloudAgent.approvePlan` ሆን ብሎ ስህተት ይጥላል — Codex Cloud ዕቅድን በራስ-ሰር ያዘጋጃል እና
የማጽደቂያ መግቢያ የለውም። `CodexCloudAgent.listSources` `[]` ይመልሳል።
`CursorCloudAgent` የCursor Background / Cloud Agentsን በይፋዊው REST
API (`api.cursor.com/v0`) እና **የተጠቃሚ ወይም የአገልግሎት-መለያ API ቁልፍ** በመጠቀም ያንቀሳቅሳል — ይህም
የCursor IDE OAuth ክፍለ-ጊዜን እንደገና ከመጠቀም ይልቅ ይበልጥ ደህንነቱ የተጠበቀ፣ የመጀመሪያ ወገን አማራጭ ነው (አቅራቢ `cursor`፣
የእገዳ አደጋ ማስጠንቀቂያ ያለው)። እሱ ቀላል REST አስማሚ ነው (የ`@cursor/sdk` ቤተኛ
ጥገኝነት የለውም)። `approvePlan` ስህተት ይጥላል (የCursor ወኪሎች በራስ-ገዝ ሁኔታ ይሰራሉ)፤ `listSources` ቁልፉ
ሊደርስባቸው የሚችላቸውን ማከማቻዎች ይዘረዝራል። Cursor በአቢይ ሆሄያት የተጻፉ የሁኔታ enum እሴቶችን
(`CREATING`/`RUNNING`/`FINISHED`/`ERROR`) ይመልሳል፤ እነዚህም ወደ የጋራው
`CloudAgentStatus` በግልጽ ሁኔታ ይመደባሉ። `baseUrl` ለእያንዳንዱ ማረጋገጫ መረጃ ሊተካ ስለሚችል፣ የAPI ስሪት/ዱካ
የኮድ ለውጥ ሳያስፈልግ ሊስተካከል ይችላል።
## የጎራ ዓይነቶች
ምንጭ፦ `src/lib/cloudAgent/types.ts`
```typescript
export const CLOUD_AGENT_STATUS = {
QUEUED: "queued",
RUNNING: "running",
AWAITING_APPROVAL: "awaiting_approval",
COMPLETED: "completed",
FAILED: "failed",
CANCELLED: "cancelled",
} as const;
export interface CloudAgentSource {
repoName: string;
repoUrl: string; // ትክክለኛ URL መሆን አለበት
branch?: string;
}
export interface CloudAgentResult {
prUrl?: string;
prNumber?: number;
commitMessage?: string;
diffUrl?: string;
summary?: string;
duration?: number; // በሰከንድ፣ አዎንታዊ int
cost?: number; // አዎንታዊ float
}
export interface CloudAgentActivity {
id: string;
type: "plan" | "command" | "code_change" | "message" | "error" | "completion";
content: string;
timestamp: string; // ISO 8601
metadata?: Record<string, unknown>;
}
export interface CloudAgentTask {
id: string; // ውስጣዊ `task_...` id
providerId: "jules" | "devin" | "codex-cloud" | "cursor-cloud";
externalId?: string; // የውጭ አቅራቢው id
status: CloudAgentStatus;
prompt: string; // 1..10000 ቁምፊዎች
source: CloudAgentSource;
options: {
autoCreatePr?: boolean;
planApprovalRequired?: boolean;
environment?: Record<string, string>;
};
result?: CloudAgentResult;
activities: CloudAgentActivity[];
error?: string;
createdAt: string;
updatedAt: string;
completedAt?: string;
}
```
የማረጋገጫ መርሐግብሮች (`CreateCloudAgentTaskSchema`፣ `UpdateCloudAgentTaskSchema`) ከዓይነቶቹ ጋር
አብረው ወደ ውጭ ይላካሉ፣ እንዲሁም በመስመር ተቆጣጣሪዎቹ ጥቅም ላይ ይውላሉ።
## የውሂብ ጎታ
ምንጭ፦ `src/lib/cloudAgent/db.ts` — ሰንጠረዡ በ`createCloudAgentTaskTable()` አማካኝነት እስኪያስፈልግ ድረስ አይፈጠርም (`src/lib/cloudAgent/index.ts` ሞጁሉ ሲመጣም ይጠራል)።
```sql
CREATE TABLE IF NOT EXISTS cloud_agent_tasks (
id TEXT PRIMARY KEY,
provider_id TEXT NOT NULL,
external_id TEXT,
status TEXT NOT NULL DEFAULT 'queued',
prompt TEXT NOT NULL,
source TEXT NOT NULL, -- JSON
options TEXT DEFAULT '{}', -- JSON
result TEXT, -- JSON
activities TEXT DEFAULT '[]', -- JSON
error TEXT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
completed_at TEXT
);
CREATE INDEX IF NOT EXISTS idx_cloud_agent_tasks_provider ON cloud_agent_tasks(provider_id);
CREATE INDEX IF NOT EXISTS idx_cloud_agent_tasks_status ON cloud_agent_tasks(status);
CREATE INDEX IF NOT EXISTS idx_cloud_agent_tasks_created ON cloud_agent_tasks(created_at DESC);
```
`updateCloudAgentTask` የSQL ማስገቢያ ጥቃትን ለመከላከል **የአምዶች ፍቃድ ዝርዝር**ን ያስገድዳል፦
`status`፣ `prompt`፣ `source`፣ `options`፣ `result`፣ `activities`፣ `error`፣
`completed_at`። በከፊል ማዘመኛው ውስጥ ያለ ማንኛውም ሌላ ቁልፍ ያለማሳወቂያ ይወገዳል።
## REST API — የተግባር የሕይወት ዑደት
**ማረጋገጫ፦** ሁሉም `/api/v1/agents/tasks*` የመዳረሻ ነጥቦች **የአስተዳደር ማረጋገጫ**ን ይፈልጋሉ
(`requireCloudAgentManagementAuth` ከ`src/lib/api/requireManagementAuth` የመጣውን
`requireManagementAuth` ይጠቀልላል)። ይህ ከcommit `588a0333`
(_"fix(auth): require management auth for agent and cooldown APIs"_) በኋላ ተፈጻሚ ሆኗል።
| ዘዴ | ዱካ | ዓላማ |
| ------- | ----------------------------- | ------------------------------------------------------ |
| OPTIONS | `/api/v1/agents/tasks` | የCORS ቅድመ ጥያቄ |
| GET | `/api/v1/agents/tasks` | ተግባሮችን ይዘርዝሩ (ማጣሪያ፦ `provider`፣ `status`፣ `limit≤500`) |
| POST | `/api/v1/agents/tasks` | ተግባር ይፍጠሩ (ወደ ውጫዊ አገልግሎት ይልካል + ያከማቻል) |
| DELETE | `/api/v1/agents/tasks?id=...` | ተግባርን በመጠይቅ id ይሰርዙ (የውጫዊውን ተግባር **አይሰርዝም**) |
| OPTIONS | `/api/v1/agents/tasks/[id]` | የCORS ቅድመ ጥያቄ |
| GET | `/api/v1/agents/tasks/[id]` | ተግባርን ያንብቡ + ሁኔታውን ከውጫዊ አገልግሎት ሲያስፈልግ ያመሳስሉ |
| POST | `/api/v1/agents/tasks/[id]` | እርምጃ፦ `approve` / `message` / `cancel` |
| DELETE | `/api/v1/agents/tasks/[id]` | ተግባርን በዱካ id ይሰርዙ |
### ተግባር ይፍጠሩ
```bash
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{
"providerId": "devin",
"prompt": "Fix the bug in src/foo.ts where the parser returns null",
"source": {
"repoName": "user/repo",
"repoUrl": "https://github.com/user/repo",
"branch": "main"
},
"options": {
"autoCreatePr": true,
"planApprovalRequired": false
}
}'
```
ምላሽ `201`፦
```json
{
"data": {
"id": "task_1731512345678_abc123def",
"providerId": "devin",
"externalId": "session_xyz",
"status": "queued",
"prompt": "...",
"source": { "repoName": "user/repo", "repoUrl": "...", "branch": "main" },
"options": { "autoCreatePr": true },
"createdAt": "2026-05-13T12:34:56.789Z"
}
}
```
### ዕቅድን ያጽድቁ
```bash
curl -X POST http://localhost:20128/api/v1/agents/tasks/<id> \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{"action":"approve"}'
```
### የክትትል መልዕክት ይላኩ
```bash
curl -X POST http://localhost:20128/api/v1/agents/tasks/<id> \
-d '{"action":"message","message":"Also add a unit test for the parser"}'
```
### ይሰርዙ (የአካባቢ ሁኔታ ብቻ)
```bash
curl -X POST http://localhost:20128/api/v1/agents/tasks/<id> \
-d '{"action":"cancel"}'
```
`cancel` በአካባቢያዊው DB ውስጥ `status`ን ወደ `"cancelled"` ይቀይራል፤ ነገር ግን
የውጫዊውን አቅራቢ አይጠራም — በ`CloudAgentBase` ውስጥ የማቋረጫ RPC የለም። የውጫዊ
ክፍያን ለማቆም ተግባሩን በአቅራቢው የራሱ console ውስጥ ያቋርጡ።
## REST API — የCloud Provider መሠረተ ልማት
በ`src/app/api/cloud/` ስር ያሉት እነዚህ ረዳት endpoints የprovider ግንኙነት metadataን ለማንበብ እና የmodel aliasesን ለመፍታት በርቀት ደንበኞች
(CLI፣ Electron app ወይም sync workers) ይጠቀሙባቸዋል። እነዚህ endpoints የtask endpoints የሚጠቀሙበትን management auth ሳይሆን
**መደበኛ API key** (`validateApiKey` በመጠቀም) ማረጋገጫን ይጠቀማሉ።
| ዘዴ | መንገድ | ዓላማ |
| ---- | ------------------------------- | -------------------------------------------------------------- |
| POST | `/api/cloud/auth` | API keyን ያረጋግጣል፣ የተደበቀ የግንኙነት metadata እና model aliasesን ይመልሳል |
| PUT | `/api/cloud/credentials/update` | `accessToken` / `refreshToken` / `expiresAt`ን ያድሳል |
| POST | `/api/cloud/model/resolve` | model aliasን ወደ `{ provider, model }` ይፈታል |
| GET | `/api/cloud/models/alias` | ሁሉንም model aliases ይዘረዝራል |
| PUT | `/api/cloud/models/alias` | model aliasን ያዘጋጃል (ከነቃም በራስ-ሰር ከCloud ጋር ያመሳስላል) |
`/api/cloud/auth` ጥሬ `apiKey` / `accessToken` / `refreshToken`ን ፈጽሞ አይመልስም።
`hasApiKey`፣ `hasAccessToken`፣ `hasRefreshToken` እና የተደበቀ ቅድመ ዕይታን
(`maskedApiKey`: የመጀመሪያዎቹ 4 + `****` + የመጨረሻዎቹ 4) ይመልሳል።
## የCredentials መፍትሔ
በ`src/lib/cloudAgent/api.ts` ውስጥ ያለው `getCloudAgentCredentials(providerId)`፦
1. `getProviderConnections({ provider: providerId, isActive: true })`ን በመጠቀም ንቁ የprovider ግንኙነቶችን ይጭናል።
2. ለእያንዳንዱ ግንኙነት `apiKey`ን (ከተቆረጡ ትርፍ ክፍተቶች ጋር) ይመርጣል። ከሌለ `accessToken`ን ይጠቀማል።
3. የመጀመሪያውን ባዶ ያልሆነ token በ`{ apiKey: token }` ተጠቅልሎ ይመልሳል።
4. ጥቅም ላይ ሊውል የሚችል token ካልተገኘ `null`ን ይመልሳል — APIው `400`ን ከሚከተለው ጋር ይመልሳል፦
`"No active credentials configured for cloud agent provider: <id>"`።
ይህ ማለት Cloud Agents እንደ መደበኛ LLM providers ተመሳሳዩን Provider Connection table እንደገና ይጠቀማሉ ማለት ነው።
Julesን ለማንቃት `provider: "jules"` ያለው፣ ንቁ የሆነ እና `apiKey`ው የተሞላ ግንኙነት ይፍጠሩ።
## Dashboard
ምንጭ፦ `src/app/(dashboard)/dashboard/cloud-agents/page.tsx`
የሚከተሉትን የሚያደርግ `"use client"` React page፦
- tasksን ይዘረዝራል (በ`GET /api/v1/agents/tasks` በየጊዜው ይጠየቃሉ)።
- ከ`CreateCloudAgentTaskSchema` ጋር በሚዛመድ form አማካኝነት አዳዲስ tasksን ያስገባል።
- የሁኔታ badges (`queued`፣ `running`፣ `awaiting_approval`፣ `completed`፣
`failed`፣ `cancelled`) ያሳያል እና የ`activities[]` timelineን ይቀርጻል።
- `status === "completed"` ሲሆን `result.prUrl` / `commitMessage` / `summary`ን በግልጽ ያሳያል።
## ከA2A ጋር ያለው ውህደት
የ`tasks/send` handlerን ወደ `getAgent(...).createTask(...)` የሚያስተላልፍ A2A skill በመመዝገብ እና የA2A task
ሁኔታ eventsን ወደ JSON-RPC 2.0 protocol በመተርጎም Cloud Agentsን እንደ A2A skills ማቅረብ ይቻላል። [A2A-SERVER.md](./A2A-SERVER.md)ን ይመልከቱ።
## አዲስ Cloud Agent ማከል
1. `CloudAgentBase`ን የሚያራዝም `src/lib/cloudAgent/agents/<name>.ts` ይፍጠሩ።
2. `createTask`፣ `getStatus`፣ `approvePlan`ን (የማይመለከት ከሆነ exception ይጣሉ)፣
`sendMessage`፣ `listSources`ን ይተግብሩ። ሁኔታን መደበኛ ለማድረግ `this.mapStatus(...)`ን ይጠቀሙ።
3. በ`src/lib/cloudAgent/registry.ts` ውስጥ በቋሚ `providerId` ስር ይመዝግቡት።
4. በ`src/lib/cloudAgent/types.ts` ውስጥ ያለውን የ`providerId` literal union
(`CloudAgentTask.providerId` እና `CreateCloudAgentTaskSchema`) ያስፋፉ።
5. providerው የግንኙነት record የሚያስፈልገው ከሆነ ወደ`src/shared/constants/providers.ts` ያክሉት።
OAuthን መሠረት ያደረጉ providers `src/lib/oauth/providers/`ንም ያስፈልጋቸዋል።
6. በ`tests/unit/cloud-agent-*.test.ts` ስር testsን ያክሉ።
7. ይህን doc እና የdashboardን `CLOUD_AGENTS` constant ያዘምኑ።
## ውቅረት
| የአካባቢ ተለዋዋጭ | ዓላማ |
| ---------------- | ------------------------------------------------ |
| `DATA_DIR` | `cloud_agent_tasks`ን የያዘው የSQLite የውሂብ ጎታ መገኛ |
| `JWT_SECRET` | በተግባር ማብቂያዎች ላይ ለአስተዳደር ማረጋገጫ ያስፈልጋል |
| `API_KEY_SECRET` | የአቅራቢ ግንኙነት ማረጋገጫ መረጃዎችን በማከማቻ ውስጥ ለማመስጠር ያስፈልጋል |
በአሁኑ ጊዜ ለCloud-Agent የተለዩ የአካባቢ ተለዋዋጮች የሉም — እያንዳንዱ ሚስጥር
በ`provider_connections` ሰንጠረዥ ውስጥ ይገኛል።
## በተጨማሪ ይመልከቱ
- [A2A-SERVER.md](./A2A-SERVER.md)
- [API_REFERENCE.md](../reference/API_REFERENCE.md)
- [SKILLS.md](./SKILLS.md)
- [MEMORY.md](./MEMORY.md)
- ምንጭ፦ `src/lib/cloudAgent/`
- መስመሮች፦ `src/app/api/v1/agents/tasks/`፣ `src/app/api/cloud/`
- ዳሽቦርድ፦ `src/app/(dashboard)/dashboard/cloud-agents/page.tsx`

887
docs/i18n/am/docs/frameworks/EMBEDDED-SERVICES.md Normal file
View File

@@ -0,0 +1,887 @@
# Embedded Services (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/EMBEDDED-SERVICES.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/EMBEDDED-SERVICES.md) · 🇦🇿 [az](../../../az/docs/frameworks/EMBEDDED-SERVICES.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/EMBEDDED-SERVICES.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/EMBEDDED-SERVICES.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/EMBEDDED-SERVICES.md) · 🇩🇰 [da](../../../da/docs/frameworks/EMBEDDED-SERVICES.md) · 🇩🇪 [de](../../../de/docs/frameworks/EMBEDDED-SERVICES.md) · 🇬🇷 [el](../../../el/docs/frameworks/EMBEDDED-SERVICES.md) · 🇪🇸 [es](../../../es/docs/frameworks/EMBEDDED-SERVICES.md) · 🇪🇪 [et](../../../et/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/EMBEDDED-SERVICES.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/EMBEDDED-SERVICES.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/EMBEDDED-SERVICES.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇱 [he](../../../he/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/EMBEDDED-SERVICES.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/EMBEDDED-SERVICES.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/EMBEDDED-SERVICES.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇩 [id](../../../id/docs/frameworks/EMBEDDED-SERVICES.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇹 [it](../../../it/docs/frameworks/EMBEDDED-SERVICES.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/EMBEDDED-SERVICES.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/EMBEDDED-SERVICES.md) · 🇰🇭 [km](../../../km/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/EMBEDDED-SERVICES.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/EMBEDDED-SERVICES.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/EMBEDDED-SERVICES.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/EMBEDDED-SERVICES.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/EMBEDDED-SERVICES.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/EMBEDDED-SERVICES.md) · 🇲🇲 [my](../../../my/docs/frameworks/EMBEDDED-SERVICES.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/EMBEDDED-SERVICES.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/EMBEDDED-SERVICES.md) · 🇳🇴 [no](../../../no/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [or](../../../or/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/EMBEDDED-SERVICES.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/EMBEDDED-SERVICES.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/EMBEDDED-SERVICES.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/EMBEDDED-SERVICES.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/EMBEDDED-SERVICES.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/EMBEDDED-SERVICES.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/EMBEDDED-SERVICES.md) · 🇱🇰 [si](../../../si/docs/frameworks/EMBEDDED-SERVICES.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/EMBEDDED-SERVICES.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/EMBEDDED-SERVICES.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/EMBEDDED-SERVICES.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/EMBEDDED-SERVICES.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/EMBEDDED-SERVICES.md) · 🇮🇳 [te](../../../te/docs/frameworks/EMBEDDED-SERVICES.md) · 🇹🇭 [th](../../../th/docs/frameworks/EMBEDDED-SERVICES.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/EMBEDDED-SERVICES.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/EMBEDDED-SERVICES.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/EMBEDDED-SERVICES.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/EMBEDDED-SERVICES.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/EMBEDDED-SERVICES.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/EMBEDDED-SERVICES.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/EMBEDDED-SERVICES.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/EMBEDDED-SERVICES.md)
---
> **ስሪት:** v3.8.44
> **ለመጨረሻ ጊዜ የተዘመነው:** 2026-07-03
> **ዒላማ አንባቢዎች:** የተካተቱ አገልግሎቶችን (9Router, CLIProxyAPI, Mux, Bifrost) የሚጨምሩ፣ የሚንከባከቡ ወይም ስህተት የሚያርሙ መሐንዲሶች።
የተካተቱ አገልግሎቶች OmniRoute በአካባቢው የሚጭናቸው፣ የሚቆጣጠራቸው እና
እንደ ዋና የማዘዋወሪያ ዒላማዎች የሚያቀርባቸው በአካባቢው የተጫኑ የሂደት ጎን-ለ-ጎን መሣሪያዎች ናቸው። ከውጫዊ አቅራቢዎች (በAPI ቁልፎች
አማካኝነት በበይነመረብ የሚደረስባቸው) በተለየ፣ የተካተቱ አገልግሎቶች ከOmniRoute ጋር በአንድ ማሽን ላይ ይሰራሉ እና በloopback በኩል ይገናኛሉ።
---
## የይዘት ማውጫ
1. [አጠቃላይ እይታ](#1-overview)
2. [አርክቴክቸር — 4 ንብርብሮች](#2-architecture--4-layers)
3. [የሕይወት ዑደት ሁኔታ ማሽን](#3-lifecycle-state-machine)
4. [የAPI ማጣቀሻ](#4-api-reference)
5. [ደህንነት](#5-security)
6. [አዲስ የተካተተ አገልግሎት ማከል](#6-adding-a-new-embedded-service)
7. [ችግር መፍታት](#7-troubleshooting)
8. [ተደጋጋሚ ጥያቄዎች](#8-faq)
---
## 1. አጠቃላይ እይታ
### የተካተቱ አገልግሎቶች ለምን ያስፈልጋሉ?
አምስት አገልግሎቶች ተካተዋል፦
| አገልግሎት | npm ጥቅል | ነባሪ ወደብ | ዓላማ |
| --------------- | ---------------------------------- | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **9Router** | `9router` | 20130 | OmniRoute እንደ ንዑስ አቅራቢ ሊጠቀምበት የሚችል AI ራውተር። ሞዴሎች እንደ `9router/{sub}/{model}` ይቀርባሉ |
| **CLIProxyAPI** | የGitHub ልቀት ባይነሪ (`cliproxy`) | 8317 | ለAnthropic CLI የማረጋገጫ ፍሰቶች የአካባቢ ፕሮክሲ አስማሚ። የOAuth ቶከኖች ጊዜያቸው ሲያልቅ ተተኪ ማዘዋወርን ያቀርባል |
| **Mux** | `mux` (ያለ ግራፊክ በይነገጽ `mux server`) | 8322 | የአካባቢ ወኪል-ማቀናበሪያ ዴሞን (coder/mux)። የሕይወት ዑደቱ ብቻ የሚተዳደር — የማዘዋወሪያ ዒላማ አይደለም (የLLM ፕሮክሲ ማድረግ የለም)። |
| **Bifrost** | `@maximhq/bifrost` | 8080 | የGo AI-ጌትዌይ ማስተላለፊያ የኋላ-ጫፍ። በሚሰራበት ጊዜ በማስተላለፊያ መስመሩ (`/v1/relay/`) በራስ-ሰር ይመረጣል |
| **Dario** | `@askalf/dario` | 3456 | የClaude ምዝገባ ፕሮክሲ — ለClaude-Code ቅርጽ ላለው ትራፊክ የCLIProxyAPI አማራጭ/ተተኪ፤ የገባው ቁልፍ `DARIO_ADMIN_TOKEN` በመሆን የእሱን `/admin/*` OAuth መቆጣጠሪያ ክፍል ይጠብቃል |
አምስቱም ተመሳሳይ የቁጥጥር ሞዴል ይከተላሉ፦
- OmniRoute በ`DATA_DIR/services/{name}/` ስር ይጭናቸዋል (ከOmniRoute የራሱ `package.json` ተለይተው)
- OmniRoute እንደ ልጅ ሂደቶች ያስጀምራቸዋል እና ይከታተላቸዋል
- OmniRoute ጊዜያዊ API ቁልፍን ወደ ልጅ ሂደቱ አካባቢ ያስገባል፣ እንዲሁም አገልግሎቱን ሳያቋርጥ ያድሰዋል (ተግባራዊ በሚሆንበት ቦታ)
- ሁሉም የአስተዳደር መስመሮች (`/api/services/*`) **LOCAL_ONLY** ናቸው — ከloopback ብቻ ተደራሽ ናቸው (ጥብቅ ደንብ #17)
### ቁልፍ ውሳኔዎች (ከንድፍ ዕቅዱ)
| ውሳኔ | እሴት |
| ----------------------------- | ----------------------------------------------------------------- |
| የዳሽቦርድ መዳረሻ ወደ 9Router ቤተኛ UI | በ`/dashboard/providers/services/9router/embed/*` ላይ Reverse proxy |
| የመጫኛ ዘዴ | `npm install {package}` በ`execFile` በኩል (የshell እሴት ማስገባት የለም) |
| የአጠቃቀም ሁነታ | አቅራቢው በማዘዋወሪያ ሞተሩ ውስጥ እንደ `9router/{sub}/{model}` ይመዘገባል |
| የAPI ቁልፍ አስተዳደር | OmniRoute ያመነጫል፣ በማከማቻ ላይ ያመሰጥራል (AES-256-GCM)፣ እና በenv በኩል ያስገባል |
| የዳሽቦርድ አካባቢ | `/dashboard/providers/services` (ሦስት ትሮች) |
| ራስ-ሰር ማስጀመር | ለእያንዳንዱ አገልግሎት የማብሪያ/ማጥፊያ አማራጭ፣ ነባሪው OFF |
---
## 2. አርክቴክቸር — 4 ንብርብሮች
```
┌────────────────────────────────────────────────────────────────────┐
│ ንብርብር 1 — UI │
│ /dashboard/providers/services (ትሮች፦ CLIProxyAPI | 9Router | Mux) │
│ የቀጥታ ሎጎች (SSE)፣ ማስጀመር/ማቆም/ዳግም ማስጀመር/ማዘመን፣ ቅንብሮች፣ መጫን │
│ │
│ src/app/(dashboard)/dashboard/providers/services/ │
│ ├── page.tsx ሼል + በ ?tab= የትር ማዘዋወር │
│ ├── tabs/ CliproxyServiceTab, NinerouterServiceTab,│
│ │ MuxServiceTab │
│ └── components/ ServiceStatusCard, ServiceLifecycleButtons,│
│ ServiceLogsPanel, ApiKeyCard, ... │
└──────────────────────┬─────────────────────────────────────────────┘
│ HTTP (Next.js fetch)
┌──────────────────────▼─────────────────────────────────────────────┐
│ ንብርብር 2 — API (LOCAL_ONLY — loopback ብቻ) │
│ │
│ /api/services/9router/{install|start|stop|restart|update| │
│ rotate-key|status|auto-start|logs} │
│ /api/services/cliproxy/{install|start|stop|restart|update| │
│ status|auto-start|logs} │
│ /api/services/mux/{install|start|stop|restart|update| │
│ status|auto-start|logs} │
│ /dashboard/providers/services/9router/embed/[...path] │
│ (የተገላቢጦሽ HTTP + WebSocket ፕሮክሲ → የ9Router upstream) │
│ │
│ መግቢያ መቆጣጠሪያ፦ LOCAL_ONLY_API_PREFIXES "/api/services/" እና │
│ "/dashboard/providers/services/*/embed/" ያካትታል │
└──────────────────────┬─────────────────────────────────────────────┘
│ በሂደት ውስጥ የሚደረጉ ጥሪዎች
┌──────────────────────▼─────────────────────────────────────────────┐
│ ንብርብር 3 — ServiceSupervisor (src/lib/services/) │
│ │
│ ServiceSupervisor.ts አጠቃላይ ተቆጣጣሪ (child_process.spawn) │
│ ├── መጫን፦ execFile('npm', ['install', pkg, '--prefix']) │
│ ├── ማስጀመር፦ spawn(node, [entrypoint], {env, cwd}) │
│ ├── api_key፦ crypto.randomBytes(32) → env NINEROUTER_API_KEY │
│ ├── ፖርት፦ ለ9Router 20130 (ሊዋቀር የሚችል) │
│ ├── ሎጎች፦ የstdio ቀለበት ቋት 5 MB → የSSE ክስተቶች │
│ ├── ጤና፦ HTTP GET /health በየ2–5 s፣ በፍላጎት ጊዜ ማገገም │
│ └── የሕይወት ዑደት፦ SIGTERM 15 s → SIGKILL │
│ │
│ registry.ts getSupervisor(name) / registerSupervisor() │
│ bootstrap.ts ሂደቱ ሲጀምር ሁሉንም SERVICES[] ያስነሳል │
│ apiKey.ts getOrCreateApiKey(), generateServiceApiKey() │
│ modelSync.ts ወቅታዊ GET /v1/models → service_models ሰንጠረዥ │
│ ringBuffer.ts ክብ የሎግ ቋት (ለእያንዳንዱ አገልግሎት 5 MB) │
│ healthCheck.ts በየጊዜው የሚጠይቅ HTTP የጤና መመርመሪያ │
│ installers/ ninerouter.ts, cliproxy.ts, mux.ts │
│ (የጫኝ ማስማሚያዎች) │
└──────────────────────┬─────────────────────────────────────────────┘
│ ከOpenAI ጋር ተኳሃኝ HTTP (loopback)
┌──────────────────────▼─────────────────────────────────────────────┐
│ ንብርብር 4 — አቅራቢ / ማዘዋወር │
│ │
│ open-sse/executors/ninerouter.ts │
│ በእያንዳንዱ ጥያቄ ፖርቱንና API ቁልፉን እንደገና ይፈልጋል (መሸጎጥ የለም)። │
│ ፕሮክሲ ከማድረጉ በፊት ከሞዴል id ላይ "9router/" ቅድመ ቅጥያን ያስወግዳል።│
│ ተቆጣጣሪው በ "running" ሁኔታ ካልሆነ 503 service_not_running ይመልሳል።│
│ │
│ src/shared/constants/providers.ts │
│ የ"9router" ግቤት፦ isEmbeddedService: true │
│ │
│ open-sse/config/providerRegistry.ts │
│ ሞዴሎች እንደ "9router/{sub}/{model}" (ቅድመ ቅጥያ ያላቸው) ይቀመጣሉ። │
│ በmodelSync.ts በየ5 min ይመሳሰላሉ። │
│ │
│ Mux የሕይወት ዑደቱ ብቻ ይተዳደራል (ንብርብሮች 1-3) — ይህ የagent- │
│ ኦርኬስትሬሽን daemon እንጂ LLM ፕሮክሲ አይደለም፤ ስለዚህ የንብርብር 4 │
│ executor/provider ግቤት የለውም፣ መቼም የማዘዋወር መድረሻ አይሆንም። │
└────────────────────────────────────────────────────────────────────┘
```
### ቁልፍ የምንጭ ፋይሎች
| ፋይል | ሚና |
| ------------------------------------------- | -------------------------------------- |
| `src/lib/services/ServiceSupervisor.ts` | ዋና ክፍል፦ የሕይወት ዑደት፣ መቆለፊያ፣ ጤና፣ የቀለበት ቋት |
| `src/lib/services/bootstrap.ts` | በሂደት ደረጃ ምዝገባ እና ራስ-ሰር ማስጀመር |
| `src/lib/services/registry.ts` | ነጠላ ኢንስታንስ ካርታ `tool → supervisor` |
| `src/lib/services/apiKey.ts` | ቁልፍ ማመንጨት፣ በእረፍት ላይ የAES-256-GCM ምስጠራ |
| `src/lib/services/modelSync.ts` | ወቅታዊ የሞዴል ማመሳሰል (5 ደቂቃ) + በጥያቄ ጊዜ |
| `src/lib/services/ringBuffer.ts` | SSE የደንበኝነት ምዝገባ ያለው 5 MB ክብ የሎግ ቋት |
| `src/lib/services/healthCheck.ts` | HTTP የጤና ፍተሻ (ሊዋቀር የሚችል የጊዜ ልዩነት) |
| `src/lib/services/installers/ninerouter.ts` | ለ9Router npm መጫን/ማዘመን/ማራገፍ |
| `src/lib/services/installers/cliproxy.ts` | ለCLIProxyAPI npm መጫን/ማዘመን/ማራገፍ |
| `src/lib/services/installers/mux.ts` | ለMux npm መጫን/ማዘመን/ማራገፍ |
| `src/app/api/services/9router/_lib.ts` | `getOrInitSupervisor()` ረዳት |
| `src/app/api/services/[name]/logs/route.ts` | የጋራ SSE ሎጎች መዳረሻ |
| `open-sse/executors/ninerouter.ts` | የአቅራቢ አስፈጻሚ (ንብርብር 4) |
---
## 3. የሕይወት ዑደት ሁኔታ ማሽን
```
install()
┌─────────────┐ ──────────► ┌─────────────┐
│ not_installed│ │ stopped │◄──────────────────┐
└─────────────┘ └──────┬──────┘ │
│ start() │
▼ │ stop()
┌──────────┐ │
│ starting │ │
└────┬─────┘ │
የጤና ምርመራው ተሳክቷል │ ብልሽት / SIGTERM │
┌────▼─────┐ (በ5s ውስጥ ይወጣል) │
│ running │──── ብልሽት ─────────►┤
└────┬─────┘ ┌─▼────┐
stop() │ │error │
▼ └──────┘
┌──────────┐
│ stopping │
└──────────┘
```
ሁኔታዎች በ`version_manager` DB ሰንጠረዥ (`status` ዓምድ) ውስጥ ይቀመጣሉ፣ እንዲሁም
በ`ServiceSupervisor` የማህደረ ትውስታ ውስጥ ሁኔታ ይንጸባረቃሉ። እየሰራ ላለ ሂደት የማህደረ ትውስታው
ሁኔታ ወሳኝ ምንጭ ነው፤ የDB ሁኔታው ደግሞ ሲነሳ ዘላቂ መጠባበቂያ ነው።
### የሁኔታ ሽግግሮች
| ከ | ክስተት | ወደ |
| --------------- | ----------------------------- | ---------------------- |
| `not_installed` | `install()` ተሳክቷል | `stopped` |
| `stopped` | `start()` ተጠርቷል | `starting` |
| `starting` | የጤና ምርመራው 200 መለሰ | `running` |
| `starting` | ሂደቱ ጤናማ ከመሆኑ በፊት ወጣ | `error` |
| `running` | `stop()` ተጠርቷል | `stopping` → `stopped` |
| `running` | ሂደቱ ሳይጠበቅ ወጣ (< 5 s) | `error` (ፈጣን ብልሽት) |
| `running` | ሂደቱ ሳይጠበቅ ወጣ (> 5 s) | `error` |
| `error` | `start()` ተጠርቷል | `starting` |
| ማንኛውም | `stopping` በሚሆንበት ጊዜ `stop()` | ምንም አያደርግም |
### የክወና መቆለፊያ
`ServiceSupervisor` የሕይወት ዑደት ክወናዎችን በasync የክወና መቆለፊያ
(`withLock()`) ተከታታይ ያደርጋል። በአንድ supervisor ላይ በአንድ ጊዜ የሚደረጉ `start()` ጥሪዎች
በትክክል አንድ spawn ብቻ ያስከትላሉ፤ ሁለተኛው ጠሪ ይጠብቃል እና ያለውን ሁኔታ ይመልሳል።
ይህ፣ ለምሳሌ auto-start እና የUI አዝራር በአንድ ጊዜ ሲነሱ፣ የውድድር ሁኔታዎችን
ይከላከላል።
---
## 4. የAPI ማጣቀሻ
በ`/api/services/` ስር ያሉ ሁሉም routes **LOCAL_ONLY** ናቸው (loopback ብቻ፣ ጥብቅ ደንብ #17)።
ከloopback ውጭ የሆኑ ጥያቄዎች auth token ቢኖራቸውም `403 LOCAL_ONLY` ይቀበላሉ።
### 4.1 የ9Router endpoints (11 routes)
#### `POST /api/services/9router/install`
9Routerን ከnpm ይጫናል። የራሱ `package.json` እና `node_modules/` ያሉትን
`DATA_DIR/services/9router/` ይፈጥራል። ከOmniRoute የራሱ deps ጋር አይጋጭም።
**የጥያቄ አካል** (ሁሉም አማራጭ ናቸው):
```json
{ "version": "latest" }
```
| መስክ | ዓይነት | ነባሪ | መግለጫ |
| --------- | -------- | ---------- | -------------------------------- |
| `version` | `string` | `"latest"` | የሚጫነው npm version tag ወይም semver |
**ምላሾች:**
| ሁኔታ | መግለጫ |
| ----- | ---------------------------------------------------------- |
| `200` | `{ ok: true, installedVersion: "x.y.z", path: "..." }` |
| `400` | ልክ ያልሆነ የጥያቄ አካል (የZod ማረጋገጫ አልተሳካም) |
| `409` | አስቀድሞ በመጫን ላይ ነው (መቆለፊያው ተይዟል) |
| `500` | npm install አልተሳካም — ቀላል የስህተት መልዕክት ለማየት `message`ን ይመልከቱ |
**ማስታወሻዎች:** `execFile('npm', [...])`ን ይጠቀማል — shell የለም፣ interpolation የለም (ጥብቅ ደንብ #13)።
የEACCES ስህተቶች በቀላሉ ሊገቡ እንደሚችሉ መልዕክቶች ይቀርባሉ።
---
#### `POST /api/services/9router/start`
9Routerን ያስጀምራል። አስቀድሞ ካልተመዘገበ supervisor ይመዘግባል፣ ከዚያ
`supervisor.start()`ን ይጠራል። አስቀድሞ እየሰራ ከሆነ idempotent ነው።
**የጥያቄ አካል:** የለም
**ምላሾች:**
| ሁኔታ | መግለጫ |
| ----- | ---------------------------------------------- |
| `200` | `ServiceStatus` object (ከታች ያለውን schema ይመልከቱ) |
| `409` | 9Router አልተጫነም (`status: "not_installed"`) |
| `503` | መጀመር አልተሳካም (የሂደት ስህተት — `lastError`ን ይመልከቱ) |
**የServiceStatus schema:**
```json
{
"tool": "9router",
"state": "running",
"pid": 12345,
"port": 20130,
"health": "healthy",
"startedAt": "2026-05-25T10:00:00.000Z",
"lastError": null
}
```
---
#### `POST /api/services/9router/stop`
9Routerን በተገቢው ሁኔታ ያቆማል። SIGTERM ይልካል፣ 15 s ይጠብቃል፣ አሁንም በሕይወት ካለ ከዚያ SIGKILL ይልካል።
አስቀድሞ ቆሞ ከሆነ idempotent ነው።
**የጥያቄ አካል:** የለም
**ምላሾች:**
| ሁኔታ | መግለጫ |
| ----- | ---------------------------------- |
| `200` | `ServiceStatus` (state: "stopped") |
| `503` | ማቆም ሳይጠበቅ አልተሳካም |
---
#### `POST /api/services/9router/restart`
በክወና መቆለፊያው ውስጥ `stop()` ከዚያ `start()` ከማድረግ ጋር ተመሳሳይ ነው።
**የጥያቄ አካል:** የለም
**ምላሾች:** ከ`start` ጋር ተመሳሳይ ናቸው (የመጨረሻውን `ServiceStatus` ይመልሳል)።
---
#### `POST /api/services/9router/update`
9Routerን ወደ አዲስ npm version ያዘምናል። አገልግሎቱ እየሰራ ከሆነ በመጀመሪያ
ይቆማል፣ npm install ይካሄዳል (አዲሱን version በቦታው ላይ ይጭናል)፣ ከዚያም
አገልግሎቱ እንደገና ይጀምራል።
**የጥያቄ አካል** (ሁሉም አማራጭ ናቸው):
```json
{ "version": "latest" }
```
**ምላሾች:**
| ሁኔታ | መግለጫ |
| ----- | --------------------------------------------------------------- |
| `200` | `{ ok: true, previousVersion: "...", installedVersion: "..." }` |
| `400` | ልክ ያልሆነ አካል |
| `500` | npm update አልተሳካም |
---
#### `POST /api/services/9router/rotate-key`
ለ9Router አዲስ API ቁልፍ ያመነጫል፣ በማከማቻ ላይ ሳለ ያመሰጥረዋል፣ እና አገልግሎቱ እየሰራ ከሆነ አዲሱን ቁልፍ ከአካባቢው እንዲወስድ ዳግም ያስጀምረዋል። የቀድሞው ቁልፍ ወዲያውኑ ዋጋ አልባ ይደረጋል።
**የጥያቄ አካል፦** የለም
**ምላሾች፦**
| ሁኔታ | መግለጫ |
| ----- | ------------------------------------------ |
| `200` | `{ keyRotated: true, restarted: boolean }` |
| `500` | ቁልፍ ማዞር አልተሳካም |
**ደህንነት፦** አዲሱ ቁልፍ በምላሹ ውስጥ ፈጽሞ አይመለስም (የማረጋገጫ መረጃ እንዳይፈስ)። በ`version_manager` ሰንጠረዥ ውስጥ ተመስጥሮ (AES-256-GCM) ይከማቻል።
---
#### `GET /api/services/9router/status`
የስሪት ሜታዳታን እና የAPI ቁልፍ ቅድመ ዕይታን ጨምሮ የተጣመረ የቀጥታ + DB ሁኔታን ይመልሳል።
**ምላሾች፦**
| ሁኔታ | መግለጫ |
| ----- | --------------------- |
| `200` | ከታች ያለውን መርሐግብር ይመልከቱ |
| `500` | የሁኔታ ንባብ አልተሳካም |
**የምላሽ መርሐግብር፦**
```json
{
"tool": "9router",
"state": "running",
"pid": 12345,
"port": 20130,
"health": "healthy",
"startedAt": "2026-05-25T10:00:00.000Z",
"lastError": null,
"installedVersion": "1.2.3",
"latestVersion": "1.2.4",
"updateAvailable": true,
"apiKeyMasked": "nr_****abcd",
"autoStart": false,
"providerExpose": false
}
```
---
#### `POST /api/services/9router/auto-start`
የራስ-ሰር ማስጀመሪያ ጠቋሚውን ያብሩ ወይም ያጥፉ። `enabled: true` ሲሆን፣ በሚቀጥለው ጊዜ OmniRoute ሲነሳ አገልግሎቱ በራስ-ሰር ይጀምራል (አገልግሎቱ ከተጫነ)።
**የጥያቄ አካል፦**
```json
{ "enabled": true }
```
**ምላሾች፦**
| ሁኔታ | መግለጫ |
| ----- | --------------------- |
| `200` | `{ autoStart: true }` |
| `400` | ልክ ያልሆነ አካል |
---
#### `GET /api/services/9router/logs`
ከ9Router stdout/stderr ቀለበታዊ ቋት የሚመጡ የቀጥታ ምዝግቦች SSE ዥረት።
**የመጠይቅ መለኪያዎች፦**
| መለኪያ | ዓይነት | ነባሪ | መግለጫ |
| -------- | --------- | --- | ---------------------------------------------------------- |
| `tail` | `integer` | 200 | በመጀመሪያ የሚላኩ የታሪክ መስመሮች ብዛት (ከፍተኛው 1000) |
| `filter` | `string` | የለም | የፊደል መጠንን የማይለይ ንዑስ ሕብረቁምፊ ማጣሪያ (regex የለም — ከReDoS የተጠበቀ) |
**የSSE ክስተቶች፦**
| ክስተት | ውሂብ | መግለጫ |
| ----------- | ----------- | --------------------- |
| `snapshot` | `LogLine[]` | የመጀመሪያ ታሪካዊ የመጨረሻ ክፍል |
| `log` | `LogLine` | የቀጥታ ምዝግብ መስመር |
| `heartbeat` | `{}` | በየ15 ሰከንዱ ግንኙነትን ማቆየት |
**የLogLine መርሐግብር፦**
```json
{
"ts": 1716633600000,
"stream": "stdout",
"line": "[9router] Listening on :20130"
}
```
**ምላሾች፦**
| ሁኔታ | መግለጫ |
| ----- | ---------------------------------------- |
| `200` | `text/event-stream` |
| `400` | የ`filter` መለኪያው በጣም ረጅም ነው (> 200 ቁምፊዎች) |
| `404` | አገልግሎቱ አልተገኘም (በተቆጣጣሪው ውስጥ አልተመዘገበም) |
---
### 4.2 የCLIProxyAPI የመዳረሻ ነጥቦች (10 መስመሮች)
CLIProxyAPI ከ`rotate-key` በስተቀር ከ9Router ጋር ተመሳሳይ የመዳረሻ ነጥብ ቅርጽ አለው፤ በተጨማሪም `accounts`፣ `provider-expose` እና `auto-restart-adopted` አሉት። አሁን በማስጀመር ጊዜ የሚወከል የተለየ የውሂብ-አውታር API ቁልፍ ይቀበላል (`needsApiKey: true` በ`bootstrap.ts` ውስጥ፣ ለሞዴል ማመሳሰል የሚውል)፤ `status` ያነሱ መስኮችን ያካትታል።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ----------------------------------- | ---------------------------------- |
| `POST` | `/api/services/cliproxy/install` | CLIProxyAPIን ከnpm ይጫኑ |
| `POST` | `/api/services/cliproxy/start` | CLIProxyAPIን ያስጀምሩ |
| `POST` | `/api/services/cliproxy/stop` | CLIProxyAPIን ያቁሙ |
| `POST` | `/api/services/cliproxy/restart` | CLIProxyAPIን ዳግም ያስጀምሩ |
| `POST` | `/api/services/cliproxy/update` | ወደ አዲስ ስሪት ያዘምኑ |
| `GET` | `/api/services/cliproxy/status` | የቀጥታ + DB ሁኔታ (`apiKeyMasked` የለም) |
| `POST` | `/api/services/cliproxy/auto-start` | ራስ-ሰር ማስጀመርን ያብሩ ወይም ያጥፉ |
የጋራው `GET /api/services/{name}/logs` የመዳረሻ ነጥብ (§4.1ን ይመልከቱ) የ`[name]` ተለዋዋጭ ክፍልን በመጠቀም ለአራቱም አገልግሎቶች ይሰራል።
---
### 4.3 የMux መዳረሻ ነጥቦች (8 መስመሮች)
Mux ከCLIProxyAPI ጋር ተመሳሳይ የመዳረሻ ነጥብ ቅርጽ አለው — በAPI ወለል ላይ የ`rotate-key` መስመር የለም (የbearer token በ`getOrCreateApiKey("mux")` በኩል እንደ9Router ተመሳሳይ መንገድ ይመነጫል እና በ`MUX_SERVER_AUTH_TOKEN` የአካባቢ ተለዋዋጭ በኩል ይወከላል፣ ነገር ግን እስካሁን የተለየ የማዞሪያ መዳረሻ ነጥብ የለም)። Mux የሚተዳደረው በሕይወት-ዑደት ብቻ ነው፦ እንደ9Router ሳይሆን፣ Layer 4 አስፈጻሚ የለውም እና እንደ የማዞሪያ አቅራቢ ፈጽሞ አይመዘገብም።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ------------------------------ | --------------------------- |
| `POST` | `/api/services/mux/install` | Muxን ከnpm ይጫኑ (`npm i mux`) |
| `POST` | `/api/services/mux/start` | Muxን ያስጀምሩ (`mux server`) |
| `POST` | `/api/services/mux/stop` | Muxን ያቁሙ |
| `POST` | `/api/services/mux/restart` | Muxን ዳግም ያስጀምሩ |
| `POST` | `/api/services/mux/update` | ወደ አዲስ የnpm ስሪት ያዘምኑ |
| `GET` | `/api/services/mux/status` | የቀጥታ + DB ሁኔታ |
| `POST` | `/api/services/mux/auto-start` | ራስ-ሰር ማስጀመርን ያብሩ ወይም ያጥፉ |
---
### 4.4 የBifrost መዳረሻ ነጥቦች (8 መስመሮች)
Bifrost በGo የተገነባ AI-ጌትዌይ ማስተላለፊያ የኋላ-ጫፍ ነው (`@maximhq/bifrost`)። ከCLIProxyAPI ጋር ተመሳሳይ የመዳረሻ ነጥብ ቅርጽ ይጠቀማል (`rotate-key` የለም — Bifrost በ`-app-dir` ስር ባለው `config.json` ውስጥ የራሱን የአቅራቢ ቁልፎች ያስተዳድራል)።
| ዘዴ | መንገድ | መግለጫ |
| ------ | ---------------------------------- | ----------------------------------------------- |
| `POST` | `/api/services/bifrost/install` | Bifrostን ከ npm (`@maximhq/bifrost`) ይጫኑ |
| `POST` | `/api/services/bifrost/start` | Bifrostን በ8080 ፖርት (ነባሪ) ያስጀምሩ |
| `POST` | `/api/services/bifrost/stop` | Bifrostን ያቁሙ |
| `POST` | `/api/services/bifrost/restart` | Bifrostን እንደገና ያስጀምሩ |
| `POST` | `/api/services/bifrost/update` | ወደ አዲስ ስሪት ያዘምኑ |
| `GET` | `/api/services/bifrost/status` | የቀጥታ + DB ሁኔታ |
| `POST` | `/api/services/bifrost/auto-start` | ራስ-ሰር ማስጀመርን ያብሩ/ያጥፉ |
| `GET` | `/api/services/bifrost/logs` | የSSE ሎግ መጨረሻ (በጋራ `[name]/logs` ተለዋዋጭ መስመር በኩል) |
**የራውቲንግ ውቅር:** `BIFROST_BASE_URL` ካልተቀናበረ እና ቁጥጥር ስር ያለው Bifrost
ኢንስታንስ እየሰራ ከሆነ፣ `getBifrostRoutingConfig()` (`routingBackend.ts` ውስጥ) በራስ-ሰር
`http://127.0.0.1:{port}`ን እንደ የሪሌይ መሠረታዊ URL ይጠቀማል። በግልጽ የተቀናበረ `BIFROST_BASE_URL` የአካባቢ ተለዋዋጭ
ሁልጊዜ ቅድሚያ ይኖረዋል።
---
### 4.5 የDario መጨረሻ ነጥቦች (12 መስመሮች)
እንደ ሌሎቹ አገልግሎቶች ተመሳሳይ የሕይወት ዑደት ቅርጽ (`install`፣ `start`፣ `stop`፣ `restart`፣
`update`፣ `status`፣ `auto-start`፣ `auto-restart-adopted`) እንዲሁም በ`admin/` ስር በቶከን የተጠበቀ OAuth
መቆጣጠሪያ አለ፦ `admin/accounts`፣ `admin/import-from-omniroute`፣
`admin/login-start`፣ `admin/login-complete` (ሁሉም በ`DARIO_ADMIN_TOKEN` የተጠበቁ ናቸው)።
### 4.6 ተቃራኒ ፕሮክሲ (የ9Router ዳሽቦርድ መክተቻ)
ዳሽቦርዱ የ9Router ድር UIን በውስጣዊ ተቃራኒ
ፕሮክሲ በኩል በiframe ውስጥ ያካትታል፦
```
GET|POST|... /dashboard/providers/services/9router/embed/[...path]
```
ይህ ፕሮክሲ፦
- ጥያቄውን ወደ `http://127.0.0.1:{port}/{path}` ያስተላልፋል (loopback ብቻ)
- ገቢ `cookie` እና `authorization` ራስጌዎችን ያስወግዳል (የOmniRoute ክፍለ ጊዜ መረጃ እንዳይፈስ)
- ለ9Router ማረጋገጫ `Authorization: Bearer {apiKey}`ን ያስገባል
- ከምላሹ `set-cookie`፣ `content-security-policy`፣ `x-frame-options`፣ `cross-origin-*`ን ያስወግዳል
- `<base href>`ን ለማስገባት እና ፍጹም መንገዶችን መደበኛ ለማድረግ (`/foo` → `/dashboard/.../embed/foo`) የHTML ምላሾችን እንደገና ይጽፋል
ለተካተተው ዳሽቦርድ የWebSocket ማሻሻያዎች በተለየ
ፖርት ላይ ባለ አጋር አገልጋይ ይስተናገዳሉ (`src/lib/services/embedWsProxy.ts`ን ይመልከቱ)።
**ደህንነት:** የመክተቻ ፕሮክሲ መስመሮች በ`LOCAL_ONLY_API_PREFIXES` ስር የተመደቡ ሲሆን
ከloopback ብቻ ሊደረስባቸው ይችላል። በCloudflare/Ngrok ቱነል በኩል JWT ያገኘ አጥቂ
ወደ ተካተቱ አገልግሎቶች በፕሮክሲ መግባት አይችልም።
---
## 5. ደህንነት
### LOCAL_ONLY ማስገደጃ (ጥብቅ ደንብ #17)
በ `/api/services/` እና `/dashboard/providers/services/*/embed/` ስር ያሉ ሁሉም መስመሮች
በ `src/server/authz/routeGuard.ts` ውስጥ LOCAL_ONLY ተብለው ተመድበዋል። የloopback ማረጋገጫው
ከማንኛውም የማረጋገጫ ቅርንጫፍ በፊት ያለምንም ሁኔታ ይሠራል፦
```
ጥያቄው ይደርሳል
→ isLocalOnlyPath(path)?
→ loopback ያልሆነ → 403 LOCAL_ONLY (ሁልጊዜ፣ ከማረጋገጫው በፊት)
→ loopback የሆነ → ወደ መደበኛው ማረጋገጫ ይቀጥላል
```
ይህ የወጣ JWT (ለምሳሌ፣ በtunnel በኩል) `npm install` እንዳያስጀምር ወይም
process እንዳይፈጥር ይከላከላል። ሙሉውን የደረጃ ማትሪክስ ለማየት
`docs/security/ROUTE_GUARD_TIERS.md`ን ይመልከቱ።
### የAPI ቁልፍ ማስገባት
9Router እና Mux ለራሳቸው HTTP endpoints የAPI ቁልፍ/bearer token ያስፈልጋቸዋል።
OmniRoute፦
1. ለአገልግሎቱ የተለየ ቅድመ ቅጥያ (`nr_` ለ9Router፣ `mx_` ለMux) በመጠቀም
በ `crypto.randomBytes(32).toString("base64url")` ቁልፍ ያመነጫል።
2. AES-256-GCMን በመጠቀም በማከማቻ ላይ ያመሰጥረዋል (ለprovider ማረጋገጫ መረጃዎች
የሚያገለግለው ተመሳሳይ cipher)።
3. በprocess መፍጠሪያ ጊዜ ዲክሪፕት አድርጎ እንደ environment variable ያስገባዋል —
`NINEROUTER_API_KEY` ለ9Router፣ `MUX_SERVER_AUTH_TOKEN` ለMux (በፍጹም እንደ CLI
flag አይተላለፍም፣ ስለዚህ tokenው በ `ps`/process ዝርዝሮች ውስጥ አይታይም)።
4. ግልጽ ያልተመሰጠረውን ቁልፍ በማንኛውም HTTP ምላሽ ውስጥ አይመልስም።
CLIProxyAPI በprocess መፍጠሪያ ጊዜ የሚገባ የተወሰነ data-plane ቁልፍ ይቀበላል
(`needsApiKey: true` — ከadapter ጋር ለmodel sync ያገለግላል)።
### የSSRF መከላከያ
የreverse HTTP proxy (`/dashboard/.../embed/[...path]`) ጥያቄዎችን ወደ
`http://127.0.0.1:{port}` ብቻ እንዲያስተላልፍ በቋሚነት ተዋቅሯል። ወደ loopback ያልሆኑ
መዳረሻዎች redirectsን ፈጽሞ አይከተልም። ከloopback ክልል ውጭ ወዳለ አድራሻ
የሚፈታ ማንኛውንም upstream URL ለመከልከል `ssrf-req-filter` library ጥቅም ላይ ይውላል።
### የShell ደህንነት (ጥብቅ ደንብ #13)
`npm install` የሚጠራው በ `execFile('npm', ['install', pkg, '--prefix', dir])` ነው —
template literals አይጠቀምም፣ shell አይጠቀምም፣ እንዲሁም ውጫዊ ዱካዎችን ወደ command
string አያስገባም። Runtime እሴቶች (ports፣ API ቁልፎች) በchild processው `env` object
በኩል ይተላለፋሉ።
### የስህተት ማጽዳት (ጥብቅ ደንብ #12)
ከ `/api/services/*` የሚመጡ ሁሉም የስህተት ምላሾች በ `buildErrorBody()` ወይም
`sanitizeErrorMessage()` በኩል ያልፋሉ። ጥሬ `err.stack` እና `err.message` ለጠሪው
በቀጥታ ፈጽሞ አይመለሱም።
---
## 6. አዲስ embedded service ማከል
እነዚህን 8 ደረጃዎች ይከተሉ። በ `src/lib/services/installers/`
እና `src/app/api/services/` ውስጥ ያሉትን ነባር implementations እንደ ዋና ማጣቀሻ ያንብቡ።
### ደረጃ 1 — installerውን ይፍጠሩ
በ `ninerouter.ts` የተቀረጸ `src/lib/services/installers/{name}.ts`ን ይፍጠሩ፦
```typescript
export const NAME_PACKAGE = "your-npm-package";
export const NAME_DEFAULT_PORT = 20132; // ነፃ port ይምረጡ
export async function install(version = "latest"): Promise<InstallResult> { ... }
export async function update(version = "latest"): Promise<InstallResult> { ... }
export async function uninstall(): Promise<void> { ... }
export function resolveSpawnArgs(apiKey: string, port: number): SpawnArgs { ... }
export async function getInstalledVersion(): Promise<string | null> { ... }
export async function getLatestVersion(): Promise<string | null> { ... }
```
ከ `installers/utils.ts` የሚገኘውን `runNpm(['install', NAME_PACKAGE, '--prefix', dir])`
ይጠቀሙ — `execSync`ን ወይም shell interpolationን ፈጽሞ አይጠቀሙ።
### ደረጃ 2 — በbootstrap ውስጥ ይመዝግቡ
በ `src/lib/services/bootstrap.ts` ውስጥ ወዳለው `SERVICES` array አንድ `ServiceEntry`
ያክሉ፦
```typescript
{
tool: "myservice",
port: NAME_DEFAULT_PORT,
healthPath: "/health",
healthIntervalMs: 5_000,
stopTimeoutMs: 15_000,
logsBufferBytes: 5_242_880,
needsApiKey: true, // API ቁልፍ የማያስፈልግ ከሆነ false
}
```
`cfg.tool === "myservice"`ን እንዲያስተናግድ `buildSpawnArgsFactory()`ን ያስፋፉ።
#### ሊሰካ የሚችል provider-plugin ውል (Phase 1፣ #7333)
`src/lib/services/providerPlugins/` የአንድ backend `bootstrap.ts` `ServiceEntry` fieldsን እና
`serviceBackends.ts` manifest-template fieldsን ወደ አንድ object የሚያጠቃልል
`ServiceProviderPlugin` ውል ያስተዋውቃል፤ ይህም የአንድ backend ቅርጽ በሁለት ያልተያያዙ
ፋይሎች ውስጥ በተናጠል እንዳይገለጽ ያደርጋል። ይህ በተጻፈበት ጊዜ **`9router` ብቻ
ተዛውሯል** — `bootstrap.ts` የ `SERVICES[]` entryውን ከ
`getServiceProviderPlugin("9router")` (`src/lib/services/providerPlugins/registry.ts`)
ያመነጫል፤ pluginው በማንኛውም ጊዜ ከጠፋ የመነሻ ስህተት ይፈጥራል። `cliproxy`፣ `mux`፣ እና `bifrost`
ነባሮቹ የinline `SERVICES[]` literals ሳይቀየሩ እንዳሉ ይቆያሉ።
`open-sse/config/providerPluginManifest.ts` እንዲሁም በሚገባ የተቀረጸ
`ProviderPluginManifestEntry`ን ከ `SERVICE_BACKEND_MANIFEST_TEMPLATE` entry የሚገነባ
ተጨማሪ `createServiceBackendManifestEntry(pluginId, template)` helper አግኝቷል — እስካሁን
ድረስ ከማንኛውም በቀጥታ ከሚሠራ request path ጋር **አልተገናኘም** (`generateProviderPluginManifestFromRegistry()`
ወይም `/v1/providers/[provider]/models`)፤ ውሉ ለሁለተኛ backend ከተረጋገጠ በኋላ ይህ
በቀጣይ የሚሠራ ሥራ ነው።
በissue #7333 ስር ተከታትለው ወደ ቀጣይ PRs የተላለፉ ሥራዎች፦ `cliproxyapi`ን በተመሳሳይ
registry ማዛወር፣ `mux`/`bifrost`ን ወደ `ServiceBackendPluginId` union ማጠቃለል፣
የexecutor-routing ልዩ አያያዝን (`open-sse/executors/index.ts`፣
`open-sse/handlers/chatCore/executorProxy.ts`) ወደ plugin ውሉ ማካተት፣ እና
`createServiceBackendManifestEntry()`ን በቀጥታ ከሚሠራ manifest/models code path ጋር ማገናኘት።
### ደረጃ 3 — migration እና DB seed ያክሉ
በ `src/lib/db/migrations/` ውስጥ migration በመጠቀም አገልግሎቱ በ `version_manager`
ውስጥ row እንዳለው ያረጋግጡ። rowው የሚከተለው ሊኖረው ይገባል፦
```sql
INSERT OR IGNORE INTO version_manager (tool, status, auto_start, provider_expose)
VALUES ('myservice', 'not_installed', 0, 0);
```
### ደረጃ 4 — 7ቱን API endpoints ይፍጠሩ
በ `src/app/api/services/{name}/` ስር፦
```
_lib.ts getOrInitSupervisor() helper
install/route.ts POST — installer.install()ን ይጠራል
start/route.ts POST — supervisor.start()ን ይጠራል
stop/route.ts POST — supervisor.stop()ን ይጠራል
restart/route.ts POST — supervisor.restart()ን ይጠራል
update/route.ts POST — installer.update()ን ይጠራል
status/route.ts GET — የቀጥታ + DB statusን ያዋህዳል
auto-start/route.ts POST — auto_start flagን ይቀያይራል
```
የጋራው `GET /api/services/[name]/logs` መስመር አስቀድሞ ተገናኝቷል — በዚያ ምንም ለውጥ
አያስፈልግም።
ሁሉንም የስህተት ምላሾች በ`createErrorResponse()` / `buildErrorBody()` በኩል ያስተላልፉ።
### ደረጃ 5 — ወደ LOCAL_ONLY_API_PREFIXES ያክሉ
በ`src/server/authz/routeGuard.ts` ውስጥ `/api/services/` አስቀድሞ መዘርዘሩን ያረጋግጡ።
አዲስ ቅድመ ቅጥያ ካስገቡ (ለምሳሌ፣ `/api/tools/`)፣ ወደ
`LOCAL_ONLY_API_PREFIXES` እና፣ ፕሮሰሶችን የሚጀምር ከሆነ፣ ወደ `SPAWN_CAPABLE_PREFIXES` ያክሉት።
በ`tests/unit/authz/routeGuard.test.ts` ውስጥ ሙከራ ያክሉ።
### ደረጃ 6 — የUI ትርን ያክሉ
`src/app/(dashboard)/dashboard/providers/services/tabs/{Name}ServiceTab.tsx` ይፍጠሩ።
የጋራ ክፍሎችን እንደገና ይጠቀሙ፦
- `ServiceStatusCard` — ቀጥታ ሁኔታ + የጤና ባጅ
- `ServiceLifecycleButtons` — ጀምር / አቁም / እንደገና ጀምር / አዘምን
- `ServiceLogsPanel` — የSSE ሎግ ጭራ (ከ`/api/services/{name}/logs` ጋር ይገናኛል)
- `ApiKeyCard` — ቁልፍን ማሳየት + ማዞር (`needsApiKey: true` ከሆነ)
ትሩን በ`ServicesPageShell.tsx` ውስጥ ይመዝግቡ።
### ደረጃ 7 — የአቅራቢ ግቤትን ያክሉ (አገልግሎቱ የማስተላለፊያ ዒላማ ከሆነ)
የተካተተው አገልግሎት ከOpenAI ጋር ተኳሃኝ የሆነ `/v1/chat/completions` መጨረሻ ነጥብ የሚያቀርብ ከሆነ፦
1. `isEmbeddedService: true` ያለውን የአቅራቢ ግቤት በ`src/shared/constants/providers.ts` ውስጥ ያክሉ።
2. `BaseExecutor`ን የሚያስፋፋ `open-sse/executors/{name}.ts` ይፍጠሩ። በእያንዳንዱ ጥያቄ ወደቡን እና
የAPI ቁልፉን እንደገና ይፈልጉ (በconstructor ውስጥ በፍጹም cache አያድርጉ)። የsupervisor ሁኔታ `"running"` ካልሆነ
`503 service_not_running` ምላሽ ይመልሱ።
3. ሞዴሎችን በአገልግሎቱ ቅድመ ቅጥያ (ለምሳሌ፣ `myservice/sub/model`) በ`open-sse/config/providerRegistry.ts` ውስጥ
ይመዝግቡ። `modelSync.ts` ወቅታዊ እንዲሆኑ ያደርጋቸዋል።
### ደረጃ 8 — ሰነድ ያዘጋጁ እና ይፈትሹ
1. `docs/frameworks/EMBEDDED-SERVICES.md`ን (ይህን ፋይል) ያዘምኑ — አገልግሎቱን በ§1 ውስጥ ወዳለው
ሰንጠረዥ እና ማንኛቸውንም አዲስ መጨረሻ ነጥቦች ወደ §4 ያክሉ።
2. በ`tests/unit/services/` ውስጥ የክፍል ሙከራዎችን (የሕይወት ዑደት፣ ጫኚ፣ የAPI ቅርጽ) ያክሉ።
3. በ`tests/integration/services/` ውስጥ የውህደት ሙከራ ያክሉ (በ`RUN_SERVICES_INT=1` የተገደበ)።
4. `docs/openapi.yaml`ን በአዲሶቹ መጨረሻ ነጥቦች ያዘምኑ።
---
## 7. መላ ፍለጋ
### አገልግሎቱ አይጀምርም
**ምልክቶች፦** የመጀመሪያ አዝራሩ 503 ይመልሳል፣ ሁኔታውም `"error"` ወይም `"starting"` ላይ ይቆያል።
**የማረጋገጫ ዝርዝር፦**
1. `GET /api/services/{name}/logs`ን (ወይም በዳሽቦርዱ ውስጥ ያለውን Logs ፓነል) ይፈትሹ።
እንደ `Error: ENOENT`፣ `address already in use` ወይም `Cannot find module` ያሉ መስመሮችን ይፈልጉ።
2. `npm` በPATH ውስጥ መኖሩን ያረጋግጡ፦ OmniRouteን ከሚያስኬደው ተመሳሳይ የተጠቃሚ መለያ `which npm`ን ያስኪዱ።
3. አገልግሎቱ መጫኑን ያረጋግጡ፦ `installedVersion`ን ለማየት
`GET /api/services/{name}/status`ን ይፈትሹ። `null` ከሆነ፣ መጀመሪያ ጭነቱን ያስኪዱ።
4. `DATA_DIR/services/{name}/node_modules/` መኖሩንና ባዶ አለመሆኑን ያረጋግጡ።
5. የተጣራውን የመውጫ ምክንያት ለማየት በሁኔታ ምላሹ ውስጥ ያለውን `lastError` መስክ ይፈትሹ።
---
### ከቀዝቃዛ ሁኔታ መጀመር ዘገምተኛ ነው (`running` ለመድረስ > 10 ሰከንድ)
**ምልክቶች፦** ሁኔታው ወደ `"running"` ወይም `"error"` ከመሄዱ በፊት ለረጅም ጊዜ `"starting"` ላይ ይቆያል።
**ማብራሪያ፦** የ9Router ከቀዝቃዛ ሁኔታ መጀመር ትላልቅ የጥገኝነት ዛፎችን (DNS፣
tunnel፣ MITM ሞጁሎች) ማስገባትን ያካትታል። ነባሪው የጤና ምርመራ ክፍተት 2 ሰከንድ ሲሆን፣
ተቆጣጣሪው ጊዜው እንዳለፈ ከማወጁ በፊት 3 ጊዜ ይሞክራል (ነገር ግን ሁኔታውን መጠየቁን ይቀጥላል)።
**መፍትሔ፦** `healthIntervalMs` እና የ`waitForHealthy` የጊዜ ገደብ
(`healthIntervalMs * 3`) በ`bootstrap.ts` ውስጥ ሊዋቀሩ ይችላሉ። ለመጀመር ረዘም ያለ
ጊዜ ለሚያስፈልጋቸው አገልግሎቶች፣ `healthIntervalMs`ን ወደ 5000 እና `stopTimeoutMs`ን ወደ 30 000 ያሳድጉ።
---
### የፖርት ግጭት (`EADDRINUSE`)
**ምልክቶች፦** ሎጎቹ `address already in use :::20130`ን ያሳያሉ።
**ምክንያቶች፦**
- ሌላ ሂደት ፖርት 20130ን አስቀድሞ እየተጠቀመ ነው።
- የቀድሞው የ9Router ሂደት ሙሉ በሙሉ አልቆመም (ዞምቢ PID)።
**መፍትሔ፦**
1. በ`.env` ውስጥ ባለው `NINEROUTER_PORT` የአካባቢ ተለዋዋጭ አማካኝነት ነባሪውን ፖርት ይቀይሩ።
2. ግጭቱን የሚፈጥረውን ሂደት ፈልገው ያቁሙ፦ `lsof -ti :20130 | xargs kill -9`።
3. ፖርቱ በ`bootstrap.ts` ውስጥ ባለው `port` መስክ አማካኝነት ለእያንዳንዱ አገልግሎት ሊዋቀር ይችላል።
**ማስታወሻ፦** 9Router ከOmniRoute ነባሪ ፖርት 20128 ጋር እንዳይጋጭ
በተለይ ፖርት 20130ን እንደ ነባሪ ይጠቀማል።
---
### በሚጫንበት ጊዜ ፈቃድ ተከልክሏል (EACCES)
**ምልክቶች፦** ጭነቱ 500 ይመልሳል፣ ሎጎቹም `EACCES` ወይም `permission denied`ን ያሳያሉ።
**ምክንያቶች፦**
- `DATA_DIR` ወይም ወላጅ ማውጫው በOmniRoute ሂደት ሊጻፍበት አይችልም።
- ከተያያዘው ቮልዩም ላይ የመጻፍ ፍቃድ ሳይኖር Dockerን rootless በሆነ ሁኔታ ማስኬድ።
**መፍትሔ፦**
1. `DATA_DIR`ን (ነባሪ፦ `~/.omniroute/`) ይፈትሹ፦ `ls -la ~/.omniroute/`
2. የOmniRoute ሂደቱ ተጠቃሚ የማውጫው ባለቤት መሆኑን ያረጋግጡ፦ `chown -R $USER ~/.omniroute/`
3. በDocker ውስጥ፣ የቮልዩም ማያያዣው ለኮንቴይነሩ ተጠቃሚ ትክክለኛ ፍቃዶች እንዳሉት ያረጋግጡ።
---
### ማዘመን አልተሳካም (`npm install` የጊዜ ገደብ ማለፍ ወይም የአውታረ መረብ ስህተት)
**ምልክቶች፦** ማዘመኑ `InstallError`ን የያዘ 500 ይመልሳል፣ ሎጎቹም የአውታረ መረብ የጊዜ ገደብ ማለፍን ያሳያሉ።
**የማረጋገጫ ዝርዝር፦**
1. npm registry ተደራሽ መሆኑን ያረጋግጡ፦ `npm ping`።
2. የድርጅት proxy መኖሩን ይፈትሹ፦ `npm config get proxy`፣ `npm config get https-proxy`።
3. ጭነቱን በእጅ ይሞክሩ፦ `npm install {package}@latest --prefix ~/.omniroute/services/{name}/`።
4. ከአውታረ መረብ በተገለለ አካባቢ ከሆኑ፣ tarballን አስቀድመው ያውርዱና `npm install /path/to/tarball.tgz`ን ይጠቀሙ።
---
### አገልግሎቱ ከተጀመረ በኋላ ወዲያውኑ `"error"` ሁኔታን ያሳያል (ፈጣን ብልሽት)
**ምልክቶች፦** ሁኔታው ከ5 ሰከንድ ባነሰ ጊዜ ውስጥ ከ`"starting"` ወደ `"error"` ይቀየራል።
`lastError` `"Fast crash (exited with code 1)"`ን ያሳያል።
**የማረጋገጫ ዝርዝር፦**
1. የሎጉን ሙሉ የመጨረሻ ክፍል ያንብቡ፦ `GET /api/services/{name}/logs?tail=500`።
2. የተለመደ ምክንያት፦ አገልግሎቱ የሚጠብቃቸው የአካባቢ ተለዋዋጮች አለመኖር።
3. ለ9Router፦ `NINEROUTER_DISABLE_MITM=true` እና
`NINEROUTER_DISABLE_TUNNEL=true` ሂደቱ ሲጀመር በሚተላለፈው አካባቢ ውስጥ መኖራቸውን ያረጋግጡ (`installers/ninerouter.ts` ውስጥ ያለውን `resolveSpawnArgs` ይመልከቱ)።
---
## 8. ተደጋግመው የሚጠየቁ ጥያቄዎች
**ጥያቄ፦ የተካተቱትን የአገልግሎት መዳረሻዎች ለloopback ያልሆኑ ደንበኞች ማጋለጥ እችላለሁ?**
አይ። የLOCAL_ONLY ደረጃ ሆን ተብሎ የተቀየሰ ነው (ጥብቅ ደንብ #17)።
`npm install`ን ማስኬድ ወይም የ`node` ሂደቶችን መጀመር የሚችሉ መንገዶች
ከloopback ያልሆነ ትራፊክ ተደራሽ መሆን የለባቸውም፤ ምክንያቱም በመሿለኪያ
(Cloudflare, Ngrok, Tailscale) በኩል የወጣ JWT፣ ያለዚያ ማንኛውንም ሂደት
እንዲጀመር ይፈቅዳል። ለ`/api/services/` ከዚህ ደንብ ለመውጣት ምንም
ልዩ ሁኔታ የለም — ከ`/api/mcp/` በተለየ፣ ከmanage-scope ማለፊያ
ዝርዝር ውጭ ነው። `docs/security/ROUTE_GUARD_TIERS.md`ን ይመልከቱ።
---
**ጥያቄ፦ 9Router እና CLIProxyAPI በproduction/cloud ማሰማራቶች ውስጥ ይገኛሉ?**
አዎ። ሁለቱም አገልግሎቶች እንደ OmniRoute ራሱ በአካባቢያዊ አጠቃቀም ቅድሚያ
የሚሰጥ ሞዴልን ይከተላሉ። በተመሳሳዩ ማሽን ላይ ይሰራሉ እና በloopback
በኩል ይገናኛሉ። እዚህ ላይ "Production" ማለት OmniRoute የተሰማራበትን
VPS ወይም አካባቢያዊ ሰርቨር እንጂ የርቀት cloud አቅራቢን አይደለም።
---
**ጥያቄ፦ supervisorን እንዴት ነው ስህተት የምፈልግበት?**
1. የSSE ምዝግብ ዥረቱን ይከታተሉ፦ `curl -N http://localhost:20128/api/services/9router/logs`።
2. በ`service:supervisor` namespace የተጣሩትን በOmniRoute pino ውጤት ውስጥ
ያሉ የተዋቀሩ ምዝግቦች ያረጋግጡ።
3. የDB ረድፉን ይመርምሩ፦ `sqlite3 ~/.omniroute/omniroute.db "SELECT * FROM version_manager WHERE tool='9router'"`።
4. የአሁኑን ቀጥታ ሁኔታ፣ PID፣ ጤና እና `lastError`ን በአንድ ጥሪ
ለማየት `GET /api/services/9router/status`ን ይጠቀሙ።
---
**ጥያቄ፦ supervisor `health: "degraded"` ወይም `health: "unknown"` ያሳያል፣ ነገር ግን ሁኔታው `"running"` ነው። ይህ ችግር ነው?**
`"degraded"` ማለት የጤና ምርመራው 200 ያልሆነ ምላሽ መልሷል ማለት ነው።
`"unknown"` ማለት እስካሁን ምንም ምርመራ አልተጠናቀቀም ማለት ነው
(ከመጀመሪያው ምርመራ ጋር ያለ የጊዜ ውድድር)። ሁለቱም በመነሻ ጊዜ
ጊዜያዊ ናቸው። ከ`"running"` በኋላ ከ`healthIntervalMs * 3` ms በላይ
ጤናው `"degraded"` ሆኖ ከቀጠለ፣ የተካተተው አገልግሎት እየሰራ ነው፣
ነገር ግን HTTP APIው ምላሽ እየሰጠ አይደለም። በሁኔታ ምላሹ ውስጥ
portን ትክክል መሆኑን እና አገልግሎቱ በእርግጥ በዚያ port ላይ እያዳመጠ
መሆኑን ያረጋግጡ።
---
**ጥያቄ፦ ሙሉ በሙሉ ዳግም ሳላስጀምር የ9Router API ቁልፍን መቀየር እችላለሁ?**
አይ። API ቁልፉ ሂደቱ በሚጀመርበት ጊዜ በenvironment variable በኩል ወደ
9Router ይተላለፋል። Environment variables በሚሰራ ሂደት ውስጥ ሊቀየሩ
አይችሉም። `POST .../rotate-key` አዲሱን ቁልፍ ተግባራዊ ለማድረግ አገልግሎቱን
በራስ-ሰር ያቆማል እና ዳግም ያስጀምራል። የቁልፉ ማዞር በአገልግሎቱ
`stopTimeoutMs` (ነባሪው 15 s) እና በመነሻ ጊዜው ድምር ውስጥ ተግባራዊ
ይሆናል።
---
**ጥያቄ፦ የring buffer ገደቡ ስንት ነው፣ ሲሞላስ ምን ይከሰታል?**
እያንዳንዱ አገልግሎት ራሱን የቻለ 5 MB ring buffer አለው። buffer ሲሞላ፣
ለአዳዲስ የምዝግብ መስመሮች ቦታ ለመስጠት ከሁሉም የቆዩት የምዝግብ
መስመሮች ይወገዳሉ። የSSE `snapshot` ክስተት በ`tail` ገደብ ውስጥ ያሉትን
በጣም የቅርብ ጊዜ መስመሮች ይመልሳል። `logsBufferPath` በDB ረድፍ ውስጥ
ካልተዋቀረ በስተቀር ምዝግቦች በዲስክ ላይ አይቀመጡም።
---
## በተጨማሪ ይመልከቱ
- `docs/security/ROUTE_GUARD_TIERS.md` — የLOCAL_ONLY ደረጃ ዝርዝሮች
- `docs/architecture/CODEBASE_DOCUMENTATION.md` — §3.2 የተካተቱ አገልግሎቶች ሞጁል የካርታ ስራ
- `docs/architecture/ARCHITECTURE.md` — የስርዓት ደረጃ አውድ
- `docs/openapi.yaml` — በማሽን የሚነበቡ የመዳረሻ ትርጓሜዎች
- `CLAUDE.md` §"አዲስ የተካተተ አገልግሎት ማከል" — የፈጣን ማጣቀሻ ማረጋገጫ ዝርዝር

237
docs/i18n/am/docs/frameworks/EVALS.md Normal file
View File

@@ -0,0 +1,237 @@
# Evaluations (Evals) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/EVALS.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/EVALS.md) · 🇦🇿 [az](../../../az/docs/frameworks/EVALS.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/EVALS.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/EVALS.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/EVALS.md) · 🇩🇰 [da](../../../da/docs/frameworks/EVALS.md) · 🇩🇪 [de](../../../de/docs/frameworks/EVALS.md) · 🇬🇷 [el](../../../el/docs/frameworks/EVALS.md) · 🇪🇸 [es](../../../es/docs/frameworks/EVALS.md) · 🇪🇪 [et](../../../et/docs/frameworks/EVALS.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/EVALS.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/EVALS.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/EVALS.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/EVALS.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/EVALS.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/EVALS.md) · 🇮🇱 [he](../../../he/docs/frameworks/EVALS.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/EVALS.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/EVALS.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/EVALS.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/EVALS.md) · 🇮🇩 [id](../../../id/docs/frameworks/EVALS.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/EVALS.md) · 🇮🇹 [it](../../../it/docs/frameworks/EVALS.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/EVALS.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/EVALS.md) · 🇰🇭 [km](../../../km/docs/frameworks/EVALS.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/EVALS.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/EVALS.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/EVALS.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/EVALS.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/EVALS.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/EVALS.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/EVALS.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/EVALS.md) · 🇲🇲 [my](../../../my/docs/frameworks/EVALS.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/EVALS.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/EVALS.md) · 🇳🇴 [no](../../../no/docs/frameworks/EVALS.md) · 🇮🇳 [or](../../../or/docs/frameworks/EVALS.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/EVALS.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/EVALS.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/EVALS.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/EVALS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/EVALS.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/EVALS.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/EVALS.md) · 🇱🇰 [si](../../../si/docs/frameworks/EVALS.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/EVALS.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/EVALS.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/EVALS.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/EVALS.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/EVALS.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/EVALS.md) · 🇮🇳 [te](../../../te/docs/frameworks/EVALS.md) · 🇹🇭 [th](../../../th/docs/frameworks/EVALS.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/EVALS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/EVALS.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/EVALS.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/EVALS.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/EVALS.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/EVALS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/EVALS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/EVALS.md)
---
> **ዋና የእውነት ምንጭ:** `src/lib/evals/`, `src/lib/db/evals.ts`, `src/app/api/evals/`
> **ለመጨረሻ ጊዜ የዘመነው:** 2026-06-28 — v3.8.40
OmniRoute የማዞሪያ ውቅሮችን፣ ነጠላ አቅራቢዎችን/ሞዴሎችን ወይም አብረው የቀረቡትን "golden set" ስብስቦች ለማነጻጸሪያ መለኪያነት ሊጠቀሙበት የሚችሉ አጠቃላይ የግምገማ ማዕቀፍ ይዞ ይመጣል።
የማዞሪያ ለውጦችን ለማረጋገጥ፣ አዲስ አቅራቢዎችን ለማፅደቅ እና ወደ ምርት ትራፊክ ከማስተላለፍ በፊት ልቀቶችን ለመቆጣጠር ይጠቀሙበት።
ማዕቀፉ በሚከተለው መልኩ ተተግብሯል፦
- በማህደረ ትውስታ ውስጥ የተካተቱ አብሮገነብ ስብስቦችን የሚመዘግብ፣ ውጤቶችን ከሚጠበቁ መስፈርቶች አንጻር የሚገመግም እና የውጤት ሰሌዳዎችን የሚያጠቃልል ንጹህ አስኪያጅ (`src/lib/evals/evalRunner.ts`)።
- ለብጁ (በተጠቃሚ የተገለጹ) ስብስቦች እና በSQLite ውስጥ ለታሪካዊ አሂያጆች የማከማቻ ንብርብር (`src/lib/db/evals.ts`)።
- እውነተኛ ጥሪዎችን ወደ `POST /v1/chat/completions` በመላክ እያንዳንዱን ጉዳይ የሚያስፈጽም፣ የምላሽ ጊዜን እና ውጤቶችን የሚመዘግብ እንዲሁም አሂያጁን የሚያከማች የማቀናበሪያ ንብርብር (`src/lib/evals/runtime.ts`)።
- በ`/api/evals/*` ስር ያሉ REST የመዳረሻ ነጥቦች (የአስተዳደር ማረጋገጫ ብቻ)።
- በ`Dashboard → Usage → Evals` (`EvalsTab.tsx`) ላይ ያለ የዳሽቦርድ ገጽታ።
## ጽንሰ-ሐሳቦች
### ስብስብ
ስብስብ አንድ `description` እና አንድ ወይም ከዚያ በላይ ጉዳዮች ያሉት ስም የተሰጠው የሙከራ ጉዳዮች ስብስብ ነው። ስብስቦች ከሁለት ምንጮች ይመጣሉ፦
| ምንጭ | የተገለጸበት ቦታ | በአሂያጅ ጊዜ ሊለወጥ ይችላል? |
| ---------- | ---------------------------------------------- | ------------------- |
| `built-in` | በመነሻ ጊዜ በ`registerSuite()` በኩል ይመዘገባል | አይ (በኮድ የተገለጸ) |
| `custom` | በSQLite `eval_suites` + `eval_cases` ውስጥ ይከማቻል | አዎ (በAPI/UI በኩል) |
አሁን ያሉት አብሮገነብ ስብስቦች (`src/lib/evals/evalRunner.ts`ን ይመልከቱ)፦
- `golden-set` — በሰላምታ/ሒሳብ/ትርጉም/ደህንነት ዙሪያ 10 የመነሻ ጉዳዮች
- `coding-proficiency` — Python/JS/SQL/TS/የሳንካ ማወቂያ
- `reasoning-logic` — ሎጂካዊ ድምዳሜዎች፣ የቃላት ችግኞች፣ የንድፍ ማወቂያ
- `multilingual` — ትርጉም እና ቋንቋ መለየት
- `safety-guardrails` — PII፣ የደህንነት ገደብ ማለፊያ፣ እምቢታ፣ የአድሎ ግንዛቤ
- `instruction-following` — JSON ብቻ፣ ቁጥር የተሰጣቸው ዝርዝሮች፣ የቋንቋ ገደቦች
- `codex-comparison` — ለንጽጽር ሁነታ የታሰቡ ቀጥተኛ የኮድ ጽሕፈት ተግባራት
### ጉዳይ
እያንዳንዱ ጉዳይ የሚከተሉትን ይይዛል፦
| መስክ | መግለጫ |
| ---------- | ------------------------------------------------------------ |
| `id` | የማይለወጥ መለያ (ውጤቶችን እና መለኪያዎችን ለመፈለጊያ ቁልፍነት ይጠቅማል) |
| `name` | ሰው ሊያነበው የሚችል መለያ |
| `model` | አሂያጁ `suite-default` ዒላማን ሲጠቀም ነባሪ ሞዴል |
| `input` | `{ messages, max_tokens? }` — ወደ `/v1/chat/completions` ይላካል |
| `expected` | `{ strategy, value }` — የውጤት አሰጣጥ መመዘኛ (ከታች ይመልከቱ) |
| `tags` | አማራጭ መለያዎች (ለምሳሌ `safety`፣ `pii`፣ `jailbreak`) |
### ዒላማ
ተመሳሳዩ ስብስብ በተለያዩ ዒላማዎች ላይ ሊካሄድ ይችላል። የዒላማው መርሐግብር
በ`src/shared/validation/schemas.ts` ውስጥ `evalTargetSchema` ነው፦
| የዒላማ አይነት | `id` | ባህሪ |
| --------------- | --------- | ------------------------------------------------------- |
| `suite-default` | `null` | እያንዳንዱ ጉዳይ የራሱን አብሮገነብ `model` መስክ ይጠቀማል |
| `model` | የሞዴል ስም | እያንዳንዱን ጉዳይ በአንድ ቀጥተኛ ሞዴል በኩል በግድ ያስኬዳል (ለምሳሌ `gpt-4o`) |
| `combo` | የcombo ስም | እያንዳንዱን ጉዳይ በአንድ combo በኩል ያስኬዳል (የማዞሪያ ሞተሩን ይፈትሻል) |
ለ`model` እና `combo`፣ የ`id` መስክ ያስፈልጋል (በZod
`superRefine()` የሚተገበር)። `compareTarget` ሲቀርብ፣ ሁለቱም ዒላማዎች የተለያዩ መሆን አለባቸው —
አስኪያጁ ለA/B ንጽጽር ሁለቱንም አሂያጆች በተመሳሳይ `runGroupId` ስር ያከማቻል።
## የውጤት አሰጣጥ መመዘኛዎች
በ `evaluateCase()` (evalRunner.ts) ውስጥ ተተግብሯል፦
| ስልት | የሚያልፈው… |
| ---------- | ------------------------------------------------------------------- |
| `exact` | `actualOutput === expected.value` |
| `contains` | `actualOutput.toLowerCase().includes(expected.value.toLowerCase())` |
| `regex` | `new RegExp(expected.value).test(actualOutput)` እውነት ከሆነ |
| `custom` | `expected.fn(actualOutput, evalCase)` እውነት ከመለሰ (አብሮገነብ ብቻ) |
**ማስታወሻ፦** ፋንክሽኖች በAPI በኩል ተከታታይ ውሂብ ሆነው ሊቀመጡ ስለማይችሉ፣ በብጁ ፋንክሽን የሚደረግ የውጤት አሰጣጥ በኮድ ለተገለጹ (አብሮገነብ)
ስብስቦች ብቻ የተያዘ ነው። `evalCaseBuilderSchema` በተጠቃሚ ለተፈጠሩ
ስብስቦች `contains | exact | regex` ብቻ ይቀበላል።
በአሁኑ ጊዜ LLM-as-judge ወይም በembedding ላይ የተመሠረተ የተመሳሳይነት መለኪያ የለም — ይህ
በ `evaluateCase()` ውስጥ ግልጽ የማስፋፊያ ነጥብ ሊሆን ይችላል።
## የውሂብ ጎታ ንድፍ
ሦስት ሰንጠረዦች (ማይግሬሽኖች `030_create_eval_runs.sql` እና
`031_create_eval_suites.sql`)፦
| ሰንጠረዥ | ዓላማ |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `eval_suites` | የብጁ ስብስብ ሜታዳታ (`id`, `name`, `description`) |
| `eval_cases` | በየስብስቡ ያሉ ጉዳዮች — `input_json`, `expected_*`, `tags_json` |
| `eval_runs` | ታሪካዊ አሂዶች — `pass_rate`, `total`, `passed`, `failed`, `avg_latency_ms`, `summary_json`, `results_json`, `outputs_json` |
አብሮገነብ ስብስቦች በDB ውስጥ **አይቀመጡም**። በማህደረ ትውስታ ውስጥ ይኖራሉ፣ እና
`evalRunner.ts` በገባ ቁጥር እንደገና ይመዘገባሉ።
## REST API
ሁሉም መዳረሻዎች የአስተዳደር ማረጋገጫ (`requireManagementAuth`) ያስፈልጋቸዋል — የሕዝብ
ፕሮክሲ በይነገጽ አካል አይደሉም።
| መዳረሻ | ዘዴ | መግለጫ |
| ----------------------------- | -------- | -------------------------------------------------------- |
| `/api/evals` | `GET` | ስብስቦችን + የቅርብ ጊዜ አሂዶችን + የውጤት ሰሌዳን + ዒላማዎችን + ቁልፎችን ዘርዝር |
| `/api/evals` | `POST` | ስብስብን አስኪድ (ነጠላ ወይም ንጽጽር) — ንድፍ `evalRunSuiteSchema` |
| `/api/evals/{suiteId}` | `GET` | አንድ ስብስብ አምጣ (አብሮገነብ ወይም ብጁ) |
| `/api/evals/suites` | `POST` | ብጁ ስብስብ ፍጠር — ንድፍ `evalSuiteSaveSchema` |
| `/api/evals/suites/{suiteId}` | `GET` | ብጁ ስብስብ አምጣ |
| `/api/evals/suites/{suiteId}` | `PUT` | ብጁ ስብስብን ተካ (ጉዳዮቹ እንደገና ይገባሉ) |
| `/api/evals/suites/{suiteId}` | `DELETE` | ብጁ ስብስብን እና ጉዳዮቹን ሰርዝ |
### ስብስብን ማስኬድ
```bash
curl -X POST http://localhost:20128/api/evals \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{
"suiteId": "golden-set",
"target": { "type": "combo", "id": "my-combo" },
"apiKeyId": "optional-api-key-uuid"
}'
```
አማራጭ መስኮች፦
- `outputs` — አስቀድሞ የተሰሉ ውጤቶች `Record<caseId, string>`። ሲቀርብ፣
አስኪያጁ **መላኩን ይዘላል** እና የተሸጎጡትን ውጤቶች ብቻ ይመዝናል (ከመስመር ውጭ
ለሚደረግ ግምገማ ጠቃሚ ነው)።
- `compareTarget` — በትይዩ የሚካሄድ ሁለተኛ ዒላማ፤ ሁለቱም አሂዶች ጎን ለጎን ለማየት
የተፈጠረ `runGroupId` ይጋራሉ።
- `apiKeyId` — የሚላኩትን `/v1/chat/completions` ጥሪዎች ለማረጋገጥ የሚያገለግል
ውስጣዊ API ቁልፍ። `REQUIRE_API_KEY` ሲነቃ ያስፈልጋል።
### ብጁ ስብስብ መፍጠር
```bash
curl -X POST http://localhost:20128/api/evals/suites \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production smoke",
"description": "Quick sanity check before deploy",
"cases": [
{
"name": "JSON shape",
"model": "gpt-4o",
"input": { "messages": [{ "role": "user", "content": "Reply with {\"ok\": true}" }] },
"expected": { "strategy": "regex", "value": "\"ok\"\\s*:\\s*true" }
}
]
}'
```
## የማስተላለፊያ ፓይፕላይን
`runEvalSuiteAgainstTarget()` (`src/lib/evals/runtime.ts`)፦
1. ስብስቡን (አብሮገነብ ወይም ብጁ) ይወስናል።
2. ለእያንዳንዱ ኬዝ፣ የኬዙን `messages`፣ የተወሰነውን `model`፣ `stream: false` እና `max_tokens: 512`
(ወይም በኬዙ የተተካውን እሴት) በመጠቀም ወደ `/v1/chat/completions` የሚላክ `Request` ይገነባል።
3. የውይይት አስተናጋጁን በቀጥታ ይጠራል (በሂደቱ ውስጥ — ተጨማሪ የHTTP ዝላይ የለም)።
4. መዘግየትን ይመዘግባል እና ጽሑፍን ከ`choices[0].message.content`
ወይም ከResponses-API `output[]` ጭነት ያወጣል።
5. ሁሉንም ውጤቶች በ`runSuite()` ደረጃ ይሰጣል፣ ከዚያም በ`saveEvalRun()` ያስቀምጣቸዋል።
ኬዞች **በቅደም ተከተል** ይከናወናሉ። በአሁኑ ጊዜ የትይዩነት ጠቋሚ የለም።
## ዳሽቦርድ
የተጠቃሚ በይነገጹ በ`Dashboard → Usage → Evals`
(`src/app/(dashboard)/dashboard/usage/components/EvalsTab.tsx`) ይገኛል። ከዚያ የሚከተሉትን
ማድረግ ይችላሉ፦
- አብሮገነብ እና ብጁ ስብስቦችን በእያንዳንዱ ኬዝ ቅድመ ዕይታ ማሰስ።
- በኬዝ መገንቢያው ብጁ ስብስቦችን መፍጠር/ማርትዕ/መሰረዝ።
- ዒላማ (የስብስብ ነባሪዎች / ሞዴል / ጥምረት) መምረጥ፣ እንደ አማራጭ ሁለተኛ
`compareTarget` እና API ቁልፍ መምረጥ፣ ከዚያም በፍላጎት ማስኬድ።
- የማስኬድ ታሪክን፣ በእያንዳንዱ ኬዝ ማለፍ/መውደቅን፣ መዘግየትን እና የተመዘገቡ ውጤቶችን መመርመር።
- በእያንዳንዱ `(suite, target)` ወሰን ውስጥ ካለው የቅርብ ጊዜ ማስኬድ የተጠቃለለውን ተንከባላይ የውጤት ሰሌዳ ማየት።
## ከAuto-Assessment RFC ጋር ያለው ግንኙነት
የተለየና ይበልጥ የተወሰነ የግምገማ ንዑስ ስርዓት በ`src/domain/assessment/`
ውስጥ ይገኛል (ለቀጥታ የውጤት አሰጣጥ ሞተሩ [AUTO-COMBO.md](../routing/AUTO-COMBO.md)ንም ይመልከቱ)።
ያ ንዑስ ስርዓት የAuto Combo ሞተሩን ዒላማ ያደርጋል — የላይኛው ምንጭ ሲበላሽ ጥምረቶች ራሳቸውን
እንዲጠግኑ አቅራቢዎችን እና ሞዴሎችን በራስ-ሰር ደረጃ ይሰጣል። የራሱን ማስኬጃ፣
የራሱን መደብ መዳቢ እና የራሱን የውጤት አሰጣጥ አመክንዮ ይጠቀማል።
እዚህ የተዘገበው የEvals ማዕቀፍ **ሰፋ ያለ፣ አጠቃላይ ዓላማ ያለው
የሙከራ ገጽታ** ነው። ለማናቸውም የድግግሞሽ ስህተት ሙከራ ስብስቦች፣ የA/B ንጽጽሮች
እና የእያንዳንዱ ልቀት መሰረታዊ ሙከራዎች ይህን ይምረጡ። ቅጽበታዊ የአቅራቢ ጤና
የማዘዋወር ውሳኔዎችን እንዲያሳድር ሲፈልጉ የAuto-Assessment ንዑስ ስርዓትን ይጠቀሙ።
## የCI ውህደት
በአሁኑ ጊዜ የተለየ `eval:ci` npm ስክሪፕት የለም። ልቀቶችን በግምገማ ውጤቶች ላይ
ተመስርተው እንዲያልፉ ከፈለጉ ሁለት መንገዶች አሉ፦
- **የHTTP መንገድ**፦ ሰርቨሩን ያስነሱ፣ የታወቀ `suiteId` + `target` በመጠቀም
`POST /api/evals`ን ይጠሩ እና በምላሹ ውስጥ `runs[].summary.passRate >= N` መሆኑን
ያረጋግጡ።
- **በሂደት ውስጥ የሚከናወን መንገድ**፦ በስክሪፕት ውስጥ `runEvalSuiteAgainstTarget()`ን
ከ`@/lib/evals/runtime` ያስመጡ፣ በሙከራ DB ላይ ያስኪዱ እና የተመለሰውን
`PersistedEvalRun.summary` ይፈትሹ።
መስመሩን እና ታሪኩን የሚሸፍኑ ሙከራዎች በ
`tests/unit/evals-route.test.ts` እና `tests/unit/evals-history.test.ts` ይገኛሉ።
## የማስፋፊያ ነጥቦች
የተለመዱ ለውጦች እና ለውጦቹን የሚያደርጉባቸው ቦታዎች፦
- **አዲስ የውጤት አሰጣጥ ስልት** — በ`evaluateCase()` (`evalRunner.ts`) ውስጥ ያለውን
`switch (evalCase.expected.strategy)` ብሎክ ያስፋፉ እና በ
`src/lib/db/evals.ts` ውስጥ `EvalCaseStrategy`ን፣ እንዲሁም በ`schemas.ts` ውስጥ
`evalCaseBuilderSchema`ን ያስፉ።
- **አዲስ አብሮገነብ ስብስብ** — የስብስብ ኦብጀክት ይግለጹ እና በ
`evalRunner.ts` ግርጌ `registerSuite()`ን ይጥሩ። በ`listSuites()` በራስ-ሰር ይገኛል።
- **በትይዩነት ማስኬድ** — በ`runEvalSuiteAgainstTarget()` ውስጥ ያለውን ተከታታይ `for` ሉፕ
ወደ የተገደበ `Promise.all` ይቀይሩ (በአሁኑ ጊዜ የትይዩነት መቆጣጠሪያ የለም)።
- **የዥረት/የመሣሪያ-ጥሪ ኬዞች** — በአሁኑ ጊዜ ማስኬጃው `stream: false`ን በግድ ይጠቀማል።
የዥረት ወይም መሣሪያን የሚያውቅ ግምገማ በ`runtime.ts` ውስጥ ለውጦችን ይፈልጋል
(ውጤት ከመስጠት በፊት የSSE ቁርጥራጮችን መመዝገብ እና ማጠቃለል)።
## በተጨማሪ ይመልከቱ
- [USER_GUIDE.md](../guides/USER_GUIDE.md) — የምርቱ አጠቃላይ አጠቃቀም መመሪያ
- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — የጥያቄ ሂደት ማጣቀሻ
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — የAuto Combo የውጤት አሰጣጥ ሞተር (በቀጥታ የሚሰራ)
- ምንጭ፦ `src/lib/evals/`፣ `src/lib/db/evals.ts`፣ `src/app/api/evals/`
- የተጠቃሚ በይነገጽ፦ `src/app/(dashboard)/dashboard/usage/components/EvalsTab.tsx`

1060
docs/i18n/am/docs/frameworks/GAMIFICATION.md Normal file
View File

File diff suppressed because it is too large Load Diff

76
docs/i18n/am/docs/frameworks/LOCAL_CORPUS_CONTEXT.md Normal file
View File

@@ -0,0 +1,76 @@
# Local Corpus Context Source (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇦🇿 [az](../../../az/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇩🇰 [da](../../../da/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇩🇪 [de](../../../de/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇬🇷 [el](../../../el/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇪🇸 [es](../../../es/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇪🇪 [et](../../../et/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇱 [he](../../../he/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇩 [id](../../../id/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇹 [it](../../../it/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇰🇭 [km](../../../km/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇲🇲 [my](../../../my/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇳🇴 [no](../../../no/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [or](../../../or/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇱🇰 [si](../../../si/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇮🇳 [te](../../../te/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇹🇭 [th](../../../th/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/LOCAL_CORPUS_CONTEXT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/LOCAL_CORPUS_CONTEXT.md)
---
> **ዋና የእውነት ምንጭ:** `src/lib/localCorpus/index.ts` (የተገደበ የጽሑፍ ማውጫ),
> `src/lib/localCorpus/configured.ts` (የተዋቀረ የአሂድ ጊዜ),
> `src/lib/db/localCorpus.ts` (የስር ዱካ ቋሚ ማከማቻ),
> `open-sse/mcp-server/tools/localCorpusTools.ts` (3 ለንባብ ብቻ የሆኑ MCP መሳሪያዎች), እና
> `src/app/api/settings/local-corpus/route.ts` (የቅንብሮች API)።
## ምንድን ነው
Local Corpus አንድ አስተዳዳሪ በግልጽ የተፈቀደ የጽሑፍ ፋይሎች ማውጫን ለOmniRoute MCP አገልጋይ እንዲያቀርብ ያስችለዋል። ፋይሎቹ በመጀመሪያው ማውጫቸው ውስጥ ይቆያሉ፦ OmniRoute በSQLite ውስጥ የሚያከማቸው መደበኛውን የስር ዱካ ብቻ ሲሆን፣ በማህደረ ትውስታ ውስጥ ያለ የፍለጋ ማውጫን ይጠብቃል። የኮርፐስ ይዘትን ወደ ማከማቻው ወይም ዳታቤዙ አይቀዳም።
የማውጫው እድሳት ደረጃ በደረጃ የሚከናወን ነው። ያልተለወጡ ፋይሎች በመጠንና በተሻሻሉበት ጊዜ መሠረት እንደገና ጥቅም ላይ ይውላሉ፤ የተለወጡ ፋይሎች እንደገና ተነበው በSHA-256 ሃሽ ይደረጋሉ፣ የተሰረዙ ፋይሎችም ይወገዳሉ። ፍለጋ ከ30 ሰከንድ በላይ ያረጀ ማውጫን ያድሳል፤ ጠሪዎችም አፋጣኝ እድሳት ሊጠይቁ ይችላሉ።
## ምንጩን ማዋቀር
የቅንብሮች መስመሩ እንደሌሎች የቅንብሮች APIዎች ተመሳሳይ የአስተዳደር ማረጋገጫ ይፈልጋል። የሚላከው ዱካ አስቀድሞ ያለ መሆን እና ፍጹም የማውጫ ዱካ መሆን አለበት።
```bash
# የተፈቀደ ማውጫን ያገናኙ
curl -X POST http://localhost:20128/api/settings/local-corpus \
-H "Content-Type: application/json" \
-d '{"rootPath":"/absolute/path/to/approved-text"}'
# ውቅሩን እና የማውጫውን ሁኔታ ያረጋግጡ
curl http://localhost:20128/api/settings/local-corpus
# የምንጭ ፋይሎችን ሳይቀይሩ ያላቅቁ
curl -X DELETE http://localhost:20128/api/settings/local-corpus
```
## MCP መሳሪያዎች
ሦስቱም መሳሪያዎች `read:local-corpus` ይፈልጋሉ። የመሳሪያዎቹ ምላሾች አንጻራዊ ዱካዎችን እና የስር ማውጫውን መሠረታዊ ስም ያሳያሉ፤ ፍጹም ዱካውን ፈጽሞ አያሳዩም።
| መሳሪያ | መግለጫ |
| :-------------------- | :---------------------------------------------------------------------- |
| `local_corpus_status` | የውቅር ሁኔታን፣ የማውጫውን መጠን፣ ገደቦችን እና የመጨረሻውን የእድሳት ጊዜ ያሳውቃል |
| `local_corpus_search` | በማውጫ የተመዘገበ ጽሑፍን ይፈልጋል እና የተገደቡ፣ በመስመር የተወሰኑ ቅንጭቦችን ይመልሳል (እስከ 20 ውጤቶች) |
| `local_corpus_read` | ከአንድ ከተፈቀደ የኮርፐስ-አንጻራዊ ፋይል የተገደበ የመስመር ክልል ያነባል |
የMCP ግብዓቶች ምሳሌ፦
```json
{ "query": "Red River monitoring", "limit": 10, "refresh": false }
```
```json
{ "relativePath": "hydrology/stations.md", "startLine": 20, "endLine": 80 }
```
## የደህንነት ወሰኖች
- የፈቃድ ዝርዝሩ በጽሑፍ ላይ ያተኮረ ነው፦ `.cfg`፣ `.csv`፣ `.geojson`፣ `.htm`፣ `.html`፣ `.ini`፣
`.js`፣ `.json`፣ `.jsonl`፣ `.jsx`፣ `.log`፣ `.md`፣ `.mjs`፣ `.ps1`፣ `.py`፣ `.sh`፣
`.sql`፣ `.toml`፣ `.ts`፣ `.tsx`፣ `.txt`፣ `.xml`፣ `.yaml`፣ እና `.yml`።
- ምልክታዊ አገናኞች ይታለፋሉ። የንባብ ዱካዎች መደበኛ ይደረጋሉ እና በተዋቀረው ስር ውስጥ መቆየት አለባቸው፤ ፍጹም ዱካዎችና የማውጫ ወሰን ለማለፍ የሚደረጉ ሙከራዎች ውድቅ ይደረጋሉ።
- ስሱ እና በራስ-ሰር የሚፈጠሩ የማውጫ ስሞች አይካተቱም፦ `.build`፣ `.codex`፣ `.env`፣
`.git`፣ `.next`፣ `.omniroute`፣ `.ssh`፣ `coverage`፣ `dist`፣ `node_modules`፣ እና
`secrets`።
- ነባሪ ገደቦቹ 5,000 ፋይሎች፣ ለእያንዳንዱ ፋይል 1 MiB፣ በጠቅላላ 64 MiB በማውጫ የተመዘገበ ይዘት፣ ለእያንዳንዱ የፍለጋ ቅንጭብ በግምት 4,000 ቁምፊዎች፣ እና ለእያንዳንዱ ንባብ 400 መስመሮች ናቸው።
- NUL የያዙ ፋይሎች ጽሑፍ እንዳልሆኑ ተቆጥረው ይታለፋሉ ወይም ውድቅ ይደረጋሉ።
እንደ PDF፣ DOCX፣ ምስሎች እና መዝገቦች ያሉ ሁለትዮሽ ሰነዶች ሆን ተብለው አይደገፉም። በማውጫ ከመመዝገባቸው በፊት በተዋቀረው ማውጫ ውስጥ ወደተፈቀደ የጽሑፍ ቅርጸት ይቀይሯቸው።
## የአሠራር ማስታወሻዎች
- የተዋቀረውን ስር መቀየር ወይም መሰረዝ የጋራውን በማህደረ ትውስታ ውስጥ ያለ ማውጫ ያጸዳል።
- የሂደት ዳግም ማስጀመር ማውጫውን ያስወግዳል፤ ቀጣዩ ፍለጋ ከተዋቀረው ምንጭ እንደገና ይገነባዋል።
- `local_corpus_status` ቅኝትን አያስገድድም። አፋጣኝ ዳግም ቅኝት በሚያስፈልግበት ጊዜ `local_corpus_search`ን ከ
`refresh: true` ጋር ይጠቀሙ።
- የቅኝት እና የንባብ አለመሳካቶች ይቆጠራሉ ወይም የተጣሩ ስህተቶች ሆነው ይመለሳሉ፤ የምንጭ ፋይሎች ፈጽሞ አይሻሻሉም።

221
docs/i18n/am/docs/frameworks/LOG-EXPORT.md Normal file
View File

@@ -0,0 +1,221 @@
# Log export (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/LOG-EXPORT.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/LOG-EXPORT.md) · 🇦🇿 [az](../../../az/docs/frameworks/LOG-EXPORT.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/LOG-EXPORT.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/LOG-EXPORT.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/LOG-EXPORT.md) · 🇩🇰 [da](../../../da/docs/frameworks/LOG-EXPORT.md) · 🇩🇪 [de](../../../de/docs/frameworks/LOG-EXPORT.md) · 🇬🇷 [el](../../../el/docs/frameworks/LOG-EXPORT.md) · 🇪🇸 [es](../../../es/docs/frameworks/LOG-EXPORT.md) · 🇪🇪 [et](../../../et/docs/frameworks/LOG-EXPORT.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/LOG-EXPORT.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/LOG-EXPORT.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/LOG-EXPORT.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/LOG-EXPORT.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/LOG-EXPORT.md) · 🇮🇱 [he](../../../he/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/LOG-EXPORT.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/LOG-EXPORT.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/LOG-EXPORT.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/LOG-EXPORT.md) · 🇮🇩 [id](../../../id/docs/frameworks/LOG-EXPORT.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/LOG-EXPORT.md) · 🇮🇹 [it](../../../it/docs/frameworks/LOG-EXPORT.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/LOG-EXPORT.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/LOG-EXPORT.md) · 🇰🇭 [km](../../../km/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/LOG-EXPORT.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/LOG-EXPORT.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/LOG-EXPORT.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/LOG-EXPORT.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/LOG-EXPORT.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/LOG-EXPORT.md) · 🇲🇲 [my](../../../my/docs/frameworks/LOG-EXPORT.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/LOG-EXPORT.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/LOG-EXPORT.md) · 🇳🇴 [no](../../../no/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [or](../../../or/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/LOG-EXPORT.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/LOG-EXPORT.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/LOG-EXPORT.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/LOG-EXPORT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/LOG-EXPORT.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/LOG-EXPORT.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/LOG-EXPORT.md) · 🇱🇰 [si](../../../si/docs/frameworks/LOG-EXPORT.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/LOG-EXPORT.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/LOG-EXPORT.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/LOG-EXPORT.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/LOG-EXPORT.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/LOG-EXPORT.md) · 🇮🇳 [te](../../../te/docs/frameworks/LOG-EXPORT.md) · 🇹🇭 [th](../../../th/docs/frameworks/LOG-EXPORT.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/LOG-EXPORT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/LOG-EXPORT.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/LOG-EXPORT.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/LOG-EXPORT.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/LOG-EXPORT.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/LOG-EXPORT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/LOG-EXPORT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/LOG-EXPORT.md)
---
የOmniRoute ጥሪ ምዝግቦችን ወደ ውጫዊ የትንታኔ ማከማቻ በተከታታይ እና በየደረጃው መላክ።
የLogs ዳሽቦርድ ትር የጥያቄ ታሪክን በSQLite (`call_logs`) ውስጥ ያስቀምጣል፤ ይህም
በማዞር እና በማቆያ ፖሊሲ የተገደበ ነው። የምዝግብ መላክ ተመሳሳዩን የመዝገብ ስብስብ በጊዜ ሰሌዳ መሠረት
ወደ ውጭ ይልካል፤ በዚህም ከአካባቢያዊው የውሂብ ጎታ በላይ ለረጅም ጊዜ እንዲቆይ እና ከሌሎች ውሂቦች ጋር እንዲጣመር ያደርጋል። BigQuery የመጀመሪያው መድረሻ ነው፤
የማስኬጃ መስመሩ መዝገብ ቤት ስለሆነ፣ ተጨማሪ መድረሻዎችን መጨመር ይቻላል።
---
## 1. እንዴት እንደሚሠራ
```
call_logs (SQLite)
→ callLogExportSource.getCallLogsForExport(cursor, batchSize)
→ LogExportRecord[] (የLogs ትር የመስኮች ስብስብ)
→ destination client.send(batch)
→ advanceLogExportCursor(id, lastRowId, count)
```
- **የጊዜ ሰሌዳ** — አንድ `JobRegistry` cron ሥራ፣ `log_export`፣ ነባሪው `0 * * * *` (በየሰዓቱ፣
UTC) ነው። በ`src/lib/initCloudSync.ts` ውስጥ ይመዘገባል፤ በ`OMNIROUTE_LOG_EXPORT_CRON` ሊቀየር ይችላል።
እያንዳንዱ ዙር ሁሉንም **የነቁ** መድረሻዎች በቅደም ተከተል ሙሉ በሙሉ ያስኬዳል።
- **ጠቋሚ** — የSQLite ስውር `call_logs.rowid`፣ ለእያንዳንዱ መድረሻ በ
`log_export_destinations.cursor_row_id` ውስጥ ዘላቂ ሆኖ ይቀመጣል። `timestamp` ሆን ተብሎ እንደ ጠቋሚ አይጠቀምም፦ ጠሪዎች
የራሳቸውን እሴት ሊያቀርቡ ስለሚችሉ፣ ዘገምተኛ ጥያቄ ከእሱ በኋላ ከተጀመረ ፈጣን ጥያቄ በኋላ
ሊጻፍ ይችላል፤ በጊዜ ማህተም ላይ የተመሠረተ ጠቋሚም ይህን ይዘለዋል።
- **በጥቅል ማስኬድ** — በእያንዳንዱ ጥያቄ `batch_size` ረድፎች (ነባሪ 500)፣ በእያንዳንዱ ዙር
`max_rows_per_run` ረድፎች (ነባሪ 10000) ይስተናገዳሉ፤ በዚህም ትልቅ የተጠራቀመ ሥራ አንድን ዙር ከማገድ ይልቅ በበርካታ ዙሮች ውስጥ ይጠናቀቃል።
- **ማድረስ** — ጠቋሚው የሚራመደው `send()` በተሳካ ሁኔታ ከተጠናቀቀ በኋላ ብቻ ነው። ያልተሳካ ጥቅል
ጠቋሚውን ባለበት ይተወዋል፤ ስለዚህ ተመሳሳይ ረድፎች በሚቀጥለው ዙር እንደገና ይሞከራሉ። የሚሰጠው ዋስትና
ቢያንስ-አንድ-ጊዜ ማድረስ ከመድረሻ-ወገን የተባዙ መዝገቦችን ማስወገድ ጋር እንጂ እውነተኛ በትክክል-አንድ-ጊዜ ማድረስ አይደለም፦ BigQuery እያንዳንዱን
ረድፍ በጥሪ ምዝግቡ id ይመድባል፤ ይህንንም በራሱ የተባዙ መዝገቦችን ማስወገጃ የጊዜ መስኮት ውስጥ በሚቻለው መጠን ያከብራል።
- **የመደራረብ መከላከያ** — የcron ዙሩ እና `POST .../run` በአንድ ጊዜ ሊነሱ ይችላሉ። አስቀድሞ
እየተስተናገደ ያለ መድረሻ ሁለት ጊዜ ከመስተናገድ ይልቅ ይዘለላል (በዙሩ ውጤት ውስጥ `skipped: true`)፤
ስለዚህ በአንድ ጊዜ የሚካሄድ ዙር ጥቅልን እንደገና መላክ ወይም ጠቋሚውን ወደኋላ መጻፍ አይችልም።
- **ከማጽዳት ማገገም** — `cursor_row_id` ከ`MAX(rowid)` በላይ ከሆነ (ሙሉው ሰንጠረዥ
ተጠርጎ እና rowids እንደገና ከጀመሩ)፣ አስኬጁ በቋሚነት ውሂቡን ማየት እንዳይሳነው ወደ 0 ይመለሳል።
### የሚላኩ ይዘቶች (ጥያቄዎች እና ምላሾች)
በነባሪነት የሚላከው ውሂብ የLogs **ዝርዝር** የሚያሳያቸውን የማጠቃለያ መስኮች ብቻ ይይዛል።
**ጥያቄዎችን እና ምላሾችን ላክ** (`includeBodies`)ን ማብራት፣ የLogs **ዝርዝር መረጃ**
ፓነል ለእያንዳንዱ ጥሪ የሚያሳየውን ይዘት በተጨማሪ ይልካል፦
| መስክ | የሚይዘው ነገር |
| -------------------------------- | ------------------------------------------------- |
| `request_body` / `response_body` | ዳሽቦርዱ በሚያሳያቸው መልኩ የጥሪው ይዘቶች |
| `pipeline_route_decision` | ራውተሩ የመረጠው ዒላማ እና ሞዴል |
| `pipeline_client_request` | ደንበኛው በላከው ትክክለኛ መልክ ያለው ጥሬ ጥያቄ |
| `pipeline_openai_request` | ወደ ውስጣዊው የOpenAI ቅርጽ ከተተረጎመ በኋላ |
| `pipeline_provider_request` | በአቅራቢው ዘዬ፣ በትክክል ወደ ላይኛው አገልግሎት እንደተላከው |
| `pipeline_provider_response` | ከላይኛው አገልግሎት የተገኘው ጥሬ ምላሽ |
| `pipeline_client_response` | ወደ ጠሪው የተመለሰው ይዘት |
| `pipeline_error` | ላልተሳካ ጥሪ የማስኬጃ መስመር-ደረጃ የስህተት ዝርዝር |
| `bodies_truncated` | ከላይ ካሉት መስኮች አንዱ `maxBodyBytes` ላይ ሲደርስ እውነት ይሆናል |
ይህ የጥያቄ ይዘት ስለሆነ፣ በነባሪነት **ጠፍቶ ነው**፤ ሆን ተብሎም ለእያንዳንዱ መድረሻ በተናጠል የሚመረጥ ነው።
የሚላከው ዳሽቦርዱ የሚያሳየው ነው፤ ምክንያቱም ሁለቱም በ`getCallLogById` በኩል ያነባሉ፦ ይዘቶች
ሲጻፉ አስቀድመው PII ተወግዶላቸዋል እና ሚስጥሮች ተሸፍነውባቸዋል፤ እንዲሁም
`noLog` API ቁልፍን በመጠቀም የተደረገ ጥሪ ምንም ይዘት አያከማችም፣ ስለዚህ የሚላክ ምንም ነገር የለም።
ይዘቶች ከፋይል ስርዓቱ አርቲፋክት በየረድፉ ይነበባሉ፤ ስለዚህ ሙሉ መረጃውን የመጫን ሂደት የሚከናወነው
ይህን ለጠየቁ መድረሻዎች ብቻ ነው። አርቲፋክቱ የጠፋ ወይም የተበላሸ ረድፍ፣
ጥቅሉን ከማሳካት እና ጠቋሚውን ከማስቆም ይልቅ፣ ማጠቃለያውን ከnull ይዘቶች ጋር ይልካል።
`maxBodyBytes` (ነባሪ 262144) ለእያንዳንዱ መስክ ከፍተኛ ገደብ ያስቀምጣል። ረዘም ያሉ ይዘቶች
ከመጣል ይልቅ **ይቆረጣሉ** — የተቆረጠ ጥያቄም ቢሆን “ምን ተጠየቀ” የሚለውን ይመልሳል — እና ረድፉ
በ`bodies_truncated` ምልክት ይደረግበታል። በዥረት የተላኩ ክፍል-በክፍል ልዩነቶች አይላኩም፤ የተገጣጠመው ምላሽ
አስቀድሞ በ`pipeline_provider_response` እና `pipeline_client_response` ውስጥ ይገኛል።
---
## 2. ፋይሎች
| ክፍል | መገኛ |
| --------------- | -------------------------------------------- |
| መድረሻ ኮንትራት | `src/lib/logExport/types.ts` |
| መዝገብ | `src/lib/logExport/registry.ts` |
| የሚስጥር አያያዝ | `src/lib/logExport/secrets.ts` |
| አስኬጅ (የጠቋሚ ዙር) | `src/lib/logExport/runner.ts` |
| የAPI ውክልና | `src/lib/logExport/presenter.ts` |
| BigQuery መድረሻ | `src/lib/logExport/destinations/bigquery.ts` |
| Google SA ማረጋገጫ | `src/lib/logExport/googleServiceAccount.ts` |
| የጥሪ ሎግ ምንጭ | `src/lib/usage/callLogExportSource.ts` |
| ቋሚ ማከማቻ | `src/lib/db/logExportDestinations.ts` |
| Cron ሥራ | `src/lib/jobs/logExportJob.ts` |
| REST ንብርብር | `src/app/api/log-export/` |
| የዳሽቦርድ ገጽ | `src/app/(dashboard)/dashboard/log-export/` |
መርሐግብር፦ `src/lib/db/migrations/170_log_export_destinations.sql`።
---
## 3. REST API
ሁሉም መስመሮች በአስተዳደር ማረጋገጫ (`requireManagementAuth`) የተጠበቁ ናቸው። ሚስጥሮች ፈጽሞ አይመለሱም፦
የተከማቸ ሚስጥር እንደ ቃል በቃል `__stored__` ይመለሳል፤ በማዘመን ጊዜ ያንን እሴት መልሶ መላክ
የተከማቸውን ማረጋገጫ መረጃ እንዳለ ያቆየዋል።
ዓይነቱ ሚስጥር እንዳለው የሚገልጽ መድረሻን መፍጠር ወይም ማዘመን **`STORAGE_ENCRYPTION_KEY`
ያስፈልገዋል**። ያለዚህ `encrypt()` ምንም ሳይለውጥ በዝምታ ያሳልፋል፤ ስለዚህ የማረጋገጫ መረጃን
በSQLite ውስጥ እንደ ግልጽ ጽሑፍ ከማስቀመጥ ይልቅ ጽሑፉ በ400 ውድቅ ይደረጋል (ይህም የTelegram
webhook የሚተገብረው ተመሳሳይ መከላከያ ነው)።
| ዘዴ | መንገድ | ዓላማ |
| -------- | ---------------------------------------- | ------------------------------------------------- |
| `GET` | `/api/log-export/types` | የመድረሻ ዓይነቶች + የውቅር መስኮቻቸው ዝርዝር |
| `GET` | `/api/log-export/destinations` | መድረሻዎችን ይዘርዝሩ (ሚስጥሮች ተሸፍነዋል) |
| `POST` | `/api/log-export/destinations` | መድረሻ ይፍጠሩ |
| `GET` | `/api/log-export/destinations/{id}` | አንዱን ያንብቡ |
| `PUT` | `/api/log-export/destinations/{id}` | ስም / የነቃ ሁኔታ / ውቅር / በጥቅል ማስኬድን ያዘምኑ |
| `DELETE` | `/api/log-export/destinations/{id}` | ይሰርዙ |
| `POST` | `/api/log-export/destinations/{id}/test` | የማረጋገጫ መረጃን ይፈትሹ፣ ምንም አይጻፉ |
| `POST` | `/api/log-export/destinations/{id}/run` | አሁን ያስወግዱ፣ ከታቀደው አሂድ ጋር ተመሳሳይ መንገድ |
| `GET` | `/api/log-export/status` | የCron ሁኔታ፣ የቅርብ ጊዜ አሂዶች፣ በእያንዳንዱ ዒላማ ያልተከናወኑ ሥራዎች |
`GET /api/log-export/types` UIውን አጠቃላይ እንዲሆን የሚያደርገው ነው፦ የዳሽቦርድ ቅጹ
ከተመለሱት የመስክ ገላጮች ይሳላል፤ ስለዚህ አዲስ መድረሻ ምንም የUI ለውጥ አያስፈልገውም።
---
## 4. BigQuery መድረሻ
የውቅር ቁልፎች (`type: "bigquery"`)፦
| ቁልፍ | ማስታወሻዎች |
| -------------------- | --------------------------------------------------------- |
| `projectId` | የውሂብ ስብስቡን የያዘው GCP ፕሮጀክት |
| `datasetId` | `[A-Za-z0-9_]+` |
| `tableId` | `[A-Za-z0-9_]+` |
| `location` | የውሂብ ስብስቡ መፈጠር ሲኖርበት ብቻ ጥቅም ላይ ይውላል (ነባሪ `EU`) |
| `serviceAccountJson` | የአገልግሎት መለያ ቁልፍ። ሚስጥር፦ በማከማቻ ጊዜ የተመሰጠረ፣ ፈጽሞ የማይመለስ |
| `autoCreate` | በመጀመሪያው ወደ ውጭ መላክ ላይ የውሂብ ስብስቡንና ሰንጠረዡን ይፍጠሩ (ነባሪ `true`) |
የአገልግሎት መለያው በዒላማው ሰንጠረዥ ላይ `bigquery.tables.updateData`፣ በተጨማሪም
`autoCreate` ከነቃ `bigquery.datasets.create` / `bigquery.tables.create` ያስፈልገዋል።
የተዋቀረ ጥቅል የHTTP ሳይሆን የ**ጠቋሚ** አሃድ ነው፦ `send()` እስከ 500 ረድፎች ብቻ ወዳሏቸው
insertAll ጥሪዎች ይከፋፍለዋል፤ ስለዚህ ትልቅ `batch_size` የBigQueryን የ10 MB የጥያቄ ገደብ ሊያልፍ
አይችልም። ጊዜያዊ ሁኔታዎች (408/429/500/502/503/504) በኤክስፖነንሺያል መዘግየት እስከ ሦስት
ጊዜ ድረስ፣ ተመሳሳይ insertIdsን እንደገና በመጠቀም ይሞከራሉ፤ የማረጋገጫና የመርሐግብር ውድቀቶች
አሂዱን በከንቱ ከማባከን ይልቅ በመጀመሪያው ሙከራ ላይ ስህተት ይጥላሉ።
ከጥቂት ጊዜ በፊት የተፈጠረ ሰንጠረዥ ለዥረት መጨረሻ ነጥቡ ገና አይታይም፤ ስለዚህም ለጥቂት
ሰከንዶች 404 ይመልሳል። ያ 404 እንደገና ይሞከራል፣ ነገር ግን **ይህ አሂድ ሰንጠረዡን
ሲፈጥር ብቻ** ነው — በእርግጥ የሌለ ሰንጠረዥ ግን ወዲያውኑ ይወድቃል። በቅርቡ በተሰረዘ ስም ስር
ሰንጠረዥን እንደገና መፍጠር BigQuery ለብዙ ደቂቃዎች የዥረት ማስገባቶችን ውድቅ እንዲያደርግ
እንደሚያደርገው ያስተውሉ፤ ይህ የመሰረዝ-ከዚያም-እንደገና-የመፍጠር ባህሪ ስለሆነ፣ ሰንጠረዥን
ከማስወገድና እንደገና ከማከል ይልቅ አዲስ የሰንጠረዥ ስም መጠቀም ይመረጣል።
**ከፊል ውድቀት ባዶ ያልሆነ `insertErrors[]` ይዞ እንደ HTTP 200 ይመጣል።** ይህ እንደ
ውድቀት ተቆጥሮ ስህተት ይጥላል፤ ይህም BigQuery ካልተቀበላቸው ረድፎች አልፎ ጠቋሚው እንዳይራመድ
ያስቆመዋል፤ `tests/unit/log-export-bigquery.test.ts` ባህሪውን ያረጋግጣል።
መጓጓዣው ተራ REST ነው — በራስ የተፈረመ RS256 ማረጋገጫ በ
`https://oauth2.googleapis.com/token` የመዳረሻ ቶከን ለማግኘት ይለወጣል፣ ከዚያም ረድፎቹ ወደ
`tabledata.insertAll` ይሄዳሉ። ምንም Google SDK አይጨመርም። የመዳረሻ ቶከኖች በእያንዳንዱ
(የአገልግሎት መለያ፣ ወሰን) በሂደቱ ውስጥ በመሸጎጫ ይቀመጣሉ።
የተፈጠረው ሰንጠረዥ ለእያንዳንዱ የLogs ትር መስክ አንድ ዓምድ ከ`exported_at` ጋር ይይዛል፤
እንዲሁም የጥሪ ሎጎች በተግባር ለሚጠየቁበት መንገድ ተዘጋጅቷል፦
- **በ`timestamp` ላይ በቀን የተከፋፈለ**፣ ስለዚህ በቀን የተወሰነ ጥያቄ እነዚያን ቀናት ብቻ ይቃኛል።
- **በ`api_key_name`፣ `provider`፣ `model`፣ `status` የተከማቸ** (በዚያ ቅደም ተከተል)፣ ስለዚህ
ማን እንዳስኬደው፣ ወዴት እንደሄደ ወይም እንደወደቀ መሰረት ማጣራት በእያንዳንዱ ክፍል ውስጥ
ያሉ ጥቅሎችን ይቀንሳል። BigQuery ቢበዛ አራት የክላስተሪንግ ዓምዶችን ይፈቅዳል፣ እና ቅደም
ተከተሉ አስፈላጊ ነው፦ በ`api_key_name` ብቻ ማጣራት ይቀንሳል፣ በ`status` ብቻ ማጣራት ግን
አይቀንስም።
- በ`partitionExpirationDays` በኩል **አማራጭ የክፍል ማቆያ** (0 ሁሉንም ያቆያል)፣ ሰንጠረዡ
ሲፈጠር ይተገበራል።
ሁለቱም ቅንብሮች በመፍጠር ጊዜ ተግባራዊ ይሆናሉ። ነባር ሰንጠረዥ ቀድሞውኑ ያለውን አቀማመጥ ይዞ ይቆያል፤ ስለዚህ
እነዚህን መተግበር ከፈለጉ መድረሻውን ወደ አዲስ የሰንጠረዥ id ያመልክቱ።
`tests/unit/log-export-bigquery.test.ts` ማፐሩና የሰንጠረዡ መርሐግብር በተመሳሳይ ሁኔታ
እንዲራመዱ ያረጋግጣል፤ በመሆኑም አዲስ የጥሪ ምዝግብ ዓምድ ወደ ውጭ በሚላክበት ሂደት ያለማስጠንቀቂያ ሊተው አይችልም።
ባቾች በ**ሁለቱም** የረድፍ ብዛትና ተከታታይ ተደርገው በተቀመጡ ባይቶች መጠን ይከፋፈላሉ። የውሂብ ጭነቶች ወደ ውጭ መላክ ከጀመሩ በኋላ የረድፍ ብዛት ብቻ በቂ አይደለም፤ መጠየቂያዎችን የያዙ 500 ረድፎች በአስር ሜጋባይቶች ሊለኩ ይችላሉ፣ እና insertAll
ከ10 MB በላይ የሆነ ጥያቄን አይቀበልም። ክፍሎቹ 500 ረድፎች ወይም 9 MB ሲደርሱ፣ ከሁለቱ ቀድሞ የደረሰው ላይ ይዘጋሉ።
---
## 5. መድረሻ ማከል
1. `LogExportDestinationType` የሚያስወጣ `src/lib/logExport/destinations/<name>.ts` ይፍጠሩ፦
የZod `configSchema`፣ ለUI የሚያገለግል የ`fields` መግለጫ ድርድር፣ `secretFields`፣ እና
`test()` / `prepare()` / `send(records)` የሚመልስ `createClient(config)`።
2. በ`src/lib/logExport/registry.ts` ውስጥ ወዳለው `DESTINATIONS` ድርድር ያክሉት።
3. በ`tests/unit/` ስር ሙከራዎችን ይጻፉ።
ለውጡ በሙሉ ይህ ብቻ ነው፦ የውሂብ ማቆያው፣ የcron ሥራው፣ የREST ንብርብሩ፣ የሚስጥር ምስጠራው እና
የdashboard ቅጹ ሁሉም registryውን ያነባሉ።
ለአዲስ መድረሻ ሁለት ደንቦች አሉ፦
- በከፊል ሲወድቅ `send()` **የግድ ስህተት መወርወር አለበት**። በስኬት መጠናቀቁ “መድረሻው እነዚህን ረድፎች ይዟል” ማለት ሲሆን፣
cursorውም እነሱን በቋሚነት አልፎ ይሄዳል።
- ተጠቃሚው ያቀረበውን URL የሚቀበል መድረሻ፣ ልክ webhooks እንደሚያደርጉት፣ fetch ከማድረጉ በፊት
በ`parseAndValidateWebhookUrl` (`src/shared/network/outboundUrlGuardPolicy.ts`) በኩል ማረጋገጥ አለበት።
BigQuery ይህን አያስፈልገውም፦ hostsዎቹ ቋሚዎች ናቸው።
---
## 6. ማስኬድ
- **Dashboard**፦ Integrations → Log export። መድረሻ ያክሉ፣ ረድፎችን ሳይጽፉ credentialsን ለማረጋገጥ
**Test**ን ያስኪዱ፣ ከዚያም ያንቁት።
- **Backlog**፦ የእያንዳንዱ መድረሻ ካርድ በመጠባበቅ ላይ ያሉ ረድፎችን እና cursorውን ያሳያል፤ `GET
/api/log-export/status` ተመሳሳይ አኃዞችን ከመጨረሻዎቹ 20 የሥራ አስኬዶች ጋር ይመልሳል።
- **የአንድ መድረሻ ውድቀት ሌሎቹን አያወድቅም** — የአስኬዱ ማጠቃለያ የእያንዳንዱን መድረሻ
ሁኔታ በ`last_status` / `last_error` ውስጥ ይመዘግባል፣ የሥራ አስኬድ ታሪኩም ድምር ውጤቱን ያቆያል።
- **መድረሻን መሰረዝ cursorውንም ይሰርዛል።** እንደገና ማከል ከቆየው እጅግ ጥንታዊው
የጥሪ log ይጀምራል፤ ይህም መድረሻው አስቀድሞ የያዛቸውን ረድፎች እንደገና ይልካል። በBigQuery ላይ የእያንዳንዱ ረድፍ
`insertId` ይህን የሚያስወግደው በBigQuery የራሱ የድግግሞሽ ማስወገጃ ጊዜ መስኮት ውስጥ ብቻ ነው፤ ስለዚህ መድረሻን
ከመሰረዝ ይልቅ ማሰናከልን ይምረጡ።

1073
docs/i18n/am/docs/frameworks/MEMORY.md Normal file
View File

File diff suppressed because it is too large Load Diff

124
docs/i18n/am/docs/frameworks/NOTION_CONTEXT.md Normal file
View File

@@ -0,0 +1,124 @@
# Notion Context Source (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/NOTION_CONTEXT.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/NOTION_CONTEXT.md) · 🇦🇿 [az](../../../az/docs/frameworks/NOTION_CONTEXT.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/NOTION_CONTEXT.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/NOTION_CONTEXT.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/NOTION_CONTEXT.md) · 🇩🇰 [da](../../../da/docs/frameworks/NOTION_CONTEXT.md) · 🇩🇪 [de](../../../de/docs/frameworks/NOTION_CONTEXT.md) · 🇬🇷 [el](../../../el/docs/frameworks/NOTION_CONTEXT.md) · 🇪🇸 [es](../../../es/docs/frameworks/NOTION_CONTEXT.md) · 🇪🇪 [et](../../../et/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/NOTION_CONTEXT.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/NOTION_CONTEXT.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/NOTION_CONTEXT.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇱 [he](../../../he/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/NOTION_CONTEXT.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/NOTION_CONTEXT.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/NOTION_CONTEXT.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇩 [id](../../../id/docs/frameworks/NOTION_CONTEXT.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇹 [it](../../../it/docs/frameworks/NOTION_CONTEXT.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/NOTION_CONTEXT.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/NOTION_CONTEXT.md) · 🇰🇭 [km](../../../km/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/NOTION_CONTEXT.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/NOTION_CONTEXT.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/NOTION_CONTEXT.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/NOTION_CONTEXT.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/NOTION_CONTEXT.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/NOTION_CONTEXT.md) · 🇲🇲 [my](../../../my/docs/frameworks/NOTION_CONTEXT.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/NOTION_CONTEXT.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/NOTION_CONTEXT.md) · 🇳🇴 [no](../../../no/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [or](../../../or/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/NOTION_CONTEXT.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/NOTION_CONTEXT.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/NOTION_CONTEXT.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/NOTION_CONTEXT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/NOTION_CONTEXT.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/NOTION_CONTEXT.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/NOTION_CONTEXT.md) · 🇱🇰 [si](../../../si/docs/frameworks/NOTION_CONTEXT.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/NOTION_CONTEXT.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/NOTION_CONTEXT.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/NOTION_CONTEXT.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/NOTION_CONTEXT.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/NOTION_CONTEXT.md) · 🇮🇳 [te](../../../te/docs/frameworks/NOTION_CONTEXT.md) · 🇹🇭 [th](../../../th/docs/frameworks/NOTION_CONTEXT.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/NOTION_CONTEXT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/NOTION_CONTEXT.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/NOTION_CONTEXT.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/NOTION_CONTEXT.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/NOTION_CONTEXT.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/NOTION_CONTEXT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/NOTION_CONTEXT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/NOTION_CONTEXT.md)
---
> **ዋና የእውነት ምንጭ:** `src/lib/notion/api.ts` (REST ደንበኛ), `src/lib/db/notion.ts`
> (የቶከን ማከማቻ), `open-sse/mcp-server/tools/notionTools.ts` (6 MCP መሣሪያዎች),
> `src/app/api/settings/notion/route.ts` (የቅንብሮች API)። የመሣሪያ ምዝገባ እና የወሰን
> ማገናኘት በ`open-sse/mcp-server/server.ts` ውስጥ ይገኛሉ።
## ምንድን ነው
OmniRoute ከ**Notion** የሥራ ቦታ ጋር እንደ **የዐውድ ምንጭ** — ወኪሎች አብሮ በተሰራው MCP አገልጋይ በኩል የሚደርሱበት ማንበብ/መጻፍ የሚቻልበት
የእውቀት ማከማቻ — ሊገናኝ ይችላል። የNotion
ውህደት ቶከን አንዴ ከተዋቀረ፣ የMCP መሣሪያዎቹ LLM ገጾችን እና ዳታቤዞችን እንዲፈልግ፣
የገጽ ይዘትን እና የብሎክ ዛፎችን እንዲያነብ፣ ዳታቤዞችን በማጣሪያዎች/መደርደሪያዎች እንዲጠይቅ እና አዳዲስ
ብሎኮችን እንዲያክል ያስችሉታል — ሞዴሉ የNotion APIን በቀጥታ ፈጽሞ እንዳይጠቀም
ሁሉም ጥያቄዎች በOmniRoute በኩል (ከድጋሚ ሙከራ፣ የጊዜ ገደብ እና የስህተት ምደባ ጋር) ይተላለፋሉ።
ውህደቱ በይፋዊው Notion REST API
(`https://api.notion.com/v1`, `Notion-Version: 2026-03-11`) ላይ የተገነባ ቀላልና የተጠናከረ መጠቅለያ ነው። ደንበኛው
(`src/lib/notion/api.ts`) የሚከተሉትን ይጨምራል፦
- ለ`429` እና `5xx` **በጨመረ የመጠበቂያ ጊዜ ድጋሚ መሞከር** (እስከ 3 ሙከራዎች)።
- በ`AbortController` በኩል **የ55 ሰከንድ የጥያቄ ጊዜ ገደብ**።
- **በዓይነት የተለየ የስህተት ምደባ** — `NotionAuthError` (401/403),
`NotionNotFoundError` (404), `NotionRateLimitError` (429፣ የ`retry after`
ፍንጮችን ያከብራል), `NotionValidationError` (400/409), `NotionServerError` (5xx),
`NotionTimeoutError`።
- ከማሳየት በፊት የቁልል ዱካ የሚመስሉ ክፍሎችን የሚያስወግድ **የመልዕክት ማጽዳት**።
## ማዋቀር
ለNotion ቶከን **ምንም የአካባቢ ተለዋዋጭ የለም** — በ
`src/lib/db/notion.ts` በኩል በSQLite `key_value` ሰንጠረዥ (namespace `notion`፣ key `integration_token`) ውስጥ
ይከማቻል። ከEndpoint ዳሽቦርድ **Context Sources** ትር
(`ObsidianSourceCard` ጎን ያለው `NotionSourceCard`) ወይም በቅንብሮች REST API በኩል ያዋቅሩት።
> [!NOTE]
> ቶከኑ **የNotion ውስጣዊ ውህደት ቶከን** ነው። በ
> <https://www.notion.com/my-integrations> ላይ ውህደት ይፍጠሩ፣ ከዚያ OmniRoute እንዲደርስባቸው የሚፈልጓቸውን
> ገጾች/ዳታቤዞች ለዚያ ውህደት ያጋሩ (የNotion የፈቃድ ሞዴል በማጋራት ላይ የተመሠረተ ነው፣
> ሙሉ የሥራ ቦታ ፈቃድ አይደለም)።
### በREST በኩል ማዋቀር
```bash
# የውህደት ቶከኑን ያስቀምጡ + ያረጋግጡ (POST የሙከራ ፍለጋ በማድረግ ያረጋግጣል)
curl -X POST http://localhost:20128/api/settings/notion \
-H "Content-Type: application/json" \
-d '{"token":"ntn_xxx"}'
# የግንኙነት ሁኔታን ይፈትሹ
curl http://localhost:20128/api/settings/notion
# ግንኙነቱን ያቋርጡ (የተከማቸውን ቶከን ያጸዳል)
curl -X DELETE http://localhost:20128/api/settings/notion
```
ሦስቱም ዘዴዎች የዳሽቦርድ ማረጋገጫ (`isAuthenticated`) ይፈልጋሉ። `POST` ሲደረግ፣
OmniRoute ቶከኑን ያስቀምጣል እና ወዲያውኑ 1 ውጤት ያለው የሙከራ ፍለጋ ያከናውናል፤ Notion
የስህተት ነገር ከመለሰ ቶከኑ ይጸዳል እና ጥሪው በ`400` ይከሽፋል።
## MCP መሣሪያዎች (6)
በ`open-sse/mcp-server/tools/notionTools.ts` ውስጥ ተገልጸዋል። ቶከኑ በጥሪ ጊዜ
በ`getNotionToken()` በኩል ይፈለጋል፤ ምንም ካልተዋቀረ መሣሪያው
`"Notion integration token not configured. Set it in Settings > Context Sources."` የሚለውን ስህተት ይጥላል።
| መሣሪያ | ወሰን | መግለጫ |
| ---------------------------- | -------------- | --------------------------------------------------------------------- |
| `notion_search` | `read:notion` | ገጾችን እና ዳታቤዞችን በጽሑፍ ጥያቄ ይፈልጋል (ርዕሶችን፣ IDsን፣ URLsን ይመልሳል)። በገጽ የተከፋፈለ። |
| `notion_get_page` | `read:notion` | የአንድን ገጽ ይዘት እና ሜታዳታ በIDው ያገኛል። |
| `notion_list_block_children` | `read:notion` | የብሎክ ወይም የገጽ ልጅ ብሎኮችን በሙሉ (የብሎክ ዛፉን) ይዘረዝራል። በገጽ የተከፋፈለ። |
| `notion_query_database` | `read:notion` | ዳታቤዝን በአማራጭ `filter` + `sorts` (የNotion API ቅርጸት) ይጠይቃል። በገጽ የተከፋፈለ። |
| `notion_get_database` | `read:notion` | የዳታቤዝን መዋቅር/ሜታዳታ በID ያገኛል። |
| `notion_append_blocks` | `write:notion` | በነባር ብሎክ ወይም ገጽ ላይ ልጅ ብሎኮችን ያክላል (በአንድ ጥያቄ ከፍተኛው 100 ብሎኮች)። |
### የግቤት መለኪያዎች
- `notion_search` — `query` (1–500 ቁምፊዎች), `pageSize` (1–100፣ ነባሪ 20),
`startCursor` (አማራጭ)።
- `notion_get_page` — `pageId` (32 ቁምፊ ሄክስ ወይም UUID)።
- `notion_list_block_children` — `blockId`, `pageSize` (1–100፣ ነባሪ 50),
`startCursor` (አማራጭ)።
- `notion_query_database` — `databaseId`, `filter` (አማራጭ፣ የNotion ማጣሪያ ቅርጸት),
`sorts` (አማራጭ ድርድር), `pageSize` (1–100፣ ነባሪ 50), `startCursor` (አማራጭ)።
- `notion_get_database` — `databaseId`።
- `notion_append_blocks` — `blockId`, `children` (የብሎክ ነገሮች ድርድር),
`after` (አማራጭ ቦታ)።
### ወሰኖች
የማንበብ መሣሪያዎቹ `read:notion`ን እና የመጻፍ መሣሪያው `write:notion`ን ይፈልጋሉ።
ወሰኖቹ በ`open-sse/mcp-server/server.ts` ውስጥ ባለው `withScopeEnforcement()` የሚተገበሩት
`OMNIROUTE_MCP_ENFORCE_SCOPES=true` ሲሆን ብቻ ነው፤ የጠሪው የተፈቀዱ ወሰኖች ከ
`OMNIROUTE_MCP_SCOPES` (በኮማ የተለዩ) ወይም ከተረጋገጠው API ቁልፍ የወሰን ዐውድ
ይመጣሉ። ለሙሉ የወሰን ሞዴሉ [MCP-SERVER.md](./MCP-SERVER.md)ን ይመልከቱ።
## መጨረሻ ነጥቦች
| ዘዴ | ዱካ | ዓላማ |
| -------- | ---------------------- | --------------------------------- |
| `GET` | `/api/settings/notion` | `{ connected, hasToken }`ን ይመልሳል። |
| `POST` | `/api/settings/notion` | የውህደት ቶክኑን ያስቀምጣል + ያረጋግጣል። |
| `DELETE` | `/api/settings/notion` | ግንኙነቱን ያቋርጣል (የተከማቸውን ቶከን ያጸዳል)። |
> እነዚህ የዳሽቦርድ ቅንብሮች መስመሮች ናቸው። ይፋዊ የ`/v1` Notion ፕሮክሲ
> መጨረሻ ነጥብ **የለም** — Notion የሚደረስበት ከላይ ባሉት MCP መሣሪያዎች ብቻ ነው።
## የአጠቃቀም ሁኔታዎች
- **በዕውቀት ላይ የተመሠረቱ መልሶች** — አንድ ወኪል መልስ ከመስጠቱ በፊት የሥራ ቦታውን `notion_search` እንዲያደርግ እና ከፍተኛውን ውጤት `notion_get_page` እንዲያደርግ ይፍቀዱ፤ በዚህም ምላሾች እውነተኛ ውስጣዊ ሰነዶችን ይጠቅሳሉ።
- **በውሂብ ጎታ የሚደገፉ የሥራ ፍሰቶች** — የተግባራት/CRM ውሂብ ጎታን በማጣሪያዎች + ቅደም ተከተሎች `notion_query_database` ያድርጉ፣ ከዚያም ረድፎቹን ያጠቃልሉ ወይም በቅድሚያ ይመድቡ።
- **መልሶ መጻፍ / ምዝግብ ማስቀመጥ** — የስብሰባ ማስታወሻዎችን፣ የክንውን ማጠቃለያዎችን ወይም የወኪል ውጤትን ወደ ነባር ገጽ ለማከል `notion_append_blocks`ን ይጠቀሙ (መጨመር ብቻ፤ አጥፊ አርትዖቶች የሉም)።
- **የመዋቅር ዳሰሳ** — የአንድን ገጽ የብሎኮች ዛፍ ለመዳሰስ `notion_list_block_children`ን፣ ወይም ከመጠየቅዎ በፊት የውሂብ ጎታውን የባህሪ መርሃግብር ለማወቅ `notion_get_database`ን ይጠቀሙ።
## ተዛማጅ
- [MCP አገልጋይ](./MCP-SERVER.md) — ማጓጓዣዎች፣ የወሰን ማስፈጸሚያ፣ ሙሉ የመሣሪያዎች ዝርዝር።
- [የObsidian ዐውድ ምንጭ](./OBSIDIAN_CONTEXT.md) — ሌላኛው አብሮገነብ የዐውድ ምንጭ።
- [የማህደረ ትውስታ ሥርዓት](./MEMORY.md) — ቀጣይነት ያለው የውይይት ማህደረ ትውስታ (ተጨማሪ
የዐውድ ንብርብር፣ በመሣሪያ ከመጎተት ይልቅ በራስ-ሰር የሚገባ)።

194
docs/i18n/am/docs/frameworks/OBSIDIAN_CONTEXT.md Normal file
View File

@@ -0,0 +1,194 @@
# Obsidian Context Source (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/OBSIDIAN_CONTEXT.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇦🇿 [az](../../../az/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇩🇰 [da](../../../da/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇩🇪 [de](../../../de/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇬🇷 [el](../../../el/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇪🇸 [es](../../../es/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇪🇪 [et](../../../et/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇱 [he](../../../he/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇩 [id](../../../id/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇹 [it](../../../it/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇰🇭 [km](../../../km/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇲🇲 [my](../../../my/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇳🇴 [no](../../../no/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [or](../../../or/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇱🇰 [si](../../../si/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇮🇳 [te](../../../te/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇹🇭 [th](../../../th/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/OBSIDIAN_CONTEXT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/OBSIDIAN_CONTEXT.md)
---
> **ዋና የእውነት ምንጭ:** `src/lib/obsidian/api.ts` (REST + ማመሳሰያ ደንበኛ)፣
> `src/lib/db/obsidian.ts` (የtoken / base-URL / WebDAV ቋሚ ማከማቻ)፣
> `src/lib/obsidianSync.ts` (የWebDAV vault ማመሳሰል)፣ `open-sse/mcp-server/tools/obsidianTools.ts`
> (22 የMCP መሣሪያዎች)፣ `src/app/api/settings/obsidian/route.ts` +
> `src/app/api/settings/obsidian/webdav/route.ts` (የቅንብሮች APIs)። የመሣሪያ ምዝገባ
> እና የscope ማገናኘት በ`open-sse/mcp-server/server.ts` ውስጥ ይገኛል።
## ምንድን ነው
OmniRoute ከ**Obsidian** vault ጋር እንደ **የአውድ ምንጭ** ይገናኛል — ወኪሎች
አብሮ በተሰራው MCP አገልጋይ አማካይነት የሚያነቡትና የሚጽፉበት አካባቢያዊ Markdown
የእውቀት ማከማቻ ነው። ውህደቱ በዴስክቶፕ መተግበሪያው ውስጥ ከሚሰራው
የማህበረሰብ **Obsidian Local REST API** plugin ጋር ይገናኛል፤ በዚህም ወኪሎች
ማስታወሻዎችን መፈለግ፣ ፋይሎችን ማንበብ/መጻፍ/ማስተካከል፣ vaultን መዘርዘር፣
ከዕለታዊ/ሳምንታዊ ወቅታዊ ማስታወሻዎች ጋር መስራት፣ tagsን ማስተዳደር፣
የObsidian ትዕዛዞችን ማስኬድ እና (እንደ አማራጭ) ባለሁለት አቅጣጫ
የዴስክቶፕ↔ሞባይል vault ማመሳሰልን ማስተባበር ይችላሉ።
ደንበኛው (`src/lib/obsidian/api.ts`) Local REST APIን በሚከተሉት ባህሪያት ይሸፍናል፦
- ለጊዜያዊ `5xx` ስህተቶች **ከbackoff ጋር ዳግም መሞከር**፣ በ`AbortController` በኩል **የ30 ሰከንድ timeout**።
- **በtype የተደረገ የስህተት ምደባ** — `ObsidianAuthError` (401/403)፣
`ObsidianNotFoundError` (404)፣ `ObsidianServerError` (5xx)፣ `ObsidianTimeoutError`።
- የተለመደውን የport ስህተት (HTTP በ`27123` ላይ፣ በ`27124` ላይ ያለው MCP
endpoint **አይደለም**) እና የTailscale ቅርጸቱን የሚጠቅስ ቀላል
**«Obsidianን ማግኘት አልተቻለም» ፍንጭ**።
- ክፍተት/slash ያላቸው የማስታወሻ ዱካዎች ደህንነታቸው እንዲጠበቅ፣ ከvault አንጻር
የሚደረግ **የዱካ ኢንኮዲንግ**።
## ማዋቀር
ለObsidian token ወይም base URL **ምንም environment variable የለም** — ሁለቱም
በ`src/lib/db/obsidian.ts` በኩል በSQLite `key_value` ሰንጠረዥ (namespace `obsidian`)
ውስጥ ይከማቻሉ። tokenው **በማከማቻ ላይ ሳለ የተመሰጠረ** ነው (AES-256-GCM፣
ከplaintext የኋላ-ተኳኋኝ fallback ጋር)። ከEndpoint dashboard
(`ObsidianSourceCard`) **Context Sources** tab ወይም በቅንብሮች REST API
በኩል ያዋቅሩ።
> [!IMPORTANT]
> የ**Obsidian Local REST API** plugin መጫንና እየሰራ መሆን አለበት። የREST
> interfaceው በ**HTTP `127.0.0.1:27123`** (ነባሪው base URL) ላይ ያዳምጣል። Port `27124`
> _የተለየ_ MCP/HTTPS endpoint ሲሆን በቅንብሮች route በግልጽ ውድቅ ይደረጋል።
> ከሌላ መሣሪያ ሲገናኙ `http://<tailscale-ip>:27123`ን ይጠቀሙ።
### የውቅር keys (SQLite `key_value`፣ namespace `obsidian`)
| Key | ዓላማ | የተመሰጠረ |
| ----------------- | --------------------------------------------- | ------ |
| `api_key` | የLocal REST API bearer token | አዎ |
| `base_url` | የREST base URL (ነባሪ `http://127.0.0.1:27123`) | አይ |
| `vault_path` | ወደ vault directory የሚወስድ ፍጹም ዱካ (ለማመሳሰል) | አይ |
| `webdav_username` | የመነጨ WebDAV username (የvault ማመሳሰል) | አይ |
| `webdav_password` | የመነጨ WebDAV password (የvault ማመሳሰል) | አዎ |
| `webdav_enabled` | የWebDAV vault ማመሳሰል መንቃቱን | አይ |
### በREST በኩል ማዋቀር
```bash
# የLocal REST API tokenን ያስቀምጡ + ያረጋግጡ (POST በstatus ፍተሻ ያረጋግጣል)
curl -X POST http://localhost:20128/api/settings/obsidian \
-H "Content-Type: application/json" \
-d '{"token":"<obsidian-rest-api-key>","baseUrl":"http://127.0.0.1:27123"}'
# የግንኙነት statusን ይፈትሹ (connected፣ hasToken፣ baseUrl፣ vaultPath ይመልሳል)
curl http://localhost:20128/api/settings/obsidian
# ግንኙነቱን ያቋርጡ (የተከማቸውን token ያጸዳል)
curl -X DELETE http://localhost:20128/api/settings/obsidian
```
ሁሉም methods የdashboard authentication ይፈልጋሉ። `POST` በport `27124`
ላይ ያለ ማንኛውንም URL ውድቅ ያደርጋል፤ ከማከማቸቱ በፊትም የLocal REST API
status endpointን በመጥራት tokenውን ያረጋግጣል።
### የWebDAV vault ማመሳሰል
`src/app/api/settings/obsidian/webdav/route.ts` እንደ አማራጭ በWebDAV የተደገፈ
የvault ማመሳሰልን ያስተዳድራል (በ`src/lib/obsidianSync.ts` የሚመራ)። ማንቃቱ
OmniRouteን ወደ አካባቢያዊ vault directory ያመለክታል እና በዘፈቀደ የWebDAV
username/password ጥንድ ይፈጥራል፦
```bash
# ለvault directory የWebDAV ማመሳሰልን ያንቁ (username/password ይፈጥራል)
curl -X POST http://localhost:20128/api/settings/obsidian/webdav \
-H "Content-Type: application/json" \
-d '{"vaultPath":"/home/me/MyVault"}'
# የWebDAV ማመሳሰል statusን ያግኙ (credentials የሚመለሱት ከነቃ ብቻ ነው)
curl http://localhost:20128/api/settings/obsidian/webdav
# የWebDAV ማመሳሰልን ያሰናክሉ (credentials + የሚተዳደረውን .stignore ያጸዳል)
curl -X DELETE http://localhost:20128/api/settings/obsidian/webdav
```
### በእያንዳንዱ API key የሚወሰን የአውድ ምንጭ (አማራጭ)
የObsidian ውቅር በ`api_key_context_sources` ሰንጠረዥ
(`src/lib/db/apiKeyContextSources.ts`) በኩል **ለእያንዳንዱ API key** ሊወሰን
ይችላል። የMCP ጥሪ የተረጋገጠ API key id ሲይዝ፣ `getObsidianConfigForApiKey()`
የዚያን key የራሱን token/base-URL/vault-path (`source: "api_key"`) ቅድሚያ
ይሰጣል፤ ካልሆነ ወደ ዓለም አቀፉ ውቅር (`source: "global"`) fallback ያደርጋል።
## MCP መሣሪያዎች (22)
በ`open-sse/mcp-server/tools/obsidianTools.ts` ውስጥ ተገልጸዋል። token/base-URL ለእያንዳንዱ ጥሪ ይወሰናሉ (መጀመሪያ የየ-API-key፣ ከዚያም ዓለም አቀፍ)። የOmniRoute **sync server**ን የሚጠቀሙ መሣሪያዎች
(አራቱ `obsidian_sync_*` መሣሪያዎች) በተጨማሪ በOmniRoute ቅንብሮች ውስጥ የተዋቀረውን የsync ማረጋገጫ token ይፈልጋሉ።
### የማንበቢያ መሣሪያዎች (`read:obsidian`)
| መሣሪያ | መግለጫ |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `obsidian_check_status` | Local REST API ተደራሽ እና የተረጋገጠ መሆኑን ያረጋግጣል። |
| `obsidian_search_simple` | በማስታወሻ ይዘት ውስጥ የሙሉ ጽሑፍ ፍለጋ ያደርጋል፤ ከፋይል ዱካዎች ጋር ቅንጭቦችን ይመልሳል። |
| `obsidian_search_structured` | የJSON Logic አገላለጽን (and/or/regex/path ማጣሪያዎች) በመጠቀም ይፈልጋል። |
| `obsidian_read_note` | ማስታወሻን በvault-relative path ያነባል፤ እንደ አማራጭም የተወሰነ heading/block/frontmatter ያነባል። |
| `obsidian_list_vault` | በvault ውስጥ ያሉ ፋይሎችን እና ማውጫዎችን (የግቤቶች ዛፍ) ይዘረዝራል። |
| `obsidian_get_document_map` | የማስታወሻውን የርዕስ አወቃቀር እንደ headings → line numbers ካርታ ያገኛል። |
| `obsidian_get_note_metadata` | ሙሉ ይዘቱን ሳያካትት frontmatter፣ tags፣ links እና የቁምፊ/ቃላት ብዛትን ያገኛል። |
| `obsidian_get_active_file` | በአሁኑ ጊዜ በObsidian ውስጥ ንቁ የሆነውን ፋይል path + content ያገኛል። |
| `obsidian_get_periodic_note` | ለአንድ ቀን ዕለታዊ/ሳምንታዊ/ወርሃዊ ወቅታዊ ማስታወሻን ያገኛል (ካልተገለጸ ዛሬ)። |
| `obsidian_get_tags` | ሁሉንም የvault tags ከድግግሞሻቸው ጋር ይዘረዝራል። |
| `obsidian_list_commands` | የሚገኙ የObsidian command IDsን ይዘረዝራል (ከ`obsidian_execute_command` ጋር ይጠቀሙ)። |
| `obsidian_sync_status` | የOmniRoute sync server ሁኔታ፦ እየሄደ መሆኑ፣ የvault ስም፣ port፣ uptime፣ የመጨረሻ sync። |
| `obsidian_sync_conflicts` | ያልተፈቱ sync ግጭቶችን (path፣ conflict path፣ detected-at) ይዘረዝራል። |
### የመጻፊያ መሣሪያዎች (`write:obsidian`)
| መሣሪያ | መግለጫ |
| -------------------------------- | ---------------------------------------------------------------------------- |
| `obsidian_write_note` | በተሰጠ Markdown ይዘት ማስታወሻን ይፈጥራል ወይም በላዩ ላይ ደርቦ ይጽፋል። |
| `obsidian_append_note` | ይዘትን ወደ ማስታወሻ ያክላል፤ እንደ አማራጭም ወደ ተወሰነ heading/block ያክላል። |
| `obsidian_patch_note` | በheading፣ block ወይም frontmatter field ላይ በትክክል append/prepend/replace ያደርጋል። |
| `obsidian_delete_note` | ማስታወሻን ከvault እስከመጨረሻው ይሰርዛል። |
| `obsidian_move_note` | ማስታወሻን በvault ውስጥ ያንቀሳቅሳል ወይም ስሙን ይቀይራል። |
| `obsidian_execute_command` | የObsidian commandን በcommand ID ያስፈጽማል። |
| `obsidian_open_file` | ፋይልን በObsidian ውስጥ ይከፍታል (ከሌለ ይፈጥረዋል)። |
| `obsidian_sync_trigger` | አፋጣኝ ባለሁለት አቅጣጫ desktop↔mobile vault sync ያስጀምራል። |
| `obsidian_sync_resolve_conflict` | የsync ግጭትን ይፈታል፦ `local` (mobile)፣ `remote` (desktop) ወይም `keep-both`ን ያቆያል። |
> [!NOTE]
> የ`obsidian_patch_note` targets `targetType` እንደ `heading | block | frontmatter`
> እና `operation` እንደ `append | prepend | replace` ይቀበላሉ፤
> `createTargetIfMissing` ደግሞ አማራጭ ነው። አራቱ `obsidian_sync_*` መሣሪያዎች ከአካባቢያዊው sync
> server (`http://127.0.0.1:27781` በነባሪ) ጋር ይገናኛሉ፣ እና sync token ይፈልጋሉ።
### ወሰኖች
የማንበቢያ መሣሪያዎች `read:obsidian`ን፣ የመጻፊያ መሣሪያዎች ደግሞ `write:obsidian`ን ይፈልጋሉ። ማስፈጸሙ
ከNotion ጋር ተመሳሳይ ነው — በ`open-sse/mcp-server/server.ts` ውስጥ በ`withScopeEnforcement()` ይከናወናል፣
በ`OMNIROUTE_MCP_ENFORCE_SCOPES=true` ይቆጣጠራል፣ የተፈቀዱ ወሰኖችም ከ`OMNIROUTE_MCP_SCOPES` ወይም ከAPI key scope context ይመጣሉ።
[MCP-SERVER.md](./MCP-SERVER.md)ን ይመልከቱ።
## መጨረሻ ነጥቦች
| ዘዴ | መንገድ | ዓላማ |
| -------- | ------------------------------- | ----------------------------------------------------- |
| `GET` | `/api/settings/obsidian` | `{ connected, hasToken, baseUrl, vaultPath }`ን ይመልሳል። |
| `POST` | `/api/settings/obsidian` | ቶከኑን ያስቀምጣል + ያረጋግጣል (`27124` ወደብን አይቀበልም)። |
| `DELETE` | `/api/settings/obsidian` | ግንኙነቱን ያቋርጣል (የተቀመጠውን ቶከን ያጸዳል)። |
| `GET` | `/api/settings/obsidian/webdav` | የWebDAV ማመሳሰል ሁኔታ + የመግቢያ ማረጋገጫዎች (ነቅቶ ሳለ)። |
| `POST` | `/api/settings/obsidian/webdav` | ለአንድ vault ማውጫ የWebDAV ማመሳሰልን ያነቃል። |
| `DELETE` | `/api/settings/obsidian/webdav` | የWebDAV ማመሳሰልን ያሰናክላል። |
> እነዚህ የዳሽቦርድ ቅንብሮች መንገዶች ናቸው። vault ራሱ በObsidian
> Local REST API (በተዋቀረው `base_url`) እና ከላይ ባሉት MCP መሣሪያዎች በኩል ይደረስበታል — ይፋዊ
> `/v1` Obsidian ፕሮክሲ መጨረሻ ነጥብ የለም።
## የአጠቃቀም ሁኔታዎች
- **በvault ላይ የተመሠረቱ መልሶች** — `obsidian_search_simple` / `obsidian_search_structured`
ከዚያም `obsidian_read_note`፤ ይህም ወኪሉ ከእውነተኛ ማስታወሻዎችዎ ተነስቶ እንዲመልስ ያደርጋል።
- **ማስታወሻ መጻፍ / ዕለታዊ ማስታወሻ መያዝ** — `obsidian_write_note`፣ `obsidian_append_note`፣ ወይም
የወኪሉን ውጤት፣ ማጠቃለያዎችን ወይም ዕለታዊ ማስታወሻዎችን
(`obsidian_get_periodic_note`) ወደ vault ለመመዝገብ ትክክለኛ ክፍልን የሚያርም `obsidian_patch_note`።
- **በvault ውስጥ ማሰስ** — ከማንበብ/ከመጻፍ በፊት መዋቅሩን ለማሰስ `obsidian_list_vault`፣ `obsidian_get_document_map` እና
`obsidian_get_tags`።
- **የObsidian አውቶሜሽን** — ፕለጊኖችን/ትዕዛዞችን ከወኪል ለማስኬድ `obsidian_list_commands` + `obsidian_execute_command`፤
አንድን ማስታወሻ በUI ውስጥ ለማሳየት `obsidian_open_file`።
- **የሞባይል ማመሳሰል** — የWebDAV ማመሳሰልን ያንቁ፣ ከዚያም ዴስክቶፕ↔ሞባይልን ለማስተባበር እና ግጭቶችን ለመፍታት `obsidian_sync_trigger` /
`obsidian_sync_status` / `obsidian_sync_conflicts` / `obsidian_sync_resolve_conflict`
ይጠቀሙ።
## ተዛማጅ
- [MCP ሰርቨር](./MCP-SERVER.md) — የማጓጓዣ ዘዴዎች፣ የወሰን ማስፈጸሚያ፣ ሙሉ የመሣሪያዎች ዝርዝር።
- [የNotion አውድ ምንጭ](./NOTION_CONTEXT.md) — ሌላኛው አብሮ የተካተተ የአውድ ምንጭ።
- [የማህደረ ትውስታ ሥርዓት](./MEMORY.md) — ቋሚ የውይይት ማህደረ ትውስታ (ተደጋጋፊ
የአውድ ንብርብር፣ በመሣሪያ ከመጎተት ይልቅ በራስ-ሰር የሚጨመር)።

163
docs/i18n/am/docs/frameworks/OPENCODE.md Normal file
View File

@@ -0,0 +1,163 @@
# OpenCode Integration (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/OPENCODE.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/OPENCODE.md) · 🇦🇿 [az](../../../az/docs/frameworks/OPENCODE.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/OPENCODE.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/OPENCODE.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/OPENCODE.md) · 🇩🇰 [da](../../../da/docs/frameworks/OPENCODE.md) · 🇩🇪 [de](../../../de/docs/frameworks/OPENCODE.md) · 🇬🇷 [el](../../../el/docs/frameworks/OPENCODE.md) · 🇪🇸 [es](../../../es/docs/frameworks/OPENCODE.md) · 🇪🇪 [et](../../../et/docs/frameworks/OPENCODE.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/OPENCODE.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/OPENCODE.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/OPENCODE.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/OPENCODE.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/OPENCODE.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/OPENCODE.md) · 🇮🇱 [he](../../../he/docs/frameworks/OPENCODE.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/OPENCODE.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/OPENCODE.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/OPENCODE.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/OPENCODE.md) · 🇮🇩 [id](../../../id/docs/frameworks/OPENCODE.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/OPENCODE.md) · 🇮🇹 [it](../../../it/docs/frameworks/OPENCODE.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/OPENCODE.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/OPENCODE.md) · 🇰🇭 [km](../../../km/docs/frameworks/OPENCODE.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/OPENCODE.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/OPENCODE.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/OPENCODE.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/OPENCODE.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/OPENCODE.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/OPENCODE.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/OPENCODE.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/OPENCODE.md) · 🇲🇲 [my](../../../my/docs/frameworks/OPENCODE.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/OPENCODE.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/OPENCODE.md) · 🇳🇴 [no](../../../no/docs/frameworks/OPENCODE.md) · 🇮🇳 [or](../../../or/docs/frameworks/OPENCODE.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/OPENCODE.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/OPENCODE.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/OPENCODE.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/OPENCODE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/OPENCODE.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/OPENCODE.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/OPENCODE.md) · 🇱🇰 [si](../../../si/docs/frameworks/OPENCODE.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/OPENCODE.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/OPENCODE.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/OPENCODE.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/OPENCODE.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/OPENCODE.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/OPENCODE.md) · 🇮🇳 [te](../../../te/docs/frameworks/OPENCODE.md) · 🇹🇭 [th](../../../th/docs/frameworks/OPENCODE.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/OPENCODE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/OPENCODE.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/OPENCODE.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/OPENCODE.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/OPENCODE.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/OPENCODE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/OPENCODE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/OPENCODE.md)
---
> **ሁኔታ:** በአጠቃላይ የሚገኝ።
> **ታዳሚዎች:** OpenCodeን ከOmniRoute ስርጭት ጋር የሚያገናኙ ኦፕሬተሮች።
> **ዋና የመረጃ ምንጭ (የውቅር መርሐግብር):** `src/shared/services/opencodeConfig.ts`
> **ዋና የመረጃ ምንጭ (npm ጥቅል):** `@omniroute/opencode-provider/` (ሊታተም የሚችል workspace)
[OpenCode](https://opencode.ai) ወኪል-ተኮር CLI/ዴስክቶፕ AI ደንበኛ ነው። የአቅራቢዎች ካታሎጉን ከ`~/.config/opencode/opencode.json` (ወይም `opencode.jsonc`) ያነባል፣ እንዲሁም በ`https://opencode.ai/config.json` የሚገኘውን መርሐግብር ይከተላል። OmniRoute ራሱን ለOpenCode ከእነዚያ አቅራቢዎች እንደ አንዱ ያቀርባል — እያንዳንዱ ጥያቄ በOmniRoute መደበኛ OpenAI-ተኳኋኝ `/v1` በይነገጽ በኩል ያልፋል፤ በዚህም OpenCode ከAuto-Combo ማዞሪያ፣ circuit breakers፣ የቁልፍ ፖሊሲዎች፣ ታዛቢነት እና ሌሎችም በራስ-ሰር ተጠቃሚ ይሆናል።
**ሁለት የሚደገፉ የውህደት መንገዶች** አሉ። አንዱን ይምረጡ — ሁለቱም ተመሳሳይ ውቅር ያመነጫሉ።
---
## መንገድ 1 — CLI አመንጪ (npm መጫን አያስፈልግም)
ለዋና ተጠቃሚዎች የሚመከር። ከOmniRoute ጋር አብሮ ይቀርባል። `opencode.json`ን ባለበት ቦታ ይጽፋል።
```bash
# OmniRouteን ከጫኑ በኋላ (npm i -g @omniroute/cli ወይም አካባቢያዊ clone)
omniroute config opencode \
--base-url http://localhost:20128 \
--api-key "$OMNIROUTE_API_KEY"
```
ከጀርባ CLIው `mergeOpenCodeConfigText()`ን (`src/shared/services/opencodeConfig.ts:104`) ይጠራል፤ ስለዚህ ቀድሞ ያለ `opencode.json` ሌሎች አቅራቢዎቹንና አስተያየቶቹን እንዳሉ ያቆያል። የOmniRoute ግቤት በአቶሚክ ሁኔታ ይጨመራል/ይተካል።
የሚገኘው ፋይል (ነባሪ የሞዴል ካታሎግ):
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"omniroute": {
"npm": "@ai-sdk/openai-compatible",
"name": "OmniRoute",
"options": {
"baseURL": "http://localhost:20128/v1",
"apiKey": "<your-key>",
},
"models": {
"claude-opus-4-5-thinking": { "name": "claude-opus-4-5-thinking" },
"claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
"gemini-3.1-pro-high": { "name": "gemini-3.1-pro-high" },
"gemini-3-flash": { "name": "gemini-3-flash" },
},
},
},
}
```
---
## መንገድ 2 — npm ጥቅል `@omniroute/opencode-provider`
ውቅሩን ከNode/TS በስክሪፕት ሲያዘጋጁ (CI pipelines፣ monorepos፣ ብጁ የመጫኛ ፍሰቶች) የሚመከር።
```bash
npm install --save-dev @omniroute/opencode-provider
```
```ts
import { writeFileSync } from "node:fs";
import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";
const config = buildOmniRouteOpenCodeConfig({
baseURL: "http://localhost:20128",
apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute",
// አማራጭ፦ ለOpenCode የሚቀርበውን የሞዴል ካታሎግ ይተኩ
models: ["auto", "claude-opus-4-7", "gpt-5.5"],
modelLabels: { auto: "Auto-Combo" },
});
writeFileSync("opencode.json", JSON.stringify(config, null, 2));
```
ከነባር ፋይል ጋር ሳያበላሽ ለማዋሃድ፣ ከ`opencodeConfig.ts` የሚገኘውን `mergeOpenCodeConfigText()` ያባዙ ወይም CLI አመንጪውን ይጠቀሙ።
ለሙሉ API [የጥቅሉን README](../../@omniroute/opencode-provider/README.md) ይመልከቱ።
---
## Runtimeው በትክክል የሚያደርገው
ሁለቱም መንገዶች ተመሳሳዩን `provider.omniroute.npm: "@ai-sdk/openai-compatible"` ያመነጫሉ። በruntime፣ OpenCode `@ai-sdk/openai-compatible`ን (አስቀድሞ የOpenCode transitive dependency የሆነውን) ጭኖ በ`baseURL` + `apiKey` ያዋቅረዋል። ከዚያ በኋላ፦
```
OpenCode UI/ወኪል
→ @ai-sdk/openai-compatible
→ HTTP POST {baseURL}/chat/completions (የOmniRoute OpenAI በይነገጽ)
→ OmniRoute /v1/chat/completions ተቆጣጣሪ (open-sse/handlers/chatCore.ts)
→ combo ማዞሪያ / Auto-Combo / executor
→ upstream አቅራቢ
```
pluginው HTTPን ፈጽሞ አይነካም። ውቅርን ብቻ ያመነጫል።
---
## የሞዴል ካታሎግ ነባሪዎች
```ts
export const OMNIROUTE_DEFAULT_OPENCODE_MODELS = [
"claude-opus-4-5-thinking",
"claude-sonnet-4-5-thinking",
"gemini-3.1-pro-high",
"gemini-3-flash",
] as const;
```
በ`models: [...]` መተካት ይችላሉ። የሚመከሩ ተጨማሪዎች፦
- `"auto"` — የOmniRouteን ያለምንም ውቅረት የሚሠራ [Auto-Combo](../routing/AUTO-COMBO.md) ራውተር ያቀርባል። ካታሎጉን በኮድዎ ውስጥ በቋሚነት ሳያስቀምጡ፣ OpenCode «ከሚገኙት ምርጡን ሞዴል» እንዲመርጥ ያስችለዋል።
- `"<combo-name>"` — በዳሽቦርዱ ውስጥ የገለጹት ማንኛውም ጥምረት፤ OmniRoute በግልጽነት ይፈታዋል።
---
## የURL መደበኛነት
ረዳቱ ሁለቱንም ቅጾች ይቀበላል፣ እና በትክክል አንድ `/v1` ያወጣል፦
| ግቤት | ውጤት (`options.baseURL`) |
| ------------------------------ | --------------------------- |
| `http://localhost:20128` | `http://localhost:20128/v1` |
| `http://localhost:20128/` | `http://localhost:20128/v1` |
| `http://localhost:20128/v1` | `http://localhost:20128/v1` |
| `http://localhost:20128/v1///` | `http://localhost:20128/v1` |
ይህ ድግግሞሽን የማስወገድ ሂደት በድሮ ውቅሮች ውስጥ የሚታየው **እጅግ የተለመደው የብልሽት ምክንያት** ነው። ከv3.8.0 በፊት የተፈጠረ፣ ወደ `/v1/v1/...` የሚያመለክት `opencode.json` ካለዎት፣ ጀነሬተሩን እንደገና ያስኪዱ ወይም `createOmniRouteProvider`ን እንደገና ይጥሩ።
---
## የማረጋገጫ ሁነቶች
| የOmniRoute ቅንብር | የሚመከር የ`apiKey` እሴት |
| ------------------------------------------- | -------------------------------------------------- |
| `REQUIRE_API_KEY=false` (ለአካባቢያዊ አጠቃቀም ነባሪ) | `sk_omniroute` (ቃል በቃል የሚጠቀም ቦታ ያዥ) |
| `REQUIRE_API_KEY=true` | ከዳሽቦርድ → API ቁልፎች የተገኘ እውነተኛ የእያንዳንዱ ተጠቃሚ API ቁልፍ። |
`x-api-key` + `anthropic-version` ለሚልኩ የAnthropic-አይነት ደንበኞች፣ የOmniRoute `extractApiKey` ከ`x-api-key` የሚመጣውን ቁልፍም ይቀበላል። OpenCode የOpenAIን በይነገጽ ስለሚጠቀም ሁልጊዜ `Authorization: Bearer ${apiKey}` ይልካል—እዚህ ምንም የAnthropic ልዩ አያያዝ አይተገበርም።
---
## ችግር ፍቺ
| ምልክት | ምክንያት | መፍትሔ |
| ------------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `/v1/v1/` በያዘ URL ላይ ለእያንዳንዱ ጥያቄ `404` | ከv3.8 በፊት ያለው ፕለጊን `/v1`ን ሁለት ጊዜ በመጨመሩ የቆየ ውቅር። | በመንገድ 1 ወይም 2 በመጠቀም እንደገና ያመንጩ። |
| `401 Invalid API key` | OmniRoute `REQUIRE_API_KEY=true` ተብሎ ተቀናብሯል፣ እና ቁልፉ አይታወቅም። | ቁልፉን በዳሽቦርዱ ውስጥ ይፍጠሩ፣ ወይም `REQUIRE_API_KEY=false` ያድርጉ (ለአካባቢያዊ አጠቃቀም ብቻ) እና `sk_omniroute`ን ይጠቀሙ። |
| በOpenCode UI ውስጥ የሞዴል ዝርዝሩ ባዶ ነው | ሁሉም 4 ነባሪ ሞዴሎች በOmniRoute አቅራቢ ታይነት ውስጥ ተደብቀዋል። | ያነቁዋቸውን ለማሳየት `models: ["auto", ...]`ን ያስተላልፉ። |
| OpenCode 500 ከ`cannot read property 'models'` ጋር | የቆየ OpenCode (< 0.1.x) በውስጥ የተጻፈ `models`ን አይቀበልም ነበር። | OpenCodeን የv1 ንድፍን (`opencode.ai/config.json`) ወደሚከተል ስሪት ያሻሽሉ። |
---
## በተጨማሪ ይመልከቱ
- [የAPI ማጣቀሻ](../reference/API_REFERENCE.md) — ሙሉው የOmniRoute REST አገልግሎት ወሰን
- [Auto-Combo](../routing/AUTO-COMBO.md) — `model: "auto"` ምን ማለት እንደሆነ
- [`@omniroute/opencode-provider` README](../../@omniroute/opencode-provider/README.md)
- ምንጭ፦ `src/shared/services/opencodeConfig.ts`፣ `src/lib/cli-helper/config-generator/opencode.ts`፣ `@omniroute/opencode-provider/src/index.ts`

574
docs/i18n/am/docs/frameworks/OPEN_SSE_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,574 @@
# open-sse Architecture (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇦🇿 [az](../../../az/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇬🇷 [el](../../../el/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇪🇪 [et](../../../et/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇰🇭 [km](../../../km/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇲🇲 [my](../../../my/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [or](../../../or/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇱🇰 [si](../../../si/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/OPEN_SSE_ARCHITECTURE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/OPEN_SSE_ARCHITECTURE.md)
---
> **በአጭሩ**: `open-sse/` በOmniRoute ውስጥ ያሉ ሁሉንም የLLM ጥያቄዎች የሚያንቀሳቅሰው ዋናው የዥረት ሞተር ነው። የጥያቄ ማስኬጃ ቅደም ተከተሉን፣ executors፣ services፣ MCP server እና የትርጉም ንብርብሩን የሚተገብሩ ~1,400 ፋይሎችን ይዟል። ይህ መመሪያ ክፍሎቹ እንዴት አብረው እንደሚሠሩ ያብራራል።
**ምንጭ:** `open-sse/` (የworkspace package፣ ~1,440 የሙከራ ያልሆኑ `.ts` ፋይሎች)
---
## ለምን የተለየ Workspace Package ያስፈልጋል?
`open-sse/` በOmniRoute monorepo ውስጥ **ራሱን የቻለ workspace** የሆነው በበርካታ ምክንያቶች ነው፦
1. **እንደገና መጠቀም** — `open-sse` በnpm ላይ እንደ `@omniroute/open-sse` ይታተማል፣ ስለዚህ ሌሎች ፕሮጀክቶች በተናጥል ሊጠቀሙበት ይችላሉ
2. **ግልጽ ድንበሮች** — የዥረት ሞተሩ ከOmniRoute-ተኮር UI/DB ንብርብር ተነጥሏል
3. **አፈጻጸም** — ሞተሩ የNext.js ጥገኞች የሉትም፣ ይህም በCLI/serverless አውዶች ፈጣን የመጀመሪያ ማስነሳትን ያስችላል
4. **የስሪት አስተዳደር** — `open-sse` በራሱ የጊዜ ሰሌዳ ልቀት ማድረግ ይችላል
```json
// package.json
"workspaces": ["open-sse"]
```
---
## ከፍተኛ-ደረጃ መዋቅር
```
open-sse/
├── index.ts # ይፋዊ መግቢያ ነጥብ
├── types.d.ts # ይፋዊ የtype ወደ ውጭ ላኪዎች
├── package.json # @omniroute/open-sse
├── config/ # የprovider ውቅሮች፣ ቋሚዎች፣ registries
├── executors/ # ለእያንዳንዱ provider የHTTP executors (67 + base.ts/index.ts)
├── handlers/ # የጥያቄ handlers (chatCore፣ responses፣ ወዘተ)
├── lib/ # ውስጣዊ utilities
├── mcp-server/ # Model Context Protocol server
├── services/ # ~298 የservice modules
├── transformer/ # የResponses API ቅርጸት transformer
├── translator/ # የቅርጸት ትርጉም (OpenAI ↔ Claude ↔ Gemini)
└── utils/ # የጋራ utilities (logging፣ error፣ stream፣ ወዘተ)
```
### የModule ብዛቶች
| ማውጫ | ፋይሎች | ዓላማ |
| `executors/` | 167 | ለእያንዳንዱ provider የHTTP executors (በDefaultExecutor factory የተዋሃዱ) |
| `handlers/` | 157 | የጥያቄ መግቢያ ነጥቦች (chatCore፣ responses፣ embeddings) |
| `services/` | ~536 | Routing፣ caching፣ rate limiting፣ refresh፣ ወዘተ |
| `translator/` | 56 | የቅርጸት ልወጣ (OpenAI ↔ Claude ↔ Gemini) |
| `mcp-server/` | 44 | የMCP tools እና transports |
| `utils/` | ~108 | በተለያዩ ክፍሎች የሚያገለግሉ utilities (logging፣ error፣ stream) |
| `config/` | ~339 | የProvider ውቅሮች፣ ቋሚዎች፣ registries |
---
## የጥያቄ ማስኬጃ ቅደም ተከተል
እያንዳንዱ የLLM ጥያቄ በ**5-ደረጃ የማስኬጃ ቅደም ተከተል** ውስጥ ያልፋል፦
```
┌──────────────┐
HTTP ጥያቄ │ 1. ROUTE │ የcombo መፍታት፣ የmodel ምርጫ
(Next.js route) └──────┬───────┘
│
▼
┌──────────────┐
│ 2. TRANSLATE│ የቅርጸት ልወጣ (OpenAI ↔ Claude ↔ Gemini)
└──────┬───────┘
│
▼
┌──────────────┐
│ 3. EXECUTE │ የprovider executor፣ HTTP፣ ድጋሚ ሙከራ፣ breaker
└──────┬───────┘
│
▼
┌──────────────┐
│ 4. STREAM │ የSSE ለውጥ፣ backpressure
└──────┬───────┘
│
▼
┌──────────────┐
│ 5. RECORD │ የአጠቃቀም ክትትል፣ የጥሪ ምዝግብ፣ የስህተት ምደባ
└──────┬───────┘
│
▼
HTTP ምላሽ (SSE ወይም JSON)
```
### ደረጃ 1፦ Route (services/combo.ts)
**መግቢያ ነጥብ**: በ`services/combo.ts` ውስጥ ያለው `handleComboChat()`
ጥያቄውን ወደ ተወሰነ `(provider, model, account, credentials)` tuple ይፈታል፦
- combo-ውን በID ይፈልጉ (ወይም ለ`auto/*` models ምናባዊ combo ይገንቡ)
- የrouting ስልቱን ይተግብሩ (priority፣ weighted፣ round-robin፣ ወዘተ)
- ጤናማ ያልሆኑ providersን ያጣሩ (circuit breaker)
- ቀጣዩን አዋጭ target ይምረጡ
ለ`auto/*` models፣ ይህ ደረጃ የሚከተሉትንም ያከናውናል፦
- የ**16-factor scoring** algorithmን ያስኬዳል (`services/autoCombo/`)
- በጤና፣ ወጪ፣ latency፣ ወዘተ ላይ በመመሥረት የ`provider+model` ጥምረት ይመርጣል
### ደረጃ 2፦ Translate (translator/)
የምንጭ ቅርጸቱ (ለምሳሌ፣ OpenAI) ከዒላማ ቅርጸቱ (ለምሳሌ፣ Claude) የተለየ ከሆነ፣ ጥያቄው **ይተረጎማል**፦
- System prompt → system message
- የTool ትርጓሜዎች → ለprovider የተወሰነ የtool ቅርጸት
- የReasoning/thinking parameters → ለprovider የተወሰኑ ተመጣጣኝ አማራጮች
- የMessage role normalization (`developer` → `system` ለOpenAI ላልሆኑ)
`translator/index.ts` የሚከተሉትን ያቀርባል፦
```ts
translateRequest(body, sourceFormat, targetFormat): TranslatedRequest
needsTranslation(source, target): boolean
```
### ደረጃ 3፦ Execute (executors/)
**መግቢያ ነጥብ**: `getExecutor(providerId).execute(request, options)`
ሁሉም providers በ`getExecutor()` factory fallback አማካኝነት `DefaultExecutor`ን (`executors/default.ts`) ይጠቀማሉ። executor-ው፦
- ወደ upstream የሚሄደውን URL ይገነባል (`buildUrl()`)
- ለprovider የተወሰኑ headersን ይጨምራል (`buildHeaders()`)
- የጥያቄውን body ይለውጣል (`transformRequest()`)
- የHTTP ጥያቄውን ከድጋሚ ሙከራ + exponential backoff ጋር ይልካል
- አስፈላጊ ከሆነ የauth refreshን ያስተናግዳል (OAuth providers)
ሁሉም executors `BaseExecutor`ን (`executors/base.ts`፣ 1170 LOC) ይወርሳሉ፣ ይህም የሚከተሉትን ያቀርባል፦
- የጋራ የድጋሚ ሙከራ ሎጂክ
- የProxy ውህደት
- የCircuit breaker ውህደት
- የአጠቃቀም ምዝገባ hooks
### ደረጃ 4፦ Stream (utils/stream.ts)
ለዥረት ምላሾች፣ executor-ው **ReadableStream** ይመልሳል። handler-ው፦
- በSSE transform በኩል ያሳልፋል (`createSSETransformStreamWithLogger`)
- የተቋረጡ ግንኙነቶችን ለመለየት heartbeat pingsን ይተገብራል
- የclient ግንኙነት መቋረጥን በአግባቡ ያስተናግዳል (`pipeWithDisconnect`)
- ዥረት ለማይጠቀሙ clients SSE → JSON ይለውጣል
ዥረት ላልሆኑ ምላሾች፣ executor-ው የተተነተነ JSON object ይመልሳል፣ እሱም ምንም ሳይለወጥ ይተላለፋል።
### ደረጃ 5፦ Record (services/usage.ts)
ምላሹ ከተሰጠ በኋላ (የተሳካም ሆነ ያልተሳካ)፣ አጠቃቀሙ ይመዘገባል፦
- ከምላሹ የተገኙ `prompt_tokens`፣ `completion_tokens`፣ `cached_tokens`
- ከዋጋ መረጃው የሚሰላ `cost_usd`
- `latency_ms`፣ `status`፣ እና ካልተሳካ `error_class`
- በ`usage_history` ሰንጠረዥ ውስጥ ይቀመጣል
የጥሪ ምዝግብ ቅርሶች (ከነቃ) ወደ `${DATA_DIR}/call_logs/` ይጻፋሉ።
---
## የቁልፍ ፋይሎች ጥልቅ ትንተና
### chatCore.ts (5977 መስመሮች)
**ዋናው የጥያቄ አስተናጋጅ**። መጠኑ ትልቅ ቢሆንም፣ ግልጽ መዋቅር አለው፦
```ts
// የchatCore.ts አስመሳይ መዋቅር
export async function handleChat(request: NextRequest) {
// 1. ማረጋገጫ + CORS
await authenticateRequest(request);
applyCorsHeaders(response);
// 2. የbody ማረጋገጫ
const body = await parseRequestBody(request);
// 3. ቅርጸትን መለየት + መተርጎም
const sourceFormat = detectFormat(request);
const targetFormat = getTargetFormat(providerId);
if (needsTranslation(sourceFormat, targetFormat)) {
body = translateRequest(body, sourceFormat, targetFormat);
}
// 4. የcombo ማዞሪያ
const targets = await resolveComboTargets(comboId, body);
for (const target of targets) {
try {
const result = await executeOnTarget(target, body);
await recordUsage(result);
return result;
} catch (err) {
// ወደሚቀጥለው target ቀጥል
}
}
// 5. የአደጋ ጊዜ አማራጭ
return await emergencyFallback(body);
}
```
አንድ ግዙፍ function ቢሆንም፣ ከ5-ደረጃው pipeline ጋር በሚዛመዱ **አስተያየት በተጨመረባቸው ክፍሎች** የተደራጀ ነው።
### combo.ts (4456 LOC)
አንድ combo ወደ ቅደም ተከተል የተደረደሩ targets እንዲፈታ የሚያደርገው **የማዞሪያ ሞተር**።
```ts
// services/combo.ts
export async function handleComboChat(body, comboId): Promise<ChatResult> {
const targets = await resolveComboTargets(comboId, body);
for (const target of targets) {
try {
return await handleSingleModel(target, body);
} catch (err) {
log.warn("target failed, trying next", { target, err });
}
}
throw new ComboExhaustedError("All targets failed");
}
```
**19 የማዞሪያ ስልቶችን** ይደግፋል (`src/shared/constants/routingStrategies.ts`ን ይመልከቱ)፦
| ስልት | ባህሪ |
| ------------------- | ------------------------------------------------------------- |
| `priority` | የመጀመሪያውን target ቅድሚያ የሚሰጥ የተደረደረ ዝርዝር |
| `weighted` | በእያንዳንዱ target ክብደት ላይ የተመሠረተ የዕድል ስሌት |
| `round-robin` | targetsን በቅደም ተከተል በዙር ማለፍ |
| `context-relay` | contextን በtargets መካከል ማስተላለፍ |
| `fill-first` | ወደሚቀጥለው ከመሄድ በፊት quotaን መሙላት |
| `p2c` | ከሁለት ምርጫዎች የተሻለውን መምረጥ |
| `random` | ወጥ የሆነ የዘፈቀደ ምርጫ |
| `least-used` | በቅርብ ጊዜ በትንሹ ጥቅም ላይ የዋለውን መምረጥ |
| `cost-optimized` | በመጀመሪያ በጣም ርካሹንና ጤናማውን target መምረጥ |
| `reset-aware` | የprovider reset windowsን ከግምት ውስጥ የሚያስገባ |
| `reset-window` | በreset window ላይ የተመሠረተ ማዞሪያ |
| `headroom` | ከፍተኛው ቀሪ የquota headroom ያለውን ቅድሚያ መስጠት |
| `strict-random` | በእውነት ወጥ የሆነ ምርጫ (የጥራት ክብደት የሌለው) |
| `auto` | ባለ16-ምክንያት ውጤት አሰጣጥን መጠቀም (`autoCombo/`) |
| `lkgp` | በመጨረሻ ጥሩ እንደሆነ የታወቀውን provider ቅድሚያ መስጠት |
| `context-optimized` | ረጅም context ላላቸው ጥያቄዎች ምርጥ |
| `fusion` | በትይዩ ወደ panel በስፋት መላክ፣ ከዚያም በjudge አማካይነት ማዋሃድ (`fusion.ts`) |
### base.ts (1170 LOC)
ሁሉም 107 executors የሚወርሱት **abstract executor**። የሚከተሉትን ይዟል፦
- `buildUrl()` — ነባሪ የURL ግንባታ (subclasses ለብጁ አጠቃቀም override ያደርጉታል)
- `buildHeaders()` — ነባሪ headers (auth፣ content-type)
- `transformRequest()` — በነባሪ ሳይቀየር ያስተላልፋል
- `execute()` — retry/backoff/breaker ያለው ዋናው የHTTP loop
```ts
// open-sse/executors/default.ts
export class DefaultExecutor extends BaseExecutor {
// ሁሉንም ከOpenAI/Anthropic ጋር ተኳኋኝ የሆኑ providers ያስተናግዳል
// Providers configurationsን (URL፣ auth፣ headers) ይመዘግባሉ፣ ነገር ግን የexecutor logicን ይጋራሉ
}
```
ለprovider የተለየ ባህሪ (auth headers፣ base URL፣ version headers) በተለያዩ executor classes ሳይሆን በprovider registry በኩል ይዋቀራል።
````
---
## አገልግሎቶች (117 ሞጁሎች)
አገልግሎቶች handlers በማጣመር የሚጠቀሙባቸው **በአንድ ዓላማ ላይ ያተኮሩ ሞጁሎች** ናቸው። ዋናዎቹ ምድቦች፦
### ማዘዋወር እና Combo
- `combo.ts` — በcombo ለሚዘዋወሩ ጥያቄዎች የመግቢያ ነጥብ
- `services/autoCombo/` — ባለ16-ምክንያት ነጥብ አሰጣጥ፣ 8 ራስ-ሰር የማዘዋወር ስልቶች
- `wildcardRouter.ts` — የwildcard መንገዶችን (`gpt-*`) ያዛምዳል
- `modelFamilyFallback.ts` — በT5 ቤተሰብ ውስጥ fallback
### የፍጥነት ገደብ እና ኮታ
- `rateLimitManager.ts` — ለእያንዳንዱ key+provider የtoken bucket
- `usage.ts` — የአጠቃቀም መመዝገቢያ
- `quotaCache.ts` — በማህደረ ትውስታ ውስጥ ያሉ የኮታ ቅጽበታዊ ቅጂዎች
### መለያ እና Token
- `tokenRefresh.ts` — በ401 ላይ OAuth ማደስ
- `accountFallback.ts` — ወደ አማራጭ መለያ መቀየር
- `sessionManager.ts` — የባለብዙ-ዙር session ሁኔታ
### ብልህነት
- `intentClassifier.ts` — የጥያቄውን ዓላማ መመደብ
- `taskAwareRouter.ts` — በተግባር ዓይነት ማዘዋወር
- `thinkingBudget.ts` — የአስተሳሰብ tokens መመደብ
- `contextManager.ts` — የማዘዋወር context ማስገባት
### የመቋቋም ችሎታ
- `resilience.ts` — ዳግም ሙከራ፣ backoff እና breaker ማስተባበር
- `emergencyFallback.ts` — የመጨረሻ አማራጭ fallback
- `modelDeprecation.ts` — ወደ ተተኪ models ራስ-ሰር ማዘዋወር
### ሁኔታ
- `signatureCache.ts` — በጥያቄ signature ድግግሞሽን ማስወገድ
- `volumeDetector.ts` — ጫናን መቀነስ
- `contextHandoff.ts` — session serialization
### መጭመቅ
- `compression/` (ንዑስ ማውጫ) — ሙሉ የመጭመቅ pipeline
- engines፣ rule packs እና adapters የሚሸፍኑ 39 ፋይሎች
### ክህሎቶች
- (በ[SKILLS.md](./SKILLS.md) ውስጥ ተሸፍኗል)
### ማህደረ ትውስታ
- (በ[MEMORY.md](./MEMORY.md) ውስጥ ተሸፍኗል)
---
## Executors (75+ ፋይሎች)
ለእያንዳንዱ provider አንድ ፋይል አለ። ሁሉም `BaseExecutor`ን ያራዝማሉ እና ልዩነት ያለውን ይተካሉ።
### የተለመዱ ንድፎች
Providers የሚፈቱት በ`getExecutor(providerId)` ሲሆን፣ የተዋቀረውን executor ይመልሳል። ከOpenAI/Anthropic ጋር ተኳኋኝ የሆኑ providers `DefaultExecutor`ን (`executors/default.ts`) ይጠቀማሉ። ለprovider የተለዩ ባህሪያት (base URL፣ auth headers፣ API version) በ`open-sse/config/providers/` ውስጥ ይዋቀራሉ፤ የrequest body ለውጦች ግን በ`open-sse/translator/` ውስጥ ይከናወናሉ።
**ብጁ URL** በprovider ውቅር በኩል ይቀናበራል፦
```ts
// በopen-sse/config/providers/ ውስጥ ያለ የProvider ውቅር
export default {
id: "together",
baseURL: "https://api.together.xyz/v1/chat/completions",
}
````
**ብጁ auth** በprovider registry የauth ውቅር (API key፣ OAuth፣ header profiles) በኩል ይስተናገዳል።
**ብጁ request body** ለውጦች (ለምሳሌ፣ Anthropic `system`ን ከ`messages` መለየቱ) ለእያንዳንዱ provider በ`open-sse/translator/` ውስጥ ይመዘገባሉ።
````
### የExecutor Factory
`executors/index.ts` `getExecutor(providerId)`ን export ያደርጋል፦
```ts
import { getExecutor } from "@omniroute/open-sse/executors";
const executor = getExecutor("anthropic");
const result = await executor.execute({
model: "claude-sonnet-4-5",
messages: [...],
});
````
መፍታቱ በ`ExecutorRegistry` (`executors/registry.ts`) በኩል ያልፋል፦ እያንዳንዱ ልዩ executor በ`executors/index.ts` አብሮገነብ ሰንጠረዥ ውስጥ ይገለጻል እና module በሚጫንበት ጊዜ በ`registerExecutor(alias, instance)` ይመዘገባል፤ `getExecutor()` registryውን ይፈትሻል እና ልዩ ግቤት ለሌለው ማንኛውም provider ወደ memoized `DefaultExecutor` fallback ያደርጋል። ሙሉው alias → executor ማዛመጃ በgolden test `tests/unit/executor-map-golden.test.ts` ተዘርዝሯል።
---
## ተርጓሚዎች
በ**3 ቅርጸቶች** መካከል ይተረጉማል፦ OpenAI፣ Anthropic፣ Gemini፣ እንዲሁም አዲሱ Responses API።
### ትርጉም የሚከናወነው መቼ ነው
```ts
import { needsTranslation, translateRequest } from "@omniroute/open-sse/translator";
if (needsTranslation(sourceFormat, targetFormat)) {
body = translateRequest(body, sourceFormat, targetFormat);
}
```
የተለመዱ ትርጉሞች፦
- `OpenAI → Anthropic`፦ የተለየ `system` መስክ፣ `x-api-key` ራስጌ
- `OpenAI → Gemini`፦ በ`messages` ፈንታ `contents`፣ `systemInstruction`
- `OpenAI → Responses API`፦ `input` ድርድር፣ `previous_response_id` ሁኔታ
### የሚስተናገዱ ልዩ ሁኔታዎች
- `developer` ሚና → OpenAI ላልሆኑ `system`
- `system` ሚና → ለGLM/ERNIE ከመጀመሪያው የተጠቃሚ መልዕክት ጋር ይዋሃዳል
- `json_schema` → የGemini `responseMimeType` + `responseSchema`
- `tools` → ለአቅራቢው የተለየ የመሣሪያ ቅርጸት
- የማሰብ መለኪያዎች (o1፣ Claude) → ለአቅራቢው የተለዩ አቻዎች
---
## MCP አገልጋይ
`open-sse/mcp-server/` የ**Model Context Protocol** አገልጋዩን ይተገብራል፦
- **110 መሣሪያዎች** (የአቅራቢ አስተዳደር፣ ጥምረቶች፣ ማህደረ ትውስታ፣ መሸጎጫ፣ ማመቅ፣ ተኪ፣ ክህሎቶች፣ ጨዋታዊነት፣ ተሰኪዎች፣ Notion፣ Obsidian፣ አካባቢያዊ ኮርፐስ)
- **3 ማጓጓዣዎች**፦ stdio፣ SSE፣ Streamable HTTP
- ለዝርዝር ፈቃድ አሰጣጥ **33 ወሰኖች**
### የመሣሪያ ምዝገባ
መሣሪያዎች በ`open-sse/mcp-server/tools/` ውስጥ እንደ ገለልተኛ ፋይሎች ይመዘገባሉ፤ እያንዳንዳቸው ስም፣ መርሐግብር፣ አስተናጋጅ እና ወሰን ወደ ውጭ ያቀርባሉ፦
```ts
// open-sse/mcp-server/tools/getHealth.ts
import { z } from "zod";
export default {
name: "omniroute_get_health",
description: "የስርዓት ጤንነት ቅጽበታዊ እይታን ያግኙ",
scope: "read:health",
inputSchema: z.object({}),
handler: async (_args, ctx) => {
return await getSystemHealth();
},
};
```
### ማጓጓዣዎች
```ts
// stdio (የCLI አጠቃቀም)
startMcpStdio(server);
// SSE (በHTTP ላይ የተመሠረተ ዥረት)
startMcpSse(server, port);
// Streamable HTTP (ዘመናዊ MCP)
startMcpStreamable(server, port);
```
### ፈቃድ አሰጣጥ
እያንዳንዱ የመሣሪያ ጥሪ በወሰን ማረጋገጫዎች (`open-sse/mcp-server/auth/`) ያልፋል፦
```ts
if (!hasScope(apiKey, "providers:read")) {
throw new Error("በቂ ያልሆነ ወሰን");
}
```
---
## ቀያሪዎች
`open-sse/transformer/` በ**Chat Completions** እና **Responses API** ቅርጸቶች መካከል ይቀይራል።
### የተለየ ቀያሪ ለምን ያስፈልጋል?
Responses API **ሁኔታን የሚይዙ ውይይቶች** (`previous_response_id`) ያሉት የOpenAI አዲስ ቅርጸት ነው። ደንበኛ የResponses ጥያቄ ሲልክ፣ OmniRoute፦
1. Responses → Chat Completions በውስጣዊ መንገድ ይቀይራል
2. ወደ አቅራቢው ይልካል (Chat Completionsን የሚደግፍ ማንኛውም አቅራቢ)
3. ምላሹን መልሶ ወደ Responses ቅርጸት ይቀይራል
4. የተቀየረውን ምላሽ ወደ ደንበኛው በዥረት ይልካል
ቀያሪው (`transformer/responsesTransformer.ts`) የሚከተለውን ያቀርባል፦
```ts
createResponsesApiTransformStream(): TransformStream
```
ይህ የሚከተሉትን ያስተናግዳል፦
- `response.output_item.added` ክስተቶች
- `response.output_text.delta` ክስተቶች
- `response.completed` ክስተት
- የመሣሪያ ጥሪ ማዛመድ (`function_call` ↔ `tool_calls`)
---
## ውቅር
`open-sse/config/` የውቅር ንብርብሩን ይይዛል፦
| ፋይል | ዓላማ |
| ------------------------------- | ----------------------------------- |
| `providerRegistry.ts` | በ352-አቅራቢ ካታሎግ ላይ ያለ የውይይት-ሞዴል መዝገብ |
| `providerModels.ts` | የሞዴል ተለዋጭ ስሞች፣ የቅርጸት ማዛመድ |
| `constants.ts` | የጊዜ ገደቦች፣ ገደቦች፣ የሁኔታ ኮዶች |
| `defaultThinkingSignature.ts` | ነባሪ የClaude ማሰብ ፊርማ |
| `modelStrip.ts` (በservices ውስጥ) | ለእያንዳንዱ አቅራቢ የመስክ ማስወገድ |
### የአቅራቢ መዝገብ መርሐግብር
```ts
interface ProviderConfig {
id: string;
name: string;
baseUrl: string;
authType: "bearer" | "api-key" | "oauth" | "cookie";
executorClass: string;
defaultModel: string;
capabilities: ProviderCapabilities;
models: ModelDefinition[];
}
```
ሞጁሉ ሲጫን የሚከናወነው የZod ማረጋገጫ ሁሉም የአቅራቢ ውቅሮች ትክክለኛ መሆናቸውን ያረጋግጣል።
---
## የአፈጻጸም ገደቦች
የማዘዋወሪያ ሞተሩ ጥብቅ የአፈጻጸም ገደቦች አሉት፦
| ክዋኔ | ግብ | መለኪያ |
| ---------------------------------------- | ----- | -------------------------- |
| የጥምረት መፍታት | <10ms | ለ50 ዒላማዎች |
| የፍጥነት ገደብ ማረጋገጫ | <1ms | በማህደረ ትውስታ ውስጥ ያለ የቶከን ባልዲ |
| የሞዴል ቤተሰብ አማራጭ | <5ms | የተሸጎጡ የቤተሰብ ትርጓሜዎች |
| የጥያቄ ማዘዋወሪያ ልከት | <2ms | ወሳኝ የአፈጻጸም መንገድ |
| **በወሳኙ የማዘዋወሪያ መንገድ ላይ የሚያግድ I/O አይኖርም** | — | ሁሉም ያልተመሳሰሉ |
---
## መወገድ ያለባቸው ንድፎች
❌ **በ`combo.ts` ውስጥ የተመሳሰሉ የDB ጥሪዎች** — አስቀድመው ያስሉ እና ይሸጉ
❌ **በአስተናጋጆች ውስጥ የድጋሚ ሙከራ አመክንዮ** — ከመቋቋም አገልግሎቱ `retry()`ን ይጠቀሙ
❌ **ቀጥተኛ የአቅራቢ ውቅር መዳረሻ** — የ`providerRegistry` getter-ዎችን ይጠቀሙ
❌ **በኮድ ውስጥ በቋሚነት የተጻፉ የአማራጭ ሰንሰለቶች** — በ`modelFamilyFallback.ts` ውስጥ ይግለጹ
❌ **በተጓዳኝ ጥያቄዎች መካከል የሁኔታ ለውጦች** — በጥያቄ ወሰን የተገደበ አውድ ብቻ ይጠቀሙ
---
## አዲስ ክፍል ማከል
### አዲስ አገልግሎት ማከል
1. በተወሰነ ኃላፊነት `open-sse/services/[serviceName].ts`ን ይፍጠሩ
2. ዋናውን የአስተናጋጅ ፈንክሽን እና ማናቸውንም ቋሚዎች ወደ ውጭ ይላኩ
3. በ`tests/unit/services/[serviceName].test.mjs` ውስጥ የክፍል ሙከራዎችን ያክሉ
4. ከማዘዋወር ጋር የተያያዘ ከሆነ በ`handlers/chatCore.ts` ውስጥ ካለው የጥያቄ ሂደት ጋር ያዋህዱ
5. አገልግሎቱ የዒላማ ምርጫን የሚነካ ከሆነ በ`combo.ts` ውስጥ ያለውን የማዘዋወሪያ አመክንዮ ያዘምኑ
6. በዚህ ፋይል ውስጥ ይመዝግቡ
### አዲስ አስፈጻሚ ማከል
1. `BaseExecutor`ን የሚያራዝም `open-sse/executors/[provider].ts` ይፍጠሩ
2. በ`config/providerRegistry.ts` ውስጥ ይመዝግቡ
3. ወደ `executors/index.ts` ፋብሪካ ያክሉ
4. ለአስፈጻሚው የክፍል ሙከራዎችን ያክሉ
5. በ`docs/architecture/ARCHITECTURE.md` ውስጥ ይመዝግቡ
### አዲስ የMCP መሣሪያ ማከል
1. `open-sse/mcp-server/tools/[category]Tools.ts`ን ይፍጠሩ ወይም ያዘምኑ
2. ለግብዓቶች የZod ንድፍ ይግለጹ
3. መሣሪያውን በ`mcp-server/index.ts` ውስጥ ይመዝግቡ
4. በ`mcp-server/auth/` ውስጥ ወዳለው የወሰን ማትሪክስ ያክሉ
5. የክፍል ሙከራዎችን ያክሉ
---
## በተጨማሪ ይመልከቱ
- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — ከፍተኛ ደረጃ ሥነ ሕንፃ
- [CODEBASE_DOCUMENTATION.md](../architecture/CODEBASE_DOCUMENTATION.md) — የምህንድስና ማጣቀሻ
- [REPOSITORY_MAP.md](../architecture/REPOSITORY_MAP.md) — በማውጫ የተከፋፈለ መግለጫ
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — ባለ16-ንጥረ ነገር ነጥብ አሰጣጥ
- [MCP-SERVER.md](./MCP-SERVER.md) — MCP አገልጋይ
- [A2A-SERVER.md](./A2A-SERVER.md) — A2A አገልጋይ
- ምንጭ፦ `open-sse/` (400+ ፋይሎች፣ ~143K LOC)

208
docs/i18n/am/docs/frameworks/PLAYGROUND_STUDIO.md Normal file
View File

@@ -0,0 +1,208 @@
# Playground Studio (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/PLAYGROUND_STUDIO.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇦🇿 [az](../../../az/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇩🇰 [da](../../../da/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇩🇪 [de](../../../de/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇬🇷 [el](../../../el/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇪🇸 [es](../../../es/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇪🇪 [et](../../../et/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇱 [he](../../../he/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇩 [id](../../../id/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇹 [it](../../../it/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇰🇭 [km](../../../km/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇲🇲 [my](../../../my/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇳🇴 [no](../../../no/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [or](../../../or/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇱🇰 [si](../../../si/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇮🇳 [te](../../../te/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇹🇭 [th](../../../th/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/PLAYGROUND_STUDIO.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/PLAYGROUND_STUDIO.md)
---
> **ባህሪ:** Playground Studio — ለ `/dashboard/playground` የተዋሃደ የAI መሞከሪያ የስራ ቦታ።
> **ዕቅዶች:** `17-playground-studio-redesign.plan.md` + `_orchestration/master-plan-group-C.md`
> **ሁኔታ:** በ v3.8.6 ተለቋል
---
## አጠቃላይ እይታ
Playground Studio `/dashboard/playground`ን ከቀላል Monaco-ተኮር አርታዒ ወደ
ሙሉ ባህሪያት ያሉት የሙከራ የስራ ቦታ ይቀይረዋል። አራት ትሮችን እና የጋራ ውቅር ፓነልን በሚያሳይ `PlaygroundStudio`
ሼል የቀድሞውን `page.tsx` ይተካል።
```
┌ Playground ──────────────────────────────────────────────────────────┐
│ [💬 ውይይት] [⚖ አወዳድር] [{} API] [🔧 ገንባ] 142↑ 38↓ · $0.002 </>│
├──────────────────────────────────────────┬───────────────────────────┤
│ {የነቃው ትር ይዘት} │ ─ ውቅር │
│ │ የመዳረሻ ነጥብ [chat ∨] │
│ │ ሞዴል [gpt-5.4 ∨] │
│ │ ስርዓት [የጽሑፍ ሳጥን] │
│ │ ሙቀት ▕▕▔▔ 0.7 │
│ │ ቅድመ-ቅንብሮች [▾ ጫን][አስቀምጥ]│
│ │ [✨ ጥያቄውን አሻሽል] │
└──────────────────────────────────────────┴───────────────────────────┘
```
---
## ትሮች
### የውይይት ትር
`ChatPlayground.tsx`ን ወደ ባለብዙ-ዙር የቀጥታ ዥረት የስራ መድረክ ያሳድገዋል፦
- በ `MarkdownMessage.tsx` አማካኝነት ሙሉ የmarkdown ማቅረብ (የኮድ ብሎኮች፣ ሰንጠረዦች፣ ዝርዝሮች፣ አገናኞች)።
- ከጋራ የውቅር ፓነሉ የሚመጣ የስርዓት ጥያቄ።
- የእያንዳንዱ መልዕክት ቶከን/ወጪ (የጥያቄ + የማጠናቀቂያ ቶከኖች)።
- የመጨረሻውን ምላሽ እንደገና ማመንጨት።
- በSSE የቀጥታ ዥረት `POST /v1/chat/completions` ይልካል።
### የማወዳደሪያ ትር
ለፕሮክሲ ዋናው ልዩነት፦ 1 ጥያቄን በአንድ ጊዜ እስከ **4 ሞዴሎች ላይ በትይዩ** ያሂዱ።
- እስከ 4 ዓምዶች፤ እያንዳንዳቸው ከ `/v1/chat/completions` በተናጥል የቀጥታ ዥረት ያሳያሉ።
- ዓምዶችን ለመጨመር `+ ሞዴል ጨምር` አዝራር (የCmd+K አቋራጭ)።
- `ሁሉንም አስኪድ ▶` `Promise.all`ን + ለእያንዳንዱ ዓምድ `AbortController`ን በመጠቀም ሁሉንም ዥረቶች በአንድ ጊዜ ያስጀምራል።
- አጠቃላይ **ሁሉንም ሰርዝ** በሂደት ላይ ያሉ ዥረቶችን በሙሉ ያቋርጣል።
- የእያንዳንዱ ዓምድ `ProviderMetrics` TTFT፣ TPS፣ ቶከኖችን እና የተገመተ ወጪን በቅጽበት ያሳያል።
- መለኪያዎች **"የደንበኛ-ወገን ግምት"** (D12) ተብለው ተሰይመዋል — ከመጀመሪያው የSSE ቁራጭ ጀምሮ የሚለኩ።
### የAPI ትር
ለላቁ ተጠቃሚዎች የመጀመሪያውን Monaco አርታዒ 100% ይጠብቃል (D14)፦
- 10 የመዳረሻ ነጥቦች፦ የውይይት ማጠናቀቂያዎች፣ ማጠናቀቂያዎች፣ embeddings፣ ምስሎች፣ ድምፅ፣ ንግግር፣ ጽሑፍ-ወደ-ንግግር ቅጂዎች፣ ማጣሪያዎች፣ ዳግም-ደረጃ ማውጣት፣ ፍለጋ።
- ባለብዙ-ሞዳል ፋይል መስቀል።
- በቅጽበት ውጤት የሚያሳይ የSSE የቀጥታ ዥረት።
- እንደ `ApiTab.tsx` ተጠቅልሏል (በፍላጎት ጊዜ የሚጫን፣ `ssr: false`)።
### የግንባታ ትር
የመሳሪያዎች/ፈንክሽን ጥሪ እና የተዋቀረ ውጤት UI፦
- `ToolsBuilder.tsx` — ለእያንዳንዱ መሳሪያ በJSON ንድፍ አርታዒ `tools[]`ን መጨመር/ማርትዕ/ማስወገድ።
መለኪያዎችን በ `ToolDefinitionSchema` (Zod) ያረጋግጣል።
- `StructuredOutputEditor.tsx` — የJSON ሁነታን ማብራት/ማጥፋት + የJSON ንድፍ አርታዒ።
ምላሹን በንድፉ መሠረት በ `StructuredOutputSchema` (Zod) ያረጋግጣል።
- ጥያቄውን `tools[]` እና/ወይም `response_format` ጋር ወደ `/v1/chat/completions` ይልካል።
## የውቅር ፓነል (የጋራ)
`StudioConfigPane.tsx` — ሁልጊዜ የሚታይ፣ ሊታጠፍ የሚችል።
| መስክ | ኮምፖነንት | ማስታወሻዎች |
| ----------- | --------------------- | ---------------------------------------------------------------------- |
| መድረሻ | `<select>` | ከ`PlaygroundEndpoint` ጋር የሚዛመዱ 10 አማራጮች |
| ሞዴል | `<input>` | ነፃ ጽሑፍ፣ ለምሳሌ `openai/gpt-4o` |
| የስርዓት መጠየቂያ | `<textarea>` | ወደ ሁሉም ትሮች ይገባል |
| መለኪያዎች | `ParamSliders` | temperature, max_tokens, top_p, presence/frequency penalty, seed, stop |
| ቅድመ-ቅንብሮች | `PresetPicker` | በስም የተቀመጡ የውቅር ቅጽበተ-ፎቶዎችን ይጫናል/ያስቀምጣል (በDB ውስጥ የሚቆዩ) |
| መጠየቂያን አሻሽል | `ImprovePromptButton` | የኮታ ማስጠንቀቂያ ሞዳልን ይከፍታል፣ `/api/playground/improve-prompt`ን ይጠራል |
ሁኔታው ወደ `PlaygroundStudio.tsx` ከፍ ተደርጎ ለሁሉም ትሮች ይተላለፋል። ትሮችን
መቀየር የውቅሩን ሁኔታ እንዳለ ያቆየዋል።
---
## የላይኛው አሞሌ
`StudioTopBar.tsx`:
- የትር መቀየሪያ (role="tablist")።
- `TokenCostCounter` — የቀጥታ ቶከን (↑/↓) እና የተገመተ ወጪ ማሳያ።
- ኮድ ወደ ውጭ መላኪያ አዝራር (`</>`) — `ExportCodeModal`ን ይከፍታል።
---
## የኮድ ወደ ውጭ መላኪያ ሞዳል
`ExportCodeModal.tsx` ከአሁኑ `PlaygroundState` የcurl / Python / TypeScript ቅንጥቦችን
ለማመንጨት `codeExport.ts`ን ይጠቀማል። የAPI ቁልፍ ቦታ ያዥ ሁልጊዜ `$OMNIROUTE_API_KEY` (D11) ነው።
---
## የመጠየቂያ ማሻሻያ
`ImprovePromptButton.tsx` → `useImprovePrompt.ts` → `POST /api/playground/improve-prompt`:
1. ሞዳሉ "ኮታ ይጠቀማል" ብሎ ያስጠነቅቃል።
2. ሲረጋገጥ፣ `{ system, prompt, model, tone }`ን ወደ ሩቱ ይልካል።
3. ሩቱ `promptImprover.META_SYSTEM_PROMPT`ን በመጠቀም በውስጥ `/v1/chat/completions`ን ይጠራል።
4. `{ improvedSystem?, improvedPrompt?, tokensIn, tokensOut }`ን ይመልሳል።
5. UI የውቅር ፓነሉን የስርዓት መጠየቂያ እና የውይይት ትሩን የተጠቃሚ መጠየቂያ ያዘምናል።
---
## ቅድመ-ቅንብሮች
`PresetPicker.tsx` → `usePresets.ts` → `/api/playground/presets/*`:
- በ`playground_presets` SQLite ሰንጠረዥ ውስጥ ይከማቻሉ (ፍልሰት `084_playground_presets.sql`)።
- እያንዳንዱ ቅድመ-ቅንብር የሚያከማቸው፦ `name`፣ `endpoint`፣ `model`፣ `system`፣ `params_json`፣ `created_at`።
- CRUD፦ `GET` ዝርዝር፣ `POST` መፍጠር፣ `GET /:id`፣ `PUT /:id`፣ `DELETE /:id`።
---
## የዥረት መለኪያዎች
`useStreamMetrics.ts` + `streamMetrics.ts` (ንጹሕ ፋንክሽን):
- `start()` — ጥያቄው የተጀመረበትን ጊዜ ይመዘግባል።
- `onFirstChunk()` — TTFTን ይመዘግባል።
- `onChunk(n)` — የማጠናቀቂያ ቶከኖችን ብዛት ያጠራቅማል።
- `finish(usage?)` — የመጨረሻ መለኪያዎችን ያሰላል፦ `ttftMs`፣ `totalMs`፣ `tps`፣ `tokensIn`፣ `tokensOut`፣ `costUsd`።
- የዋጋ መረጃው በ`src/lib/playground/types.ts` ውስጥ ካለው ቋሚ ሰንጠረዥ ይመጣል ("የተገመተ" የሚል መለያ አለው — D13)።
---
## የጀርባ ክፍል ሩቶች
| ሜተድ | ዱካ | ተቆጣጣሪ |
| -------- | -------------------------------- | --------------------------------------------------------------------------------- |
| `POST` | `/api/playground/improve-prompt` | `ImprovePromptRequestSchema`ን በZod ያረጋግጣል፤ በሜታ-መጠየቂያ `/v1/chat/completions`ን ይጠራል |
| `GET` | `/api/playground/presets` | `{ presets: PlaygroundPresetListItem[] }`ን ይመልሳል |
| `POST` | `/api/playground/presets` | ቅድመ-ቅንብር ይፈጥራል፤ `PlaygroundPresetCreateSchema`ን ያረጋግጣል |
| `GET` | `/api/playground/presets/:id` | አንድ ቅድመ-ቅንብር ወይም 404ን ይመልሳል |
| `PUT` | `/api/playground/presets/:id` | ከፊል ዝማኔ |
| `DELETE` | `/api/playground/presets/:id` | 204 |
ማረጋገጫ፦ አማራጭ (`REQUIRE_API_KEY`)። ስህተቶች በ`buildErrorBody()` በኩል (ጥብቅ ደንብ #12)።
---
## ቁልፍ ፋይሎች
| ዱካ | ዓላማ |
| -------------------------------------------------------------------------- | ------------------------------------------- |
| `src/app/(dashboard)/dashboard/playground/PlaygroundStudio.tsx` | የሼል ኮምፖነንት፣ የትሮች አስተባባሪ |
| `src/app/(dashboard)/dashboard/playground/components/StudioTopBar.tsx` | ትሮች + ቆጣሪ + የወደ ውጭ መላኪያ አዝራር |
| `src/app/(dashboard)/dashboard/playground/components/StudioConfigPane.tsx` | የጋራ ውቅረት ፓነል |
| `src/app/(dashboard)/dashboard/playground/components/tabs/ChatTab.tsx` | የውይይት የሥራ ቦታ |
| `src/app/(dashboard)/dashboard/playground/components/tabs/CompareTab.tsx` | የበርካታ ሞዴሎች ንጽጽር |
| `src/app/(dashboard)/dashboard/playground/components/tabs/ApiTab.tsx` | Monaco አርታዒ (እንደተጠበቀ) |
| `src/app/(dashboard)/dashboard/playground/components/tabs/BuildTab.tsx` | መሣሪያዎች + የተዋቀረ ውጤት |
| `src/app/(dashboard)/dashboard/playground/components/ExportCodeModal.tsx` | የኮድ ወደ ውጭ መላኪያ ሞዳል |
| `src/app/(dashboard)/dashboard/playground/components/CompareColumn.tsx` | ነጠላ የንጽጽር ዓምድ |
| `src/app/(dashboard)/dashboard/playground/components/ProviderMetrics.tsx` | የTTFT/TPS ማሳያ |
| `src/app/(dashboard)/dashboard/playground/hooks/useStreamMetrics.ts` | በደንበኛ ወገን ያለ የመለኪያ ሁክ |
| `src/app/(dashboard)/dashboard/playground/hooks/usePresets.ts` | የቅድመ-ቅንብሮች CRUD ሁክ |
| `src/app/(dashboard)/dashboard/playground/hooks/useImprovePrompt.ts` | ጥያቄ-ማሻሻያ ሁክ |
| `src/lib/playground/codeExport.ts` | curl/Python/TS አመንጪ (ከSearch Tools ጋር የሚጋራ) |
| `src/lib/playground/promptImprover.ts` | የሜታ-ጥያቄ ገንቢ |
| `src/lib/playground/streamMetrics.ts` | ንጹህ የመለኪያዎች ስሌት |
| `src/lib/db/playgroundPresets.ts` | የDB ሞጁል (CRUD) |
| `src/app/api/playground/improve-prompt/route.ts` | የጥያቄ-ማሻሻያ REST መስመር |
| `src/app/api/playground/presets/route.ts` | የቅድመ-ቅንብሮች ዝርዝር + መፍጠር |
| `src/app/api/playground/presets/[id]/route.ts` | ቅድመ-ቅንብሮችን ማግኘት/ማዘመን/መሰረዝ |
| `src/lib/db/migrations/084_playground_presets.sql` | የDB ፍልሰት |
---
## ችግር መፍታት
| ምልክት | ምክንያት | መፍትሔ |
| -------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
| Monaco አርታዒ በAPI ትር ውስጥ አይታይም | SSR Monacoን ጭኗል | `ApiTab` የ`dynamic(..., { ssr: false })` አጠቃቀምን ያረጋግጡ |
| የንጽጽር ዥረቶች በቅደም ተከተል ይጀምራሉ | የተሳሳተ የ`Promise.all` አጠቃቀም | ሁሉም የዥረት ጅምሮች በአንድ የ`Promise.all` ጥሪ ውስጥ መላክ አለባቸው |
| መለኪያዎች `null` TTFT ያሳያሉ | የመጀመሪያው ቁራጭ ተቆጣጣሪ አልተገናኘም | በSSE አንባቢ ዙር ውስጥ `useStreamMetrics.onFirstChunk()` መጠራቱን ያረጋግጡ |
| ቅድመ-ቅንብሩ አይቀመጥም | የDB ሽግግር አልተካሄደም | `npm run db:migrate`ን ያስኪዱ ወይም አገልጋዩን እንደገና ያስጀምሩ (ሽግግሩ ሲጀመር በራስ-ሰር ይከናወናል) |
| መጠየቂያን ማሻሻል 502 ይመልሳል | ሞዴል በConfig ውስጥ አልተቀናበረም | ተጠቃሚው ከማሻሻሉ በፊት በConfig ፓነል ውስጥ የሞዴል ስም ማስገባት አለበት |
| የተላከው ኮድ `MISSING_API_KEY`ን ያሳያል | ቦታ-ያዥ አልገባም | `codeExport.ts` ሁልጊዜ `API_KEY_PLACEHOLDER = "$OMNIROUTE_API_KEY"`ን ይጠቀማል |
---
## ማጣቀሻዎች
- ዋና ዕቅድ፦ `_tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md`
- የባህሪ ዕቅድ፦ `_tasks/features-v3.8.6/refactorpages/17-playground-studio-redesign.plan.md`
- የኮድ ላኪ፦ `src/lib/playground/codeExport.ts`
- የመጠየቂያ ማሻሻያ፦ `src/lib/playground/promptImprover.ts`
- Search Tools Studio፦ `docs/frameworks/SEARCH_TOOLS_STUDIO.md`

118
docs/i18n/am/docs/frameworks/PLUGINS.md Normal file
View File

@@ -0,0 +1,118 @@
# OmniRoute CLI Plugin System (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/PLUGINS.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/PLUGINS.md) · 🇦🇿 [az](../../../az/docs/frameworks/PLUGINS.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/PLUGINS.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/PLUGINS.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/PLUGINS.md) · 🇩🇰 [da](../../../da/docs/frameworks/PLUGINS.md) · 🇩🇪 [de](../../../de/docs/frameworks/PLUGINS.md) · 🇬🇷 [el](../../../el/docs/frameworks/PLUGINS.md) · 🇪🇸 [es](../../../es/docs/frameworks/PLUGINS.md) · 🇪🇪 [et](../../../et/docs/frameworks/PLUGINS.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/PLUGINS.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/PLUGINS.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/PLUGINS.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/PLUGINS.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/PLUGINS.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/PLUGINS.md) · 🇮🇱 [he](../../../he/docs/frameworks/PLUGINS.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/PLUGINS.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/PLUGINS.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/PLUGINS.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/PLUGINS.md) · 🇮🇩 [id](../../../id/docs/frameworks/PLUGINS.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/PLUGINS.md) · 🇮🇹 [it](../../../it/docs/frameworks/PLUGINS.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/PLUGINS.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/PLUGINS.md) · 🇰🇭 [km](../../../km/docs/frameworks/PLUGINS.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/PLUGINS.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/PLUGINS.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/PLUGINS.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/PLUGINS.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/PLUGINS.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/PLUGINS.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/PLUGINS.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/PLUGINS.md) · 🇲🇲 [my](../../../my/docs/frameworks/PLUGINS.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/PLUGINS.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/PLUGINS.md) · 🇳🇴 [no](../../../no/docs/frameworks/PLUGINS.md) · 🇮🇳 [or](../../../or/docs/frameworks/PLUGINS.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/PLUGINS.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/PLUGINS.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/PLUGINS.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/PLUGINS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/PLUGINS.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/PLUGINS.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/PLUGINS.md) · 🇱🇰 [si](../../../si/docs/frameworks/PLUGINS.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/PLUGINS.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/PLUGINS.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/PLUGINS.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/PLUGINS.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/PLUGINS.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/PLUGINS.md) · 🇮🇳 [te](../../../te/docs/frameworks/PLUGINS.md) · 🇹🇭 [th](../../../th/docs/frameworks/PLUGINS.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/PLUGINS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/PLUGINS.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/PLUGINS.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/PLUGINS.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/PLUGINS.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/PLUGINS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/PLUGINS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/PLUGINS.md)
---
የ`omniroute` ዋና ክፍልን ሳያሻሽሉ CLI-ውን ያስፋፉ። ፕለጊኖች ከ`gh extension` ወይም `kubectl plugin` ጋር በሚመሳሰል መልኩ የ`omniroute-cmd-*` ስያሜ ስምምነትን ይከተላሉ።
## ፈጣን አጀማመር
```bash
# ፕለጊንን ከ-npm ይጫኑ
omniroute plugin install stripe
# በልማት ላይ ያለ አካባቢያዊ ፕለጊን ይጫኑ
omniroute plugin install ./my-plugin
# የተጫኑ ፕለጊኖችን ይዘርዝሩ
omniroute plugin list
# አዲስ ፕለጊን መሠረታዊ መዋቅር ይፍጠሩ
omniroute plugin scaffold myplugin
cd omniroute-cmd-myplugin
omniroute plugin install .
```
## የፕለጊን አወቃቀር
ፕለጊን `omniroute-cmd-<name>` (ወይም `@scope/omniroute-cmd-<name>`) የተሰኘ npm ፓኬጅ ነው።
```
omniroute-cmd-myplugin/
├── package.json # "type": "module" እና "main": "index.mjs" ሊኖሩት ይገባል
├── index.mjs # register(program, ctx) እና አማራጭ metaን ይልካል
└── README.md
```
### `package.json`
```json
{
"name": "omniroute-cmd-myplugin",
"version": "0.1.0",
"type": "module",
"main": "index.mjs",
"engines": { "omniroute": ">=4.0.0" },
"keywords": ["omniroute-plugin", "omniroute-cmd"]
}
```
### `index.mjs`
```js
export const meta = {
name: "myplugin",
version: "0.1.0",
description: "My plugin for OmniRoute",
omnirouteApi: ">=4.0.0",
};
export function register(program, ctx) {
program
.command("myplugin")
.description(meta.description)
.option("-n, --name <name>")
.action(async (opts, cmd) => {
const gOpts = cmd.optsWithGlobals();
const res = await ctx.apiFetch("/api/combos", {
baseUrl: gOpts.baseUrl,
apiKey: gOpts.apiKey,
});
const data = await res.json();
ctx.emit(data, gOpts);
});
}
```
## የፕለጊን አውድ API
ወደ `register(program, ctx)` የሚተላለፈው `ctx` ኦብጀክት፦
| ባህሪ | ዓይነት | መግለጫ |
| ---------------------------- | ---------------- | ---------------------------------------------------- |
| `ctx.apiFetch(path, opts)` | `async function` | ወደ OmniRoute ሰርቨር ማንነት የተረጋገጠ fetch |
| `ctx.emit(data, opts)` | `function` | በ`--output` ፍላግ መሠረት በtable/json/jsonl/csv ውጤት ያቀርባል |
| `ctx.t(key)` | `async function` | የi18n ትርጉም ፍለጋ |
| `ctx.withSpinner(label, fn)` | `async function` | async fnን በora spinner ይከብባል |
| `ctx.baseUrl` | `string` | የተወሰነው መሠረታዊ URL |
| `ctx.apiKey` | `string \| null` | ከቀረበ API key |
## ማግኘት
ፕለጊኖች ከሚከተሉት ቦታዎች ይገኛሉ፦
1. `~/.omniroute/plugins/<name>/` — የተጠቃሚ-አካባቢያዊ ጭነቶች
2. `OMNIROUTE_PLUGIN_PATH` env var — ብጁ ማውጫ
ሁለቱም **ለCLI ብቻ** ናቸው። የሰርቨር-ወገን ፕለጊን runtime (በproxy ውስጥ የሚሰሩት marketplace/`plugin.json`
ፕለጊኖች) የራሱ መቃኛ እና የራሱ override የሆነው
`OMNIROUTE_PLUGINS_DIR` አለው —
[PLUGIN_MARKETPLACE.md → የፕለጊን ማውጫ](./PLUGIN_MARKETPLACE.md#plugin-directory)ን ይመልከቱ።
አንዱን ማዋቀር በሌላው ላይ ተጽዕኖ አያሳድርም።
የመጫን ስህተቶች ተይዘው እንደ ማስጠንቀቂያዎች ይታተማሉ — የተበላሸ ፕለጊን CLI-ውን ፈጽሞ አያበላሽም።
## ደህንነት
ፕለጊኖች ከ`omniroute` ጋር በተመሳሳይ የNode.js ፕሮሰስ ፈቃዶች ይሰራሉ። ፕለጊኖችን ከሚያምኗቸው ምንጮች ብቻ ይጫኑ። `omniroute plugin install` ግልጽ ማስጠንቀቂያ ያሳያል፣ እንዲሁም `--yes` ወይም በይነተገናኝ ማረጋገጫ ይጠይቃል።
## ማተም
1. `package.json` `"keywords": ["omniroute-plugin"]` እንዳለው ያረጋግጡ
2. እንደተለመደው `npm publish` ያድርጉ
3. ተጠቃሚዎች `omniroute plugin search <query>`ን በመጠቀም ያገኙታል (የnpm registryን ይፈልጋል)
## የፕለጊን ምሳሌ
`meta` + `register()` ያለውን አነስተኛ የሚሰራ ምሳሌ ለማየት [`examples/omniroute-cmd-hello/`](../../examples/omniroute-cmd-hello/index.mjs)ን ይመልከቱ።

361
docs/i18n/am/docs/frameworks/PLUGIN_MARKETPLACE.md Normal file
View File

@@ -0,0 +1,361 @@
# Plugin Marketplace (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/PLUGIN_MARKETPLACE.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇦🇿 [az](../../../az/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇩🇰 [da](../../../da/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇩🇪 [de](../../../de/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇬🇷 [el](../../../el/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇪🇸 [es](../../../es/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇪🇪 [et](../../../et/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇱 [he](../../../he/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇩 [id](../../../id/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇹 [it](../../../it/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇰🇭 [km](../../../km/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇲🇲 [my](../../../my/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇳🇴 [no](../../../no/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [or](../../../or/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇱🇰 [si](../../../si/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇮🇳 [te](../../../te/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇹🇭 [th](../../../th/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/PLUGIN_MARKETPLACE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/PLUGIN_MARKETPLACE.md)
---
> **ዋና የመረጃ ምንጭ:** `src/lib/plugins/` (`marketplace.ts`, `manager.ts`, `manifest.ts`,
> `scanner.ts`, `loader.ts`), `src/app/api/plugins/`፣ እና
> `src/app/(dashboard)/dashboard/plugins/`
> **ለመጨረሻ ጊዜ የተዘመነው:** 2026-06-28 — v3.8.40
OmniRoute የWordPress አይነት የፕለጊን ሥርዓትን ያካትታል። ፕለጊኖች ራሳቸውን የቻሉ
ማውጫዎች ናቸው — እያንዳንዳቸው `plugin.json` ማኒፌስት እና የመግቢያ ፋይል አላቸው — እና
ከጥያቄ ሂደቱ (`onRequest` / `onResponse` / `onError`) እንዲሁም ከ
የሕይወት ዑደት ክስተቶች (`onInstall` / `onActivate` / `onDeactivate` / `onUninstall`) ጋር ይገናኛሉ።
**የፕለጊን ገበያው** በዚህ ሥርዓት ላይ የተገነባው የማግኛ ንብርብር ነው። ሊጫኑ
የሚችሉ ፕለጊኖችን ለማሰስ የሚያስችል ካታሎግ ያቀርባል። በነባሪነት ካታሎጉ
አነስተኛ አብሮገነብ የመነሻ ሬጅስትሪ ነው፤ አንድ ኦፕሬተር ወደ ብጁ የርቀት
ሬጅስትሪ URL ሊያመለክተው ይችላል፤ በዚያ ጊዜ የማምጣት ሂደቱ DNS በሚፈታ SSRF መከላከያ
ይጠናከራል ([ደህንነት](#security)ን ይመልከቱ)።
እያንዳንዱ የፕለጊን መስመር **ለloopback ብቻ** ነው (ደረጃ 1 — `LOCAL_ONLY`)፦ ፕለጊኖች በ
child processes ውስጥ ኮድን ይጭናሉ እና ያስፈጽማሉ፤ ስለዚህ የማረጋገጫ ሁኔታው ምንም ይሁን ምን መስመሮቹ
loopback ካልሆነ መነሻ ሊደረስባቸው አይችልም።
[`docs/security/ROUTE_GUARD_TIERS.md`](../security/ROUTE_GUARD_TIERS.md)ን ይመልከቱ።
## ክፍሎቹ እንዴት አብረው እንደሚሠሩ
```
ዳሽቦርድ (/dashboard/plugins)
├─ "የተጫኑ" ትር → GET /api/plugins (listPlugins)
│ POST /api/plugins/scan (pluginManager.scan)
│ POST /api/plugins/{name}/activate|deactivate
│ DELETE /api/plugins/{name} (ማራገፍ)
└─ "ገበያ" ትር → GET /api/plugins/marketplace
→ listMarketplacePlugins()
├─ ብጁ URL የለም → አብሮገነብ SEED_REGISTRY
└─ ብጁ URL → isSafeMarketplaceUrl() SSRF መከላከያ
→ safeOutboundFetch(guard:"public-only")
```
- **የሬጅስትሪ ንብርብር** — `src/lib/plugins/marketplace.ts`፦ ካታሎጉን ይዘረዝራል / ይፈልጋል፤
ማንኛውም ችግር ሲከሰት ወደ መነሻ ሬጅስትሪው ይመለሳል።
- **የሕይወት ዑደት ንብርብር** — `src/lib/plugins/manager.ts` (`pluginManager` singleton)፦
መጫን፣ ማሻሻል፣ ማግበር፣ ማቦዘን፣ ማራገፍ፣ መቃኘት እና በጅማሬ ጊዜ መጫን።
- **የማኒፌስት ንብርብር** — `src/lib/plugins/manifest.ts`፦ ለ
`plugin.json` የZod ስኪማ + ነባሪ እሴቶች።
- **ስካነር** — `src/lib/plugins/scanner.ts`፦ በፕለጊን ማውጫው ሥር በዲስክ ላይ
ያሉ ፕለጊኖችን ያገኛል።
- **ጫኝ** — `src/lib/plugins/loader.ts`፦ እያንዳንዱን ፕለጊን በተለየ
child process ውስጥ ያስጀምራል፣ እንዲሁም የhook ጥሪዎችን በIPC በኩል ያስተላልፋል።
## የገበያ ካታሎግ
`listMarketplacePlugins()` (`src/lib/plugins/marketplace.ts`) የ
`MarketplaceEntry` ኦብጀክቶችን ዝርዝር ይመልሳል፦
| መስክ | ዓይነት | ማስታወሻዎች |
| ------------- | -------- | --------------------------- |
| `name` | string | በkebab-case የተጻፈ የፕለጊን ስም |
| `version` | string | semver |
| `description` | string | አጭር ማጠቃለያ |
| `author` | string | ደራሲ / ድርጅት |
| `license` | string | የSPDX አይነት የፈቃድ መታወቂያ |
| `downloadUrl` | string | የምንጭ ማውረጃ URL (ባዶ ሊሆን ይችላል) |
| `repository` | string? | አማራጭ የማከማቻ URL |
| `tags` | string[] | የፍለጋ/ማጣሪያ መለያዎች |
| `downloads` | number | የማውረድ ብዛት |
| `rating` | number | 0–5 |
| `verified` | boolean | ግቤቱ የተረጋገጠ ተብሎ መመልከቱን |
| `lastUpdated` | string | የISO አይነት የቀን ሕብረቁምፊ |
ብጁ የሬጅስትሪ URL ካልተዋቀረ፣ ካታሎጉ አብሮገነቡ
`SEED_REGISTRY` ይሆናል (በአሁኑ ጊዜ `request-logger`፣ `rate-limiter`፣ `cost-tracker` እና
`theme-manager`)። የመነሻ ሬጅስትሪው ሁልጊዜ ይገኛል — የተዋቀረው የርቀት
ሬጅስትሪ የማይደረስ ከሆነ፣ `200` ያልሆነ ሁኔታ ከመለሰ፣ ወይም ያልታወቀ
ይዘት ከመለሰ፣ `listMarketplacePlugins()` ማስጠንቀቂያ ይመዘግብና ወደ መነሻ ዝርዝሩ ይመለሳል።
> ማስታወሻ፦ የገበያው **ካታሎግ** (ማሰስ/መፈለግ) ከጫፍ እስከ ጫፍ ተገናኝቷል፣ ነገር ግን
> ከካታሎጉ ላይ በአንድ ጠቅታ የሚደረግ የገበያ **ጭነት** ገና አልተተገበረም — በገበያ ግቤት ላይ
> ያለው የዳሽቦርዱ "ጫን" አዝራር በአሁኑ ጊዜ
> "በቅርቡ ይመጣል" የሚል ማሳወቂያ ያሳያል። በአሁኑ ጊዜ ጭነት የሚከናወነው በአካባቢያዊ ዱካ የመጫን
> ሂደት (`POST /api/plugins`) እና በዲስክ ላይ ማግኘት (`POST /api/plugins/scan`) በኩል ነው።
## REST API
ሁሉም የመዳረሻ ነጥቦች የአስተዳደር ማረጋገጫ (`requireManagementAuth`) ይፈልጋሉ፣ **እንዲሁም**
ለloopback ብቻ የተገደቡ ናቸው — `/api/plugins` እና `/api/plugins/` በ
`LOCAL_ONLY_API_PREFIXES` (`src/server/authz/routeGuard.ts`) ውስጥ ተዘርዝረዋል።
| የመዳረሻ ነጥብ | ዘዴ | መግለጫ |
| -------------------------------- | ------ | ----------------------------------------------- |
| `/api/plugins` | GET | የተጫኑ ፕለጊኖችን ዘርዝር (አማራጭ `?status=` ማጣሪያ) |
| `/api/plugins` | POST | ከፍጹም የአካባቢ ዱካ ፕለጊን ጫን |
| `/api/plugins/scan` | POST | የፕለጊን ማውጫውን ቃኝ እና አዳዲስ ፕለጊኖችን መዝግብ |
| `/api/plugins/marketplace` | GET | የገበያ ቦታ ካታሎግ ግቤቶችን ዘርዝር |
| `/api/plugins/[name]` | GET | የተጫነ ፕለጊን ዝርዝሮችን አግኝ |
| `/api/plugins/[name]` | DELETE | ፕለጊንን አራግፍ |
| `/api/plugins/[name]/activate` | POST | አግብር (ጫን + hooks መዝግብ) |
| `/api/plugins/[name]/deactivate` | POST | አቦዝን (`onDeactivate`ን አስነሳ፣ hooksን ከምዝገባ አስወግድ) |
| `/api/plugins/[name]/config` | GET | የፕለጊን config + config schema አግኝ |
| `/api/plugins/[name]/config` | PUT | የፕለጊን configን አዘምን (ከschemaው ጋር የተረጋገጠ) |
የ`GET /api/plugins` `status` ማጣሪያ ከ
`installed` / `active` / `inactive` / `error` አንዱን ይቀበላል። ልክ ያልሆነ እሴት `400` ይመልሳል።
### የተጫኑ ፕለጊኖችን ዘርዝር
```bash
curl http://localhost:20128/api/plugins \
-H "Cookie: auth_token=..."
```
### ከአካባቢ ዱካ ጫን
```bash
curl -X POST http://localhost:20128/api/plugins \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{ "path": "/absolute/path/to/my-plugin" }'
```
`path` **ፍጹም** መሆን አለበት፣ እንዲሁም `..` የዱካ መሻገሪያ ክፍሎችን ወይም
null bytesን መያዝ የለበትም (በZod የሚያስገደድ)። የምንጭ ማውጫው ትክክለኛ
`plugin.json` መያዝ አለበት (ወይም የአንዱ ወላጅ መሆን አለበት)። ሲሳካ ምላሹ የተጫነውን
የፕለጊን ረድፍ ከ`201` ጋር ይመልሳል።
### የገበያ ቦታውን አስስ
```bash
curl http://localhost:20128/api/plugins/marketplace \
-H "Cookie: auth_token=..."
```
### የፕለጊን configን አዘምን
```bash
curl -X PUT http://localhost:20128/api/plugins/my-plugin/config \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{ "config": { "level": "debug", "maxItems": 100 } }'
```
`PUT .../config` እያንዳንዱን የቀረበ እሴት በፕለጊኑ
`configSchema` (በmanifest ውስጥ የተገለጸ) መሠረት ያረጋግጣል፦ የ`number` መስኮች `min`/`max`ን
ያከብራሉ፣ የ`select` መስኮች ከተገለጸው `enum` ጋር መዛመድ አለባቸው። በschemaው
ውስጥ የሌሉ keys እንዲያልፉ ይፈቀድላቸዋል።
## ውቅር
### የፕለጊን ማውጫ
ፕለጊኖች በOmniRoute የውሂብ ማውጫ ሥር ይገኛሉ፦
```
~/.omniroute/plugins/<plugin-name>/
├─ plugin.json
└─ index.js # (ወይም manifest.main የሚያመለክተው ማንኛውም ፋይል)
```
`getDefaultPluginDir()` (`src/lib/plugins/scanner.ts`) ያንን ማውጫ በ
ሦስት ደረጃዎች ይወስናል፦
1. **`OMNIROUTE_PLUGINS_DIR`**፣ ሲዋቀር — `HOME` ምንም ቢል እንደተሰጠው ይጠቀማል። ይህ
የፕለጊኑ ዛፍ በአብዛኛው ከcontainerው home directory ጋር ምንም ግንኙነት
በሌለው ዱካ ላይ bind-mounted ለሚሆንባቸው Docker/K8s የተዘጋጀ ግልጽ መቆጣጠሪያ ነው (#11827)።
2. `<home>/.omniroute/plugins`፣ `<home>` ከ`HOME` / `USERPROFILE`
environment variables የሚመጣበት።
3. `/tmp/.omniroute/plugins`፣ processው ምንም home ሳያስገኝ ሲቀር።
የተወሰነው ማውጫ ሲጀመር `scanner.dir_resolved` ተብሎ አንድ ጊዜ ይመዘገባል፣ ያሸነፈውን
ግቤት (`OMNIROUTE_PLUGINS_DIR`፣ `home`፣ ወይም `no-home-fallback`) በመጥቀስ — በዚህም በዝምታ
ደረጃ 3 ላይ የሚያርፍ image ባዶ የፕለጊን ዝርዝር ብቻ ከማሳወቅ ይልቅ ይህንን ይገልጻል።
`POST /api/plugins/scan` ትክክለኛ
`plugin.json` የያዘ ማንኛውንም ንዑስ ማውጫ እዚያ ፈልጎ ያገኛል እና ይመዘግበዋል፤ ያው ማውጫ
`pluginManager.install()` ፕለጊኖችን የሚቀዳበት root በመሆኑ፣ override ማድረግ discoveryን እና
installationን በአንድነት ያንቀሳቅሳል።
> **`OMNIROUTE_PLUGINS_DIR` `OMNIROUTE_PLUGIN_PATH` አይደለም።** የኋለኛው የሚነበበው
> `omniroute` subcommandsን የሚጨምሩ `omniroute-cmd-*` npm
> packagesን ለማግኘት በCLI command-plugin loader (`bin/cli/plugins.mjs`) ብቻ ነው — እዚህ በተገለጸው runtime scanner
> ላይ ምንም ተፅዕኖ የለውም። ለዚያ ክፍል [PLUGINS.md](./PLUGINS.md)ን ይመልከቱ።
### ብጁ የገበያ ቦታ registry URL
የገበያ ቦታ ካታሎግ ምንጭ ከ`pluginMarketplaceUrl` setting
ይነበባል (`src/lib/plugins/marketplace.ts` `settings.pluginMarketplaceUrl`ን ያነባል)። ወደ
`http(s)` URL ሲዋቀር፣ `listMarketplacePlugins()` ያንን URL fetch በማድረግ
የግቤቶችን ከፍተኛ-ደረጃ JSON array ወይም `plugins` array ያለውን object
ይቀበላል፤ string `name` የሌላቸው ግቤቶች ተጣርተው ይወገዳሉ። ካልተዋቀረ (ወይም fetchው
በSSRF guard ምክንያት ካልተሳካ / መጥፎ ምላሽ ከመለሰ)፣ አብሮ የተካተተው seed registry
ጥቅም ላይ ይውላል።
በdashboard ውስጥ ያለው "Marketplace" tab ለዚህ URL መስክ ያቀርባል (ከ
`GET /api/settings` ተመልሶ የሚነበብ)።
> የትግበራ ማስታወሻ፦ የdashboard "Save" እርምጃ
> `pluginMarketplaceUrl`ን ወደ `PATCH /api/settings` ይልካል። ይህ በተጻፈበት
> ጊዜ ይህ key በ`updateSettingsSchema`
> (`src/shared/validation/settingsSchemas.ts`) ውስጥ አልተገለጸም፣ ስለዚህ በእሱ ላይ
> ከመመሥረትዎ በፊት በreleaseዎ ውስጥ persistenceን ያረጋግጡ — የ**ማንበቢያ** ዱካው (`getSettings()` →
> `listMarketplacePlugins()`) keyው በsettings store ውስጥ ከተገኘ በኋላ ያከብረዋል።
## ደህንነት
### የራውት ደረጃ — loopback ብቻ
ፕለጊኖች ኮድን በተጀመሩ የልጅ ፕሮሰሶች ውስጥ ያስፈጽማሉ፤ ስለዚህ መላው `/api/plugins`
ገጽታ `LOCAL_ONLY` (ደረጃ 1) ተብሎ ተመድቧል። የloopback ማስገደጃው ከማንኛውም
የማረጋገጫ ፍተሻ **በፊት** ያለምንም ቅድመ ሁኔታ ይሰራል፤ ስለዚህ በቱነል
በኩል ሳጥኑ ላይ የደረሰ ሾልኮ የወጣ የአስተዳደር ቶከን እንኳን ፕለጊን
መጫን፣ ማግበር ወይም ማራገፍ አይችልም።
[`docs/security/ROUTE_GUARD_TIERS.md`](../security/ROUTE_GUARD_TIERS.md) እና
ጥብቅ ደንቦች #15 / #17ን ይመልከቱ።
### የገበያ ቦታ ሬጅስትሪ SSRF መከላከያ
ብጁ የሬጅስትሪ URL በአጥቂ ተጽዕኖ ሊደረግበት የሚችል ውቅር ነው፤ ስለዚህ
ከመውሰዱ በፊት `listMarketplacePlugins()` በሁለት ንብርብሮች ያጣራዋል፦
1. **`isSafeMarketplaceUrl(url)`** (`src/lib/plugins/marketplace.ts`)፦
- `http:` / `https:` ያልሆነን ማንኛውንም ነገር ውድቅ ያደርጋል።
- መደበኛውን `isPrivateHost`
(`src/shared/network/outboundUrlGuard.ts`) በመጠቀም ቀጥተኛ private/loopback/link-local/ULA አስተናጋጆችን (IPv4 **እና** IPv6፣
IPv4-mappedን ጨምሮ) ውድቅ ያደርጋል።
- **ሁለቱንም** `A` እና `AAAA` መዝገቦች ይፈታል፤ እና ከተፈቱት
አድራሻዎች **ማንኛውም** private ከሆነ ውድቅ ያደርጋል — በዚህም public-hostname → private-IP ማለፊያውን ይዘጋል።
- **በመዝጋት ይከሽፋል**፦ የDNS መፍታት ካልተሳካ URLው ውድቅ ይደረጋል።
2. **`safeOutboundFetch(url, { guard: "public-only", timeoutMs: 5000 })`**
(`src/shared/network/safeOutboundFetch.ts`)፦ የpublic-only URL
መከላከያውን በማምጣት ጊዜ እንደገና ይተገብራል፤ እንዲሁም **ማዞሪያዎችን ያግዳል** (የpublic → private `30x`
ሽግግር አይኖርም)።
ከሁለቱ ንብርብሮች በአንዱ ያልፈው URL ጥያቄውን አያቋርጥም — የገበያ ቦታው
ያለምንም ማሳወቂያ አብሮ ወደተካተተው የመነሻ ሬጅስትሪ ይመለሳል፤ ማስጠንቀቂያም ይመዘግባል።
> ይህ መከላከያ `A` + `AAAA`ን በተለይ ለመፍታት እና IPv4 ብቻን ከሚፈትሽ ፍተሻ ይልቅ
> መደበኛውን `isPrivateHost` ለመጠቀም በPR #3774 ውስጥ ተጠናክሯል።
### የፕለጊን አፈጻጸም መነጠል
- **የፕሮሰስ መነጠል** — `loadPlugin()` (`src/lib/plugins/loader.ts`)
እያንዳንዱን ፕለጊን በተለየ Node.js የልጅ ፕሮሰስ ውስጥ ያስጀምራል፤ በIPCም
ይገናኛል። የhook ጥሪዎች `SIGTERM` → `SIGKILL` የማጠናከሪያ ቅደም ተከተል ያለው የጊዜ ገደብ አላቸው።
- **የEnv የተፈቀዱ ዝርዝር** — የልጅ ፕሮሰሱ የሚቀበለው በተፈቀዱት ዝርዝር ውስጥ
ያሉ የአካባቢ ተለዋዋጮችን ብቻ ነው፤ ሰፋ ያለው ስብስብ የሚፈቀደው manifestው
የ`env` ፈቃድ ሲጠይቅ ብቻ ነው።
- **የዱካ ገደብ** — install/upgrade/uninstall፣ ማንኛውም ቅጂ ወይም ተደጋጋሚ ስረዛ ከመደረጉ በፊት የፕለጊኑ
ማውጫ እና `manifest.main` በሚተዳደረው የፕለጊን ስር ማውጫ **ውስጥ** እንደሚፈቱ ያረጋግጣሉ (በተበላሹ የDB ዱካዎች እና በ`manifest.main` ውስጥ ያለ `../` ዱካ ማቋረጥን ይከላከላል)። ማግበር symlinkዎችን በ
`realpath` ይፈታል፤ እና ከፕለጊኑ ማውጫ የሚወጣ መግቢያ ነጥብ ለመጫን እምቢ ይላል።
- **አማራጭ የትክክለኛነት ማስማሪያ** — manifest የ`integrity`
(`sha256-<base64>`፣ SRI ቅርጸት) መስክ ሊያውጅ ይችላል። ሲኖር ጫኚው
በመጫን ጊዜ የመግቢያ ፋይሉን hash ያረጋግጣል፤ ካልተዛመደም ለማግበር እምቢ ይላል። ይህ
በምርጫ የሚነቃ የለውጥ ማወቂያ እንጂ **የደህንነት ወሰን አይደለም** — loopback-only ራውቲንግ
እና የፈቃድ ሞዴሉ እውነተኛዎቹ ወሰኖች ናቸው።
## Manifest (`plugin.json`)
በ`PluginManifestSchema` (`src/lib/plugins/manifest.ts`) የተረጋገጠ፦
| መስክ | ዓይነት | ማስታወሻዎች |
| ------------------ | --------- | ---------------------------------------------------- |
| `name` | string | አስፈላጊ፤ kebab-case (`^[a-z0-9-]+$`)፣ 1–100 ቁምፊዎች |
| `version` | string | አስፈላጊ፤ semver (`MAJOR.MINOR.PATCH`) |
| `description` | string? | ≤ 500 ቁምፊዎች |
| `author` | string? | ≤ 200 ቁምፊዎች |
| `license` | string? | ነባሪው `MIT` ነው |
| `main` | string? | የመግቢያ ፋይል፤ ነባሪው `index.js` ነው |
| `source` | enum? | `local` \| `marketplace` (ነባሪው `local` ነው) |
| `tags` | string[]? | የፍለጋ መለያዎች |
| `requires` | object? | `{ omniroute?, permissions[] }` |
| `hooks` | object? | ፕለጊኑ የትኞቹን hooks እንደሚተገብር የሚያውጁ Booleans |
| `skills` | object[]? | አማራጭ የክህሎት ትርጓሜዎች |
| `enabledByDefault` | boolean? | ሲጫን በራስ-ሰር አግብር |
| `configSchema` | object? | የውቅር መስኮች ካርታ (`string`/`number`/`boolean`/`select`) |
| `integrity` | string? | አማራጭ `sha256-<base64>` የመግቢያ ፋይል ማስማሪያ |
ፈቃዶች ከ
`network` / `file-read` / `file-write` / `env` / `exec`
enum ይወሰዳሉ።
## የሕይወት ዑደት ፍሰት
```
ጫን (POST /api/plugins, ዱካ)
→ manifestን ቃኝ/አረጋግጥ → ወደ staging ቅዳ → main በማውጫው ውስጥ መሆኑን አረጋግጥ
→ በአቶሚክ ሁኔታ ወደ ~/.omniroute/plugins/<name> እንደገና ሰይም → የDB ረድፍ አስገባ
→ onInstallን አስነሳ → enabledByDefault ከሆነ፦ አግብር
አግብር (POST /api/plugins/{name}/activate)
→ የrealpath ወሰን ማረጋገጫ → loadPlugin() (የልጅ ሂደት አስነሳ)
→ የታወጁ hooksን መዝግብ → status = "active" → onActivateን አስነሳ
አቦዝን (POST /api/plugins/{name}/deactivate)
→ onDeactivateን አስነሳ (ከምዝገባ ማስወገድ በፊት) → hooksን ከምዝገባ አስወግድ
→ የልጅ ሂደቱን አቁም → status = "inactive"
አራግፍ (DELETE /api/plugins/{name})
→ active ከሆነ አቦዝን → onUninstallን አስነሳ
→ የወሰን ማረጋገጫ የተደረገበትን የፕለጊን ማውጫ በተደጋጋሚ ሰርዝ → የDB ረድፉን ሰርዝ
```
`install`ን፣ የmanifest ስሪቱ ከተጫነው ስሪት **በጥብቅ
የሚበልጥ** በሆነ ማውጫ ላይ እንደገና ማስኬድ በራስ-ሰር ያሻሽለዋል (ንጹሕ ዳግም ጭነት፤ config ወደ
ነባሪ እሴቶች ይመለሳል)። ተመሳሳይ ወይም የቆየ ስሪት ውድቅ ይደረጋል።
## የውሂብ ጎታ
ሰንጠረዥ `plugins` (ፍልሰት `076_create_plugins.sql`)፦
| ዓምድ | ዓይነት | ማስታወሻዎች |
| --------------- | ------- | ------------------------------------------------ |
| `id` | TEXT PK | UUID |
| `name` | TEXT | ልዩ |
| `version` | TEXT | semver፤ ነባሪ `1.0.0` |
| `description` | TEXT | አማራጭ |
| `author` | TEXT | አማራጭ |
| `license` | TEXT | ነባሪ `MIT` |
| `main` | TEXT | የመግቢያ ፋይል፤ ነባሪ `index.js` |
| `source` | TEXT | ነባሪ `local` |
| `tags` | TEXT | የJSON ድርድር፤ ነባሪ `[]` |
| `status` | TEXT | `installed` \| `active` \| `inactive` \| `error` |
| `enabled` | INT | 0/1፤ ነባሪ 0 |
| `manifest` | TEXT | ሙሉ የmanifest JSON |
| `config` | TEXT | JSON፤ ነባሪ `{}` |
| `config_schema` | TEXT | JSON፤ ነባሪ `{}` |
| `hooks` | TEXT | የታወጁ የhook ስሞች JSON ድርድር፤ ነባሪ `[]` |
| `permissions` | TEXT | የJSON ድርድር፤ ነባሪ `[]` |
| `plugin_dir` | TEXT | ፍጹም የመጫኛ ማውጫ |
| `error_message` | TEXT | `status = "error"` ሲሆን ይቀናበራል |
| `installed_at` | TEXT | `datetime('now')` |
| `updated_at` | TEXT | `datetime('now')` |
| `activated_at` | TEXT | ሲነቃ ይቀናበራል |
የፕለጊን መለኪያዎች/ትንታኔዎች በተጨማሪ ሰንጠረዦች
(`090_plugin_metrics.sql`, `091_plugin_analytics.sql`) ውስጥ ይከታተላሉ።
## ዳሽቦርድ
በ`/dashboard/plugins`
(`src/app/(dashboard)/dashboard/plugins/page.tsx`) የሚገኘው የዳሽቦርድ ገጽ ሁለት ትሮችን ያቀርባል፦
- **የተጫኑ** — የተጫኑ ፕለጊኖችን ከታወጁ hooks፣ ከማግበር/ማቦዘን መቀያየሪያ፣ ከማራገፊያ አዝራር እና ከ"ፕለጊኖችን ቃኝ"
ድርጊት (`POST /api/plugins/scan`) ጋር ይዘረዝራል።
- **የገበያ ቦታ** — ከ`GET /api/plugins/marketplace` የሚገኘውን ካታሎግ፣ ብጁ registry URLን ለማቀናበር
ከሚያስችል መስክ ጋር ያሳያል።
የእያንዳንዱ ፕለጊን config ገጽ በ`/dashboard/plugins/[name]/config`
(`src/app/(dashboard)/dashboard/plugins/[name]/config/page.tsx`) ይገኛል።
## በተጨማሪ ይመልከቱ
- [`docs/security/ROUTE_GUARD_TIERS.md`](../security/ROUTE_GUARD_TIERS.md) —
`/api/plugins` loopback-only (Tier 1) የሆነበት ምክንያት
- [`docs/frameworks/SKILLS.md`](./SKILLS.md) — ተዛማጁ የክህሎቶች ማዕቀፍ
(`src/lib/skills/`)፤ plugins በmanifestቸው ውስጥ ክህሎቶችን ሊገልጹ ይችላሉ
- [`docs/frameworks/WEBHOOKS.md`](./WEBHOOKS.md) — በክስተት የሚመሩ ወደ ውጭ የሚደረጉ
ውህደቶች
- [`docs/security/ERROR_SANITIZATION.md`](../security/ERROR_SANITIZATION.md) —
እያንዳንዱ የplugin መስመር ለስህተት ምላሾች የሚጠቀምበት የ`buildErrorBody()` ንድፍ

254
docs/i18n/am/docs/frameworks/PLUGIN_SDK.md Normal file
View File

@@ -0,0 +1,254 @@
# OmniRoute Plugin SDK (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/PLUGIN_SDK.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/PLUGIN_SDK.md) · 🇦🇿 [az](../../../az/docs/frameworks/PLUGIN_SDK.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/PLUGIN_SDK.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/PLUGIN_SDK.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/PLUGIN_SDK.md) · 🇩🇰 [da](../../../da/docs/frameworks/PLUGIN_SDK.md) · 🇩🇪 [de](../../../de/docs/frameworks/PLUGIN_SDK.md) · 🇬🇷 [el](../../../el/docs/frameworks/PLUGIN_SDK.md) · 🇪🇸 [es](../../../es/docs/frameworks/PLUGIN_SDK.md) · 🇪🇪 [et](../../../et/docs/frameworks/PLUGIN_SDK.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/PLUGIN_SDK.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/PLUGIN_SDK.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/PLUGIN_SDK.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/PLUGIN_SDK.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/PLUGIN_SDK.md) · 🇮🇱 [he](../../../he/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/PLUGIN_SDK.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/PLUGIN_SDK.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/PLUGIN_SDK.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/PLUGIN_SDK.md) · 🇮🇩 [id](../../../id/docs/frameworks/PLUGIN_SDK.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/PLUGIN_SDK.md) · 🇮🇹 [it](../../../it/docs/frameworks/PLUGIN_SDK.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/PLUGIN_SDK.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/PLUGIN_SDK.md) · 🇰🇭 [km](../../../km/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/PLUGIN_SDK.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/PLUGIN_SDK.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/PLUGIN_SDK.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/PLUGIN_SDK.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/PLUGIN_SDK.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/PLUGIN_SDK.md) · 🇲🇲 [my](../../../my/docs/frameworks/PLUGIN_SDK.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/PLUGIN_SDK.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/PLUGIN_SDK.md) · 🇳🇴 [no](../../../no/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [or](../../../or/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/PLUGIN_SDK.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/PLUGIN_SDK.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/PLUGIN_SDK.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/PLUGIN_SDK.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/PLUGIN_SDK.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/PLUGIN_SDK.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/PLUGIN_SDK.md) · 🇱🇰 [si](../../../si/docs/frameworks/PLUGIN_SDK.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/PLUGIN_SDK.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/PLUGIN_SDK.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/PLUGIN_SDK.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/PLUGIN_SDK.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/PLUGIN_SDK.md) · 🇮🇳 [te](../../../te/docs/frameworks/PLUGIN_SDK.md) · 🇹🇭 [th](../../../th/docs/frameworks/PLUGIN_SDK.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/PLUGIN_SDK.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/PLUGIN_SDK.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/PLUGIN_SDK.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/PLUGIN_SDK.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/PLUGIN_SDK.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/PLUGIN_SDK.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/PLUGIN_SDK.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/PLUGIN_SDK.md)
---
## ፈጣን አጀማመር
```ts
import { definePlugin } from "omniroute/plugins/sdk";
export default definePlugin({
name: "my-plugin",
priority: 50,
onRequest: async (ctx) => {
console.log(`Request ${ctx.requestId} for ${ctx.model}`);
},
onResponse: async (ctx, response) => {
console.log(`Response for ${ctx.requestId}`);
return response;
},
onError: async (ctx, error) => {
console.error(`Error: ${error.message}`);
},
});
```
## የAPI ማጣቀሻ
### `definePlugin(def: PluginDefinition): Plugin`
ነባሪ ቅንብሮች ያሉት Plugin ነገርን የሚፈጥር የፋብሪካ ፈንክሽን።
**መለኪያዎች፦**
- `name` (string, አስፈላጊ) — በkebab-case የተጻፈ የPlugin ስም
- `priority` (number, አማራጭ, ነባሪ፦ 100) — ዝቅተኛው ቀድሞ ይሰራል
- `enabled` (boolean, አማራጭ, ነባሪ፦ true) — እንደነቃ ይጀምር?
- `onRequest` (function, አማራጭ) — ከchat handler በፊት ይሰራል
- `onResponse` (function, አማራጭ) — ከchat handler በኋላ ይሰራል
- `onError` (function, አማራጭ) — የhandler ስህተት ሲኖር ይሰራል
### `blockRequest(response?): BlockingHookResult`
ጥያቄውን ያግዱ እና እንደ አማራጭ ብጁ ምላሽ ይመልሱ።
```ts
onRequest: (ctx) => {
if (!ctx.headers["authorization"]) {
return blockRequest({ error: "Unauthorized", status: 401 });
}
};
```
### `modifyBody(body): PluginResult`
ጥያቄው ወደ provider ከመድረሱ በፊት የጥያቄውን ይዘት ያሻሽሉ።
```ts
onRequest: (ctx) => {
return modifyBody({ ...ctx.body, temperature: 0.7 });
};
```
### `addMetadata(metadata): PluginResult`
metadataን ከጥያቄው context ጋር ያያይዙ።
```ts
onRequest: (ctx) => {
return addMetadata({ source: "my-plugin", version: "1.0.0" });
};
```
## የPlugin Context (`PluginContext`)
| መስክ | ዓይነት | መግለጫ |
| ----------- | ------------------------- | ------------------ |
| `requestId` | `string` | ልዩ የጥያቄ መለያ |
| `model` | `string` | የተጠየቀው የmodel ስም |
| `provider` | `string` | የዒላማ provider ID |
| `body` | `Record<string, unknown>` | የጥያቄ ይዘት |
| `headers` | `Record<string, string>` | የጥያቄ headers |
| `metadata` | `Record<string, unknown>` | ሊለወጥ የሚችል metadata |
| `timestamp` | `number` | የጥያቄ timestamp |
## Manifest (`plugin.json`)
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "A sample plugin",
"author": "your-name",
"main": "index.js",
"hooks": {
"onRequest": { "enabled": true, "priority": 50 },
"onResponse": true,
"onError": false
},
"requires": {
"permissions": ["network", "file-read"]
},
"enabledByDefault": false,
"configSchema": {
"apiKey": {
"type": "string",
"description": "API key for external service"
},
"maxRetries": { "type": "number", "min": 1, "max": 10, "default": 3 },
"debug": { "type": "boolean", "default": false },
"mode": { "type": "string", "enum": ["fast", "slow"], "default": "fast" }
}
}
```
### የHook ቅድሚያ
Hooks በቅድሚያ ሊዋቀሩ ይችላሉ (ዝቅተኛ = ቀድሞ ይሰራል)፦
```json
{
"hooks": {
"onRequest": { "enabled": true, "priority": 10 },
"onResponse": { "enabled": true, "priority": 100 }
}
}
```
ወይም እንደ ቀላል boolean እሴቶች (ነባሪ ቅድሚያ 100)፦
```json
{
"hooks": {
"onRequest": true,
"onResponse": true
}
}
```
## የፈቃድ ስርዓት
ፕለጊኖች በsandbox በተከለለ VM አውድ ውስጥ ይሰራሉ። ውጫዊ ሀብቶችን ለመድረስ ግልጽ ፈቃዶች ያስፈልጋሉ፦
| ፈቃድ | የሚፈቅዳቸው |
| ------------ | ------------------------------------------------------------ |
| `network` | `fetch`, `AbortController`, `Headers`, `Request`, `Response` |
| `file-read` | `fs.readFile`, `fs.readdir`, `fs.stat` |
| `file-write` | `fs.writeFile`, `fs.mkdir`, `fs.rm` |
| `env` | ለንባብ ብቻ የሆነ `process.env` proxy |
| `exec` | `child_process.exec`, `child_process.execSync` |
ፈቃድ ከሌለ፣ ተዛማጅ globals በsandbox ውስጥ አይገኙም።
## የውቅረት Schema
ሊዋቀሩ የሚችሉ ቅንብሮችን በ`configSchema` ውስጥ ይግለጹ፦
```json
{
"configSchema": {
"apiKey": { "type": "string", "description": "የውጫዊ API ቁልፍ" },
"maxRetries": { "type": "number", "min": 1, "max": 10, "default": 3 },
"debug": { "type": "boolean", "default": false },
"mode": { "type": "string", "enum": ["fast", "slow"], "default": "fast" }
}
}
```
የመስክ አይነቶች፦ `string`፣ `number`፣ `boolean`፣ `select`
የመስክ አማራጮች፦ `default`፣ `min`፣ `max`፣ `enum`፣ `description`
የውቅረት እሴቶች በውሂብ ጎታው ውስጥ ይቀመጣሉ፣ እንዲሁም በdashboard የውቅረት ገጽ በኩል ማግኘት ይቻላል።
## አብረው የተካተቱ ክስተቶች
| ክስተት | መቼ | Payload |
| ----------------- | ------------------------------ | ----------------------------- |
| `onRequest` | ከchat handler በፊት | የጥያቄ አውድ |
| `onResponse` | ከchat handler በኋላ | የምላሽ ውሂብ |
| `onError` | የhandler ስህተት ሲከሰት | የስህተት object |
| `onModelSelect` | ለrouting model ሲመረጥ | የmodel መረጃ |
| `onComboResolve` | Combo routing ሲፈታ | የCombo ዒላማዎች |
| `onRateLimit` | የRate limit ገደብ ሲደረስ | የገደብ መረጃ |
| `onQuotaExhaust` | Quota ሲያልቅ | የQuota መረጃ |
| `onProviderError` | Provider ስህተት ሲመልስ | የስህተት ዝርዝሮች |
| `onStreamStart` | SSE stream ሲጀምር | የStream መረጃ |
| `onStreamEnd` | SSE stream ሲያበቃ | የStream ስታቲስቲክስ |
| `onInstall` | Plugin ሲጫን | `{ name, version, manifest }` |
| `onActivate` | Plugin ሲነቃ | `{ name, version, manifest }` |
| `onDeactivate` | Plugin ከስራ ሲቦዝን | `{ name, version, manifest }` |
| `onUninstall` | Plugin ሲወገድ (ፋይሎች ከመሰረዛቸው በፊት) | `{ name, version, manifest }` |
## ምሳሌዎች
### የጥያቄ Logger
```ts
import { definePlugin } from "omniroute/plugins/sdk";
export default definePlugin({
name: "request-logger",
onRequest: async (ctx) => {
console.log(`[${new Date().toISOString()}] ${ctx.method} ${ctx.model} -> ${ctx.provider}`);
},
});
```
### የRate Limiter
```ts
import { definePlugin, blockRequest } from "omniroute/plugins/sdk";
const requests = new Map<string, number[]>();
export default definePlugin({
name: "rate-limiter",
priority: 10,
onRequest: async (ctx) => {
const key = ctx.headers["x-api-key"] || "anonymous";
const now = Date.now();
const window = 60000; // 1 ደቂቃ
const maxRequests = 100;
const timestamps = (requests.get(key) || []).filter((t) => t > now - window);
timestamps.push(now);
requests.set(key, timestamps);
if (timestamps.length > maxRequests) {
return blockRequest({ error: "Rate limit exceeded", status: 429 });
}
},
});
```
### የምላሽ Transformer
```ts
import { definePlugin } from "omniroute/plugins/sdk";
export default definePlugin({
name: "response-transformer",
onResponse: async (ctx, response) => {
if (response.choices) {
response.choices = response.choices.map((c: any) => ({
...c,
message: { ...c.message, content: c.message.content.trim() },
}));
}
return response;
},
});
```

813
docs/i18n/am/docs/frameworks/RADAR.md Normal file
View File

@@ -0,0 +1,813 @@
# Radar Free-Model Catalog (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/RADAR.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/RADAR.md) · 🇦🇿 [az](../../../az/docs/frameworks/RADAR.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/RADAR.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/RADAR.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/RADAR.md) · 🇩🇰 [da](../../../da/docs/frameworks/RADAR.md) · 🇩🇪 [de](../../../de/docs/frameworks/RADAR.md) · 🇬🇷 [el](../../../el/docs/frameworks/RADAR.md) · 🇪🇸 [es](../../../es/docs/frameworks/RADAR.md) · 🇪🇪 [et](../../../et/docs/frameworks/RADAR.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/RADAR.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/RADAR.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/RADAR.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/RADAR.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/RADAR.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/RADAR.md) · 🇮🇱 [he](../../../he/docs/frameworks/RADAR.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/RADAR.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/RADAR.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/RADAR.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/RADAR.md) · 🇮🇩 [id](../../../id/docs/frameworks/RADAR.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/RADAR.md) · 🇮🇹 [it](../../../it/docs/frameworks/RADAR.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/RADAR.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/RADAR.md) · 🇰🇭 [km](../../../km/docs/frameworks/RADAR.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/RADAR.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/RADAR.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/RADAR.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/RADAR.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/RADAR.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/RADAR.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/RADAR.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/RADAR.md) · 🇲🇲 [my](../../../my/docs/frameworks/RADAR.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/RADAR.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/RADAR.md) · 🇳🇴 [no](../../../no/docs/frameworks/RADAR.md) · 🇮🇳 [or](../../../or/docs/frameworks/RADAR.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/RADAR.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/RADAR.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/RADAR.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/RADAR.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/RADAR.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/RADAR.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/RADAR.md) · 🇱🇰 [si](../../../si/docs/frameworks/RADAR.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/RADAR.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/RADAR.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/RADAR.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/RADAR.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/RADAR.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/RADAR.md) · 🇮🇳 [te](../../../te/docs/frameworks/RADAR.md) · 🇹🇭 [th](../../../th/docs/frameworks/RADAR.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/RADAR.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/RADAR.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/RADAR.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/RADAR.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/RADAR.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/RADAR.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/RADAR.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/RADAR.md)
---
> **የእውነት ምንጭ:** `src/lib/radar/`, `src/lib/db/radar.ts`, `src/app/api/radar/`
> **መጨረሻ የተዘመነው:** 2026-09-01 — v3.8.51
> **በአገልግሎት አቅራቢ የሚስተናገደው አገልግሎት ማስረጃ ወሰን:** እዚህ የተገለጹት የአገልጋይ-ወገን ደንቦች
> በ2026-09-01 ሆን ተብሎ የግል በተደረገው Radar አገልጋይ ላይ በትክክለኛው ክለሳ
> `main@dce70f004364912f3f144cdb69f4cbcde16093ed` ተረጋግጠዋል። ያ አተገባበር በዚህ OSS ማከማቻ ውስጥ
> አይሰራጭም፤ በአገልግሎት አቅራቢ የሚስተናገደው አገልግሎት መገኘት የተለየ የክንውን ሁኔታ ሆኖ ይቀጥላል።
Radar በልቀት መሠረቱ (`open-sse/config/freeModelCatalog.data.ts` ውስጥ ያለው
`FREE_MODEL_BUDGETS`) ላይ የተፈረመ፣ በቅርብ ጊዜ የተመረጠ የነፃ-ሞዴል
ካታሎግን የሚያደራርብ **አማራጭ ተጨማሪ ክፍል** ነው። ይህ ያለው የነፃ ደረጃዎች ሁኔታ
ከልቀት ዑደት ይልቅ ፈጥኖ ስለሚለዋወጥ ነው — አቅራቢዎች በልቀቶች መካከል ነፃ ኮታዎችን
ይጨምራሉ፣ ያሳንሳሉ ወይም ያቋርጣሉ፣ እና የመሠረት ካታሎጉ ሊታደስ የሚችለው
አዲስ ስሪት ሲለቀቅ ብቻ ነው።
**ዛሬ ነፃ የሆነ ምንም ነገር በርቀት ምግብ ምክንያት ነፃ መሆኑን አያቆምም።** Radar
የመሠረት ግቤትን ፈጽሞ በክፍያ ግድግዳ አይከልልም፤ በንባብ ጊዜ የገደብ/ሁኔታ መስኮችን ብቻ ያድሳል እና
በልቀቶች መካከል አዲስ የተገኙ ነፃ ሞዴሎችን በተጨማሪ ሊያካትት ይችላል። ከዋኝ አሁንም አንድ
ሞዴልን በአካባቢው መደበቅ እና ከዚያው ዳሽቦርድ መልሶ ማስመለስ ይችላል። የመሠረት ካታሎጉ ራሱ
በዲስክ ላይ ፈጽሞ አይቀየርም — ከታች ያለውን
[በንባብ ጊዜ የተደራራቢ ውህደት ደንቦች](#read-time-overlay-merge-rules) ይመልከቱ።
---
## በv3.8.51 ውስጥ ያለው የአቅርቦት ሁኔታ
የሚከተለው ሁኔታ ይህ OSS ልቀት ከቆዩ የRadar የሥራ ፍሰቶች በተለየ ሁኔታ ምን እንደሚተገብር
ያብራራል። ይህ የኮድ-ደረጃ ሁኔታ ነው፤ አንድ የተወሰነ በአገልግሎት አቅራቢ የሚስተናገድ ዝርጋታ
ወይም ውጫዊ ውህደት በአሁኑ ጊዜ እንደሚገኝ የሚገባ ቃል አይደለም።
| ዘርፍ | በዚህ ልቀት ውስጥ ያለው ሁኔታ |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| የተፈረመ ካታሎግ ደንበኛ | ከተለየ የመርጦ-መግባት አማራጭ፣ ከEd25519 ማረጋገጫ፣ ከተመሰጠሩ አካባቢያዊ ቅንብሮች/መሸጎጫ፣ ከቋሚ የማሳያ/የነቃ መሻሪያዎች፣ ሊቀለበሱ ከሚችሉ የስረዛ ምልክቶች፣ ከመርሐግብር አስኪያጅ እና ከዳሽቦርድ ጋር ከ`RADAR_ENABLED` በስተጀርባ ተተግብሯል። |
| የአበርካች ማግበር | ዳሽቦርዱ በአገልጋዩ ወደሚስተናገደው የGitHub የይገባኛል ጥያቄ ፍሰት ያገናኛል እና ነባር `omr_…` ቁልፍ ይቀበላል። የአበርካች ብቁነት በግል አገልግሎቱ ይወሰናል፤ OSS ደንበኛው ምንም የGitHub ቶከን ወይም የማውጣት አመክንዮ አልያዘም። |
| የደጋፊ-ቁልፍ ማግበር | ተተግብሯል። ጥሬው ቁልፍ ይረጋገጣል፣ በማከማቻ ጊዜ ይመሰጠራል፣ በንባብ ጊዜ ይሸፈናል፣ እና በአገልጋይ-ወገን ማመሳሰል ብቻ ይላካል። ቁልፉን መቀየር ወይም ማጽዳት መብትን የሚመለከቱትን አራቱንም የምግብ መሸጎጫዎች ዋጋ ያሳጣል። |
| የሪፈራል አገናኞች | በተናጠል የተፈረመ፣ በየሰዓቱ የሚታደስ ምግብ ሆነው ተተግብረዋል። ቋሚ አገናኞች ወዲያውኑ ለማህበረሰብ ደረጃው ይገኛሉ፤ ውስን ዘመቻዎች የቀጥታ-ደረጃ ውሂብ ሆነው ይቆያሉ። |
| የደጋፊ ቅናሾች | የተለየ፣ የተፈረመ፣ የቀጥታ-ብቻ ምግብ እና የዳሽቦርድ ገጽ ሆነው ተተግብረዋል። ደንበኛው የተዘጋውን የጥቅማጥቅም ንድፍ እንደገና ያረጋግጣል፣ የመጨረሻውን ትክክለኛ መሸጎጫ ይጠብቃል፣ ጊዜያቸው ያለፈባቸውን ግቤቶች ያጣራል፣ እና የአጋር ቅናሾችን በግልጽ ይሰይማል። |
| የመረጃ ትንተና እና የደጋፊ እውቅና | በጥብቅ የተፈረመ የቀጥታ-ብቻ ምግብ፣ በRadar ባለቤትነት ከሚተዳደር ELO፣ ከተጨባጭ የካታሎግ ወቅታዊነት/አዝማሚያ፣ ከተረጋገጠ አካባቢያዊ የደጋፊ ባጅ፣ ከዳሽቦርድ ገጽ፣ እና አካባቢያዊ-ብቻ ከሆኑ የCLI ሁኔታ/ማመሳሰል ትዕዛዞች ጋር ተተግብሯል። |
| ክፍያዎች እና የግብይት ኢሜይል | በOSS ደንበኛው ውስጥ አልተተገበሩም። ግዢ፣ ልገሳ፣ የደረሰኝ ግምገማ፣ መልሶ ማግኘት እና የደብዳቤ ማድረስ የግል አገልግሎቱ ኃላፊነቶች ናቸው፤ በአገልግሎት አቅራቢ የሚስተናገደው አገልግሎት መገኘት አሁንም በክትትል በሚደረግ ዝርጋታው እና በአቅራቢ ውቅር ላይ ይመሰረታል። |
| የምርምር-ወኪል የሥራ ፍሰት | የዚህ የደንበኛ ልቀት አካል አይደለም። የተመረጡ የምግብ ይዘቶች የአገልጋይ-ወገን ውሂብ ሆነው ይቆያሉ፤ በOmniRoute ጭነት ውስጥ ምንም ራስ-ገዝ የምርምር ወኪል አይሠራም። |
---
## የይፋዊ ማስታወቂያ አንባቢ
አጠቃላይ የማስታወቂያ አንባቢው ከRadar የባህሪ ማብሪያ የተለየ ነው። የዳሽቦርዱ Home እና
Changelog መመልከቻ የማከማቻውን ይፋዊ `news.json` በቀላል `GET` ወደ
`NEWS_JSON_URL` (`src/shared/utils/releaseNotes.ts`) በመላክ ያመጣሉ። ምንም የRadar ቅንብር፣ ጥያቄ፣ የአቅራቢ
ውቅር፣ የአጠቃቀም መዝገብ ወይም አካባቢያዊ የማሰናበት ሁኔታ አይልኩም።
`news.json` በ`parseNewsPayload()` የተተገበረውን ዝግ v2 መርሐግብር ይጠቀማል፦
- `schemaVersion: 2` እና የተገደበ `items[]` ስብስብ፤
- የማይቀያየሩ፣ ልዩ የማስታወቂያ `id` እሴቶች፤
- በግልጽ የተገለጹ `active` እና ISO `publishedAt` መስኮች፤
- አስገዳጅ የእንግሊዝኛ ጽሑፍ ከአማራጭ አካባቢያዊ ትርጉሞች ጋር፤
- አማራጭ፣ ማረጋገጫ መረጃ የማይጠይቁ HTTPS አገናኞች እና በተፈቀደው ዝርዝር ውስጥ ያለ አዶ፤
- አዲሱን ንቁ ንጥል በቅድሚያ መምረጥ፣ አካባቢያዊ ቋንቋ ካልተገኘ ወደ እንግሊዝኛ መመለስ እና ለእያንዳንዱ ID አካባቢያዊ ማሰናበት።
ተንታኙ የቆዩ forks የተበላሸ Changelog እይታ ሳያጋጥማቸው እንዲሸጋገሩ፣ የቀድሞውን ነጠላ
`{ active, title, message, ... }` ቅርጽ ለጊዜው ይቀበላል። ልክ ያልሆኑ feeds ምንም ተጽዕኖ አያሳድሩም። የRadar ማስጀመሪያ
ግቤት `active: false` ሆኖ ይላካል፤ ይህንን ወደ `true` መቀየር ከውህደትና ከስምሪት በኋላ
የሚከናወን የተለየ የልቀት እርምጃ ሲሆን `RADAR_ENABLED`ን ወይም ራሱን የቻለውን የfeed-sync ፈቃድ አይቀይርም።
---
## ማብሪያ፦ `RADAR_ENABLED` (በነባሪ ጠፍቷል)
Radar ከጫፍ እስከ ጫፍ በ`RADAR_ENABLED` የባህሪ ማብሪያ
(`src/shared/constants/featureFlagDefinitions.ts`፣ ምድብ `policies`፣
`defaultValue: "false"`) ይገደባል።
**ማብሪያው ሲጠፋ በይነገጹ ፈጽሞ አይኖርም፦**
- የአካባቢያዊ ሞዴል ሁኔታ ንባብና ጽሑፍን ጨምሮ ሁሉም `/api/radar/*` endpoints፣
ማንኛውንም የRadar ሞጁል ከመንካታቸው በፊት `404` ይመልሳሉ።
- የዳሽቦርድ ገጾቹ (`/dashboard/radar`፣ `/dashboard/radar/setup`፣
`/dashboard/radar/combos`፣ `/dashboard/radar/offers`፣ `/dashboard/radar/intel`) `notFound()`ን ያሳያሉ።
- `getRadarCatalog()` (`src/lib/radar/index.ts`) ሳይነካ የቀረውን መሠረታዊ ስብስብ —
ተመሳሳይ የግቤት ብዛት፣ ተመሳሳይ እሴቶች፣ እያንዳንዱ ግቤት `origin: "baseline"` የሚል መለያ ያለው — ይመልሳል፣ እንዲሁም
የfeed cacheን ፈጽሞ አያነብም።
- ምንም የRadar የአውታረ መረብ ጥሪ ፈጽሞ አይደረግም፤ እያንዳንዱ የsync ሞጁል `fetch`ን
ከመንካቱ በፊት `{ status: "disabled" }`ን ይመልሳል።
ይህ ጥብቅ የበላይ ደረጃ መግቢያ ነው፦ ማብሪያውን ማብራት _ገጾቹን_ ብቻ ይከፍታል፣ ከዚያ የበለጠ
ምንም አያደርግም። ውሂብ አይሰቅልም፣ የጀርባ sync አያስጀምርም፣ እንዲሁም
routingን ወይም የሞዴል ምርጫን አይቀይርም — ከታች ያለውን የተለየ ፈቃድ ይመልከቱ።
---
## የውሂብ sync የተለየ ፈቃድ ይፈልጋል — የግላዊነት ቃል ኪዳኑ
`RADAR_ENABLED`ን ማብራት UIን ብቻ ይከፍታል። feedን sync ማድረግ በ`radar_settings.opt_in` ውስጥ የሚከማች
ሁለተኛ፣ ራሱን የቻለ ፈቃድ ይፈልጋል (`src/lib/db/radar.ts`፣
migration `136_radar_cache_settings.sql`)። `syncRadar()` ማንኛውንም የአውታረ መረብ ጥሪ ከማድረጉ በፊት ማብሪያውን _እና_
ፈቃዱን ይፈትሻል፦
```
ማብሪያው ጠፍቷል → { status: "disabled" } — የአውታረ መረብ ጥሪ የለም
ፈቃዱ false ነው → { status: "opt_out" } — የአውታረ መረብ ጥሪ የለም
```
ሁለቱም ሲበሩ የsync ሂደቱ እንደሚከተለው ነው፦
1. `GET <feed base URL>/v1/catalog/latest` ከ`x-omniroute-radar-schema: 2` እና ከአማራጭ
`Authorization: Bearer <supporter key>` header ጋር (ከታች ይመልከቱ)። የschema header በማይኖርበት ጊዜ servers በነባሪ የተለየ
ፊርማ ያለውን v1 የሽግግር artifact ይጠቀማሉ፣ በዚህም የቆዩ የተጫኑ clients ዝማኔዎችን
መቀበላቸውን ይቀጥላሉ።
2. ይህ ማውረድ ብቻ የሚደረግበት የመተግበሪያ ፍሰት ነው፣ ነገር ግን አሁንም HTTPS ጥያቄ ነው። የሚስተናገደው
መሠረተ ልማት እንደ ምንጭ IP ያሉ የተለመዱ የግንኙነት metadataዎችን ይቀበላል። supporter
key ሲዋቀር፣ sync አገልግሎቱ መብቱን እንዲወስን ያንን key በBearer header ውስጥ ይልካል።
ከላይ ባለው የማስረጃ ወሰን ውስጥ በተገለጸው ትክክለኛው የprivate-server revision ላይ፣
የfeed-request ሒሳብ አያያዝ ለእጅ የስነምግባር ጥሰት ግምገማ key hashesን፣ የተጠቃለለ አጠቃቀምን እና በየቀኑ የሚቀያየር
የIP truncated HMACን ይጠቀማል፤ እነዚያ tables keyንም ሆነ IPውን በጥሬ ቅርጽ አያከማቹም።
የመሠረተ ልማት access logs እና encrypted delivery outbox የተለያዩ የአሠራር
ወሰኖች ናቸው።
3. OmniRoute ጥያቄዎችን፣ ምላሾችን፣ ውይይቶችን፣ የአቅራቢ ማረጋገጫ መረጃዎችን፣ የሞዴል ትራፊክን፣
uptimeን፣ latencyን ወይም የአካባቢያዊ አቅራቢውን ውቅር ወደRadar አገልግሎት ፈጽሞ አይልክም።
4. ምላሹ ይረጋገጣል፣ ትክክለኛነቱ ይፈተሻል፣ እንዲሁም በአካባቢው cache ይደረጋል (
[የደህንነት ሞዴል](#security-model)ን ይመልከቱ)። Radar በትክክል አራት server-side የአውታረ መረብ መንገዶች አሉት፦
`syncRadar()` ለcatalog፣ `syncRadarReferrals()` ለreferrals፣ እና
`syncRadarOffers()` / `syncRadarIntel()` ለsupporter-only offers እና Intel።
**supporter key** የfeed አገልግሎቱ የትኛውን ደረጃ ማቅረብ እንዳለበት እንዲወስን የሚያስችል አማራጭ Bearer token
(`radar_settings.supporter_key`) ነው (
[ደረጃዎች](#tiers-community-and-live)ን ይመልከቱ)። ይህ፦
- ለአቅራቢ ማረጋገጫ መረጃዎች ከሚጠቀሙት ተመሳሳይ AES-256-GCM `encrypt()`/`decrypt()`
helpers (`src/lib/db/encryption.ts`) ጋር **በማከማቻ ላይ encrypted** ሆኖ ይቀመጣል።
- በ`POST /api/radar/settings` (`{ supporterKey: "omr_" + 40 hex chars }`) በኩል ይቀናበራል፣ እና
**ፈጽሞ ተመልሶ አይታይም** — ምላሹ የተሸፈነ ቅርጽ (`omr_****abcd`) ይመልሳል።
- እሱን መቀየር ወይም ማጽዳት catalog፣ referrals፣ offers እና Intel cachesን በአንድ የማይከፋፈል እርምጃ ዋጋ አልባ ያደርጋል።
ቀጣዩ sync/read አዲሱን መብት server-side ይወስናል፤ keyን ማስቀመጥ በራሱ
የአውታረ መረብ ጥያቄ አያደርግም ወይም single-use activation keyን አይጠቀምም።
- በsync GET ላይ እንደ Bearer token ወደfeed አገልግሎቱ ይላካል — ስለ
keyው ሌላ ምንም ነገር ከclient አይወጣም።
---
## ከመርጦ መግባት በፊት የሚታዩ የመዳረሻ እና የደህንነት ደንቦች
እንቅስቃሴ-አልባው ዳሽቦርድ ከሁለቱ የማግበሪያ እርምጃዎች አንዱ ከመከናወኑ **በፊት** እነዚህን ደንቦች ከ
`src/app/(dashboard)/dashboard/radar/RadarAccessExplainer.tsx` ያሳያል።
መደበኛው የመዳረሻ ደረጃ መለኪያ የሚከተለው ነው፦
| ደረጃ | ብቁነት | መዳረሻ | የድግግሞሽ/የማብቂያ ደንብ |
| --------------------- | ------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------- |
| ማህበረሰብ | ማንኛውም ሰው፤ ቁልፍ አያስፈልግም | ሙሉው ካታሎግ በ30 ቀናት ገደማ ዘግይቶ ይቀርባል | ሁልጊዜ ይገኛል፤ ቁልፍ አይሰጥም |
| ኮከብ + መከተል | GitHub OAuth በማከማቻው ላይ ኮከብ መስጠትን እና ባለቤቱን መከተልን ሁለቱንም ያረጋግጣል | አንድ የቀጥታ ካታሎግ ንባብ፣ ከዚያ ማህበረሰብ | በእያንዳንዱ መግቢያ አንድ ጊዜ ይሰጣል፤ ዳግም አይሰጥም |
| ከፍተኛ 10 አስተዋጽዖ አበርካች | በቅርብ ጊዜው በተጠናቀቀው ሳምንታዊ ደረጃ አሰጣጥ ከ1–10 ያሉ ደረጃዎች | 365 የቀጥታ ቀናት | ሲጠየቅ ይወሰዳል፤ ከደረጃ አሰጣጡ መውጣት የተሰጠውን ጊዜ አያሳጥርም |
| ከፍተኛ 100 አስተዋጽዖ አበርካች | በዚያ የደረጃ አሰጣጥ ከ11–100 ያሉ ደረጃዎች | 90 የቀጥታ ቀናት | ተመሳሳይ ሲጠየቅ የሚወሰድ/አንድ ጊዜ ብቻ የሚፈጸም የይገባኛል ጥያቄ ደንብ |
| የደጋፊ ግዢ | የአንድ ጊዜ የ6 ወር፣ የ1 ዓመት ወይም የዕድሜ ልክ ግዢ | የቀጥታ ካታሎግ፣ የተፈረሙ የቀጥታ ቅናሾች እና Intel | ራስ-ሰር ዕድሳት የለም |
| ልገሳ/በእጅ የሚሰጥ ፈቃድ | በባለቤቱ የተገመገመ ልገሳ ወይም ባለቤቱ ለተወሰነ የቀናት ብዛት/ለዕድሜ ልክ የሰጠው ፈቃድ | ለተሰጠው ጊዜ ተመሳሳይ የቀጥታ መብት | ኦዲት የሚደረግበት፣ አንድ ጊዜ ብቻ የሚፈጸም ፈቃድ |
የተዋሃዱ PRs፣ commits እና የተቀየሩ መስመሮች **ለደረጃ አሰጣጥ የሚያገለግሉ ግብዓቶች ብቻ** ናቸው። ከከፍተኛ 100 ውጪ የሆነ መግቢያ፣
የPR ብዛቱ ምንም ያህል ቢሆንም የአስተዋጽዖ አበርካች ፈቃድ አያገኝም። ጊዜ ያላቸው ግዢዎች፣ ልገሳዎች፣ የአስተዋጽዖ አበርካችነት ጊዜያት እና
በእጅ የሚሰጡ ፈቃዶች አሁን ካለው የማብቂያ ጊዜ ላይ ይደመራሉ፤ የዕድሜ ልክ ፈቃድ ከሁሉም ይበልጣል። የደረጃ ለውጥ ከዚህ በፊት
የተሰጠውን ጊዜ ወደኋላ በመመለስ ፈጽሞ አይሰርዝም ወይም አያሳጥርም።
በአገልጋዩ ላይ የሚስተናገደው ፈቃድ ግላዊ ሲሆን፣ ለተጠቃሚው የሚታየው ደንብ በአንድ ጊዜ አንድ ንቁ ጭነት ብቻ እንዲኖር ነው። ይህ
ልቀት የሃርድዌር ቁልፍ እንዳለው **አይገልጽም**፦ የOSS ማመሳሰያው የሃርድዌር አሻራ አይወስድም ወይም
ክሪፕቶግራፊያዊ የመሣሪያ ሊዝ አያስተዳድርም። ከላይ በተረጋገጠው የግል አገልጋይ ማሻሻያ ላይ፣ ተግባራዊ የሆነው
አስፈጻሚነት የመብት ማረጋገጥን፣ እንዲሁም ተመሳሳዩ ንቁ ቁልፍ በ24 ሰዓታት ውስጥ ከአራተኛ የተለየ IP
ሲታይ በእጅ ለሚደረግ ግምገማ የሚያገለግል ምልክትን ያካትታል። ያ ምልክት ቁልፍን በራስ-ሰር ፈጽሞ አያግድም ወይም አይሰርዝም። መልሶ ማግኘት
የጠፋውን ቁልፍ ይሰርዝና ይተካዋል፣ ነገር ግን ነባሩን የማብቂያ ጊዜ ያስጠብቃል፤ የተገዛውን ወይም የተሰጠውን ጊዜ
እንደገና አያስጀምርም።
የቀጥታ ቅናሾች በእጅ የተመረጡ ሲሆኑ ሊቀየሩ ወይም ሊያበቁ ይችላሉ። የመርጦ መግቢያ ማያ ገጹ ትክክለኛውን
የግላዊነት ወሰንም ይገልጻል፦ የተፈረመ የካታሎግ/ሪፈራል ሜታዳታ ይወርዳል፤ ትክክለኛ ቁልፍ በተጨማሪ
የተፈረሙ ቅናሾችን እና Intelን ይከፍታል፤ Bearer ቁልፉ እና መደበኛ የግንኙነት ሜታዳታ ወደ ሚስተናገደው አገልግሎት ይደርሳሉ፤
ጥያቄዎች፣ ምላሾች፣ ውይይቶች፣ የአቅራቢ ማረጋገጫዎች፣ የሞዴል ትራፊክ፣ የሥራ ጊዜ፣ መዘግየት እና የአካባቢያዊ
አቅራቢ ውቅር ግን አይደርሱም።
---
## የደጋፊ ቁልፍ ማግኘት
የማግበሪያ ማያ ገጹ (`/dashboard/radar`) የደጋፊ ቁልፍ **ለማግኘት** ወደ ሁለት ሂደቶች
የሚወስዱ አገናኞችን ይዟል። የOSS ማከማቻው ራሱ ቁልፍ ፈጽሞ አያወጣም፣ የክፍያ ኮድ ፈጽሞ
አያስኬድም፣ እንዲሁም **ዋጋ ፈጽሞ አይገልጽም** — ዋጋ የሚወሰነውና የሚታየው ሙሉ በሙሉ
በመዳረሻ ገጾቹ ላይ እንጂ በዚህ ማከማቻ ውስጥ አይደለም (የዝርዝር መግለጫ ውሳኔ D14)።
- **"አስተዋጽዖ አድራጊ ነኝ"** — `RADAR_CONTRIBUTOR_CLAIM_URL`ን (ነባሪ
`https://radar.omniroute.online/auth/github`) ይከፍታል፤ ይህም በግል Radar አገልጋይ ላይ
የሚስተናገድ የGitHub OAuth ጥያቄ ሂደት ነው። የቅርብ ጊዜውን የተጠናቀቀ ሳምንታዊ ደረጃ
ይፈትሻል፦ ከፍተኛ 10 365 ቀናትን ሲያገኙ፣ ከ11–100 ያሉ ደረጃዎች 90 ቀናትን ያገኛሉ።
ከከፍተኛ 100 ውጭ የPR ብዛት በፍጹም መዳረሻ አይሰጥም፤ በምትኩ ሂደቱ የተለየውን
የኮከብ + የመከተል አንድ ጊዜ ጥቅም ላይ የሚውል ደረጃ ይፈትሻል።
- **"ፕሮጀክቱን ይደግፉ"** — `RADAR_SUPPORTER_PLANS_URL`ን (ነባሪ
`https://radar.omniroute.online/planos`) ይከፍታል፤ ይህም ለአንድ ጊዜ የ6-ወር፣ የ1-ዓመት እና
የዕድሜ ልክ አማራጮች የተስተናገዱበት ገጽ ነው። የOSS ገጹ አሁንም ምንም የገንዘብ ዋጋ
አያሳይም።
ሁለቱም URLs በአገልጋይ በኩል (`src/lib/radar/links.ts`፣ ከ`RADAR_FEED_URL` ጋር ተመሳሳይ
የenv-override ንድፍ) ይወሰናሉ፣ እና በነባሩ `GET /api/radar/settings` ምላሽ
(`contributorClaimUrl`፣ `supporterPlansUrl`) በኩል ወደ ዳሽቦርዱ ይተላለፋሉ — የደንበኛ
ኮምፖነንቱ ራሱ `process.env`ን ፈጽሞ አያነብም።
| Var | ዓላማ |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `RADAR_CONTRIBUTOR_CLAIM_URL` | የአስተዋጽዖ አድራጊ ጥያቄ URLን ይተካል (ነባሪ `https://radar.omniroute.online/auth/github`)። |
| `RADAR_SUPPORTER_PLANS_URL` | የደጋፊ ዕቅዶች URLን ይተካል (ነባሪ `https://radar.omniroute.online/planos`)። |
### የጠፋ የደጋፊ ቁልፍን መልሶ ማግኘት
የተስተናገደው አገልግሎት የመልሶ ማግኛ መግቢያ ነጥብ `https://radar.omniroute.online/recover`
ነው፤ ከዕቅዶች ገጹም አገናኝ ተደርጎለታል። የአካባቢው ጭነት የገዢውን/የአስተዋጽዖ
አድራጊውን ኢ-ሜይል ፈጽሞ ስለማይቀበል እና ከተመሰጠሩ ቅንብሮቹ ጥሬ ቁልፍን ዳግም
ማዋቀር ስለማይችል፣ መልሶ ማግኘት ሙሉ በሙሉ ከOSS ደንበኛው ውጭ ሆኖ ይቆያል።
1. ከቁልፉ ጋር የተያያዘውን ኢ-ሜይል ያስገቡ። ሊመለስ የሚችል ፈቃድ ቢኖርም ባይኖርም
አገልግሎቱ ተመሳሳይ የተቀበለ ገጽ ይመልሳል፤ ስለዚህ ቅጹ መለያዎችን አይዘረዝርም።
2. ብቁ ከሆነ፣ የማድረሻ ሠራተኛው አጭር ዕድሜ ያለውና ለአንድ ጊዜ የሚያገለግል አገናኝ
ይልካል። አገናኙን መክፈት ቶከኑን ወዲያውኑ ወደ ጊዜያዊ የተመሰጠረ
`HttpOnly`/`Secure` ኩኪ ያንቀሳቅሰዋል፣ ከዚያም ወደ ንጹሕ `/recover` URL ያዞራል፤
ገጹ ምንም ቶከን፣ ኢ-ሜይል፣ የቀድሞ ቁልፍ ወይም ምትክ ቁልፍ አይይዝም።
3. መሻሩን ያረጋግጡ። የግል አገልግሎቱ የቀድሞውን ቁልፍ ይሽራል፣ በተመሳሳይ
ዕቅድ/የማብቂያ ጊዜ ምትኩን ይፈጥራል፣ እና በአንድ ግብይት ውስጥ በኢ-ሜይል እንዲላክ
ወረፋ ያስይዘዋል። ምትኩ ፈጽሞ ወደ አሳሹ አይመለስም።
4. ምትኩን በ`/dashboard/radar` ውስጥ ይለጥፉ። የቀድሞው ቁልፍ አሁን ወደ `community`
መውረድ አለበት፤ ምትኩ የተረጋገጠ `live` ማመሳሰል ማምረት አለበት። ተመሳሳዩን
የመልሶ ማግኛ አገናኝ ዳግም መክፈት አጠቃላይ የሆነ ልክ ያልሆነ/ጊዜው ያለፈ
ምላሽ በመስጠት ሊከሽፍ ይገባል።
የተስተናገደው የመልሶ ማግኛ route እና የደብዳቤ ሠራተኛ በኮዱ ውስጥ ሊኖሩ ይችላሉ፣
ነገር ግን በተወሰነ ማሰማራት ውስጥ አሁንም የማይገኙ ሊሆኑ ይችላሉ። አገልጋዩ
እስኪሰማራ፣ የማድረሻ አቅራቢው ቁጥጥር በተደረገበት ተቀባይ እስኪዋቀር እና ሙሉው
ለአንድ ጊዜ የሚያገለግል አገናኝ እስኪፈተሽ ድረስ ሂደቱን ለምርት ዝግጁ ብለው አይጥሩት።
አንድ ጎብኚ ቁልፍ (`omr_` + 40 hex ቁምፊዎች) ካገኘ በኋላ፣ የማግበሪያ ማያ ገጹ
(`src/app/(dashboard)/dashboard/radar/page.tsx`) ቁልፍ ለመለጠፍ የሚያስችል ግብዓትን
እንደ ዋና መንገድ ይዟል፦ ቁልፍ ለጥፎ ማስገባት `POST /api/radar/settings`
(`{ optIn: true, supporterKey }`)ን በአንድ ጥሪ ይልካል — ቁልፍ መለጠፍ ሁለቱንም፣
ቁልፉን ማቀናበርና መሳተፍን መምረጥ፣ በማከናወን ማያ ገጹን ይከፍታል። ቅርጸቱ
(`omr_` + 40 hex ቁምፊዎች) ለተጠቃሚ ምቾት በመጀመሪያ በደንበኛ በኩል በጋራው
`isValidSupporterKeyFormat()` አጋዥ (`src/lib/radar/supporterKey.ts`) ይፈተሻል፤
በሁለቱም ሁኔታ የአገልጋዩ Zod schema የመጨረሻ ሥልጣን ያለው ማረጋገጫ ነው። አንዴ
ቁልፍ ከተቀናበረ፣ የማግበሪያ ማያ ገጹ ከባዶ ግብዓት ይልቅ የተሸፈነውን ቅርጽ
(ከ`GET /api/radar/settings` የሚመጣውን `supporterKeyMasked`) ያሳያል፤ አዲስ ቁልፍ
ለመለጠፍ "ቁልፍ ቀይር" መቆጣጠሪያም ይኖረዋል — ጥሬው ቁልፍ ዳግም ፈጽሞ አይታይም።
ከላይ ያሉት ሁለቱ የጥያቄ/ዕቅዶች አዝራሮች በመጀመሪያ ቁልፍን _ለማግኘት_ መንገዶች
ሆነው ይቀጥላሉ፤ ይህ ግብዓት ደግሞ ቁልፍ ቀድሞውኑ ያለው ኦፕሬተር የሚያገብርበት ነው።
### ከመጀመሪያ እስከ መጨረሻ ማግበር እና የተመራ ማዋቀር
የግል feed አገልግሎቱ እና ይህ የOSS ደንበኛ ሆን ተብሎ ጠባብ የተደረገ ወሰን አላቸው፦
አገልግሎቱ የደጋፊ ቁልፉን ያወጣል እና ያረጋግጣል፣ በአካባቢው ያለው OmniRoute
ጭነት ደግሞ ቁልፉን ይመሰጥራል፣ የተፈረሙ artifactsን በአገልጋይ በኩል ያመሳስላል፣
እና የአቅራቢ ማዋቀርን ይመራል። የታገዘው የማረጋገጫ ቅደም ተከተል፦
1. አዲስ የወጣ ወይም መልሶ የተገኘ ቁልፍን ከአስተዋጽዖ አድራጊው የይገባኛል ጥያቄ፣ plans/checkout፣ የመልሶ ማግኛ
ሂደት፣ ወይም ፈቃድ ካለው የግል አገልጋይ ኦፕሬተር ያግኙ። ጥሬውን ቁልፍ በምዝግቦች፣
ቅጽበታዊ ምስሎች፣ የጉዳይ አስተያየቶች፣ ወይም የትዕዛዝ መስመር ነጋሪ እሴቶች ውስጥ አይለጥፉ።
2. በአካባቢያዊው OmniRoute ጭነት ላይ የ`RADAR_ENABLED` ባህሪ ጠቋሚን ያንቁ። ይህ UIን
ያሳያል፣ ነገር ግን የተለየው የመሳተፍ ምርጫ እስኪቀመጥ ድረስ በኔትወርክ ላይ ምንም እንቅስቃሴ አያደርግም።
3. `/dashboard/radar`ን ይክፈቱ፣ ቁልፉን ይለጥፉ እና ያግብሩ። አሳሹ አንድ አካባቢያዊ
`POST /api/radar/settings` ከ`{ optIn: true, supporterKey }` ጋር ይልካል፤ ቁልፉ በአካባቢው ይመሰጠራል እና
ምላሹ `omr_****<last4>`ን ብቻ ይይዛል።
4. የማግበሪያ ማያ ገጹ የካታሎግ ማመሳሰሉን እንዲያከናውን ይፍቀዱ፣ ወይም **አሁን አመሳስል**ን ይምረጡ። ገጹ
`live`፣ የፊድ ስሪት እና የማምጫ ጊዜ ማሳየቱን ያረጋግጡ። ማንነቱ ለተረጋገጠ አካባቢያዊ ምርመራ፣
`GET /api/radar/status` ቁልፉን ሳይመልስ የመሳተፍ ምርጫ/የቁልፍ መኖርን እና አራቱን የመሸጎጫ ሁኔታዎች
ያሳያል። `POST /api/radar/sync-all` ካታሎግን፣ ሪፈራሎችን፣ ቅናሾችን እና Intelን በግልጽ ማደስ ይችላል።
5. `/dashboard/radar/setup?provider=<provider>`ን ይክፈቱ። በአቅራቢው የሚተዳደረውን የምስክርነት መረጃ URL
ይከተሉ፣ **API ቁልፍ አክል**ን ይምረጡ፣ በእውነተኛው የአቅራቢ ቅጽ በኩል ያስቀምጡ፣ ወደ መመሪያው ይመለሱ እና
**ግንኙነትን ፈትሽ**ን ያሂዱ። መመሪያው መደበኛዎቹን `/api/providers` እና
`/api/providers/<connection-id>/test` ራውቶች ይጠቀማል፤ ትይዩ የRadar ምስክርነት መረጃ አይፈጥርም።
6. ቢያንስ ሁለት ተኳኋኝ የአቅራቢ ግንኙነቶች ንቁ ከሆኑ በኋላ `/dashboard/radar/combos`ን ይክፈቱ።
የተጠቆመውን ቤተሰብ ይገምግሙ እና ነባሩን የኮምቦ API በመጠቀም ኮምቦውን ይፍጠሩ። ቅናሾች እና
Intel የተለያዩ፣ የቀጥታ ሁኔታ ብቻ ያላቸው የተፈረሙ መሸጎጫዎች ሆነው ይቆያሉ፣ እና በተመደቡላቸው የRadar ገጾች ላይ ሊፈተሹ ይችላሉ።
7. `/dashboard/radar`ን እና የማዋቀሪያ ገጹን እንደገና ይጫኑ። የመሳተፍ ምርጫው፣ የተሸፈነው የቁልፍ ሁኔታ፣ የተረጋገጠው መሸጎጫ፣ የተቀመጠው
የአቅራቢ ግንኙነት እና የሙከራ ድርጊቱ ከዳግም ጭነቱ በኋላም መቆየት አለባቸው። ጥሬው ቁልፍ እና የአቅራቢው
ምስክርነት መረጃ ከእይታ ከጠፉ በኋላ ብቻ ማስረጃ ይቅረጹ።
ቁልፍ ማስቀመጥ በራሱ የቀጥታ መብት ማረጋገጫ አይደለም። ማረጋገጫው የግል
አገልግሎቱ `GET /v1/license/check` ውጤት፣ በOSS ካታሎግ የቀረበው `live` ደረጃ፣ የተረጋገጠ የተፈረመ
መሸጎጫ እና እውነተኛው የአቅራቢ ግንኙነት/ሙከራ ፍሰት ጥምረት ነው። ልክ ያልሆነ፣ ጊዜው ያለፈበት ወይም የተሻረ ቁልፍ
ካታሎጉን በደህና ወደ `community` ዝቅ ያደርገዋል፤ እንደ ስኬታማ የቀጥታ ቁልፍ ማረጋገጫ መገለጽ የለበትም።
### የግል የአስተዳዳሪ ፓነል አገናኝ
`RADAR_ADMIN_URL` እንደ አማራጭ በCosts የጎን አሞሌ ክፍል ውስጥ ለተጠቃሚው ከሚታየው
የRadar ንጥል ቀጥሎ **Radar Admin ↗**ን ያክላል። ሆን ተብሎ ነባሪ እሴት አልተሰጠውም፤ ተለዋዋጩ
ካልተዋቀረ ወይም ልክ ካልሆነ፣ ቋሚው የጎን አሞሌ፣ የትዕዛዝ ምርጫ ሰሌዳ እና የጎን አሞሌ ማበጀት ማያ ገጽ ምንም
የአስተዳዳሪ ንጥል ወይም የግል URL አይዙም።
እሴቱ በአገልጋዩ በኩል ይወሰናል እና በአስተዳደር ማንነት ማረጋገጫ በተጠበቀው
`GET /api/settings` ምላሽ በኩል ማንነቱ ለተረጋገጠ የዳሽቦርድ ክፍለ ጊዜ ብቻ፣ ወይም በአካባቢያዊ መግቢያ-አልባ የመነሻ ማዋቀር ወቅት ለታመነው
loopback ባለቤት ይተላለፋል። CLI፣ የውስጥ አገልግሎት እና manage-scope API-key
ማንነት ማረጋገጫ አይቀበሉትም። አሳሹ በ`noopener noreferrer` የሚከፈተውን ውጫዊ አገናኝ
ከማሳየቱ በፊት ምላሹን እንደገና ያረጋግጣል።
ከምስክርነት መረጃ ነጻ የሆነ HTTPS tunnel/tailnet URL ይጠቀሙ። መደበኛ HTTP የሚፈቀደው እንደ
`http://127.0.0.1:9351` ላለ loopback SSH ማስተላለፊያ ብቻ ነው፤ ሌሎች መርሃግብሮች፣ የተካተቱ ምስክርነት መረጃዎች፣ የተበላሹ URLs እና
የርቀት HTTP መዳረሻዎች በደህንነት ሁኔታ እንዳይሰሩ ይደረጋሉ እና አሰሳውን እንቅስቃሴ-አልባ ያደርጋሉ።
---
## የደህንነት ሞዴል
### በትክክለኛዎቹ ባይቶች ላይ የEd25519 ፊርማ
የፊዱ ይዘት በEd25519 ይፈረማል። `verifyFeedBytes()`
(`src/lib/radar/verify.ts`) በአውታረ መረቡ ላይ በተቀበላቸው **ትክክለኛ የምላሽ ባይቶች**
ላይ ፊርማውን ያረጋግጣል — ይዘቱ ከማረጋገጡ በፊት ፈጽሞ እንደገና አይሰራጭም፤ ስለዚህ
ባይት-በ-ባይት እንደገና ኢንኮድ ማድረግ በድብቅ የፊርማ ማረጋገጫውን ማሰናከል ወይም ማለፍ
አይችልም። የማረጋገጫ ውድቀት (`invalid_signature`) ይዘቱ ከመተንተኑ ወይም
ከመሸጎጡ በፊት ማመሳሰሉን ያቋርጣል።
### የተወሰነ የሕዝብ ቁልፍ + ማዞር
ማረጋገጫውን የሚያከናውነው የሕዝብ ቁልፍ በ`src/lib/radar/pinnedKeys.ts`
(`PINNED_FEED_PUBLIC_KEYS`) ውስጥ ተወስኗል፤ ይህም አዲስ ቁልፍ ከማዞር በፊት ከፊት
እንዲታከልና በቀድሞ ቁልፍ የተፈረሙ አሮጌ የተሸጎጡ ፊዶች እንደገና
እስኪመሳሰሉ ድረስ ትክክለኛ ሆነው እንዲቆዩ በድርድር መልክ ተቀምጧል።
### ለፎርክ ምቹ የenv መሻሪያዎች
ሁለት የenv ተለዋዋጮች ፎርኮችና በራሳቸው የሚያስተናግዱ ተጠቃሚዎች ነባሪውን
የOmniRoute አገልግሎት ከመጠቀም ይልቅ ደንበኛውን ወደ ራሳቸው ፊድ እንዲያመለክቱ ያስችላሉ —
ከታች [ፊድን በራስዎ እንዴት እንደሚያስተናግዱ](#how-to-self-host-a-feed) ይመልከቱ፦
| ተለዋዋጭ | ዓላማ |
| ------------------- | ----------------------------------------------------------------------------------- |
| `RADAR_FEED_URL` | የፊዱን መሠረታዊ URL ይተካል (ነባሪ `https://radar.omniroute.online`)። |
| `RADAR_FEED_PUBKEY` | የተወሰነውን የሕዝብ ቁልፍ (base64-DER SPKI ወይም PEM) በመተካት አብሮ የተካተተውን ድርድር በዚህ አንድ ቁልፍ ይተካል። |
### የስሪት ዝቅተኛ ገደብ
`syncRadar()` የወረደው ፊድ `version` አሁን ከተሸጎጠው ስሪት በጥብቅ የበለጠ ካልሆነ
ውድቅ ያደርገዋል (`compareVersions()`፣ በነጥብ የተለየ `YYYY.MM.DD.n` ንጽጽር) —
`{ status: "stale" }`። ይህ የተጠለፈ ወይም በስህተት የተዋቀረ የፊድ መጨረሻ ነጥብ ደንበኛን
ወደ ቀድሞ፣ በተለየ መንገድ ወደተፈረመ ይዘት መመለስ እንዳይችል ይከላከላል።
### ሁለት ቀኖች፣ እና ሁለቱም ለምን እንደሚቀመጡ
የተሸጎጠ ፊድ ሁለት የተለያዩ ቀኖችን ይይዛል፤ ሁለቱን ማምታታት ሁለቱም
የሚቀመጡበት ዋና ምክንያት ነው፦
| መስክ | የመጣበት | የሚመልሰው ጥያቄ |
| ------------- | -------------- | ------------------------ |
| `generatedAt` | የተፈረመው የፊድ ይዘት | **ውሂቡ** ምን ያህል ያረጀ እንደሆነ |
| `fetchedAt` | የዚህ ጭነት ሰዓት | ይህ ጭነት መቼ **እንዳወረደው** |
ከደቂቃዎች በፊት የወረደ ፊድ ከሳምንታት በፊት የተዘጋጁ አሃዞችን ሊይዝ ይችላል፤ ስለዚህ
`fetchedAt` ብቻውን ተደራቢው ከተቀመጠበት መሠረታዊ ውሂብ የበለጠ ወቅታዊ መሆኑን
ለአስተዳዳሪው ሊገልጽ አይችልም። ሁለቱም በ`radar_feed_cache` ውስጥ ይቀመጣሉ፣
በ`getRadarCatalog().meta` ይመለሳሉ፣ እና በ`GET /api/radar/status` ለየብቻ
ሪፖርት ይደረጋሉ። የ`generated_at` ዓምድ ከመኖሩ በፊት (migration 163) የተሸጎጠ ረድፍ
እንደ`null` ይነበባል — ያልታወቀው የማውረጃ ጊዜን ከመዋስ ይልቅ ያልታወቀ ሆኖ
ይቆያል። `radar_referrals_cache` ከmigration 142 ጀምሮ የራሱን `generated_at` ይዞ ቆይቷል።
ከላይ ያለው የስሪት ዝቅተኛ ገደብ የሚያነጻጽረው `version`ን እንጂ ከሁለቱ ቀኖች
አንዱን አይደለም።
ሁለት ክፍተቶች አሁንም አሉ፣ ሁለቱም ሆን ተብለው የተተዉ ናቸው፦ ዳሽቦርዱ አሁንም
`Last fetched`ን ብቻ ያሳያል፤ ስለዚህ የግንባታ ቀኑን በዚያ ለማንበብ አዲስ መለያ
(እና 41 የአካባቢ ቋንቋ ግቤቶቹ) ያስፈልጋል፤ እንዲሁም የቅናሾችና የመረጃ መሸጎጫዎች
የፊድ ንድፎቻቸው የግንባታ ቀን ቢይዙም እንኳ ምንም የግንባታ ቀን አያስቀምጡም —
ስለዚህ `GET
/api/radar/status` እንደ "ያልታወቀ" ሊነበብ የሚችል `null` ከማሳወቅ ይልቅ ለእነዚህ
ሁለት መስኩን ይተወዋል።
### የንድፍ ማረጋገጫ
የወረዱት ባይቶች የፊርማ ማረጋገጫው **ከተከናወነ በኋላ** በ`RadarFeedSchema`
(`src/lib/radar/feedSchema.ts`፣ የZod ንድፍ) መሠረት ይተነተናሉ እና ይረጋገጣሉ።
የንድፍ አለመዛመድ `{ status: "invalid_schema" }`ን ይመልሳል፣ መሸጎጫውም
ሳይነካ ይቀራል። የተሸጎጠው ይዘት በእያንዳንዱ ንባብ (`getRadarCatalog()`) ላይ
ለመከላከያ እንደገና ይረጋገጣል — የተበላሸ ወይም በእጅ የተስተካከለ የመሸጎጫ ረድፍ
ከመቅረብ ይልቅ ወደ መሠረታዊው ውሂብ ይመለሳል።
### የምላሽ መጠን ገደብ (10 MB)
`syncRadar()` በፊዱ ምላሽ አካል ላይ **የ10 MB ጥብቅ ገደብ** ያስፈጽማል — የተፈረመው
ፊድ በKB መጠን ያለ JSON ሰነድ ነው፤ ስለዚህ ከዚህ በላይ ያለ ማንኛውም ነገር
ህጋዊ ካታሎግን ሳይሆን በስህተት የተዋቀረ ወይም ጎጂ `RADAR_FEED_URL`ን
(ወይም ከላይኛው ምንጭ የሚቀርብ ቆሻሻ ውሂብን) ያመለክታል። አፈጻጸሙ ሁለት ደረጃዎች አሉት፦
1. ራስጌው ከገደቡ በላይ የሆነ ዋጋ ሲገልጽ የ`Content-Length` ቅድመ ምርመራ
የምላሽ አካሉን ማንበብ ሙሉ በሙሉ ይዘላል።
2. የምላሽ አካሉን በማንበብ ጊዜ የሚደረግ የጠቅላላ መጠን ክትትል `Content-Length`
ባይኖርም ወይም እውነተኛውን መጠን አሳንሶ ቢገልጽም ገደቡን ያስፈጽማል —
ራስጌው በራሱ ፈጽሞ አይታመንም። የተሰበሰቡትን ክፍሎች ማገናኘት በኋላ
ለሚደረገው የEd25519 ፊርማ ማረጋገጫ የሚያስፈልጉትን ትክክለኛ ባይቶች ይጠብቃል።
ገደቡን ማለፍ `{ status: "too_large" }`ን ይመልሳል እና መሸጎጫውን ሳይነካ ይተወዋል፤
ይህም ከሌሎች የማመሳሰል ውድቀቶች (`invalid_signature`፣ `invalid_schema`፣ `stale`)
ጋር ተመሳሳይ የማያጠፋ አሠራርን ይከተላል።
---
## ደረጃዎች፦ `community` እና `live`
የፊድ ንድፉ `tier: "community" | "live"` መስክ ይይዛል፤ ይህም በጥያቄው መሠረት
(የደጋፊ ቁልፉ መኖርና ትክክለኛነት) በፊድ አገልግሎቱ **በሰርቨር በኩል**
ይወሰናል — ክላይንቱ የራሱን ደረጃ ፈጽሞ አይወስንም።
- **`community`** — ከአዲሱ ውሂብ በግምት 30 ቀናት የዘገየ ነፃ ካታሎግ።
ያልተረጋገጠ ወይም ልክ ያልሆነ ቁልፍ ያለው ጥያቄ የሚቀበለው ይህንን ነው።
- **`live`** — ትክክለኛ የደጋፊ ቁልፍ ላላቸው ጥያቄዎች የሚቀርበው በጣም የቅርብ ጊዜ
ካታሎግ።
**ልክ ያልሆነ ወይም ጊዜው ያለፈበት የደጋፊ ቁልፍ ወደ `community` ይወርዳል — ፈጽሞ
ስህተት አይሆንም።** የማመሳሰል መንገዱ የፊርማ/ንድፍ/ስሪት አለመሳካቶችን (ሁሉም
ሊያገግሙ የሚችሉና በመሸጎጫው ሁኔታ ላይ ከባድ ጉዳት የማያደርሱ) ከተሳካ
`{ status: "updated", version, tier }` ብቻ ይለያል። ክላይንቱ ሊያስተናግደው
የሚገባ የደረጃ-ተኮር የስህተት መንገድ የለም።
### የሚቀርበው ደረጃ ከተፈረመው አካል ሳይሆን ከምላሽ ራስጌ ይመጣል
የተፈረመው የፊድ **አካል** `tier` መስክ ሁልጊዜ `"live"` ነው — የፊድ አገልግሎቱ
**ለእያንዳንዱ ስሪት ሁለት የተፈረሙ አርቲፋክቶችን** ያቀርባል፦ live ወቅታዊ
ዘመቻዎችን ያካትታል፣ community ግን ያስቀራቸዋል። እያንዳንዱ አርቲፋክት በራሱ
ትክክለኛ ባይቶች ላይ ይፈረማል። አካሉ አሁንም የመብት ውሳኔው ምንጭ አይደለም፤
ለአንድ ጥያቄ በተግባር የተመረጠው ደረጃ በ**`x-omniroute-feed-tier` የምላሽ ራስጌ**
ውስጥ ይላካል፣ ይህም ከጥያቄው `Authorization` ቁልፍ በመነሳት በሰርቨር በኩል
ይወሰናል።
`syncRadar()` (`src/lib/radar/sync.ts::parseServedTierHeader()`) ክላይንቱ ሊያምነው
የሚገባውን ደረጃ የሚወስን ብቸኛ ቦታ ነው፦
1. `x-omniroute-feed-tier`ን በ`RadarTierSchema` (Zod) ይተንትኑ — የሌለ ራስጌ፣ ወይም
በትክክል `"community"` ወይም `"live"` ያልሆነ እሴት **እንደሌለ**
ይቆጠራል (እንዳለ ሆኖ በመሸጎጫው/UI ውስጥ ፈጽሞ አይታመንም፤ ይህም ራስጌው
ከመኖሩ በፊት የነበሩ የቆዩ የፊድ ሰርቨሮችንም ያካትታል)።
2. ደረጃ 1 ምንም ነገር ካላስገኘ ብቻ ወደ ተፈረመው አካል `tier` መስክ
(ሁልጊዜ `"live"`) ይመለሱ።
3. የተወሰነው ደረጃ በመሸጎጫ ውስጥ የሚቀመጠውና እንደ `{ status: "updated",
version, tier }` የሚመለሰው ነው — ዳሽቦርዱ የሚያሳየው ይህንን እሴት እንጂ የአካሉን
ጥሬ መስክ አይደለም።
---
## በንባብ ጊዜ የተደራቢ ውህደት ደንቦች
`applyFeed()` (`src/lib/radar/applyFeed.ts`) በመሸጎጫ ያለውን ፊድ በስታቲክ
መሠረታዊ ውሂቡ **ላይ** በ**ንባብ ጊዜ**፣ በ`getRadarCatalog()` ውስጥ ያዋህዳል።
የመሠረታዊ ውሂቡ ድርድር (`FREE_MODEL_BUDGETS`) ፈጽሞ አይቀየርም — በእያንዳንዱ
ጥሪ ላይ አዲስ `MergedEntry[]` ይሰላል።
በቅድሚያ ቅደም ተከተል አራት ደንቦች፦
1. **ፊዱ የአካባቢ ማሻሻያን ፈጽሞ አይተካም።** በየመስኩ፦ ኦፕሬተሩ
በአንድ ግቤት ላይ ያለ መስክን ካበጀ (`localOverrides` ካርታ፣ ቁልፉ
`provider:modelId`)፣ ለዚያ የተወሰነ መስክ የፊዱ እሴት ይዘለላል — የኦፕሬተሩ
እሴት ያሸንፋል።
2. **`enabled: false` ግቤቱን ከምንጩ መረጃ ጋር ያሰናክለዋል።** አንድን ግቤት
የሚያጠፋ የፊድ ግቤት በተዋሃደው ውጤት ላይ `enabled: false` እና
`disabledBy: "radar"` ያስቀምጣል፤ በዚህም UI አንድ ግቤት ከሚገኝ ወደ ተሰናከለ
_ለምን_ እንደተቀየረ ማብራራት ይችላል።
3. **በፊዱ ውስጥ የሌለ በተጠቃሚ የታከለ ግቤት ሳይነካ ይቆያል።** በመሠረታዊ
ውሂቡ ውስጥ ብቻ ያሉ (ወይም በአካባቢው የታከሉ) እና ተጓዳኝ የፊድ ግቤት
የሌላቸው ግቤቶች ሳይቀየሩ ያልፋሉ።
4. **በማጥፋት ምልክት የተደረገበት ግቤት ፈጽሞ እንደገና አይመለስም።** ኦፕሬተሩ
አንድን ግቤት በግልጽ ከሰረዘ (`tombstones` ስብስብ)፣ ፊዱ ያንን
`provider:modelId` በኋለኛ ስሪት እንደገና ቢያክለውም መልሶ አያመጣውም።
ሊስተካከሉ የሚችሉ መስኮችና የማጥፋት ምልክቶች በ
`radar_local_model_state` (ማይግሬሽን `153_radar_local_model_state.sql`) ውስጥ
በቋሚነት ይቀመጣሉ። ይፋዊው የDB አስማሚ (`src/lib/db/radar.ts`) እነዚያን ረድፎች
በ`applyFeed()` ወደሚጠቀምባቸው `localOverrides` ካርታ እና `tombstones` ስብስብ
ይቀይራል፤ የምርት `getRadarCatalog()` የባንዲራ፣ የመሸጎጫ እና የንድፍ መግቢያ
ቁጥጥሮች ካለፉ በኋላ ያንን ሁኔታ ይጭናል። በኦፕሬተሩ ሊስተካከሉ የሚችሉት
`displayName` እና `enabled` ብቻ ናቸው። የአቅራቢ/ሞዴል ማንነት፣ የፊድ ምንጭ
መረጃ፣ ኮታ፣ ችሎታዎች፣ ToS እና የማዋቀሪያ ውሂብ በዚህ በይነገጽ በኩል
ሊጻፉ አይችሉም።
ዳሽቦርዱ አራት የአካባቢ ድርጊቶችን ያቀርባል፦
- **አርትዕ** የአካባቢውን የማሳያ ስምና የነቃ/የጠፋ ሁኔታ ይቀይራል።
- **የአካባቢ ለውጦችን ዳግም አስጀምር** የማጥፋት ምልክቱን ሳይቀይር ሁለቱንም
ሊስተካከሉ የሚችሉ መስኮች ያጸዳል።
- **ደብቅ** የማጥፋት ምልክት ይፈጥራል፤ ስለዚህ በኋላ የሚመጡ የፊድ ዝማኔዎች
ረድፉን እንደገና መፍጠር አይችሉም።
- **መልስ** የማጥፋት ምልክቱን ያስወግዳል፤ በተናጠል የተቀመጠ ማሻሻያ ካለ
አሁንም ተግባራዊ ሆኖ ይቆያል።
የፊድ `enabled: false` የደህንነት ልዩ ሁኔታ ሆኖ ይቆያል፦ ጊዜ ያለፈበትን
የአካባቢ `enabled: true` ያሸንፋል፣ የተዋሃደውን ግቤት እንደተሰናከለ ያቆያል፣
እና `disabledBy: "radar"` ይመዘግባል።
የካታሎግ ህትመቶች `schemaVersion: 2` ይጠቀማሉ። `contextWindow` እና እያንዳንዱ
`tools`፣ `vision` እና `thinking` በተናጠል `number | null` / `boolean | null` ናቸው፦
`null` ማለት ያልታወቀ ማለት ሲሆን፣ `false` ማለት ግን በD16 የተረጋገጠ ይፋዊ
የአቅራቢ ምንጭ ችሎታው እንደሌለ በግልጽ ይገልጻል ማለት ነው። የውስጥ
OmniRoute ሬጅስትሪ/ሞዴል-ዝርዝር ባንዲራዎች በቀጥታ ወደ ፊድ እውነታዎች ፈጽሞ
አያድጉም። ክላይንቱ አሁንም v1 ቅጽበታዊ ቅጂዎችን ይቀበላል፤ የቀድሞው
መገንቢያ `false`ን እንደ አለመኖር ቦታ ያዥ ስለተጠቀመ፣ v1 `false` ወደ
ያልታወቀ ይደበኛል፣ v1 `true` ግን እንደ እውነታ ይቆያል። ያልታወቁ የንድፍ
ስሪቶች በነባሪ ይከለከላሉ፣ እና የመጨረሻው ትክክለኛ መሸጎጫ እንደሚገኝ
ይቆያል። ባዶ ያልሆነ አውድ/ችሎታ ያለው እያንዳንዱ v2 ሞዴል ማረጋገጫ
የማይጠይቅ HTTPS `metadataEvidenceUrls[]` ሊኖረው ይገባል፤ አለበለዚያ የንድፍ
ማረጋገጫው አይሳካም እና መሸጎጫው አይተካም። የካታሎጉ ሰንጠረዥ ሦስቱንም
ሁኔታዎች እንደ `✓`፣ `✕` እና `?` ያሳያል።
### የተመሩ ጥምረቶች እና MCP መዳረሻ
የተረጋገጡ `familyId` እሴቶች ከንባብ ጊዜ ተደራቢ ውህደቱ በኋላም ይቆያሉ፣ እና
ንጹሕ የሆነውን `buildRadarComboSuggestions()` ሞጁል
(`src/lib/radar/comboSuggestions.ts`) ያንቀሳቅሳሉ። አንድ ቤተሰብ የሚጠቆመው
ቢያንስ ሁለት የተለያዩ አቅራቢዎች ንቁ ግንኙነቶች ሲኖራቸውና ትክክለኛውን
በጥንቃቄ የተመረጠ የሞዴል ID ሲያቀርቡ ብቻ ነው። የተሰናከሉ ሞዴሎች፣
ንቁ ያልሆኑ አቅራቢዎች፣ የሌሉ የሞዴል IDs፣ አንድ አባል ብቻ ያላቸው
ቤተሰቦች እና አሻሚ የተለዋጭ ስም/ቅድመ ቅጥያ ማዛመዶች በነባሪ ይከለከላሉ።
ጥቆማዎች ነባሩን `priority` ስትራቴጂ ይጠቀማሉ፣ ከፍተኛውን ተደጋጋሚ ወርሃዊ
በጀት በመጀመሪያ ያስቀምጣሉ፤ UI የሚፈጥራቸው በ`POST /api/combos` በኩል ብቻ
ነው።
መመሪያ ያለው UI በ`/dashboard/radar/combos` ይገኛል። የሚያነበው የአካባቢውን
`GET /api/radar/catalog` እና `GET /api/combos/builder/options` መጨረሻ ነጥቦች ብቻ ነው። የRadar ማመሳሰልን ፈጽሞ አያስጀምርም፣
የአቅራቢ ማረጋገጫዎችን አያነብም፣ ወይም በቀጥታ ወደ combo የውሂብ ጎታ አይጽፍም።
የMCP ደንበኞች ተመሳሳዩን የአካባቢ ትንበያ በ`omniroute_radar_catalog` (`read:radar`) ማንበብ ይችላሉ።
አማራጭ የሆኑት `provider`፣ `familyId` እና `enabledOnly` ማጣሪያዎች አንድ የአካባቢ
`GET /api/radar/catalog` ንባብ ከተከናወነ በኋላ ይገመገማሉ። የተገደበው ውጤቱ የካታሎግ ሜታዳታን ከአቅራቢ/ሞዴል፣
ከማሳያ ስም፣ `familyId`፣ ኮታ፣ ችሎታዎች፣ የነቃ/የጠፋ ሁኔታ፣ ምንጭ እና `disabledBy` ጋር ያካትታል፤ የማዋቀሪያ URLs፣
ደረጃዎች፣ ግንኙነቶች፣ የኢ-ሜይል አድራሻዎች፣ ቁልፎች እና የሪፈራል ውሂብ ፈጽሞ አይመለሱም። ይህ መሣሪያ
ለንባብ ብቻ ሲሆን `/api/radar/sync`ን ፈጽሞ አይጠራም።
### የመነሻ ምልክቶች
እያንዳንዱ የተዋሃደ ግቤት UIው እንደ ባጅ የሚያሳየው `origin` መስክ አለው፦
- `"baseline"` — ከቋሚው የልቀት ካታሎግ ሳይለወጥ የቀረ።
- `"radar"` — አንድ ወይም ከዚያ በላይ መስኮች በfeed ታድሰዋል።
- `"local"` — ኦፕሬተሩ በዚህ ግቤት ላይ ቢያንስ አንድ የአካባቢ መሻር አለው (የfeedው የሚለው ምንም ቢሆን፣ በደንብ 1 መሠረት የአካባቢ
መሻሮች ሁልጊዜ ቅድሚያ ያገኛሉ)።
---
## አካባቢያዊ በይነገጾች — ፈጽሞ የፊድ ፕሮክሲ አይደሉም
ከታች ያሉት የአካባቢያዊ Radar ራውት ስብስቦች በ`src/app/api/radar/` ስር ያለውን UI ይደግፋሉ፦
| ራውት | ዘዴ | ዓላማ |
| ------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| `/api/radar/catalog` | GET | ከአካባቢያዊ መሸጎጫ የተዋሃደውን ካታሎግ (`getRadarCatalog()`) ይመልሳል። |
| `/api/radar/sync` | POST | `syncRadar()`ን በሰርቨር በኩል ያስጀምራል፤ የተገኘውን ሁኔታ ይመልሳል። |
| `/api/radar/settings` | GET | `{ optIn, hasSupporterKey, supporterKeyMasked }`ን ይመልሳል — ጥሬውን ቁልፍ ፈጽሞ አይመልስም። |
| `/api/radar/settings` | POST | የመርጦ መግቢያ ቅንብሩን እና/ወይም (የተመሰጠረውን) የደጋፊ ቁልፍ ያስቀምጣል። |
| `/api/radar/referrals` | GET | ከአካባቢያዊ መሸጎጫ `{ fixed, campaigns, tier }`ን ይመልሳል — ከታች [የሪፈራል አገናኞች](#referral-links-free-credits)ን ይመልከቱ። |
| `/api/radar/offers` | GET | ከተረጋገጠው አካባቢያዊ ቀጥታ መሸጎጫ ንቁ ቅናሾችን ይመልሳል፤ የደጋፊ ቁልፉን ፈጽሞ አይመልስም። |
| `/api/radar/offers/sync` | POST | በሰርቨር በኩል ያለውን፣ የቀጥታ ቁልፍን ብቻ የሚጠቀመውን `syncRadarOffers()` የሥራ ፍሰት ያስጀምራል። |
| `/api/radar/intel` | GET | የተረጋገጠ አካባቢያዊ ቀጥታ Intelን ከደጋፊ-ማወቂያ ቡሊያን ጋር ይመልሳል፤ ማንነትን ወይም ቁልፍን ፈጽሞ አይመልስም። |
| `/api/radar/intel/sync` | POST | በሰርቨር በኩል ያለውን፣ የቀጥታ ቁልፍን ብቻ የሚጠቀመውን `syncRadarIntel()` የሥራ ፍሰት ያስጀምራል። |
| `/api/radar/status` | GET | ለካታሎግ፣ ሪፈራሎች፣ ቅናሾች እና Intel ምስጢሮችን ሳያካትት ለንባብ-ብቻ የሆነ የአካባቢያዊ ቅንብሮች/መሸጎጫ ሁኔታ ይመልሳል። |
| `/api/radar/sync-all` | POST | አራቱንም በሰርቨር በኩል ያሉ የማመሳሰል ሞጁሎች ያስኬዳል፣ ለእያንዳንዱ ፊድም የተለየ ሁኔታ ይመልሳል። |
| `/api/radar/local-model-state` | GET | ለማርትዕ/ወደነበረበት መመለሻ መቆጣጠሪያዎች ቋሚ ሆነው የተቀመጡ ሽሮችን እና ምናባዊ ስረዛዎችን ይዘረዝራል። |
| `/api/radar/local-model-state` | PATCH | የተረጋገጡትን `displayName`/`enabled` የመሻር መስኮች ያስቀምጣል ወይም ያጸዳል። |
| `/api/radar/local-model-state` | PUT | `{ provider, modelId, tombstoned }`ን በመጠቀም ምናባዊ ስረዛ ይፈጥራል ወይም ያስወግዳል። |
| `/api/radar/local-model-state` | DELETE | ማንኛውንም ምናባዊ ስረዛ እንዳለ በማቆየት አርትዖት የሚደረግባቸውን የመሻር መስኮች ያጸዳል። |
**ጥብቅ ደንብ፦ እነዚህ ራውቶች ፈጽሞ ለፊድ አገልግሎቱ ፕሮክሲ አይሆኑም።** አሳሹ ሁልጊዜ የሚገናኘው
ከአካባቢያዊው OmniRoute ሰርቨር ጋር ብቻ ነው። የRadar አገልግሎትን የሚጠቀሙት አራቱ ሞጁሎች
`src/lib/radar/sync.ts` (ካታሎግ)፣ `src/lib/radar/referralsSync.ts` (ሪፈራሎች)፣
`src/lib/radar/offersSync.ts` (ቅናሾች) እና `src/lib/radar/intelSync.ts` (Intel) ናቸው፤ ሁሉም የሚሠሩት
በሰርቨር በኩል እንጂ በደንበኛ በኩል ፈጽሞ አይደለም። ይህም
የፊድ URLን እና ማንኛውንም የደጋፊ ቁልፍ ሙሉ በሙሉ ከደንበኛ-ተኮር የአውታረ መረብ ትራፊክ ውጭ ያደርጋል።
`RADAR_ENABLED` ሲጠፋ ሁሉም የRadar የመገልገያ ጫፎች `404` ይመልሳሉ (ከላይ
[ሰንደቅ](#flag-radar_enabled-default-off)ን ይመልከቱ)፤ የራውት ስህተት ምላሾችንም
በማከማቻው አቀፍ የስህተት-ማጽዳት ደንብ (`docs/security/ERROR_SANITIZATION.md`) መሠረት
በ`buildErrorBody()`/`sanitizeErrorMessage()` በኩል ያስተላልፋሉ።
### ማረጋገጫ
ሁሉም የRadar የመገልገያ ጫፎች `isAuthenticated()`
(`src/shared/utils/apiAuth.ts`)ን በመጠቀም ማረጋገጫ ይጠይቃሉ — የዳሽቦርድ ክፍለ-ጊዜ ኩኪ ወይም የአስተዳደር ወሰን ያለው
API ቁልፍ፤ ይህም የቀረውን `/api/settings/*` የሚጠብቀው ተመሳሳይ መግቢያ ነው። የሰንደቅ-መጥፋት
`404` ማረጋገጫው ሁልጊዜ ከማረጋገጫው **በፊት** ይከናወናል፤ ስለዚህ `RADAR_ENABLED`
የጠፋበት ጭነት በባይት ደረጃ አንድ ዓይነት ሆኖ ይቆያል (በይነገጹ እንደሌለ ለማወቅ ብቻ የማረጋገጫ ጥያቄ አይቀርብም)፤
ሰንደቁ አንዴ ከበራ፣ ማረጋገጫ የሌለው ጥያቄ ከማንኛውም የውሂብ ጎታ ንባብ ወይም
ጽሕፈት በፊት `401` ያገኛል። `GET /api/radar/settings` የማረጋገጫው ሁኔታ ምንም ይሁን ምን ጥሬውን የደጋፊ ቁልፍ ፈጽሞ አይመልስም —
የተሸፈነውን ቅርጽ እና `hasSupporterKey` ቡሊያን ብቻ ይመልሳል።
---
## የደጋፊ ቅናሾች
ቅናሾች የራሳቸውን የተፈረመ አርቲፋክት፣ `GET /v1/offers/latest`፣ ይጠቀማሉ፤ እንዲሁም ካታሎጉን ወይም የሪፈራል መሸጎጫውን በፍጹም አይጋሩም። የሰርቨሩ መዳረሻ ነጥብ ትክክለኛ እና ገቢር የደጋፊ Bearer ቁልፍ ይፈልጋል፤ የማህበረሰብ አማራጭ የለም። ስለዚህ `syncRadarOffers()` የባህሪ ጠቋሚው ሲጠፋ፣ ኦፕሬተሩ ለመሳተፍ ሳይመርጥ፣ ወይም ምንም የደጋፊ ቁልፍ ሳይዋቀር ከአውታረ መረቡ በፊት ይቆማል።
ከተሳካ GET በኋላ ደንበኛው በትክክለኛዎቹ የምላሽ ባይቶች ላይ ያለውን የEd25519 ፊርማ ያረጋግጣል፣ `RadarOffersFeedSchema`ን ያረጋግጣል፣ የተፈረመው የይዘት ክፍል እና የ`x-omniroute-feed-tier` ራስጌ ሁለቱም `live` እንዲሉ ይጠይቃል፣ በነጥቦች የተለየ በጥብቅ አዲስ ስሪት መሆኑን ያስፈጽማል፣ እና ከዚያ በኋላ ብቻ `radar_offers_cache`ን በአቶማዊነት ይተካል (ማይግሬሽን `144_radar_offers_cache.sql`)። ሌሎቹ ፊዶች የሚጠቀሙበት ተመሳሳይ የ10 MB ራስጌ-እና-ዥረት ገደብ ተፈጻሚ ይሆናል። የፊርማ፣ የስኪማ፣ የደረጃ፣ የድጋሚ ማጫወት፣ የመጠን፣ የHTTP እና የአውታረ መረብ አለመሳካቶች በሙሉ ለመጨረሻ ጊዜ የተረጋገጠውን መሸጎጫ ይጠብቃሉ።
ዝግ የቅናሽ ቅርጹ ሦስት ሊነጻጸሩ የሚችሉ የጥቅም አይነቶችን ይደግፋል፦ መቶኛ በመሠረታዊ ነጥቦች፣ ክሬዲት በአነስተኛ የገንዘብ አሃዶች፣ ወይም የሙከራ ቀናት። የአጋር ቅናሽ ከተመሳሳይ አይነት የሆነ ይፋዊ መነሻ መለኪያን ማካተት አለበት፣ እና ጥቅሙ በጥብቅ ከዚያ መብለጥ አለበት፤ ይፋዊ ቅናሾች የአጋር መነሻ መለኪያ የላቸውም። URLs የማረጋገጫ መረጃ የሌላቸው HTTPS መሆን አለባቸው። `getRadarOffers()` የተሸጎጠውን ጭነት በመከላከያዊነት እንደገና ያረጋግጣል እና በእያንዳንዱ አካባቢያዊ ንባብ ጊዜ ጊዜያቸው ያለፈባቸውን ግቤቶች ያጣራል፤ `/dashboard/radar/offers` ከማሳየቱ በፊት የጊዜ ማለፍን እንደገና ያጣራል፣ ሲገኝ የፖርቱጋልኛ ጽሑፍን በእንግሊዝኛ አማራጭ ይጠቀማል፣ እና የአጋር ቅናሾችን በግልጽ ይሰይማል።
አሳሹ የሚጠራው አካባቢያዊ መስመሮችን ብቻ ነው፦ የተሸፈነውን የቅንብሮች ቅጽበታዊ ገጽታ ያነባል፣ በሰርቨር በኩል ለማደስ `POST /api/radar/offers/sync`ን ይጠይቃል፣ ከዚያም `GET /api/radar/offers`ን ያነባል። ቁልፍ ከሌለ የፊድ ጥያቄ ለመላክ ከመሞከር ይልቅ ነባር የአስተዋጽዖ አድራጊ/ድጋፍ አገናኞችን ያሳያል። ውጫዊ የቅናሽ አገናኞች `noopener noreferrer`ን በመጠቀም በአዲስ ትር ይከፈታሉ። በዚህ ልቀት ምንም `radar_offers` MCP መሣሪያ አልቀረበም።
---
## Radar Intel፣ የደጋፊ ባጅ እና CLI
Intel በ`GET /v1/intel/latest` ላይ የሚገኝ የተፈረመ አርቲፋክት ነው። ዝግ `RadarIntelFeedSchema` በግል አስተዳዳሪው ከተረጋገጡ ንጽጽሮች የተዘጋጁ በRadar ባለቤትነት የሚያዙ የELO ደረጃዎችን እና ከተፈረሙ የካታሎግ ቅጽበታዊ ገጽታዎች የተገኙ እውነታዊ የካታሎግ እድሜ/ብዛት ልዩነቶችን ብቻ ይቀበላል። ዘዴው በመነሻ ደረጃ 1000 እና K=32 ላይ ተወስኗል። ምንም ንጽጽር ካልተረጋገጠ ባዶ የደረጃ ዝርዝር ትክክለኛ ነው፤ ደንበኛው በፍጹም ራሱ አያመነጭም።
`syncRadarIntel()` እንደ ቅናሾች ተመሳሳይ የሰርቨር-ወገን Bearer፣ የ30 ሰከንድ የጊዜ ገደብ፣ የ10 MiB የዥረት ገደብ፣ የትክክለኛ-ባይት Ed25519 ማረጋገጫ፣ ጥብቅ ስኪማ፣ የ`live` የይዘት ክፍል/ራስጌ መስፈርት፣ የስሪት ዝቅተኛ ወሰን እና የመጨረሻውን-ጥሩ-መሸጎጫ ጥበቃ ይተገብራል። የተረጋገጠ የቀጥታ ቅጽበታዊ ገጽታ ከተከማቸ በኋላ ደንበኛው `radar:<sha256(supporter key)>`ን ይፈጥራል፣ ያንን የአንድ-አቅጣጫ ማንነት ብቻ ያከማቻል፣ እና የተወሰነውን `radar_supporter` የእውቅና ክስተት ያወጣል። የእሱ `radar-supporter` ባጅ በተደጋጋሚ ሲተገበር ውጤቱ አይለወጥም እና ዜሮ XP ይሰጣል፤ የደረጃ ሰሌዳዎችን በፍጹም አያዘምንም ወይም `token_share`ን እንደገና አይጠቀምም። `/dashboard/radar/intel` ባጁን የሚያሳየው ከተረጋገጠ አካባቢያዊ የመሸጎጫ ሜታዳታ ብቻ ነው።
CLI `omniroute radar status`ን እና `omniroute radar sync`ን ያቀርባል። ሁለቱም ከአካባቢያዊ OmniRoute API ጋር ብቻ ይገናኛሉ። `status` ለንባብ ብቻ የሆነ `GET /api/radar/status`ን ያከናውናል፤ `sync` አንድ `POST /api/radar/sync-all` ይልካል እና ለእያንዳንዱ ፊድ ውጤት ያትማል። ሁለቱም ትዕዛዞች የደጋፊ ቁልፉን አያነቡም፣ አይቀበሉም ወይም አያትሙም፣ እንዲሁም የRadar አገልግሎትን በቀጥታ አያገኙም።
---
## የሪፈራል አገናኞች (ነፃ ክሬዲቶች)
የሪፈራል አገናኞች ከካታሎግ ፊድ በተለየ **ራሱን የቻለ፣ ሁልጊዜ ወቅታዊ** ከሆነ ፊድ —
`GET /v1/referrals/latest` — ይቀርባሉ። ይህ ሆን ተብሎ የተደረገ ነው፦ በማህበረሰብ ደረጃው ላይ
ያለው የካታሎግ ፊድ እስከ 30 ቀናት ሊያረጅ የሚችል ቅጽበታዊ ግልባጭ ነው፣ ስለዚህ ከእሱ
የሚወጣ የሪፈራል አገናኝ ከአገልጋዩ እውነተኛ የአገናኞች ዝርዝር በተመሳሳይ
ጊዜ ያህል ይዘገይ ነበር (አዲስ የታከለ ሪፈራል ነፃ/የማህበረሰብ ተጠቃሚ ጋር ለመድረስ
እስከ አንድ ወር ሊፈጅበት ይችል ነበር)። የሪፈራሎች ፊድ በራሱ፣ በጣም አጭር የጊዜ ልዩነት
በማመሳሰል ያንን መዘግየት ያስወግዳል።
```ts
// የGET /v1/referrals/latest ምላሽ አካል (በEd25519 የተፈረመ፣ ከካታሎግ
// ፊድ ጋር ተመሳሳይ የተሰካ ቁልፍ ያለው)፦
{
feed: "omniroute-radar-referrals",
schemaVersion: 1,
generatedAt: string, // ISO — ቆራጥ፦ በሪፈራል አገናኞች ሁሉ ውስጥ ከፍተኛው max(updatedAt)፣
// ስለዚህ ሁለት ተመሳሳይ ጥያቄዎች ፍጹም ተመሳሳይ
// የተፈረሙ ባይቶች/ፊርማ ያመነጫሉ
referrals: {
fixed: RadarReferral[], // ያለማረጋገጫ/ማህበረሰብን ጨምሮ በእያንዳንዱ ደረጃ ውስጥ ይገኛል
campaigns: RadarReferral[], // የሚሞላው ለትክክለኛ ቀጥታ (supporter) Bearer
// ቁልፍ ብቻ ነው፤ ያለማረጋገጫ/ጊዜው ያለፈበት-ቁልፍ ጥያቄዎች [] ያገኛሉ
},
}
// RadarReferral = { provider, url, kind: "fixo" | "campanha", validUntil,
// requiredAction, isDefault }
```
ከካታሎግ ፊድ በተለየ፣ ይህ አካል ምንም `tier` መስክ አይይዝም — አገልጋዩ
በ`Authorization` ቁልፍ መሠረት በየጥያቄው ምን እንደሚካተት ይወስናል፣ ስለዚህ
የ`x-omniroute-feed-tier` ምላሽ ራስጌ ለቀረበው ደረጃ ብቸኛው ምንጭ ነው
(`referralsSync.ts::syncRadarReferrals`)፤ የሌለ ወይም ያልታወቀ ራስጌ ወደ
`"community"`፣ ማለትም አነስተኛው ፈቃድ ወዳለው ግምት፣ ዝቅ ይላል። `RadarReferralsFeedSchema`
(`src/lib/radar/referralsFeedSchema.ts`) መላውን አካል ያረጋግጣል፤ ሁለቱም ፊዶች
እያንዳንዱን ሪፈራል በተመሳሳይ መንገድ እንዲያረጋግጡ ከ`feedSchema.ts` የሚላከውን
ተመሳሳይ የየሪፈራሉን `RadarReferralSchema` እንደገና ይጠቀማል። እያንዳንዱ
`RadarReferral.url` `https://` መሆን አለበት — የ`http://` url የስኪማ ማረጋገጫውን
አያልፍም።
በ`RadarFeedSchema` (`feedSchema.ts`) ላይ ያለው የድሮው በካታሎግ ውስጥ የተካተተ
`referrals` መስክ ቀድሞ በመሸጎጫ ለተቀመጡ የካታሎግ ፊዶች ኋላቀር ተኳኋኝነት
ሲባል ተቀምጧል፣ ነገር ግን `getRadarReferrals()` ከእንግዲህ አያነበውም —
ከታች [መዳረሻ](#accessor)ን ይመልከቱ።
### ማመሳሰል
`syncRadarReferrals()` (`src/lib/radar/referralsSync.ts`) ለሪፈራሎች አውታረ መረቡን
የሚጠቀም ብቸኛው ሞጁል ነው፤ የ`syncRadar()`ን ውል በትክክል ያንጸባርቃል፦ ጠቋሚው
ጠፍቷል → `disabled`፤ opt-in ሐሰት ነው → `opt_out`፤
`${RADAR_FEED_URL}/v1/referrals/latest`ን ያወርዳል (ከካታሎጉ ጋር ተመሳሳይ
የ`RADAR_FEED_URL`/`RADAR_FEED_PUBKEY` fork ተተኪዎች)፣ ትክክለኛዎቹን የምላሽ ባይቶች
የEd25519 ፊርማ ያረጋግጣል (`verifyFeedBytes`)፣ በ`RadarReferralsFeedSchema` ላይ
ያረጋግጣል፣ እና በ`radar_referrals_cache` ሰንጠረዥ ውስጥ በመሸጎጫ ያስቀምጣል
(ፍልሰት `142_radar_referrals_cache.sql`) — ይህም ከካታሎጉ `radar_feed_cache` ሙሉ
በሙሉ የተለየ ሰንጠረዥ ነው። የ10 MB የምላሽ ገደብ እና የ`generatedAt` ዝቅተኛ
ገደብ ከመሸጎጫው የቆየ ገቢ ፊድን ውድቅ በማድረግ፣ የቆየ የተፈረመ አርቲፋክት
እንደገና ከመጫወት ይከላከላሉ። እኩል የጊዜ ማህተም ተቀባይነት አለው፦ አገልጋዩ
ሆን ብሎ ለማህበረሰብ እና ቀጥታ የሪፈራል ልዩነቶች ተመሳሳይ ቆራጥ `generatedAt`
ይሰጣል፣ ስለዚህ ከsupporter-ቁልፍ ለውጥ በኋላ መሠረታዊው የአገናኞች ስብስብ
ሳይለወጥ የተፈረመው ጭነት እና የቀረበው ደረጃ ሊለወጡ ይችላሉ። ፈጽሞ
exception አይጥልም — ሁልጊዜ የሁኔታ ኦብጀክት ይመልሳል፤ ስህተቶች በ`reason`
ውስጥ stack trace ፈጽሞ አይይዙም።
ሁለት አስነሺዎች የሪፈራሎች መሸጎጫ ወቅታዊ እንዲሆን ያደርጋሉ፣ ሁለቱም ከካታሎጉ
የ24h ድግግሞሽ ነፃ ናቸው፦
- **በማንበብ ጊዜ ማመሳሰል** — መሸጎጫው በሌለበት ወይም ከ`REFERRALS_STALE_MS`
(1h፣ `shouldSyncReferralsOnRead()`) በላይ ባረጀ ጊዜ፣ ምላሹን ከማቅረቡ በፊት
`GET /api/radar/referrals` ራሱ `syncRadarReferrals()`ን በቦታው ይጠራል። የትኛውንም
የበስተጀርባ ጊዜ ቆጣሪ ሳይጠብቁ፣ ቋሚ አገናኞችን ለሚቀጥለው የዳሽቦርድ ጭነት
"ሁልጊዜ ወቅታዊ" የሚያደርጋቸው ይህ ነው።
- **የጊዜ ሰሌዳ አስኪያጅ የጎን ማመሳሰል** — `radarSchedulerTick()` (`scheduler.ts`)
ለካታሎጉ በሚጠቀምበት ተመሳሳይ የሰዓት ምት ላይ የሪፈራሎችን መርጀት ለብቻው
ይገመግማል፣ ጊዜው ሲደርስ `syncRadarReferrals()`ን ይጠራል። ይህ በዚያ ምት ላይ
የካታሎጉ ጊዜ ደርሶም ይሁን አይደርስ ይሰራል፣ እና የ`RadarTickResult`ን ቅርጽ
ፈጽሞ አይነካም (በተቻለ መጠን የሚከናወን የጎን ተጽዕኖ ብቻ ሲሆን፣ ስህተት
ቢከሰት ችላ ይባላል)።
### መዳረሻ
`src/lib/radar/index.ts` ሁለት ለንባብ-ብቻ የሆኑ መዳረሻዎችን ይልካል፣ ሁለቱም
ፈጽሞ exception አይጥሉም (ከ`getRadarCatalog()` ጋር ተመሳሳይ የመከላከያ ውል —
ጠቋሚው ጠፍቷል፣ መሸጎጫ የለም፣ ወይም የተበላሸ በመሸጎጫ የተቀመጠ ጭነት
አለ፤ ሁሉም ከስህተት ይልቅ ወደ ባዶው ቅርጽ ይፈታሉ)፦
- `getRadarReferrals()` → `{ fixed: RadarReferral[], campaigns: RadarReferral[] }`፣
ከ`radar_referrals_cache` (በ`getRadarReferralsCache()` በኩል) በማንበብ እና
በ`RadarReferralsFeedSchema` በኩል በማረጋገጥ — ከካታሎግ መሸጎጫው **አይደለም**።
- `getDefaultReferralFor(provider)` → ለዚያ provider `isDefault: true` ያለውን
`fixed` ሪፈራል፣ ወይም `null`። `fixed`ን ብቻ ይመለከታል — campaign ፈጽሞ
እንደ provider "ነባሪ" አገናኝ ጥቅም ላይ አይውልም።
ትክክለኛው "ለአንድ provider የትኛው ሪፈራል ነባሪ ነው" የሚለው ደንብ
በ`findDefaultReferral()` (`src/lib/radar/referrals.ts`) ውስጥ ይገኛል፤ ይህም
**ምንም DB import የሌለው** አነስተኛ pure function ነው — ወደ `"use client"`
component ለማስገባት ደህንነቱ የተጠበቀ ነው። `getRadarReferrals`/
`getDefaultReferralFor` (`index.ts` ውስጥ) `@/lib/db/radar`ን ይጭናሉ፣ ስለዚህ
በserver-only ይቆያሉ፤ የproviders ዳሽቦርድ `better-sqlite3`ን ወደ አሳሹ
እንዳያቀናጅ፣ ከ`index.ts` ይልቅ `referrals.ts`ን በቀጥታ ያስገባል (ከታች ይመልከቱ)።
### `GET /api/radar/referrals`
ልክ እንደ ሌሎቹ የRadar route ሁሉ ተመሳሳይ የgate ቅደም ተከተልን ይከተላል፦ `RADAR_ENABLED` ጠፍቶ ከሆነ →
`404` (መጀመሪያ ይፈተሻል፣ ባይት-ለ-ባይት ተመሳሳይ የሆነ inertia)፤ ማንነቱ ያልተረጋገጠ → `401`፤ ካልሆነ፣
ጊዜ ያለፈበት ሲሆን sync-on-read ያስነሳል (ከላይ ይመልከቱ)፣ ከዚያም
`{ fixed, campaigns, tier }` ያለውን `200` ይመልሳል — `tier` በቀጥታ ከ(ምናልባት አሁን ከታደሰው)
የcache row ይመጣል፣ ለመረጃ ብቻ ነው (ከታች ያለውን የUI ለስላሳ upsell ጽሑፍ ይመራል)።
የfeed serverን በቀጥታ proxy አያደርግም — የrouteው የራሱ source ምንም `fetch(` call የለውም፤
network የሚከሰተው በ`syncRadarReferrals()` ውስጥ ብቻ ነው፣ ልክ እንደ `/api/radar/catalog`
ተመሳሳይ የlocal-cache-only መርህን ይከተላል።
### የDashboard UI — በ`/dashboard/radar` ላይ ያለው "ነፃ credits" tab
አዲስ route ከመፍጠር ይልቅ ነባሩን የRadar ገጽ (`src/app/(dashboard)/dashboard/radar/page.tsx`)
እንደ ሁለተኛ tab እንደገና ይጠቀማል — ገጹ አስቀድሞ በሚያመጣው ውሂብ ላይ ለተመሠረተ ልዩነት
የrouting/i18n ወሰንን ይቀንሳል። አንዴ መሳተፍ ከተመረጠ፣ tab barው
**Catalog** (ነባሩ table) እና **ነፃ credits** ያቀርባል፦
- ቋሚ links በprovider ይመደባሉ፤ እያንዳንዳቸው `requiredAction`ን (ሲኖር)
እና ወደ referral URL የሚወስድ `target="_blank" rel="noopener noreferrer"` button ያሳያሉ።
- Campaigns ተመሳሳዩን፣ እንዲሁም `validUntil`ን ሲኖር ያሳያሉ።
- `campaigns` ባዶ ሲሆን **እና** የቀረበው tier `community` ሲሆን፣ UIው
አጭር የupsell ማስታወሻ ("ለተወሰነ ጊዜ የሚቆዩ campaigns ለደጋፊዎች የተጨመረ ጥቅም ናቸው") ያሳያል — ይህ **በፍጹም**
የቋሚ links ዝርዝርን አይደብቅም ወይም አይገድብም፤ ዝርዝሩ ለእያንዳንዱ tier ሙሉ ሆኖ ይቆያል።
upsellው ለስላሳ መልዕክት ብቻ እንጂ በፍጹም እገዳ አይደለም።
### በprovider ስም ላይ ያለ referral link (የproviders dashboard)
`ProviderPageHeader` (`src/app/(dashboard)/dashboard/providers/[id]/components/`)
የprovider ስምን `providerInfo.website` ሲኖር አስቀድሞ ያገናኘው ነበር፤ ለገቢ የሚውል linkም አንድ
ቀደምት አብነት አለው፦ የKimi (Moonshot AI) partner-link ማስታወሻ
(`providers.kimiPartnerLinkNote` i18n key)። D28 አዲስ key ከማስገባት ይልቅ
ለRadar ነባሪ referrals ያንኑ ትክክለኛ፣ የማይጎላ የማስታወሻ ንድፍ እንደገና ይጠቀማል።
በዕቅድ የተደረገ ልቅ ትስስር፦
- `resolveProviderHeaderLink()` (`src/app/(dashboard)/dashboard/providers/providerPageUtils.ts`)
**pure** function ነው — `(staticWebsite, referralUrl) => { website, isReferralLink }`
— በ`@/lib/radar` ወይም `@/lib/db/*` ላይ ምንም dependency የለውም። `providerPageUtils.ts`
በአጠቃላይ ከእነዚያ imports ነፃ ሆኖ ይቆያል (በ
`tests/unit/provider-header-referral-link.test.ts` የተረጋገጠ)።
- `ProviderDetailPageClient.tsx` (`"use client"` component) የRadar ውሂብን
fetch ማድረግ የሚፈቀድለት ብቸኛው ቦታ ነው — በ`fetch("/api/radar/referrals")`፣ የRadar dashboard
ገጹ ራሱ የሚጠቀምበትን ተመሳሳይ የlocal-route ንድፍ በመጠቀም — እና ነባሪ referralን
client-side ላይ ከDB-free `src/lib/radar/referrals.ts` በመጣው `findDefaultReferral()` ያሰላል።
- `RADAR_ENABLED` ጠፍቶ ሲሆን fetchው 404 ይመልሳል፣ `referralUrl` `null` ሆኖ ይቆያል፣ እና
`resolveProviderHeaderLink()` ነባሩን የcatalog `website` ሳይቀይር ይመልሳል — የprovider ገጹ
ይህ ባህሪ ከመኖሩ በፊት እንደነበረው ባይት-ለ-ባይት ተመሳሳይ ነው። እስካሁን cache ከሌለ ወይም
ለዚያ የተወሰነ provider ነባሪ referral ከሌለም ውጤቱ ተመሳሳይ ነው።
- ነባሪ referral ተፈጻሚ ሲሆን፣ `ProviderPageHeader` `isReferralLink`ን ይቀበላል
እና ከKimi partner link ጋር ተመሳሳይ የማይጎላ ማስታወሻ/tooltip ያሳያል (`providers.kimiPartnerLinkNote`
keyን እንደገና በመጠቀም) — በፍጹም አዲስ፣ የተለየ visual treatment አይጠቀምም።
---
## ፊድን እራስዎ እንዴት ማስተናገድ እንደሚችሉ
በካታሎጉ ላይ ሙሉ ቁጥጥር ማድረግ የሚፈልግ fork ወይም እራሱ አስተናጋጅ የደንበኛ ኮድን ሳይነካ የራሱን ፊድ
አገልግሎት ማስኬድ ይችላል፦
1. `RadarFeedSchema` (`src/lib/radar/feedSchema.ts`)ን የሚያሟላ JSON ይዘት የሚመልስ `GET /v1/catalog/latest` endpoint ያቅርቡ — ከፍተኛ ደረጃ `feed:
"omniroute-radar"`፣ `schemaVersion: 2`፣ `version`፣ `tier`፣ `providers`፣ `models`፣
`quirks` እና `totals`። `x-omniroute-radar-schema: 2`ን ያክብሩ፤ ከሽግግር ጋር ተኳሃኝ የሆነ አገልጋይ
ይህን ያላካተቱ ጥያቄዎችን በነባሪነት በተለየ ሁኔታ ወደተፈረመ v1 artifact መምራት አለበት።
2. ትክክለኛዎቹን የምላሽ bytes በEd25519 የቁልፍ ጥንድ ይፈርሙ እና base64
ፊርማውን በ`x-omniroute-feed-signature` የምላሽ header ውስጥ ይመልሱ።
3. `RADAR_FEED_URL`ን ወደ አዲሱ base URL እና `RADAR_FEED_PUBKEY`ን ወደ ተዛማጁ
ይፋዊ ቁልፍ (base64-DER SPKI ወይም PEM) ያዘጋጁ —
[የenv var ማጣቀሻውን](../reference/ENVIRONMENT.md#27-radar-feed-self-hosting) ይመልከቱ።
4. `RADAR_ENABLED`ን ያንቁ እና በ`POST /api/radar/settings`
(`{ optIn: true }`) በኩል መርጠው ይግቡ።
ሌላ ምንም የኮድ ለውጥ አያስፈልግም — `verifyFeedBytes()` ማሻሻያውን
በራስ-ሰር ይወስዳል (`getFeedPublicKeys()` በ`src/lib/radar/pinnedKeys.ts` ውስጥ)፣ እና የversion
ንጽጽር፣ የschema ማረጋገጫ እና የማዋሃድ ደንቦቹ በራስ-አስተናጋጅ
ፊድ ላይም በተመሳሳይ ሁኔታ ይተገበራሉ።
የReferral አገናኞች (ከላይ [የReferral አገናኞች (ነፃ ክሬዲቶች)](#referral-links-free-credits)ን
ይመልከቱ) የተለየና አማራጭ artifact ናቸው፦ `/v1/catalog/latest`ን ብቻ
የሚያቀርብ fork አሁንም ሙሉ በሙሉ ይሠራል — `syncRadarReferrals()` ከ`/v1/referrals/latest`
በሚመጣ `404` ጊዜ ወደ `{ status: "error" }` ዝቅ ይላል፣ እና cacheው ባዶ ሆኖ ስለሚቆይ
`GET /api/radar/referrals` ቀሪውን ገጽ ከማሳካት ይልቅ `{ fixed: [], campaigns: [], tier: null }`ን
መመለሱን ይቀጥላል። የReferral አገናኞችንም ለማቅረብ፣
`RadarReferralsFeedSchema` (`src/lib/radar/referralsFeedSchema.ts`)ን የሚያሟላ
`GET /v1/referrals/latest` ያቅርቡ እና ከካታሎግ ፊዱ ጋር በተመሳሳይ Ed25519 የቁልፍ ጥንድ
ይፈርሙት።
የSupporter ቅናሾች ሌላ አማራጭ artifact ናቸው። እነሱን ለማቅረብ፣
`GET /v1/offers/latest`ን በተዘጋው `RadarOffersFeedSchema`
(`src/lib/radar/offersFeedSchema.ts`) ይተግብሩ፣ ቀጥታ entitlement ይጠይቁ፣
`x-omniroute-feed-tier: live`ን ይመልሱ እና ትክክለኛዎቹን bytes በተመሳሳዩ ቁልፍ ይፈርሙ። ይህን
endpoint ያላካተተ fork የካታሎግ/Referral ባህሪውን ሳይቀይር ያቆያል፤ የቅናሽ ማደስ አጥፊ ባልሆነ ሁኔታ ይሳናል፣ እና
ለመጨረሻ ጊዜ የተረጋገጠው አካባቢያዊ የቅናሽ cache እንደተገኘ ይቆያል።
Intelም በተመሳሳይ ሁኔታ አማራጭ ነው። እራሱ አስተናጋጅ `RadarIntelFeedSchema`
(`src/lib/radar/intelFeedSchema.ts`)ን በመጠቀም `GET /v1/intel/latest`ን ማቅረብ፣ ቀጥታ entitlement መጠየቅ፣
`x-omniroute-feed-tier: live`ን መመለስ እና ትክክለኛዎቹን bytes በጋራው Ed25519 ቁልፍ መፈረም ይችላል። endpointን
አለማካተት ካታሎግን፣ Referralsን እና ቅናሾችን ሳይቀይር ያቆያል፤ የIntel ማደስ ለመጨረሻ ጊዜ የተረጋገጠውን
አካባቢያዊ snapshot ይጠብቃል።
---
## ተዛማጅ ሰነዶች
- [`docs/security/ERROR_SANITIZATION.md`](../security/ERROR_SANITIZATION.md) — የ
`/api/radar/*` routes የሚከተሉት የስህተት-ምላሽ ንድፍ።
- [`docs/reference/ENVIRONMENT.md`](../reference/ENVIRONMENT.md#27-radar-feed-self-hosting)
— የ`RADAR_FEED_URL` / `RADAR_FEED_PUBKEY` ማጣቀሻ።

173
docs/i18n/am/docs/frameworks/SEARCH_TOOLS_STUDIO.md Normal file
View File

@@ -0,0 +1,173 @@
# Search Tools Studio (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/SEARCH_TOOLS_STUDIO.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇦🇿 [az](../../../az/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇩🇰 [da](../../../da/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇩🇪 [de](../../../de/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇬🇷 [el](../../../el/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇪🇸 [es](../../../es/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇪🇪 [et](../../../et/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇱 [he](../../../he/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇩 [id](../../../id/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇹 [it](../../../it/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇰🇭 [km](../../../km/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇲🇲 [my](../../../my/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇳🇴 [no](../../../no/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [or](../../../or/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇱🇰 [si](../../../si/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇮🇳 [te](../../../te/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇹🇭 [th](../../../th/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/SEARCH_TOOLS_STUDIO.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/SEARCH_TOOLS_STUDIO.md)
---
> **ባህሪ:** Search Tools Studio — ለ`/dashboard/search-tools` የተዋሃደ የድር መሣሪያዎች የሥራ ቦታ።
> **ዕቅዶች:** `18-search-tools-studio-redesign.plan.md` + `_orchestration/master-plan-group-C.md`
> **ሁኔታ:** በv3.8.6 ተለቋል
---
## አጠቃላይ እይታ
Search Tools Studio፣ `/dashboard/search-tools`ን ከመሠረታዊ የፍለጋ መሞከሪያ ወደ ድር ፍለጋን፣ ድር ይዘት ማውጣትን እና በጎን ለጎን የአቅራቢዎች ንጽጽርን ወደሚያዋህድ
ባለሦስት-ትር Studio ይለውጠዋል።
```
┌ Search Tools ──────────────────────────────────────────────────────────┐
│ [🔍 ፍለጋ] [📄 ይዘት ማውጣት] [⚖ ማወዳደር] 142ms · $0.001 </> │
│ ⓘ [የሞዳሊቲዎች መመሪያ] │
├──────────────────────────────────────────┬─────────────────────────────┤
│ {የነቃው ትር ይዘት} │ ─ ውቅር │
│ │ አቅራቢ [ራስ-ሰር ∨] │
│ │ 🟢 Serper $0.001 │
│ │ 🟢 Tavily $0.008 │
│ │ 🔥 Firecrawl (ማምጣት) │
│ │ ዓይነት [ድር | ዜና] │
│ │ ሙሉ ገጽ [ ] (ይዘት ማውጣት) │
│ │ ቅርጸት [md|text|html] │
│ │ የዳግም ደረጃ ሞዴል [∨] │
└──────────────────────────────────────────┴─────────────────────────────┘
```
---
## ትሮች
### የፍለጋ ትር
ነባሩን `SearchForm` + `ResultsPanel` + `RerankPanel` ወደ አንድ ትር ያሳድጋል፦
- ጥያቄ → ውጤቶች (ርዕስ፣ URL፣ ቅንጭብ፣ የተዛማጅነት ነጥብ)።
- በውቅር ክፍሉ ውስጥ የአቅራቢ ሜታዳታ (ወጪ፣ ኮታ፣ ሁኔታ)።
- የዳግም ደረጃ ክፍል፦ የዳግም ደረጃ ሞዴል ይምረጡ፣ ውጤቶችን እንደገና ያስቀምጡ፣ `positionDelta`ን ያሳዩ።
- ምንም የፍለጋ አቅራቢዎች ባልተዋቀሩበት ጊዜ CTA ያለው ባዶ ሁኔታ።
- የፍለጋ ታሪክ በ`SearchHistory.tsx` በኩል።
- `POST /v1/search`ን ይጠራል (ነባር endpoint፣ ምንም ለውጥ የለም)።
### ይዘት የማውጣት ትር
በ`POST /v1/web/fetch` በኩል ከURL ይዘት ለማውጣት የሚያገለግል አዲስ ትር (በዕቅድ 05 የተፈጠረ)፦
- ግቤት፦ URL + የሙሉ-ገጽ መቀያየሪያ + የቅርጸት መራጭ (markdown / text / HTML)።
- ማስገባት → ማምጣት → `ScrapeResult.tsx`ን ማቅረብ።
- `ScrapeResult` የmarkdown ቅድመ-እይታን + የጥሬ ውሂብ መቀያየሪያን ያቀርባል።
- ገደብ፦ የምላሹ ይዘት ከ**256 KB** በላይ ከሆነ፣ UI `(ተቆርጧል፣ ጥሬውን ይመልከቱ)` ያሳያል እና ጥሬ ውሂቡን በMonaco modal ውስጥ ይከፍታል (D21)።
- የሜታዳታ ፓነል፦ አቅራቢ (firecrawl/jina-reader/tavily-search/tinyfish/nimble-search/anysearch-search)፣ የምላሽ ጊዜ፣ ወጪ፣ የምላሽ መጠን፣ የአገናኞች ብዛት።
- `useScrapeFetch.ts` hookን ይጠቀማል።
### የንጽጽር ትር
ተመሳሳዩን ጥያቄ/URL በአንድ ጊዜ እስከ **4 አቅራቢዎች** ድረስ ያስኬዳል (D22)፦
- ለእያንዳንዱ አቅራቢ በጎን ለጎን የተቀመጡ ዓምዶች።
- መለኪያዎች፦ የምላሽ ጊዜ፣ ወጪ፣ የውጤቶች ብዛት፣ የምላሽ መጠን።
- ለፍለጋ የURL መደራረብ ስሌት (ከመጀመሪያው ውጤት ጋር የሚጋሩ የURL ብዛት)።
- ለእያንዳንዱ አቅራቢ `POST /v1/search`ን (ፍለጋ) ወይም `POST /v1/web/fetch`ን (ይዘት ማውጣት) ይጠራል።
---
## የውቅር ክፍል (የጋራ)
`SearchToolsConfigPane.tsx` — ሁልጊዜ የሚታይ፣ ሊታጠፍ የሚችል።
| መስክ | ማስታወሻዎች |
| ------------ | ------------------------------------------------------- |
| አቅራቢ | የሁኔታ ባጅ ያለው ተቆልቋይ ዝርዝር (የተዋቀረ / የጎደለ / የመጠን ገደብ የተጣለበት) |
| ዓይነት | `web` ወይም `news` (ለፍለጋ ብቻ) |
| ሙሉ ገጽ | ለይዘት ማውጣት መቀያየሪያ — ከመጀመሪያው የሚታይ ይዘት ይልቅ ሙሉውን ገጽ ያመጣል |
| ቅርጸት | `markdown`፣ `text` ወይም `html` (ለይዘት ማውጣት ብቻ) |
| የዳግም ደረጃ ሞዴል | ከፍለጋ በኋላ ደረጃዎችን እንደገና ለማስቀመጥ አማራጭ ሞዴል |
| ታሪክ | ሊታጠፍ የሚችል የፍለጋ ታሪክ ክፍል |
---
## SearchConceptCard
`SearchConceptCard.tsx` — ሁልጊዜ የሚታይ፣ ሊታጠፍና ሊዘረጋ የሚችል accordion። የሚከተሉትን ያብራራል፦
| ጽንሰ-ሐሳብ | አጭር መግለጫ |
| ------------------- | ----------------------------------------------------- |
| **ፍለጋ** | የድር ውጤቶችን ዝርዝር (ርዕስ፣ URL፣ አጭር መግለጫ፣ የአግባብነት ውጤት) ያመጣል |
| **ይዘት ማውጣት** | የአንድ URL ሙሉ ይዘትን (markdown፣ ጽሑፍ ወይም HTML) ያወጣል |
| **ማወዳደር** | ተመሳሳዩን መጠይቅ በN አቅራቢዎች ላይ ጎን ለጎን ያስኬዳል |
| **ዳግም ደረጃ መስጠት** | የመጠይቁን አግባብነት ለማሻሻል ውጤቶችን በLLM እንደገና ያደራጃል |
| **ራስ-ሰር (በጣም ርካሹ)** | በጣም ርካሹን የሚገኝ አቅራቢ በራስ-ሰር ይመርጣል |
---
## የአቅራቢዎች ካታሎግ
`ProviderCatalog.tsx` ሙሉውን የአቅራቢዎች ዝርዝር ከ`GET /api/search/providers`
ያቀርባል (fetch አቅራቢዎችን ለማካተት በF4 የተስፋፋ)፦
| `kind` | `"search"` (20 አቅራቢዎች) ወይም `"fetch"` (firecrawl, jina-reader, tavily-search, tinyfish, nimble-search, anysearch-search) |
ሁኔታው ማረጋገጫ መረጃዎች መኖራቸውን እና ሁሉም
ቁልፎች በአሁኑ ጊዜ በ cooldown ውስጥ መሆናቸውን በመፈተሽ **ጥያቄው በሚቀርብበት ጊዜ ይወሰናል**።
---
## ኮድ ወደ ውጭ መላክ
`ExportCodeModal` (ከPlayground Studio የመጣ) + `codeExport.ts` ለሁለቱም
`/v1/search` እና `/v1/web/fetch` ጥሪዎች የcurl / Python / TypeScript የኮድ ቁርጥራጮችን ያመነጫሉ።
የAPI ቁልፍ ቦታ ያዥ ሁልጊዜ `$OMNIROUTE_API_KEY` ነው (D11፣ ከPlayground Studio ጋር የጋራ)።
---
## የBackend ለውጦች
ለዚህ ባህሪ አንድ የBackend ለውጥ ብቻ አስፈልጎ ነበር፦
### የተስፋፋ `GET /api/search/providers`
`src/app/api/search/providers/route.ts` እንዲከተለው ተስፋፍቷል፦
- ሁሉንም 6 fetch አቅራቢዎች (`firecrawl`፣ `jina-reader`፣ `tavily-search`፣ `tinyfish`፣ `nimble-search`፣ `anysearch-search`) በarray ውስጥ ማካተት።
- በእያንዳንዱ item ላይ `kind: "search" | "fetch"` መጨመር።
- ከቀጥታ የማረጋገጫ መረጃ ሁኔታ የሚወሰን `status: "configured" | "missing" | "rate_limited"` መጨመር።
- ከነባር ስሪቶች ጋር ተኳሃኝነትን መጠበቅ — ነባር fields (`id`፣ `name`፣ ወዘተ) ሳይለወጡ ይቆያሉ።
---
## ቁልፍ ፋይሎች
| ዱካ | ዓላማ |
| --------------------------------------------------------------------------------- | --------------------------------------- |
| `src/app/(dashboard)/dashboard/search-tools/SearchToolsClient.tsx` | የStudio shell፣ የtab አስተባባሪ |
| `src/app/(dashboard)/dashboard/search-tools/components/SearchToolsTopBar.tsx` | Tabs + መለኪያዎች + ወደ ውጭ መላኪያ አዝራር |
| `src/app/(dashboard)/dashboard/search-tools/components/SearchToolsConfigPane.tsx` | የጋራ የውቅር panel |
| `src/app/(dashboard)/dashboard/search-tools/components/SearchConceptCard.tsx` | ገላጭ cards (ሁልጊዜ የሚታዩ) |
| `src/app/(dashboard)/dashboard/search-tools/components/ProviderCatalog.tsx` | የአቅራቢዎች ዝርዝር ከmetadata ጋር |
| `src/app/(dashboard)/dashboard/search-tools/components/ScrapeResult.tsx` | የMarkdown ቅድመ-እይታ + የጥሬ ይዘት toggle |
| `src/app/(dashboard)/dashboard/search-tools/components/tabs/SearchTab.tsx` | የፍለጋ + ዳግም ደረጃ መስጫ tab |
| `src/app/(dashboard)/dashboard/search-tools/components/tabs/ScrapeTab.tsx` | የይዘት ማውጫ tab |
| `src/app/(dashboard)/dashboard/search-tools/components/tabs/CompareTab.tsx` | የበርካታ አቅራቢዎች ማወዳደሪያ tab |
| `src/app/(dashboard)/dashboard/search-tools/hooks/useScrapeFetch.ts` | የይዘት ማውጫ fetch hook |
| `src/app/api/search/providers/route.ts` | በ`kind` + `status` + fetch አቅራቢዎች የተስፋፋ |
| `open-sse/config/searchRegistry.ts` | ለፍለጋ አቅራቢ metadata ዋና የእውነት ምንጭ |
---
## መላ ፍለጋ
| ምልክት | ምክንያት | መፍትሔ |
| ---------------------------------------- | ----------------------- | --------------------------------------------------------------------------------- |
| የScrape ትር "endpoint not available" ያሳያል | `/v1/web/fetch` አልተገናኘም | ዕቅድ 05 መዋሃዱን ያረጋግጡ፤ `src/app/api/v1/web/fetch/route.ts` መኖሩን ያረጋግጡ |
| የአቅራቢዎች ካታሎግ ሁሉንም እንደ "missing" ያሳያል | ምስክርነቶች አልተዋቀሩም | በ`/dashboard/providers` ውስጥ ምስክርነቶችን ያክሉ |
| የScrape ይዘት ተቆርጧል | ምላሹ ከ256 KB ገደብ በላይ ነው | የሚጠበቅ ባህሪ ነው (D21)። ሙሉ ይዘቱን ለማየት "view raw" አዝራሩን ይጠቀሙ |
| የCompare ትር 2 አቅራቢዎችን ብቻ ያሳያል | የጥያቄ መጠን ገደብ ንቁ ነው | ሁለት ወይም ከዚያ በላይ አቅራቢዎች በማቀዝቀዣ ጊዜ ውስጥ ሊሆኑ ይችላሉ — በConfig ፓነል ውስጥ የአቅራቢውን ሁኔታ ያረጋግጡ |
| "Size" በሰንጠረዡ ውስጥ እንደ ጥሬ ቁልፍ ይታያል | የi18n ቁልፍ ይጎድላል | `search.size` በአካባቢ ቋንቋ ፋይሉ ውስጥ መኖሩን ያረጋግጡ፤ i18nን እንደገና ይገንቡ |
---
## ማጣቀሻዎች
- ዋና ዕቅድ፦ `_tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md`
- የባህሪ ዕቅድ፦ `_tasks/features-v3.8.6/refactorpages/18-search-tools-studio-redesign.plan.md`
- የፍለጋ አቅራቢ መዝገብ፦ `open-sse/config/searchRegistry.ts`
- Playground Studio (የጋራ `ExportCodeModal` + `codeExport.ts`)፦ `docs/frameworks/PLAYGROUND_STUDIO.md`
- የድር ማምጫ backend፦ `src/app/api/v1/web/fetch/route.ts`

485
docs/i18n/am/docs/frameworks/SKILLS.md Normal file
View File

@@ -0,0 +1,485 @@
# Skills Framework (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/SKILLS.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/SKILLS.md) · 🇦🇿 [az](../../../az/docs/frameworks/SKILLS.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/SKILLS.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/SKILLS.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/SKILLS.md) · 🇩🇰 [da](../../../da/docs/frameworks/SKILLS.md) · 🇩🇪 [de](../../../de/docs/frameworks/SKILLS.md) · 🇬🇷 [el](../../../el/docs/frameworks/SKILLS.md) · 🇪🇸 [es](../../../es/docs/frameworks/SKILLS.md) · 🇪🇪 [et](../../../et/docs/frameworks/SKILLS.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/SKILLS.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/SKILLS.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/SKILLS.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/SKILLS.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/SKILLS.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/SKILLS.md) · 🇮🇱 [he](../../../he/docs/frameworks/SKILLS.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/SKILLS.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/SKILLS.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/SKILLS.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/SKILLS.md) · 🇮🇩 [id](../../../id/docs/frameworks/SKILLS.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/SKILLS.md) · 🇮🇹 [it](../../../it/docs/frameworks/SKILLS.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/SKILLS.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/SKILLS.md) · 🇰🇭 [km](../../../km/docs/frameworks/SKILLS.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/SKILLS.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/SKILLS.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/SKILLS.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/SKILLS.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/SKILLS.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/SKILLS.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/SKILLS.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/SKILLS.md) · 🇲🇲 [my](../../../my/docs/frameworks/SKILLS.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/SKILLS.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/SKILLS.md) · 🇳🇴 [no](../../../no/docs/frameworks/SKILLS.md) · 🇮🇳 [or](../../../or/docs/frameworks/SKILLS.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/SKILLS.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/SKILLS.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/SKILLS.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/SKILLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/SKILLS.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/SKILLS.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/SKILLS.md) · 🇱🇰 [si](../../../si/docs/frameworks/SKILLS.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/SKILLS.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/SKILLS.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/SKILLS.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/SKILLS.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/SKILLS.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/SKILLS.md) · 🇮🇳 [te](../../../te/docs/frameworks/SKILLS.md) · 🇹🇭 [th](../../../th/docs/frameworks/SKILLS.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/SKILLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/SKILLS.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/SKILLS.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/SKILLS.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/SKILLS.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/SKILLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/SKILLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/SKILLS.md)
---
> **የእውነት ምንጭ:** `src/lib/skills/` እና `src/app/api/skills/`
> **ለመጨረሻ ጊዜ የተዘመነው:** 2026-06-28 — v3.8.40
OmniRoute የቋንቋ ሞዴሎች (እና ኦፕሬተሮች) እንደገና ጥቅም ላይ የሚውሉ ችሎታዎችን — ከፋይል ስርዓት ንባብ እና HTTP ጥያቄዎች እስከ በsandbox የተገደበ የኮድ አፈጻጸም እና በጥንቃቄ የተመረጡ የገበያ ቦታ ክህሎቶች — እንዲያቀናብሩ የሚያስችል ሊስፋፋ የሚችል የSkills ማዕቀፍ ያቀርባል።
አንድ skill በስሪት የሚተዳደር፣ በschema የተገለጸ የሥራ አሃድ ነው። OmniRoute በወጪ ጥያቄዎች ውስጥ skillsን እንደ tool definitions ሊያስገባ፣ ከሞዴሉ ተመልሰው የሚመጡ tool callsን ሊያቋርጥ፣ ተዛማጁን handler ሊያስኬድ እና ውይይቱ እንዲቀጥል ውጤቱን መልሶ ለሞዴሉ ሊያቀርብ ይችላል። ሞዴሉ implementationን ፈጽሞ አያይም — የtool interfaceን ብቻ ነው የሚያየው።
---
## Agent Skills ከ Omni Skills ጋር ሲነጻጸሩ
OmniRoute ሁለት የተለያዩ ግን እርስ በርስ የሚደጋገፉ የskill ስርዓቶች አሉት፦
| መለኪያ | **Omni Skills** (ይህ ሰነድ) | **Agent Skills** |
| :----------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------ |
| ዓላማ | የLLM tool ማስገባት + በsandbox የተገደበ አፈጻጸም | ውጫዊ agents እንዲያገኙትና እንዲጠቀሙበት የSKILL.md ካታሎግ |
| የእውነት ምንጭ | `src/lib/skills/` + የገበያ ቦታ | `src/lib/agentSkills/` + `skills/` ማውጫ |
| የruntime ሁነታ | ወደ ውጪ በሚላኩ ጥያቄዎች ውስጥ ይገባል፣ በtool-call events ላይ ይፈጸማል | የማይለወጥ markdown ካታሎግ + REST/MCP/A2A የማግኛ endpoints |
| ማን ይጠቀምበታል | OmniRoute ራሱ (combo routing፣ ገቢ LLM calls) | ውጫዊ agents፣ MCP clients፣ A2A orchestrators |
| ብዛት | ተለዋዋጭ (በገበያ ቦታ የሚመራ) | 45 የካታሎግ ግቤቶች (23 API + 21 CLI + 1 config) |
| ቅርጸት | `SkillDefinition` ከtool schema + handler ጋር | `SKILL.md` frontmatter + markdown body |
| ማግኘት | `/api/skills/*` REST + `omniroute_skills_*` MCP tools | `/api/agent-skills/*` REST + `omniroute_agent_skills_*` MCP tools + A2A `list-capabilities` |
**Omni Skills** የአፈጻጸም ሞተር ናቸው — አንድ LLM toolን ሲጠራ OmniRoute _ምን ማድረግ እንደሚችል_ ይገልጻሉ።
**Agent Skills** የሰነድ ካታሎግ ናቸው — በቀጥታ ወደ agent prompts ሊገቡ በሚችሉ የተዋቀሩ SKILL.md ፋይሎች አማካኝነት፣ ውጫዊ agents የOmniRouteን REST API እና CLI _እንዴት መጠቀም እንዳለባቸው_ ያብራራሉ።
ስለ Agent Skills ካታሎግ፣ generator፣ MCP tools እና A2A skill፣ [docs/frameworks/AGENT-SKILLS.md](./AGENT-SKILLS.md)ን ይመልከቱ።
---
## ጽንሰ-ሐሳቦች
### የSkill ምንጮች
ሦስት የskills ምንጮች በአንድ registry ውስጥ አብረው ይኖራሉ፦
1. **አብሮገነብ skills** (`src/lib/skills/builtins.ts`) — ከOmniRoute ጋር ይቀርባሉ። የተለመዱ አጠቃቀሞችን ይሸፍናሉ፦
- `file_read`, `file_write` — በእያንዳንዱ API key የተለየ sandbox workspace በ`<DATA_DIR>/skills/workspaces/<hashed-key>/` ስር
- `http_request` — በ`safeOutboundFetch` በኩል ወደ ውጪ የሚላክ HTTP፣ ከ`guard: "public-only"` ጋር
- `web_search` — ከcaching (`executeWebSearch`) ጋር ሊቀየር የሚችል search provider
- `eval_code` — በDocker sandbox የተገደበ `node` ወይም `python` አፈጻጸም
- `execute_command` — በDocker sandbox የተገደበ የshell command
- `browser` — በPlaywright የሚደገፍ scaffolding፣ በነባሪ የተሰናከለ (`builtin/browser.ts`)
2. **SkillsMP** (የOmniRoute የገበያ ቦታ) — ከ`https://skillsmp.com/api/v1/skills/search` ይመጣል። በSettings ውስጥ `skillsmpApiKey` ያስፈልጋል።
3. **SkillsSH** (`skills.sh` የማህበረሰብ ካታሎግ) — ከ`https://skills.sh/api/search` ይመጣል። ማረጋገጫ አያስፈልግም፤ የSKILL.md ይዘት ከGitHub raw ይወሰዳል።
አንድ "active provider" dashboardው ከየትኛው ካታሎግ እንደሚጭን ይቆጣጠራል (`src/lib/skills/providerSettings.ts`)። በ**Settings → Memory & Skills** ስር ይቀይሩት። ነባሪ፦ `skillsmp`።
### የSkill ማንነት
Skills በin-memory registry (`src/lib/skills/registry.ts`) ውስጥ በ`name@version` ቁልፍ ይመዘገባሉ። ስሪቱ semver (`^\d+\.\d+\.\d+$`) መሆን አለበት። `resolveVersion()` የ`^`፣ `~`፣ `>`፣ `>=`፣ `<`፣ `<=`፣ `==` እና ትክክለኛ ተዛማጅ ገደቦችን ይረዳል።
### የSkill ሁነታ
እያንዳንዱ skill መቼ እንደሚገባ የሚቆጣጠር runtime ሁነታ አለው፦
| ሁነታ | ባህሪ |
| ------ | ------------------------------------------------------------------- |
| `on` | ሁልጊዜ እንደ tool definition ይገባል |
| `off` | ፈጽሞ አይገባም፣ ፈጽሞም ሊፈጸም አይችልም |
| `auto` | ከገቢው ጥያቄ አንጻር ነጥብ ይሰጠዋል፤ ነጥቡ ≥ `AUTO_MIN_SCORE` (ነባሪ 3) ከሆነ ብቻ ይገባል |
`auto` ከገበያ ቦታ ለተጫኑ skills ነባሪው ነው። `enabled=true` እና `mode="off"` አብረው "የተመዘገበ ግን ንቁ ያልሆነ" ማለት ነው — በlegacy column በኩል `enabled`ን መቀያየር የቆዩ codepaths ወጥነታቸውን እንዲጠብቁ `mode`ንም ያሻሽላል (`src/app/api/skills/[id]/route.ts`)።
### ሁኔታ (አፈጻጸሞች)
የSkill አፈጻጸሞች በ`skill_executions` table ውስጥ በሚከተሉት ሁኔታዎች ይከታተላሉ (`src/lib/skills/types.ts`)፦
```ts
enum SkillStatus {
PENDING = "pending",
RUNNING = "running",
SUCCESS = "success",
ERROR = "error",
TIMEOUT = "timeout",
}
```
### የRegistry Cache
`SkillRegistry` የ60 ሰከንድ TTL cache (`registry.ts:14`) ያለው singleton ነው። `loadFromDatabase()` idempotent ሲሆን በ`pendingLoad` አማካኝነት በተመሳሳይ ጊዜ የሚደረጉ ጥሪዎችን ያስወግዳል። ማንኛውም write (`register`/`unregister`/`unregisterById`) cacheን ዋጋ አልባ ያደርገዋል። ስሪቶችን በ`getSkillVersions(name)` እና `resolveVersion(name, constraint)` ይፈልጉ።
### Providerን ያገናዘበ ማስገባት
በ`src/lib/skills/injection.ts` ውስጥ ያለው `injectSkills()` የተመዘገቡ skillsን ወደ provider-specific tool definitions የሚቀይር የመግቢያ ነጥብ ነው፦
- **OpenAI** — `{ type: "function", function: { name, description, parameters } }`
- **Anthropic** — `{ name, description, input_schema }`
- **Google (Gemini)** — `{ name, description, parameters }`
ሞዴሉ መልሶ ሲጠራው ተቆጣጣሪው ትክክለኛውን ስሪት መምረጥ እንዲችል የመሣሪያው ስም እንደ `name@version` ይቀመጣል።
### AUTO ውጤት አሰጣጥ
`mode="auto"` በሚሆንበት ጊዜ፣ እያንዳንዱ ዕጩ ክህሎት ከጥያቄው ዐውድ አንጻር ውጤት ያገኛል (`scoreAutoSkill()` በ-`injection.ts` ውስጥ)፦
| ምልክት | ነጥቦች |
| -------------------------------------------- | ------------- |
| የክህሎቱ ስም በዐውዱ ውስጥ ሳይለወጥ ይገኛል | +6 |
| እያንዳንዱ የስም ቃል ከዐውዱ ቃል ጋር ይዛመዳል | +2 |
| እያንዳንዱ የመለያ ንዑስ-ሕብረቁምፊ ከዐውዱ ጋር ይዛመዳል | +3 |
| እያንዳንዱ የመግለጫ ቃል ከዐውዱ ጋር ይዛመዳል | +1 |
| የበስተጀርባ ምክንያት ከስም ቃል ጋር ይዛመዳል | ለእያንዳንዱ ቃል +2 |
| የበስተጀርባ ምክንያት ከመለያ ጋር ይዛመዳል | ለእያንዳንዱ ቃል +2 |
| በመለያዎች ውስጥ ያለው የአቅራቢ ፍንጭ ከጥያቄው አቅራቢ ጋር ይዛመዳል | +2 / −2 |
`score >= AUTO_MIN_SCORE = 3` ያላቸው ከፍተኛዎቹ `AUTO_MAX_SKILLS = 5` ክህሎቶች ይካተታሉ። እኩል ውጤቶች በ`installCount` (ከከፍተኛ ወደ ዝቅተኛ)፣ ከዚያም በፊደል ቅደም ተከተል ስም ይወሰናሉ (`injection.ts:225-235`)።
### የመሣሪያ ጥሪ መጥለፍ
በ`src/lib/skills/interception.ts` ውስጥ ያለው `handleToolCallExecution()`፣ ከላይኛው አገልግሎት የመሣሪያ ጥሪ ምላሽ ከተመለሰ በኋላ በውይይት ተቆጣጣሪው ይጠራል፦
1. `extractToolCalls()` ለእያንዳንዱ አቅራቢ የተለዩ ቅርጾችን ያነባል (OpenAI `tool_calls` / Responses `function_call`፣ Anthropic `tool_use`፣ Gemini `functionCalls`)።
2. አብሮገነብ የመሣሪያ ተለዋጭ ስሞች (ለምሳሌ፣ `omniroute_web_search` → `web_search`) በመጀመሪያ ይፈታሉ። አብሮገነብ ተቆጣጣሪዎች በቦታው ይሰራሉ።
3. ሌላ ማንኛውም ነገር በ`skillExecutor.execute(name@version, args, { apiKeyId, sessionId })` በኩል ይመራል።
4. ውጤቶች እንደአግባቡ መልሰው በምላሹ ውስጥ ይገባሉ — `tool_results`፣ `function_call_output` ንጥሎች፣ ወይም Anthropic `tool_result` ብሎኮች።
በማስፈጸሚያ ዐውድ ውስጥ ያለው `customSkillExecutionEnabled`፣ አብሮገነብ መጥለፍን ብቻ ለመፍቀድ `false` ሊደረግ ይችላል (በተጠቃሚ የተወሰኑ ተቆጣጣሪዎችን በግልጽ ሁኔታ በሚያሰናክሉ የጥያቄ መንገዶች ይጠቀማል)።
---
## Docker ሳንድቦክስ
አብሮ ያልተሰሩ የኮድ መንገዶች (`eval_code`, `execute_command`) በDocker ውስጥ በ`SandboxRunner` (`src/lib/skills/sandbox.ts`) በኩል ይሰራሉ። እያንዳንዱ ኮንቴይነር በሚከተሉት አማራጮች ይጀመራል፦
```
--rm --network none|bridge --cap-drop ALL
--security-opt no-new-privileges --pids-limit 100
--cpus <cpuLimit/1000> --memory <memoryLimit>m
--tmpfs /tmp:rw,noexec,nosuid,size=64m
--tmpfs /workspace:rw,noexec,nosuid,size=64m
--read-only (readOnly=true ሲሆን)
```
ነባሪዎች (`SandboxRunner.DEFAULT_CONFIG`)፦
| መስክ | ነባሪ | ማስታወሻዎች |
| ---------------- | --------------- | ---------------------------------------------------- |
| `cpuLimit` | 100 (= 0.1 CPU) | ወደ `--cpus` ከመተላለፉ በፊት በ1000 ይካፈላል |
| `memoryLimit` | 256 MB | ጥብቅ ገደብ |
| `timeout` | 30000 ms | በ`SIGTERM` + `docker kill` አማካኝነት ለስላሳ ማቋረጥ |
| `networkEnabled` | `false` | ወደ `--network none` ይቀየራል |
| `readOnly` | `true` | Root FS ለንባብ ብቻ ነው፤ `/tmp` እና `/workspace` tmpfs ናቸው |
`SandboxRunner.kill(id)` እና `killAll()` ለመዝጋት ተጋልጠዋል፤ እየሰሩ ያሉ ኮንቴይነሮች በ`runningContainers: Map<string, ChildProcess>` ውስጥ ይከታተላሉ።
### የሳንድቦክስ የአካባቢ ተለዋዋጮች
በ`src/lib/skills/builtins.ts` ውስጥ በ`process.env` በኩል የተዋቀሩ፦
| የአካባቢ ተለዋዋጭ | ነባሪ | ዓላማ |
| --------------------------------- | ---------------- | ---------------------------------------------------------------- |
| `SKILLS_MAX_FILE_BYTES` | `1048576` (1 MB) | ለ`file_read` እና `file_write` ገደብ |
| `SKILLS_MAX_HTTP_RESPONSE_BYTES` | `256000` | ለ`http_request` ምላሽ አካል ገደብ |
| `SKILLS_MAX_SANDBOX_OUTPUT_CHARS` | `100000` | ወደ ጠሪው ለሚመለሱ stdout/stderr ገደብ |
| `SKILLS_SANDBOX_TIMEOUT_MS` | `10000` | በሳንድቦክስ ውስጥ ለሚሰሩ ትዕዛዞች ነባሪ የጊዜ ገደብ፤ ከፍተኛው 60 s ነው |
| `SKILLS_SANDBOX_NETWORK_ENABLED` | `false` | ለውጪ ግንኙነት ዋና መቆጣጠሪያ። በእያንዳንዱ ጥሪ ማስቻልን ለመፍቀድ `1` ወይም `true` ያድርጉት |
| `SKILLS_ALLOWED_SANDBOX_IMAGES` | (ከታች ይመልከቱ) | በነጠላ ሰረዝ የተለያዩ የተፈቀዱ Docker images |
በነባሪ የተፈቀዱ images፦ `alpine:3.20`, `node:22-alpine`, `python:3.12-alpine`። በ`SKILLS_ALLOWED_SANDBOX_IMAGES` በኩል የሚጨመሩ ማናቸውም images ከነባሪዎቹ ጋር ይዋሃዳሉ፤ የማይታወቁ images በ`normalizeImage()` ውድቅ ይደረጋሉ።
> ማስታወሻ፦ የተለየ `SKILLS_EXECUTION_TIMEOUT_MS` የአካባቢ ተለዋዋጭ የለም። የሳንድቦክስ ያልሆነው አስተናጋጅ የጊዜ ገደብ በ`SkillExecutor` (`executor.ts:13`) ውስጥ ወደ 30 s በቋሚነት ተቀምጧል፤ ነገር ግን በሂደት ጊዜ በ`skillExecutor.setTimeout(ms)` ሊተካ ይችላል።
### የሥራ ቦታ ማግለል
`file_read` እና `file_write` እያንዳንዱን መንገድ በ`<DATA_DIR>/skills/workspaces/<sha256(apiKeyId).slice(0,24)>/` ላይ ካለው ለእያንዳንዱ API ቁልፍ የተመደበ የሥራ ቦታ አንጻር ይፈታሉ። የመንገድ ማቋረጥ (`..`) እና የተከለከሉ ክፍሎች (`.env`, `.git`, `.ssh`, `.omniroute`, `.codex`, `secrets`) ማንኛውም የዲስክ I/O ከመከናወኑ በፊት ውድቅ ይደረጋሉ።
### የHTTP ደህንነት ማጠናከሪያ
`http_request` (`builtins.ts:257`)፦
- የተፈቀዱ ዘዴዎች ዝርዝር፦ `GET, HEAD, POST, PUT, PATCH, DELETE`
- የታገዱ ወደ ውጪ የሚላኩ ራስጌዎች፦ `host, connection, content-length, cookie, set-cookie, authorization, proxy-authorization`
- አቅጣጫ ማዞሪያዎች ተሰናክለዋል (`allowRedirect: false`)
- `guard: "public-only"` በሆነው `safeOutboundFetch` በኩል ይመራል (የግል/loopback ክልሎች ታግደዋል)
- ምላሹ በ`SKILLS_MAX_HTTP_RESPONSE_BYTES` ላይ ይቆረጣል፤ ደንበኛው `truncated: true` ያያል
---
## ድብልቅ አስፈጻሚ (ቅድመ ዕይታ)
`src/lib/skills/hybrid.ts` በእያንዳንዱ ጥሪ `direct` (በሂደት ውስጥ) እና `sandbox` አፈጻጸም መካከል የሚወስን `HybridExecutor` ይገልጻል፤ በጊዜ ማብቂያ/የማህደረ ትውስታ ስህተቶች ጊዜ `autoUpgrade` የዳግም ሙከራ መንገድ አለው። አብረው የተገናኙት `directExecutor` / `sandboxRunner` አተገባበሮች ጊዜያዊ ናቸው (`executeDirect`፣ `executeInSandbox` ጊዜያዊ ነገሮችን ይመልሳሉ) — ይህን ሞጁል በግንባታ ላይ እንዳለ ውል ይቁጠሩት። እውነተኛው አፈጻጸም አሁንም በ`skillExecutor` + `SandboxRunner` በኩል ይከናወናል።
---
## ማከማቻ
ስኪማው በሁለት ማይግሬሽኖች ውስጥ ይገኛል፦
- `src/lib/db/migrations/016_create_skills.sql` — መሠረታዊ `skills` እና `skill_executions` ሰንጠረዦች፣ በ`(api_key_id, name)` እና `(skill_id, status, created_at)` ላይ ኢንዴክሶች አሏቸው።
- `src/lib/db/migrations/027_skill_mode_and_metadata.sql` — `mode`፣ `source_provider`፣ `tags` (JSON)፣ `install_count`ን ወደ `skills` ያክላል።
`skill_executions.status` በዳታቤዝ ደረጃ የተገደበ ነው፦ `CHECK(status IN ('pending', 'running', 'success', 'error', 'timeout'))`።
---
## REST API
ሁሉም የመዳረሻ ነጥቦች በ`src/app/api/skills/` ስር ይገኛሉ። የአስተዳደር መዳረሻ ነጥቦች (`/api/skills`፣ `/api/skills/[id]`፣ `/api/skills/install`) በ`requireManagementAuth()` በኩል **የአስተዳደር ማረጋገጫ** ይፈልጋሉ። የገበያ/ጭነት ፍሰቶቹ ቀለል ያለውን `isAuthenticated()` (ክፍለ ጊዜ ወይም API ቁልፍ) ይጠቀማሉ።
| የመዳረሻ ነጥብ | ሜተድ | ዓላማ |
| --------------------------------- | ------ | ------------------------------------------------------------------------ | --- | ------------------------ | -------- | ------------------ |
| `/api/skills` | GET | የተመዘገቡ ክህሎቶችን ዘርዝር። `?q=`፣ `?mode=onን | off | auto`፣ `?source=skillsmp | skillssh | local`፣ ገጽ ከፈላ |
| `/api/skills/[id]` | PUT | `enabled` ወይም `mode`ን አዘምን |
| `/api/skills/[id]` | DELETE | በመታወቂያ ምዝገባውን ሰርዝ |
| `/api/skills/install` | POST | ብጁ ክህሎት ጫን (የማስተናገጃ ኮድ + ስኪማ) |
| `/api/skills/marketplace` | GET | የSkillsMP ካታሎግን ፈልግ (`q` ባዶ ሲሆን ታዋቂ ነባሪዎችን ይመልሳል) |
| `/api/skills/marketplace/install` | POST | የSkillsMP ክህሎት ጫን (ንቁ አቅራቢ = `skillsmp` መሆን ያስፈልጋል) |
| `/api/skills/skillssh` | GET | የskills.sh ካታሎግን ፈልግ (`?q=&limit=`፣ ከፍተኛው 100) |
| `/api/skills/skillssh/install` | POST | የskills.sh ክህሎት ጫን (ንቁ አቅራቢ = `skillssh` መሆን ያስፈልጋል) |
| `/api/skills/executions` | GET | በገጽ የተከፋፈለ የአፈጻጸም ታሪክ (`?apiKeyId=`) |
| `/api/skills/executions` | POST | የተመዘገበ ክህሎትን እንደ አስፈላጊነቱ አስፈጽም |
`settings.skillsEnabled === false` ሲሆን፣ `POST /api/skills/executions` መዳረሻ ነጥቡ HTTP `503`ን ከ`{ error: "Skills execution is disabled..." }` ጋር ይመልሳል (`executor.ts:42-45`)። ኦፕሬተሮች ዋናውን መቀየሪያ ከ**ቅንብሮች → AI** ማብራት ይችላሉ።
### ምሳሌ፦ ብጁ ክህሎት መጫን
```bash
curl -X POST http://localhost:20128/api/skills/install \
-H "Authorization: Bearer $OMNIROUTE_MGMT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "reverse-text",
"version": "1.0.0",
"description": "Reverses a string",
"schema": {
"input": { "type": "object", "properties": { "text": { "type": "string" } }, "required": ["text"] },
"output": { "type": "object", "properties": { "reversed": { "type": "string" } } }
},
"handlerCode": "echo-handler",
"apiKeyId": "your-api-key-id"
}'
```
የ`handlerCode` ሕብረቁምፊ **የማስተናገጃ ስም ፍለጋ** ነው — ሊፈጸም የሚችል ኮድ አይደለም። አስፈጻሚው `skillExecutor.registerHandler(name, fn)` (`executor.ts:25`)ን በመጠቀም ያዛምደዋል። የገበያ ጭነቶች የSKILL.md ጽሑፍን እንደ ሰነድ በዚህ መስክ ያከማቻሉ፣ እና አፈጻጸሙን በሞዴል በተፈጠሩ የመሣሪያ ጥሪዎች በኩል ያስተላልፋሉ። በተጠቃሚ የቀረበ የዘፈቀደ ምንጭ eval አይደረግም።
---
## MCP መሣሪያዎች
አራት MCP መሣሪያዎች የክህሎቶችን በይነገጽ (`open-sse/mcp-server/tools/skillTools.ts`) ይሸፍናሉ። MCP አገልጋዩ ሲነሳ በራስ-ሰር ይመዘገባሉ።
| መሣሪያ | መግለጫ |
| ----------------------------- | --------------------------------------------------------- |
| `omniroute_skills_list` | ክህሎቶችን ይዘረዝራል፤ አማራጭ ማጣሪያዎች፦ `apiKeyId`፣ `name`፣ `enabled` |
| `omniroute_skills_enable` | አንድን ክህሎት በ`skillId` ያንቁ/ያሰናክሉ |
| `omniroute_skills_execute` | ክህሎትን በግቤት payload ያስፈጽማል |
| `omniroute_skills_executions` | የቅርብ ጊዜ የአፈጻጸም ታሪክ (ነባሪ 50፣ ከፍተኛው 100) |
ስለ የማጓጓዣ ቅንብር እና የወሰን ምደባዎች [MCP-SERVER.md](./MCP-SERVER.md)ን ይመልከቱ።
---
## A2A ውህደት
`src/lib/skills/a2a.ts` የ`memory_aware_routing` A2A ክህሎት ገላጭን እና የ`registerA2ASkill(registry)` አጋዥን ወደ ውጭ ይልካል። ብጁ A2A ክህሎቶች በ`src/lib/a2a/skills/` ውስጥ ይገኛሉ፣ እና በ`A2A_SKILL_HANDLERS` (`src/lib/a2a/taskExecution.ts`) በኩል ይላካሉ። ለሙሉው የተግባር የሕይወት ዑደት [A2A-SERVER.md](./A2A-SERVER.md)ን ይመልከቱ።
---
## አዲስ አብሮገነብ ክህሎት ማከል
1. **handlerን ይግለጹ** በ`src/lib/skills/builtins.ts` (ወይም በ`src/lib/skills/builtin/` ሥር ባለ ተጓዳኝ ፋይል)። ፊርማ፦ `(input, { apiKeyId, sessionId }) => Promise<output>`።
2. **Sandbox የተደረገ የኮድ መንገድ ነው?** `sandboxRunner.run(image, command, env, sandboxConfig({...}))`ን ይጥሩ። ከallowlist ጋር `normalizeImage()`ን ይጠቀሙ።
3. **የፋይል ስርዓት መንገድ ነው?** ዲስኩን ከመንካትዎ በፊት ሁልጊዜ በ`resolveWorkspacePath(input, context)` ያሳልፉት።
4. **የአውታረ መረብ ጥሪ ነው?** `safeOutboundFetch`ን ከ`guard: "public-only"` ጋር ይጠቀሙ፤ headersን በ`sanitizeHeaders()` ያጽዱ።
5. **ይመዝግቡ** ግቤቱን ወደ `builtinSkills` በማከል (ወይም በሚነሳበት ጊዜ እንደ `registerBrowserSkill(executor)` ያለውን በመጥራት)።
6. **አብሮገነብ የመሣሪያ ተለዋጭ ስሞችን ያገናኙ** (አማራጭ)፤ upstream model የተለየ ስም የሚያወጣ ከሆነ በ`BUILTIN_TOOL_ALIASES` (`interception.ts:23`) ውስጥ።
7. **ሙከራዎች** በ`src/lib/skills/__tests__/` (Vitest)።
---
## ብጁ (አብሮገነብ ያልሆነ) ክህሎት ማከል
1. ሂደቱ ሲጀምር handlerን ይመዝግቡ፦
```ts
skillExecutor.registerHandler("my-handler", async (input, ctx) => { ... });
```
2. ክህሎቱን በ`POST /api/skills/install` በኩል ያስገቡ (የ`handlerCode` መስክ ከተመዘገበው handler ስም ጋር መዛመድ አለበት)።
3. `mode`ን በ`PUT /api/skills/[id]` በኩል ወደ `on` ወይም `auto` ይቀይሩ።
---
## የክወና ምክሮች
- **ዋና ማብሪያ/ማጥፊያ፦** `settings.skillsEnabled = false` ሁሉንም አፈጻጸም ይከለክላል፣ እና በ`/api/skills/executions` ላይ HTTP `503` ይመልሳል። registryው መጫኑን ይቀጥላል።
- **የውጪ ግንኙነትን ይዝጉ፦** ሙሉ በሙሉ ከአውታረ መረብ የተነጠለ sandboxing ለማድረግ `SKILLS_SANDBOX_NETWORK_ENABLED`ን ሳያቀናብሩ ይተዉት (ነባሪ)። በእያንዳንዱ ጥሪ `networkEnabled: true` ቢሆንም አሁንም ዋናውን gate ይፈልጋል።
- **የተወሰኑ imagesን ይፍቀዱ፦** allowlistን ለማስፋት `SKILLS_ALLOWED_SANDBOX_IMAGES="myorg/sandbox:1.0,node:22-alpine"`ን ያቀናብሩ።
- **አፈጻጸሞችን ኦዲት ያድርጉ፦** `/dashboard/skills/executions` እና `omniroute_skills_executions` ሁለቱም `skill_executions`ን ይጠይቃሉ። የተሳኩ አሂዶች `durationMs`ን ያካትታሉ፤ ያልተሳኩት `errorMessage`ን ያካትታሉ።
- **የcache ማጽዳት፦** በDB ላይ በእጅ ለውጦችን ካደረጉ በኋላ `skillRegistry.invalidateCache()`ን ይጥሩ፤ አለበለዚያ 60 s ይጠብቁ።
- **ስም-አልባ workspace፦** `apiKeyId` ባዶ ሲሆን፣ ሁሉም ጥሪዎች ወደ ተመሳሳዩ `"anonymous"` workspace በhash ይመደባሉ — share-aware ኮድ ሁልጊዜ እውነተኛ key ማሳለፍ አለበት።
---
## የአፈጻጸም የሕይወት ዑደት (v3.8.16+)
`SkillExecutor` (`src/lib/skills/executor.ts`) እያንዳንዱን የክህሎት ጥሪ የሚያስተዳድር **ነጠላ ኢንስታንስ (singleton)** ነው። የጊዜ ማብቃቶችን፣ ዳግም ሙከራዎችን እና የአፈጻጸም ሁኔታን ለማረም የሕይወት ዑደቱን መረዳት ወሳኝ ነው።
### ባለ 5-ደረጃ የሕይወት ዑደት
```
execute() ተጠራ
│
▼
┌─────────────┐
│ PENDING │ ← ወረፋ ላይ፣ ገና አልተጀመረም (የDB ረድፍ ተፈጥሯል)
└──────┬──────┘
│ አስተናጋጁን አስጀምር
▼
┌─────────────┐
│ RUNNING │ ← አስተናጋጁ ከጊዜ ማብቂያ ጋር ተጠርቷል
└──────┬──────┘
│
┌────┴────┬──────────┬──────────┐
│ │ │ │
▼ ▼ ▼ ▼
SUCCESS ERROR TIMEOUT (ሌላ መንገድ የለም — በወላጅ ሂደቱ ተቋርጧል)
│ │ │
└────┬────┴──────────┘
│
▼
የDB ረድፍ በሁኔታ፣ ውጤት፣ durationMs ተዘምኗል
```
### ነባሪ ውቅር
| ቅንብር | ነባሪ | በዚህ ሊዋቀር ይችላል |
| ------------ | ------------- | ------------------------------------ |
| `timeout` | `30000` (30s) | `skillExecutor.setTimeout(ms)` |
| `maxRetries` | `3` | `skillExecutor.setMaxRetries(count)` |
> **አስፈላጊ**፦ አስፈጻሚው ነጠላ ኢንስታንስ ነው — `setTimeout()`ን መጥራት በዓለም አቀፍ ደረጃ ሁሉንም ቀጣይ ጥሪዎች ይነካል። ለእያንዳንዱ ክህሎት የተለየ የጊዜ ማብቂያ በአሁኑ ጊዜ አይደገፍም፤ ለእያንዳንዱ ክህሎት የተለያዩ የጊዜ ማብቂያዎች ካስፈለጉዎት፣ የተለያዩ ሂደቶችን ያስገቡ ወይም አስፈጻሚውን fork ያድርጉ።
### የሁኔታ እሴቶች
ከ`src/lib/skills/types.ts`፦
```ts
enum SkillStatus {
PENDING = "pending", // ወረፋ ላይ፣ ገና አልተጀመረም
RUNNING = "running", // አስተናጋጁ ተጠርቷል
SUCCESS = "success", // አስተናጋጁ ትክክለኛ ውጤት መልሷል
ERROR = "error", // አስተናጋጁ ልዩ ሁኔታ አስነስቷል
TIMEOUT = "timeout", // የአስፈጻሚውን የጊዜ ማብቂያ አልፏል
}
```
> **ማስታወሻ**፦ የ`TIMEOUT` ሁኔታ በenum ውስጥ ተገልጿል፣ ነገር ግን በአሁኑ የአስፈጻሚ ትግበራ **በተግባር ወደ DB አይጻፍም** — የጊዜ ማብቃቶች `"Skill execution timed out"` ከሚለው መልዕክት ጋር እንደ `ERROR` ይታያሉ። የሁኔታ enum ለወደፊት አጠቃቀም ተይዟል።
### አፈጻጸሞችን መመርመር
```ts
import { skillExecutor } from "omniroute/skills/executor";
// አንድን የተወሰነ አፈጻጸም በID አግኝ
const exec = skillExecutor.getExecution("exec-uuid-123");
if (exec) {
console.log(`${exec.skillName}: ${exec.status} in ${exec.durationMs}ms`);
}
// ለአንድ API ቁልፍ የቅርብ ጊዜ አፈጻጸሞችን ዘርዝር
const recent = skillExecutor.listExecutions("api-key-id", 50, 0);
for (const e of recent) {
console.log(`${e.skillName} → ${e.status} (${e.durationMs}ms)`);
}
// አጠቃላይ አፈጻጸሞችን ቁጠር
const total = skillExecutor.countExecutions("api-key-id");
```
### የዳግም ሙከራ ባህሪ
የ`maxRetries` ቅንብር ይቀመጣል፣ ነገር ግን በአስፈጻሚው `execute()` ዘዴ **በአሁኑ ጊዜ ጥቅም ላይ አይውልም** — አንድ ሙከራ ብቻ ያከናውናል። የ`maxRetries` እሴት ለወደፊት ትግበራ እና ሊያነቡት ለሚፈልጉ hooks ተጋልጧል።
ለአሁን፣ ዳግም ሙከራዎች በክህሎት አስተናጋጁ ውስጥ መተግበር አለባቸው። አብሮገነብ
ክህሎቶች በአስፈጻሚው ላይ ይመዘገባሉ (ለምሳሌ፣ `registerBuiltinSkills(executor)`
/ `registerBrowserSkill(executor)` በ`src/lib/skills/builtin/` ውስጥ)፤ የትኛውንም አስተናጋጅ
ቢመዘግቡ፣ የራሱን የዳግም ሙከራ ዑደት ማካተት ይችላል፦
```ts
// በክህሎት አስተናጋጅ ውስጥ
async function handler(input, ctx) {
const maxRetries = 3;
let lastError: Error | null = null;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await fetchSomething(input);
} catch (err) {
lastError = err as Error;
if (attempt < maxRetries) {
await new Promise((r) => setTimeout(r, 1000 * attempt));
}
}
}
throw lastError;
}
```
---
## SkillMode በዝርዝር
የ`SkillMode` enum (`src/lib/skills/types.ts`) ክህሎቶች **መቼ እና እንዴት** እንደሚጠሩ ይቆጣጠራል፦
```ts
enum SkillMode {
AUTO = "auto", // LLM ክህሎቱን መቼ መጥራት እንዳለበት ይወስናል
MANUAL = "manual", // የሚጠራው በተጠቃሚው ግልጽ ጥያቄ ብቻ ነው
HYBRID = "hybrid", // AUTO ነጥብ አሰጣጥ + በእጅ መሻር
}
```
> **ማስታወሻ**፦ የኮድ ማከማቻው `SkillMode` (AUTO/MANUAL/HYBRID)ን ይገልጻል፤ የ`Skill.mode` መስክ ግን የተለየ ቅርጽ (`"on" | "off" | "auto"`) ይጠቀማል። እነዚህ የተዛመዱ ቢሆኑም ተመሳሳይ አይደሉም — `SkillMode` ለአስፈጻሚ ፖሊሲ ሲሆን፣ `Skill.mode` ደግሞ እያንዳንዱ ክህሎት እንዲሰራ ለማድረግ ነው።
### እያንዳንዱን ሁነታ መቼ መጠቀም እንዳለብዎት
| ሁነታ | የLLM ባህሪ | የአጠቃቀም ሁኔታ |
| -------- | -------------------------------------------------------------- | ------------------------------------------- |
| `AUTO` | LLM አስፈላጊ ነው ብሎ ሲያስብ ክህሎቱን መጥራት ይችላል | አጠቃላይ ዓላማ ያላቸው ክህሎቶች (ፋይል ማንበብ፣ HTTP ጥያቄዎች) |
| `MANUAL` | LLM ክህሎቱን መጥራት አይችልም፤ የሚያስነሳው ግልጽ የ`executeSkill` API ጥሪ ብቻ ነው | ስሱ ክዋኔዎች (በውሂብ ጎታ ላይ መጻፍ፣ ክፍያዎች) |
| `HYBRID` | LLM ክህሎቱን ሊጠቁም ይችላል፤ ተጠቃሚው ማረጋገጥ አለበት | ተጓዳኝ ውጤቶች ያሏቸው ነገር ግን አደገኛ ያልሆኑ ክህሎቶች |
### AUTO ነጥብ አሰጣጥ
የ`AUTO` ሁነታ ሲሰራ፣ እያንዳንዱ እጩ ክህሎት በ`src/lib/skills/injection.ts`
ውስጥ ባለው `scoreAutoSkill()` አማካኝነት ከጥያቄው ዐውድ ጋር በማነጻጸር ነጥብ
ያገኛል — ይህም ድምር ላይ የተመሠረተ የኢንቲጀር ነጥብ ስርዓት ነው (የክህሎት ስም መዛመድ፣ የስም/መለያ/መግለጫ ቶከኖች መደራረብ፣
የበስተጀርባ-ምክንያት ፍንጮች፣ የአቅራቢ-ፍንጭ ጉርሻ/ቅጣት)። `score >= AUTO_MIN_SCORE = 3`
ያላቸው ከፍተኛዎቹ `AUTO_MAX_SKILLS = 5` ክህሎቶች ሊጠሩ እንደሚችሉ መሣሪያዎች
ይጨመራሉ፤ እኩል ነጥቦች በ`installCount` ከዚያም በስም ይለያያሉ። ሙሉውን የነጥብ ሰንጠረዥ
ቀደም ብሎ በዚህ ሰነድ ውስጥ በ[**የመሣሪያ ንድፍ ማመንጨት → AUTO ነጥብ አሰጣጥ**](#auto-scoring)
ይመልከቱ፤ የfloat `0.6` ዓይነት ገደብም ሆነ በ`registry.ts` ውስጥ የነጥብ አሰጣጥ የለም።
---
## አብረው የተካተቱ ክህሎቶች ካታሎግ
OmniRoute በ`src/lib/skills/builtin/` ውስጥ በጥንቃቄ የተመረጡ አብረው የተካተቱ ክህሎቶችን ይዞ ይመጣል። በጣም የተለመዱት፦
### የአሳሽ ራስ-ሰር ማስኬጃ ክህሎት
የአሳሽ ክህሎቱ (`src/lib/skills/builtin/browser.ts`) በPlaywright/Puppeteer በኩል ያለ ግራፊክ በይነገጽ የአሳሽ ራስ-ሰር ማስኬጃን ይሰጣል። **ተተግብሯል፣ ነገር ግን በነባሪው የክህሎቶች ካታሎግ ውስጥ አልተካተተም** — ለመጠቀም የአሳሽ ቅጥያ ፕለጊኑን ለብቻው ይጫኑ።
```ts
// በውቅርዎ ውስጥ ያንቁ
const config: SkillConfig = {
enabled: true,
mode: SkillMode.MANUAL, // ሁልጊዜ ግልጽ ጥሪ እንዲኖር ይጠይቁ
allowedSkills: ["browser"],
timeout: 60000, // ለገጽ ጭነቶች 60 ሰከንድ
maxRetries: 1,
};
```
### ሌሎች አብረው የተካተቱ ምድቦች
| ምድብ | ክህሎቶች | ሁነታ |
| -------- | ----------------------------------------------- | ------ |
| የፋይል I/O | `file_read`, `file_write` | AUTO |
| HTTP | `http_request` | AUTO |
| ፍለጋ | `web_search` | AUTO |
| ኮድ ማስፈጸም | `eval_code` (በተገደበ አካባቢ የሚሰራ JavaScript/Python) | HYBRID |
| ስርዓት | `execute_command` (በተገደበ አካባቢ የሚሰራ CLI አፈጻጸም) | MANUAL |
### ብጁ ክህሎት ማከል
በፕለጊን ስርዓቱ አማካኝነት ብጁ ክህሎት እንዴት ማከል እንደሚቻል [የPlugin SDK እና የክህሎቶች ውህደት](./PLUGIN_SDK.md)ን ይመልከቱ።
---
## ተጨማሪ ይመልከቱ
- [MCP-SERVER.md](./MCP-SERVER.md) — የMCP መሣሪያ ምዝገባ እና የመጓጓዣ ዘዴዎች
- [A2A-SERVER.md](./A2A-SERVER.md) — የA2A ተግባር የሕይወት ዑደት እና የክህሎት ስርጭት
- [USER_GUIDE.md](../guides/USER_GUIDE.md#-skills-system) — ለተጠቃሚዎች የቀረበ መግቢያ
- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — የጥያቄ ማስኬጃ ሂደት እና የክፍሎች ካርታ
- ምንጭ፦ `src/lib/skills/`፣ `src/app/api/skills/`፣ `open-sse/mcp-server/tools/skillTools.ts`
- ሙከራዎች፦ `src/lib/skills/__tests__/integration.test.ts`

496
docs/i18n/am/docs/frameworks/TRAFFIC_INSPECTOR.md Normal file
View File

@@ -0,0 +1,496 @@
# Traffic Inspector (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/TRAFFIC_INSPECTOR.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇦🇿 [az](../../../az/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇩🇰 [da](../../../da/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇩🇪 [de](../../../de/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇬🇷 [el](../../../el/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇪🇸 [es](../../../es/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇪🇪 [et](../../../et/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇱 [he](../../../he/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇩 [id](../../../id/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇹 [it](../../../it/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇰🇭 [km](../../../km/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇲🇲 [my](../../../my/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇳🇴 [no](../../../no/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [or](../../../or/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇱🇰 [si](../../../si/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇮🇳 [te](../../../te/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇹🇭 [th](../../../th/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/TRAFFIC_INSPECTOR.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/TRAFFIC_INSPECTOR.md)
---
Traffic Inspector የOmniRoute አብሮገነብ HTTPS ትራፊክ ማረሚያ ነው — ከCharles Proxy / mitmweb / HTTP Toolkit ጋር ተመሳሳይ፣ **LLM-aware** እና **agent-aware** የሆነ መሣሪያ ነው። በ`/dashboard/tools/traffic-inspector` ላይ የሚገኝ ሲሆን እስከ 5 ከሚደርሱ በአንድ ጊዜ ከሚሠሩ የቀረጻ ምንጮች ቀጥታ ትራፊክ ይቀበላል።
**የዳሽቦርድ መገኛ:** `/dashboard/tools/traffic-inspector`
**የጎን አሞሌ ቡድን:** መሣሪያዎች (ከAgentBridge በኋላ)
**በተጨማሪ ይመልከቱ:** [`AGENTBRIDGE.md`](./AGENTBRIDGE.md) — AgentBridge የቀረጻ ሁነታ 1 ነው።
---
## §1 አጠቃላይ እይታ
### Traffic Inspectorን ልዩ የሚያደርጉት ነገሮች
| ባህሪ | mitmweb | Charles | Fiddler | **OmniRoute Traffic Inspector** |
| ------------------------------------------------------------------- | :-----: | :-----: | :-----: | :-----------------------------: |
| በድር ላይ የተመሠረተ | ✓ | ✗ | ✗ | ✓ |
| ክፍት ምንጭ | ✓ | ✗ | ከፊል | ✓ |
| **Agent-aware** (ጥያቄው ከAntigravity/Copilot/ወዘተ መምጣቱን ያውቃል) | ✗ | ✗ | ✗ | ✓ |
| **LLM-aware** (የOpenAI/Anthropic/Gemini ቅርጽን፣ ቶከኖችን እና ሞዴልን ይተነትናል) | ✗ | ✗ | ✗ | ✓ |
| **የሞዴል ማዛመድ ይታያል** (gemini-3-flash → claude-sonnet-4.7) | ✗ | ✗ | ✗ | ✓ |
| **የፕሮክሲ/የላይኛው አገልጋይ መዘግየት መለያየት** | ከፊል | ✗ | ✗ | ✓ |
| **ከOmniRoute ጋር የተዋሃደ** መስመር ማስያዝ፣ አማራጭ መንገድ እና ወጪ | ✗ | ✗ | ✗ | ✓ |
| **የሥርዓቱ አጠቃላይ ፕሮክሲ ማረም** (በማሽኑ ላይ ያለ ማንኛውም መተግበሪያ) | ✓ | ✓ | ✓ | ✓ |
| **ብጁ አስተናጋጅ ቀረጻ** (ለእያንዳንዱ አስተናጋጅ የDNS ማዘዋወር) | ✓ | ✓ | ✓ | ✓ |
| **HTTP_PROXY የአካባቢ ተለዋዋጭ ሁነታ** | ✓ | ✓ | ✓ | ✓ |
| **የውይይት እይታ** (ባለብዙ ዙር አረፋዎች፣ tool_use/tool_result) | ✗ | ✗ | ✗ | ✓ |
| **የSSE ዥረት ማዋሃጃ** (ከልዩነት ክስተቶች መልሶ ይገነባል) | ✗ | ✗ | ✗ | ✓ |
| **የክፍለ ጊዜ ቀረጻ** (ስም ሊሰጠው እና ወደ .har/.jsonl ሊላክ የሚችል) | ✗ | ✓ | ✓ | ✓ |
### አርክቴክቸሩ በአንድ አንቀጽ
`TrafficBuffer` (`src/mitm/inspector/buffer.ts`) በጋራ የሚጠቀሙበት፣ በማህደረ ትውስታ ውስጥ የሚገኝ ቀለበት ቋት ነው (ነባሪው 1000 ግቤቶች ሲሆን፣ በ`INSPECTOR_BUFFER_SIZE` ሊዋቀር ይችላል)። ሁሉም የቀረጻ ምንጮች `push()`ን በመጠቀም ወደ እሱ ይጽፋሉ። የቋቱ ክፍል `kindDetector.ts`ን በመጠቀም እያንዳንዱን ግቤት ይመድባል (የLLM ጥያቄ መሆኑን ይወስናል)፣ `contextKey`ን (የሥርዓት መጠየቂያው SHA-256 አሻራ) ያሰላል፣ እንዲሁም በ`globalTrafficBuffer.subscribe()` በኩል ለሁሉም የWebSocket ተመዝጋቢዎች ያሰራጫል። ዳሽቦርዱ በ`GET /api/tools/traffic-inspector/ws` በኩል ይገናኛል፤ ሲገናኝም ቅጽበታዊ ቅጂ ይቀበላል፣ ከዚያም `new`/`update`/`clear` ክስተቶች ይከተላሉ።
---
## §2 የቀረጻ ሁነታዎች
Traffic Inspector **5 በአንድ ጊዜ የሚሰሩ የቀረጻ ምንጮችን** ይደግፋል። እያንዳንዱ በተናጠል ሊበራ ወይም ሊጠፋ ይችላል። በእያንዳንዱ `InterceptedRequest` (`src/mitm/inspector/types.ts`) ላይ ያለው `source` መስክ ከ `"agent-bridge"`፣ `"custom-host"`፣ `"http-proxy"`፣ `"system-proxy"` ወይም `"tproxy"` አንዱ ነው።
### ሁነታ 1 — AgentBridge (ነባሪ፣ ሁልጊዜ የበራ)
**ምንጭ:** የAgentBridge ማስተናገጃዎች (`src/mitm/handlers/base.ts`)
**ዘዴ:** በ`MitmHandlerBase` ውስጥ ያለ እያንዳንዱ `intercept()` ጥሪ፣ ጥያቄውን ከማስተላለፉ በፊት `hookBufferStart()`ን እና ሲጠናቀቅ `hookBufferUpdate()`ን ይጠራል። ምንም ተጨማሪ ውቅር አያስፈልግም — AgentBridge መስራት እንደጀመረ ወዲያውኑ ይሰራል።
**ሽፋን:** በAgentBridge ውስጥ የተዋቀሩት 9 የIDE ወኪሎች
**ማስታወሻ:** በ`InterceptedRequest` ውስጥ ያለው `source` መስክ = `"agent-bridge"`
### ሁነታ 2 — ብጁ አስተናጋጆች (የDNS አቅጣጫ ለውጥ)
**ምንጭ:** በተጠቃሚ የተገለጸ የአስተናጋጆች ዝርዝር (`inspector_custom_hosts` ሰንጠረዥ)
**ዘዴ:** በUI በኩል አስተናጋጅ ማከል `127.0.0.1 <host>`ን ወደ `/etc/hosts` ያክላል (sudo ያስፈልጋል)። ነባሩ የAgentBridge MITM አገልጋይ (ወደብ 443) ለአዲሱ አስተናጋጅ የSNI ምስክር ወረቀትን ተለዋዋጭ በሆነ መንገድ ያመነጫል።
**ሽፋን:** የታከለውን አስተናጋጅ የሚጠቀም ማንኛውም መተግበሪያ — የመተግበሪያ ውቅር ለውጥ አያስፈልግም
**ማስታወሻ:** `source` = `"custom-host"`
የአጠቃቀም ምሳሌዎች፦
- ከPython ስክሪፕቶች የሚመጣውን `api.openai.com` ይከታተሉ
- `my-internal-llm.company.com`ን ከስህተት ያጽዱ
- በተመሳሳይ አውታረ መረብ ላይ ካሉ ተንቀሳቃሽ መሣሪያዎች ትራፊክ ይቅረጹ (በARP spoofing — የላቀ)
### ሁነታ 3 — የHTTP_PROXY አዳማጭ (ወደብ 8080)
**ምንጭ:** የ`HTTP_PROXY`/`HTTPS_PROXY` የአካባቢ ተለዋዋጮችን የሚጠቀሙ መተግበሪያዎች
**ዘዴ:** እንደ መደበኛ ግልጽ የHTTP/HTTPS ተኪ የሚሰራ በወደብ 8080 (`src/mitm/inspector/httpProxyServer.ts`) ላይ ያለ ሁለተኛ አዳማጭ። የ`CONNECT` ዋሻዎችን (HTTPS) እና ቀጥተኛ የHTTP ጥያቄዎችን ይቀበላል።
**ሽፋን:** የ`HTTP_PROXY` የአካባቢ ተለዋዋጭን የሚያከብር ማንኛውም መተግበሪያ — የDNS ለውጥም ሆነ sudo አያስፈልግም
**ማስታወሻ:** `source` = `"http-proxy"`
```bash
# ለአንድ ትዕዛዝ ፈጣን ቀረጻ፦
HTTPS_PROXY=http://127.0.0.1:8080 curl https://api.openai.com/v1/models
# በሼል ክፍለ ጊዜ ውስጥ ቀጣይነት ያለው ቀረጻ፦
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
```
**የTLS ገደብ:** የHTTPS `CONNECT` ዋሻዎች እንደ ሜታዳታ ብቻ (አስተናጋጅ፣ ወደብ፣ የጊዜ መረጃ) ይቀረጻሉ — የTLS ይዘት በነባሪ ዲክሪፕት አይደረግም። የይዘቱን ሙሉ ምርመራ ለማንቃት "በተኪ ሁነታ HTTPSን ዲክሪፕት አድርግ" መቀያየሪያውን ያብሩ (በፈቃድ የሚነቃ፣ የAgentBridge ምስክር ወረቀት የታመነ እንዲሆን ይፈልጋል)።
**የወደብ ግጭት:** ወደብ 8080 በጥቅም ላይ ከሆነ፣ AgentBridge የተዋቀረ ስህተት ያለው 409 ይመልሳል። ወደቡን በ`INSPECTOR_HTTP_PROXY_PORT` የአካባቢ ተለዋዋጭ በኩል ይቀይሩ።
### ሁነታ 4 — የስርዓት አቀፍ ተኪ (የላቀ፣ በፈቃድ የሚነቃ)
**ምንጭ:** የOS ደረጃ የተኪ ቅንብሮች (በማሽኑ ላይ ላሉ ሁሉም መተግበሪያዎች ተፈጻሚ ይሆናል)
**ዘዴ:** ሁሉንም የHTTP/HTTPS ትራፊክ በHTTP_PROXY አዳማጭ በኩል ለማስተላለፍ የOS APIዎችን ይጠቀማል፦
- **macOS:** `networksetup -setwebproxy / -setsecurewebproxy`
- **Linux:** `gsettings set org.gnome.system.proxy` + `/etc/environment`
- **Windows:** `netsh winhttp set proxy 127.0.0.1:8080`
**ሽፋን:** በማሽኑ ላይ የስርዓት ተኪ ቅንብሮችን የሚያከብር እያንዳንዱ መተግበሪያ
**ማስታወሻ:** `source` = `"system-proxy"`
**የደህንነት ዘዴዎች:**
- በራስ-ሰር የማሰናከያ ሰዓት ቆጣሪ (ነባሪው 30 ደቂቃ፣ በ`INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES` ሊዋቀር ይችላል)
- ቀዳሚው የስርዓት ተኪ ሁኔታ በDB ውስጥ ተቀምጦ ለውጡ ሲመለስ እንደነበረ ይመለሳል
- የስርዓት ተኪው ንቁ ሆኖ ሳለ ተጠቃሚው ወደ ሌላ ገጽ ከሄደ፣ ዳሽቦርዱ "የስርዓት ተኪውን ወደነበረበት በመመለስ ላይ" የሚል ጥያቄ ያሳያል
- UI `⚠ የላቀ` ባጅን + ግልጽ የማረጋገጫ ምልክት ሳጥንን ያሳያል
### ሁነታ 5 — TPROXY ግልጽ ዲክሪፕሽን (Linux፣ root፣ በፈቃድ የሚነቃ)
**ምንጭ:** የከርነል TPROXY + የፖሊሲ ማዘዋወር (`src/mitm/tproxy/`)
**ዘዴ:** በ`mangle OUTPUT` ውስጥ ወደ ዒላማ ወደብ (ነባሪ `443`) የሚደረጉ አዲስ የአካባቢ ወጪ የTCP ግንኙነቶችን ምልክት ያደርጋል፤ `ip rule` ምልክት የተደረገባቸውን ፓኬቶች ወደ አካባቢያዊ መዳረሻ እንደገና ያዘዋውራል፣ እና የ`mangle PREROUTING` `TPROXY` ዒላማ ወደ ግልጽ (**IP_TRANSPARENT**) አዳማጭ (ነባሪ ወደብ `8443`) ያስተላልፋቸዋል። አዳማጩ በተለዋዋጭ CA **ለእያንዳንዱ የSNI አስተናጋጅ ስም በፍላጎት ጊዜ** በሚሰጥ የleaf ምስክር ወረቀት TLSን ያቋርጣል፣ ዲክሪፕት የተደረገውን ልውውጥ ይቀርጻል፣ እና ጥያቄውን እንደገና ኢንክሪፕት በማድረግ ወደ ዋናው መዳረሻ ያስተላልፋል።
**ሽፋን:** በዒላማ ወደቡ ላይ ያሉ **ማናቸውም** የመዳረሻ አስተናጋጆች — የ`/etc/hosts` spoof፣ የ`HTTP_PROXY` የአካባቢ ተለዋዋጭ ወይም የስርዓት አቀፍ ተኪ ለውጥ አያስፈልግም። የሚጠለፈው ሂደት ምንም የውቅር ለውጥ አያስፈልገውም፣ ነገር ግን ተለዋዋጩን CA ማመን አለበት።
**ማስታወሻ:** `source` = `"tproxy"`
**መስፈርቶች:** Linux ብቻ (**IP_TRANSPARENT** በLinux ላይ ብቻ ይገኛል)፣ የ**CAP_NET_ADMIN** ችሎታ (root)፣ እና በC toolchain (`npm run build:native:tproxy`) መገንባት ያለበት ቤተኛ N-API addon። እነዚህ በማይገኙበት ጊዜ፣ የዳሽቦርዱ መቀያየሪያ "የTPROXY ዲክሪፕሽን Linux + root + ቤተኛውን addon ይፈልጋል" በሚል tooltip ይሰናከላል። የፋየርዎል ደንቦቹ በግብይታዊ መንገድ ተግባራዊ ይሆናሉ/ይመለሳሉ (ብልሽት የ`mangle` ደንብን በፍጹም ትቶ አይሄድም) እና ሲያስነሱ ይጸዳሉ። በSO_MARK ላይ የተመሠረተ የዙር መከላከያ ተኪው በራሱ እንደገና ኢንክሪፕት አድርጎ የሚያስተላልፈው ትራፊክ እንደገና እንዳይጠለፍ ይከላከላል።
ይህ የራሱ የተለየ የኦፕሬተር መመሪያ ያለው ሰፊ ንዑስ ስርዓት ነው — ለሙሉ የፋየርዎል አሰራር፣ በየSNI የሚፈጠረው ተለዋዋጭ CA + የtrust-store ጫኝ፣ የአካባቢ ብቻ መስመር፣ የዙር መከላከያ ዝርዝሮች እና የውቅር መርሃግብር `docs/security/MITM-TPROXY-DECRYPT.md`ን ይመልከቱ (git፤ ወደ `/docs` አልተጠናቀረም)። መቀያየሪያው በ`GET / POST / DELETE /api/tools/agent-bridge/tproxy` ይቆጣጠራል (ማስታወሻ፦ መስመሩ በTraffic Inspector ቅድመ ቅጥያ ሳይሆን በAgentBridge ቅድመ ቅጥያ ስር ይገኛል)።
### የቀረጻ ሁነታዎች ንጽጽር
| ሁነታ | ማዋቀር | Sudo? | ተደራሽነት | ማስታወሻዎች |
| ----------------- | ----------------------------- | :--------------------: | --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 1. AgentBridge | ራስ-ሰር | አንድ ጊዜ (cert+hosts) | 9 IDE agents | በነባሪ ክፍት ነው |
| 2. Custom Hosts | ለእያንዳንዱ host ግብዓት | አዎ (hosts file) | ያንን host የሚጠቀም ማንኛውም app | በDB ውስጥ ቋሚ ሆኖ ይቀመጣል |
| 3. HTTP_PROXY | `export HTTPS_PROXY=...` | አይ | envን የሚያከብሩ Apps | Port 8080፣ በነባሪ TLS decrypt የለም |
| 4. System-wide | Toggle + ማረጋገጫ | አዎ | በማሽኑ ላይ ያሉ ሁሉም apps | በ30 ደቂቃ ውስጥ በራስ-ሰር ይሰናከላል |
| 5. TPROXY decrypt | Toggle (Linux + native addon) | አዎ (root + CA install) | በታለመው port ላይ ያለ ማንኛውም host | የተለያዩ hostsን ዲክሪፕት ያደርጋል፤ በነባሪ ዝግ ነው — `docs/security/MITM-TPROXY-DECRYPT.md`ን ይመልከቱ (git፤ ወደ `/docs` አልተጠናቀረም) |
---
## §3 የተጠቃሚ በይነገጽ
### 3.1 አቀማመጥ
```
┌─ የትራፊክ መርማሪ ─────────────────────────────────────────────────────┐
│ ┌─ የቀረጻ ምንጮች መሣሪያ አሞሌ ──────────────────────────────────────┐ │
│ │ [✓ AgentBridge] [✓ ብጁ አስተናጋጆች (3)] [○ HTTP_PROXY] [○ ስርዓት]│ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ┌─ የማጣሪያ/መቆጣጠሪያ አሞሌ ───────────────────────────────────────┐ │
│ │ መገለጫ፦ (●) LLM ብቻ (○) ብጁ (○) ሁሉም │ │
│ │ [⎉ ለአፍታ አቁም] [🗑 አጽዳ] [⬇ .har] [● ክፍለ ጊዜ ቅረጽ] ● ቀጥታ 482/1k│ │
│ └─────────────────────────────────────────────────────────────────────┘ │
├══◀▶══════════════════════════════╬══════════════════════════════════════╤╡
│ የጥያቄዎች ዝርዝር (መጠኑ የሚቀየር) ║ የዝርዝር መቃኛ ▲ │
│ ────────────────────────────── │ ║ [ውይይት][ራስጌዎች][ጥያቄ] │ │
│ ▎ 14:32 POST 200 12k AG openai ║ [ምላሽ][ጊዜ][LLM][ስታቲስቲክስ] │ │
│ ▎ 14:31 POST 200 8k CP openai ║ ▼ │
│ ▎ 14:31 POST 503 ⚠ KR ... ║ │
│ ▎ 14:30 GET 200 3k 🌐 ብጁ ║ │
└══════════════════════════════════╝══════════════════════════════════════╝
```
### 3.2 የጥያቄዎች ዝርዝር (የግራ ፓነል)
- **ቨርቹዋላይዝድ** (`useVirtualList` + `ResizeObserver`)፦ ሳይቀዘቅዝ 1000 ንጥሎችን ይይዛል
- በሚመረመርበት ጊዜ ማቆም የሚያስችል መቀየሪያ ያለው **ራስ-ሰር ማሸብለል**
- **በቀለም ኮድ የተደረገ ሁኔታ**፦ አረንጓዴ (2xx)፣ ቢጫ (3xx)፣ ቀይ (4xx/5xx)፣ ግራጫ (በሂደት ላይ)
- **የኤጀንት ኢሞጂ**፦ 🔵 Antigravity፣ 🟢 Copilot፣ 🟠 Kiro፣ 🟣 Codex፣ 🔷 Cursor፣ 🟤 Zed፣ 🟡 Claude Code፣ ⚫ Open Code፣ 🌐 ብጁ አስተናጋጅ
- **የዐውድ ቀለም አሞሌ**፦ በ`contextKey` (የስርዓት ጥያቄው SHA-256) ቀለም የተሰጠው 1px የግራ ድንበር — ተዛማጅ ውይይቶችን በዓይን እንዲቧደኑ ያደርጋል
- **ሰነፍ የውሂብ አካል**፦ በዝርዝር ትሮች ውስጥ የሚተገበረው የተመረጠው ጥያቄ የውሂብ አካል ብቻ ነው (1000 × 1MB የውሂብ አካላትን ከማቅረብ ይቆጠባል)
### 3.3 የዝርዝር መቃኛ — 7 ትሮች
| ትር | ይዘት | ማስታወሻዎች |
| -------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| **ውይይት** | ባለብዙ-ተራ የውይይት አረፋዎች (system/user/assistant + tool_use/tool_result) | ከማንኛውም የአቅራቢ ቅርጸት ወደ መደበኛ ቅርጽ የተለወጠ፤ የሚታየው `detectedKind === "llm"` ሲሆን ብቻ ነው |
| **ራስጌዎች** | የጥያቄ + የምላሽ ራስጌ ሰንጠረዦች | ስሱ ራስጌዎች (Authorization፣ Cookie፣ api-key) በነባሪነት ይደበቃሉ፤ «ሚስጥሮችን አሳይ» መቀየሪያ |
| **ጥያቄ** | ጥሬ የውሂብ አካል፣ የJSON ዛፍ እይታ፣ የሞዴል መስክ ባጅ | በተዋበ ሁኔታ የታተመ JSON ወይም ጥሬ ጽሑፍ |
| **ምላሽ** | ጥሬ የውሂብ አካል ወይም የSSE ክስተት ዝርዝር፤ «ጥሬ ↔ የተዋሃደ» መቀየሪያ | የSSE አዋሃጅ ከdelta ክስተቶች የመጨረሻውን መልዕክት እንደገና ይገነባል |
| **ጊዜ** | ዋተርፎል፦ የፕሮክሲ ትርፍ ጊዜ ከላይኛው አገልግሎት መዘግየት ጋር | ጠቅላላ፣ TTFB እና መጠን |
| **የLLM ዝርዝሮች** | አቅራቢ፣ ሞዴል፣ የመልዕክቶች ብዛት፣ የገቢ/ወጪ ቶከኖች፣ የወጪ ግምት፣ የተመደበ ዒላማ | ለLLM ጥያቄዎች ብቻ ይታያል |
| **ስታቲስቲክስ** | Recharts፦ የመዘግየት የጊዜ መስመር፣ የቶከን አሞሌ ገበታ፣ የመሣሪያ ጥሪ መበተኛ | የተቀዳ ክፍለ ጊዜ ሲጫን ብቻ ይታያል |
### 3.4 የመሣሪያ አሞሌ መቆጣጠሪያዎች
| መቆጣጠሪያ | ድርጊት |
| ------------ | --------------------------------------------------------------------- |
| ⎉ ለአፍታ አቁም | አዳዲስ ጥያቄዎችን ማቅረብ ያቆማል፤ «X አዲስ» ባጅ እየተጠራቀመ ይሄዳል |
| 🗑 አጽዳ | የተጠቃሚ በይነገጽ ዝርዝሩን ያጸዳል (የሰርቨር ቋት አይነካም) |
| ⬇ .har ላክ | አሁን የተጣራውን ዝርዝር እንደ HAR ፋይል ያወርዳል |
| ● ክፍለ ጊዜ ቅረጽ | ስም የተሰጠው የቀረጻ ክፍለ ጊዜ ይጀምራል |
| የመገለጫ መራጭ | LLM ብቻ / ብጁ አስተናጋጆች / ሁሉም |
| የአስተናጋጅ ማጣሪያ | በ`host` መስክ ላይ የንዑስ ሕብረቁምፊ ማዛመድ |
| የኤጀንት ማጣሪያ | ተቆልቋይ፦ ሁሉም / በየኤጀንቱ |
| የሁኔታ ማጣሪያ | ሁሉም / 2xx / 3xx / 4xx / 5xx / ስህተት |
| የምንጭ ማጣሪያ | ሁሉም / agent-bridge / custom-host / http-proxy / system-proxy / tproxy |
| **ቀጥታ** ማጣሪያ | በሂደት ላይ ያሉ (ክፍት) ጥያቄዎችን ብቻ አሳይ — `liveOnly` መቀየሪያ (§4.6ን ይመልከቱ) |
### 3.5 መጠናቸው የሚቀየር ፓነሎች
- ዝርዝሩ እና የዝርዝር መቃኛው በመጎተቻ መያዣ ተለያይተዋል
- የዝርዝር ስፋት፦ ዝቅተኛው 280px፣ ከፍተኛው 720px፣ በ`localStorage` (`inspector.listWidth`) ውስጥ ይቀመጣል
- ወደ 48px ሀዲድ ማጠፍ ይቻላል (አዶ ብቻ)፤ ለማስፋት በሀዲዱ ውስጥ ያለ ረድፍን ጠቅ ያድርጉ
---
## §4 LLM-ን የሚያውቁ ባህሪያት
### 4.1 ዓይነት መለያ (`src/mitm/inspector/kindDetector.ts`)
እያንዳንዱን ጥያቄ 4 ምልክቶችን በመጠቀም `"llm"`፣ `"app"` ወይም `"unknown"` ብሎ ይመድባል፦
1. **የአስተናጋጅ መዝገብ** — ~18 የሚታወቁ የLLM API አስተናጋጅ ስሞች (OpenAI, Anthropic, Gemini, Groq, Mistral, Together, Fireworks, Cohere, Perplexity, Hugging Face, OpenRouter, xAI, Moonshot, ወዘተ)
2. **የዱካ ንድፎች** — `/v1/chat/completions`፣ `/v1/messages`፣ `/generateContent`፣ `/v1/responses`፣ ወዘተ
3. **የይዘት ቅርጽ** — `messages[]` (OpenAI/Claude)፣ `contents[]` (Gemini)፣ `prompt`፣ `input` መስኮችን ይለያል
4. **የተጠቃሚ-ወኪል ፍንጮች** — በUA ሕብረቁምፊ ውስጥ `codex`፣ `claude`፣ `gemini`፣ `antigravity`፣ `kiro`፣ `copilot`፣ `cursor`
በMode 2 በኩል የታከሉ ብጁ አስተናጋጆች `kind`-ቸውን ከቅጹ ግቤት ይወርሳሉ (ነባሪው `"custom"` ነው)።
### 4.2 SSE አዋሃጅ (`src/mitm/inspector/sseMerger.ts`)
**ራሱን የቻለ ከባዶ የተተገበረ አተገባበር።** የክስተት ትንተናው
[የWHATWG በአገልጋይ የሚላኩ ክስተቶች ስልተ ቀመር](https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream)ን የሚከተል ሲሆን፣
መልሶ መገንባቱ ደግሞ ይፋዊዎቹን [OpenAI](https://platform.openai.com/docs/api-reference/chat/create)፣
[Anthropic](https://platform.claude.com/docs/en/build-with-claude/streaming) እና
[Gemini](https://ai.google.dev/api/generate-content#method:-models.streamgeneratecontent)
የዥረት መርሐግብሮች ይከተላል።
ከጥሬ የSSE ልዩነት ክስተቶች የመጨረሻውን የረዳት መልዕክት መልሶ ይገነባል፦
- **Anthropic**፦ `content_block_delta`ን በማውጫ ያከማቻል፤ `text_delta`፣ `input_json_delta` (የመሣሪያ ጥሪዎች)፣ `thinking_delta`ን ይይዛል
- **OpenAI**፦ የChat Completions ምርጫዎችን/የመሣሪያ ጥሪዎችን እና የResponses API ውጤት ንጥሎችን
በማውጫ ያከማቻል
- **Gemini**፦ `candidates[i].content.parts`ን ያከማቻል
- **ያልታወቀ**፦ ጥሬ ክስተቶችን እንዳሉ ይመልሳል
የResponse ትር መቀያየሪያ ያሳያል፦ **"ጥሬ ክስተቶች ↔ የተዋሃደ"**።
### 4.3 የውይይት መደበኛ አድራጊ (`src/mitm/inspector/conversationNormalizer.ts`)
**ራሱን የቻለ ከባዶ የተተገበረ አተገባበር።** መደበኛ ማድረግ በአካባቢያዊ ጥቁር-ሳጥን
ውሎች እና በይፋዊዎቹ OpenAI፣ Anthropic እና Gemini የመልዕክት መርሐግብሮች ይገለጻል፤ ምንም የላይኛው ምንጭ
የአተገባበር ምንጭ ጥቅም ላይ አልዋለም።
OpenAI፣ Anthropic እና Gemini የመልዕክት ቅርጸቶችን ከማሳየት በፊት ወደ አንድ `NormalizedConversation` ይቀይራል፦
```ts
interface NormalizedConversation {
request: NormalizedTurn[]; // ከጥያቄው አካል የሚመጡ messages / contents / prompt
response: NormalizedTurn[]; // የረዳት ምላሽ (በsseMerger የተዋሃደ)
contextKey: string | null; // የSHA-256 የስርዓት-prompt አሻራ
}
```
የብሎክ ዓይነቶች፦ `text`፣ `tool_use`፣ `tool_result`። የConversation ትር አቅራቢው ማንም ቢሆን ይህን ቅርጽ ይጠቀማል።
### 4.4 የአውድ ቁልፍ ቀለም መስጠት (`src/mitm/inspector/contextKey.ts`)
- የስርዓት prompt-ን `SHA-256` ያሰላል (የመጀመሪያው `role:system` መልዕክት፣ ወይም `system` መስክ፣ ወይም የGemini `systemInstruction`)
- ባለ12-ቁምፊ ሄክስ ቅድመ ቅጥያ ይመልሳል (`"a3f9c2..."`)
- የፊት ገጽ ቁልፉን ለግራ-ድንበር አሞሌው ወደ የተወሰነ HSL ቀለም ይዛመዳል
- **የ"ተመሳሳይ አውድ" ማጣሪያ**፦ `ctx #a3f` ቺፕን ጠቅ ማድረግ ተመሳሳይ አሻራ ያላቸውን ጥያቄዎች ብቻ ለማሳየት ማጣሪያ ያክላል
ይህም በአንድ የወኪል ክፍለ ጊዜ ውስጥ የሚሰሩ የተለያዩ "ስብዕናዎች" ወይም ተግባራትን በእይታ መለየት ቀላል ያደርገዋል።
### 4.5 የLLM ሜታዳታ ማውጣት
ለLLM ጥያቄዎች፣ የLLM Details ትር የሚከተሉትን ያወጣል፦
```ts
interface LlmMetadata {
provider: string | null; // "openai" | "anthropic" | "gemini" | ...
apiKind: string | null; // "chat.completions" | "messages" | "embeddings" | ...
model: string | null; // ከጥያቄው አካል ወይም ከምላሹ
messages: number; // የዙር ብዛት
tokensIn: number | null; // usage.prompt_tokens / usage.input_tokens
tokensOut: number | null; // usage.completion_tokens / usage.output_tokens
streamed: boolean; // ምላሹ SSE ከሆነ true
mappedTo: string | null; // x-omniroute-mapped ራስጌ
costEstimateUsd: number | null; // በOmniRoute ዋጋ አወጣጥ ላይ የተመሠረተ የተገመተ ወጪ
}
```
### 4.6 በሂደት ላይ ያሉ ጥያቄዎች የቀጥታ ማጣሪያ
የጥያቄው `status` መስክ `number | "in-flight" | "error"` ነው — ጥያቄው እንደጀመረ ግቤቱ
እንደ `"in-flight"` ይገፋል፣ እና ምላሹ (ወይም ስህተቱ) ሲደርስ **ባለበት ይዘምናል**። የመሣሪያ አሞሌው **"ቀጥታ"** መቀያየሪያ
(`liveOnly`፣ i18n ቁልፍ `trafficInspector.liveOnly`) ዝርዝሩን
`status === "in-flight"` ወደሆኑ ግቤቶች ይገድባል፣ ይህም ክፍት ግንኙነቶችን በቅጽበት እንዲመለከቱ ያስችልዎታል።
ማጣሪያው በ
`src/lib/inspector/matchesTrafficFilter.ts` ውስጥ ያለ ንጹህ፣ በደንበኛ-ጎን የሚሰራ ማጣሪያ ነው፦
```ts
if (f.liveOnly && req.status !== "in-flight") return false;
```
የመቀያየሪያው ሁኔታ በ`useTrafficFilters` (የመርማሪው ዳሽቦርድ hooks) ውስጥ ይኖራል፣ እና
ከሌሎቹ ማጣሪያዎች (መገለጫ፣ አስተናጋጅ፣ ወኪል፣ ምንጭ፣ ሁኔታ፣ አውድ) ጋር ይጣመራል።
### 4.7 የሂደት ባለቤትነት መለየት (Linux)
በLinux ላይ፣ እያንዳንዱ የተጠለፈ ጥያቄ **ጥያቄውን ከጀመረው አካባቢያዊ
ሂደት** ጋር ሊያያዝ ይችላል። ሁለት አማራጭ መስኮች ወደ `InterceptedRequest` ታክለዋል፦
```ts
pid?: number; // የጀመረው ሂደት መለያ (በLinux ላይ ብቻ)
processName?: string; // የጀመረው ሂደት ስም (በLinux ላይ ብቻ)
```
`src/mitm/inspector/processAttribution.ts` የግንኙነቱን _የደንበኛ_
ጊዜያዊ ወደብ ከPID + ስም ጋር በሚከተለው መንገድ ያዛምዳል፦
1. ለወደቡ የsocket inode-ን ለማግኘት `/proc/net/tcp` እና `/proc/net/tcp6`ን ያነባል
(`parseProcNetTcpForInode`፣ በfixture ሊሞከር የሚችል ንጹህ parser)።
2. ወደ `socket:[<inode>]` የሚያመለክት symlink ለማግኘት `/proc/<pid>/fd/`ን ይቃኛል።
3. የሂደቱን ስም ከ`/proc/<pid>/comm` ያነባል።
የ1 ሰከንድ TTL መሸጎጫ በጭነት ጊዜ የprocfs ቅኝት ወጪን ይገድባል። ባለቤትነት መለየቱ
**በተቻለ መጠን** የሚከናወን ነው — ማንኛውም ውድቀት ወደ `null` ይፈታል እና ቀረጻውን ፈጽሞ አያግድም። በ
macOS/Windows ላይ ፋንክሽኑ `null` ይመልሳል (stub፤ የ`lsof`/`GetExtendedTcpTable`
ድጋፍ ቀጣይ ሥራ ነው)።
---
## §5 ክፍለ-ጊዜዎች
### 5.1 ክፍለ-ጊዜ መቅዳት
1. በመሣሪያ አሞሌው ላይ **"● ክፍለ-ጊዜ ቅዳ"** የሚለውን ጠቅ ያድርጉ → ስም ያስገቡ (አማራጭ)
2. የቀጥታ ውሂብ ፍሰቱ እንደተለመደው ይቀጥላል፤ ቀይ ብልጭ ድርግም የሚል አመልካች `◉ REC · <name> · 00:42 · 23 ጥያቄዎች` ያሳያል
3. **"⏹ አቁም"** የሚለውን ጠቅ ያድርጉ → የክፍለ-ጊዜው ቅጽበታዊ ቅጂ ወደ `inspector_sessions` + `inspector_session_requests` ይቀመጣል
### 5.2 የተቀዳ ክፍለ-ጊዜን መመልከት
በመሣሪያ አሞሌው ውስጥ ያለው የ**ክፍለ-ጊዜዎች** ተቆልቋይ ዝርዝር የተቀመጡ ክፍለ-ጊዜዎችን ያሳያል። አንዱን ሲመርጡ፦
- የክፍለ-ጊዜውን ቅጽበታዊ ቅጂ (የታሰረ ሁኔታ) ይጭናል
- አንድ ሰንደቅ ይህን ያሳያል፦ `የተቀዳው ክፍለ-ጊዜ "<name>" እየታየ ነው — [ወደ ቀጥታ ተመለስ]`
- የስታቲስቲክስ ትር ከRecharts ድምር ስታቲስቲክስ ጋር ዝግጁ ይሆናል
### 5.3 የወጪ ቅርጸቶች
እያንዳንዱ ክፍለ-ጊዜ በሚከተሉት ቅርጸቶች ወደ ውጭ ሊላክ ይችላል፦
| ቅርጸት | አጠቃቀም |
| -------------------------- | -------------------------------------------------------------------------- |
| **HAR** (HTTP Archive 1.2) | ከChrome DevTools፣ Charles እና Fiddler ጋር ተኳዃኝ ነው — ከመስመር ውጭ ለመተንተን ያስመጡት |
| **JSONL** | በእያንዳንዱ መስመር አንድ `InterceptedRequest` — ከ`llm-interceptor` ቅርጸት ጋር ተኳዃኝ ነው |
በ`GET /api/tools/traffic-inspector/sessions/{id}/export.har` ወይም በክፍለ-ጊዜዎች ተቆልቋይ ዝርዝር ውስጥ ባለው ⬇ አዝራር በኩል ወደ ውጭ ይላኩ።
---
## §6 ደህንነት
የትራፊክ መርማሪው የፈቃድ ማረጋገጫ ራስጌዎችን እና የጥያቄ ይዘቶችን ጨምሮ **ሁሉንም የተጠለፈ HTTPS ትራፊክ** ያሳያል። የሚከተሉት ቁጥጥሮች ተተግብረዋል፦
| ቁጥጥር | ዝርዝሮች |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **LOCAL_ONLY** | ሁሉም መንገዶች እና የWebSocket መዳረሻ በloopback ብቻ የተገደቡ ናቸው (ከማረጋገጫ በፊት በ`routeGuard.ts` ውስጥ ተፈጻሚ ይደረጋል) |
| **የምስጢር መደበቂያ** | መስመራዊው `maskSecret()` ቃኚ ከ`TrafficBuffer.push()` በፊት የRFC 6750 Bearer ማረጋገጫዎችን፣ በአቅራቢ ቅድመ-ቅጥያ የተጀመሩ ቁልፎችን እና ረጅም ግልጽ ያልሆኑ ቶከኖችን ይሰውራል |
| **የይዘት መጠን ገደብ** | ከ`INSPECTOR_MAX_BODY_KB` (ነባሪ 1024 KB) በላይ የሆኑ ይዘቶች `"(ለአፈጻጸም ሲባል አጥሯል)"` ከሚል ማስታወቂያ ጋር ይቆረጣሉ |
| **የራስጌ ማጽዳት** | ስሞች ወደ ትንሽ ፊደል ይቀየራሉ፤ የፍሬም/hop-by-hop እና የproxy-auth ራስጌዎች ይወገዳሉ፤ ኩኪዎች ሙሉ በሙሉ ይሰወራሉ፤ የማረጋገጫ ዋጋዎች ወደ `maskSecret()` ይላካሉ |
| **CSP** | በተጨመሩ የምላሽ ይዘቶች በኩል XSS እንዳይከሰት በትራፊክ መርማሪ ገጾች ላይ ጥብቅ የይዘት ደህንነት ፖሊሲ ተተግብሯል |
| **በነባሪነት ቋሚ ማከማቻ የለም** | `TrafficBuffer` በማህደረ ትውስታ ውስጥ ብቻ የሚኖር ሲሆን አገልጋዩ ዳግም ሲጀምር ይጠፋል። ክፍለ-ጊዜዎች የሚቀመጡት በግልጽ ሲቀዱ ብቻ ነው |
### ተፈጻሚ የተደረጉ ጥብቅ ደንቦች
| ደንብ | አተገባበር |
| --------------------------------- | --------------------------------------------------------------------------------- |
| **#12** `sanitizeErrorMessage` | ከትራፊክ መርማሪ መንገዶች የሚመጡ ሁሉም የHTTP ስህተት ምላሾች ይጸዳሉ |
| **#15 + #17** `isLocalOnlyPath()` | `/api/tools/traffic-inspector/` LOCAL_ONLY + SPAWN_CAPABLE (የስርዓት proxy ትዕዛዞች) ነው |
### የታወቁ ገደቦች
- **በመላው ስርዓት የሚሠራ የproxy ሁነታ** VPN ደንበኞችን እና SSOን ጨምሮ በማሽኑ ላይ ያሉትን ሁሉንም መተግበሪያዎች ይነካል። ሁልጊዜ ከራስ-ሰር ማሰናከያ ቆጣሪው ጋር ይጠቀሙበት። በጋራ በሚጠቀሙባቸው ማሽኖች ላይ አይጠቀሙበት።
- **CONNECT tunnel HTTPS**፦ Mode 3 (HTTP_PROXY) የTLS ጠለፋ ካልነቃ በስተቀር ለHTTPS መዳረሻዎች የዋሻውን ሜታዳታ ብቻ ይይዛል። ይህ ሆን ተብሎ የተደረገ ነው — የAgentBridge ሰርተፍኬት ታማኝ ሆኖ ሳይወሰድ ግልጽ የትራፊክ ቀረጻ ማድረግ ለእነዚያ መተግበሪያዎች የTLS ማረጋገጫን ያበላሻል።
- **በአንዳንድ ክፍሎች ውስጥ በቀጥታ የተጻፉ ሕብረቁምፊዎች**፦ አንዳንድ የUI ክፍሎች (F7/F8) እስካሁን በi18n ቁልፎች ያልተሸፈኑ ጥቂት በቀጥታ የተጻፉ ሕብረቁምፊዎች አሏቸው። እነዚህ በi18n ክፍተት ሪፖርቱ ውስጥ እንደ የታወቀ ገደብ ተመዝግበዋል፤ በቀጣይ የማሻሻያ ዙር ይዛወራሉ። የተጎዱት ሕብረቁምፊዎች ለተግባራዊ አጠቃቀም ትርጉም የማያስፈልጋቸው የUI ማስዋቢያ መለያዎች ናቸው።
---
## §7 ችግር መፍታት
### WebSocket ግንኙነት መቋረጥ
የቀጥታ ፍሰቱ "ግንኙነት ተቋርጧል" የሚል ካሳየ፦
1. አገልጋዩ አሁንም እየሰራ መሆኑን ያረጋግጡ፦ `GET /api/tools/traffic-inspector/capture-modes`
2. ገጹን እንደገና ይጫኑ — WebSocket እንደገና ይገናኛል እና አዲስ ቅጽበታዊ ቅጂ ይቀበላል
3. አገልጋዩ እንደገና ከተጀመረ፣ በማህደረ ትውስታ ያለው ቋት ተጽድቷል — ክፍለ ጊዜ ተመዝግቦ ካልነበረ በስተቀር የቆዩ ግቤቶች ጠፍተዋል
### የፖርት 8080 ግጭት
የHTTP_PROXY ሁነታ መጀመር ካልቻለ፦
```bash
lsof -i :8080 # ሂደቱን ያግኙ
```
ፖርቱን ይቀይሩ፦
```bash
# .env
INSPECTOR_HTTP_PROXY_PORT=8888
```
### የስርዓት ፕሮክሲ ወደ ቀድሞው አለመመለስ
OmniRoute የስርዓት-አቀፍ ፕሮክሲ ሁነታ ንቁ በሆነበት ጊዜ ከተበላሸ፦
**macOS፦**
```bash
networksetup -setwebproxystate Wi-Fi off
networksetup -setsecurewebproxystate Wi-Fi off
```
**Linux (GNOME)፦**
```bash
gsettings set org.gnome.system.proxy mode 'none'
```
**Windows፦**
```cmd
netsh winhttp reset proxy
```
ዳሽቦርዱ የDB ሁኔታው ፕሮክሲው ንቁ እንደነበር እንደሚያመለክት ካወቀ፣ በሚቀጥለው ጭነት ላይ "የስርዓት ፕሮክሲን ወደ ቀድሞው መልስ" የሚል አማራጭም ያቀርባል።
### ቋቱ ሙሉ ነው
ቋቱ `INSPECTOR_BUFFER_SIZE` ላይ ሲደርስ (ነባሪው 1000)፣ አዲስ ግቤቶች በጣም የቆዩትን ያስወጣሉ። አስፈላጊ ጥያቄዎች እየጠፉ ከሆነ፦
- `INSPECTOR_BUFFER_SIZE`ን ይጨምሩ (ለምሳሌ፣ 5000) — ይህ የማህደረ ትውስታ አጠቃቀምን በመጨመር የማቆያ ጊዜን ያራዝማል
- ተዛማጅ የጊዜ መስኮቱን በDB ውስጥ ለማቆየት ክፍለ ጊዜ ይቅዱ
---
## §8 የAPI ማጣቀሻ
ሁሉም መንገዶች `LOCAL_ONLY` (ለloopback ብቻ) እና `SPAWN_CAPABLE` (የስርዓት ፕሮክሲ ትዕዛዞች) ናቸው። `src/server/authz/routeGuard.ts`ን ይመልከቱ።
መሠረታዊ ዱካ፦ `/api/tools/traffic-inspector/`
### የጥያቄ አስተዳደር
| ዘዴ | ዱካ | መግለጫ |
| ------ | --------------------------- | ------------------------------------------------------------------------------- |
| GET | `/requests` | ጥያቄዎችን ይዘርዝሩ (ሊጣሩ የሚችሉ፦ `?profile=llm&host=&agent=&status=&source=&sessionId=`) |
| GET | `/requests/{id}` | የአንድ ጥያቄ ዝርዝሮች |
| DELETE | `/requests` | በማህደረ ትውስታ ያለውን ቋት ያጽዱ |
| POST | `/requests/{id}/replay` | ተመሳሳዩን ጥያቄ በOmniRoute ራውተር በኩል እንደገና ያስፈጽሙ |
| PUT | `/requests/{id}/annotation` | በጥያቄ ላይ ማስታወሻ ያስቀምጡ ወይም ያዘምኑ |
### WebSocket
| ዘዴ | ዱካ | መግለጫ |
| --- | ----- | ---------------------------------------------------------------------------- |
| GET | `/ws` | የቀጥታ WebSocket ፍሰት። ሲገናኝ `snapshot`ን፣ ከዚያ `new`/`update`/`clear` ክስተቶችን ይልካል |
### ወደ ውጭ መላክ
| ዘዴ | ዱካ | መግለጫ |
| --- | ------------- | ------------------------------------- |
| GET | `/export.har` | አሁን የተጣራውን ዝርዝር እንደ HAR 1.2 ወደ ውጭ ይላኩ |
### ብጁ አስተናጋጆች
| ዘዴ | ዱካ | መግለጫ |
| ------ | --------------- | -------------------------------------- |
| GET | `/hosts` | ብጁ አስተናጋጆችን ይዘርዝሩ |
| POST | `/hosts` | አስተናጋጅ ያክሉ (`/etc/hosts`ን በራስ-ሰር ያርታዕ) |
| DELETE | `/hosts/{host}` | አስተናጋጅ ያስወግዱ |
| PATCH | `/hosts/{host}` | `enabled`ን ያብሩ ወይም ያጥፉ |
### የመያዣ ሁነታዎች
| ዘዴ | ዱካ | መግለጫ |
| ---- | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| GET | `/capture-modes` | የAgentBridge / custom-hosts / HTTP_PROXY / system-proxy ሁነታዎች ሁኔታ + የ`tls-intercept` ማብሪያ/ማጥፊያ |
| POST | `/capture-modes/http-proxy` | የHTTP_PROXY አዳማጭን ያስጀምሩ/ያቁሙ (`{action: "start"\|"stop"}`) |
| POST | `/capture-modes/system-proxy` | የስርዓት-አቀፍ ፕሮክሲን ይተግብሩ/ወደ ቀድሞው ይመልሱ (`{action: "apply"\|"revert"}`) |
| POST | `/capture-modes/tls-intercept` | በፕሮክሲ ሁነታ የHTTPS ይዘት ዲክሪፕሽንን ያብሩ ወይም ያጥፉ (`{enabled: boolean}`) |
> **TPROXY ዲክሪፕት** (የመያዣ ሁነታ 5) በAgentBridge ቅድመ ቅጥያ ስር ባለ **የተለየ** መንገድ ይንቀሳቀሳል —
> `GET / POST / DELETE /api/tools/agent-bridge/tproxy` — በ
> `/api/tools/traffic-inspector/` ስር አይደለም።
> `docs/security/MITM-TPROXY-DECRYPT.md`ን ይመልከቱ (git፤ ወደ `/docs` አልተጠናቀረም)።
### ክፍለ ጊዜዎች
| ዘዴ | ዱካ | መግለጫ |
| ------ | --------------------------- | ---------------------------------------------------------------- |
| POST | `/sessions` | መቅዳት ይጀምሩ (`{name?: string}`) |
| PATCH | `/sessions/{id}` | ያቁሙ ወይም እንደገና ይሰይሙ (`{action: "stop"\|"rename", name?: string}`) |
| GET | `/sessions` | ሁሉንም የተቀመጡ ክፍለ ጊዜዎች ይዘርዝሩ |
| GET | `/sessions/{id}` | የክፍለ ጊዜ ቅጽበታዊ ቅጂ (ሁሉም ጥያቄዎች) |
| DELETE | `/sessions/{id}` | ክፍለ ጊዜን ይሰርዙ |
| GET | `/sessions/{id}/export.har` | ክፍለ ጊዜውን እንደ HAR 1.2 ወደ ውጭ ይላኩ |
### ውስጣዊ ማስገቢያ (D4 መጠባበቂያ)
| ዘዴ | ዱካ | መግለጫ |
| ---- | ------------------ | -------------------------------------------------------------------------------------------- |
| POST | `/internal/ingest` | ከ`server.cjs` passthrough ዱካ የተጠለፈ ጥያቄን ይቀበላል፤ የ`INSPECTOR_INTERNAL_INGEST_TOKEN` ራስጌ ያስፈልጋል |
ሙሉ የOpenAPI ንድፎች፦ `docs/openapi.yaml` → መለያ `Traffic Inspector`።

230
docs/i18n/am/docs/frameworks/WEBHOOKS.md Normal file
View File

@@ -0,0 +1,230 @@
# Webhooks (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../frameworks/WEBHOOKS.md) · 🇸🇦 [ar](../../../ar/docs/frameworks/WEBHOOKS.md) · 🇦🇿 [az](../../../az/docs/frameworks/WEBHOOKS.md) · 🇧🇬 [bg](../../../bg/docs/frameworks/WEBHOOKS.md) · 🇧🇩 [bn](../../../bn/docs/frameworks/WEBHOOKS.md) · 🇨🇿 [cs](../../../cs/docs/frameworks/WEBHOOKS.md) · 🇩🇰 [da](../../../da/docs/frameworks/WEBHOOKS.md) · 🇩🇪 [de](../../../de/docs/frameworks/WEBHOOKS.md) · 🇬🇷 [el](../../../el/docs/frameworks/WEBHOOKS.md) · 🇪🇸 [es](../../../es/docs/frameworks/WEBHOOKS.md) · 🇪🇪 [et](../../../et/docs/frameworks/WEBHOOKS.md) · 🇮🇷 [fa](../../../fa/docs/frameworks/WEBHOOKS.md) · 🇫🇮 [fi](../../../fi/docs/frameworks/WEBHOOKS.md) · 🇫🇷 [fr](../../../fr/docs/frameworks/WEBHOOKS.md) · 🇮🇪 [ga](../../../ga/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [gu](../../../gu/docs/frameworks/WEBHOOKS.md) · 🇳🇬 [ha](../../../ha/docs/frameworks/WEBHOOKS.md) · 🇮🇱 [he](../../../he/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [hi](../../../hi/docs/frameworks/WEBHOOKS.md) · 🇭🇷 [hr](../../../hr/docs/frameworks/WEBHOOKS.md) · 🇭🇺 [hu](../../../hu/docs/frameworks/WEBHOOKS.md) · 🇦🇲 [hy](../../../hy/docs/frameworks/WEBHOOKS.md) · 🇮🇩 [id](../../../id/docs/frameworks/WEBHOOKS.md) · 🇳🇬 [ig](../../../ig/docs/frameworks/WEBHOOKS.md) · 🇮🇹 [it](../../../it/docs/frameworks/WEBHOOKS.md) · 🇯🇵 [ja](../../../ja/docs/frameworks/WEBHOOKS.md) · 🇬🇪 [ka](../../../ka/docs/frameworks/WEBHOOKS.md) · 🇰🇭 [km](../../../km/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [kn](../../../kn/docs/frameworks/WEBHOOKS.md) · 🇰🇷 [ko](../../../ko/docs/frameworks/WEBHOOKS.md) · 🇱🇹 [lt](../../../lt/docs/frameworks/WEBHOOKS.md) · 🇱🇻 [lv](../../../lv/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [ml](../../../ml/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [mr](../../../mr/docs/frameworks/WEBHOOKS.md) · 🇲🇾 [ms](../../../ms/docs/frameworks/WEBHOOKS.md) · 🇲🇹 [mt](../../../mt/docs/frameworks/WEBHOOKS.md) · 🇲🇲 [my](../../../my/docs/frameworks/WEBHOOKS.md) · 🇳🇵 [ne](../../../ne/docs/frameworks/WEBHOOKS.md) · 🇳🇱 [nl](../../../nl/docs/frameworks/WEBHOOKS.md) · 🇳🇴 [no](../../../no/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [or](../../../or/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [pa](../../../pa/docs/frameworks/WEBHOOKS.md) · 🇵🇭 [phi](../../../phi/docs/frameworks/WEBHOOKS.md) · 🇵🇱 [pl](../../../pl/docs/frameworks/WEBHOOKS.md) · 🇵🇹 [pt](../../../pt/docs/frameworks/WEBHOOKS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/frameworks/WEBHOOKS.md) · 🇷🇴 [ro](../../../ro/docs/frameworks/WEBHOOKS.md) · 🇷🇺 [ru](../../../ru/docs/frameworks/WEBHOOKS.md) · 🇱🇰 [si](../../../si/docs/frameworks/WEBHOOKS.md) · 🇸🇰 [sk](../../../sk/docs/frameworks/WEBHOOKS.md) · 🇸🇮 [sl](../../../sl/docs/frameworks/WEBHOOKS.md) · 🇷🇸 [sr](../../../sr/docs/frameworks/WEBHOOKS.md) · 🇸🇪 [sv](../../../sv/docs/frameworks/WEBHOOKS.md) · 🇰🇪 [sw](../../../sw/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [ta](../../../ta/docs/frameworks/WEBHOOKS.md) · 🇮🇳 [te](../../../te/docs/frameworks/WEBHOOKS.md) · 🇹🇭 [th](../../../th/docs/frameworks/WEBHOOKS.md) · 🇹🇷 [tr](../../../tr/docs/frameworks/WEBHOOKS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/frameworks/WEBHOOKS.md) · 🇵🇰 [ur](../../../ur/docs/frameworks/WEBHOOKS.md) · 🇺🇿 [uz](../../../uz/docs/frameworks/WEBHOOKS.md) · 🇻🇳 [vi](../../../vi/docs/frameworks/WEBHOOKS.md) · 🇳🇬 [yo](../../../yo/docs/frameworks/WEBHOOKS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/frameworks/WEBHOOKS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/frameworks/WEBHOOKS.md)
---
> **የእውነት ምንጭ:** `src/lib/webhookDispatcher.ts`, `src/lib/db/webhooks.ts`, `src/app/api/webhooks/`
> **መጨረሻ የተዘመነው:** 2026-06-28 — v3.8.40
OmniRoute በመድረክ ክስተቶች ጊዜ HTTP webhooks ሊያስነሳ ይችላል። ከ
Slack፣ PagerDuty፣ Datadog፣ ውስጣዊ የማንቂያ አገልግሎቶች ወይም ከማንኛውም HTTP ተቀባይ ጋር ለማዋሃድ ይጠቀሙባቸው።
አሰራጩ እያንዳንዱን ርክክብ በHMAC-SHA256 ይፈርማል፣ ጊዜያዊ
ውድቀቶች ሲከሰቱ እንደገና ይሞክራል፣ ለእያንዳንዱ webhook የርክክብ ጤንነትን ይከታተላል፣ እና በተደጋጋሚ
የሚወድቁ endpointsን በራስ-ሰር ያሰናክላል።
## የሚደገፉ ክስተቶች
የ`WebhookEvent` ዓይነት (`src/lib/webhooks/eventDescriptions.ts`፣ በ`src/lib/webhookDispatcher.ts` ጥቅም ላይ የሚውል) በአሁኑ ጊዜ በትክክል አራት ክስተቶችን ይወክላል፦
| ክስተት | የሚነሳበት ጊዜ |
| ------------------- | ------------------------------------------------- |
| `request.completed` | በproxy የተላለፈ ጥያቄ በተሳካ ሁኔታ ሲጠናቀቅ |
| `request.failed` | በproxy የተላለፈ ጥያቄ ከሁሉም ድጋሚ ሙከራዎች/fallback በኋላ ሲወድቅ |
| `quota.exceeded` | አንድ API key የበጀት/quota ገደብን ሲያልፍ |
| `test.ping` | በሙከራ endpoint ጥቅም ላይ የሚውል ሰው ሰራሽ ክስተት |
ምዝገባዎች እያንዳንዱን ክስተት ለመቀበል ቀጥተኛውን `"*"` ይቀበላሉ። በ
`events` ውስጥ ያሉ ያልታወቁ የክስተት ስሞች በስርጭት ጊዜ ችላ ይባላሉ።
> ማስታወሻ፦ የአሰራጩ API ተገናኝቷል፣ ነገር ግን ለአንዳንድ
> `test.ping` ያልሆኑ ክስተቶች የምርት ጥሪ ቦታዎች አሁንም በመጨመር ላይ ናቸው። በርስዎ ልቀት ውስጥ
> የትኞቹ መንገዶች አሰራጩን እንደሚጠሩ ለማየት `grep dispatchEvent`ን ይፈትሹ።
## አርክቴክቸር
```
ጠሪ (handler፣ service፣ monitor)
dispatchEvent(event, data) [src/lib/webhookDispatcher.ts]
-> getEnabledWebhooks() [src/lib/db/webhooks.ts]
-> በwebhook.events አጣራ
-> ለእያንዳንዱ ተዛማጅ (በትይዩ):
deliverWebhook(url, payload, secret)
payloadን ገንባ { event, timestamp, data }
bodyን በHMAC-SHA256 ፈርም (secret ካለ)
በ10s timeout POST አድርግ
በ5xx / network error ላይ እስከ 3 ጊዜ ድጋሚ ሞክር
recordWebhookDelivery(id, status, success)
-> disableWebhooksWithHighFailures(10)
```
ስርጭቱ ለጠሪው አስነስቶ-የሚረሳ ነው፦ `Promise.allSettled`
በእያንዳንዱ webhook ላይ የሚከሰቱ ስህተቶችን ስለሚያልፍ፣ አንድ መጥፎ ተቀባይ ሌሎቹን ማገድ አይችልም።
## HMAC ፊርማ
አንድ webhook `secret` ሲኖረው፣ OmniRoute የJSON bodyውን ፈርሞ የሚከተለውን ይልካል፦
```
Content-Type: application/json
User-Agent: OmniRoute-Webhook/1.0
X-Webhook-Event: <event>
X-Webhook-Timestamp: <ISO-8601>
X-Webhook-Signature: sha256=<hex HMAC-SHA256(secret, body)>
```
> የheader ስሞች የ`X-Webhook-*` ቅድመ ቅጥያን ይጠቀማሉ (`X-OmniRoute-*` አይደለም)። የፊርማው
> እሴት `sha256=<hex>` ነው — ሙሉውን ቅድመ ቅጥያ ያረጋግጡ።
`createWebhook` ያለ secret ከተጠራ፣ የDB ሞጁሉ አንድ ያመነጫል
(`whsec_<48 hex>`)፣ ስለዚህ ሁሉም webhooks በነባሪነት የተፈረሙ ናቸው።
### በተቀባዩ ላይ ማረጋገጥ
```typescript
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody: string, signature: string, secret: string) {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && timingSafeEqual(a, b);
}
```
ማንኛውም የJSON ትንተና ከመደረጉ በፊት ሁልጊዜ **ጥሬውን** የጥያቄ body በመጠቀም ያረጋግጡ።
## የድጋሚ ሙከራ እና የውድቀት ፖሊሲ
`deliverWebhook(url, payload, secret, maxRetries = 3)`:
- ለእያንዳንዱ ሙከራ የ10 ሰከንድ የጊዜ ገደብ (`AbortController`)።
- HTTP 2xx እንደ ስኬት ይቆጠራል።
- HTTP 3xx/4xx ዳግም ሊሞከር የማይችል የመጨረሻ ሁኔታ ሆኖ ይቆጠራል — እንደተላከ ይመዘገባል፣
`success = res.ok` ይሆናል።
- HTTP 5xx እና የአውታረ መረብ ስህተቶች በጨምሮ በሚሄድ የመጠበቂያ ጊዜ ዳግም ይሞከራሉ፦
`2^attempt * 1000 ms` (1s, 2s, 4s)።
- ከ`maxRetries` በኋላ ማድረሱ እንደወደቀ ይመዘገባል።
- እያንዳንዱ ማድረስ `last_triggered_at`ን፣ `last_status`ን ያዘምናል፤ እንዲሁም
`failure_count`ን ዳግም ወደ ዜሮ ይመልሳል ወይም ይጨምራል።
- አሰራጩ ከእያንዳንዱ ሰፊ ስርጭት በኋላ `disableWebhooksWithHighFailures(10)`ን ይጠራል፤
ስለዚህ `failure_count >= 10` ያለው ማንኛውም webhook በራስ-ሰር ይሰናከላል።
## የውሂብ ጎታ
ሰንጠረዥ `webhooks` (ማዛወሪያ `011_webhooks.sql`)፦
| ዓምድ | ዓይነት | ማስታወሻዎች |
| ------------------- | ------- | ---------------------------------- |
| `id` | TEXT PK | UUID |
| `url` | TEXT | የመድረሻ URL |
| `events` | TEXT | JSON ድርድር፤ ነባሪው `["*"]` |
| `secret` | TEXT | HMAC ሚስጥር (ካልተሰጠ በራስ-ሰር የሚፈጠር) |
| `enabled` | INT | 0/1፤ ነባሪው 1 |
| `description` | TEXT | አማራጭ በሰው የሚነበብ መለያ |
| `created_at` | TEXT | `datetime('now')` |
| `last_triggered_at` | TEXT | በእያንዳንዱ የማድረስ ሙከራ ላይ ይዘምናል |
| `last_status` | INT | የመጨረሻው ሙከራ HTTP ሁኔታ (0 = አውታረ መረብ) |
| `failure_count` | INT | ሲሳካ ወደ 0 ይመለሳል፣ ሲወድቅ +1 ይጨምራል |
የማድረስ ታሪክ በተለየው `webhook_deliveries` ሰንጠረዥ ውስጥ ይቀመጣል
(ማዛወሪያ `069_webhook_deliveries.sql`፣ በእያንዳንዱ ሙከራ
`src/lib/db/webhookDeliveries.ts::insertDelivery` በኩል የሚጻፍ)፤ ይህም
በ`webhooks` ረድፍ ላይ ካሉት ድምር ቆጣሪዎች በተጨማሪ ነው። የዓይነት ሜታዳታ (Slack / Discord /
Telegram / ብጁ የpayload ቀያሪዎች) በ`070_webhooks_kind_metadata.sql` ታክሏል።
## REST API
ሁሉም endpoints የአስተዳደር ማረጋገጫ (`requireManagementAuth`) ይፈልጋሉ።
| Endpoint | ዘዴ | መግለጫ |
| ------------------------------- | ------ | -------------------------------- |
| `/api/webhooks` | GET | webhooksን ዘርዝር (ሚስጥሮች የተሸፈኑ) |
| `/api/webhooks` | POST | webhook ፍጠር |
| `/api/webhooks/[id]` | GET | የwebhook ዝርዝር መረጃ (ሙሉ ሚስጥር) |
| `/api/webhooks/[id]` | PUT | መስኮችን አዘምን |
| `/api/webhooks/[id]` | DELETE | አስወግድ |
| `/api/webhooks/[id]/test` | POST | `test.ping`ን ላክ (ያለ ድጋሚ ሙከራዎች) |
| `/api/webhooks/[id]/deliveries` | GET | ለአንድ webhook የቅርብ ጊዜ የማድረስ ሙከራዎች |
| `/api/webhooks/validate-url` | POST | ቅድመ-በረራ URL ማረጋገጫ (የSSRF መከላከያ) |
`GET /api/webhooks` በዝርዝር ገጾች ላይ ሚስጥሩ እንዳይጋለጥ ወደ `<የመጀመሪያዎቹ 10 ቁምፊዎች>...` ይሸፍነዋል።
ሚስጥሩን በእርግጥ ሲያስፈልግዎ የ`[id]` GETን ይጠቀሙ።
### webhook መፍጠር
```bash
curl -X POST http://localhost:20128/api/webhooks \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.slack.com/services/...",
"secret": "whsec_my_shared_secret",
"events": ["quota.exceeded", "request.failed"],
"description": "Slack alerts"
}'
```
`secret` ከተተወ፣ አገልጋዩ `whsec_<hex>` ሚስጥር ያመነጫል እና በምላሹ
ውስጥ ይመልሰዋል።
### webhookን መሞከር
```bash
curl -X POST http://localhost:20128/api/webhooks/<id>/test \
-H "Cookie: auth_token=..."
```
`{ delivered, status, error }`ን ይመልሳል። ምንም ድጋሚ ሙከራዎች አይደረጉም — ተቀባዩ payloadን እና ፊርማውን መቀበሉን
በፍጥነት ለማረጋገጥ ጠቃሚ ነው።
## ዳሽቦርድ
በ `/dashboard/webhooks` የሚገኘው የዳሽቦርድ ገጽ (`src/app/(dashboard)/dashboard/webhooks/page.tsx` ይመልከቱ) የሚከተሉትን ያቀርባል፦
- የክስተት መራጭ በመጠቀም webhooks መፍጠር/ማርትዕ
- በ `enabled`፣ `failure_count` እና `last_status` ላይ የተመሠረተ የሁኔታ አመልካች (ንቁ / ንቁ ያልሆነ / ስህተት ያጋጠመው)
- በአንድ ጠቅታ የሙከራ ማድረስ
- በእጅ የማንቃት/የማሰናከል መቀያየሪያ
## የPayload ምሳሌዎች
### request.completed
```json
{
"event": "request.completed",
"timestamp": "2026-05-13T20:30:00.123Z",
"data": {
"trace_id": "...",
"api_key_id": "...",
"provider": "openai",
"model": "gpt-5",
"status": 200,
"tokens_in": 142,
"tokens_out": 350,
"cost_usd": 0.0042
}
}
```
### test.ping
```json
{
"event": "test.ping",
"timestamp": "2026-05-13T20:32:00.000Z",
"data": {
"message": "Test webhook delivery from OmniRoute",
"webhookId": "<uuid>"
}
}
```
ከ `test.ping` ውጪ ላሉ ክስተቶች የመስኮች ቅርጽ እነሱን በሚልኩ የጥሪ ቦታዎች ይወሰናል፤ የ `data` ኦብጀክትን ከወደፊት ለሚመጡ ለውጦች ተኳሃኝ አድርገው ይያዙት (መስኮችን ይጨምሩ፣ በአለመኖራቸው ላይ ጥገኛ አይሁኑ)።
## ምርጥ ልምዶች
- **በእያንዳንዱ ማድረስ ላይ ፊርማውን ያረጋግጡ** ከጥሬው body ጋር በማነጻጸር — ይህ የwebhook URLዎን ከሚገምት ማንኛውም ሰው የሚላኩ የተጭበረበሩ POSTsን ይከላከላል።
- **በ~5 ሰከንዶች ውስጥ 2xx ምላሽ ይስጡ** — አሰራጩ በ10 s ጊዜው ያልቃል። ዘገምተኛ ተቀባዮች ድጋሚ ሙከራዎችን ይጨርሳሉ እና `failure_count`ን ያሳድጋሉ።
- **Handlersን idempotent ያድርጉ** — ድጋሚ ሙከራዎች እና ቢያንስ-አንድ-ጊዜ የማድረስ ባህሪ የተባዙ መልዕክቶች ሊኖሩ እንደሚችሉ ያመለክታሉ።
- **በትንሹ ይመዝገቡ** — በትክክል የሚጠቀሙባቸውን ክስተቶች ብቻ ይዘርዝሩ፤ `"*"` እርስዎ በማይቆጣጠሯቸው ተቀባዮች ላይ ወጪ ይጨምራል።
- **`failure_count`ን ይከታተሉ** — endpoints 10 ተከታታይ ውድቀቶች ሲያጋጥሙ በራስ-ሰር ይሰናከላሉ፤ ተቀባዩን ካስተካከሉ በኋላ `PUT /api/webhooks/[id]`ን ከ `enabled: true` ጋር በመጥራት ዳግም ያስጀምሩት።
- **ሚስጥሮችን በየጊዜው ይቀይሩ** — አዲስ `secret` በ `PUT` ይላኩ፣ አዲሱን እሴት ወደ ተቀባዩ ያሰማሩ እና በሙከራ endpoint በኩል ያረጋግጡ።
## በተጨማሪ ይመልከቱ
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — ሙሉ የአስተዳደር API ወሰን
- [RESILIENCE_GUIDE.md](../architecture/RESILIENCE_GUIDE.md) — በ `request.failed` በኩል ከሚታዩ የአቅራቢ ውድቀቶች ጀርባ ያሉ የcircuit breaker / cooldown ባህሪያት
- ምንጭ፦ `src/lib/webhookDispatcher.ts`, `src/lib/db/webhooks.ts`

219
docs/i18n/am/docs/getting-started/AUTO-COMBO-GUIDE.md Normal file
View File

@@ -0,0 +1,219 @@
# Auto-Combo: Let OmniRoute Pick the Best AI for You (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../getting-started/AUTO-COMBO-GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇦🇿 [az](../../../az/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇩🇰 [da](../../../da/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇩🇪 [de](../../../de/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇬🇷 [el](../../../el/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇪🇸 [es](../../../es/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇪🇪 [et](../../../et/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇱 [he](../../../he/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇩 [id](../../../id/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇹 [it](../../../it/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇰🇭 [km](../../../km/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇲🇲 [my](../../../my/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇳🇴 [no](../../../no/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [or](../../../or/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇱🇰 [si](../../../si/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇮🇳 [te](../../../te/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇹🇭 [th](../../../th/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/getting-started/AUTO-COMBO-GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/getting-started/AUTO-COMBO-GUIDE.md)
---
> **በአጭሩ**: ሞዴልዎን ወደ `auto` ያዘጋጁ፤ OmniRoute ለእያንዳንዱ ጥያቄ ምርጡን AI አቅራቢ በራስ-ሰር ይመርጣል። ምንም ውቅር አያስፈልግም።
---
## ምን ያደርጋል
አንድ የተወሰነ AI ሞዴል (እንደ GPT-4o ወይም Claude) ከመምረጥ ይልቅ፣ OmniRoute ለእያንዳንዱ ጥያቄ **ምርጡን በራስ-ሰር እንዲመርጥ** ማድረግ ይችላሉ። የሚከተሉትን ግምት ውስጥ ያስገባል፦
- **ጤንነት** — አቅራቢው አሁን እየሠራ ነው?
- **ፍጥነት** — ምን ያህል ፈጣን ነው?
- **ወጪ** — ምን ያህል ያስከፍላል?
- **ጥራት** — በዚህ ዓይነት ተግባር ጥሩ ነው?
- **አቅም** — ቀሪ ኮታ አለው?
OmniRoute ሁሉንም ያገናኟቸውን አቅራቢዎች ደረጃ ሰጥቶ ምርጡን ይመርጣል። ያ ካልተሳካ፣ ቀጣዩን በራስ-ሰር ይሞክራል።
---
## ፈጣን መጀመሪያ
**ደረጃ 1**: በIDE ወይም CLIዎ ውስጥ ሞዴልዎን ወደ `auto` ያዘጋጁ፦
```
model: "auto"
```
**ደረጃ 2**: ይኸው ብቻ ነው! ቀሪውን OmniRoute ያከናውናል።
**ደረጃ 3** (አማራጭ): ለተወሰኑ ተግባራት ተለዋጭ ይጠቀሙ፦
```
model: "auto/coding" # ለኮድ ምርጡ
model: "auto/fast" # ፈጣኑ ምላሽ
model: "auto/cheap" # ርካሹ አማራጭ
```
---
## የትኛውን "auto" ልጠቀም?
| የሚፈልጉት... | ይህን ይጠቀሙ | በጣም ተስማሚ የሆነው | እንዴት እንደሚሠራ |
| ----------------- | -------------- | -------------------- | ------------------------------- |
| **በአጠቃላይ ምርጡ** | `auto` | አጠቃላይ ጥያቄዎች፣ ውይይት | ፍጥነትን፣ ወጪን እና ጥራትን ያመጣጥናል |
| **ለኮድ ምርጡ** | `auto/coding` | ኮድ መጻፍ፣ ስህተት ማረም | በኮድ ሥራዎች ጥሩ የሆኑ ሞዴሎችን ይመርጣል |
| **ፈጣኑ ምላሽ** | `auto/fast` | ፈጣን መልሶች፣ ዝቅተኛ መዘግየት | ከሁሉም በላይ ለፍጥነት ቅድሚያ ይሰጣል |
| **ርካሹ አማራጭ** | `auto/cheap` | ገንዘብ መቆጠብ | ርካሹን አቅራቢ ይመርጣል |
| **ብልሁ ሞዴል** | `auto/smart` | ውስብስብ ተግባራት | ጥራትን ያስቀድማል + አዳዲስ ሞዴሎችን ይመረምራል |
| **በጣም ተገኝነት ያለው** | `auto/offline` | አቅራቢዎች ሥራ በሚበዛባቸው ጊዜ | ከፍተኛ አቅም ያላቸውን አቅራቢዎች ይመርጣል |
### ምሳሌዎች
```bash
# አጠቃላይ ውይይት — ሚዛናዊ
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
# ኮድ ማመንጨት — ጥራትን ያስቀድማል
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto/coding","messages":[{"role":"user","content":"Write a Python function"}]}'
# ፈጣን መልስ — ፍጥነትን ያስቀድማል
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto/fast","messages":[{"role":"user","content":"What is 2+2?"}]}'
```
---
## እንዴት እንደሚሠራ (ቀላል ስሪት)
`model: "auto"` ያለው ጥያቄ ሲልኩ፣ OmniRoute፦
1. **ያገናኟቸውን አቅራቢዎች በሙሉ ይመለከታል** — ያከሏቸውን እያንዳንዱን አቅራቢ (OpenAI፣ Anthropic፣ Google፣ ወዘተ)
2. **ለእያንዳንዱ ደረጃ ይሰጣል**፣ ከሌሎች ነገሮች ጋር የሚከተሉትን ክብደት በመስጠት፦
- እየሠራ ነው? (ጤንነት)
- በቂ አቅም አለው? (ኮታ)
- ምን ያህል ያስከፍላል? (ዋጋ)
- ምን ያህል ፈጣን ነው? (ፍጥነት)
- በዚህ ተግባር ጥሩ ነው? (ጥራት)
3. **ምርጡን ይመርጣል** — ከፍተኛውን ውጤት ያገኘው አቅራቢ ጥያቄዎን ይቀበላል
4. **በራስ-ሰር ያገግማል** — ካልተሳካ፣ OmniRoute ቀጣዩን በራስ-ሰር ይሞክራል
### የደረጃ አሰጣጥ ሥርዓቱ
እያንዳንዱ አቅራቢ ከ0 እስከ 1 የሆነ ውጤት ያገኛል። ውጤቱ ከፍ ባለ ቁጥር፣ ተስማሚነቱ የተሻለ ይሆናል።
| መለኪያ | ክብደት | ትርጉሙ |
| ------------ | ---- | -------------------------------------- |
| ጤንነት | 20% | አቅራቢው እየሠራ ነው? (የcircuit breaker ሁኔታ) |
| ኮታ | 15% | ቀሪ አቅም አለው? |
| ወጪ | 15% | ምን ያህል ውድ ነው? (ይበልጥ ርካሽ = ከፍተኛ ውጤት) |
| ፍጥነት | 12% | ምን ያህል ፈጣን ነው? (ዝቅተኛ መዘግየት = ከፍተኛ ውጤት) |
| ለተግባሩ ተስማሚነት | 8% | በዚህ ዓይነት ተግባር ጥሩ ነው? |
| መረጋጋት | 5% | ወጥነት አለው? (ዝቅተኛ የስህተት መጠን) |
| ደረጃ | 5% | የመለያ ደረጃ (Ultra > Pro > Free) |
| ሌላ | 20% | የአውድ ቅርርብ፣ የግንኙነት ጥግግት፣ ወዘተ |
### ተለዋጮች የደረጃ አሰጣጡን እንዴት እንደሚቀይሩ
እያንዳንዱ ተለዋጭ የተለያዩ ክብደቶችን ይጠቀማል፦
| ተለዋጭ | ቅድሚያ የሚሰጠው | ቁልፍ ክብደቶች |
| -------------- | ---------- | ------------------------------- |
| `auto` | ሚዛናዊ | health=20%, quota=15%, cost=15% |
| `auto/coding` | ጥራት | taskFit=37%, stability=15% |
| `auto/fast` | ፍጥነት | latency=32%, health=28% |
| `auto/cheap` | ወጪ | cost=37% |
| `auto/smart` | ጥራት + ማሰስ | taskFit=37%, exploration=10% |
| `auto/offline` | አቅም | quota=37%, health=28% |
---
## ብልሽቶችን እንዴት እንደሚቆጣጠር
OmniRoute **ሦስት የጥበቃ ደረጃዎች** አሉት፦
### 1. ራስ-ሰር ወደ አማራጭ መመለስ
ምርጡ አቅራቢ ካልተሳካ፣ OmniRoute ቀጣዩን በራስ-ሰር ይሞክራል። እርስዎ ምንም ማድረግ አያስፈልግዎትም።
### 2. ራስን መጠገን
አንድ አቅራቢ በተደጋጋሚ ካልተሳካ፦
- **ውጤት < 0.2** → ለ5 ደቂቃዎች ይገለላል
- **የወረዳ መቆራረጫ ክፍት** → በራስ-ሰር ይገለላል
- **ከአቅራቢዎቹ ከ50% በላይ አይሰሩም** → የክስተት ሁነታ (ፍለጋ የለም)
### 3. የአደጋ ጊዜ አማራጭ
ሁሉም አቅራቢዎች ካልተሳኩ፣ OmniRoute እንደ Kiro ወይም Qoder ወዳሉ የተረጋጉ ነፃ አቅራቢዎች እንደ መጨረሻ አማራጭ ጥያቄውን ይመራል።
---
## የብዙ መለያዎች ድጋፍ
ለተመሳሳይ አቅራቢ ብዙ መለያዎች ካሉዎት (ለምሳሌ፣ ሁለት OpenAI ቁልፎች)፣ OmniRoute እያንዳንዱን እንደ **የተለየ እጩ** ይቆጥረዋል። ይህም ማለት፦
- መለያ A ቀሪ ኮታ አለው → ይጠቀምበታል
- መለያ B የፍጥነት ገደብ ተጥሎበታል → ይዘለዋል
- መለያ C ርካሽ ነው → ቅድሚያ ይሰጠዋል
እያንዳንዱ መለያ በራሱ ጤናማነት፣ ኮታ እና ፍጥነት መሠረት በተናጠል ይመዘናል።
---
## የBandit ፍለጋ
OmniRoute የተሻሉ አማራጮችን ለማግኘት አልፎ አልፎ አዳዲስ አቅራቢዎችን **ይፈትሻል**፦
- **ነባሪ**፦ ከጥያቄዎች 5% ወደ ዘፈቀደ አቅራቢዎች ይሄዳሉ
- **Auto/smart**፦ 10% የፍለጋ መጠን
- **ይሰናከላል**፦ ከአቅራቢዎቹ ከ50% በላይ ጤናማ ካልሆኑ
ይህ OmniRoute ለእርስዎ የአጠቃቀም ዘይቤዎች የትኞቹ አቅራቢዎች በተሻለ ሁኔታ እንደሚሰሩ እንዲማር ይረዳዋል።
---
## የተለመዱ ጥያቄዎች
### "ሁልጊዜ በጣም ውዱን ሞዴል ይመርጣል?"
**አይ።** በነባሪነት ወጪ ከውጤቱ 15% ብቻ ነው። ርካሽ፣ ፈጣን እና ጤናማ አቅራቢ ውድ ከሆነው ሊበልጥ ይችላል። ለወጪ የበለጠ ቅድሚያ መስጠት ከፈለጉ `auto/cheap`ን ይጠቀሙ።
### "አንድ አቅራቢ መስራት ቢያቆምስ?"
OmniRoute በራስ-ሰር ይዘለዋል እና ቀጣዩን ይሞክራል። አንድ አቅራቢ በተደጋጋሚ ካልተሳካ፣ ለጊዜው (ከ5-30 ደቂቃዎች) ይገለላል። እርስዎ ምንም ማድረግ አያስፈልግዎትም።
### "የትኛው አቅራቢ ጥቅም ላይ እንደዋለ ማየት እችላለሁ?"
የምላሹን ራስጌዎች ይመልከቱ — OmniRoute በእያንዳንዱ ምላሽ ውስጥ ጥቅም ላይ የዋሉትን አቅራቢ እና ሞዴል ያካትታል።
### "ከአጠቃቀሜ ይማራል?"
አዎ! የውጤት አሰጣጥ ስርዓቱ ከጊዜ በኋላ የተሻሉ ውሳኔዎችን ለመስጠት ታሪካዊ ውሂብን (መዘግየት፣ የስህተት መጠኖች፣ የስኬት መጠኖች) ይጠቀማል።
### "በ`auto` እና `auto/smart` መካከል ያለው ልዩነት ምንድን ነው?"
- `auto` — ሚዛናዊ፣ 5% ፍለጋ
- `auto/smart` — ለጥራት ቅድሚያ የሚሰጥ (ከ`auto/coding` ጋር ተመሳሳይ ክብደቶች)፣ 10% ፍለጋ
ከፍተኛውን ጥራት ሲፈልጉ እና አልፎ አልፎ የሚደረግ ፍለጋን የሚቀበሉ ከሆነ `auto/smart`ን ይጠቀሙ።
### "የተወሰነ አቅራቢ እንዲጠቀም ማስገደድ እችላለሁ?"
አዎ! ከ`auto` ይልቅ የ`priority` ስልት ያለውን ጥምረት ይጠቀሙ፣ ከዚያም የጥምረቱን **ትክክለኛ ስም** እንደ `model` መስክ ይላኩ (ለምሳሌ፣ `model: "my-combo"` — `auto` አይደለም)። ለዝርዝሮች [ቴክኒካዊ ማጣቀሻውን](../routing/AUTO-COMBO.md) ይመልከቱ።
### "ይህ ከround-robin በምን ይለያል?"
Round-robin በቅደም ተከተል በአቅራቢዎች መካከል ይዘዋወራል። Auto-combo **እያንዳንዱን አቅራቢ ይመዝናል** እና ምርጡን ይመርጣል። የበለጠ ብልህ ነው — ጤናማነትን፣ ፍጥነትን፣ ወጪን እና ጥራትን ከግምት ውስጥ ያስገባል።
---
## ቀጣዩ ምንድን ነው?
- **[አቅራቢ ያገናኙ](./PROVIDERS-GUIDE.md)** — የመጀመሪያውን AI አቅራቢዎን ያክሉ
- **[የነፃ ደረጃዎች መመሪያ](./FREE-TIERS-GUIDE.md)** — የክሬዲት ካርድ ሳያስፈልግ ነፃ AI ያግኙ
- **[መላ ፍለጋ](../guides/TROUBLESHOOTING.md)** — የተለመዱ ችግሮችን ያስተካክሉ
- **[ቴክኒካዊ ማጣቀሻ](../routing/AUTO-COMBO.md)** — የውጤት አሰጣጥ ስልተ ቀመሩን በጥልቀት ይመልከቱ
---
## ተጨማሪ ይወቁ
ለገንቢዎች እና አስተዋጽዖ አድራጊዎች፣ ለሚከተሉት [Auto-Combo ቴክኒካዊ ማጣቀሻ](../routing/AUTO-COMBO.md)ን ይመልከቱ፦
- ሙሉ ባለ16-ምክንያት የውጤት አሰጣጥ ስልተ ቀመር
- የሁነታ ጥቅል የክብደት ሰንጠረዦች
- የትግበራ ፋይል ዱካዎች
- የAPI መጨረሻ ነጥቦች
- ራስን የማስተካከል ስልተ ቀመር ዝርዝሮች

221
docs/i18n/am/docs/getting-started/FREE-TIERS-GUIDE.md Normal file
View File

@@ -0,0 +1,221 @@
# Free Tiers Guide: Understand and Combine Free AI Access (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../getting-started/FREE-TIERS-GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇦🇿 [az](../../../az/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇩🇰 [da](../../../da/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇩🇪 [de](../../../de/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇬🇷 [el](../../../el/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇪🇸 [es](../../../es/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇪🇪 [et](../../../et/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇱 [he](../../../he/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇩 [id](../../../id/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇹 [it](../../../it/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇰🇭 [km](../../../km/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇲🇲 [my](../../../my/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇳🇴 [no](../../../no/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [or](../../../or/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇱🇰 [si](../../../si/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇮🇳 [te](../../../te/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇹🇭 [th](../../../th/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/getting-started/FREE-TIERS-GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/getting-started/FREE-TIERS-GUIDE.md)
---
> **በአጭሩ**: OmniRoute 357 የአቅራቢ መታወቂያዎችን ይመዘግባል፣ ከእነዚህም **152 የአቅራቢ-ካታሎግ ግቤቶች `hasFree` ተብለው ምልክት ተደርጎባቸዋል**። ይበልጥ ጥብቅ የሆነውና ኦዲት የተደረገበት የነፃ-ሞዴል ካታሎግ **35 ተደጋጋሚ የፑል ቁልፎችን / 482 ግቤቶችን** (475 ንቁ + 7 የተቋረጡ) ይሸፍናል። ሰፋ ያለ የመጠባበቂያ አቅም ለማግኘት በርካታ ተስማሚ አቅራቢዎችን ያገናኙ፤ እያንዳንዱ ኮታ፣ የማጽደቅ ደንብ፣ የግላዊነት ፖሊሲ እና የተከፈለ ከኮታ-በላይ አጠቃቀም ሁኔታ አሁንም ተፈጻሚ ነው።
---
## ነፃ ደረጃዎች ምንድን ናቸው?
ብዙ የAI አቅራቢዎች አንዳንድ ዓይነት **ነፃ መዳረሻ** ይሰጣሉ። እንደ አቅራቢው ሁኔታ፣ ይህ
ማረጋገጫ የማይፈልግ endpoint፣ ተደጋጋሚ ኮታ፣ የፍጥነት ገደብ ያለው ነገር ግን ከፍተኛ የአጠቃቀም ጣሪያ የሌለው መዳረሻ፣ የምዝገባ ስጦታ፣
በእጅ የሚሰጥ ፈቃድ፣ ወይም ጊዜያዊ ማስተዋወቂያ ሊሆን ይችላል። አንዳንድ አማራጮች መለያ፣ API ቁልፍ፣
ክሬዲት ካርድ፣ KYC፣ ወይም ለአቅራቢው የተለዩ ውሎችን መቀበል ይጠይቃሉ።
OmniRoute እነዚህን ነፃ ደረጃዎች ወደ አንድ endpoint **ያሰባስባል**። ለ10 የተለያዩ አገልግሎቶች በተናጠል ከመመዝገብ ይልቅ፣ ሁሉንም ከOmniRoute ጋር ያገናኛሉ፤ ከዚያም ለእያንዳንዱ ጥያቄ ምርጡን ነፃ አማራጭ በራስ-ሰር ለመምረጥ `model: "auto"` ይጠቀማሉ።
---
## ነፃ መዳረሻ የሚሰጡ ተወካይ አቅራቢዎች
### ተደጋጋሚ፣ ቁልፍ የማይፈልግ፣ ወይም ከፍተኛ ጣሪያ የሌለው መዳረሻ
እነዚህ አቅራቢዎች ኦዲት በተደረገበት ካታሎግ ውስጥ ተደጋጋሚ፣ ቁልፍ የማይፈልግ፣ ወይም ከፍተኛ ጣሪያ የሌለው የነፃ መዳረሻ መንገድ አላቸው። “ከፍተኛ ጣሪያ የሌለው” ማለት በይፋ የታተመ የቶከን ጣሪያ የለም ማለት ነው፤ የፍጥነት፣ የበአንድ ጊዜ ጥያቄዎች፣ የመለያ፣ የክልል እና የፖሊሲ ገደቦች አሁንም ሊተገበሩ ይችላሉ፦
| አቅራቢ | ሞዴሎች | ኮታ | እንዴት እንደሚገናኝ |
| ----------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Kiro AI** | Claude Sonnet 4.5፣ Haiku 4.5፣ DeepSeek V3.2 እና ሌሎች | ኦዲት የተደረገበት ካታሎግ 25K-ቶከን የጋራ ወርሃዊ ፑል እንዳለ ይገምታል | OAuth/የመለያ ሂደት፤ ToS በካታሎጉ ውስጥ `avoid` ተብሎ ተሰይሟል |
| **OpenCode Free** | በአቅራቢው መዝገብ ውስጥ ያለው የአሁኑ `*-free` ሞዴል ስብስብ | ቁልፍ አያስፈልግም፤ በይፋ የታተመ የቶከን ጣሪያ የለም | የአቅራቢ ማረጋገጫ መረጃ አያስፈልግም፤ ToS `avoid` ተብሎ ተሰይሟል |
| **Pollinations** | የአሁኑ ቁልፍ የማይፈልግ ሞዴል ስብስብ፤ አንዳንድ ቀደምት ሞዴሎች ተቋርጠዋል ወይም ቁልፍ ይፈልጋሉ | ቁልፍ አያስፈልግም፤ በይፋ የታተመ የቶከን ጣሪያ የለም | ቁልፍ ለማይፈልጉ ሞዴሎች የአቅራቢ ማረጋገጫ መረጃ አያስፈልግም |
| **Logfare** | kimi-k3፣ deepseek-v4-pro፣ glm-5.2፣ gpt-5.6-luna፣ minimax-m3 እና ሌሎች | ነፃ API ቁልፍ (የፍጥነት ገደብ የለም፣ ካርድ አያስፈልግም)፤ ለምርምር **እያንዳንዱ ጥያቄ ይመዘገባል** (በlogfare.ai/consent መውጣት ይቻላል) | በlogfare.ai/register ፈጣን ቁልፍ፤ ToS/ግላዊነት በlogfare.ai/tos እና logfare.ai/privacy |
| **Cloudflare AI** | Workers AI ካታሎግ | ኦዲት የተደረገበት ፑል በታተሙ የአጠቃቀም አሃዶች መሠረት ~30M ቶከኖች/ወር እንዳሉ ይገምታል | Cloudflare መለያ እና API ማረጋገጫ መረጃ |
| **Gemini** | Gemini Flash ቤተሰብ | ኦዲት የተደረገበት ፑል ~60M ቶከኖች/ወር እንዳሉ ይገምታል | Google AI Studio API ቁልፍ፤ የፍጥነት ገደቦች ተፈጻሚ ናቸው |
| **Groq** | Llama፣ GPT-OSS እና Qwen ሞዴሎች | ኦዲት የተደረገበት ፑል ~15M ቶከኖች/ወር እንዳሉ ይገምታል | Groq API ቁልፍ፤ የፍጥነት ገደቦች ተፈጻሚ ናቸው |
| **Cerebras** | GLM 4.7 እና GPT-OSS 120B | ኦዲት የተደረገበት ፑል ~30M ቶከኖች/ወር እንዳሉ ይገምታል | Cerebras API ቁልፍ፤ የፍጥነት ገደቦች ተፈጻሚ ናቸው |
### የምዝገባ ስጦታዎች እና ለአቅራቢ የተለዩ ክሬዲቶች
እነዚህ አቅራቢዎች ሲመዘገቡ **ነፃ ክሬዲቶችን** ይሰጡዎታል፦
| አቅራቢ | ነፃ ክሬዲቶች | ሞዴሎች | እንዴት እንደሚገኙ |
| ------------- | ------------------------------------------------- | ------------------- | --------------------------------------------- |
| **DeepSeek** | 5M ነፃ ቶከኖች | DeepSeek V4 | በplatform.deepseek.com ይመዝገቡ |
| **LongCat** | 10M-ቶከን የአንድ ጊዜ ስጦታ | LongCat 2.0 | API ቁልፍ + KYC፤ ከስጦታው በኋላ በአጠቃቀም መጠን ይክፈሉ |
| **Vertex AI** | በበጀት ሞዴሉ ውስጥ ~300M ቶከኖች ተብሎ የተወከለ $300 የምዝገባ ክሬዲት | Gemini እና የአጋር ሞዴሎች | Google Cloud መለያ፤ የክፍያ እና የብቁነት ደንቦች ተፈጻሚ ናቸው |
### ሌላ የተገደበ መዳረሻ
እነዚህ አቅራቢዎች የተወሰኑ ገደቦች ያሏቸው **ነፃ ደረጃዎች** አሏቸው፦
| አቅራቢ | ነፃ ገደብ | ሞዴሎች | ለሚከተለው ምርጥ ነው |
| -------------------------- | ---------------------------------------------------------------------- | ------------------------- | ------------- |
| **GitHub Models** | በኦዲት የተረጋገጠ የጋራ ክምችት፤ በወር ~18M ቶከኖች እንደሚኖሩት ይገመታል | ሰፊ የሞዴል ግምገማ |
| **Hugging Face** | በየወሩ የሚታደስ አነስተኛ ክምችት | ሙከራዎች እና የሞዴል ልዩነት |
| **OpenRouter free models** | በጥያቄ ብዛት የተገደበ የጋራ ክምችት፤ አማራጭ የአንድ ጊዜ ተጨማሪ ክፍያ በየጊዜው የሚታደሰውን ፈቃድ ይጨምራል | ሰፊ የመጠባበቂያ ካታሎግ |
| **AI Horde** | ቁልፍ የማያስፈልገው የማህበረሰብ አቅም፤ ተደራሽነቱ ይለያያል | አጋጣሚን የሚጠቀም የተከፋፈለ ኢንፈረንስ |
---
## ነፃ ደረጃዎችን እንዴት ማጣመር እንደሚቻል
የOmniRoute ልዩ ችሎታ **ነፃ ደረጃዎችን ማጣመር** ነው። በአንድ አቅራቢ ላይ ከመመሥረት ይልቅ፣ በርካታ ነፃ አቅራቢዎችን በማገናኘት OmniRoute ለእያንዳንዱ ጥያቄ በጣም ተስማሚውን በራስ-ሰር እንዲመርጥ ያደርጋሉ።
### ምሳሌ፦ ሰፊ የነፃ ደረጃ ሽፋን
በአንድ ኮታ ላይ ያለውን ጥገኝነት ለመቀነስ በርካታ አቅራቢዎችን ያገናኙ፦
1. **Gemini** — በየጊዜው የሚታደስ የAPI ቁልፍ ኮታ
2. **Groq** — በየጊዜው የሚታደስ የAPI ቁልፍ ኮታ
3. **Pollinations** — ቁልፍ የማያስፈልገው፣ የጥያቄ ፍጥነቱ የተገደበ መዳረሻ
4. **LongCat** — በምዝገባ ጊዜ አንድ ጊዜ የሚሰጥ ጥቅም (KYC ያስፈልጋል)
ከዚያ `model: "auto"` ይጠቀሙ፣ እና OmniRoute የሚከተሉትን ያደርጋል፦
- በቅድሚያ ከፍተኛ ደረጃ የተሰጠውን ብቁ ግንኙነት ይሞክራል
- ኮታው ካለቀ ወይም የጤንነት ምርመራው ካልተሳካ → ቀጣዩን የተዋቀረ አቅራቢ ይሞክራል
- ቁልፍ የማያስፈልገው አቅራቢ የማይገኝ ከሆነ → በቀሩት ዒላማዎች በኩል ይቀጥላል
- ሁሉም ካልተሳኩ → LongCatን እንደ ምትኬ ይጠቀማል
**ውጤት**፦ በራስ-ሰር ወደ ምትኬ በመሸጋገር ሰፊ የነፃ ደረጃ ሽፋን — ይህ ግን ገደብ የለሽ አቅምን አያረጋግጥም።
---
## ነፃ አቅራቢዎችን እንዴት ማገናኘት እንደሚቻል
### ደረጃ 1፦ ዳሽቦርዱን ይክፈቱ
በአሳሽዎ ውስጥ ወደ `http://localhost:20128` ይሂዱ።
### ደረጃ 2፦ ወደ አቅራቢዎች ይሂዱ
በጎን አሞሌው ላይ **Providers**ን ጠቅ ያድርጉ።
### ደረጃ 3፦ አቅራቢ አክልን ጠቅ ያድርጉ
የ**+ Add Provider** አዝራሩን ጠቅ ያድርጉ።
### ደረጃ 4፦ ነፃ አቅራቢ ይምረጡ
ካታሎጉን ያስሱ እና የእያንዳንዱን አቅራቢ ወቅታዊ `hasFree`፣ የማረጋገጫ፣ የኮታ፣ የግላዊነት፣
እና የToS ሜታዳታ ይመርምሩ። የአቅራቢው ካርድ እና
[የነፃ ደረጃዎች ማጣቀሻ](../reference/FREE_TIERS.md) በየጊዜው የሚታደሱ ስብስቦችን፣
ጣሪያ የሌለውን/ቁልፍ የማያስፈልገውን መዳረሻ፣ የምዝገባ ክሬዲቶችን፣ የተቋረጡ ግቤቶችን እና ከፍተኛ ስጋት ያላቸውን ምንጮች ይለያሉ።
### ደረጃ 5፦ አገናኝን ጠቅ ያድርጉ
ለ`NOAUTH` አቅራቢ ምንም የመግቢያ ማረጋገጫ አያስፈልግም። የOAuth እና የAPI ቁልፍ አቅራቢዎች
በሰነድ በተገለጸው የመለያ ሂደታቸው በኩል መገናኘት አለባቸው።
### ደረጃ 6፦ ይድገሙ
ውሎቻቸው እና የግላዊነት ሞዴላቸው ከአጠቃቀም ሁኔታዎ ጋር የሚስማሙ በርካታ አቅራቢዎችን ያገናኙ።
---
## ካታሎጉን በትክክል ማንበብ
- `NOAUTH` ማለት OmniRoute የአቅራቢ የመግቢያ ማረጋገጫ ከእርስዎ አይጠይቅም ማለት ነው፤ የሥራ ቀጣይነትን፣
ግላዊነትን ወይም ገደብ የለሽ አቅምን አያረጋግጥም።
- `hasFree` የግኝት ሜታዳታ ነው። በየጊዜው የሚታደስ ኮታን፣ ቁልፍ የማያስፈልገውን መዳረሻን፣
የምዝገባ ክሬዲትን፣ የማጽደቂያ ፕሮግራምን ወይም ማስተዋወቂያን ሊወክል ይችላል።
- `recurring-uncapped` ማለት በይፋ የታተመ የቶከን ጣሪያ አልተገኘም ማለት ነው፤ የጥያቄ ፍጥነት እና
የትይዩነት ገደቦች አሁንም ይተገበራሉ።
- `one-time-initial` በምዝገባ ጊዜ የተሰጠው ጥቅም ካለቀ በኋላ አይታደስም።
- `tos: avoid` ከመጠቀምዎ በፊት የአቅራቢውን ውሎች እና የመለያ ስጋት እንዲገመግሙ የሚያስጠነቅቅ ማስጠንቀቂያ ነው።
- `discontinued` ተብለው ምልክት የተደረገባቸው ግቤቶች እንደ ታሪካዊ ማስረጃ ይቆያሉ፣ እና በአሁኑ ጊዜ
ነፃ እንደሆኑ ተደርገው መቅረብ የለባቸውም።
---
## OmniRoute ነፃ ደረጃዎችን እንዴት የተሻሉ እንደሚያደርግ
### 1. በራስ-ሰር ወደ ምትኬ መሸጋገር
አንድ ነፃ አቅራቢ በሥራ ተጨናንቆ ወይም ከመስመር ውጭ ከሆነ፣ OmniRoute ቀጣዩን በራስ-ሰር ይሞክራል። እርስዎ ምንም ማድረግ አያስፈልግዎትም።
### 2. ብልህ ማዘዋወር
OmniRoute በሚከተሉት መሠረት ለእያንዳንዱ ጥያቄ **በጣም ተስማሚውን ነፃ አቅራቢ** ይመርጣል፦
- ፍጥነት — በአሁኑ ጊዜ ፈጣኑ አቅራቢ የትኛው ነው?
- ጥራት — ለዚህ ተግባር በጣም ተስማሚው አቅራቢ የትኛው ነው?
- አቅም — ቀሪ ኮታ ያለው አቅራቢ የትኛው ነው?
### 3. የቶከን ቁጠባ
የOmniRoute የመጭመቂያ የሥራ ሂደት ብቁ የሆኑ የጥያቄ ጽሑፍ እና የመሣሪያ ውጤት ቶከኖችን ሊቀንስ ይችላል።
ትክክለኛው ቁጠባ በይዘቱ፣ በተመረጡት ሞተሮች፣ በአቅራቢው የአጠቃቀም ስሌት እና በታማኝነት
ቅንብሮች ላይ ይመረኮዛል፤ መጭመቅ የእያንዳንዱን አቅራቢ ኮታ በቋሚ መጠን አያባዛም።
### 4. የበርካታ መለያዎች ድጋፍ
የአቅራቢው ውሎች በርካታ መለያዎችን ወይም የመግቢያ ማረጋገጫዎችን የሚፈቅዱ ከሆነ፣ OmniRoute እያንዳንዱን
ግንኙነት እንደ የተለየ የማዘዋወር እጩ ሊቆጥረው ይችላል። የአቅራቢውን ኮታ ወይም የመዳረሻ ፖሊሲ
ለማለፍ ተጨማሪ መለያዎችን አይፍጠሩ።
---
## የነፃ ደረጃ ስሌት
በቀጥታ ስርጭት ላይ ያለው፣ የጋራ ስብስቦች ድግግሞሽ የተወገደለት ካታሎግ በአሁኑ ጊዜ የሚከተሉትን ሪፖርት ያደርጋል፦
| መለኪያ | የአሁኑ ኦዲት የተደረገበት ዋጋ | ትርጓሜ |
| --------------------------------------- | ---------------------------------------: | ------------------------------------------------------------------------------------------- |
| ተደጋጋሚ በቁጥር የተወሰነ ድጎማ | **~1.62B ቶከኖች/ወር** | የጋራ ስብስቦች አንድ ጊዜ ብቻ ተቆጥረዋል፤ ገደብ የሌላቸው አቅራቢዎችን ከድምሩ አያካትትም |
| የምዝገባ ድጎማዎችን ያካተተ የመጀመሪያ ወር | **~2.22B ቶከኖች** | ተደጋጋሚው ጠቅላላ ድምር ከአንድ ጊዜ እና ተደጋጋሚ ክሬዲቶች ጋር |
| ኦዲት የተደረገበት የነፃ ሞዴሎች ዝርዝር | **35 ተደጋጋሚ የስብስብ ቁልፎች / 482 የካታሎግ ግቤቶች** | 475 ንቁ + 7 የተቋረጡ፤ ከ357-አቅራቢ ካታሎግ የተለየ |
| የተወከሉ ተደጋጋሚ/ቁልፍ-አልባ ለዘላለም ነፃ አቅራቢዎች | **53** | በተደጋጋሚ ዕለታዊ/ወርሃዊ/ክሬዲት/ገደብ-አልባ እና ቁልፍ-አልባ የካታሎግ ዓይነቶች ያሉ ልዩ አቅራቢዎች፤ በብቁነት የተገደቡ ረድፎች አልተካተቱም |
| `hasFree` የሚል ምልክት ያላቸው የአቅራቢ ካታሎግ ግቤቶች | **152 / 357** | ሰፋ ያለ የአቅራቢ ሜታዳታ፤ ሁሉም በቁጥር ሊወሰን የሚችል ተደጋጋሚ ኮታ የላቸውም |
እነዚህ እሴቶች ከ`open-sse/config/freeModelCatalog.ts` የተሰሉ ናቸው፤ ስለ የስብስብ ድግግሞሽ ማስወገድ፣ የToS ምልክቶች፣
የተቋረጡ ግቤቶች እና የምዝገባ ክሬዲት ዘዴ [የነፃ ደረጃዎች ማጣቀሻ](../reference/FREE_TIERS.md)ን ይመልከቱ።
---
## የተለመዱ ጥያቄዎች
### "ይህ በእርግጥ ነፃ ነው?"
ካታሎጉ በአቅራቢዎች የታተሙ ውሎችን እና የፕሮጀክቱን ምርምር ይመዘግባል፣ ነገር ግን ቅናሾች ሊለወጡ ይችላሉ።
ከመጠቀምዎ በፊት የአቅራቢውን ወቅታዊ ዋጋ፣ ኮታ፣ የግላዊነት ፖሊሲ እና የብቁነት መስፈርቶች ያረጋግጡ።
### "የነፃው ደረጃ ያልቃል?"
ማንኛውም አቅራቢ የአጠቃቀም ፍጥነትን ሊገድብ፣ ሞዴሎችን ሊቀይር፣ መዳረሻን ሊያግድ ወይም ከመስመር ውጭ ሊሆን ይችላል። በርካታ
ግንኙነቶች የመጠባበቂያ ሽፋንን ያሻሽላሉ፣ ነገር ግን የሚገኝ ነፃ መስመር እንዳለ ዋስትና አይሰጡም።
### "ነፃ አቅራቢዎችን ለምርት አገልግሎት መጠቀም እችላለሁ?"
የአቅራቢው SLA፣ የውሂብ አያያዝ፣ ገደቦች እና ውሎች የምርት አገልግሎት
መስፈርቶችዎን የሚያሟሉ ከሆነ ብቻ። ወሳኝ የሥራ ጫናዎች ክትትል ያለው፣ በውል አግባብ የሆነ መጠባበቂያ ሊኖራቸው ይገባል።
### "የተደበቀው ጉዳት ምንድን ነው?"
የሚኖሩ የአማራጭ መስዋዕቶች ጥብቅ ገደቦችን፣ የጥበቃ ዝርዝሮችን፣ KYCን፣ የክሬዲት ካርድ ማረጋገጫን፣ በ
ጥያቄዎች ላይ ማሰልጠንን፣ ደካማ ግላዊነትን፣ SLA አለመኖርን፣ የሞዴሎች ተደጋጋሚ ለውጥን፣ ጂኦግራፊያዊ ገደቦችን፣ ከገደብ በላይ ለሆነ አጠቃቀም ክፍያን ወይም
ከመለያ ፖሊሲ ጋር የተያያዘ ስጋትን ሊያካትቱ ይችላሉ። OmniRoute ያለውን ሜታዳታ ያሳያል፤ የትኛውን ማንቃት እንደሚፈልጉ እርስዎ ይመርጣሉ።
### "ተጨማሪ ነፃ ኮታ እንዴት ማግኘት እችላለሁ?"
1. ተጨማሪ ነፃ አቅራቢዎችን ያገናኙ
2. ተገቢ የማመቂያ ሞተሮችን ያንቁ እና ለሥራ ጫናዎ የተገኘውን ቁጠባ ይለኩ
3. ለነፃ/ርካሽ አቅራቢዎች ቅድሚያ ለመስጠት `auto/cheap`ን ይጠቀሙ
4. የአቅራቢዎችን ውሎች ሳይጥሱ ተጨማሪ የተፈቀዱ አቅራቢዎችን ወይም ማረጋገጫዎችን ያክሉ
### "ነፃ አቅራቢዎች ዝቅተኛ ጥራት አላቸው?"
የግድ አይደለም። አንዳንድ አቅራቢዎች በሚከፈልባቸው
መስመሮች የሚገኙትን ተመሳሳይ የሞዴል ቤተሰቦች ያቀርባሉ፣ ነገር ግን ገደቦች፣ መዘግየት፣ ግላዊነት፣ አስተማማኝነት እና የሞዴል ስሪቶች ሊለያዩ ይችላሉ።
የነፃ አቅራቢዎች ደረጃ አሰጣጥ ገጽን እንደ የጥራት ምልክት ይጠቀሙ እና በትክክል የሚቀርበውን ሞዴል ያረጋግጡ።
---
## ቀጣዩ ምንድን ነው?
- **[የራስ-ሰር ጥምር መመሪያ](./AUTO-COMBO-GUIDE.md)** — OmniRoute ለእርስዎ ምርጡን AI እንዲመርጥ ያድርጉ
- **[የአቅራቢዎች መመሪያ](./PROVIDERS-GUIDE.md)** — ተጨማሪ አቅራቢዎችን ያገናኙ
- **[የችግር መፍቻ](../guides/TROUBLESHOOTING.md)** — የተለመዱ ችግሮችን ይፍቱ
- **[የነፃ ደረጃዎች ማጣቀሻ](../reference/FREE_TIERS.md)** — የነፃ ደረጃዎች ሙሉ ዝርዝር

332
docs/i18n/am/docs/getting-started/PROVIDERS-GUIDE.md Normal file
View File

@@ -0,0 +1,332 @@
# Providers Guide: Connect AI Models to OmniRoute (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../getting-started/PROVIDERS-GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/getting-started/PROVIDERS-GUIDE.md) · 🇦🇿 [az](../../../az/docs/getting-started/PROVIDERS-GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/getting-started/PROVIDERS-GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/getting-started/PROVIDERS-GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/getting-started/PROVIDERS-GUIDE.md) · 🇩🇰 [da](../../../da/docs/getting-started/PROVIDERS-GUIDE.md) · 🇩🇪 [de](../../../de/docs/getting-started/PROVIDERS-GUIDE.md) · 🇬🇷 [el](../../../el/docs/getting-started/PROVIDERS-GUIDE.md) · 🇪🇸 [es](../../../es/docs/getting-started/PROVIDERS-GUIDE.md) · 🇪🇪 [et](../../../et/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/getting-started/PROVIDERS-GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/getting-started/PROVIDERS-GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/getting-started/PROVIDERS-GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇱 [he](../../../he/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/getting-started/PROVIDERS-GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/getting-started/PROVIDERS-GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/getting-started/PROVIDERS-GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇩 [id](../../../id/docs/getting-started/PROVIDERS-GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇹 [it](../../../it/docs/getting-started/PROVIDERS-GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/getting-started/PROVIDERS-GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/getting-started/PROVIDERS-GUIDE.md) · 🇰🇭 [km](../../../km/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/getting-started/PROVIDERS-GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/getting-started/PROVIDERS-GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/getting-started/PROVIDERS-GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/getting-started/PROVIDERS-GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/getting-started/PROVIDERS-GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/getting-started/PROVIDERS-GUIDE.md) · 🇲🇲 [my](../../../my/docs/getting-started/PROVIDERS-GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/getting-started/PROVIDERS-GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/getting-started/PROVIDERS-GUIDE.md) · 🇳🇴 [no](../../../no/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [or](../../../or/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/getting-started/PROVIDERS-GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/getting-started/PROVIDERS-GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/getting-started/PROVIDERS-GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/getting-started/PROVIDERS-GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/getting-started/PROVIDERS-GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/getting-started/PROVIDERS-GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/getting-started/PROVIDERS-GUIDE.md) · 🇱🇰 [si](../../../si/docs/getting-started/PROVIDERS-GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/getting-started/PROVIDERS-GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/getting-started/PROVIDERS-GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/getting-started/PROVIDERS-GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/getting-started/PROVIDERS-GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/getting-started/PROVIDERS-GUIDE.md) · 🇮🇳 [te](../../../te/docs/getting-started/PROVIDERS-GUIDE.md) · 🇹🇭 [th](../../../th/docs/getting-started/PROVIDERS-GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/getting-started/PROVIDERS-GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/getting-started/PROVIDERS-GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/getting-started/PROVIDERS-GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/getting-started/PROVIDERS-GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/getting-started/PROVIDERS-GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/getting-started/PROVIDERS-GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/getting-started/PROVIDERS-GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/getting-started/PROVIDERS-GUIDE.md)
---
> **በአጭሩ**: አቅራቢ ማለት ከAI አገልግሎት (እንደ OpenAI፣ Anthropic፣ Google) ጋር የሚደረግ ግንኙነት ነው። OmniRouteን ለመጠቀም ቢያንስ አንድ አቅራቢ ያስፈልግዎታል።
---
## አቅራቢ ምንድን ነው?
አቅራቢን እንደ **የስልክ አገልግሎት አቅራቢ** ያስቡት። ጥሪዎችን ለማድረግ የስልክ አገልግሎት አቅራቢ እንደሚያስፈልግዎት ሁሉ፣ AI ሞዴሎችን ለመጠቀም የAI አቅራቢ ያስፈልግዎታል። OmniRoute ከ**ሁሉም አቅራቢዎች** ጋር እንደሚሰራ ስልክ ነው — በመካከላቸው በራስ-ሰር መቀያየር ይችላሉ።
### የአቅራቢዎች ዓይነቶች
| ዓይነት | ምንድን ነው | ምሳሌዎች | ወጪ |
| ----------- | ------------------- | --------------------------------- | ---------------- |
| **ነፃ** | ክፍያ አያስፈልግም | Kiro, OpenCode Free, Pollinations | $0 |
| **API ቁልፍ** | API ቁልፍ ያስፈልግዎታል | OpenAI, Anthropic, Google | በአጠቃቀም መጠን ይክፈሉ |
| **OAuth** | በመለያዎ ይግቡ | Claude Code, GitHub Copilot | የደንበኝነት ምዝገባ |
| **የድር ኩኪ** | የአሳሽዎን ክፍለ-ጊዜ ይጠቀማል | ChatGPT Web (Codex), Gemini Web | $0 (መለያዎን ይጠቀማል) |
### የድር ኩኪ አቅራቢዎች
ለአጠቃላይ የማዋቀር መመሪያዎች፣ ገደቦች፣ ችግር መፍቻ እና ለእያንዳንዱ አቅራቢ የተወሰነ የማረጋገጫ መመሪያ **[WEB-COOKIE-GUIDE.md](./WEB-COOKIE-GUIDE.md)**ን ይመልከቱ።
---
## ፈጣን ጅምር፦ የመጀመሪያ አቅራቢዎን ያገናኙ
### አማራጭ የመጀመሪያ አጠቃቀም የነፃ አቅራቢ ማዋቀር
የመጀመሪያ አጠቃቀም አዋቂው ግልጽ የሆነ **ነፃ አቅራቢዎችን ያዋቅሩ** ካርድ ያቀርባል። አሁን ብቁ የሆኑትን
ዝርዝር ከOmniRoute ማረጋገጫ የማይፈልጉ አቅራቢዎች መዝገብ ያዘጋጃል፤ ከዚያም ከማረጋገጥዎ በፊት እያንዳንዱን
አቅራቢ እንዲገመግሙና ምርጫውን እንዲያነሱ ያስችልዎታል። OmniRoute መጀመሪያ የሦስተኛ ወገን ውሎችን፣ ግላዊነትን፣ ተገኝነትን እና የአጠቃቀም መጠን ገደቦችን
እንዲገመግሙ የአቅራቢውን የጥንቃቄ ማስታወቂያ እና ወደ ጣቢያው የሚወስድ አገናኝ ያሳያል።
ይህ እርምጃ አማራጭ ነው፦ አዋቂውን መጨረስ በስውር የነፃ አቅራቢ ግንኙነቶችን አይፈጥርም።
አሁንም የሌሉትን አቅራቢዎች ብቻ ይፈጥራል፣ ነባር የተበጁ ግንኙነቶችን
ሳይነካ ይተዋል፣ እንዲሁም የተፈጠሩ፣ አስቀድመው የተዋቀሩ እና ያልተሳኩ አቅራቢዎችን በተናጠል ሪፖርት ያደርጋል። ከፊል ውጤት ከተገኘ በኋላ
ያልተሳኩትን ብቻ ያለስጋት እንደገና መሞከር ይችላሉ።
### አማራጭ A፦ ነፃ አቅራቢ (የብድር ካርድ አያስፈልግም)
1. ዳሽቦርዱን በ`http://localhost:20128` ይክፈቱ
2. ወደ **አቅራቢዎች** → **አቅራቢ ያክሉ** ይሂዱ
3. ከእነዚህ ነፃ አቅራቢዎች አንዱን ይምረጡ፦
- **Kiro AI** — ነፃ Claude ሞዴሎች (ማረጋገጫ አያስፈልግም)
- **OpenCode Free** — ነፃ GPT ሞዴሎች (ማረጋገጫ አያስፈልግም)
- **Pollinations** — ነፃ GPT-5፣ Claude፣ Gemini (ቁልፍ አያስፈልግም)
- **LongCat** — 10M ቶከኖች በነፃ (የአንድ ጊዜ ስጦታ፣ መለያ + KYC ያስፈልጋል)
- **Cloudflare AI** — 50+ ሞዴሎች፣ 10K ኒውሮኖች/ቀን
- **MLX Gemma 26B** — የአካባቢ Apple Silicon ሞዴል (~38.5 ቶከን/ሰከንድ፣ ~15.9GB RAM)
- **MLX Qwen 3.8 27B** — የአካባቢ Apple Silicon ሞዴል (~9.1 ቶከን/ሰከንድ፣ ~13.1GB RAM)
4. **አገናኝ**ን ጠቅ ያድርጉ
5. ተጠናቋል! አሁን ነፃ የAI መዳረሻ አለዎት።
### አማራጭ B፦ የAPI ቁልፍ አቅራቢ (የሚከፈልበት)
1. ከአቅራቢው ድረ-ገጽ API ቁልፍ ያግኙ፦
- **OpenAI**: https://platform.openai.com/api-keys
- **Anthropic**: https://console.anthropic.com/
- **Google**: https://aistudio.google.com/apikey
- **DeepSeek**: https://platform.deepseek.com/
- **Groq**: https://console.groq.com/
2. ዳሽቦርዱን በ`http://localhost:20128` ይክፈቱ
3. ወደ **አቅራቢዎች** → **አቅራቢ ያክሉ** ይሂዱ
4. አቅራቢዎን ይምረጡ
5. የAPI ቁልፍዎን ይለጥፉ
6. **አገናኝ**ን ጠቅ ያድርጉ
7. ተጠናቋል! አሁን የዚያ አቅራቢ ሞዴሎች መዳረሻ አለዎት።
### አማራጭ C፦ OAuth አቅራቢ (የደንበኝነት ምዝገባ)
1. ዳሽቦርዱን በ`http://localhost:20128` ይክፈቱ
2. ወደ **አቅራቢዎች** → **አቅራቢ ያክሉ** ይሂዱ
3. አቅራቢዎን ይምረጡ (ለምሳሌ፣ Claude Code፣ GitHub Copilot)
4. **በOAuth ይገናኙ**ን ጠቅ ያድርጉ
5. በመለያዎ ይግቡ
6. ተጠናቋል! አሁን የደንበኝነት ምዝገባዎ ሞዴሎች መዳረሻ አለዎት።
### አማራጭ D፦ የአካባቢ MLX ሞዴሎች (Apple Silicon)
የተዋሃደ ማህደረ ትውስታ ላላቸው Apple Silicon Mac ኮምፒውተሮች፣ OmniRoute በ`mlx-lm.server` በኩል እየሰሩ ካሉ የአካባቢ MLX ሞዴሎች ጋር እንደ መደበኛ OpenAI-ተኳሃኝ የአካባቢ አቅራቢዎች መገናኘትን ይደግፋል።
#### ቅድመ ሁኔታዎች
- **Apple Silicon Mac** (M1/M2/M3/M4)፤ 24GB+ የተዋሃደ ማህደረ ትውስታ ይመከራል
- **uv** የፓኬጅ አስተዳዳሪ፦ `curl -LsSf https://astral.sh/uv/install.sh | sh`
- **mlx-lm**: `uv pip install mlx-lm`
#### ፈጣን ጅምር
1. **ጥገኞችን ይጫኑ**፦
```bash
# uv አስቀድሞ ካልተጫነ ይጫኑ
curl -LsSf https://astral.sh/uv/install.sh | sh
# mlx-lmን ይጫኑ
uv pip install mlx-lm
```
2. **የMLX አገልጋዮችን በእጅ ያስጀምሩ** (በተለያዩ ተርሚናሎች)፦
```bash
# ተርሚናል 1፦ Gemma 4 26B A4B IT-QAT (ወደብ 11435)
uv run mlx_lm.server --model mlx-community/gemma-4-26B-A4B-it-qat-q4_0-mlx-aligned --port 11435 --host 127.0.0.1
# ተርሚናል 2፦ Qwen 3.8 27B MLX Mixed (ወደብ 11436)
uv run mlx_lm.server --model maglun/Qwen3.8-27B-MLX-Mixed-3.80bpw --port 11436 --host 127.0.0.1
```
3. **በOmniRoute ዳሽቦርድ ውስጥ ያገናኙ**፦
- ወደ **አቅራቢዎች** → **አቅራቢ ያክሉ** ይሂዱ
- **MLX Gemma 26B** ወይም **MLX Qwen 3.8 27B**ን ይምረጡ
- **አገናኝ**ን ጠቅ ያድርጉ (API ቁልፍ አያስፈልግም)
4. **ከOpenCode ጋር ይጠቀሙ**፦
```bash
# OpenCode OmniRouteን እንዲጠቀም ያዋቅሩ
opencode config set api.base_url http://localhost:20128/v1
opencode config set api.key <your-omniroute-api-key>
# የMLX ሞዴሎችን ይጠቀሙ
opencode run --model mlx-gemma/gemma-4-26b
opencode run --model mlx-qwen/qwen3.8-27b
```
#### የማህደረ ትውስታ አስተዳደር
**አስፈላጊ**፦ በ24GB የተዋሃደ ማህደረ ትውስታ፣ በአንድ ጊዜ **አንድ ትልቅ MLX ሞዴል ብቻ ሊሰራ ይችላል**።
- Gemma 26B፦ ~15.9GB ከፍተኛ የማህደረ ትውስታ አጠቃቀም
- Qwen 3.8 27B፦ ~13.1GB ከፍተኛ የማህደረ ትውስታ አጠቃቀም
ይህን በእጅ ማስተዳደር አለብዎት፦
- በአንድ ጊዜ አንድ MLX አገልጋይ ብቻ ያስኪዱ፣ ወይም
- ሁለቱንም በተለያዩ ማሽኖች ላይ ያስኪዱ፣ ወይም
- ሌላኛውን ከማስጀመርዎ በፊት አንዱን ያቁሙ
OmniRoute የMLX አገልጋይ ሂደቶችን በራስ-ሰር አያስተዳድርም — ጥያቄዎችን እርስዎ ወደሚያዋቅሯቸው OpenAI-ተኳሃኝ የመጨረሻ ነጥቦች ብቻ ይመራል።
#### የመሣሪያ ጥሪ ድጋፍ
ሁለቱም ሞዴሎች OpenAI-ተኳሃኝ የመሣሪያ ጥሪን ይደግፋሉ። በሚከተለው ይፈትሹ፦
```bash
curl -X POST http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-d '{
"model": "mlx-gemma/gemma-4-26b",
"messages": [{"role": "user", "content": "What is 2+2? Use the calculator tool."}],
"tools": [{"type": "function", "function": {"name": "calculator", "description": "Calculate", "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}}]
}'
```
#### የችግር መፍቻ
| ችግር | መፍትሔ |
| ------------------ | ------------------------------------------------------------------------ |
| ሰርቨሩ አይጀምርም | `uv run mlx_lm.server --help`ን ያረጋግጡ እና የሞዴል መለያዎቹን ያረጋግጡ |
| የማስታወሻ ቦታ አልቋል | አንድ ሞዴል ብቻ እየሰራ መሆኑን ያረጋግጡ፤ ሌሎች መተግበሪያዎችን ይዝጉ፤ Activity Monitorን ያረጋግጡ |
| ግንኙነት ተቀባይነት አላገኘም | ሰርቨሩ በትክክለኛው ወደብ (11435/11436) ላይ እየሰራ መሆኑን ያረጋግጡ |
| ምላሾች ዘገምተኛ ናቸው | የመጀመሪያው ጥያቄ ሞዴሉን ወደ ማስታወሻ ይጭናል (~30-60 ሰከንድ)፤ ቀጣዮቹ ጥያቄዎች ፈጣን ናቸው |
| የመሣሪያ ጥሪ አይሰራም | ሞዴሉ መሣሪያዎችን እንደሚደግፍ ያረጋግጡ፤ የትርጉም ስህተቶች ካሉ የOmniRoute ምዝግብ ማስታወሻዎችን ያረጋግጡ |
---
## ምርጥ ነፃ አቅራቢዎች
እነዚህ አቅራቢዎች የክሬዲት ካርድ ሳያስፈልግ **ነፃ መዳረሻ** ይሰጣሉ፦
| አቅራቢ | ነፃ ኮታ | ሞዴሎች | እንዴት እንደሚገናኙ |
| ----------------- | ------------- | ---------------------------------------- | -------------- |
| **Kiro AI** | በወር 50 ክሬዲቶች | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | ማረጋገጫ አያስፈልግም |
| **OpenCode Free** | ያልተገደበ | GPT-4o, Claude, Gemini | ማረጋገጫ አያስፈልግም |
| **Pollinations** | ቁልፍ አያስፈልግም | GPT-5, Claude, Gemini, DeepSeek, Llama 4 | ማረጋገጫ አያስፈልግም |
| **LongCat** | የአንድ ጊዜ 10M | LongCat-2.0 | API ቁልፍ + KYC |
| **Cloudflare AI** | በቀን 10K ኒውሮኖች | 50+ ሞዴሎች | ማረጋገጫ አያስፈልግም |
| **NVIDIA NIM** | ~40 RPM | 129 ሞዴሎች | API ቁልፍ ያስፈልጋል |
| **Cerebras** | ሲመዘገቡ $5 ክሬዲት | GLM 4.7, GPT-OSS 120B | API ቁልፍ + ካርድ |
| **Qoder** | ያልተገደበ | Kimi-K2, DeepSeek-R1, Qwen3-coder | ማረጋገጫ አያስፈልግም |
**ጠቃሚ ምክር**፦ በራስ-ሰር ወደ ተተኪ አቅራቢ በመቀየር **ያልተገደበ ነፃ AI** ለማግኘት በርካታ ነፃ አቅራቢዎችን ያገናኙ!
---
## ምርጥ የሚከፈልባቸው አቅራቢዎች
እነዚህ አቅራቢዎች በAPI ቁልፎች **ከፍተኛ ጥራት ያላቸው ሞዴሎችን** ይሰጣሉ፦
| አቅራቢ | ምርጥ ሞዴሎች | ወጪ | ነፃ ደረጃ |
| ------------- | --------------------------- | --------------------- | ------------------ |
| **OpenAI** | GPT-5, GPT-4o | ለ1M ቶከኖች $2.50-$10 | $5 ነፃ ክሬዲቶች |
| **Anthropic** | Claude Opus 4.6, Sonnet 4.6 | ለ1M ቶከኖች $3-$15 | $5 ነፃ ክሬዲቶች |
| **Google** | Gemini 2.5 Pro, Flash | ለ1M ቶከኖች $0.075-$1.25 | በቀን 1,500 ነፃ ጥያቄዎች |
| **DeepSeek** | DeepSeek V4 | ለ1M ቶከኖች $0.14-$0.28 | 5M ነፃ ቶከኖች |
| **Groq** | Llama 4, Mixtral | ለ1M ቶከኖች $0.05-$0.27 | 30 RPM ነፃ |
| **xAI** | Grok 3 | ለ1M ቶከኖች $0.30-$0.60 | — |
---
## አቅራቢን እንዴት ማገናኘት እንደሚቻል (ደረጃ በደረጃ)
### ደረጃ 1፦ ዳሽቦርዱን ይክፈቱ
በድር አሳሽዎ ወደ `http://localhost:20128` ይሂዱ።
### ደረጃ 2፦ ወደ አቅራቢዎች ይሂዱ
በጎን አሞሌው ውስጥ **አቅራቢዎች**ን ጠቅ ያድርጉ።
### ደረጃ 3፦ አቅራቢ አክልን ጠቅ ያድርጉ
የ**+ አቅራቢ አክል** አዝራሩን ጠቅ ያድርጉ።
### ደረጃ 4፦ አቅራቢዎን ይምረጡ
ዝርዝሩን ያስሱ ወይም አቅራቢዎን ይፈልጉ። ከዚያ በእሱ ላይ ጠቅ ያድርጉ።
### ደረጃ 5፦ የማረጋገጫ መረጃዎችን ያስገቡ
- **ነፃ አቅራቢዎች**፦ የማረጋገጫ መረጃ አያስፈልግም — **አገናኝ**ን ብቻ ጠቅ ያድርጉ
- **API ቁልፍ የሚጠቀሙ አቅራቢዎች**፦ የAPI ቁልፍዎን ይለጥፉ
- **OAuth አቅራቢዎች**፦ **በOAuth አገናኝ**ን ጠቅ ያድርጉና ይግቡ
### ደረጃ 6፦ ግንኙነቱን ይፈትሹ
መሥራቱን ለማረጋገጥ **ግንኙነትን ፈትሽ**ን ጠቅ ያድርጉ።
### ደረጃ 7፦ ተጠናቋል!
አሁን አቅራቢዎ ተገናኝቷል። በ`model: "auto"` ሊጠቀሙበት ወይም አቅራቢውን በቀጥታ ሊገልጹ ይችላሉ።
---
## በርካታ አቅራቢዎችን መጠቀም
OmniRoute **ከበርካታ አቅራቢዎች** ጋር በተሻለ ሁኔታ ይሠራል። ይህም የሚከተሉትን ይሰጥዎታል፦
- **በራስ-ሰር ወደ ተተኪ መቀየር** — አንድ አቅራቢ ካልሠራ፣ OmniRoute ቀጣዩን ይሞክራል
- **ወጪን ማመቻቸት** — OmniRoute ለእያንዳንዱ ጥያቄ በጣም ርካሹን አቅራቢ ይመርጣል
- **ፍጥነትን ማመቻቸት** — OmniRoute ለእያንዳንዱ ጥያቄ በጣም ፈጣኑን አቅራቢ ይመርጣል
- **ጥራትን ማመቻቸት** — OmniRoute ለእያንዳንዱ ተግባር ምርጡን አቅራቢ ይመርጣል
### የሚመከር ቅንብር
ምርጥ ተሞክሮ ለማግኘት ቢያንስ **3 አቅራቢዎችን** ያገናኙ፦
1. **አንድ ነፃ አቅራቢ** (Kiro, OpenCode Free, ወይም Pollinations) — ሁልጊዜ ዝግጁ
2. **አንድ ፈጣን አቅራቢ** (Groq, Cerebras) — ለፈጣን ምላሾች
3. **አንድ ጥራት ያለው አቅራቢ** (OpenAI, Anthropic, Google) — ለውስብስብ ተግባራት
ከዚያ `model: "auto"`ን ይጠቀሙ፤ OmniRouteም ለእያንዳንዱ ጥያቄ ምርጡን በራስ-ሰር ይመርጣል።
---
## ለእያንዳንዱ አቅራቢ የተለየ ማዋቀር
### OpenAI
1. የAPI ቁልፍ ያግኙ፦ https://platform.openai.com/api-keys
2. በOmniRoute ውስጥ፦ አቅራቢዎች → አቅራቢ ያክሉ → OpenAI
3. የAPI ቁልፉን ይለጥፉ → ያገናኙ
### Anthropic
1. የAPI ቁልፍ ያግኙ፦ https://console.anthropic.com/
2. በOmniRoute ውስጥ፦ አቅራቢዎች → አቅራቢ ያክሉ → Anthropic
3. የAPI ቁልፉን ይለጥፉ → ያገናኙ
### Google (Gemini)
1. የAPI ቁልፍ ያግኙ፦ https://aistudio.google.com/apikey
2. በOmniRoute ውስጥ፦ አቅራቢዎች → አቅራቢ ያክሉ → Gemini
3. የAPI ቁልፉን ይለጥፉ → ያገናኙ
### DeepSeek
1. የAPI ቁልፍ ያግኙ፦ https://platform.deepseek.com/
2. በOmniRoute ውስጥ፦ አቅራቢዎች → አቅራቢ ያክሉ → DeepSeek
3. የAPI ቁልፉን ይለጥፉ → ያገናኙ
### Groq
1. የAPI ቁልፍ ያግኙ፦ https://console.groq.com/
2. በOmniRoute ውስጥ፦ አቅራቢዎች → አቅራቢ ያክሉ → Groq
3. የAPI ቁልፉን ይለጥፉ → ያገናኙ
---
## የተለመዱ ጥያቄዎች
### "OmniRouteን ለመጠቀም መክፈል ያስፈልገኛል?"
**አይፈልግም!** OmniRoute ነፃ እና ክፍት ምንጭ ነው። ምንም ክፍያ ሳይከፍሉ ነፃ አቅራቢዎችን (Kiro, OpenCode Free, Pollinations) መጠቀም ይችላሉ። የሚከፈልባቸውን አቅራቢዎች ለመጠቀም ከመረጡ ብቻ ይከፍላሉ።
### "በየትኛው አቅራቢ መጀመር አለብኝ?"
በ**Kiro AI** ይጀምሩ — ነፃ ነው፣ የAPI ቁልፍ አያስፈልገውም፣ እና Claude ሞዴሎችን እንዲጠቀሙ ያስችልዎታል። ከዚያም እንደ አስፈላጊነቱ ተጨማሪ አቅራቢዎችን ያክሉ።
### "ብዙ አቅራቢዎችን በአንድ ጊዜ መጠቀም እችላለሁ?"
**አዎ!** የOmniRoute ዋና ዓላማ ይህ ነው። ብዙ አቅራቢዎችን ያገናኙ እና OmniRoute ለእያንዳንዱ ጥያቄ ምርጡን እንዲመርጥ `model: "auto"`ን ይጠቀሙ።
### "አንድ አቅራቢ መስራት ቢያቆምስ?"
OmniRoute ያልተሳኩ አቅራቢዎችን በራስ-ሰር ይዘላቸዋል እና ቀጣዩን ይሞክራል። እርስዎ ምንም ማድረግ አያስፈልግዎትም።
### "አቅራቢን እንዴት አለያያለሁ?"
ወደ አቅራቢዎች ይሂዱ → አቅራቢውን ጠቅ ያድርጉ → **ግንኙነት ያቋርጡ**ን ጠቅ ያድርጉ።
### "ነባር የAPI ቁልፎቼን መጠቀም እችላለሁ?"
**አዎ!** ቀድሞውኑ ለOpenAI፣ Anthropic፣ Google፣ ወዘተ የAPI ቁልፎች ካሉዎት፣ በOmniRoute ውስጥ ሊጠቀሙባቸው ይችላሉ። አቅራቢውን ሲያገናኙ ቁልፎቹን ብቻ ይለጥፉ።
---
## ቀጥሎ ምን አለ?
- **[የራስ-ሰር ጥምረት መመሪያ](./AUTO-COMBO-GUIDE.md)** — OmniRoute ምርጡን AI እንዲመርጥልዎት ያድርጉ
- **[የነፃ ደረጃዎች መመሪያ](./FREE-TIERS-GUIDE.md)** — ያለ ክሬዲት ካርድ ነፃ AI ያግኙ
- **[መላ ፍለጋ](../guides/TROUBLESHOOTING.md)** — የተለመዱ ችግሮችን ይፍቱ
- **[የአቅራቢዎች ማጣቀሻ](../reference/PROVIDER_REFERENCE.md)** — የ226 አቅራቢዎች ሙሉ ዝርዝር
## የCursor ምስሎች
የCursor ዕቅድ ምስሎች `IMAGE_PROVIDERS.cursor` (`cursor-agent-image`)ን ይጠቀማሉ። [CURSOR_IMAGE.md](../providers/CURSOR_IMAGE.md)ን ይመልከቱ።

190
docs/i18n/am/docs/getting-started/QUICK-START.md Normal file
View File

@@ -0,0 +1,190 @@
# Quick Start: Get OmniRoute Running in 3 Minutes (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../getting-started/QUICK-START.md) · 🇸🇦 [ar](../../../ar/docs/getting-started/QUICK-START.md) · 🇦🇿 [az](../../../az/docs/getting-started/QUICK-START.md) · 🇧🇬 [bg](../../../bg/docs/getting-started/QUICK-START.md) · 🇧🇩 [bn](../../../bn/docs/getting-started/QUICK-START.md) · 🇨🇿 [cs](../../../cs/docs/getting-started/QUICK-START.md) · 🇩🇰 [da](../../../da/docs/getting-started/QUICK-START.md) · 🇩🇪 [de](../../../de/docs/getting-started/QUICK-START.md) · 🇬🇷 [el](../../../el/docs/getting-started/QUICK-START.md) · 🇪🇸 [es](../../../es/docs/getting-started/QUICK-START.md) · 🇪🇪 [et](../../../et/docs/getting-started/QUICK-START.md) · 🇮🇷 [fa](../../../fa/docs/getting-started/QUICK-START.md) · 🇫🇮 [fi](../../../fi/docs/getting-started/QUICK-START.md) · 🇫🇷 [fr](../../../fr/docs/getting-started/QUICK-START.md) · 🇮🇪 [ga](../../../ga/docs/getting-started/QUICK-START.md) · 🇮🇳 [gu](../../../gu/docs/getting-started/QUICK-START.md) · 🇳🇬 [ha](../../../ha/docs/getting-started/QUICK-START.md) · 🇮🇱 [he](../../../he/docs/getting-started/QUICK-START.md) · 🇮🇳 [hi](../../../hi/docs/getting-started/QUICK-START.md) · 🇭🇷 [hr](../../../hr/docs/getting-started/QUICK-START.md) · 🇭🇺 [hu](../../../hu/docs/getting-started/QUICK-START.md) · 🇦🇲 [hy](../../../hy/docs/getting-started/QUICK-START.md) · 🇮🇩 [id](../../../id/docs/getting-started/QUICK-START.md) · 🇳🇬 [ig](../../../ig/docs/getting-started/QUICK-START.md) · 🇮🇹 [it](../../../it/docs/getting-started/QUICK-START.md) · 🇯🇵 [ja](../../../ja/docs/getting-started/QUICK-START.md) · 🇬🇪 [ka](../../../ka/docs/getting-started/QUICK-START.md) · 🇰🇭 [km](../../../km/docs/getting-started/QUICK-START.md) · 🇮🇳 [kn](../../../kn/docs/getting-started/QUICK-START.md) · 🇰🇷 [ko](../../../ko/docs/getting-started/QUICK-START.md) · 🇱🇹 [lt](../../../lt/docs/getting-started/QUICK-START.md) · 🇱🇻 [lv](../../../lv/docs/getting-started/QUICK-START.md) · 🇮🇳 [ml](../../../ml/docs/getting-started/QUICK-START.md) · 🇮🇳 [mr](../../../mr/docs/getting-started/QUICK-START.md) · 🇲🇾 [ms](../../../ms/docs/getting-started/QUICK-START.md) · 🇲🇹 [mt](../../../mt/docs/getting-started/QUICK-START.md) · 🇲🇲 [my](../../../my/docs/getting-started/QUICK-START.md) · 🇳🇵 [ne](../../../ne/docs/getting-started/QUICK-START.md) · 🇳🇱 [nl](../../../nl/docs/getting-started/QUICK-START.md) · 🇳🇴 [no](../../../no/docs/getting-started/QUICK-START.md) · 🇮🇳 [or](../../../or/docs/getting-started/QUICK-START.md) · 🇮🇳 [pa](../../../pa/docs/getting-started/QUICK-START.md) · 🇵🇭 [phi](../../../phi/docs/getting-started/QUICK-START.md) · 🇵🇱 [pl](../../../pl/docs/getting-started/QUICK-START.md) · 🇵🇹 [pt](../../../pt/docs/getting-started/QUICK-START.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/getting-started/QUICK-START.md) · 🇷🇴 [ro](../../../ro/docs/getting-started/QUICK-START.md) · 🇷🇺 [ru](../../../ru/docs/getting-started/QUICK-START.md) · 🇱🇰 [si](../../../si/docs/getting-started/QUICK-START.md) · 🇸🇰 [sk](../../../sk/docs/getting-started/QUICK-START.md) · 🇸🇮 [sl](../../../sl/docs/getting-started/QUICK-START.md) · 🇷🇸 [sr](../../../sr/docs/getting-started/QUICK-START.md) · 🇸🇪 [sv](../../../sv/docs/getting-started/QUICK-START.md) · 🇰🇪 [sw](../../../sw/docs/getting-started/QUICK-START.md) · 🇮🇳 [ta](../../../ta/docs/getting-started/QUICK-START.md) · 🇮🇳 [te](../../../te/docs/getting-started/QUICK-START.md) · 🇹🇭 [th](../../../th/docs/getting-started/QUICK-START.md) · 🇹🇷 [tr](../../../tr/docs/getting-started/QUICK-START.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/getting-started/QUICK-START.md) · 🇵🇰 [ur](../../../ur/docs/getting-started/QUICK-START.md) · 🇺🇿 [uz](../../../uz/docs/getting-started/QUICK-START.md) · 🇻🇳 [vi](../../../vi/docs/getting-started/QUICK-START.md) · 🇳🇬 [yo](../../../yo/docs/getting-started/QUICK-START.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/getting-started/QUICK-START.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/getting-started/QUICK-START.md)
---
> **በአጭሩ**: ይጫኑ → ነፃ አቅራቢን ያገናኙ → IDEዎን ወደ OmniRoute ያመልክቱ። ተጠናቋል።
---
## ደረጃ 1፦ OmniRouteን ይጫኑ
የሚመርጡትን ዘዴ ይምረጡ፦
### አማራጭ A፦ npm (የሚመከር)
```bash
npm install -g omniroute
```
### አማራጭ B፦ Docker
```bash
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest
```
`:latest` ከታተሙት የተረጋጉ SemVer ስሪቶች ከፍተኛው ነው። git `main`ን **አይከታተልም**። ለGitOps `diegosouzapw/omniroute:X.Y.Z`ን ይወስኑ። [የምስል መለያዎች / የልቀት ቻናሎች](../guides/DOCKER_GUIDE.md#release-channels)ን ይመልከቱ።
### አማራጭ C፦ ከምንጭ ኮድ
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install
npm run dev
```
---
## ደረጃ 2፦ OmniRouteን ያስጀምሩ
```bash
omniroute
```
OmniRoute በ`http://localhost:20128` ይጀምራል። ዳሽቦርዱ በራስ-ሰር ይከፈታል።
---
## ደረጃ 3፦ ነፃ አቅራቢን ያገናኙ
ነፃ አቅራቢን በማገናኘት OmniRouteን **ምንም ክፍያ ሳይከፍሉ** መጠቀም ይችላሉ።
### አማራጭ A፦ Kiro (ነፃ Claude — የክሬዲት ካርድ አያስፈልግም)
1. በ`http://localhost:20128` ያለውን ዳሽቦርድ ይክፈቱ
2. ወደ **አቅራቢዎች** → **አቅራቢ አክል** ይሂዱ
3. **Kiro AI**ን ይምረጡ
4. **አገናኝ**ን ጠቅ ያድርጉ (የAPI ቁልፍ አያስፈልግም!)
5. ተጠናቋል! አሁን የClaude ሞዴሎችን በነፃ መጠቀም ይችላሉ።
### አማራጭ B፦ OpenCode Free (ማረጋገጫ አያስፈልግም)
1. በ`http://localhost:20128` ያለውን ዳሽቦርድ ይክፈቱ
2. ወደ **አቅራቢዎች** → **አቅራቢ አክል** ይሂዱ
3. **OpenCode Free**ን ይምረጡ
4. **አገናኝ**ን ጠቅ ያድርጉ (የAPI ቁልፍ አያስፈልግም!)
5. ተጠናቋል! አሁን በርካታ ሞዴሎችን በነፃ መጠቀም ይችላሉ።
### አማራጭ C፦ Pollinations (ቁልፍ አያስፈልግም)
1. በ`http://localhost:20128` ያለውን ዳሽቦርድ ይክፈቱ
2. ወደ **አቅራቢዎች** → **አቅራቢ አክል** ይሂዱ
3. **Pollinations**ን ይምረጡ
4. **አገናኝ**ን ጠቅ ያድርጉ (የAPI ቁልፍ አያስፈልግም!)
5. ተጠናቋል! አሁን GPT-5፣ Claude፣ Gemini እና ሌሎችንም በነፃ መጠቀም ይችላሉ።
---
## ደረጃ 4፦ እንደሚሠራ ያረጋግጡ
ከ[API ቁልፎች](http://localhost:20128/dashboard/api-manager) አዲስ ቁልፍ ይፍጠሩ። ይህ ቁልፍ እንደገና ስለማይታይ በደህና ያስቀምጡት። ይህ ቁልፍ መሣሪያዎች OmniRouteን እንዲያገኙበት እንጂ የላይኛውን አቅራቢዎች ለመድረስ እንዳልሆነ ያስታውሱ።
```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```
ያገናኟቸው ሞዴሎች ተዘርዝረው መታየት አለባቸው።
---
## ደረጃ 5፦ IDEዎን ወይም CLIዎን ወደ OmniRoute ያመልክቱ
በIDEዎ ወይም በCLI መሣሪያዎ ውስጥ የሚከተሉትን ያዋቅሩ፦
```
Base URL: http://localhost:20128/v1
API Key: [copy from Dashboard → Endpoints]
Model: auto
```
ይኸው ነው! አሁን IDEዎ በራስ-ሰር የአቅራቢ ምርጫ ከሚያደርገው OmniRoute ጋር ይሠራል።
### የIDE ምሳሌ፦ VSCode/Continue.dev
1. በVSCode ውስጥ የ[Continue.dev](https://marketplace.visualstudio.com/items?itemName=Continue.continue) ቅጥያን ይጫኑ።
2. የሚከተሉትን መስመሮች ለማከል `~/.continue/config.yaml`ዎን ያዘምኑ፦
```
- name: OmniRoute - Auto
provider: openai
model: auto
apiBase: http://localhost:20128/v1
apiKey: <YOUR_KEY>
```
3. በContinue.dev የውይይት ፓነል ውስጥ `OmniRoute - Auto`ን ይምረጡ፤ ከዚያም ጥያቄዎችን ወደ OmniRoute ይልካሉ።
4. (አማራጭ) ለአንባቢው ልምምድ — IDEዎ በቅድሚያ በተገነቡት ሌሎች ውቅሮች በሙሉ `config.yaml`ን እንዲያዘምን ያድርጉ 😊
### የCLI ምሳሌ፦ Codex CLI
1. በክወና ስርዓትዎ ውስጥ የአካባቢ ተለዋዋጩን ቋሚ አድርገው ያዋቅሩ።
ለmacOS/Linux (ወደ `~/.bashrc` ወይም `~/.zshrc`ዎ ያክሉ)፦
```bash
export OMNIROUTE_API_KEY="<YOUR_KEY>"
```
ለWindows (Command Prompt)፦
```
setx OMNIROUTE_API_KEY <YOUR_KEY>
```
2. አሁን Codexን ለOmniRoute በተዋቀረ መልኩ እናስጀምር። ይህን ያስኪዱ፦
```
omniroute launch-codex --model auto
```
endpointን እና api keyን ለመወሰን `codex`ን እና የትዕዛዝ መስመር መለኪያዎችን በመጠቀም ይህንን በእጅ ማድረግ ይችላሉ፤ ነገር ግን ከላይ ባለው ትዕዛዝ OmniRoute ሁሉንም ነገር ያከናውንልዎታል።
ተመሳሳዩ የአንድ-ትዕዛዝ ማስጀመሪያ በአጠቃላይ ማስጀመሪያው በኩል ለሌሎች CLIዎችም ይሠራል — `omniroute run <target>`፣ `claude`፣ `codex`፣ `aider`፣ `goose`፣ `opencode`፣ `qwen` እና `gemini`ን ይደግፋል ([የCLI ውህደቶች](../guides/CLI-INTEGRATIONS.md)ን ይመልከቱ)።
3. አሁን CLIው ጥያቄዎችን ወደ OmniRoute መላክ አለበት።
### መሣሪያዎ ወደ OmniRoute እያስተላለፈ መሆኑን ያረጋግጡ
ከግራ የጎን አሞሌው [ክትትል/ምዝግብ ማስታወሻዎች](http://localhost:20128/dashboard/logs)ን ጠቅ በማድረግ የጥያቄውን ዝርዝር ማየት ይችላሉ። ወደ ውስጥ ጠቅ በማድረግ ተጨማሪ ዝርዝሮችን ያያሉ። በተጨማሪም ከሚወዱት harness ምን መረጃ እንደሚላክ ማየት ይችላሉ። ይህ ከትምህርት እና ከስህተት ማረም አንጻር ጠቃሚ ነው።
---
## ቀጥሎ ምን አለ?
- **[የAuto-Combo መመሪያ](./AUTO-COMBO-GUIDE.md)** — OmniRoute ምርጡን AI እንዲመርጥልዎ ያድርጉ
- **[የአቅራቢዎች መመሪያ](./PROVIDERS-GUIDE.md)** — ተጨማሪ አቅራቢዎችን (ነፃ እና የሚከፈልባቸውን) ያገናኙ
- **[የነፃ ደረጃዎች መመሪያ](./FREE-TIERS-GUIDE.md)** — የክሬዲት ካርድ ሳያስፈልግ ነፃ AI ያግኙ
- **[መላ ፍለጋ](../guides/TROUBLESHOOTING.md)** — የተለመዱ ችግሮችን ይፍቱ
---
## የተለመዱ ጥያቄዎች
### "የAPI ቁልፍ ያስፈልገኛል?"
**አይ!** ነፃ አቅራቢዎችን (Kiro፣ OpenCode Free፣ Pollinations) ያለምንም የAPI ቁልፍ መጠቀም ይችላሉ። በዳሽቦርዱ ውስጥ ብቻ ያገናኟቸው።
### "`auto` ምንድን ነው?"
`auto`፣ OmniRoute ለእያንዳንዱ ጥያቄ ምርጡን አቅራቢ በራስ-ሰር እንዲመርጥ ያዛል። ፍጥነትን፣ ወጪን፣ ጥራትን እና ተገኝነትን ከግምት ያስገባል። ለዝርዝሮች [የAuto-Combo መመሪያ](./AUTO-COMBO-GUIDE.md)ን ይመልከቱ።
### "ምን ያህል ያስከፍላል?"
OmniRoute ራሱ **ነፃ እና ክፍት ምንጭ** ነው። የሚከፍሉት ለሚጠቀሙባቸው አቅራቢዎች ብቻ ነው። ብዙ አቅራቢዎች ነፃ ደረጃዎች አሏቸው — [የነፃ ደረጃዎች መመሪያ](./FREE-TIERS-GUIDE.md)ን ይመልከቱ።
### "ከClaude Code / Cursor / Copilot ጋር መጠቀም እችላለሁ?"
**አዎ!** OmniRoute የOpenAI ቅርጸትን ከሚደግፍ ከማንኛውም መሣሪያ ጋር ይሠራል። base URLን ወደ `http://localhost:20128/v1` ብቻ ያዋቅሩ። ለተወሰኑ የማዋቀር መመሪያዎች [የCLI መሣሪያዎች መመሪያ](../reference/CLI-TOOLS.md)ን ይመልከቱ።
### "አንድ አቅራቢ ቢቋረጥስ?"
OmniRoute ያልተሳኩ አቅራቢዎችን በራስ-ሰር ይዘላል እና ቀጣዩን ይሞክራል። ምንም ነገር ማድረግ አያስፈልግዎትም። ለዝርዝሮች [የAuto-Combo መመሪያ](./AUTO-COMBO-GUIDE.md)ን ይመልከቱ።
---
## እገዛ ይፈልጋሉ?
- **[መላ ፍለጋ](../guides/TROUBLESHOOTING.md)** — የተለመዱ ችግሮች እና መፍትሔዎች
- **[Discord](https://discord.gg/U47eFqAXCn)** — የማኅበረሰብ ድጋፍ
- **[GitHub Issues](https://github.com/diegosouzapw/OmniRoute/issues)** — ስህተቶችን ሪፖርት ያድርጉ

195
docs/i18n/am/docs/getting-started/WEB-COOKIE-GUIDE.md Normal file
View File

@@ -0,0 +1,195 @@
# Web Cookie Providers (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../getting-started/WEB-COOKIE-GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇦🇿 [az](../../../az/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇩🇰 [da](../../../da/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇩🇪 [de](../../../de/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇬🇷 [el](../../../el/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇪🇸 [es](../../../es/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇪🇪 [et](../../../et/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇱 [he](../../../he/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇩 [id](../../../id/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇹 [it](../../../it/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇰🇭 [km](../../../km/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇲🇲 [my](../../../my/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇳🇴 [no](../../../no/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [or](../../../or/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇱🇰 [si](../../../si/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇮🇳 [te](../../../te/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇹🇭 [th](../../../th/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/getting-started/WEB-COOKIE-GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/getting-started/WEB-COOKIE-GUIDE.md)
---
Web Cookie አቅራቢዎች OmniRoute የAPI ቁልፍን ከመጠቀም ይልቅ በነባሩ የአሳሽ ክፍለ-ጊዜዎ በኩል የAI አገልግሎትን እንዲጠቀም ያስችሉታል። በድረ-ገጹ በኩል የአገልግሎቱ መዳረሻ ካለዎት እና OmniRoute ያንኑ ማንነቱ የተረጋገጠ ክፍለ-ጊዜ እንዲጠቀም ሲፈልጉ ጠቃሚ ናቸው።
ከAPI-key አቅራቢዎች በተለየ፣ Web Cookie አቅራቢዎች አሳሽዎ ወደ ድረ-ገጹ የሚልካቸውን የማረጋገጫ መረጃዎች በመጠቀም ማንነትን ያረጋግጣሉ።
---
# ከመጀመርዎ በፊት
> **አስፈላጊ፦** የማረጋገጫ መረጃዎችን ሁልጊዜ ከ**ቀጥታ የአውታረ መረብ ጥያቄ** ይቅዱ፤ ከአሳሽዎ cookie ማከማቻ **አይቅዱ**።
ብዙ የማንነት ማረጋገጫ ችግሮች የሚከሰቱት cookies ከተሳሳተ ቦታ በመቅዳት ነው።
## ከCookie ማከማቻ አይቅዱ
አብዛኛዎቹ አሳሾች የተከማቹ cookiesን በሚከተለው መንገድ ያሳያሉ፦
```
DevTools
→ Application (ወይም Storage)
→ Cookies
```
እነዚህ cookies ትክክል ቢመስሉም፣ ምናልባት፦
- ጊዜ ያለፈባቸው
- ያልተሟሉ
- በማንነት በተረጋገጡ ጥያቄዎች ላይ ብቻ የሚላኩ cookies የጎደሏቸው
ሊሆኑ ይችላሉ።
እነዚህን እሴቶች መጠቀም፣ ትክክል ቢመስሉም እንኳ፣ የማንነት ማረጋገጫ እንዳይሳካ ሊያደርግ ይችላል።
## ከቀጥታ ጥያቄ ይቅዱ
በምትኩ፣ ከተሳካ ጥያቄ የተገኙትን cookies ይጠቀሙ፦
```
DevTools
→ Network
→ ገጹን ያድሱ
→ የውይይት ወይም የንግግር ጥያቄ ይክፈቱ
→ Request Headers
→ Cookie
```
የ`Cookie` ጥያቄ ራስጌ አሳሽዎ በተሳካ ሁኔታ የተጠቀመበትን ትክክለኛ የማንነት ማረጋገጫ መረጃ ይዟል።
ለአብዛኛዎቹ Web Cookie አቅራቢዎች፣ ይህ ወደ OmniRoute መለጠፍ ያለበት እሴት ነው።
---
# አጠቃላይ ማዋቀር
ለአብዛኛዎቹ Web Cookie አቅራቢዎች የማዋቀር ሂደቱ ተመሳሳይ ነው።
1. ወደ አቅራቢው ድረ-ገጽ ይግቡ።
2. የአሳሹን Developer Tools ይክፈቱ።
3. የ**Network** ትርን ይክፈቱ።
4. ገጹን ያድሱ።
5. ማንነቱ የተረጋገጠ የውይይት ወይም የንግግር ጥያቄ ይክፈቱ።
6. የሚያስፈልጉትን የማረጋገጫ መረጃዎች ይቅዱ።
7. OmniRouteን ይክፈቱ።
8. ወደ **Providers → Add Provider** ይሂዱ።
9. የWeb Cookie አቅራቢዎን ይምረጡ።
10. የማረጋገጫ መረጃዎቹን ይለጥፉ።
11. **Test Connection**ን ጠቅ ያድርጉ።
12. አቅራቢውን ያስቀምጡ።
የሚያስፈልጉት ትክክለኛ የማረጋገጫ መረጃዎች እንደ አቅራቢው ይለያያሉ።
---
# የአቅራቢ የማረጋገጫ መረጃ ቅርጸቶች
የተለያዩ ድረ-ገጾች የማንነት ማረጋገጫን በተለያዩ መንገዶች ያከማቻሉ። አንዳንዶቹ cookies ብቻ ይፈልጋሉ፣ ሌሎች ግን ተጨማሪ ራስጌዎችን ወይም tokensን ሊፈልጉ ይችላሉ።
| አቅራቢ | የማረጋገጫ መረጃ ቅርጸት | የአቅራቢ መመሪያ |
| ------------------------------- | ----------------------------- | -------------------------------- |
| Claude Web | ሙሉ Cookie ጥያቄ ራስጌ | `docs/providers/CLAUDE_WEB.md` |
| ChatGPT Web (Codex) | ሙሉ Cookie ራስጌ | `docs/providers/CHATGPT_WEB.md` |
| Gemini Web | _(ያረጋግጡ)_ | |
| Copilot Web | _(ያረጋግጡ)_ | `docs/providers/COPILOT-M365.md` |
| Microsoft 365 Copilot (BizChat) | WS access_token + chathubPath | `docs/providers/COPILOT-M365.md` |
| Grok Web | _(ያረጋግጡ)_ | |
| ... | ... | ... |
> አዳዲስ Web Cookie አቅራቢዎች ሲጨመሩ ወይም የነባር አቅራቢዎች የማንነት ማረጋገጫ መስፈርቶች ሲቀየሩ ይህን ሰንጠረዥ ያዘምኑ።
---
# Web Cookie አቅራቢዎች ምን ማድረግ ይችላሉ እና ምን ማድረግ አይችሉም
Web Cookie አቅራቢዎች የድረ-ገጽን የውይይት በይነገጽ እንደገና ይጠቀማሉ። ከይፋዊ APIs ጋር ተመሳሳይ ችሎታዎችን **አይሰጡም**።
## የሚደገፉ
- ነባሩን የአሳሽ ክፍለ-ጊዜዎን በመጠቀም ማንነትን ማረጋገጥ
- በመለያዎ በኩል የሚገኙ ሞዴሎችን መድረስ
- የውይይት ምላሾችን በዥረት መቀበል
- የAPI ቁልፍ አያስፈልግም
## የማይደገፉ
- የፈንክሽን ጥሪ
- የመሣሪያ ጥሪ
- ራስ-ሰር የፋይል አርትዖት
- በወኪል የሚከናወኑ የIDE የሥራ ፍሰቶች
- በAPI ብቻ የሚገኙ ባህሪያት
ይህ የሚጠበቅ ባህሪ ነው እና ስህተት **አይደለም**።
የመሣሪያ አፈጻጸም፣ ራስ-ሰር የፋይል አርትዖት ወይም ሌሎች የወኪል የሥራ ፍሰቶች ካስፈለጉዎት፣ ከWeb Cookie አቅራቢ ይልቅ **API-key አቅራቢ** ይጠቀሙ።
---
# የማረጋገጫ ገደብ
የተሳካ **Test Connection** ወይም የcookie ማረጋገጫ፣ የቀረቡት የማረጋገጫ መረጃዎች በሚጠበቀው ቅርጸት ያሉ መሆናቸውን ብቻ ያረጋግጣል።
Issue #7857 እስኪፈታ ድረስ፣ የተሳካ ማረጋገጫ አቅራቢው በተሳካ ሁኔታ ማንነትን እንደሚያረጋግጥ **ዋስትና አይሰጥም**።
የማንነት ማረጋገጫ አሁንም ካልተሳካ፣ የማረጋገጫ መረጃዎቹን ከአሳሽ cookie ማከማቻ ሳይሆን ከቀጥታ የአውታረ መረብ ጥያቄ መቅዳትዎን ያረጋግጡ።
---
# መላ ፍለጋ
## የማንነት ማረጋገጫ አልተሳካም
የማረጋገጫ መረጃዎቹ ከሚከተለው መቅዳታቸውን ያረጋግጡ፦
```
Network
→ Request Headers
→ Cookie
```
እና ከሚከተለው **አለመቅዳታቸውን** ያረጋግጡ፦
```
Application
→ Cookies
```
---
## Cookie በአሳሽ ውስጥ ይሠራል፣ ነገር ግን በOmniRoute ውስጥ አይሠራም
አንዳንድ አቅራቢዎች በማንነት በተረጋገጡ ጥያቄዎች ወቅት ብቻ የሚላኩ cookiesን ያካትታሉ።
አንድን ንግግር በተሳካ ሁኔታ ከከፈቱ በኋላ፣ የማረጋገጫ መረጃዎቹን ከአዲስ የአውታረ መረብ ጥያቄ እንደገና ይቅዱ።
---
## ክፍለ-ጊዜው ጊዜው አልፏል
Web Cookie አቅራቢዎች ነባሩን የአሳሽ ክፍለ-ጊዜዎን ይጠቀማሉ።
የአሳሽ ክፍለ-ጊዜዎ ጊዜው ካለፈ ወይም ከመለያዎ ከወጡ፣ አዲስ የማረጋገጫ መረጃዎችን መቅዳት አለብዎት።
---
## Test Connection ይሳካል፣ ነገር ግን ጥያቄዎች አይሳኩም
Issue #7857 እስኪፈታ ድረስ፣ ማረጋገጫውን ማለፍ የማንነት ማረጋገጫ ጥያቄው እንደሚሳካ ዋስትና አይሰጥም።
ተጨማሪ መላ ፍለጋ ከማድረግዎ በፊት፣ የማረጋገጫ መረጃዎችዎን ከአዲስ ማንነቱ የተረጋገጠ ጥያቄ እንደገና ይቅዱ።
---
# የአቅራቢ ምሳሌ
አንድን አቅራቢ የሚመለከት የተሟላ ደረጃ-በደረጃ መመሪያ ለማየት፦
- **Claude Web** — `docs/providers/CLAUDE_WEB.md`
ይመልከቱ።
የClaude Web መመሪያ ለWeb Cookie አቅራቢ የተሟላውን የማዋቀር ሂደት ያሳያል እና እንደ ማጣቀሻ አተገባበር ያገለግላል።
---
# ምርጥ ልምዶች
- የማረጋገጫ መረጃዎችን ከአዲስ ማንነቱ የተረጋገጠ ጥያቄ ይቅዱ።
- የቆዩ cookiesን እንደገና ከመጠቀም ይቆጠቡ።
- Web Cookie አቅራቢዎችን በሚጠቀሙበት ጊዜ የአሳሽ ክፍለ-ጊዜዎን ንቁ አድርገው ያቆዩ።
- የተቀዱ cookiesን እንደ ሚስጥራዊ የማረጋገጫ መረጃዎች ይያዙ።
- የፈንክሽን ጥሪ ወይም የወኪል የሥራ ፍሰቶች ሲያስፈልጉዎት API-key አቅራቢዎችን ይጠቀሙ።

276
docs/i18n/am/docs/guides/ANTIGRAVITY-ONBOARDING.md Normal file
View File

@@ -0,0 +1,276 @@
# OmniRoute Antigravity (Google One AI) Onboarding Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/ANTIGRAVITY-ONBOARDING.md) · 🇸🇦 [ar](../../../ar/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇦🇿 [az](../../../az/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇧🇬 [bg](../../../bg/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇧🇩 [bn](../../../bn/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇨🇿 [cs](../../../cs/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇩🇰 [da](../../../da/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇩🇪 [de](../../../de/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇬🇷 [el](../../../el/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇪🇸 [es](../../../es/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇪🇪 [et](../../../et/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇷 [fa](../../../fa/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇫🇮 [fi](../../../fi/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇫🇷 [fr](../../../fr/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇪 [ga](../../../ga/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [gu](../../../gu/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇳🇬 [ha](../../../ha/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇱 [he](../../../he/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [hi](../../../hi/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇭🇷 [hr](../../../hr/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇭🇺 [hu](../../../hu/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇦🇲 [hy](../../../hy/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇩 [id](../../../id/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇳🇬 [ig](../../../ig/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇹 [it](../../../it/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇯🇵 [ja](../../../ja/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇬🇪 [ka](../../../ka/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇰🇭 [km](../../../km/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [kn](../../../kn/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇰🇷 [ko](../../../ko/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇱🇹 [lt](../../../lt/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇱🇻 [lv](../../../lv/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [ml](../../../ml/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [mr](../../../mr/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇲🇾 [ms](../../../ms/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇲🇹 [mt](../../../mt/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇲🇲 [my](../../../my/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇳🇵 [ne](../../../ne/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇳🇱 [nl](../../../nl/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇳🇴 [no](../../../no/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [or](../../../or/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [pa](../../../pa/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇵🇭 [phi](../../../phi/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇵🇱 [pl](../../../pl/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇵🇹 [pt](../../../pt/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇷🇴 [ro](../../../ro/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇷🇺 [ru](../../../ru/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇱🇰 [si](../../../si/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇸🇰 [sk](../../../sk/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇸🇮 [sl](../../../sl/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇷🇸 [sr](../../../sr/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇸🇪 [sv](../../../sv/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇰🇪 [sw](../../../sw/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [ta](../../../ta/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇮🇳 [te](../../../te/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇹🇭 [th](../../../th/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇹🇷 [tr](../../../tr/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇵🇰 [ur](../../../ur/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇺🇿 [uz](../../../uz/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇻🇳 [vi](../../../vi/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇳🇬 [yo](../../../yo/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/ANTIGRAVITY-ONBOARDING.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/ANTIGRAVITY-ONBOARDING.md)
---
> **የሚያገኙት**፦ በGoogle One AI Pro የደንበኝነት ምዝገባዎ በኩል Gemini 3.1 Pro፣ Gemini 3.7 Flash፣ Claude Sonnet 4.6 እና ሌሎች ሞዴሎችን መጠቀም — እንደ አንድ ወጥ መግቢያ በር በOmniRoute በኩል የሚተላለፉ።
**ይፋዊ ማጣቀሻዎች**፦
- [Google Antigravity](https://antigravity.google) — የምርቱ መነሻ ገጽ
- [Antigravity ዕቅዶች እና ዋጋ](https://antigravity.google/pricing) — የደንበኝነት ምዝገባ ደረጃዎች
- [Antigravity ሰነዶች፦ ዕቅዶች](https://antigravity.google/docs/plans) — የመሠረታዊ ኮታ ዝርዝሮች
- [Google One AI ዕቅዶች](https://one.google.com/about/google-ai-plans/) — የGoogle One የደንበኝነት ምዝገባ ንጽጽር
- [Antigravity CLI ብሎግ](https://antigravity.google/blog/introducing-google-antigravity-cli) — የCLI ማስታወቂያ
---
## 1. Antigravity ከAntigravity CLI (agy) ጋር
ሁለቱም አቅራቢዎች **ተመሳሳዩን የGoogle የኋላ ስርዓት** ይጋራሉ — አንድ ዓይነት OAuth ደንበኛ፣ የቶከን እድሳት፣ የመጨረሻ ነጥቦች እና የGoogle መለያዎች። ልዩነቱ የሚያዩዋቸው ሞዴሎች ናቸው።
> የGoogleን ይፋዊ ንጽጽር ለማየት [የAntigravity CLI ማስታወቂያን](https://antigravity.google/blog/introducing-google-antigravity-cli) ይመልከቱ።
| ገጽታ | `antigravity` (IDE) | `agy` (CLI) |
| ------------------ | ------------------------------------------ | ------------------------------------------------- |
| **የGoogle ምርት** | Antigravity 2.0 / Antigravity IDE | Antigravity CLI |
| **የኋላ ስርዓት** | ተመሳሳዩ Google Cloud Code API | ተመሳሳዩ Google Cloud Code API |
| **OAuth / ቶከን** | ተመሳሳይ ደንበኛ፣ ተመሳሳይ እድሳት | ተመሳሳይ ደንበኛ፣ ተመሳሳይ እድሳት |
| **የሞዴል ካታሎግ** | ቋሚ የተመረጠ ዝርዝር (በOmniRoute ውስጥ በቋሚነት የተቀመጠ) | `:fetchAvailableModels`ን በመጠቀም ከGoogle በቀጥታ የሚፈተሽ |
| **Claude ሞዴሎች** | Sonnet 4.6፣ Opus 4.6 (እያንዳንዳቸው 4 ልዩነቶች) | Sonnet 4.6፣ Opus 4.6 (እያንዳንዳቸው 4 ልዩነቶች) |
| **የGemini አሰያየም** | ግልጽ መለያዎች (Low/Medium/High) | የต้น ምንጭ IDs (extra-low/low/agent) |
| **ተጨማሪ ሞዴሎች** | `gpt-oss-120b-medium` | ከGoogle የሚቀርቡ ተጨማሪ ሞዴሎችን ሊያካትት ይችላል |
| **ነባሪ የአጠቃቀም ሁኔታ** | የIDE ውህደት (VS Code፣ JetBrains) | የCLI / API መዳረሻ |
| **ኮታ** | ከagy ጋር የጋራ (ተመሳሳዩ Google መለያ) | ከantigravity ጋር የጋራ (ተመሳሳዩ Google መለያ) |
**የሚገኙ ሞዴሎች (በሙከራ የተረጋገጡ፣ 2026-07-29)**፦
- Gemini፦ 3.6 Flash፣ 3.5 Flash፣ 3.1 Pro፣ 3 Flash፣ 2.5 Flash (የተለያዩ የማሰብ ደረጃዎች)
- Claude፦ Sonnet 4.6፣ Opus 4.6 (እያንዳንዳቸው default/low/medium/high ልዩነቶች ያሏቸው)
- ሌላ፦ GPT-OSS 120B Medium
- **Claude Sonnet 5 አይገኝም** — የሚደገፉት የ4.6 ልዩነቶች ብቻ ናቸው
**የሞዴል ካታሎጉ የሚለያይበት ምክንያት**፦ የGoogle CLI «ለፍጥነት እና ለዝቅተኛ ተጨማሪ ጭነት የተመቻቸ» እና «ከGemini ሞዴሎች ጋር በጋራ የተመቻቸ» ነው (በGoogle ይፋዊ ብሎግ መሠረት)። የWeb/IDE ምርቱ «ለሁሉን አቀፍነት የተመቻቸ» ነው። CLI ሞዴሎችን በተለዋዋጭ ሁኔታ ለማግኘት `:fetchAvailableModels`ን ይጠቀማል፣ IDE ግን ቋሚ የተመረጠ ዝርዝር ይጠቀማል።
**በተግባር**፦ ለGemini ሞዴሎች `agy/` ቅድመ ቅጥያን ይጠቀሙ (ለምሳሌ `agy/gemini-3.7-flash-high`)። ለቋሚው የተመረጠ ዝርዝር `antigravity/`ን ይጠቀሙ። ሁለቱም ተመሳሳዩን የGoogle የኋላ ስርዓት ይጠቀማሉ፣ ነገር ግን የተለያዩ የሞዴል አሰያየሞችን ያቀርባሉ። ኮታው የጋራ ነው — ከሁለቱ አቅራቢዎች አንዱን መጠቀም በተመሳሳዩ የGoogle መለያ ገደቦች ላይ ይቆጠራል።
---
## 2. Google One AI Pro፡ የኮታ ስርዓት
> ስለ ይፋዊ የኮታ ዝርዝሮች [Antigravity Docs: Plans](https://antigravity.google/docs/plans)ን፣ ስለ አዳዲስ የዋጋ ለውጦች ደግሞ [Changes to Antigravity Plans](https://antigravity.google/blog/changes-to-antigravity-plans)ን ይመልከቱ።
Google Antigravity በመልዕክት ብዛት ሳይሆን በ"የተሰራ ሥራ" (የስሌት ክብደት) ላይ የተመሠረተ **ባለሁለት-ደረጃ ኮታ** ይጠቀማል።
### ሁለቱ ደረጃዎች
| ደረጃ | ምንነቱ | የማደስ ዑደት |
| ----------------- | -------------------------------- | ---------------------------------------------------------- |
| **የ5-ሰዓት ፈጣን ዙር** | ወዲያውኑ ጥቅም ላይ የሚውል የ"ተሰራ ሥራ" ክምችት | በአንድ ክፍለ ጊዜ ውስጥ ከመጀመሪያው ጥያቄ በኋላ በ5 ሰዓት ዳግም ይጀመራል |
| **የ7-ቀን መነሻ ገደብ** | ጥብቅ ሳምንታዊ ከፍተኛ ገደብ | ከተደረሰበት የ5-ሰዓት ማደሱን ይሽራል፤ እስከሚቀጥለው የ7-ቀን ጊዜ ድረስ መዳረሻን ይዘጋል |
**"የተሰራ ሥራ" እንዴት እንደሚሰላ**፡ ከፍተኛ የወኪል አጠቃቀም ያላቸው ተግባራት (ለምሳሌ፣ "ይህን ሙሉ repository እንደገና አዋቅር") ከቀላል ተግባራት (ለምሳሌ፣ "ይህን function አስተካክል") ይልቅ ኮታውን በፍጥነት ይጠቀማሉ። ፍጆታን የሚያሳይ ቅጽበታዊ dashboard የለም።
### የዕቅድ ደረጃዎች
| ዕቅድ | ዋጋ | ኮታ | ሳምንታዊ ገደብ |
| ------------ | ---------- | ----------------------------- | ------------------------------ |
| ነጻ | $0 | በቂ ኮታ፣ በየሳምንቱ የሚታደስ | አዎ |
| AI Pro | $19.99/mo | ከፍተኛ ኮታ፣ በየ5 ሰዓቱ የሚንከባለል እድሳት | አዎ (ከተደረሰበት የ5-ሰዓት እድሳቱን ይሽራል) |
| AI Ultra 5x | $99.99/mo | የPro ኮታ 5x | ሳምንታዊ ገደብ የለም |
| AI Ultra 20x | $199.99/mo | የPro ኮታ 20x | ሳምንታዊ ገደብ የለም |
### Gemini እና Gemini ያልሆኑ ሞዴሎች
- **Gemini ሞዴሎች** (Flash + Pro)፡ በAPI ዋጋ አሰጣጥ መሠረት የሚቀነስ አንድ የጋራ የፍጥነት ገደብ ይጠቀማሉ። Flash ከPro 8x ርካሽ ከሆነ፣ 8x ተጨማሪ የFlash ቶከኖችን ያገኛሉ።
- **Gemini ያልሆኑ ሞዴሎች** (Claude, GPT-OSS)፡ **የተለያዩ** የፍጥነት ገደቦች አሏቸው። Gemini በተዘጋበት ጊዜም እንኳ ሊገኙ ይችላሉ።
### AI ክሬዲቶች (ከገደብ በላይ አጠቃቀም)
> ክሬዲቶች እንዴት እንደሚሰሩ ለማወቅ [Google One AI credits](https://support.google.com/googleone/answer/14534406)ን ይመልከቱ።
የመነሻ ኮታው ሙሉ በሙሉ ጥቅም ላይ ሲውል፦
- **በፍጹም**፡ ኮታው እስኪታደስ ይጠብቁ፤ "Baseline model quota reached" የሚለውን ያሳያል
- **ሁልጊዜ**፡ AI ክሬዲቶችን በራስ-ሰር ይጠቀሙ፤ የመነሻ ኮታው ሲታደስ ወደ እሱ ይመለሳል
ክሬዲቶች በተናጠል ይገዛሉ፣ በመደበኛው የAPI ዋጋ አሰጣጥም ይቀነሳሉ።
### ቁልፍ ዝርዝሮች
- ኮታው **በመለያ ደረጃ የጋራ ነው** — በAntigravity IDE፣ CLI እና OmniRoute ውስጥ ያለው ተመሳሳይ Google መለያ አንድ የኮታ ክምችት ይጋራል
- እያንዳንዱ Google መለያ የራሱ ነጻ ኮታ አለው — በርካታ መለያዎች = በርካታ የኮታ ክምችቶች
- AI Pro ተጠቃሚዎች ሳምንታዊው የመነሻ ገደብ ላይ ሲደረስ ከ5-ሰዓት ዳግም ማስጀመር ይልቅ **የ7-ቀን መዘጋት** እንደገጠማቸው ሪፖርት አድርገዋል (Google ይህ ለከፍተኛ ፍላጎት ሆን ተብሎ የተነደፈ መሆኑን አረጋግጧል)
**የመለያዎ ኮታ ሲያልቅ**፡ OmniRoute በcombo route ውስጥ በሚቀጥለው ዝግጁ መለያ በራስ-ሰር እንደገና ይሞክራል። በእጅ ጣልቃ መግባት አያስፈልግም።
---
## 3. projectIdን እንዴት ማግኘት እንደሚቻል
እያንዳንዱ antigravity/agy ግንኙነት የGoogle Cloud Code `projectId` ያስፈልገዋል። ያለእሱ፣ `/v1internal:models` endpoint 404 ይመልሳል።
### ዘዴ A፡ ራስ-ሰር (የሚመከር)
OmniRoute ይህን በራስ-ሰር ያከናውናል። በDashboard OAuth በኩል አዲስ Google መለያ ሲያክሉ፦
1. OmniRoute ቶከኑን ያድሳል
2. projectIdን ለማግኘት `loadCodeAssist`ን ይጠራል
3. ምንም project ከሌለ፣ አንድ ለመፍጠር `onboardUser`ን ይጠራል
4. አዲስ የተፈጠረውን projectId ለማግኘት `loadCodeAssist`ን እንደገና ይሞክራል
5. ወደ database ያስቀምጠዋል
**ይህ ለአብዛኞቹ መለያዎች ይሰራል** — ምንም በእጅ የሚከናወን ደረጃ አያስፈልግም።
### ዘዴ B፡ በagy CLI በኩል በእጅ
ራስ-ሰር ማግኘቱ ካልተሳካ (ይህ መቼ እንደሚከሰት ክፍል 5ን ይመልከቱ)፦
```bash
# agy CLIን ይጫኑ (አስቀድሞ ካልተጫነ)
npm install -g @anthropic-ai/agy
# በGoogle መለያዎ ይግቡ
agy login
# ማስጀመር የሚያስፈልገውን መለያ ይምረጡ
# ይህ Cloud Code ምዝገባን ያስጀምርና projectId ይመድባል
```
`agy login` በተሳካ ሁኔታ ከተጠናቀቀ በኋላ፣ በOmniRoute Dashboard ውስጥ ቶከኑን ያድሱ። projectId በራስ-ሰር ይገኛል።
### እንዴት ማረጋገጥ እንደሚቻል
databaseን ይፈትሹ፦
```bash
# በOmniRoute container ውስጥ
node -e "const db=require('better-sqlite3')('/app/data/storage.sqlite'); \
console.log(JSON.stringify(db.prepare(\
'SELECT email,project_id FROM provider_connections WHERE provider=\"agy\"'\
).all(), null, 2))"
```
ወይም logsን ይፈትሹ፦
```
podman logs omniroute 2>&1 | grep "projectId discovered"
```
---
## 4. OAuth የማዞሪያ URI
### ችግሩ
Google OAuth ትክክለኛ የማዞሪያ URI ይፈልጋል። የOmniRoute ነባሪ ቅንብር `http://127.0.0.1:20128/callback` (loopback) ይጠቀማል። ይህ ለአካባቢያዊ ግንባታዎች ይሠራል፣ ነገር ግን **ለርቀት ማሰማራቶች አይሠራም** (ለምሳሌ፣ በLAN IP በኩል የሚደረስበት ሰርቨር)።
Google የሚከተሉትን የማዞሪያ URIዎች ውድቅ ያደርጋል፦
- IP አድራሻዎችን የሚጠቀሙ (`.com`፣ `.org`፣ ወዘተ. የሚያልቅ ዶሜይን መሆን አለበት)
- በOAuth ደንበኛ ውቅር ውስጥ ከተመዘገቡት የማዞሪያ URIዎች ጋር የማይዛመዱ
### መፍትሔው
**አማራጭ A፦ አብሮ የተካተተውን OAuth ፍሰት ይጠቀሙ (ነባሪ)**
- OmniRouteን ከ`localhost` ወይም `127.0.0.1` ሲደርሱበት ይሠራል
- ምንም ውቅር አያስፈልግም
**አማራጭ B፦ ብጁ OAuth ማረጋገጫዎች**
- በአካባቢዎ ውስጥ `ANTIGRAVITY_OAUTH_CLIENT_TYPE=web` ያዘጋጁ
- የራስዎን Google OAuth ማረጋገጫዎች ያቅርቡ፦
```
GOOGLE_OAUTH_CLIENT_ID=your-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
```
- በGoogle Cloud Console ውስጥ `https://your-domain.com/callback`ን እንደ ተፈቀደ የማዞሪያ URI ይመዝግቡ
**አማራጭ C፦ ለመጀመሪያ መግቢያ agy CLIን ይጠቀሙ**
- OmniRouteን በሚደርስበት ማሽን ላይ `agy login`ን ያስኪዱ
- የOAuth ፍሰቱ በአካባቢው ይጠናቀቃል፣ ቶከኖችም ይከማቻሉ
- በDashboard በኩል ግንኙነቱን ወደ OmniRoute ያስመጡ
### ገደቦች
- ብጁ OAuth ማረጋገጫዎች የዶሜይን ስም ይፈልጋሉ (Google IP አድራሻዎችን እንደ የማዞሪያ URIዎች አይቀበልም)
- ዶሜይን ከሌለዎት፣ በምትኩ አማራጭ A ወይም Cን ይጠቀሙ
---
## 5. ችግር መፍታት፦ ራስ-ሰር ማዋቀር ሳይሳካ ሲቀር
OmniRoute ለአብዛኛዎቹ መለያዎች የprojectId ፍለጋን እና የመጀመሪያ ምዝገባን በራስ-ሰር ያስተናግዳል። ይህ ሳይሳካ ሲቀር፣ ዋናው ምክንያት ብዙውን ጊዜ ከሚከተሉት አንዱ ነው፦
### የመለያው ክልል ታግዷል
**ምልክት**፦ `agy login` "Eligibility check failed: Your current account is not eligible for Antigravity, because it is not currently available in your location." የሚል መልዕክት ይመልሳል።
**ዋና ምክንያት**፦ Google መለያዎች በምዝገባ ጊዜ የሚዘጋጅ የጀርባ ስርዓት "Country Association" መስክ አላቸው። agy CLI እና Cloud Code API ይህን መስክ በጥብቅ ይፈትሻሉ — የድር Gemini ግን የአሁኑን IPዎን ብቻ ይፈትሻል።
> ከመለያዎ ጋር የተያያዘውን ክልል ለመፈተሽ ወይም ለመለወጥ፣ [Google Country Association Form](https://policies.google.com/country-association-form)ን ይጎብኙ።
**የድር Gemini ለምን ይሠራል፣ agy ግን ለምን አይሠራም**፦
- የድር Gemini / Google One፦ የአሁኑን IP ብቻ ይፈትሻል (proxy ያልፋል)
- agy CLI / Cloud Code API፦ የጀርባ ስርዓቱን Country Association መስክ ያነባል (proxy አይረዳም)
**መፍትሔ**፦
1. በUS IP ላይ ሆነው [Google Country Association Form](https://policies.google.com/country-association-form)ን ይጎብኙ
2. የክልል ለውጥ ጥያቄ ያስገቡ ("I live in a different country"ን ይምረጡ)
3. Google ጥያቄውን እስኪያስኬድ እና የኢሜይል ማሳወቂያ እስኪልክ ከ1-24 ሰዓታት ይጠብቁ
4. ከዚያ `agy login` ሊሳካ ይገባል
### መለያው Cloud Code ፕሮጀክት የለውም
**ምልክት**፦ ምዝግቦቹ `loadCodeAssist returned no project id` እና `onboardUser failed (400)` ያሳያሉ።
**ዋና ምክንያት**፦ መለያው ከዚህ በፊት በGoogle Cloud Code ተመዝግቦ አያውቅም፣ እና ራስ-ሰር የመጀመሪያ ምዝገባው አልተሳካም።
**መፍትሔ**፦ የCloud Code ምዝገባን ለማስጀመር `agy login`ን በእጅ ያስኪዱ፣ ከዚያም በOmniRoute Dashboard ውስጥ ቶከኑን ያድሱ።
### ቶከኑ ጊዜው አልፏል ወይም ተሰርዟል
**ምልክት**፦ በምዝግቦች ውስጥ የ401 ስህተቶች፣ ወይም "Token has expired" መልዕክቶች ይታያሉ።
**መፍትሔ**፦ ቶከኑን በDashboard → Providers → agy → የማደሻ አዶን ጠቅ ያድርጉ በሚለው መንገድ ያድሱ። የማደሻ ቶከኑ ራሱ ከተሰረዘ፣ በOAuth በኩል እንደገና ማረጋገጥ ያስፈልግዎታል።
---
## የውሳኔ ፍሰት ሰንጠረዥ
```
መለያው አይሰራም?
│
├─ በውሂብ ጎታው ውስጥ projectId አለው?
│ ├─ አዎ → ችግሩ ሌላ ቦታ ነው (ቶከኑ ጊዜው አልፏል፣ የጥያቄ መጠን ገደብ፣ ወዘተ.)
│ └─ የለም ↓
│
├─ የመለያው የአገር ግንኙነት ወደ ተከለከለ ክልል ተቀናብሯል?
│ ├─ አዎ → በGoogle የአገር ግንኙነት ቅጽ ላይ ክልሉን ይቀይሩ
│ │ (https://policies.google.com/country-association-form)
│ │ ከ1-24 ሰዓታት ይጠብቁ፣ ከዚያ እንደገና ይሞክሩ
│ └─ የለም ↓
│
├─ መለያው የGoogle One AI Pro ደንበኝነት አለው?
│ ├─ የለውም → መጀመሪያ በone.google.com ይመዝገቡ
│ └─ አለው ↓
│
├─ ራስ-ሰር ፍለጋን ይሞክሩ (በዳሽቦርዱ ውስጥ ቶከኑን ያድሱ)
│ ├─ ይሰራል → ተጠናቋል
│ └─ አሁንም አይሰራም ↓
│
└─ በእጅ፦ በማሽኑ ላይ `agy login` ያስኪዱ
├─ ይሰራል → በዳሽቦርዱ ውስጥ ቶከኑን ያድሱ፣ projectId ይገኛል
└─ አይሰራም → የስህተት መልዕክቱን ይመልከቱ፤ ምናልባት የክልል ወይም የደንበኝነት ችግር ነው
```
---
## ፈጣን ማጣቀሻ
| ተግባር | ትዕዛዝ / URL |
| ------------------------ | ----------------------------------------------------------------------------- |
| የመለያውን ክልል መቀየር | [የGoogle የአገር ግንኙነት ቅጽ](https://policies.google.com/country-association-form) |
| የagy CLI መግቢያ | `agy login` |
| በDB ውስጥ projectIdን ማረጋገጥ | `SELECT email,project_id FROM provider_connections WHERE provider='agy'` |
| ምዝግቦችን ማረጋገጥ | `podman logs omniroute 2>&1 \| grep projectId` |
| ቶከን ማደስ | ዳሽቦርድ → አቅራቢዎች → agy → የማደሻ አዶውን ጠቅ ያድርጉ |
---
_ለመጨረሻ ጊዜ የተዘመነው፦ 2026-07-31። በOmniRoute v3.8.50 ላይ የተመሠረተ።_

113
docs/i18n/am/docs/guides/CHAOS-MODE.md Normal file
View File

@@ -0,0 +1,113 @@
# Chaos Mode (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/CHAOS-MODE.md) · 🇸🇦 [ar](../../../ar/docs/guides/CHAOS-MODE.md) · 🇦🇿 [az](../../../az/docs/guides/CHAOS-MODE.md) · 🇧🇬 [bg](../../../bg/docs/guides/CHAOS-MODE.md) · 🇧🇩 [bn](../../../bn/docs/guides/CHAOS-MODE.md) · 🇨🇿 [cs](../../../cs/docs/guides/CHAOS-MODE.md) · 🇩🇰 [da](../../../da/docs/guides/CHAOS-MODE.md) · 🇩🇪 [de](../../../de/docs/guides/CHAOS-MODE.md) · 🇬🇷 [el](../../../el/docs/guides/CHAOS-MODE.md) · 🇪🇸 [es](../../../es/docs/guides/CHAOS-MODE.md) · 🇪🇪 [et](../../../et/docs/guides/CHAOS-MODE.md) · 🇮🇷 [fa](../../../fa/docs/guides/CHAOS-MODE.md) · 🇫🇮 [fi](../../../fi/docs/guides/CHAOS-MODE.md) · 🇫🇷 [fr](../../../fr/docs/guides/CHAOS-MODE.md) · 🇮🇪 [ga](../../../ga/docs/guides/CHAOS-MODE.md) · 🇮🇳 [gu](../../../gu/docs/guides/CHAOS-MODE.md) · 🇳🇬 [ha](../../../ha/docs/guides/CHAOS-MODE.md) · 🇮🇱 [he](../../../he/docs/guides/CHAOS-MODE.md) · 🇮🇳 [hi](../../../hi/docs/guides/CHAOS-MODE.md) · 🇭🇷 [hr](../../../hr/docs/guides/CHAOS-MODE.md) · 🇭🇺 [hu](../../../hu/docs/guides/CHAOS-MODE.md) · 🇦🇲 [hy](../../../hy/docs/guides/CHAOS-MODE.md) · 🇮🇩 [id](../../../id/docs/guides/CHAOS-MODE.md) · 🇳🇬 [ig](../../../ig/docs/guides/CHAOS-MODE.md) · 🇮🇹 [it](../../../it/docs/guides/CHAOS-MODE.md) · 🇯🇵 [ja](../../../ja/docs/guides/CHAOS-MODE.md) · 🇬🇪 [ka](../../../ka/docs/guides/CHAOS-MODE.md) · 🇰🇭 [km](../../../km/docs/guides/CHAOS-MODE.md) · 🇮🇳 [kn](../../../kn/docs/guides/CHAOS-MODE.md) · 🇰🇷 [ko](../../../ko/docs/guides/CHAOS-MODE.md) · 🇱🇹 [lt](../../../lt/docs/guides/CHAOS-MODE.md) · 🇱🇻 [lv](../../../lv/docs/guides/CHAOS-MODE.md) · 🇮🇳 [ml](../../../ml/docs/guides/CHAOS-MODE.md) · 🇮🇳 [mr](../../../mr/docs/guides/CHAOS-MODE.md) · 🇲🇾 [ms](../../../ms/docs/guides/CHAOS-MODE.md) · 🇲🇹 [mt](../../../mt/docs/guides/CHAOS-MODE.md) · 🇲🇲 [my](../../../my/docs/guides/CHAOS-MODE.md) · 🇳🇵 [ne](../../../ne/docs/guides/CHAOS-MODE.md) · 🇳🇱 [nl](../../../nl/docs/guides/CHAOS-MODE.md) · 🇳🇴 [no](../../../no/docs/guides/CHAOS-MODE.md) · 🇮🇳 [or](../../../or/docs/guides/CHAOS-MODE.md) · 🇮🇳 [pa](../../../pa/docs/guides/CHAOS-MODE.md) · 🇵🇭 [phi](../../../phi/docs/guides/CHAOS-MODE.md) · 🇵🇱 [pl](../../../pl/docs/guides/CHAOS-MODE.md) · 🇵🇹 [pt](../../../pt/docs/guides/CHAOS-MODE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CHAOS-MODE.md) · 🇷🇴 [ro](../../../ro/docs/guides/CHAOS-MODE.md) · 🇷🇺 [ru](../../../ru/docs/guides/CHAOS-MODE.md) · 🇱🇰 [si](../../../si/docs/guides/CHAOS-MODE.md) · 🇸🇰 [sk](../../../sk/docs/guides/CHAOS-MODE.md) · 🇸🇮 [sl](../../../sl/docs/guides/CHAOS-MODE.md) · 🇷🇸 [sr](../../../sr/docs/guides/CHAOS-MODE.md) · 🇸🇪 [sv](../../../sv/docs/guides/CHAOS-MODE.md) · 🇰🇪 [sw](../../../sw/docs/guides/CHAOS-MODE.md) · 🇮🇳 [ta](../../../ta/docs/guides/CHAOS-MODE.md) · 🇮🇳 [te](../../../te/docs/guides/CHAOS-MODE.md) · 🇹🇭 [th](../../../th/docs/guides/CHAOS-MODE.md) · 🇹🇷 [tr](../../../tr/docs/guides/CHAOS-MODE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CHAOS-MODE.md) · 🇵🇰 [ur](../../../ur/docs/guides/CHAOS-MODE.md) · 🇺🇿 [uz](../../../uz/docs/guides/CHAOS-MODE.md) · 🇻🇳 [vi](../../../vi/docs/guides/CHAOS-MODE.md) · 🇳🇬 [yo](../../../yo/docs/guides/CHAOS-MODE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CHAOS-MODE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CHAOS-MODE.md)
---
> **ዳሽቦርድ:** **Chaos Mode** (የጎን አሞሌ) → `/dashboard/chaos`
> **API:** `GET` / `PUT` `/api/chaos/config` · `POST /api/chaos/run` (የዳሽቦርድ ክፍለ-ጊዜ) · `POST /api/skills/collect/chaos` (የAPI ቁልፍ)
> **ምንጭ:** `src/lib/chaos/chaosExecutor.ts`, `src/lib/chaos/chaosConfig.ts`
Chaos Mode **አንድን ተግባር በአንድ ጊዜ ወደ በርካታ አቅራቢዎች ይልካል** — እያንዳንዱ ተሳታፊ አቅራቢ
አንድ የሞዴል ኢንስታንስ ያቀርባል፣ እርስዎም ሁሉንም መልሶች ጎን ለጎን (ወይም በሰንሰለት) ያገኛሉ። ይህ
ባለብዙ-ሞዴል የማስፈጸሚያ በይነገጽ እንጂ የማዘዋወሪያ ስልት አይደለም፦ መደበኛው `/v1/chat/completions`
ትራፊክዎ በእሱ ፈጽሞ አይነካም።
**ማብራሪያ — "chaos" የሚለውን ስም የያዙ ሦስት የተለያዩ ነገሮች አሉ፦**
| ነገር | ምንድን ነው | የተመዘገበበት ቦታ |
| -------------- | --------------------------------------------------------------------------- | -------------------------------------------- |
| **Chaos Mode** | እዚህ የተገለጹት የዳሽቦርድ ገጽ + API፦ አንድን ተግባር ለብዙ አቅራቢዎች ያሰራጫል (በትይዩ ወይም በትብብር)። | ይህ መመሪያ |
| `auto/chaos` | ለጽናት ሙከራ፣ የስህተት-ማስገቢያ የውጤት ክብደቶች ያሉት የAuto-Combo ሞዴል id። የሚዋቀር ነገር የለም። | [AUTO-COMBO.md](../routing/AUTO-COMBO.md) |
| የChaos ጥምር ውቅር | `config.chaos.enabled` ያለው የተቀመጠ ጥምር፣ ከአማራጭ ዳኛ ሞዴል ጋር ለፓነል ያሰራጫል (በAPI ብቻ)። | `open-sse/services/autoCombo/chaosEngine.ts` |
## ማዋቀር
1. **Dashboard → Chaos Mode** (`/dashboard/chaos`) ይክፈቱ።
2. **ያብሩት** — Chaos Mode በነባሪ **ተሰናክሎ** ይመጣል (`enabled: false` በ
`src/lib/chaos/chaosConfig.ts`)። ተሰናክሎ ሳለ፣ `POST /api/chaos/run`
`400 — "Chaos Mode is not enabled. Enable it in Dashboard → Chaos Mode."` የሚል ምላሽ ይሰጣል።
3. ተሳታፊዎቹን እና ነባሪ ቅንብሮቹን ይምረጡ (በቅንብሮች ማከማቻው በኩል ለእያንዳንዱ ኢንስታንስ ተቀምጠው ይቆያሉ)፦
| መስክ | ትርጉም | ነባሪ / ገደቦች |
| ------------------- | ----------------------------------------------------------- | ----------------------------- |
| `enabled` | ዋና ማብሪያ/ማጥፊያ | `false` |
| `defaultMode` | `parallel` ወይም `collaborative` (ከታች ይመልከቱ) | `parallel` |
| `providerOverrides` | የእያንዳንዱ አቅራቢ ተሳትፎ (`providerId`፣ አማራጭ `modelId`፣ `enabled`) | ባዶ = ሁሉም ንቁ አቅራቢዎች፣ ከፍተኛው 200 |
| `systemPrompt` | አብሮገነብ የChaos ስርዓት መመሪያን ለመተካት | አማራጭ፣ ከፍተኛው 10 000 ቁምፊዎች |
| `timeoutMs` | ለእያንዳንዱ የሞዴል ጥሪ ከፍተኛው ጊዜ | `120000` (5 000–600 000) |
| `maxTokens` | ለእያንዳንዱ የሞዴል ጥሪ `max_tokens` | `4096` (256–128 000) |
4. **ከገጹ ራሱ ሙከራ ያስኪዱ** — የውጤቶች ፓነሉ የእያንዳንዱን አቅራቢ መልስ፣
ሁኔታ እና ቆይታ ያሳያል።
## የማስፈጸሚያ ሁነታዎች
- **`parallel`** — እያንዳንዱ ሞዴል ተመሳሳይ ተግባርን በአንድ ጊዜ ይቀበላል፤ ሁሉንም መልሶች
ለየብቻ ይቀበላሉ።
- **`collaborative`** — ሞዴሎቹ **በሰንሰለት** ይሰራሉ፦ እያንዳንዱ ሞዴል የቀድሞውን ሞዴል ውጤት ያያል፣
እና እንዲያሻሽለው፣ እንዲያስፋፋው፣ እንዲተቸው ወይም አማራጭ እንዲያቀርብ ይጠየቃል። የምላሹ `summary` መስክ
የተሳኩ ውጤቶችን በሰንሰለቱ ቅደም ተከተል ያገናኛል (የትይዩ አፈጻጸሞች `summary` የላቸውም)።
## API
### `POST /api/chaos/run` — የዳሽቦርድ ክፍለ-ጊዜ
በኩኪ የተረጋገጠ (የአስተዳደር ክፍለ-ጊዜ —
[MANAGEMENT-AUTH.md](MANAGEMENT-AUTH.md) ይመልከቱ)፤ በዳሽቦርድ ገጹ ጥቅም ላይ ይውላል።
```jsonc
// የጥያቄ ይዘት
{
"task": "Compare approaches to X", // ያስፈልጋል
"providers": ["glm", "kimi"], // አማራጭ ማጣሪያ
"mode": "parallel", // አማራጭ — defaultModeን ይተካል
"systemPrompt": "…", // አማራጭ መተኪያ
"maxTokens": 4096, // አማራጭ መተኪያ
}
```
### `POST /api/skills/collect/chaos` — የAPI ቁልፍ
ለውጫዊ ጠሪዎች የBearer-token ልዩነት። ቁልፉ **የChaos Mode ፈቃድ**
(`chaosModeEnabled`) ሊኖረው ይገባል፤ ይህም **በነባሪ ጠፍቷል** — ለእያንዳንዱ ቁልፍ በ
**Dashboard → API Manager → edit key → permissions → Chaos Mode** ውስጥ ያንቁት። ከላይ ካለው ጋር ተመሳሳይ የጥያቄ ይዘት ይጠቀማል።
```bash
curl -X POST http://localhost:20128/api/skills/collect/chaos \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task":"Compare approaches to X","mode":"parallel"}'
```
ሁለቱም መጨረሻ ነጥቦች ተመሳሳይ ቅርጽ ይመልሳሉ፦
```jsonc
{
"task": "…",
"mode": "parallel",
"startedAt": "2026-09-01T00:00:00.000Z",
"totalProviders": 3,
"totalResults": 3,
"models": [
{
"providerId": "glm",
"providerName": "GLM",
"modelId": "glm-4.7",
"status": "success",
"content": "…",
"durationMs": 3210,
},
],
"summary": "…", // ለcollaborative ሁነታ ብቻ
}
```
## ችግር መፍታት
- **`400 Chaos Mode is not enabled`** — ከላይ ያለውን ደረጃ 2 ይመልከቱ፦ ዓለም አቀፉ ማብሪያ ጠፍቷል።
- **የAPI ቁልፉ በ`/api/skills/collect/chaos` ላይ ውድቅ ይደረጋል** — ቁልፉ የእያንዳንዱ ቁልፍ
`chaosModeEnabled` ፈቃድ የለውም (በነባሪ ጠፍቷል፤ ይህ ቅንብር እንጂ ስህተት አይደለም)።
- **የጠበቁት አቅራቢ ከውጤቶቹ ውስጥ የለም** — በChaos Mode ገጽ ላይ `providerOverrides`ን
ያረጋግጡ (የተሰናከለ መተኪያ አቅራቢውን ያስወግደዋል)፣ እንዲሁም የአቅራቢው ግንኙነት
ንቁ መሆኑን ያረጋግጡ።

214
docs/i18n/am/docs/guides/CLAUDE-CODE-CONFIGURATION.md Normal file
View File

@@ -0,0 +1,214 @@
# Claude Code CLI — Configuration with OmniRoute (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇪 [de](../../../de/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇹 [it](../../../it/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇷 [ko](../../../ko/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇹 [pt](../../../pt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇻🇳 [vi](../../../vi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CLAUDE-CODE-CONFIGURATION.md)
---
የ **Claude Code** CLI (`claude`)ን ወደ OmniRoute — የአካባቢ ወይም የርቀት VPS —
በእያንዳንዱ ሞዴል መገለጫዎች፣ የCodex ውቅርን በማንጸባረቅ ያመልክቱ።
---
## ፈጣን አጀማመር
```bash
# በአካባቢ OmniRoute ላይ Claude Codeን ያስጀምሩ (ንቁውን አውድ በራስ-ሰር ያገኛል)
omniroute launch
# በርቀት OmniRoute ላይ (`omniroute connect <host>`ን ካስኬዱ በኋላ፣ ይህ በራስ-ሰር ይሆናል)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx
# ለእያንዳንዱ ሞዴል መገለጫዎችን ይፍጠሩ፣ ከዚያም አንዱን ያስጀምሩ
omniroute setup-claude # ወደ ~/.claude/profiles/<name>/settings.json ይጽፋል
omniroute launch --profile glm52 # Claude Code glm/glm-5.2ን በOmniRoute በኩል በመጠቀም
```
---
## Claude Code ከጌትዌይ ጋር እንዴት እንደሚገናኝ
Claude Code ከ **Anthropic Messages API** ጋር ይገናኛል፣ እናም የአካባቢ ተለዋዋጮችን በመጠቀም ወደ ብጁ
መዳረሻ ይመራል (`--base-url` ጠቋሚ የለውም)፦
| ተለዋዋጭ | ዓላማ |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL` | የጌትዌይ መሠረታዊ URL (Claude Code `/v1/messages`ን ይጨምራል)። **የ`/v1` ቅጥያ አይኖርም።** |
| `ANTHROPIC_AUTH_TOKEN` | እንደ `Authorization: Bearer …` ይላካል — የOmniRoute መዳረሻ ቶከንዎን / API ቁልፍዎን ይጠቀሙ |
| `ANTHROPIC_API_KEY` | አማራጭ፦ እንደ `x-api-key` ይላካል። ሁለቱም ከተዋቀሩ፣ `ANTHROPIC_AUTH_TOKEN` ቅድሚያ ያገኛል |
| `ANTHROPIC_MODEL` | የተወሰነ ሞዴል እንዲጠቀም ያስገድዳል (የ`/model` መራጭን ነባሪ ይሽራል) |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` → ቤተኛው የ`/model` መራጭ ከ`/v1/models` የተገኙ `claude*`/`anthropic*` ሞዴሎችን ይዘረዝራል |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | በእያንዳንዱ ምላሽ የውጤት ቶከኖችን ይገድባል (ለምሳሌ `65536`) |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | ለራስ-ሰር ማጠቃለያ የቶከን ገደብ |
> የአካባቢ ተለዋዋጮች **በማስጀመሪያ ጊዜ አንድ ጊዜ** ይነበባሉ — ከቀየሯቸው በኋላ Claude Codeን እንደገና ያስጀምሩ።
`omniroute launch` እነዚህን ሁሉ ያዋቅርልዎታል፦ መሠረታዊ URL + ቶከንን
ከንቁው አውድ ይፈታል (ስለዚህ `omniroute connect <vps>` ከዚያም `omniroute launch`
በቀጥታ ይሠራል)፣ የሰርቨሩን ጤና ይፈትሻል፣ እና `claude`ን ያስኬዳል።
---
## የግኝት ተለዋጭ ስሞች — Claude ያልሆኑ ሞዴሎችን በ`/model` መራጭ ውስጥ ያሳዩ
የClaude Code ጌትዌይ ሞዴል ግኝት በ`claude`
ወይም `anthropic` የሚጀምሩ መለያዎችን ብቻ ይዘረዝራል፤ ስለዚህ `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` ሲሆን ቤተኛው
የ`/model` መራጭ በተለምዶ **የOmniRoute Claude/Anthropic ሞዴሎችን ብቻ** ያሳያል —
`kimi/kimi-k2.6` ወይም `glm/glm-5.2` በትክክል ቢዘዋወርም እንኳ ፈጽሞ አይታይም።
OmniRoute ማንኛውንም የነቃ ሞዴል (እና ጥምረት) በ`claude/…` መለያ ስር ማንጸባረቅ ይችላል፤ በዚህም
ያንን ማጣሪያ አልፎ በመራጩ ውስጥ ይታያል፦
```
kimi/kimi-k2.6 → claude/kimi/kimi-k2.6 "Kimi K2.6 (OmniRoute)"
glm/glm-5.2 → claude/glm/glm-5.2 "GLM 5.2 (OmniRoute)"
<ጥምረት "custo-otimizado"> → claude/combo/custo-otimizado
```
ከእነዚህ አንዱን በClaude Code ውስጥ ሲመርጡ፣ OmniRoute ከማዞሩ በፊት የ`claude/` መጠቅለያውን
አስወግዶ ወደ እውነተኛው መለያ ይመልሰዋል — እውነተኛ `claude/<real-claude-model>` መለያ
(ትክክለኛው የClaude OAuth አቅራቢ) ሁልጊዜ ሳይነካ ይቀራል።
**ይህ በነባሪነት ጠፍቷል** እና በሶስት-ደረጃ መቆጣጠሪያ (በጣም ዝርዝር የሆነው
ቅድሚያ ያገኛል) ይቆጣጠራል፤ ስለዚህ መደበኛ OmniRoute፣ Claude Codeን ለማይጠቀሙ
ደንበኞች ካታሎጉን ፈጽሞ አያባዛም፦
| ደረጃ | ቦታ |
| ------- | ---------------------------------------------------------------- |
| ሞዴል | የአቅራቢ ዝርዝር ገጽ → ለእያንዳንዱ ሞዴል "በClaude Code ውስጥ አሳይ" መቀያየሪያ |
| አቅራቢ | የአቅራቢ ዝርዝር ገጽ → የአቅራቢ-ደረጃ መቀያየሪያ (ሁሉንም ሞዴሎቹን ያካትታል) |
| ዓለም አቀፍ | ቅንብሮች → የባህሪ ጠቋሚዎች → `EXPOSE_CC_DISCOVERY_ALIASES` (በነባሪነት ጠፍቷል) |
የ`EXPOSE_CC_DISCOVERY_ALIASES` የአካባቢ ተለዋዋጭ ዓለም አቀፉ ደረጃ እንዲበራ ያስገድዳል
እና በዳሽቦርዱ ላይ ከተደረገው ማሻሻያ ቅድሚያ ያገኛል (የባህሪ ጠቋሚዎች ገጽ
ይህ ሲከሰት "በአካባቢ ተለዋዋጭ በኩል ንቁ" የሚል ማስታወሻ ያሳያል)። የእያንዳንዱ አቅራቢ እና
የእያንዳንዱ ሞዴል መቀያየሪያዎች ከዚያ ይበልጥ ያጠራሉ — ለምሳሌ ዓለም አቀፉ ጠፍቶ + የKimi አቅራቢ በርቶ ከሆነ
የKimi ሞዴሎችን ብቻ ያሳያል።
> ⚠️ **Claude ባልሆኑ ሞዴሎች ላይ የመስኮት አለመዛመድ።** Claude Code ለማያውቀው ማንኛውም መለያ የ200K አውድ
> መስኮት እንዳለው ይገምታል (እውነተኛውን መስኮት ከ`/v1/models` ማንበብ አይችልም)። ትልቅ መስኮት ላለው ሞዴል
> (ለምሳሌ የKimi K2 256K)፣ ራስ-ሰር ማጠቃለያው ያለጊዜው እንዳይነሳ፣
> `CLAUDE_CODE_AUTO_COMPACT_WINDOW`ን ከሞዴሉ እውነተኛ መስኮት በታች ወዳለ እሴት ያቀናብሩ። ከላይ የተፈጠሩት መገለጫዎች ይህን
> ቀድሞውኑ ለእያንዳንዱ ሞዴል ያደርጋሉ።
---
## በዳሽቦርዱ ላይ ያለው የመነሻ ማዋቀሪያ ብሎክ
የClaude መሣሪያ ካርድ (**Dashboard → CLI Code**) ለዚህ ኢንስታንስ ትክክለኛውን የ`settings.json` ክፍልፋይ፣ ከdiscovery-alias መረጃ አዝራሩ አጠገብ፣ ከቅጂ አዝራር ጋር ያሳያል፦
```jsonc
{
"env": {
"ANTHROPIC_BASE_URL": "http://<የእርስዎ OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<የእርስዎ OmniRoute API ቁልፍ>",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
},
}
```
መሠረታዊ URL በካርዱ የተወሰነው ነው (እርስዎ ያስገቡትን ብጁ ለውጥ ጨምሮ)፣ እና አስቀድሞ ደረጃውን የጠበቀ ነው — የ`/v1` ቅጥያም ሆነ በመጨረሻ የሚመጣ ስላሽ የለውም። **ቁልፉ በፍጹም አይታይም**፦ ብሎኩ ከቦታ ያዥ ጋር ስለሚቀርብ፣ የማያ ገጽ ቅጂ ወይም የተለጠፈ ቅንጭብ ቁልፉን ሊያጋልጥ አይችልም። ቁልፍዎን በቦታው ላይ ይለጥፉ።
እውነተኛው የአውድ መስኮት 200K ላልሆነ ማንኛውም ሞዴል፣ `CLAUDE_CODE_AUTO_COMPACT_WINDOW`ን በዚያው `env` ብሎክ ስር ያክሉ — Claude Code ለማያውቀው ለእያንዳንዱ id 200K እንዳለው ይገምታል፤ ስለዚህ ካልተዋቀረ ራስ-ሰር ማመቅ በተሳሳተ ነጥብ ላይ ይጀምራል (በቀደመው ክፍል ያለውን ማስጠንቀቂያ ይመልከቱ)። የቅንጭብ ገንቢውም ይህን እሴት ይቀበላል፤ ስለዚህ የዒላማውን ሞዴል የአውድ መስኮት የሚያውቅ ጠሪ በቀጥታ ሊያወጣው ይችላል።
ምንጭ፦ `src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet` (ንጹሕ ገንቢ፣ በክፍል ሙከራ የተፈተነ) በ`ClaudeGatewayOnboardingBlock` የሚታይ።
---
## መገለጫዎች (`CLAUDE_CONFIG_DIR`)
Claude Code **ቤተኛ የመገለጫ ፋይሎች የሉትም** (ከCodex `~/.codex/<name>.config.toml` በተለየ)። የተለመደው ዘዴ `CLAUDE_CONFIG_DIR` ነው — ለእያንዳንዱ መገለጫ የተለየ የውቅር ማውጫ፣ እያንዳንዱም የራሱ `settings.json`፣ ማረጋገጫዎች፣ ታሪክ እና መሸጎጫ ያለው።
`omniroute setup-claude` በቀጥታ ያለውን የ`/v1/models` ካታሎግ ያመጣና ለእያንዳንዱ ሞዴል አንድ መገለጫ በ`~/.claude/profiles/<name>/settings.json` ላይ ይጽፋል፤ እንዲሁም **ከ`setup-codex` ጋር ተመሳሳይ ስሞችን** (`glm52`፣ `kimi-k27`፣ `deepseek-pro`፣ …) እንደገና ይጠቀማል፦
```jsonc
// ~/.claude/profiles/glm52/settings.json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "glm/glm-5.2",
"effortLevel": "xhigh",
"env": {
"ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
"ANTHROPIC_MODEL": "glm/glm-5.2",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
},
}
```
> **የማረጋገጫ ቶከኑ በመገለጫው ውስጥ በፍጹም አይጻፍም።** በ
> `omniroute launch --profile <name>` ያስጀምሩት (ከንቁው አውድ `ANTHROPIC_AUTH_TOKEN`ን
> ያስገባል)፣ ወይም `ANTHROPIC_AUTH_TOKEN`ን እራስዎ ወደ ውጭ ይላኩና
> `CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude`ን ያስኪዱ።
**ከሞዴል ግኝት በኋላ ራስ-ሰር ማመሳሰል (በምርጫ የሚነቃ)።** የአቅራቢ ሞዴል ማመሳሰል በቀጥታ ያለውን ካታሎግ በሚቀይርበት ጊዜ ሁሉ OmniRoute እነዚህን ተመሳሳይ የ`~/.claude/profiles/<name>/settings.json` ፋይሎች በራስ-ሰር እንደገና ሊፈጥር ይችላል — ስለዚህ ትዕዛዙን እንደገና ሳያስኬዱ አዲስ ወይም እንደገና የተሰየሙ ሞዴሎች መገለጫዎችን ያገኛሉ። በነባሪነት **ጠፍቷል**፦ ከ**CLI Code dashboard** ("የCLI መገለጫ ራስ-ሰር ማመሳሰል" → Claude Code) ያብሩት፣ ወይም `OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true`ን ያቀናብሩ (`CLI_ALLOW_CONFIG_WRITES`ንም ያከብራል፣ ይህም በነባሪነት በርቷል)። ሲነቃ የመገለጫ ፋይሎችን ብቻ ይጽፋል፤ ንቁውን/ነባሪውን የClaude ውቅር፣ ማረጋገጫ ወይም `~/.claude/settings.json`ን ፈጽሞ አይቀይርም።
### መገለጫዎችን መፍጠር + መጠቀም
```bash
# አካባቢያዊ OmniRoute
omniroute setup-claude
# የርቀት VPS (የVPS URLን በእያንዳንዱ መገለጫ ውስጥ ያካትታል)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx
# የተወሰኑ አቅራቢዎች ብቻ
omniroute setup-claude --only glm,kimi
# ሳይጻፍ ቅድመ ዕይታ
omniroute setup-claude --dry-run
# መገለጫ ማስጀመር
omniroute launch --profile kimi-k27
```
---
## የሞዴል ደረጃዎች (አማራጭ)
Claude Code ጥያቄዎችን ወደ ችሎታ ደረጃዎች ያዞራል። ለእያንዳንዱ ደረጃ የተለያዩ አቅራቢዎችን መጠቀም ከፈለጉ፣ በenv /
ቅንብሮች በኩል እያንዳንዱን ከአንድ OmniRoute ሞዴል ጋር ያዛምዱ፦
```bash
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"
```
አለበለዚያ፣ አንድ `ANTHROPIC_MODEL` (መገለጫዎች የሚያዘጋጁት) ለሁሉም ነገር ጥቅም ላይ ይውላል።
---
## የርቀት ሁነታ
አንዴ `omniroute connect <host>` ን ካስኬዱ ([የርቀት ሁነታ](./REMOTE-MODE.md)ን ይመልከቱ)፣ `omniroute launch` እና `omniroute setup-claude`
ያንን የርቀት አገልጋይ በራስ-ሰር ዒላማ ያደርጋሉ፣ እንዲሁም የእሱን ወሰን የተበጀለት የመዳረሻ ቶከን ይጠቀማሉ — ተጨማሪ
ጥቆማዎች አያስፈልጉም። ለእያንዳንዱ ጥሪ በ`--remote` / `--api-key` ይሽሩት።
---
## መላ ፍለጋ
**Claude Code መግቢያውን ችላ ይላል** — `ANTHROPIC_BASE_URL` **`/v1` እንደሌለው**
ያረጋግጡ፣ ከዚያ `claude`ን ዳግም ያስጀምሩ (env በማስጀመሪያ ጊዜ አንድ ጊዜ ብቻ ይነበባል)። `omniroute launch`
ይህን ለእርስዎ ያከናውናል።
**የ`/model` መራጩ ባዶ ነው / የመግቢያ ሞዴሎች ጠፍተዋል** — Claude Code
v2.1.219+ እና `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` ያስፈልጋሉ። በመራጩ ውስጥ የሚታዩት `claude*` /
`anthropic*` የሞዴል IDዎች ብቻ ናቸው፤ ማንኛውንም ሌላ ሞዴል በ
`ANTHROPIC_MODEL=<id>` ያስገድዱ (መገለጫዎች የሚያደርጉት ይህንኑ ነው)።
**`400 Ambiguous model 'claude-…'`** — Claude Code ሁልጊዜ **ቅድመ ቅጥያ የሌላቸው**
የሞዴል IDዎችን (ለምሳሌ `claude-opus-4-8`) ይልካል፤ ስለዚህ ሁለቱም Claude Code (`cc/…`) እና
Claude (`claude/…`) አቅራቢዎች ሲገናኙ ቅድመ ቅጥያ የሌለው id ከሁለት መስመሮች ጋር ይዛመዳል፣ እና
OmniRoute መገመትን አይቀበልም። ከሁለቱ መንገዶች በአንዱ ያስተካክሉት፦ ቅድመ ቅጥያ ያለውን id በ
`ANTHROPIC_MODEL=cc/claude-opus-4-8` ይወስኑ፣ ወይም **ቅድመ ቅጥያ ለሌላቸው Claude ሞዴሎች Claude Codeን
ቅድሚያ ስጥ**ን ያንቁ — በClaude አቅራቢ ገጽ ላይ ያለውን መቀያየሪያ፣ ወይም
`OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true`ን (በነባሪ ጠፍቷል፤
[አካባቢ](../reference/ENVIRONMENT.md)ን ይመልከቱ) — ይህም ቅድመ ቅጥያ የሌላቸውን `claude-*`
IDዎች በምትኩ ወደ Claude Code ያዞራል። ግልጽ የአቅራቢ ቅድመ ቅጥያዎች ሁልጊዜ ቅድሚያ ያገኛሉ።
**የማረጋገጫ ስህተቶች** — መገለጫው ምንም ቶከን አይይዝም። `omniroute launch --profile`ን
ይጠቀሙ (ቶከኑን ያስገባል) ወይም `ANTHROPIC_AUTH_TOKEN`ን export ያድርጉ።
**መገለጫዎች አይነጣጠሉም** — እያንዳንዱ መገለጫ የተለየ `CLAUDE_CONFIG_DIR` ነው፤ በክፍለ ጊዜው ውስጥ
`echo $CLAUDE_CONFIG_DIR` ወደ `~/.claude/profiles/<name>` እንደሚያመለክት ያረጋግጡ።

87
docs/i18n/am/docs/guides/CODEX-APP-SERVER-PROVIDER.md Normal file
View File

@@ -0,0 +1,87 @@
# OpenAI Codex — App-Server provider (`codex-app-server`) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/CODEX-APP-SERVER-PROVIDER.md) · 🇸🇦 [ar](../../../ar/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇦🇿 [az](../../../az/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇧🇬 [bg](../../../bg/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇧🇩 [bn](../../../bn/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇨🇿 [cs](../../../cs/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇩🇰 [da](../../../da/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇩🇪 [de](../../../de/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇬🇷 [el](../../../el/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇪🇸 [es](../../../es/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇪🇪 [et](../../../et/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇷 [fa](../../../fa/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇫🇮 [fi](../../../fi/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇫🇷 [fr](../../../fr/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇪 [ga](../../../ga/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [gu](../../../gu/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇳🇬 [ha](../../../ha/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇱 [he](../../../he/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [hi](../../../hi/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇭🇷 [hr](../../../hr/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇭🇺 [hu](../../../hu/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇦🇲 [hy](../../../hy/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇩 [id](../../../id/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇳🇬 [ig](../../../ig/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇹 [it](../../../it/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇯🇵 [ja](../../../ja/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇬🇪 [ka](../../../ka/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇰🇭 [km](../../../km/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [kn](../../../kn/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇰🇷 [ko](../../../ko/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇱🇹 [lt](../../../lt/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇱🇻 [lv](../../../lv/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [ml](../../../ml/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [mr](../../../mr/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇲🇾 [ms](../../../ms/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇲🇹 [mt](../../../mt/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇲🇲 [my](../../../my/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇳🇵 [ne](../../../ne/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇳🇱 [nl](../../../nl/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇳🇴 [no](../../../no/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [or](../../../or/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [pa](../../../pa/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇵🇭 [phi](../../../phi/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇵🇱 [pl](../../../pl/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇵🇹 [pt](../../../pt/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇷🇴 [ro](../../../ro/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇷🇺 [ru](../../../ru/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇱🇰 [si](../../../si/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇸🇰 [sk](../../../sk/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇸🇮 [sl](../../../sl/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇷🇸 [sr](../../../sr/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇸🇪 [sv](../../../sv/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇰🇪 [sw](../../../sw/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [ta](../../../ta/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇮🇳 [te](../../../te/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇹🇭 [th](../../../th/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇹🇷 [tr](../../../tr/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇵🇰 [ur](../../../ur/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇺🇿 [uz](../../../uz/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇻🇳 [vi](../../../vi/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇳🇬 [yo](../../../yo/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CODEX-APP-SERVER-PROVIDER.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CODEX-APP-SERVER-PROVIDER.md)
---
OmniRoute OpenAI Codexን ለመጠቀም **ሁለት** መንገዶችን ያቀርባል፦
| አቅራቢ | ከOpenAI ጋር የሚገናኝበት መንገድ | የአጠቃቀም ገደብ |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **`codex`** | የChatGPT/OpenAI OAuth ቶከንዎን በቀጥታ ወደ Responses API ደግሞ ይልካል | **አዎ** — ይፋዊው ክፍለ-ጊዜ ለፕሮክሲ/ራውተር አጠቃቀም ፈቃድ የለውም |
| **`codex-app-server`** | የ**Codex CLI የራሱን `codex app-server`** በJSON-RPC/WebSocket ያንቀሳቅሳል፤ CLIው ልክ እንደ በይነተገናኝ `codex` ክፍለ-ጊዜ የራሱን OAuth (`~/.codex/auth.json`) ይዞ በራሱ ያድሳል | **አይ** — OmniRoute ቶከንን ወደ API በፍጹም ደግሞ አይልክም |
`codex-app-server` ቶከንን ደግሞ ስለማይልክ፣ የክፍለ-ጊዜ ድጋሚ-መላክ
የአጠቃቀም ገደቡ አይመለከተውም። ነገር ግን፣ **በተዋቀረው app-server
URL ላይ ሊደረስበት የሚችል Codex CLI** ያስፈልገዋል፣ እና CLIው **በመለያ መግባት** አለበት።
---
## 1. አርክቴክቸር
```
┌─ OmniRoute መተግበሪያ ──────────────┐ ┌─ codex-app-server የጎን ኮንቴይነር ─────┐
│ CodexAppServerExecutor │ WS │ codex app-server │
│ ws://codex-app-server:1456 ─────┼───────▶│ --listen ws://0.0.0.0:1456 │
│ (+ የችሎታ ቶከን) │ JSON │ --ws-auth capability-token │
│ │ RPC │ OpenAI OAuthን በራሱ ያስተዳድራል │
└──────────────────────────────────┘ │ (~/.codex/auth.json, ራስ-ሰር ዕድሳት) │
│ ይጋራል (compose volumes) └─────────────────────────────────────┘
▼
codex-appserver-token → የWS ችሎታ ቶከን (ሁለቱም ይሰቅሉታል)
codex-appserver-home → ~/.codex (auth.json በዳሽቦርዱ ይጻፋል፣
በጎን ኮንቴይነሩ codex app-server ይነበባል)
```
- የጎን ኮንቴይነሩ ከችሎታ ቶከን ጀርባ **በውስጣዊው compose አውታረ መረብ ላይ ብቻ**
(`ws://codex-app-server:1456`) ጥያቄዎችን ይቀበላል። ለአስተናጋጁ ወይም ለበይነመረብ
**ፈጽሞ** አይጋለጥም።
- Codex CLI በ`omniroute:base` ውስጥ አስቀድሞ ተካትቷል፤ ስለዚህ የጎን ኮንቴይነሩን
ሲያስኬዱ በአስተናጋጁ ወይም በተጠቃሚው ማሽን ላይ codexን መጫን አያስፈልግም።
## 2. ማስነሳት
```bash
# ስብስቡን ከcodex app-server የጎን ኮንቴይነር መገለጫ ጋር ያስጀምሩ፦
docker compose --profile base --profile codex-app-server up -d
# (podman፦ podman compose --profile base --profile codex-app-server up -d)
```
የጎን ኮንቴይነሩ በመጀመሪያው መነሳት የWS ችሎታ ቶከኑን ያመነጫል (ወደ የጋራ
`codex-appserver-token` volume)፣ መተግበሪያውም ተመሳሳዩን ቶከን
በ`OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE` ያነባል። ቶከኑን በእጅ ማገናኘት አያስፈልግም።
## 3. መገናኘት + በመለያ መግባት
1. በዳሽቦርዱ ውስጥ ለ**OpenAI Codex (App-Server)** ግንኙነት ያክሉ። ምንም API
ቁልፍ ወይም ቶከን አያስፈልግም (ማረጋገጫ የማይፈልግ አቅራቢ ነው — ማረጋገጫውን የጎን ኮንቴይነሩ ይይዛል)።
2. የጎን ኮንቴይነሩ Codex CLI **እስካሁን በመለያ ካልገባ**፣ የግንኙነት ጤና
ምርመራው _"እየሰራ ነው፣ ነገር ግን በመለያ አልገባም"_ ብሎ ያሳያል (ቀይ የማረጋገጫ ስህተት አይደለም)።
**በChatGPT ይግቡ**ን ይጠቀሙ፦ ይህ መደበኛውን Codex device-OAuth በአሳሽዎ
ውስጥ ያስኬዳል፣ ከዚያም በ**ማረጋገጫውን ተግብር** አማካኝነት `~/.codex/auth.json`ን ወደ የጋራ volume
ይጽፋል (ያው አንድ መግቢያ ለ`codex` እና ለ`codex-app-server`
አቅራቢዎች ያገለግላል)።
3. በመለያ ከገቡ በኋላ፣ የጤና ምርመራው አረንጓዴ ይሆናል (`/readyz`ን **እና**
`account/read`ን ያረጋግጣል — ማለትም አገልግሎቱ መነሳቱን _እና_ ማረጋገጫ ማግኘቱን) እና መስራት ይጀምራል።
ዳሽቦርዱ በትክክል እየሰራ ያለ `~/.codex/auth.json`ን ፈጽሞ አይተካም — የሚጽፈው
ፋይሉ ከሌለ ወይም ቶከኑ ጊዜው ካለፈበት ብቻ ነው (ምትኬ ሁልጊዜ ይወሰዳል)።
## 4. የማሰማሪያ ሁኔታዎች
- **አስቀድሞ ማረጋገጫ ያገኘ Codex CLI ያለው ኦፕሬተር** — የአስተናጋጅዎን
`~/.codex` በጎን ኮንቴይነሩ (`codex-appserver-home`) ውስጥ ይስቀሉ እና የመግቢያ ደረጃውን ይዝለሉ።
- **ይፋዊ ተጠቃሚ፣ codex በአካባቢው ያልተጫነ** — ችግር የለውም፦ የጎን ኮንቴይነሩ
CLIውን ይዟል። ተጠቃሚው በዳሽቦርዱ በኩል ብቻ ማረጋገጫ ያደርጋል።
- **Bare-metal OmniRoute (የጎን ኮንቴይነር የሌለው፣ የአስተናጋጅ codex)** —
`OMNIROUTE_CODEX_APPSERVER_WS`ን ወደ ራስዎ `codex app-server` ያመልክቱ እና የአስተናጋጁ
codex በመለያ መግባቱን ያረጋግጡ፤ binaryው ከሌለ "codex አልተጫነም" የሚለው ፍንጭ
ይታያል።
## 5. የመኖሪያ / UDP ወጪ ትራፊክ (ለኦፕሬተር ተጨማሪ፣ አብሮ አይቀርብም)
ከላይ ያለው አጠቃላይ የጎን ኮንቴይነር ወጪ ትራፊኩን በኮንቴይነሩ መደበኛ አውታረ መረብ ይልካል።
የCodex ትራፊክ በ**መኖሪያ መውጫ** በኩል እንዲወጣ የሚፈልግ ኦፕሬተር (ለምሳሌ TCP + UDP/QUICን
የሚያስተላልፍ TUN tailscale የጎን ኮንቴይነር) ያንን እንደ የተለየ compose
override ያስኬዳል፤ ሆን ተብሎም ከቀረበው `codex-app-server`
መገለጫ ውስጥ **አልተካተተም**። ለዚያ ውቅር ውስጣዊውን የኦፕሬሽን መመሪያ ይመልከቱ።

586
docs/i18n/am/docs/guides/CODEX-CLI-CONFIGURATION.md Normal file
View File

@@ -0,0 +1,586 @@
# Codex CLI — Configuration with OmniRoute (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/CODEX-CLI-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇩🇪 [de](../../../de/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇹 [it](../../../it/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇰🇷 [ko](../../../ko/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇵🇹 [pt](../../../pt/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇻🇳 [vi](../../../vi/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CODEX-CLI-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CODEX-CLI-CONFIGURATION.md)
---
Codex CLIን OmniRouteን እንደ OpenAI-ተኳሃኝ backend በመጠቆም ለመጠቀም የተሟላ መመሪያ።
---
> **TOML ብቸኛው ውጤታማ ቅርጸት ነው።** ዘመናዊው Codex `~/.codex/config.toml`ን
> ብቻ ያነባል (በ codex-cli 0.147.0 የተረጋገጠ፦ `codex --help`
> የ`-c/--config` መሻሮች “ከ`~/.codex/config.toml` የተጫነ” መሆኑን ይገልጻል)። የድሮው
> `~/.codex/config.yaml` የቀድሞው npm CLI ነበር እና ያለምንም ማሳወቂያ ችላ ይባላል።
> የdashboard ማመንጫው (`/api/cli-tools/apply`፣ መሣሪያ `codex`) TOMLን
> ጥንቃቄ በተሞላበት ውህደት ይጽፋል — ነባር ቁልፎች እና ሌሎች የprovider ብሎኮች ይጠበቃሉ፣
> የAPI ቁልፉ በ`OMNIROUTE_API_KEY` ውስጥ ይቆያል (ፈጽሞ በፋይሉ ውስጥ አይቀመጥም)፣ እና የቀረ
> የቀድሞ `config.yaml` ሳይነካ እንደ የሽግግር ማስታወሻ ሪፖርት ይደረጋል።
## በቀጥታ ለመለጠፍ ዝግጁ የሆነ config.toml
`<YOUR_HOST>` እና `<YOUR_KEY>`ን በእርስዎ እሴቶች ይተኩ፦
```toml
# ~/.codex/config.toml
model = "cx/gpt-5.5"
model_provider = "omniroute"
model_reasoning_effort = "xhigh"
model_context_window = 400000
model_auto_compact_token_limit = 350000
tool_output_token_limit = 32768 # ለእያንዳንዱ የመሣሪያ ጥሪ የታሪክ ማከማቻ ገደብ
[model_providers.omniroute]
name = "OmniRoute"
base_url = "http://<YOUR_HOST>:20128/v1"
env_key = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api = "responses"
```
```bash
# ~/.bashrc ወይም ~/.zshrc — ትክክለኛው የቁልፍ እሴት፣ ፈጽሞ በ config.toml ውስጥ አይቀመጥም
export OMNIROUTE_API_KEY="<YOUR_KEY>"
```
### macOS፦ በChatGPT መተግበሪያ ውስጥ የታሸገ Codex
Codexን በChatGPT ዴስክቶፕ መተግበሪያ በኩል ከጫኑት፣ የ`codex` binaryው
በመተግበሪያው bundle ውስጥ ብቻ ሊኖር እና ገና በshell `PATH`ዎ ላይ ላይኖር ይችላል።
የresources ማውጫውን ወደ shell ማስጀመሪያ ፋይልዎ ያክሉ፦
```bash
export PATH="/Applications/ChatGPT.app/Contents/Resources:$PATH"
```
አዲስ shell ይክፈቱ፣ ከዚያ ያረጋግጡ፦
```bash
command -v codex
codex --version
```
### ማረጋገጫ የማይፈልግ አካባቢያዊ OmniRoute፦ የplaceholder ቁልፍ በቂ ነው
Codex የመጀመሪያው ጥያቄ ከCLIው ከመውጣቱ **በፊት**
በ`env_key` የተጠቀሰው environment variable መኖሩን ያረጋግጣል። **አካባቢያዊው**
የOmniRoute instanceዎ auth የማይፈልግ ከሆነ፣ ባዶ ያልሆነ ማንኛውም placeholder ይሠራል፦
```bash
export OMNIROUTE_API_KEY="${OMNIROUTE_API_KEY:-local}"
```
የOmniRoute serverዎ የተጠበቀ ወይም የርቀት ከሆነ በምትኩ እውነተኛ ቁልፍ ይጠቀሙ።
> **የተለመዱ የhost አማራጮች**
>
> | መዳረሻ | URL |
> | --------------- | ----------------------------- |
> | አካባቢያዊ አውታረ መረብ | `http://192.168.0.1:20128/v1` |
> | Tailscale | `http://100.x.x.x:20128/v1` |
> | Loopback | `http://localhost:20128/v1` |
---
## `wire_api = "responses"` — ለሁሉም models የሚሠራው ለምንድን ነው
Codex CLI `wire_api = "chat"`ን (Chat Completions) በFebruary 2026 ከአገልግሎት ውጪ አድርጎታል፣ እና አሁን `wire_api = "responses"`ን (OpenAI Responses API) **ይጠይቃል**። `wire_api = "chat"`ን ማዋቀር ከv0.138 ጀምሮ ሲጀመር ወዲያውኑ crash እንዲያደርግ ያስከትላል።
GLM እና Kimiን ጨምሮ ብዙ providers አሁንም የChat Completions endpoint ብቻ ያቀርባሉ። DeepSeek V4 አሁን ከAnthropic-ተኳሃኝ endpoint ጋር ተወላጅ Responses APIንም ያቀርባል፤ OmniRoute Responsesን በነባሪነት ይጠቀማል፣ እና እያንዳንዱ DeepSeek connection የAnthropic ተኳሃኝነትን እንዲመርጥ ያስችለዋል።
**OmniRoute ይህን ያለማስታወቂያ ይፈታዋል፦**
```
Codex CLI
→ wire_api = "responses"
→ POST /v1/responses (OmniRoute)
→ OmniRoute የproviderውን ተወላጅ protocol ይመርጣል፣ አስፈላጊ ሲሆንም ይተረጉማል
→ POST /responses (DeepSeek V4) ወይም /chat/completions (Mistral / GLM / Kimi / ሌሎች)
```
OmniRouteን ሲጠቀሙ የተለየ translation proxy ፈጽሞ አያስፈልግዎትም። **ሁሉም models `wire_api = "responses"`ን ይጠቀማሉ** — OmniRoute ቀሪውን ያስተናግዳል።
> **`wire_api` ነባሪው ነው** — fieldው በነባሪነት `"responses"` ስለሚሆን ከ`config.toml` ሙሉ በሙሉ ሊቀር ይችላል። ዓላማውን እየመዘገቡ ከሆነ ብቻ በግልጽ ያዋቅሩት።
---
## የአውድ መስኮት እና ማጠቃለል
### የቶከን ውቅር መስኮች
| መስክ | መግለጫ |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `model_context_window` | ለገቢር ሞዴሉ አጠቃላይ የቶከን በጀት። ሞዴሉ በይፋ ባስታወቀው ገደብ ላይ ያዘጋጁት። |
| `model_auto_compact_token_limit` | የታሪክ ራስ-ሰር ማጠቃለልን የሚያስጀምር ገደብ። **ከፍተኛው፦ ከ`model_context_window` 90%** — ከ90% በላይ ያሉ እሴቶች ያለማሳወቂያ ችላ ይባላሉ። |
| `tool_output_token_limit` | በታሪክ ውስጥ ለእያንዳንዱ የመሣሪያ ጥሪ ውጤት የሚከማቹ ቶከኖች ገደብ። አንድ ትልቅ የመሣሪያ ምላሽ መስኮቱን እንዳይሞላ ይከላከላል። **ይህ ከፍተኛው የውጤት መጠን አይደለም** — የታሪክ ማከማቻ ገደብ ነው። |
| `compact_prompt` | በማጠቃለል ወቅት ጥቅም ላይ ለሚውለው የስርዓት መጠየቂያ የመስመር ውስጥ መሻሪያ (v0.138+)። |
> **ስለ `model_max_output_tokens` ማስታወሻ**፦ ይህ መስክ **የCodex CLI ውቅር መርሃግብር አካል አይደለም** (በCodex Rust ኮድ ማከማቻ ውስጥ የለም)። ከተዘጋጀ ያለማሳወቂያ ችላ ይባላል። በእሱ ላይ አይመኩ — በታሪክ ውስጥ የሚከማቸውን የመሣሪያ ውጤት መጠን ለመቆጣጠር `tool_output_token_limit`ን ይጠቀሙ።
### በሞዴል የተከፋፈሉ የአውድ መስኮቶች
| ሞዴል | OmniRoute ID | የአውድ መስኮት | `auto_compact` | `tool_output_limit` |
| ------------------------------------ | ------------------------------------ | --------------------- | -------------- | ------------------- |
| GPT-5.5 | `cx/gpt-5.5` | 400k አስተማማኝ (1M ከፍተኛ) | 350,000 | 32,768 |
| Kimi K2.7 (ማሰብ) | `kmc/kimi-k2.7` | 131,072 | 112,000 | 32,768 |
| Kimi K2.6 | `kmc/kimi-k2.6` | 131,072 | 112,000 | 32,768 |
| GLM-5.2 / 5.2-max (ማሰብ) | `glm/glm-5.2` | 131,072 | 112,000 | 32,768 |
| MiMo V2.5 Pro (ማሰብ) | `opencode-go/mimo-v2.5-pro` | 131,072 | 112,000 | 32,768 |
| Qwen 3.7 Plus (ማሰብ) | `opencode-go/qwen3.7-plus` | 32,768 | 28,000 | 16,384 |
| DeepSeek V4 Pro (OllamaCloud) | `ollamacloud/deepseek-v4-pro` | 131,072 | 112,000 | 32,768 |
| DeepSeek V4 Pro | `ds/deepseek-v4-pro` | 1,000,000 | 900,000 | 65,536 |
| MiMo V2.5 | `opencode-go/mimo-v2.5` | 131,072 | 112,000 | 32,768 |
| Gemma 4 31B (OllamaCloud) | `ollamacloud/gemma4:31b` | 32,768 | 28,000 | 16,384 |
| Nemotron 3 Super (OllamaCloud) | `ollamacloud/nemotron-3-super` | 32,768 | 28,000 | 16,384 |
| GPT-OSS 20B (OllamaCloud) | `ollamacloud/gpt-oss:20b` | 32,768 | 28,000 | 16,384 |
| DeepSeek V4 Flash (OllamaCloud) | `ollamacloud/deepseek-v4-flash` | 65,536 | 56,000 | 16,384 |
| Gemini 3 Flash Preview (OllamaCloud) | `ollamacloud/gemini-3-flash-preview` | 1,000,000 | 850,000 | 32,768 |
| GLM-5 Turbo | `glm/glm-5-turbo` | 131,072 | 112,000 | 16,384 |
| GLM-4.7 Flash | `glm/glm-4.7-flash` | 131,072 | 112,000 | 16,384 |
| Mistral Large Latest | `mistral/mistral-large-latest` | 262,144 | 220,000 | 16,384 |
> **የማጠቃለል ቀመር፦** `effective_window = model_context_window - min(tool_output_token_limit, 20000)`። ከ20k በላይ ያሉ እሴቶች የማጠቃለል ማስጀመሪያውን አይቀይሩም።
> **አጠቃላይ መመሪያ፦** `model_auto_compact_token_limit`ን ከ`model_context_window` 85–88% ላይ ያዘጋጁ። ፈጽሞ ከ90% በላይ አያድርጉት — ያለማሳወቂያ ችላ ይባላል።
---
## የሞዴል ቅድመ ቅጥያ፦ `cx/`
በOmniRoute ውስጥ ያሉ ሁሉም Codex ሞዴሎች `cx/` ቅድመ ቅጥያን ይጠቀማሉ፦
| የCodex CLI ስም | የOmniRoute ሞዴል |
| ----------------------- | ------------------ |
| `cx/gpt-5.5` | GPT-5.5 መደበኛ |
| `cx/gpt-5.4` | GPT-5.4 መደበኛ |
| `cx/gpt-5.4-mini` | GPT-5.4 mini |
| `cx/gpt-5.1-codex-mini` | GPT-5.1 Codex mini |
ሌሎች አቅራቢዎች የየራሳቸውን ቅድመ ቅጥያ (`kmc/`, `glm/`, `ds/`, `ollamacloud/`, `opencode-go/`, `mistral/`) ይጠቀማሉ — ቅድመ ቅጥያው ከOmniRoute አቅራቢ ተለዋጭ ስም ጋር ይዛመዳል።
---
## የማመዛዘን ጥረት
ሞዴሉ ምላሽ ከመስጠቱ በፊት ምን ያህል "እንደሚያስብ" ይቆጣጠራል።
| እሴት | የአጠቃቀም ዓላማ |
| -------- | --------------------------------- |
| `none` | ምንም ማመዛዘን የለም — ቀጥተኛ ምላሽ |
| `low` | ቀላል ተግባራት (ዳግም መሰየም፣ ቅርጸት ማስተካከል) |
| `medium` | ካልተገለጸ **የአገልጋይ ነባሪ** |
| `high` | መካከለኛ ተግባራት (ኮድን መልሶ ማዋቀር፣ ማረም) |
| `xhigh` | ሥነ ሕንፃ፣ ጥልቅ ትንተና፣ ውስብስብ ችግሮች |
```bash
# ለእያንዳንዱ ጥሪ መሻር
codex -c model_reasoning_effort=low "ተለዋዋጭ xን ወደ count ዳግም ሰይም"
codex -c model_reasoning_effort=xhigh "የauth ሞጁሉን ንደፍ"
```
Desktop የሐሳብ ጽሑፍን (የተመሰጠሩ ብሎቦችን ብቻ ሳይሆን) ማሳየት እንዲችል የማመዛዘን **ማጠቃለያ** ያዘጋጁ፦
```toml
# ~/.codex/config.toml
model_reasoning_effort = "xhigh" # ወይም በሚደገፍበት ጊዜ ultra
model_reasoning_summary = "detailed" # auto | concise | detailed | none
```
### የOmniRoute የማሰብ በጀት (የአገልጋይ ቅንብር)
በOmniRoute አስተናጋጅ ላይ ያለው **Settings → AI → Thinking Budget** የCodex ጥረት/ማጠቃለያ ወደ ላይኛው አቅራቢ እንዲደርስ **`passthrough`** መሆን አለበት። **`auto` ሁነታ** ሁሉንም የደንበኛ `reasoning` / `reasoning_effort` መስኮች ያስወግዳል፣ እና Codex በትክክል ቢዋቀርም የማሰብ ፓነሎችን ባዶ ያደርጋል።
ሙሉ መመሪያ፦ [THINKING_BUDGET.md](./THINKING_BUDGET.md)።
መጭመቅ እና የጥያቄ መሸጎጫ እርስ በርሳቸው የማይያያዙ ሲሆኑ፣ በ`passthrough` ስርም መሥራታቸውን ይቀጥላሉ።
---
## መገለጫዎች — ለእያንዳንዱ ሞዴል/የሥራ ፍሰት በስም የተቀመጡ ውቅሮች
መገለጫዎች በአንድ ጠቋሚ ሞዴልን + የአውድ መስኮትን እንዲቀይሩ ያስችሉዎታል። እያንዳንዱ መገለጫ በመሠረታዊው `config.toml` ላይ ተደራቢ የሚሆን ጠፍጣፋ
`~/.codex/<name>.config.toml` ፋይል ነው።
> **የስያሜ ደንብ (Codex CLI v0.137+)፦** ፋይሉ `~/.codex/<name>.config.toml` መሆን አለበት — **የ`profile-` ቅድመ ቅጥያ አይኖርም**።
> CLIው `-p kimi-k27` → `~/.codex/kimi-k27.config.toml` በማለት ይፈታዋል። ፋይሉ ካልተገኘ፣ ነባሪው ያለምንም ማሳወቂያ ይተገበራል።
```bash
codex --profile kimi-k27 "የዚህን ኮድ ማከማቻ 10k መስመሮች ተንትን"
codex -p glm52 "የሥነ ሕንፃ ግምገማ"
codex --profile deepseek-flash "ተለዋዋጩን ዳግም ሰይም" # ፈጣን፣ ርካሽ
```
### የጥረት መገለጫዎች (ተመሳሳይ ሞዴል፣ የተለያየ ጥረት)
```bash
codex -p low # cx/gpt-5.5, ጥረት=low
codex -p medium # cx/gpt-5.5, ጥረት=medium
codex -p high # cx/gpt-5.5, ጥረት=high
codex -p xhigh # cx/gpt-5.5, ጥረት=xhigh (ነባሪ)
codex -p chat # cx/gpt-5.5, ምንም ጥረት አልተቀመጠም (የአገልጋይ ነባሪ)
```
### የማሰብ ሞዴሎች (ከፍተኛ ማሰብ) — xhigh + ዝርዝር ማጠቃለያ
| መገለጫ | ሞዴል | አውድ | የአጠቃቀም ዓላማ |
| ------------ | --------------------------- | ---- | ------------------- |
| `kimi-k27` | `kmc/kimi-k2.7` | 128k | ምርጥ የማሰብ ጥራት (Kimi) |
| `glm52` | `glm/glm-5.2` | 128k | GLM ማሰብ |
| `glm52max` | `glm/glm-5.2-max` | 128k | ከፍተኛው GLM ማሰብ |
| `mimo-pro` | `opencode-go/mimo-v2.5-pro` | 128k | MiMo ማሰብ |
| `qwen37plus` | `opencode-go/qwen3.7-plus` | 32k | Qwen ማሰብ |
### ጥሩ ሞዴሎች — ከፍተኛ ጥረት
| መገለጫ | ሞዴል | አውድ | የአጠቃቀም ዓላማ |
| -------------- | ----------------------------- | ---- | ----------------------------- |
| `kimi-k26` | `kmc/kimi-k2.6` | 128k | አጠቃላይ ዓላማ (Kimi) |
| `deepseek-pro` | `ollamacloud/deepseek-v4-pro` | 128k | DeepSeek Pro በOllamaCloud በኩል |
| `deepseek` | `ds/deepseek-v4-pro` | 1M | DeepSeek Pro ቀጥተኛ፣ ግዙፍ አውድ |
| `mimo` | `opencode-go/mimo-v2.5` | 128k | MiMo አጠቃላይ |
### ቀላል ሞዴሎች — ምንም የማመዛዘን ጥረት የሌላቸው
| መገለጫ | ሞዴል | አውድ | የአጠቃቀም ዓላማ |
| ---------- | ------------------------------ | --- | --------------- |
| `gemma4` | `ollamacloud/gemma4:31b` | 32k | ወጪ ቆጣቢ፣ ብቃት ያለው |
| `nemotron` | `ollamacloud/nemotron-3-super` | 32k | NVIDIA Nemotron |
| `gptoss` | `ollamacloud/gpt-oss:20b` | 32k | ክፍት ምንጭ GPT |
### ፈጣን ሞዴሎች — ዝቅተኛ ጥረት
| መገለጫ | ሞዴል | አውድ | የአጠቃቀም ዓላማ |
| ---------------- | ------------------------------------ | ---- | ---------------- |
| `deepseek-flash` | `ollamacloud/deepseek-v4-flash` | 64k | ፈጣን ተግባራት |
| `gemini-flash` | `ollamacloud/gemini-3-flash-preview` | 1M | በጣም ፈጣን፣ ግዙፍ አውድ |
| `glm5turbo` | `glm/glm-5-turbo` | 128k | GLM Turbo |
| `glm47flash` | `glm/glm-4.7-flash` | 128k | GLM Flash |
| `mistral` | `mistral/mistral-large-latest` | 256k | Mistral Large |
### ፈጣን የውሳኔ ሰንጠረዥ
| ተግባር | የሚመከር ፕሮፋይል |
| ------------------------------ | ------------------------------------------------- |
| ስም መቀየር፣ ቅርጸት ማስተካከል፣ መሠረታዊ ኮድ | `--profile deepseek-flash` ወይም `-p low` |
| ማብራራት፣ ቀላል ግምገማ | `-p chat` ወይም `-p gemini-flash` |
| ስህተት ማረም፣ መጠነኛ የኮድ መዋቅር ማሻሻያ | `-p medium` ወይም `-p kimi-k26` |
| አዲስ ባህሪ፣ ውስብስብ ሙከራዎች | `-p high` ወይም `-p mimo` |
| አርክቴክቸር፣ ጥልቅ ትንተና | `-p kimi-k27` ወይም `-p glm52` ወይም `-p xhigh` |
| የኮድ ማከማቻ ትንተና (1M ctx ያስፈልገዋል) | `--profile deepseek` ወይም `--profile gemini-flash` |
| ከፍተኛው የማሰብ ጥራት | `-p glm52max` ወይም `-p mimo-pro` |
| ወጪን የሚቆጥብ | `-p gemma4` ወይም `-p gptoss` |
---
## በ`omniroute setup-codex` ፕሮፋይሎችን በራስ-ሰር ማመንጨት
OmniRouteን በVPS ላይ ካስኬዱ፣ ከቀጥታ የሞዴል ካታሎጉ የፕሮፋይል ፋይሎችን በራስ-ሰር ማመንጨት ይችላሉ፦
```bash
# ከVPS (በፖርት 20128 ላይ ያለውን አካባቢያዊ OmniRoute ይጠቀማል)
omniroute setup-codex
# ከማንኛውም ማሽን — ወደ VPSዎ ያመልክቱ
omniroute setup-codex --remote http://100.x.x.x:20128 --api-key sk-xxx
# ፋይሎችን ሳይጽፉ ቅድመ-ዕይታ
omniroute setup-codex --remote http://100.x.x.x:20128 --dry-run
# የGLM እና Kimi ፕሮፋይሎችን ብቻ ያመንጩ
omniroute setup-codex --only glm,kimi
# ወደ ብጁ ማውጫ ይጻፉ
omniroute setup-codex --codex-home /path/to/.codex
```
ትዕዛዙ `/v1/models`ን ያመጣል፣ ለሚታወቁ ሞዴሎች የተስተካከሉ ፕሮፋይሎችን ይጠቀማል፣ ለሌሎች ተኳዃኝ የጽሑፍ ሞዴሎች ደግሞ ወደ ካታሎግ ሜታዳታ ይመለሳል፤ ለእያንዳንዱም `~/.codex/<name>.config.toml`ን ይጽፋል። ኢደምፖተንት ነው — እንደገና ማስኬድ ደህንነቱ የተጠበቀ ነው።
OmniRoute የአቅራቢ ሞዴል ማግኘት/ማስመጣት ቀጥታ ካታሎጉን በተሳካ ሁኔታ ከቀየረ በኋላ እነዚህን ተመሳሳይ የፕሮፋይል ፋይሎች **በራስ-ሰር ማመሳሰል**ም ይችላል። ይህ **በምርጫ የሚነቃ ሲሆን በነባሪነት ጠፍቷል**፦ ከ**CLI Code ዳሽቦርድ** ("CLI profile auto-sync" → Codex) ያብሩት፣ ወይም `OMNIROUTE_AUTO_SYNC_CODEX_PROFILES=true`ን ያዘጋጁ (`CLI_ALLOW_CONFIG_WRITES`ንም ያከብራል፤ ይህም በነባሪነት በርቷል)። ሲነቃ የተለዩ `~/.codex/*.config.toml` የፕሮፋይል ፋይሎችን ብቻ ይጽፋል፤ ንቁ/ነባሪውን `~/.codex/config.toml`፣ የCodex-lb ቅንብሮችን፣ ማረጋገጫን ወይም የአቅራቢ ምርጫን በፍጹም አይቀይርም።
---
## Codexን በ`omniroute launch-codex` ማስጀመር
Codexን ከማስጀመሩ በፊት የOmniRoute ኢንስታንስዎን የጤና ሁኔታ ይፈትሻል፦
```bash
# በአካባቢያዊ OmniRoute ላይ ያስጀምሩ (ነባሪ ፖርት 20128)
omniroute launch-codex
# በተወሰነ ፕሮፋይል ያስጀምሩ
omniroute launch-codex --profile kimi-k27
# በርቀት VPS ላይ ያስጀምሩ
omniroute launch-codex --remote http://100.x.x.x:20128/v1 --api-key sk-xxx
# ተጨማሪ ነጋሪ እሴቶችን ለcodex ያስተላልፉ
omniroute launch-codex --profile glm52 -- --yolo "fix this bug"
```
Codex በማኒፌስት የሚመሩት ሁለቱ አጠቃላይ የመግቢያ ነጥቦችም ዒላማ ነው
(`bin/cli/cli-manifest.mjs`)፦
```bash
# መስተጋብራዊ የሞዴል መራጭ → ~/.codex/<name>.config.toml ይጽፋል (TOML, env_key)
omniroute configure codex
# የomniroute አቅራቢን በ-c ሰንደቆች በማስገባት codexን ያስጀምሩ (ምንም ውቅር አይጻፍም)
omniroute run codex
```
---
## አዲስ የCodex CLI ባህሪያት (v0.138–v0.141)
| ስሪት | ባህሪ |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.138 | ወደ ዴስክቶፕ መተግበሪያ ማስተላለፍ (`/app`)፣ v2 የግል መዳረሻ ቶከኖች፣ `--profile` እንደ ብቸኛው የፕሮፋይል መራጭ (የቆዩ በፋይል ውስጥ ያሉ `[profiles]` ሰንጠረዦች ሲጀመር ብልሽት ያስከትላሉ) |
| v0.139 | `web_search = "live"` — ከኮድ ሁነታ ቤተኛ የድር ፍለጋ፤ በMCP መሣሪያ ስኪማዎች ውስጥ `oneOf`/`allOf`፤ `codex doctor` የenv ምርመራዎች |
| v0.140 | በክፍለ-ጊዜ ውስጥ `/usage` የቶከን ዕይታ፤ ከClaude Code ክፍለ-ጊዜዎች `/import`፤ `codex delete <SESSION_ID>` ንዑስ ትዕዛዝ፤ በአቅራቢ ውቅር ውስጥ ባለ `aws` ኦብጀክት የAmazon Bedrock ማረጋገጫ |
| v0.141 | ለርቀት አስፈጻሚዎች E2E የተመሰጠረ Noise ሪሌይ፤ የSQLite WAL ማስተካከያ፤ የP-521 TLS ድጋፍ |
### አዲስ የ`config.toml` መስኮች (ከv0.137 በኋላ)
```toml
# ቤተኛ የድር ፍለጋ (v0.139)
web_search = "live" # "disabled" | "cached" | "live"
# የተለየ የገንቢ ስርዓት መመሪያ (v0.138)
developer_instructions = "Always prefer functional style."
# ብጁ የማጠቃለያ መመሪያ
compact_prompt = "Summarise the above as bullet points."
# /reviewን ወደ ርካሽ ሞዴል ይምሩ
review_model = "glm/glm-5-turbo"
# የOpenAI አገልግሎት ደረጃ
service_tier = "fast" # "fast" | "flex"
```
### አዲስ የ`[model_providers.<id>]` መስኮች
```toml
[model_providers.omniroute]
base_url = "http://100.x.x.x:20128/v1"
env_key = "OMNIROUTE_API_KEY"
requires_openai_auth = false
# በእያንዳንዱ ጥያቄ ላይ የማይለወጡ ተጨማሪ ራስጌዎች
[model_providers.omniroute.http_headers]
"X-Custom-Header" = "value"
# ከenv vars የሚነበቡ ራስጌዎች
[model_providers.omniroute.env_http_headers]
"X-Trace-Id" = "TRACE_ID"
# ተጨማሪ የURL መጠይቅ መለኪያዎች (ለAzure api-version ጠቃሚ)
[model_providers.omniroute.query_params]
"api-version" = "2024-12-01-preview"
```
### የAmazon Bedrock ማረጋገጫ (v0.140)
```toml
[model_providers.bedrock]
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"
[model_providers.bedrock.aws]
profile = "default" # ~/.aws/credentials ፕሮፋይል
region = "us-east-1"
```
---
## በርካታ ሰርቨሮች
```toml
[model_providers.omniroute-main]
base_url = "http://192.168.0.1:20128/v1"
env_key = "OMNIROUTE_API_KEY"
[model_providers.omniroute-tailscale]
base_url = "http://100.x.x.x:20128/v1"
env_key = "OMNIROUTE_API_KEY"
```
---
## Claude Code — ተመጣጣኝ ውቅር
| Codex CLI (`config.toml`) | Claude Code (የአካባቢ ተለዋዋጭ) | ውጤት |
| --------------------------------- | ------------------------------------- | ------------------------- |
| `tool_output_token_limit = 32768` | _(በቀጥታ አልተጋለጠም)_ | የእያንዳንዱ መሣሪያ ታሪክ ገደብ |
| `model_context_window = 400000` | _(በሞዴሉ የሚወሰን)_ | የአውድ መስኮት |
| — | `CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536` | በእያንዳንዱ ምላሽ ከፍተኛው ቶከን ብዛት |
```bash
# ~/.bashrc — የClaude Code ቶከን ገደብ
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536
```
---
## ፈጣን ማጣቀሻ — የCLI ጠቋሚዎች
| ጠቋሚ | አጭር ቅጽ | ውጤት |
| --------------------- | ------ | ---------------------------------------- |
| `--model <id>` | `-m` | ለዚህ አስነሳስ `model`ን ይተካል |
| `--profile <name>` | `-p` | `~/.codex/<name>.config.toml`ን ይጭናል |
| `--config key=value` | `-c` | ማንኛውንም የconfig.toml መስክ ይተካል (ሊደገም የሚችል) |
| `--enable <feature>` | — | የባህሪ ጠቋሚን በግድ ያነቃል |
| `--disable <feature>` | — | የባህሪ ጠቋሚን በግድ ያሰናክላል |
| `--search` | — | ለዚህ አስነሳስ የቀጥታ ድር ፍለጋን ያነቃል |
በv0.140 አዲስ፦
```bash
codex delete <SESSION_ID> # አንድን ክፍለ ጊዜ ሰርዝ
codex delete <SESSION_ID> --force # ማረጋገጫን ዝለል
codex debug models --bundled # አብሮ የታሸገውን የሞዴል ካታሎግ እንደ JSON ዘርዝር
```
በበይነተገናኝ ክፍለ ጊዜ ውስጥ፦
| ትዕዛዝ | ውጤት |
| --------- | ------------------------------------ |
| `/model` | የሞዴል መምረጫውን ይከፍታል |
| `/usage` | ለዚህ ክፍለ ጊዜ የቶከን አጠቃቀምን ያሳያል (v0.140) |
| `/app` | ወደ ዴስክቶፕ መተግበሪያው ያስተላልፋል (v0.138) |
| `/import` | የClaude Code ክፍለ ጊዜን ያስመጣል (v0.140) |
| `/help` | ሁሉንም የስላሽ ትዕዛዞች ይዘረዝራል |
---
## ለረጅም ጊዜ የሚሄዱ ተግባራት
ሁለት የOmniRoute ነባሪ ቅንብሮች ለብዙ ሰዓታት የሚቆዩ የCodex CLI ክፍለ ጊዜዎችን በድብቅ ሊያበላሹ ይችላሉ። አንዳቸውም የCodex CLI ቅንብር አይደሉም — ሁለቱም በOmniRoute በኩል ይገኛሉ። መለያዎችን ከሚያጣብቁ እና የስራ-ፈት ጊዜ ማቋረጫዎችን ከሚያሰናክሉ የላይኛው ዥረት ፕሮክሲዎች ውቅርን የሚያዛውሩ ተጠቃሚዎች ብዙውን ጊዜ ሁለቱንም ችግሮች ያጋጥማቸዋል እና OmniRoute “ረጅም ክፍለ ጊዜን ማስቀጠል አይችልም” ብለው ይደመድማሉ።
| ምልክት | ሊሆን የሚችለው ምክንያት | ማስተካከያ |
| ---------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------ |
| ክፍለ ጊዜው መለያዎችን መቀያየሩን ይቀጥላል / በዙሮች መካከል የprompt-cache ቀጣይነት ይጠፋል | የክፍለ ጊዜ ቁርኝት TTL `0` ነው (ተሰናክሏል) | `sessionAffinityTtlMs` |
| ለደንበኛው የሚታይ ማሳወቂያ ሳይኖር ግንኙነቱ በማመዛዘን መሃል ይቋረጣል | ከላይኛው ዥረት ምንም ቁራጭ ሳይመጣ ከ10 ደቂቃ በኋላ የዥረት ስራ-ፈት ተቆጣጣሪው ተነስቷል | `STREAM_IDLE_TIMEOUT_MS` |
ተዛማጅ ውይይቶች፦ [#7126](https://github.com/diegosouzapw/OmniRoute/discussions/7126) (የረጅም ተግባር መቋረጦች)፣ [#5718](https://github.com/diegosouzapw/OmniRoute/discussions/5718) (ቁርኝት በነባሪ የሚጠፋበት ምክንያት)። ክትትል፦ [#7287](https://github.com/diegosouzapw/OmniRoute/issues/7287)።
### 1. የክፍለ ጊዜ ቁርኝት — አንድን ውይይት ከአንድ መለያ ጋር ማጣበቅ
**ነባሪ፦** `sessionAffinityTtlMs = 0` (ተሰናክሏል)።
**የሚዋቀርበት ቦታ**
- ዳሽቦርድ → **ቅንብሮች → ማዞሪያ** → **የክፍለ ጊዜ ቁርኝት** → **የቁርኝት TTL (ሰከንዶች)** (`ComboDefaultsTab`)
- ወይም ቅንብሮችን በ`sessionAffinityTtlMs` እና **ሚሊሰከንዶች** በመጠቀም PATCH ያድርጉ (የZod ክልል `0`–`86_400_000`፣ ማለትም እስከ 24 ሰዓታት)
> በ#7274 ውስጥ ከCodex-ብቻ `codexSessionAffinityTtlMs` ስሙ ተቀይሯል። የቀድሞው ቁልፍ አሁንም እንደ ለንባብ-ብቻ ተለዋጭ ስም ተቀባይነት አለው፤ አዳዲስ ውቅሮች `sessionAffinityTtlMs`ን መጠቀም አለባቸው። አሁን TTL ከ`0` በላይ ከሆነ ቁርኝት በCodex ብቻ ሳይሆን በ**ማንኛውም** አቅራቢ ላይ ይተገበራል — [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md) → የክፍለ ጊዜ ቁርኝትን ይመልከቱ።
**በ0 ላይ ሲቆይ የሚበላሸው ነገር**
ባለብዙ ዙር የCodex ውይይት እያንዳንዱ ዙር በንቁው የcombo ስትራቴጂ በተናጥል ይመራል እና በ**እያንዳንዱ ዙር የተለየ መለያ** ላይ ሊደርስ ይችላል። ይህም የላይኛው ዥረት ክፍለ ጊዜ / የprompt-cache ቀጣይነትን ያቋርጣል። OmniRoute የCodex ክፍለ ጊዜ ራስጌዎችን (`x-codex-session-id` / `x-session-id` / `x-omniroute-session`) እና እንደ `prompt_cache_key` / `session_id` ያሉ የbody መስኮችን የሚመለከተው TTL ከ`0` በላይ ሲሆን ብቻ ነው (`extractSessionAffinityKey` በ`src/sse/services/auth.ts` ውስጥ)።
**ለብዙ ሰዓታት ለሚቆይ ነጠላ ተግባር የሚመከር**
TTLን **ከተግባሩ ከሚጠበቀው የጠቅላላ የሰዓት ርዝመት በላይ** ያዘጋጁ (የUI ከፍተኛው **86400 ሰከንዶች** = 24 ሰዓታት ነው)፦
| የሚጠበቀው የተግባር ርዝመት | የቁርኝት TTL (UI፣ ሰከንዶች) | `sessionAffinityTtlMs` |
| ----------------- | --------------------- | ---------------------- |
| ጥቂት ሰዓታት | `14400` (4h) | `14400000` |
| ሌሊቱን ሙሉ / ~12h | `43200` (12h) | `43200000` |
| ሙሉ ቀን | `86400` (24h፣ ከፍተኛው) | `86400000` |
መርጦ መግባት ሆን ተብሎ የተደረገ ነው፦ ቁርኝትን ማሰናከል በመለያዎች መካከል የጭነት ማመጣጠንን ይደግፋል፤ ማንቃት ደግሞ ለአንድ ረጅም የወኪል ክፍለ ጊዜ ቀጣይነትን ይደግፋል። ይህ መመሪያ ነባሪውን **አይለውጥም** — ረጅም የCodex ተግባራትን የሚያስኬዱ ኦፕሬተሮች መርጠው መግባት አለባቸው።
### 2. የዥረት ስራ-ፈት ጊዜ ገደብ — ጸጥ ያሉ የማመዛዘን ዙሮችን አታቋርጡ
**ነባሪ፦** `STREAM_IDLE_TIMEOUT_MS = 600000` (10 ደቂቃዎች)። ካልተዋቀረ `REQUEST_TIMEOUT_MS`ን ይወርሳል፤ የጋራው መነሻ መስመርም 600000 ነው። [`docs/guides/SETUP_GUIDE.md`](SETUP_GUIDE.md) → የጊዜ ገደቦችን ይመልከቱ።
**በነባሪው ላይ የሚበላሸው ነገር**
ከ10 ደቂቃዎች በላይ **ምንም እውነተኛ upstream chunk ሳይኖር** ዝም ብሎ የሚቆይ የCodex reasoning / tool turn በSSE idle watchdog (`open-sse/utils/stream.ts`) በግድ ይዘጋል። ደንበኛው ብዙውን ጊዜ ምንም መልዕክት ሳይኖር ግንኙነቱ ሲቋረጥ ብቻ ያያል — ይህም “ምንም ማሳወቂያ ሳይኖር በራስ-ሰር ቆመ” ከሚለው ጋር ይዛመዳል።
ወሳኝ ዝርዝር፦ የOmniRoute ሰው ሠራሽ SSE **heartbeat የidle ሰዓት ቆጠራውን ዳግም አያስጀምርም**። `lastChunkTime`ን የሚያዘምነው እውነተኛ upstream body chunk ብቻ ነው። አሁንም “እያሰበ” ያለ ጸጥ ያለ ሞዴል፣ ከwatchdog እይታ አንጻር ከቆመ upstream ጋር ተመሳሳይ ይመስላል።
ተዛማጅ የUndici body inactivity፦ `FETCH_BODY_TIMEOUT_MS` (ይህም በነባሪ ተመሳሳዩን የ10 ደቂቃ መነሻ ይጠቀማል፤ `0` ያሰናክለዋል)። ለstreaming፣ `FETCH_TIMEOUT_MS` የሚሸፍነው የግንኙነት ማዋቀርን / የመጀመሪያ headersን ብቻ ነው — streamው ንቁ ከሆነ በኋላ፣ መቆም የሚተዳደረው በ`STREAM_IDLE_TIMEOUT_MS` እና `FETCH_BODY_TIMEOUT_MS` ነው።
**ለብዙ ሰዓታት የሚቆይ አንድ ተግባር የሚመከር**
በOmniRoute process environment (`.env` / compose / systemd) ውስጥ፦
```bash
# ለረጅም reasoning turns የstream idle + body inactivity ማቋረጫዎችን ያሰናክሉ
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0
```
ወይም ከሚጠብቁት ረጅሙ የጸጥታ ክፍተት በላይ ያድርጓቸው (እሴቶቹ በሚሊሰከንድ ናቸው)፦
```bash
# ምሳሌ፦ በupstream chunks መካከል እስከ 2 ሰዓታት የሚደርስ ጸጥታን ይፍቀዱ
STREAM_IDLE_TIMEOUT_MS=7200000
FETCH_BODY_TIMEOUT_MS=7200000
```
እነዚህን env vars ከቀየሩ በኋላ OmniRouteን ዳግም ያስጀምሩ።
### ተግባራዊ የአሠራር ዘዴ — የብዙ ሰዓታት Codex ተግባር
1. **መለያውን ይሰኩ፦** Dashboard → Settings → Routing → Session affinity → Affinity TTL = `43200` (12h) ወይም `86400` (ከፍተኛው 24h)።
2. በOmniRoute environment ውስጥ **የidle ማቋረጫዎችን ያሳድጉ / ያሰናክሉ**፦
```bash
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0
```
3. የተለመደውን Codex `config.toml` (`wire_api = "responses"`፣ ትክክለኛ `base_url`፣ `OMNIROUTE_API_KEY`) ያቆዩ — ለእነዚህ ሁለት ባህሪያት በCodex በኩል ያሉ affinity/idle knobs የሉም።
4. OmniRouteን ዳግም ያስጀምሩ፣ ከዚያም ረጅሙን Codex ተግባር ይጀምሩ።
### የነባሪ ቅንብሮች ውሳኔ (#7287)
| Knob | የሚላከው ነባሪ | በዚህ መመሪያ ውስጥ ይቀየር? |
| ------------------------ | ----------------- | ----------------------------------------------------------------------------------- |
| `sessionAffinityTtlMs` | `0` (ጠፍቷል) | **አይ** — በምርጫ የሚነቃ ሆኖ ይቀጥላል (load-balancing እና continuity፤ Discussion #5718ን ይመልከቱ) |
| `STREAM_IDLE_TIMEOUT_MS` | `600000` (10 ደቂቃ) | **አይ** — ለአጠቃላይ traffic 10 ደቂቃ ሆኖ ይቀጥላል፤ የረጅም Codex ኦፕሬተሮች ያሳድጉታል ወይም ያሰናክሉታል |
ከሁለቱ ነባሪዎች አንዱን በዓለም አቀፍ ደረጃ መቀየር፣ የCodexን ብቻ ሳይሆን የአንድ instanceን እያንዳንዱን client ባህሪ ይቀይራል። knobsን በሰነድ ይግለጹ፤ ግልጽ የoperator ውሳኔ ሌላ እስኪል ድረስ ነባሪዎቹን እንዳሉ ይተዉ።
### የidle መቋረጦችን መመርመር
idle watchdog ሲነሳ፣ OmniRoute እንደሚከተለው የተቀረጸ መስመር log ያደርጋል፦
```text
[STREAM] Idle timeout: no data from codex for 600000ms (model: cx/gpt-5.5)
```
`Idle timeout: no data from`ን (ወይም code `stream_idle_timeout`ን / error name `StreamIdleTimeoutError`ን) grep ያድርጉ። provider segment ማለት OmniRoute ለዚያ request የተጠቀመው ማንኛውም ነገር (`codex`፣ ሌላ provider id፣ ወይም የማይታወቅ ከሆነ `provider`) ነው — ሁልጊዜ ቃል በቃል `codex` አይደለም።
---
## የችግኝ መፍቻ
**`Error: wire_api = "chat" is no longer supported`**
ከውቅርዎ ውስጥ `wire_api = "chat"`ን ያስወግዱ። `wire_api = "responses"`ን ያዘጋጁ ወይም መስኩን ይተዉት (ከv0.138 ጀምሮ ነባሪው `"responses"` ነው)።
**`Error: model not found`**
ሞዴሉ በትክክለኛው ቅድመ ቅጥያ በOmniRoute ውስጥ መኖሩን ያረጋግጡ። `omniroute models list`ን ይጠቀሙ ወይም `/dashboard/providers/<provider>`ን ይክፈቱ።
**`Authentication error`**
`OMNIROUTE_API_KEY` ወደ አካባቢ ተለዋዋጭነት መላኩን ያረጋግጡ፦ `echo $OMNIROUTE_API_KEY`።
**`ERROR: Missing environment variable: OMNIROUTE_API_KEY`**
Codex የመጀመሪያውን ጥያቄ ከመላኩ በፊት የአካባቢ ተለዋዋጩ መኖሩን ያረጋግጣል። ለተጠበቁ ሰርቨሮች እውነተኛ ቁልፍ ወደ አካባቢው ይላኩ፤ ወይም **አካባቢያዊው** OmniRoute ምሳሌዎ ማረጋገጫ የማይፈልግ ከሆነ፣ እንደ `OMNIROUTE_API_KEY=local` ያለ ባዶ ያልሆነ ጊዜያዊ እሴት ይጠቀሙ። ይህን ወደ `~/.bashrc` ወይም `~/.zshrc` ካከሉት ሼሉን እንደገና ያስጀምሩ።
**`Connection refused`**
OmniRoute እየሰራ መሆኑን እና የ`base_url` አስተናጋጅ/ወደብ ለአውታረ መረብዎ (አካባቢያዊ፣ Tailscale ወይም VPS) ትክክል መሆኑን ያረጋግጡ።
**ክፍለ ጊዜው የአውድ ገደቡ አቅራቢያ ይቋረጣል**
`model_context_window`ን እና `model_auto_compact_token_limit`ን በግልጽ ያዘጋጁ። ከላይ ያለውን የአውድ መስኮት ሰንጠረዥ ይመልከቱ።
**ማጠቃለሉ በጣም ዘግይቶ ይጀምራል**
`model_auto_compact_token_limit`ን ወደ 80–85% የመስኮቱ መጠን ዝቅ ያድርጉ። ከ90% በላይ በፍጹም አያዘጋጁት።
**መገለጫው አይጫንም (`-p <name>` ያለማስጠንቀቂያ ችላ ይባላል)**
ፋይሉ በ`~/.codex/<name>.config.toml` (`profile-` ቅድመ ቅጥያ ሳይኖረው) መኖሩን ያረጋግጡ። `ls ~/.codex/*.config.toml`ን ያስኪዱ።
**ረጅም የCodex ተግባር በመሃል ይቋረጣል / በዙሮች መካከል መለያዎችን ይቀይራል**
[ረጅም ጊዜ የሚሰሩ ተግባራት](#long-running-tasks)ን ይመልከቱ። የክፍለ ጊዜ ቁርኝትን (TTL ከተግባሩ ቆይታ በላይ ሆኖ) ያንቁ እና `STREAM_IDLE_TIMEOUT_MS` / `FETCH_BODY_TIMEOUT_MS`ን ይጨምሩ ወይም ያሰናክሉ። በOmniRoute ምዝግቦች ውስጥ `Idle timeout: no data from`ን በgrep ይፈልጉ።

249
docs/i18n/am/docs/guides/COST_TRACKING.md Normal file
View File

@@ -0,0 +1,249 @@
# Cost & Spend Tracking (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/COST_TRACKING.md) · 🇸🇦 [ar](../../../ar/docs/guides/COST_TRACKING.md) · 🇦🇿 [az](../../../az/docs/guides/COST_TRACKING.md) · 🇧🇬 [bg](../../../bg/docs/guides/COST_TRACKING.md) · 🇧🇩 [bn](../../../bn/docs/guides/COST_TRACKING.md) · 🇨🇿 [cs](../../../cs/docs/guides/COST_TRACKING.md) · 🇩🇰 [da](../../../da/docs/guides/COST_TRACKING.md) · 🇩🇪 [de](../../../de/docs/guides/COST_TRACKING.md) · 🇬🇷 [el](../../../el/docs/guides/COST_TRACKING.md) · 🇪🇸 [es](../../../es/docs/guides/COST_TRACKING.md) · 🇪🇪 [et](../../../et/docs/guides/COST_TRACKING.md) · 🇮🇷 [fa](../../../fa/docs/guides/COST_TRACKING.md) · 🇫🇮 [fi](../../../fi/docs/guides/COST_TRACKING.md) · 🇫🇷 [fr](../../../fr/docs/guides/COST_TRACKING.md) · 🇮🇪 [ga](../../../ga/docs/guides/COST_TRACKING.md) · 🇮🇳 [gu](../../../gu/docs/guides/COST_TRACKING.md) · 🇳🇬 [ha](../../../ha/docs/guides/COST_TRACKING.md) · 🇮🇱 [he](../../../he/docs/guides/COST_TRACKING.md) · 🇮🇳 [hi](../../../hi/docs/guides/COST_TRACKING.md) · 🇭🇷 [hr](../../../hr/docs/guides/COST_TRACKING.md) · 🇭🇺 [hu](../../../hu/docs/guides/COST_TRACKING.md) · 🇦🇲 [hy](../../../hy/docs/guides/COST_TRACKING.md) · 🇮🇩 [id](../../../id/docs/guides/COST_TRACKING.md) · 🇳🇬 [ig](../../../ig/docs/guides/COST_TRACKING.md) · 🇮🇹 [it](../../../it/docs/guides/COST_TRACKING.md) · 🇯🇵 [ja](../../../ja/docs/guides/COST_TRACKING.md) · 🇬🇪 [ka](../../../ka/docs/guides/COST_TRACKING.md) · 🇰🇭 [km](../../../km/docs/guides/COST_TRACKING.md) · 🇮🇳 [kn](../../../kn/docs/guides/COST_TRACKING.md) · 🇰🇷 [ko](../../../ko/docs/guides/COST_TRACKING.md) · 🇱🇹 [lt](../../../lt/docs/guides/COST_TRACKING.md) · 🇱🇻 [lv](../../../lv/docs/guides/COST_TRACKING.md) · 🇮🇳 [ml](../../../ml/docs/guides/COST_TRACKING.md) · 🇮🇳 [mr](../../../mr/docs/guides/COST_TRACKING.md) · 🇲🇾 [ms](../../../ms/docs/guides/COST_TRACKING.md) · 🇲🇹 [mt](../../../mt/docs/guides/COST_TRACKING.md) · 🇲🇲 [my](../../../my/docs/guides/COST_TRACKING.md) · 🇳🇵 [ne](../../../ne/docs/guides/COST_TRACKING.md) · 🇳🇱 [nl](../../../nl/docs/guides/COST_TRACKING.md) · 🇳🇴 [no](../../../no/docs/guides/COST_TRACKING.md) · 🇮🇳 [or](../../../or/docs/guides/COST_TRACKING.md) · 🇮🇳 [pa](../../../pa/docs/guides/COST_TRACKING.md) · 🇵🇭 [phi](../../../phi/docs/guides/COST_TRACKING.md) · 🇵🇱 [pl](../../../pl/docs/guides/COST_TRACKING.md) · 🇵🇹 [pt](../../../pt/docs/guides/COST_TRACKING.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/COST_TRACKING.md) · 🇷🇴 [ro](../../../ro/docs/guides/COST_TRACKING.md) · 🇷🇺 [ru](../../../ru/docs/guides/COST_TRACKING.md) · 🇱🇰 [si](../../../si/docs/guides/COST_TRACKING.md) · 🇸🇰 [sk](../../../sk/docs/guides/COST_TRACKING.md) · 🇸🇮 [sl](../../../sl/docs/guides/COST_TRACKING.md) · 🇷🇸 [sr](../../../sr/docs/guides/COST_TRACKING.md) · 🇸🇪 [sv](../../../sv/docs/guides/COST_TRACKING.md) · 🇰🇪 [sw](../../../sw/docs/guides/COST_TRACKING.md) · 🇮🇳 [ta](../../../ta/docs/guides/COST_TRACKING.md) · 🇮🇳 [te](../../../te/docs/guides/COST_TRACKING.md) · 🇹🇭 [th](../../../th/docs/guides/COST_TRACKING.md) · 🇹🇷 [tr](../../../tr/docs/guides/COST_TRACKING.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/COST_TRACKING.md) · 🇵🇰 [ur](../../../ur/docs/guides/COST_TRACKING.md) · 🇺🇿 [uz](../../../uz/docs/guides/COST_TRACKING.md) · 🇻🇳 [vi](../../../vi/docs/guides/COST_TRACKING.md) · 🇳🇬 [yo](../../../yo/docs/guides/COST_TRACKING.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/COST_TRACKING.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/COST_TRACKING.md)
---
OmniRoute የእያንዳንዱን ጥያቄ ወጪ እንዴት እንደሚገምት፣ እንደሚመዘግብ እና ሪፖርት እንደሚያደርግ — እንዲሁም የዳሽቦርዱ ቁጥር ለምን **የቁጠባ መከታተያ** እንጂ የክፍያ መጠየቂያ እንዳልሆነ።
በተጨማሪ ይመልከቱ፦ [የተጠቃሚ መመሪያ](./USER_GUIDE.md) · [የባህሪያት ማሳያ](./FEATURES.md)
---
## ምን እንደሆነ (እና ምን እንዳልሆነ)
OmniRoute የቶክን ብዛቶችን በሞዴሉ የዋጋ ተመኖች በማባዛት ለእያንዳንዱ completion በአንድ ጥያቄ የሚወጣውን የUSD ወጪ ይመድባል። እነዚህ ቁጥሮች የ**ወጪዎች** ዳሽቦርድን፣ `omniroute cost` / `omniroute usage` CLIን፣ የCSV/JSON ውጪ ማስተላለፎችን እና የእያንዳንዱ API ቁልፍ በጀቶችን ያንቀሳቅሳሉ።
> **የዳሽቦርዱ "ወጪ" የቁጠባ መከታተያ እንጂ የክፍያ መጠየቂያ አይደለም።** OmniRoute በፍጹም ክፍያ አያስከፍልዎትም
> — ጥያቄዎችዎን ቀድሞውኑ ወዳገናኟቸው አቅራቢዎች (የራስዎ የደንበኝነት ምዝገባዎች፣
> ነጻ ደረጃዎች እና API ቁልፎች) ይመራል። ሙሉ በሙሉ በነጻ ሞዴሎች ላይ የተከማቸ "$290 ጠቅላላ ወጪ" ማለት በግምት
> **ለሚከፈልበት API ያልከፈሉት $290** ማለት ነው። ይህ አኃዝ ተመሳሳይ ትራፊክ በመደበኛ የዝርዝር ዋጋዎች ምን ያህል ሊያስወጣ እንደሚችል የሚያሳይ _ግምት_ ነው፤ ስለዚህ አጠቃቀምዎ የት እንደተከማቸ እና ወደ ርካሽ/ነጻ አቅራቢዎች መምራት ምን ያህል እንደሚያቆጥብልዎት ማየት ይችላሉ።
ይህ አተያይ በፕሮጀክቱ [README](../../README.md) ውስጥ በቀጥታ ተገልጿል ("የዳሽቦርዱ
'ወጪ' የቁጠባ መከታተያ እንጂ የክፍያ መጠየቂያ አይደለም")።
ቁጥሩ ግምት ስለሆነ፦
- ይህ OmniRoute ለእያንዳንዱ ሞዴል ባለው የዋጋ ሰንጠረዥ ላይ ይመሰረታል። የዋጋ
ግቤት የሌለው ሞዴል `0` ወጪ ያበረክታል (በመዳሰሻው ውስጥ እንደ "የቆየ / ነጻ" ረድፍ ይታያል)።
- የነጻ ደረጃ እና የደንበኝነት ምዝገባ ትራፊክም ቢሆን _የተገመተ_ ወጪ ያከማቻል — ይህ የሚቆጥቡት መጠን እንጂ የሚፈለግብዎት ክፍያ አይደለም።
---
## ወጪዎች እንዴት እንደሚገመቱ
### የዋጋ ምንጭ
ወጪዎች የሚመጡት በዚህ የቅድሚያ ቅደም ተከተል ከሚወሰን የዋጋ ሰንጠረዥ ነው
([`src/lib/pricingSync.ts`](../../src/lib/pricingSync.ts))፦
1. **የተጠቃሚ ሽረዎች** — በዳሽቦርዱ ውስጥ / በ`PATCH /api/pricing` በኩል ያዘጋጇቸው ዋጋዎች።
2. **የተመሳሰለ ውጫዊ ዋጋ** — ማመሳሰል ሲነቃ ከLiteLLM ይፋዊ
`model_prices_and_context_window.json` የሚወሰድ (የእርስዎን ሽረዎች በፍጹም እንዳይተካ በተለየ
`pricing_synced` namespace ውስጥ ይከማቻል)።
3. **በኮድ ውስጥ የተወሰኑ ነባሪዎች** — ከOmniRoute ጋር የሚቀርቡ።
የውጫዊ ዋጋ ማመሳሰል **በምርጫ የሚነቃ** ሲሆን፣ በነባሪነት ተሰናክሏል። ተዛማጅ env vars
([`.env.example`](../../.env.example) ይመልከቱ)፦
| Env var | ነባሪ | ዓላማ |
| ----------------------- | --------- | ---------------------------------------------------- |
| `PRICING_SYNC_ENABLED` | `false` | ሲጀመር የጀርባ LiteLLM የዋጋ ማመሳሰልን ያንቁ። |
| `PRICING_SYNC_INTERVAL` | `86400` | የማመሳሰል ልዩነት በ**ሰከንዶች** (በነባሪ በየቀኑ)። |
| `PRICING_SYNC_SOURCES` | `litellm` | በነጠላ ሰረዝ የተለየ የምንጭ ዝርዝር (ዛሬ የሚደገፈው `litellm` ብቻ ነው)። |
### የወጪ ቀመር
ወጪው በእያንዳንዱ ጥያቄ የቶክን ብዛቶችን እና በሚሊዮን ቶክን የሚተመኑ ዋጋዎችን በመጠቀም
በ[`src/lib/usage/costCalculator.ts`](../../src/lib/usage/costCalculator.ts)
(`computeCostFromPricing` / `calculateCost`) ውስጥ ይሰላል፦
- **የግቤት ቶክኖች** (የcache ንባቦች እና cache-creation ቶክኖች ከተቀነሱ በኋላ) × `input` ተመን።
- **የCache-read ቶክኖች** × `cached` ተመን (ከሌለ የግቤት ተመኑን ይጠቀማል)።
- **የCache-creation ቶክኖች** × `cache_creation` ተመን (ከሌለ የግቤት ተመኑን ይጠቀማል)።
- **የውጤት ቶክኖች** × `output` ተመን።
- **የማመዛዘኛ ቶክኖች** × `reasoning` ተመን (ከሌለ የውጤት ተመኑን ይጠቀማል)።
ሁሉም ተመኖች በ1,000,000 ቶክኖች የUSD ዋጋ እንደሆኑ ይተረጎማሉ። የCodex "fast"/"priority" ወይም
"flex" የአገልግሎት ደረጃ የወጪ ማባዣ (`getCodexFastCostMultiplier`) ይተገብራል — ለምሳሌ flex
በ50% የቶክን ቅናሽ ይከፈልበታል፣ ይህም በዳሽቦርዱ ውስጥ እንደ **የflex ቁጠባ** ይታያል።
የሞዴል ስሞች መጀመሪያ መደበኛ መልክ ይሰጣቸዋል (እንደ `openai/` ወይም
`accounts/fireworks/models/` ያሉ የአቅራቢ መንገድ ቅድመ ቅጥያዎች ይወገዳሉ)፤ በዚህም የቆዩ ረድፎች ከዋጋ ጋር መዛመዳቸውን ይቀጥላሉ።
### ወጪ እንዴት እንደሚመዘገብ
- የእያንዳንዱ ጥያቄ ወጪ ምላሹ ከተሰጠ በኋላ ይሰላል፣ እና ለደንበኛው ምንም መዘግየት እንዳይጨምር ያለመጠበቅ ይመዘገባል። የጋራ ኮታ ፍጆታ በሚቀጥለው
event-loop tick ላይ በ[`src/lib/quota/spendRecorder.ts`](../../src/lib/quota/spendRecorder.ts) በኩል ቀጠሮ ይያዝለታል።
- የAPI ቁልፍ ወጪ በ
[`SpendBatchWriter`](../../src/lib/spend/batchWriter.ts) ይቋትና በቡድን ይጻፋል (ነባሪ የflush ልዩነት 60s፣
የ1,000 ግቤቶች buffer)። በሚከተሉት ማስተካከል ይቻላል፦
| Env var | ነባሪ | ዓላማ |
| ----------------------------------- | ------- | ------------------------------- |
| `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS` | `60000` | የFlush ልዩነት በሚሊሰከንዶች። |
| `OMNIROUTE_SPEND_MAX_BUFFER_SIZE` | `1000` | ከflush በፊት ከፍተኛው የተቋተ ግቤቶች ብዛት። |
የዳሽቦርዱ የወጪ አኃዞች በእያንዳንዱ ረድፍ ከተከማቸ የዶላር መጠን **አይነበቡም** — በምትኩ analytics endpoint በሚሠራበት በእያንዳንዱ ጊዜ ከቶክን ብዛቶች እና ከወቅታዊው የዋጋ ሰንጠረዥ በቀጥታ እንደገና ይሰላሉ። ይህም የተሳሳተ ዋጋን ማረም (እና እንደገና ማመሳሰል) የቆዩ የወጪ ግምቶችን ወደኋላ ተመልሶ እንዲያዘምን ያደርጋል።
---
## ዳሽቦርድ፦ የወጪዎች ገጽ
የ**ወጪዎች** ገጽ በ`/dashboard/costs`
(`src/app/(dashboard)/dashboard/costs/`) ይገኛል።
ዋናው እይታው **የወጪ አጠቃላይ እይታ** ትር
(`src/app/(dashboard)/dashboard/costs/CostOverviewTab.tsx`) ሲሆን፣
ሁሉንም ውሂብ ከ`GET /api/usage/analytics` ይጭናል።
የሚያሳያቸው፦
- **የወጪ ሰድሮች** — ለ_ዛሬ (1d)_፣ _7d_፣ _30d_ እና ለተመረጠው
የጊዜ መስኮት የተገመተ ወጪ። የክልል መራጭ፦ `7d`፣ `30d`፣ `90d`፣ `all`።
- **ዋና መለኪያዎች** — በጊዜ መስኮቱ ውስጥ ያሉ ጥያቄዎች፣ ንቁ አቅራቢዎች፣ ንቁ ሞዴሎች እና አማካይ
የአንድ ጥያቄ ወጪ።
- **የወጪ ማሰሻ** — በ**አቅራቢ**፣ **ሞዴል**፣
**API ቁልፍ**፣ **መለያ** ወይም **የአገልግሎት ደረጃ** የተመደበ፣ ሊደረደርና ሊጣራ የሚችል ሰንጠረዥ፤ ወጪ፣ ጥያቄዎች፣ ቶከኖች፣ አማካይ
የአንድ ጥያቄ ወጪ እና ከጠቅላላው ያለውን ድርሻ % ያካትታል።
- **የቶከን አጠቃቀም** — ጠቅላላ / ግቤት / ውጤት ቶከኖች እና የግቤት:ውጤት ምጥጥን።
- **የማስተላለፊያ ቅልጥፍና** — የመጠባበቂያ ሽግግር ብዛት፣ የመጠባበቂያ ሽግግር መጠን እና የተጠየቀው ሞዴል ሽፋን።
- **ወርሃዊ ትንበያ** — ከቅርብ ጊዜው ዕለታዊ አማካይ በመነሳት የወሩ መጨረሻ ወጪን ይተነብያል።
- **የወቅቶች ንጽጽር** — በጊዜ መስኮቱ የመጀመሪያ እና ሁለተኛ አጋማሽ መካከል ያለው የ% ለውጥ።
- **ገበታዎች** — ዕለታዊ የወጪ አዝማሚያ፣ የአቅራቢ ድርሻ (ክብ ገበታ)፣ ከፍተኛ አቅራቢዎች፣ ከፍተኛ ሞዴሎች፣ ወጪ
በAPI ቁልፍ፣ ወጪ በመለያ፣ ሳምንታዊ የአጠቃቀም ንድፍ እና የእንቅስቃሴ ሙቀት ካርታ።
- **ወደ ውጭ መላክ** — የአሁኑን የጊዜ መስኮት እንደ **CSV** ወይም **JSON** ያውርዱ (አዝራሮቹ
የወጪ ውሂቡ ከዜሮ በላይ ሲሆን ይታያሉ)።
ዋጋ የተመደበለት ትራፊክ በማይኖርበት ጊዜ፣ ረድፎቹ `$0` ከማሳየት ይልቅ "የቆየ / ነፃ" መለያን ያሳያሉ፤
ይህም የቁጠባ መከታተያውን ሞዴል ያንጸባርቃል።
### ተዛማጅ የወጪዎች ንዑስ ገጾች
የወጪዎች ክፍል የሚከተሉትንም ያካትታል (ሁሉም በ`/dashboard/costs/` ስር ናቸው)፦
- **ዋጋ አወጣጥ** (`/dashboard/costs/pricing`) — የእያንዳንዱን ሞዴል ዋጋ ይመልከቱ እና ይሻሩ (የጋራውን
የዋጋ አወጣጥ ትር ያሳያል)።
- **በጀት** (`/dashboard/costs/budget`) — ለእያንዳንዱ ወሰን የወጪ ገደቦችን ያዘጋጁ (የጋራውን
የበጀት ትር ያሳያል)።
- **የኮታ ድርሻ** (`/dashboard/costs/quota-share`) — የጋራ ኮታ ስብስቦች እና የፍጆታ ፍጥነት
እይታዎች።
---
## API መዳረሻዎች
ካልተገለጸ በስተቀር፣ እነዚህ ሁሉ የአስተዳደር ማረጋገጫን (loopback/JWT፣ በ`requireManagementAuth` በኩል)
ይፈልጋሉ።
### የአጠቃቀም እና የወጪ ትንታኔ
| ዘዴ | መዳረሻ | ዓላማ |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/api/usage/analytics` | ሙሉ የወጪ/አጠቃቀም ትንታኔ፦ ማጠቃለያ፣ ዕለታዊ አዝማሚያ፣ በአቅራቢ/ሞዴል/API ቁልፍ/መለያ/ደረጃ። መጠይቅ፦ `range`፣ `startDate`፣ `endDate`፣ `apiKeyIds`፣ `presets`። |
| `GET` | `/api/usage/utilization` | በጊዜ ሂደት የእያንዳንዱ አቅራቢ ኮታ አጠቃቀም። መጠይቅ፦ `range` (`1h`/`24h`/`7d`/`30d`)፣ `provider`። |
| `GET` | `/api/usage/history` | ያልተቀነባበሩ የአጠቃቀም ታሪክ ረድፎች። |
| `GET` | `/api/usage/call-logs` | የእያንዳንዱ ጥያቄ ጥሪ መዝገቦች (ሞዴል፣ ቶከኖች፣ ወጪ፣ መዘግየት፣ ሁኔታ)። |
| `GET` | `/api/usage/quota` | የአቅራቢ ኮታ ሁኔታ። |
| `GET` | `/api/usage/proxy-logs` | የፕሮክሲ ጥያቄ መዝገቦች። |
### በጀቶች
| ዘዴ | መዳረሻ | ዓላማ |
| ------ | ------------------------ | ------------------------------------------------------------------- |
| `GET` | `/api/usage/budget` | ለአንድ API ቁልፍ የወጪ ማጠቃለያ + የበጀት ማረጋገጫ (`apiKeyId` የመጠይቅ መለኪያ ያስፈልጋል)። |
| `POST` | `/api/usage/budget` | ለአንድ API ቁልፍ ዕለታዊ/ሳምንታዊ/ወርሃዊ የUSD ገደቦችን + የማስጠንቀቂያ ጣራን ያዘጋጁ። |
| `GET` | `/api/usage/budget/bulk` | በAPI ቁልፎች ላይ የጅምላ በጀት ማጠቃለያዎች። |
> የበጀት APIው ለእያንዳንዱ **API ቁልፍ** (`apiKeyId`) የተወሰነ ነው።
> በ`GET /api/usage/budget` የሚመለሱ ገደቦች `dailyLimitUsd`፣ `weeklyLimitUsd`፣ `monthlyLimitUsd`፣
> `warningThreshold` እና እየተከማቹ ያሉ ድምሮችን (`totalCostToday`፣ `totalCostMonth`፣ …) ያካትታሉ።
### ዋጋ አወጣጥ
| ዘዴ | መዳረሻ | ዓላማ |
| -------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| `GET` | `/api/pricing` | የአሁኑ የተዋሃደ ዋጋ አወጣጥ (ተጠቃሚ + የተመሳሰለ + ነባሪዎች)። የእያንዳንዱን ግቤት ምንጭ ለማየት `?includeSources=1` ይጠቀሙ። |
| `PATCH` | `/api/pricing` | ለ`{ provider: { model: { input, output, cached, … } } }` ዋጋ አወጣጥን ይሻሩ። |
| `DELETE` | `/api/pricing` | ዋጋ አወጣጥን ወደ ነባሪዎች ይመልሱ (እንደ አማራጭ በ`?provider=&model=` ሊወሰን ይችላል)። |
| `GET` | `/api/pricing/defaults` | ነባሪ የእያንዳንዱ 1M መጠባበቂያ ተመኖችን ያሳዩ። |
| `GET` | `/api/pricing/models` | በሞዴል የተመደበ ዋጋ አወጣጥ። |
| `POST` | `/api/pricing/sync` | ከውጫዊ ምንጮች (LiteLLM) በእጅ የሚደረግ ማመሳሰልን ያስጀምሩ። |
| `GET` | `/api/pricing/sync` | የአሁኑ የማመሳሰል ሁኔታ። |
| `DELETE` | `/api/pricing/sync` | ሁሉንም የተመሳሰለ የዋጋ አወጣጥ ውሂብ ያጽዱ። |
### ሌሎች ከወጪ ጋር የተያያዙ መዳረሻዎች
| ዘዴ | መዳረሻ | ዓላማ |
| ----- | ----------------------------- | --------------------------------------------------- |
| `GET` | `/api/free-tier/summary` | የነፃ ሞዴል ቶከን ድምሮች፣ በዚህ ወር ጥቅም ላይ የዋለው እና ቀሪው ነፃ ፈቃድ። |
| `GET` | `/api/quota/pools/[id]/usage` | ለጋራ ኮታ ስብስብ የአጠቃቀም መጠን። |
---
## CLI
የOmniRoute CLI የወጪ፣ የአጠቃቀም እና የዋጋ ትዕዛዞችን ያቀርባል (በ
[`bin/cli/commands/registry.mjs`](../../bin/cli/commands/registry.mjs) ውስጥ የተመዘገቡ)።
### `omniroute cost`
ከ`/api/usage/analytics` የተጠቃለለ የወጪ ሪፖርት።
```bash
omniroute cost # ያለፉት 30d፣ በአቅራቢ የተመደበ
omniroute cost --period 7d # ያለፉት 7 ቀናት
omniroute cost --group-by model # በ provider | model | combo | api-key | day መድብ
omniroute cost --since 2026-06-01 --until 2026-06-13
omniroute cost --api-key <key> --limit 50
```
ዓምዶች፦ ቡድን፣ ጥያቄዎች፣ የገቡ/የወጡ ቶከኖች፣ ወጪ (USD) እና ከጠቅላላው ያለው %። በመጨረሻ
አጠቃላይ ድምር መስመር ይታተማል (በ`--quiet` ወይም `--output json` ይታገዳል)።
### `omniroute usage`
```bash
omniroute usage analytics --period 30d [--provider <id>] # የእያንዳንዱ አቅራቢ የወጪ ማጠቃለያ
omniroute usage logs [--limit 100] [--follow] [--api-key <k>] [--search <q>]
omniroute usage quota [--provider <id>] [--check]
omniroute usage utilization [--api-key <k>]
omniroute usage history [--limit 100]
omniroute usage proxy-logs [--limit 100]
# በጀቶች
omniroute usage budget list
omniroute usage budget get [scope]
omniroute usage budget set <amount> [--scope global] [--period monthly]
omniroute usage budget reset [scope]
```
### `omniroute pricing`
```bash
omniroute pricing list [--provider <p>] [--model <m>] [--limit 200]
omniroute pricing get <model>
omniroute pricing sync [--provider <p>] [--force] # POST /api/pricing/sync
omniroute pricing diff [--model <m>]
omniroute pricing defaults show
omniroute pricing defaults set [--input <p>] [--output <p>] [--cache-read <p>] [--cache-write <p>]
```
> `pricing defaults show` `GET /api/pricing/defaults`ን ያነባል። በምትኩ የእያንዳንዱን ሞዴል
> ዋጋ ለማርትዕ፣ የ**ዋጋ አወጣጥ** ዳሽቦርድ ገጽን ወይም `PATCH /api/pricing`ን ይጠቀሙ።
---
## መላ መፈለግ
- **ሁሉም ወጪዎች $0 / "Legacy / Free" ያሳያሉ።** ጥቅም ላይ ያሉት ሞዴሎች የዋጋ ግቤት የላቸውም።
ውጫዊ ማመሳሰልን (`PRICING_SYNC_ENABLED=true`) ያንቁና `omniroute pricing sync`ን ያሂዱ፣ ወይም
በዋጋ አወጣጥ ገጽ / `PATCH /api/pricing` በኩል ዋጋዎችን በእጅ ያዘጋጁ።
- **የታሪካዊ ሞዴል ዋጋ በትክክል አልተተመነም።** ዋጋውን ያስተካክሉ (ይሽሩት ወይም እንደገና ያመሳስሉት) — በእያንዳንዱ የትንታኔ ንባብ ላይ ወጪው
ከቶከን ብዛት እንደገና ይሰላል፣ ስለዚህ ግምቶቹ ያለፈውን ጊዜ ጨምሮ ይዘምናሉ።
- **ወጪው ከቅጽበታዊ ጊዜ ወደኋላ ይቀራል።** የእያንዳንዱ ቁልፍ ወጪ በምድብ ይሰራል፤ ይበልጥ ወቅታዊ ቁጥሮች ካስፈለጉዎት
`OMNIROUTE_SPEND_FLUSH_INTERVAL_MS`ን ዝቅ ያድርጉ።
---
ይህ በሰፊው ዳሽቦርድ ውስጥ የት እንደሚገባ ለማወቅ፣ [የተጠቃሚ መመሪያ](./USER_GUIDE.md)ን እና
[የባህሪያት ማዕከለ-ስዕላት](./FEATURES.md)ን ይመልከቱ።

653
docs/i18n/am/docs/guides/DOCKER_GUIDE.md Normal file
View File

@@ -0,0 +1,653 @@
# 🐳 Docker Guide — OmniRoute (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/DOCKER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/DOCKER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/DOCKER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/DOCKER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/DOCKER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/DOCKER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/DOCKER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/DOCKER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/DOCKER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/DOCKER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/DOCKER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/DOCKER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/DOCKER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/DOCKER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/DOCKER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/DOCKER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/DOCKER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/DOCKER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/DOCKER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/DOCKER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/DOCKER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/DOCKER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/DOCKER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/DOCKER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/DOCKER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/DOCKER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/DOCKER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/DOCKER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/DOCKER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/DOCKER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/DOCKER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/DOCKER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/DOCKER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/DOCKER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/DOCKER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/DOCKER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/DOCKER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/DOCKER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/DOCKER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/DOCKER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/DOCKER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/DOCKER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/DOCKER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/DOCKER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/DOCKER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/DOCKER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/DOCKER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/DOCKER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/DOCKER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/DOCKER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/DOCKER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/DOCKER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/DOCKER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/DOCKER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/DOCKER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/DOCKER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/DOCKER_GUIDE.md)
---
> የተሟላ የDocker ማሰማሪያ ማጣቀሻ። በፍጥነት ለመጀመር [የREADME Docker ክፍልን](../README.md#-docker) ይመልከቱ።
## ማውጫ
- [ፈጣን ማስኬድ](#quick-run)
- [ከአካባቢ ፋይል ጋር](#with-environment-file)
- [Docker Compose](#docker-compose)
- [የሚገኙ መገለጫዎች](#available-profiles)
- [OmniRoute በDocker ውስጥ ሲሄድ የአስተናጋጁን CLI መሣሪያዎች ማዋቀር](#configuring-host-cli-tools-when-omniroute-runs-in-docker)
- [Redis Sidecar](#redis-sidecar)
- [የምርት Compose](#production-compose)
- [የDockerfile ደረጃዎች](#dockerfile-stages)
- [ወሳኝ የአካባቢ ተለዋዋጮች](#critical-environment-variables)
- [Docker Compose ከCaddy (HTTPS) ጋር](#docker-compose-with-caddy-https-auto-tls)
- [Cloudflare ፈጣን Tunnel](#cloudflare-quick-tunnel)
- [የImage መለያዎች](#image-tags)
- [ተገኝነት፦ ነባሪው SQLite ነጠላ-ቅጂ ነው](#availability-default-sqlite-is-single-replica)
- [አስፈላጊ ማስታወሻዎች](#important-notes)
---
## ፈጣን ማስኬድ
```bash
docker run -d \
--name omniroute \
--restart unless-stopped \
--stop-timeout 40 \
-p 20128:20128 \
-v omniroute-data:/app/data \
diegosouzapw/omniroute:latest
```
## ከአካባቢ ፋይል ጋር
```bash
# መጀመሪያ .envን ይቅዱ እና ያርትዑ
cp .env.example .env
docker run -d \
--name omniroute \
--restart unless-stopped \
--stop-timeout 40 \
--env-file .env \
-p 20128:20128 \
-v omniroute-data:/app/data \
diegosouzapw/omniroute:latest
```
## Docker Compose
```bash
# መሠረታዊ መገለጫ (የCLI መሣሪያዎች የሉም)
docker compose --profile base up -d
# የCLI መገለጫ (Claude Code፣ Codex፣ OpenClaw አብሮገነብ)
docker compose --profile cli up -d
# የአስተናጋጅ መገለጫ (በዋናነት ለLinux፤ የአስተናጋጁን CLI binaries ለንባብ ብቻ ይጫናል)
docker compose --profile host up -d
# CLI + CLIProxyAPI sidecarን ያጣምሩ
docker compose --profile cli --profile cliproxyapi up -d
```
## የሚገኙ መገለጫዎች
OmniRoute ከአራት የCompose መገለጫዎች ጋር ይቀርባል። ከአካባቢዎ ጋር የሚዛመደውን ይምረጡ።
| መገለጫ | አገልግሎት | መቼ መጠቀም እንዳለብዎ | ትእዛዝ |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `base` (ነባሪ) | `omniroute-base` | ያለ ግራፊክ በይነገጽ የሚሠራ አገልጋይ / አነስተኛ የማስኬጃ አካባቢ፤ የአቅራቢ CLIዎች አልተካተቱም | `docker compose --profile base up -d` |
| `cli` | `omniroute-cli` | `omniroute providers/setup/doctor`ን እና የተካተቱ CLIዎችን (Codex፣ Claude Code፣ Droid፣ OpenClaw) የሚጠሩ በወኪል የሚከናወኑ የሥራ ፍሰቶች | `docker compose --profile cli up -d` |
| `host` | `omniroute-host` | `~/.local/bin`፣ `~/.codex`፣ `~/.claude` ወዘተን ለንባብ ብቻ በመጫን ከ`network_mode` ጋር ተመሳሳይ የአስተናጋጅ CLIዎች መዳረሻ የሚፈልጉ Linux አስተናጋጆች | `docker compose --profile host up -d` |
| `cliproxyapi` | `cliproxyapi` | ወደላይኛው የCLI ፕሮክሲ ግንኙነት ለማቅረብ [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) sidecarን በport `8317` ላይ ያስኪዱ | `docker compose --profile cliproxyapi up -d` |
> ብዙ መገለጫዎችን ማጣመር ይቻላል፦ `docker compose --profile cli --profile cliproxyapi up -d`።
## OmniRoute በDocker ውስጥ ሲሠራ የhost CLI መሣሪያዎችን ማዋቀር
`omniroute setup-codex`፣ `setup-claude`፣ `config set <tool>` እና የdashboard
**ውቅር አስቀምጥ** አዝራር ሁሉም እንደ `~/.codex/*.config.toml` ያሉ ፋይሎችን ይጽፋሉ። እነዚህ ዱካዎች
ትርጉም የሚኖራቸው CLIው በትክክል በሚሠራበት ማሽን ላይ ብቻ ነው። በcontainer
ውስጥ ካስኬዷቸው ጽሑፉ በcontainerው የራሱ home (`/home/node` —
imageው `USER node` በመጠቀም ይሠራል) ውስጥ ያርፋል፤ እዚያም ምንም የhost CLI ፈጽሞ አያነበውም፣ እንዲሁም
containerው እንደገና በተፈጠረበት ቅጽበት ይጣላል።
OmniRoute ይህን ሁኔታ ፈልጎ ያገኝና ሊጠቀሙበት የማይችሉትን ስኬት ከመዘገብ ይልቅ
መመሪያዎችን በማቅረብ ጽሑፉን ይከለክላል፦ CLIው `2` በሚለው ኮድ ይወጣል፣ APIው ደግሞ `422`
እና `containerEphemeralTarget: true` ይመልሳል።
### የሚመከር፦ CLIውን በhost ላይ፣ OmniRouteን በDocker ውስጥ ያስኪዱ
containerው APIውን ያቀርባል፤ CLIው ደግሞ የhost መሣሪያዎችዎን ያዋቅራል።
```bash
docker compose --profile base up -d
npm install -g omniroute
omniroute connect http://localhost:20128 # CLIውን ወደ containerው ያመልክቱ
omniroute setup-codex # በhostዎ ላይ ያለውን ትክክለኛ ~/.codex ይጽፋል
```
Codex፣ Claude Code፣ Cursor ወይም ተመሳሳይ መሣሪያዎች በlaptopዎ ላይ ሲሠሩ ይህ
ትክክለኛው ምርጫ ነው — ይህም የተለመደው አወቃቀር ነው።
### አማራጭ፦ የhost ውቅር ማውጫዎችን bind-mount ያድርጉ (`host` profile)
containerው ራሱ የhost ውቅርዎን እንዲጽፍ ከፈለጉ፣
ማውጫዎቹን mount አድርገው ያስገቡና `CLI_CONFIG_HOME`ን ወደ mount root ያመልክቱ። `host` profile
ይህንን አስቀድሞ ያደርጋል፦
```yaml
environment:
- CLI_CONFIG_HOME=/host-home
- CLI_ALLOW_CONFIG_WRITES=true
volumes:
- ~/.codex:/host-home/.codex:rw
- ~/.claude:/host-home/.claude:rw
```
ዱካውን አስተማማኝ የሚያደርገው bind mount ነው፦ OmniRoute
`/proc/self/mountinfo`ን ያነባል፣ እንዲሁም mounted ለሆኑ ዱካዎች (እና ልጅ ማውጫዎቻቸው mount ለሆኑ
ማውጫዎች፤ ይህም ከላይ ያለውን የ`/host-home` ቅርጽ በትክክል ይገልጻል) መጻፍን ይፈቅዳል፤
mounted ያልሆኑትን ግን አሁንም ይከለክላል።
### የአደጋ ጊዜ መውጫ፦ የcontainerውን የራሱ CLIs ያዋቅሩ (በጥንቃቄ ይጠቀሙ)
CLIs በእርግጥ በcontainerው ውስጥ በሚኖሩበት ጊዜ (`cli` profile)፣ መጻፉ
የታሰበ ነው። `--allow-container-write`ን ለማንኛውም `setup-*` ትእዛዝ ያስተላልፉ፣ ወይም ለserverው
`OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` ያዘጋጁ። ጽሑፉ containerው ከጠፋ በኋላ
እንደማይቆይ ከሚገልጽ ማስጠንቀቂያ ጋር ይቀጥላል።
> **የደህንነት ማስጠንቀቂያ — `cli` profile + `docker.sock` mount።**
> የ`cli` profileው `/var/run/docker.sock`ን bind-mount ያደርጋል፤ ይህም በcontainer ውስጥ ያለው
> auto-updater ከhost daemon stackውን እንደገና እንዲፈጥር ያስችለዋል
> (`src/lib/system/autoUpdate.ts` ያንን socket መኖሩን ይመረምራል፣ ከሌለ ደግሞ
> የDocker ዱካውን ይዘላል)። ያ socket **የhost-root እምነት
> ወሰን** ነው፦ ሊደርስበት የሚችል ማንኛውም ነገር የhost Docker daemonን እንደ
> root ያንቀሳቅሳል — በhostው ላይ ያለን ማንኛውንም container መፍጠር፣ መመርመር፣ ማቆም እና ማስወገድ ይችላል።
> አንድምታዎቹ፦
>
> 1. **የ`cli` profileውን port ፈጽሞ ለnetwork አያጋልጡ።** በ
> `127.0.0.1` (`ports: "127.0.0.1:${DASHBOARD_PORT:-20128}:..."`) ላይ ያትሙት
> — LAN ላይ ሊደረስበት የሚችል `cli` profile ማንኛውንም የdashboard-ደረጃ RCE ወደ
> ሙሉ የhost መጣስ ይለውጣል።
> 2. **ተጨማሪ የhost ማውጫዎችን ወደ `cli` profile አታስገቡ።**
> የDocker socket ከማንኛውም ተጨማሪ mount ጋር ሲሆን containerው የfilesystemዎን እና የhost ውቅርዎን
> ሙሉ በሙሉ እንዲያነብና እንዲጽፍ ያስችለዋል። አንድ መሣሪያ projectን ማየት ካስፈለገው፣
> በCLI binaryው በአካባቢው ያስኪዱት — ወደ `cli` container አታስገቡት።
>
> በcontainer ውስጥ auto-update ካላስፈለገዎት፣ `cli` profileውን አያብሩ
> (`COMPOSE_PROFILES=core,redis` ወይም አጭር አማራጭ)። ሌሎቹ profiles
> የDocker socketን mount አያደርጉም።
>
> ከMITM ጋር የተያያዘውን የአደጋ ሞዴል ለማየት `docs/security/MITM-TPROXY-DECRYPT.md`ን (git፤ ወደ `/docs` አልተጠናቀረም) ይመልከቱ፤
> ስለ `codex`/`claude-code`/`droid`/`openclaw` binary ምንጭ ሰንሰለት ደግሞ
> `docs/security/SUPPLY_CHAIN.md`ን ይመልከቱ።
## Redis Sidecar
OmniRoute ለተሰራጨው የጥያቄ መጠን ገዳቢ እና ለጋራ መሸጎጫ Redisን ይጠቀማል። የ`redis` አገልግሎት በ`docker-compose.yml` ውስጥ **ሁልጊዜ ይገለጻል** (የፕሮፋይል ገደብ የለውም) እና ከማንኛውም ሌላ ፕሮፋይል ጋር አብሮ ይጀምራል።
| ዝርዝር | እሴት |
| --------------------- | ------------------------------------ |
| ምስል | `redis:7-alpine` |
| የኮንቴይነር ስም | `omniroute-redis` |
| ውስጣዊ ፖርት | `6379` |
| የሆስት ፖርት (ሊቀየር የሚችል) | `REDIS_PORT` (ነባሪው `6379`) |
| የሆስት ማሰሪያ (ሊቀየር የሚችል) | `REDIS_BIND_HOST` (ነባሪው `127.0.0.1`) |
| ቮልዩም | `omniroute-redis-data` → `/data` |
| የጤና ምርመራ | `redis-cli ping` (በየ10 ሰከንዱ) |
ተዛማጅ የአካባቢ ተለዋዋጮች፦
- `REDIS_URL` — ወደ መተግበሪያው የሚገባ የግንኙነት ሕብረቁምፊ (በነባሪ `redis://redis:6379`)።
- `REDIS_PORT` — ለRedis ኮንቴይነሩ የሆስት-ወገን ፖርት ማዛመድ።
- `REDIS_BIND_HOST` — ፖርቱ የሚታተምበት የሆስት በይነገጽ። ነባሪው `127.0.0.1` ነው።
> **ለምን loopback በነባሪ እንደሚጠቀም፦** sidecarው ያለ `requirepass` ይሰራል፣ እና የመተግበሪያው
> ኮንቴይነሮች በcompose አውታረ መረብ (`redis:6379`) በኩል ይደርሱበታል — የታተመው ፖርት
> ለሆስት-ወገን መሣሪያዎች (`redis-cli`፣ አካባቢያዊ `npm run dev`) ብቻ ነው። በ
> `0.0.0.0` ላይ ማተም ያልተረጋገጠ Redisን በLANዎ ላይ ላለ እያንዳንዱ ሆስት ያጋልጣል።
> `REDIS_BIND_HOST=0.0.0.0` ካዘጋጁ፣ `--requirepass`ንም ወደ አገልግሎቱ `command:` ያክሉ።
**Redisን ማሰናከል** አይመከርም (የጥያቄ መጠን ገዳቢው ወደ በማህደረ ትውስታ ውስጥ የሚሰራ አማራጭ ዝቅ ይላል)። ግድ ከሆነ፣ በ`docker-compose.yml` ውስጥ ያለውን የ`redis:` አገልግሎት ብሎክ ያስወግዱ/በአስተያየት ያሰናክሉ ወይም ወደ ዜሮ ይመጥኑት፦
```bash
docker compose up -d --scale redis=0
```
## የምርት Compose
ከdev ጎን ለጎን ለሚሰራ የተነጠለ የምርት ቅጽበታዊ ግልባጭ፣ `docker-compose.prod.yml`ን ይጠቀሙ።
| ዝርዝር | እሴት |
| -------------- | ----------------------------------------------------------------------------- |
| ፋይል | `docker-compose.prod.yml` |
| ነባሪ የዳሽቦርድ ፖርት | `PROD_DASHBOARD_PORT=20130` (ወደ ውስጣዊ `${DASHBOARD_PORT:-20128}` የተዛመደ) |
| ነባሪ API ፖርት | `PROD_API_PORT=20131` |
| ምስል | `omniroute:prod` (ከ`runner-cli` ዒላማ የተገነባ) |
| Redis ኮንቴይነር | `omniroute-redis-prod` (`redis:8.6.2`፣ የተለየ `redis-prod-data` ቮልዩም) |
| የውሂብ ቮልዩም | `omniroute-prod-data` (ስም ያለው፣ በድጋሚ ግንባታዎች መካከል የሚቆይ) |
| የጤና ምርመራዎች | `node healthcheck.mjs` + `redis-cli ping`፣ `depends_on` በRedis ጤንነት ላይ የተመሠረተ |
አጠቃቀም፦
```bash
# የምርት ስታኩን ይገንቡ እና ያስጀምሩ
docker compose -f docker-compose.prod.yml up -d --build
# ሎጎችን በቀጥታ ይመልከቱ
docker compose -f docker-compose.prod.yml logs -f
# ያቁሙ እና ያስወግዱ (ቮልዩሞችን ያቆዩ)
docker compose -f docker-compose.prod.yml down
```
የምርት ስታኩ ከdev compose ጋር በትይዩ ይሰራል (የተለያዩ የኮንቴይነር ስሞች፣ ፖርቶች እና ቮልዩሞች አሉት)፣ ስለዚህ ምርት እንደተነሳ ሳለ በአካባቢዎ ላይ ማሻሻልዎን መቀጠል ይችላሉ።
## የDockerfile ደረጃዎች
ማከማቻው ባለብዙ ደረጃ Dockerfile (`Dockerfile`) ይዟል። ሦስት ደረጃዎች ቀርበዋል፤ ለአጠቃቀምዎ ተስማሚውን `target` ይምረጡ።
| ደረጃ | መሠረታዊ ምስል | ዓላማ |
| ------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `builder` | `node:26-trixie-slim` | ጥገኞችን ይጭናል (`npm ci --legacy-peer-deps`) እና `npm run build`ን ያስኬዳል (በነባሪ Turbopack — ከታች ያሉትን የግንባታ ጊዜ ሀብቶች ይመልከቱ) |
| `runner-base` | `node:26-trixie-slim` | የNext.js ራሱን የቻለ ውጤት ያለው የምርት አሂድ ጊዜ። **ምንም የአቅራቢ CLIዎች አልተካተቱም።** |
| `runner-cli` | `runner-base` | `git`፣ `docker.io`፣ `docker-compose` እና ዓለም አቀፍ CLIዎችን ይጨምራል፦ `@openai/codex`፣ `@anthropic-ai/claude-code`፣ `droid`፣ `openclaw`። **ለኤጀንታዊ የሥራ ፍሰቶች ይህን ይምረጡ።** |
የተወሰነ targetን በእጅ ይገንቡ፦
```bash
docker build --target runner-base -t omniroute:base .
docker build --target runner-cli -t omniroute:cli .
```
### የግንባታ ጊዜ ሀብቶች
ሦስት የግንባታ ነጋሪ እሴቶች የ`builder` ደረጃውን የሀብት ፍጆታ ይቆጣጠራሉ። እነዚህ ለግንባታ ጊዜ ብቻ ናቸው —
`OMNIROUTE_MEMORY_MB` (ከታች) የተለየ የአሂድ ጊዜ ቅንብር ነው።
| የግንባታ ነጋሪ እሴት | ነባሪ | ውጤት |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| `OMNIROUTE_USE_TURBOPACK` | `1` | `0` በምትኩ በwebpack ይገነባል። ዝቅተኛ ከፍተኛ የማህደረ ትውስታ ፍጆታ፣ ግን የዘገየ። |
| `OMNIROUTE_BUILD_MEMORY_MB` | `6144` | ለተጀመረው `next build` የV8 heap ከፍተኛ ገደብ (`--max-old-space-size`)። |
| `OMNIROUTE_BUILD_WORKERS` | `2` | `CIRCLE_NODE_TOTAL`ን ይመግባል፤ Next ለገጽ-ውሂብ መሰብሰብ `workers = N - 1`ን ያሰላል። |
`OMNIROUTE_BUILD_WORKERS` ትልቅ builder ላይ ከፍ ማድረግ ያለብዎት እና የተገደበ ግንባታ
ከ`✓ Compiled successfully` **በኋላ** ሲቋረጥ መጠርጠር ያለብዎት ቅንብር ነው። እያንዳንዱ
የገጽ-ውሂብ worker የራሱ ሂደት ነው፣ ወላጁ `next build` ራሱም እንዲሁ ነው፤
በቀጥታ በሚሠራ VPS ላይ የተደረገ ድጋሚ ሙከራ (ጉዳይ #7518) የእያንዳንዱን ሂደት ከፍተኛ RSS
ከ`NODE_OPTIONS` heap ጠቋሚ ነፃ በሆነ መልኩ ~4.5 GB እንደሆነ ለክቷል (Turbopack ከV8 heap
ውጭ ባለው ቤተኛ/Rust ማህደረ ትውስታ ውስጥ ያጠናቅራል)። የ`2` ነባሪ እሴት (→ 1 worker፣ በአጠቃላይ 2
ሂደቶች) የህትመት pipeline ለሚጠቀምባቸው 16 GB / 4 vCPU በGitHub የሚስተናገዱ runners
ተመጣጥኖ ተዘጋጅቷል። በ`8` (→ 7 workers) ያ runner ማህደረ ትውስታ አልቆበት
buildkit ደረጃውን በ`ResourceExhausted: ... cannot allocate memory` አሳስቶታል፤
`3` (→ 2 workers) የእያንዳንዱ ሂደት RSS በግምት ፈንታ በቀጥታ ከተለካ በኋላም
አሁንም አልተመጣጠነም። `tests/unit/docker-build-memory-budget.test.ts`
በተለካው አኃዝ መሠረት ስሌቱን ያደርጋል፣ ከሁለቱ ቅንብሮች አንዱ ከrunner አቅም
በላይ ካደገም ይወድቃል።
Turbopack ከV8 heap **ውጭ** በሚኖር ቤተኛ Rust ማህደረ ትውስታ ውስጥ ያጠናቅራል፤ ስለዚህ
`OMNIROUTE_BUILD_MEMORY_MB` ወሰን አያበጅለትም። የማህደረ ትውስታ ገደብ ባለው host ላይ
ግንባታው ምንም የስህተት ጽሑፍ ሳያሳይ በOOM killer SIGKILL ይደረጋል — በ`Creating an optimized production build`
መሀል ላይ በቀላሉ ይቆማል፤ ይህም የማህደረ ትውስታ ማለቅ ሳይሆን የተንጠለጠለ
ያስመስለዋል። የግንባታ host የተገደበ ከሆነ bundlerን ይቀይሩ፦
```bash
docker build --target runner-base \
--build-arg OMNIROUTE_USE_TURBOPACK=0 \
-t omniroute:base .
```
`webpackBuildWorker` ነቅቷል፤ ስለዚህ `next build` ወላጅ **እና** worker
ሂደት ያስኬዳል፣ እያንዳንዱም `OMNIROUTE_BUILD_MEMORY_MB`ን በተናጠል ያከብራል። የcontainer
ገደቡን ከዚያ እሴት አንድ እጥፍ ሳይሆን በግምት ከሁለት እጥፉ በላይ ያድርጉ።
በዚህ tree ላይ የተለካ (`--target runner-base`፣ `OMNIROUTE_BUILD_MEMORY_MB=6144`)፦
| Bundler | የcontainer ገደብ | ውጤት |
| --------- | -------------- | ------------------------------ |
| Turbopack | 8 GiB / 16 GiB | በሁለቱም ላይ ያለማሳወቂያ በOOM ተቋርጧል |
| webpack | 8 GiB | የግንባታ worker SIGKILL ተደርጓል |
| webpack | 12 GiB | ተሳክቷል፣ ከፍተኛ ፍጆታው 11.1 GiB ደርሷል |
### የአሂድ ጊዜ ነባሪዎች
በ`runner-base` የሚላኩ ነባሪዎች፦ `PORT=20128`፣ `HOSTNAME=0.0.0.0`፣ `OMNIROUTE_MEMORY_MB=1024`፣ `NODE_OPTIONS=--max-old-space-size=1024`፣ `DATA_DIR=/app/data`፣ `OMNIROUTE_MIGRATIONS_DIR=/app/migrations`።
በDocker ውስጥ ያለ የማህደረ ትውስታ ባህሪ፦
- ምስሉ `OMNIROUTE_MEMORY_MB=1024`ን ያዘጋጃል፣ ከእሱም `NODE_OPTIONS=--max-old-space-size=1024`ን ያመነጫል።
- ትክክለኛው የserver ሂደት `OMNIROUTE_MEMORY_MB`ን በሚያነብ እና `--max-old-space-size=<OMNIROUTE_MEMORY_MB>`ን በሚጨምር ራሱን በቻለው launcher ይጀመራል።
- Node በተደጋጋሚ ከቀረቡት የ`--max-old-space-size` እሴቶች የመጨረሻውን ይጠቀማል፤ ስለዚህ `OMNIROUTE_MEMORY_MB`ን ማዘጋጀት ውጤታማውን የDocker heap ገደብ ይቆጣጠራል።
- ምስሉ ሁልጊዜ ስለሚያዘጋጀው፣ የlauncher የራሱ በRAM የተመጣጠነ fallback በDocker ስር ፈጽሞ አይተገበርም። ለworkloadዎ በግልጽ ከፍ ያድርጉት (ከታች ያለውን ሰንጠረዥ ይመልከቱ)። `2048` እንኳን ለcoding-agent `/v1/responses` አሁንም ትንሽ ነው።
### ለcoding agents የአሂድ ጊዜ RAM
የ1 GiB Docker ነባሪ ለdashboard/ቀላል-chat ዝቅተኛ መጠን እንጂ የምርት መጠን አይደለም። ረጅም የ`POST /v1/responses` bodies (በመቶዎች የሚቆጠሩ መልዕክቶች፣ በአስርዎች የሚቆጠሩ መሣሪያዎች) በcompression ወቅት በርካታ በማህደረ ትውስታ ውስጥ የሚገኙ graphsን ይይዛሉ። ሁለት በከፊል ተደራራቢ ~3 MiB / ~750k-token requests በ**12 GiB** old-space ላይ V8ን (`FATAL ERROR: Reached heap limit`) አቋርጠዋል፣ እንዲሁም የ16 GiB cgroup OOM ላይ ደርሰዋል። [#7849](https://github.com/diegosouzapw/OmniRoute/issues/7849)ን ይመልከቱ።
**cgroup `--memory`ን ከheap በላይ ያዘጋጁ** — ቤተኛ buffers፣ SQLite እና የcompression መካከለኛ ውጤቶች ከV8 ውጭ ይኖራሉ።
| የሥራ ጫና | `OMNIROUTE_MEMORY_MB` | ኮንቴይነር / cgroup | ማስታወሻዎች |
| ------------------------------------- | --------------------- | ---------------------- | ---------------------------------------------------------------------------- |
| ዳሽቦርድ፣ አንድ ቀላል ውይይት | `1024` (የimage ነባሪ) | ≥2 GiB | |
| አንድ የኮዲንግ ወኪል (Claude/Codex/Grok) | `8192` | ≥10 GiB | የተለመደ ባለአንድ-ክፍለ-ጊዜ `/v1/responses` |
| ሁለት በአንድ ጊዜ የሚካሄዱ ረጅም `/v1/responses` | `10240`–`12288` | ≥12–16 GiB | የV8 ማቋረጥ የተለካው በ~12 GiB heap ላይ ነው |
| ሦስት+ በአንድ ጊዜ የሚካሄዱ ረጅም አውዶች | በአንድ process ላይ አያድርጉ | በተከታታይ ያስኬዱ / ተጨማሪ RAM | ነባሪው ከባድ የመቀበያ ገደብ 1 በሂደት ላይ ያለ ሥራ ነው፤ RAM ሳይጨምሩ ይህን ማሳደግ ማቋረጡን እንደገና ያስከትላል |
በባዶ ማሽን ላይ `omniroute serve`፣ `OMNIROUTE_MEMORY_MB` **ካልተዋቀረ** ከRAM ~35% ያስተካክላል (`[512, 4096]` ውስጥ ተገድቦ)። Docker ሁልጊዜ `1024` ስለሚያዘጋጅ፣ ያ ማስተካከያ በይፋዊው image ውስጥ ፈጽሞ አይከናወንም።
```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
## ወሳኝ የአካባቢ ተለዋዋጮች
በ[ENVIRONMENT.md](../reference/ENVIRONMENT.md) ውስጥ ከተመዘገቡት ነባሪዎች በተጨማሪ፣ በDocker ስር ሲሰራ የሚከተሉት ተለዋዋጮች ከፍተኛ ጠቀሜታ አላቸው፦
| ተለዋዋጭ | ዓላማ | ነባሪ |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| `OMNIROUTE_WS_BRIDGE_SECRET` | ለWebSocket bridge የሚያገለግል የጋራ ምስጢር። **በምርት አካባቢ ያስፈልጋል** — ወደ ጠንካራ የዘፈቀደ ሕብረቁምፊ ያቀናብሩት። | አልተቀናበረም (መቅረብ አለበት) |
| `REDIS_URL` | ለrate limiter / cache backend የግንኙነት ሕብረቁምፊ | `redis://redis:6379` |
| `REDIS_PORT` | አብሮ ለቀረበው Redis container የhost ወደብ | `6379` |
| `REDIS_BIND_HOST` | አብሮ የቀረበው Redis ወደብ የሚታተምበት የhost interface (AUTH ካላከሉ loopback) | `127.0.0.1` |
| `AUTO_UPDATE_HOST_REPO_DIR` | ለራስ-አዘምን የሥራ ፍሰቶች ወደ `cli` profile በ`/workspace/omniroute` ላይ የሚጫን የhost ዱካ | `.` (የአሁኑ ማውጫ) |
| `OMNIROUTE_MEMORY_MB` | ለDocker standalone server የruntime Node heap ከፍተኛ ገደብ፤ ከላይ ያለውን የimage ነባሪ ይተካል። Coding agents፦ `8192`+ ([runtime RAM](#runtime-ram-for-coding-agents)ን ይመልከቱ)። | `1024` |
| `DASHBOARD_PORT` / `API_PORT` | ለdashboard (20128) እና API (20129) የተጋለጡ ወደቦችን ይተካል | `20128` / `20129` |
| `APP_BIND_HOST` | docker-compose የdashboard/API/live-WS ወደቦችን የሚያትምበት የhost interface። `REQUIRE_API_KEY=false` ሲሆን (ነባሪው)፣ `0.0.0.0` ማንነት ያልተረጋገጠውን `/v1` proxy ለLAN ያጋልጣል — ወሰኑን ያስፉት `REQUIRE_API_KEY=true` ሲሆን ወይም ከፊት ለፊት reverse proxy ሲኖር ብቻ ነው። | `127.0.0.1` |
| `CLIPROXY_BIND_HOST` | docker-compose የ`cliproxyapi` sidecarን የሚያትምበት የhost interface — የውሂብ volumeው የprovider ማረጋገጫዎችን ይይዛል። | `127.0.0.1` |
| `OMNIROUTE_PLUGINS_DIR` | የruntime plugin scanner የሚያነብበትና የሚጭንበት ማውጫ። plugins በbind-mount ሲጫኑ ያቀናብሩት፦ ነባሪው `HOME`ን ይከተላል፣ image ግን ይህን ወደ ውጭ ላይልክ ይችላል። | `~/.omniroute/plugins` |
| `OMNIROUTE_BASE_PATH` | appው ከreverse proxy ጀርባ ሲታተም የURL ንዑስ ዱካ (ለምሳሌ፦ `/omniroute`) | _(ባዶ = root)_ |
| `NEXT_PUBLIC_BASE_URL` | ንዑስ ዱካውን ያካተተ ይፋዊ የbrowser origin (ለምሳሌ፦ `https://host/omniroute`) | አልተቀናበረም |
| `PROD_DASHBOARD_PORT` | ለ`docker-compose.prod.yml` የhost dashboard ወደብ | `20130` |
| `CLIPROXYAPI_PORT` | ለ`cliproxyapi` sidecar የhost ወደብ | `8317` |
## በንዑስ ዱካ ላይ Reverse Proxy (Traefik / nginx)
የNext.js `basePath` በstandalone bundle ውስጥ ይካተታል። OmniRoute በapp root ላይ ባለ sentinel file ውስጥ የተካተተውን
እሴት ይመዘግባል (በ`npm run build` ጊዜ ይጻፋል፤ በ
`scripts/docker/ensure-docker-base-path.mjs` ይነበባል) እና container ሲጀምር ከ
`OMNIROUTE_BASE_PATH` ጋር ያወዳድረዋል። እሴቶቹ ሲለያዩ እና image-ው ለ
domain root የተገነባ ከሆነ፣ entrypoint-ው standalone manifests-ን፣ በውስጡ የተካተቱትን
`basePath`/`assetPrefix` literals (Next 16 የSSR asset URL-ዎችን ከ
`assetPrefix` ብቻ ያቀርባል — patcher-ው ንዑስ ዱካውን ወደዚያ ይገለብጣል)፣ የተካተቱትን
`/_next/static` asset URL-ዎች (client-reference manifests፣ media imports፣ አስቀድመው የቀረቡ
የስህተት ገጾች) እና client `process.env` shim-ን `node dev/run-standalone.mjs`
ከመሠራቱ በፊት እንደገና ይጽፋል።
### በCompose መገንባት (የሚመከር)
image-ው እና runtime-ው እንዲጣጣሙ ሁለቱንም variables በ`.env` ውስጥ ያዘጋጁ፣ ከዚያም እንደገና ይገንቡ፦
```bash
# .env
OMNIROUTE_BASE_PATH=/omniroute
NEXT_PUBLIC_BASE_URL=https://myhostname.example.com/omniroute
```
```bash
docker compose --profile base up -d --build
```
`docker-compose.yml` `OMNIROUTE_BASE_PATH`-ን እንደ Docker build-arg እና እንደ
runtime environment variable ያስተላልፋል።
### አስቀድሞ የተገነባ root image + runtime ንዑስ ዱካ
የታተሙት `diegosouzapw/omniroute:*` images ለdomain root የተገነቡ ናቸው። ሆኖም
`OMNIROUTE_BASE_PATH`-ን በruntime ላይ ማዘጋጀት ይችላሉ፤ container-ው ሲጀምር bundle-ውን አንድ ጊዜ
ያስተካክላል። ከሚዛመደው public origin ጋር ያጣምሩት፦
```yaml
services:
omniroute:
image: diegosouzapw/omniroute:latest
environment:
OMNIROUTE_BASE_PATH: /omniroute
NEXT_PUBLIC_BASE_URL: https://myhostname.example.com/omniroute
```
Reverse proxy-ው **ሙሉውን** ውጫዊ ዱካ እንዲያስተላልፍ ያዋቅሩት (prefix-ን አያስወግዱ)።
Next.js `/omniroute/...`-ን ተቀብሎ assets-ን ከ
`/omniroute/_next/...` እንዲያቀርብ፣ Traefik `PathPrefix(`/omniroute`)`-ን ያለ
`StripPrefix` ወደ container-ው መምራት አለበት።
የDocker healthcheck በንቁው `OMNIROUTE_BASE_PATH` prefix የተደረገበትን ቀላል
`/healthz` lifecycle endpoint ይፈትሻል። `/api/monitoring/health` ለ
ሰው/dashboard diagnostics እንደቀረበ ይቆያል፤ የcontainer HEALTHCHECK-ን እንደገና ወደዚያ ለማመልከት (ለምሳሌ
ጥልቅ የጤና ማስፈጸሚያ)፣ `OMNIROUTE_HEALTHCHECK_PATH=/api/monitoring/health` ያዘጋጁ።
ያ ዱካ **ጥልቅ** ፍተሻ ነው (DB + monitoring summary) — እንደገና መጠቀምን ከመረጡ ለDocker
አልፎ አልፎ ለሚሠራው `HEALTHCHECK` ተስማሚ ነው፣ ነገር ግን ለKubernetes `livenessProbe`
ክፍተቶች **አይደለም**።
ለorchestrators (Kubernetes፣ Nomad፣ ወዘተ)፦
| Probe | የሚመረጥ | የሚወገድ |
| --------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
| Liveness | HTTP `GET /livez`፣ ወይም በዋናው port ላይ TCP (`PORT`፣ default `20128`) | `/api/monitoring/health` እንደ liveness |
| Readiness | HTTP `GET /healthz` | event-loop በሥራ መጠመድን እንደ መሞት የሚቆጥሩ አጭር timeouts |
| Deep / blackbox | `/api/monitoring/health` | — |
`/healthz` የprocess lifecycle (`ok` / `starting` / `stopping`) ሪፖርት ያደርጋል። `/livez`
process-ው በሕይወት መኖሩን ብቻ ይፈትሻል (handler-ው መሥራት በቻለ ቁጥር 200 ይመልሳል፤
readiness-ን አይጠብቅም)። ሁለቱም አሁንም request handling ከሚሠራበት ተመሳሳይ Node event loop ላይ
ይሠራሉ፤ ስለዚህ CPU-bound catalog ወይም compression ሥራ ሊያዘገያቸው ይችላል — በሥራ መጠመድ ≠ መሞት። HTTP
probes time out ካደረጉ TCP liveness-ን ይምረጡ። ሙሉ የprobe መመሪያ፦
[የMonitoring መመሪያ — የKubernetes probe ምክረ ሐሳቦች](../ops/MONITORING_GUIDE.md#kubernetes-probe-recommendations).
## Docker Compose ከ Caddy ጋር (HTTPS Auto-TLS)
OmniRoute የCaddy ራስ-ሰር SSL ማቅረብን በመጠቀም በደህንነት ለውጭ ሊቀርብ ይችላል። የጎራዎ DNS A መዝገብ ወደ አገልጋይዎ IP አድራሻ መጠቆሙን ያረጋግጡ።
```yaml
services:
omniroute:
image: diegosouzapw/omniroute:latest
container_name: omniroute
restart: unless-stopped
volumes:
- omniroute-data:/app/data
environment:
- PORT=20128
# ለOAuth መልሶ ጥሪዎች፣ ለዳሽቦርድ አገናኞች እና ለሚፈጠሩ የወል ዩአርኤሎች በአሳሹ በኩል የሚታይ መነሻ።
- NEXT_PUBLIC_BASE_URL=https://your-domain.com
# ለጊዜ ሰሌዳ የተያዙ ሥራዎች / ራስ-ሰር ጥያቄዎች የውስጥ ከአገልጋይ-ወደ-አገልጋይ ዩአርኤል።
- BASE_URL=http://omniroute:20128
- AUTH_COOKIE_SECURE=true
caddy:
image: caddy:latest
container_name: caddy
restart: unless-stopped
ports:
- "80:80"
- "443:443"
command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128
volumes:
omniroute-data:
```
Caddy ለወደላይኛው ኮንቴይነር መደበኛዎቹን የማስተላለፊያ ራስጌዎች ያዘጋጃል። OmniRoute
`NEXT_PUBLIC_BASE_URL`ን ለOAuth መልሶ ጥሪዎች እና ለሚፈጠሩ የወል
አገናኞች ቀኖናዊ የወል መነሻ አድርጎ ይጠቀማል፤ ማንነት የተረጋገጠባቸው የዳሽቦርድ የመጻፍ ጥያቄዎች ተመሳሳይ-መነሻ ጥያቄዎችን ከክፍለ-ጊዜ ጋር የተሳሰረ CSRF
ጥበቃ ጋር ይጠቀማሉ። OmniRoute የወል መነሻውን ከግልጽ
ውቅር ይልቅ ከታመኑ የተላለፉ ራስጌዎች እንዲወስን ሆን ብለው በሚፈልጉባቸው የላቁ ማሰማሪያዎች ላይ ብቻ `OMNIROUTE_TRUST_PROXY`ን ያንቁ።
## Cloudflare Quick Tunnel
ለDocker ማሰማሪያዎች የዳሽቦርድ ድጋፍ በ`Dashboard → Endpoints` ላይ በአንድ ጠቅታ የሚነቃ **Cloudflare Quick Tunnel**ን ያካትታል። መጀመሪያ ሲነቃ `cloudflared`ን አስፈላጊ ሲሆን ብቻ ያወርዳል፣ ወደ አሁኑ `/v1` የመጨረሻ ነጥብዎ ጊዜያዊ ቱነል ያስጀምራል፣ እና የተፈጠረውን `https://*.trycloudflare.com/v1` ዩአርኤል በመደበኛው የወል ዩአርኤልዎ ሥር በቀጥታ ያሳያል።
የመጨረሻ ነጥብ ቱነል ፓነሎችን (Cloudflare፣ Tailscale፣ ngrok) የነቃውን የቱነል ሁኔታ ሳይቀይሩ ከ`Settings → Appearance` ማሳየት ወይም መደበቅ ይቻላል።
### የቱነል ማስታወሻዎች
- የQuick Tunnel ዩአርኤሎች ጊዜያዊ ሲሆኑ ከእያንዳንዱ ዳግም ማስጀመር በኋላ ይቀየራሉ።
- ከOmniRoute ወይም ከኮንቴይነር ዳግም ማስጀመር በኋላ Quick Tunnels በራስ-ሰር አይመለሱም። በሚያስፈልግበት ጊዜ ከዳሽቦርዱ እንደገና ያንቋቸው።
- የሚተዳደረው ጭነት በአሁኑ ጊዜ Linux፣ macOS እና Windowsን በ`x64` / `arm64` ይደግፋል።
- በተገደቡ የኮንቴይነር አካባቢዎች ውስጥ ጫጫታ የሚያበዙ የQUIC UDP ቋት ማስጠንቀቂያዎችን ለማስወገድ፣ የሚተዳደሩ Quick Tunnels በነባሪ HTTP/2 ማጓጓዣን ይጠቀማሉ። የተለየ ማጓጓዣ ከፈለጉ `CLOUDFLARED_PROTOCOL=quic` ወይም `auto` ያዘጋጁ።
- የDocker ምስሎች የስርዓቱን CA ሥሮች ያካትታሉ እና ወደሚተዳደረው `cloudflared` ያስተላልፏቸዋል፤ ይህም ቱነሉ በኮንቴይነሩ ውስጥ ሲጀመር የTLS እምነት አለመሳካቶችን ያስወግዳል።
- OmniRoute አንድ ሁለትዮሽ ፋይል ከማውረድ ይልቅ ቀድሞ ያለውን እንዲጠቀም ከፈለጉ `CLOUDFLARED_BIN=/absolute/path/to/cloudflared`ን ያዘጋጁ።
## የምስል መለያዎች
| ምስል | መለያ | መጠን | መግለጫ |
| ------------------------ | -------- | ------ | ---------------------------------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250MB | ከፍተኛው **የታተመ** የተረጋጋ SemVer (git `main` አይደለም) |
| `diegosouzapw/omniroute` | `3.8.0` | ~250MB | ለGitOps ይህን የመለያ ምድብ በቋሚነት ይወስኑ |
ባለብዙ-መድረክ ማኒፌስት፦ `linux/amd64` + `linux/arm64` ቤተኛ (Apple Silicon፣ AWS Graviton፣ Raspberry Pi)። Docker ተዛማጁን የሕንፃ ዓይነት በራስ-ሰር ይመርጣል፤ በARM አስተናጋጆች ላይ AMD64 ማስመሰልን ማስገደድ ካስፈለገዎ `--platform linux/amd64`ን ያስተላልፉ።
### የልቀት ቻናሎች
OmniRoute ለተረጋጉ ልቀቶች፣ ለነቃ የልቀት-ቅርንጫፍ ሙከራ እና ለልማት ግንባታዎች የተለያዩ የDocker ቻናሎችን ያትማል።
| ቻናል | ምንጭ | ተለዋዋጭነት | የሚመከር አጠቃቀም |
| ------------------------------- | --------------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| `:<version>` / `:<version>-web` | የተፈረመ/ስሪት የተሰጠው ልቀት | የማይለወጥ | ትክክለኛ ልቀትን በቋሚነት የሚወስኑ የምርት ማሰማሪያዎች |
| `:latest` / `:latest-web` | ከፍተኛው **የታተመ** የተረጋጋ SemVer | ተለዋዋጭ የተረጋጋ ጠቋሚ | ከSemVer የሕትመት ሥራ **በኋላ** የተረጋጉ ልቀቶችን ይከተላል — `main`ን ወይም ያልተለቀቁ የ`release/v*` ለውጦችን **አይከታተልም** |
| `:next` / `:next-web` | የአሁኑ ነባሪ `release/v*` ቅርንጫፍ | ተለዋዋጭ ቅድመ-ልቀት ጠቋሚ | በነቃው የልቀት ቅርንጫፍ ላይ የደረሱ ነገር ግን ገና በተረጋጋ ልቀት ውስጥ ያልገቡ ማስተካከያዎችን መፈተሽ |
| `:main` / `:main-web` | `main` ቅርንጫፍ | ተለዋዋጭ የልማት ጠቋሚ | ለልማት እና ለውህደት ሙከራ ብቻ |
#### የቅድመ-ልቀት ቻናሉን መጠቀም
የ`next` ቻናል ወደ አሁኑ ነባሪ `release/v*` ቅርንጫፍ በሚደረግ እያንዳንዱ push ላይ እንደገና ይገነባል፣ እንዲሁም ለAMD64 እና ARM64 ይታተማል። የቆዩ የጥገና ቅርንጫፎች በላዩ ላይ መጻፍ አይችሉም። ቻናሉ ቀጣዩ የተረጋጋ መለያ ከመቆረጡ በፊት ወደ ነቃው የልቀት ቅርንጫፍ የተዋሃዱ ማስተካከያዎችን ለማግኘት መሳብ የሚቻል ምስል ያቀርባል።
```bash
docker pull diegosouzapw/omniroute:next
docker pull diegosouzapw/omniroute:next-web
```
ለDocker Compose፣ በተመረጠው መገለጫ ጥቅም ላይ የዋለውን የምስል መለያ ይተኩ፣ ከዚያም አገልግሎቱን ይሳቡ እና እንደገና ይፍጠሩ፦
```yaml
services:
omniroute:
image: diegosouzapw/omniroute:next
```
```bash
docker compose pull
docker compose up -d
```
#### ደህንነት እና ወደ ቀድሞ ሁኔታ መመለስ
`next` ተንሳፋፊ የቅድመ-ልቀት ቻናል ነው። ወደ ነቃው የልቀት ቅርንጫፍ በሚደረግ በማንኛውም push ላይ ሊቀየር ይችላል፣ እና **ለምርት አጠቃቀም አይደገፍም**። አንድን የተወሰነ ግንባታ በሚገመግሙበት ጊዜ የምስሉን ዳይጀስት በቋሚነት ይወስኑ፦
```bash
docker pull diegosouzapw/omniroute:next
docker image inspect diegosouzapw/omniroute:next --format '{{index .RepoDigests 0}}'
```
ከመሞከርዎ በፊት የOmniRoute ውሂብ ቮልዩምን ወይም bind-mounted የውሂብ ማውጫውን ምትኬ ያስቀምጡ። ወደ ቀድሞው ስሪት ለመመለስ፣ ከዚህ በፊት ጥቅም ላይ የዋለውን የተረጋጋ ስሪት ወይም digest መልሰው በማስቀመጥ container-ውን እንደገና ይፍጠሩ፦
```bash
docker pull diegosouzapw/omniroute:<stable-version>
docker compose up -d
```
የrelease branch build `latest`ን ፈጽሞ ማንቀሳቀስ አይችልም፤ የተረጋጋውን pointer ማሳደግ የሚችለው ብቁ የሆነ የተረጋጋ semantic version ብቻ ነው። የ`next` images የrelease image ምርመራውን እና CRITICAL የተጋላጭነት ማገጃውን እንደነበረ ይዘው ይቆያሉ።
**`latest` ለgit ወቅታዊነትን አያረጋግጥም።** በ`main` ወይም በንቁው `release/v*` branch ላይ የተዋሃዱ ማስተካከያዎች፣ የተረጋጋ SemVer image እስኪታተም እና publish job-ው `:latest`ን እስኪያሳድግ ድረስ በ`:latest` ውስጥ **አይካተቱም** (ከዚያ SemVer ጋር ተመሳሳይ digest)። GitHub ማስተካከያውን አስቀድሞ እያሳየ ሳለ `latest` የቆመ ከመሰለ፣ release branch-ውን ለመሞከር `:next`ን pull ያድርጉ ወይም የSemVer tag-ውን ይጠብቁ።
| የሚፈልጉት | ይጠቀሙ |
| ------------------------------------------------------------ | ---------------------------------------- |
| መለወጥ የሌለበት GitOps / production | `:X.Y.Z`ን (ወይም image digest-ውን) pin ያድርጉ |
| የታተሙ የተረጋጉ ስሪቶችን መከተል እና በእያንዳንዱ release ላይ እንደገና መፍጠርን መቀበል | `:latest` |
| ያልታተሙ `release/v*` commitsን መሞከር | `:next` (ለproduction አይደለም) |
| `main`ን መሞከር | `:main` (ለproduction አይደለም) |
## ተገኝነት፦ ነባሪ SQLite አንድ ቅጂ ብቻ ነው
መደበኛው Docker / Kubernetes OmniRoute **አንድ Node ሂደት + አንድ SQLite ጻፊ** ነው። በዚህ ቶፖሎጂ ከፍተኛ ተገኝነት **አይደገፍም**።
| ገደብ | ውጤት |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| አንድ ጻፊ | በተመሳሳዩ SQLite ፋይል ላይ በርካታ ቅጂዎችን **አያስኬዱ**። ይህ DBውን ያበላሻል። |
| ዳግም መፍጠር / ዳግም ማስጀመር / HEALTHCHECK ማቋረጥ | በሂደት ላይ ያሉ SSEዎች፣ የዳሽቦርድ ክፍለ-ጊዜዎች እና በማህደረ ትውስታ ውስጥ ያለ ሁኔታ **ሙሉ በሙሉ ይቋረጣሉ**። ሁሉም የተገናኙ ደንበኞች ግንኙነታቸውን ያጣሉ። endpoint ባዶ በሆነበት ጊዜ የሚመጡ አዳዲስ ጥያቄዎች OmniRoute JSON ሳይሆን ከreverse-proxy **`502 Bad Gateway: Unknown error`** ያገኛሉ — ደንበኞች ይህን ከአቅራቢ ብልሽት ለይተው ማወቅ አይችሉም (#11015)። |
| ከ`/healthz` ጋር ተመሳሳይ event loop | ሥራ የበዛበት የካታሎግ ወይም የመጭመቅ tick ፍተሻዎችን ሊያዘገይ ይችላል፤ አጭር timeout ደግሞ **ብቸኛውን** ቅጂ እንደገና ያስጀምራል። |
**የፍተሻ ማትሪክስ** ([የKubernetes ፍተሻ ምክረ ሐሳቦችን](../ops/MONITORING_GUIDE.md#kubernetes-probe-recommendations) ይመልከቱ)፦
| ፍተሻ | ዒላማ | አይጠቀሙ |
| ---------- | ------------------------------------------------------ | ---------------------------------------------- |
| ሕያውነት | በ`PORT` ላይ TCP (ነባሪ `20128`)፣ ወይም ለስላሳ HTTP `/healthz` | `/api/monitoring/health` |
| ዝግጁነት | HTTP `GET /healthz` | የevent loop ሥራ መብዛትን እንደ ሞት የሚቆጥሩ ጥብቅ timeouts |
| ጥልቅ / ለሰዎች | `/api/monitoring/health` | ራስ-ሰር የkubelet ሕያውነት ፍተሻ |
**ማሻሻያዎች፦** እያንዳንዱ ክፍለ-ጊዜ እንደሚቋረጥ ይጠብቁ። ከቻሉ ደንበኞችን ቀስ በቀስ ያስወጡ፤ በነባሪ SQLite ላይ rolling update የለም። Compose `restart: unless-stopped` ከDocker `HEALTHCHECK` ጋር ኮንቴይነሩ Unhealthy ሲሆን ብቸኛውን ሂደት ይተካል — የጉዳቱ ስፋትም ተመሳሳይ ነው።
ለ**አንድ ቅጂ** የKubernetes ቅንጭብ (Recreate ያስፈልጋል፤ በአንድ SQLite ፋይል ላይ `replicas`ን አይጨምሩ)፦
```yaml
spec:
replicas: 1
strategy:
type: Recreate
template:
spec:
terminationGracePeriodSeconds: 90
containers:
- name: omniroute
lifecycle:
preStop:
exec:
command: ["/bin/sleep", "15"]
readinessProbe:
httpGet:
path: /healthz
port: 20128
periodSeconds: 5
livenessProbe:
tcpSocket:
port: 20128
periodSeconds: 20
```
የ`preStop` sleep ከSIGTERM በፊት kube የService endpointsን እንዲያስወግድ ያስችለዋል፤ በዚህም **አዲስ** ትራፊክ እየተቋረጠ ያለውን ሂደት መድረስ ያቆማል። በሂደት ላይ ያለ `/v1/responses` SSE በከባድ admission leases አማካኝነት እስከ `SHUTDOWN_TIMEOUT_MS` (ነባሪ 30s) ድረስ ቀስ በቀስ ይጠናቀቃል (#11015)። አሁንም ሂደቱን የሚደርሱ አዳዲስ ጥያቄዎች `503` + `Retry-After: 5` ያገኛሉ። ተተኪው Ready እስኪሆን ድረስ ያለው የRecreate ባዶ-endpoint ክፍተት ሙሉ መቋረጥ ሆኖ ይቀራል — ይህ የSQLite ቶፖሎጂ ነው እንጂ የፍተሻ የተሳሳተ ውቅር አይደለም።
ውጫዊ Postgres / multi-writer HA **በሰነድ የተገለጸ መደበኛ መንገድ አይደለም**። HA ካስፈለገዎት አንድ ቅጂ ብቻ ይጠቀሙ ወይም ፕሮጀክቱ ለየብቻ የፈተሸውንና በሰነድ ያስቀመጠውን ቶፖሎጂ ያስኪዱ። የPostgres/MySQL ሥራ በ[#8075](https://github.com/diegosouzapw/OmniRoute/issues/8075) ውስጥ ይገኛል። ይህ እስኪለቀቅ ድረስ **ትልቅ** የ`/v1/responses` አቅምን ለማባዛት የሚደገፈው ብቸኛ መንገድ N እርስ በርሳቸው ገለልተኛ ሂደቶችን (የሚቀጥለውን ክፍል ይመልከቱ) ማስኬድ ነው እንጂ በአንድ volume ላይ `replicas > 1` ማድረግ አይደለም።
## የአቅም ማስፋፋት፦ N ነጻ ሂደቶች
አንድ Node ሂደት **አንድ V8 heap** ነው። ሁለት በጊዜ የሚደራረቡ ~3 MiB / ~~750k-token የኮዲንግ-ወኪል `POST /v1/responses` ጥያቄዎች (RTK + Caveman) ያንን heap በ~~12 Gi (`FATAL ERROR: Reached heap limit`) ላይ እንዲቋረጥ ያደርጉታል፣ እንዲሁም 16 Gi cgroupን OOM ሊያደርጉ ይችላሉ። [#7849](https://github.com/diegosouzapw/OmniRoute/issues/7849)ን ይመልከቱ። ይህ መለኪያ የ**ማህደረ ትውስታ በጀት** ማስጠንቀቂያ እንጂ፣ በአንድ ጊዜ ለሚሰሩ ረጅም `/v1/responses` ጥያቄዎች የምርቱ ጥብቅ ከፍተኛ ገደብ ሁለት ነው ማለት አይደለም። ከባድ የchat መግቢያ፣ ከዚያው V8/cgroup ጣሪያ በራስ-ሰር በሚወሰን የገቢ ባይት በጀት (`OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES`፣ `src/shared/middleware/admissionBudget.ts`) ይቆጣጠራል — አስቀድሞ መጠኑ በተወሰነ ሂደት ላይ ይህን ወደ ላይ መቀየር (ወይም የቀድሞውን `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` የጥያቄ-ብዛት ገደብ ማዘጋጀት) መቋረጡን እንደገና ያስከትላል። አነስተኛ chats፣ `/healthz`፣ `/v1/models` እና MCP በዚያ ገደብ ውስጥ **አይካተቱም**።
### አንድ ሂደት፦ ከሁለት በላይ ረጅም `/v1/responses`
**ጤናማ** ሂደት (heap ከ`OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO` በታች፣ ነባሪው `0.75`) የሂደቱ አጠቃላይ በሂደት ላይ ያለ የባይት በጀት (`OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` / #10110) በቂ ቦታ ካለው፣ በአንድ ጊዜ ከሁለት በላይ ረጅም `POST /v1/responses` ጥያቄዎችን ማስኬድ **ይችላል**። ከ`OMNIROUTE_CHAT_LARGE_BODY_BYTES` (ነባሪው 256 KiB) ጋር እኩል ወይም ከዚያ በላይ የሆኑ bodies፣ እንደ መዋቅር-ከባድ ጥያቄዎች ተመሳሳይ የከባድ ስራ lease ይወስዳሉ፣ እንዲሁም ተመሳሳዩን [#10437](https://github.com/diegosouzapw/OmniRoute/pull/10437) `tryAcquireHealthyHeadroom` ማምለጫ (`OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM`) ይጠቀማሉ። በአንድ ጊዜ በአስርዎች የሚቆጠሩ ረጅም SSE clientsን ማስኬድ (ኦፕሬተሮች ብዙውን ጊዜ 40–50 ያስፈልጋቸዋል) የ**ማህደረ ትውስታ በጀት** ጉዳይ ነው — heap + ዋና/headroom slots + `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES`ን በተገቢው መጠን ያዘጋጁ — የምርቱ ጥብቅ “ከፍተኛው 2” ገደብ አይደለም። ጫና ያለበት heap አሁንም ዳግም ሊሞከር በሚችል `503` ጥያቄዎችን ይቀንሳል፣ ስለዚህ #7849 ተመልሶ አይከሰትም።
**heapsን ለማባዛት** (ነጻ የV8 old-spaces) **ዛሬ**፦
| ያድርጉ | አያድርጉ |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **N containers/pods**ን ያስኪዱ፤ እያንዳንዳቸውም የራሳቸው `DATA_DIR` / volume ይኑራቸው | በአንድ SQLite file ላይ `replicas > 1` አያዘጋጁ |
| ከባድ በሂደት ላይ ያሉ ጥያቄዎችን + healthy-headroomን ከheap / በሂደት ላይ ካለው የባይት በጀት አንጻር መጠናቸውን ይወስኑ፤ 1–2 ጥንቃቄ የተሞላበት የ#7849 ነባሪ እንጂ የምርቱ ጥብቅ ከፍተኛ ገደብ አይደለም | ለአንድ ሂደት 8× RAM እና ያልተገደበ የብዛት ገደብ አይስጡ |
| አማራጭ፦ ለ**ጋራ የquota counters** `QUOTA_STORE_DRIVER=redis` + `QUOTA_STORE_REDIS_URL` | Redisን እንደ የጋራ SQLite አይቁጠሩት — አይደለም |
| የprovider secretsን ወደ እያንዳንዱ instance ይቅዱ (ወይም የተከፋፈሉ dashboardsን ይቀበሉ) | በinstances መካከል አንድ dashboard / አንድ call-log አይጠብቁ |
| ከፊት ለፊት ማንኛውንም load balancer ይጠቀሙ፤ በAPI key ወይም session የተጣበቀ ማድረግ በቂ ነው | ለአንድ vendor የተወሰነ መጠን-አዋቂ middleware አይጠይቁ |
ሃርድዌር፦ በእያንዳንዱ instance በአንድ ጊዜ የሚሰሩ ረጅም `/v1/responses` ጥያቄዎች ብዛት የ**ማህደረ ትውስታ በጀት** ጉዳይ ነው (heap + በሂደት ላይ ያሉ ባይቶች / #10110)። N ነጻ `DATA_DIR`s አሁንም heapsን ያባዛሉ፦ የhost RAM `N × cgroup`ን መሸፈን አለበት፣ “N=8 ያለው አንድ 16 Gi pod”ን አይደለም። በአንድ SQLite file ላይ ፈጽሞ `replicas > 1` አያዘጋጁ።
የCompose ንድፍ (ሁለት heaps፣ ሁለት volumes — `deploy.replicas: 2` አይደለም)፦
```yaml
services:
omniroute-a:
image: diegosouzapw/omniroute:3.8.49
environment:
DATA_DIR: /app/data
OMNIROUTE_MEMORY_MB: "12288"
QUOTA_STORE_DRIVER: redis
QUOTA_STORE_REDIS_URL: redis://redis:6379
volumes: [omniroute-a-data:/app/data]
ports: ["20128:20128"]
omniroute-b:
image: diegosouzapw/omniroute:3.8.49
environment:
DATA_DIR: /app/data
OMNIROUTE_MEMORY_MB: "12288"
QUOTA_STORE_DRIVER: redis
QUOTA_STORE_REDIS_URL: redis://redis:6379
volumes: [omniroute-b-data:/app/data]
ports: ["20138:20128"]
volumes:
omniroute-a-data:
omniroute-b-data:
```
የሂደት ውስጥ ጥግግት (compressionን ከHTTP isolate ማውጣት) [#11023](https://github.com/diegosouzapw/OmniRoute/issues/11023) ነው። በጋራ durable state ላይ ያለ አንድ ሎጂካዊ cluster [#8075](https://github.com/diegosouzapw/OmniRoute/issues/8075) ነው።
## ጠቃሚ ማስታወሻዎች
- **SQLite WAL ሁነታ፦** OmniRoute የቅርብ ጊዜ ለውጦችን ወደ `storage.sqlite` checkpoint ማድረግ እንዲችል `docker stop` እስኪጠናቀቅ ድረስ ጊዜ ሊሰጠው ይገባል። አብረው የቀረቡት Compose ፋይሎች የ40 ሰከንድ የማቆሚያ የእፎይታ ጊዜን አስቀድመው አዘጋጅተዋል። image-ውን በቀጥታ የሚያስኬዱ ከሆነ፣ `--stop-timeout 40`ን ይጠቀሙ።
- **`DISABLE_SQLITE_AUTO_BACKUP`፦** መደበኛ/ከመጻፍ በፊት የሚደረጉ ምትኬዎች በውጫዊ ሥርዓት የሚተዳደሩ ከሆነ ወደ `true` ያቀናብሩት። ያሉ የውሂብ ጎታዎች ፍልሰቶች አሁንም የራሳቸውን ዘላቂ የደህንነት ቅጂ እና የጅምላ ፍልሰት መከላከያ ይፈልጋሉ።
- **የውሂብ ቋሚነት፦** ኮንቴይነሩ ዳግም በሚጀምርበት ጊዜ ሁሉ የውሂብ ጎታዎን፣ ቁልፎችዎን እና ውቅሮችዎን ለማቆየት ሁልጊዜ volumeን ወደ `/app/data` mount ያድርጉ።
- **የፖርት ውቅር፦** ነባሪውን `20128` ፖርት ለመቀየር `PORT` environment variableን override ያድርጉ።
## ተጨማሪ ይመልከቱ
- [የVM ማሰማሪያ መመሪያ](../ops/VM_DEPLOYMENT_GUIDE.md) — የVM + nginx + Cloudflare ማዋቀር
- [የFly.io ማሰማሪያ መመሪያ](../ops/FLY_IO_DEPLOYMENT_GUIDE.md) — ወደ Fly.io ያሰማሩ
- [የEnvironment ውቅር](../reference/ENVIRONMENT.md) — ሙሉ የ`.env` ማጣቀሻ

277
docs/i18n/am/docs/guides/ELECTRON_GUIDE.md Normal file
View File

@@ -0,0 +1,277 @@
# Electron Desktop Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/ELECTRON_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/ELECTRON_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/ELECTRON_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/ELECTRON_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/ELECTRON_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/ELECTRON_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/ELECTRON_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/ELECTRON_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/ELECTRON_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/ELECTRON_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/ELECTRON_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/ELECTRON_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/ELECTRON_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/ELECTRON_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/ELECTRON_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/ELECTRON_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/ELECTRON_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/ELECTRON_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/ELECTRON_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/ELECTRON_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/ELECTRON_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/ELECTRON_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/ELECTRON_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/ELECTRON_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/ELECTRON_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/ELECTRON_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/ELECTRON_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/ELECTRON_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/ELECTRON_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/ELECTRON_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/ELECTRON_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/ELECTRON_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/ELECTRON_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/ELECTRON_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/ELECTRON_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/ELECTRON_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/ELECTRON_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/ELECTRON_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/ELECTRON_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/ELECTRON_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/ELECTRON_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/ELECTRON_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/ELECTRON_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/ELECTRON_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/ELECTRON_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/ELECTRON_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/ELECTRON_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/ELECTRON_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/ELECTRON_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/ELECTRON_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/ELECTRON_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/ELECTRON_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/ELECTRON_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/ELECTRON_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/ELECTRON_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/ELECTRON_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/ELECTRON_GUIDE.md)
---
> **ዋና የመረጃ ምንጭ:** `electron/` workspace
> **መጨረሻ የተዘመነው:** 2026-06-28 — v3.8.40
OmniRoute በ**Electron 41** + **electron-builder 26.10** ላይ የተገነባ በበርካታ መድረኮች (Windows / macOS / Linux) ላይ የሚሠራ የዴስክቶፕ መተግበሪያ ይዞ ይመጣል። የዴስክቶፕ መተግበሪያው የNext.js standalone አገልጋይን እንደ ልጅ ሂደት ያስጀምራል፣ `BrowserWindow`ን ወደ እሱ ያመለክታል፣ እንዲሁም የስርዓት ትሪ፣ ራስ-ሰር ማዘመኛ፣ የIPC ድልድይ እና ምንም ውቅር የማይፈልግ የሚስጥር ማስነሻ ያክላል።
## ሥነ ሕንፃ
```
┌──────────────────────────────────────────────┐
│ የElectron ዋና ሂደት (electron/main.js) │
│ ├─ የነጠላ ኢንስታንስ መቆለፊያ │
│ ├─ ልጅ ሂደት፦ Next.js standalone አገልጋይ │
│ │ (በElectron Node የማስኬጃ አካባቢ የሚጀመር) │
│ ├─ BrowserWindow → http://localhost:PORT │
│ ├─ የስርዓት ትሪ + የአውድ ምናሌ │
│ ├─ በelectron-updater በኩል ራስ-ሰር ማዘመን │
│ ├─ የይዘት ደህንነት ፖሊሲ (የክፍለ ጊዜ ራስጌዎች) │
│ └─ የሚስጥር ማስነሻ (JWT / API_KEY_SECRET) │
└──────────────────────────────────────────────┘
↕ የIPC ድልድይ (electron/preload.js)
┌──────────────────────────────────────────────┐
│ አቅራቢ (Next.js ዳሽቦርድ) │
│ window.electronAPI.* (contextIsolation) │
└──────────────────────────────────────────────┘
```
## ስሪቶች
ከ`electron/package.json` የተረጋገጠ፦
| ጥቅል | ስሪት |
| ------------------ | -------------------------------------------------------------------- |
| `electron` | `^43.4.1` |
| `electron-builder` | `^26.15.3` |
| `electron-updater` | `^6.8.9` |
| `better-sqlite3` | root `^13.0.2` (የNode-API አስቀድሞ ግንባታዎች — የElectron ዳግም ግንባታ አያስፈልግም) |
| የመተግበሪያ ስሪት | `3.8.0` |
| የመተግበሪያ መታወቂያ | `online.omniroute.desktop` |
| የምርት ስም | `OmniRoute` |
## ስክሪፕቶች (root `package.json`)
| ስክሪፕት | ዓላማ |
| --------------------------------- | ------------------------------------------------------------------- |
| `npm run electron:dev` | `npm run dev`ን ያስጀምራል + `localhost:20128`ን ይጠብቃል + Electronን ያስጀምራል |
| `npm run electron:build` | Next.jsን ይገነባል፣ ከዚያም ለአሁኑ OS `electron-builder`ን ያስኬዳል |
| `npm run electron:build:win` | የWindows NSIS ጫኝ + ተንቀሳቃሽ ስሪት (x64) ይገነባል |
| `npm run electron:build:mac` | የmacOS DMG (Intel + Apple Silicon) ይገነባል |
| `npm run electron:build:linux` | የLinux AppImage + DEB (x64 + arm64) ይገነባል |
| `npm run electron:smoke:packaged` | የታሸገውን ባይነሪ ያስጀምራል፣ `/login`ን ለHTTP 200 ይመረምራል፣ ከዚያም ያቆማል |
የ`electron/` workspace የሚከተሉትንም ያቀርባል፦
- `npm run prepare:bundle` — `scripts/build/prepare-electron-standalone.mjs`ን ያስኬዳል
- `npm run build:mac-x64` / `build:mac-arm64` — የነጠላ አርክቴክቸር macOS ግንባታዎች
- `npm run pack` — ለአካባቢያዊ ሙከራ የማውጫ-ብቻ ግንባታ (ጫኝ የሌለው)
## የማውጫ አቀማመጥ
```
electron/
├── package.json # የElectron ጥገኞች + የelectron-builder ውቅር
├── main.js # ዋና ሂደት (24 KB — ከታች ያሉትን ማብራሪያዎች ይመልከቱ)
├── preload.js # የcontextBridge IPC ድልድይ
├── types.d.ts # የAppInfo / ServerStatus / ElectronAPI ዓይነቶች
├── README.md # በworkspace ውስጥ ያሉ ማስታወሻዎች
├── assets/ # icon.png, icon.ico, icon.icns, tray-icon.png
└── dist-electron/ # የelectron-builder ውጤት (በgit ችላ የተባለ)
scripts/
├── build/
│ └── prepare-electron-standalone.mjs # የ.next/electron-standalone ጥቅልን ያዘጋጃል
└── dev/
└── smoke-electron-packaged.mjs # ከግንባታ በኋላ የሚደረግ የsmoke ሙከራ
```
ሁለቱም `main.js` እና `preload.js` TypeScript ሳይሆኑ **CommonJS `.js` ፋይሎች** ናቸው።
የrenderer ወገን ዓይነት መግለጫዎች `electron/types.d.ts` ውስጥ ይገኛሉ።
## IPC ድልድይ (`preload.js`)
preload በ`contextIsolation: true` እና `nodeIntegration: false`፣ `contextBridge`ን
በመጠቀም በተፈቀደለት ዝርዝር ውስጥ ያለ APIን በ`window.electronAPI` ላይ ያቀርባል።
```javascript
const VALID_CHANNELS = {
invoke: [
"get-app-info",
"open-external",
"get-data-dir",
"restart-server",
"check-for-updates",
"download-update",
"install-update",
"get-app-version",
],
send: ["window-minimize", "window-maximize", "window-close"],
receive: ["server-status", "port-changed", "update-status"],
};
```
የቀረቡ ሜተዶች፦
| የRenderer ጥሪ | ዓይነት |
| ----------------------------------------------------------------- | ------------------------ |
| `getAppInfo()` → `{ name, version, platform, isDev, port }` | invoke |
| `openExternal(url)` | invoke |
| `getDataDir()` | invoke |
| `restartServer()` | invoke |
| `getAppVersion()` | invoke |
| `checkForUpdates()` / `downloadUpdate()` / `installUpdate()` | invoke |
| `minimizeWindow()` / `maximizeWindow()` / `closeWindow()` | send |
| `onServerStatus(cb)` / `onPortChanged(cb)` / `onUpdateStatus(cb)` | receive (disposer ይመልሳል) |
የreceive አጋዥ ሜተዶች በ`removeAllListeners` ላይ ከመመሥረት ይልቅ **disposer function**
ይመልሳሉ — ይህም React components እንደገና በሚጫኑበት ጊዜ listener እንዳይከማች ይከላከላል።
## የServer የሕይወት ዑደት
`main.js` ከsystem Node ጋር የnative-module ABI አለመጣጣምን ለማስወገድ፣ የNext.js standalone
ጥቅልን በElectron Node runtime በቀጥታ ያስጀምራል፦
```js
spawn(process.execPath, [serverScript], {
cwd: NEXT_SERVER_PATH,
env: {
...serverEnv,
PORT,
NODE_ENV: "production",
ELECTRON_RUN_AS_NODE: "1",
NODE_PATH,
},
stdio: "pipe",
});
```
ዋና ዋና ነጥቦች፦
- `waitForServer()` windowን ከማሳየቱ በፊት URLን እስከ 30 s ድረስ በየጊዜው ይፈትሻል (በcold start ጊዜ ባዶ ማያ ገጽ አይታይም)።
- `stdio: "pipe"` stdout/stderrን ይይዛል፤ የዝግጁነት ሐረጎች (`Ready` / `listening`) `server-status: running`ን በIPC ይልካሉ።
- `before-quit` ለሰላማዊ SIGTERM (WAL checkpoint) እስከ 5 s ድረስ ይጠብቃል፣ ከዚያ SIGKILLን ይልካል።
- በtray ውስጥ ያለው የport መቀየሪያ (`20128`, `3000`, `8080`) serverን አቁሞ እንደገና ያስጀምራል፣ ከዚያም BrowserWindowን እንደገና ይጭናል።
## ዜሮ-ውቅር ሚስጥር ማስጀመሪያ
በመጀመሪያው ማስጀመር፣ ዋናው ፕሮሰስ የጎደሉ ሚስጥሮችን በራስ-ሰር ያመነጫል እና ያስቀምጣል፦
| ሚስጥር | ምንጭ |
| ------------------------ | ------------------------------------------------------------------------------- |
| `JWT_SECRET` | `crypto.randomBytes(64).toString("hex")` |
| `STORAGE_ENCRYPTION_KEY` | `crypto.randomBytes(32).toString("hex")` (የተመሰጠሩ የመግቢያ መረጃዎች አስቀድመው ካሉ እምቢ ይላል) |
| `API_KEY_SECRET` | `crypto.randomBytes(32).toString("hex")` |
በ`<DATA_DIR>/server.env` ውስጥ ይቀመጣል። `DATA_DIR` እንደሚከተለው ይፈታል፦
- Windows: `%APPDATA%\omniroute`
- Linux: `$XDG_CONFIG_HOME/omniroute` ወይም `~/.omniroute`
- macOS: `~/.omniroute`
## መስኮት እና ሲስተም ትሪ
- `BrowserWindow`: 1400×900 (ዝቅተኛው 1024×700)፣ `backgroundColor: "#0a0a0a"`።
- macOS: `titleBarStyle: "hiddenInset"`፣ የመስኮት መቆጣጠሪያ አዝራሮች በ`{ x: 16, y: 16 }`።
- Windows/Linux: የስርዓቱ ተወላጅ የርዕስ አሞሌ።
- የመዝጊያ አዝራሩ ወደ ሲስተም ትሪ ያሳንሳል፤ የትሪው ምናሌ **OmniRouteን ክፈት**፣ **ዳሽቦርድን ክፈት** (በውጫዊ አሳሽ)፣ **የሰርቨር ፖርት** ንዑስ ምናሌ፣ **ዝማኔዎችን ፈልግ**፣ **ውጣ** አሉት።
## የይዘት ደህንነት ፖሊሲ
በ`session.defaultSession.webRequest.onHeadersReceived` በኩል ይዋቀራል። ዋና ዋና መመሪያዎች፦
- `frame-ancestors 'none'`፣ `object-src 'none'`፣ `child-src 'none'`
- `connect-src 'self' http://localhost:* http://127.0.0.1:* ws://localhost:* ws://127.0.0.1:* https://*.omniroute.online https://*.omniroute.dev`
- የልማት ሁነታ `'unsafe-eval'`ን ወደ `script-src` ብቻ ይጨምራል
## ራስ-ሰር ዝማኔ
`electron-updater`ን ከGitHub አቅራቢ (`diegosouzapw/OmniRoute`) ጋር ይጠቀማል።
- `autoDownload = false`፣ `autoInstallOnAppQuit = true`
- ክስተቶች በ`update-status` IPC በኩል ወደ renderer ይተላለፋሉ፦
`checking`፣ `available`፣ `not-available`፣ `downloading` (`percent`ን ጨምሮ)፣ `downloaded`፣ `error`
- `installUpdate()` ሰርቨሩን ካቆመ በኋላ `autoUpdater.quitAndInstall()`ን ይጠራል
- በልማት ሁነታ (`!app.isPackaged`) ይዘለላል
## የግንባታ ሂደት
1. `npm run build` → Next.js standalone በ`.next/standalone` ውስጥ።
2. `prepare-electron-standalone.mjs` → ወደ `.next/electron-standalone` እንደገና ያዘጋጃል፣ እንዲሁም ጥቅሉ ቦታውን መቀየር እንዲችል በ`server.js` + `required-server-files.json` ውስጥ ያሉ ፍጹም ዱካዎችን እንደገና ይጽፋል።
3. `electron-builder` `main.js`፣ `preload.js`፣ `node_modules` እና `extraResources: { ../.next/electron-standalone → app }`ን ያሽጋል።
### የግንባታ ዒላማዎች
| ስርዓተ ክወና | ዒላማዎች |
| -------- | --------------------------------------------- |
| Windows | NSIS ጫኚ + ተንቀሳቃሽ (x64) |
| macOS | DMG (Intel + arm64፣ ወደ Applications ጎትቶ በመጣል) |
| Linux | AppImage + DEB (x64 + arm64) |
የNSIS ቅንብሮች፦ `oneClick: false`፣ ተጠቃሚው የመጫኛ ማውጫውን እንዲመርጥ ያስችላል፣ የዴስክቶፕ እና የStart-Menu አቋራጮችን ይፈጥራል።
## የታሸገውን ግንባታ የጭስ ሙከራ ማድረግ
```bash
npm run electron:smoke:packaged
```
`scripts/dev/smoke-electron-packaged.mjs`፦
- ለአሁኑ መድረክ በ`electron/dist-electron/` ውስጥ ያለውን የታሸገ executable በራስ-ሰር ያገኛል።
- የገንቢውን ውሂብ እንዳይነካ በተነጠሉ `HOME`/`APPDATA`/`XDG_*` ማውጫዎች ያስጀምራል።
- በ45 s ውስጥ HTTP 200 ለማግኘት `http://127.0.0.1:20128/login`ን በተደጋጋሚ ይፈትሻል።
- ለከባድ የስህተት ቅጦች (`Cannot find module`፣ `MODULE_NOT_FOUND`፣ `ERR_DLOPEN_FAILED`፣ `Failed to start server`፣ ወዘተ) stderr/stdoutን ይከታተላል።
- ዝግጁነት ከተረጋገጠ በኋላ ለ2 s የተረጋጋ የማስኬጃ ጊዜ ይጠብቃል፣ ከዚያ SIGTERMን ይልካል እና ፖርቱ ነፃ እስኪሆን ይጠብቃል።
- በCI ውስጥ፣ `--no-sandbox --disable-gpu`ን (እና በLinux ላይ `--disable-dev-shm-usage`ን) በራስ-ሰር ያስተላልፋል።
የአካባቢ ተለዋዋጭ መሻሮች፦ `ELECTRON_SMOKE_APP_EXECUTABLE`፣ `ELECTRON_SMOKE_URL`፣ `ELECTRON_SMOKE_TIMEOUT_MS`፣ `ELECTRON_SMOKE_SETTLE_MS`፣ `ELECTRON_SMOKE_DATA_DIR`፣ `ELECTRON_SMOKE_KEEP_DATA`፣ `ELECTRON_SMOKE_STREAM_LOGS`።
## የኮድ ፊርማ
`electron/package.json` የፊርማ ማረጋገጫዎችን በቀጥታ **አያዋቅርም**። በenv vars በኩል ወደ `electron-builder` ያስተላልፏቸው፦
### macOS
```bash
export APPLE_ID=<email>
export APPLE_APP_SPECIFIC_PASSWORD=<password>
export APPLE_TEAM_ID=<id>
export CSC_LINK=path/to/cert.p12
export CSC_KEY_PASSWORD=<cert-password>
npm run electron:build:mac
```
### Windows
```bash
export CSC_LINK=path/to/cert.pfx
export CSC_KEY_PASSWORD=<cert-password>
npm run electron:build:win
```
### Linux
የAppImage ፊርማ አማራጭ ነው — ፊርማ የሚደረግ ከሆነ `LINUX_GPG_KEY`ን ያዘጋጁ።
## ስርጭት
የግንባታ ውጤቶች በ`electron/dist-electron/` ውስጥ ይቀመጣሉ፦
- `OmniRoute.Setup.X.Y.Z.exe`, `OmniRoute X.Y.Z.exe` (Windows)
- `OmniRoute-X.Y.Z-mac.dmg`, `OmniRoute-X.Y.Z-arm64-mac.dmg` (macOS)
- `OmniRoute-X.Y.Z.AppImage`, `omniroute-desktop_X.Y.Z_amd64.deb` (Linux)
ልቀቶች በGitHub Releases (`diegosouzapw/OmniRoute`) ላይ ይታተማሉ፤ `electron-updater`ም አዳዲስ ስሪቶችን የሚፈትሸው በዚያው ነው።
## ችግር መፍታት
| ምልክት | መፍትሔ |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| ከElectron ዋና ስሪት ማሻሻያ በኋላ `Cannot find module 'better-sqlite3'` | better-sqlite3 v13 የNode-API ቀድሞ ግንባታዎችን ይዞ ይመጣል — በስር ማውጫው ላይ `npm install`ን እና `prepare:bundle`ን እንደገና ያስኪዱ (ለአሁኑ መድረክ ቀድሞ ግንባታውን ያረጋግጣል) |
| ለnative module `ERR_DLOPEN_FAILED` | `prepare:bundle`ን እንደገና ያስኪዱ — ለአሁኑ መድረክ የNode-API ቀድሞ ግንባታ ሲጎድል ወዲያውኑ ያቋርጣል |
| በLinux ላይ መስኮቱ ባዶ ሆኖ ይታያል | የNext.js server በትክክል ከPORT ጋር መገናኘቱን ያረጋግጡ (`[Server]` logsን ይፈትሹ) |
| የmacOS notarization ሂደት ይቆማል | `APPLE_*` vars በ`.env` ውስጥ ብቻ ሳይሆኑ export መደረጋቸውን ያረጋግጡ |
| የWindows SmartScreen ማስጠንቀቂያ | በEV cert ይፈርሙ፣ ወይም ተጠቃሚዎች ቀኝ-ጠቅ አድርገው → "ለማንኛውም አስኪድ" የሚለውን ይምረጡ |
| የport-in-use ስህተት ምክንያት smoke test አይሳካም | `electron:smoke:packaged`ን ከማስኬድዎ በፊት በ20128 ላይ ያለ ማንኛውንም local dev server ያቁሙ |
## ተጨማሪ ይመልከቱ
- [SETUP_GUIDE.md](./SETUP_GUIDE.md)
- [RELEASE_CHECKLIST.md](../ops/RELEASE_CHECKLIST.md)
- ምንጭ፦ `electron/main.js`, `electron/preload.js`, `electron/package.json`
- ረዳቶች፦ `scripts/build/prepare-electron-standalone.mjs`, `scripts/dev/smoke-electron-packaged.mjs`

2
docs/i18n/am/docs/guides/FEATURES.md
View File

@@ -4,7 +4,7 @@
---
🌐 **ቋንቋዎች:** 🇺🇸 [እንግሊዝኛ](./FEATURES.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/guides/FEATURES.md) | 🇸🇦 [ዓረብኛ](../i18n/ar/docs/guides/FEATURES.md) | 🇦🇿 [አዘርባጃንኛ](../i18n/az/docs/guides/FEATURES.md) | 🇧🇬 [ቡልጋሪያኛ](../i18n/bg/docs/guides/FEATURES.md) | 🇧🇩 [ቤንጋልኛ](../i18n/bn/docs/guides/FEATURES.md) | 🇨🇿 [ቼክኛ](../i18n/cs/docs/guides/FEATURES.md) | 🇩🇰 [ዴንማርክኛ](../i18n/da/docs/guides/FEATURES.md) | 🇩🇪 [ጀርመንኛ](../i18n/de/docs/guides/FEATURES.md) | 🇬🇷 [ግሪክኛ](../i18n/el/docs/guides/FEATURES.md) | 🇪🇸 [ስፓኒሽ](../i18n/es/docs/guides/FEATURES.md) | 🇪🇪 [ኢስቶኒያኛ](../i18n/et/docs/guides/FEATURES.md) | 🇮🇷 [ፋርስኛ](../i18n/fa/docs/guides/FEATURES.md) | 🇫🇮 [ፊንላንድኛ](../i18n/fi/docs/guides/FEATURES.md) | 🇫🇷 [ፈረንሳይኛ](../i18n/fr/docs/guides/FEATURES.md) | 🇮🇪 [አይሪሽ](../i18n/ga/docs/guides/FEATURES.md) | 🇮🇳 [ጉጃራቲኛ](../i18n/gu/docs/guides/FEATURES.md) | 🇳🇬 [ሃውሳ](../i18n/ha/docs/guides/FEATURES.md) | 🇮🇱 [ዕብራይስጥ](../i18n/he/docs/guides/FEATURES.md) | 🇮🇳 [ሂንዲ](../i18n/hi/docs/guides/FEATURES.md) | 🇭🇷 [ክሮኤሽያኛ](../i18n/hr/docs/guides/FEATURES.md) | 🇭🇺 [ሃንጋሪኛ](../i18n/hu/docs/guides/FEATURES.md) | 🇦🇲 [አርሜኒያኛ](../i18n/hy/docs/guides/FEATURES.md) | 🇮🇩 [ኢንዶኔዥያኛ](../i18n/id/docs/guides/FEATURES.md) | 🇳🇬 [ኢግቦ](../i18n/ig/docs/guides/FEATURES.md) | 🇮🇹 [ጣልያንኛ](../i18n/it/docs/guides/FEATURES.md) | 🇯🇵 [ጃፓንኛ](../i18n/ja/docs/guides/FEATURES.md) | 🇬🇪 [ጆርጂያኛ](../i18n/ka/docs/guides/FEATURES.md) | 🇰🇭 [ክመር](../i18n/km/docs/guides/FEATURES.md) | 🇮🇳 [ካናዳኛ](../i18n/kn/docs/guides/FEATURES.md) | 🇰🇷 [ኮሪያኛ](../i18n/ko/docs/guides/FEATURES.md) | 🇱🇹 [ሊቱዌኒያኛ](../i18n/lt/docs/guides/FEATURES.md) | 🇱🇻 [ላትቪያኛ](../i18n/lv/docs/guides/FEATURES.md) | 🇮🇳 [ማላያላም](../i18n/ml/docs/guides/FEATURES.md) | 🇮🇳 [ማራቲኛ](../i18n/mr/docs/guides/FEATURES.md) | 🇲🇾 [ማላይኛ](../i18n/ms/docs/guides/FEATURES.md) | 🇲🇹 [ማልትኛ](../i18n/mt/docs/guides/FEATURES.md) | 🇲🇲 [በርማኛ](../i18n/my/docs/guides/FEATURES.md) | 🇳🇵 [ኔፓልኛ](../i18n/ne/docs/guides/FEATURES.md) | 🇳🇱 [ደች](../i18n/nl/docs/guides/FEATURES.md) | 🇳🇴 [ኖርዌይኛ](../i18n/no/docs/guides/FEATURES.md) | 🇮🇳 [ኦዲያ](../i18n/or/docs/guides/FEATURES.md) | 🇮🇳 [ፑንጃቢኛ](../i18n/pa/docs/guides/FEATURES.md) | 🇵🇭 [ፊሊፒኖ](../i18n/phi/docs/guides/FEATURES.md) | 🇵🇱 [ፖላንድኛ](../i18n/pl/docs/guides/FEATURES.md) | 🇵🇹 [ፖርቱጋልኛ (ፖርቱጋል)](../i18n/pt/docs/guides/FEATURES.md) | 🇧🇷 [ፖርቱጋልኛ (ብራዚል)](../i18n/pt-BR/docs/guides/FEATURES.md) | 🇷🇴 [ሮማኒያኛ](../i18n/ro/docs/guides/FEATURES.md) | 🇷🇺 [ሩሲያኛ](../i18n/ru/docs/guides/FEATURES.md) | 🇱🇰 [ሲንሃላ](../i18n/si/docs/guides/FEATURES.md) | 🇸🇰 [ስሎቫክኛ](../i18n/sk/docs/guides/FEATURES.md) | 🇸🇮 [ስሎቬንኛ](../i18n/sl/docs/guides/FEATURES.md) | 🇷🇸 [ሰርቢያኛ](../i18n/sr/docs/guides/FEATURES.md) | 🇸🇪 [ስዊድንኛ](../i18n/sv/docs/guides/FEATURES.md) | 🇰🇪 [ስዋሂሊ](../i18n/sw/docs/guides/FEATURES.md) | 🇮🇳 [ታሚልኛ](../i18n/ta/docs/guides/FEATURES.md) | 🇮🇳 [ተሉጉኛ](../i18n/te/docs/guides/FEATURES.md) | 🇹🇭 [ታይኛ](../i18n/th/docs/guides/FEATURES.md) | 🇹🇷 [ቱርክኛ](../i18n/tr/docs/guides/FEATURES.md) | 🇺🇦 [ዩክሬንኛ](../i18n/uk-UA/docs/guides/FEATURES.md) | 🇵🇰 [ኡርዱ](../i18n/ur/docs/guides/FEATURES.md) | 🇺🇿 [ኡዝቤክኛ](../i18n/uz/docs/guides/FEATURES.md) | 🇻🇳 [ቬትናምኛ](../i18n/vi/docs/guides/FEATURES.md) | 🇳🇬 [ዮሩባ](../i18n/yo/docs/guides/FEATURES.md) | 🇨🇳 [ቻይንኛ (ቀለል ያለ)](../i18n/zh-CN/docs/guides/FEATURES.md) | 🇹🇼 [ቻይንኛ (ባህላዊ)](../i18n/zh-TW/docs/guides/FEATURES.md)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/FEATURES.md) · 🇸🇦 [ar](../../../ar/docs/guides/FEATURES.md) · 🇦🇿 [az](../../../az/docs/guides/FEATURES.md) · 🇧🇬 [bg](../../../bg/docs/guides/FEATURES.md) · 🇧🇩 [bn](../../../bn/docs/guides/FEATURES.md) · 🇨🇿 [cs](../../../cs/docs/guides/FEATURES.md) · 🇩🇰 [da](../../../da/docs/guides/FEATURES.md) · 🇩🇪 [de](../../../de/docs/guides/FEATURES.md) · 🇬🇷 [el](../../../el/docs/guides/FEATURES.md) · 🇪🇸 [es](../../../es/docs/guides/FEATURES.md) · 🇪🇪 [et](../../../et/docs/guides/FEATURES.md) · 🇮🇷 [fa](../../../fa/docs/guides/FEATURES.md) · 🇫🇮 [fi](../../../fi/docs/guides/FEATURES.md) · 🇫🇷 [fr](../../../fr/docs/guides/FEATURES.md) · 🇮🇪 [ga](../../../ga/docs/guides/FEATURES.md) · 🇮🇳 [gu](../../../gu/docs/guides/FEATURES.md) · 🇳🇬 [ha](../../../ha/docs/guides/FEATURES.md) · 🇮🇱 [he](../../../he/docs/guides/FEATURES.md) · 🇮🇳 [hi](../../../hi/docs/guides/FEATURES.md) · 🇭🇷 [hr](../../../hr/docs/guides/FEATURES.md) · 🇭🇺 [hu](../../../hu/docs/guides/FEATURES.md) · 🇦🇲 [hy](../../../hy/docs/guides/FEATURES.md) · 🇮🇩 [id](../../../id/docs/guides/FEATURES.md) · 🇳🇬 [ig](../../../ig/docs/guides/FEATURES.md) · 🇮🇹 [it](../../../it/docs/guides/FEATURES.md) · 🇯🇵 [ja](../../../ja/docs/guides/FEATURES.md) · 🇬🇪 [ka](../../../ka/docs/guides/FEATURES.md) · 🇰🇭 [km](../../../km/docs/guides/FEATURES.md) · 🇮🇳 [kn](../../../kn/docs/guides/FEATURES.md) · 🇰🇷 [ko](../../../ko/docs/guides/FEATURES.md) · 🇱🇹 [lt](../../../lt/docs/guides/FEATURES.md) · 🇱🇻 [lv](../../../lv/docs/guides/FEATURES.md) · 🇮🇳 [ml](../../../ml/docs/guides/FEATURES.md) · 🇮🇳 [mr](../../../mr/docs/guides/FEATURES.md) · 🇲🇾 [ms](../../../ms/docs/guides/FEATURES.md) · 🇲🇹 [mt](../../../mt/docs/guides/FEATURES.md) · 🇲🇲 [my](../../../my/docs/guides/FEATURES.md) · 🇳🇵 [ne](../../../ne/docs/guides/FEATURES.md) · 🇳🇱 [nl](../../../nl/docs/guides/FEATURES.md) · 🇳🇴 [no](../../../no/docs/guides/FEATURES.md) · 🇮🇳 [or](../../../or/docs/guides/FEATURES.md) · 🇮🇳 [pa](../../../pa/docs/guides/FEATURES.md) · 🇵🇭 [phi](../../../phi/docs/guides/FEATURES.md) · 🇵🇱 [pl](../../../pl/docs/guides/FEATURES.md) · 🇵🇹 [pt](../../../pt/docs/guides/FEATURES.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/FEATURES.md) · 🇷🇴 [ro](../../../ro/docs/guides/FEATURES.md) · 🇷🇺 [ru](../../../ru/docs/guides/FEATURES.md) · 🇱🇰 [si](../../../si/docs/guides/FEATURES.md) · 🇸🇰 [sk](../../../sk/docs/guides/FEATURES.md) · 🇸🇮 [sl](../../../sl/docs/guides/FEATURES.md) · 🇷🇸 [sr](../../../sr/docs/guides/FEATURES.md) · 🇸🇪 [sv](../../../sv/docs/guides/FEATURES.md) · 🇰🇪 [sw](../../../sw/docs/guides/FEATURES.md) · 🇮🇳 [ta](../../../ta/docs/guides/FEATURES.md) · 🇮🇳 [te](../../../te/docs/guides/FEATURES.md) · 🇹🇭 [th](../../../th/docs/guides/FEATURES.md) · 🇹🇷 [tr](../../../tr/docs/guides/FEATURES.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/FEATURES.md) · 🇵🇰 [ur](../../../ur/docs/guides/FEATURES.md) · 🇺🇿 [uz](../../../uz/docs/guides/FEATURES.md) · 🇻🇳 [vi](../../../vi/docs/guides/FEATURES.md) · 🇳🇬 [yo](../../../yo/docs/guides/FEATURES.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/FEATURES.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/FEATURES.md)
የOmniRoute ዳሽቦርድ እያንዳንዱን ክፍል የሚያሳይ ምስላዊ መመሪያ።

255
docs/i18n/am/docs/guides/FREE_PROVIDER_RANKINGS.md Normal file
View File

@@ -0,0 +1,255 @@
# Free Provider Rankings (Arena ELO) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/FREE_PROVIDER_RANKINGS.md) · 🇸🇦 [ar](../../../ar/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇦🇿 [az](../../../az/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇧🇬 [bg](../../../bg/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇧🇩 [bn](../../../bn/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇨🇿 [cs](../../../cs/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇩🇰 [da](../../../da/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇩🇪 [de](../../../de/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇬🇷 [el](../../../el/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇪🇸 [es](../../../es/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇪🇪 [et](../../../et/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇷 [fa](../../../fa/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇫🇮 [fi](../../../fi/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇫🇷 [fr](../../../fr/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇪 [ga](../../../ga/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [gu](../../../gu/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇳🇬 [ha](../../../ha/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇱 [he](../../../he/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [hi](../../../hi/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇭🇷 [hr](../../../hr/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇭🇺 [hu](../../../hu/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇦🇲 [hy](../../../hy/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇩 [id](../../../id/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇳🇬 [ig](../../../ig/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇹 [it](../../../it/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇯🇵 [ja](../../../ja/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇬🇪 [ka](../../../ka/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇰🇭 [km](../../../km/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [kn](../../../kn/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇰🇷 [ko](../../../ko/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇱🇹 [lt](../../../lt/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇱🇻 [lv](../../../lv/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [ml](../../../ml/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [mr](../../../mr/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇲🇾 [ms](../../../ms/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇲🇹 [mt](../../../mt/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇲🇲 [my](../../../my/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇳🇵 [ne](../../../ne/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇳🇱 [nl](../../../nl/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇳🇴 [no](../../../no/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [or](../../../or/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [pa](../../../pa/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇵🇭 [phi](../../../phi/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇵🇱 [pl](../../../pl/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇵🇹 [pt](../../../pt/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇷🇴 [ro](../../../ro/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇷🇺 [ru](../../../ru/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇱🇰 [si](../../../si/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇸🇰 [sk](../../../sk/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇸🇮 [sl](../../../sl/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇷🇸 [sr](../../../sr/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇸🇪 [sv](../../../sv/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇰🇪 [sw](../../../sw/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [ta](../../../ta/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇮🇳 [te](../../../te/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇹🇭 [th](../../../th/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇹🇷 [tr](../../../tr/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇵🇰 [ur](../../../ur/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇺🇿 [uz](../../../uz/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇻🇳 [vi](../../../vi/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇳🇬 [yo](../../../yo/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/FREE_PROVIDER_RANKINGS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/FREE_PROVIDER_RANKINGS.md)
---
> **TL;DR**: OmniRoute የሞዴል ጥራትን በመጠቀም **ነፃ** አቅራቢዎቹን በ**Arena AI
> (LMArena-style) ELO ውጤቶች** ደረጃ ይሰጣል። ለተግባርዎ እጅግ ጠንካራ ሞዴሎችን የትኞቹ ነፃ አቅራቢዎች
> እንደሚያቀርቡ ለማየት፣ በዳሽቦርዱ ውስጥ ያለውን **የነፃ አቅራቢዎች ደረጃ** ገጽ ይክፈቱ —
> አጠቃላይ ደረጃውን ወይም በምድብ (ኮድ መጻፍ፣ ግምገማ፣ ሰነድ ማዘጋጀት፣ ስህተት ማረም) የተጣራውን ማየት ይችላሉ።
---
## ምንድን ነው
OmniRoute **ነፃ/ማረጋገጫ-የማይፈልጉ** ተብለው ምልክት የተደረገባቸውን 155 የካታሎግ ግቤቶች ጨምሮ 329 አቅራቢዎችን ይመዘግባል
(ማረጋገጫ-የማይፈልጉ፣
የነፃ ደረጃ OAuth፣ ወይም የነፃ ደረጃ API ቁልፍ — የ
[ነፃ ደረጃዎች መመሪያ](../getting-started/FREE-TIERS-GUIDE.md) እና ሙሉውን
[የነፃ ደረጃዎች ማውጫ](../reference/FREE_TIERS.md) ይመልከቱ)። ችግሩ፦ የነፃ አቅራቢዎች የሞዴል ጥራት
እጅግ ይለያያል። የዘመኑን እጅግ የላቀ ሞዴል የሚያቀርብ ማረጋገጫ-የማይፈልግ አቅራቢ፣
አነስተኛ የቆየ ሞዴል ከሚያቀርብ አቅራቢ እጅግ የበለጠ ጠቃሚ ነው።
**የነፃ አቅራቢዎች ደረጃ** የእያንዳንዱን ነፃ አቅራቢ ካታሎግ ከ
**Arena AI የደረጃ ሰንጠረዥ** በተገኙ **በማኅበረሰብ የተሰበሰቡ የጥራት ውጤቶች** ጋር በማጣመር
"**ምርጡን ሞዴል የሚሰጠኝ የትኛው ነፃ አቅራቢ ነው?**" ለሚለው ጥያቄ መልስ ይሰጣል
(በሰው ምርጫ ላይ የተመሠረተ ELO፣ ከLMArena
የቻትቦት መወዳደሪያ ጀርባ ካለው ሐሳብ ጋር ተመሳሳይ)። ከዚያም አቅራቢዎቹ በ**ምርጥ ነፃ ሞዴላቸው** ጥንካሬ መሠረት ደረጃ ያገኛሉ።
ደረጃው የሚሰላው ከሦስት እውነተኛ ምንጮች ነው፦
1. የነፃ አቅራቢዎች ዝርዝሮች — `NOAUTH_PROVIDERS`፣ እንዲሁም `hasFree` ምልክት የተደረገባቸው `OAUTH_PROVIDERS` /
`APIKEY_PROVIDERS` ግቤቶች
(`src/shared/constants/providers.ts`)።
2. ከአቅራቢ መዝገቡ የተገኘው የእያንዳንዱ አቅራቢ የሞዴል ካታሎግ
(`open-sse/config/providerRegistry.ts`)።
3. በArena ELO ማመሳሰያ ሞተር (`src/lib/arenaEloSync.ts`) ውስጥ ባለው `model_intelligence` DB ሰንጠረዥ
የተከማቹ ከELO የተወሰዱ የተግባር-ተስማሚነት ውጤቶች።
የማጣመሪያው አመክንዮ `src/lib/freeProviderRankings.ts` ውስጥ ይገኛል።
---
## እንዴት መድረስ እንደሚቻል
### የዳሽቦርድ ገጽ
ዳሽቦርዱን ይክፈቱና ወደ **ወጪዎች → የነፃ አቅራቢዎች ደረጃ** ይሂዱ፣ ወይም በቀጥታ ወደዚህ ይሂዱ፦
```
/dashboard/free-provider-rankings
```
ገጹ (`src/app/(dashboard)/dashboard/free-provider-rankings/page.tsx`) የሚከተሉትን ያሳያል፦
- ደረጃቸው ከፍተኛ የሆኑትን ሦስት ነፃ አቅራቢዎች የሚያሳይ **ከፍተኛ-3 መድረክ** (🥇 🥈 🥉)።
- የሚከተሉት ዓምዶች ያሉት ሙሉ **የደረጃ ሰንጠረዥ**፦ **ደረጃ**፣ **አቅራቢ**፣ **ከፍተኛ ሞዴል**፣
**ውጤት**፣ **አማካይ ውጤት**፣ **ሞዴሎች**፣ **ዓይነት**።
- **የምድብ ማጣሪያ አዝራሮች**፦ _ሁሉም ምድቦች_፣ _ነባሪ_፣ _ኮድ መጻፍ_፣ _ግምገማ_፣
_ሰነድ ማዘጋጀት_፣ _ስህተት ማረም_።
የእያንዳንዱ አቅራቢ **ዓይነት** ባጅ አገልግሎቱ በምን መንገድ ነፃ እንደሆነ ያሳያል፦
| ባጅ | ትርጉም |
| -------- | ------------------------------------ |
| `NOAUTH` | ሁልጊዜ ነፃ፣ ምንም የመግቢያ ማረጋገጫ አያስፈልግም |
| `OAUTH` | ነፃ ደረጃ (`hasFree`) ያለው OAuth አቅራቢ |
| `APIKEY` | ነፃ ደረጃ (`hasFree`) ያለው የAPI ቁልፍ አቅራቢ |
ውጤቶች ከጥሬ ቁጥሮች ይልቅ ለሰው በሚገቡ መለያዎች (ለምሳሌ _እጅግ የላቀ_፣ _በጣም ጥሩ_፣ _እጅግ ጥሩ_፣
_ጥሩ_፣ _አማካይ_) ይታያሉ፤ ምክንያቱም መሠረታዊው እሴት መቶኛ ሳይሆን አንጻራዊ
የደረጃ ጥራት ነው።
### API መገናኛ
ገጹ በሕዝብ ሊደረስበት በሚችል የማንበብ መገናኛ
(`src/app/api/free-provider-rankings/route.ts`) የተደገፈ ነው፦
```
GET /api/free-provider-rankings
GET /api/free-provider-rankings?category=coding
GET /api/free-provider-rankings?category=coding&limit=20
```
የመጠይቅ መለኪያዎች (በZod የተረጋገጡ)፦
| መለኪያ | ዓይነት | ነባሪ | ማስታወሻዎች |
| ---------- | ------ | ----- | ------------------------------------------------------------------------------------ |
| `category` | string | (የለም) | ከ`default`፣ `coding`፣ `review`፣ `documentation`፣ `debugging` አንዱ። ለተዋሃደው ደረጃ አያካትቱት። |
| `limit` | number | `50` | በ`1–100` ክልል ውስጥ ይገደባል። |
የምላሽ ቅርጽ፦
```json
{
"rankings": [
{
"id": "<provider-id>",
"name": "<provider name>",
"icon": "<icon>",
"color": "<hex color>",
"textIcon": "<short label>",
"category": "noauth | oauth | apikey",
"topModel": {
"modelId": "<registry model id>",
"modelName": "<model display name>",
"score": 0.0,
"eloRaw": 0,
"confidence": "high | medium | low",
"category": "<task category>"
},
"averageScore": 0.0,
"modelCount": 0
}
]
}
```
`eloRaw` የመጀመሪያው የArena ELO እሴት ነው፤ `score` ደግሞ መደበኛ የተደረገው የተግባር-ተስማሚነት እሴት ነው
(ከታች ይመልከቱ)። ውጤት የተሰጣቸው ሞዴሎች የሌሏቸው አቅራቢዎች ከምላሹ ይቀራሉ።
---
## ውጤቶቹ እንዴት እንደሚሠሩ
### ምንጭ፦ Arena AI የደረጃ ሰንጠረዥ
የArena ELO ማመሳሰያ ሞተር (`src/lib/arenaEloSync.ts`) ሁለት የደረጃ ሰንጠረዦችን — `text`
እና `code` — ከArena AI የደረጃ ሰንጠረዥ API
(`https://api.wulong.dev/arena-ai-leaderboards/v1/leaderboard`) ያመጣል። እያንዳንዱ የደረጃ ሰንጠረዥ መዝገብ
የሞዴል ስም፣ አቅራቢ፣ የELO `score`፣ የመተማመኛ ክልል እና የድምፅ ብዛት ይይዛል።
የደረጃ ሰንጠረዥ ምድቦች ከOmniRoute የተግባር ምድቦች ጋር እንዲህ ይዛመዳሉ፦
| የArena ደረጃ ሰንጠረዥ | የOmniRoute ተግባር ምድቦች |
| ---------------- | ------------------------------------------------- |
| `text` | `default`, `review`, `documentation`, `debugging` |
| `code` | `coding` |
### መደበኛነት ማስያዝ (የተግባር ተስማሚነት ውጤት)
ጥሬ የELO ውጤቶች በየደረጃ ሰንጠረዡ ወደ **በ`[0.4, 0.98]` ውስጥ ያለ የተግባር ተስማሚነት እሴት** ይመጠናሉ፦
```
taskFit = 0.4 + 0.58 * ((elo - minElo) / (maxElo - minElo))
```
ውጤቱ ፈጽሞ `0` ወይም `1` አይደርስም፤ ይህም ለተጠቃሚ ማሻሻያዎች ተጨማሪ ክልል ይተዋል። ይህ በAPI ምላሽ ውስጥ የሚያዩት
የ`score` መስክ እና በዳሽቦርዱ ላይ የሚታየው መለያ ነው።
### የመተማመኛ ደረጃ
እያንዳንዱ መዝገብ በArena የድምፅ ብዛት ላይ ተመሥርቶ የመተማመኛ ደረጃ ያገኛል፦
| የመተማመኛ ደረጃ | ድምፆች |
| ---------- | ------- |
| `high` | ≥ 5,000 |
| `medium` | ≥ 1,000 |
| `low` | < 1,000 |
### ማከማቻ እና ወቅታዊነት
መጠናቸው የተስተካከለ መዝገቦች በ
`source = "arena_elo"` (`src/lib/db/modelIntelligence.ts`) ወደ `model_intelligence` የDB ሰንጠረዥ ይጻፋሉ። መዝገቦቹ **ከ
7 ቀናት በኋላ ጊዜያቸው ያልፋል**፤ ስለዚህ ማመሳሰል ያቆመ አቅራቢ ያረጀ ውሂብ ከማቅረብ ይልቅ
በመጨረሻ ከዝርዝሩ ይወጣል።
ማመሳሰሉ **በነባሪ እንዲሠራ የተደረገ ነው**፦
- አገልጋዩ ሲጀምር አንድ ጊዜ ይሠራል፤ ከዚያም በየተወሰነ ጊዜ ቆጣሪ ይደጋገማል
(`src/lib/arenaEloSync.ts`፣ ከ`src/instrumentation-node.ts` የተገናኘ)።
- እሱ **የማያግድ እና ፈጽሞ ወሳኝ ስህተት የማያስከትል** ነው — ከላይኛው ምንጭ ውሂብ ማምጣት ካልተሳካ፣ OmniRoute
መሥራቱን ይቀጥላል፤ የደረጃ ሰንጠረዦቹም የመጨረሻውን ትክክለኛ ውሂብ ብቻ ያሳያሉ (ወይም ባዶ ሁኔታ ያሳያሉ)።
ሁለት የአካባቢ ተለዋዋጮች ይቆጣጠሩታል (በ
[`docs/reference/ENVIRONMENT.md`](../reference/ENVIRONMENT.md) ውስጥ ተመዝግበዋል)፦
| ተለዋዋጭ | ነባሪ | ዓላማ |
| ------------------------- | ---------------- | ------------------------------------------ |
| `ARENA_ELO_SYNC_ENABLED` | `true` | ወደ ውጭ ከሚደረገው ማመሳሰል ለመውጣት ወደ `false` ያዘጋጁት። |
| `ARENA_ELO_SYNC_INTERVAL` | `86400` (24 ሰዓት) | የማመሳሰል ክፍተት፣ በሰከንድ። |
### በእጅ ማመሳሰል / ሁኔታ / ማጽዳት
ለኦፕሬተሮች፣ ማንነት ማረጋገጥ የሚጠይቅ የአስተዳደር መዳረሻ ነጥብ በእጅ መቆጣጠሪያ ያቀርባል
(`src/app/api/intelligence/sync/route.ts` — የአስተዳደር ማንነት ማረጋገጫ ያስፈልገዋል)፦
```
GET /api/intelligence/sync # የአሁኑ የማመሳሰል ሁኔታ (enabled, lastSync, nextSync, intervalMs)
POST /api/intelligence/sync # በእጅ ማመሳሰልን ያስጀምሩ፤ ሳይጻፍ ቅድመ ዕይታ ለማየት body: { "dryRun": true }
DELETE /api/intelligence/sync # ሁሉንም የተመሳሰሉ arena_elo የመረጃ መዝገቦች ያጽዱ
```
የደረጃ ገጹ ባዶ ከሆነ፣ በእጅ የሚደረግ `POST /api/intelligence/sync` (ወይም በቀላሉ
አገልጋዩን እንደገና ማስጀመር) እንደገና ውሂብ ይሞላበታል።
### ሞዴሎችን ከደረጃ ሰንጠረዡ ጋር ማዛመድ
የመዝገብ ሞዴል IDዎች እና የArena ሞዴል ስሞች ሁልጊዜ በትክክል አይዛመዱም። የደረጃ አሰጣጡ
ተለዋዋጭ ማዛመድን ይጠቀማል (`findMatchingIntelligence` በ`src/lib/freeProviderRankings.ts` ውስጥ)፦
1. መደበኛ በተደረገው የሞዴል ID ላይ ትክክለኛ ማዛመድ።
2. በመጨረሻ ያለውን የስሪት ቅጥያ ካስወገዱ በኋላ ማዛመድ (ለምሳሌ `kimi-k2.6` → `kimi-k2`)።
3. በቅድመ ቅጥያ ማዛመድ (የደረጃ ሰንጠረዡ የሞዴል ስም የመዝገቡ ID ቅድመ ቅጥያ ሲሆን)።
በማመሳሰሉ በኩል፣ የታወቁ የአቅራቢ ቅድመ ቅጥያዎች (`anthropic/`, `openai/`, `google/`, …)
ይወገዳሉ፤ እንዲሁም አነስተኛ የተለዋጭ ስም ካርታ መደበኛ ስሞችን OmniRoute በውስጥ ወደሚጠቀምባቸው
ልዩነቶች ያስፋፋል፤ ስለዚህ ሞዴሎች በማንኛውም ስም ሊገኙ ይችላሉ።
### አንድ አቅራቢ እንዴት ደረጃ እንደሚሰጠው
ለእያንዳንዱ ነፃ አቅራቢ፣ ሞተሩ በካታሎጉ ውስጥ ላለ እያንዳንዱ ሞዴል ውጤት ይሰጣል፤ ከዚያም፦
- **ከፍተኛው ሞዴል** = ከአቅራቢው ሞዴሎች ከፍተኛውን ውጤት ያገኘው።
- **አማካይ ውጤት** = ውጤት በተሰጣቸው የአቅራቢው ሞዴሎች ሁሉ ላይ ያለው አማካይ ውጤት።
- **ሞዴሎች** = ከአቅራቢው ሞዴሎች የArena ውጤት የነበራቸው ብዛት።
አቅራቢዎች መጀመሪያ በ**ከፍተኛው ሞዴል ውጤት**፣ ከዚያም በአማካይ ውጤት ይደረደራሉ። ይህ ቢያንስ አንድ
ጠንካራ ነፃ ሞዴል የሚያቀርብ አቅራቢን ይሸልማል።
---
## ነፃ አቅራቢዎችን ለመምረጥ አጠቃቀሙ
1. **ትክክለኛውን ምድብ ይምረጡ።** ለወኪል-ተኮር/የኮድ የሥራ ጫናዎች **ኮድ ማድረግ** ማጣሪያን ይጠቀሙ፤ ወይም
ለአጠቃላይ ውይይት **ሁሉም ምድቦች** / **ነባሪ** ላይ ይተዉት። የእያንዳንዱ የደረጃ ሰንጠረዥ ከፍተኛ ሞዴል
የተለያየ ስለሆነ፣ ተመሳሳዩ አቅራቢ በተለያዩ ምድቦች የተለያየ
ደረጃ ሊያገኝ ይችላል።
2. **ለአንድ ጊዜ ማዋቀሮች የመድረኩን ከፍተኛ ደረጃዎች ይምረጡ።** አንድ ወይም ሁለት ነፃ
አቅራቢዎችን ብቻ ማገናኘት ከፈለጉ፣ በምድብዎ ከፍተኛ ደረጃ ካላቸው ይጀምሩ።
3. **የዓይነት ባጁን ያረጋግጡ።** `NOAUTH` አቅራቢዎች ለማገናኘት ፈጣኖቹ ናቸው (ምንም
የመግቢያ ማረጋገጫ አያስፈልግም)። የ`OAUTH` / `APIKEY` ነፃ ደረጃዎች ፈጣን ምዝገባ ያስፈልጋቸዋል፣ ነገር ግን ብዙውን ጊዜ
ይበልጥ ኃይለኛ ሞዴሎችን ያቀርባሉ። ስለ ግንኙነት ደረጃዎች [የነፃ ደረጃዎች መመሪያ](../getting-started/FREE-TIERS-GUIDE.md)ን
ይመልከቱ።
4. **በርካታ አቅራቢዎችን ያገናኙና Auto-Combo እንዲወስን ያድርጉ።** ይህን ገጽ
የሚያንቀሳቅሰው ተመሳሳይ የArena ELO ውሂብ የAuto-Combo የውጤት አሰጣጥ ሞተርን
**የተግባር ተስማሚነት ምክንያት**ም ይመግባል
(`open-sse/services/autoCombo/taskFitness.ts`፣ የመፍትሔ ቅደም ተከተል
`user_override → arena_elo → models_dev_tier → static table`)። ስለዚህ ከፍተኛ ደረጃ ያላቸውን
ነፃ አቅራቢዎች ካገናኙ በኋላ፣ `model: "auto"`ን (ለምሳሌ `auto/coding`) በመጠቀም ማዘዋወር
በእያንዳንዱ ጥያቄ ከፍተኛ ጥራት ያላቸውን ነፃ ሞዴሎች በራስ-ሰር ይመርጣል።
ሙሉውን የ16 ምክንያቶች ውጤት አሰጣጥ ለማየት [Auto-Combo](../routing/AUTO-COMBO.md)ን ይመልከቱ።
---
## ተዛማጅ ሰነዶች
- [የነፃ ደረጃዎች መመሪያ](../getting-started/FREE-TIERS-GUIDE.md) — ነፃ
አቅራቢዎችን ያለ ክሬዲት ካርድ እንዴት ማገናኘት እንደሚቻል።
- [የነፃ ደረጃዎች ማውጫ](../reference/FREE_TIERS.md) — የነፃ አቅራቢዎችና
ገደቦቻቸው ሙሉ ዝርዝር።
- [Auto-Combo](../routing/AUTO-COMBO.md) — ተመሳሳዩን የArena ELO የተግባር ተስማሚነት ውሂብ
የሚጠቀመው ባለ16 ምክንያቶች የማዘዋወር ሞተር።
- [የአካባቢ ተለዋዋጮች](../reference/ENVIRONMENT.md) — የ`ARENA_ELO_SYNC_ENABLED` /
`ARENA_ELO_SYNC_INTERVAL` ማጣቀሻ።

198
docs/i18n/am/docs/guides/KIRO_SETUP.md Normal file
View File

@@ -0,0 +1,198 @@
# Kiro Setup Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/KIRO_SETUP.md) · 🇸🇦 [ar](../../../ar/docs/guides/KIRO_SETUP.md) · 🇦🇿 [az](../../../az/docs/guides/KIRO_SETUP.md) · 🇧🇬 [bg](../../../bg/docs/guides/KIRO_SETUP.md) · 🇧🇩 [bn](../../../bn/docs/guides/KIRO_SETUP.md) · 🇨🇿 [cs](../../../cs/docs/guides/KIRO_SETUP.md) · 🇩🇰 [da](../../../da/docs/guides/KIRO_SETUP.md) · 🇩🇪 [de](../../../de/docs/guides/KIRO_SETUP.md) · 🇬🇷 [el](../../../el/docs/guides/KIRO_SETUP.md) · 🇪🇸 [es](../../../es/docs/guides/KIRO_SETUP.md) · 🇪🇪 [et](../../../et/docs/guides/KIRO_SETUP.md) · 🇮🇷 [fa](../../../fa/docs/guides/KIRO_SETUP.md) · 🇫🇮 [fi](../../../fi/docs/guides/KIRO_SETUP.md) · 🇫🇷 [fr](../../../fr/docs/guides/KIRO_SETUP.md) · 🇮🇪 [ga](../../../ga/docs/guides/KIRO_SETUP.md) · 🇮🇳 [gu](../../../gu/docs/guides/KIRO_SETUP.md) · 🇳🇬 [ha](../../../ha/docs/guides/KIRO_SETUP.md) · 🇮🇱 [he](../../../he/docs/guides/KIRO_SETUP.md) · 🇮🇳 [hi](../../../hi/docs/guides/KIRO_SETUP.md) · 🇭🇷 [hr](../../../hr/docs/guides/KIRO_SETUP.md) · 🇭🇺 [hu](../../../hu/docs/guides/KIRO_SETUP.md) · 🇦🇲 [hy](../../../hy/docs/guides/KIRO_SETUP.md) · 🇮🇩 [id](../../../id/docs/guides/KIRO_SETUP.md) · 🇳🇬 [ig](../../../ig/docs/guides/KIRO_SETUP.md) · 🇮🇹 [it](../../../it/docs/guides/KIRO_SETUP.md) · 🇯🇵 [ja](../../../ja/docs/guides/KIRO_SETUP.md) · 🇬🇪 [ka](../../../ka/docs/guides/KIRO_SETUP.md) · 🇰🇭 [km](../../../km/docs/guides/KIRO_SETUP.md) · 🇮🇳 [kn](../../../kn/docs/guides/KIRO_SETUP.md) · 🇰🇷 [ko](../../../ko/docs/guides/KIRO_SETUP.md) · 🇱🇹 [lt](../../../lt/docs/guides/KIRO_SETUP.md) · 🇱🇻 [lv](../../../lv/docs/guides/KIRO_SETUP.md) · 🇮🇳 [ml](../../../ml/docs/guides/KIRO_SETUP.md) · 🇮🇳 [mr](../../../mr/docs/guides/KIRO_SETUP.md) · 🇲🇾 [ms](../../../ms/docs/guides/KIRO_SETUP.md) · 🇲🇹 [mt](../../../mt/docs/guides/KIRO_SETUP.md) · 🇲🇲 [my](../../../my/docs/guides/KIRO_SETUP.md) · 🇳🇵 [ne](../../../ne/docs/guides/KIRO_SETUP.md) · 🇳🇱 [nl](../../../nl/docs/guides/KIRO_SETUP.md) · 🇳🇴 [no](../../../no/docs/guides/KIRO_SETUP.md) · 🇮🇳 [or](../../../or/docs/guides/KIRO_SETUP.md) · 🇮🇳 [pa](../../../pa/docs/guides/KIRO_SETUP.md) · 🇵🇭 [phi](../../../phi/docs/guides/KIRO_SETUP.md) · 🇵🇱 [pl](../../../pl/docs/guides/KIRO_SETUP.md) · 🇵🇹 [pt](../../../pt/docs/guides/KIRO_SETUP.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/KIRO_SETUP.md) · 🇷🇴 [ro](../../../ro/docs/guides/KIRO_SETUP.md) · 🇷🇺 [ru](../../../ru/docs/guides/KIRO_SETUP.md) · 🇱🇰 [si](../../../si/docs/guides/KIRO_SETUP.md) · 🇸🇰 [sk](../../../sk/docs/guides/KIRO_SETUP.md) · 🇸🇮 [sl](../../../sl/docs/guides/KIRO_SETUP.md) · 🇷🇸 [sr](../../../sr/docs/guides/KIRO_SETUP.md) · 🇸🇪 [sv](../../../sv/docs/guides/KIRO_SETUP.md) · 🇰🇪 [sw](../../../sw/docs/guides/KIRO_SETUP.md) · 🇮🇳 [ta](../../../ta/docs/guides/KIRO_SETUP.md) · 🇮🇳 [te](../../../te/docs/guides/KIRO_SETUP.md) · 🇹🇭 [th](../../../th/docs/guides/KIRO_SETUP.md) · 🇹🇷 [tr](../../../tr/docs/guides/KIRO_SETUP.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/KIRO_SETUP.md) · 🇵🇰 [ur](../../../ur/docs/guides/KIRO_SETUP.md) · 🇺🇿 [uz](../../../uz/docs/guides/KIRO_SETUP.md) · 🇻🇳 [vi](../../../vi/docs/guides/KIRO_SETUP.md) · 🇳🇬 [yo](../../../yo/docs/guides/KIRO_SETUP.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/KIRO_SETUP.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/KIRO_SETUP.md)
---
ይህ መመሪያ Kiro (በAWS የሚስተናገድ AI የኮድ ረዳት) መለያዎችን ወደ OmniRoute ማከልን፣
በክፍለ-ጊዜ ግጭት ሳይኖር በርካታ መለያዎችን በአንድ ጊዜ ማስኬድ ላይ በማተኮር ይሸፍናል።
---
## ዳራ፦ የKiro መለያዎች ለምን ሊጋጩ ይችላሉ
የKiro የጀርባ ስርዓት ንቁ ክፍለ-ጊዜዎችን ለመከታተል የAWS SSO OIDC ደንበኛ ምዝገባዎችን ይጠቀማል።
ወሳኙ ገደብ፦ **እያንዳንዱ የOIDC ደንበኛ ምዝገባ በአንድ ጊዜ አንድ ንቁ
ክፍለ-ጊዜ ብቻ ይደግፋል**። ሁለተኛ መሣሪያ ወይም ተጠቃሚ በተመሳሳይ
የተመዘገበ ደንበኛ ሲረጋገጥ፣ የጀርባ ስርዓቱ የመጀመሪያውን መለያ የማደሻ ቶከን ውድቅ ያደርገዋል።
ይህ፣ ሌላ የKiro መለያ አስቀድሞ በገባበት ማሽን ላይ `kiro-cli login` ሲያስኬዱ
ችግር የሚፈጥረው ያው ዘዴ ነው — አዲሱ መግቢያ የመጀመሪያውን
መለያ ቶከን ይሽራል።
---
## OmniRoute ይህን እንዴት እንደሚፈታው (v3.8.0+)
ከv3.8.0 ጀምሮ፣ OmniRoute በእያንዳንዱ የKiro ግንኙነት ማስመጣት ወቅት
`registerClient()` (AWS SSO OIDC) ይጠራል። ይህ ለእያንዳንዱ የOmniRoute ግንኙነት የራሱን የተወሰነ የOIDC
ደንበኛ ምዝገባ ይሰጣል። እያንዳንዱ የደንበኛ ምዝገባ ራሱን የቻለ ስለሆነ፣ አንድ መለያን ማደስ ወይም
እንደገና ማረጋገጥ በማንኛውም ሌላ መለያ የማደሻ ቶከን ላይ ተጽዕኖ አያሳድርም።
ማግለሉ በማደሻ-ቶከን ማስመጣት ዘዴዎች ላይ የሚተገበር ሲሆን፣ የAPI-ቁልፍ ማረጋገጫ
የOIDC ማደሻ ክፍለ-ጊዜዎችን ሙሉ በሙሉ ያስወግዳል፦
| የማስመጣት ዘዴ | የማግለል ሁኔታ |
| --------------------------------------- | --------------------------------------------------------------------------- |
| AWS Builder ID / IDC የመሣሪያ-ኮድ ፍሰት | የመሣሪያ-ኮድ ፍሰቱ ከተዋወቀ ጀምሮ የተገለለ |
| **ቶከን አስመጣ** (የማደሻ ቶከንን በእጅ መለጠፍ) | ከv3.8.0 ጀምሮ የተገለለ |
| **የGoogle / GitHub ማኅበራዊ መግቢያ** | ከv3.8.0 ጀምሮ የተገለለ |
| **ራስ-ሰር ማስመጣት** (kiro-cli SQLite) | ከv3.8.0 ጀምሮ የተገለለ (የSQLite ዱካ አስቀድሞ የተገለለ ነበር፤ የSSO-መሸጎጫ ተተኪ አሁን ደግሞ ተገልሏል) |
| **API ቁልፍ** (የረጅም ጊዜ CodeWhisperer ቁልፍ) | የማደሻ ክፍለ-ጊዜ የለም፤ ቁልፉ ተረጋግጦ እንደ ተሸካሚ ማረጋገጫ ይከማቻል |
---
## ከv3.8.0 በፊት ለተፈጠሩ ግንኙነቶች የሽግግር ማስታወሻ
ከv3.8.0 በፊት የገቡ ግንኙነቶች በ`providerSpecificData` ውስጥ የተከማቸ
የተወሰነ የOIDC ደንበኛ ምዝገባ የላቸውም። እነዚህ ግንኙነቶች መስራታቸውን ይቀጥላሉ፣ ነገር ግን የጋራ
የማኅበራዊ-ማረጋገጫ ማደሻ መዳረሻን ይጠቀማሉ፤ ይህም ማለት እንዲህ ያሉ ሁለት ግንኙነቶች አሁንም እርስ በርሳቸውን
ውድቅ ሊያደርጉ ይችላሉ።
**ማግለልን ለማግኘት፦** የድሮውን ግንኙነት ከ**ዳሽቦርድ → አቅራቢዎች** ይሰርዙ እና
ከሚደገፉት የማስመጣት ፍሰቶች ማንኛውንም በመጠቀም እንደገና ያስመጡት። ሁሉም አዲስ የተፈጠሩ ግንኙነቶች
የራሳቸውን የደንበኛ ምዝገባ በራስ-ሰር ያገኛሉ።
---
## ሁለት የKiro መለያዎችን ጎን ለጎን ማከል
### ቅድመ ሁኔታዎች
- OmniRoute v3.8.0 ወይም ከዚያ በኋላ።
- የሚሰራ የKiro መለያ (ኢሜይል + የይለፍ ቃል፣ Google፣ ወይም GitHub መግቢያ)።
- እንደ አማራጭ ሁለተኛ የKiro መለያ።
### ደረጃ 1፦ የመጀመሪያውን መለያ ያስመጡ
1. **ዳሽቦርድ → አቅራቢዎች → አቅራቢ አክል → Kiro** ይክፈቱ።
2. ከሚከተሉት አንዱን ይምረጡ፦
- **ቶከን አስመጣ** — በ`aorAAAAAG` የሚጀምር የማደሻ ቶከን ይለጥፉ።
- **API ቁልፍ** — የረጅም ጊዜ የKiro / CodeWhisperer API ቁልፍ ይለጥፉ።
- **የGoogle / GitHub መግቢያ** — የOAuth ፍሰቱን በአሳሹ ውስጥ ያጠናቅቁ።
- **ራስ-ሰር ማስመጣት** — አዝራሩን ጠቅ ያድርጉ፤ OmniRoute ማረጋገጫዎችን ከአካባቢያዊው
የkiro-cli የውሂብ ጎታ ወይም `~/.aws/sso/cache` ያነባል።
3. ግንኙነቱ ይቀመጣል። የማደሻ-ቶከን ፍሰቶች የተወሰነ
የOIDC ደንበኛን በራስ-ሰር ይመዘግባሉ። የAPI-ቁልፍ ፍሰቶች ቁልፉን በAWS ያረጋግጣሉ እና የማደሻ ቶከን አያከማቹም።
### ደረጃ 2፦ ሁለተኛውን መለያ ያስመጡ
ለሁለተኛው መለያ ደረጃ 1ን ይድገሙ። እያንዳንዱ ማስመጣት የተለየ የOIDC
ደንበኛ ምዝገባ ስለሚፈጥር፣ ሁለቱ ግንኙነቶች ሙሉ በሙሉ የተገለሉ ናቸው።
### ደረጃ 3፦ ሁለቱም ግንኙነቶች ንቁ መሆናቸውን ያረጋግጡ
1. **ዳሽቦርድ → አቅራቢዎች** — ሁለቱም የKiro ግንኙነቶች **ንቁ** ሁኔታን ማሳየት አለባቸው።
2. **ዳሽቦርድ → ጤና** — ሁለቱም ግንኙነቶች የቶከን ጤና ፍተሻቸውን ማለፍ አለባቸው።
### ደረጃ 4፦ በመለያዎቹ መካከል ለማስተላለፍ ጥምረት ይጠቀሙ
ጭነትን ለማመጣጠን ወይም በአንዱ ላይ ችግር ሲኖር ወደ ሌላው ለመሸጋገር፣ ሁለቱንም ግንኙነቶች እንደ ዒላማ ያካተተ ጥምረት ይፍጠሩ፦
```
kiro/kiro-dev → kiro/kiro-pro
```
ለጥምረት ውቅር [FEATURES.md](./FEATURES.md) እና የማስተላለፊያ ሰነዶችን ይመልከቱ።
---
## የድርጅት / IDC ተጠቃሚዎች
ለAWS IAM Identity Center (IDC) መለያዎች፣ በ**Dashboard → Providers → Kiro → Device Code** ውስጥ ያለውን **AWS Builder ID / IDC device-code**
ፍሰት ይጠቀሙ። የdevice-code ፍሰቱ ሁልጊዜም ሙሉ በሙሉ የተነጠለ ነው። ለእነዚህ ግንኙነቶች እንደገና ማስመጣት አያስፈልግም።
ነባሪ ባልሆነ AWS ክልል ውስጥ የሚሰሩ የድርጅት ተጠቃሚዎች፣ በImport Token API በኩል
ሲያስመጡ ክልሉን መግለጽ ይችላሉ፦
```bash
curl -X POST http://localhost:20128/api/oauth/kiro/import \
-H "Content-Type: application/json" \
-d '{"refreshToken": "aorAAAAAG...", "region": "eu-west-1"}'
```
የ`region` መስክ ካልተገለጸ ነባሪው `us-east-1` ነው።
---
## የAPI ቁልፍ ማስመጣት ፍሰት
የAPI ቁልፍ ማረጋገጫ ለረጅም ጊዜ የሚያገለግሉ Kiro / AWS CodeWhisperer bearer ምስክርነቶች ነው።
የOAuth እድሳትን አይጠቀምም፣ ስለዚህ የጋራ OIDC ክፍለ-ጊዜ ዋጋ መሰረዝን ያስወግዳል።
### Dashboard
1. **Dashboard -> Providers -> Kiro**ን ይክፈቱ።
2. **API Key**ን ይምረጡ።
3. የAPI ቁልፉን እና አማራጭ የAWS ክልልን ይለጥፉ (በነባሪ `us-east-1`)።
4. OmniRoute ቁልፉን ያረጋግጣል እና ግንኙነቱን ያስቀምጣል።
### API
```bash
curl -X POST http://localhost:20128/api/oauth/kiro/api-key \
-H "Content-Type: application/json" \
-d '{"apiKey": "kiro_or_codewhisperer_key", "region": "us-east-1"}'
```
### ውስጣዊ ውል
የAPI መስመሩ `KiroService.validateApiKey()`ን በመጥራት ቁልፉን ያረጋግጣል፤ ይህም
ከክልሉ ጋር በሚዛመደው CodeWhisperer/Amazon Q endpoint ላይ `ListAvailableProfiles`ን በመጠቀም `profileArn`ን ይፈታል።
የተቀመጠው ግንኙነት የሚከተለውን ይጠቀማል፦
```json
{
"authType": "apikey",
"providerSpecificData": {
"authMethod": "api_key",
"region": "us-east-1",
"profileArn": "arn:aws:codewhisperer:..."
}
}
```
በruntime ጊዜ፣ `KiroExecutor.buildHeaders()` ቁልፉን እንደ
`Authorization: Bearer <key>` ይልካል እና `tokentype: API_KEY`ን ይጨምራል። የኮታ/መገለጫ ጥሪዎች
ተመሳሳዩን ምልክት ይጠቀማሉ፤ በዚህም AWS bearer-ን እንደ OIDC ወይም የማህበራዊ መዳረሻ token ሳይሆን
እንደ ረጅም ጊዜ የሚያገለግል API ቁልፍ ይቆጥረዋል።
---
## የOIDC ደንበኛ ጊዜ ማብቃት
የAWS SSO OIDC የሕዝብ ደንበኞች በአብዛኛው ከ90 ቀናት በኋላ ጊዜያቸው ያበቃል
(`clientSecretExpiresAt`)። OmniRoute ይህን የጊዜ ማህተም ለታዛቢነት በ`providerSpecificData`
ውስጥ ያከማቻል። አንድ ግንኙነት ከ~90 ቀናት በኋላ መታደስ ካቆመ፣
አዲስ የOIDC ደንበኛ ምዝገባ ለማግኘት ግንኙነቱን እንደገና ያስመጡ። ጊዜው ሲያበቃ በራስ-ሰር እንደገና መመዝገብ
እንደ ወደፊት ማሻሻያ ተመዝግቧል።
የAPI ቁልፍ ግንኙነቶች በAWS SSO OIDC በኩል ስለማይታደሱ፣
የOIDC ደንበኛ ጊዜ ማብቂያ የላቸውም።
---
## መላ ፍለጋ
### ሁለተኛው መለያ በተደጋጋሚ ከስርዓቱ ይወጣል
- ሁለቱንም ግንኙነቶች በ**Dashboard → Providers** ውስጥ ይፈትሹ እና እያንዳንዳቸው በጥሬ JSON ውስጥ null ያልሆነ
`clientId` እንደሚያሳዩ ያረጋግጡ (በመረጃ አዶው በኩል ይታያል)። ከግንኙነቶቹ አንዱ `clientId` ከሌለው፣
ከv3.8.0 በፊት የገባ ነው — እንደገና ያስመጡት።
### ማስመጣት በ"Token validation failed" ይከሽፋል
- የrefresh token በ`aorAAAAAG` መጀመሩን ያረጋግጡ።
- OmniRoute ወደ `https://oidc.us-east-1.amazonaws.com` (ወይም ወደ ተዋቀረው
ክልል) መድረስ መቻሉን ያረጋግጡ። ከድርጅት proxy ጀርባ ከሆኑ፣
በ**Dashboard → Settings → Proxies** ውስጥ የprovider ደረጃ proxy ያቀናብሩ።
### የAPI ቁልፍ ማስመጣት ይከሽፋል
- ቁልፉ የKiro / CodeWhisperer API ቁልፍ እንጂ refresh token አለመሆኑን ያረጋግጡ።
- የAWS ክልሉ ከቁልፉ/መለያው ጋር መዛመዱን ያረጋግጡ። `us-east-1` ነባሪው ነው።
- ቁልፉ `ListAvailableProfiles`ን መጥራት መቻል አለበት፤ አለበለዚያ OmniRoute
አስፈላጊውን `profileArn` መፍታት አይችልም።
ለሌሎች ችግሮች፣ ዋናውን [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) ይመልከቱ።

154
docs/i18n/am/docs/guides/MANAGEMENT-AUTH.md Normal file
View File

@@ -0,0 +1,154 @@
# Management Authentication (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/MANAGEMENT-AUTH.md) · 🇸🇦 [ar](../../../ar/docs/guides/MANAGEMENT-AUTH.md) · 🇦🇿 [az](../../../az/docs/guides/MANAGEMENT-AUTH.md) · 🇧🇬 [bg](../../../bg/docs/guides/MANAGEMENT-AUTH.md) · 🇧🇩 [bn](../../../bn/docs/guides/MANAGEMENT-AUTH.md) · 🇨🇿 [cs](../../../cs/docs/guides/MANAGEMENT-AUTH.md) · 🇩🇰 [da](../../../da/docs/guides/MANAGEMENT-AUTH.md) · 🇩🇪 [de](../../../de/docs/guides/MANAGEMENT-AUTH.md) · 🇬🇷 [el](../../../el/docs/guides/MANAGEMENT-AUTH.md) · 🇪🇸 [es](../../../es/docs/guides/MANAGEMENT-AUTH.md) · 🇪🇪 [et](../../../et/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇷 [fa](../../../fa/docs/guides/MANAGEMENT-AUTH.md) · 🇫🇮 [fi](../../../fi/docs/guides/MANAGEMENT-AUTH.md) · 🇫🇷 [fr](../../../fr/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇪 [ga](../../../ga/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [gu](../../../gu/docs/guides/MANAGEMENT-AUTH.md) · 🇳🇬 [ha](../../../ha/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇱 [he](../../../he/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [hi](../../../hi/docs/guides/MANAGEMENT-AUTH.md) · 🇭🇷 [hr](../../../hr/docs/guides/MANAGEMENT-AUTH.md) · 🇭🇺 [hu](../../../hu/docs/guides/MANAGEMENT-AUTH.md) · 🇦🇲 [hy](../../../hy/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇩 [id](../../../id/docs/guides/MANAGEMENT-AUTH.md) · 🇳🇬 [ig](../../../ig/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇹 [it](../../../it/docs/guides/MANAGEMENT-AUTH.md) · 🇯🇵 [ja](../../../ja/docs/guides/MANAGEMENT-AUTH.md) · 🇬🇪 [ka](../../../ka/docs/guides/MANAGEMENT-AUTH.md) · 🇰🇭 [km](../../../km/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [kn](../../../kn/docs/guides/MANAGEMENT-AUTH.md) · 🇰🇷 [ko](../../../ko/docs/guides/MANAGEMENT-AUTH.md) · 🇱🇹 [lt](../../../lt/docs/guides/MANAGEMENT-AUTH.md) · 🇱🇻 [lv](../../../lv/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [ml](../../../ml/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [mr](../../../mr/docs/guides/MANAGEMENT-AUTH.md) · 🇲🇾 [ms](../../../ms/docs/guides/MANAGEMENT-AUTH.md) · 🇲🇹 [mt](../../../mt/docs/guides/MANAGEMENT-AUTH.md) · 🇲🇲 [my](../../../my/docs/guides/MANAGEMENT-AUTH.md) · 🇳🇵 [ne](../../../ne/docs/guides/MANAGEMENT-AUTH.md) · 🇳🇱 [nl](../../../nl/docs/guides/MANAGEMENT-AUTH.md) · 🇳🇴 [no](../../../no/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [or](../../../or/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [pa](../../../pa/docs/guides/MANAGEMENT-AUTH.md) · 🇵🇭 [phi](../../../phi/docs/guides/MANAGEMENT-AUTH.md) · 🇵🇱 [pl](../../../pl/docs/guides/MANAGEMENT-AUTH.md) · 🇵🇹 [pt](../../../pt/docs/guides/MANAGEMENT-AUTH.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/MANAGEMENT-AUTH.md) · 🇷🇴 [ro](../../../ro/docs/guides/MANAGEMENT-AUTH.md) · 🇷🇺 [ru](../../../ru/docs/guides/MANAGEMENT-AUTH.md) · 🇱🇰 [si](../../../si/docs/guides/MANAGEMENT-AUTH.md) · 🇸🇰 [sk](../../../sk/docs/guides/MANAGEMENT-AUTH.md) · 🇸🇮 [sl](../../../sl/docs/guides/MANAGEMENT-AUTH.md) · 🇷🇸 [sr](../../../sr/docs/guides/MANAGEMENT-AUTH.md) · 🇸🇪 [sv](../../../sv/docs/guides/MANAGEMENT-AUTH.md) · 🇰🇪 [sw](../../../sw/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [ta](../../../ta/docs/guides/MANAGEMENT-AUTH.md) · 🇮🇳 [te](../../../te/docs/guides/MANAGEMENT-AUTH.md) · 🇹🇭 [th](../../../th/docs/guides/MANAGEMENT-AUTH.md) · 🇹🇷 [tr](../../../tr/docs/guides/MANAGEMENT-AUTH.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/MANAGEMENT-AUTH.md) · 🇵🇰 [ur](../../../ur/docs/guides/MANAGEMENT-AUTH.md) · 🇺🇿 [uz](../../../uz/docs/guides/MANAGEMENT-AUTH.md) · 🇻🇳 [vi](../../../vi/docs/guides/MANAGEMENT-AUTH.md) · 🇳🇬 [yo](../../../yo/docs/guides/MANAGEMENT-AUTH.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/MANAGEMENT-AUTH.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/MANAGEMENT-AUTH.md)
---
OmniRoute የአስተዳደር መስመሮችን ለመፍቀድ **አራት የማረጋገጫ መረጃ ቤተሰቦች** አሉት።
እርስ በርሳቸው የሚተካኩ አይደሉም። የInference API ቁልፎች (`sk-…`) በግልጽ `manage` ወይም `admin` ወሰን ካልተሰጣቸው በስተቀር አገልጋዩን **አያስተዳድሩም**።
መደበኛ ትግበራ፦ `src/lib/api/requireManagementAuth.ts`።
| የማረጋገጫ መረጃ | የተለመደ ቅርጽ | የሚፈጠርበት ቦታ | የታሰበለት አጠቃቀም | የአስተዳደር ችሎታ |
| -------------------- | ---------------------------------- | ---------------------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
| የዳሽቦርድ JWT ክፍለ ጊዜ | `auth_token` ኩኪ | የዳሽቦርድ መግቢያ | የአሳሽ UI | ለCSRF፣ ለአካባቢያዊነት እና ሁልጊዜ ጥበቃ ለሚደረግላቸው መስመሮች ደንቦች ተገዢ የሆነ ሙሉ የዳሽቦርድ አስተዳደር |
| የCLI machine-id ቶከን | ውስጣዊ / አካባቢያዊ | የCLI ማስነሻ (`omniroute` በተመሳሳይ ማሽን ላይ) | አካባቢያዊ CLI | አካባቢያዊ አስተዳደር ብቻ |
| ወሰን ያለው Access Token | `oma_live_…` | **ቅንብሮች → የመዳረሻ ቶከኖች** ወይም `omniroute connect` | የርቀት CLI እና የአስተዳደር API | መስመሩ የሚፈልገውን `read`፣ `write` ወይም `admin` ወሰን ማሟላት አለበት |
| የInference API ቁልፍ | `sk-…` (እና ሌሎች የAPI ቁልፍ ቅድመ ቅጥያዎች) | **API Manager / API ቁልፎች** | `/v1/*` inference | የቁልፉ ሜታዳታ `manage` ወይም `admin`ን ካላካተተ በስተቀር **ምንም** |
`oma_` የማረጋገጫ መረጃዎች የአስተዳደር/CLI ማረጋገጫዎች ናቸው። የInference API ቁልፎች **አይደሉም**።
ለአገልጋዩ የመግቢያ/API-ቁልፍ ማረጋገጫ ከተሰናከለ፣ አንዳንድ የአስተዳደር መስመሮች
ያልተረጋገጡ ጥሪዎችን ሊቀበሉ ይችላሉ። አካባቢያዊ-ብቻ እና ሁልጊዜ ጥበቃ የሚደረግላቸው መስመሮች አሁንም
የራሳቸውን ደንቦች ይተገብራሉ። ስለዚህ ከእነዚህ የማረጋገጫ መረጃዎች አንዱን ማቅረብ በሁሉም ሁኔታ
ግዴታ አይደለም፤ እንዲሁም የሚፈለገው ወሰን እና የመስመሩ አካባቢያዊነት ሳይሟሉ አንዱን መያዝ በሁሉም ሁኔታ በቂ አይደለም።
ተዛማጅ፦ [የርቀት ሁነታ](./REMOTE-MODE.md) (`oma_live_…` ለርቀት CLI እንዴት እንደሚፈጠር)።
---
## የወሰን ማትሪክሶች
እነዚህ ሁለት የወሰን ቃላት ስብስቦች **የተለያዩ** ናቸው። አትቀላቅሏቸው።
### የAccess Token ወሰኖች (`oma_live_…`)
| ወሰን | የተለመዱ ክንውኖች |
| ------- | ------------------------------------------------------ |
| `read` | ቶከኑ እንዲያያቸው የተፈቀደለትን ዝርዝር/ሁኔታ GETዎች |
| `write` | ከadmin በታች ያሉ ለውጦች (መፍጠር/ማዘመን/መሰረዝ) |
| `admin` | ሙሉ የርቀት CLI / የግንኙነት ቶከን (የይለፍ ቃል ማስነሻ በነባሪ ይህን ይጠቀማል) |
`read` ያለው ቶከን `write` መስመርን መጥራት አይችልም። የሩጫ ጊዜ መልዕክት ቅርጽ፦
`Access token scope '<have>' is insufficient; '<need>' required.`
### የAPI-ቁልፍ አስተዳደር ወሰኖች
| ወሰን | ትርጉም |
| -------- | ------------------------------------------------------------------- |
| (ምንም) | Inference ብቻ። የአስተዳደር መስመሮች 403 ይመልሳሉ። |
| `manage` | የአስተዳደር API (ከ`requireManagementAuth` የAPI-ቁልፍ ቅርንጫፍ ጋር ተመሳሳይ መግቢያ) |
| `admin` | `hasManageScope`ንም ያሟላል (የአስተዳደር ችሎታ እንዳለው ይቆጠራል) |
በAPI ቁልፎች / API Manager UI ውስጥ ለቁልፉ `manage`ን አንቃ። ያንን ወሰን ሆን ብለህ ካልሰጠኸው በስተቀር የውይይት ደንበኛ ቁልፍን ለአውቶሜሽን ዳግም አትጠቀም።
---
## እንዴት መፍጠር እና መሻር እንደሚቻል
### የዳሽቦርድ JWT ክፍለ ጊዜ
1. `/login`ን ክፈትና በአስተዳደር የይለፍ ቃል (በመጀመሪያው ማስነሻ `INITIAL_PASSWORD`) ግባ።
2. `auth_token` ኩኪው HttpOnly ነው። የአሳሽ ዳሽቦርዱ በራስ-ሰር ይጠቀምበታል።
3. በ`/api/auth/logout` በኩል ውጣ። ለመቅዳት የሚቻል ረጅም ጊዜ የሚቆይ ሚስጥር የለም።
### የCLI machine-id ቶከን
1. `omniroute`ን ከአገልጋዩ ጋር **በተመሳሳይ ሆስት** ላይ (loopback) አሂድ።
2. CLIው በ`~/.omniroute/` ስር machine-id ቶከን ያስነሳል (chmod 600)።
3. ይህ ከሌላ ማሽን **አይሰራም**። ለርቀት CLI Access Token ተጠቀም።
### ወሰን ያለው Access Token (`oma_live_…`)
1. ዳሽቦርድ፦ **ቅንብሮች → የመዳረሻ ቶከኖች** → ፍጠር (ስም + ወሰን)። **ሚስጥሩ አንድ ጊዜ ብቻ ይታያል።**
2. ወይም CLI፦ `omniroute connect <host>` (የይለፍ ቃል → ቶከን)። [የርቀት ሁነታ](./REMOTE-MODE.md)ን ይመልከቱ።
3. ራስጌ፦ `Authorization: Bearer oma_live_…`
4. ከተመሳሳዩ የመዳረሻ ቶከኖች ገጽ ላይ ሻር (ወይም የCLI ዐውዱን ሰርዝ)።
5. አገልጋዩ የሚያከማቸው ሃሽን ብቻ ነው። ግልጽ ጽሑፉን እንደ የይለፍ ቃል ያዙት።
### `manage` ወሰን ያለው API ቁልፍ
1. ዳሽቦርድ፦ **API Manager / API ቁልፎች** → ቁልፍ ፍጠር ወይም አርትዕ → `manage`ን (ወይም `admin`ን) አንቃ።
2. ራስጌ፦ `Authorization: Bearer sk-…` (የቁልፉ ትክክለኛ ቅድመ ቅጥያ)።
3. በተመሳሳዩ UI ውስጥ ሻር ወይም `manage`ን አስወግድ።
4. CLI ላልሆነ አውቶሜሽን ዝቅተኛውን መብት ይጠቀሙ፦ GET-ብቻ ለሆኑ ስራዎች `read` Access Tokenን ይምረጡ፤ ጠሪው `/v1`ንም ሆነ አስተዳደርን መጠቀም ሲኖርበት ብቻ በAPI ቁልፍ ላይ `manage`ን ይጠቀሙ።
---
## የራስጌ ቅርጸት
```http
Authorization: Bearer oma_live_<secret>
Authorization: Bearer sk-<secret>
Cookie: auth_token=<dashboard-jwt>
```
የአስተዳደር ማረጋገጫዎችን በURL ዱካ ወይም በመጠይቅ ሕብረቁምፊ ውስጥ አያስቀምጡ። የአስተዳደር
ማረጋገጫ በራስጌ/ኩኪ ብቻ ነው።
---
## ቀድቶ ለመለጠፍ የሚያገለግሉ ምሳሌዎች
ለንባብ ብቻ (አቅራቢዎችን ዘርዝር)። የ`read` Access Token ይጠቀሙ፦
```bash
curl -sS "$OMNIROUTE_URL/api/providers" \
-H "Authorization: Bearer oma_live_<read-token>"
```
ለማሻሻል (የአቅራቢ ግንኙነት ፍጠር)። የ`write`/`admin` Access Token ወይም
የ`manage` ወሰን ያለው API key ይጠቀሙ፦
```bash
curl -sS -X POST "$OMNIROUTE_URL/api/providers" \
-H "Authorization: Bearer oma_live_<write-or-admin-token>" \
-H "Content-Type: application/json" \
-d '{"provider":"openai","apiKey":"<upstream-key>"}'
```
ኢንፈረንስ (አስተዳደር አይደለም)። መደበኛ API key፤ `manage` አያስፈልግም፦
```bash
curl -sS "$OMNIROUTE_URL/v1/models" \
-H "Authorization: Bearer sk-<inference-key>"
```
---
## የአሁኑ የሩጫ ጊዜ ስህተቶች (ምስጢሮችን መልሰው አያሳዩ)
| ሁኔታ | የተለመደ ሁኔታ ኮድ | መልዕክት (ምስጢራዊ መረጃው የተወገደ) |
| ------------------------------------ | ------------ | -------------------------------------------------------------------- |
| ማረጋገጫ የለም | 401 | `Authentication required` |
| ልክ ያልሆነ/ጊዜው ያለፈ `oma_live_…` | 401 | `Invalid or expired access token` |
| `manage`/`admin` የሌለው ልክ የሆነ API key | 403 | `API key lacks 'manage' scope. Enable it in the API Keys dashboard.` |
| በአስተዳደር መስመር ላይ ልክ ያልሆነ መደበኛ API key | 403 | `Invalid management token` |
| የAccess Token ወሰን በጣም ዝቅተኛ ነው | 403 | `Access token scope '<have>' is insufficient; '<need>' required.` |
"Invalid management token" ማለት bearer እንደ የአስተዳደር
ማረጋገጫ **ተቀባይነት አላገኘም** ማለት ነው። የትኛውን ዓይነት መፍጠር እንዳለብዎት **አይነግርዎትም**። ከላይ ያለውን ሰንጠረዥ ይጠቀሙ፦
የኢንፈረንስ ቁልፎች የ`manage` ወሰን ያስፈልጋቸዋል፤ የርቀት CLI `oma_live_…` ያስፈልገዋል፤ dashboard
ደግሞ የክፍለ ጊዜ ኩኪውን ይጠቀማል።
---
## የሚመከረው ዝቅተኛ-ፈቃድ ምርጫ
| ጠሪ | ይህን ይጠቀሙ |
| ---------------------------------- | ---------------------------------------- |
| አሳሽ | የDashboard ክፍለ ጊዜ |
| በአገልጋዩ አስተናጋጅ ላይ ያለ CLI | Machine token |
| ከላፕቶፕ ወደ ርቀት አገልጋይ የሚገናኝ CLI | ከ`omniroute connect` የሚገኝ `oma_live_…` |
| CI / ስክሪፕቶች (ለአስተዳደር ብቻ) | የሚሠራውን አነስተኛውን ወሰን የያዘ `oma_live_…` |
| ሁለቱንም `/v1` እና `/api` መጥራት ያለበት CI | `manage` ያለው API key **ወይም** ሁለት ማረጋገጫዎች |

118
docs/i18n/am/docs/guides/OPENCODE-V2-PLUGIN.md Normal file
View File

@@ -0,0 +1,118 @@
# OpenCode v2 plugin — install and configure (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/OPENCODE-V2-PLUGIN.md) · 🇸🇦 [ar](../../../ar/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇦🇿 [az](../../../az/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇧🇬 [bg](../../../bg/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇧🇩 [bn](../../../bn/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇨🇿 [cs](../../../cs/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇩🇰 [da](../../../da/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇩🇪 [de](../../../de/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇬🇷 [el](../../../el/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇪🇸 [es](../../../es/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇪🇪 [et](../../../et/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇷 [fa](../../../fa/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇫🇮 [fi](../../../fi/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇫🇷 [fr](../../../fr/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇪 [ga](../../../ga/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [gu](../../../gu/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇳🇬 [ha](../../../ha/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇱 [he](../../../he/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [hi](../../../hi/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇭🇷 [hr](../../../hr/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇭🇺 [hu](../../../hu/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇦🇲 [hy](../../../hy/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇩 [id](../../../id/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇳🇬 [ig](../../../ig/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇹 [it](../../../it/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇯🇵 [ja](../../../ja/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇬🇪 [ka](../../../ka/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇰🇭 [km](../../../km/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [kn](../../../kn/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇰🇷 [ko](../../../ko/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇱🇹 [lt](../../../lt/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇱🇻 [lv](../../../lv/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [ml](../../../ml/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [mr](../../../mr/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇲🇾 [ms](../../../ms/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇲🇹 [mt](../../../mt/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇲🇲 [my](../../../my/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇳🇵 [ne](../../../ne/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇳🇱 [nl](../../../nl/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇳🇴 [no](../../../no/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [or](../../../or/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [pa](../../../pa/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇵🇭 [phi](../../../phi/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇵🇱 [pl](../../../pl/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇵🇹 [pt](../../../pt/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇷🇴 [ro](../../../ro/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇷🇺 [ru](../../../ru/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇱🇰 [si](../../../si/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇸🇰 [sk](../../../sk/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇸🇮 [sl](../../../sl/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇷🇸 [sr](../../../sr/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇸🇪 [sv](../../../sv/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇰🇪 [sw](../../../sw/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [ta](../../../ta/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇮🇳 [te](../../../te/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇹🇭 [th](../../../th/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇹🇷 [tr](../../../tr/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇵🇰 [ur](../../../ur/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇺🇿 [uz](../../../uz/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇻🇳 [vi](../../../vi/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇳🇬 [yo](../../../yo/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/OPENCODE-V2-PLUGIN.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/OPENCODE-V2-PLUGIN.md)
---
`@omniroute/opencode-plugin-v2` ሙሉውን የOmniRoute ካታሎግዎን — ሞዴሎችን፣ ኮምቦዎችን እና
ራስ-ሰር ኮምቦዎችን — ከማሳያ ስሞች፣ ዋጋ እና የነጻ ደረጃ
በጀቶች ጋር ወደ OpenCode v2 ሞዴል መራጭ ያክላል።
OpenCode v1 እና v2 ፕለጊኖችን በተለያዩ ውሎች ስለሚጭኑ፣ ይህ ከ`@omniroute/opencode-plugin`
የተለየ ፓኬጅ ነው። ከዋናው የOpenCode ስሪትዎ ጋር የሚዛመደውን ይምረጡ፤ ምንም ነገር
በመካከላቸው አይጋራም፣ ስለዚህ አንዱን ማሻሻል ሌላውን እንዲያሻሽሉ አያስገድድዎትም።
## መስፈርቶች
- OpenCode v2።
- ሊደረስበት የሚችል OmniRoute ጌትዌይ (በነባሪ `http://localhost:20128`)።
- Node.js 22 ወይም 24።
## መጫን
ፕለጊኑን ወደ `opencode.json` ያክሉ፦
```json
{
"plugins": [
{
"package": "@omniroute/opencode-plugin-v2",
"options": {
"providerId": "omniroute",
"baseURL": "http://localhost:20128"
}
}
]
}
```
ከዚያ ሞዴሎች እንደ `omniroute/<provider>/<model>` ይታያሉ፤ `providerId` ያንን ቅድመ ቅጥያ እና
OpenCode ምስክርነቱን የሚያከማችበትን የውህደት መታወቂያ ይወስናል።
## ምስክርነቶች
ፕለጊኑ የጌትዌይ ቁልፍን በሦስት ቦታዎች፣ በዚህ ቅደም ተከተል ይፈልጋል፦
1. **በOpenCode ውስጥ ያገናኙት ምስክርነት።** ፕለጊኑ ውህደት ስለሚመዘግብ፣
የOpenCode የራሱ የማረጋገጫ ፍሰት ቁልፉን ማከማቸት ይችላል። ምንም ነገር በ`opencode.json` ውስጥ አይቀመጥም — ይህን ይምረጡ።
2. ለእያንዳንዱ ፕሮጀክት የተለየ መተካት ለማድረግ፣ በፕለጊኑ አማራጮች ውስጥ `apiKey`። ይህ ቁልፉን
ወደ ማከማቻ ሊያስገቡት በሚችሉ ፋይል ውስጥ ያስቀምጣል።
3. በአካባቢው ውስጥ `OMNIROUTE_API_KEY`።
ከሦስቱ አንዱም ከሌለ፣ ካታሎጉ ባዶ ይሆናል፤ ፕለጊኑም ዝም ብሎ ባዶ መራጭ
ከመተው ይልቅ ሲጀምር አንድ ጊዜ ይህን ያሳውቃል።
### የአስተዳደር ቶከኑ የተለየ ቁልፍ ነው
ኮምቦዎች፣ የአቅራቢ ጤንነት እና ማበልጸግ (የማሳያ ስሞች፣ ዋጋ፣ የነጻ ደረጃ በጀቶች) የሚመጡት
ከጌትዌዩ `/api/*` የመጨረሻ ነጥቦች ነው፤ አብዛኛዎቹ ማሰማራቶች እነዚህን ከየጥያቄ ቁልፉ ይልቅ በ**አስተዳደር** ቶከን
ይጠብቃሉ፦
```json
"options": {
"baseURL": "http://localhost:20128",
"managementReadToken": "<management read token>"
}
```
ካልተዋቀረ፣ `managementReadToken` ወደ `apiKey` ይመለሳል። ጌትዌዩ ያንን መመለሻ
ውድቅ ሲያደርግ፣ ካታሎጉ አሁንም ይታተማል፤ ነገር ግን ከማሳያ ስሞች ይልቅ ጥሬ የሞዴል መታወቂያዎችን ይይዛል፣ መደበኛ
ቅጽል ስም ድግግሞሽ ማስወገድ፣ ዋጋ እና ኮምቦዎችም አይኖሩትም። ይህ ሲከሰት ፕለጊኑ ለእያንዳንዱ የመጨረሻ ነጥብ አንድ ጊዜ፣
የመጨረሻ ነጥቡን እና የጠፋውን በመጥቀስ ያስጠነቅቃል — ስለዚህ አቅሙ የቀነሰ መራጭ በፍጹም ምስጢር አይሆንም።
## አማራጮች
| ቁልፍ | ነባሪ | ማስታወሻዎች |
| -------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
| `providerId` | `"omniroute"` | የአቅራቢ መታወቂያ፣ የውህደት መታወቂያ እና ሞዴሎች የሚታዩበት ቅድመ ቅጥያ |
| `baseURL` | አስፈላጊ | የጌትዌይ ሥር፣ `http(s)` ብቻ፤ የ`/v1` ቅጥያ አስፈላጊ በሆነበት ቦታ ይጨመራል |
| `apiKey` | የተገናኘ ምስክርነት፣ ከዚያ `OMNIROUTE_API_KEY` | ለ`/v1/*` የውይይት ቁልፍ |
| `managementReadToken` | ወደ `apiKey` ይመለሳል | ለ`/api/*` ቁልፍ — ብዙውን ጊዜ **ተመሳሳይ** አይደለም |
| `displayName` | `"OmniRoute"` | በመራጩ ውስጥ የአቅራቢው ስም |
| `timeoutMs` | `10000` | ለእያንዳንዱ የመጨረሻ ነጥብ የማምጣት ጊዜ ገደብ (ራስ-ሰር ኮምቦዎች 5 ሰከንድ ይጠቀማሉ) |
| `modelCacheTtlMs` | `300000` | የካታሎግ መሸጎጫ TTL፤ የዲስክ ቅጽበታዊ ገጽታ ቀዝቃዛ ጅማሮዎችን ያፋጥናል |
| `timeouts` | ወደ `timeoutMs` ይመለሳል | በms ለእያንዳንዱ የመጨረሻ ነጥብ በጀቶች፦ `models`፣ `combos`፣ `autoCombos`፣ `enrichment` |
| `enrichment` | `true` | ስሞችን፣ ዋጋን እና የነጻ ደረጃ በጀቶችን ያምጡ |
| `providerTag` | `true` | ሞዴሉ የሚመራበትን የላይኛው አቅራቢ ከማሳያ ስሙ በፊት እንደ ቅድመ ቅጥያ ያክሉ |
| `usableOnly` | `false` | ጌትዌዩ እንደተዘጋጁ የሚዘግባቸውን አቅራቢዎች ብቻ ያቆዩ |
| `visibleModels` / `hiddenModels` | `[]` | ትክክለኛ-ወይም-ቅጥያ የፈቃድ ዝርዝሮች፤ ክልከላ ቅድሚያ ያገኛል |
| `geminiSanitization` | `true` | Gemini ከመሣሪያ መርሃግብሮች ውድቅ የሚያደርጋቸውን የJSON-Schema ቁልፍ ቃላት ያስወግዱ (`$ref` መሣሪያዎች ሳይነኩ ይተላለፋሉ) |
| `apiFormat.allowAnthropic` | `false` | በፈቃድ ዝርዝሩ ውስጥ ያሉ መታወቂያዎችን በAnthropic API ብሎክ በኩል ያስተላልፉ |
| `apiFormat.anthropicModels` | `[]` | ወደ Anthropic የሚመሩ ሙሉ የሞዴል መታወቂያዎች |
| `logLevel` / `startupDebug` | `warn` / `false` | የመዝገብ ማስታወሻ ዝርዝር ደረጃ |
## ካታሎጉ እንዴት ወቅታዊ ሆኖ እንደሚቆይ
ካታሎጉ በሚያስፈልግበት ጊዜ ይመጣል እና ለ`modelCacheTtlMs` በካሽ ይቀመጣል፤ የዲስክ ቅጽበታዊ ቅጂም ጌትዌዩ ሊደረስበት በማይችልበት ጊዜ የመጨረሻው የታወቀ ካታሎግ እንዲገኝ ያደርጋል — መቋረጡ ከወቅታዊነት በስተቀር ምንም አያሳጣዎትም። ሞዴሎች እና ጥምረቶች እንደደረሱ ይታተማሉ፤ ራስ-ጥምረቶች፣ የአቅራቢዎች ዝርዝር እና የማበልጸጊያ ተደራቢው ሲደርሱ ይካተታሉ፣ ስለዚህ አንድ ዘገምተኛ የመገናኛ ነጥብ ሙሉውን መራጭ አግቶ ሊይዝ አይችልም።
ስሞቹ ጌትዌዩ የሚያውቀውን መረጃ ይይዛሉ፦ ሞዴሉ የሚመራበትን የላይኛው አቅራቢ፣ የ`[Free]` ምልክት እና አብሮት የሚመጣውን በጀት — ስለዚህ ተመሳሳዩን ሞዴል የሚሸጡ ሁለት ግንኙነቶች እንደተለያዩ ይቆያሉ። ቅድመ ቅጥያውን በ`"providerTag": false` ያጥፉት።
በእጅ የሚደረግ የማደስ ትዕዛዝ የለም፦ የOpenCode v2 ትዕዛዞች የጥያቄ አብነቶች እንጂ የመልሶ ጥሪ ተግባራት አይደሉም፣ ስለዚህ ፕለጊን እንዲህ ያለውን ማቅረብ አይችልም። ማደሶች TTLን ይከተላሉ፤ አስተናጋጁ እንዲጭን የሚጠየቀው ካታሎጉ ወይም ተደራቢው በእርግጥ ሲለወጥ ብቻ ነው፣ በእያንዳንዱ ማደስ ጊዜ አይደለም።
## በGemini ላይ የመሣሪያ ጥሪ
Gemini የመሣሪያ መግለጫዎቻቸው `$schema` ወይም `additionalProperties` የያዙ ሙሉ ጥያቄዎችን `400 INVALID_ARGUMENT` በማለት ውድቅ ያደርጋል። ፕለጊኑ የዚህ አቅራቢ Gemini ሞዴል ከሚቀበላቸው የመሣሪያ ንድፎች ውስጥ እነዚያን ቁልፍ ቃላት ያስወግዳል፣ ሌሎቹን ጥያቄዎች በሙሉ ሳይነካ ይተዋቸዋል። `$ref` የያዘ መሣሪያ ሳይለወጥ ይተላለፋል እንጂ ቁልፍ ቃላቱ አይወገዱበትም፤ ምክንያቱም ማጣቀሻውን ማስወገድ ንድፉን "ማንኛውንም ነገር ተቀበል" ወደሚል ያሰፋዋል።
ይህን ለማጥፋት `"geminiSanitization": false` ያዘጋጁ።
## ችግር ፍቺ
| ምልክት | ምክንያት |
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
| መራጩ ምንም የOmniRoute ሞዴል አያሳይም | ምንም ቁልፍ አልተገኘም (የማስጀመሪያ ማስጠንቀቂያውን ይመልከቱ)፣ ወይም ጌትዌዩ ሊደረስበት አይችልም |
| ጥሬ የሞዴል መለያዎች፣ ጥምረቶች የሉም፣ ዋጋ የለም | የአስተዳደር መገናኛ ነጥቦቹ ቶከኑን ውድቅ አድርገዋል — `managementReadToken`ን ያዘጋጁ |
| በ`opencode-<id>/…` ላይ የተቆለፈ ክፍለ ጊዜ | የv1 ፕለጊን `opencode-<id>`ን አትሟል፤ v2 `<id>`ን ያለ ቅድመ ቅጥያ ያትማል፣ ስለዚህ ሞዴሉን በ`<id>/…` ስር እንደገና ይምረጡ |
## በተጨማሪ ይመልከቱ
- [CLI-INTEGRATIONS.md](CLI-INTEGRATIONS.md) — ቀላል ክብደት ያለው openai-ተኳሃኝ የOpenCode ማዋቀርን ጨምሮ፣ እያንዳንዱ `setup-*` CLI ውህደት።
- [REMOTE-MODE.md](REMOTE-MODE.md) — CLIን ወደ ሩቅ ጌትዌይ ማመልከት።

195
docs/i18n/am/docs/guides/PWA_GUIDE.md Normal file
View File

@@ -0,0 +1,195 @@
# Progressive Web App (PWA) Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/PWA_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/PWA_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/PWA_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/PWA_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/PWA_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/PWA_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/PWA_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/PWA_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/PWA_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/PWA_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/PWA_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/PWA_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/PWA_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/PWA_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/PWA_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/PWA_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/PWA_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/PWA_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/PWA_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/PWA_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/PWA_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/PWA_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/PWA_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/PWA_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/PWA_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/PWA_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/PWA_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/PWA_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/PWA_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/PWA_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/PWA_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/PWA_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/PWA_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/PWA_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/PWA_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/PWA_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/PWA_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/PWA_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/PWA_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/PWA_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/PWA_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/PWA_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/PWA_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/PWA_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/PWA_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/PWA_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/PWA_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/PWA_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/PWA_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/PWA_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/PWA_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/PWA_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/PWA_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/PWA_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/PWA_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/PWA_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/PWA_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/PWA_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/PWA_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/PWA_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/PWA_GUIDE.md)
---
OmniRoute ሙሉ በሙሉ ሊጫን የሚችል Progressive Web App ሆኖ ይቀርባል። ዳሽቦርዱን ከማንኛውም የሞባይል አሳሽ — Android (Chrome) ወይም iOS (Safari) — ሲከፍቱ "ወደ መነሻ ማያ ገጽ ማከል" ይችላሉ፤ ምንም የመተግበሪያ መደብር ሳያስፈልግ እንደ ቤተኛ መተግበሪያ ያለ ተሞክሮ ያገኛሉ።
## PWA ምንድን ነው?
Progressive Web App የOmniRoute የድር ዳሽቦርድን ቤተኛ የሞባይል መተግበሪያ የሚመስልና እንደዚያው የሚሰማ ያደርገዋል። ከተጫነ በኋላ፦
- በራሱ አዶ ከመነሻ ማያ ገጽዎ ይጀምራል
- ሙሉ ማያ ገጽ ላይ ይከፈታል — የአሳሽ አድራሻ አሞሌ ወይም የትር UI የለም
- ለግንኙነት የተዘጋጀ ገጽ በመጠቀም ከመስመር ውጭ ይሰራል
- ፈጣን ጭነት እንዲኖር የማይለወጡ ሀብቶችን በመሸጎጫ ያከማቻል
- ቁመታዊና አግድማ አቀማመጦችን ይደግፋል
## ጭነት
### Android (Chrome)
1. የOmniRoute ዳሽቦርድን Chrome ውስጥ ይክፈቱ፦ `http://YOUR_IP:20128`
2. Chrome የ**"OmniRouteን ወደ መነሻ ማያ ገጽ አክል"** ማስታወቂያን በራስ-ሰር ያሳያል፤ ካልሆነ፦
- የ**⋮** ምናሌን (ሦስት ነጥቦች) ይንኩ → **"ወደ መነሻ ማያ ገጽ አክል"** ወይም **"መተግበሪያውን ጫን"**
3. ጥያቄውን ያረጋግጡ
4. OmniRoute እንደ ራሱን የቻለ መተግበሪያ በመነሻ ማያ ገጽዎ ላይ ይታያል
### iOS (Safari)
1. የOmniRoute ዳሽቦርድን Safari ውስጥ ይክፈቱ፦ `http://YOUR_IP:20128`
2. የ**ማጋራት** አዝራሩን (ቀስት ያለው ሳጥን) ይንኩ
3. ወደ ታች ያሸብልሉና **"ወደ መነሻ ማያ ገጽ አክል"**ን ይንኩ
4. ስም ይስጡት (ነባሪው "OmniRoute" ነው) እና **አክል**ን ይንኩ
5. OmniRoute ከመተግበሪያው አዶ ጋር በመነሻ ማያ ገጽዎ ላይ ይታያል
### ዴስክቶፕ (Chrome / Edge)
1. የOmniRoute ዳሽቦርድን ይክፈቱ
2. በአድራሻ አሞሌው ውስጥ ያለውን **የመጫኛ አዶ** ጠቅ ያድርጉ (ወይም ⋮ → "OmniRouteን ጫን...")
3. ጥያቄውን ያረጋግጡ
4. OmniRoute እንደ ራሱን የቻለ መስኮት ይከፈታል — ትሮች የሉም፣ የአድራሻ አሞሌም የለም
## ባህሪያት
### የሙሉ ማያ ገጽ ተሞክሮ
ማኒፌስቱ በ`display: "fullscreen"` ተዋቅሯል፤ ይህም የተጫነው መተግበሪያ ሙሉውን ማያ ገጽ ይጠቀማል ማለት ነው — የአሳሽ መቆጣጠሪያዎች የሉም፣ ከሁኔታ አሞሌው ጋርም መደራረብ የለም። ይህ ዳሽቦርዱ በእውነት ቤተኛ መተግበሪያ እንዲመስል ያደርገዋል።
### ከመስመር ውጭ ድጋፍ
OmniRoute ብልህ የመሸጎጫ አያያዝን የሚያቀርብ service worker (`sw.js`) ያካትታል፦
| የሀብት ዓይነት | ስልት | ባህሪ |
| ------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------- |
| **የመተግበሪያ መሠረታዊ ክፍል** | መሸጎጫ-ቅድሚያ | `/`፣ `/offline`፣ ማኒፌስት እና አዶዎች በጭነት ጊዜ አስቀድመው በመሸጎጫ ይከማቻሉ |
| **የማይለወጡ ሀብቶች** (CSS, JS, ምስሎች, ቅርጸ-ቁምፊዎች) | መጀመሪያ አውታረ መረብ፣ ካልተሳካ መሸጎጫ | አዲስ ይዘትን ከአውታረ መረቡ ያመጣል፤ ከመስመር ውጭ ከሆነ ወደ መሸጎጫው ይመለሳል |
| **Next.js ጥቅሎች** (`/_next/`) | መጀመሪያ አውታረ መረብ፣ ከመሸጎጫ ማዘመን ጋር | ከአውታረ መረቡ ያመጣና መሸጎጫውን ያዘምናል፤ ከመስመር ውጭ ከሆነ በመሸጎጫ ያለውን ስሪት ያቀርባል |
| **የአሰሳ ጥያቄዎች** | ማለፊያ (ፈጽሞ አይጠለፍም) | አሳሹ የHTTP/3→HTTP/2 መመለሻን ይቆጣጠራል፤ የሞተ QUIC socket ወደ `Response.error()` መቀየር የለበትም |
| **API / የዳሽቦርድ መስመሮች** (`/api/`, `/a2a`, `/dashboard`) | ማለፊያ (ፈጽሞ በመሸጎጫ አይቀመጥም) | ሁልጊዜ በቀጥታ ወደ አገልጋዩ ይሄዳል — በservice worker ፈጽሞ አይጠለፍም |
### ከመስመር ውጭ ገጽ
አውታረ መረቡ በማይገኝበት ጊዜ አንድ ተጠቃሚ ወደ አዲስ ገጽ ሲሄድ፣ service worker ለዚህ የተዘጋጀውን `/offline` ገጽ ያቀርባል፤ ገጹም፦
- ግልጽ የሆነ **"የግንኙነት ችግር"** መልዕክት ያሳያል
- በቅጽበት የሚዘመን የቀጥታ **በመስመር ላይ/ከመስመር ውጭ ሁኔታ አመልካች** ያሳያል
- ግንኙነቱ ሲመለስ እንደገና ለመጫን የ**"ግንኙነትን እንደገና ሞክር"** አዝራር ያቀርባል
- ለምርመራ ወደ **የሁኔታ ገጽ** ያገናኛል
### የመተግበሪያ አዶዎች
OmniRoute ለእያንዳንዱ መድረክ የተመቻቹ አዶዎችን ያቀርባል፦
| ፋይል | መጠን | የሚጠቀሙበት |
| ---------------------- | -------------- | ------------------------- |
| `icon-512.png` | 512×512 | የAndroid መጫኛ ጥያቄ፣ የመነሻ ገጽ |
| `apple-touch-icon.png` | 180×180 | የiOS መነሻ ማያ ገጽ አዶ |
| `icon-192.svg` | 192×192 (ቬክተር) | የAndroid ተስማሚ አዶ |
| `apple-touch-icon.svg` | 180×180 (ቬክተር) | የApple አማራጭ |
| `favicon.svg` | ቬክተር | የአሳሽ ትሮች |
| `favicon.ico` | ባለብዙ መጠን | የቆዩ አሳሾች |
### ራስ-ሰር ምዝገባ
service worker በዋናው አቀማመጥ ውስጥ ባለው `<PwaRegister />` component በኩል በራስ-ሰር ይመዘገባል። ምንም የተጠቃሚ እርምጃ አያስፈልግም — አሳሹ ትክክለኛውን ማኒፌስት እና service worker እንዳገኘ ወዲያውኑ መተግበሪያው ሊጫን የሚችል ይሆናል።
## ቴክኒካዊ አርክቴክቸር
### የድር መተግበሪያ Manifest (`manifest.webmanifest`)
በNext.js በኩል ከ`src/app/manifest.ts` የሚመነጭ፦
```json
{
"name": "OmniRoute",
"short_name": "OmniRoute",
"description": "OmniRoute ለብዙ አቅራቢዎች LLMs የሚያገለግል AI ጌትዌይ ነው። ለሁሉም የAI አቅራቢዎችዎ አንድ የመገናኛ ነጥብ።",
"start_url": "/",
"scope": "/",
"display": "fullscreen",
"orientation": "any",
"background_color": "#0b0f1a",
"theme_color": "#0b0f1a",
"icons": [
{
"src": "/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any maskable"
},
{ "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
]
}
```
### Service Worker (`public/sw.js`)
ምንም የframework ጥገኞች የሌሉት vanilla service worker፣ የሚከተሉት ባህሪያት አሉት፦
- **የመጫን ደረጃ**፦ የመተግበሪያውን shell (root፣ offline ገጽ፣ manifest፣ icons) አስቀድሞ cache ያደርጋል
- **የማግበር ደረጃ**፦ የድሮ cache ስሪቶችን ያጸዳል እና ሁሉንም clients ይቆጣጠራል
- **የFetch ደረጃ**፦ በጥያቄው ዓይነት (navigation፣ static asset፣ API) ላይ የተመሠረተ ብልህ routing
- **የCache ስሪት አስተዳደር**፦ `omniroute-pwa-v3` — ማሻሻያ ሲደረግ አዲስ cache እንዲፈጠር ለማስገደድ ይህን ያሳድጉ
### የLayout Metadata (`src/app/layout.tsx`)
Root layout ለPWA ተገዢነት የሚያስፈልጉትን ሁሉንም meta tags ያቀርባል፦
- የ`manifest` link ወደ `/manifest.webmanifest`
- `apple-web-app-capable: true` ለiOS standalone mode
- `apple-web-app-status-bar-style: black-translucent`
- `mobile-web-app-capable: yes` ለAndroid Chrome
- `theme-color: #0b0f1a`
- `viewport-fit: cover` ከጠርዝ እስከ ጠርዝ rendering ለማድረግ
### Component፦ `PwaRegister`
በ`src/shared/components/PwaRegister.tsx` የሚገኘው ይህ client component፦
1. ሲጫን ይሰራል (በclient-side ላይ ብቻ)
2. በbrowser ውስጥ የ`serviceWorker` ድጋፍ መኖሩን ያረጋግጣል
3. `/sw.js`ን ያለምንም ማሳወቂያ ይመዘግባል (መተግበሪያውን እንዳያግዱ errors ችላ ይባላሉ)
4. ምንም ነገር render አያደርግም (`return null`) — side-effect ብቻ ያለው component ነው
## ከTermux (Android) ጋር መጠቀም
OmniRouteን በAndroid ላይ በTermux በኩል ሲያስኬዱ፣ PWAው ያለችግር ይሰራል፦
1. OmniRouteን በTermux ውስጥ ያስጀምሩ፦ `npx omniroute`
2. በዚያው ስልክ ላይ Chromeን ይክፈቱ፦ `http://localhost:20128`
3. PWAውን በ"ወደ መነሻ ማያ ገጽ አክል" በኩል ይጫኑ
4. PWAው ከአካባቢያዊው Termux server ጋር ይገናኛል — ሁሉም ነገር በመሣሪያው ላይ ይሰራል
ይህ ጥምረት የAndroid ስልክዎ **server** (Termux) እና **client** (PWA) ሁለቱም ነው ማለት ነው — ሙሉ በሙሉ ራሱን የቻለ AI gateway።
## ከሌሎች መሣሪያዎች መጠቀም
የOmniRoute serverዎን በbrowser መድረስ በሚችል ማንኛውም መሣሪያ ላይ PWAውን ይጫኑ፦
- **ሌላ ስልክ/ታብሌት**፦ ወደ `http://PHONE_IP:20128` ይሂዱ እና PWAውን ይጫኑ
- **ላፕቶፕ**፦ Chrome/Edgeን ይክፈቱ እና እንደ desktop PWA ይጫኑት
- **Browser ያለው Smart TV**፦ dashboardን በሙሉ ማያ ገጽ ይድረሱበት
## ማበጀት
### የInstance ስም
የPWAው ርዕስ ከ`Dashboard → Settings` የሚገኘውን **Instance Name** setting ያከብራል። Instanceዎን "የእኔ AI Gateway" ብለው ከቀየሩት፣ የተጫነው PWA ያንን ስም ያሳያል።
### ብጁ Favicon
በ`Dashboard → Settings` በኩል ብጁ favicon ከሰቀሉ፣ በdesktop ላይ ያለው የPWA icon ብጁውን icon ያንጸባርቃል። የMobile መነሻ ማያ ገጽ icons ቀድሞ የተዘጋጁትን `icon-512.png` እና `apple-touch-icon.png` files ይጠቀማሉ።
## ገደቦች
- **የPush ማሳወቂያዎች የሉም** — Service worker-ው Push APIን አይተገብርም። በምትኩ ማሳወቂያዎች በElectron መተግበሪያው ይስተናገዳሉ።
- **የበስተጀርባ ማመሳሰል የለም** — ከመስመር ውጭ የሚከናወኑ ድርጊቶች በኋላ እንደገና እንዲፈጸሙ ወረፋ አይያዝላቸውም። PWAው በዋናነት የዳሽቦርድ መመልከቻ ነው።
- **የiOS ገደቦች** — በiOS ላይ ያለው Safari ሁሉንም የPWA ባህሪያት አይደግፍም (ለምሳሌ፣ የመጫን ጥያቄዎች በእጅ መከናወን አለባቸው፣ እንዲሁም የበስተጀርባ service worker-ዎች የተገደቡ ናቸው)።
- **የCache መጠን** — Service worker-ው ቋሚ ሀብቶችን ብቻ cache ያደርጋል። ከ`/api/` መስመሮች የሚመጡ ትላልቅ የምላሽ ውሂብ ጥቅሎች ፈጽሞ cache አይደረጉም።
- **ብጁ አዶዎች በሞባይል ላይ** — በቅንብሮች ውስጥ faviconን መቀየር በሞባይል ላይ ያለውን የመነሻ ማያ ገጽ አዶ አያዘምነውም (ይህ የPWA አዶዎችን እንደገና ማመንጨት ይጠይቃል)።
## የፋይሎች ማጣቀሻ
| ፋይል | ዓላማ |
| --------------------------------------- | ------------------------------------------------------------- |
| `src/app/manifest.ts` | የNext.js manifest መስመር (`manifest.webmanifest`ን ያመነጫል) |
| `public/sw.js` | የcache ማድረግ ሎጂክ ያለው service worker |
| `src/shared/components/PwaRegister.tsx` | Service worker-ውን የሚመዘግብ የclient ክፍለ አካል |
| `src/app/offline/page.tsx` | የቀጥታ ሁኔታ አመልካች ያለው ከመስመር ውጭ መጠባበቂያ ገጽ |
| `src/app/layout.tsx` | የPWA metadata (apple-web-app፣ theme-color፣ ወዘተ) ያለው ዋና layout |
| `public/icon-512.png` | 512×512 PNG አዶ (Android፣ የመነሻ ማያ ገጽ) |
| `public/apple-touch-icon.png` | 180×180 PNG አዶ (የiOS መነሻ ማያ ገጽ) |
| `public/icon-192.svg` | 192×192 SVG አዶ (Android adaptive) |
| `public/apple-touch-icon.svg` | 180×180 SVG አዶ (የApple መጠባበቂያ) |

464
docs/i18n/am/docs/guides/REMOTE-MODE.md Normal file
View File

@@ -0,0 +1,464 @@
# Remote Mode (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/REMOTE-MODE.md) · 🇸🇦 [ar](../../../ar/docs/guides/REMOTE-MODE.md) · 🇦🇿 [az](../../../az/docs/guides/REMOTE-MODE.md) · 🇧🇬 [bg](../../../bg/docs/guides/REMOTE-MODE.md) · 🇧🇩 [bn](../../../bn/docs/guides/REMOTE-MODE.md) · 🇨🇿 [cs](../../../cs/docs/guides/REMOTE-MODE.md) · 🇩🇰 [da](../../../da/docs/guides/REMOTE-MODE.md) · 🇩🇪 [de](../../../de/docs/guides/REMOTE-MODE.md) · 🇬🇷 [el](../../../el/docs/guides/REMOTE-MODE.md) · 🇪🇸 [es](../../../es/docs/guides/REMOTE-MODE.md) · 🇪🇪 [et](../../../et/docs/guides/REMOTE-MODE.md) · 🇮🇷 [fa](../../../fa/docs/guides/REMOTE-MODE.md) · 🇫🇮 [fi](../../../fi/docs/guides/REMOTE-MODE.md) · 🇫🇷 [fr](../../../fr/docs/guides/REMOTE-MODE.md) · 🇮🇪 [ga](../../../ga/docs/guides/REMOTE-MODE.md) · 🇮🇳 [gu](../../../gu/docs/guides/REMOTE-MODE.md) · 🇳🇬 [ha](../../../ha/docs/guides/REMOTE-MODE.md) · 🇮🇱 [he](../../../he/docs/guides/REMOTE-MODE.md) · 🇮🇳 [hi](../../../hi/docs/guides/REMOTE-MODE.md) · 🇭🇷 [hr](../../../hr/docs/guides/REMOTE-MODE.md) · 🇭🇺 [hu](../../../hu/docs/guides/REMOTE-MODE.md) · 🇦🇲 [hy](../../../hy/docs/guides/REMOTE-MODE.md) · 🇮🇩 [id](../../../id/docs/guides/REMOTE-MODE.md) · 🇳🇬 [ig](../../../ig/docs/guides/REMOTE-MODE.md) · 🇮🇹 [it](../../../it/docs/guides/REMOTE-MODE.md) · 🇯🇵 [ja](../../../ja/docs/guides/REMOTE-MODE.md) · 🇬🇪 [ka](../../../ka/docs/guides/REMOTE-MODE.md) · 🇰🇭 [km](../../../km/docs/guides/REMOTE-MODE.md) · 🇮🇳 [kn](../../../kn/docs/guides/REMOTE-MODE.md) · 🇰🇷 [ko](../../../ko/docs/guides/REMOTE-MODE.md) · 🇱🇹 [lt](../../../lt/docs/guides/REMOTE-MODE.md) · 🇱🇻 [lv](../../../lv/docs/guides/REMOTE-MODE.md) · 🇮🇳 [ml](../../../ml/docs/guides/REMOTE-MODE.md) · 🇮🇳 [mr](../../../mr/docs/guides/REMOTE-MODE.md) · 🇲🇾 [ms](../../../ms/docs/guides/REMOTE-MODE.md) · 🇲🇹 [mt](../../../mt/docs/guides/REMOTE-MODE.md) · 🇲🇲 [my](../../../my/docs/guides/REMOTE-MODE.md) · 🇳🇵 [ne](../../../ne/docs/guides/REMOTE-MODE.md) · 🇳🇱 [nl](../../../nl/docs/guides/REMOTE-MODE.md) · 🇳🇴 [no](../../../no/docs/guides/REMOTE-MODE.md) · 🇮🇳 [or](../../../or/docs/guides/REMOTE-MODE.md) · 🇮🇳 [pa](../../../pa/docs/guides/REMOTE-MODE.md) · 🇵🇭 [phi](../../../phi/docs/guides/REMOTE-MODE.md) · 🇵🇱 [pl](../../../pl/docs/guides/REMOTE-MODE.md) · 🇵🇹 [pt](../../../pt/docs/guides/REMOTE-MODE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/REMOTE-MODE.md) · 🇷🇴 [ro](../../../ro/docs/guides/REMOTE-MODE.md) · 🇷🇺 [ru](../../../ru/docs/guides/REMOTE-MODE.md) · 🇱🇰 [si](../../../si/docs/guides/REMOTE-MODE.md) · 🇸🇰 [sk](../../../sk/docs/guides/REMOTE-MODE.md) · 🇸🇮 [sl](../../../sl/docs/guides/REMOTE-MODE.md) · 🇷🇸 [sr](../../../sr/docs/guides/REMOTE-MODE.md) · 🇸🇪 [sv](../../../sv/docs/guides/REMOTE-MODE.md) · 🇰🇪 [sw](../../../sw/docs/guides/REMOTE-MODE.md) · 🇮🇳 [ta](../../../ta/docs/guides/REMOTE-MODE.md) · 🇮🇳 [te](../../../te/docs/guides/REMOTE-MODE.md) · 🇹🇭 [th](../../../th/docs/guides/REMOTE-MODE.md) · 🇹🇷 [tr](../../../tr/docs/guides/REMOTE-MODE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/REMOTE-MODE.md) · 🇵🇰 [ur](../../../ur/docs/guides/REMOTE-MODE.md) · 🇺🇿 [uz](../../../uz/docs/guides/REMOTE-MODE.md) · 🇻🇳 [vi](../../../vi/docs/guides/REMOTE-MODE.md) · 🇳🇬 [yo](../../../yo/docs/guides/REMOTE-MODE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/REMOTE-MODE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/REMOTE-MODE.md)
---
OmniRoute ራሱ በሌላ ቦታ (በVPS፣ በቤት ሰርቨር፣ በTailnetዎ ላይ ባለ ሌላ ማሽን) ላይ እየሰራ፣ `omniroute` CLIን በላፕቶፕዎ ላይ ያስኪዱ።
በ`omniroute connect` አንድ ጊዜ ይግቡ፤ ከዚያ በኋላ **እያንዳንዱ** የCLI ትዕዛዝ ያንን የርቀት
ሰርቨር ይጠቀማል — ተመሳሳይ ትዕዛዞች፣ ተመሳሳይ ውጤት፣ በርቀት ሰርቨሩ ላይ መፈጸማቸው ብቻ ይለያል።
የሚጫን ሁለተኛ መሣሪያ የለም፦ የርቀት ሁነታው መደበኛው `omniroute` CLI
ከወሰን ካላቸው **የመዳረሻ ቶከኖች** ጋር ነው።
```bash
npm install -g omniroute # መደበኛው CLI
omniroute connect 192.168.0.15 # ይግቡ (የይለፍ ቃል → ወሰን ያለው ቶከን)
omniroute models list # ← አሁን የርቀት ሰርቨሩን ሞዴሎች ይዘረዝራል
omniroute configure codex # ← ከርቀት ካታሎጉ የአካባቢ Codex መገለጫ ይጽፋል
```
---
## እንዴት እንደሚሰራ
```
የእርስዎ ላፕቶፕ የርቀት OmniRoute (VPS)
┌────────────────────┐ ┌───────────────────────────────┐
│ omniroute CLI │ POST /api/cli/connect (የይለፍ ቃል → ቶከን) │
│ ዐውድ፦ vps │ ───────────────► │ ወሰን ያለው የመዳረሻ ቶከን ይፈጥራል │
│ baseUrl, token │ Authorization: Bearer oma_live_… │
│ │ ───────────────► │ እያንዳንዱ የአስተዳደር መንገድ፣ │
│ ውቅሮችን በአካባቢው │ ◄─────────────── │ በቶከኑ ወሰን መሠረት ይፈተሻል │
│ ይጽፋል │ └───────────────────────────────┘
└────────────────────┘
```
- **ዐውዶች** እያንዳንዳቸው አንድ ሰርቨር ያከማቻሉ (`~/.omniroute/config.json`፣ `chmod 600`)።
`omniroute contexts use <name>` ንቁውን ሰርቨር ይቀይራል፤ `default` የአካባቢው ሰርቨር ነው።
- **የመዳረሻ ቶከኖች** (`oma_live_…`) የአስተዳደር ትዕዛዞችን ይፈቅዳሉ። እነዚህ
ከየመገመቻ API ቁልፎች (`sk-…`፣ ለ`/v1/chat/completions` የሚያገለግሉ) የተለዩ ናቸው።
- በሰርቨር በኩል የሚከማቸው የቶከኑ SHA-256 hash ብቻ ነው። ግልጽ ጽሑፉ በሚፈጠርበት ጊዜ
**አንድ ጊዜ** ብቻ ይታያል።
---
## መገናኘት
### በአስተዳደር የይለፍ ቃል (የመነሻ ማዋቀር)
```bash
omniroute connect 192.168.0.15
# ለhttp://192.168.0.15:20128 የአስተዳደር የይለፍ ቃል፦ ********
# ✔ ከhttp://192.168.0.15:20128 ጋር ተገናኝቷል — ዐውድ '192.168.0.15' (ወሰን፦ admin)
```
የይለፍ ቃል ፍሰቱ በነባሪነት **admin** ቶከን ይፈጥራል (የይለፍ ቃሉን ስለያዙ፣
አስቀድመው ሙሉ ቁጥጥር አለዎት)። በ`--scope` ወሰኑን ይቀንሱ፦
```bash
omniroute connect 192.168.0.15 --scope write
```
አማራጮች፦ `--port <p>` (አስተናጋጁ ወደብ ካልያዘ)፣ `--name <ctx>` (የዐውድ ስም)፣
`--scope read|write|admin`። ሙሉ URL እንዳለ ይከበራል፦
`omniroute connect https://omni.example.com`።
### አስቀድሞ በተፈጠረ ቶከን
በዳሽቦርዱ ውስጥ (ወይም `omniroute tokens create`ን በመጠቀም) ወሰን ያለው ቶከን ያመንጩና
ይለጥፉት — የይለፍ ቃል አያስፈልግም፦
```bash
omniroute connect 192.168.0.15 --key oma_live_xxxxxxxx
```
CLIው `GET /api/cli/whoami`ን በመጠቀም ያረጋግጠዋል፣ ከዚያም እንደ ንቁ ዐውድ ያስቀምጠዋል።
---
## ወሰኖች
ሦስት ተዋረዳዊ ደረጃዎች (`admin ⊃ write ⊃ read`)፦
| ወሰን | ማድረግ የሚችለው |
| ------- | ------------------------------------------------------------------------ |
| `read` | መዘርዘር/መመርመር — `models list`፣ `providers status`፣ `logs`፣ `usage`፣ `cost` |
| `write` | ማንበብ **+** ማዋቀር/መተግበር — `setup-codex`፣ `keys add`፣ `config set`፣ ድብልቆች |
| `admin` | መጻፍ **+** ማስተዳደር — የ`tokens` CRUD፣ አቅራቢዎችን መጨመር፣ አገልግሎቶች፣ ፖሊሲ፣ oauth |
ሰርቨሩ እያንዳንዱ መንገድ የሚፈልገውን ወሰን ከHTTP ዘዴው
(`GET`→read፣ ለውጦች→write) እና ለስሱ ቦታዎች ከተዘጋጀው የadmin የፈቃድ ዝርዝር
(`/api/cli/tokens`፣ የ`/api/providers` ለውጦች፣ `/api/oauth`፣ `/api/services`፣ …) ይወስናል።
በቂ ያልሆነ ወሰን ያለው ቶከን ግልጽ ከሆነ መልዕክት ጋር `403` ያገኛል።
> ፕሮሰሶችን የሚጀምሩ መንገዶች (`/api/services/*`፣ `/api/mcp/*`፣ …)
> **ለloopback ብቻ** ሆነው ይቆያሉ — የርቀት ቶከን ወሰኑ ምንም ይሁን ምን ፈጽሞ ሊደርስባቸው አይችልም።
## በርቀት ጭነት ላይ Antigravityን ማገናኘት
Antigravity የGoogle firstparty/nativeapp ፈቃድ መስጫ ገጽን ይጠቀማል። Google
የፈቃድ ኮዱን የሚለቀው **የloopback ማዘዋወሪያው**
(`http://127.0.0.1:<port>/callback`) **መግባቱን ከሚያጸድቀው አሳሽ
ሊደረስበት ሲችል ብቻ ነው**። በርቀት VPS ጭነት ላይ ያ loopback ያለው
በእርስዎ ማሽን ላይ ሳይሆን በአገልጋዩ ላይ ነው፤ ስለዚህ የፈቃድ መስጫው **ለዘላለም
ተንጠልጥሎ ይቀራል እና ምንም ኮድ አያወጣም** — መደበኛው የ"callback URLን ለጥፍ"
አማራጭ የሚለጠፍ ነገር አይኖረውም። (ይህ ከGoogle ወገን የሆነ ገደብ ነው፦
በጥቅሉ የቀረበውን Antigravity desktop client በሚጠቀም ማንኛውም proxy ላይ ተመሳሳይ
መንጠልጠል ይከሰታል፤ በOmniRoute ላይ ብቻ አይደለም።)
dashboardው እርስዎ ከመቆምዎ በፊት ይህን ያውቃል፦ ከlocalhost ውጭ ከሆነ አድራሻ
**Providers → Antigravity → Connect**ን ሲከፍቱ፣ አጠቃላዩን "callback URLን ቅዳ"
ማሳወቂያ ከታች ባሉት ሁለት መፍትሔዎች ይተካዋል፤ በእያንዳንዱም የእርስዎ host እና port
አስቀድመው ተሞልተዋል። (የLAN አድራሻም ይቆጠራል — ይህን callback በተመለከተ
`192.168.x.x` localhost አይደለም።)
Antigravityን ከርቀት OmniRoute ጋር ለማገናኘት ሁለት የሚደገፉ መንገዶች አሉ።
### አማራጭ A — የአካባቢ መግቢያ ረዳት (የሚመከር)
OAuthን `127.0.0.1` ሊደረስበት በሚችልበት **በራስዎ ኮምፒውተር** ላይ ያሂዱ።
ረዳቱ በቀጥታ ከGoogle ጋር ይገናኛል፤ ስለዚህ dashboardው ላይ ያለው ስሪት
ማጠናቀቅ በማይችልበት ሁኔታ ፈቃድ መስጠቱ በአካባቢው ይጠናቀቃል።
**አስቀድመው ተገናኝተው ከሆነ** (`omniroute connect <host>`)፣ የሚቀዱት
ምንም ነገር የለም — ረዳቱ credentialን ወደዚያ ጭነት ለእርስዎ ያደርሳል፦
```bash
# በእርስዎ LOCAL ማሽን ላይ (Node.js + አሳሽ ያስፈልጋል)፦
omniroute connect 192.168.0.15 # አንድ ጊዜ — የadmin ወሰን ያለው context token ይፈጥራል
npx omniroute login antigravity
# ↳ የGoogle ፈቃድ መስጫውን ይከፍታል፣ callbackን በአካባቢ loopback port ላይ ይይዛል፣
# ይለዋውጠዋል፣ እና credentialን ወደ ገባሪው context POST ያደርጋል፦
#
# Antigravity በhttp://192.168.0.15:20128 ላይ ተገናኝቷል (ግንኙነት abc123)።
# የሚለጠፍ ነገር የለም — ይህን terminal መዝጋት ይችላሉ።
```
ገባሪው context ወደ ሌላ ማሽን በሚያመለክትበት ጊዜ ሁሉ pushው በራስ-ሰር
ይከናወናል። በ`--push` / `--no-push` በሁለቱም አቅጣጫ ያስገድዱት፣ ወይም
በ`--context <name>` የተወሰነ contextን ዒላማ ያድርጉ።
**የእርስዎ ማሽን VPSውን መድረስ ካልቻለ** (በfirewall የታገደ፣ SSH የሌለው፣
ከአውታረ መረብ የተለየ ዴስክ)፣ ረዳቱ አሁንም ይሠራል — በእርግጥ _የሚያስፈልገው_
Googleን ብቻ ነው። `--no-push`ን ይጠቀሙ፣ ወይም pushው እንዲከሽፍ ብቻ ይተዉት፦
አስቀድመው ያጠናቀቁትን ፈቃድ ከመጣል ይልቅ blobውን ወደ ማተም ይመለሳል።
```bash
npx omniroute login antigravity --no-push
# omniroute-cred-v1.eyJ2IjoxLCJ...
```
ከዚያ በ**ርቀት** dashboard ውስጥ፦ **Providers → Antigravity → Connect**፣ እና
የ`omniroute-cred-v1.…` blobን በ**Step 2** መስክ ውስጥ ይለጥፉ (callback URLን ወይም
credential blobን ይቀበላል)። OmniRoute ዲኮድ ያደርገዋል፣ Cloud Code
onboardingን በአገልጋዩ በኩል ያስኬዳል፣ እና ግንኙነቱን በቋሚነት ያስቀምጣል።
> blobው refresh token ይዟል — እንደ የይለፍ ቃል ይያዙት። በpush መንገድ ላይ
> በcontextዎ የተረጋገጠ ግንኙነት በኩል አንድ ጊዜ ይላካል፤ በመለጠፍ መንገድ ላይ ደግሞ
> በdashboard ግንኙነትዎ በኩል ይላካል። በሁለቱም መንገድ በማከማቻ ላይ በተመሰጠረ መልኩ
> ይቀመጣል፣ እና የተሳካ push በterminalዎ ላይ ፈጽሞ አያትመውም።
Flags፦ `--no-browser` (URLን በራስ-ሰር ከመክፈት ይልቅ ያትሙት)፣ `--port <n>`
(loopback portን ይወስኑ)፣ `--timeout <ms>`፣ `--push` / `--no-push` (ራስ-ሰር
ማድረሱን ይሻሩ)፣ `--context <name>` (የተወሰነ contextን ዒላማ ያድርጉ)።
### አማራጭ B — የSSH local-forward tunnel
ወደ VPSው የSSH መዳረሻ ካለዎት፣ loopback callbackው በtunnel በኩል ወደ አገልጋዩ
እንዲመለስ dashboard portን forward ያድርጉ፦
```bash
# በእርስዎ LOCAL ማሽን ላይ፦
ssh -L 20128:127.0.0.1:20128 user@your-vps
# ከዚያ http://localhost:20128ን በLOCAL አሳሽዎ ይክፈቱ እና Antigravityን
# በመደበኛው መንገድ ያገናኙ — የ127.0.0.1:20128/callback ማዘዋወሪያ አሁን በSSH በኩል VPSውን ይደርሳል።
```
dashboardውን እንደ `localhost:20128` ስለሚደርሱበት፣ የGoogle ፈቃድ መስጠቱ
ይጠናቀቃል እና callbackው በዚያው tunnel በኩል ወደ አገልጋዩ ይደርሳል —
blob አያስፈልግም። ግንኙነቱ ገባሪ እንደሆነ እስኪታይ ድረስ tunnelውን ክፍት ያድርጉት።
ከታች ካሉት ቋሚ-loopback providers በተለየ፣ እዚህ **አንድ forward በቂ ነው**፦
የAntigravity callback የdashboard portን ራሱን ይጠቀማል፤ ስለዚህ tunnel ማድረግ
ያለብዎት ሁለተኛ provider-specific port የለም።
> ሙሉ በሙሉ headless የሆነ አማራጭ (ረዳት የሌለው፣ tunnel የሌለው)፣ የ**ራስዎን**
> Google OAuth web credentials + ይፋዊ base URL ማዋቀር ነው፤ የproviderውን OAuth
> environment variables ይመልከቱ። ከላይ ያሉት ሁለት አማራጮች ተጨማሪ የGoogle ማዋቀር አያስፈልጋቸውም።
---
## Codex / Grokን በርቀት ጭነት ላይ ማገናኘት (ቋሚ-loopback አቅራቢዎች)
Codex፣ xAI (`xai-oauth`) እና Grok CLI (`grok-cli`) ከዋናው OAuth መተግበሪያቸው ጋር **ቋሚ** loopback
`redirect_uri` ይመዘግባሉ። OmniRoute ይህን መቀየር አይችልም — አቅራቢው
ሁልጊዜ አሳሹን ወደዚያው በኮድ የተወሰነ አድራሻ ይመልሳል፦
| አቅራቢ | አቅራቢው የሚያዞርበት ቋሚ callback |
| ----------- | ------------------------------------- |
| `codex` | `http://localhost:1455/auth/callback` |
| `xai-oauth` | `http://127.0.0.1:56121/callback` |
| `grok-cli` | `http://127.0.0.1:56122/callback` |
እዚያ ያለው `localhost` ማለት **አሳሹን የሚያስኬደው ማሽን** ሲሆን፣ የOmniRoute PKCE
callback አገልጋይ ደግሞ በ**አገልጋዩ** loopback ላይ ያዳምጣል። ዳሽቦርዱን እንደ
`http://192.168.0.15:20128` ባለ LAN አድራሻ ላይ ከፈቱ፣ ሁለቱ ፈጽሞ አይገናኙም፦ የፈቃድ
ኮዱ ምንም ነገር ወደማያዳምጥበት የራስዎ ላፕቶፕ `localhost:1455` ይላካል፣
እና አቅራቢው ስህተት ሳያሳይ መግባቱን ያሰናክላል።
ዳሽቦርዱ popupን ከመክፈቱ በፊት ይህን በመለየት፣ መግባቱ ያለምንም ማሳወቂያ እንዲከሽፍ
ከመፍቀድ ይልቅ የtunnel ትዕዛዙን ያሳያል (#8046)።
### መፍትሔ — **ሁለቱንም** ports ወደፊት ያስተላልፉ
```bash
# አሳሹን በሚያስኬደው ማሽን ላይ፦
ssh -L 20128:127.0.0.1:20128 -L 1455:127.0.0.1:1455 <user>@192.168.0.15
# ከዚያ http://localhost:20128ን ይክፈቱና Codexን ከዚያ ያገናኙ
```
ሁለት forwards ያስፈልጋሉ፣ አንዱን ብቻ ወደፊት ማስተላለፍ አሁንም አይሠራም፦
- **`20128`** (የዳሽቦርዱ port) originን ትክክለኛ-localhost ያደርገዋል፤ ይህም
OmniRoute የPKCE callback አገልጋዩን እንዲያስጀምር የሚያደርገው ነው — የLAN origin
ወደዚያ branch ፈጽሞ አይደርስም።
- **`1455`** (የአቅራቢው ቋሚ callback port) አሳሹ የሚመለስበት ቦታ
ነው፤ በtunnel በኩል ወደ አገልጋዩ loopback መድረስ አለበት።
xAI ወይም Grok CLIን ሲያገናኙ `1455`ን በ`56121`/`56122`፣ `20128`ን ደግሞ
በእርስዎ ትክክለኛ የዳሽቦርድ port ይቀይሩ። ግንኙነቱ active መሆኑን እስኪያሳይ ድረስ tunnelን
ክፍት ያድርጉት።
> **የSSH መዳረሻ የለም?** Codex እና Grok CLI የተለጠፈ tokenንም ይቀበላሉ — በconnect dialog ላይ ያለው
> **Paste API Key** / **Import auth.json** tab። ይህ መንገድ loopback
> callback ስለሌለው ከማንኛውም origin ይሠራል። Codex በተጨማሪ ቀላል access
> token ወይም የ`~/.codex/auth.json` session blobን ይቀበላል።
---
## Tokensን ማስተዳደር
```bash
omniroute tokens create --name "laptop" --scope write [--expires 30]
# ↳ secretን አንድ ጊዜ ብቻ ያትማል — አሁን ይቅዱት
omniroute tokens list # የተሸፈነ፦ id፣ name፣ scope፣ prefix፣ status፣ expiry
omniroute tokens revoke <id|prefix> # ወዲያውኑ ይሻሩ
omniroute tokens scopes # ሦስቱን scopes ያብራራል
```
የ`tokens` ትዕዛዞች **admin** credential ያስፈልጋቸዋል። Tokensን በዳሽቦርዱ ውስጥ
በ**Settings → Access Tokens** ስርም ማስተዳደር ይችላሉ (መፍጠር፣ መሻር፣ አንድ-ጊዜ-መቅዳት)።
---
## Coding CLIን ከርቀት catalog ማዋቀር
`omniroute configure` የ**active server**ን ቀጥታ model catalog ያነባል እና
በ**እርስዎ** ማሽን ላይ config ይጽፋል።
```bash
omniroute configure codex
# አቅራቢዎች፦ glm, kmc, ollamacloud, opencode-go, …
# አቅራቢ፦ glm
# Model id፦ glm/glm-5.2
# ✔ ~/.codex/glm52.config.tomlን ጽፏል
# እንዲህ ይጠቀሙበት፦ codex --profile glm52
# ከመስተጋብር ውጭ
omniroute configure codex --provider glm --model glm/glm-5.2 --name glm52
# በተደጋጋሚ የሚጠቀሙበትን model በinteractive picker አናት ላይ ያቆዩ
omniroute configure codex --provider glm --model glm/glm-5.2 --favorite --yes
```
Pickerው model IDsን ብቻ (URLsን ወይም credentialsን ፈጽሞ ሳይሆን) በአካባቢያዊው
`model-preferences.json` ፋይል ውስጥ በcontext እና CLI target ተለይተው ያቆያል። Favorites
ከቅርብ ጊዜ ምርጫዎች በፊት ይታያሉ፤ የተመረጠ modelን
ከዚያ context/target ዝርዝር ለማስወገድ `--unfavorite`ን ይጠቀሙ።
የተጻፈው profile የinference keyውን በenv var
(`OMNIROUTE_API_KEY`) ይጠቅሳል — secretው ፈጽሞ ወደ disk አይጻፍም። ለአንድ ጊዜው
መሠረታዊ Codex setup (የ`[model_providers.omniroute]` block)፣
[CODEX-CLI-CONFIGURATION.md](./CODEX-CLI-CONFIGURATION.md)ን ይመልከቱ።
### CLIን ከርቀቱ ጋር ማስጀመር (ምንም config ሳይጻፍ)
`omniroute run <target>` በተጨማሪ active contextን ያከብራል፦ የርቀቱ base URL
እና የcontext credentialው በተጀመረው process ውስጥ ብቻ ይከተታሉ።
```bash
omniroute connect 192.168.0.15
omniroute run claude --model openai/gpt-5.4 # Claude Code → ርቀት
omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p "hello"
omniroute run opencode --model glm/glm-5.2 -- run "reply OK"
# በትክክል ምን እንደሚጀመር ቅድመ-እይታ ያድርጉ (የenv KEY ስሞች ብቻ፣ values ፈጽሞ አይደሉም)፦
omniroute run codex --dry-run --json
```
Targets፦ `claude`፣ `codex`፣ `aider`፣ `goose`፣ `opencode`፣ `qwen`፣ `gemini`
(ነጠላ source፦ `bin/cli/cli-manifest.mjs`)። Qwen እና Gemini ሲወጡ
በሚወገድ ጊዜያዊ፣ የተነጠለ home ውስጥ ይሠራሉ፤ ስለዚህ ማስጀመሩ የግል tool configurationዎን
ፈጽሞ አይነካም — ወይም ወደ ውስጡ መረጃ አያፈስም።
### ለእያንዳንዱ CLI የsetup ትዕዛዞች
እያንዳንዱ የሚደገፍ CLI ርቀትን የሚያውቅ setup ትዕዛዝ አለው (ሁሉም active
contextን ወይም `--remote <url> --api-key <key>`ን ያከብራሉ)፦
| CLI | ትዕዛዝ | የሚጽፈው |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Codex | `omniroute setup-codex` | `~/.codex/<name>.config.toml` መገለጫዎች (ለእያንዳንዱ ሞዴል) |
| Claude Code | `omniroute setup-claude` | `~/.claude/profiles/<name>/settings.json` (ለእያንዳንዱ ሞዴል) |
| OpenCode | `omniroute setup-opencode` | `~/.config/opencode/opencode.json` — ሁሉንም የካታሎግ ሞዴሎች የያዘው OpenAI-ተኳኋኝ `omniroute` አቅራቢ (`opencode -m omniroute/<model>`ን ያሂዱ) |
| Cline | `omniroute setup-cline` | `~/.cline/data/{globalState,secrets}.json` (የCLI ሁነታ) + ወደ VS Code ቅጥያ ቅንብሮች የሚለጠፉትን ያትማል (OpenAI-ተኳኋኝ፣ `/v1` **የሌለበት** መሠረታዊ URL) |
| Kilo Code | `omniroute setup-kilo` | `~/.local/share/kilo/auth.json` (CLI) + የVS Code `kilocode.*` ቅንብሮች — OpenAI-ተኳኋኝ፣ `/v1` **ያለበት** መሠረታዊ URL |
| Continue | `omniroute setup-continue` | `~/.continue/config.yaml` (VS Code/JetBrains + `cn` CLI) — `provider: openai`፣ `/v1` **ያለበት** `apiBase`፣ ቁልፉ በ`${{ secrets.OMNIROUTE_API_KEY }}` በኩል |
| Cursor | `omniroute setup-cursor` | በመተግበሪያው ውስጥ የሚከተሏቸውን ደረጃዎች ያትማል (Settings → Models → `/v1` **ያለበት** Override OpenAI Base URL + ቁልፍ + ሞዴል)። የCursor ውቅር ግልጽ ያልሆነ SQLite ነው — ለውይይት ፓነል ብቻ |
| Roo Code | `omniroute setup-roo` | የRoo ማስመጫ JSON (`~/.omniroute/roo-settings.json`) ይጽፋል + `roo-cline.autoImportSettingsPath`ን ያዘጋጃል + የUI ደረጃዎችን ያትማል (OpenAI-ተኳኋኝ፣ `/v1` **ያለበት** መሠረታዊ URL) |
| Crush | `omniroute setup-crush` | `~/.config/crush/crush.json` — `openai-compat` አቅራቢ፣ `/v1` **ያለበት** `base_url`፣ ቁልፉ በ`$OMNIROUTE_API_KEY` በኩል |
| Goose | `omniroute setup-goose` | `~/.config/goose/config.yaml` (`GOOSE_PROVIDER=openai` + `/v1` **የሌለበት** `OPENAI_HOST` + `GOOSE_MODEL`) + የአካባቢ ተለዋዋጮች መመሪያ |
| Aider | `omniroute setup-aider` | `~/.aider.conf.yml` (`/v1` **የሌለበት** `openai-api-base` + `model: openai/<id>`) + የአካባቢ ተለዋዋጮች መመሪያ (`aider --message --yes`) |
| Qwen Code | `omniroute setup-qwen` | በ`~/.qwen/settings.json` ውስጥ የV4 `modelProviders.openai` ግቤት + `OMNIROUTE_API_KEY` በ`~/.qwen/.env` ውስጥ |
```bash
# OpenCode (OpenAI-ተኳኋኝ አቅራቢ፣ ሁሉም የካታሎግ ሞዴሎች፣ የርቀት VPS)
omniroute setup-opencode --remote http://192.168.0.15:20128 --api-key oma_live_xxx
omniroute setup-opencode --only glm,kimi # ተዛማጅ ሞዴሎችን ብቻ ያስቀምጡ
opencode -m omniroute/glm/glm-5.2 "..." # መጀመሪያ OMNIROUTE_API_KEYን export ያድርጉ
```
> OpenCode የበለጠ የዳበረ **plugin** ውህደትም አለው፦ `omniroute setup opencode`
> (አሁን በ`--remote` በኩል የርቀት ድጋፍ አለው) `@omniroute/opencode-plugin`ን ይጭናል።
> `setup-opencode` ቀላል ክብደት ያለው OpenAI-ተኳኋኝ አማራጭ ነው። የAPI ቁልፉ
> በ`{env:OMNIROUTE_API_KEY}` በኩል ይጠቀሳል — በፍጹም ወደ ዲስክ አይጻፍም።
>
> በOpenCode v2 ላይ በምትኩ `@omniroute/opencode-plugin-v2`ን ይጠቀሙ፦ ተመሳሳይ ካታሎግ፣
> የተለየ የጫኚ ውል። ውህደቱ ሲገናኝ ቁልፉን ከOpenCode የራሱ የምስክርነት መረጃ
> ማከማቻ ያነባል፣ ስለዚህ የርቀት መግቢያ በ`opencode.json` ውስጥ ምንም ቁልፍ
> አያስፈልገውም።
---
## አውዶችን ማስተዳደር (በአገልጋዮች መካከል መቀያየር)
**አውድ** የተቀመጠ አገልጋይ (baseUrl + ማረጋገጫ መረጃ + ወሰን) ነው። `omniroute connect`
አንድ አውድ ይፈጥርና ንቁ ያደርገዋል፤ ከዚያ በኋላ እያንዳንዱ ትእዛዝ ወደዚያ ይመራል። አውዶችን በ`omniroute contexts`
ያስተዳድሩ እና በመካከላቸው ይቀያየሩ፦
```bash
omniroute contexts list # ሁሉም አውዶች፤ ንቁው በ● ይመለከታል
omniroute contexts current # ንቁው አገልጋይ፣ የማረጋገጫ ሁኔታ እና ወሰን
```
```text
| ስም | መሠረታዊ URL | ማረጋገጫ | ወሰን | መግለጫ
● | vps | http://100.67.86.91:20128 | token | admin | የርቀት OmniRoute (…)
| default | http://localhost:20128 | ✗ | |
```
**አገልጋዮችን ይቀያይሩ** — ከዚያ በኋላ የሚሰጠው እያንዳንዱ ትእዛዝ ንቁውን አውድ ይከተላል፦
```bash
omniroute contexts use vps # → አሁን ሁሉም ትእዛዞች የርቀት VPSን ይጠቀማሉ
omniroute tokens list # (በVPS ላይ ይሠራል)
omniroute contexts use default # → ወደ localhost ተመለስ
omniroute tokens list # (በአካባቢያዊው አገልጋይ ላይ ይሠራል)
```
**አውድን በእጅ ያክሉ** (በ`connect` ፋንታ)፣ ይመርምሩት ወይም ስሙን ይቀይሩ፦
```bash
omniroute contexts add staging --url https://staging.example.com:20128 \
--access-token oma_live_xxxx --scope write --description "የሙከራ አገልጋይ"
omniroute contexts show staging # ለአንድ አውድ ሙሉ ዝርዝሮች
omniroute contexts rename staging stg
```
**አውድን ያስወግዱ** — ማረጋገጫ ይጠይቃል፤ ይህን ለመዝለል `--yes` ይጠቀሙ
(ያለበለዚያ በደህና ውድቅ ለሚያደርጉ ስክሪፕቶች / መስተጋብራዊ ላልሆኑ shells ያስፈልጋል)፦
```bash
omniroute contexts remove stg --yes
```
> `default` (localhost) ሊወገድ አይችልም። ንቁውን አውድ ማስወገድ ወደ
> `default` ይመልሳል። ጠቃሚ ምክር፦ አውድን ማስወገድ የሚያስወግደው **አካባቢያዊ** የተቀመጠውን ማረጋገጫ መረጃ ብቻ ነው —
> መዳረሻን በትክክል ለማቋረጥ ቶከኑን በአገልጋዩ ላይ በ`omniroute tokens revoke <id>` ይሻሩ።
አውዶችን **ወደ ውጭ መላክ / ከውጭ ማስገባት** (ለምሳሌ፣ በማሽኖች መካከል ለማዛወር)። አዲስ አውዶች የሚያስቀምጡት
የቁልፍ ሰንሰለት ማጣቀሻን ብቻ ነው፤ የOS ቁልፍ ሰንሰለት ሲገኝ የማረጋገጫ መረጃዎች ወደ ውጭ በሚላከው ፋይል ውስጥ አይገለበጡም፦
```bash
omniroute contexts export --out contexts.json # ነባሪ፦ stdout
omniroute contexts import contexts.json # ይተካል፤ ነባሮቹን ለማቆየት --merge
omniroute contexts migrate --yes # የቆዩ plaintext ቶከኖችን ወደ ቁልፍ ሰንሰለት ያዛውሩ
```
ጥቅም ላይ የሚውል የOS ቁልፍ ሰንሰለት በሌላቸው headless ስርዓቶች ላይ CLIው
በ`0600` ሁነታ ወደ `config.json` ይመለሳል እና የአንድ ጊዜ ማስጠንቀቂያ ያትማል። ከዚያ ተተኪ ዘዴ የተላኩ ፋይሎችን
(እና ከማዛወር በፊት ያሉ ማናቸውንም የቆዩ ውቅሮች) እንደ ምስጢራዊ መረጃ ይያዙ።
---
## ፈጣን የጫፍ-እስከ-ጫፍ ማረጋገጫ
የርቀት ቅንብርን ከባዶ ለማረጋገጥ ቀድተው ሊለጥፉት የሚችሉት የሂደት ዑደት — ይገናኙ፣ ወሰን ያለውን
ቶከን ይፍጠሩ፣ ትእዛዝን ያስተላልፉ፣ ወደ ኋላ ይቀያየሩ እና ቅንብሩን ያፍርሱ።
`192.168.0.15`ን በአገልጋይዎ host/IP (Tailscale፣ LAN ወይም ይፋዊ
`https://…` URL) ይተኩ።
```bash
# 1. ይገናኙ (የይለፍ ቃል → የአስተዳዳሪ ቶከን፣ ንቁ የሚሆን አውድ ሆኖ ይቀመጣል)
omniroute connect 192.168.0.15 # ወይም፦ --key oma_live_xxxx (የይለፍ ቃል የለም)
omniroute contexts current # የርቀት አገልጋዩን + ወሰኑን ያሳያል
# 2. ይጠቀሙበት — አሁን የአስተዳደር ትእዛዞች በርቀት አገልጋዩ ላይ ይሠራሉ
omniroute tokens create --name laptop --scope read # ይበልጥ ጠባብ ወሰን ያለው ቶከን ይፍጠሩ
omniroute tokens list # ከርቀት አገልጋዩ የመጣ የተደበቀ ዝርዝር
# 3. ወደ ኋላና ወደ ፊት ይቀያየሩ
omniroute contexts use default # → አካባቢያዊ
omniroute contexts use 192-168-0-15 # → እንደገና የርቀት (`contexts list` ላይ ያለው ስም)
# 4. ያፍርሱ። ማስታወሻ፦ `contexts remove` የሚሰርዘው አካባቢያዊውን የማረጋገጫ መረጃ ብቻ ነው —
# በአገልጋዩ ላይ ያለውን ቶከን አይሽርም። መዳረሻን በትክክል ማቋረጥ ከፈለጉ
# መጀመሪያ በአገልጋዩ በኩል ይሻሩት።
omniroute tokens revoke <id|prefix> # በአገልጋዩ ላይ መዳረሻን ያቋርጣል
omniroute contexts remove 192-168-0-15 --yes # አካባቢያዊውን አውድ ያስወግዱ (ንቁ ቢሆንም → ወደ default ይመለሳል)፣ ያለ ማረጋገጫ ጥያቄ
```
> `--yes` `contexts remove`ን መስተጋብራዊ ያልሆነ ያደርገዋል (በስክሪፕቶች/CI ውስጥ ያስፈልጋል፤
> ያለሱ መስተጋብራዊ ያልሆነ shell ተንጠልጥሎ ከመቆየት ይልቅ በደህና ውድቅ ያደርጋል)።
> **ንቁውን** አውድ ማስወገድ በራስ-ሰር ወደ `default` ይመልሳል።
---
## የደህንነት ማስታወሻዎች
- የቶክኑ ግልጽ ጽሑፍ አንድ ጊዜ ብቻ ይታያል፤ በቋሚነት የሚቀመጠው የSHA-256 ሃሽ ብቻ ነው (እንደ API ቁልፎች)።
- `omniroute connect` የመግቢያ የተደጋጋሚ የግዳጅ ሙከራ መቆለፊያን እና የኦዲት መዝገብ ማስቀመጥን እንደገና ይጠቀማል።
- ለመጓጓዣው HTTPS ወይም Tailnet መጠቀም ይመረጣል፤ ፕሮቶኮል ያልተገለጸለት አስተናጋጅ ለLAN/Tailscale ምቾት በነባሪ `http://`
ይጠቀማል — ለTLS ሙሉ `https://…` URL ያስገቡ።
- ተመራጩ የአካባቢ አውድ ፋይል `~/.omniroute/config.json` (`chmod 600`)
ሲሆን `credentialRef` ብቻ ይይዛል፤ ቶክኑ ራሱ በስርዓተ ክወናው
የቁልፍ ሰንሰለት (`keytar`) ውስጥ ይከማቻል እና በመዝገቦች ውስጥ ፈጽሞ አይታተምም። የሚሰራ
ቤተኛ የቁልፍ ሰንሰለት የሌላቸው ራስ-አልባ ጭነቶች ይኸውኑ `0600` ፋይል እንደ ግልጽ መጠባበቂያ ይጠቀማሉ እና
አንድ ጊዜ ማስጠንቀቂያ ያወጣሉ። የቁልፍ ሰንሰለት ጀርባ-አገልግሎትን ከጫኑ በኋላ
`omniroute contexts migrate --yes` ይጠቀሙ።
---
## የAPI መዳረሻ ነጥቦች (ማጣቀሻ)
| ዘዴ | መስመር | ማረጋገጫ | ወሰን |
| ------ | --------------------- | --------------- | ---------------------- |
| POST | `/api/cli/connect` | የአስተዳደር የይለፍ ቃል | — (ይፋዊ፣ በይለፍ ቃል የተገደበ) |
| GET | `/api/cli/whoami` | የመዳረሻ ቶክን | ማንበብ |
| GET | `/api/cli/tokens` | የመዳረሻ ቶክን | አስተዳዳሪ |
| POST | `/api/cli/tokens` | የመዳረሻ ቶክን | አስተዳዳሪ |
| DELETE | `/api/cli/tokens/:id` | የመዳረሻ ቶክን | አስተዳዳሪ |
ለሙሉ ንድፎች [openapi.yaml](../openapi.yaml)ን ይመልከቱ።

418
docs/i18n/am/docs/guides/SETUP_GUIDE.md Normal file
View File

@@ -0,0 +1,418 @@
# 📖 Setup Guide — OmniRoute (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/SETUP_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/SETUP_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/SETUP_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/SETUP_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/SETUP_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/SETUP_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/SETUP_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/SETUP_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/SETUP_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/SETUP_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/SETUP_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/SETUP_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/SETUP_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/SETUP_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/SETUP_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/SETUP_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/SETUP_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/SETUP_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/SETUP_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/SETUP_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/SETUP_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/SETUP_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/SETUP_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/SETUP_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/SETUP_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/SETUP_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/SETUP_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/SETUP_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/SETUP_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/SETUP_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/SETUP_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/SETUP_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/SETUP_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/SETUP_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/SETUP_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/SETUP_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/SETUP_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/SETUP_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/SETUP_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/SETUP_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/SETUP_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/SETUP_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/SETUP_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/SETUP_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/SETUP_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/SETUP_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/SETUP_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/SETUP_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/SETUP_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/SETUP_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/SETUP_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/SETUP_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/SETUP_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/SETUP_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/SETUP_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/SETUP_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/SETUP_GUIDE.md)
---
> የOmniRoute ሙሉ የማዋቀሪያ ማጣቀሻ። ለአጭር ስሪቱ፣ [README ውስጥ ያለውን ፈጣን ጅምር](../README.md#-quick-start) ይመልከቱ።
## ማውጫ
- [የመጫኛ ዘዴዎች](#install-methods)
- [የCLI መሣሪያ ውቅር](#cli-tool-configuration)
- [የፕሮቶኮል ማዋቀር (MCP + A2A)](#protocol-setup-mcp--a2a)
- [የጊዜ ገደብ ውቅር](#timeout-configuration)
- [የተከፋፈለ-ፖርት ሁነታ](#split-port-mode)
- [Void Linux (xbps-src)](#void-linux-xbps-src-template)
- [ማራገፍ](#uninstalling)
---
## የመጫኛ ዘዴዎች
### npm (የሚመከር)
```bash
npm install -g omniroute
omniroute
```
ዳሽቦርዱ በ`http://localhost:20128` ይከፈታል፣ የAPI መሠረታዊ URL ደግሞ `http://localhost:20128/v1` ነው።
### pnpm
```bash
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core
omniroute
```
> **የpnpm ተጠቃሚዎች፦** ለ`better-sqlite3` እና `@swc/core` ቤተኛ የግንባታ ስክሪፕቶችን ለማንቃት `--allow-build` ጥቆማ ያስፈልጋል። በpnpm v11 ላይ `pnpm approve-builds -g` ትዕዛዝ ለዓለም አቀፍ ጭነቶች አይደገፍም።
### Arch Linux (AUR)
```bash
yay -S omniroute-bin
systemctl --user enable --now omniroute.service
```
የ[AUR ጥቅል](https://aur.archlinux.org/packages/omniroute-bin) OmniRouteን ይጭናል፣ እንዲሁም የsystemd ተጠቃሚ አገልግሎትን ያቀርባል።
### ከምንጭ ኮድ
```bash
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
> **የWindows ማስታወሻ፦** በነባሪነት፣ የቀድሞው `%USERPROFILE%\.omniroute` ማውጫ ከሌለ OmniRoute `%APPDATA%\omniroute`ን ይጠቀማል። የተለየ የውሂብ ማውጫ አካባቢ ለመምረጥ `DATA_DIR`ን ያዘጋጁ።
> **ማስታወሻ፦** `npm install` በመጀመሪያው ማስኬድ `.env`ን ከ`.env.example` በራስ-ሰር ያመነጫል። ተከታይ ጭነቶች ነባር `.env`ን አይተኩም፤ ስለዚህ ብጁ ለውጦች ይጠበቃሉ። እንደገና ለማመንጨት፣ ዳግም ከማስኬድዎ በፊት `.env`ን ይሰርዙ።
### Docker
የCompose መገለጫዎችን እና Caddy HTTPSን ጨምሮ ለተሟላ የDocker ማዋቀር [የDocker መመሪያውን](./DOCKER_GUIDE.md) ይመልከቱ።
### የዴስክቶፕ መተግበሪያ (Electron)
OmniRoute በElectron 41 + electron-builder 26.10 ላይ የተገነባ የዴስክቶፕ መጠቅለያ ይዞ ይመጣል። የሚገኙ ስክሪፕቶች (የworkspace ሥር)፦
```bash
npm run electron:dev # ዴስክቶፕን በቀጥታ ዳግም መጫን ያስኪዱ
npm run electron:build # ለአሁኑ OS ይገንቡ (በራስ-ሰር የሚታወቅ)
npm run electron:build:win # የWindows ጫኝ (NSIS + ተንቀሳቃሽ)
npm run electron:build:mac # macOS (dmg + zip, arm64+x64)
npm run electron:build:linux # Linux (AppImage + deb + rpm)
npm run electron:smoke:packaged # የታሸገውን ግንባታ የsmoke ሙከራ ያድርጉ
```
የዴስክቶፕ ጫኞች ልቀቶች ከGitHub Releases ጋር ተያይዘዋል። ስለElectron ዝርዝር መረጃ (ፊርማ፣ IPC bridge፣ ስርጭቶች)፣ [`ELECTRON_GUIDE.md`](./ELECTRON_GUIDE.md)ን ይመልከቱ _(በኋለኛ ደረጃ የተፈጠረ)_።
### ማሳያ አልባ አገልጋይ (CI/አውቶሜሽን)
ክትትል ለማያስፈልጋቸው ማዋቀሪያዎች (Docker፣ Kubernetes፣ CI)፣ የሚከተለውን ይጠቀሙ፦
```bash
omniroute setup --non-interactive
omniroute providers test-batch
```
ከenv ተለዋዋጮች (`INITIAL_PASSWORD`፣ `OMNIROUTE_WS_BRIDGE_SECRET`፣ ወዘተ) ጋር ሲጣመር፣ ሙሉ በሙሉ በስክሪፕት ሊቆጣጠር የሚችል የOmniRoute ኢንስታንስ እንዲያስነሱ ያስችልዎታል።
### የCLI አማራጮች
| ትዕዛዝ | መግለጫ |
| ----------------------- | -------------------------------------------------------- |
| `omniroute` | አገልጋዩን ያስጀምሩ (`PORT=20128`፣ API እና ዳሽቦርድ በአንድ ፖርት ላይ) |
| `omniroute setup` | ለይለፍ ቃል እና ለመጀመሪያው አቅራቢ የሚመራ የCLI መነሻ ማዋቀር |
| `omniroute doctor` | አገልጋዩን ሳያስጀምሩ የአካባቢ ጤንነት ምርመራዎችን ያከናውኑ |
| `omniroute providers` | አቅራቢዎችን ከCLI ያግኙ፣ ይዘርዝሩ፣ ያረጋግጡ እና ይፈትሹ |
| `omniroute config` | የCLI መሣሪያ ውቅር — ውቅሮችን ይዘርዝሩ፣ ያግኙ፣ ያዘጋጁ፣ ያረጋግጡ |
| `omniroute status` | ከመስመር ውጭ የሁኔታ ዳሽቦርድ — ስሪት፣ DB፣ መሣሪያዎች፣ ውቅር |
| `omniroute logs` | የአጠቃቀም ምዝግቦችን ከAPI በቀጥታ ይልቀቁ (`--follow`ን ይደግፋል) |
| `omniroute update` | የOmniRoute ዝማኔዎችን ይፈትሹ ወይም ይተግብሩ |
| `omniroute provider` | የአቅራቢ ግንኙነቶችን ያስተዳድሩ — ያክሉ፣ ይዘርዝሩ፣ ያስወግዱ፣ ይፈትሹ፣ ነባሪ ያድርጉ |
| `omniroute --port 3000` | ዋናውን/API ፖርት ወደ 3000 ያዘጋጁ |
| `omniroute --mcp` | የMCP አገልጋይን ያስጀምሩ (stdio ማጓጓዣ) |
| `omniroute --no-open` | አሳሹን በራስ-ሰር አይክፈቱ |
| `omniroute --help` | እገዛ ያሳዩ |
ማሳያ አልባ ማዋቀርን በጥቆማዎች ወይም በአካባቢ ተለዋዋጮች በስክሪፕት መቆጣጠር ይቻላል፦
```bash
omniroute setup --non-interactive --password "$OMNIROUTE_PASSWORD"
omniroute setup --non-interactive --add-provider --provider openai --api-key "$OPENAI_API_KEY"
omniroute setup --non-interactive --add-provider --provider openai --api-key "$OPENAI_API_KEY" --test-provider
```
ዳሽቦርዱን ሳይከፍቱ የአካባቢ ምርመራዎችን ያከናውኑ፦
```bash
omniroute doctor
omniroute doctor --json
omniroute doctor --no-liveness
```
ዳሽቦርዱን ሳይከፍቱ ከSSH ወይም ከስክሪፕቶች አቅራቢዎችን ያስተዳድሩ፦
```bash
omniroute providers available
omniroute providers available --search openai
omniroute providers available --category api-key
omniroute providers list
omniroute providers test <id-or-name>
omniroute providers test-all
omniroute providers validate
```
---
## የCLI መሣሪያ ውቅር
### 1) አቅራቢዎችን ያገናኙ እና API ቁልፍ ይፍጠሩ
1. Dashboard → `Providers` ይክፈቱ እና ቢያንስ አንድ አቅራቢ (OAuth ወይም API ቁልፍ) ያገናኙ።
2. Dashboard → `Endpoints` ይክፈቱ እና API ቁልፍ ይፍጠሩ።
3. (አማራጭ) Dashboard → `Combos` ይክፈቱ እና የመጠባበቂያ ሰንሰለትዎን ያዘጋጁ።
### 2) የኮድ መጻፊያ መሣሪያዎን ያመልክቱ
```txt
መሠረታዊ URL: http://localhost:20128/v1
API ቁልፍ: [ከEndpoint ገጽ ይቅዱ]
ሞዴል: if/qwen3.8-max-preview (ወይም ማንኛውም የአቅራቢ/ሞዴል ቅድመ ቅጥያ)
```
የጽሑፍ አርታዒዎ `Authorization: Bearer ...` መላክ ካልቻለ፣ በምትኩ ቶከን የተካተተበትን ተኳኋኝነት ያለው መሠረታዊ አድራሻ ይጠቀሙ፦
```txt
መሠረታዊ URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/
የሞዴሎች URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/models
የውይይት URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/chat/completions
የOllama Tags URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/api/tags
```
ከClaude Code፣ Codex CLI፣ Cursor፣ Cline፣ OpenClaw፣ OpenCode እና ከOpenAI ጋር ተኳኋኝ ከሆኑ SDKዎች ጋር ይሠራል።
#### በ`setup-*` በራስ-ሰር ያዋቅሩ
መሠረታዊ URLን እና ቁልፉን በእጅ ከመለጠፍ ይልቅ፣ OmniRoute ከቀጥታ የሞዴል ካታሎግ በመነሳት የእያንዳንዱን መሣሪያ
የራሱን ውቅር እንዲጽፍ ያድርጉ። ለእያንዳንዱ መሣሪያ አንድ ትእዛዝ፦
```bash
omniroute setup-codex # ~/.codex/<name>.config.toml መገለጫዎች
omniroute setup-claude # ~/.claude/profiles/<name>/settings.json
omniroute setup-opencode # ~/.config/opencode/opencode.json (ከopenai ጋር ተኳኋኝ)
omniroute setup-cline # የCline CLI + VS Code ቅጥያ ቅንብሮች
omniroute setup-kilo # Kilo Code
omniroute setup-continue # ~/.continue/config.yaml (Continue / cn)
omniroute setup-cursor # የCursor ውስጠ-መተግበሪያ ደረጃዎችን ያትማል
omniroute setup-roo # የRoo Code ማስመጣት + autoImport ጠቋሚ
omniroute setup-crush # ~/.config/crush/crush.json
omniroute setup-goose # ~/.config/goose/config.yaml
omniroute setup-aider # ~/.aider.conf.yml
omniroute setup-qwen # ~/.qwen/settings.json + ~/.qwen/.env
```
እያንዳንዳቸው አካባቢያዊ መሣሪያን ከ**ሩቅ** OmniRoute ጋር ለማዋቀር `--remote <url> --api-key <key>`ን፣ እንዲሁም ቅድመ ዕይታ ለማድረግ `--dry-run`ን ይቀበላሉ። ትክክለኛው
env ተጨምሮለት እና ምንም ውቅር ሳይጻፍ CLIን ለማስጀመር፣ አጠቃላይ ማስጀመሪያውን
`omniroute run <target>` (claude, codex, aider, goose, opencode, qwen, gemini) ይጠቀሙ፤ የቀድሞዎቹ ለየመሣሪያው የተለዩ ማስጀመሪያዎች `omniroute launch` (Claude Code) እና
`omniroute launch-codex` (Codex) አሁንም ይገኛሉ።
ሙሉውን ሰንጠረዥ (እያንዳንዱ ትእዛዝ ምን እንደሚጽፍ፣ ሁሉንም flags፣ አካባቢያዊ ከሩቅ ጋር፣ የመሠረታዊ URL
`/v1` ስምምነቶች) ለማየት **[የCLI ውህደቶች](./CLI-INTEGRATIONS.md)**ን ይመልከቱ።
ለእያንዳንዱ መሣሪያ ዝርዝር ውቅር (Claude Code፣ Codex CLI፣ Cursor፣ Cline፣ OpenClaw፣ Kilo Code፣ Copilot እና ሌሎችም)፣ የተለየውን **[የCLI መሣሪያዎች መመሪያ](../reference/CLI-TOOLS.md)** ይመልከቱ።
---
## የፕሮቶኮል ማዋቀር (MCP + A2A)
### MCP ማዋቀር (የሞዴል አውድ ፕሮቶኮል)
የMCP ማጓጓዣን በstdio ሁኔታ ያስጀምሩ፦
```bash
omniroute --mcp
```
የሚመከር የማረጋገጫ ፍሰት፦
```bash
# 1. የMCP አገልጋይን ያስጀምሩ
omniroute --mcp
# 2. ከMCP ደንበኛዎ የሚከተሉትን ይጥሩ፦
omniroute_get_health # የስርዓቱን ጤንነት መመለስ አለበት
omniroute_list_combos # ንቁ combosን መመለስ አለበት
# 3. ወይም ሙሉውን የE2E ስብስብ ያሂዱ፦
npm run test:protocols:e2e
```
#### የMCP ደንበኛ ውቅር
**Claude Code፦**
```bash
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
```
**Cursor / Cline፦**
ወደ MCP ቅንብሮችዎ ያክሉ፦
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"],
"env": {}
}
}
}
```
**ሙሉ የMCP ሰነድ፦** [የMCP አገልጋይ README](../../open-sse/mcp-server/README.md) — 110 መሣሪያዎች፣ የIDE ውቅሮች፣ Python/TS/Go ደንበኞች።
### A2A ማዋቀር (ከወኪል-ወደ-ወኪል ፕሮቶኮል)
Agent Cardን ያረጋግጡ፦
```bash
curl http://localhost:20128/.well-known/agent.json
```
ተግባር ይላኩ፦
```bash
curl -X POST http://localhost:20128/a2a \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```
**ሙሉ የA2A ሰነድ፦** [የA2A አገልጋይ README](../../src/lib/a2a/README.md) — JSON-RPC 2.0፣ ክህሎቶች፣ streaming፣ የተግባር የሕይወት ዑደት።
---
## የጊዜ ገደብ ውቅር
### መሠረታዊ የጊዜ ገደቦች
ለአብዛኛዎቹ ማሰማሪያዎች፣ እነዚህ ሁለት ተለዋዋጮች ብቻ ያስፈልጉዎታል፦
| ተለዋዋጭ | ነባሪ | ዓላማ |
| ------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `REQUEST_TIMEOUT_MS` | `600000` | የላይኛው አገልግሎት ምላሽ-መጀመሪያ ጊዜ ገደብ፣ የተደበቁ Undici ጊዜ ገደቦች፣ TLS fingerprint ጥያቄዎች እና API bridge ጥያቄ/ፕሮክሲ ጊዜ ገደቦች የጋራ መነሻ ዋጋ |
| `STREAM_IDLE_TIMEOUT_MS` | `REQUEST_TIMEOUT_MS`ን ይወርሳል | OmniRoute የSSE ዥረቱን ከማቋረጡ በፊት በዥረት ቁርጥራጮች መካከል የሚፈቀደው ከፍተኛው ክፍተት |
ከቀድሞ ስሪቶች ጋር ተኳሃኝነት ተጠብቋል፦ ነባር `FETCH_TIMEOUT_MS`፣ `API_BRIDGE_PROXY_TIMEOUT_MS` እና ሌሎች የየደረጃው የጊዜ ገደብ ተለዋዋጮች አሁንም ይሠራሉ፣ እንዲሁም የጋራውን መነሻ ዋጋ ይተካሉ።
### ለአቅራቢዎች የተለዩ ማስታወሻዎች
Claude Code-ተኳሃኝ ለሆኑ የላይኛው አገልግሎቶች (`anthropic-compatible-cc-*`)፣ የአቅራቢው ወገን የንባብ ጊዜ ገደቦች ከenv ውቅርዎ ጋር እንዲጣጣሙ፣ OmniRoute የወጪውን `X-Stainless-Timeout` header ከተወሰነው fetch ጊዜ ገደብ ያመነጫል።
ከሦስተኛ ወገን Claude Code-ተኳሃኝ reverse proxyዎች ጋር፣ OmniRoute ነባሪውን `anthropic-beta` ስብስብ ጥንቃቄ የተሞላበት እንዲሆን ያደርጋል፤ እንዲሁም `Client Cache Control` በ`Auto` ላይ ሲተው፣ ደንበኛው ያቀረባቸውን `cache_control` ምልክቶች ብቻ ወደፊት ያስተላልፋል። የየግንኙነቱን "Enable redact-thinking beta" መቀያየሪያ የላይኛው አገልግሎት የተደበቁ የClaude አስተሳሰብ ዥረቶችን በተለይ ሲፈልግ ብቻ ያንቁ።
### የላቁ የጊዜ ገደብ መተኪያዎች
| ተለዋዋጭ | ነባሪ | ዓላማ |
| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------- |
| `FETCH_TIMEOUT_MS` | `REQUEST_TIMEOUT_MS`ን ይወርሳል | የምላሽ headerዎች እስኪደርሱ ድረስ ጥቅም ላይ የሚውለው የላይኛው አገልግሎት ምላሽ-መጀመሪያ ጊዜ ገደብ |
| `FETCH_HEADERS_TIMEOUT_MS` | `FETCH_TIMEOUT_MS`ን ይወርሳል | የላይኛውን አገልግሎት ምላሽ headerዎች ለመቀበል የUndici ጊዜ ገደብ |
| `FETCH_BODY_TIMEOUT_MS` | `FETCH_TIMEOUT_MS`ን ይወርሳል | በላይኛው አገልግሎት body ቁርጥራጮች መካከል ያለው የUndici ጊዜ ገደብ (`0` ያሰናክለዋል) |
| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | የUndici TCP ግንኙነት ጊዜ ገደብ |
| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | የUndici ሥራ-ፈት keep-alive socket ጊዜ ገደብ |
| `TLS_CLIENT_TIMEOUT_MS` | `FETCH_TIMEOUT_MS`ን ይወርሳል | በ`wreq-js` በኩል ለሚደረጉ TLS fingerprint ጥያቄዎች የጊዜ ገደብ |
| `API_BRIDGE_PROXY_TIMEOUT_MS` | `REQUEST_TIMEOUT_MS`ን ይወርሳል ወይም `600000` | ከAPI port ወደ dashboard port ለሚደረግ የ`/v1` ፕሮክሲ ማስተላለፍ የጊዜ ገደብ |
| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | በAPI bridge server ላይ የገቢ ጥያቄ ጊዜ ገደብ |
| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | በAPI bridge server ላይ የገቢ header ጊዜ ገደብ |
| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | በAPI bridge server ላይ የkeep-alive ጊዜ ገደብ |
| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | በAPI bridge server ላይ የsocket እንቅስቃሴ-አልባነት ጊዜ ገደብ (`0` ያሰናክለዋል) |
> **ማስታወሻ፦** ለዥረት ጥያቄዎች፣ `FETCH_TIMEOUT_MS` የግንኙነት ማዋቀርን / የመጀመሪያውን የላይኛው አገልግሎት ምላሽ መጠበቅን ብቻ ይሸፍናል። ዥረቱ ገቢር ከሆነ በኋላ፣ OmniRoute የሚያቋርጠው ትክክለኛ መቆም (`STREAM_IDLE_TIMEOUT_MS`) ወይም የUndici body እንቅስቃሴ-አልባነት (`FETCH_BODY_TIMEOUT_MS`) ሲኖር ብቻ ነው።
### የReverse Proxy ተኳሃኝነት
OmniRouteን ከNginx፣ Caddy፣ Cloudflare ወይም ሌላ reverse proxy ጀርባ የሚያስኬዱ ከሆነ፣ የproxy ጊዜ ገደቦችም ከOmniRoute stream/fetch ጊዜ ገደቦችዎ ከፍ ያሉ መሆናቸውን ያረጋግጡ።
---
## የተከፋፈለ-ፖርት ሁነታ
ለላቁ ሁኔታዎች (reverse proxy፣ የcontainer አውታረ መረብ) API እና Dashboardን በተለያዩ ፖርቶች ላይ ያስኪዱ፦
```bash
PORT=20128 DASHBOARD_PORT=20129 omniroute
# API፦ http://localhost:20128/v1
# Dashboard፦ http://localhost:20129
```
---
## የVoid Linux (xbps-src) Template
ለVoid Linux ተጠቃሚዎች `xbps-src`ን በመጠቀም native package መገንባት ይችላሉ። ይህን ክፍል እንደ `srcpkgs/omniroute/template` ያስቀምጡ፦
```bash
# የ'omniroute' Template ፋይል
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
# ለእያንዳንዱ release checksumን በሚከተለው እንደገና ይፍጠሩ፦
# curl -L -o /tmp/omniroute.tar.gz "https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" && sha256sum /tmp/omniroute.tar.gz
checksum=PLACEHOLDER_REGENERATE_PER_RELEASE
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
do_build() {
local _gyp_arch
case "$XBPS_TARGET_MACHINE" in
aarch64*) _gyp_arch=arm64 ;;
armv7*|armv6*) _gyp_arch=arm ;;
i686*) _gyp_arch=ia32 ;;
*) _gyp_arch=x64 ;;
esac
NODE_ENV=development npm ci --ignore-scripts
npm run build
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
mkdir -p "$_bs3_release"
cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
rm -rf .next/standalone/node_modules/@img
for _mod in pino-abstract-transport split2 process-warning; do
cp -r "node_modules/$_mod" .next/standalone/node_modules/
done
}
do_check() {
npm run test:unit
}
do_install() {
vmkdir usr/lib/omniroute/.next
vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
for _d in \
.next/standalone/.next/server/app/dashboard \
.next/standalone/.next/server/app/dashboard/settings \
.next/standalone/.next/server/app/dashboard/providers; do
touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
done
cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
vbin "${WRKDIR}/omniroute"
}
post_install() {
vlicense LICENSE
}
```
---
## ማራገፍ
| ትእዛዝ | ድርጊት |
| ------------------------ | ------------------------------------------------------------------------------ |
| `npm run uninstall` | የስርዓቱን መተግበሪያ ያስወግዳል፣ ነገር ግን በ`~/.omniroute` ውስጥ ያሉትን **DBዎን እና ውቅሮችዎን ያቆያል**። |
| `npm run uninstall:full` | መተግበሪያውን ያስወግዳል፣ እንዲሁም **ሁሉንም ውቅሮች፣ ቁልፎች እና databases በቋሚነት ይሰርዛል**። |
> በሁሉም ዘዴዎች ላይ ዝርዝር የማራገፍ መመሪያዎችን ለማግኘት [UNINSTALL.md](./UNINSTALL.md)ን ይመልከቱ።

189
docs/i18n/am/docs/guides/TERMUX_GUIDE.md Normal file
View File

@@ -0,0 +1,189 @@
# Termux Headless Setup (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/TERMUX_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/TERMUX_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/TERMUX_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/TERMUX_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/TERMUX_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/TERMUX_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/TERMUX_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/TERMUX_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/TERMUX_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/TERMUX_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/TERMUX_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/TERMUX_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/TERMUX_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/TERMUX_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/TERMUX_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/TERMUX_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/TERMUX_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/TERMUX_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/TERMUX_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/TERMUX_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/TERMUX_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/TERMUX_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/TERMUX_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/TERMUX_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/TERMUX_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/TERMUX_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/TERMUX_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/TERMUX_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/TERMUX_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/TERMUX_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/TERMUX_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/TERMUX_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/TERMUX_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/TERMUX_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/TERMUX_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/TERMUX_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/TERMUX_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/TERMUX_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/TERMUX_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/TERMUX_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/TERMUX_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/TERMUX_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/TERMUX_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/TERMUX_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/TERMUX_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/TERMUX_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/TERMUX_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/TERMUX_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/TERMUX_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/TERMUX_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/TERMUX_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/TERMUX_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/TERMUX_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/TERMUX_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/TERMUX_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/TERMUX_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/TERMUX_GUIDE.md)
---
OmniRoute በTermux በኩል Android ላይ headless አገልጋይ ሆኖ መስራት ይችላል። የElectron ዴስክቶፕ መተግበሪያ በTermux ውስጥ አይደገፍም፤ ነገር ግን የድር ዳሽቦርዱና ከOpenAI ጋር ተኳሃኝ የሆነው API ከአካባቢያዊ አሳሹ ወይም በተመሳሳይ አውታረ መረብ ላይ ካሉ ሌሎች መሣሪያዎች ይሰራሉ።
## ቅድመ ሁኔታዎች
Termuxን ከF-Droid ወይም ከGitHub releases ይጫኑ፤ ከዚያም ፓኬጆቹን ያዘምኑና እንደ `better-sqlite3` ላሉ ቤተኛ ጥገኞች የሚያስፈልጉትን የግንባታ መሣሪያዎች ይጫኑ።
```bash
pkg update
pkg upgrade
pkg install nodejs python build-essential git
```
> **የNode.js ስሪት፦** OmniRoute Node `>=22.22.2 <23 || >=24.0.0 <27` ይፈልጋል (በ`package.json` / `SUPPORTED_NODE_RANGE` ውስጥ ካለው `engines` ጋር ይዛመዳል)። የTermux `nodejs-lts` በተለምዶ Node 20 LTSን ይዞ ይመጣል፤ ይህም **ከእንግዲህ አይደገፍም** — በምትኩ `pkg install nodejs` (የአሁኑን) ይጫኑና `node --version` የ22.x/24.x+ መስመር እንደሚያሳይ ያረጋግጡ።
የቤተኛ ፓኬጅ ማጠናቀር ካልተሳካ፣ ከላይ ያለውን የ`pkg install` ትዕዛዝ እንደገና ያስኪዱና የOmniRoute ጭነቱን እንደገና ይሞክሩ።
## መጫን
የታተመውን የቅርብ ጊዜ ፓኬጅ በቀጥታ ያስኪዱ፦
```bash
npx -y omniroute@latest
```
እንዲሁም በስርዓቱ አቀፍ ደረጃ መጫን ይችላሉ፦
```bash
npm install -g omniroute
omniroute
```
## ማስኬድ
OmniRouteን በheadless አገልጋይ ሁነታ ያስጀምሩ፦
```bash
omniroute
```
ወይም፦
```bash
npx omniroute
```
ዳሽቦርዱ የሚያዳምጠው በ፦
```text
http://localhost:20128
```
ያንን URL በAndroid አሳሹ ውስጥ ይክፈቱ። ደንበኛ ፕሮግራሞችን በTermux ውስጥ ካስኬዱ፣ ከOpenAI ጋር ተኳሃኝ ለሆነው መሠረታዊ URL ተመሳሳዩን አስተናጋጅና ወደብ ይጠቀሙ።
## ከበስተጀርባ ማስኬድ
ለቀላል የበስተጀርባ ሂደት፦
```bash
nohup omniroute > omniroute.log 2>&1 &
```
ለማቆም፦
```bash
pkill -f omniroute
```
መሣሪያው ከተነሳ በኋላ በራስ-ሰር እንዲጀምር፣ የTermux:Boot ተጨማሪውን ይጫኑና የማስነሻ ስክሪፕት ይፍጠሩ፦
```bash
mkdir -p ~/.termux/boot
cat > ~/.termux/boot/omniroute.sh <<'EOF'
#!/data/data/com.termux/files/usr/bin/sh
cd "$HOME"
nohup omniroute > "$HOME/omniroute.log" 2>&1 &
EOF
chmod +x ~/.termux/boot/omniroute.sh
```
የAndroid የባትሪ ማመቻቸት ለረጅም ጊዜ የሚሰሩ የበስተጀርባ ሂደቶችን ሊያቆም ይችላል። አገልጋዩ መስመር ላይ እንዲቆይ የሚጠበቅ ከሆነ ለTermux የባትሪ ማመቻቸትን ያሰናክሉ።
## ከሌሎች መሣሪያዎች መድረስ
በWiFi አውታረ መረቡ ላይ የስልኩን IP አድራሻ ያግኙ፦
```bash
ip addr show wlan0
```
ከዚያም ዳሽቦርዱን ከሌላ መሣሪያ ይክፈቱ፦
```text
http://PHONE_IP:20128
```
ለምሳሌ፦
```text
http://192.168.1.50:20128
```
ስልኩንና ደንበኛውን በተመሳሳይ የታመነ አውታረ መረብ ላይ ያቆዩ። OmniRouteን ከስልኩ ውጭ ተደራሽ ካደረጉ፣ API keysንና የዳሽቦርድ ማረጋገጫን ያንቁ።
## የውሂብ ማውጫ
በነባሪነት OmniRoute በLinux ላይ ጥቅም ላይ የሚውለውን ተመሳሳይ የአገልጋይ-ወገን የውሂብ ዱካ ባህሪ በመከተል ውሂብን በTermux መነሻ ማውጫ ስር ያከማቻል። የውሂብ ጎታውን በግልጽ በተወሰነ ቦታ ለማስቀመጥ፦
```bash
export DATA_DIR="$HOME/.omniroute"
omniroute
```
## ገደቦች
- Electron በTermux ውስጥ አይሰራም።
- የስርዓት ትሪ ወይም የዴስክቶፕ ውህደት የለም።
- ይህ ዝግጅት ለአገልጋይ ብቻ ነው፦ የአሳሽ ዳሽቦርዱን ይጠቀሙ።
- ቤተኛ ጥገኞች በአካባቢው ማጠናቀር ሊያስፈልጋቸው ይችላል።
- ዝቅተኛ ማህደረ ትውስታ ያላቸው የAndroid መሣሪያዎች ያነሱ በአንድ ጊዜ የሚካሄዱ ጥያቄዎችን ሊፈልጉ ይችላሉ።
- የMITM/የስርዓት ሰርተፍኬት ባህሪያት ከTermux ውጭ በAndroid ደረጃ የtrust-store ስራ ሊያስፈልጋቸው ይችላል።
## ችግር መፍታት
### የማይደገፍ መድረክ፦ android (እያንዳንዱ ጥያቄ HTTP 500 ይመልሳል)
**ምልክት፦** `omniroute` / `omniroute serve` `✔ OmniRoute is running!` ብሎ ያትማል፤ ነገር ግን እያንዳንዱ የዳሽቦርድ ወይም API ጥያቄ ዝርዝር የሌለውን `500 Internal Server Error` ይመልሳል። `~/.omniroute/logs/application/app.log` ባዶ ሆኖ ይቆያል፣ `APP_LOG_LEVEL=debug` ጠቃሚ ነገር አያትምም፣ እና የምላሹ ይዘት የJSON ዝርዝር የሌለው ተራ ጽሑፍ (`Internal Server Error`) ነው።
**ምክንያት፦** አንዳንድ የTermux/Node ግንባታዎች `process.platform === "android"` ብለው ሪፖርት ያደርጋሉ። የNext.js `getCacheDirectory()` ያንን መድረክ አያስተናግድም፦ `~/.cache` (ወይም አጠቃላይ tmp ማውጫ) _ቀድሞውኑ_ እንዲኖር ይፈልጋል፤ አለበለዚያ instrumentation hookን በሚጭንበት ጊዜ በሚከተለው ስህተት ይወድቃል፦
```text
Error: An error occurred while loading instrumentation hook: Unsupported platform: android
```
hookው ጨርሶ ስለማይጫን፣ logging ጨርሶ አይጀምርም — 500ው ምንም መንስኤ ማወቅ የማይቻል ይመስላል። OmniRoute በAndroid/Termux ላይ ይህ probe እንዲሳካ፣ Next.js ከመጀመሩ በፊት በCLI entrypoint ውስጥ `~/.cache`ን ይፈጥራል (እንዲሁም `XDG_CACHE_HOME` ካልተዋቀረ ያዋቅረዋል)።
**የሚደገፍ መፍትሔ (ፓኬጁን ሳይቀይሩ)፦**
```bash
mkdir -p ~/.cache
omniroute serve
```
በአሁኖቹ የOmniRoute ግንባታዎች CLIው ይህን በAndroid/Termux ላይ በራስ-ሰር ያደርጋል — አዲስ `npx -y omniroute@latest` / ዓለም አቀፍ ጭነት ይህን በእጅ የሚደረግ እርምጃ መፈለግ የለበትም። ካሻሻሉ በኋላም ስህተቱን ካዩ፣ ከላይ እንዳለው `~/.cache`ን አንድ ጊዜ ይፍጠሩና እንደገና ያስጀምሩ።
`process.platform = "linux"` እንዲሆን ለማስገደድ `dist/server.js`ን **አይቀይሩ**። ይህ ዓይነቱ የፓኬጅ ለውጥ በእያንዳንዱ ዳግም ጭነት/ማሻሻያ ጊዜ ይተካል፤ የcache ማውጫው አንዴ ከተፈጠረም አያስፈልግም።
### የbetter-sqlite3 ግንባታ ስህተቶች
የTermux የግንባታ መሣሪያ ስብስብን ይጫኑ፦
```bash
pkg install nodejs python build-essential
```
ከዚያ እንደገና ያስኪዱ፦
```bash
npx -y omniroute@latest
```
### ወደቡ ቀድሞውኑ ጥቅም ላይ ነው
በነባሪው ወደብ ላይ የሚያዳምጠውን ይፈትሹ፦
```bash
ss -ltnp | grep 20128
```
አሮጌውን ሂደት ያቁሙ፦
```bash
pkill -f omniroute
```
### ዳሽቦርዱ ከሌላ መሣሪያ ሊደረስበት አይችልም
ሁለቱም መሣሪያዎች በተመሳሳይ WiFi አውታረ መረብ ላይ መሆናቸውን ያረጋግጡ፤ ከዚያም ከTermux ይፈትሹ፦
```bash
curl http://localhost:20128
```
የአካባቢ መዳረሻ የሚሰራ ሆኖ የLAN መዳረሻ ካልሰራ፣ በስልኩ ላይ የAndroid hotspot/WiFi isolationን እና ማንኛውንም firewall ወይም VPN profile ይፈትሹ።

87
docs/i18n/am/docs/guides/THINKING_BUDGET.md Normal file
View File

@@ -0,0 +1,87 @@
# Thinking Budget (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/THINKING_BUDGET.md) · 🇸🇦 [ar](../../../ar/docs/guides/THINKING_BUDGET.md) · 🇦🇿 [az](../../../az/docs/guides/THINKING_BUDGET.md) · 🇧🇬 [bg](../../../bg/docs/guides/THINKING_BUDGET.md) · 🇧🇩 [bn](../../../bn/docs/guides/THINKING_BUDGET.md) · 🇨🇿 [cs](../../../cs/docs/guides/THINKING_BUDGET.md) · 🇩🇰 [da](../../../da/docs/guides/THINKING_BUDGET.md) · 🇩🇪 [de](../../../de/docs/guides/THINKING_BUDGET.md) · 🇬🇷 [el](../../../el/docs/guides/THINKING_BUDGET.md) · 🇪🇸 [es](../../../es/docs/guides/THINKING_BUDGET.md) · 🇪🇪 [et](../../../et/docs/guides/THINKING_BUDGET.md) · 🇮🇷 [fa](../../../fa/docs/guides/THINKING_BUDGET.md) · 🇫🇮 [fi](../../../fi/docs/guides/THINKING_BUDGET.md) · 🇫🇷 [fr](../../../fr/docs/guides/THINKING_BUDGET.md) · 🇮🇪 [ga](../../../ga/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [gu](../../../gu/docs/guides/THINKING_BUDGET.md) · 🇳🇬 [ha](../../../ha/docs/guides/THINKING_BUDGET.md) · 🇮🇱 [he](../../../he/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [hi](../../../hi/docs/guides/THINKING_BUDGET.md) · 🇭🇷 [hr](../../../hr/docs/guides/THINKING_BUDGET.md) · 🇭🇺 [hu](../../../hu/docs/guides/THINKING_BUDGET.md) · 🇦🇲 [hy](../../../hy/docs/guides/THINKING_BUDGET.md) · 🇮🇩 [id](../../../id/docs/guides/THINKING_BUDGET.md) · 🇳🇬 [ig](../../../ig/docs/guides/THINKING_BUDGET.md) · 🇮🇹 [it](../../../it/docs/guides/THINKING_BUDGET.md) · 🇯🇵 [ja](../../../ja/docs/guides/THINKING_BUDGET.md) · 🇬🇪 [ka](../../../ka/docs/guides/THINKING_BUDGET.md) · 🇰🇭 [km](../../../km/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [kn](../../../kn/docs/guides/THINKING_BUDGET.md) · 🇰🇷 [ko](../../../ko/docs/guides/THINKING_BUDGET.md) · 🇱🇹 [lt](../../../lt/docs/guides/THINKING_BUDGET.md) · 🇱🇻 [lv](../../../lv/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [ml](../../../ml/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [mr](../../../mr/docs/guides/THINKING_BUDGET.md) · 🇲🇾 [ms](../../../ms/docs/guides/THINKING_BUDGET.md) · 🇲🇹 [mt](../../../mt/docs/guides/THINKING_BUDGET.md) · 🇲🇲 [my](../../../my/docs/guides/THINKING_BUDGET.md) · 🇳🇵 [ne](../../../ne/docs/guides/THINKING_BUDGET.md) · 🇳🇱 [nl](../../../nl/docs/guides/THINKING_BUDGET.md) · 🇳🇴 [no](../../../no/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [or](../../../or/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [pa](../../../pa/docs/guides/THINKING_BUDGET.md) · 🇵🇭 [phi](../../../phi/docs/guides/THINKING_BUDGET.md) · 🇵🇱 [pl](../../../pl/docs/guides/THINKING_BUDGET.md) · 🇵🇹 [pt](../../../pt/docs/guides/THINKING_BUDGET.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/THINKING_BUDGET.md) · 🇷🇴 [ro](../../../ro/docs/guides/THINKING_BUDGET.md) · 🇷🇺 [ru](../../../ru/docs/guides/THINKING_BUDGET.md) · 🇱🇰 [si](../../../si/docs/guides/THINKING_BUDGET.md) · 🇸🇰 [sk](../../../sk/docs/guides/THINKING_BUDGET.md) · 🇸🇮 [sl](../../../sl/docs/guides/THINKING_BUDGET.md) · 🇷🇸 [sr](../../../sr/docs/guides/THINKING_BUDGET.md) · 🇸🇪 [sv](../../../sv/docs/guides/THINKING_BUDGET.md) · 🇰🇪 [sw](../../../sw/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [ta](../../../ta/docs/guides/THINKING_BUDGET.md) · 🇮🇳 [te](../../../te/docs/guides/THINKING_BUDGET.md) · 🇹🇭 [th](../../../th/docs/guides/THINKING_BUDGET.md) · 🇹🇷 [tr](../../../tr/docs/guides/THINKING_BUDGET.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/THINKING_BUDGET.md) · 🇵🇰 [ur](../../../ur/docs/guides/THINKING_BUDGET.md) · 🇺🇿 [uz](../../../uz/docs/guides/THINKING_BUDGET.md) · 🇻🇳 [vi](../../../vi/docs/guides/THINKING_BUDGET.md) · 🇳🇬 [yo](../../../yo/docs/guides/THINKING_BUDGET.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/THINKING_BUDGET.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/THINKING_BUDGET.md)
---
> **ዳሽቦርድ:** ቅንብሮች → **AI** → የአስተሳሰብ በጀት
> **API:** `GET` / `PUT` `/api/settings/thinking-budget`
> **ምንጭ:** `open-sse/services/thinkingBudget.ts`
የአስተሳሰብ በጀት OmniRoute ወደ አቅራቢዎች በሚልክበት ጊዜ **የደንበኛውን የአስተሳሰብ/የምክንያታዊ ትንተና መለኪያዎች እንደገና ይጽፍ እንደሆነ** ይቆጣጠራል። መጭመቅን፣ ማዘዋወርን ወይም የጥያቄ መሸጎጫን አያበራም ወይም አያጠፋም።
## ሁነታዎች
| ሁነታ | OmniRoute የሚያደርገው | መቼ መጠቀም እንደሚገባ |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **`passthrough`** (ነባሪ) | የደንበኛውን መስኮች ሳይቀይር ይተዋል (`reasoning`፣ `reasoning_effort`፣ የClaude `thinking`፣ የGemini `thinking_config`፣ ወዘተ)። | **Codex / Desktop / ጥረትን እና የምክንያታዊ ትንተና ማጠቃለያዎችን መቆጣጠር ያለበት ማንኛውም ደንበኛ።** ደንበኛው `reasoning.summary`ን ሲጠይቅ የአስተሳሰብ ፓነሎች እንዲታዩ ያስፈልጋል። |
| **`auto`** | ወደ ዋናው አቅራቢ ከመላኩ በፊት **ሁሉንም** የአስተሳሰብ/የምክንያታዊ ትንተና መስኮች ከጥያቄው ይሰርዛል። | **አቅራቢው** ነባሪ እሴቶችን እንዲወስን ሆን ብለው ሲፈልጉ እና በደንበኛ የሚቆጣጠር አስተሳሰብ በማያስፈልግዎት ጊዜ ብቻ። “አስተሳሰብን በራስ-ሰር አሳይ” ማለት **አይደለም**። |
| **`custom`** | እያንዳንዱን ጥያቄ በቋሚ የአስተሳሰብ ቶከን በጀት ይተካል። | ለሁሉም ትራፊክ በአስተሳሰብ ቶከኖች ላይ ጥብቅ ገደብ ለማድረግ። |
| **`adaptive`** | የመልዕክት ብዛትን፣ መሣሪያዎችን እና የጥያቄውን ርዝመት በመጠቀም በጀቱን ከመሠረታዊ ጥረት ያመጣጥናል። | የደንበኛውን ዓላማ ሙሉ በሙሉ ሳያስወግዱ ቶከኖችን ለስላሳ ቁጥጥር ለማድረግ። |
### `auto` የሚያስወግደው
ሁነታው `auto` ሲሆን፣ `stripThinkingConfig()` ከሌሎች ጋር የሚከተሉትን ይሰርዛል፦
- OpenAI / Responses: `reasoning`፣ `reasoning_effort`
- Claude: `thinking`፣ እንዲሁም በሚገኝበት ጊዜ `output_config.effort`
- Gemini: `generationConfig.thinking_config` / `thinkingConfig`
አንድ ደንበኛ (ለምሳሌ Codex Desktop) `reasoning: { effort: "ultra", summary: "detailed" }` ከላከ፣ **auto ያንን ኦብጀክት ያስወግዳል**። ዋናው አቅራቢ አሁንም ለአንዳንድ የምክንያታዊ ትንተና ቶከኖች ክፍያ ሊያስከፍል ይችላል፣ ነገር ግን ብዙውን ጊዜ **ባዶ ወይም የተመሰጠሩ-ብቻ** የሆኑ የምክንያታዊ ትንተና ንጥሎችን ይመልሳል — ስለዚህ UIው ጠቃሚ የአስተሳሰብ ዥረት አያሳይም።
## ይህ **ያልሆነው**
| ባህሪ | ግንኙነት |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **መጭመቅ** (Caveman፣ RTK፣ stacked፣ …) | የተለየ የሂደት መስመር ነው። በሁሉም የአስተሳሰብ-በጀት ሁነታዎች ስር ይሰራል። |
| **የጥያቄ / የፍቺ መሸጎጫ** | የተለየ ነው። በአስተሳሰብ-በጀት ሁነታ አይጎዳም። |
| **ጥምር ማዘዋወር / አማራጭ መንገዶች** | የተለየ ነው። አይጎዳም። |
| **የAPI ቁልፍ ቶከን ገደቦች / የወጪ በጀቶች** | የተለየ ነው። አይጎዳም። |
| **የምክንያታዊ ትንተና መልሶ ማጫወቻ መሸጎጫ** | ለጥብቅ አቅራቢዎች (DeepSeek፣ Kimi፣ Qwen-thinking፣ …) ባለብዙ-ዙር ዳግም ማስገባት። ከDesktop “አስተሳሰብን አሳይ” ጋር ተመሳሳይ አይደለም። |
| **`encrypted_content`ን መፍታት** | **የማይቻል ነው።** የOpenAI/Codex የግል የምክንያታዊ ትንተና ብሎቦች የማይነበቡ ናቸው። OmniRoute ፈጽሞ አይፈታቸውም (#7095 / #7176 / #7304)። |
## የሚታይ አስተሳሰብ (Codex / Responses ደንበኞች)
አንድ ደንበኛ የአስተሳሰብ ጽሑፍን እንዲያሳይ **እነዚህ ሁሉ** ያስፈልጋሉ፦
1. Thinking Budget ሁነታ = **`passthrough`** (ወይም ለሚጠቀሙበት መንገድ የማጠቃለያ ጥያቄዎችን በበቂ ሁኔታ ሳይቀይር የሚያስቀር custom/adaptive)።
2. ደንበኛው ማጠቃለያ መጠየቅ አለበት፣ ለምሳሌ Codex `model_reasoning_summary = "detailed"` / `auto` (`none` ሳይሆን)።
3. Upstream በተጨባጭ `response.reasoning_summary_text.*` በዥረት ማስተላለፍ አለበት (ወይም በንጥሉ ላይ ባዶ ያልሆነ `reasoning.summary` መኖር አለበት)።
“የተመሰጠረ የግል አስተሳሰብ” ብቻ ከደረሰዎት፣ ምክንያቱ ከሚከተሉት አንዱ ነው፦
- ሁነታው **`auto`** ነበር (የደንበኛው ጥያቄ ተወግዷል)፣ ወይም
- Upstream ያለ ማጠቃለያ ጽሑፍ `encrypted_content` መልሷል (የአቅራቢ ገደብ፤ OmniRoute ማሳየት የሚችለው ቦታ ያዥ ብቻ ነው፣ ግልጽ ጽሑፍን አይደለም)።
## የAPI ምሳሌዎች
```bash
# አንብብ
curl -sS https://localhost:20128/api/settings/thinking-budget \
-H "Authorization: Bearer $OMNIROUTE_TOKEN"
# ለCodex / Desktop የአስተሳሰብ ታይነት የሚመከር
curl -sS -X PUT https://localhost:20128/api/settings/thinking-budget \
-H "Authorization: Bearer $OMNIROUTE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"mode":"passthrough","customBudget":10240,"effortLevel":"medium"}'
```
Schema (`updateThinkingBudgetSchema`)፦ `mode` ∈ `passthrough|auto|custom|adaptive`፤ አማራጭ `customBudget`፣ `effortLevel`፣ `baseBudget`፣ `complexityMultiplier`።
### ቋሚነት / ዳግም ማስጀመር
እሴቱ `thinkingBudget` በተባለው የቅንብሮች ቁልፍ ስር ይከማቻል፣ እና ሂደቱ ሲጀምር ይጫናል (`hydrateThinkingBudgetConfig`)። በDB ወይም API ባልሆኑ አንዳንድ መንገዶች ከቀየሩት በኋላ፣ በማህደረ ትውስታ ያለው singleton በዲስክ ላይ ካለው ጋር እንዲዛመድ **የOmniRoute ሂደቱን ዳግም ያስጀምሩ**።
## የኦፕሬተር ማረጋገጫ ዝርዝር
- [ ] Codex / Desktop ተጠቃሚዎች፦ ሁነታ = **passthrough**
- [ ] አስተሳሰብን በማስወገድ ሳይሆን በ**መልዕክቶች** ላይ የቶከን ቁጠባ ከፈለጉ Compression እንደነቃ ይቆይ
- [ ] `auto` “የበለጠ አስተሳሰብ እንዲያሳይ” አይጠብቁ
- [ ] የተመሰጠሩ-ብቻ ማጠቃለያዎች የ**አቅራቢ** ባህሪ ናቸው፤ passthrough ዲክሪፕት ሊያደርጋቸው አይችልም
## ተዛማጅ ሰነዶች
- [REASONING_REPLAY.md](../routing/REASONING_REPLAY.md) — ባለብዙ-ዙር `reasoning_content` መሸጎጫ
- [USER_GUIDE.md](./USER_GUIDE.md) — የቅንብሮች ዳሽቦርድ ትሮች
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — የቅንብሮች መዳረሻዎች

107
docs/i18n/am/docs/guides/TIERS.md Normal file
View File

@@ -0,0 +1,107 @@
# OmniRoute Tiers — User Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/TIERS.md) · 🇸🇦 [ar](../../../ar/docs/guides/TIERS.md) · 🇦🇿 [az](../../../az/docs/guides/TIERS.md) · 🇧🇬 [bg](../../../bg/docs/guides/TIERS.md) · 🇧🇩 [bn](../../../bn/docs/guides/TIERS.md) · 🇨🇿 [cs](../../../cs/docs/guides/TIERS.md) · 🇩🇰 [da](../../../da/docs/guides/TIERS.md) · 🇩🇪 [de](../../../de/docs/guides/TIERS.md) · 🇬🇷 [el](../../../el/docs/guides/TIERS.md) · 🇪🇸 [es](../../../es/docs/guides/TIERS.md) · 🇪🇪 [et](../../../et/docs/guides/TIERS.md) · 🇮🇷 [fa](../../../fa/docs/guides/TIERS.md) · 🇫🇮 [fi](../../../fi/docs/guides/TIERS.md) · 🇫🇷 [fr](../../../fr/docs/guides/TIERS.md) · 🇮🇪 [ga](../../../ga/docs/guides/TIERS.md) · 🇮🇳 [gu](../../../gu/docs/guides/TIERS.md) · 🇳🇬 [ha](../../../ha/docs/guides/TIERS.md) · 🇮🇱 [he](../../../he/docs/guides/TIERS.md) · 🇮🇳 [hi](../../../hi/docs/guides/TIERS.md) · 🇭🇷 [hr](../../../hr/docs/guides/TIERS.md) · 🇭🇺 [hu](../../../hu/docs/guides/TIERS.md) · 🇦🇲 [hy](../../../hy/docs/guides/TIERS.md) · 🇮🇩 [id](../../../id/docs/guides/TIERS.md) · 🇳🇬 [ig](../../../ig/docs/guides/TIERS.md) · 🇮🇹 [it](../../../it/docs/guides/TIERS.md) · 🇯🇵 [ja](../../../ja/docs/guides/TIERS.md) · 🇬🇪 [ka](../../../ka/docs/guides/TIERS.md) · 🇰🇭 [km](../../../km/docs/guides/TIERS.md) · 🇮🇳 [kn](../../../kn/docs/guides/TIERS.md) · 🇰🇷 [ko](../../../ko/docs/guides/TIERS.md) · 🇱🇹 [lt](../../../lt/docs/guides/TIERS.md) · 🇱🇻 [lv](../../../lv/docs/guides/TIERS.md) · 🇮🇳 [ml](../../../ml/docs/guides/TIERS.md) · 🇮🇳 [mr](../../../mr/docs/guides/TIERS.md) · 🇲🇾 [ms](../../../ms/docs/guides/TIERS.md) · 🇲🇹 [mt](../../../mt/docs/guides/TIERS.md) · 🇲🇲 [my](../../../my/docs/guides/TIERS.md) · 🇳🇵 [ne](../../../ne/docs/guides/TIERS.md) · 🇳🇱 [nl](../../../nl/docs/guides/TIERS.md) · 🇳🇴 [no](../../../no/docs/guides/TIERS.md) · 🇮🇳 [or](../../../or/docs/guides/TIERS.md) · 🇮🇳 [pa](../../../pa/docs/guides/TIERS.md) · 🇵🇭 [phi](../../../phi/docs/guides/TIERS.md) · 🇵🇱 [pl](../../../pl/docs/guides/TIERS.md) · 🇵🇹 [pt](../../../pt/docs/guides/TIERS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/TIERS.md) · 🇷🇴 [ro](../../../ro/docs/guides/TIERS.md) · 🇷🇺 [ru](../../../ru/docs/guides/TIERS.md) · 🇱🇰 [si](../../../si/docs/guides/TIERS.md) · 🇸🇰 [sk](../../../sk/docs/guides/TIERS.md) · 🇸🇮 [sl](../../../sl/docs/guides/TIERS.md) · 🇷🇸 [sr](../../../sr/docs/guides/TIERS.md) · 🇸🇪 [sv](../../../sv/docs/guides/TIERS.md) · 🇰🇪 [sw](../../../sw/docs/guides/TIERS.md) · 🇮🇳 [ta](../../../ta/docs/guides/TIERS.md) · 🇮🇳 [te](../../../te/docs/guides/TIERS.md) · 🇹🇭 [th](../../../th/docs/guides/TIERS.md) · 🇹🇷 [tr](../../../tr/docs/guides/TIERS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/TIERS.md) · 🇵🇰 [ur](../../../ur/docs/guides/TIERS.md) · 🇺🇿 [uz](../../../uz/docs/guides/TIERS.md) · 🇻🇳 [vi](../../../vi/docs/guides/TIERS.md) · 🇳🇬 [yo](../../../yo/docs/guides/TIERS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/TIERS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/TIERS.md)
---
OmniRoute የሚደገፉትን 352 አቅራቢዎች በ3 የኢኮኖሚ ደረጃዎች ያደራጃል። እያንዳንዱ
ጥያቄ አንዱ በተሳካ ሁኔታ ምላሽ እስኪሰጥ ድረስ በቅደም ተከተል በእነሱ ውስጥ ያልፋል — ምንም
የመጠባበቂያ ኮድ ሳይጽፉ በጣም ርካሹን ተግባራዊ ምላሽ ያገኛሉ።
## ደረጃ 1 — የደንበኝነት ምዝገባ
**አስቀድመው ክፍያ የሚፈጽሙላቸው አቅራቢዎች።** OmniRoute የኮታው ጊዜ ከማለቁ በፊት
እያንዳንዱን የኮታ ክፍል ይጠቀማል።
| አቅራቢ | ለምን ደረጃ 1 |
| ----------------------------------- | ------------------------------------------------- |
| Claude Code OAuth | Anthropic Pro/Team — ቋሚ ክፍያ፣ ብዙውን ጊዜ ጥቅም ላይ የማይውል |
| OpenAI Codex (የChatGPT ደንበኝነት ምዝገባ) | Plus/Team የCodex ኮታን ያካትታል |
| GitHub Copilot | በእያንዳንዱ ተጠቃሚ — ኮታው በየወሩ ዳግም ይጀመራል |
| Cursor IDE | የPro ዕቅድ ኮታ |
| Antigravity / Devin Desktop | አብረው የተካተቱ ኮታዎች |
**ስልት**፦ ከሞዴሉ ጥንካሬዎች ጋር ለሚስማማ ለእያንዳንዱ ጥያቄ በመጀመሪያ ወደዚህ ያስተላልፉ።
የኮታ መከታተያው እየቀረቡ ያሉ ዳግም መጀመሪያዎችን ይከታተላል፣ እና `reset-aware`
ጥምር ስልትም በዚሁ መሠረት ቅድሚያ ይሰጣል። መጀመሪያ ወደ ደረጃ 1 ለማስተላለፍ እና ኮታው
ሲያልቅ ብቻ ወደ ክፍያ ደረጃዎች ለመሸጋገር `auto/thrifty` idን ይጠቀሙ — ወይም በዕቅዱ
ውስጥ በተካተተው አቅም ላይ ለመቆየትና ካልተገኘ ጥያቄውን ዝግ ለማድረግ `auto/subscription`ን
ይጠቀሙ። [ለደንበኝነት ምዝገባ ቅድሚያ የሚሰጥ ማስተላለፍ](../routing/SUBSCRIPTION_LADDER.md)ን ይመልከቱ።
## ደረጃ 2 — ርካሽ
**ዋጋቸው ከ$1/1M ቶከኖች በታች የሆኑ በቶከን የሚከፈላቸው አቅራቢዎች።** ለከፍተኛ መጠን ሥራ
ወይም የደረጃ 1 ኮታዎች ገደባቸውን ከደረሱ በኋላ እንዲውሉ የተያዙ ናቸው።
| አቅራቢ | ዋጋ (ግብዓት/ውጤት) | ጥንካሬዎች |
| ---------------------- | ----------------- | ----------------- |
| DeepSeek V4 Pro | $0.27 / $1.10 በ1M | ኮድ፣ ምክንያታዊ አስተሳሰብ |
| GLM-4.5 | $0.60 / $2.20 በ1M | ረጅም ዐውድ |
| MiniMax M1 | $0.20 / $1.10 በ1M | ፍጥነት |
| Qwen Coder | $0.30 / $1.20 በ1M | ኮድ |
| OpenRouter (በዋጋ የተመቻቸ) | ይለያያል | 100+ ሞዴሎች፣ ተለዋዋጭ |
**ስልት**፦ `cost-optimized` ጥምር የተግባሩን የችሎታ ማጣሪያ
(ምስል፣ JSON ሁነታ፣ መሣሪያዎች፣ ከፍተኛው ዐውድ) የሚያሟላውን ዝቅተኛው $/token ያለውን ሞዴል ይመርጣል።
## ደረጃ 3 — ነፃ
**ምንም ወጪ የሌላቸው አቅራቢዎች** — ነፃ ደረጃዎች፣ የክሬዲት ፕሮግራሞች፣ የOAuth ዕለታዊ ኮታዎች።
| አቅራቢ | ነፃ ኮታ / ክሬዲቶች |
| ---------------- | ------------------------------------ |
| Kiro AI | ነፃ የClaude ደረጃ (ለጋስ የፍትሐዊ አጠቃቀም ገደብ) |
| OpenCode Free | ማረጋገጫ አያስፈልግም፣ ለጋስ የጥያቄ ፍጥነት ገደቦች |
| Qoder | ነፃ OAuth |
| Google Vertex AI | ለአዲስ መለያ $300 ክሬዲቶች |
| Amazon Q | ለAWS ተጠቃሚዎች ነፃ ደረጃ |
| Pollinations | ክፍት ይፋዊ API |
| Cloudflare AI | የWorkers AI ነፃ ደረጃ |
**ስልት**፦ የበጀት ገደብ ያለው `auto` ጥምር ደረጃ 1+2 ሳይሳካ ሲቀር
ወይም `useFreeOnly=true` ሲዋቀር ወደዚህ ያስተላልፋል። ነፃ አቅራቢዎች ብዙውን ጊዜ ደካማ
የጥያቄ ፍጥነት ገደቦች አሏቸው — የወረዳ ቆራጩ ከቆይታ በኋላ መልሶ ያስነሳቸዋል።
## ደረጃዎችን ማዋቀር
ዳሽቦርድ → **ደረጃዎች** → አቅራቢዎችዎን ይመድቡ። ነባሪዎቹ (ከ`tierDefaults.json`) ምክንያታዊ
ናቸው፤ ቅድሚያ ሊሰጧቸው የሚፈልጓቸው የተወሰኑ የደንበኝነት ምዝገባዎች ወይም ሊያስወግዷቸው የሚፈልጓቸው አቅራቢዎች ሲኖሩ ያርትዑ።
የAuto-Combo 16-ምክንያቶች የውጤት አሰጣጥ ደረጃውንም ከግምት ውስጥ ያስገባል።
[`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md)ን ይመልከቱ።
## ቴሌሜትሪ
ዳሽቦርድ → **አጠቃቀም** በየቀኑ በእያንዳንዱ ደረጃ የወጡትን ቶከኖች ያሳያል። ይህን ለሚከተሉት ይጠቀሙ፦
- ደረጃ 1 ሙሉ በሙሉ ጥቅም ላይ መዋሉን ያረጋግጡ (ካልሆነ የደንበኝነት ምዝገባ ዋጋን እያባከኑ ነው)
- የትኞቹ የደረጃ 2 ሞዴሎች በብዛት እንደሚመረጡ ይለዩ (ወደ 1-2 ያጠቃልሉ)
- ደረጃ 3 በሙከራ/ዳሰሳ የሥራ ጫናዎች ላይ ገንዘብ እንደሚቆጥብ ያረጋግጡ
## የተለመዱ ንድፎች
### ሙሉ በሙሉ ነፃ የሥራ ጫና
```json
{
"strategy": "auto",
"config": { "auto": { "weights": { "costInv": 0.5, "tierPriority": 0.3 } } }
}
```
በጥብቅ ወደ ደረጃ 3 ያዘነብላል፤ ደረጃ 3 የማይገኝ ከሆነ ብቻ ደረጃ 2ን ይጠቀማል።
### ለደንበኝነት ምዝገባ ቅድሚያ ከሚሰጥ ርካሽ መጠባበቂያ ጋር
```json
{
"strategy": "priority",
"targets": [
{ "provider": "claude-code-oauth", "weight": 1 },
{ "provider": "deepseek", "weight": 1 },
{ "provider": "kiro", "weight": 1 }
]
}
```
ከደረጃ 1 → ደረጃ 2 → ደረጃ 3 ጋር የሚዛመድ በግልጽ የተደረደረ ዝርዝር።

2
docs/i18n/am/docs/guides/UNINSTALL.md
View File

@@ -4,7 +4,7 @@
---
🌐 **ቋንቋዎች:** 🇺🇸 [እንግሊዝኛ](./UNINSTALL.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/guides/UNINSTALL.md) | 🇸🇦 [العربية](../i18n/ar/docs/guides/UNINSTALL.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/guides/UNINSTALL.md) | 🇧🇬 [Български](../i18n/bg/docs/guides/UNINSTALL.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/guides/UNINSTALL.md) | 🇨🇿 [Čeština](../i18n/cs/docs/guides/UNINSTALL.md) | 🇩🇰 [Dansk](../i18n/da/docs/guides/UNINSTALL.md) | 🇩🇪 [Deutsch](../i18n/de/docs/guides/UNINSTALL.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/guides/UNINSTALL.md) | 🇪🇸 [Español](../i18n/es/docs/guides/UNINSTALL.md) | 🇪🇪 [Eesti](../i18n/et/docs/guides/UNINSTALL.md) | 🇮🇷 [فارسی](../i18n/fa/docs/guides/UNINSTALL.md) | 🇫🇮 [Suomi](../i18n/fi/docs/guides/UNINSTALL.md) | 🇫🇷 [Français](../i18n/fr/docs/guides/UNINSTALL.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/guides/UNINSTALL.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/guides/UNINSTALL.md) | 🇳🇬 [Hausa](../i18n/ha/docs/guides/UNINSTALL.md) | 🇮🇱 [עברית](../i18n/he/docs/guides/UNINSTALL.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/guides/UNINSTALL.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/guides/UNINSTALL.md) | 🇭🇺 [Magyar](../i18n/hu/docs/guides/UNINSTALL.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/guides/UNINSTALL.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/guides/UNINSTALL.md) | 🇳🇬 [Igbo](../i18n/ig/docs/guides/UNINSTALL.md) | 🇮🇹 [Italiano](../i18n/it/docs/guides/UNINSTALL.md) | 🇯🇵 [日本語](../i18n/ja/docs/guides/UNINSTALL.md) | 🇬🇪 [ქართული](../i18n/ka/docs/guides/UNINSTALL.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/guides/UNINSTALL.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/guides/UNINSTALL.md) | 🇰🇷 [한국어](../i18n/ko/docs/guides/UNINSTALL.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/guides/UNINSTALL.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/guides/UNINSTALL.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/guides/UNINSTALL.md) | 🇮🇳 [मराठी](../i18n/mr/docs/guides/UNINSTALL.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/guides/UNINSTALL.md) | 🇲🇹 [Malti](../i18n/mt/docs/guides/UNINSTALL.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/guides/UNINSTALL.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/guides/UNINSTALL.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/guides/UNINSTALL.md) | 🇳🇴 [Norsk](../i18n/no/docs/guides/UNINSTALL.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/guides/UNINSTALL.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/guides/UNINSTALL.md) | 🇵🇭 [Filipino](../i18n/phi/docs/guides/UNINSTALL.md) | 🇵🇱 [Polski](../i18n/pl/docs/guides/UNINSTALL.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/guides/UNINSTALL.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/guides/UNINSTALL.md) | 🇷🇴 [Română](../i18n/ro/docs/guides/UNINSTALL.md) | 🇷🇺 [Русский](../i18n/ru/docs/guides/UNINSTALL.md) | 🇱🇰 [සිංහල](../i18n/si/docs/guides/UNINSTALL.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/guides/UNINSTALL.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/guides/UNINSTALL.md) | 🇷🇸 [Српски](../i18n/sr/docs/guides/UNINSTALL.md) | 🇸🇪 [Svenska](../i18n/sv/docs/guides/UNINSTALL.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/guides/UNINSTALL.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/guides/UNINSTALL.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/guides/UNINSTALL.md) | 🇹🇭 [ไทย](../i18n/th/docs/guides/UNINSTALL.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/guides/UNINSTALL.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/guides/UNINSTALL.md) | 🇵🇰 [اردو](../i18n/ur/docs/guides/UNINSTALL.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/guides/UNINSTALL.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/guides/UNINSTALL.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/guides/UNINSTALL.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/guides/UNINSTALL.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/guides/UNINSTALL.md)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/UNINSTALL.md) · 🇸🇦 [ar](../../../ar/docs/guides/UNINSTALL.md) · 🇦🇿 [az](../../../az/docs/guides/UNINSTALL.md) · 🇧🇬 [bg](../../../bg/docs/guides/UNINSTALL.md) · 🇧🇩 [bn](../../../bn/docs/guides/UNINSTALL.md) · 🇨🇿 [cs](../../../cs/docs/guides/UNINSTALL.md) · 🇩🇰 [da](../../../da/docs/guides/UNINSTALL.md) · 🇩🇪 [de](../../../de/docs/guides/UNINSTALL.md) · 🇬🇷 [el](../../../el/docs/guides/UNINSTALL.md) · 🇪🇸 [es](../../../es/docs/guides/UNINSTALL.md) · 🇪🇪 [et](../../../et/docs/guides/UNINSTALL.md) · 🇮🇷 [fa](../../../fa/docs/guides/UNINSTALL.md) · 🇫🇮 [fi](../../../fi/docs/guides/UNINSTALL.md) · 🇫🇷 [fr](../../../fr/docs/guides/UNINSTALL.md) · 🇮🇪 [ga](../../../ga/docs/guides/UNINSTALL.md) · 🇮🇳 [gu](../../../gu/docs/guides/UNINSTALL.md) · 🇳🇬 [ha](../../../ha/docs/guides/UNINSTALL.md) · 🇮🇱 [he](../../../he/docs/guides/UNINSTALL.md) · 🇮🇳 [hi](../../../hi/docs/guides/UNINSTALL.md) · 🇭🇷 [hr](../../../hr/docs/guides/UNINSTALL.md) · 🇭🇺 [hu](../../../hu/docs/guides/UNINSTALL.md) · 🇦🇲 [hy](../../../hy/docs/guides/UNINSTALL.md) · 🇮🇩 [id](../../../id/docs/guides/UNINSTALL.md) · 🇳🇬 [ig](../../../ig/docs/guides/UNINSTALL.md) · 🇮🇹 [it](../../../it/docs/guides/UNINSTALL.md) · 🇯🇵 [ja](../../../ja/docs/guides/UNINSTALL.md) · 🇬🇪 [ka](../../../ka/docs/guides/UNINSTALL.md) · 🇰🇭 [km](../../../km/docs/guides/UNINSTALL.md) · 🇮🇳 [kn](../../../kn/docs/guides/UNINSTALL.md) · 🇰🇷 [ko](../../../ko/docs/guides/UNINSTALL.md) · 🇱🇹 [lt](../../../lt/docs/guides/UNINSTALL.md) · 🇱🇻 [lv](../../../lv/docs/guides/UNINSTALL.md) · 🇮🇳 [ml](../../../ml/docs/guides/UNINSTALL.md) · 🇮🇳 [mr](../../../mr/docs/guides/UNINSTALL.md) · 🇲🇾 [ms](../../../ms/docs/guides/UNINSTALL.md) · 🇲🇹 [mt](../../../mt/docs/guides/UNINSTALL.md) · 🇲🇲 [my](../../../my/docs/guides/UNINSTALL.md) · 🇳🇵 [ne](../../../ne/docs/guides/UNINSTALL.md) · 🇳🇱 [nl](../../../nl/docs/guides/UNINSTALL.md) · 🇳🇴 [no](../../../no/docs/guides/UNINSTALL.md) · 🇮🇳 [or](../../../or/docs/guides/UNINSTALL.md) · 🇮🇳 [pa](../../../pa/docs/guides/UNINSTALL.md) · 🇵🇭 [phi](../../../phi/docs/guides/UNINSTALL.md) · 🇵🇱 [pl](../../../pl/docs/guides/UNINSTALL.md) · 🇵🇹 [pt](../../../pt/docs/guides/UNINSTALL.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/UNINSTALL.md) · 🇷🇴 [ro](../../../ro/docs/guides/UNINSTALL.md) · 🇷🇺 [ru](../../../ru/docs/guides/UNINSTALL.md) · 🇱🇰 [si](../../../si/docs/guides/UNINSTALL.md) · 🇸🇰 [sk](../../../sk/docs/guides/UNINSTALL.md) · 🇸🇮 [sl](../../../sl/docs/guides/UNINSTALL.md) · 🇷🇸 [sr](../../../sr/docs/guides/UNINSTALL.md) · 🇸🇪 [sv](../../../sv/docs/guides/UNINSTALL.md) · 🇰🇪 [sw](../../../sw/docs/guides/UNINSTALL.md) · 🇮🇳 [ta](../../../ta/docs/guides/UNINSTALL.md) · 🇮🇳 [te](../../../te/docs/guides/UNINSTALL.md) · 🇹🇭 [th](../../../th/docs/guides/UNINSTALL.md) · 🇹🇷 [tr](../../../tr/docs/guides/UNINSTALL.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/UNINSTALL.md) · 🇵🇰 [ur](../../../ur/docs/guides/UNINSTALL.md) · 🇺🇿 [uz](../../../uz/docs/guides/UNINSTALL.md) · 🇻🇳 [vi](../../../vi/docs/guides/UNINSTALL.md) · 🇳🇬 [yo](../../../yo/docs/guides/UNINSTALL.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/UNINSTALL.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/UNINSTALL.md)
ይህ መመሪያ OmniRouteን ከስርዓትዎ ላይ በንጽህና እንዴት ማስወገድ እንደሚችሉ ያብራራል።

436
docs/i18n/am/docs/guides/USAGE_QUOTA_GUIDE.md Normal file
View File

@@ -0,0 +1,436 @@
# Usage, Quota & Spend Tracking (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USAGE_QUOTA_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USAGE_QUOTA_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USAGE_QUOTA_GUIDE.md)
---
> **በአጭሩ**: OmniRoute የእያንዳንዱን ጥያቄ የቶከን አጠቃቀም ይከታተላል፣ ወጪውን ያሰላል፣ ለእያንዳንዱ API ቁልፍ የተወሰነውን ኮታ ያስከብራል፣ እንዲሁም ትንታኔዎችን በዳሽቦርዱ ላይ ያሳያል። ይህ መመሪያ ሁሉም ነገር እንዴት እንደሚሠራ ያብራራል።
**ምንጮች:**
- `open-sse/services/usage.ts` (~70KB) — ዋናው የአጠቃቀም ክትትል
- `src/lib/usageAnalytics.ts` (~10KB) — ለዳሽቦርዱ የሚደረግ ውሂብ ማጠቃለያ
- `src/lib/db/quotaSnapshots.ts` — ታሪካዊ የኮታ ውሂብ
- `src/lib/db/usage*.ts` — ከአጠቃቀም ጋር የተያያዙ በርካታ የውሂብ ጎታ ሞጁሎች
---
## አጠቃላይ እይታ
በOmniRoute በኩል የሚያልፍ እያንዳንዱ ጥያቄ የሚከተሉትን የሚይዝ **የአጠቃቀም መዝገብ** ያመነጫል፦
- **ማንነት**: የትኛው API ቁልፍ፣ አቅራቢ፣ ሞዴል እና combo
- **ቶከኖች**: የመጠየቂያ ቶከኖች፣ የማጠናቀቂያ ቶከኖች፣ የተሸጎጡ ቶከኖች፣ ጠቅላላ
- **ወጪ**: የUSD መጠን (ከዋጋ ውሂብ የሚሰላ)
- **ጊዜ**: መዘግየት፣ የመጀመሪያ/ማብቂያ ጊዜ ማህተሞች
- **ሁኔታ**: ስኬት፣ ስህተት፣ የፍጥነት ገደብ፣ ወዘተ።
እነዚህ መዝገቦች ወደ **ትንታኔዎች** ይጠቃለላሉ፣ እንደ **የኮታ ቅጽበታዊ መዝገቦች** በቋሚነት ይቀመጣሉ፣ እንዲሁም **ለእያንዳንዱ ቁልፍ የበጀት ገደቦችን** ለማስከበር ጥቅም ላይ ይውላሉ።
```
ጥያቄ ──▶ chatCore ──▶ usage.record() ──▶ SQLite
│
┌───────┼───────┐
▼ ▼ ▼
ትንታኔዎች ኮታ ክፍያ
(ዳሽቦርድ) (ማስከበር) (መላክ)
```
---
## የሚመዘገበው ምንድን ነው
የ`usage.ts` አገልግሎት ለእያንዳንዱ ጥያቄ **የአጠቃቀም ክስተት** ይመዘግባል፦
| መስክ | ዓይነት | ምንጭ |
| ------------------ | ------- | ---------------------------------------------------------- |
| `id` | string | በምዝገባ ወቅት የሚፈጠር UUID |
| `apiKeyId` | string | ጥያቄውን የጀመረው API ቁልፍ |
| `provider` | string | የአቅራቢ መለያ (openai፣ anthropic፣ ወዘተ) |
| `model` | string | የሞዴል መለያ (gpt-5፣ claude-opus-4-6፣ ወዘተ) |
| `comboId` | string? | በcombo በኩል ከተመራ የcombo መለያ |
| `promptTokens` | number | ከውጫዊ አቅራቢው ምላሽ |
| `completionTokens` | number | ከውጫዊ አቅራቢው ምላሽ |
| `cachedTokens` | number | በመሸጎጫው ውስጥ የተገኙ ቶከኖች (የAnthropic መጠየቂያ መሸጎጫ፣ ወዘተ) |
| `totalTokens` | number | መጠየቂያ + ማጠናቀቂያ |
| `costUsd` | number | ከዋጋ ውሂብ የሚሰላ |
| `latencyMs` | number | ከመጀመሪያ እስከ መጨረሻ ያለው የጥያቄ ቆይታ |
| `status` | enum | `success`, `error`, `rate_limited`, `timeout`, `cancelled` |
| `errorClass` | string? | ሁኔታው success ካልሆነ የስህተት ክፍል |
| `timestamp` | string | ISO 8601 UTC |
| `metadata` | object | በብጁ ተሰኪ የገባ ውሂብ |
### ቶከኖቹ ከየት ይመጣሉ
ቶከኖች ከውጫዊ አቅራቢው ምላሽ በ**ምላሽ አስተናጋጅ** ውስጥ ይወጣሉ፦
```ts
// ከ open-sse/handlers/chatCore.ts
const response = await providerExecutor.execute(provider, request);
const usage = response.usage || {
prompt_tokens: 0,
completion_tokens: 0,
cached_tokens: 0,
};
```
የአጠቃቀም ውሂብ ለማይመልሱ አቅራቢዎች (አንዳንድ የድር-cookie አቅራቢዎች)፣ OmniRoute `~4 chars per token` የሚለውን ግምታዊ ደንብ በመጠቀም ቶከኖቹን **ይገምታል** (`open-sse/services/autoCombo/pipelineRouter.ts`ን ይመልከቱ)።
### የተሸጎጡ ቶከኖች
OmniRoute `cached_tokens`ን ከ`prompt_tokens` ለይቶ ይከታተላል፣ ምክንያቱም፦
- የAnthropic መጠየቂያ መሸጎጫ ለተሸጎጡ ቶከኖች የተቀነሰ ዋጋ ያስከፍላል (ከመደበኛው 10%)
- አንዳንድ አቅራቢዎች በተለየ መንገድ ዋጋ ሊተመንላቸው የሚገባ `cache_read_input_tokens` ይመልሳሉ
- ትንታኔዎች **የመሸጎጫ ስኬት መጠን** = `cached_tokens / prompt_tokens` ማሳየት ይችላሉ
---
## የወጪ ስሌት
ወጪዎች ከLiteLLM በተመሳሰለ **የዋጋ መረጃ** (`src/lib/pricingSync.ts`) ይሰላሉ፦
| ሞዴል | ግብዓት $/1M | ውጤት $/1M | ከመሸጎጫ $/1M |
| ----------------- | --------- | -------- | ---------- |
| gpt-5 | $2.50 | $10.00 | — |
| claude-opus-4-6 | $15.00 | $75.00 | $1.50 |
| claude-sonnet-4-5 | $3.00 | $15.00 | $0.30 |
| gemini-2.5-pro | $1.25 | $10.00 | — |
የወጪ ቀመር (`src/lib/usage/costCalculator.ts`)፦
```ts
cost =
(prompt_tokens - cached_tokens) * input_price +
cached_tokens * cached_price +
completion_tokens * output_price;
```
> **ከጥያቄው የመሸጎጫ ቶከኖችን ለምን እንቀንሳለን?** የተሸጎጠው ክፍል ዋጋው ለብቻው ይሰላል፤ ለጠቅላላው ጥያቄ የግብዓት ዋጋ ማስከፈል ወጪውን ከልክ በላይ ይቆጥራል።
### የዋጋ ማመሳሰል
የዋጋ መረጃ በ`/api/pricing/sync` መጨረሻ ነጥብ አማካኝነት ከLiteLLM በራስ-ሰር ይመሳሰላል (የሚጀመረው አብሮ በተካተተው cron ተግባር እንጂ ለተጠቃሚ በሚታይ env var አይደለም)፦
```bash
# በእጅ ማስጀመሪያ
curl -X POST http://localhost:20128/api/pricing/sync
```
የዋጋ መረጃ ለሌላቸው ሞዴሎች፣ OmniRoute ውስጣዊ አማካይ ተመኖችን (ከLiteLLM የዋጋ መረጃ የተገኙ) በመጠቀም **ወጪውን ወደ መገመት** ይመለሳል።
---
## የቀን ክልል ማጠቃለያ
የ`usageAnalytics.ts` ሞጁል ከጥሬ የአጠቃቀም መረጃ የዳሽቦርድ መግብሮችን ያሰላል። 7 የጊዜ ክልሎችን ይደግፋል፦
| ክልል | የጊዜ መስኮት | የአጠቃቀም ሁኔታ |
| -------- | ----------------------- | ----------------- |
| `1d` | ያለፉት 24 ሰዓታት | የሰዓት ወጪ ጭማሪን መለየት |
| `7d` | ያለፉት 7 ቀናት | ሳምንታዊ ግምገማ |
| `30d` | ያለፉት 30 ቀናት | ወርሃዊ ክፍያ |
| `90d` | ያለፉት 90 ቀናት | የሩብ ዓመት ትንተና |
| `ytd` | ከዚህ ዓመት ጃንዋሪ 1 ጀምሮ | ዓመታዊ በጀትን መከታተል |
| `all` | ሁሉም ጊዜ | የዕድሜ ልክ ስታቲስቲክስ |
| `custom` | ተጠቃሚው የሚወስነው መጀመሪያ/መጨረሻ | ኦዲቶች፣ ጊዜያዊ መጠይቆች |
### የሚሰሉ የዳሽቦርድ መግብሮች
ለማንኛውም የቀን ክልል፣ የትንታኔ ንብርብሩ የሚከተሉትን ያሰላል፦
| መግብር | መግለጫ |
| ------------------- | ---------------------------------------- |
| **የማጠቃለያ ካርዶች** | ጠቅላላ ጥያቄዎች፣ ጠቅላላ ወጪ፣ ጠቅላላ ቶከኖች፣ የስኬት መጠን |
| **የዕለታዊ አዝማሚያ ገበታ** | በቀን የሚወጣ ወጪ + ቶከኖች፣ በሞዴል ተደራርበው |
| **የእንቅስቃሴ ሙቀት ካርታ** | የቀኑ ሰዓት × የሳምንቱ ቀን ፍርግርግ፣ ቀለም = የጥያቄ ብዛት |
| **የሞዴል ዝርዝር** | የወጪ ክብ ገበታ በሞዴል |
| **የአቅራቢ ዝርዝር** | የጥያቄዎች አሞሌ ገበታ በአቅራቢ |
| **ከፍተኛ API ቁልፎች** | በወጪ ከፍተኛዎቹን 10 ቁልፎች የሚያሳይ ሰንጠረዥ |
| **የስህተት ትንተና** | በጊዜ ሂደት የስህተት መጠን፣ ዋና የስህተት ምድቦች |
### ፕሮግራማዊ መዳረሻ
````ts
import { computeAnalytics } from "@/lib/usageAnalytics";
const analytics = await computeAnalytics(
history, // የአጠቃቀም ታሪክ መዝገቦች
"7d", // የጊዜ ክልል፦ "1d" | "7d" | "30d" | "90d" | "ytd" | "all" | "custom"
connectionMap, // የአቅራቢ ግንኙነት ካርታ (connectionId → የመለያ ስም)
{
startDate: "2025-01-01", // አማራጭ፦ ለ"custom" ክልል
endDate: "2025-06-01", // አማራጭ፦ ለ"custom" ክልል
}
);
console.log(analytics.summary.totalCost); // 12.34 (ሳንቲሞች)
console.log(analytics.byModel[0]); // { model, cost, requests, promptTokens, completionTokens }
---
## የኮታ ቁጥጥር
ለእያንዳንዱ API ቁልፍ የሚደረገው የኮታ ቁጥጥር በሁለት ቦታዎች ይተገበራል፦
1. **ለስላሳ ገደብ** (`quotaWarnAt`)፦ አጠቃቀሙ ከመጠን ገደቡ ሲያልፍ በዳሽቦርዱ ላይ ማስጠንቀቂያ ይታያል
2. **ጠንካራ ገደብ** (`quotaLimit`)፦ ገደቡ ሲታለፍ ጥያቄው በ-HTTP 429 ውድቅ ይደረጋል
### ውቅር
```ts
// ለእያንዳንዱ API ቁልፍ
await updateApiKey(keyId, {
quotaWarnAt: 5_00, // $5.00 — ማስጠንቀቂያ አሳይ
quotaLimit: 10_00, // $10.00 — ሙሉ በሙሉ አቁም
quotaWindow: "month", // "day" | "week" | "month" | "all"
});
````
### የቁጥጥር ፍሰት
```
ጥያቄ ──▶ quotaCheck()
│
├── በገደቡ ውስጥ ነው? ──▶ ፍቀድ
│
└── ገደቡን አልፏል? ──▶ 429 በጣም ብዙ ጥያቄዎች
ከ-Retry-After ራስጌ ጋር
```
### የኮታ ቅጽበተ-ሁኔታዎች
`quotaSnapshots` ሰንጠረዥ ለአዝማሚያ ትንተና **ታሪካዊ የኮታ ሁኔታን** ያከማቻል፦
| መስክ | መግለጫ |
| ----------- | -------------------------------- | ------ | ------- |
| `apiKeyId` | ክትትል የሚደረግበት ቁልፍ |
| `window` | "day" | "week" | "month" |
| `used` | በዚህ ጊዜ መስኮት ውስጥ ጥቅም ላይ የዋለ ወጪ (በሳንቲም) |
| `limit` | ገደቡ (በሳንቲም) |
| `resetAt` | የጊዜ መስኮቱ ዳግም የሚጀመርበት ጊዜ |
| `createdAt` | ቅጽበተ-ሁኔታው የተወሰደበት ጊዜ |
ከ0 በላይ ወጪ በሚጠቀም **በእያንዳንዱ ጥያቄ** ላይ ቅጽበተ-ሁኔታዎች ይወሰዳሉ፣ እና ለሚከተሉት ያገለግላሉ፦
- በዳሽቦርዱ ውስጥ የኮታ ሂደት አሞሌን ማሳየት
- የ30 ቀናት የኮታ አዝማሚያ ገበታዎችን ማሳየት
- አጠቃቀሙ ወደ ገደቡ ሲቃረብ ማንቂያዎችን ማስነሳት
---
## REST API
### የአጠቃቀም መዝገቦችን ዘርዝር
```bash
GET /api/usage?range=7d&limit=100
GET /api/usage?apiKeyId=key-123&range=30d
GET /api/usage?provider=openai&range=1d
```
ምላሽ፦
```json
{
"records": [
{
"id": "uuid",
"apiKeyId": "key-123",
"provider": "openai",
"model": "gpt-5",
"promptTokens": 1234,
"completionTokens": 567,
"totalTokens": 1801,
"costUsd": 0.005,
"latencyMs": 1234,
"status": "success",
"timestamp": "2026-06-08T12:00:00Z"
}
],
"total": 1234,
"nextCursor": "..."
}
```
### የትንታኔ ማጠቃለያን አግኝ
```bash
GET /api/usage/analytics?range=7d&groupBy=model
```
ምላሽ፦
```json
{
"summary": {
"totalCost": 12.34,
"totalRequests": 5678,
"totalTokens": 12345678,
"successRate": 0.987,
"avgLatencyMs": 1234
},
"models": [
{ "model": "gpt-5", "cost": 8.5, "requests": 1234, "tokens": 4567890 },
{
"model": "claude-opus-4-6",
"cost": 3.84,
"requests": 234,
"tokens": 234567
}
],
"daily": [
{ "date": "2026-06-01", "cost": 1.5, "requests": 800 },
{ "date": "2026-06-02", "cost": 2.0, "requests": 1000 }
]
}
```
### የአጠቃቀም ትንታኔን ጠይቅ
የአጠቃቀም ውሂብ በቀጥታ በREST ወደ ውጭ መላኪያ መዳረሻዎች ሳይሆን በዳሽቦርዱ ወይም በMCP መሣሪያዎች በኩል ይደረስበታል። የሚገኙ ትንታኔዎች፦
- **`/api/usage/analytics`** — የተጠቃለሉ የአጠቃቀም መለኪያዎች (በሞዴል፣ በአቅራቢ ወይም በቁልፍ ይመድቡ)
- **`/api/usage/quota`** — ለእያንዳንዱ API ቁልፍ የአሁኑ የኮታ ሁኔታ
- **`/api/usage/history`** — የጥያቄ ታሪክ ምዝግቦች
---
## MCP መሣሪያዎች
ሁለት MCP መሣሪያዎች የአጠቃቀም ውሂብን ለወኪሎች ያቀርባሉ (`open-sse/mcp-server/tools/` ይመልከቱ)፦
| መሣሪያ | መግለጫ |
| ----------------------- | ----------------------------------- |
| `omniroute_cost_report` | ለተወሰነ ጊዜ የእያንዳንዱን ቁልፍ ወጪ ሪፖርት ያመነጫል |
| `omniroute_check_quota` | የአንድ API ቁልፍ የአሁኑን የኮታ ሁኔታ ይመልሳል |
የወኪል ጥሪ ምሳሌ፦
```json
{
"tool": "omniroute_cost_report",
"args": { "period": "week" }
}
```
---
## የማቆያ ጊዜ እና ማጽዳት
የአጠቃቀም ውሂብ በእያንዳንዱ ጥያቄ ~1-10KB ያድጋል። በትልቅ ደረጃ ይህ ከፍተኛ ሊሆን ይችላል።
### የማቆያ ቅንብሮች
የአጠቃቀም ታሪክ ማቆያ ጊዜ በUI ውስጥ ባሉት የውሂብ ጎታ ቅንብሮች ወይም በ`/api/settings/database` በኩል ይዋቀራል።
በነባሪ፣ የአጠቃቀም ታሪክ ለ**90 ቀናት** ይቆያል።
### ማጽዳት
የቆዩ መዝገቦች በ`src/lib/db/cleanup.ts` ይጸዳሉ፦
- በጀርባ በሚሠራው cron ሂደት ይጀመራል
- ከተዋቀረው `usageHistory` የማቆያ ቅንብር በላይ የቆዩ መዝገቦችን ከ`usage_history` ይሰርዛል
### የማከማቻ ግምት
| የጥያቄ መጠን | የ30 ቀናት ማከማቻ | የ90 ቀናት ማከማቻ |
| -------------- | ------------ | ------------ |
| 100 ጥያቄ/ቀን | ~3MB | ~9MB |
| 1,000 ጥያቄ/ቀን | ~30MB | ~90MB |
| 10,000 ጥያቄ/ቀን | ~300MB | ~900MB |
| 100,000 ጥያቄ/ቀን | ~3GB | ~9GB |
በጣም ከፍተኛ ትራፊክ ካለ፣ የሚከተሉትን ያስቡበት፦
- በውሂብ ጎታ ቅንብሮች በኩል የማቆያ ጊዜውን መቀነስ
- ከጥሬ መዝገቦች ይልቅ `aggregated_metrics` መጠቀም (ለትንታኔ ብቻ)
---
## ወጪን የማመቻቸት ምክሮች
### 1. ትክክለኛውን ሞዴል ይጠቀሙ
```bash
# ፈጣን መልስ — ርካሽ + ፈጣን ይጠቀሙ
curl -d '{"model":"auto/fast","messages":[...]}'
# ውስብስብ ተግባር — ጥራት ያለውን ይጠቀሙ
curl -d '{"model":"auto/smart","messages":[...]}'
```
### 2. መሸጎጫን ያንቁ
የAnthropic የጥያቄ መሸጎጫ ተደጋጋሚ አውድ ላይ **90% ይቆጥባል**፦
```ts
// መሸጎጫው ራስ-ሰር ነው — ተመሳሳዩን ትልቅ የስርዓት ጥያቄ ብቻ ያካትቱ
const response = await openai.chat({
model: "claude-sonnet-4-5",
system: longSystemPrompt, // በራስ-ሰር ይሸጎጣል
messages: [{ role: "user", content: "..." }],
});
```
### 3. መጭመቅን ይጠቀሙ
RTK + Caveman መጭመቅ፣ መሣሪያዎች በብዛት በሚጠቀሙ ክፍለ ጊዜዎች ላይ **15-95% ይቆጥባል**፦
```ts
const config = {
compression: {
engine: "rtk",
intensity: "aggressive",
},
};
```
### 4. ለእያንዳንዱ ቁልፍ ኮታ ያዘጋጁ
ከቁጥጥር ውጭ የሆኑ ወጪዎችን ለመከላከል ሁልጊዜ `quotaLimit` ያዘጋጁ፦
```ts
await updateApiKey(keyId, { quotaLimit: 10_00 }); // በወር $10 ገደብ
```
### 5. ከፍተኛ ተጠቃሚዎችን ይመርምሩ
በAPI ቁልፍ ለመመደብ እና በወጪ ለመደርደር ዳሽቦርዱን ወይም **`/api/usage/analytics`** ይጠቀሙ፦
```bash
GET /api/usage/analytics?groupBy=apiKey
```
---
## ችግር መፍታት
### "ወጪው ከተጠበቀው በላይ ነው"
1. **`/api/usage/analytics?groupBy=model`** ያረጋግጡ — ውድ የሆነውን ሞዴል ያግኙ
2. **`/api/usage/analytics?groupBy=apiKey`** ያረጋግጡ — ከፍተኛ ተጠቃሚውን ያግኙ
3. የዋጋ መረጃው ወቅታዊ መሆኑን ያረጋግጡ፦ `POST /api/pricing/sync`
### "መዝገቦች ጠፍተዋል"
- Dashboard → Database → Cleanup ስር ያሉትን የDB ማቆያ ቅንብሮች ያረጋግጡ — የቆዩ መዝገቦች በየጊዜው በሚሠራው የማጽዳት ተግባር (`src/lib/db/cleanup.ts`) ይሰረዛሉ
- በ`src/lib/db/usage*.ts` ውስጥ ስህተቶች እንዳሉ ያረጋግጡ — የDB ጽሑፍ ማስገባት አለመሳካቶች ይመዘገባሉ፣ ነገር ግን ለተጠቃሚው አይታዩም
- ጥያቄው በእርግጥ `chatCore` ላይ መድረሱን ያረጋግጡ — የcombo ማስተላለፊያን ያረጋግጡ
### "ኮታው ተግባራዊ አይሆንም"
- የቁልፉን `quotaLimit` ቅንብር ያረጋግጡ
- `quotaWindow` በትክክል መዘጋጀቱን ያረጋግጡ
- የ`quotaSnapshots` መዝገቦችን ይፈልጉ — በእያንዳንዱ ጥያቄ መፈጠር አለባቸው
---
## በተጨማሪ ይመልከቱ
- [DATABASE_GUIDE.md](../ops/DATABASE_GUIDE.md) — የአጠቃቀም ሰንጠረዦች ንድፍ
- [ENVIRONMENT.md](../reference/ENVIRONMENT.md#18-pricing-sync) — የዋጋ ማመሳሰያ env vars
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — `auto/fast`፣ `auto/cheap` ወጪን እንዴት እንደሚቀንሱ
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — ሙሉ የ`/api/usage/*` ማጣቀሻ
- ምንጭ፦ `open-sse/services/usage.ts`፣ `src/lib/usageAnalytics.ts`፣ `src/lib/db/usage*.ts`

2
docs/i18n/am/docs/guides/USER_GUIDE.md
View File

@@ -4,7 +4,7 @@
---
🌐 **ቋንቋዎች:** 🇺🇸 [English](./USER_GUIDE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/guides/USER_GUIDE.md) | 🇸🇦 [العربية](../i18n/ar/docs/guides/USER_GUIDE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/guides/USER_GUIDE.md) | 🇧🇬 [Български](../i18n/bg/docs/guides/USER_GUIDE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/guides/USER_GUIDE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/guides/USER_GUIDE.md) | 🇩🇰 [Dansk](../i18n/da/docs/guides/USER_GUIDE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/guides/USER_GUIDE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/guides/USER_GUIDE.md) | 🇪🇸 [Español](../i18n/es/docs/guides/USER_GUIDE.md) | 🇪🇪 [Eesti](../i18n/et/docs/guides/USER_GUIDE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/guides/USER_GUIDE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/guides/USER_GUIDE.md) | 🇫🇷 [Français](../i18n/fr/docs/guides/USER_GUIDE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/guides/USER_GUIDE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/guides/USER_GUIDE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/guides/USER_GUIDE.md) | 🇮🇱 [עברית](../i18n/he/docs/guides/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/guides/USER_GUIDE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/guides/USER_GUIDE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/guides/USER_GUIDE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/guides/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/guides/USER_GUIDE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/guides/USER_GUIDE.md) | 🇮🇹 [Italiano](../i18n/it/docs/guides/USER_GUIDE.md) | 🇯🇵 [日本語](../i18n/ja/docs/guides/USER_GUIDE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/guides/USER_GUIDE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/guides/USER_GUIDE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/guides/USER_GUIDE.md) | 🇰🇷 [한국어](../i18n/ko/docs/guides/USER_GUIDE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/guides/USER_GUIDE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/guides/USER_GUIDE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/guides/USER_GUIDE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/guides/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/guides/USER_GUIDE.md) | 🇲🇹 [Malti](../i18n/mt/docs/guides/USER_GUIDE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/guides/USER_GUIDE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/guides/USER_GUIDE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/guides/USER_GUIDE.md) | 🇳🇴 [Norsk](../i18n/no/docs/guides/USER_GUIDE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/guides/USER_GUIDE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/guides/USER_GUIDE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/guides/USER_GUIDE.md) | 🇵🇱 [Polski](../i18n/pl/docs/guides/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/guides/USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/guides/USER_GUIDE.md) | 🇷🇴 [Română](../i18n/ro/docs/guides/USER_GUIDE.md) | 🇷🇺 [Русский](../i18n/ru/docs/guides/USER_GUIDE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/guides/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/guides/USER_GUIDE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/guides/USER_GUIDE.md) | 🇷🇸 [Српски](../i18n/sr/docs/guides/USER_GUIDE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/guides/USER_GUIDE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/guides/USER_GUIDE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/guides/USER_GUIDE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/guides/USER_GUIDE.md) | 🇹🇭 [ไทย](../i18n/th/docs/guides/USER_GUIDE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/guides/USER_GUIDE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/guides/USER_GUIDE.md) | 🇵🇰 [اردو](../i18n/ur/docs/guides/USER_GUIDE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/guides/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/guides/USER_GUIDE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/guides/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/guides/USER_GUIDE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/guides/USER_GUIDE.md)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md)
አቅራቢዎችን ለማዋቀር፣ ጥምረቶችን ለመፍጠር፣ የCLI መሣሪያዎችን ለማቀናጀት እና OmniRouteን ለማሰማራት የተሟላ መመሪያ።

139
docs/i18n/am/docs/guides/VSCODE-COPILOT.md Normal file
View File

@@ -0,0 +1,139 @@
# VS Code Copilot Chat — OmniCopilot extension (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../guides/VSCODE-COPILOT.md) · 🇸🇦 [ar](../../../ar/docs/guides/VSCODE-COPILOT.md) · 🇦🇿 [az](../../../az/docs/guides/VSCODE-COPILOT.md) · 🇧🇬 [bg](../../../bg/docs/guides/VSCODE-COPILOT.md) · 🇧🇩 [bn](../../../bn/docs/guides/VSCODE-COPILOT.md) · 🇨🇿 [cs](../../../cs/docs/guides/VSCODE-COPILOT.md) · 🇩🇰 [da](../../../da/docs/guides/VSCODE-COPILOT.md) · 🇩🇪 [de](../../../de/docs/guides/VSCODE-COPILOT.md) · 🇬🇷 [el](../../../el/docs/guides/VSCODE-COPILOT.md) · 🇪🇸 [es](../../../es/docs/guides/VSCODE-COPILOT.md) · 🇪🇪 [et](../../../et/docs/guides/VSCODE-COPILOT.md) · 🇮🇷 [fa](../../../fa/docs/guides/VSCODE-COPILOT.md) · 🇫🇮 [fi](../../../fi/docs/guides/VSCODE-COPILOT.md) · 🇫🇷 [fr](../../../fr/docs/guides/VSCODE-COPILOT.md) · 🇮🇪 [ga](../../../ga/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [gu](../../../gu/docs/guides/VSCODE-COPILOT.md) · 🇳🇬 [ha](../../../ha/docs/guides/VSCODE-COPILOT.md) · 🇮🇱 [he](../../../he/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [hi](../../../hi/docs/guides/VSCODE-COPILOT.md) · 🇭🇷 [hr](../../../hr/docs/guides/VSCODE-COPILOT.md) · 🇭🇺 [hu](../../../hu/docs/guides/VSCODE-COPILOT.md) · 🇦🇲 [hy](../../../hy/docs/guides/VSCODE-COPILOT.md) · 🇮🇩 [id](../../../id/docs/guides/VSCODE-COPILOT.md) · 🇳🇬 [ig](../../../ig/docs/guides/VSCODE-COPILOT.md) · 🇮🇹 [it](../../../it/docs/guides/VSCODE-COPILOT.md) · 🇯🇵 [ja](../../../ja/docs/guides/VSCODE-COPILOT.md) · 🇬🇪 [ka](../../../ka/docs/guides/VSCODE-COPILOT.md) · 🇰🇭 [km](../../../km/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [kn](../../../kn/docs/guides/VSCODE-COPILOT.md) · 🇰🇷 [ko](../../../ko/docs/guides/VSCODE-COPILOT.md) · 🇱🇹 [lt](../../../lt/docs/guides/VSCODE-COPILOT.md) · 🇱🇻 [lv](../../../lv/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [ml](../../../ml/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [mr](../../../mr/docs/guides/VSCODE-COPILOT.md) · 🇲🇾 [ms](../../../ms/docs/guides/VSCODE-COPILOT.md) · 🇲🇹 [mt](../../../mt/docs/guides/VSCODE-COPILOT.md) · 🇲🇲 [my](../../../my/docs/guides/VSCODE-COPILOT.md) · 🇳🇵 [ne](../../../ne/docs/guides/VSCODE-COPILOT.md) · 🇳🇱 [nl](../../../nl/docs/guides/VSCODE-COPILOT.md) · 🇳🇴 [no](../../../no/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [or](../../../or/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [pa](../../../pa/docs/guides/VSCODE-COPILOT.md) · 🇵🇭 [phi](../../../phi/docs/guides/VSCODE-COPILOT.md) · 🇵🇱 [pl](../../../pl/docs/guides/VSCODE-COPILOT.md) · 🇵🇹 [pt](../../../pt/docs/guides/VSCODE-COPILOT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/VSCODE-COPILOT.md) · 🇷🇴 [ro](../../../ro/docs/guides/VSCODE-COPILOT.md) · 🇷🇺 [ru](../../../ru/docs/guides/VSCODE-COPILOT.md) · 🇱🇰 [si](../../../si/docs/guides/VSCODE-COPILOT.md) · 🇸🇰 [sk](../../../sk/docs/guides/VSCODE-COPILOT.md) · 🇸🇮 [sl](../../../sl/docs/guides/VSCODE-COPILOT.md) · 🇷🇸 [sr](../../../sr/docs/guides/VSCODE-COPILOT.md) · 🇸🇪 [sv](../../../sv/docs/guides/VSCODE-COPILOT.md) · 🇰🇪 [sw](../../../sw/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [ta](../../../ta/docs/guides/VSCODE-COPILOT.md) · 🇮🇳 [te](../../../te/docs/guides/VSCODE-COPILOT.md) · 🇹🇭 [th](../../../th/docs/guides/VSCODE-COPILOT.md) · 🇹🇷 [tr](../../../tr/docs/guides/VSCODE-COPILOT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/VSCODE-COPILOT.md) · 🇵🇰 [ur](../../../ur/docs/guides/VSCODE-COPILOT.md) · 🇺🇿 [uz](../../../uz/docs/guides/VSCODE-COPILOT.md) · 🇻🇳 [vi](../../../vi/docs/guides/VSCODE-COPILOT.md) · 🇳🇬 [yo](../../../yo/docs/guides/VSCODE-COPILOT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/VSCODE-COPILOT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/VSCODE-COPILOT.md)
---
**OmniCopilot** በOmniRoute የሚቀርብልዎትን እያንዳንዱን ሞዴል በGitHub Copilot Chat _ነባር_ የሞዴል መምረጫ ውስጥ ያስገባል። ሁለተኛ የጎን አሞሌ ወይም የተለየ የውይይት UI የለም — የCopilot ወኪል ሁነታ፣ የመሳሪያ ጥሪ፣
MCP ሰርቨሮች እና ብጁ መመሪያዎች ሁሉ መስራታቸውን ይቀጥላሉ፤ ልዩነቱ እርስዎ በመረጡት ሞዴል ላይ መስራታቸው ብቻ ነው።
| | |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **ጫን (VS Code)** | [Marketplace → `diegosouzapw.omnicopilot`](https://marketplace.visualstudio.com/items?itemName=diegosouzapw.omnicopilot) |
| **ጫን (forks)** | [Open VSX](https://open-vsx.org/extension/diegosouzapw/omnicopilot) — Cursor, Windsurf, VSCodium, Theia, code-server, Gitpod, Antigravity, Kiro |
| **ምንጭ / ችግሮች** | [github.com/diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot) (MIT) |
| **የሚያስፈልገው** | VS Code 1.104+ |
> **የCopilot ደንበኝነት ምዝገባ አያስፈልግም።** ከVS Code 1.122 ጀምሮ የቋንቋ-ሞዴል አቅራቢ ያለGitHub መግቢያ እና ያለማንኛውም የCopilot ዕቅድ ይሰራል። በመስመር ውስጥ የሚቀርቡ ማጠናቀቂያዎች እና
> በembeddings ላይ የተመሰረቱ ባህሪያት ከአቅራቢው API ውጭ ስለሆኑ አሁንም Copilot ያስፈልጋቸዋል።
---
## ማዋቀር
1. **OmniRouteን ያስኪዱ** — `npm install -g omniroute && omniroute` (ዳሽቦርዱ `http://localhost:20128` ላይ ነው)።
2. **ቅጥያውን ይጫኑ** — በExtensions እይታ ውስጥ "OmniRoute" ብለው ይፈልጉ።
3. **ሞዴል ይምረጡ** — Copilot Chat → የሞዴል መምረጫ → **ሞዴሎችን ያስተዳድሩ…** → **OmniRoute**፣ ከዚያ የሚፈልጉትን ምልክት ያድርጉበት።
OmniRoute በነባሪው ወደብ ላይ ሲሰራ የሚዋቀር ነገር የለም። ለርቀት ምሳሌ፣
**በActivity Bar ውስጥ ያለውን የOmniRoute አዶ ይክፈቱ** (ወይም `OmniRoute: Manage Connection`ን ያስኪዱ) እና የሚከተሉትን ያዋቅሩ፦
- **የሰርቨር URL** — የሰርቨሩ ስር፣ ለምሳሌ `http://192.168.0.15:20128`። የ`/v1` ቅጥያ
በቅጥያው በራስ-ሰር ይጨመራል፤ እርስዎ አያካትቱት።
- **የAPI ቁልፍ** — ሰርቨሩ `REQUIRE_API_KEY`ን ሲያዘጋጅ ብቻ። በVS
Code SecretStorage በኩል በስርዓተ ክወናው የቁልፍ ማከማቻ ውስጥ ይቀመጣል፤ በ`settings.json` ውስጥ ፈጽሞ አይቀመጥም።
---
## መምረጫው የሚያሳየው
ቅጥያው ጥሬውን የ`GET /v1/models` ውሂብ አያሳይም — ቅርጽ ይሰጠዋል፣ እና የሚያዩት ብዛት
ከካታሎጉ መጠን ያነሰ የሚሆነው ሆን ተብለው በተደረጉ ሁለት ምክንያቶች ነው።
### ለእያንዳንዱ ሞዴል አንድ id ይጠይቃል
`MODELS_CATALOG_PREFIX_MODE` በነባሪ **`dual`** ነው፣ ይህም እያንዳንዱን ሞዴል ሁለት ጊዜ ያስተዋውቃል — አንድ ጊዜ
በአጭሩ ተለዋጭ ቅድመ ቅጥያ እና አንድ ጊዜ በመደበኛው የአቅራቢ ቅድመ ቅጥያ — ስለዚህ የቆዩ የደንበኛ
ውቅሮች ከሁለቱም ቅርጾች ማናቸውንም ማግኘት ይቀጥላሉ፦
```
cc/claude-sonnet-4-6 ← ተለዋጭ ቅድመ ቅጥያ
claude/claude-sonnet-4-6 ← መደበኛ ቅድመ ቅጥያ፣ ተመሳሳይ ሞዴል
```
ቅጥያው **`GET /v1/models?prefix=alias`**ን ይጠይቃል፤ በዚህም ለሌሎች ደንበኞችዎ በሰርቨር ደረጃ ያለውን ቅንብር ሳይቀይር
ለእያንዳንዱ ሞዴል አንድ id ይመጣል። በማጣቀሻ ምሳሌ ላይ ይህ
**2345 ግቤቶችን ወደ 1396 አሳንሷል — 949 ድግግሞሾች፣ የጠፋ ሞዴል ዜሮ።**
በምትኩ ይህን በሰርቨር ደረጃ ለ_እያንዳንዱ_ ደንበኛ ማስተካከል ከፈለጉ፣ በዳሽቦርዱ ውስጥ የ
`MODELS_CATALOG_PREFIX_MODE` ባህሪ ጠቋሚን ወደ `alias` ያዘጋጁ። ለመጠይቅ
መለኪያው እና ለእያንዳንዱ ሁነታ ሰንጠረዥ [API_REFERENCE → prefix](../reference/API_REFERENCE.md#model-id-prefixes-prefix)ን ይመልከቱ።
### መወያየት የማይችሉ ሞዴሎችን ይደብቃል
ካታሎጉ የምስል፣ ቪዲዮ፣ ድምፅ፣ ዳግም ደረጃ ሰጪ፣ embedding እና የይዘት ክትትል ሞዴሎችንም ይዘረዝራል። እነዚህ
በውይይት ጥያቄ ላይ ለማንኛውም ውድቅ ይደረጋሉ፦
```
HTTP 400 — ሞዴል '<id>' የምስል-ማመንጫ ሞዴል ስለሆነ በ
/v1/chat/completions ላይ ጥቅም ላይ ሊውል አይችልም። በምትኩ POST /v1/images/generationsን ይጠቀሙ።
```
ስለዚህ ወደ መምረጫው ከመድረሳቸው በፊት በ`type` መስካቸው መሠረት ይጣራሉ። **የResponses-API
ሞዴሎች ይቀመጣሉ** — እያንዳንዱ Codex / GPT-5.x ግቤት `supported_endpoints: ["responses"]`ን ያስተዋውቃል፣
እና OmniRoute እነዚያን ለ`/v1/chat/completions` ይተረጉማል፣ ስለዚህ ሙሉ በሙሉ ጥቅም ላይ ሊውሉ ይችላሉ።
### ፈጽሞ ያላዋቀሯቸው አቅራቢዎች
ካታሎጉ **ንቁ ግንኙነት** ካላቸው አቅራቢዎች የመጡ ሞዴሎችን _እና_ ሁሉንም **noAuth**
አቅራቢዎችን — የነፃውን ደረጃ አብዛኛውን የሚያካትቱ ቁልፍ አልባ አቅራቢዎችን — ይዘረዝራል። ይህ ሆን ተብሎ የተደረገ ነው። እነሱን ለመደበቅ
በዳሽቦርዱ ቅንብሮች ውስጥ ወደ `blockedProviders` ያክሏቸው፤ በቅጥያው ውስጥ ምንም ነገር አይቀየርም።
---
## በVS Code ትር ውስጥ ያለ Dashboard
`omnicopilot.dashboardOpen: "editor"` የOmniRoute dashboardን በውጫዊ browser ፈንታ በSimple Browser በኩል በeditor ትር ውስጥ ያሳያል። ማካተት **በserver ላይ በምርጫ የሚነቃ** ሲሆን፣ ይህም በ`DASHBOARD_ALLOW_EMBED=vscode` ይከናወናል፤ የHTML ገጾቹን በነባሪው `frame-ancestors 'none'` +
`X-Frame-Options: DENY` ፈንታ በ`frame-ancestors 'self' vscode-webview:` ያቀርባል። የAPI ወሰን (`/api`፣ `/v1`፣ `/v1beta`፣ `/a2a`፣ `/healthz`) በሁለቱም ሁኔታዎች ጥብቅ headersን እንዳሉ ይጠብቃል።
> ⚠️ **ይህ የbuild ጊዜ flag ነው፣ የruntime አይደለም።** Next.js `headers()`ን ወደ route
> manifest ያጠናቅራል፣ ስለዚህ bundleው በሚገነባበት ጊዜ `next.config.mjs` variableውን ያነባል
> (`next.config.mjs` → `resolveDashboardEmbedMode`፣ `scripts/build/dashboardEmbed.mjs`)።
> ቀድሞ በተገነባ server ፊት ለፊት variableውን export ማድረግ ምንም ነገር አይቀይርም — headersዎቹ በbuildው ውስጥ ተካትተዋል።
```bash
# variableው በBUILD command ላይ መኖር አለበት
DASHBOARD_ALLOW_EMBED=vscode npm run build # ወይም npm run build:release
npm start
```
| እንዴት እንደጫኑት | ማካተትን ማንቃት ይችላሉ? |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| ከsource | ✅ ከላይ እንደተገለጸው variableውን በbuild command ላይ ያዘጋጁ |
| `npm install -g omniroute` | ❌ የታተመው package ቀድሞ የተገነባ bundle ይዞ ይመጣል — በምትኩ ከsource ይገንቡ |
| Docker image | ✅ `docker build --build-arg DASHBOARD_ALLOW_EMBED=vscode -t omniroute:embed .` — በDocker Hub ላይ ያለው ቀድሞ የተገነባ image ማካተት የነቃበት አይደለም |
ማካተት የነቃበት build ከሌለ ገጹ በframe ውስጥ መታየትን ይከለክላል፤ extensionው ይህንን ከresponse headers ይለያል እና ወደ ውጫዊ browser ይመለሳል — ምንም ነገር አይበላሽም፣ እና ይህንን አንድ ጊዜ ያሳውቃል።
[`ENVIRONMENT.md`](../reference/ENVIRONMENT.md)ን እና issue
[#10273](https://github.com/diegosouzapw/OmniRoute/issues/10273)ን ይመልከቱ።
---
## ሌሎች toolsዎን ከVS Code ውስጥ ማዋቀር
**`OmniRoute: Configure Coding CLI`** ለCodex CLI፣ Claude Code፣ Cline፣ Continue፣ Cursor፣ Aider፣ OpenCode፣ Goose፣ Crush፣ Qwen Code፣
Kilo እና Roo ዝግጁ-ለአጠቃቀም profiles እንዲጽፍ `omniroute` CLIን ያንቀሳቅሳል — እነዚህም በ
[`CLI-INTEGRATIONS.md`](CLI-INTEGRATIONS.md) የተገለጹት ተመሳሳይ configs ናቸው። API keyው ለCLIው በ
`OMNIROUTE_API_KEY` environment variable በኩል ይሰጣል፤ በcommand line ላይ ፈጽሞ አይሰጥም።
---
## ችግር መፍታት
| ምልክት | ምክንያት / መፍትሔ |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| በpicker ውስጥ የOmniRoute models አይታዩም | Serverውን ማግኘት አልተቻለም። የstatus-bar ነጥቡ ግራጫ ይሆናል፤ `OmniRoute: Check Connection`ን ያሂዱ። Discovery ሆን ተብሎ ያለማሳወቂያ ይከናወናል፣ እና ጥያቄ ከማቅረብ ይልቅ ምንም models አያክልም። |
| እያንዳንዱ model ሁለት ጊዜ ይታያል | ከ1.0.1 በፊት የሆነ OmniCopilot እየተጠቀሙ ነው — update ያድርጉ። extensionው አሁን `?prefix=alias`ን ይጠይቃል። |
| ቀደም ሲል የነበረ image/audio model ከዝርዝሩ ጠፍቷል | ከ1.0.1 ጀምሮ ሆን ተብሎ የተደረገ ነው — የchat requestን ፈጽሞ መመለስ አይችልም ነበር። |
| Panel ከActivity Bar ጠፍቷል | VS Code ተጨማሪ view containersን በActivity Bar ግርጌ ወዳለው **"…"** overflow ያንቀሳቅሳል፣ እና በright-click የተደበቀ container እንደተደበቀ ይቆያል። Activity Barን right-click ያድርጉ → **OmniRoute**ን ምልክት ያድርጉ፣ ወይም በ`OmniRoute: Manage Connection` ይክፈቱት። |
| `editor` mode ቢሆንም Dashboard በbrowser ውስጥ ይከፈታል | Serverው በ`DASHBOARD_ALLOW_EMBED=vscode` **አልተገነባም** (ከላይ ይመልከቱ) — ቀድሞ በተገነባ install ላይ በstartup ጊዜ ማዘጋጀት ምንም አይቀይርም። fallbackው ሆን ተብሎ የተደረገ ነው። |
| providersን ከቀየሩ በኋላ የModels ዝርዝሩ አልታደሰም | `OmniRoute: Refresh Models`፣ ወይም በpanel ውስጥ ያለው ↻ link። |
---
## በተጨማሪ ይመልከቱ
- [`CLI-INTEGRATIONS.md`](CLI-INTEGRATIONS.md) — ሌሎች ሁሉም የኮድ መጻፊያ መሣሪያዎች
- [`REMOTE-MODE.md`](REMOTE-MODE.md) — የርቀት OmniRouteን መቆጣጠር
- [`../reference/API_REFERENCE.md`](../reference/API_REFERENCE.md) — የ`/v1/models` ውል
- [`docs/CATALOG.md`](https://github.com/diegosouzapw/OmniCopilot/blob/main/docs/CATALOG.md) — የቅጥያው የራሱ ካታሎግ ማስታወሻዎች

81
docs/i18n/am/docs/ops/BRANCHING_MODEL.md Normal file
View File

@@ -0,0 +1,81 @@
# Branching & Release Model (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/BRANCHING_MODEL.md) · 🇸🇦 [ar](../../../ar/docs/ops/BRANCHING_MODEL.md) · 🇦🇿 [az](../../../az/docs/ops/BRANCHING_MODEL.md) · 🇧🇬 [bg](../../../bg/docs/ops/BRANCHING_MODEL.md) · 🇧🇩 [bn](../../../bn/docs/ops/BRANCHING_MODEL.md) · 🇨🇿 [cs](../../../cs/docs/ops/BRANCHING_MODEL.md) · 🇩🇰 [da](../../../da/docs/ops/BRANCHING_MODEL.md) · 🇩🇪 [de](../../../de/docs/ops/BRANCHING_MODEL.md) · 🇬🇷 [el](../../../el/docs/ops/BRANCHING_MODEL.md) · 🇪🇸 [es](../../../es/docs/ops/BRANCHING_MODEL.md) · 🇪🇪 [et](../../../et/docs/ops/BRANCHING_MODEL.md) · 🇮🇷 [fa](../../../fa/docs/ops/BRANCHING_MODEL.md) · 🇫🇮 [fi](../../../fi/docs/ops/BRANCHING_MODEL.md) · 🇫🇷 [fr](../../../fr/docs/ops/BRANCHING_MODEL.md) · 🇮🇪 [ga](../../../ga/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [gu](../../../gu/docs/ops/BRANCHING_MODEL.md) · 🇳🇬 [ha](../../../ha/docs/ops/BRANCHING_MODEL.md) · 🇮🇱 [he](../../../he/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [hi](../../../hi/docs/ops/BRANCHING_MODEL.md) · 🇭🇷 [hr](../../../hr/docs/ops/BRANCHING_MODEL.md) · 🇭🇺 [hu](../../../hu/docs/ops/BRANCHING_MODEL.md) · 🇦🇲 [hy](../../../hy/docs/ops/BRANCHING_MODEL.md) · 🇮🇩 [id](../../../id/docs/ops/BRANCHING_MODEL.md) · 🇳🇬 [ig](../../../ig/docs/ops/BRANCHING_MODEL.md) · 🇮🇹 [it](../../../it/docs/ops/BRANCHING_MODEL.md) · 🇯🇵 [ja](../../../ja/docs/ops/BRANCHING_MODEL.md) · 🇬🇪 [ka](../../../ka/docs/ops/BRANCHING_MODEL.md) · 🇰🇭 [km](../../../km/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [kn](../../../kn/docs/ops/BRANCHING_MODEL.md) · 🇰🇷 [ko](../../../ko/docs/ops/BRANCHING_MODEL.md) · 🇱🇹 [lt](../../../lt/docs/ops/BRANCHING_MODEL.md) · 🇱🇻 [lv](../../../lv/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [ml](../../../ml/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [mr](../../../mr/docs/ops/BRANCHING_MODEL.md) · 🇲🇾 [ms](../../../ms/docs/ops/BRANCHING_MODEL.md) · 🇲🇹 [mt](../../../mt/docs/ops/BRANCHING_MODEL.md) · 🇲🇲 [my](../../../my/docs/ops/BRANCHING_MODEL.md) · 🇳🇵 [ne](../../../ne/docs/ops/BRANCHING_MODEL.md) · 🇳🇱 [nl](../../../nl/docs/ops/BRANCHING_MODEL.md) · 🇳🇴 [no](../../../no/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [or](../../../or/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [pa](../../../pa/docs/ops/BRANCHING_MODEL.md) · 🇵🇭 [phi](../../../phi/docs/ops/BRANCHING_MODEL.md) · 🇵🇱 [pl](../../../pl/docs/ops/BRANCHING_MODEL.md) · 🇵🇹 [pt](../../../pt/docs/ops/BRANCHING_MODEL.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/BRANCHING_MODEL.md) · 🇷🇴 [ro](../../../ro/docs/ops/BRANCHING_MODEL.md) · 🇷🇺 [ru](../../../ru/docs/ops/BRANCHING_MODEL.md) · 🇱🇰 [si](../../../si/docs/ops/BRANCHING_MODEL.md) · 🇸🇰 [sk](../../../sk/docs/ops/BRANCHING_MODEL.md) · 🇸🇮 [sl](../../../sl/docs/ops/BRANCHING_MODEL.md) · 🇷🇸 [sr](../../../sr/docs/ops/BRANCHING_MODEL.md) · 🇸🇪 [sv](../../../sv/docs/ops/BRANCHING_MODEL.md) · 🇰🇪 [sw](../../../sw/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [ta](../../../ta/docs/ops/BRANCHING_MODEL.md) · 🇮🇳 [te](../../../te/docs/ops/BRANCHING_MODEL.md) · 🇹🇭 [th](../../../th/docs/ops/BRANCHING_MODEL.md) · 🇹🇷 [tr](../../../tr/docs/ops/BRANCHING_MODEL.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/BRANCHING_MODEL.md) · 🇵🇰 [ur](../../../ur/docs/ops/BRANCHING_MODEL.md) · 🇺🇿 [uz](../../../uz/docs/ops/BRANCHING_MODEL.md) · 🇻🇳 [vi](../../../vi/docs/ops/BRANCHING_MODEL.md) · 🇳🇬 [yo](../../../yo/docs/ops/BRANCHING_MODEL.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/BRANCHING_MODEL.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/BRANCHING_MODEL.md)
---
OmniRoute **ትይዩ-ዑደት** የልቀት ሞዴልን ይጠቀማል፦ ለንቁው ዑደት የተወሰነ `release/vX.Y.Z`
ቅርንጫፍ፣ ለታተመው መስመር `main`፣ እና ያ ዑደት ሲለቀቅ የማይለወጥ
`vX.Y.Z` መለያ። ኮሚቶች በ`release/*` _እና_ በ
`main` ላይ ሲገቡ ማየት የሚጠበቅ ነው — የተደበላለቀ አሠራር አይደለም።
የጥገና ኃላፊዎች ዝርዝር በ`CLAUDE.md` (ጥብቅ ደንብ #21) እና
በ[RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md) ውስጥ ይገኛል። ይህ ገጽ ለሕዝብ
የቀረበ፣ ለአስተዋጽዖ አድራጊዎች የተዘጋጀ ማጠቃለያ ነው።
## በአጭሩ
| ማጣቀሻ | ሚና |
| ---------------- | -------------------------------------------------------------- |
| `release/vX.Y.Z` | **ንቁ ዑደት** — ለዚያ ስሪት ዕለታዊ ልማት እና የPR ውህደቶች |
| `main` | **የታተመ መስመር** — ልቀቱ ሲወጣ ዑደቱን በsquash-merge ይቀበላል |
| `vX.Y.Z` (መለያ) | **የልቀት ምልክት** — በልቀት ጊዜ የሚፈጠር፣ “ምን እንደተለቀቀ” የሚያመለክት የማይለወጥ ጠቋሚ |
```mermaid
flowchart LR
A["feat/fix ቅርንጫፍ"] --> B["PR → release/vX.Y.Z"]
B --> C["የrelease/vX.Y.Z ጫፍ"]
C --> D["የልቀት PR በsquash-merge → main ይዋሃዳል"]
D --> E["መለያ vX.Y.Z"]
C --> F["ቀጣዩ ዑደት፦ release/vX+1 ከታገደው ጫፍ ይፈጠራል"]
```
## የእኔ PR የትኛውን ቅርንጫፍ ማነጣጠር አለበት?
**ንቁውን `release/vX.Y.Z` ቅርንጫፍ ያነጣጥሩ — `main`ን አይደለም።**
1. ከተከፈቱት `release/v*` ቅርንጫፎች ከፍተኛውን ይፈልጉ (ይህ ሲጻፍ የነበረው ምሳሌ፦
`release/v3.8.49`)።
2. ከዚያ ጫፍ ቅርንጫፍ ይፍጠሩ (`git fetch` + checkout / rebase ወደዚያ)።
3. PRን **base = ያ `release/vX.Y.Z`** በማድረግ ይክፈቱ።
`main` የዕለት ተዕለት ውህደት ቅርንጫፍ አይደለም። `main`ን በማነጣጠር የተከፈቱ PRዎች
ከመዋሃዳቸው በፊት ብዙውን ጊዜ ወደ ሌላ ቅርንጫፍ እንዲያነጣጥሩ መቀየር ያስፈልጋቸዋል።
## የልቀት ማገድ (ትይዩ ዑደቶች)
አንድ ልቀት በሚጣጣምበት ጊዜ፣ `release-freeze` የሚል መለያ ያለው ምልክት ጉዳይ
ይከፈታል። ይህ **ልማትን አያቆምም**፦
- የታገደው `release/vX.Y.Z` ለዚያ ልቀት የልቀት ኃላፊው ይሆናል።
- አስተዋጽዖ አድራጊዎች ሥራቸውን ማስገባታቸውን እንዲቀጥሉ፣ የቀጣዩ ዑደት `release/vX+1`
ከታገደው ጫፍ ይፈጠራል።
- አሁንም የታገደውን ቅርንጫፍ የሚያነጣጥሩ ክፍት PRዎች ንቁውን (ከፍተኛውን)
`release/v*` ቅርንጫፍ **እንዲያነጣጥሩ መቀየር** አለባቸው።
የሚፈልጉት ቅርንጫፍ ሊዋሃድ የሚችል ነው ብለው ከመገመትዎ በፊት፣ ክፍት የማገድ ጉዳይ እንዳለ ያረጋግጡ፦
```bash
gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open
```
የውህደት አሠራሮች (የባለቤቱ `queue` መለያ → Mergify) በ
[MERGE_TRAIN.md](./MERGE_TRAIN.md) ውስጥ ተመዝግበዋል።
## ቅርንጫፍና መለያ ሁለቱም ለምን ያስፈልጋሉ?
| ቅርስ | የቆይታ ጊዜ | ዓላማ |
| ---------------- | -------------- | ------------------------------------------------------- |
| `release/vX.Y.Z` | በሂደት ላይ ያለ ዑደት | የተገመገሙ PRዎችን ይሰበስባል፣ CI-green ሆኖ ይቆያል፣ እና የPR መሠረት ይሆናል |
| መለያ `vX.Y.Z` | ለዘላለም | ወደ npm / GitHub Releases የተለቀቁትን ትክክለኛ ቢቶች ያመለክታል |
ቅርንጫፉ የሥራ ቦታ ነው፤ መለያው የታሸገ ጥቅል ነው። ወደ
`main` በsquash-merge ከተዋሃደ በኋላ፣ የቀደመው የልቀት PR እስኪጠናቀቅ ሳይጠብቅ
ቀጣዩ ዑደት በ`release/vX+1` ላይ ይቀጥላል።
## ተዛማጅ ሰነዶች
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — ማዋቀር፣ ሙከራዎች፣ የPR ማረጋገጫ ዝርዝር
- [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md) — ከመልቀቅ በፊት ማረጋገጥ
- [MERGE_TRAIN.md](./MERGE_TRAIN.md) — የውህደት ወረፋ እና አማራጭ የውህደት ባቡር
- [RELEASE_GREEN.md](./RELEASE_GREEN.md) — የልቀት ጫፉን አረንጓዴ አድርጎ ማቆየት

23
docs/i18n/am/docs/ops/BRANCH_PROTECTION_MAIN.md Normal file
View File

@@ -0,0 +1,23 @@
# Branch protection — `main` (OpenSSF Scorecard: Branch-Protection) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/BRANCH_PROTECTION_MAIN.md) · 🇸🇦 [ar](../../../ar/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇦🇿 [az](../../../az/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇧🇬 [bg](../../../bg/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇧🇩 [bn](../../../bn/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇨🇿 [cs](../../../cs/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇩🇰 [da](../../../da/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇩🇪 [de](../../../de/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇬🇷 [el](../../../el/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇪🇸 [es](../../../es/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇪🇪 [et](../../../et/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇷 [fa](../../../fa/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇫🇮 [fi](../../../fi/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇫🇷 [fr](../../../fr/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇪 [ga](../../../ga/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [gu](../../../gu/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇳🇬 [ha](../../../ha/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇱 [he](../../../he/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [hi](../../../hi/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇭🇷 [hr](../../../hr/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇭🇺 [hu](../../../hu/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇦🇲 [hy](../../../hy/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇩 [id](../../../id/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇳🇬 [ig](../../../ig/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇹 [it](../../../it/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇯🇵 [ja](../../../ja/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇬🇪 [ka](../../../ka/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇰🇭 [km](../../../km/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [kn](../../../kn/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇰🇷 [ko](../../../ko/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇱🇹 [lt](../../../lt/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇱🇻 [lv](../../../lv/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [ml](../../../ml/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [mr](../../../mr/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇲🇾 [ms](../../../ms/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇲🇹 [mt](../../../mt/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇲🇲 [my](../../../my/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇳🇵 [ne](../../../ne/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇳🇱 [nl](../../../nl/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇳🇴 [no](../../../no/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [or](../../../or/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [pa](../../../pa/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇵🇭 [phi](../../../phi/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇵🇱 [pl](../../../pl/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇵🇹 [pt](../../../pt/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇷🇴 [ro](../../../ro/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇷🇺 [ru](../../../ru/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇱🇰 [si](../../../si/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇸🇰 [sk](../../../sk/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇸🇮 [sl](../../../sl/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇷🇸 [sr](../../../sr/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇸🇪 [sv](../../../sv/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇰🇪 [sw](../../../sw/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [ta](../../../ta/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇮🇳 [te](../../../te/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇹🇭 [th](../../../th/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇹🇷 [tr](../../../tr/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇵🇰 [ur](../../../ur/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇺🇿 [uz](../../../uz/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇻🇳 [vi](../../../vi/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇳🇬 [yo](../../../yo/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/BRANCH_PROTECTION_MAIN.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/BRANCH_PROTECTION_MAIN.md)
---
የባለቤት እርምጃ። በቅንብሮች → ቅርንጫፎች → ደንብ አክል በኩል ይተግብሩ፣ ወይም፦
```bash
gh api -X PUT repos/diegosouzapw/OmniRoute/branches/main/protection \
--input - <<'JSON'
{ "required_status_checks": { "strict": true, "contexts": ["Quality Ratchet", "Quality Gates (Extended)", "Fast Quality Gates"] },
"enforce_admins": false,
"required_pull_request_reviews": { "required_approving_review_count": 0, "dismiss_stale_reviews": true },
"restrictions": null,
"required_linear_history": false,
"allow_force_pushes": false,
"allow_deletions": false }
JSON
```
የScorecard Branch-Protection ውጤትን ከ0 ከፍ ያደርገዋል። `enforce_admins:false` ነባሩን
የወደፊት-ውህደት ፍሰት ተግባራዊ እንደሆነ ያቆየዋል፤ ከተረጋጋ በኋላ ወደ `true` ያጥብቁት።

228
docs/i18n/am/docs/ops/CONTRIBUTION_GOLDEN_PATH.md Normal file
View File

@@ -0,0 +1,228 @@
# Contribution Golden Path (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇸🇦 [ar](../../../ar/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇦🇿 [az](../../../az/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇧🇬 [bg](../../../bg/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇧🇩 [bn](../../../bn/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇨🇿 [cs](../../../cs/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇩🇰 [da](../../../da/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇩🇪 [de](../../../de/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇬🇷 [el](../../../el/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇪🇸 [es](../../../es/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇪🇪 [et](../../../et/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇷 [fa](../../../fa/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇫🇮 [fi](../../../fi/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇫🇷 [fr](../../../fr/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇪 [ga](../../../ga/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [gu](../../../gu/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇳🇬 [ha](../../../ha/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇱 [he](../../../he/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [hi](../../../hi/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇭🇷 [hr](../../../hr/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇭🇺 [hu](../../../hu/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇦🇲 [hy](../../../hy/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇩 [id](../../../id/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇳🇬 [ig](../../../ig/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇹 [it](../../../it/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇯🇵 [ja](../../../ja/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇬🇪 [ka](../../../ka/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇰🇭 [km](../../../km/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [kn](../../../kn/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇰🇷 [ko](../../../ko/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇱🇹 [lt](../../../lt/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇱🇻 [lv](../../../lv/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [ml](../../../ml/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [mr](../../../mr/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇲🇾 [ms](../../../ms/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇲🇹 [mt](../../../mt/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇲🇲 [my](../../../my/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇳🇵 [ne](../../../ne/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇳🇱 [nl](../../../nl/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇳🇴 [no](../../../no/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [or](../../../or/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [pa](../../../pa/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇵🇭 [phi](../../../phi/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇵🇱 [pl](../../../pl/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇵🇹 [pt](../../../pt/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇷🇴 [ro](../../../ro/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇷🇺 [ru](../../../ru/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇱🇰 [si](../../../si/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇸🇰 [sk](../../../sk/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇸🇮 [sl](../../../sl/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇷🇸 [sr](../../../sr/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇸🇪 [sv](../../../sv/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇰🇪 [sw](../../../sw/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [ta](../../../ta/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇮🇳 [te](../../../te/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇹🇭 [th](../../../th/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇹🇷 [tr](../../../tr/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇵🇰 [ur](../../../ur/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇺🇿 [uz](../../../uz/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇻🇳 [vi](../../../vi/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇳🇬 [yo](../../../yo/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/CONTRIBUTION_GOLDEN_PATH.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/CONTRIBUTION_GOLDEN_PATH.md)
---
ይህን መመሪያ በመጠቀም ለአንድ pull request አነስተኛውንና አስተማማኝ የልማት ዑደት ይምረጡ። ይህ ከዚህ በታች
የተገናኙትን ለየአካባቢው የተለዩ የአርክቴክቸርና የደህንነት ሰነዶች አይተካም፤ እያንዳንዱን የተለመደ
የለውጥ ዓይነት ከውሎቹ፣ ከተኮሩ ፍተሻዎቹና ከCI ሽፋኑ ጋር ያገናኛል።
## እያንዳንዱ ለውጥ የሚከተለው መንገድ
1. **አርትዖት ከመጀመርዎ በፊት base-ውን ይምረጡ።** ከፍተኛውን ንቁ `release/v*` branch ያግኙና
ከጫፉ branch ይፍጠሩ። `main`ን ሳይሆን ያንን branch ዒላማ ያድርጉ። የrelease freeze ተግባራዊ ከሆነ፣ የታገደውን
branch ዒላማ አያድርጉ፤ በ
[Branching & Release Model](BRANCHING_MODEL.md) የተገለጸውን ቀጣዩን ንቁ ዑደት ይጠቀሙ።
2. **ውሎቹን ይሰይሙ።** ለውጡ የሚነካቸውን እያንዳንዱን catalog፣ schema፣ የተፈጠረ artifact፣ public API ወይም የተጠቃሚ
interface ይለዩ። ከታች ያለው ሰንጠረዥ ዝቅተኛውን የመነሻ ስብስብ ያቀርባል።
3. **የተኮሩ tests ይጻፉ ወይም ያዘምኑ።** በ`src/`፣ `open-sse/`፣ `electron/` ወይም
`bin/` ውስጥ የሚደረጉ የproduction ለውጦች በዚያው PR ውስጥ automated test ያስፈልጋቸዋል። ባህሪውን
የሚያረጋግጡ አነስተኛዎቹን test files ያስኪዱ፣ ከዚያም የተዘረዘሩትን የተኮሩ gates ያስኪዱ።
4. **CI ሰፊውን matrix እንዲያስኬድ ይፍቀዱ።** ሙሉዎቹ unit shards፣ Vitest፣ coverage ratchet እና
production build በPR ላይ ይሰራሉ። የተኮረ ውድቀት ሰፊ ተጽዕኖ እንዳለ ሲያመለክት
ወይም ለውጡ በበርካታ subsystems ላይ ሲዘረጋ ብቻ ሰፊ suiteን በአካባቢዎ ያስኪዱ።
5. **ከreview በፊት ያስማሙ።** ንቁውን base fetch ያድርጉ፣ አዲሶቹን commits እና ከእሱ አንጻር ያለውን
diffዎን ይመርምሩ፣ ከዚያም በcontributor workflow መሠረት base-ውን rebase ወይም merge ያድርጉ። የgenerated-file
እና catalog conflictsን ከምንጫቸው ይፍቱ፣ እንደገና ያመንጩዋቸው፣ የተኮረውን ዑደት እንደገና ያስኪዱ፣ እና
PR-ው አሁንም ንቁውን release branch ዒላማ ማድረጉን ያረጋግጡ።
6. **ማስረጃ ይመዝግቡ።** በPR template ውስጥ ያስኬዷቸውን commands፣ የተጨመሩ ወይም የተቀየሩ እያንዳንዱን test file፣
migrations ወይም feature flags፣ እና ገና ያልተጠናቀቀ CI-only validation ይዘርዝሩ።
## በለውጥ ዓይነት የተደራጁ ዋና መንገዶች
ከታች ያሉት commands ዝቅተኛዎቹ የተኮሩ ፍተሻዎች ናቸው፤ የቀየሩትን ባህሪ በቀጥታ የሚሸፍን test
ለመዝለል ፈቃድ አይደሉም።
### Provider
**ውሎች**
- በ`src/shared/constants/providers/` ውስጥ ያለው Provider definition እና በ
`src/shared/constants/providers.ts` ውስጥ ያለው composition።
- በ`open-sse/config/providerRegistry.ts` ወይም በተለዩት registry files ውስጥ ያሉ models እና capabilities።
- Executor/translator selection፣ OAuth ወይም API-key configuration፣ dashboard assets፣ እና ተፈጻሚ ሲሆን የተፈጠረ
provider reference።
- Public credentials `resolvePublicCred()`ን መጠቀም አለባቸው፤ error responses የጋራ sanitized
error helpersን መጠቀም አለባቸው። `docs/security/PUBLIC_CREDS.md`ን (git፤ ወደ`/docs` አይcompiledም) እና
[Error Sanitization](../security/ERROR_SANITIZATION.md)ን ይመልከቱ።
**የተኮረ ዑደት**
```bash
npm run check:provider-consistency
npm run check:provider-assets
node --import tsx/esm --test tests/unit/provider-translate-path-golden.test.ts
node --import tsx/esm --test tests/unit/<provider-or-executor>.test.ts
npm run gen:provider-reference # catalog-ው ሲቀየር፤ የተፈጠረውን diff commit ያድርጉ
npm run lint
```
እያንዳንዱን የተነካ request familyም test ያድርጉ፦ chat፣ Responses፣ images፣ embeddings፣ audio ወይም video።
የተፈጠሩ catalog እና golden diffsን እንደ contract changes ይገምግሙ፤ ያለምርመራ አይቀበሏቸው።
### Routing
**ውሎች**
- በ`src/shared/constants/routingStrategies.ts` ውስጥ ያሉ public strategy values እና UI metadata።
- በ`open-sse/services/combo.ts` እና `open-sse/services/combo/` ስር ያሉ dispatch እና ordering።
- Combo schemas፣ persistence፣ resilience state፣ model capabilities፣ እና API/UI controls።
- ባህሪ ሲቀየር [Auto-Combo Engine](../routing/AUTO-COMBO.md) እና resilience documentation።
**የተኮረ ዑደት**
```bash
node --import tsx/esm --test tests/unit/combo-<behavior>.test.ts
npm run test:combo:matrix # የstrategy ወይም dispatch ለውጦች
npm run check:known-symbols # የstrategy registration ለውጦች
npm run lint
```
በአካባቢዎ deterministic mocked-upstream testsን ይጠቀሙ። Live combo smokes credentials ያስፈልጋቸዋል፣ እና
በእጅ የሚከናወኑ እንጂ የCI ምትክ አይደሉም።
### UI / UX
**ውሎች**
- በ`src/app/` እና
`src/shared/components/` ስር ያሉ Next.js route/page እና የጋራ component boundaries።
- API response shapes፣ loading/empty/error states፣ የkeyboard እና screen-reader ባህሪ፣
responsive layout፣ theming፣ እና locale expansion።
- በ`src/i18n/messages/en.json` ውስጥ ያሉ የእንግሊዝኛ UI source strings፤ አዲስ user-facing copyን hard-code አያድርጉ።
**የተኮረ ዑደት**
```bash
node --import tsx --test tests/unit/dashboard/<feature>.test.ts
npx vitest run --config vitest.config.ts tests/unit/ui/<component>.test.tsx
npm run check:dashboard-typecheck
npm run lint
```
ለinteraction ወይም visual changes app-ውን ያስኪዱ፣ እና ጠባብና ሰፊ viewportsን ይፈትሹ። CI
production buildን እና ሰፋፊ suitesን ያስኬዳል፤ visual behavior ግን አሁንም ከለውጡ ጋር የሚስማማ focused component፣ Playwright፣
ወይም በሰነድ የተመዘገበ manual check ያስፈልገዋል።
### i18n
**ውሎች**
- `src/i18n/messages/en.json` የUI source ነው፤ `config/i18n.json` ደግሞ የlocale source ነው።
- የCLI catalogs በ`bin/cli/locales/` ስር ለብቻቸው ይገኛሉ።
- ICU placeholders እና tagsን በትክክል ያቆዩ። የproduct/provider/model ስሞችን፣
የprotocol እና header ስሞችን፣ commands፣ code/JSON identifiers፣ URLs፣ environment variables፣ ወይም
እንደ `OmniRoute`፣ `OAuth`፣ `MCP` እና `A2A` ያሉ protected termsን አይተርጉሙ። የአሁኑ source list
`scripts/i18n/glossary/protected-terms.json` ነው።
**የተኮረ ዑደት**
```bash
npm run i18n:sync-ui:dry
npm run i18n:check-ui-coverage
npm run i18n:check-value-drift
npm run i18n:check-glossary
npm run check:cli-i18n # የCLI strings/catalogs ሲቀየሩ
npm run lint
```
ይህ ለነባሩ system መመሪያ እንጂ toolingውን ወይም key modelን ለማስፋፋት ግብዣ አይደለም።
ምትክ system-ው እየተነደፈ ባለበት ጊዜ i18n patchesን በጥንቃቄና በውስን መልኩ ያድርጉ። ሥራው generated translationsን በግልጽ ካልጠየቀ
እና የተፈጠረውን diff ካልገመገሙ፣ external servicesን የሚጠሩ translation
commandsን አያስኪዱ።
### CLI
**ውሎች**
- በ`bin/cli/` ውስጥ ያሉ ይፋዊ ትዕዛዞችና flags፣ የሚመነጩ API ትዕዛዞች፣ exit codes፣ stdout/stderr እና
የJSON ውጤት ቅርጾች፣ የconfig/environment ባህሪ፣ እና በጥቅል የሚካተቱ ፋይሎች።
- ለCLI ተጠቃሚ የሚታዩ ሕብረቁምፊዎች የCLI i18n layerን መጠቀም እና የ`en`/`pt-BR` catalogsን የተመሳሰሉ አድርገው ማቆየት አለባቸው።
- Nodeን እንደሚደገፈው runtime እና የታተመውን binary contract ጠብቁ።
**ያተኮረ ዑደት**
```bash
node --import tsx/esm --test tests/unit/cli/<command>.test.ts
npm run check:cli-i18n
npm run build:cli # የሚመነጩ/በጥቅል የሚሰበሰቡ የCLI ለውጦች
npm run check:pack-policy # የpackage surface ለውጦች
npm run lint
```
ባህሪው በparsing፣ በፋይሎች ወይም በexit status ላይ ሲመሠረት ትክክለኛውን ትዕዛዝ በጊዜያዊ data directory ውስጥ ይጠቀሙ።
CI ይበልጥ ሰፊዎቹን የpackage artifact እና ecosystem ማረጋገጫዎች ያከናውናል።
### የውሂብ ጎታ
**ውሎች**
- በ`src/lib/db/` ስር ያሉ domain modules፤ የተወሰኑ modulesን በቀጥታ import ያድርጉ (የቀድሞው `localDb.ts` re-export layer ተወግዷል)።
- በ`src/lib/db/migrations/` ስር ያሉ ቁጥር የተሰጣቸው፣ idempotent የSQL migrations፣ የtransaction ደህንነት፣ የupgrade
ባህሪ፣ indexes፣ እና በschemaው የሚነካ እያንዳንዱ caller።
- Routes እና handlers በቀጥታ raw SQL ፈጽሞ አያስኬዱም።
**ያተኮረ ዑደት**
```bash
npm run check:migration-numbering
npm run check:db-rules
node --import tsx/esm --test tests/unit/db/<domain>.test.ts
node --import tsx/esm --test tests/unit/db/migration-<number>.test.ts
npm run lint
```
migration ሲጨምሩ አዲስ የውሂብ ጎታን እና ከቀዳሚው schema የሚደረግ upgradeን ሁለቱንም ይፈትኑ። የውሂብ ጎታ ሙከራዎች
handlesን መዝጋት እና በcleanup ጊዜ `resetDbInstance()`ን መጥራት አለባቸው። `npm run test:bun:db`ን ያስኪዱት
የbest-effort Bun adapter path ሲለወጥ ብቻ ነው፤ Node ዋናው ማጣቀሻ ሆኖ ይቀጥላል።
### Build / deploy
**ውሎች**
- Root እና workspace manifests/lockfile፣ `scripts/build/`፣ Next.js standalone assembly፣ የ`dist/`
package ይዘቶች፣ የElectron platform metadata፣ የCI workflows፣ እና deployment sentinels።
- የሚደገፉ የNode ranges እና በ`CLAUDE.md` ውስጥ allow-list የተደረገው የBun አጠቃቀም ሳይበላሹ መቆየት አለባቸው።
- Build artifacts ክትትል ሳይደረግባቸው ይቆያሉ፤ የdependency፣ license፣ workflow፣ እና package policies ተፈጻሚ ናቸው።
**ያተኮረ ዑደት**
```bash
node --import tsx/esm --test tests/unit/build/<behavior>.test.ts
npm run check:build-scope
npm run check:lockfile # የdependency ወይም lockfile ለውጦች
npm run check:pack-policy # የታተመው package surface ለውጦች
npm run lint
```
ለውጡ compilation፣ standalone assembly፣ assets ወይም runtime bundlingን ሲነካ ብቻ `npm run build`ን በአካባቢዎ ይጠቀሙ።
`npm run build:release`ን ለrelease/deploy validation ብቻ ይጠቀሙ። የCI build የመጨረሻው cross-platform ምልክት ነው፤
platform-specific የElectron ለውጦች ተዛማጅ የሆነ focused build ወይም smoke evidence ያስፈልጋቸዋል።
## የአካባቢያዊ ዙር ከCI ጋር ሲነጻጸር
| ለእያንዳንዱ ማሻሻያ በአካባቢው ያስኪዱ | CI ሰፊውን ምልክት ያቀርባል |
| ------------------------------------------------------ | -------------------------------------------------- |
| ከላይ ያሉት የባህሪ ቀጥተኛ ሙከራዎች እና የምድብ መግቢያዎች | የተከፋፈለ ሙሉ የአሃድ ሙከራ ስብስብ እና ተከታታይ ሙከራዎች |
| `npm run lint` | የVitest ሙከራ ስብስቦች እና የሽፋን/ጥራት ደረጃን የሚያጠናክሩ ፍተሻዎች |
| የተነካው ውል ሲጠይቅ ብቻ የዓይነት ፍተሻ ወይም ግንባታ | የምርት ግንባታ፣ የደህንነት፣ የሰነዶች፣ የጥገኝነት እና የPR ፖሊሲ መግቢያዎች |
| ራስ-ሰር ሂደት ባህሪውን ማረጋገጥ ሳይችል ሲቀር ብቻ በእጅ መስተጋብር/ቀጥታ ፍተሻዎች | በየስራ ፍሰቱ የተዋቀሩ የተለያዩ ስራዎች ውህደት እና የመድረክ ፍተሻዎች |
የተሳካ ያተኮረ ዙር ስለተቀየረው ውል ማስረጃ ነው፤ ነገር ግን ያልተዛመዱ የCI ፍተሻዎች
እንደሚያልፉ ማረጋገጫ አይደለም። በተቃራኒው፣ እያንዳንዱን የአካባቢ ማስተካከያ ሙሉውን የማከማቻ ማትሪክስ እንዲጠብቅ አያድርጉ።
## የማስታረቂያ ማረጋገጫ ዝርዝር
ግምገማ ከመጠየቅዎ በፊት፦
- የPR መሠረቱ አሁንም ከፍተኛው ንቁ `release/v*` ቅርንጫፍ መሆኑን ያረጋግጡ።
- ያንን መሠረት ያምጡ እና ቅርንጫፍዎን ከፈጠሩ በኋላ የገቡትን commits ይገምግሙ።
- ያልታሰቡ ወይም በራስ-ሰር የተፈጠሩ ለውጦችን ለማግኘት `git diff <active-base>...HEAD`ን ይገምግሙ።
- ምንጩን በማዘመን እና ውጤቱን እንደገና በማመንጨት የካታሎግ እና በራስ-ሰር የተፈጠሩ ሰነዶች ግጭቶችን ይፍቱ።
- ከማስታረቁ በኋላ በPR መግለጫው ውስጥ የተዘረዘሩትን እያንዳንዱን ያተኮረ ሙከራ/መግቢያ እንደገና ያስኪዱ።
- ከተቀየረ መሠረት ጋር ለማዛመድ ብቻ assertionsን በፍጹም አያላሉ ወይም አስፈላጊ ሙከራዎችን አያስወግዱ።
ለልቀት እገዳ እና የመድረሻ ቅርንጫፍን እንደገና ለመወሰን ደንቦች፣
[የቅርንጫፍ እና የልቀት ሞዴል](BRANCHING_MODEL.md)ን ይጠቀሙ። ለተሟላው የCI ዝርዝር፣
[የጥራት መግቢያዎች ማጣቀሻ](../architecture/QUALITY_GATES.md)ን ይጠቀሙ።

657
docs/i18n/am/docs/ops/DATABASE_GUIDE.md Normal file
View File

@@ -0,0 +1,657 @@
# Database Schema & Operations Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/DATABASE_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/DATABASE_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/DATABASE_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/DATABASE_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/DATABASE_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/DATABASE_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/DATABASE_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/DATABASE_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/DATABASE_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/DATABASE_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/DATABASE_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/DATABASE_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/DATABASE_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/DATABASE_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/DATABASE_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/DATABASE_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/DATABASE_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/DATABASE_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/DATABASE_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/DATABASE_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/DATABASE_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/DATABASE_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/DATABASE_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/DATABASE_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/DATABASE_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/DATABASE_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/DATABASE_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/DATABASE_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/DATABASE_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/DATABASE_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/DATABASE_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/DATABASE_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/DATABASE_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/DATABASE_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/DATABASE_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/DATABASE_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/DATABASE_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/DATABASE_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/DATABASE_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/DATABASE_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/DATABASE_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/DATABASE_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/DATABASE_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/DATABASE_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/DATABASE_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/DATABASE_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/DATABASE_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/DATABASE_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/DATABASE_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/DATABASE_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/DATABASE_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/DATABASE_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/DATABASE_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/DATABASE_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/DATABASE_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/DATABASE_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/DATABASE_GUIDE.md)
---
> **TL;DR**: OmniRoute እንደ ዋና ማከማቻው **SQLite ከWAL journaling ጋር** ይጠቀማል፤ ለሚስጥራዊ መስኮች ደግሞ በማከማቻ ላይ **AES-256-GCM** ምስጠራን ይጠቀማል። ይህ መመሪያ schema፣ migrations፣ backup/recovery እና የክወና runbooksን ይሸፍናል።
**ምንጮች፦**
- `src/lib/db/core.ts` — singleton + SCHEMA_SQL (17 መሠረታዊ ሰንጠረዦች)
- `src/lib/db/migrationRunner.ts` — ስሪት ያላቸው migrations
- `src/lib/db/migrations/` — 167 ስሪት ያላቸው SQL ፋይሎች
- `src/lib/db/encryption.ts` — የምስጠራ አጋዥ ተግባራት
- `src/lib/db/backup.ts` — የbackup export/import
- `src/lib/db/healthCheck.ts` — የጤና ምርመራዎች
---
## SQLite ለምን?
OmniRoute በPostgreSQL/MySQL ፈንታ SQLiteን የመረጠው በበርካታ ምክንያቶች ነው፦
| መለኪያ | SQLite | PostgreSQL |
| ------------------ | ---------------------------- | ---------------------------------- |
| **ማሰማራት** | የተካተተ — የተለየ server አያስፈልግም | የserver ቅንብር ያስፈልገዋል |
| **ምስጠራ** | በመተግበሪያ ደረጃ (AES-256-GCM) | አብሮገነብ TDE |
| **አፈጻጸም** | ለአነስተኛ/መካከለኛ የሥራ ጫናዎች ፈጣን | ለእጅግ ብዙ በአንድ ጊዜ ለሚከናወኑ ጽሑፎች የተሻለ |
| **ተመሳሳይ ጊዜ አጠቃቀም** | WAL mode በአንድ ጊዜ ማንበብን ይፈቅዳል | ሙሉ MVCC |
| **Backup** | የአንድ ፋይል ቅጂ | `pg_dump` ወይም የfilesystem snapshot |
| **የአጠቃቀም ሁኔታ** | ለእያንዳንዱ ተጠቃሚ የሚጫን፣ የተካተተ | ባለብዙ ተከራይ SaaS |
ለ**አንድ ተጠቃሚ፣ አንድ instance** deployments (የOmniRoute ዋና የአጠቃቀም ሁኔታ)፣ SQLite ቀላልና ፈጣን ነው።
### WAL Journaling
`core.ts` databaseን በ**WAL (Write-Ahead Logging) mode** ይከፍታል፦
```ts
// src/lib/db/core.ts
db.pragma("journal_mode = WAL");
db.pragma("busy_timeout = 2000");
db.pragma("synchronous = NORMAL");
db.pragma(`cache_size = -${DEFAULT_DATABASE_SETTINGS.optimization.cacheSize}`);
```
WAL በጽሑፍ ሥራዎች ወቅት **በአንድ ጊዜ ማንበብን** ይፈቅዳል — ጥያቄዎች እየተመዘገቡ ሳለ query ለሚያደርገው dashboard ይህ አስፈላጊ ነው።
ነባሪው የcache መጠን **65,536 KiB (64 MiB)** ነው። SQLite አሉታዊ
`cache_size`ን በKiB እንደ ግምታዊ ከፍተኛ ገደብ ይተረጉማል እና ገጾችን እንደ አስፈላጊነቱ ይመድባል።
**Settings > System & Storage > Cache Size** ከ**1 እስከ
1,000,000 KiB** ያሉ ኢንቲጀር እሴቶችን ይቀበላል፤ ቅንብሩን ማስቀመጥ በቀጥታ በሚሠራው database connection ላይ ይተገብረዋል፣
እና OmniRoute ሲጀመር የተቀመጠውን እሴት መልሶ ይጭናል።
---
## የDatabase አካባቢ
የSQLite ፋይሉ የሚቀመጠው በ፦
| OS | ዱካ |
| ------- | -------------------------------------------------- |
| Linux | `~/.omniroute/storage.sqlite` |
| macOS | `~/.omniroute/storage.sqlite` |
| Windows | `%USERPROFILE%\.omniroute\storage.sqlite` |
| Docker | `/app/data/storage.sqlite` (በ`DATA_DIR` ሊዋቀር ይችላል) |
ተጓዳኝ ፋይሎች፦
- `storage.sqlite-wal` — write-ahead log
- `storage.sqlite-shm` — የጋራ memory ፋይል
- `call_logs/` — የጥያቄ payload artifacts (ከነቃ)
**አካባቢውን መቀየር፦**
```bash
DATA_DIR=/custom/path omniroute
```
---
## የጎራ ሞጁል አርክቴክቸር
የOmniRoute የውሂብ ጎታ በ`src/lib/db/` ውስጥ **110 ከፍተኛ-ደረጃ TypeScript ሞጁሎች** አሉት። እያንዳንዱ የጎራ ሞጁል፦
- አንድ ወይም ከዚያ በላይ የተወሰኑ ሰንጠረዦችን ይቆጣጠራል
- ዓይነት-የተወሰነላቸው CRUD ተግባራትን ወደ ውጭ ይልካል
- የሌላ ሞጁል ሰንጠረዦችን ፈጽሞ አይነካም
- DBን ለመድረስ ከ`core.ts` የሚገኘውን `getDbInstance()` ይጠቀማል
### 110ዎቹ ከፍተኛ-ደረጃ DB ሞጁሎች
OmniRoute በ`src/lib/db/` ውስጥ **110 ከፍተኛ-ደረጃ TypeScript ፋይሎች** አሉት። ከዚህ በታች የዋና ሞጁሎች ናሙና ቀርቧል፤ ሙሉውን ዝርዝር ለማየት የማውጫውን ዝርዝር ይመልከቱ፦
| ሞጁል | ሰንጠረዦች | ኃላፊነት |
| ----------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
| `providers.ts` | `provider_connections` | የOAuth/API ቁልፍ አቅራቢ ምዝገባ እና የማረጋገጫ መረጃ |
| `models.ts` | `key_value` (የሞዴል ውሂብ) | የሞዴል ትርጓሜዎች፣ ችሎታዎች እና ዋጋ አወጣጥ |
| `combos.ts` | `combos` | የጥምር ማዘዋወሪያ ውቅሮች እና ቅደም ተከተል |
| `apiKeys.ts` | `api_keys` | የAPI ቁልፍ የሕይወት ዑደት፣ ወሰኖች እና የኮታ ክትትል |
| `settings.ts` | `key_value`, `api_keys`, `combos` | የስርዓት ውቅር እና የጋራ KV ማከማቻ |
| `backup.ts` | — | የምትኬ ወደ ውጭ መላክ/ከውጭ ማስገባት ክወናዎች |
| `proxies.ts` | `proxy_registry`, `proxy_assignments`, `provider_connections` | የፕሮክሲ ውቅሮች እና የማዘዋወሪያ ደንቦች |
| `prompts.ts` | `prompt_templates` | እንደገና ጥቅም ላይ የሚውሉ የጥያቄ አብነቶች እና ስሪት አስተዳደር |
| `webhooks.ts` | `webhooks` | በክስተት የሚነሱ የwebhook ምዝገባዎች እና ምዝግቦች |
| `detailedLogs.ts` | `request_detail_logs` | ለእያንዳንዱ ጥያቄ የኦዲት ምዝገባ (አማራጭ፣ ከፍተኛ መጠን ያለው) |
| `domainState.ts` | `domain_*` (5 ሰንጠረዦች) | የጎራ በጀቶች፣ የወረዳ መቋረጫዎች፣ መቆለፊያዎች፣ ተተኪ ሰንሰለቶች እና የወጪ ታሪክ |
| `registeredKeys.ts` | `registered_keys`, `account_key_limits`, `provider_key_limits` | ለMCP/A2A በተፈቀደ ዝርዝር ውስጥ የገቡ API ቁልፎች |
| `quotaSnapshots.ts` | `quota_snapshots` | ታሪካዊ የኮታ አጠቃቀም |
| `modelComboMappings.ts` | `model_combo_mappings` | ሞዴሎችን ከነባሪ ጥምሮች ጋር ማዛመድ |
| `cliToolState.ts` | `cli_tool_state` | ለCLI የተወሰነ ዘላቂ ሁኔታ |
| `encryption.ts` | — | መስኮችን ለማመስጠር/ምስጠራቸውን ለመፍታት የሚረዱ መሳሪያዎች |
| `readCache.ts` | — | ብዙ የንባብ ክወናዎች ባሏቸው ሂደቶች የሚያገለግል በማህደረ ትውስታ ውስጥ ያለ መሸጎጫ |
| `secrets.ts` | `key_value` (የተመሰጠሩ ግቤቶች) | የተመሰጠረ ሚስጥራዊ መረጃ ማከማቻ |
| `stateReset.ts` | — | ለሙከራ የDB ሁኔታን ማጽዳት/ዳግም ማስጀመር |
| `contextHandoffs.ts` | `context_handoffs` | ለወኪል ርክክብ የክፍለ ጊዜ አውድ |
| `usage*.ts` | `usage_history`, `call_logs`, `proxy_logs` | የአጠቃቀም ክትትል |
| `compression*.ts` | `compression_settings`, `compression_combos` | የመጭመቂያ ውቅር |
### የሞጁል ወሰኖች
አንድ ዋና የአርክቴክቸር ደንብ፦ **ሞጁሎች የእርስ በርሳቸውን ሰንጠረዦች በቀጥታ አይደርሱም**። ከሌላ ሞጁል ውሂብ ጋር ለመስራት፣ ተግባሩን ከዚያ ሞጁል ያስመጡ።
```ts
// ❌ ስህተት፦ ከሌላ ሞጁል ቀጥተኛ SQL
db.prepare("SELECT * FROM provider_connections").all();
// ✅ ትክክል፦ የproviders ሞጁሉን ተግባር ይጠቀሙ
import { listProviders } from "@/lib/db/providers";
const providers = await listProviders();
```
ይህ ደንብ በኮድ ግምገማ ይተገበራል — የማይለዋወጥ ራስ-ሰር ማረጋገጫ የለም፣ ነገር ግን ጥሰቶች ምልክት ይደረግባቸዋል።
---
## መሠረታዊ ስኪማ (17 ሰንጠረዦች)
`core.ts` በ`SCHEMA_SQL` ውስጥ ያሉትን 17 መሠረታዊ ሰንጠረዦች ይገልጻል። እነዚህ በ`001_initial_schema.sql` ማይግሬሽን የሚፈጠሩ ሲሆን ዋናውን ስኪማ ይመሠርታሉ።
### ዋና ሰንጠረዦች (በመጀመሪያው ማይግሬሽን የተፈጠሩ)
| ሰንጠረዥ | ዓላማ | ቁልፍ ዓምዶች |
| -------------------------- | -------------------------- | ----------------------------------------------------------------------- |
| `provider_connections` | የአቅራቢ ማረጋገጫ መረጃዎች (የተመሰጠሩ) | `id`, `provider`, `auth_type`, `api_key`, `is_active` |
| `provider_nodes` | የአቅራቢ ኖድ ማስተላለፊያ መረጃ | `id`, `type`, `name`, `base_url`, `created_at` |
| `key_value` | አጠቃላይ የKV ማከማቻ | `namespace`, `key`, `value` |
| `combos` | የማስተላለፊያ ጥምረት ትርጓሜዎች | `id`, `name`, `data`, `sort_order` |
| `api_keys` | ለጌትዌዩ የሚያገለግሉ API ቁልፎች | `id`, `name`, `key`, `machine_id`, `allowed_models` |
| `db_meta` | የውሂብ ጎታ ሜታዳታ | `key`, `value` |
| `usage_history` | የጥያቄ አጠቃቀም መዝገቦች | `id`, `provider`, `model`, `tokens_input`, `tokens_output`, `timestamp` |
| `call_logs` | የጥያቄ ይዘቶች እና ምላሾች | `id`, `timestamp`, `status`, `model`, `provider`, `latency_ms` |
| `proxy_logs` | የፕሮክሲ ጥያቄ ምዝግቦች | `id`, `timestamp`, `proxy_type`, `status`, `provider` |
| `domain_fallback_chains` | ከሞዴል ወደ አቅራቢ የሚወስዱ ሰንሰለቶች | `model`, `chain` |
| `domain_budgets` | ለእያንዳንዱ ጎራ የወጪ በጀቶች | `api_key_id`, `daily_limit_usd`, `warning_threshold`, `reset_interval` |
| `domain_budget_reset_logs` | የበጀት ዳግም ማስጀመር ታሪክ | `id`, `api_key_id`, `reset_interval`, `previous_spend`, `reset_at` |
| `domain_cost_history` | የእያንዳንዱ ጎራ ወጪ ክትትል | `id`, `api_key_id`, `cost`, `timestamp` |
| `domain_lockout_state` | የጎራ ፍጥነት ገደብ ሁኔታ | `identifier`, `attempts`, `locked_until` |
| `domain_circuit_breakers` | የእያንዳንዱ ጎራ ሰርኪት መቆራረጫ ሁኔታ | `name`, `state`, `failure_count`, `last_failure_time` |
| `semantic_cache` | የLLM ምላሽ መሸጎጫ | `id`, `signature`, `model`, `prompt_hash`, `response` |
| `quota_snapshots` | ታሪካዊ የኮታ ቅጽበተ-ምስሎች | `id`, `provider`, `connection_id`, `window_key`, `remaining_percentage` |
### ተጨማሪ ሰንጠረዦች (በኋለኞቹ ማይግሬሽኖች የታከሉ)
ቀጣይ ማይግሬሽኖች እንደሚከተሉት ያሉ ሰንጠረዦችን ይጨምራሉ፦
- `cli_tool_state` (ማይግሬሽን 011) — የCLI መሣሪያ ሁኔታ
- `mcp_*` ሰንጠረዦች — የMCP አገልጋይ ኦዲት
- `a2a_*` ሰንጠረዦች — የA2A ተግባር ሁኔታ
- `usage_*` ሰንጠረዦች — የአጠቃቀም ክትትል
- `plugin_*` ሰንጠረዦች — የፕለጊን ሥርዓት
- `skill_executions` — የክህሎት አፈጻጸም ታሪክ
- `memory_*` ሰንጠረዦች — የማህደረ ትውስታ ሥርዓት
- `compression_*` ሰንጠረዦች — የማመቅ ሥርዓት
- `webhook_*` ሰንጠረዦች — የwebhook ማድረሻ ምዝግብ
- `acp_*` ሰንጠረዦች — የወኪል ደንበኛ ፕሮቶኮል
- `oneproxy_*` ሰንጠረዦች — የ1proxy የገበያ ቦታ
- `proxy_assignments` — የፕሮክሲ ወሰን ትስስሮች
- `detailed_call_artifacts` — የጥሪ ምዝግብ አርቲፋክቶች ሜታዳታ
- `quota_alert_history` — የኮታ ማንቂያ ኦዲት
- `command_code_auth_sessions` — የCommand Code OAuth ክፍለ-ጊዜዎች
የ~30+ ሰንጠረዦች ሙሉ ዝርዝር በ`src/lib/db/migrations/` ውስጥ ይገኛል።
---
## ማይግሬሽኖች
OmniRoute በ`src/lib/db/migrations/` ውስጥ **የስሪት ቁጥር ያላቸው፣ ዳግም ቢሄዱም ተመሳሳይ ውጤት የሚሰጡ ማይግሬሽኖችን** ይጠቀማል። እያንዳንዱ ማይግሬሽን `NNN_description.sql` ተብሎ የተሰየመ አንድ SQL ፋይል ነው።
### የማይግሬሽን አሰያየም
```
001_initial_schema.sql
002_mcp_a2a_tables.sql
003_provider_node_custom_paths.sql
...
021_combo_call_log_targets.sql
```
### ማይግሬሽኖች እንዴት እንደሚሄዱ
ሲጀመር `migrationRunner.ts`፦
1. ካልነበረ የ`_omniroute_migrations` ሰንጠረዥን ይፈጥራል
2. ከዚህ ቀደም የተተገበሩ ማይግሬሽኖችን ይጠይቃል
3. ማናቸውንም አዲስ ማይግሬሽኖች በቅደም ተከተል፣ እያንዳንዳቸውን በአንድ transaction ውስጥ ይተገብራል
4. እያንዳንዱን የተተገበረ ማይግሬሽን ከtimestamp ጋር ይመዘግባል
```ts
// src/lib/db/migrationRunner.ts (ቀለል ያለ)
export async function runMigrations(db: SqliteDatabase, migrationsDir: string) {
const applied = getAppliedMigrations(db);
const available = readMigrationFiles(migrationsDir);
for (const migration of available) {
if (applied.includes(migration.id)) continue;
db.transaction(() => {
db.exec(migration.sql);
recordAppliedMigration(db, migration.id);
})();
}
}
```
### ዳግም ሲሄዱ ተመሳሳይ ውጤት መስጠት
ማይግሬሽኖች **ዳግም ቢሄዱም ተመሳሳይ ውጤት የሚሰጡ** መሆን አለባቸው — ሁለት ጊዜ ማስኬድ ምንም ተግባር ሊፈጽም አይገባም፦
```sql
-- 004_proxy_registry.sql
CREATE TABLE IF NOT EXISTS proxy_registry (
id TEXT PRIMARY KEY,
host TEXT NOT NULL,
port INTEGER NOT NULL,
...
);
```
የ`IF NOT EXISTS`፣ `IF EXISTS` እና `OR IGNORE` / `OR REPLACE` clausesን በስፋት ይጠቀሙ።
### አዲስ ማይግሬሽን ማከል
1. **ቀጣዩን ቁጥር ይለዩ**፦ `ls src/lib/db/migrations/ | tail -1`
2. **ፋይሉን ይፍጠሩ**፦ `NNN_my_change.sql`
3. **ደህንነቱ የተጠበቀ DDL ይጠቀሙ**፦ `CREATE TABLE IF NOT EXISTS`፣ `ALTER TABLE ... ADD COLUMN`
4. **ውሂብን በጥንቃቄ ወደ ኋላ ይሙሉ**፦ ነባር rowsን ለማስተናገድ `UPDATE ... WHERE ...` ይጠቀሙ
5. **በቅጂ ላይ ይፈትሹ**፦ ያልተፈተሹ ማይግሬሽኖችን በproduction ላይ ፈጽሞ አያስኪዱ
ምሳሌ፦
```sql
-- 022_add_combo_priority.sql
ALTER TABLE combos ADD COLUMN priority INTEGER DEFAULT 100;
UPDATE combos SET priority = 100 WHERE priority IS NULL;
CREATE INDEX IF NOT EXISTS idx_combos_priority ON combos(priority);
```
> **ከቀድሞ ስሪቶች ጋር የማይጣጣሙ ለውጦች** (ለምሳሌ፣ columnsን ማስወገድ) አስቸጋሪ ናቸው። OmniRoute downgradeን አይደግፍም — አንዴ ማይግሬሽን ከተተገበረ በኋላ የschemaው ለውጥ ቋሚ ነው። በዚህ መሠረት ያቅዱ።
---
## በማከማቻ ውስጥ ምስጠራ
ሚስጥራዊ fields (API keys፣ OAuth tokens፣ connection strings) **AES-256-GCM**ን በመጠቀም በማከማቻ ውስጥ ይመሰጠራሉ።
### እንዴት እንደሚሠራ
```ts
// src/lib/db/encryption.ts (ቀለል ያለ)
const key = deriveKeyFromPassphrase(passphrase, salt);
const iv = randomBytes(12);
const cipher = createCipheriv("aes-256-gcm", key, iv);
const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
const authTag = cipher.getAuthTag();
return { encrypted, iv, authTag };
```
### የት እንደሚጠቀም
- `provider_connections.api_key` — በapplication ደረጃ የተመሰጠረ
- `provider_connections.access_token`, `refresh_token`, `id_token` — በapplication ደረጃ የተመሰጠሩ
- `namespace = "secrets"` ያላቸው `key_value` entries — በapplication ደረጃ የተመሰጠሩ
- `proxy_registry.auth` — ካለ በapplication ደረጃ የተመሰጠረ
### የምስጠራ ቁልፍ
የምስጠራ ቁልፉ ከ**passphrase** (በ`STORAGE_ENCRYPTION_KEY` env var በኩል ከሚዘጋጅ) እና ከ**salt** (በDB ውስጥ ከሚከማች) ይመነጫል። ውሂብን ለመፍታት ሁለቱም ያስፈልጋሉ።
```bash
# ደህንነቱ የተጠበቀ passphrase ይፍጠሩ
openssl rand -hex 32
# በ.env ውስጥ ያዘጋጁ
STORAGE_ENCRYPTION_KEY=<your-key>
```
> **ወሳኝ**፦ የምስጠራ ቁልፉን ማጣት ሁሉንም የተመሰጠረ ውሂብ የመድረስ ችሎታን ማጣት ማለት ነው። **ቁልፉን ከdatabaseው ተለይቶ ምትኬ ይያዙ**።
### የማይመሰጠሩ ነገሮች
ለአፈጻጸም ሲባል፣ የሚከተሉት በplaintext ይከማቻሉ፦
- የProvider ማሳያ ስሞች
- የModel ትርጓሜዎች (ከወዲሁ ይፋዊ ናቸው)
- የRouting ደንቦች
- የUsage መዝገቦች (PII የለም)
---
## የምስጠራ ጥንቃቄዎች (v3.8.16+)
OmniRoute ሁለት የምስጠራ ዘዴዎችን በግልጽነት ለማስተናገድ **`migrateLegacyEncryptedString()`**ን ይጠቀማል፦
- **የቀድሞ** (ከ-v3.5.0 በፊት)፦ በXOR ላይ የተመሠረተ "ምስጠራ" (እውነተኛ ክሪፕቶግራፊ አይደለም)
- **የአሁኑ**፦ AES-256-GCM ከትክክለኛ IV እና የማረጋገጫ መለያ ጋር
የፍልሰት አጋዡ የቀድሞውን ቅርጸት በመለየት በመጀመሪያው ንባብ በአዲሱ ዘዴ እንደገና ያመሰጥረዋል። ይህም ማረጋገጫ መረጃዎችን ሳያጡ የቆየ የውሂብ ጎታን ማሻሻል እንዲችሉ ያደርጋል።
---
## የንባብ መሸጎጫ
በተደጋጋሚ ለሚነበብ ውሂብ (ሞዴሎች፣ አቅራቢዎች፣ ቅንብሮች)፣ `readCache.ts` **በማህደረ ትውስታ ውስጥ የሚገኝ መሸጎጫ** ያቀርባል፦
```ts
// ሲጀመር ይሸጎጣል፣ ሲጻፍ ዋጋ አልባ ይሆናል
const providers = await getCachedProviders(); // ፈጣን፣ በማህደረ ትውስታ ውስጥ
const fresh = await listProviders(); // ዘገምተኛ፣ DBን ይደርሳል
```
| የተሸጎጠ አካል | የመሸጎጫ ቁልፍ | TTL |
| ---------------------- | -------------- | ---------- |
| `models` | `models:v1` | እስከሚጻፍ ድረስ |
| `provider_connections` | `providers:v1` | እስከሚጻፍ ድረስ |
| `settings` | `settings:v1` | እስከሚጻፍ ድረስ |
| `combos` | `combos:v1` | እስከሚጻፍ ድረስ |
በተዛማጁ ሰንጠረዥ ላይ በሚደረግ እያንዳንዱ ጽሑፍ መሸጎጫው ዋጋ አልባ ይደረጋል።
---
## ምትኬ እና መልሶ ማግኘት
### በእጅ የሚደረግ ምትኬ
```bash
# አካባቢያዊ ምትኬ ለመፍጠር CLIን ይጠቀሙ
omniroute backup create --name pre-migration
# ወይም በAPI በኩል
curl -X PUT http://localhost:20128/api/db-backups \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "pre-migration"}'
```
የምትኬ ፋይሉ የሚከተሉትን ያካትታል፦
- ሁሉንም የDB ሰንጠረዦች (ወደ JSON የተከታተሉ)
- የጥሪ ምዝግብ ቅርሶች (በbase64 የተመሰጠሩ፣ አማራጭ)
- ቅንብሮች + ሚስጥሮች (የተመሰጠሩ)
- የተሰኪ ውቅር
### መልሶ ማግኘት
```bash
# በCLI በኩል
omniroute restore pre-migration
# በAPI በኩል
curl -X POST http://localhost:20128/api/db-backups/restore \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "pre-migration"}'
```
> **ማስጠንቀቂያ**፦ መልሶ ማግኘት መላውን DB ይተካል። በመጀመሪያ ሁሉንም ደንበኞች ያቁሙ።
### ራስ-ሰር ምትኬዎች
```bash
# በCLI በኩል ራስ-ሰር ዕለታዊ ምትኬዎችን ያንቁ
omniroute backup auto enable --cron "0 2 * * *" --retention 7
```
መርሐግብሩ በየ30 ሰከንዱ በሚሠራ የበስተጀርባ ሥራ
(ነባሪ) በአገልጋዩ በኩል ይከናወናል፣ እንዲሁም የcron አገላለጹን ከአካባቢያዊ የአገልጋይ ሰዓት አንጻር ይገመግማል።
| ተለዋዋጭ | ነባሪ | መግለጫ |
| ------------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS` | `30000` | የምልክት ክፍተት በms (ዝቅተኛው `5000`)። በተዛማጁ የcron ደቂቃ ውስጥ በአስተማማኝ ሁኔታ ለመግባት ከ60 s ያነሰ መሆን አለበት። |
### SQLite ትኩስ ምትኬ
የቀጥታ DBን ያለ የአገልግሎት መቋረጥ ለመጠባበቅ፦
```bash
sqlite3 ~/.omniroute/storage.sqlite ".backup /backups/omniroute-hot.db"
```
ይህ የSQLiteን የመስመር ላይ ምትኬ API ይጠቀማል — OmniRoute እየሠራ ሳለ ማስኬዱ ደህንነቱ የተጠበቀ ነው።
---
## የአፈጻጸም ማስተካከያ
### WAL ሁነታ
WAL በነባሪነት ነቅቷል። ብዙ የጽሑፍ ሥራዎች ላሏቸው ጭነቶች፣ የሚከተለውን ያስቡበት፦
```sql
PRAGMA wal_autocheckpoint = 1000; -- በየ1000 ገጾች Checkpoint ያድርጉ
PRAGMA journal_size_limit = 67108864; -- 64MB የWAL ገደብ
```
### ማውጫዎች
ለአፈጻጸም ቁልፍ የሆኑ ማውጫዎች (በማይግሬሽኖች በራስ-ሰር የሚፈጠሩ)፦
- `idx_models_provider` — በአቅራቢ የሞዴል ፍለጋዎች
- `idx_combo_targets_combo_id` — የኮምቦ ዒላማ ማስፋፊያ
- `idx_usage_history_api_key_timestamp` — የአጠቃቀም ትንታኔ
- `idx_quota_snapshots_api_key_window` — የኮታ ክትትል
- `idx_call_logs_timestamp` — የጥሪ ምዝግብ መጠይቆች
አዲስ ማውጫ ለመጨመር፣ ማይግሬሽን ይፍጠሩ፦
```sql
-- 023_add_my_index.sql
CREATE INDEX IF NOT EXISTS idx_my_table_my_column ON my_table(my_column);
```
### በማህደረ ትውስታ የተሰናሰለ I/O
በጣም ትልቅ ለሆኑ የውሂብ ጎታዎች (>10GB)፣ የማህደረ ትውስታ ስነዳውን በSQLite pragma በኩል ማስተካከል ይቻላል፦
```sql
-- በSQLite pragma በኩል ያዘጋጁ (በcore.ts ወይም በruntime ውስጥ ያስተካክሉ)
PRAGMA mmap_size = 268435456; -- 256MB
```
### ማጠቃለያ
ለረጅም ጊዜ የሚሰሩ የOmniRoute ኢንስታንሶች አልፎ አልፎ `VACUUM` በማድረግ ይጠቀማሉ፦
```bash
sqlite3 ~/.omniroute/storage.sqlite "VACUUM;"
```
ትራፊክ ዝቅተኛ በሆነባቸው ጊዜያት በየወሩ ያስኪዱት። (WAL ሁነታ ፍላጎቱን ይቀንሳል፣ ነገር ግን ሙሉ በሙሉ አያስወግደውም።)
---
## የጤና ምርመራ
`src/lib/db/healthCheck.ts` **በDB ደረጃ የጤና ምርመራዎችን** ያቀርባል፦
ሁለቱም ግሶች ማረጋገጫ ይፈልጋሉ (ካልሆነ `401`)። `GET` ምርመራ ብቻ ያደርጋል፤ `POST` ደግሞ
`autoRepair` ነቅቶ ተመሳሳዩን ምርመራ ያስኬዳል።
```bash
GET /api/db/health # ምርመራ
POST /api/db/health # ምርመራ + ጥገና
```
ምላሹ በ`runDbHealthCheck()` የሚፈጠረው `DbHealthCheckResult` ነው
(`src/lib/db/healthCheck.ts`)፦
```json
{
"isHealthy": false,
"issues": [
{
"type": "broken_reference",
"table": "domain_budgets",
"description": "የጎራ በጀቶች ከአሁን በኋላ የሌሉ API ቁልፎችን ዋቢ አድርገዋል።",
"count": 2
}
],
"repairedCount": 0,
"backupCreated": false,
"autoRepair": false,
"checkedAt": "2026-08-18T09:00:00.000Z",
"driver": { "name": "better-sqlite3", "degraded": false }
}
```
| መስክ | ትርጉም |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `isHealthy` | `issues` ባዶ ሲሆን `true` ነው። `driver` በምንም ጊዜ ተጽዕኖ አያሳድርበትም። |
| `issues[].type` | ከ`integrity_check_failed`፣ `broken_reference`፣ `stale_snapshot`፣ `invalid_state` አንዱ። |
| `repairedCount` | በዚህ ማስኬጃ ወቅት የተጠገኑ ረድፎች፤ `autoRepair` false ሲሆን ሁልጊዜ `0` ነው። |
| `backupCreated` | ከጥገናው በፊት ምትኬ ተወስዶ እንደሆነ። |
| `checkedAt` | ማስኬጃው እና የሚጽፈው ማንኛውም የጥገና ማስታወሻ የሚጋሩት ISO የጊዜ ማኅተም። |
| `driver.name` | የተመረመረውን የውሂብ ጎታ የሚያገለግለው SQLite driver። |
| `driver.degraded` | ጽሑፎች በውሂብ ጎታው ፋይል በዘላቂነት የማይደገፉ ሲሆን `true` ነው — የ`sql.js` WASM አማራጭ (የሙሉ ፋይል ቋሚ ማከማቻ) ወይም በማህደረ ትውስታ ውስጥ ያለ የውሂብ ጎታ። |
ተመሳሳዩ ይዘት በ`omniroute_db_health_check` MCP መሣሪያም ይመለሳል።
ብልሽትን ለመለየት `PRAGMA integrity_check`ን ያስኪዱ፦
```bash
sqlite3 ~/.omniroute/storage.sqlite "PRAGMA integrity_check;"
# ይህን ማተም አለበት፦ ok
```
ከ`ok` ውጭ ማንኛውንም ነገር ከመለሰ፣ **የውሂብ ጎታውን መጠቀም ወዲያውኑ ያቁሙ** እና ከምትኬ ይመልሱት።
---
## ከአደጋ መልሶ ማግኘት
### ሁኔታ 1፦ የWAL ፋይል ጠፍቷል
የ`-wal` ፋይሉ ጠፍቷል፣ ነገር ግን `-shm` እና ዋናው DB ሳይበላሹ አሉ፦
```bash
# በሚቀጥለው ጊዜ ሲከፈት በራስ-ሰር መልሶ ያገኛል
omniroute
```
SQLite በራስ-ሰር መልሶ ማግኘት ካልቻለ፦
```bash
sqlite3 ~/.omniroute/storage.sqlite ".recover" > recovered.sql
sqlite3 recovered.db < recovered.sql
mv recovered.db ~/.omniroute/storage.sqlite
```
### ሁኔታ 2፦ ዋናው የDB ፋይል ተበላሽቷል
ከመጠባበቂያ ቅጂ ወደነበረበት ይመልሱ፦
```bash
omniroute sync pull --merge # ወይም፦ omniroute backup restore <backup-id>
```
### ሁኔታ 3፦ የምስጠራ ቁልፍ ጠፍቷል
ያለ ቁልፉ **መልሶ ማግኘት አይቻልም**። የተመሰጠሩት መስኮች ሊነበቡ አይችሉም። ሁሉንም አቅራቢዎች በአዲስ ማረጋገጫዎች በእጅ እንደገና ያክሉ።
> **መከላከያ**፦ ሁልጊዜ የምስጠራ ቁልፉን ለብቻው መጠባበቂያ ቅጂ ያስቀምጡ፤ በተሻለ ሁኔታ በየይለፍ ቃል አስተዳዳሪ ወይም KMS ውስጥ።
### ሁኔታ 4፦ ዲስኩ ሞልቷል
SQLite የ`SQLITE_FULL` ስህተቶችን ይመልሳል። የዲስክ ቦታ ነፃ ያድርጉ፣ ከዚያ፦
```bash
# ቦታ ነፃ ለማድረግ WALን የማረጋገጫ ነጥብ ያከናውኑ
sqlite3 ~/.omniroute/storage.sqlite "PRAGMA wal_checkpoint(TRUNCATE);"
```
---
## የተለመዱ ክዋኔዎች
### ሰንጠረዥን መመርመር
```bash
sqlite3 ~/.omniroute/storage.sqlite "SELECT * FROM api_keys LIMIT 5;"
```
### በሁሉም ሰንጠረዦች ውስጥ ያሉ ረድፎችን መቁጠር
```bash
sqlite3 ~/.omniroute/storage.sqlite <<EOF
SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%';
EOF
```
### ሁሉንም ውሂብ ዳግም ማስጀመር (ማጥፋት)
```bash
# መጀመሪያ OmniRouteን ያቁሙ
omniroute stop
# የDB ፋይሉን ይሰርዙ
rm ~/.omniroute/storage.sqlite*
# እንደገና ያስጀምሩ (ባዶ DB እንደገና ይፈጥራል)
omniroute
```
ለ**ተመራጭ** ዳግም ማስጀመር (አቅራቢዎችን አቆይቶ የአጠቃቀም ውሂብን ለማጥፋት)፦
```bash
DELETE FROM usage_history WHERE timestamp < datetime('now', '-30 day');
DELETE FROM call_logs WHERE timestamp < datetime('now', '-30 day');
DELETE FROM proxy_logs WHERE timestamp < datetime('now', '-30 day');
```
### አንድ ሰንጠረዥ ወደ ውጭ መላክ
```bash
sqlite3 ~/.omniroute/storage.sqlite <<EOF
.mode csv
.output api_keys.csv
SELECT * FROM api_keys;
EOF
```
---
## ችግር ፍቺ
### "የውሂብ ጎታው ተቆልፏል"
ሌላ ሂደት የመጻፍ መቆለፊያ ይዟል። ከሚከተሉት አንዱን ያድርጉ፦
- ሌላው ሂደት እስኪጠናቀቅ ይጠብቁ (`lsof | grep storage.sqlite`ን ይፈትሹ)
- ሌላውን ሂደት ያቋርጡ
- ችግሩ ከቀጠለ OmniRouteን እንደገና ያስጀምሩ
### "የውጭ ቁልፍ ገደብ አልተሳካም"
አንድ የጎራ ሞጁል የማጣቀሻ ታማኝነትን እየጣሰ ነው። የሚከተሉትን ይፈትሹ፦
- በጥገኛ ሰንጠረዦች ውስጥ ያሉ ወላጅ-አልባ ረድፎች
- ያልተሰራጩ ተከታታይ ስረዛዎች
- የውጭ ቁልፍን የቀየረ የቅርብ ጊዜ ፍልሰት
ጥሰቶችን ለማግኘት `PRAGMA foreign_key_check;`ን ያስኪዱ።
### "የማህደረ ትውስታ እጥረት"
የSQLite በማህደረ ትውስታ ላይ የተመሠረተ I/O የOS ገደቡን እያለፈ ነው። በSQLite pragma በኩል ይቀንሱት፦
```sql
PRAGMA mmap_size = 134217728; -- ከ256MB ይልቅ 128MB
```
ወይም ያሰናክሉት፦
```sql
PRAGMA mmap_size = 0;
```
### "ፍልሰቱ በመካከል አልተሳካም"
ፍልሰቱ በግብይት ውስጥ የተከናወነ ስለሆነ ወደ ነበረበት መመለስ ነበረበት። ካልተመለሰ፦
1. **OmniRouteን ያቁሙ** (ተጨማሪ ሙከራዎችን ለመከላከል)
2. **የDBውን ሁኔታ ይፈትሹ** `sqlite3`ን በመጠቀም
3. **በእጅ ያስተካክሉ** ከፊል ፍልሰቱን
4. **እንደገና ያስኪዱ** OmniRouteን (ፍልሰቱ እንደገና ይሞከራል)
ይህን ለመከላከል ሁልጊዜ ፍልሰቶችን መጀመሪያ በቅጂ ላይ ይፈትሹ።
---
## በተጨማሪ ይመልከቱ
- [USAGE_QUOTA_GUIDE.md](../guides/USAGE_QUOTA_GUIDE.md) — የአጠቃቀም ሰንጠረዦች
- [MONITORING_GUIDE.md](./MONITORING_GUIDE.md) — የጤንነት ክትትል
- [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md) — የልቀት ፍሰት
- ምንጭ፦ `src/lib/db/` (80+ ፋይሎች፣ ~25K LOC)

98
docs/i18n/am/docs/ops/HOMOLOGATION.md Normal file
View File

@@ -0,0 +1,98 @@
# Homologation Suite (`npm run homolog`) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/HOMOLOGATION.md) · 🇸🇦 [ar](../../../ar/docs/ops/HOMOLOGATION.md) · 🇦🇿 [az](../../../az/docs/ops/HOMOLOGATION.md) · 🇧🇬 [bg](../../../bg/docs/ops/HOMOLOGATION.md) · 🇧🇩 [bn](../../../bn/docs/ops/HOMOLOGATION.md) · 🇨🇿 [cs](../../../cs/docs/ops/HOMOLOGATION.md) · 🇩🇰 [da](../../../da/docs/ops/HOMOLOGATION.md) · 🇩🇪 [de](../../../de/docs/ops/HOMOLOGATION.md) · 🇬🇷 [el](../../../el/docs/ops/HOMOLOGATION.md) · 🇪🇸 [es](../../../es/docs/ops/HOMOLOGATION.md) · 🇪🇪 [et](../../../et/docs/ops/HOMOLOGATION.md) · 🇮🇷 [fa](../../../fa/docs/ops/HOMOLOGATION.md) · 🇫🇮 [fi](../../../fi/docs/ops/HOMOLOGATION.md) · 🇫🇷 [fr](../../../fr/docs/ops/HOMOLOGATION.md) · 🇮🇪 [ga](../../../ga/docs/ops/HOMOLOGATION.md) · 🇮🇳 [gu](../../../gu/docs/ops/HOMOLOGATION.md) · 🇳🇬 [ha](../../../ha/docs/ops/HOMOLOGATION.md) · 🇮🇱 [he](../../../he/docs/ops/HOMOLOGATION.md) · 🇮🇳 [hi](../../../hi/docs/ops/HOMOLOGATION.md) · 🇭🇷 [hr](../../../hr/docs/ops/HOMOLOGATION.md) · 🇭🇺 [hu](../../../hu/docs/ops/HOMOLOGATION.md) · 🇦🇲 [hy](../../../hy/docs/ops/HOMOLOGATION.md) · 🇮🇩 [id](../../../id/docs/ops/HOMOLOGATION.md) · 🇳🇬 [ig](../../../ig/docs/ops/HOMOLOGATION.md) · 🇮🇹 [it](../../../it/docs/ops/HOMOLOGATION.md) · 🇯🇵 [ja](../../../ja/docs/ops/HOMOLOGATION.md) · 🇬🇪 [ka](../../../ka/docs/ops/HOMOLOGATION.md) · 🇰🇭 [km](../../../km/docs/ops/HOMOLOGATION.md) · 🇮🇳 [kn](../../../kn/docs/ops/HOMOLOGATION.md) · 🇰🇷 [ko](../../../ko/docs/ops/HOMOLOGATION.md) · 🇱🇹 [lt](../../../lt/docs/ops/HOMOLOGATION.md) · 🇱🇻 [lv](../../../lv/docs/ops/HOMOLOGATION.md) · 🇮🇳 [ml](../../../ml/docs/ops/HOMOLOGATION.md) · 🇮🇳 [mr](../../../mr/docs/ops/HOMOLOGATION.md) · 🇲🇾 [ms](../../../ms/docs/ops/HOMOLOGATION.md) · 🇲🇹 [mt](../../../mt/docs/ops/HOMOLOGATION.md) · 🇲🇲 [my](../../../my/docs/ops/HOMOLOGATION.md) · 🇳🇵 [ne](../../../ne/docs/ops/HOMOLOGATION.md) · 🇳🇱 [nl](../../../nl/docs/ops/HOMOLOGATION.md) · 🇳🇴 [no](../../../no/docs/ops/HOMOLOGATION.md) · 🇮🇳 [or](../../../or/docs/ops/HOMOLOGATION.md) · 🇮🇳 [pa](../../../pa/docs/ops/HOMOLOGATION.md) · 🇵🇭 [phi](../../../phi/docs/ops/HOMOLOGATION.md) · 🇵🇱 [pl](../../../pl/docs/ops/HOMOLOGATION.md) · 🇵🇹 [pt](../../../pt/docs/ops/HOMOLOGATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/HOMOLOGATION.md) · 🇷🇴 [ro](../../../ro/docs/ops/HOMOLOGATION.md) · 🇷🇺 [ru](../../../ru/docs/ops/HOMOLOGATION.md) · 🇱🇰 [si](../../../si/docs/ops/HOMOLOGATION.md) · 🇸🇰 [sk](../../../sk/docs/ops/HOMOLOGATION.md) · 🇸🇮 [sl](../../../sl/docs/ops/HOMOLOGATION.md) · 🇷🇸 [sr](../../../sr/docs/ops/HOMOLOGATION.md) · 🇸🇪 [sv](../../../sv/docs/ops/HOMOLOGATION.md) · 🇰🇪 [sw](../../../sw/docs/ops/HOMOLOGATION.md) · 🇮🇳 [ta](../../../ta/docs/ops/HOMOLOGATION.md) · 🇮🇳 [te](../../../te/docs/ops/HOMOLOGATION.md) · 🇹🇭 [th](../../../th/docs/ops/HOMOLOGATION.md) · 🇹🇷 [tr](../../../tr/docs/ops/HOMOLOGATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/HOMOLOGATION.md) · 🇵🇰 [ur](../../../ur/docs/ops/HOMOLOGATION.md) · 🇺🇿 [uz](../../../uz/docs/ops/HOMOLOGATION.md) · 🇻🇳 [vi](../../../vi/docs/ops/HOMOLOGATION.md) · 🇳🇬 [yo](../../../yo/docs/ops/HOMOLOGATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/HOMOLOGATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/HOMOLOGATION.md)
---
በ homologation VPS ላይ የሚሰራውን OmniRoute deploy በእውነተኛ አካባቢ የሚያረጋግጥ E2E ማረጋገጫ
(`HOMOLOG_BASE_URL`፣ ለምሳሌ `http://192.168.0.15:20128`)። አንድ ትዕዛዝ የrelease STOP #2 በእጅ የሚከናወን የማረጋገጫ ዝርዝርን በራስ-ሰር በሚከናወንና ማስረጃ በሚያመነጭ ሂደት ይተካል።
## የሚሸፍነው
| ንብርብር | የሚያረጋግጠው | አተገባበር |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| L0 — ጤና/ተመሳሳይነት | `/api/monitoring/health` በ`200`፣ በ`status: "healthy"` እና በሚጠበቀው version ምላሽ መስጠቱን | `scripts/homolog/lib/parity.mjs` |
| L1a — ጊዜያዊ key | የAdmin login → `POST /api/keys` ለሂደቱ የተወሰነ scope ያለው API key ይፈጥራል፤ ውጤቱ ምንም ቢሆን በ`finally` block ውስጥ ይሻራል (`DELETE /api/keys/:id`) | `scripts/homolog/lib/adminClient.mjs` |
| L1b — የAPI ወሰን | የ`/v1/models` catalog፣ እውነተኛ non-streaming chat completion (tier-critical model፣ `max_tokens: 5`)፣ ልክ ላልሆነ key `401`፣ እና ይፋዊ `/api/monitoring/health` | `tests/homolog/api/core.http` (httpYac) |
| L1c — SSE streaming | እውነተኛ streaming chat completion፤ `text/event-stream` መሆኑን፣ ቢያንስ አንድ content delta መኖሩን እና የ`[DONE]` ማብቂያ መኖሩን ያረጋግጣል | `scripts/homolog/lib/sseCheck.mjs` |
| L2 — እውነተኛ providers | በቀጥታ ባለው `/v1/models` catalog ውስጥ ለሚገኝ ለእያንዳንዱ ወሳኝ provider አንድ ዝቅተኛ ወጪ ያለው chat request፣ በpromptfoo በሂደቱ ወቅት የሚመነጭ | `scripts/homolog/gen-promptfoo.mjs` + `scripts/homolog/lib/providerTiers.mjs` |
| L4a — የUI auth | በእውነተኛው login form በኩል አንድ ጊዜ ይገባል፣ እና session-ን (`storageState`) በUI layer በሙሉ እንደገና ይጠቀማል | `tests/homolog/ui/auth.setup.ts` |
| L4b — የUI routes | በ`src/app/(dashboard)/dashboard` ስር ያለ እያንዳንዱ static `page.tsx` (ከfilesystem የሚገኝ፣ dynamic `[param]` routes የሚዘለሉ) ያለ HTTP error፣ page error ወይም የNext.js error boundary ይጫናል | `tests/homolog/ui/routes.spec.ts` |
| L4c — ወሳኝ የUI ፍሰት | በdashboard UI በኩል API key ይፈጥራል እና እንደገና ይሽረዋል (በVPS ላይ ምንም ቅሪት አይተውም) | `tests/homolog/ui/api-key-flow.spec.ts` |
| L5 — የተዋሃደ report | httpYac (በ`junit-to-ctrf`)፣ promptfoo→CTRF adapter፣ እና Playwright CTRF reporter-ን ወደ አንድ `homolog-ctrf.json` ያዋህዳል፤ በተጨማሪም ለሰው ለማንበብ የሚመች `homolog-report/summary.md` ይፈጥራል | `scripts/homolog/run.mjs` |
በreplay ራሱ ውስጥ የLLM ተሳትፎ ፈጽሞ የለም — ይህ የተወሰነ ውጤት ያለው regression battery እንጂ eval አይደለም። AI የሚገባው ወደፊት በሚደረግ የmaintenance ሥራ ውስጥ ብቻ ነው (ከታች Roadmapን ይመልከቱ)።
## ቅድመ ሁኔታዎች
1. `.env.homolog.example`ን ወደ `.env.homolog` ይቅዱ (በ git ችላ የሚባል — ፈጽሞ commit አያድርጉት) እና የሚከተሉትን ይሙሉ፦
- `HOMOLOG_BASE_URL` — የታለመው deploy፣ ለምሳሌ `http://192.168.0.15:20128`።
- `HOMOLOG_ADMIN_PASSWORD` — ለዚያ deploy የዳሽቦርድ አስተዳደር የይለፍ ቃል።
- `HOMOLOG_CRITICAL_PROVIDERS` — እውነተኛ የ smoke chat ጥያቄ የሚደርሳቸው፣ በኮማ የተለያዩ የአቅራቢ ቅድመ ቅጥያዎች (ለምሳሌ `openai,anthropic,gemini,codex,grok,glm,deepseek,openrouter`)።
- `HOMOLOG_API_KEY` — በመደበኛ ሙከራዎች ባዶ ይተዉት፤ suiteው የራሱን ጊዜያዊ ቁልፍ ይፈጥራል እና ይሰርዛል። ይህን የሚያቀናብሩት አንድን layer ለብቻው debug ለማድረግ ብቻ ነው።
2. በrepoው ውስጥ `npm install`ን ያሂዱ (የsuiteው dependencies — `httpyac`, `promptfoo`,
`playwright-ctrf-json-reporter`, `junit-to-ctrf`, `ctrf` — መደበኛ devDependencies ናቸው)።
3. የbrowser binaries አስቀድመው ከሌሉ `npx playwright install`ን ያሂዱ።
## እንዴት እንደሚሄድ
```bash
npm run homolog
```
ስሪቱ ከአካባቢያዊው `package.json` ጋር የማይዛመድ deployን
ለማረጋገጥ (ለምሳሌ፣ አሁንም በቀደመው patch release ላይ ያለ homologation box)፣ የሚጠበቀውን
ስሪት በግልጽ override ያድርጉ፦
```bash
HOMOLOG_EXPECT_VERSION=3.8.47 npm run homolog
```
ማንኛውም layer ከወደቀ ሂደቱ ከዜሮ የተለየ የመውጫ ኮድ ይመልሳል፣ እና ቢወድቅም እንኳ ሁልጊዜ የፈጠረውን ጊዜያዊ
API key ለመሰረዝ ይሞክራል (`finally` block በ`scripts/homolog/run.mjs` ውስጥ)።
## ሪፖርቱን ማንበብ
ሁሉም ውጤቶች በ`homolog-report/` ውስጥ ይቀመጣሉ (በ git ችላ የሚባል)፦
- `summary.md` — ወደ stdout የሚታተመው ያው ሰንጠረዥ፣ ለእያንዳንዱ layer አንድ ረድፍ (✅/❌ + ዝርዝር)።
- `homolog-ctrf.json` — የተዋሃደው CTRF ሪፖርት (የAPI/SSE፣ provider-smoke እና
UI ውጤቶች ውህደት) — ከrelease STOP #2 checklist ጋር መያያዝ ያለበት artifact ይህ ነው።
- `httpyac-junit.xml`, `api-ctrf.json`, `providers-ctrf.json`, `ui-ctrf.json` — የእያንዳንዱ
layer ጥሬ/መካከለኛ ሪፖርቶች።
- `promptfooconfig.yaml`, `provider-misses.json` — ለአሁኑ ሂደት የተፈጠረው promptfoo config እና
ከቀጥታ catalog የጎደሉ ማናቸውም ወሳኝ አቅራቢዎች።
የወደቀ L0 ወዲያውኑ ሂደቱን ያቋርጣል (ምንም ጊዜያዊ ቁልፍ አይፈጠርም)፤ ምክንያቱም የስሪት/ጤና
አለመዛመድ ማለት ከዚያ በታች ያለው እያንዳንዱ layer የተሳሳተውን deploy እንደሚያረጋግጥ ማለት ነው።
## UIው በትክክል ሲለወጥ መነሻውን እንደገና ማዘጋጀት
L4b (route smoke) እና L4c (API-key UI flow) የሚመሩት በእውነተኛ DOM locators እንጂ
በsnapshots አይደለም፤ ስለዚህ አብዛኛዎቹ ትክክለኛ የUI ለውጦች የsuite ማሻሻያ አያስፈልጋቸውም። አንድ ለውጥ
locatorን ሲያበላሽ (ለምሳሌ፣ ስሙ የተቀየረ የአዝራር መለያ ወይም የተዛወረ settings page)፦
1. locatorን አሁን ካለው source ጋር እንደገና ያረጋግጡ (specsዎቹ እያንዳንዱ locator በየትኛው
file/line እንደተረጋገጠ አስቀድመው ይመዘግባሉ — ያንኑ ንድፍ ይከተሉ፣ አይገምቱ)።
2. በ`tests/homolog/ui/` ውስጥ ያለውን spec ያዘምኑ።
3. ማስተካከያውን ለማረጋገጥ `npm run homolog`ን (ወይም የተጎዳውን Playwright spec ብቻ) በVPS ላይ
እንደገና ያሂዱ፣ ከዚያ commit ያድርጉ።
በዚህ suite ውስጥ የvisual/pixel baseline የለም (F1) — ለዚያ Roadmapን ይመልከቱ።
## የወደፊት ዕቅድ (F2 / F3)
ዲዛይኑ እና ደረጃ በደረጃ ትግበራው በውስጣዊው የዕቅድ spec
`_tasks/superpowers/specs/2026-07-13-homolog-e2e-suite-design.md` ውስጥ ይገኛሉ (አልተገናኘም — ውስጣዊ
`_tasks/` artifact ነው፣ የዚህ repo ክትትል ከሚደረግባቸው docs ክፍል አይደለም)። ማጠቃለያ፦
- **F2** — ሙሉ walkthrough recording → Playwright Test Agents (`planner`/`generator`)
ወደ flow specs ይቀይሩታል (combo መፍጠር፣ providerን መፈተሽ፣ settingsን ማርትዕ፣ MCP tools) +
ተለዋዋጭ dataን (metrics፣ timestamps፣ logs) የሚሸፍኑ masks ያሉት visual regression baseline (Lost Pixel) +
ለእያንዳንዱ release የ`healer` የጥገና ሂደት።
- **F3** — የresilience/contract/wiring ሽፋን፦ toxiproxy + በdevbox ላይ ያለ አስመሳይ OpenAI-compatible
provider፣ ወደ እሱ የተጠቆመ በVPS ላይ ያለ `homolog-resilience` combo
(የተገባ timeout → fallbackን + circuit breaker open/closeን በ
`/api/monitoring/health` በኩል ማረጋገጥ)፤ ከ
`docs/openapi.yaml` ጋር gated Schemathesis contract testing (ዝቅተኛ `--max-examples`፣ ቋሚ seeds፣ LLM ያልሆኑ endpoints ብቻ)፤ እና
`npm run homolog`ን + የእሱን `summary.md` ወደ `/generate-release` STOP #2 phase ማገናኘት።

71
docs/i18n/am/docs/ops/MERGE_TRAIN.md Normal file
View File

@@ -0,0 +1,71 @@
# Merge Queue & Manual Merge-Train Runbook (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/MERGE_TRAIN.md) · 🇸🇦 [ar](../../../ar/docs/ops/MERGE_TRAIN.md) · 🇦🇿 [az](../../../az/docs/ops/MERGE_TRAIN.md) · 🇧🇬 [bg](../../../bg/docs/ops/MERGE_TRAIN.md) · 🇧🇩 [bn](../../../bn/docs/ops/MERGE_TRAIN.md) · 🇨🇿 [cs](../../../cs/docs/ops/MERGE_TRAIN.md) · 🇩🇰 [da](../../../da/docs/ops/MERGE_TRAIN.md) · 🇩🇪 [de](../../../de/docs/ops/MERGE_TRAIN.md) · 🇬🇷 [el](../../../el/docs/ops/MERGE_TRAIN.md) · 🇪🇸 [es](../../../es/docs/ops/MERGE_TRAIN.md) · 🇪🇪 [et](../../../et/docs/ops/MERGE_TRAIN.md) · 🇮🇷 [fa](../../../fa/docs/ops/MERGE_TRAIN.md) · 🇫🇮 [fi](../../../fi/docs/ops/MERGE_TRAIN.md) · 🇫🇷 [fr](../../../fr/docs/ops/MERGE_TRAIN.md) · 🇮🇪 [ga](../../../ga/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [gu](../../../gu/docs/ops/MERGE_TRAIN.md) · 🇳🇬 [ha](../../../ha/docs/ops/MERGE_TRAIN.md) · 🇮🇱 [he](../../../he/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [hi](../../../hi/docs/ops/MERGE_TRAIN.md) · 🇭🇷 [hr](../../../hr/docs/ops/MERGE_TRAIN.md) · 🇭🇺 [hu](../../../hu/docs/ops/MERGE_TRAIN.md) · 🇦🇲 [hy](../../../hy/docs/ops/MERGE_TRAIN.md) · 🇮🇩 [id](../../../id/docs/ops/MERGE_TRAIN.md) · 🇳🇬 [ig](../../../ig/docs/ops/MERGE_TRAIN.md) · 🇮🇹 [it](../../../it/docs/ops/MERGE_TRAIN.md) · 🇯🇵 [ja](../../../ja/docs/ops/MERGE_TRAIN.md) · 🇬🇪 [ka](../../../ka/docs/ops/MERGE_TRAIN.md) · 🇰🇭 [km](../../../km/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [kn](../../../kn/docs/ops/MERGE_TRAIN.md) · 🇰🇷 [ko](../../../ko/docs/ops/MERGE_TRAIN.md) · 🇱🇹 [lt](../../../lt/docs/ops/MERGE_TRAIN.md) · 🇱🇻 [lv](../../../lv/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [ml](../../../ml/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [mr](../../../mr/docs/ops/MERGE_TRAIN.md) · 🇲🇾 [ms](../../../ms/docs/ops/MERGE_TRAIN.md) · 🇲🇹 [mt](../../../mt/docs/ops/MERGE_TRAIN.md) · 🇲🇲 [my](../../../my/docs/ops/MERGE_TRAIN.md) · 🇳🇵 [ne](../../../ne/docs/ops/MERGE_TRAIN.md) · 🇳🇱 [nl](../../../nl/docs/ops/MERGE_TRAIN.md) · 🇳🇴 [no](../../../no/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [or](../../../or/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [pa](../../../pa/docs/ops/MERGE_TRAIN.md) · 🇵🇭 [phi](../../../phi/docs/ops/MERGE_TRAIN.md) · 🇵🇱 [pl](../../../pl/docs/ops/MERGE_TRAIN.md) · 🇵🇹 [pt](../../../pt/docs/ops/MERGE_TRAIN.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/MERGE_TRAIN.md) · 🇷🇴 [ro](../../../ro/docs/ops/MERGE_TRAIN.md) · 🇷🇺 [ru](../../../ru/docs/ops/MERGE_TRAIN.md) · 🇱🇰 [si](../../../si/docs/ops/MERGE_TRAIN.md) · 🇸🇰 [sk](../../../sk/docs/ops/MERGE_TRAIN.md) · 🇸🇮 [sl](../../../sl/docs/ops/MERGE_TRAIN.md) · 🇷🇸 [sr](../../../sr/docs/ops/MERGE_TRAIN.md) · 🇸🇪 [sv](../../../sv/docs/ops/MERGE_TRAIN.md) · 🇰🇪 [sw](../../../sw/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [ta](../../../ta/docs/ops/MERGE_TRAIN.md) · 🇮🇳 [te](../../../te/docs/ops/MERGE_TRAIN.md) · 🇹🇭 [th](../../../th/docs/ops/MERGE_TRAIN.md) · 🇹🇷 [tr](../../../tr/docs/ops/MERGE_TRAIN.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/MERGE_TRAIN.md) · 🇵🇰 [ur](../../../ur/docs/ops/MERGE_TRAIN.md) · 🇺🇿 [uz](../../../uz/docs/ops/MERGE_TRAIN.md) · 🇻🇳 [vi](../../../vi/docs/ops/MERGE_TRAIN.md) · 🇳🇬 [yo](../../../yo/docs/ops/MERGE_TRAIN.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/MERGE_TRAIN.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/MERGE_TRAIN.md)
---
ከv3.8.49 (የጥራት/ፍጥነት ዕቅዱ WS3.2/WS3.4) ጀምሮ፣ የተገመገሙ PRዎችን ወደ
`release/vX.Y.Z` ለማዋሃድ ነባሪው መንገድ **Mergify merge queue** (`.mergify.yml`) ነው፤
ከዚህ በታች የተመዘገበው **በእጅ የሚከናወን merge-train** ተተኪ አማራጭ ነው — በክስተቶች፣
በልቀት እገዳዎች ወቅት፣ ወይም የMergify Open Source ዕቅድ ቢቀየር የሚያገለግል።
## ነባሪ መንገድ፦ የMergify ወረፋ
1. PRው በዘመቻዎቹ ተገምግሞ/አረንጓዴ ሆኖ፣ በባለቤቱ የቅድመ-ውህደት ⭐
በር ይፀድቃል (ሪፖርቱ + የእያንዳንዱ ንጥል ውሳኔ — `/merge-prs` ደረጃ 0.75ን ይመልከቱ)።
2. ባለቤቱ (ወይም በባለቤቱ ውሳኔ መሠረት የሚሠራው ክፍለ-ጊዜ) **`queue`**
መለያውን ያክላል። መለያው ራሱ የውህደት ፈቃድ ነው፤ Mergify የሚያደርገው እሱን ማስፈጸም ብቻ ነው።
3. Mergify በወረፋ ላይ ካሉ PRዎች እስከ 10 ድረስ በቡድን ያደራጃል፣ ቡድኑን በፈጣን በሮች ይፈትሻል፣
ከዚያም ያዋህዳል (squash)። ቀይ የሆነ ቡድን **በራስ-ሰር በሁለት ይከፈላል** — ችግር ያለበት PR
በ~log2(N) ዳግም ማረጋገጫዎች ተለይቶ ከወረፋው ይወጣል፤ የተቀሩት ይቀጥላሉ።
4. ከውህደት በኋላ፣ ቀጣይነት ያለው release-green workflow በpush ጊዜ አዲሱን tip ያረጋግጣል
እና ጥምረቱ የኋሊት መቀነስ ካስከተለ የአመጣጥ ጉዳይ ይከፍታል (በራስ-ሰር ፈጽሞ አይመልስም)።
የደህንነት ገደቦች (`CLAUDE.md` ጥብቅ ደንቦች #21/#22ን ያንጸባርቃሉ)፦
- **የልቀት እገዳ ክፍት ነው** → የታገደውን branch ዒላማ ላደረጉ PRዎች መለያ አትጨምሩ፤ መጀመሪያ ወደ
ንቁው `release/vX+1` ዳግም ዒላማ አድርጉ።
- **የሌላ ክፍለ-ጊዜ በሂደት ላይ ያለ PR** → ፈጽሞ መለያ አትጨምሩበት፤ የራሱን ሥራ ወረፋ የሚያስገባው
ባለቤት ክፍለ-ጊዜው ብቻ ነው።
- የሙከራ-ብቻ ልዩነቶች እና `hotfix` መለያ ያላቸው PRዎች አስቀድመው የተቀነሰ CI ያስኬዳሉ
(`RELEASE_CHECKLIST.md` → Hotfix Fast-Laneን ይመልከቱ)፤ የወረፋው ሁኔታዎች በትክክል የተከናወነውን
ማንኛውንም የፍተሻ ስብስብ ይቀበላሉ (`#check-failure=0` + `#check-pending=0`)።
## ተተኪ አማራጭ፦ በእጅ የሚከናወነው merge-train
ወረፋው በማይገኝበት ጊዜ ይጠቀሙበታል። ይህ በv3.8.47 ዑደት ወቅት በአንድ ቀን 33 PRዎችን
ያጠናቀቀውን አሠራር ደንብ ያደርገዋል፦
1. **ቡድኑን አሰባስቡ** (~10–30 የተገመገሙ+የፀደቁ PRዎች)። የ`linked:` ግጭቶችን
(ተመሳሳይ `tap.testFiles`፣ ተመሳሳይ የCHANGELOG ክፍሎች) ይፈትሹ እና እነዚያን በቅደም ተከተል ያስኬዱ።
2. **አንድ ጊዜ ብቻ ያረጋግጡ**፦ ከrelease tip በተነሳ በተነጠለ worktree ውስጥ ሁሉንም የቡድኑን
heads በአካባቢው ያዋህዱ፣ ከዚያም ከልቀቱ ጋር እኩል የሆነውን ስብስብ ያስኪዱ
(`npm run check:release-green`፣ ከልቀት በፊት `--with-build`ን ይጨምሩ)።
`scripts/release/merge-train.sh <base> <PR#>…` ደረጃዎች 1–2ን በራስ-ሰር ያከናውናል (የሚጋጩ
PRዎች ይወጣሉ፣ trainው ይቀጥላል)። ሙሉ ሁነታው `npm run test:unit`ን ያስኬዳል — ለ
box የተስተካከለው runner (`--test-concurrency=20`) እንጂ፣ ዋናውን ደረጃ በ16-core box
ላይ በ~25% እንዲሠራ ያደረጉትን ሁለት ተከታታይ 4-core CI shards አይደለም (በ
2026-07-18 ተስተካክሏል)። `--fast` (በቀን ውስጥ የmega-train ማጠናቀቂያዎች፣ በባለቤቱ የፀደቀ
2026-07-18) እያንዳንዱን static gate + vitest ይጠብቃል፣ ነገር ግን በተሳፈሩት PRዎች
የተቀየሩትን node:test ፋይሎች ብቻ ያስኬዳል፤ ሙሉው ስብስብ በተከማቸው tip ላይ
ቢያንስ በቀን አንድ ጊዜ መካሄድ አለበት (`--fast` የሌለው አንድ train)።
3. **አረንጓዴ** → PRዎቹን በቅደም ተከተል ያዋህዱ (ከእያንዳንዱ በፊት `state,headRefOid`ን ዳግም በመፈተሽ —
headው የተንቀሳቀሰ PR ወደ ግምገማ ይመለሳል)። የእያንዳንዱ ውህደት የተጣራ ልዩነት
የPRው የራሱ ለውጥ መሆኑን ያረጋግጡ (በራስ-ሰር የተፈቱ መመለሻዎች አይኑሩ፦ ከወሰን ውጭ የሆኑ
ስረዛዎችን ለማግኘት `git diff --stat`ን ይመርምሩ)።
4. **ቀይ** → አንድ በአንድ ዳግም ከማረጋገጥ ይልቅ ቡድኑን በግማሽ ይክፈሉ (እያንዳንዱን ግማሽ ያረጋግጡ)፤
ችግር ያለበትን PR ከማስረጃው ጋር ወደ ግምገማ ወረፋው ይመልሱ።
5. **ፈጽሞ አታድርጉ**፦ በእገዳ ወቅት ወደ ታገደው branch ማዋሃድ፤ `git stash`ን የትኛውም ቦታ መጠቀም፤
ቀይ ሁኔታ ይጠፋል በሚል ተስፋ CIን በጅምላ ዳግም ማስኬድ (ደንቡ፦ ቀይ ሁኔታ መረጃ ነው)።
## ደረጃ አከፋፈል (ወረፋው በፈጣን በሮች ብቻ ለምን ደህንነቱ እንደተጠበቀ)
- **በእያንዳንዱ PR** (quality.yml ፈጣን በሮች)፦ በTIA ተጽዕኖ ያገኙ ሙከራዎች + ሙሉ unit 4-shard +
vitest + lint bag + typecheck + የdocs/changelog ታማኝነት።
- **በእያንዳንዱ ቡድን/tip** (ቀጣይነት ያለው release-green)፦ ወደrelease branch በሚደረግ እያንዳንዱ push ላይ
`--quick` HARD gates፤ ሙሉ `--with-build --full-ci` ፍተሻዎች በቀን 3×።
- **በእያንዳንዱ ልቀት** (በrelease PR ላይ ci.yml)፦ E2E ×9ን፣
package-artifact + tarball boot-smokeን፣ coverage/ratchetsን ጨምሮ ሙሉው matrix።
ምንም ነገር ከቀድሞው ባነሰ ደረጃ አይረጋገጥም — ከባዱ የፍተሻ ወሰን ከበፊቱ በእያንዳንዱ PR ፋንታ
በእያንዳንዱ ቡድን/tip ይሠራል፤ O(N) የዙር-ጉዞዎችን የሚያስወግደውም ይህ ነው።

570
docs/i18n/am/docs/ops/MONITORING_GUIDE.md Normal file
View File

@@ -0,0 +1,570 @@
# Monitoring & Observability Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/MONITORING_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/MONITORING_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/MONITORING_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/MONITORING_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/MONITORING_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/MONITORING_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/MONITORING_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/MONITORING_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/MONITORING_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/MONITORING_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/MONITORING_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/MONITORING_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/MONITORING_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/MONITORING_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/MONITORING_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/MONITORING_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/MONITORING_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/MONITORING_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/MONITORING_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/MONITORING_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/MONITORING_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/MONITORING_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/MONITORING_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/MONITORING_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/MONITORING_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/MONITORING_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/MONITORING_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/MONITORING_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/MONITORING_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/MONITORING_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/MONITORING_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/MONITORING_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/MONITORING_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/MONITORING_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/MONITORING_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/MONITORING_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/MONITORING_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/MONITORING_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/MONITORING_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/MONITORING_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/MONITORING_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/MONITORING_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/MONITORING_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/MONITORING_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/MONITORING_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/MONITORING_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/MONITORING_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/MONITORING_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/MONITORING_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/MONITORING_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/MONITORING_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/MONITORING_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/MONITORING_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/MONITORING_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/MONITORING_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/MONITORING_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/MONITORING_GUIDE.md)
---
> **TL;DR**: OmniRoute አብሮገነብ የጤና ክትትል፣ የአቅራቢ autopilot፣ የኮታ መከታተያ እና የታዛቢነት hooks ይዞ ይመጣል። ይህ መመሪያ dashboardን፣ ማንቂያዎችን እና መላ ፍለጋን ይሸፍናል።
**ምንጮች፦**
- `src/lib/monitoring/observability.ts` — የታዛቢነት snapshot
- `src/lib/monitoring/comboHealthAutopilot.ts` — የcombo ጤና autopilot
- `src/lib/monitoring/providerHealthAutopilot.ts` — የአቅራቢ autopilot
- `src/lib/monitoring/providerHealthMatrix.ts` — የአቅራቢ ጤና matrix
- `src/lib/localHealthCheck.ts` — የአካባቢ ጤና ምርመራ
- `src/lib/tokenHealthCheck.ts` — የtoken እድሳት ጤና
- `src/lib/proxyHealth.ts` — የproxy ጤና cache (በPROXY_GUIDE.md ውስጥ ተሸፍኗል)
---
## አጠቃላይ እይታ
OmniRoute **3 የክትትል ንብርብሮች** አሉት፦
```
┌──────────────────────────────────────────────────────────────┐
│ ንብርብር 1፦ የስርዓት ጤና (በserver ደረጃ) │
│ ├─ localHealthCheck.ts — DB፣ ports፣ native deps │
│ ├─ db/healthCheck.ts — integrity፣ FK፣ orphaned artifacts │
│ └─ Dashboard፦ /dashboard/health │
├──────────────────────────────────────────────────────────────┤
│ ንብርብር 2፦ የአቅራቢ ጤና (የእያንዳንዱ አቅራቢ ጽናት) │
│ ├─ providerHealthAutopilot.ts — circuit breaker፣ cooldowns │
│ ├─ providerHealthMatrix.ts — በአቅራቢ/model የጤና ውጤቶች │
│ └─ Dashboard፦ /dashboard/providers │
├──────────────────────────────────────────────────────────────┤
│ ንብርብር 3፦ ቀጥታ ታዛቢነት (የruntime snapshots) │
│ ├─ observability.ts — circuit breakers፣ sessions፣ quota │
│ ├─ tokenHealthCheck.ts — የOAuth token እድሳት ጤና │
│ └─ MCP tools፦ omniroute_get_health, omniroute_get_session_snapshot │
└──────────────────────────────────────────────────────────────┘
```
---
## የDashboard ገጾች
### `/dashboard/health` (የስርዓት ጤና)
ከፍተኛ-ደረጃው የጤና dashboard የሚከተሉትን ያሳያል፦
| ክፍል | የሚያሳየው |
| ----------------- | --------------------------------------------------- |
| **የServer ሁኔታ** | Uptime፣ version፣ port፣ ንቁ connections |
| **Database** | Connection፣ integrity፣ የWAL መጠን፣ የቅርብ ጊዜ migrations |
| **የአቅራቢ ማጠቃለያ** | የንቁ፣ ጤናማ እና ክፍት breaker ብዛት |
| **የኮታ መከታተያዎች** | ንቁ sessions፣ ማንቂያ መስጠት፣ ያለቀባቸው |
| **የቅርብ ጊዜ ስህተቶች** | የመጨረሻዎቹ 10 ስህተቶች ከstack traces ጋር |
| **የሀብት አጠቃቀም** | Memory፣ CPU፣ የheap pressure አመልካች |
### `/dashboard/providers` (የአቅራቢ ጤና)
የእያንዳንዱ አቅራቢ dashboard፦
| ዓምድ | መግለጫ |
| ----------- | ---------------------------------------- |
| አቅራቢ | የአቅራቢ ID + የማሳያ ስም |
| ጤና | አረንጓዴ/ቢጫ/ቀይ ሁኔታ |
| Circuit | ክፍት/ዝግ/በከፊል-ክፍት ሁኔታ |
| Connections | የconnections ብዛት፣ የመጨረሻ እድሳት |
| Models | የሚገኙ models፣ የእያንዳንዱ model ጤና |
| ወጪ | የዛሬ ወጪ፣ የ7-ቀን አዝማሚያ |
| ስህተቶች | የመጨረሻዎቹ 24h የስህተት ብዛት፣ ከፍተኛው error class |
የሚከተሉትን ለማየት አቅራቢውን ጠቅ ያድርጉ፦
- የቅርብ ጊዜ requests ከlatency ዝርዝር ትንተና ጋር
- የእያንዳንዱ connection የጤና ውጤቶች
- የእያንዳንዱ model lockouts
- የAutopilot ምክረ ሐሳቦች
### `/dashboard/quota` (የኮታ ክትትል)
ለእያንዳንዱ API key፦
- የአሁኑ አጠቃቀም ከገደቡ ጋር (progress bar)
- የኮታ አዝማሚያ (የ30-ቀን chart)
- ቀጣዩ የreset ጊዜ
- የማንቂያ ታሪክ
### `/dashboard/combos` (የCombo ጤና)
ለእያንዳንዱ combo፦
- Strategy + targets
- የእያንዳንዱ target ጤና
- የቅርብ ጊዜ fallback events
- የስኬት መጠን (24h፣ 7d፣ 30d)
---
## የጤና ምርመራ API
OmniRoute **ሁለት** የHTTP ጤና መከታተያ መገናኛዎችን ያቀርባል። ለኦርኬስትሬተሮች እርስ በርሳቸው ተለዋዋጭ አይደሉም።
| ዱካ | ዓላማ | ክብደት | ለዚህ ይጠቀሙበት |
| ---------------------------- | ------------------------------------------------------ | ------------------------- | ------------------------------------------------------------ |
| `GET /healthz` | የሕይወት ዑደት ሕያውነት/ዝግጁነት (`ok` / `starting` / `stopping`) | ቀላል (የደረጃ ምልክት ብቻ) | የKubernetes **readiness**፤ HTTP መጠቀም ካለብዎት ለስላሳ **liveness** |
| `GET /api/monitoring/health` | ጥልቅ የስርዓት + አቅራቢ ማጠቃለያ (DB፣ heap፣ የካታሎግ ብዛቶች፣ …) | ከባድ (የተመሳሰለ DB / ክትትል ሥራ) | ዳሽቦርዶች፣ የblackbox ጥልቅ ምርመራዎች፣ የDocker አብሮገነብ healthcheck |
> **ማስታወሻ፦** የአቅራቢ ጤና ማትሪክሶች፣ የautopilot ችግሮች፣ የquota መከታተያዎች፣ የtoken ጤና እና ከ`/api/monitoring/health` በላይ የሆነ የlatency ዝርዝር በ**MCP tool** `observability_snapshot` ወይም በ**dashboard** ገጾች በኩል ይገኛሉ — ለእነዚህ የተለዩ REST መስመሮች የሉም።
ሁለቱም መስመሮች ጥያቄዎችን ከሚያስተናግደው ጋር በ**ተመሳሳዩ የNode event loop** ላይ ይሰራሉ። CPUን አጥብቆ የሚጠቀም ዱካ (ትልቅ የ`GET /v1/models` ካታሎግ ሥራ፣ ረጅም-ዐውድ ማመቅ / token መቁጠር) `/healthz`ን ጨምሮ **ሁሉንም** HTTP handlers ሊያዘገይ ይችላል። event loop ሥራ በዝቶበታል ≠ process ሞቷል። ጫናውን የሚፈጥረውን ማስተካከል ይመረጣል፤ የprobe ማስተካከያ የተሳሳተ ማቋረጥን ብቻ ይቀንሳል።
### ቀላል የorchestrator probe
```bash
GET /healthz
# ወይም HEAD /healthz
```
- የserver lifecycle phase ዝግጁ ሲሆን **200** + body `ok`
- በመነሳት ወይም በመዘጋት ጊዜ **503** + `starting` / `stopping`
- አተገባበር፦ `src/app/healthz/route.ts` (የDB ping የለም)
### የስርዓት ጤና (ጥልቅ)
```bash
GET /api/monitoring/health
```
ምላሽ፦
```json
{
"status": "healthy",
"version": "3.8.16",
"uptime": 123456,
"checks": {
"database": { "status": "pass", "latency_ms": 2 },
"writeable": { "status": "pass" },
"integrity": { "status": "pass", "result": "ok" },
"foreign_keys": { "status": "pass", "violations": 0 },
"heap_pressure": { "status": "pass", "usage_mb": 142, "threshold_mb": 512 },
"active_sessions": 12,
"providers": {
"total": 7,
"healthy": 6,
"degraded": 1,
"down": 0
}
}
}
```
#### `credentialHealth`፦ probe-cache ከSQLite `test_status` ጋር
`GET /api/monitoring/health` → `credentialHealth` **በማህደረ ትውስታ ውስጥ ያለው የprobe-cache
መለኪያ** እንጂ የ`provider_connections.test_status` የቀጥታ ውሂብ ማሳያ አይደለም። ከ#12532 በኋላ
የrequest path `getCachedCredentialHealthSummary()`ን ብቻ ያነባል፤ background probes
cacheን ከevent loop ውጪ ያድሳሉ።
| ንብርብር | የት | ትርጉሙ |
| -------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| የProbe-cache መለኪያ | `credentialHealth.total` / `healthy` / `failed` / `unknown` / `stale` | በprocess memory ውስጥ አሁንም የተያዙ የመጨረሻዎቹ የcredential-health probe ውጤቶች። `source` ሁልጊዜ `probe-cache` ነው። |
| የከሸፈ connection ዝርዝር | `credentialHealth.failedConnections` | **`failed > 0` ሲሆን ብቻ** ይኖራል። `status=error` ያላቸው የcache rows የተገደበ ዝርዝር (`connectionId`፣ `status`፣ የተጣራ `lastError` / `lastErrorType`)። ዝርዝሩ ሲገደብ `failedOmitted` ይዘጋጃል። |
| SQLite sticky status | `credentialHealth.staleDbNonOkCount` | በpersisted `test_status` ውስጥ የሚታወቅ non-ok (`error`፣ `expired`፣ `credits_exhausted`፣ `banned`፣ `deactivated`፣ `unavailable`) ያላቸው **active** (`is_active=1`) connection rows ብዛት። |
ሁለቱ ንብርብሮች ሆን ብለው ሊለያዩ ይችላሉ፦
- መለኪያው `failed=0` ሆኖ `staleDbNonOkCount>0` ሲሆን — SQLite አሁንም የተጣበቀ
`test_status` (ለምሳሌ `expired` ወይም `credits_exhausted`) አለው፤ የቅርብ ጊዜው
የprobe-cache snapshot ግን እንደ `status=error` አይቆጥረውም።
- መለኪያው `failed>0` ሆኖ SQLite ጤናማ ሲመስል — የቅርብ ጊዜ probe ከሽፎ
cache ውስጥ ተቀምጧል፤ DB row አልተዘመነም ወይም በኋላ ተጠርጓል።
ይህን endpoint በመሰብሰብ ጊዜ በ`provider_connections.test_status` ላይ ብቻ ተመስርተው ማንቂያ አያስነሱ።
ለቀጥታ የprobe ውድቀቶች `failed` + `failedConnections`ን፣ የተቀመጠውን
የsticky-status ብዛት ሲፈልጉ ደግሞ `staleDbNonOkCount`ን ይጠቀሙ።
### የKubernetes probe ምክሮች
OmniRoute **አንድ የNode process** (አንድ event loop) ነው። መደበኛው የDocker `HEALTHCHECK` ቀላሉን `/healthz` ዒላማ ያደርጋል። `/api/monitoring/health` ለkubelet liveness የጊዜ ክፍተቶች **በጣም ከባድ** ነው።
| ፕሮብ | የሚመከር ዒላማ | ማስታወሻዎች |
| ---------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ማስጀመሪያ** | HTTP `GET /healthz` ከረጅም `failureThreshold` (ወይም ትልቅ `startPeriod`) ጋር | ቀዝቃዛ ማስጀመር + SQLite ማዛወር ከጥቂት ሰከንዶች ሊበልጥ ይችላል |
| **ዝግጁነት** | HTTP `GET /healthz` | የሕይወት ዑደት `ok` / `starting` / `stopping` (200 ከ503 ጋር ሲነጻጸር)። ሉፑ በCPU ከታገደ አሁንም ይዋዥቃል። **200 ከበርካታ ሰከንዶች በኋላ መመለሱ ጤናማ አይደለም** (#10303) — ይህም ባለ3-ባይት ተቆጣጣሪው ከመስራቱ በፊት የክስተት ሉፑ የማስኬጃ ጊዜ እንዳላገኘ ያሳያል |
| **ሕያውነት** | HTTP `GET /livez`፣ **ወይም TCP** በዋናው የአገልግሎት ወደብ (`PORT`፣ ነባሪ `20128`) | `/livez` ሂደቱ ሕያው መሆኑን ብቻ ያረጋግጣል (ተቆጣጣሪው ከሰራ ሁልጊዜ 200)። አሁንም የክስተት ሉፑን ይጋራል — ሥራ የበዛበት ≠ የሞተ፣ እና የክስተት ሉፕ የማስኬጃ ጊዜ እጦትን (#10303) ከTCP በተሻለ አያገኝም። በካታሎግ/መጭመቅ ጫና ወቅት HTTP ፕሮቦች ጊዜያቸው ካለፈ **TCP**ን ይምረጡ፤ በሁለቱም ሁኔታ በአጭር የክስተት ሉፕ መቆም ምክንያት ፖዱን **አይግደሉ** |
| **ጥልቅ የጤና ምርመራ** | `GET /api/monitoring/health` ከውጫዊ ፈታሽ | ለkubelet `livenessProbe` / ተደጋጋሚ `readinessProbe` አይደለም |
የምሳሌ ቅርጽ (ገደቦቹን ከቀዝቃዛ ማስጀመርዎ እና ከመጭመቅ ጫናዎ ጋር ያስተካክሉ)፦
```yaml
ports:
- name: http
containerPort: 20128
startupProbe:
httpGet:
path: /healthz
port: http
failureThreshold: 30
periodSeconds: 5
readinessProbe:
httpGet:
path: /healthz
port: http
periodSeconds: 5
timeoutSeconds: 2
failureThreshold: 6
livenessProbe:
httpGet:
path: /livez
port: http
periodSeconds: 10
timeoutSeconds: 3
failureThreshold: 6
# የክስተት ሉፑ ሲቆም HTTP /livez አሁንም ጊዜው ሊያልፍ ይችላል። TCP
# ጥንቃቄ የተሞላበት አማራጭ ነው፦
# tcpSocket:
# port: http
```
የkubelet **ሕያውነት** ፕሮብን ወደ `/api/monitoring/health` **አታመልክቱ**። ይህ ዱካ እውነተኛ የDB/ክትትል ሥራ ያከናውናል፣ እና በጫና ወቅት በስህተት ችግር እንዳለ ያመለክታል።
ተዛማጅ፦ [#10052](https://github.com/diegosouzapw/OmniRoute/issues/10052) (የክስተት ሉፑ ሥራ ሲበዛበት የሚደረጉ ፕሮቦች)፣ [#9685](https://github.com/diegosouzapw/OmniRoute/issues/9685) / [#10055](https://github.com/diegosouzapw/OmniRoute/pull/10055) (የካታሎግ ዋጋ አሰጣጥ ግብዓት መቆጣጠር)፣ [#10117](https://github.com/diegosouzapw/OmniRoute/issues/10117) (የመጭመቅ ቶከን-ቆጠራ ግብዓት መቆጣጠር)።
### አማራጭ የጥያቄ-ዱካ ሥራ (ማህደረ ትውስታ፣ ክህሎቶች፣ የቶከን ማደስ)
የማህደረ ትውስታ ማውጣት፣ ክህሎቶችን ማስገባት እና የOAuth ቶከን ማደስ **ዋናውን Node የክስተት ሉፕ** ከ`/healthz` ጋር ይጋራሉ። እነዚህ የዳሽቦርድ አብራ/አጥፋ ባህሪያት (`memoryEnabled`፣ `skillsEnabled`) እንጂ የሠራተኛ ፑል አይደሉም። [አካባቢ — የማህደረ ትውስታ፣ ክህሎቶች እና ቶከን ማደስ የክስተት-ሉፕ ወጪ](../reference/ENVIRONMENT.md#event-loop-cost-of-memory-skills-and-token-refresh-10349)ን ይመልከቱ።
### የአቅራቢ ጤና
> **የREST መዳረሻ የለም።** የአቅራቢ ጤና ውሂብ በMCP መሣሪያ `observability_snapshot` ወይም በዳሽቦርድ `/dashboard/providers` ገጽ በኩል ይገኛል።
### የአቅራቢ ዝርዝር
> **የREST መዳረሻ የለም።** የእያንዳንዱ አቅራቢ ዝርዝር በዳሽቦርድ `/dashboard/providers` ገጽ በኩል ይገኛል።
---
## የአቅራቢ ጤና ራስ-ሰር አስተዳዳሪ
የ`providerHealthAutopilot.ts` ሞጁል፦
1. የአቅራቢ ችግሮችን የሚለይ (የወረዳ መቋረጫ መከፈት፣ የማቀዝቀዣ ጊዜዎች፣ መታገዶች፣ የኮታ ማስጠንቀቂያዎች)
2. ችግሮቹን ለመፍታት **የሚመከሩ እርምጃዎችን** የሚያመነጭ
3. በአማራጭነት ዝቅተኛ ስጋት ያላቸውን እርምጃዎች **በራስ-ሰር የሚያስፈጽም**
**ራሱን የሚጠግን ስርዓት** ነው።
### የሚለዩ የችግር ዓይነቶች
| የችግር ዓይነት | ክብደት | የሁኔታ ምሳሌ |
| ---------------------------- | ------- | -------------------------------- |
| `provider_circuit_open` | ወሳኝ | ከ5 ውድቀቶች በኋላ የወረዳ መቋረጫው ተከፍቷል |
| `provider_circuit_half_open` | ማስጠንቀቂያ | ወረዳው መልሶ ማገገምን እየፈተነ ነው |
| `connection_cooldown` | ማስጠንቀቂያ | ከ429 በኋላ ግንኙነቱ በማቀዝቀዣ ጊዜ ውስጥ ነው |
| `stale_connection_error` | ማስጠንቀቂያ | የመጨረሻው ማደስ ከ30+ ደቂቃዎች በፊት አልተሳካም |
| `terminal_connection_error` | ወሳኝ | OAuth ተሰርዟል፣ ቁልፉ ልክ አይደለም |
| `inactive_connection` | መረጃ | ግንኙነቱ በቅንብሮች ውስጥ ተሰናክሏል |
| `model_lockout` | ማስጠንቀቂያ | የተወሰነው ሞዴል በለይቶ ማቆያ ውስጥ ነው |
| `quota_monitor_warning` | ማስጠንቀቂያ | የኮታ አጠቃቀም 80%+ ደርሷል |
### የሚመነጩ የእርምጃ ዓይነቶች
| እርምጃ | ስጋት | መግለጫ |
| ------------------------------ | ----- | ------------------------------- |
| `clear_provider_breaker` | መካከለኛ | የወረዳ መቋረጫውን ወደ ዝግ ሁኔታ ዳግም ያስጀምሩ |
| `clear_connection_cooldown` | ዝቅተኛ | የግንኙነቱን የማቀዝቀዣ ጊዜ ያስወግዱ |
| `clear_stale_connection_error` | ዝቅተኛ | ጊዜ ያለፈበትን የስህተት ምልክት ያጽዱ |
| `clear_model_lockout` | ዝቅተኛ | በለይቶ ማቆያ ውስጥ ያለውን ሞዴል ዳግም ያንቁ |
| `reactivate_connection` | መካከለኛ | የቦዘነውን ግንኙነት ዳግም ያንቁ |
| `deactivate_connection` | ከፍተኛ | ችግር ያለበትን ግንኙነት ያሰናክሉ |
### API
> **የREST መጨረሻ ነጥብ የለም።** የራስ-ሰር አስተዳዳሪ ችግሮች በMCP መሣሪያ `observability_snapshot` ወይም በዳሽቦርዱ በኩል ይገኛሉ። ራስ-ሰር አስተዳዳሪው በውስጥ ይሰራል፤ ባህሪው የሚዋቀረው በቅንብሮች DB (የእያንዳንዱ ግንኙነት `autopilotMode` መስክ) እንጂ በአካባቢ ተለዋዋጮች አይደለም — ለራስ-ሰር አስተዳዳሪ ሁነታ አካባቢ ተለዋዋጭ `grep -rn` ሲደረግ ምንም ውጤት አይገኝም።
### የራስ-ሰር አስተዳዳሪ ሁነታ
ራስ-ሰር አስተዳዳሪው በነባሪነት በ**በእጅ ሁነታ** ይሰራል — ችግሮችን ይለያል እና የሚመከሩ እርምጃዎችን ያመነጫል፣ ነገር ግን በራስ-ሰር አይተገብራቸውም። እርምጃዎቹ በዳሽቦርዱ በኩል ሊተገበሩ ይችላሉ።
---
## የጥምረት ጤና ራስ-ሰር አስተዳዳሪ
`comboHealthAutopilot.ts` የአቅራቢ ራስ-ሰር አስተዳዳሪው **ለጥምረት የተለየ** አቻ ነው። ይህ፦
- ጤናማ ያልሆኑ ጥምረቶችን ይለያል
- የዒላማዎችን ቅደም ተከተል እንደገና እንዲደራጅ ይመክራል
- የተበላሹ ዒላማዎች እንዲሰናከሉ ሐሳብ ያቀርባል
- ከN ውድቀቶች በኋላ የማይሰሩ ዒላማዎችን በራስ-ሰር ያስወግዳል
### የጥምረት ችግር ምሳሌዎች
```
ጥምረት "always-on" (የቅድሚያ ስልት)
├─ ዒላማ 1: openai/gpt-5 (ጤናማ)
├─ ዒላማ 2: anthropic/claude-opus-4-6 (⚠️ እስከ 14:00 ድረስ የሞዴል መታገድ)
└─ ዒላማ 3: kiro/claude-sonnet-4-5 (ጤናማ)
የሚመከር እርምጃ፦ ቅደም ተከተሉን እንደገና ያደራጁ — መታገዱ እስኪያበቃ ድረስ kiroን ከanthropic በላይ ያንቀሳቅሱ
```
---
## የኮታ መከታተያዎች
`observability.ts` ለደንበኝነት ምዝገባ አቅራቢዎች (Claude Code፣ Codex፣ GitHub Copilot) **በክፍለ ጊዜ የተከፋፈሉ የኮታ መከታተያዎችን** ያቀርባል፦
```ts
interface QuotaMonitorSnapshot {
sessionId: string;
provider: string;
accountId: string;
status: "starting" | "idle" | "healthy" | "warning" | "exhausted" | "error";
lastQuotaPercent: number | null; // 0-100
lastQuotaUsed: number | null;
lastQuotaTotal: number | null;
lastResetAt: string | null;
nextPollAt: string | null;
totalPolls: number;
totalAlerts: number;
consecutiveFailures: number;
}
```
### የሁኔታዎች ትርጉም
| ሁኔታ | መቼ | የUI እርምጃ |
| ----------- | ---------------------- | ------------------------ |
| `starting` | የመጀመሪያ ምርመራ በሂደት ላይ ነው | የመጫን አመልካች |
| `idle` | የቅርብ ጊዜ እንቅስቃሴ የለም | ከዳሽቦርዱ የተደበቀ |
| `healthy` | ከ50% በላይ ኮታ ቀርቷል | አረንጓዴ ነጥብ |
| `warning` | ከ50% በታች ኮታ ቀርቷል | ቢጫ ማንቂያ |
| `exhausted` | ኮታ = 0% | ቀይ እገዳ፣ ወደ ቀጣዩ አቅራቢ ያዛውሩ |
| `error` | ምርመራው አልተሳካም | ቀይ ነጥብ፣ በቅርቡ እንደገና ይሞክሩ |
### API
> **የREST መጨረሻ ነጥብ የለም።** የኮታ መከታተያ ውሂብ በMCP መሣሪያ `observability_snapshot` ወይም በዳሽቦርዱ በኩል ይገኛል።
---
## የታዛቢነት ቅጽበታዊ እይታ
የMCP መሣሪያው `observability_snapshot` ለAI ወኪሎች **የተሟላ የስርዓት ቅጽበታዊ እይታ** ይመልሳል፦
```json
{
"circuitBreakers": [
{
"name": "openai",
"state": "closed",
"failureCount": 0,
"lastFailureTime": null,
"retryAfterMs": null
}
],
"sessions": [
{
"sessionId": "sess-123",
"createdAt": 1234567890,
"lastActive": 1234567999,
"requestCount": 42,
"connectionId": "conn-456",
"ageMs": 109
}
],
"quotaMonitors": {/* ከላይ ይመልከቱ */},
"uptime": 12345,
"version": "3.8.16"
}
```
ወኪሎች ይህን በመጠቀም **የማዞሪያ ውሳኔዎችን** ያደርጋሉ—ለምሳሌ፣ "የopenai ወረዳ ክፍት ከሆነ፣ መጀመሪያ ወደ anthropic አዙር"።
---
## የቶከን ጤንነት ምርመራ
የOAuth አቅራቢዎች (Claude Code፣ GitHub Copilot፣ Cursor) **ወቅታዊ የቶከን ማደስ** ያስፈልጋቸዋል። `src/lib/tokenHealthCheck.ts` የበስተጀርባ መርሐግብር አስኪያጅን ያስኬዳል፦
- **የማጣሪያ ዙር**፦ በየ60 ሰከንዱ (`TICK_MS = 60 * 1000` ያለው ማጣሪያ በ`src/lib/tokenHealthCheck.ts:30`)
- **የእያንዳንዱ ግንኙነት የጤንነት ምርመራ ክፍተት**፦ ነባሪው 60 ደቂቃ (`DEFAULT_HEALTH_CHECK_INTERVAL_MIN = 60`) ነው፤ በቅንብሮች DB በኩል ሊዋቀር ይችላል
- **401 ሲከሰት ቅድመ-ማደስ**፦ በእያንዳንዱ ግንኙነት interceptor ይከናወናል
### የቶከን ጤንነት ሁኔታ
```ts
interface TokenHealth {
connectionId: string;
provider: string;
status: "valid" | "expiring_soon" | "expired" | "refresh_failed";
expiresAt: string;
lastRefresh: string;
nextRefresh: string;
consecutiveFailures: number;
}
```
### ውቅር
የቶከን ጤንነት ምርመራ ውቅር በውስጥ በ`tokenHealthCheck.ts` ይከናወናል።
### የቶከን ጤንነት
> **የREST መዳረሻ የለም።** የቶከን ጤንነት ውሂብ በዳሽቦርዱ ወይም በMCP መሣሪያ `observability_snapshot` በኩል ይገኛል።
---
## ማንቂያ
### አብረው የተካተቱ ቻናሎች
OmniRoute **3 የማንቂያ ቻናሎችን** ይደግፋል፦
| ቻናል | ማዋቀር | የአጠቃቀም ሁኔታ |
| ----------- | -------- | ------------------------- |
| የዳሽቦርድ ሰንደቅ | ሁልጊዜ ክፍት | በመተግበሪያ ውስጥ ማሳወቂያዎች |
| Webhook | URL ያዋቅሩ | Slack፣ Discord፣ PagerDuty |
| ምዝግብ | ነባሪ | ለውጫዊ የምዝግብ ማሰባሰቢያ |
### የWebhook ውቅር
> **ማስታወሻ፦** የWebhook ማንቂያ ውቅር በዳሽቦርዱ የቅንብሮች ገጽ በኩል ይከናወናል። ለWebhook URL፣ የክስተት ማጣሪያ እና የpayload ማበጀት የቅንብሮች UIን ይመልከቱ።
### የማንቂያ ዓይነቶች
| ማንቂያ | መቼ | ነባሪ ክብደት |
| ---------------------------- | ---------------------------------- | -------- |
| `provider_circuit_open` | ወረዳው ሲከፈት | ወሳኝ |
| `provider_circuit_half_open` | ወረዳው መልሶ ማገገሙን ሲፈትሽ | መረጃ |
| `quota_warning` | ኮታው 80%+ ሲደርስ | ማስጠንቀቂያ |
| `quota_exhausted` | ኮታው 100% ሲደርስ | ወሳኝ |
| `token_refresh_failed` | 3+ ተከታታይ የማደስ ውድቀቶች ሲኖሩ | ማስጠንቀቂያ |
| `token_expired` | ቶከኑ የማብቂያ ጊዜውን ሲያልፍ | ወሳኝ |
| `combo_target_unhealthy` | የCombo ዒላማው ለ1h+ በማቀዝቀዣ ጊዜ ውስጥ ሲቆይ | ማስጠንቀቂያ |
| `db_integrity_warning` | የFK ጥሰቶች > 0 ሲሆኑ | ማስጠንቀቂያ |
| `heap_pressure` | የHeap አጠቃቀም > 80% የገደቡ ሲሆን | ማስጠንቀቂያ |
---
## የአፈጻጸም መለኪያዎች
### ክትትል የሚደረግባቸው መለኪያዎች
| መለኪያ | ዓይነት | ምንጭ |
| ----------------------- | ------ | ------------------------------- |
| `request_count` | ቆጣሪ | `services/usage.ts` |
| `request_latency_ms` | ሂስቶግራም | `services/usage.ts` |
| `tokens_consumed` | ቆጣሪ | `services/usage.ts` |
| `cost_usd` | ቆጣሪ | `services/usage.ts` |
| `provider_errors` | ቆጣሪ | `services/errorClassifier.ts` |
| `circuit_state_changes` | ቆጣሪ | `services/resilience.ts` |
| `cache_hits` | ቆጣሪ | `services/signatureCache.ts` |
| `compression_savings` | ሂስቶግራም | `services/compression/stats.ts` |
| `quota_used` | ጌጅ | `services/quotaMonitor.ts` |
| `memory_used_mb` | ጌጅ | `observability.ts` |
### የመዘግየት ፐርሰንታይሎች (p50/p95/p99)
> **የREST መዳረሻ ነጥብ የለም።** የመዘግየት ፐርሰንታይል ውሂብ በዳሽቦርዱ `/dashboard/health` ገጽ በኩል ይገኛል። ወደ Prometheus/OpenTelemetry መላክ ለv3.9 ታቅዷል።
### ወደ Prometheus / OpenTelemetry መላክ (ደረጃ 2)
ለv3.9 የታቀደ፦ ወደ Prometheus፣ OpenTelemetry እና Datadog ቤተኛ መላክ።
ለአሁን፣ `/api/monitoring/health`ን በማንኛውም HTTP-ላይ የተመሠረተ የክትትል ሥርዓት (Prometheus blackbox exporter፣ Datadog HTTP check፣ ወዘተ) ይሰብስቡ።
---
## የማንቂያ አዘገጃጀቶች
### Slack
> **ማስታወሻ፦** የWebhook ማንቂያ በዳሽቦርዱ Settings ገጽ በኩል ይዋቀራል — ለዚህ የተለዩ የwebhook የአካባቢ ተለዋዋጮች የሉም (`grep -rn` ምንም ውጤት አይመልስም)። ለwebhook URL፣ ለክስተት ማጣሪያ እና ለpayload ማበጀት Settings UIን ይመልከቱ።
### Discord
> የWebhook ማንቂያ ከSlack ጋር ተመሳሳይ የSettings UI ሂደትን ይጠቀማል። Discord ተመሳሳይ የJSON payload ቅርጽን ይቀበላል።
### PagerDuty
> የWebhook ማንቂያ ተመሳሳይ የSettings UI ሂደትን ይጠቀማል። የPagerDuty Events API v2 routing keys በSettings UI ውስጥ ይዋቀራሉ።
### ብጁ Webhook (JSON)
> JSON body ያለውን POST የሚቀበል ማንኛውም HTTP መዳረሻ ነጥብ ይሠራል። URLን በSettings UI ውስጥ ያዋቅሩ።
---
## የዳሽቦርድ ውቅር
### የጤና ዳሽቦርዱን ያብጁ
`~/.omniroute/dashboard.json` ይፍጠሩ፦
```json
{
"health": {
"sections": ["server_status", "database", "providers", "quota_monitors", "recent_errors"],
"refresh_interval_ms": 5000
}
}
```
### አቅራቢን ከላይ ይሰኩ
```json
{
"health": {
"pinned_providers": ["openai", "anthropic"]
}
}
```
---
## ችግር መፍታት
### "አቅራቢው ጤናማ ነው ይላል፣ ግን ጥያቄዎች አይሳኩም"
1. **autopilot issues**ን ይፈትሹ — ምናልባት አንድ model ታግዶ ይሆናል
2. የተወሰነውን የስህተት ምድብ ለማየት **recent errors**ን ይመልከቱ
3. በአቅራቢው ካርድ ውስጥ ያለውን **connection test** ይሞክሩ
4. አቅራቢው **በupstream የrate limit ገደብ እንደተጣለበት** ይፈትሹ (በአካባቢው አይታይም)
### "Quota ጤናማ ነው ይላል፣ ግን 429ዎችን አያለሁ"
- 429 ማለት አቅራቢው quotaዎን እንደጨረሱ እየገለጸ ነው
- የOmniRoute quota ክትትል **ያልታደሰ** ሊሆን ይችላል — ትክክለኛው መረጃ በአቅራቢው upstream ላይ ነው
- የQuota ውሂብ በውስጣዊው quota monitor በኩል በራስ-ሰር ይታደሳል
### "Comboው እየከሸፈ ነው፣ ግን ሁሉም targets ጤናማ ይመስላሉ"
- የtarget ቅደም ተከተል ችግሮች ካሉ ለማየት **combo health** ዳሽቦርድን ይፈትሹ
- **fallback events**ን ይመልከቱ — ምናልባት comboው አማራጮቹን በጣም ፈጥኖ እየጨረሰ ይሆናል
- **strategy**ው ከአጠቃቀምዎ ጋር እንደሚዛመድ ያረጋግጡ (priority ከ round-robin ከ auto)
### "የውሂብ ጎታ ጤና ምርመራው እየከሸፈ ነው"
- `sqlite3 ~/.omniroute/storage.sqlite "PRAGMA integrity_check;"`ን ያስኪዱ
- "ok" ከሆነ — የሐሰት ማንቂያ ነው፤ የጤና ምርመራው ከልክ በላይ ጥብቅ እየሆነ ነው
- ሌላ ማንኛውም ውጤት ከሆነ — **OmniRouteን ያቁሙ** እና [የአደጋ ማገገሚያ መመሪያውን](./DATABASE_GUIDE.md#disaster-recovery) ይከተሉ
### "የMemory heap ጫናው አሳሳቢ ነው"
```bash
# የአሁኑን heap ይፈትሹ
node -e "console.log(process.memoryUsage())"
# በእጅ GCን ያስነሱ (--expose-gc ካለ)
node --expose-gc -e "global.gc(); console.log(process.memoryUsage())"
# በአንድ ጊዜ የሚካሄዱ ጥያቄዎችን ይቀንሱ (በenv var ሳይሆን በዳሽቦርዱ Settings ገጽ በኩል ያዋቅሩ)
# `MAX_CONCURRENT_REQUESTS` env var የለም — በSettings → Concurrency ውስጥ ያዋቅሩት።
```
---
## በተጨማሪ ይመልከቱ
- [USAGE_QUOTA_GUIDE.md](../guides/USAGE_QUOTA_GUIDE.md) — የአጠቃቀም እና የወጪ ክትትል
- [DATABASE_GUIDE.md](./DATABASE_GUIDE.md) — የDB መዋቅር + ጤና
- [PROXY_GUIDE.md](./PROXY_GUIDE.md) — የproxy ጤና (የተለየ cache)
- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — የስርዓት አርክቴክቸር
- [RESILIENCE_GUIDE.md](../architecture/RESILIENCE_GUIDE.md) — የcircuit breaker ዝርዝሮች
- ምንጭ፦ `src/lib/monitoring/` (4 ፋይሎች፣ 2121 LOC)

816
docs/i18n/am/docs/ops/PROXY_GUIDE.md Normal file
View File

@@ -0,0 +1,816 @@
# 🌐 OmniRoute Proxy Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/PROXY_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/PROXY_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/PROXY_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/PROXY_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/PROXY_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/PROXY_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/PROXY_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/PROXY_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/PROXY_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/PROXY_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/PROXY_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/PROXY_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/PROXY_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/PROXY_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/PROXY_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/PROXY_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/PROXY_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/PROXY_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/PROXY_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/PROXY_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/PROXY_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/PROXY_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/PROXY_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/PROXY_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/PROXY_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/PROXY_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/PROXY_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/PROXY_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/PROXY_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/PROXY_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/PROXY_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/PROXY_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/PROXY_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/PROXY_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/PROXY_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/PROXY_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/PROXY_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/PROXY_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/PROXY_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/PROXY_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/PROXY_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/PROXY_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/PROXY_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/PROXY_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/PROXY_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/PROXY_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/PROXY_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/PROXY_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/PROXY_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/PROXY_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/PROXY_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/PROXY_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/PROXY_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/PROXY_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/PROXY_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/PROXY_GUIDE.md)
---
> **የጂኦግራፊያዊ እገዳዎችን ይለፉ፣ ማንነትዎን ይጠብቁ፣ እና የAI ትራፊክን በማንኛውም ፕሮክሲ በኩል ያስተላልፉ — ያለምንም የውቅረት ውስብስብነት።**
OmniRoute ወደ ላይኛ ደረጃ የAI አቅራቢዎች የሚላከውን ትራፊክ በHTTP፣ HTTPS ወይም SOCKS5 ፕሮክሲዎች በኩል እንዲያስተላልፉ የሚያስችልዎትን ሙሉ ባህሪያት ያሉት የፕሮክሲ አስተዳደር ስርዓት ያካትታል። በታገደ ክልል ውስጥ ቢሆኑ፣ የIP ማዞር ቢያስፈልግዎት፣ ወይም ስውር የጣት አሻራ አጠቃቀምን ቢፈልጉ — ይህ መመሪያ ሁሉንም ይሸፍናል።
---
## የይዘት ማውጫ
- [ፕሮክሲዎችን ለምን ይጠቀማሉ?](#why-use-proxies)
- [የአርክቴክቸር አጠቃላይ እይታ](#architecture-overview)
- [ባለ4-ደረጃ የፕሮክሲ ስርዓት](#4-level-proxy-system)
- [የፕሮክሲ መዝገብ (CRUD)](#proxy-registry-crud)
- [የ1proxy ነጻ የገበያ ቦታ](#1proxy-free-proxy-marketplace)
- [የፕሮክሲ ማዞር](#proxy-rotation)
- [ፀረ-ማወቂያ እና ስውርነት](#anti-detection--stealth)
- [ወደ ላይኛ ደረጃ የፕሮክሲ ሁነታዎች](#upstream-proxy-modes)
- [የዳሽቦርድ UI](#dashboard-ui)
- [የAPI ማጣቀሻ](#api-reference)
- [የአካባቢ ተለዋዋጮች](#environment-variables)
- [መላ መፈለግ](#troubleshooting)
---
## ፕሮክሲዎችን ለምን ይጠቀማሉ?
ብዙ የAI አቅራቢዎች በጂኦግራፊያዊ ክልል መሠረት መዳረሻን ይገድባሉ። በ**ሩሲያ፣ ቻይና፣ ኢራን፣ ኩባ፣ ቱርክ** እና በሌሎች አገሮች ያሉ ገንቢዎች እንደሚከተለው ያሉ ስህተቶችን ያጋጥማቸዋል፦
```
unsupported_country_region_territory
```
ከታገዱ ክልሎች ውጭም ቢሆን፣ ፕሮክሲዎች ለሚከተሉት ጠቃሚ ናቸው፦
| የአጠቃቀም ሁኔታ | መግለጫ |
| --------------------- | --------------------------------------------------- |
| **የጂኦግራፊያዊ እገዳን ማለፍ** | ከታገዱ አገሮች OpenAI፣ Anthropic፣ Codex እና Copilotን መድረስ |
| **የIP ማዞር** | የፍጥነት ገደብን ለማስወገድ ጥያቄዎችን በበርካታ IPዎች ላይ ማሰራጨት |
| **ግላዊነት** | እውነተኛ IPዎን ከወደ ላይኛ ደረጃ አቅራቢዎች መደበቅ |
| **ተገዢነት** | ትራፊክን በተወሰኑ የሕግ ስልጣን ክልሎች በኩል ማስተላለፍ |
| **ሙከራ** | ከተለያዩ ክልሎች የሚመጡ ጥያቄዎችን ማስመሰል |
---
## የአርክቴክቸር አጠቃላይ እይታ
```
┌───────────────────────────────────────────────────────────────┐
│ OmniRoute አገልጋይ │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ የፕሮክሲ │ │ የፕሮክሲ │ │ የፕሮክሲ │ │
│ │ መዝገብ │───▶│ አከፋፋይ │───▶│ Fetch (undici) │ │
│ │ (SQLite) │ │ (የተሸጎጠ) │ │ │ │
│ └─────────────┘ └──────────────┘ └────────┬─────────┘ │
│ ▲ │ │
│ │ ▼ │
│ ┌──────┴──────┐ ┌──────────────────┐ │
│ │ የ1proxy │ │ ወደ ላይኛ ደረጃ │ │
│ │ ማመሳሰል │ │ የአቅራቢ API │ │
│ │ (ነጻ ስብስብ) │ │ │ │
│ └─────────────┘ └──────────────────┘ │
└───────────────────────────────────────────────────────────────┘
```
### ዋና ክፍሎች
| ክፍል | ፋይል | ሚና |
| ---------------- | -------------------------------------------- | ---------------------------------------------- |
| **የፕሮክሲ መዝገብ** | `src/lib/db/proxies.ts` | ለፕሮክሲ ግቤቶች እና የወሰን ምደባዎች CRUD |
| **የፕሮክሲ አከፋፋይ** | `open-sse/utils/proxyDispatcher.ts` | በመሸጎጥ የ`undici` ProxyAgent/SOCKS አከፋፋዮችን ይፈጥራል |
| **የፕሮክሲ Fetch** | `open-sse/utils/proxyFetch.ts` | `fetch()`ን ከፕሮክሲ አከፋፋይ ማስገባት ጋር ይጠቀልላል |
| **የቅንብሮች መንገድ** | `src/app/api/settings/proxy/route.ts` | የቆየ የፕሮክሲ ውቅረት API (GET/PUT/DELETE) |
| **የአስተዳደር መንገድ** | `src/app/api/v1/management/proxies/route.ts` | የመዝገብ CRUD API (GET/POST/PATCH/DELETE) |
| **የ1proxy DB** | `src/lib/db/oneproxy.ts` | የነጻ ፕሮክሲ የገበያ ቦታ ዘላቂ ማከማቻ |
---
## ባለ 4-ደረጃ ፕሮክሲ ስርዓት
OmniRoute በቅድሚያ ቅደም ተከተል የሚወሰኑ **አራት እርስ በርስ ገለልተኛ ወሰኖች** ላይ የፕሮክሲ ውቅርን ይደግፋል፦
```
የቅድሚያ አወሳሰን ቅደም ተከተል (ከከፍተኛ → ዝቅተኛ)፦
1. 🔵 የመለያ/ግንኙነት ፕሮክሲ → ለእያንዳንዱ API ቁልፍ / OAuth ግንኙነት
2. 🟡 የአቅራቢ ፕሮክሲ → ለእያንዳንዱ አቅራቢ (ለምሳሌ፣ ሁሉም የOpenAI ትራፊክ)
3. 🟠 የጥምረት ፕሮክሲ → ለእያንዳንዱ የጥምረት/ማስተላለፊያ ውቅር
4. 🟢 ዓለም አቀፍ ፕሮክሲ → ሁሉም ትራፊክ፣ ሁሉም አቅራቢዎች
```
### አወሳሰኑ እንዴት እንደሚሠራ
OmniRoute ወደ ላይኛው አቅራቢ ጥያቄ ሲልክ፣ እያንዳንዱን ደረጃ በቅደም ተከተል የሚፈትሸውን `resolveProxyForConnectionFromRegistry()` ይጠራል፦
1. **የመለያ ደረጃ** — ለዚህ የተወሰነ የግንኙነት ID ፕሮክሲ ተመድቧል?
2. **የአቅራቢ ደረጃ** — ለዚህ አቅራቢ (ለምሳሌ፣ `openai`) ፕሮክሲ ተመድቧል?
3. **ዓለም አቀፍ ደረጃ** — ዓለም አቀፍ ፕሮክሲ ተዋቅሯል?
4. **ፕሮክሲ የለም** — ከአቅራቢው ጋር ቀጥተኛ ግንኙነት።
የመጀመሪያው ተዛማጅ ይመረጣል። ይህም ዓለም አቀፍ ፕሮክሲን እንደ ተጠባባቂ እንዲያዘጋጁ፣ ነገር ግን ለተወሰኑ አቅራቢዎች ወይም ግንኙነቶች እንዲተኩት ያስችልዎታል።
### በፕሮክሲ የሚያልፈው
| የትራፊክ ዓይነት | በፕሮክሲ ያልፋል? | ማስታወሻዎች |
| --------------- | ----------- | -------------------------------------------- |
| የውይይት ማጠናቀቂያዎች | ✅ | ሁሉም የ`/v1/chat/completions` ጥያቄዎች |
| ኢምቤዲንጎች | ✅ | `/v1/embeddings` |
| ምስል ማመንጨት | ✅ | `/v1/images/generations` |
| ድምፅ (TTS/STT) | ✅ | `/v1/audio/*` |
| የOAuth ቶከን ልውውጥ | ✅ | `unsupported_country_region_territory`ን ይፈታል |
| የግንኙነት ሙከራዎች | ✅ | "ግንኙነትን ሞክር" አዝራር ፕሮክሲን ይጠቀማል |
| የቶከን እድሳት | ✅ | ከበስተጀርባ የሚከናወን የOAuth እድሳት |
| የሞዴል ማመሳሰል | ✅ | የሞዴል ዝርዝር እና ፍለጋ |
---
## የፕሮክሲ መዝገብ (CRUD)
የፕሮክሲ መዝገቡ ሁሉንም ፕሮክሲዎችዎን የሚያከማች SQLite ሰንጠረዥ (`proxy_registry`) ነው። እያንዳንዱ ፕሮክሲ የሚከተሉት አሉት፦
| መስክ | ዓይነት | መግለጫ |
| ---------- | ------ | --------------------------------- |
| `id` | UUID | ልዩ መለያ |
| `name` | ሕብረቁምፊ | ለሰው በቀላሉ የሚነበብ ስያሜ |
| `type` | ሕብረቁምፊ | ፕሮቶኮል፦ `http`፣ `https`፣ `socks5` |
| `host` | ሕብረቁምፊ | የፕሮክሲ አስተናጋጅ ስም ወይም IP |
| `port` | ኢንቲጀር | የፖርት ቁጥር |
| `username` | ሕብረቁምፊ | የማረጋገጫ የተጠቃሚ ስም (በማከማቻ ላይ የተመሰጠረ) |
| `password` | ሕብረቁምፊ | የማረጋገጫ የይለፍ ቃል (በማከማቻ ላይ የተመሰጠረ) |
| `region` | ሕብረቁምፊ | የጂኦግራፊያዊ ክልል ስያሜ |
| `notes` | ሕብረቁምፊ | ነፃ-ጽሑፍ ማስታወሻዎች |
| `status` | ሕብረቁምፊ | `active` ወይም `inactive` |
| `source` | ሕብረቁምፊ | `manual` ወይም `oneproxy` |
### ፕሮክሲ መፍጠር
**በዳሽቦርድ በኩል፦**
1. ወደ **ቅንብሮች → ፕሮክሲ** ይሂዱ
2. **ፕሮክሲ ጨምር**ን ጠቅ ያድርጉ
3. ዓይነቱን፣ አስተናጋጁን፣ ፖርቱን እና አማራጭ የማረጋገጫ መረጃዎችን ይሙሉ
4. ያስቀምጡ
**በAPI በኩል፦**
```bash
curl -X POST http://localhost:20128/api/v1/management/proxies \
-H "Content-Type: application/json" \
-d '{
"name": "US Proxy",
"type": "http",
"host": "proxy.example.com",
"port": 8080,
"username": "user",
"password": "pass",
"region": "US"
}'
```
### ፕሮክሲን ማዘመን
```bash
curl -X PATCH http://localhost:20128/api/v1/management/proxies \
-H "Content-Type: application/json" \
-d '{
"id": "proxy-uuid-here",
"host": "new-proxy.example.com",
"port": 9090
}'
```
> **ማስታወሻ፦** ባዶ ያልሆኑ ምትኮችን በግልጽ ካልላኩ በስተቀር የማረጋገጫ መረጃዎቹ እንዳሉ ይቆያሉ። ለ`username`/`password` ባዶ ሕብረቁምፊዎችን መላክ የተከማቹትን እሴቶች እንዳሉ ያቆያል።
### ፕሮክሲን መሰረዝ
```bash
# ፕሮክሲው ለማንኛውም ወሰን ከተመደበ አይሳካም
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"
# በግድ ሰርዝ (ምደባዎችንም ያስወግዳል)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"
```
### ፕሮክሲዎችን መዘርዘር
```bash
curl "http://localhost:20128/api/v1/management/proxies?limit=50&offset=0"
```
### ፕሮክሲዎችን ለወሰኖች መመደብ
```bash
# ለዓለም አቀፍ ወሰን መድብ
curl -X PUT http://localhost:20128/api/settings/proxy \
-H "Content-Type: application/json" \
-d '{"level": "global", "proxy": {"type":"http","host":"proxy.example.com","port":8080}}'
# ለተወሰነ አቅራቢ መድብ
curl -X PUT http://localhost:20128/api/settings/proxy \
-H "Content-Type: application/json" \
-d '{"level": "provider", "id": "openai", "proxy": {"type":"socks5","host":"socks.example.com","port":1080}}'
# ለተወሰነ ግንኙነት/ቁልፍ መድብ
curl -X PUT http://localhost:20128/api/settings/proxy \
-H "Content-Type: application/json" \
-d '{"level": "key", "id": "connection-uuid", "proxy": {"type":"http","host":"key-proxy.com","port":3128}}'
```
### ተግባራዊውን ፕሮክሲ መወሰን
ለአንድ የተወሰነ ግንኙነት የትኛው ፕሮክሲ ጥቅም ላይ እንደሚውል ያረጋግጡ፦
```bash
curl "http://localhost:20128/api/settings/proxy?resolve=connection-uuid"
```
የተወሰነውን ፕሮክሲ ከደረጃው (`account`፣ `provider` ወይም `global`) እና ከምንጩ ጋር ይመልሳል።
### በጅምላ መመደብ
አንድን ፕሮክሲ በአንድ ጊዜ ለብዙ አቅራቢዎች ወይም ግንኙነቶች ይመድቡ፦
```bash
curl -X POST http://localhost:20128/api/v1/management/proxies/bulk-assign \
-H "Content-Type: application/json" \
-d '{
"scope": "provider",
"scopeIds": ["openai", "anthropic", "codex"],
"proxyId": "proxy-uuid"
}'
```
### ማስመጣት/ላክ
ፕሮክሲዎች በ**ምትኬ/መልሶ ማግኛ** ስርዓቱ ውስጥ ተካትተዋል። የOmniRoute ውቅርዎን ሲልኩ፦
1. ወደ **ዳሽቦርድ → ቅንብሮች → ምትኬ** ይሂዱ
2. **ላክ**ን ጠቅ ያድርጉ — የፕሮክሲ መዝገቡ እና ምደባዎቹ ተካትተዋል
3. መልሶ ለማግኘት፣ **አስመጣ**ን ጠቅ ያድርጉ እና የምትኬ ፋይሉን ይስቀሉ
የፕሮክሲ መዝገቡ **በhost+port upsert**ንም ይደግፋል — ቀድሞ ያለን ፕሮክሲ (ተመሳሳይ አስተናጋጅ እና ፖርት) ካስመጡ፣ የተባዛ ከመፍጠር ይልቅ ያዘምነዋል።
### ከድሮ ስርዓት ማዛወር
በቀድሞ ስሪት (ከregistry በፊት) proxies ካዋቀሩ፣ OmniRoute በራስ-ሰር ያዛውራቸዋል፦
```
የቀድሞ key_value store → proxy_registry + proxy_assignments
```
ይህ ከማሻሻያው በኋላ ለመጀመሪያ ጊዜ ሲጀመር አንድ ጊዜ ይከናወናል። እንደገና ለማስኬድ `migrateLegacyProxyConfigToRegistry({ force: true })`ን ይጠቀሙ።
---
## 1proxy ነፃ ፕሮክሲ የገበያ ቦታ
> 🆕 **በ[@oyi77](https://github.com/oyi77) የተበረከተ** — PR [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847) (ጉዳይ [#1788](https://github.com/diegosouzapw/OmniRoute/issues/1788))
OmniRoute በዓለም ዙሪያ ያሉ **በመቶዎች የሚቆጠሩ ነፃና የተረጋገጡ ፕሮክሲዎችን** ለማግኘት ከ**[1proxy](https://1proxy-api.aitradepulse.com)** የማህበረሰብ መድረክ ጋር ይዋሃዳል። ይህ የራሳቸው የፕሮክሲ መሠረተ ልማት ለሌላቸው ተጠቃሚዎች እጅግ ተስማሚ ነው።
### እንዴት እንደሚሠራ
```
┌─────────────┐ ማመሳሰል ┌─────────────────┐ ማዞር ┌──────────┐
│ 1proxy API │ ────────────▶ │ proxy_registry │ ────────────▶ │ አቅራቢ API │
│ (ውጫዊ) │ እስከ 500 │ source=oneproxy │ በጥራት │ │
└─────────────┘ ፕሮክሲዎች └─────────────────┘ └──────────┘
```
1. **ማመሳሰል** — OmniRoute ከ1proxy API የተረጋገጡ ፕሮክሲዎችን ያመጣል
2. **ማከማቸት** — ፕሮክሲዎች `source = 'oneproxy'` በሚል በዚያው `proxy_registry` ሰንጠረዥ ውስጥ ይቀመጣሉ
3. **ማጣራት** — በፕሮቶኮል፣ በአገር እና በጥራት ነጥብ ያጣሩ
4. **ማዞር** — የጥራት፣ የዘፈቀደ ወይም ተከታታይ ስልቶችን በመጠቀም ምርጡን ፕሮክሲ ይምረጡ
5. **ራስ-ሰር የጥራት ቅነሳ** — ያልተሳኩ ፕሮክሲዎች የጥራት ነጥባቸው ይቀነሳል፤ ከገደቡ በታች ሲሆን → እንደ ንቁ ያልሆነ ምልክት ይደረግበታል
### ፕሮክሲዎችን ማመሳሰል
**በዳሽቦርድ በኩል፦**
1. ወደ **ቅንብሮች → 1proxy** ትር ይሂዱ
2. **"አሁን አመሳስል"** የሚለውን ጠቅ ያድርጉ
3. ስታቲስቲክስን ይመልከቱ፦ ጠቅላላ ፕሮክሲዎች፣ የንቁ ፕሮክሲዎች ብዛት፣ አማካይ ጥራት እና በአገር የተከፋፈለ ዝርዝር
**በAPI በኩል፦**
```bash
# ማመሳሰልን አስጀምር
curl -X POST http://localhost:20128/api/settings/oneproxy \
-H "Content-Type: application/json" \
-d '{}'
# ምላሽ፦
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }
```
### ፕሮክሲዎችን ማጣራት
```bash
# በፕሮቶኮል አጣራ
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"
# በአገር አጣራ
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"
# በዝቅተኛው የጥራት ነጥብ አጣራ
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"
# ማጣሪያዎችን አጣምር
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"
```
### የፕሮክሲ ጥራት ነጥቦች
እያንዳንዱ የ1proxy ፕሮክሲ ከሜታዳታ ጋር ይመጣል፦
| መስክ | መግለጫ |
| --------------- | -------------------------------------- |
| `qualityScore` | ከ1proxy ማረጋገጫ የተገኘ የ0-100 ደረጃ |
| `latencyMs` | የተለካ የአውታረ መረብ መዘግየት |
| `anonymity` | `transparent`፣ `anonymous` ወይም `elite` |
| `googleAccess` | ፕሮክሲው የGoogle አገልግሎቶችን ማግኘት መቻሉን |
| `countryCode` | ባለሁለት ፊደል ISO የአገር ኮድ |
| `lastValidated` | የመጨረሻው ማረጋገጫ የጊዜ ማህተም |
የጥራት ነጥቦች በተለዋዋጭ ሁኔታ ይስተካከላሉ፦
- **ያልተሳኩ ጥያቄዎች** ነጥቡን በ10 ይቀንሳሉ
- **ነጥቡ ወደ ≤10 ይወርዳል** → ፕሮክሲው `inactive` ተብሎ ምልክት ይደረግበታል
- ንቁ ያልሆኑ ፕሮክሲዎች ከማዞሪያው ይገለላሉ
### የማዞሪያ ስልቶች
```bash
# በጥራት አዙር (ምርጡ ፕሮክሲ መጀመሪያ) — ነባሪ
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
-H "Content-Type: application/json" \
-d '{"strategy": "quality"}'
# የዘፈቀደ ማዞሪያ
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
-d '{"strategy": "random"}'
# ተከታታይ (በቅርቡ ያልተረጋገጠው መጀመሪያ)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
-d '{"strategy": "sequential"}'
```
### የወረዳ ተቋራጭ
የ1proxy ማመሳሰል አብሮገነብ የወረዳ ተቋራጭ አለው፦
- **5 ተከታታይ የማመሳሰል አለመሳካቶች** ካጋጠሙ በኋላ፣ ተጨማሪ የማመሳሰል ሙከራዎች ይታገዳሉ
- በዚህ ዳግም ያስጀምሩ፦ `resetOneproxyCircuitBreaker()` ወይም አገልጋዩን ዳግም ያስጀምሩ
- የማመሳሰል ሁኔታ በ`GET /api/settings/oneproxy?action=status` ይገኛል
### የ1proxy ፕሮክሲዎችን ማጽዳት
```bash
# አንድ የ1proxy ፕሮክሲ ሰርዝ
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"
# ሁሉንም የ1proxy ፕሮክሲዎች አጽዳ (በእጅ የተጨመሩ ፕሮክሲዎች አይነኩም)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"
```
---
## ፀረ-ማወቂያ እና ስውርነት
OmniRoute ትራፊክን በፕሮክሲ በኩል ብቻ አያስተላልፍም — ትራፊኩ ሕጋዊ እንዲመስልም ያደርገዋል፦
### የTLS አሻራ ማስመሰል
ከአሳሽ ያልሆኑ የTLS ግንኙነት ልውውጦችን የሚጠቁሙ የቦት ማወቂያ ስርዓቶችን ለማለፍ፣ አሳሽ-መሰል የTLS አሻራዎችን ለማመንጨት `wreq-js`ን ይጠቀማል።
### የCLI አሻራ ማዛመድ
**የCLI አሻራ መቀየሪያው** (`Settings → Security`) ከቤተኛ CLI ባይነሪዎች (Claude Code፣ Codex፣ ወዘተ) ትክክለኛ ፊርማ ጋር እንዲዛመዱ የHTTP ራስጌዎችን እና የJSON የውሂብ አካል መስኮችን እንደገና ያደራጃል። ይህ ከፕሮክሲው **በተጨማሪ** ይሰራል፦
```
የእርስዎ IP (የታገደ) → የፕሮክሲ IP (US) → የአቅራቢ API
+ የTLS ማስመሰል
+ የCLI አሻራ
```
ሁለቱንም **የIP መደበቅ** እና **የጥያቄ ትክክለኛነት** በአንድ ጊዜ ያገኛሉ።
### የፕሮክሲ IP ጥበቃ
በዳሽቦርዱ ውስጥ ያሉ በቀለም የተለዩ ባጆች የትኛው የፕሮክሲ ደረጃ ንቁ እንደሆነ ያሳያሉ፦
| ባጅ | ደረጃ | ትርጉም |
| --- | ------- | ------------------------------- |
| 🟢 | ዓለም አቀፍ | ሁሉም ትራፊክ በዚህ ፕሮክሲ በኩል ያልፋል |
| 🟡 | አቅራቢ | የዚህ አቅራቢ ትራፊክ ብቻ በፕሮክሲ ይተላለፋል |
| 🔵 | ግንኙነት | ይህ የተወሰነ ቁልፍ/መለያ ይህን ፕሮክሲ ይጠቀማል |
ባጁ ለማረጋገጫ የተፈታውን የፕሮክሲ IPም ያሳያል።
---
## የላይኛው ዥረት ፕሮክሲ ሁነታዎች
የCLIProxyAPI ንድፍን ለሚጠቀሙ አቅራቢዎች፣ OmniRoute ሦስት የላይኛው ዥረት ፕሮክሲ ሁነታዎችን ይደግፋል፦
| ሁነታ | መግለጫ |
| ------------- | --------------------------------------------- |
| `native` | OmniRoute የፕሮክሲ ማስተላለፍን በቀጥታ ያስተናግዳል (ነባሪ) |
| `cliproxyapi` | ወደ ውጫዊ CLIProxyAPI ኢንስታንስ ውክልና ይሰጣል |
| `fallback` | መጀመሪያ ቤተኛውን ይሞክራል፣ ካልተሳካ ወደ CLIProxyAPI ይመለሳል |
ለእያንዳንዱ አቅራቢ ያዋቅሩ፦
```bash
curl -X PUT "http://localhost:20128/api/upstream-proxy/openai" \
-H "Content-Type: application/json" \
-d '{"mode": "native", "enabled": true}'
```
---
## የዳሽቦርድ UI
### Settings → Proxy ትር
- **ዓለም አቀፍ ፕሮክሲ** ውቅር (ለሁሉም ትራፊክ አንድ ጊዜ ያዋቅሩ)
- **ለእያንዳንዱ አቅራቢ ፕሮክሲ** መሻሮች
- **ለእያንዳንዱ ግንኙነት ፕሮክሲ** ምደባዎች
- በተዋቀረው ፕሮክሲ በኩል **የግንኙነት ሙከራ**
- ንቁውን የፕሮክሲ ደረጃ የሚያሳዩ **በቀለም የተለዩ ባጆች**
### Settings → 1proxy ትር
- ነፃ ፕሮክሲዎችን ለማምጣት **አሁን አመሳስል** አዝራር
- **የስታቲስቲክስ ካርዶች**፦ ጠቅላላ፣ ንቁ፣ አማካይ ጥራት፣ የመጨረሻ ማመሳሰል
- **ማጣሪያዎች**፦ ፕሮቶኮል፣ የአገር ኮድ፣ ዝቅተኛ ጥራት
- አስተናጋጅ፣ ፕሮቶኮል፣ አገር፣ የጥራት ውጤት፣ መዘግየት፣ ማንነት መደበቅ እና የGoogle መዳረሻ ያለው **የፕሮክሲ ሰንጠረዥ**
- የስኬት/ውድቀት ክትትል እና ተከታታይ የውድቀት ብዛት ያለው **የማመሳሰል ሁኔታ** ፓነል
- ሁሉንም የ1proxy ግቤቶች ለማስወገድ **ሁሉንም አጽዳ**
---
## የAPI ማጣቀሻ
### የፕሮክሲ ቅንብሮች API
| ዘዴ | መጨረሻ ነጥብ | መግለጫ |
| -------- | ---------------------------------------------- | ------------------------ |
| `GET` | `/api/settings/proxy` | ሙሉውን የፕሮክሲ ውቅር ያግኙ |
| `GET` | `/api/settings/proxy?level=global` | ዓለም አቀፍ ፕሮክሲውን ያግኙ |
| `GET` | `/api/settings/proxy?level=provider&id=openai` | የአቅራቢውን ፕሮክሲ ያግኙ |
| `GET` | `/api/settings/proxy?resolve=connectionId` | ተግባራዊውን ፕሮክሲ ይፍቱ |
| `PUT` | `/api/settings/proxy` | የፕሮክሲ ውቅሩን ያዘምኑ |
| `DELETE` | `/api/settings/proxy?level=provider&id=openai` | በደረጃው ላይ ያለውን ፕሮክሲ ያስወግዱ |
### የፕሮክሲ መዝገብ API
| ዘዴ | መጨረሻ ነጥብ | መግለጫ |
| -------- | ------------------------------------------------- | ---------------- |
| `GET` | `/api/v1/management/proxies` | ሁሉንም ፕሮክሲዎች ዘርዝሩ |
| `GET` | `/api/v1/management/proxies?id=uuid` | ፕሮክሲውን በID ያግኙ |
| `GET` | `/api/v1/management/proxies?id=uuid&where_used=1` | የፕሮክሲ ምደባዎችን ያግኙ |
| `POST` | `/api/v1/management/proxies` | ፕሮክሲ ይፍጠሩ |
| `PATCH` | `/api/v1/management/proxies` | ፕሮክሲውን ያዘምኑ |
| `DELETE` | `/api/v1/management/proxies?id=uuid` | ፕሮክሲውን ይሰርዙ |
| `DELETE` | `/api/v1/management/proxies?id=uuid&force=1` | በግድ ይሰርዙ |
| `POST` | `/api/v1/management/proxies/bulk-assign` | በጅምላ ይመድቡ |
| `GET` | `/api/v1/management/proxies/assignments` | ምደባዎችን ዘርዝሩ |
| `GET` | `/api/v1/management/proxies/health` | የፕሮክሲ ጤና ስታቲስቲክስ |
### የቱነሎች API
OmniRoute ኢንስታንስዎን ወጪ ትራፊክን በፕሮክሲ በኩል ከማስተላለፍ ይልቅ ለሕዝባዊ ኢንተርኔት (Cloudflare/ngrok/Tailscale) ለማጋለጥ፣ [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md)ን ይመልከቱ። የቱነሉ REST API በ`/api/tunnels/{cloudflared,ngrok,tailscale}/*` ስር ይገኛል፣ እና ከላይ ከተመዘገበው የወጪ ፕሮክሲ ሰንሰለት ነጻ ነው።
### 1proxy API
| ዘዴ | መጨረሻ ነጥብ | መግለጫ |
| -------- | -------------------------------------- | ------------------------- |
| `GET` | `/api/settings/oneproxy` | የ1proxy ፕሮክሲዎችን ዘርዝሩ |
| `GET` | `/api/settings/oneproxy?action=stats` | ስታቲስቲክስ + የማመሳሰል ሁኔታን ያግኙ |
| `GET` | `/api/settings/oneproxy?action=status` | የማመሳሰል ሁኔታን ብቻ ያግኙ |
| `POST` | `/api/settings/oneproxy` | ማመሳሰልን ያስጀምሩ |
| `POST` | `/api/settings/oneproxy/rotate` | ወደ ቀጣዩ ፕሮክሲ ያዙሩ |
| `DELETE` | `/api/settings/oneproxy?id=uuid` | አንዱን ይሰርዙ |
| `DELETE` | `/api/settings/oneproxy?clearAll=1` | ሁሉንም ያጽዱ |
### የላይኛው ዥረት ፕሮክሲ API
| ዘዴ | መጨረሻ ነጥብ | መግለጫ |
| -------- | --------------------------------- | ------------------------- |
| `GET` | `/api/upstream-proxy/:providerId` | የላይኛውን ዥረት ፕሮክሲ ውቅር ያግኙ |
| `PUT` | `/api/upstream-proxy/:providerId` | የላይኛውን ዥረት ፕሮክሲ ሁነታ ያዋቅሩ |
| `DELETE` | `/api/upstream-proxy/:providerId` | የላይኛውን ዥረት ፕሮክሲ ውቅር ያስወግዱ |
---
## የአካባቢ ተለዋዋጮች
| ተለዋዋጭ | ነባሪ | መግለጫ |
| --------------------- | ------ | ---------------------------------------------------------- |
| `ENABLE_SOCKS5_PROXY` | `true` | የSOCKS5 ፕሮክሲ ድጋፍን ያንቁ (በ`.env.example` ውስጥ ነባሪው `true` ነው) |
---
## ችግር ፈቺ
### "SOCKS5 ፕሮክሲ ተሰናክሏል"
በ`.env` ፋይልዎ ውስጥ `ENABLE_SOCKS5_PROXY=true` ያዘጋጁና እንደገና ያስጀምሩ።
### በፕሮክሲ በኩል የሚከሰቱ የ"socket hang up" ስህተቶች
የስራ ፈት ግንኙነቶችን በሚያቋርጡ ርካሽ ፕሮክሲዎች ላይ ይህ የተለመደ ነው። OmniRoute ይህን ቀድሞውኑ በሚከተሉት መንገዶች ይቆጣጠራል፦
- በፕሮክሲ ግንኙነቶች ላይ keep-aliveን በማሰናከል (`keepAliveTimeout: 1`)
- pipeliningን በማሰናከል (`pipelining: 0`)
- ተደጋጋሚ የhandshake ሂደቶችን ለማስወገድ dispatchersን በመሸጎጥ
ችግሩ ከቀጠለ፣ ሌላ ፕሮክሲ ይሞክሩ ወይም የ1proxy rotation ባህሪን ይጠቀሙ።
### በOAuth ወቅት "unsupported_country_region_territory"
የOAuth ፍሰትን ከመጀመርዎ **በፊት** ፕሮክሲው መዋቀሩን ያረጋግጡ። OmniRoute የOAuth token exchangeን በተዋቀረው ፕሮክሲ በኩል ያስተላልፋል። መጀመሪያ ዓለም አቀፍ ወይም በአቅራቢ ደረጃ ያለ ፕሮክሲ ያዘጋጁ፣ ከዚያ ይገናኙ።
### ፕሮክሲው ጥቅም ላይ አለመዋሉ
የመፍትሔ ቅደም ተከተሉን ያረጋግጡ፦
1. በ`GET /api/settings/proxy?resolve=your-connection-id` ያረጋግጡ
2. የፕሮክሲው `status` `active` መሆኑን ያረጋግጡ (`inactive` አለመሆኑን)
3. የፕሮክሲ ምደባው ወሰን ከግንኙነትዎ ጋር መዛመዱን ያረጋግጡ
### የ1proxy ማመሳሰል አለመሳካት
የማመሳሰል ሁኔታውን ያረጋግጡ፦
```bash
curl "http://localhost:20128/api/settings/oneproxy?action=status"
```
`consecutiveFailures >= 5` ከሆነ፣ circuit breaker ተነስቷል። ዳግም ለማስጀመር አገልጋዩን እንደገና ያስጀምሩ፣ ወይም በእጅ እስኪጀመር ይጠብቁ።
---
## የውሂብ ጎታ ንድፍ
### `proxy_registry` ሰንጠረዥ
```sql
CREATE TABLE proxy_registry (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
type TEXT NOT NULL DEFAULT 'http',
host TEXT NOT NULL,
port INTEGER NOT NULL,
username TEXT DEFAULT '',
password TEXT DEFAULT '',
region TEXT,
notes TEXT,
status TEXT DEFAULT 'active',
source TEXT NOT NULL DEFAULT 'manual', -- 'manual' ወይም 'oneproxy'
quality_score INTEGER, -- 0-100 (ለ1proxy ብቻ)
latency_ms INTEGER, -- ሚሊሰከንዶች (ለ1proxy ብቻ)
anonymity TEXT, -- transparent/anonymous/elite
google_access INTEGER DEFAULT 0, -- Googleን ማግኘት ይችላል? (1proxy)
last_validated TEXT, -- ISO timestamp (1proxy)
country_code TEXT, -- ISO ባለ2-ፊደል ኮድ (1proxy)
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
```
### `proxy_assignments` ሰንጠረዥ
```sql
CREATE TABLE proxy_assignments (
id INTEGER PRIMARY KEY AUTOINCREMENT,
proxy_id TEXT NOT NULL REFERENCES proxy_registry(id),
scope TEXT NOT NULL, -- 'global', 'provider', 'account', 'combo'
scope_id TEXT, -- የአቅራቢ ID፣ የግንኙነት ID ወይም የcombo ID
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL,
UNIQUE(scope, scope_id)
);
```
---
## የፕሮክሲ ጤንነት ማረጋገጥ (v3.8.16+)
የOmniRoute **proxy fast-fail** ዘዴ (`src/lib/proxyHealth.ts`) ፈጣን የTCP ግንኙነት ማረጋገጫን በመጠቀም የማይሰሩ ፕሮክሲዎችን በ<2s ውስጥ ይለያል፤ ከዚያም በእያንዳንዱ ጥያቄ ላይ የሚፈጠረውን ተጨማሪ ወጪ ለማስወገድ **ውጤቱን ይሸጉጣል**።
### እንዴት እንደሚሰራ
```
ጥያቄ ──▶ ProxyHealthCache.get(url)
│
├─ በመሸጎጫ ተገኝቷል + አዲስ ነው? ──▶ የተሸጎጠውን ሁኔታ መልስ
│
└─ በመሸጎጫ አልተገኘም / ያረጀ ነው? ──▶ የTCP ግንኙነት ወደ host:port
(ጊዜ ገደብ፦ FAST_FAIL_TIMEOUT_MS)
──▶ ለHEALTH_CACHE_TTL_MS ሸጉጥ
──▶ ውጤቱን መልስ
```
ያለዚህ፣ የማይሰራ ፕሮክሲ ከመክሸፉ በፊት እያንዳንዱን ጥያቄ ለሙሉ `PROXY_TIMEOUT_MS` (ነባሪ 30s) ያግዳል።
### ሊስተካከሉ የሚችሉ የአካባቢ ተለዋዋጮች
| ተለዋዋጭ | ነባሪ | ዓላማ |
| ---------------------------- | ------- | ------------------------------------- |
| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000` | ለእያንዳንዱ የጤንነት ማረጋገጫ የTCP ግንኙነት ጊዜ ገደብ |
| `PROXY_HEALTH_CACHE_TTL_MS` | `30000` | የጤንነት ውጤት በመሸጎጫ የሚቆይበት ጊዜ |
**የሚመከሩ እሴቶች፦**
| ሁኔታ | የFast-fail ጊዜ ገደብ | የመሸጎጫ TTL | ምክንያት |
| ------------------------------ | ----------------- | --------- | ------------------------------------------------------- |
| ከፍተኛ ፍሰት ያለው የAPI gateway | 1500ms | 60000ms | ኃይለኛ fail-fast፣ ማረጋገጫዎችን ለመቀነስ ረዘም ያለ መሸጎጫ |
| በተለያዩ ጂኦግራፊያዊ ቦታዎች የተሰራጩ nodes | 3000ms | 15000ms | ቀርፋፋ አውታረ መረቦች ተጨማሪ ጊዜ ያስፈልጋቸዋል፤ ለፈጣን failover አጭር መሸጎጫ |
| ልማት / ሙከራ | 1000ms | 10000ms | በአካባቢያዊ ፕሮክሲዎች ላይ ፈጣን ድግግሞሽ |
| ድብቅነት / ፀረ-ማግኘት | 2500ms | 45000ms | የrate limit ገደቦችን ሊያስነሳ የሚችል ፈጣን ፍተሻን ለማስወገድ |
### የፕሮክሲ ጤንነትን መመርመር
```ts
import { getAllProxyHealthStatuses, invalidateProxyHealth } from "omniroute/proxyHealth";
const statuses = getAllProxyHealthStatuses();
for (const s of statuses) {
console.log(`${s.proxyUrl} → healthy=${s.healthy}, stale=${s.stale}`);
}
// የተወሰነ ፕሮክሲ እንደገና እንዲፈተሽ አስገድድ
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");
```
የመሸጎጫ ግቤቱ `HEALTH_CACHE_TTL_MS`ን ሲያልፍ የ`stale` ምልክት `true` ይሆናል፣ ቀጣዩም ጥያቄ አዲስ ማረጋገጫ ያስነሳል።
### በፕሮክሲ ዓይነት የተመሰረቱ ነባሪዎች
የጤንነት ማረጋገጫው በURL scheme ላይ የተመሰረቱ አግባብነት ያላቸውን ነባሪዎች ይጠቀማል፦
| Scheme | ነባሪ port |
| -------------------------- | -------- |
| `http://` | 8080 |
| `https://` | 443 |
| `socks5://` / `socks5h://` | 1080 |
በURL ውስጥ ያሉ ብጁ ports (`http://host:9999`) ሁልጊዜ ከscheme ነባሪው ቅድሚያ ይሰጣቸዋል።
---
## የፕሮክሲ ትንታኔ እና ታዛቢነት
OmniRoute ኦፕሬተሮች የማዘዋወር ስርዓተ ጥለቶችን፣ ድንገተኛ የመዘግየት ጭማሪዎችን እና ተደጋጋሚ ብልሽቶችን እንዲመረምሩ ለማገዝ የእያንዳንዱን ፕሮክሲ አጠቃቀም ይከታተላል።
### የሚከታተሉ መረጃዎች
በተዋቀረ ፕሮክሲ በኩል ለሚያልፍ እያንዳንዱ ጥያቄ፣ OmniRoute የሚከተሉትን ይመዘግባል፦
| መለኪያ | መግለጫ |
| ------------ | ------------------------------------------- |
| `proxy_url` | ሙሉ የፕሮክሲ URL (የማረጋገጫ መረጃዎች ተሸፍነው) |
| `provider` | የላይኛው ዥረት አቅራቢ መለያ (openai, anthropic, ወዘተ) |
| `latency_ms` | የፕሮክሲ የግንኙነት ማቋቋሚያን ጨምሮ ጠቅላላ የደርሶ መልስ ጊዜ |
| `connect_ms` | የTCP ግንኙነት ጊዜ ብቻ |
| `status` | ከላይኛው ዥረት የተመለሰ የHTTP ሁኔታ ኮድ |
| `error` | ጥያቄው ካልተሳካ የስህተት ክፍል |
| `timestamp` | ISO 8601 UTC |
### ውሂቡን ማግኘት
```bash
# የቅርብ ጊዜ የፕሮክሲ ክስተቶች
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
"http://localhost:20128/api/usage/proxy-logs?limit=100"
```
ትክክለኛው የመጨረሻ ነጥብ `/api/usage/proxy-logs` ነው (`src/app/api/usage/proxy-logs/route.ts`ን ይመልከቱ)። ይህ የመጨረሻ ነጥብ የሚከተሉትን ይደግፋል፦
- `GET /api/usage/proxy-logs` — የፕሮክሲ ምዝግቦችን ሰርስሮ ማውጣት
- `DELETE /api/usage/proxy-logs` — ሁሉንም የፕሮክሲ ምዝግቦች ማጽዳት
ካስፈለገ፣ የተጠቃለሉ ስታቲስቲክሶችን በSQL በኩል በቀጥታ ከ`proxy_logs` ሰንጠረዥ መጠየቅ ይቻላል። የዳሽቦርዱ UI የተጠቃለሉ እይታዎችን ሊያቀርብ ይችላል።
### የተለመዱ ስርዓተ ጥለቶች
**በስኬትና በውድቀት መካከል የሚፈራረቅ ፕሮክሲን ለይቶ ማወቅ**፦
```sql
SELECT proxy_url,
COUNT(*) AS total,
SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) AS errors,
ROUND(100.0 * SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) / COUNT(*), 1) AS error_pct
FROM proxy_logs
WHERE timestamp > datetime('now', '-1 hour')
GROUP BY proxy_url
HAVING error_pct > 5
ORDER BY error_pct DESC;
```
**ዘገምተኛ ፕሮክሲዎችን ማግኘት** (የp95 መዘግየት > 2s)፦
```sql
WITH ranked AS (
SELECT proxy_url, latency_ms,
PERCENT_RANK() OVER (PARTITION BY proxy_url ORDER BY latency_ms) AS pct
FROM proxy_logs
WHERE timestamp > datetime('now', '-24 hour')
)
SELECT proxy_url, latency_ms
FROM ranked
WHERE pct >= 0.95
ORDER BY latency_ms DESC;
```
---
## የማፈራረቅ ስልት የውሳኔ ዛፍ
በርካታ ፕሮክሲዎች ለአንድ ወሰን ሲመደቡ፣ OmniRoute ለእያንዳንዱ ጥያቄ የትኛውን መጠቀም እንዳለበት ለመምረጥ **የማፈራረቅ ስልት** ይጠቀማል። ስልቱ በወሰን ደረጃ ይዋቀራል (ዓለም አቀፍ፣ ለእያንዳንዱ አቅራቢ፣ ለእያንዳንዱ መለያ፣ ለእያንዳንዱ ጥምረት)።
### የሚገኙ ስልቶች
| ስልት | መቼ መጠቀም እንደሚገባ | የጥቅምና ጉዳት ሚዛን |
| --------------- | ------------------------------------- | --------------------------------------------------------- |
| `quality` (ነባሪ) | የተለያየ ጥራት ያላቸው ፕሮክሲዎች በሚጠቀም የምርት አካባቢ | ከፍተኛ ደረጃ የተሰጣቸውን ፕሮክሲዎች ይመርጣል፤ ዝቅተኛ ደረጃ ያላቸውን ላያገለግል ይችላል |
| `random` | የጭነት ስርጭት፣ ግላዊነት | እኩል ስርጭት፤ የጥራት ምልክቶችን ችላ ይላል |
| `sequential` | ስህተት ማረም፣ ውጤቱ አስቀድሞ የሚወሰን ሙከራ | ፕሮክሲዎችን በቅደም ተከተል ያፈራርቃል፤ ለመረዳት ቀላል ነው |
### የውሳኔ ዛፍ
```
ለፕሮክሲዎችዎ የጥራት ውጤቶች አሉዎት?
│
┌───────────┴───────────┐
│ │
አዎ የለም
│ │
ሁሉም ፕሮክሲዎች │
በጥራት በግምት │
እኩል ናቸው? │
│ │
┌────┴────┐ │
│ │ │
አዎ አይደሉም ይጠቀሙ
│ │ `random`
│ │ (እኩል ስርጭት
│ │ ከጊዜ በኋላ የጥራት
│ │ ውሂብን ያከማቻል)
│ │
│ `quality`ን ይጠቀሙ
│ (ለተለያየ ጥራት
│ ምርጥ ነው)
│
`random`ን ይጠቀሙ
(ጭነቱን በእኩልነት
ያሰራጩ)
```
## ለራስዎ ፕሮክሲዎች ራስ-ሰር የብልሽት ማግለል
የ1proxy የገበያ ቦታ ፑል ያልተሳኩ ፕሮክሲዎችን በራሱ ቀስ በቀስ ከአገልግሎት ያወጣል (ይመልከቱ
[የፕሮክሲ ጥራት ውጤቶች](#proxy-quality-scores))። ወደ መዝገቡ **እርስዎ** ላከሏቸው
ፕሮክሲዎች፣ የበስተጀርባ ጤና መርሐግብር አስኪያጁ
(`src/lib/proxyHealth/scheduler.ts`) ምንም ነገር ሳይሰርዝ፣ ተመሳሳይ የሆነውን
«የማይሰራ አባልን ከሰንሰለቱ በራስ-ሰር የማግለል» ባህሪ ያቀርባል፦
```bash
# .env — አንድን ፕሮክሲ ከ3 ተከታታይ ያልተሳኩ ምርመራዎች በኋላ ለስላሳ በሆነ መንገድ ያሰናክሉ፤
# እንደገና ለምርመራዎች ምላሽ መስጠት ሲጀምር በራስ-ሰር ያንቁት።
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3
```
በባለብዙ-ፕሮክሲ ሰንሰለት ውስጥ የሚሠራበት መንገድ፦
1. መርሐግብር አስኪያጁ እያንዳንዱን የተመዘገበ ፕሮክሲ በየ`PROXY_HEALTH_INTERVAL_MS`
ይመረምራል (ነባሪው 10 ደቂቃ፤ ዝቅተኛው 1 ደቂቃ)።
2. ከ`PROXY_AUTO_REMOVE_AFTER` ተከታታይ **አሳማኝ** ብልሽቶች በኋላ (እውነተኛ
የግንኙነት ብልሽት — የጊዜ ማብቃት ወይም የምርመራ ኢላማው የራሱ 5xx በፍጹም አይቆጠርም፤
[የፕሮክሲ ጤና ምርመራ](#proxy-health-checking-v3816)ን ይመልከቱ)፣ የፕሮክሲው `status`
ወደ `dead` ይቀየራል።
3. `dead` በፑል/ሽክርክር መፍቻ የሚጠቀምበት የንቁ-ሁኔታ ማጣሪያ
ከሚያገላቸው ሁኔታዎች አንዱ ነው፤ ስለዚህ የአንድ ወሰን ሽክርክር (round-robin / random / sticky /
latency — [የሽክርክር ስልት ውሳኔ ዛፍ](#rotation-strategy-decision-tree)ን ይመልከቱ)
ያንን ፕሮክሲ ለአዳዲስ ጥያቄዎች መስጠቱን ወዲያውኑ ያቆማል። በፑሉ ውስጥ ያሉ ሌሎች ፕሮክሲዎች
አይነኩም፣ እንዲሁም መላው ፑል ያለማስጠንቀቂያ ወደ ቀጥተኛ ግንኙነት
ፈጽሞ አይመለስም — የ[ባለ4-ደረጃ ፕሮክሲ ስርዓት](#4-level-proxy-system)ን የዝግ-ብልሽት
መከላከያ ይመልከቱ።
4. መርሐግብር አስኪያጁ `dead` ፕሮክሲዎችን በተመሳሳይ ክፍተተ-ጊዜ መመርመሩን ይቀጥላል። ቀጣዩ
የተሳካ ምርመራ `status`ን መልሶ ወደ `active` ይቀይረዋል፣ እናም ፕሮክሲው እንደገና ወደ ሽክርክሩ ይገባል —
እንደገና በእጅ ማከል አያስፈልግም።
ይህ ሆን ተብሎ **በምርጫ የሚነቃ እና አጥፊ ያልሆነ** ነው፦ በነባሪነት መርሐግብር አስኪያጁ
ብልሽቶችን ብቻ ይቆጥራል እና ይመዘግባል (`decision.ts` ውስጥ ያለውን ፖሊሲ C ይመልከቱ)፤
እንዲሁም `PROXY_AUTO_DISABLE` አንድንም ረድፍ ፈጽሞ አይሰርዝም — ለዚያ የተለየውና ይበልጥ ጥብቅ የሆነው
`PROXY_AUTO_REMOVE` ጠቋሚ አለ። ሁለቱም `true` ከተደረጉ፣ `PROXY_AUTO_REMOVE`
ቅድሚያ ያገኛል (ሊሰረዝ ለተቃረበ ፕሮክሲ በመካከል ለስላሳ ማሰናከል ምንም ጥቅም የለውም)።
ለተሟላው የተለዋዋጮች ዝርዝር የ[አካባቢ ውቅር](../reference/ENVIRONMENT.md) ማጣቀሻን
ይመልከቱ።
---
> 📖 **ተዛማጅ ሰነዶች፦**
>
> - [የተጠቃሚ መመሪያ](../guides/USER_GUIDE.md) — አጠቃላይ ማዋቀር እና ውቅር
> - [የAPI ማጣቀሻ](../reference/API_REFERENCE.md) — ሙሉ የAPI ሰነድ
> - [የአካባቢ ውቅር](../reference/ENVIRONMENT.md) — ሁሉም የአካባቢ ተለዋዋጮች

311
docs/i18n/am/docs/ops/QUALITY_GATE_PLAYBOOK.md Normal file
View File

@@ -0,0 +1,311 @@
# Quality-Gate System — Critical Assessment, Catalog and Replication Playbook (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/QUALITY_GATE_PLAYBOOK.md) · 🇸🇦 [ar](../../../ar/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇦🇿 [az](../../../az/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇧🇬 [bg](../../../bg/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇧🇩 [bn](../../../bn/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇨🇿 [cs](../../../cs/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇩🇰 [da](../../../da/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇩🇪 [de](../../../de/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇬🇷 [el](../../../el/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇪🇸 [es](../../../es/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇪🇪 [et](../../../et/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇷 [fa](../../../fa/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇫🇮 [fi](../../../fi/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇫🇷 [fr](../../../fr/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇪 [ga](../../../ga/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [gu](../../../gu/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇳🇬 [ha](../../../ha/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇱 [he](../../../he/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [hi](../../../hi/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇭🇷 [hr](../../../hr/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇭🇺 [hu](../../../hu/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇦🇲 [hy](../../../hy/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇩 [id](../../../id/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇳🇬 [ig](../../../ig/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇹 [it](../../../it/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇯🇵 [ja](../../../ja/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇬🇪 [ka](../../../ka/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇰🇭 [km](../../../km/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [kn](../../../kn/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇰🇷 [ko](../../../ko/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇱🇹 [lt](../../../lt/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇱🇻 [lv](../../../lv/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [ml](../../../ml/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [mr](../../../mr/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇲🇾 [ms](../../../ms/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇲🇹 [mt](../../../mt/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇲🇲 [my](../../../my/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇳🇵 [ne](../../../ne/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇳🇱 [nl](../../../nl/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇳🇴 [no](../../../no/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [or](../../../or/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [pa](../../../pa/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇵🇭 [phi](../../../phi/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇵🇱 [pl](../../../pl/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇵🇹 [pt](../../../pt/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇷🇴 [ro](../../../ro/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇷🇺 [ru](../../../ru/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇱🇰 [si](../../../si/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇸🇰 [sk](../../../sk/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇸🇮 [sl](../../../sl/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇷🇸 [sr](../../../sr/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇸🇪 [sv](../../../sv/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇰🇪 [sw](../../../sw/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [ta](../../../ta/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇮🇳 [te](../../../te/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇹🇭 [th](../../../th/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇹🇷 [tr](../../../tr/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇵🇰 [ur](../../../ur/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇺🇿 [uz](../../../uz/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇻🇳 [vi](../../../vi/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇳🇬 [yo](../../../yo/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/QUALITY_GATE_PLAYBOOK.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/QUALITY_GATE_PLAYBOOK.md)
---
> **ይህ ሰነድ ምንድን ነው።** የOmniRoute የጥራት-በር ስርዓት ወሳኝ ግምገማ፣
> ከኢንዱስትሪው ምርጥ ልምዶች ጋር የተነጻጸረ፣ **በተጨማሪም** የሁሉም የጥራት
> ማረጋገጫ ነጥቦች አጠቃላይ ዝርዝር እና ተመሳሳይ ስርዓትን
> በማንኛውም ፕሮጀክት ላይ ለመተግበር **ከመሣሪያ ያልተገደበ የማባዛት ዕቅድ**። በ2026-06-16 ከትክክለኛው የrepository ሁኔታ (ከትውስታ ሳይሆን) የተፈጠረ።
>
> መመዘኛዎች፦ OWASP DSOMM · OpenSSF Scorecard · SLSA · SonarQube "Clean as You Code" ·
> Quality-Ratchet pattern · DORA 2024 · OWASP LLM Top 10 (2025) · የmutation-testing ምርጥ ልምዶች።
>
> ለእያንዳንዱ በር ባለሥልጣናዊ ማጣቀሻ (እያንዳንዱ በር ምን እንደሚያረጋግጥ፣ CI job፣ ratchet ከ
> policy ጋር፣ blocking ከadvisory ጋር)፣
> [የጥራት በሮች ማጣቀሻን](../architecture/QUALITY_GATES.md) ይመልከቱ።
---
## ክፍል 1 — ውሳኔ እና የብስለት ምደባ
**አጠቃላይ ደረጃ፦ A− / "የላቀ"። ከፕሮጀክቶች ከፍተኛው ~5–10%።** ስርዓቱ ኢንዱስትሪው በግልጽ ስም የሚጠራቸውን
በርካታ ንድፎች በራሱ ተግባራዊ ያደርጋል — ይህም እጅግ ጠንካራው የመጣጣም
ምልክት ነው (የማረጋገጫ ዝርዝር አልቀዳንም፤ ትክክለኛዎቹ ልምዶች ላይ በተናጥል ደርሰናል)።
| የማጣቀሻ ማዕቀፍ | ያለንበት ደረጃ | ውጤት |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| **OWASP DSOMM** (5 ደረጃዎች፣ 5 ልኬቶች) | ጠንካራ ደረጃ 3፣ በ_የፈተና ጥንካሬ_ እና _የስታቲክ ትንተና ጥልቀት_ ወደ 4 እየደረሰ። አብዛኞቹ ድርጅቶች በ1–2 ላይ ናቸው። | **L3→L4** |
| **OpenSSF Scorecard** (18 ፍተሻዎች) | CI-Tests፣ Code-Review፣ Dependency-Update-Tool፣ Fuzzing፣ SAST፣ Signed-Releases (provenance)፣ Token-Permissions፣ Vulnerabilities እና Dangerous-Workflow እናልፋለን። **ክፍተቶች፦** በ`main` ላይ Branch-Protection OFF ነው፤ አንዳንድ actions አልተሰኩም። | **~7–8/10** |
| **SLSA** (4 ደረጃዎች) | `npm publish --provenance` + `id-token: write` + በGitHub የሚስተናገድ build = **L2**፣ ወደ L3 እየቀረበ። ለL3+ የተጠናከረ/hermetic builder ይጎድላል። | **L2→L3** |
| **SonarQube "Clean as You Code"** | ተመሳሳይ ፍልስፍና፦ ratchet የ_ኋላ መመለስ አለመኖርን_ በበር ይቆጣጠራል (አዲስ code metricን አያባብስም)። **ልዩነት፦** Sonar **ጥቂት** ሁኔታዎችን ይመክራል፤ እኛ ~46 በሮች አሉን (የድካም አደጋ)። | **የተጣጣመ፣ ከማስጠንቀቂያ ጋር** |
| **Quality-Ratchet pattern** | የማጣቀሻ ትግበራ፦ ratchet + `dedicatedGate` + `tightenSlack` + `--require-tighten` + graceful-skip። ከአብዛኞቹ ይፋዊ ምሳሌዎች ይበልጥ የተራቀቀ። | **አርአያነት ያለው** |
| **DORA 2024** | በ_መረጋጋት_ ዘርፍ እጅግ ጠንካራ። አደጋ፦ ከባድ በሮች _lead time_ን ሊጨምሩ ይችላሉ — ይህም በfast-gates ክፍፍል ተቀንሷል፣ ነገር ግን የሽፋን ክፍተት አለ (ክፍል 2ን ይመልከቱ)። | **ጠንካራ (መረጋጋት)** |
| **OWASP LLM Top 10 (2025)** | አደጋ #1ን (prompt-injection) በruntime guard + promptfoo (eval) + garak (red-team) እንሸፍናለን። መደበኛ የኢንዱስትሪ መሣሪያዎች። | **የተሸፈነ** |
| **Mutation testing** | Stryker በየሌሊቱ፣ thresholds 70/50፣ 8 ወሳኝ modules። የኢንዱስትሪ ስምምነት (60% ያለው / 80% አዲስ፣ በየሌሊቱ) — **እኛ እንበልጠዋለን**። **ክፍተት፦** score እስካሁን ratchet አይደለም። | **ሊደርስ ተቃርቧል** |
---
## ክፍል 2 — ወሳኝ ግምገማ (ጥንካሬዎች + ሐቀኛ ድክመቶች)
### ጥንካሬዎች (ከአማካይ በላይ የሆኑ)
1. **ባለብዙ-መለኪያ ratchet engine።** የስርዓቱ ዋና እምብርት። በ`quality-baseline.json` ውስጥ 24 መለኪያዎች
- 4 የተለዩ baselines፣ እያንዳንዳቸው አቅጣጫ (`up`/`down`)፣ የስህተት ወሰን (`eps`)፣ የመፍትሔ ክፍተት
(`tightenSlack`) እና `dedicatedGate` flag ያላቸው። የተስተካከሉ ነገሮች **እንደተስተካከሉ ይቆያሉ** — ይህ
ለcodebase entropy መድኃኒት ነው።
2. **ለsupply-chain ጥልቀት ያለው መከላከያ።** SAST (CodeQL/Sonar) + secrets (gitleaks ከ
`useDefault` ጋር) + SCA (osv/npm-audit/Trivy/Dependabot) + licenses + lockfile + SBOM + SLSA
provenance + Scorecard + workflow hardening (zizmor)። ይህን ያህል የተሟላ stack ያላቸው codebases ጥቂት ናቸው።
3. **የGoodhart's Law መድኃኒቶች።** Coverageን እንደ ግብ መጠቀም የተለመደ anti-pattern ነው
("መለኪያው ግብ በሚሆንበት ጊዜ፣ ጥሩ መለኪያ መሆኑን ያቆማል")። እኛ የማመጣጠኛ መንገዶቹ አሉን፦
**mutation testing** (testው bugን ይይዝ እንደሆነ እንጂ lineን ብቻ ያስኬዳል እንደሆነ አይለካም)፣
**`check-test-masking`** (እንዲያልፉ assertsን ማዳከምን ይከለክላል)፣
**በእያንዳንዱ module የcoverage ዝቅተኛ ገደቦች** (ቀላል ክፍሎችን ብቻ ሳይሆን HIGH-risk codeን መፈተሽን ያስገድዳሉ) እና
**`check-pr-evidence`** (Hard Rule #18)።
4. **Anti-hallucination / consistency gates።** አልፎ አልፎ የሚገኝ እና ጠቃሚ ምድብ፦ `check-known-symbols`፣
`check-fetch-targets`፣ `check-openapi-routes`፣ `check-docs-symbols` docs፣ specs እና
string dispatches በሕይወት ያሉ symbolsን እንዲያመለክቱ ያረጋግጣሉ። lint/test የማይይዘውን "rot" ይይዛል።
5. **Advisory→blocking lifecycle።** አዳዲስ gates እንደ advisory ይገባሉ (እየበሰሉ ሳሉ
mergesን አያግዱም)፣ ከዚያም በcycle መጨረሻ blocking ይሆናሉ። ጣሪያውን ሳያሳንስ ውዝግብን ይቀንሳል።
6. **Infra ሲጎድል በአግባቡ መዝለል።** Scanners (`--ratchet`) binary/network
ካልተሳካ `exit 0` በማድረግ ይወጣሉ — የinfra እጥረት ሕጋዊ PRን ፈጽሞ አያግድም። የበሰለ engineering ነው።
7. **በደንብ የተደነገገ ባህል።** Hard Rules + `trust-but-verify` + stale-allowlist + evidence-gate
ሥነ-ሥርዓትን ወደ ራስ-ሰር ማረጋገጫ ይቀይራሉ።
### ሐቀኛ ድክመቶች (እውነተኛ ክፍተቶች)
1. **🔴 የfast-gates ክፍፍሉ አሁንም መዋቅራዊ ክፍተት ይተዋል።** `quality.yml` (PR→`release/**`)
አሁን typecheck፣ ፈጣን deterministic tests እና ለcode PRs advisory production buildን ያስኬዳል፣
ነገር ግን አሁንም ከ`ci.yml` የሚመጣውን ሙሉ የrelease-PR ወሰን (coverage ratchets፣
package artifact፣ integration፣ E2E፣ SonarQube) አያስኬድም። ምክንያቱ (ፍጥነት) ትክክለኛ ነው፣ ነገር ግን gateው
merge በሚደረግበት ቦታ መሆን አለበት (shift-left)። **ትልቁ በመጠባበቅ ላይ ያለ መዋቅራዊ ማስተካከያ።**
2. **🟠 የGate መብዛት/ድካም አደጋ።** ~46 gates + 25 jobs እጅግ ብዙ ናቸው። Sonar ራሱ እንዲህ ሲል ያስጠነቅቃል፦
ከመጠን በላይ conditions "gate fatigue" እና የቅድሚያ ክርክሮችን ያስከትላሉ፣ gate ችላ ሊባል
የሚችልበት አደጋም አለ። DORA ከባድ gates lead-timeን እንደሚጨምሩ ያስጠነቅቃል። በadvisory tiers እና
non-absolute ratchets እናቃልለዋለን፣ ነገር ግን **ለእያንዳንዱ gate ወቅታዊ የROI ግምገማ** የለም (አንዳንድ የ
doc-sync micro-gates ሊዋሃዱ ይችላሉ)።
3. **🟠 Mutation score እስካሁን ratchet አይደለም።** coverage-gamingን ለመከላከል በጣም ጠንካራው መድኃኒት
**advisory** ነው። ከሚጠባበቁ ንጥሎች ከፍተኛው ዋጋ ያለው ነው (እና ቀድሞውኑ 90% ተገንብቷል)።
4. **🟡 መከልከል ያለባቸው Advisories (በትክክለኛው ወሰን)።** `osv` (vulnCount) እና `oasdiff`
baselines የቀዘቀዙ ቢሆኑም advisory ናቸው። osv-advisory ትርጉም አለው (በድሮ dep ላይ አዲስ CVE ከመጣ
ያልተዛመደ PRን ሊያግድ ይችላል) — ነገር ግን መካከለኛ መንገድ አለ (በTrivy እንዳደረግነው
CRITICAL+fixable ብቻ ማገድ)። oasdiff advisory መሆኑ ውልን የሚሰብር ለውጥ ሊያልፍ ይችላል ማለት ነው።
5. **🟡 Runtime security በሌሊት ብቻ ይካሄዳል።** schemathesis/garak/promptfoo/chaos/k6 በሌሊት ይሰራሉ።
ትክክለኛ ውሳኔ ነው (ዝግ ናቸው፣ live server ያስፈልጋቸዋል)፣ ነገር ግን PR የinjection-guard regressionን
ሊያስገባ ይችላል፣ ይህም በቀጣዩ ሌሊት ብቻ ይገኛል።
6. **🟡 በ`main` ላይ branch-protection OFF ነው።** `BRANCH_LOCK_TOKEN` የ_release_ branchesን ይቆልፋል፣ ነገር ግን
`main` ራሱ ያልተጠበቀ ነው። Scorecard/DSOMM ነጥብ ይቀንሳሉ። የOwner እርምጃ ያስፈልጋል።
7. **🟡 CodeQL default-setup፤ semgrep በrepoው ውስጥ አልተደነገገም።** default-setup ይሰራል (0 alerts)፣ ነገር ግን
committed `codeql.yml` የበለጠ ቁጥጥር ይሰጣል፤ semgrep በrepoው ውስጥ versioned ከመሆን ይልቅ
በexternal cloud platform በኩል ይሰራል።
---
## ክፍል 3 — የጥራት ማረጋገጫ ነጥቦች የተሟላ ካታሎግ (በማንኛውም ስታክ ላይ የሚሠራ)
ከታች ያሉት 12 ምድቦች እንደገና ጥቅም ላይ ሊውል በሚችል መልኩ የቀረበው "የጥራት ሥርዓት" ናቸው። እያንዳንዱ ምድብ
**ዓላማውን** (ምንን መጠበቅ እንዳለበት)፣ **የምንጠቀምባቸውን መሣሪያዎች** እና በማንኛውም ስታክ ላይ ተመሳሳዩን ለመተግበር የሚያስችለውን **ከመሣሪያ ነፃ የሆነ አቻ አቀራረብ**
ይዘረዝራል።
### 1. ቅጥ እና ቅርጸት (ውጤቱ የማይለዋወጥ፣ ፈጣን)
- **OmniRoute:** Prettier + ESLint በ lint-staged (pre-commit) በኩል፣ 2-spaces/double-quotes/100col።
- **አጠቃላይ:** በራስ-ሰር ሊያስተካክል የሚችል አንድ formatter + አንድ linter፣ በ staged files ላይ በ pre-commit የሚሠሩ።
### 2. ዓይነቶች
- **OmniRoute:** `typecheck:core` (አጋጅ) + `typecheck:noimplicit:core` (አማካሪ) + `type-coverage` ratchet 92.17% + የእያንዳንዱ ፋይል any-budget።
- **አጠቃላይ:** በ CI ውስጥ ጥብቅ typecheck + ወደኋላ እንዳይመለስ የተገደበ type-coverage መለኪያ + የእያንዳንዱ ፋይል `any`/escape-hatch በጀት።
### 3. ሙከራዎች (ጥንካሬ)
- **OmniRoute:** 2 የማይደራረቡ runners (Node native + vitest)፣ 8 shards፣ አጠቃላይ coverage 60/60/60/60 + ratchet ~76% + **ለወሳኝ modules 8 የእያንዳንዱ module ዝቅተኛ ወሰኖች** + የምሽት property tests + የምሽት **mutation testing**።
- **አጠቃላይ:** test runner(s) + **ፍጹም** coverage ዝቅተኛ ወሰን (ዜሮ እንዳይሆን) + coverage **ratchet** (ወደኋላ እንዳይመለስ) + **ከፍተኛ አደጋ ላለው ኮድ የእያንዳንዱ module ዝቅተኛ ወሰኖች** (የGoodhart ችግርን ለመከላከል) + ለንጹሕ logic property-based ሙከራ + የሙከራ ጥራት ትክክለኛ መለኪያ የሆነ የምሽት **mutation testing**።
### 4. የሙከራ ፖሊሲ (ሥርዓቱን እንዳይጭበረበር)
- **OmniRoute:** `pr-test-policy` (የምርት ኮድ ሙከራ ይፈልጋል)፣ `check-test-masking` (የተዳከሙ asserts ያግዳል)፣ `pr-evidence` (የስኬት መግለጫ የማስረጃ block ይፈልጋል)፣ `test-discovery` (እያንዳንዱ ሙከራ በ runner እንዲሰበሰብ ያደርጋል)።
- **አጠቃላይ:** "አዲስ ኮድ ⇒ አዲስ ሙከራ" gate + assert-removed/tautology detector + የማስረጃ መስፈርት (TDD ወይም living test) + ከ globs ውጭ የተተወ ሙከራ እንዳይኖር ዋስትና።
### 5. ውስብስብነት እና የኮድ ጤንነት (ratchets)
- **OmniRoute:** ESLint-warnings (3769↓)፣ jscpd duplication (5.72%↓)፣ cyclomatic+max-lines complexity (1800↓)፣ cognitive complexity sonarjs (753↓)፣ dead-code/unused-exports knip (339↓)፣ የእያንዳንዱ ፋይል file-size (የተቆለፈ፣ መቀነስ ብቻ)፣ circular-deps (ብጁ Tarjan፣ አጋጅ)።
- **አጠቃላይ:** እያንዳንዱን የጤንነት መለኪያ ratchet ማድረግ (ማስጠንቀቂያዎች፣ ድግግሞሽ፣ cyclomatic **እና** cognitive complexity፣ dead code፣ file size፣ import cycles)። አቅጣጫው ሁልጊዜ "ወደኋላ አትመለስ" ነው።
### 6. የማይንቀሳቀስ ደኅንነት (SAST + ሚስጥሮች)
- **OmniRoute:** CodeQL (ratchet alerts = 0)፣ gitleaks (`[extend] useDefault=true` — ወሳኝ!)፣ SonarQube፣ ብጁ የደኅንነት ደንቦች (public-creds፣ error-helper፣ route-guard-membership፣ route-validation)።
- **አጠቃላይ:** SAST (CodeQL/Sonar/semgrep) ከ alert ratchet ጋር + **የተወረሰ default ruleset** ያለው secrets scanner (default ን የሚተካ custom config = እውርነት) + ለፕሮጀክቱ የተለዩ Hard Rule የደኅንነት gates።
### 7. የአቅርቦት ሰንሰለት (ጥገኞች)
- **OmniRoute:** osv-scanner + npm-audit + Trivy + Dependabot (SCA)፣ license-checker (SPDX allowlist)፣ lockfile-lint (HTTPS+sha512+registry)፣ `check-deps` anti-slopsquatting (allowlist + ዕድሜ ≥72h)።
- **አጠቃላይ:** ከብዙ ምንጮች የሚመጣ SCA + license allowlist + lockfile integrity check + የዕድሜ/typosquatting ማረጋገጫ ያለው dependency allowlist + ዝማኔዎችን በቡድን የሚያቀርብ bot።
### 8. የአቅርቦት ሰንሰለት (ግንባታ እና ልቀት)
- **OmniRoute:** SBOM (CycloneDX + syft)፣ SLSA provenance (`--provenance`)፣ OpenSSF Scorecard (በየሳምንቱ)፣ workflow ማጠናከር (zizmor: artipacked→`persist-credentials:false`፣ cache-poisoning፣ token-permissions)።
- **አጠቃላይ:** በ publish ጊዜ SBOM ማመንጨት + የተፈረመ provenance (SLSA L2+) + በመርሐግብር የሚሠራ Scorecard + ሁሉንም workflows ማጠናከር (ዝቅተኛ-መብት tokens፣ non-pusher checkout ላይ የተቀመጡ credentials እንዳይኖሩ፣ actions በ SHA እንዲቆለፉ)።
### 9. ውሎች እና API
- **OmniRoute:** oasdiff (breaking-change OpenAPI)፣ schemathesis (የምሽት contract fuzz)፣ openapi-coverage (% የተመዘገቡ routes፣ ratchet 38.3%)፣ openapi-security-tiers (spec ከ route-guard ጋር)።
- **አጠቃላይ:** breaking-change contract diff (oasdiff/buf) + በ spec ላይ የሚደረግ property-based fuzz (schemathesis) + ወደኋላ እንዳይመለስ የተገደበ የሰነድ coverage + spec↔code ወጥነት።
### 10. ሰነዶች እና i18n (እንዳያረጁ)
- **OmniRoute:** docs-sync (የተንጸባረቁ versions)፣ docs-counts-sync (በሰነዶች ውስጥ ያሉ numbers ከ code ጋር)፣ env-doc-sync፣ doc-links፣ fabricated-docs፣ cli-i18n፣ i18n-ui-coverage (`--threshold=65` + ratchet 80.1%)።
- **አጠቃላይ:** versions/counts/env-vars በ docs እና code መካከል ማመሳሰል (gate እንጂ መተማመን አይደለም) + internal links ማረጋገጥ + ወደኋላ እንዳይመለስ የተገደበ i18n coverage።
### 11. ቅዠትን መከላከል / ወጥነት (እምብዛም የማይገኘው ምድብ)
- **OmniRoute:** known-symbols (string dispatch ⇒ በእውን ያለ symbol)፣ provider-consistency፣ fetch-targets (client fetch ⇒ በእውን ያለ route)፣ docs-symbols፣ db-rules (Hard Rules #2/#5)፣ migration-numbering።
- **አጠቃላይ:** ለእያንዳንዱ "የተደገመ የእውነት ምንጭ" (registry፣ string dispatch፣ cross-layer references)፣ ሁለቱ ወገኖች እንደሚዛመዱ የሚያረጋግጥ gate። typecheck/test የማይይዙትን መበላሸት ይይዛል።
### 12. የመቋቋም ችሎታ እና ዶሜይን (ለምርቱ የተለየ)
- **OmniRoute:** chaos (fault-injection)፣ heap-growth (leak)፣ k6 (soak)፣ promptfoo+garak (LLM red-team OWASP LLM Top 10)፣ 3ቱ የመቋቋም ችሎታ ሕጎች (circuit-breaker/cooldown/lockout)።
- **አጠቃላይ:** የ**እርስዎን** ዶሜይን የብልሽት ሁኔታዎች ለይተው ለእያንዳንዳቸው gate (የምሽት ቢሆንም እንኳ) ይኑርዎት። ለ AI apps፦ injection red-team። ለ distributed systems፦ chaos + leak + soak።
---
## ክፍል 4 — ለማንኛውም ፕሮጀክት የማባዛት ዕቅድ
በ**ደረጃዎች** ይገንቡ፤ እያንዳንዱ ደረጃ ለብቻው ጥቅም የሚሰጥ ይሁን። ሁሉንም 12 ምድቦች በአንድ ጊዜ ለመተግበር አይሞክሩ —
ይህ ክፍል 2 የሚያስጠነቅቀውን የጌት ድካም በትክክል ያስከትላል። እያንዳንዱ አዲስ ጌት በ**ምክር ሰጪ** ሁኔታ ይጀምርና የተረጋጋ ሲሆን **አጋጅ** ይሆናል።
### እንደገና ጥቅም ላይ የሚውለው ዋና ክፍል፦ የ«ራቼት ጌት አወቃቀር»
መላው ሥርዓት በዚህ ባለ3-ፋይል ንድፍ ዙሪያ ይሽከረከራል። መጀመሪያ ይህን ይቅዱ፦
1. **`baseline.json`** — የተቆለፈው የመለኪያ እሴት + `direction` (`up`/`down`) + `eps` (መዋዠቅን መከላከያ) + `tightenSlack` + `dedicatedGate`።
2. **`collect-metrics.<ext>`** — መሣሪያውን ያስኬዳል፣ ቁጥሩን ያወጣል፣ `metrics.json`ን ይጽፋል።
3. **`check-ratchet.<ext>`** — `metrics.json`ን ከ`baseline.json` ጋር ያነጻጽራል፤ ከ`eps` በላይ መቀነስ ካለ **ብቻ** `exit 1`፤ መሣሪያው/መሠረተ ልማቱ ከሌለ `exit 0` (በሰላም መዝለል)፤ `--require-tighten` ካለ፣ መነሻውን ሳያዘምኑ **መሻሻል** ከተገኘ `exit 1` (የተገኘውን ማሻሻያ ይቆልፋል)።
ይህ ከተዘጋጀ፣ **እያንዳንዱ** አዲስ መለኪያ (ሽፋን፣ ውስብስብነት፣ ማስጠንቀቂያዎች፣ SAST ማንቂያዎች፣ የቅርቅብ መጠን፣ የሚውቴሽን ነጥብ…) በመነሻው ውስጥ አንድ መስመር ብቻ ይሆናል።
### ደረጃ 0 — መሠረት (1ኛ ሳምንት)
CI አለ፤ ቅርጸት አስተካካይ + ሊንተር + የዓይነት ማረጋገጫ + 1 የሙከራ አስኪያጅ + **ፍጹም** የሽፋን ዝቅተኛ ገደብ
(ለምሳሌ፣ 60%)። Pre-commit ፈጣንና በራስ-ሰር ሊስተካከሉ የሚችሉ ፍተሻዎችን ያስኬዳል። _ውጤት፦ የትኛውም PR መሠረታዊ ነገሮችን አያበላሽም።_
### ደረጃ 1 — የራቼት ሞተር (2ኛ ሳምንት) — **የሁሉም ነገር መሠረት**
ከላይ ያሉትን 3 ፋይሎች ይተግብሩ። ለማስጠንቀቂያዎች፣ ሽፋን፣ ውስብስብነት፣ ድግግሞሽ፣
ጥቅም ላይ የማይውል ኮድ እና የፋይል መጠን መነሻዎችን ይቆልፉ። _ውጤት፦ ከዚህ በኋላ የኮድ ማከማቻው መሻሻል ብቻ ይችላል።_
### ደረጃ 2 — ጥልቅ የማይንቀሳቀስ ትንተና (3ኛ ሳምንት)
SAST (CodeQL/Sonar/semgrep) ከማንቂያ ራቼት ጋር፤ የምስጢር መረጃ ቃኚ (**ነባሪውን ደንብ ስብስብ ይውረስ**)፤
SCA (osv/Dependabot) + የፈቃድ ዝርዝር + lockfile-lint። _ውጤት፦ የታወቁ ተጋላጭነቶች እና የወጡ ምስጢሮች አያልፉም።_
### ደረጃ 3 — የግንባታ አቅርቦት ሰንሰለት (4ኛ ሳምንት)
በሕትመት ጊዜ SBOM + የተፈረመ የምንጭ ማረጋገጫ (SLSA L2) + በጊዜ ሰሌዳ የሚካሄድ Scorecard + የሥራ ፍሰት ማጠናከር
(zizmor፦ አነስተኛ ቶከኖች፣ ያልተቀመጡ ማረጋገጫዎች፣ የተቸነከሩ ድርጊቶች)። _ውጤት፦ ሊከታተሉ የሚችሉና ከመነካካት የተጠበቁ ልቀቶች።_
### ደረጃ 4 — የሙከራ ጥንካሬ (5–6ኛ ሳምንት)
ጠቃሚ ከሆነ 2ኛ የሙከራ አስኪያጅ፤ **ለወሳኝ ሞጁሎች የሞጁል-ተኮር የሽፋን ዝቅተኛ ገደቦች** (Goodhartን ለመከላከል)፤
ለንጹህ ሎጂክ ባህሪ-ተኮር ሙከራ፤ **በየሌሊቱ የሚውቴሽን ሙከራ** → 1ኛው ነጥብ ሲመጣ፣
`mutationScore`ን ራቼት ያድርጉ። _ውጤት፦ ሽፋን የከንቱ ውበት መለኪያ መሆኑን ያቆማል፤ ሙከራዎች ሳንካዎችን እንደሚይዙ በማስረጃ ይረጋገጣል።_
### ደረጃ 5 — ውል እና ተለዋዋጭ ትንተና (7ኛ ሳምንት)
ይፋዊ API ካለ፦ oasdiff (ለውጥን የሚሰብር፣ **አጋጅ**) + schemathesis (በየሌሊቱ ፋዝ ሙከራ)።
እንደ ዘርፉ ተገቢነት DAST/የቀይ-ቡድን ሙከራ በየሌሊቱ። _ውጤት፦ ውሎች በጸጥታ አይሰበሩም።_
### ደረጃ 6 — ቅዠትን መከላከል እና የዘርፍ ፍተሻ (8ኛ ሳምንት)
በፕሮጀክቱ ውስጥ ላለ እያንዳንዱ «የተደገመ እውነት» አንድ የወጥነት ጌት። ለዘርፉ የተለዩ የውድቀት-ሁነታ
ጌቶች (ለAI፦ የመርፌ ጥቃት የቀይ-ቡድን ሙከራ)። _ውጤት፦ መዋቅራዊ መበስበስ እና የዘርፍ ውድቀቶች የደኅንነት መረብ ይኖራቸዋል።_
### ደረጃ 7 — አስተዳደር (ቀጣይነት ያለው)
- ለእያንዳንዱ አዲስ ጌት የምክር ሰጪ→አጋጅ ዑደት።
- `stale-allowlist`፦ እያንዳንዱ ማፈኛ ምክንያት + issue ይኖረዋል፤ ጊዜው ያለፈበት ማፈኛ ይገኛል።
- `evidence-gate`፦ በPR ውስጥ ያለ የስኬት ይገባኛል ጥያቄ ማስረጃ ይፈልጋል (ሙከራ ወይም ቀጣይነት ያለው ሙከራ)።
- **በየሩብ ዓመቱ ለእያንዳንዱ ጌት የROI ግምገማ** (ተመላሽ የማያስገኙትን ያስወግዱ/በጀት ይንሷቸው — ድካምን ይከላከላል)።
- የፕሮጀክትዎን ጥብቅ ደንቦች ወደ ሊተገበሩ የሚችሉ ጌቶች ያሳድጉ።
### ሁሉን አቋርጠው የሚሠሩ መርሆች (ለድርድር የማይቀርቡ)
- **ራቼት እንጂ ፍጹም እሴት አይደለም።** ቋሚ ቁጥርን ሳይሆን _አለመቀነስን_ በጌት ይቆጣጠሩ (ከዜሮ በላይ እንዲሆን ከሚያስገድዱ ዝቅተኛ ገደቦች በስተቀር)።
- **ፍጹም ዝቅተኛ ገደብ + ራቼት በአንድነት።** ዝቅተኛው ገደብ መፍረስን ይከላከላል፤ ራቼቱ ቀስ በቀስ መሸርሸርን ይከላከላል።
- **Goodhartን በንድፍ ይከላከሉ።** እያንዳንዱ የታለመ መለኪያ ሚዛን የሚጠብቅ ተቃራኒ መለኪያ ያስፈልገዋል (ሽፋን ⇒ ሚውቴሽን + መሸፈንን መከላከል፤ አስቸጋሪውን ኮድ ለመፈተሽ የሚያስገድዱ የሞጁል-ተኮር ዝቅተኛ ገደቦች)።
- **በሰላም መዝለል።** የጎደለ መሠረተ ልማት ፈጽሞ አያግድም፤ እውነተኛ መቀነስ ብቻ ያግዳል።
- **ውድ ለሆኑ መለኪያዎች `dedicatedGate`።** ውጫዊ binary የሚፈልጉ መለኪያዎች፣ ከተመሳሳይ ጊዜ ማዕከላዊ ራቼት ውጭ፣ የራሳቸው ስክሪፕት (ከመዝለል ጋር) ይኖራቸው።
- **ውህደቱ በሚከናወንበት ቦታ ጌት ያድርጉ።** በፈጣኑ ጌት እና በትክክለኛው ውህደት መካከል ክፍተት አይተዉ (ከfast-gates መከፈል የተገኘው ትምህርት)።
- **ጥቂትና በጥንቃቄ የተመረጡ አጋጅ ጌቶች።** Sonar/DORA፦ በጣም ብዙ ሁኔታዎች = ድካም። ከአጋጅ ጌቶች ግድግዳ ይልቅ ምክር ሰጪ + ራቼትን ይምረጡ።
---
## ክፍል 5 — የሚመከሩ ማሻሻያዎች (በቅድሚያ የተደረደሩ፣ ተኳኋኝ)
**P0 — ከፍተኛው ROI፣ ለመጠቀም ከሞላ ጎደል ዝግጁ**
1. **የMutation score ratchet** (የመጀመሪያው የምሽት Stryker ውጤቶችን ካመነጨ በኋላ)። የcoverage-Goodhart ችግርን ለመከላከል ቁልፍ መፍትሔ፤ ~90% ተጠናቋል።
2. **የቀረውን የfast-gates ክፍተት ዝጉ** — የማማከር ሳምንቱ ካለቀ በኋላ በ`quality.yml` ያለውን የproduction build ወደ አስገዳጅ ደረጃ ከፍ ያድርጉ፣ እና የተወሰኑ release-PR-only ማረጋገጫዎችን ወደ PR→release መንገድ ማዛወርዎን ይቀጥሉ።
3. **በ`main` ላይ Branch-protection** (የባለቤት ቅንብር) — Scorecardን ያሳድጋል፣ የDSOMM ክፍተቱንም ይዘጋል።
**P1 — ጠቃሚ** 4. **osv/oasdiff → በትክክለኛው ወሰን አስገዳጅ** — osv CRITICAL+fixableን ብቻ (እንደ Trivy ባለ ሁለት ደረጃ አካሄድ)፤ oasdiff ደግሞ breaking-changesን ያግዳል። 5. **`require-tighten` → አስገዳጅ** (በዑደቱ መጨረሻ) — የልኬቶችን መሻሻል ያጸናል። 6. **ለእያንዳንዱ gate የROI/ጊዜ ግምገማ** በ`ci-summary` ውስጥ — ዘገምተኛ/ዝቅተኛ ዋጋ ያላቸውን gates ፈልጎ ለማስወገድ።
**P2 — እየቀነሰ የሚሄድ ጥቅም** 7. **SLSA L3** — ከL2 ወደ ላይ መሄድ ከፈለጉ hermetic/reproducible builder (GitHub SLSA generator)። 8. **በሪፖዚቶሪው የተቀመጠ CodeQL config + versioned semgrep** — የበለጠ ቁጥጥር/ውጤትን የመድገም ችሎታ። 9. **ለእያንዳንዱ PR የDAST smoke** — ከፍተኛ ስጋት ባላቸው endpoints ላይ ፈጣን የschemathesis/promptfoo ንዑስ ስብስብ (በምሽት ብቻ ሳይሆን)። 10. **የFlakiness dashboard + DORA metrics** — gates ፍጥነትን እየሸረሸሩ አለመሆናቸውን ለማረጋገጥ።
---
## ክፍል 6 — ከrelease የተገኙ ተጨባጭ ትምህርቶች (በPhase 9 የሚጨመሩ gates)
> ይህ ክፍል gate **የጎደለባቸውን** በrelease መዝጊያዎች ወቅት የተከሰቱ እውነተኛ ክስተቶች፣
> ከተጨባጭ ማስረጃና ከታቀደው gate ጋር ይመዘግባል። እያንዳንዱ ንጥል ለክፍል 5 እጩ ነው።
### ትምህርት v3.8.27 (2026-06-17) — የ"fast-gates hole" የተወሰኑ regressions እስከ release ቀን እንዲደርሱ ያደርጋል
**ምን ተከሰተ።** በv3.8.27 `/generate-release` ወቅት፣ release PR (`release/v3.8.27` → `main`)
በተቀናጀው ዑደት ውስጥ ሙሉው `ci.yml` matrix ሲሠራ ይህ **የመጀመሪያው** ጊዜ ነበር። ውጤቱ፦ በአንድ ጊዜ 12 ውድቀቶች —
**3 የተወሰኑ tests** + ~9 flakes/env። አንዳቸውም በቀጥታ የሚሠራው ምርት regressions አልነበሩም፣
ነገር ግን የዑደቱ PRዎች ወደ `release/**` የሚገቡት ሙሉውን unit suite፣ `pr-test-policy`ን (test-masking)፣
ሙሉውን integration suite ወይም schema parity checkingን በማያስኬደው **Fast QG
(`quality.yml`)** በኩል ስለሆነ ሁሉም ሳይታወቁ ቀርተዋል። 3ቱ የተወሰኑ ችግሮች፦
1. **በUI ለውጥ ምክንያት ያረጀ test** — `permissions modal switch buttons declare button type`፦
#4034 4ኛ switch ጨመረ (a11y `type="button"` እንደተጠበቀ ነበር)፤ የtest `=== 3` ቆጠራ ጊዜ ያለፈበት
ሆነ። Static analysis ይህንን በ#4034 PR ውስጥ መያዝ ነበረበት።
2. **በpackaging ለውጥ ምክንያት ያረጀ test** — `findMissingArtifactPaths ... root runtime files`፦
`dist/http-method-guard.cjs` ሕጋዊ required-path ሆነ፤ የtest የሚጠበቀው ዝርዝር ጊዜ ያለፈበት
ሆነ።
3. **መረጃ የሚያጣ modularization divergence (ከሁሉም የከፋው)** — `settings schemas accept ... unprefixed
toggle`፦ **modularized** የሆነው `updateSettingsSchema` (`schemas/settings.ts`፣ በ#3988 የተፈጠረ) ከcanonical
ምንጩ (`settingsSchemas.ts`) ተለየ፦ **45 fields vs 85 — 40 dropped + 6 divergent (qdrant\*)**።
ይህ **dead-code** ነበር (runtime canonical የሆነውን ይጠቀማል)፣ ስለዚህ በቀጥታ ተጽዕኖ አልነበረውም፤ ነገር ግን በእጅ የተጻፈ parity
test ብቻ ያዘው። #4030 ከ#3988/#3993 የመጡ 16 ተመሳሳይ የተጣሉ ነገሮችን መልሷል፣ ይህኛው ግን አምልጧል።
**የታቀዱ gates (Phase 9)፦**
- **G1 — የfast-gates ክፍተቱን በእርግጥ ዝጉ (P0 #2ን ያስፋፋል)።** በ`quality.yml` (PR→`release/**`) ውስጥ፣
ከtypecheck + impacted tests በተጨማሪ **`pr-test-policy` (test-masking) + ሙሉውን የተወሰነ
unit suite** (ወይም ቢያንስ ፈጣንና non-flaky የሆኑትን static/parity files) ያስኪዱ።
በዚህ መንገድ ጊዜ ያለፈባቸው tests እና assert removal የሚያስገባቸው PR ውስጥ ይያዛሉ — በ
release ቀን ሳይሆን። integration/e2eን ከዚህ ውጭ ያድርጉ (ዘገምተኛ/flaky)፣ ነገር ግን የተወሰነው ንብርብር በ
PR→main ውስጥ ብቻ ሊቀር **አይችልም**።
- **G2 — Modularization parity gate (አዲስ፣ በአሁኑ ጊዜ ያልተሸፈነ)።** በmodularized barrel (`src/shared/validation/schemas/*`፣ `providerRegistry`
modules፣ ወዘተ.) እንደገና export ለተደረገ ለእያንዳንዱ symbol፣ **shape**ን (`z.object` keys፣ registry entries) ከcanonical
ምንጩ ጋር የሚያነጻጽር እና divergence (የተጣለ/ተጨማሪ field) ሲኖር **የሚያወድቅ** ማረጋገጫ። ይህ ከ
#3988 የመጣውን የ40-field መጥፋት በዚያው PR ውስጥ ይይዘው ነበር። በእጅ የተጻፉ parity testsን ወደ አጠቃላይ መፍትሔ ያሰፋል (እነዚህም አንድ ሰው
ለመጻፍ ባስታወሰባቸው ቦታዎች ብቻ ይገኛሉ)። ወጪው ዝቅተኛ ነው፦ ሁለቱንም import በማድረግ `Object.keys(shape)`ን diff ያደርጋል።
- **G3 — የተወሰነ flake triage (ድጋፍ)።** LiveWS-startup እና integration-combo/breaker
tests የሚወድቁት በCI ውስጥ ባለ server timeout/cascade (env) ምክንያት እንጂ በlogic ምክንያት አይደለም። release-PR ቀይ ምልክት
**እውነተኛ signalsን ብቻ** እንዲያሳይ እንጂ በመካከል ያሉትን የተወሰኑ regressions የሚሸፍን noise እንዳይሆን፣ እነዚህን
`known-flaky` (ከissue ጋር quarantined) ብለው ምልክት ያድርጉ።
**መርህ፦** _gate የmerge ሂደቱ በሚከናወንበት ቦታ መሥራት አለበት_ (በ"Cross-cutting principles" ውስጥ ቀድሞውኑ ተጠቅሷል)።
የv3.8.27 ክስተት ይህ በlint/typecheck ላይ ብቻ ሳይሆን በ**የተወሰነ test layer** ላይም እንደሚሠራ ያሳያል —
አለበለዚያ ጊዜ ያለፈባቸው tests + መረጃ የሚያጣ modularization ዕዳ የሚታየው በPR→main ውስጥ፣ በጅምላ፣
ከሁሉም በከፋው ጊዜ ብቻ ነው።
---
## ምንጮች (የኢንዱስትሪው ምርጥ አሠራሮች)
- OWASP DevSecOps ብስለት ሞዴል (DSOMM) — https://dsomm.owasp.org/about
- OpenSSF Scorecard / SLSA — https://openssf.org · https://slsa.dev
- SonarQube "ኮድ በሚጽፉበት ጊዜ ንጹሕ ያድርጉት" — https://docs.sonarsource.com/sonarqube-server/latest/user-guide/clean-as-you-code
- የጥራት ራቼቶች (LeadDev) — https://leaddev.com/software-quality/introducing-quality-ratchets-tool-managing-complex-systems
- ራቼቲንግን በመጠቀም ቀጣይነት ያለው የኮድ ማሻሻያ (Greiner) — https://robertgreiner.com/continuous-code-improvement-using-ratcheting/
- DORA 2024 የDevOps ሁኔታ — https://cloud.google.com/blog/products/devops-sre/announcing-the-2024-dora-report
- የሚውቴሽን ሙከራ ምርጥ አሠራሮች (Stryker) — https://stryker-mutator.io
- ሽፋን እንደ ጎጂ አሠራር (Goodhart) — https://www.industriallogic.com/blog/code-coverage-complications/
- OWASP ከፍተኛ 10 ለLLM መተግበሪያዎች (2025) — https://owasp.org/www-project-top-10-for-large-language-model-applications/
- የኮንትራት ሙከራ (oasdiff/schemathesis) — https://www.oasdiff.com · https://schemathesis.readthedocs.io

212
docs/i18n/am/docs/ops/REDIS_PRODUCTION_CONFIG.md Normal file
View File

@@ -0,0 +1,212 @@
# Redis Production Configuration Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/REDIS_PRODUCTION_CONFIG.md) · 🇸🇦 [ar](../../../ar/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇦🇿 [az](../../../az/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇧🇬 [bg](../../../bg/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇧🇩 [bn](../../../bn/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇨🇿 [cs](../../../cs/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇩🇰 [da](../../../da/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇩🇪 [de](../../../de/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇬🇷 [el](../../../el/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇪🇸 [es](../../../es/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇪🇪 [et](../../../et/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇷 [fa](../../../fa/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇫🇮 [fi](../../../fi/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇫🇷 [fr](../../../fr/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇪 [ga](../../../ga/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [gu](../../../gu/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇳🇬 [ha](../../../ha/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇱 [he](../../../he/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [hi](../../../hi/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇭🇷 [hr](../../../hr/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇭🇺 [hu](../../../hu/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇦🇲 [hy](../../../hy/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇩 [id](../../../id/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇳🇬 [ig](../../../ig/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇹 [it](../../../it/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇯🇵 [ja](../../../ja/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇬🇪 [ka](../../../ka/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇰🇭 [km](../../../km/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [kn](../../../kn/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇰🇷 [ko](../../../ko/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇱🇹 [lt](../../../lt/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇱🇻 [lv](../../../lv/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [ml](../../../ml/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [mr](../../../mr/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇲🇾 [ms](../../../ms/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇲🇹 [mt](../../../mt/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇲🇲 [my](../../../my/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇳🇵 [ne](../../../ne/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇳🇱 [nl](../../../nl/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇳🇴 [no](../../../no/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [or](../../../or/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [pa](../../../pa/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇵🇭 [phi](../../../phi/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇵🇱 [pl](../../../pl/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇵🇹 [pt](../../../pt/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇷🇴 [ro](../../../ro/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇷🇺 [ru](../../../ru/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇱🇰 [si](../../../si/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇸🇰 [sk](../../../sk/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇸🇮 [sl](../../../sl/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇷🇸 [sr](../../../sr/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇸🇪 [sv](../../../sv/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇰🇪 [sw](../../../sw/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [ta](../../../ta/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇮🇳 [te](../../../te/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇹🇭 [th](../../../th/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇹🇷 [tr](../../../tr/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇵🇰 [ur](../../../ur/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇺🇿 [uz](../../../uz/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇻🇳 [vi](../../../vi/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇳🇬 [yo](../../../yo/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/REDIS_PRODUCTION_CONFIG.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/REDIS_PRODUCTION_CONFIG.md)
---
## አጠቃላይ እይታ
Redis በOmniRoute ውስጥ **አማራጭ፣ ወሳኝ ያልሆነ ጥገኝነት** ነው — Redis በማይገኝበት ጊዜ መተግበሪያው በተገቢ ሁኔታ ወደ አማራጭ አሠራር (በማህደረ ትውስታ ውስጥ
የሚሠሩ አማራጮች) ይሸጋገራል። በምርት አካባቢ Redisን ማስተካከል ለአራት የተለያዩ
የሥራ ጫናዎች መዘግየትን ይቀንሳል፦
| የሥራ ጫና | አንቀሳቃሽ | የደንበኛ ፋብሪካ | የቁልፍ ንድፍ |
| ---------------------- | ----------------------------- | ----------------------------------------------------- | ----------------------------------------------- |
| የፍጥነት ገደብ | `rateLimiter.ts` | `getRedisClient()` — ሲያስፈልግ የሚጀመር `ioredis` singleton | `<prefix>rl:*` በLua አቶሚክ የሆኑ የፍጥነት ገደብ ጊዜ መስኮቶች |
| የማረጋገጫ መሸጎጫ | `apiKeys.ts` | የ`rateLimiter`ን ደንበኛ እንደገና ይጠቀማል | `<prefix>auth:api_key:<sha256>` ከTTL ጋር |
| የኮታ ማከማቻ | `redisQuotaStore.ts` | የተለየ `getRedisClient(url)` singleton | `<prefix>quota:*` ለእያንዳንዱ instance ሊዋቀር የሚችል |
| የማሟሟቂያ circuit breaker | `redisCircuitBreakerStore.ts` | በ`circuitBreakerFactory.ts` ውስጥ ያለ የተለየ ደንበኛ | `<prefix>warmup:cb:<connectionId>` |
አራቱም የሥራ ጫናዎች OmniRoute ከሌሎች መተግበሪያዎች ጋር በአንድ
Redis instance (ለምሳሌ `127.0.0.1:6379`) ላይ አብሮ እንዲሠራ አንድ የnamespace ቅድመ ቅጥያ ይጋራሉ። [የቁልፍ Namespace አደረጃጀት](#key-namespacing)ን ይመልከቱ።
---
## የአሁኑ ውቅር (የኮድ ነባሪዎች)
| ቅንብር | እሴት | የሚገኝበት |
| ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
| `REDIS_URL` የአካባቢ ተለዋዋጭ | `redis://redis:6379` (compose)፣ አማራጭ | `rateLimiter.ts:5`, `.env.example` |
| `REDIS_KEY_PREFIX` የአካባቢ ተለዋዋጭ | `omniroute:` (ነባሪ) | `rateLimiter.ts`, `redisQuotaStore.ts`, `redisCircuitBreakerStore.ts`, `.env.example` |
| `QUOTA_STORE_REDIS_URL` የአካባቢ ተለዋዋጭ | የተለየ፣ ከ`REDIS_URL` ሊለይ ይችላል | `quota/storeFactory.ts` |
| `QUOTA_STORE_DRIVER` | `"sqlite"` (ነባሪ)፣ `"redis"` አማራጭ | `quota/storeFactory.ts` |
| ioredis `maxRetriesPerRequest` | `3` | የ`rateLimiter.ts` ደንበኛ መፍጠሪያ |
| `enableReadyCheck` | አልተቀናበረም (የioredis ነባሪ፦ `true`) | — |
| `lazyConnect` | አልተቀናበረም (የioredis ነባሪ፦ `false`) | — |
| `retryStrategy` | አልተቀናበረም (የioredis ነባሪ፦ 200ms መሠረት፣ ኤክስፖነንሻል) | — |
| TLS / የይለፍ ቃል / DB መረጃ ጠቋሚ | **አልተዋቀረም** | — |
| Sentinel / Cluster | **አልተዋቀረም** — standalone ባለአንድ-node ብቻ | — |
---
## የቁልፍ Namespace አደረጃጀት
OmniRoute የRedis instanceን በhost ላይ ከሚሠሩ ሌሎች ማናቸውም ነገሮች ጋር ይጋራል። Namespace ከሌለ፣
እንደ `auth:api_key:<sha256>` ወይም `rl:*` ያሉ ቁልፎች ተመሳሳዩን Redis ከሚጠቀሙ ሌሎች መተግበሪያዎች
ቁልፎች ጋር ሊጋጩ ይችላሉ (ይህ instance Redisን ከሌሎች አገልግሎቶች ጎን ለጎን በ`127.0.0.1:6379` ላይ ያስኬዳል)።
ለ**እያንዳንዱ** የOmniRoute ቁልፍ ቅድመ ቅጥያ ለማከል `REDIS_KEY_PREFIX`ን ባዶ ያልሆነ ሕብረቁምፊ ያድርጉ፦
```bash
# .env — ሁሉም የOmniRoute ቁልፎች omniroute:rl:*, omniroute:auth:*, omniroute:quota:*, omniroute:warmup:cb:* ይሆናሉ
REDIS_KEY_PREFIX=omniroute:
```
- **ነባሪ፦** `omniroute:` (`REDIS_KEY_PREFIX` ካልተቀናበረ ወይም ባዶ ከሆነ ይተገበራል)።
- **የሚተገበርባቸው፦** የፍጥነት ገዳቢ + የማረጋገጫ መሸጎጫ (በ`keyPrefix` በኩል የሚጋራ `ioredis` ደንበኛ)፣
የኮታ ማከማቻ (`KEY_PREFIX = "${REDIS_KEY_PREFIX}quota"`) እና የማሟሟቂያ circuit breaker
(`KEY_PREFIX = "${REDIS_KEY_PREFIX}warmup:cb:"`)።
- ቁልፎች በRedis ውስጥ አስቀድመው በሚኖሩበት ጊዜ **ቅድመ ቅጥያውን መቀየር** የድሮ ቁልፎቹን ያለ ተጠቃሚ ያስቀራቸዋል (እነሱም
በTTL / LRU በኩል ጊዜያቸው ያበቃል)። መቀየሩ ደህንነቱ የተጠበቀ ነው፤ ምንም migration አያስፈልግም። አንዱ ልዩ ሁኔታ የተከለከለ ተብሎ ምልክት ለተደረገበት connection የማሟሟቂያ
circuit-breaker ቁልፍ ነው፦ ያለ TTL በቋሚነት ይቀመጣል፤ ስለዚህ ቀሪዎቹን በ`redis-cli --scan --pattern '<old-prefix>warmup:cb:*'` ይዘርዝሩና ይሰርዟቸው።
- **ioredis `keyPrefix`** በጽሑፍ ጊዜ ቅድመ ቅጥያውን በራስ-ሰር ይጨምራል፣ በንባብ ጊዜም በራስ-ሰር ያስወግደዋል፤
ስለዚህ የመተግበሪያው ኮድ ቅድመ ቅጥያውን በፍጹም አያየውም።
---
## የሚመከሩ የምርት አካባቢ ማስተካከያዎች
### 1. የግንኙነት ፑል / የደንበኛ አማራጮች (የioredis `Redis` constructor)
አሁን ያለው ኮድ ያለምንም ብጁ አማራጮች አንድ `new Redis(url)` ይፈጥራል። ለምርት
ባለብዙ-ቅጂ ማሰማራቶች፣ በኮዱ ውስጥ የደንበኛ ፋብሪካ ያስተላልፉ ወይም `getRedisClient()`ን ይጠቅልሉ፦
```typescript
const redis = new Redis(REDIS_URL, {
maxRetriesPerRequest: null, // የድጋሚ ሙከራ ገደብ የለም፤ retryStrategy እንዲወስን ይተዉት
enableReadyCheck: true, // ጥሪዎችን ከመቀበሉ በፊት አገልጋዩ ዝግጁ መሆኑን ያረጋግጡ
lazyConnect: true, // ሲፈጠር አይገናኝ፤ የመጀመሪያውን ጥሪ ይጠብቅ
retryStrategy: (times) => {
if (times > 10) return null; // ከ10 ድጋሚ ሙከራዎች በኋላ ይተዉ → በኋላ እንደገና ይገናኙ
return Math.min(times * 200, 5000); // 200ms፣ 400ms፣ …፣ ከፍተኛው 5s
},
enableAutoPipelining: true, // በአንድ ጊዜ የሚከናወኑ ትዕዛዞችን ወደ አንድ የTCP ጽሑፍ ያጣምሩ
keepAlive: 10000, // በየ10s የTCP keep-alive
});
```
**ቁልፍ የምርጫ ሚዛኖች፦**
- `maxRetriesPerRequest: null` + `retryStrategy` — ጊዜያዊ የRedis ዳግም መጀመሮች እያንዳንዱን
ጥያቄ ወዲያውኑ እንዳያከሽፉ ለምርት አካባቢ ይመረጣል። በ`checkRateLimit()` ውስጥ ያለው
የማህደረ ትውስታ አማራጭ የብልሽት መንገዱን ይሸፍናል።
- `lazyConnect: true` — አገልጋዩ ግንኙነቶችን መቀበል ከመጀመሩ በፊት Redis ሥራ ላይ
መሆኑ የሚፈልግ የጅምር ጥገኝነትን ያስወግዳል።
- `enableAutoPipelining: true` — በአንድ ጊዜ ለሚከናወኑ የፍጥነት-ገደብ ፍተሻዎች የደርሶ-መልስ
ጉዞዎችን ይቀንሳል፤ በአንድ ግንኙነት ከ50 RPS በላይ ጠቃሚ ነው።
### 2. የRedis አገልጋይ ውቅር (`redis.conf`)
```
# ማህደረ ትውስታ
maxmemory 80% # ለOS ገጽ መሸጎጫ ቦታ ይተዉ
maxmemory-policy allkeys-lru # በጫና ጊዜ የቆዩ የማረጋገጫ መሸጎጫ ግቤቶችን ያስወጡ
# ዘላቂነት (አማራጭ — OmniRoute ያለዚህም ብልሽትን የሚቋቋም ነው)
save 300 1 # ≥1 ቁልፍ ከተቀየረ ቢያንስ በየ5 ደቂቃው snapshot ያድርጉ
appendonly no # AOF አያስፈልግም፤ ውሂቡ እንደገና ሊፈጠር ይችላል
appendfsync no # የfsync ተጨማሪ ወጪ የለም (RDB በቂ ነው)
# አውታረ መረብ
timeout 0 # በሥራ-ፈትነት ምክንያት ግንኙነት አይቋረጥ
tcp-keepalive 300 # የ5 ደቂቃ keep-alive
tcp-backlog 511 # ለድንገተኛ ከፍተኛ ጭነት የግንኙነት backlog
# አፈጻጸም
hz 10 # ነባሪ፤ ለመዘግየት-ስሱ አጠቃቀም 100
activedefrag yes # fragmentation >10% ሲሆን በራስ-ሰር ያጠጋጉ
```
**የ`maxmemory-policy allkeys-lru` የምርጫ ሚዛን፦** የማረጋገጫ መሸጎጫ ግቤቶች በማህደረ ትውስታ
ጫና ጊዜ ሊወገዱ ይችላሉ። ይህ ደህንነቱ የተጠበቀ ነው — `setCachedApiKey` በማይገኝበት ጊዜ ሁልጊዜ
እንደገና ይሞላዋል፣ እና የSQLite አማራጭ ባለሥልጣን ምንጭ ነው። የፍጥነት-ገዳቢው Lua script በንድፍ
ለአጭር ጊዜ የሚኖሩ ትናንሽ ቁልፎችን ይፈጥራል።
### 3. የDocker Compose ቅንብሮች
የምርት compose (`docker-compose.prod.yml`) `redis:8.6.2-alpine`ን ይጠቀማል። የሚከተለውን ያክሉ፦
```yaml
redis:
image: redis:8.6.2-alpine
command:
[
"redis-server",
"--maxmemory",
"512mb",
"--maxmemory-policy",
"allkeys-lru",
"--activedefrag",
"yes",
"--save",
"300 1",
]
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 3s
retries: 3
start_period: 5s
```
### 4. የባለብዙ-ኢንስታንስ / ማስፋፊያ ግምቶች
**ለሁሉም ቅጂዎች አንድ Redis** — የፍጥነት-ገዳቢው Lua script በአንድ
ባለሥልጣን የቁልፍ ክፍተት ላይ ይመረኮዛል። ከቅጂዎች ጀርባ ያሉ በርካታ የRedis ኢንስታንሶች atomicityን
ያሳጣሉ እና በጀቱን በእጥፍ ያሳድጋሉ። ለሁሉም የመተግበሪያ ቅጂዎች አንድ Redis (ወይም failover ያለው
Redis Sentinel cluster) ይጠቀሙ።
**የግንኙነት ብዛት፦** እያንዳንዱ የመተግበሪያ ቅጂ ወደ Redis **2 የTCP ግንኙነቶችን** ይከፍታል
(የፍጥነት ገዳቢ ደንበኛ + የኮታ ማከማቻ ደንበኛ)። በ10 ቅጂዎች → 20 ግንኙነቶች፣ ይህም
ከነባሪ የRedis ኢንስታንስ 10k የግንኙነት ጣሪያ በጣም በታች ነው።
### 5. ክትትል
በጤና-ፍተሻ endpoint በኩል ያጋልጡ፦
```typescript
// src/app/api/monitoring/health/route.ts አስቀድሞ የrateLimiter ፋንክሽኖችን ይጠራል
// ለRedis የተወሰኑ ፍተሻዎችን ያክሉ፦
// 1. የPING መዘግየትን በioredis .ping()
// 2. የማህደረ ትውስታ አጠቃቀምን በINFO memory
// 3. የግንኙነት ብዛትን በINFO clients
// 4. የmaxmemory-policy የስኬት መጠንን (evicted_keys / keyspace_hits)
```
መከታተል ያለባቸው ቁልፍ መለኪያዎች፦
- **በሰከንድ የሚወገዱ ቁልፎች** — ያለማቋረጥ ከዜሮ በላይ ከሆነ፣ `maxmemory`ን ይጨምሩ
- **የታገዱ ደንበኞች** — ከዜሮ በላይ መሆን ዘገምተኛ Lua scripts ወይም ከፍተኛ ፉክክርን ያመለክታል
- **ውድቅ የተደረጉ ግንኙነቶች** — የግንኙነት ገደቡ ላይ ተደርሷል፤ በ20 ግንኙነቶች ይህ አልፎ አልፎ ብቻ ይከሰታል
---
## የአርክቴክቸር ሥዕላዊ መግለጫ
```mermaid
flowchart LR
subgraph App["የመተግበሪያ ቅጂ"]
RL[rateLimiter.ts]
AK[apiKeys.ts]
QS[redisQuotaStore.ts]
end
RL -- "REDIS_URL" --> R1[(Redis\nየጋራ)]
AK -- "የRLን client እንደገና ይጠቀማል" --> R1
QS -- "QUOTA_STORE_REDIS_URL" --> R2[(Redis\nየኮታ ማከማቻ)]
R1 --> R2 -- "ተመሳሳይ instance ሊሆን ይችላል" --> R1
```
---
## ማጣቀሻዎች
| ፋይል | ዓላማ |
| ---------------------------------- | ------------------------------------------------------------------- |
| `src/shared/utils/rateLimiter.ts` | ዋናው Redis client፣ የLua የፍጥነት ገደብ script፣ እና በማህደረ ትውስታ ውስጥ fallback |
| `src/lib/db/apiKeys.ts` | የማረጋገጫ cache — Redis→SQLite fallback |
| `src/lib/quota/redisQuotaStore.ts` | ለአማራጭ የኮታ ማከማቻ የተለየ Redis client |
| `src/lib/quota/storeFactory.ts` | በ`sqlite` እና `redis` የኮታ drivers መካከል ይቀያየራል |
| `docker-compose.prod.yml` | የምርት Redis container (image `redis:8.6.2-alpine`) |
| `.env.example` | የRedis env vars ሰነድ |
| `src/app/api/local/redis/` | ለልማት container orchestration የAPI routes |
| `bin/cli/commands/redis.mjs` | ለልማት container orchestration የCLI commands |

95
docs/i18n/am/docs/ops/RELEASE_GREEN.md Normal file
View File

@@ -0,0 +1,95 @@
# Release-Green: keeping the queue and release branch green (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/RELEASE_GREEN.md) · 🇸🇦 [ar](../../../ar/docs/ops/RELEASE_GREEN.md) · 🇦🇿 [az](../../../az/docs/ops/RELEASE_GREEN.md) · 🇧🇬 [bg](../../../bg/docs/ops/RELEASE_GREEN.md) · 🇧🇩 [bn](../../../bn/docs/ops/RELEASE_GREEN.md) · 🇨🇿 [cs](../../../cs/docs/ops/RELEASE_GREEN.md) · 🇩🇰 [da](../../../da/docs/ops/RELEASE_GREEN.md) · 🇩🇪 [de](../../../de/docs/ops/RELEASE_GREEN.md) · 🇬🇷 [el](../../../el/docs/ops/RELEASE_GREEN.md) · 🇪🇸 [es](../../../es/docs/ops/RELEASE_GREEN.md) · 🇪🇪 [et](../../../et/docs/ops/RELEASE_GREEN.md) · 🇮🇷 [fa](../../../fa/docs/ops/RELEASE_GREEN.md) · 🇫🇮 [fi](../../../fi/docs/ops/RELEASE_GREEN.md) · 🇫🇷 [fr](../../../fr/docs/ops/RELEASE_GREEN.md) · 🇮🇪 [ga](../../../ga/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [gu](../../../gu/docs/ops/RELEASE_GREEN.md) · 🇳🇬 [ha](../../../ha/docs/ops/RELEASE_GREEN.md) · 🇮🇱 [he](../../../he/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [hi](../../../hi/docs/ops/RELEASE_GREEN.md) · 🇭🇷 [hr](../../../hr/docs/ops/RELEASE_GREEN.md) · 🇭🇺 [hu](../../../hu/docs/ops/RELEASE_GREEN.md) · 🇦🇲 [hy](../../../hy/docs/ops/RELEASE_GREEN.md) · 🇮🇩 [id](../../../id/docs/ops/RELEASE_GREEN.md) · 🇳🇬 [ig](../../../ig/docs/ops/RELEASE_GREEN.md) · 🇮🇹 [it](../../../it/docs/ops/RELEASE_GREEN.md) · 🇯🇵 [ja](../../../ja/docs/ops/RELEASE_GREEN.md) · 🇬🇪 [ka](../../../ka/docs/ops/RELEASE_GREEN.md) · 🇰🇭 [km](../../../km/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [kn](../../../kn/docs/ops/RELEASE_GREEN.md) · 🇰🇷 [ko](../../../ko/docs/ops/RELEASE_GREEN.md) · 🇱🇹 [lt](../../../lt/docs/ops/RELEASE_GREEN.md) · 🇱🇻 [lv](../../../lv/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [ml](../../../ml/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [mr](../../../mr/docs/ops/RELEASE_GREEN.md) · 🇲🇾 [ms](../../../ms/docs/ops/RELEASE_GREEN.md) · 🇲🇹 [mt](../../../mt/docs/ops/RELEASE_GREEN.md) · 🇲🇲 [my](../../../my/docs/ops/RELEASE_GREEN.md) · 🇳🇵 [ne](../../../ne/docs/ops/RELEASE_GREEN.md) · 🇳🇱 [nl](../../../nl/docs/ops/RELEASE_GREEN.md) · 🇳🇴 [no](../../../no/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [or](../../../or/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [pa](../../../pa/docs/ops/RELEASE_GREEN.md) · 🇵🇭 [phi](../../../phi/docs/ops/RELEASE_GREEN.md) · 🇵🇱 [pl](../../../pl/docs/ops/RELEASE_GREEN.md) · 🇵🇹 [pt](../../../pt/docs/ops/RELEASE_GREEN.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/RELEASE_GREEN.md) · 🇷🇴 [ro](../../../ro/docs/ops/RELEASE_GREEN.md) · 🇷🇺 [ru](../../../ru/docs/ops/RELEASE_GREEN.md) · 🇱🇰 [si](../../../si/docs/ops/RELEASE_GREEN.md) · 🇸🇰 [sk](../../../sk/docs/ops/RELEASE_GREEN.md) · 🇸🇮 [sl](../../../sl/docs/ops/RELEASE_GREEN.md) · 🇷🇸 [sr](../../../sr/docs/ops/RELEASE_GREEN.md) · 🇸🇪 [sv](../../../sv/docs/ops/RELEASE_GREEN.md) · 🇰🇪 [sw](../../../sw/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [ta](../../../ta/docs/ops/RELEASE_GREEN.md) · 🇮🇳 [te](../../../te/docs/ops/RELEASE_GREEN.md) · 🇹🇭 [th](../../../th/docs/ops/RELEASE_GREEN.md) · 🇹🇷 [tr](../../../tr/docs/ops/RELEASE_GREEN.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/RELEASE_GREEN.md) · 🇵🇰 [ur](../../../ur/docs/ops/RELEASE_GREEN.md) · 🇺🇿 [uz](../../../uz/docs/ops/RELEASE_GREEN.md) · 🇻🇳 [vi](../../../vi/docs/ops/RELEASE_GREEN.md) · 🇳🇬 [yo](../../../yo/docs/ops/RELEASE_GREEN.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/RELEASE_GREEN.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/RELEASE_GREEN.md)
---
## ይህ የሚፈታው ችግር
**ሙሉው ጌት** (`.github/workflows/ci.yml` — unit shards፣ vitest፣ ratchets፣
`package-artifact`፣ SonarQube፣ E2E) የሚሰራው **በrelease PR ላይ ብቻ** (PR → `main`) ነው።
`release/**`ን ዒላማ ያደረጉ PRዎች **fast-gates**ን (`quality.yml`፦ TIA-ተጽዕኖ ያረፈባቸው
ሙከራዎች + typecheck + lint) እና፣ ለኮድ ለውጦች፣ **አማካሪ** production buildን
ያገኛሉ። ውጤቱ፦ በrelease ላይ ብቻ የሚከሰቱ አለመሳካቶች በrelease ቅርንጫፍ ላይ በዝምታ
መከማቸታቸውን ሊቀጥሉ እና በrelease ጊዜ **እያንዳንዳቸው በ~40 ደቂቃ የሚፈጁ ደረጃዎች**
ሆነው ሊፈነዱ ይችላሉ።
የ"release-green family" ዓላማ እነዚያን አለመሳካቶች **አስቀድሞ መተንበይ** ነው —
ከሙሉው ጌት ጋር ተመጣጣኝ የሆነውን **በአካባቢያዊ ሁኔታ / ከrelease ውጭ**፣
በማንኛውም ጊዜ ማረጋገጥ፣ በዚህም release PR በመጀመሪያው CI አሂዶቱ አረንጓዴ
እንዲሆን ማድረግ ነው።
> **ለድርድር የማይቀርብ መርህ፦** ከዚህ ውስጥ ምንም ነገር አስተዋጽዖ አበርካቹን
> አያግድም። PRቸው እንዲወድቅ የሚያደርግ አስገዳጅ check አንጨምርም። **drift**ው
> (ratchets) በrelease ጊዜ ጠባቂው rebaseline እንዲያደርገው ነው — በፍጹም
> የአስተዋጽዖ አበርካቹ ጉዳይ አይደለም። የትኛውም ክፍል PRን **አይዘጋም**
> (የእውቅና ስርቆት)፣ እንዲያልፍም ሙከራን **አያዳክምም**።
## ስብስቡ (4 ክፍሎች) — እያንዳንዱም እንዴት ለብቻው እንደሚሰራ
| ክፍል | ምንነቱ | መቼ እንደሚሰራ | ወሰን |
| -------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- | -------------------------- |
| **`/green-prs`** (Solution A) | ጠባቂው **የክፍት PRዎች ወረፋ** ላይ በፍላጎት የሚያካሂደው ቅኝት | **ለብቻው፣ በየጊዜው** — በተለይም ከ`/generate-release` **በፊት** | ሙሉው የPR ወረፋ → `release/**` |
| **`/validate-release-green`** (Solution C — `npm run check:release-green`) | የማረጋገጫ ሞተር፦ ሙሉውን ጌት በአንድ ቅርንጫፍ ወይም በmerge እጩ ላይ እንደገና ያከናውናል | ለብቻው፣ በማንኛውም ጊዜ | የተወሰነ ቅርንጫፍ ወይም merge-PR |
| **`/babysit <PR#>`** | የ**አንድ** PRን **ቀጥታ CI** ወደ አረንጓዴ ያደርሳል | ለብቻው፣ ለእያንዳንዱ PR | አንድ PR |
| **`nightly-release-green.yml`** (Solution D) | ራስ-ሰር የሆነ የማታ workflow፤ HARD red ሲኖር issue ይከፍታል | ራስ-ሰር (cron) | ንቁው release ቅርንጫፍ |
**ለ"ይህ ለreleaseዎች ብቻ ነው?" አጭር መልስ፦** **አይደለም።** `/green-prs` የተነደፈው
**በየጊዜው፣ በreleaseዎች መካከል** እንዲሰራ ነው። ለብቻው ማስኬድ መደበኛው አጠቃቀም
ነው — release ማለት እሱን ማስኬድ ከፍተኛውን ዋጋ የሚሰጥበት ጊዜ ብቻ ነው።
## ከPR-ወደ-release የምክር ግንባታ
`quality.yml` አሁን draft ላልሆኑ የኮድ PR-ዎች እና የMergify ወረፋ ቅርንጫፎች `Build (advisory)`ን ያካትታል።
በ`ci.yml` ውስጥ ያለውን የproduction ግንባታ አሠራር ይደግማል፦ Node 24፣ `npm-ci-retry`፣
`check:node-runtime`፣ እና `OMNIROUTE_USE_TURBOPACK=1`ን በመጠቀም `npm run build`። በዚህ workflow ውስጥ ከዚያ በኋላ ያለ ምንም quality job የግንባታ artifact ስለማይጠቀም፣ ሆን ብሎ የግንባታ artifact አይሰቅልም።
ምልክቱ ከPR-ወደ-release የሚያግድ gate እንዲሆን፣ አንድ ሳምንት የተረጋጋ የrelease-PR ሂደት ካለፈ በኋላ `continue-on-error`ን ያስወግዱ።
## መፍትሔ C — `npm run check:release-green` (ሞተሩ)
ከአሁኑ working tree ጋር የrelease ደረጃን የሚያክል validation ይደግማል፣ እና እያንዳንዱን ቀይ ሁኔታ ይመድባል፦
- **HARD** (typecheck፣ lint errors፣ unit፣ vitest፣ db-rules፣ public-creds፣ አማራጭ
`package-artifact`) → **እውነተኛ ጉድለት**፤ `exit 1`። በsource branch ላይ ይስተካከላል (TDD፣ Rule #18)።
- **DRIFT** (eslint **warnings**፣ cognitive-complexity፣ file-size) → በዑደቱ ውስጥ የተከማቸ ratchet drift ነው፣ **የአስተዋጽዖ አድራጊው ጥፋት አይደለም**፤ የሚደረገው ሪፖርት ማድረግ ብቻ ሲሆን፣ **በrelease ወቅት በmaintainer እንደገና baseline ይደረጋል**። Drift **በፍጹም** exit codeን አይለውጥም — ስለዚህ ማንንም አያግድም።
```bash
npm run check:release-green # የአሁኑ branch (working tree)
node scripts/quality/validate-release-green.mjs --json # የተዋቀረ output
node scripts/quality/validate-release-green.mjs --quick # unit+vitestን ይዘላል (drift+typecheck+lint ብቻ)
node scripts/quality/validate-release-green.mjs --with-build # package-artifactን ያካትታል (ቀርፋፋ)
```
ምርመራ አድርጎ **ሪፖርት** ብቻ ያቀርባል (ራስ-ሰር ማስተካከያ የለም)። የfix-to-green ማቀናበሪያው
በ`/green-prs` እና `/review-prs` ውስጥ ይገኛል።
## መፍትሔ A — `/green-prs` (የወረፋ ቅኝት)
ሂደት (ማጠቃለያ — ዝርዝሩን በ`green-prs` skill ይመልከቱ)፦
1. ከንቁ release branch ጋር የሚነጻጸሩ ክፍት PR-ዎችን ወረፋ **ይመዝግቡ**።
2. እያንዳንዱን PR **ይመድቡ** (አዋጭ / ውድቅ ሊደረግ የሚገባ / የደራሲ እርምጃ የሚያስፈልገው) — ውድቅ ሊደረጉ የሚገባቸው/የደራሲ እርምጃ የሚያስፈልጋቸው **ሪፖርት ይደረጋሉ እንጂ አይዘጉም** (ደራሲው ይወስናል)።
3. ለእያንዳንዱ አዋጭ PR፣ በ**ተነጠለ worktree** (Rule #19) ውስጥ PR-ውን ወደ release tip ያምጡ እና
`npm run check:release-green`ን ያስኪዱ፦
- **HARD** → co-authorshipን በመጠቀም **በአስተዋጽዖ አድራጊው branch ላይ** ያስተካክሉ (የደራሲውን «Merged» ሁኔታ ይጠብቃል)፣
ሁሉም HARD-ዎች እስኪወገዱ ድረስ እንደገና ያስኪዱ።
- **DRIFT** → እንዳለ ይተዉት፤ በrelease ወቅት እንደገና baseline ይደረጋል።
4. የPR × (ፍርድ፣ HARD reds፣ ተስተካክሏል?፣ DRIFT፣ አሁን release-green ነው?) ሰንጠረዥ **ሪፖርት ያድርጉ**።
ወረፋውን merge ሳያደርግ **ማዘጋጀት** ይችላል፤ merge የሚያደርገው በግልጽ ሲጠየቅ ብቻ ነው — PRንም በፍጹም አይዘጋም።
## የሚመከር የጊዜ ሰሌዳ
- **`/green-prs`ን በየጊዜው ያስኪዱ** (ለምሳሌ፣ በየሳምንቱ) እና **ሁልጊዜ ከ
`/generate-release` በፊት**።
- **`nightly-release-green.yml`ን** (መፍትሔ D) እንደ ቀጣይነት ያለው ምልክት ያቆዩ፦ HARD red issue ሲከፍት፣ ቅኝት ለማድረግ ጊዜው ነው።
- branchን ወይም የተወሰነ merge candidateን ለመፈተሽ **`/validate-release-green`ን** እንደ አስፈላጊነቱ ይጠቀሙ።
- አንድ የተወሰነ PR በቀጥታ CI ላይ ወደ green መድረስ ሲያስፈልገው **`/babysit <PR#>`ን** ይጠቀሙ።
## ከrelease ጋር ያለው ግንኙነት
- `/generate-release` validationን በ**Phase 0 (pre-flight)** ውስጥ ይጠራል፦ DRIFTን እንደገና baseline ያደርጋል፣ እና release PRን ከመክፈቱ በፊት
HARDን ያስተካክላል።
- `/review-prs` በmerge ውሳኔ ደረጃ ላይ release-green gateን ይጠቀማል (ከmerge በፊት green)።
የሁሉም ክፍሎች ግብ አንድ ነው፦ በrelease ቀን በ40 ደቂቃ ንብርብሮች ውስጥ ቀይ ሁኔታዎችን ከመከታተል ይልቅ፣ **በመጀመሪያው CI run ላይ green የሆነ release PR**።

58
docs/i18n/am/docs/ops/RUNNER_BOX.md Normal file
View File

@@ -0,0 +1,58 @@
# Self-Hosted Runner Box Operations (.113 pool) (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/RUNNER_BOX.md) · 🇸🇦 [ar](../../../ar/docs/ops/RUNNER_BOX.md) · 🇦🇿 [az](../../../az/docs/ops/RUNNER_BOX.md) · 🇧🇬 [bg](../../../bg/docs/ops/RUNNER_BOX.md) · 🇧🇩 [bn](../../../bn/docs/ops/RUNNER_BOX.md) · 🇨🇿 [cs](../../../cs/docs/ops/RUNNER_BOX.md) · 🇩🇰 [da](../../../da/docs/ops/RUNNER_BOX.md) · 🇩🇪 [de](../../../de/docs/ops/RUNNER_BOX.md) · 🇬🇷 [el](../../../el/docs/ops/RUNNER_BOX.md) · 🇪🇸 [es](../../../es/docs/ops/RUNNER_BOX.md) · 🇪🇪 [et](../../../et/docs/ops/RUNNER_BOX.md) · 🇮🇷 [fa](../../../fa/docs/ops/RUNNER_BOX.md) · 🇫🇮 [fi](../../../fi/docs/ops/RUNNER_BOX.md) · 🇫🇷 [fr](../../../fr/docs/ops/RUNNER_BOX.md) · 🇮🇪 [ga](../../../ga/docs/ops/RUNNER_BOX.md) · 🇮🇳 [gu](../../../gu/docs/ops/RUNNER_BOX.md) · 🇳🇬 [ha](../../../ha/docs/ops/RUNNER_BOX.md) · 🇮🇱 [he](../../../he/docs/ops/RUNNER_BOX.md) · 🇮🇳 [hi](../../../hi/docs/ops/RUNNER_BOX.md) · 🇭🇷 [hr](../../../hr/docs/ops/RUNNER_BOX.md) · 🇭🇺 [hu](../../../hu/docs/ops/RUNNER_BOX.md) · 🇦🇲 [hy](../../../hy/docs/ops/RUNNER_BOX.md) · 🇮🇩 [id](../../../id/docs/ops/RUNNER_BOX.md) · 🇳🇬 [ig](../../../ig/docs/ops/RUNNER_BOX.md) · 🇮🇹 [it](../../../it/docs/ops/RUNNER_BOX.md) · 🇯🇵 [ja](../../../ja/docs/ops/RUNNER_BOX.md) · 🇬🇪 [ka](../../../ka/docs/ops/RUNNER_BOX.md) · 🇰🇭 [km](../../../km/docs/ops/RUNNER_BOX.md) · 🇮🇳 [kn](../../../kn/docs/ops/RUNNER_BOX.md) · 🇰🇷 [ko](../../../ko/docs/ops/RUNNER_BOX.md) · 🇱🇹 [lt](../../../lt/docs/ops/RUNNER_BOX.md) · 🇱🇻 [lv](../../../lv/docs/ops/RUNNER_BOX.md) · 🇮🇳 [ml](../../../ml/docs/ops/RUNNER_BOX.md) · 🇮🇳 [mr](../../../mr/docs/ops/RUNNER_BOX.md) · 🇲🇾 [ms](../../../ms/docs/ops/RUNNER_BOX.md) · 🇲🇹 [mt](../../../mt/docs/ops/RUNNER_BOX.md) · 🇲🇲 [my](../../../my/docs/ops/RUNNER_BOX.md) · 🇳🇵 [ne](../../../ne/docs/ops/RUNNER_BOX.md) · 🇳🇱 [nl](../../../nl/docs/ops/RUNNER_BOX.md) · 🇳🇴 [no](../../../no/docs/ops/RUNNER_BOX.md) · 🇮🇳 [or](../../../or/docs/ops/RUNNER_BOX.md) · 🇮🇳 [pa](../../../pa/docs/ops/RUNNER_BOX.md) · 🇵🇭 [phi](../../../phi/docs/ops/RUNNER_BOX.md) · 🇵🇱 [pl](../../../pl/docs/ops/RUNNER_BOX.md) · 🇵🇹 [pt](../../../pt/docs/ops/RUNNER_BOX.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/RUNNER_BOX.md) · 🇷🇴 [ro](../../../ro/docs/ops/RUNNER_BOX.md) · 🇷🇺 [ru](../../../ru/docs/ops/RUNNER_BOX.md) · 🇱🇰 [si](../../../si/docs/ops/RUNNER_BOX.md) · 🇸🇰 [sk](../../../sk/docs/ops/RUNNER_BOX.md) · 🇸🇮 [sl](../../../sl/docs/ops/RUNNER_BOX.md) · 🇷🇸 [sr](../../../sr/docs/ops/RUNNER_BOX.md) · 🇸🇪 [sv](../../../sv/docs/ops/RUNNER_BOX.md) · 🇰🇪 [sw](../../../sw/docs/ops/RUNNER_BOX.md) · 🇮🇳 [ta](../../../ta/docs/ops/RUNNER_BOX.md) · 🇮🇳 [te](../../../te/docs/ops/RUNNER_BOX.md) · 🇹🇭 [th](../../../th/docs/ops/RUNNER_BOX.md) · 🇹🇷 [tr](../../../tr/docs/ops/RUNNER_BOX.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/RUNNER_BOX.md) · 🇵🇰 [ur](../../../ur/docs/ops/RUNNER_BOX.md) · 🇺🇿 [uz](../../../uz/docs/ops/RUNNER_BOX.md) · 🇻🇳 [vi](../../../vi/docs/ops/RUNNER_BOX.md) · 🇳🇬 [yo](../../../yo/docs/ops/RUNNER_BOX.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/RUNNER_BOX.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/RUNNER_BOX.md)
---
በራሱ ላይ የሚስተናገደው ፑል (በስምንቱም runners ላይ `self-hosted, omni-release`፤ በሁለቱ ላይ `omni-build`) በ **.113** ማሽን ላይ ይሰራል።
የተለካው 2026-08-28 (v3.8.50 ድህረ-ምርመራ፣ ክፍል III)፦
| ሀብት | ዋጋ | ለመርሐግብር ምን ማለት ነው |
| --------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| RAM / CPU | **31 GB / 32 cores** (ይህ ሰነድ መጀመሪያ ሲጻፍ 16 GB ነበር) | አንድ `next-build` እስከ **~14 GB** ይደርሳል → 2 ከባድ builds በአንድ ጊዜ ሲሰሩ ማሽኑን እስከ ገደቡ ይጫኑታል፤ 3 ደግሞ ያወርዱታል (2026-08-28 06:42Z፦ load 56፣ ሁለት jobs ጠፍተዋል) |
| swap | 15 GB | v3.8.50 በሚታተምበት ጊዜ swap በመጠቀም አልፎታል፤ ጫናው በ `/proc/pressure/memory` ላይ ይታያል |
| `/tmp` | **12 GB tmpfs = RAM** | እዚያ የተቀመጠ ማንኛውም ነገር memory ነው፤ ቅሪቶች ከ3 ሰዓት በኋላ ይጸዳሉ |
| disk | 188 GB | የ8 runners `_work` checkouts ያለ ገደብ ~70 GB ይደርሳሉ |
| runners | **6 listeners**፦ 4 OmniRoute (1 `omni-build` + 1 `omni-release`-only + 2 `omni-light`) + OmniHeuris + OmniMind | ሁሉም ከላይ ያለውን memory ይጋራሉ፤ `omniroute-113-3/-4/-7/-8` ተሰናክለዋል (`systemctl enable --now` አንዱን መልሶ ያስነሳል) |
## janitorን ይጫኑ (አንድ ጊዜ፣ በማሽኑ ላይ)
```bash
scp scripts/ops/runner-janitor.sh root@192.168.0.113:/opt/omniroute-ops/runner-janitor.sh
ssh root@192.168.0.113 'chmod +x /opt/omniroute-ops/runner-janitor.sh; apt-get install -y lsof'
# cron (root)፦ በየ30 ደቂቃው፣ ወደ /var/log/runner-janitor.log መዝግብ
*/30 * * * * MAX_ACTIVE_RUNNERS=6 /opt/omniroute-ops/runner-janitor.sh >> /var/log/runner-janitor.log 2>&1
```
`lsof` ያስፈልጋል፦ janitor አንድን ዱካ ከማስወገዱ በፊት ክፍት
ፋይሎችን አንድ ጊዜ በመመልከት ዱካው ስራ ፈት መሆኑን ያረጋግጣል፤ መሣሪያው ከሌለ ምንም
አያስወግድም፣ ይህንንም ያሳውቃል
(exit 1)። ማንኛውንም ለውጥ መጀመሪያ በ `--dry-run` ይሞክሩ — ምን እንደሚያደርግ
በትክክል ያትማል፣ ምንም ነገርም አይነካም።
በእያንዳንዱ run የሚያደርገው፦ የራሳችንን ቅሪቶች (`runner-*`፣ `omniroute-*`፣
`next-build*`፣ `e2e-build.tar.gz`) **በtmpfs ላይ ከ3 ሰዓት** እና በdisk
`_work/_temp` ላይ ከ24 ሰዓት በኋላ ያጸዳል፤ ከ75 ደቂቃ በላይ የቆየ `next-build`ን
ያቋርጣል (ምንም job ያን ያህል ጊዜ አይሰራም — 2026-08-27 ላይ GitHub jobን
እንደጠፋ ካወጀ በኋላ አንዱ ለ70 ደቂቃ ሲሰራ ቆይቷል)፤ unitናቸው
**የቆመ** runners የ48 ሰዓት checkoutsን ያስወግዳል፤ disk ≥ 85 %፣ memory PSI
`full/avg60` ≥ 10 %፣ እና ከ `MAX_ACTIVE_RUNNERS` በላይ listeners ሲኖሩ
(ከomniroute/other ክፍፍል ጋር) ማንቂያ ይሰጣል። Exit 1 = ትኩረት ያስፈልጋል፤ logን ያንብቡ።
## Runner ዩኒቶች፦ KillMode
የrunner ነባሪ `KillMode=process`፣ ዩኒት ሲቆም ወይም ዳግም ሲጀምር `Runner.Worker → npm → next-build`ን በሕይወት ይተዋል — ከምንም job ጋር ያልተያያዘ orphan build RAM እና CPUን መብላቱን ይቀጥላል። እያንዳንዱ OmniRoute ዩኒት `KillMode=mixed` ያለው drop-in
(`/etc/systemd/system/actions.runner.diegosouzapw-OmniRoute.<name>.service.d/10-killmode.conf`)
አለው፦ መጀመሪያ SIGTERM ወደ listener ይላካል፤ `TimeoutStop` ላይ ደግሞ SIGKILL ወደ ሙሉው cgroup ይላካል። ይህ ዩኒቱ በሚቀጥለው ጊዜ ዳግም ሲጀምር ተግባራዊ ይሆናል — **በአንድ ጊዜ አንድ runner ብቻ፣ idle ሲሆን ብቻ**፣ idle መሆኑን ማረጋገጥና ዳግም ማስጀመሩን በአንድ ትዕዛዝ ውስጥ በማድረግ ዳግም ያስጀምሩ።
## የአሠራር ደንቦች
- **የከባድ build ጣሪያ፦ በአንድ ጊዜ አንድ — በlabel የተገደበ (ከ2026-08-29 ጀምሮ)።** ሙሉ `next build`ን የሚያስኬድ እያንዳንዱ job `[self-hosted, omni-build]`ን target ያደርጋል፤ ይህን label የያዘውም **`omniroute-113-5`** ብቻ ነው (በrunners API በኩል የታከለ — እንደገና መመዝገብ አልተደረገም)፦ `ci.yml` `Build`፣ `npm-publish.yml` `publish`፣ ሁለቱም `nightly-release-green` validations፣ እና `docker-publish.yml` **amd64** (hosted 7 GB በዚህ tree ላይ ResourceExhausted ሆኗል — #11976)። arm64 Docker leg በwebpack ከ`ubuntu-24.04-arm` ላይ ይቆያል (የARM box የለም)። Docker amd64ም webpackን ይጠቀማል፦ Turbopack በዚህ tree ላይ 31 GB እያለም በBuildKit ውስጥ panic አድርጓል (`TurbopackInternalError:
there must be a path to a root`፣ run 33253576569)፤ ተመሳሳዩ tree የarm64 webpack build ግን በhosted ARM ላይ ተሳክቷል። `docker-publish` amd64 የ`heavy-build-main` concurrency groupን ከ`ci.yml` `Build` ጋር ይጋራል (`cancel-in-progress: false`)፤ ስለዚህ በአንዱ slot ላይ ወረፋ ይጠብቃል። Docker Engine በ`omniroute-113-5` ላይ መኖር አለበት (`docker info` የpublish job የመጀመሪያው step ነው)። ቀዳሚው ጣሪያ ሁለት ነበር፤ ለ31 GB ግን የተሳሳተ ነበር፦ በ2026-08-29 17:26 UTC ሁለት በተመሳሳይ ጊዜ የሚሄዱ `next-build`ዎች (15.4 GB + 17.2 GB RSS) boxን 4 GB swap ጥቅም ላይ እያለ ወደ 5 GB ነጻ ቦታ አውርደውት፣ kernel OOM አንዱን kill አድርጓል — systemd killን በ_ሌላኛው_ runner ዩኒት ላይ መዝግቧል፣ `runsvc.sh`ም ያንን listener በSIGKILL kill አድርጎታል፤ በእሱ ላይ የነበረው jobም "The runner has received a shutdown signal" በሚል ሞቷል (ከhosted-runner OOM ጋር ተመሳሳይ ጽሑፍ)። `omniroute-113-6` `omni-release`ን ብቻ ይይዛል። ከ`main` merges፣ PRs እና nightly የሚመጡ heavy builds አሁን በአንድ slot ላይ ተራ በተራ ይሄዳሉ፤ ወረፋው የዚህ ዋጋ ነው። Proxmox VM ተጨማሪ RAM (48–64 GB) ባገኘበት ቀን ሁለተኛው slot ይመለሳል፦
`gh api -X POST repos/<repo>/actions/runners/<id of omniroute-113-6>/labels -f 'labels[]=omni-build'`.
- **Light pool፦ `omni-light` (2026-08-29፣ #11965)።** `omniroute-113` እና `omniroute-113-2` ሙሉ build ሳይሆን backend-only `next build` (~5–6 GB) ለሚያስፈልጋቸው jobs `omni-light`ን ይይዛሉ፦ nightly Schemathesis፣ promptfoo፣ garak እና axe-a11y jobs። እነዚህ በhosted 7 GB runner ላይ ይሠሩ ነበር፤ ማንም ሳይከታተላቸው በ`release/v3.8.51` ላይ ሞተዋል። በbox ላይ ያለው ከፋ ሁኔታ 2 heavy + 2 light ≈ 30 + 12 GB ነው — ከ31 GB RAM በላይ ሆኖ በ16 GB swap ውስጥ ይገባል፤ ለheadroom ትክክለኛው መፍትሔ በProxmox VM (`tomni-proxmox-113`) ላይ ተጨማሪ RAM መጨመር ነው፤ ይህም የlabel ጣሪያዎቹን ወደ 3 heavy + 2 light ይቀይራል።
- **ሆን ተብሎ የቀነሱ listeners።** አራት OmniRoute ዩኒቶች በ2026-08-29 disabled ሆነዋል — boxን የሚጠቀሙት `ci.yml` `Build` እና nightlies ብቻ ሲሆኑ፣ 8 listeners idle ነበሩ፤ እያንዳንዱ ተጨማሪ listenerም 14 GB ሊጠቀም የሚችል tenant ነው። የjanitor ጣሪያ 6 ነው (`MAX_ACTIVE_RUNNERS=6` በcron ውስጥ)፦ በbox ላይ ያለውን እያንዳንዱን `Runner.Listener` ይቆጥራል፤ OmniHeuris + OmniMindም በእኛ አራት ላይ ሁለት ይጨምራሉ።
- **ማንኛውም runner busy ሆኖ ሳለ `/tmp`ን ወይም `_work`ን በእጅ ፈጽሞ አያጽዱ።** በማረጋገጡና በመሰረዙ መካከል ክፍተት ያለው check-then-delete፣ በ2026-08-27 በሂደት ላይ የነበረ Build job `_work`ን ያጣበት ምክንያት ነው። janitor ማረጋገጡንና ማስወገዱን በአንድ step ውስጥ ያከናውናል፤ እሱ እንዲሠራው ይተዉት።
- በjob መካከል runnerን ማቆም jobን cancel ያደርጋል (በቀጥታ የታየ)፦ `systemctl stop`ን listenerው የ`Runner.Worker` child በማይኖረው ጊዜ ብቻ ያስኪዱ — እና ይህን በአንድ ትዕዛዝ ውስጥ ያድርጉ።
- Workflows artefactsን በ`/tmp` ውስጥ ማቆየት የለባቸውም (እሱ RAM ነው)። ወደ`$RUNNER_TEMP` ያውርዱ (በdisk ላይ፣ ለእያንዳንዱ runner) — የ1.3 GB `next-build` artefact በtmpfs ላይ ለማረፍ 27–32 ደቂቃ ወስዷል፤ ከdisk ለመጫን ግን 2 ደቂቃ ብቻ ወስዷል።
- `.15` VPS ለhomologation ብቻ ነው — CI runnersን ፈጽሞ አያስኬድም።

95
docs/i18n/am/docs/ops/SQLITE_RUNTIME.md Normal file
View File

@@ -0,0 +1,95 @@
# SQLite Runtime Resolution (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/SQLITE_RUNTIME.md) · 🇸🇦 [ar](../../../ar/docs/ops/SQLITE_RUNTIME.md) · 🇦🇿 [az](../../../az/docs/ops/SQLITE_RUNTIME.md) · 🇧🇬 [bg](../../../bg/docs/ops/SQLITE_RUNTIME.md) · 🇧🇩 [bn](../../../bn/docs/ops/SQLITE_RUNTIME.md) · 🇨🇿 [cs](../../../cs/docs/ops/SQLITE_RUNTIME.md) · 🇩🇰 [da](../../../da/docs/ops/SQLITE_RUNTIME.md) · 🇩🇪 [de](../../../de/docs/ops/SQLITE_RUNTIME.md) · 🇬🇷 [el](../../../el/docs/ops/SQLITE_RUNTIME.md) · 🇪🇸 [es](../../../es/docs/ops/SQLITE_RUNTIME.md) · 🇪🇪 [et](../../../et/docs/ops/SQLITE_RUNTIME.md) · 🇮🇷 [fa](../../../fa/docs/ops/SQLITE_RUNTIME.md) · 🇫🇮 [fi](../../../fi/docs/ops/SQLITE_RUNTIME.md) · 🇫🇷 [fr](../../../fr/docs/ops/SQLITE_RUNTIME.md) · 🇮🇪 [ga](../../../ga/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [gu](../../../gu/docs/ops/SQLITE_RUNTIME.md) · 🇳🇬 [ha](../../../ha/docs/ops/SQLITE_RUNTIME.md) · 🇮🇱 [he](../../../he/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [hi](../../../hi/docs/ops/SQLITE_RUNTIME.md) · 🇭🇷 [hr](../../../hr/docs/ops/SQLITE_RUNTIME.md) · 🇭🇺 [hu](../../../hu/docs/ops/SQLITE_RUNTIME.md) · 🇦🇲 [hy](../../../hy/docs/ops/SQLITE_RUNTIME.md) · 🇮🇩 [id](../../../id/docs/ops/SQLITE_RUNTIME.md) · 🇳🇬 [ig](../../../ig/docs/ops/SQLITE_RUNTIME.md) · 🇮🇹 [it](../../../it/docs/ops/SQLITE_RUNTIME.md) · 🇯🇵 [ja](../../../ja/docs/ops/SQLITE_RUNTIME.md) · 🇬🇪 [ka](../../../ka/docs/ops/SQLITE_RUNTIME.md) · 🇰🇭 [km](../../../km/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [kn](../../../kn/docs/ops/SQLITE_RUNTIME.md) · 🇰🇷 [ko](../../../ko/docs/ops/SQLITE_RUNTIME.md) · 🇱🇹 [lt](../../../lt/docs/ops/SQLITE_RUNTIME.md) · 🇱🇻 [lv](../../../lv/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [ml](../../../ml/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [mr](../../../mr/docs/ops/SQLITE_RUNTIME.md) · 🇲🇾 [ms](../../../ms/docs/ops/SQLITE_RUNTIME.md) · 🇲🇹 [mt](../../../mt/docs/ops/SQLITE_RUNTIME.md) · 🇲🇲 [my](../../../my/docs/ops/SQLITE_RUNTIME.md) · 🇳🇵 [ne](../../../ne/docs/ops/SQLITE_RUNTIME.md) · 🇳🇱 [nl](../../../nl/docs/ops/SQLITE_RUNTIME.md) · 🇳🇴 [no](../../../no/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [or](../../../or/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [pa](../../../pa/docs/ops/SQLITE_RUNTIME.md) · 🇵🇭 [phi](../../../phi/docs/ops/SQLITE_RUNTIME.md) · 🇵🇱 [pl](../../../pl/docs/ops/SQLITE_RUNTIME.md) · 🇵🇹 [pt](../../../pt/docs/ops/SQLITE_RUNTIME.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/SQLITE_RUNTIME.md) · 🇷🇴 [ro](../../../ro/docs/ops/SQLITE_RUNTIME.md) · 🇷🇺 [ru](../../../ru/docs/ops/SQLITE_RUNTIME.md) · 🇱🇰 [si](../../../si/docs/ops/SQLITE_RUNTIME.md) · 🇸🇰 [sk](../../../sk/docs/ops/SQLITE_RUNTIME.md) · 🇸🇮 [sl](../../../sl/docs/ops/SQLITE_RUNTIME.md) · 🇷🇸 [sr](../../../sr/docs/ops/SQLITE_RUNTIME.md) · 🇸🇪 [sv](../../../sv/docs/ops/SQLITE_RUNTIME.md) · 🇰🇪 [sw](../../../sw/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [ta](../../../ta/docs/ops/SQLITE_RUNTIME.md) · 🇮🇳 [te](../../../te/docs/ops/SQLITE_RUNTIME.md) · 🇹🇭 [th](../../../th/docs/ops/SQLITE_RUNTIME.md) · 🇹🇷 [tr](../../../tr/docs/ops/SQLITE_RUNTIME.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/SQLITE_RUNTIME.md) · 🇵🇰 [ur](../../../ur/docs/ops/SQLITE_RUNTIME.md) · 🇺🇿 [uz](../../../uz/docs/ops/SQLITE_RUNTIME.md) · 🇻🇳 [vi](../../../vi/docs/ops/SQLITE_RUNTIME.md) · 🇳🇬 [yo](../../../yo/docs/ops/SQLITE_RUNTIME.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/SQLITE_RUNTIME.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/SQLITE_RUNTIME.md)
---
OmniRoute ሲጀምር የSQLite ነጂውን ባለ 5-ደረጃ የአማራጭ ሰንሰለት በመጠቀም ይፈልጋል፦
1. **አብሮ የታሸገ `better-sqlite3`** (በ`package.json` ውስጥ ባለው `dependencies` በኩል)
— ፈጣኑ አማራጭ፣ ቤተኛ ባይነሪ ሲሆን፣ የግንባታ መሣሪያዎች ሲኖሩ `npm install` ይጭነዋል።
2. **በአሂድ ጊዜ የሚጫን `better-sqlite3`** (በ`~/.omniroute/runtime/` ውስጥ)
— ለመጀመሪያ ጊዜ ሲሠራ እንደ አስፈላጊነቱ **ወይም** በ`scripts/build/postinstall.mjs → scripts/postinstall.mjs` በኩል ይጫናል።
ከመጫኑ በፊት፣ የተበላሹ ወይም ለተሳሳተ መድረክ የተዘጋጁ ባይነሪዎችን
ለመከላከል የቤተኛ `.node` ማጂክ ባይቶችን (ELF / Mach-O / PE) ያረጋግጣል።
3. **`node:sqlite`** (Node ≥22.5 መደበኛ ቤተ-መጻሕፍት) — ቤተኛ ግንባታ አያስፈልገውም፤
ሁለቱም የbetter-sqlite3 መንገዶች ሲሳኩ ጥቅም ላይ ይውላል። የተወሰነ የባህሪያት ስብስብ አለው።
4. **`sql.js`** (WASM) — የመጨረሻው አማራጭ። በሁሉም ቦታ ይሠራል፣ ነገር ግን ቀርፋፋ ነው
እና ውሂብን በተመሳሳይ ጊዜ ከመጻፍ ይልቅ በጊዜ ክፍተት ይጽፋል።
## ይህ ውስብስብነት ለምን ያስፈልጋል?
- **Windows EBUSY**፦ የቀዳሚው ስሪት `better_sqlite3.node` በሚሠራ ሂደት ተቆልፎ ከሆነ፣
`npm install -g omniroute@latest` ሊሳካ ይችላል። በ`~/.omniroute/runtime/`
ውስጥ የሚደረገው የአሂድ ጊዜ ጭነት ዓለም አቀፉን የnpm መሸጎጫ ያልፋል።
- **የግንባታ መሣሪያዎች አለመኖር**፦ አንዳንድ አካባቢዎች (VS Build
Tools የሌለባቸው የድርጅት Windows ስርዓቶች፣ አነስተኛ Docker ምስሎች) `better-sqlite3`ን
ማጠናቀር አይችሉም። የአሂድ ጊዜ ጫኚው ቀድሞ የተገነባ ባይነሪን ከnpm መዝገብ ያገኛል፤
ይህ ቢሳካም የአማራጭ ነጂዎቹ OmniRoute መነሳቱን እንዲቀጥል ያረጋግጣሉ።
- **ከውጭ አውታረ መረብ የተለዩ ስርዓቶች**፦ የnpm መዝገብ የማይደረስ ከሆነ፣ `node:sqlite`
ወይም `sql.js` መሠረታዊ ተግባራዊነትን ያረጋግጣሉ።
## የማጂክ ባይት ማረጋገጫ
በአሂድ ጊዜ የተጫነ `.node` ፋይል ከመጫኑ በፊት፣ OmniRoute የመጀመሪያዎቹን 8
ባይቶች ያነባል እና ከሚታወቁ የመድረክ ማጂክ እሴቶች ጋር ያዛምዳቸዋል፦
| መድረክ | ባይቶች (ሄክስ) | መለያ |
| --------------------- | ------------- | ----------- |
| Linux | `7F 45 4C 46` | `elf` |
| macOS 64-ቢት BE | `FE ED FA CF` | `macho` |
| macOS 64-ቢት LE | `CF FA ED FE` | `macho-le` |
| macOS fat (universal) | `CA FE BA BE` | `macho-fat` |
| Windows | `4D 5A` (MZ) | `pe` |
የማይዛመድ ማጂክ → ፋይሉ ችላ ይባላል፣ የአማራጭ ሂደቱም ወደሚቀጥለው ደረጃ ይሄዳል።
## ንቁውን ነጂ ማረጋገጥ
```typescript
import { getDriverInfo } from "@/lib/db/core";
const info = getDriverInfo();
// { source: "bundled" | "runtime" | "runtime-installed-now" | "node-sqlite" | "sql-js",
// kind: "better-sqlite3" | "node-sqlite" | "sql-js" }
```
## በእጅ መቆጣጠር
```bash
# ለፈጣን CI ጭነቶች የpostinstall ቅድመ-ማሞቂያን ዝለል
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute
# የአሂድ ጊዜ better-sqlite3ን በግድ እንደገና ጫን
rm -rf ~/.omniroute/runtime
omniroute # በሚቀጥለው መነሻ ላይ እንደገና ይጫናል
# የትኛው ነጂ ንቁ እንደሆነ አረጋግጥ
omniroute config db-info # (የCLI ትእዛዙ ካለ)
```
## ማጣቀሻ
አተገባበር፦
- `bin/cli/runtime/magicBytes.mjs` — የባይነሪ ማጂክ ባይት ማረጋገጫ አጋዥ ተግባራት
- `bin/cli/runtime/sqliteRuntime.mjs` — ባለ 5-ደረጃ የአሂድ ጊዜ ፈላጊ + እንደ አስፈላጊነቱ የሚሠራ ጫኚ
- `bin/cli/runtime/index.mjs` — የመነሻ አቀናባሪ (`warmUpRuntimes()`)
- `scripts/postinstall.mjs` — ከnpm ጭነት በኋላ የሚሠራ መንጠቆ (ውድቀት የማያስከትል ቅድመ-ማሞቂያ)
- `src/lib/db/core.ts` — የ`ensureDbInitialized()` / `getDriverInfo()` ወደ ውጭ ማቅረቦች
## ባለአንድ-ጸሐፊ ቶፖሎጂ (HA አይደገፍም)
ከላይ ያለው የነጂ አማራጭ ሰንሰለት አሁንም በ**አንድ ሂደት** ውስጥ ይሠራል። በነባሪው SQLite
OmniRoute **አንድ ጸሐፊ** ብቻ አለው፦
- ሁለት የOmniRoute ቅጂዎችን ከአንድ `storage.sqlite` ፋይል ጋር አታገናኙ።
- የኮንቴይነር ዳግም መነሳት፣ Recreate ማሰማራት፣ OOM kill ወይም HEALTHCHECK ዳግም ማስጀመር
በሂደት ላይ ያሉ ሁሉንም የSSE ክፍለ-ጊዜዎች ያቋርጣል። በመደበኛው መንገድ የክፍለ-ጊዜ ቀስ በቀስ ማቋረጥ የለም።
- ቀርፋፋ `/healthz`ን እንደ ሞተ የሚቆጥር የአቀናባሪ ሕያውነት ፍተሻ ብቸኛውን
ቅጂ ያቋርጣል። TCP ሕያውነት + HTTP `/healthz` ዝግጁነትን ይምረጡ።
[Docker መመሪያ — ተገኝነት](../guides/DOCKER_GUIDE.md#availability-default-sqlite-is-single-replica)
እና [የKubernetes ፕሮብ ምክረ ሐሳቦች](./MONITORING_GUIDE.md#kubernetes-probe-recommendations)ን ይመልከቱ።

318
docs/i18n/am/docs/ops/TUNNELS_GUIDE.md Normal file
View File

@@ -0,0 +1,318 @@
# Tunnels Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/TUNNELS_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/TUNNELS_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/TUNNELS_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/TUNNELS_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/TUNNELS_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/TUNNELS_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/TUNNELS_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/TUNNELS_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/TUNNELS_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/TUNNELS_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/TUNNELS_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/TUNNELS_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/TUNNELS_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/TUNNELS_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/TUNNELS_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/TUNNELS_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/TUNNELS_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/TUNNELS_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/TUNNELS_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/TUNNELS_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/TUNNELS_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/TUNNELS_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/TUNNELS_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/TUNNELS_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/TUNNELS_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/TUNNELS_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/TUNNELS_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/TUNNELS_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/TUNNELS_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/TUNNELS_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/TUNNELS_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/TUNNELS_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/TUNNELS_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/TUNNELS_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/TUNNELS_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/TUNNELS_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/TUNNELS_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/TUNNELS_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/TUNNELS_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/TUNNELS_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/TUNNELS_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/TUNNELS_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/TUNNELS_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/TUNNELS_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/TUNNELS_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/TUNNELS_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/TUNNELS_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/TUNNELS_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/TUNNELS_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/TUNNELS_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/TUNNELS_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/TUNNELS_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/TUNNELS_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/TUNNELS_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/TUNNELS_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/TUNNELS_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/TUNNELS_GUIDE.md)
---
> **የእውነት ምንጭ:** `src/lib/{cloudflaredTunnel,ngrokTunnel,tailscaleTunnel}.ts`, `src/app/api/tunnels/`
> **መጨረሻ የተዘመነው:** 2026-06-28 — v3.8.40
OmniRoute በሦስት የቱነል ባክኤንዶች አማካይነት የአካባቢ አገልጋዩን (`http://localhost:20128`) ለሕዝባዊ
በይነመረብ ተደራሽ ማድረግ ይችላል። ይህ ለሚከተሉት ጠቃሚ ነው፦
- በይፋ ተደራሽ የሆነ የማዘዋወሪያ URL ለሚፈልጉ የደመና አቅራቢዎች (Antigravity, Gemini, Cursor)
የOAuth መልሶ ጥሪዎች።
- VM ሳያሰማሩ የአካባቢ ኢንስታንስዎን ከቡድን አባላትዎ ጋር ማጋራት።
- የሞባይል፣ የርቀት ወይም የኔትወርክ-ተሻጋሪ ሙከራ።
ሦስቱም ባክኤንዶች በሂደቱ ውስጥ ይተዳደራሉ — OmniRoute ከዳሽቦርዱ ወይም ከREST API መሠረታዊውን
ባይነሪ ወይም SDK ያስጀምራል/ያቆማል። የተገላቢጦሽ-ፕሮክሲ ወይም systemd ማዋቀር
አያስፈልግም።
## የባክኤንዶች አጭር መግለጫ
| ባክኤንድ | ቋሚነት | ወጪ | ማዋቀር |
| --------------------------- | ----------------------------------------- | ---------------- | ----------------------------------------- |
| **Cloudflare Quick Tunnel** | ጊዜያዊ (በእያንዳንዱ ዳግም ማስጀመር URL ይለወጣል) | ነፃ | ምንም — `cloudflared`ን በራስ-ሰር ይጭናል |
| **ngrok** | የሚከፈልበት ዕቅድ ወይም ቋሚ ዶሜይን እስከተዋቀረ ድረስ የተረጋጋ | ነፃ ደረጃ + የሚከፈልበት | የngrok መለያ + authtoken ያስፈልጋል |
| **Tailscale Funnel** | በእርስዎ tailnet ውስጥ በእያንዳንዱ ኖድ የተረጋጋ | ለግል አጠቃቀም ነፃ | የTailscale ጭነት + መግባት + Funnel ACL ያስፈልጋል |
አተገባበሮቹ በ`src/lib/cloudflaredTunnel.ts`፣
`src/lib/ngrokTunnel.ts` እና `src/lib/tailscaleTunnel.ts` ውስጥ ይገኛሉ። ሦስቱም `phase`፣ `running`፣ `publicUrl`፣ `apiUrl`፣
`targetUrl` እና `lastError` መስኮች ያሉት ተመሳሳይ ቅርጽ ያለው `status` ኦብጀክት ይመልሳሉ፤ ስለዚህ ዳሽቦርዱ በአንድ ወጥ መንገድ ሊያሳያቸው ይችላል።
## 1. Cloudflare Tunnel (Quick Tunnel + Named Tunnel)
`src/lib/cloudflaredTunnel.ts` `cloudflared`ን እንደ ልጅ ሂደት ያስኬዳል። የተሰየመ-ቱነል ውቅር መቅረቡ ወይም አለመቅረቡ በሚወስነው
ሁለት ሁነታዎችን ይደግፋል፦
- **ፈጣን ቱነል (ነባሪ)።** `cloudflared tunnel --url
http://localhost:<apiPort>`ን ያስኬዳል እና የተመደበውን `*.trycloudflare.com` URL
ከstdout ይተነትናል። URL-ዎቹ ጊዜያዊ ሲሆኑ በእያንዳንዱ ዳግም ማስጀመር ይለወጣሉ።
- **የተሰየመ ቱነል (በምርጫ)።** `CLOUDFLARED_CONFIG` በአካባቢው ወደሚተዳደር
የcloudflared `config.yml` ሲያመለክት፣ OmniRoute `cloudflared tunnel --no-autoupdate
--config <path> run`ን ያስኬዳል፤ ይህም **የተረጋጋ፣ የተሰየመ የአስተናጋጅ ስም** ይሰጥዎታል። ውቅሩ
የቱነሉን UUID፣ `credentials-file` እና `ingress` ማዘዋወር ያቀርባል፤ ስለዚህ
`--url` አይተላለፍም እና የZero Trust ዳሽቦርድ ቶከን አያስፈልግም። `run`
ማረጋገጫዎችን ከውቅሩ ፍጹም የ`credentials-file` ዱካ ያነባል — `cert.pem`
አያስፈልግም (ይህ ለቱነል የሕይወት ዑደት አስተዳደር ብቻ ጥቅም ላይ ይውላል)።
ቁልፍ ባህሪያት፦
- **በራስ-ሰር መጫን።** በመጀመሪያ አጠቃቀም፣ OmniRoute የቅርብ ጊዜውን `cloudflared`
ባይነሪ ከይፋዊው GitHub releases ያወርዳል (የሚተዳደረው ጭነት በ
`DATA_DIR/cloudflared/` ስር ይገኛል)። የወረደው ንብረት SHA256 ከመፈጸሙ በፊት ከrelease manifest ጋር ይረጋገጣል።
- **የሂደት ክትትል።** የcloudflared PID እና የተፈታው URL በ
`quick-tunnel-state.json` ውስጥ በቋሚነት ይቀመጣሉ፤ ይህም ዳሽቦርዱ ከዳግም ጭነቶች በኋላ ሁኔታውን እንዲቀጥል ያስችለዋል።
### የተሰየመ ቱነል ማዋቀር (የተረጋጋ የአስተናጋጅ ስም)
1. በcloudflared CLI በአካባቢው የሚተዳደር ቱነል ይፍጠሩ (አንድ ጊዜ ብቻ)፦
```bash
cloudflared tunnel login
cloudflared tunnel create omniroute
cloudflared tunnel route dns omniroute ai.example.com
```
2. የአስተናጋጅ ስምዎን ወደ OmniRoute የአካባቢ API ወደብ (ነባሪ 20128) የሚያዘዋውር
`~/.cloudflared/config.yml` ይጻፉ፦
```yaml
tunnel: <UUID-from-create>
credentials-file: /home/you/.cloudflared/<UUID>.json
ingress:
- hostname: ai.example.com
service: http://127.0.0.1:20128
- service: http_status:404
```
3. OmniRouteን ወደ ውቅሩ ያመልክቱ እና ቱነሉን (ዳግም) ያስጀምሩ፦
```bash
export CLOUDFLARED_CONFIG="/home/you/.cloudflared/config.yml"
# አማራጭ — OmniRoute የሚዘግበውን የአስተናጋጅ ስም ይተካል፤ አለበለዚያ ከውቅሩ
# የመጀመሪያ ingress ደንብ ይነበባል፦
# export CLOUDFLARED_HOSTNAME="ai.example.com"
```
ቱነሉን እንደ ፈጣን ቱነል በተመሳሳይ መንገድ ያንቁት (ከታች REST / ዳሽቦርድ / CLI)።
የተሰየመ ቱነል ለማውጣት የሚታሰስ ሕዝባዊ URL አያመነጭም፤ ስለዚህ ዝግጁነት የሚለየው
ከcloudflared የተመዘገበ የedge ግንኙነት ሲሆን፣ `publicUrl`/`apiUrl`
ከ`CLOUDFLARED_HOSTNAME` (ወይም ከውቅሩ የመጀመሪያ ingress የአስተናጋጅ ስም) ይዘገባሉ።
### በREST በኩል ማንቃት / ማሰናከል
endpoint-ው የተለያዩ `start`/`stop` ዱካዎችን ሳይሆን `{action: "enable" | "disable"}` body ይጠቀማል።
የአስተዳደር ማረጋገጫ (የአስተዳዳሪ ክፍለ ጊዜ ወይም የአስተዳዳሪ API ቁልፍ) ያስፈልጋል።
```bash
# አንቃ
curl -X POST http://localhost:20128/api/tunnels/cloudflared \
-H "Content-Type: application/json" \
-H "Cookie: auth_token=..." \
-d '{"action":"enable"}'
# ሁኔታ
curl http://localhost:20128/api/tunnels/cloudflared \
-H "Cookie: auth_token=..."
# አሰናክል
curl -X POST http://localhost:20128/api/tunnels/cloudflared \
-H "Content-Type: application/json" \
-H "Cookie: auth_token=..." \
-d '{"action":"disable"}'
```
ወይም በዳሽቦርዱ በኩል፦ **ቅንብሮች → ቱነሎች → Cloudflare**።
### አማራጭ env vars
| ተለዋዋጭ | ዓላማ |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `CLOUDFLARED_BIN` | የሁለትዮሽ ፋይሉን ዱካ ይተካል። ከተዋቀረ እና ትክክለኛ ከሆነ፣ OmniRoute ከማውረድ ይልቅ ይህንን ይጠቀማል። |
| `CLOUDFLARED_PROTOCOL` / `TUNNEL_TRANSPORT_PROTOCOL` | የማጓጓዣ ፕሮቶኮል (ነባሪው `http2`፤ `quic` እና `auto` እንዲሁም ይደገፋሉ)። |
| `CLOUDFLARED_CONFIG` | በአካባቢው የሚተዳደር የcloudflared `config.yml` ዱካ። ሲዋቀር፣ OmniRoute ፈጣን ቱነል ከማስኬድ ይልቅ **የተሰየመ/ቋሚ** ቱነል (`tunnel --config <path> run`) ያስኬዳል። |
| `CLOUDFLARED_HOSTNAME` | በተሰየመው ቱነል ሪፖርት የሚደረገውን ይፋዊ የአስተናጋጅ ስም ይተካል (ለምሳሌ `ai.example.com`)። ካልተዋቀረ፣ ከውቅሩ የመጀመሪያ `ingress` የአስተናጋጅ ስም ይነበባል። |
## 2. ngrok
`src/lib/ngrokTunnel.ts` **`@ngrok/ngrok` SDK**ን ይጠቀማል (በሂደቱ ውስጥ የሚሰራ፣ የCLI ንዑስ-ሂደት የሌለው)። ቀድሞ የተገነቡ ባይነሪዎች የሌሏቸው ፕላትፎርሞች መተግበሪያውን በሚነሳበት ጊዜ እንዳያበላሹ፣ የኔቲቭ ሞጁሉ ለመጀመሪያ ጊዜ ሲጀመር ዘግይቶ ይመጣል።
### ቅድመ ሁኔታዎች
1. በ<https://ngrok.com> ይመዝገቡ።
2. authtokenዎን ከngrok ዳሽቦርድ ይቅዱ።
3. ከሚከተሉት በአንዱ ያቅርቡት፦
- `.env`: `NGROK_AUTHTOKEN=<token>`፣ ወይም
- ዳሽቦርድ፦ **Settings → Tunnels → ngrok**፣ ወይም
- የREST ይዘት (ለአንድ ጊዜ)፦ `{"action":"enable","authToken":"<token>"}`።
አንዳቸውም ካልተዋቀሩ፣ ሁኔታው `phase: "needs_auth"`ን ይመልሳል።
### በREST በኩል ማንቃት / ማሰናከል
```bash
# ማንቃት (NGROK_AUTHTOKENን ከenv ይጠቀማል)
curl -X POST http://localhost:20128/api/tunnels/ngrok \
-H "Content-Type: application/json" \
-H "Cookie: auth_token=..." \
-d '{"action":"enable"}'
# ኢንላይን token በመጠቀም ማንቃት
curl -X POST http://localhost:20128/api/tunnels/ngrok \
-H "Content-Type: application/json" \
-H "Cookie: auth_token=..." \
-d '{"action":"enable","authToken":"2abc..."}'
# ሁኔታ
curl http://localhost:20128/api/tunnels/ngrok \
-H "Cookie: auth_token=..."
# ማሰናከል
curl -X POST http://localhost:20128/api/tunnels/ngrok \
-H "Content-Type: application/json" \
-H "Cookie: auth_token=..." \
-d '{"action":"disable"}'
```
ምላሹ የተመደበውን `publicUrl` ያካትታል (ለምሳሌ፣
`https://abcd-1234.ngrok-free.app`)። ብጁ ዶሜይኖች፣ ክልሎች እና የፖሊሲ ደንቦች
በngrok ዳሽቦርድ ውስጥ መዋቀር አለባቸው — OmniRoute ራሱ የአካባቢውን ዒላማ URL ወደSDKው ከማስተላለፍ ውጭ ሌላ ነገር አያደርግም።
## 3. Tailscale Funnel
`src/lib/tailscaleTunnel.ts` የአካባቢውን API ወደብ በ**Funnel** (ለserve የTailscale የወል በይነመረብ መውጫ) በኩል ተደራሽ ለማድረግ የስርዓቱን `tailscale` CLI ያቀናጃል። ሙሉውን የሕይወት ዑደት ይደግፋል፦ መጫን፣ መግባት፣ daemonን ማስጀመር፣ ማንቃት እና ማሰናከል።
ትግበራው `tailscale funnel --bg <port>`ን (የበስተጀርባ ሁነታ) ይጠራል። የወል URL ቅርጹ `https://<machine>.<tailnet>.ts.net/` ነው።
### ቅድመ ሁኔታዎች
1. Tailscaleን ይጫኑ (ወይም OmniRoute እንዲጭነው ይፍቀዱ — ከታች ያለውን `install` endpoint ይመልከቱ)።
2. ይግቡ (`tailscale login` ወይም በOmniRoute `login` endpoint በኩል)።
3. በTailscale የአስተዳዳሪ ኮንሶል ውስጥ Funnelን ለtailnetዎ ያንቁ፦
<https://login.tailscale.com/admin/settings/features>።
በLinux እና macOS፣ daemonው (`tailscaled`) ለመቆጣጠር `sudo`ን ይፈልጋል። የPOST endpointዎቹ፣ ጥሪው በሚቆይበት ጊዜ ወደOmniRoute MITM የይለፍ ቃል መሸጎጫ (`getCachedPassword` / `setCachedPassword`) የሚተላለፍ አማራጭ `sudoPassword` መስክ ይቀበላሉ። Windows በ`C:\Program Files\Tailscale\tailscale.exe` ያለውን ነባሪ የአገልግሎት ጭነት ይጠቀማል።
### የREST endpointዎች
መጫን፣ መግባት፣ daemon እና tunnel የተለያዩ ጉዳዮች በመሆናቸው፣ Tailscale ከሌሎቹ backendዎች የበለጠ ሰፊ በይነገጽ አለው።
| Endpoint | ዘዴ | ዓላማ |
| ------------------------------------- | ------ | ------------------------------------------------------- |
| `/api/tunnels/tailscale` | `GET` | የተዋሃደ የtunnel ሁኔታ (`phase`፣ `tunnelUrl`፣ `apiUrl`፣ ወዘተ) |
| `/api/tunnels/tailscale/check` | `GET` | ዝቅተኛ-ደረጃ ማረጋገጫ፦ ተጭኗል? ተገብቷል? daemon እየሰራ ነው? |
| `/api/tunnels/tailscale/install` | `POST` | Tailscaleን መጫን (በSSE የሚለቀቁ የሂደት ክስተቶች) — Linux/macOS |
| `/api/tunnels/tailscale/start-daemon` | `POST` | `tailscaled`ን በLinux/macOS ማስጀመር |
| `/api/tunnels/tailscale/login` | `POST` | የመግቢያ ሂደቱን መጀመር፤ በአሳሽ ውስጥ የሚከፈት `authUrl`ን ይመልሳል |
| `/api/tunnels/tailscale/enable` | `POST` | Funnelን ለAPI ወደብ ማስጀመር |
| `/api/tunnels/tailscale/disable` | `POST` | Funnelን ማቆም |
ሁሉም የTailscale endpointዎች የአስተዳደር ማረጋገጫ ይፈልጋሉ (`routeUtils.ts ::
requireTailscaleAuth`ን ይመልከቱ)።
የማንቃት ምሳሌ፦
```bash
curl -X POST http://localhost:20128/api/tunnels/tailscale/enable \
-H "Content-Type: application/json" \
-H "Cookie: auth_token=..." \
-d '{"sudoPassword":"<linux-pwd>","port":20128}'
```
Funnel በአስተዳዳሪ ኮንሶሉ ውስጥ ካልነቃ፣ ምላሹ `funnelNotEnabled: true`ን እና በአሳሽ ውስጥ የሚከፈት `enableUrl`ን ያካትታል።
### አማራጭ env ተለዋዋጮች
| ተለዋዋጭ | ዓላማ |
| --------------- | -------------------------- |
| `TAILSCALE_BIN` | የ`tailscale` ባይነሪ ዱካን መተካት |
## የመዳረሻ ነጥቦች ማጠቃለያ
| መዳረሻ ነጥብ | ዘዴ | የጥያቄ አካል | ማረጋገጫ |
| ------------------------------------- | ------ | ----------------------------------- | ------ |
| `/api/tunnels/cloudflared` | `GET` | — | አስተዳደር |
| `/api/tunnels/cloudflared` | `POST` | `{action: "enable" \| "disable"}` | አስተዳደር |
| `/api/tunnels/ngrok` | `GET` | — | አስተዳደር |
| `/api/tunnels/ngrok` | `POST` | `{action, authToken?}` | አስተዳደር |
| `/api/tunnels/tailscale` | `GET` | — | አስተዳደር |
| `/api/tunnels/tailscale/check` | `GET` | — | አስተዳደር |
| `/api/tunnels/tailscale/install` | `POST` | `{sudoPassword?}` (SSE) | አስተዳደር |
| `/api/tunnels/tailscale/start-daemon` | `POST` | `{sudoPassword?}` | አስተዳደር |
| `/api/tunnels/tailscale/login` | `POST` | `{hostname?}` | አስተዳደር |
| `/api/tunnels/tailscale/enable` | `POST` | `{sudoPassword?, hostname?, port?}` | አስተዳደር |
| `/api/tunnels/tailscale/disable` | `POST` | `{sudoPassword?}` | አስተዳደር |
ማዕከላዊ `/api/settings/tunnels` መዳረሻ ነጥብ የለም — እያንዳንዱ backend
ራሱን የቻለ ነው።
## የOAuth callback ግምትዎች
OmniRouteን በtunnel በኩል ሲያጋልጡ፣ dashboard እና የOAuth ፍሰቶች
የcallback URLዎችን በ`localhost` ሳይሆን በ**ይፋዊ** hostname መሠረት
መገንባት አለባቸው። ካልሆነ፣ የOAuth አቅራቢው ተጠቃሚውን አገልጋዮቹ
ሊደርሱበት ወደማይችሉት URL ይመልሰዋል፣ እና handshake አይሳካም።
የdashboard ማስተካከያዎች እና የቅንብሮች ማስቀመጫዎች የtunnel hostnameን
በ`NEXT_PUBLIC_BASE_URL` ውስጥ ማስቀመጥን አይጠይቁም። ማረጋገጫ ያለፈው
dashboard ከsession ጋር በተሳሰረ CSRF token ተመሳሳይ-origin unsafe
ጥያቄዎችን ይልካል፤ ስለዚህ ephemeral Cloudflare Quick Tunnel hostዎችም
ከገቡ በኋላ ለመደበኛ የUI አስተዳደር ጥቅም ላይ ሊውሉ ይችላሉ።
ይህን ያቀናብሩ፦
```bash
NEXT_PUBLIC_BASE_URL=https://<your-tunnel-host>
```
OAuthን ከማስጀመርዎ በፊት OmniRouteን እንደገና ያስጀምሩ። ለephemeral
Cloudflare Quick Tunnels URLው ከእያንዳንዱ ዳግም ማስጀመር በኋላ ይቀየራል፤
ስለዚህ በproduction ውስጥ OAuthን ለመጠቀም የተጠበቀ domain ያለውን ngrok
ወይም Tailscale Funnelን ይምረጡ።
## ጤና እና ክትትል
dashboard የtunnel ሁኔታን በ**ቅንብሮች → Tunnels** ሥር ያሳያል፦
- ንቁ backend(ዎች) እና የአሁኑ `phase` (`stopped`፣ `starting`፣ `running`፣
`needs_auth`፣ `error`)።
- የአሁኑ ይፋዊ URL እና ከእሱ የተወሰነው API URL (`<publicUrl>/v1`)።
- tunnelው የሚያስተላልፍበት የአካባቢ target URL።
- ካለ፣ የመጨረሻው የስህተት መልዕክት።
በፕሮግራም ለመከታተል የእያንዳንዱን backend `GET` መዳረሻ ነጥብ በየጊዜው
ይጠይቁ። ከአንድ በላይ backendን በአንድ ጊዜ ማስኬድ ይፈቀዳል፤ OmniRoute
እያንዳንዱን ለብቻው ይከታተላል።
## መላ ፍለጋ
### "cloudflared binary አልተገኘም"
OmniRoute በመጀመሪያ አጠቃቀም ጊዜ በራስ-ሰር ለመጫን ይሞክራል። መጫኑ
ከታገደ (የተገደበ network፣ የGitHub መዳረሻ ከሌለ)፣ `cloudflared`ን ከ
<https://github.com/cloudflare/cloudflared/releases> በእጅ ያውርዱ እና
`CLOUDFLARED_BIN=/path/to/cloudflared` ያቀናብሩ።
### "ngrok፦ authtoken ያስፈልጋል"
`phase: "needs_auth"` ምንም authtoken አልተገኘም ማለት ነው።
`NGROK_AUTHTOKEN`ን በ`.env` ውስጥ ያቀናብሩ፣ በdashboard በኩል ያዋቅሩት፣
ወይም `authToken`ን በenable POST body ውስጥ ያስተላልፉ።
### "tailscale፦ funnel አልነቃም"
የenable ምላሹ `funnelNotEnabled: true`ን ሲያካትት፣ Funnel ለtailnetዎ
ቦዝኗል። የተመለሰውን `enableUrl` (ወይም የadmin console feature ገጽ)
ይክፈቱ እና Funnelን ያብሩ።
### የTunnel URL ለውጦች OAuthን ያበላሻሉ
ngrokን ከተጠበቀ domain ጋር ወይም Tailscale Funnelን ይጠቀሙ (ሁለቱም
በእያንዳንዱ node የተረጋጉ ናቸው)። Cloudflare Quick Tunnels በንድፋቸው
ephemeral ስለሆኑ ረጅም ጊዜ ለሚቆዩ የOAuth callbackዎች አይመከሩም።
### በLinux/macOS ላይ ለTailscale ፈቃድ ተከልክሏል
`tailscaled` root ያስፈልገዋል። `sudoPassword`ን ለሚመለከተው POST መዳረሻ
ነጥብ ያቅርቡ፣ ወይም daemonን እርስዎ ያስኪዱ (`sudo systemctl start tailscaled`)።
## በተጨማሪ ይመልከቱ
- [PROXY_GUIDE.md](./PROXY_GUIDE.md) — ለወጪ ትራፊክ outbound proxy (1proxy, SOCKS5, HTTP)።
- [ENVIRONMENT.md](../reference/ENVIRONMENT.md) — `NEXT_PUBLIC_BASE_URL`ን ጨምሮ ሙሉ የenv vars ዝርዝር።
- [FLY_IO_DEPLOYMENT_GUIDE.md](./FLY_IO_DEPLOYMENT_GUIDE.md),
[DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md) — ለተረጋጋ የወል ማስተናገጃ ከtunneling ሌላ አማራጮች።
- ምንጭ፦ `src/lib/{cloudflaredTunnel,ngrokTunnel,tailscaleTunnel}.ts`,
`src/app/api/tunnels/`.

2
docs/i18n/am/docs/ops/VM_DEPLOYMENT_GUIDE.md
View File

@@ -4,7 +4,7 @@
---
🌐 **ቋንቋዎች:** 🇺🇸 [English](./VM_DEPLOYMENT_GUIDE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](../i18n/ar/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](../i18n/bg/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](../i18n/da/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](../i18n/es/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇪🇪 [Eesti](../i18n/et/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](../i18n/fr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](../i18n/he/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](../i18n/it/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](../i18n/ja/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](../i18n/ko/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇲🇹 [Malti](../i18n/mt/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](../i18n/no/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](../i18n/pl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](../i18n/ro/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](../i18n/ru/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇸 [Српски](../i18n/sr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](../i18n/th/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇰 [اردو](../i18n/ur/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/ops/VM_DEPLOYMENT_GUIDE.md)
🌐 **Languages:** 🇺🇸 [English](../../../../ops/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/VM_DEPLOYMENT_GUIDE.md)
በCloudflare በሚተዳደር ዶሜይን ላይ OmniRouteን በVM (VPS) ውስጥ ለመጫንና ለማዋቀር የተሟላ መመሪያ።

49
docs/i18n/am/docs/plans/11690-anysearch-provider-integration.md Normal file
View File

File diff suppressed because one or more lines are too long

13
docs/i18n/am/docs/plans/7778-hierarchical-admission.md Normal file
View File

@@ -0,0 +1,13 @@
# #7778 hierarchical admission cleanup plan (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../plans/7778-hierarchical-admission.md) · 🇸🇦 [ar](../../../ar/docs/plans/7778-hierarchical-admission.md) · 🇦🇿 [az](../../../az/docs/plans/7778-hierarchical-admission.md) · 🇧🇬 [bg](../../../bg/docs/plans/7778-hierarchical-admission.md) · 🇧🇩 [bn](../../../bn/docs/plans/7778-hierarchical-admission.md) · 🇨🇿 [cs](../../../cs/docs/plans/7778-hierarchical-admission.md) · 🇩🇰 [da](../../../da/docs/plans/7778-hierarchical-admission.md) · 🇩🇪 [de](../../../de/docs/plans/7778-hierarchical-admission.md) · 🇬🇷 [el](../../../el/docs/plans/7778-hierarchical-admission.md) · 🇪🇸 [es](../../../es/docs/plans/7778-hierarchical-admission.md) · 🇪🇪 [et](../../../et/docs/plans/7778-hierarchical-admission.md) · 🇮🇷 [fa](../../../fa/docs/plans/7778-hierarchical-admission.md) · 🇫🇮 [fi](../../../fi/docs/plans/7778-hierarchical-admission.md) · 🇫🇷 [fr](../../../fr/docs/plans/7778-hierarchical-admission.md) · 🇮🇪 [ga](../../../ga/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [gu](../../../gu/docs/plans/7778-hierarchical-admission.md) · 🇳🇬 [ha](../../../ha/docs/plans/7778-hierarchical-admission.md) · 🇮🇱 [he](../../../he/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [hi](../../../hi/docs/plans/7778-hierarchical-admission.md) · 🇭🇷 [hr](../../../hr/docs/plans/7778-hierarchical-admission.md) · 🇭🇺 [hu](../../../hu/docs/plans/7778-hierarchical-admission.md) · 🇦🇲 [hy](../../../hy/docs/plans/7778-hierarchical-admission.md) · 🇮🇩 [id](../../../id/docs/plans/7778-hierarchical-admission.md) · 🇳🇬 [ig](../../../ig/docs/plans/7778-hierarchical-admission.md) · 🇮🇹 [it](../../../it/docs/plans/7778-hierarchical-admission.md) · 🇯🇵 [ja](../../../ja/docs/plans/7778-hierarchical-admission.md) · 🇬🇪 [ka](../../../ka/docs/plans/7778-hierarchical-admission.md) · 🇰🇭 [km](../../../km/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [kn](../../../kn/docs/plans/7778-hierarchical-admission.md) · 🇰🇷 [ko](../../../ko/docs/plans/7778-hierarchical-admission.md) · 🇱🇹 [lt](../../../lt/docs/plans/7778-hierarchical-admission.md) · 🇱🇻 [lv](../../../lv/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [ml](../../../ml/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [mr](../../../mr/docs/plans/7778-hierarchical-admission.md) · 🇲🇾 [ms](../../../ms/docs/plans/7778-hierarchical-admission.md) · 🇲🇹 [mt](../../../mt/docs/plans/7778-hierarchical-admission.md) · 🇲🇲 [my](../../../my/docs/plans/7778-hierarchical-admission.md) · 🇳🇵 [ne](../../../ne/docs/plans/7778-hierarchical-admission.md) · 🇳🇱 [nl](../../../nl/docs/plans/7778-hierarchical-admission.md) · 🇳🇴 [no](../../../no/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [or](../../../or/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [pa](../../../pa/docs/plans/7778-hierarchical-admission.md) · 🇵🇭 [phi](../../../phi/docs/plans/7778-hierarchical-admission.md) · 🇵🇱 [pl](../../../pl/docs/plans/7778-hierarchical-admission.md) · 🇵🇹 [pt](../../../pt/docs/plans/7778-hierarchical-admission.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/plans/7778-hierarchical-admission.md) · 🇷🇴 [ro](../../../ro/docs/plans/7778-hierarchical-admission.md) · 🇷🇺 [ru](../../../ru/docs/plans/7778-hierarchical-admission.md) · 🇱🇰 [si](../../../si/docs/plans/7778-hierarchical-admission.md) · 🇸🇰 [sk](../../../sk/docs/plans/7778-hierarchical-admission.md) · 🇸🇮 [sl](../../../sl/docs/plans/7778-hierarchical-admission.md) · 🇷🇸 [sr](../../../sr/docs/plans/7778-hierarchical-admission.md) · 🇸🇪 [sv](../../../sv/docs/plans/7778-hierarchical-admission.md) · 🇰🇪 [sw](../../../sw/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [ta](../../../ta/docs/plans/7778-hierarchical-admission.md) · 🇮🇳 [te](../../../te/docs/plans/7778-hierarchical-admission.md) · 🇹🇭 [th](../../../th/docs/plans/7778-hierarchical-admission.md) · 🇹🇷 [tr](../../../tr/docs/plans/7778-hierarchical-admission.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/plans/7778-hierarchical-admission.md) · 🇵🇰 [ur](../../../ur/docs/plans/7778-hierarchical-admission.md) · 🇺🇿 [uz](../../../uz/docs/plans/7778-hierarchical-admission.md) · 🇻🇳 [vi](../../../vi/docs/plans/7778-hierarchical-admission.md) · 🇳🇬 [yo](../../../yo/docs/plans/7778-hierarchical-admission.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/plans/7778-hierarchical-admission.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/plans/7778-hierarchical-admission.md)
---
1. ነባሩን የነጠላ-ቁልፍ semaphore ውል እና አዲሱን አቶሚክ የባለብዙ-ቁልፍ ውል በተለዩ ሙከራዎች ያረጋግጡ፦ ከፊል reservations እንዳይኖሩ፣ FIFO queueing፣ abort፣ timeout፣ queue-full፣ idempotent release፣ stats እና cleanup።
2. ነባሩን የመለያ semaphore በቦታው ላይ አጠቃላይ ያድርጉት። `acquire()`ን በ`acquireMany()` ዙሪያ እንደ compatibility wrapper ያቆዩት፤ ሁለተኛ scheduler ወይም dependency አይጨምሩ።
3. በ`chatCore` ውስጥ ያለውን የመለያ-ብቻ acquisition፣ ከ`withRateLimit` በፊት ወዲያውኑ በሚከናወን አንድ ድምር global/provider/account acquisition ይተኩት። account rotation ግንኙነቱን በቀየረ ቁጥር ሙሉውን ስብስብ እንደገና ያግኙ፣ እና releaseን የstreaming ሂደቱ እስኪጠናቀቅ ድረስ ያቆዩት።
4. ነባሩን የresilience settings pipeline (types፣ defaults፣ normalization፣ schema፣ API response፣ UI እና translations) በglobal እና provider caps ያስፋፉ። እውነተኛው scope ግልጽ እንዲሆን የቀድሞውን Bottleneck concurrency control እንደ connection/quota-scope concurrency እንደገና ይሰይሙት።
5. የተወሰኑ ሙከራዎችን፣ lint፣ typecheck፣ static checks እና ሙሉውን test suite ያስኪዱ፤ የባህሪ ለውጡን በchangelog ውስጥ ይመዝግቡ።
ሆን ተብሎ የተጠበቀ ባህሪ፦ ዜሮ/null concurrency gateን ያልፋል፣ account-only callers `acquire()`ን መጠቀማቸውን ይቀጥላሉ፣ blocked-account controls የkey format እና APIያቸውን ይዘው ይቆያሉ፣ እና የprovider rate-limit queue ባህሪ ሳይለወጥ ይቆያል።

180
docs/i18n/am/docs/providers/AGENTROUTER.md Normal file
View File

@@ -0,0 +1,180 @@
# AgentRouter Setup Guide (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../providers/AGENTROUTER.md) · 🇸🇦 [ar](../../../ar/docs/providers/AGENTROUTER.md) · 🇦🇿 [az](../../../az/docs/providers/AGENTROUTER.md) · 🇧🇬 [bg](../../../bg/docs/providers/AGENTROUTER.md) · 🇧🇩 [bn](../../../bn/docs/providers/AGENTROUTER.md) · 🇨🇿 [cs](../../../cs/docs/providers/AGENTROUTER.md) · 🇩🇰 [da](../../../da/docs/providers/AGENTROUTER.md) · 🇩🇪 [de](../../../de/docs/providers/AGENTROUTER.md) · 🇬🇷 [el](../../../el/docs/providers/AGENTROUTER.md) · 🇪🇸 [es](../../../es/docs/providers/AGENTROUTER.md) · 🇪🇪 [et](../../../et/docs/providers/AGENTROUTER.md) · 🇮🇷 [fa](../../../fa/docs/providers/AGENTROUTER.md) · 🇫🇮 [fi](../../../fi/docs/providers/AGENTROUTER.md) · 🇫🇷 [fr](../../../fr/docs/providers/AGENTROUTER.md) · 🇮🇪 [ga](../../../ga/docs/providers/AGENTROUTER.md) · 🇮🇳 [gu](../../../gu/docs/providers/AGENTROUTER.md) · 🇳🇬 [ha](../../../ha/docs/providers/AGENTROUTER.md) · 🇮🇱 [he](../../../he/docs/providers/AGENTROUTER.md) · 🇮🇳 [hi](../../../hi/docs/providers/AGENTROUTER.md) · 🇭🇷 [hr](../../../hr/docs/providers/AGENTROUTER.md) · 🇭🇺 [hu](../../../hu/docs/providers/AGENTROUTER.md) · 🇦🇲 [hy](../../../hy/docs/providers/AGENTROUTER.md) · 🇮🇩 [id](../../../id/docs/providers/AGENTROUTER.md) · 🇳🇬 [ig](../../../ig/docs/providers/AGENTROUTER.md) · 🇮🇹 [it](../../../it/docs/providers/AGENTROUTER.md) · 🇯🇵 [ja](../../../ja/docs/providers/AGENTROUTER.md) · 🇬🇪 [ka](../../../ka/docs/providers/AGENTROUTER.md) · 🇰🇭 [km](../../../km/docs/providers/AGENTROUTER.md) · 🇮🇳 [kn](../../../kn/docs/providers/AGENTROUTER.md) · 🇰🇷 [ko](../../../ko/docs/providers/AGENTROUTER.md) · 🇱🇹 [lt](../../../lt/docs/providers/AGENTROUTER.md) · 🇱🇻 [lv](../../../lv/docs/providers/AGENTROUTER.md) · 🇮🇳 [ml](../../../ml/docs/providers/AGENTROUTER.md) · 🇮🇳 [mr](../../../mr/docs/providers/AGENTROUTER.md) · 🇲🇾 [ms](../../../ms/docs/providers/AGENTROUTER.md) · 🇲🇹 [mt](../../../mt/docs/providers/AGENTROUTER.md) · 🇲🇲 [my](../../../my/docs/providers/AGENTROUTER.md) · 🇳🇵 [ne](../../../ne/docs/providers/AGENTROUTER.md) · 🇳🇱 [nl](../../../nl/docs/providers/AGENTROUTER.md) · 🇳🇴 [no](../../../no/docs/providers/AGENTROUTER.md) · 🇮🇳 [or](../../../or/docs/providers/AGENTROUTER.md) · 🇮🇳 [pa](../../../pa/docs/providers/AGENTROUTER.md) · 🇵🇭 [phi](../../../phi/docs/providers/AGENTROUTER.md) · 🇵🇱 [pl](../../../pl/docs/providers/AGENTROUTER.md) · 🇵🇹 [pt](../../../pt/docs/providers/AGENTROUTER.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/providers/AGENTROUTER.md) · 🇷🇴 [ro](../../../ro/docs/providers/AGENTROUTER.md) · 🇷🇺 [ru](../../../ru/docs/providers/AGENTROUTER.md) · 🇱🇰 [si](../../../si/docs/providers/AGENTROUTER.md) · 🇸🇰 [sk](../../../sk/docs/providers/AGENTROUTER.md) · 🇸🇮 [sl](../../../sl/docs/providers/AGENTROUTER.md) · 🇷🇸 [sr](../../../sr/docs/providers/AGENTROUTER.md) · 🇸🇪 [sv](../../../sv/docs/providers/AGENTROUTER.md) · 🇰🇪 [sw](../../../sw/docs/providers/AGENTROUTER.md) · 🇮🇳 [ta](../../../ta/docs/providers/AGENTROUTER.md) · 🇮🇳 [te](../../../te/docs/providers/AGENTROUTER.md) · 🇹🇭 [th](../../../th/docs/providers/AGENTROUTER.md) · 🇹🇷 [tr](../../../tr/docs/providers/AGENTROUTER.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/providers/AGENTROUTER.md) · 🇵🇰 [ur](../../../ur/docs/providers/AGENTROUTER.md) · 🇺🇿 [uz](../../../uz/docs/providers/AGENTROUTER.md) · 🇻🇳 [vi](../../../vi/docs/providers/AGENTROUTER.md) · 🇳🇬 [yo](../../../yo/docs/providers/AGENTROUTER.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/providers/AGENTROUTER.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/providers/AGENTROUTER.md)
---
[AgentRouter](https://agentrouter.org) ከAnthropic ጋር ተኳሃኝ የሆነ፣ Claude እና ሌሎች ሞዴሎችን ብዙውን ጊዜ ከቀጥታው Anthropic API ባነሰ ዋጋ እንደገና የሚሸጥ የማስተላለፊያ አገልግሎት ነው።
ለኦፊሴላዊው Claude Code ደንበኛ ያለ ለውጥ እንደሚተካ `ANTHROPIC_BASE_URL` ሆኖ የተነደፈ በመሆኑ፣ ከClaude Code የግንኙነት ቅርጽ ጋር የሚዛመድ ትራፊክን ብቻ ይቀበላል (የተወሰነ
User-Agent፣ `anthropic-beta` ጠቋሚዎች፣ Stainless SDK ራስጌዎች፣ ወዘተ)።
## ፈጣን መጀመሪያ — ቤተኛውን `agentrouter` አቅራቢ ይጠቀሙ (የሚመከር)
ለአብዛኛዎቹ ተጠቃሚዎች **ምንም ልዩ ቅንብር አያስፈልግም**። OmniRoute ሙሉው የClaude Code የግንኙነት ቅርጽ ቀድሞውኑ የተካተተበትን አብሮገነብ
`agentrouter` አቅራቢ ይዞ ይመጣል (`open-sse/config/providerRegistry.ts` → `agentrouter` ይመልከቱ)። እሱን ለመጠቀም፦
1. **ዳሽቦርድ → አቅራቢዎች → አቅራቢ አክል**ን ይክፈቱ።
2. ከዝርዝሩ **AgentRouter**ን ይምረጡ።
3. የ`sk-...` API ቁልፍዎን ይለጥፉና ያስቀምጡ።
ይህን ብቻ ነው — ምንም የአካባቢ ተለዋዋጮች ወይም ብጁ የአቅራቢ ዓይነት አያስፈልጉም። አብሮገነብ ሞዴሎች
`claude-opus-4-6`፣ `claude-haiku-4-5-20251001`፣ `glm-5.1` እና
`deepseek-v3.2`ን ያካትታሉ።
የቀረው የዚህ መመሪያ ክፍል **የላቀውን አካሄድ** ይሸፍናል፦ የ
`anthropic-compatible-cc-*` አቅራቢ ዓይነትን መጠቀም። በግንኙነት ቅርጹ ላይ የበለጠ ቁጥጥር ሲያስፈልግዎ ይህን ይጠቀሙ — ለምሳሌ፣ ገና በቤተኛው የአቅራቢዎች መዝገብ ውስጥ ካልተካተቱ ሌሎች ከAgentRouter ጋር ተመሳሳይ የሆኑ የማስተላለፊያ አገልግሎቶች ጋር ሲገናኙ፣ ወይም መሠረታዊ URLን፣ የውይይት ዱካውን ወይም የራስጌዎችን ስብስብ ሲሽሩ።
---
## የላቀ፦ በClaude Code ተኳሃኝ የአቅራቢ ዓይነት መገናኘት
OmniRoute በትክክለኛው የግንኙነት ቅርጽ Anthropic Messages APIን በሚጠቀመው **Claude Code
ተኳሃኝ** የአቅራቢ ዓይነት (`anthropic-compatible-cc-*`) በኩል AgentRouterን (እና ተመሳሳይ የማስተላለፊያ አገልግሎቶችን) ይደግፋል። ወደ `https://agentrouter.org` የሚያመለክት አጠቃላይ
`openai-compatible-chat` አቅራቢ **አይሠራም** — የላይኛው WAF እንደClaude
Code የማይመስሉ ጥያቄዎችን ውድቅ ያደርጋል።
---
## ቅድመ ሁኔታዎች
- የAgentRouter መለያ እና API ቁልፍ። አዲስ የሚመዘገቡ ተጠቃሚዎች በፕሮጀክቱ [README](../README.md) ውስጥ ባለው የአጋርነት አገናኝ ነፃ ክሬዲት ያገኛሉ።
- OmniRoute የ`ENABLE_CC_COMPATIBLE_PROVIDER` ባህሪ ጠቋሚ ነቅቶለት እየሠራ መሆን
(ከታች ይመልከቱ)።
## 1. ከCC ጋር ተኳሃኝ የሆነውን የአቅራቢ ዓይነት ያንቁ
የClaude Code ተኳሃኝ የአቅራቢ ዓይነት ከኦፊሴላዊው Claude Code ደንበኛ ጋር በእጅጉ የሚመሳሰል ትራፊክ ስለሚልክ፣ ከባህሪ ጠቋሚ ጀርባ ተደብቋል። OmniRouteን ከማስጀመርዎ በፊት የአካባቢ ተለዋዋጭ በማዋቀር ያንቁት፦
```bash
ENABLE_CC_COMPATIBLE_PROVIDER=true
```
የDocker ምሳሌ፦
```bash
docker run -d --name omniroute \
--restart unless-stopped \
-p 20128:20128 \
-v omniroute-data:/app/data \
-e ENABLE_CC_COMPATIBLE_PROVIDER=true \
diegosouzapw/omniroute:latest
```
ዳግም ካስጀመሩ በኋላ፣ ዳሽቦርዱ ከነባሮቹ OpenAI-compatible እና Anthropic-compatible ፍሰቶች በተጨማሪ **Claude Code Compatible አክል** የሚል አማራጭ ያሳያል።
## 2. አቅራቢውን በዳሽቦርዱ ውስጥ ይፍጠሩ
1. **ዳሽቦርድ → አቅራቢዎች → አቅራቢ አክል**ን ይክፈቱ።
2. **Claude Code Compatible አክል**ን ይምረጡ (ከላይ ያለው ጠቋሚ ሲዋቀር ብቻ ይታያል)።
3. መስኮቹን ይሙሉ፦
| መስክ | እሴት |
| --------- | --------------------------------------------------- |
| ስም | `AgentRouter` (ወይም ማንኛውም መለያ) |
| ቅድመ ቅጥያ | `agentrouter` (በመዝገቦችና በዳሽቦርዱ ውስጥ የሚታይ ቀላል ተለዋጭ ስም) |
| መሠረታዊ URL | `https://agentrouter.org` |
| የውይይት ዱካ | `/v1/messages?beta=true` (ነባሪ — እንዳለ ይተዉት) |
> መደበኛው የሞዴል መለያ አሁንም ሙሉውን የአቅራቢ ኖድ መታወቂያ
> (`anthropic-compatible-cc-{uuid}/{model}`) ይጠቀማል። **ቅድመ ቅጥያ**ው ይበልጥ ለወዳጃዊ የመዝገብ ውጤት በ`src/lib/usage/callLogs.ts` የሚፈታ የማሳያ
> ተለዋጭ ስም ብቻ ነው።
4. (አማራጭ) ከማስቀመጥዎ በፊት ግንኙነቱን ለማረጋገጥ API ቁልፍዎን በ**Validate** መስክ ውስጥ ይለጥፉና **Check**ን ጠቅ ያድርጉ።
5. **Add**ን ጠቅ ያድርጉ።
ከተፈጠረ በኋላ፣ አቅራቢውን ይክፈቱና በAgentRouter API ቁልፍዎ (`sk-...`) **Connection** ያክሉ። የግንኙነቱ `test_status` ወደ `active` መቀየር አለበት።
## 3. በጥምር በኩል ወይም በቀጥታ ይጠቀሙበት
የአቅራቢዎን ቅድመ ቅጥያ እንደ namespace በመጠቀም ሞዴሉን ይጥቀሱ፦
```bash
curl -X POST http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "agentrouter/claude-opus-4-6",
"messages": [{"role": "user", "content": "hello"}],
"max_tokens": 100
}'
```
መደበኛው የሞዴል ID `anthropic-compatible-cc-{uuid}/claude-opus-4-6` እንዲሁም ይሠራል፤
በዳታቤዙና በጥምር ውቅሩ ውስጥም የሚታየው ይህ ነው።
ወይም እንደማንኛውም ሌላ አቅራቢ ለማስተላለፍ፣ ለመጠባበቂያ እና ለኮታ አስተዳደር
ወደ ጥምር ያክሉት።
---
## የwire image ዝርዝሮች
ለማጣቀሻ፣ cc-compatible bridge በእያንዳንዱ ወደ upstream በሚላክ ጥያቄ ላይ
የሚከተሉትን ይልካል (`open-sse/services/claudeCodeCompatible.ts`ን ይመልከቱ)፦
| ራስጌ | እሴት |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer <api-key>` |
| `User-Agent` | `claude-cli/2.1.258 (external, sdk-cli)` |
| `anthropic-version` | `2023-06-01` |
| `anthropic-beta` | `claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24` |
| በየግንኙነቱ የredact-thinking beta መቀያየሪያ | በተለይ redacted thinking streams ለሚፈልጉ upstreams `redact-thinking-2026-02-12`ን ያክላል |
| በየግንኙነቱ የsummarized thinking መቀያየሪያ | አስቀድሞ display mode ላልተወሰነላቸው CC Compatible thinking requests `display: "summarized"`ን ያክላል |
| `anthropic-dangerous-direct-browser-access` | `true` |
| `x-app` | `cli` |
| `X-Stainless-*` | የተለያዩ የStainless SDK ራስጌዎች (ቋንቋ፣ የpackage ስሪት፣ OS፣ አርክቴክቸር፣ ወዘተ) |
ጥያቄዎች የupstream WAF / client whitelistን እንዲያልፉ የሚያስችላቸው ይህ ነው።
---
## መላ ፍለጋ
**`{"error":{"message":"unauthorized client detected, ..."}}`** — ጥያቄዎ ከClaude Code wire image ጋር
አልተዛመደም። ይህ የሚከሰተው አቅራቢው በ`anthropic-compatible-cc` ፋንታ
እንደ `openai-compatible-chat` ሲዋቀር፣ ወይም በማስጀመሪያ ጊዜ
`ENABLE_CC_COMPATIBLE_PROVIDER=true` ጠቋሚው ሳይዘጋጅ ሲቀር ነው።
**`{"error":{"message":"无效的令牌","type":"new_api_error"}}` (HTTP 401)** —
«ልክ ያልሆነ token»። wire imageው ትክክል ነው፣ ነገር ግን API keyው ውድቅ ተደርጓል። በ
AgentRouter dashboard ውስጥ አዲስ key ይፍጠሩ እና ግንኙነቱን ያዘምኑ።
**`{"error":{"code":"content-blocked","type":"agent_router_api_error"}}`
(HTTP 400)** — የAgentRouter moderation hook የጥያቄውን ይዘት ውድቅ አድርጎታል፣ ወይም
የkeyው ዕቅድ የተጠየቀውን ሞዴል አይፈቅድም። የተለየ prompt ወይም ሞዴል ይሞክሩ፤
ጉዳት የሌለው prompt በተደጋጋሚ ከታገደ የAgentRouter ድጋፍን ያነጋግሩ።
**`[400]: content-blocked` በተወሰኑ ሞዴሎች ላይ ብቻ** — አብዛኞቹ የAgentRouter ዕቅዶች
የተወሰኑ ሞዴሎችን ብቻ ይፈቅዳሉ (ለምሳሌ `claude-opus-4-6`)። ሌሎች የሞዴል IDዎች
keyው ትክክለኛ ቢሆንም `unauthorized_client_error`ን ይመልሳሉ። ዕቅድዎ የትኞቹን ሞዴሎች
እንደሚሸፍን በAgentRouter dashboard ውስጥ ያረጋግጡ።
**`Invalid JSON response from provider (reset after Ns)` ከomniroute logs** —
upstream JSON ያልሆነ body መልሷል (በተለምዶ ከWAF የመጣ HTML error page)።
ይህ ብዙውን ጊዜ ጥያቄው የAgentRouter backendን ፈጽሞ እንዳልደረሰ ያመለክታል —
የአቅራቢው ID በ`anthropic-compatible-cc-` መጀመሩን እንደገና ያረጋግጡ (ከኋላ ያለውን ሰረዝ
ያስተውሉ — በ`open-sse/services/claudeCodeCompatible.ts` ውስጥ
`CLAUDE_CODE_COMPATIBLE_PREFIX`ን ይመልከቱ)፣ እንዲሁም feature flagው መንቃቱን ያረጋግጡ።
**የAgentRouter አቅራቢ አስቀድሞ ቢኖርም `unauthorized client detected` / HTML error page** —
ምናልባት **ከአንድ በላይ** የAgentRouter አቅራቢ አለዎት እና ጥያቄዎ የተሳሳተውን እያገኘ ነው።
ቀሪ በእጅ የተሠራ `anthropic-compatible-*` (`cc` ያልሆነ) ወይም
`openai-compatible-chat-*` አቅራቢ በ`agentrouter` ቅድመ ቅጥያ ከተፈጠረ፣
የ`agentrouter/<model>` ሞዴል IDዎችን ሊቆጣጠር ይችላል (ጥምሮችም በnode ID ሊጠቅሱት ይችላሉ)፤
ስለዚህ ትራፊኩ ትክክለኛውን wire image አካትቶ ወደሚመጣው አብሮገነብ
`agentrouter` አቅራቢ ፋንታ ወደዚያ አቅራቢ ይመራል — ይህም አጠቃላይ User-Agent
ይልክና ውድቅ ይደረጋል። ሞዴሉ በእርግጥ ወዴት እንደሚፈታ በomniroute logs ውስጥ ያረጋግጡ
(`ROUTING` tag `agentrouter/<model> → <providerId>/<model>`ን ያሳያል)፤ `<providerId>`
`agentrouter` ካልሆነ፣ በnative provider ላይ ያዋህዱ፦ ጥምሮችን ወደ
`agentrouter/<model>` (providerId `agentrouter`) ያመልክቱ እና የተባዙ compatible providersን
ይሰርዙ። native provider ምንም የwire-image ውቅር ወይም
`customUserAgent` አያስፈልገውም።
---
## በተጨማሪ ይመልከቱ
- [`docs/providers/CLAUDE_WEB.md`](./CLAUDE_WEB.md) — የClaude Web አቅራቢ ውህደት ማስታወሻዎች
- [`docs/reference/FREE_TIERS.md`](../reference/FREE_TIERS.md) — የነፃ ደረጃ አቅራቢዎች
ማውጫ
- [`open-sse/services/claudeCodeCompatible.ts`](../../open-sse/services/claudeCodeCompatible.ts)
— የምስል በሽቦ ላይ አተገባበር

Some files were not shown because too many files have changed in this diff Show More