OmniRoute/docs/i18n/az/docs/frameworks/PLUGIN_SDK.md

OmniRoute Plugin SDK (Azərbaycan dili)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Sürətli başlanğıc

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 arayışı

definePlugin(def: PluginDefinition): Plugin

Standart dəyərlərlə Plugin obyekti yaradan fabrik funksiyası.

Parametrlər:

• name (string, tələb olunur) — kebab-case formatında plagin adı
• priority (number, istəyə bağlı, standart: 100) — Daha aşağı dəyərə malik olan əvvəl icra olunur
• enabled (boolean, istəyə bağlı, standart: true) — Aktiv vəziyyətdə başlasın?
• onRequest (function, istəyə bağlı) — Söhbət emalçısından əvvəl icra olunur
• onResponse (function, istəyə bağlı) — Söhbət emalçısından sonra icra olunur
• onError (function, istəyə bağlı) — Emalçı xətası zamanı icra olunur

blockRequest(response?): BlockingHookResult

Sorğunu bloklayın və istəyə bağlı olaraq fərdi cavab qaytarın.

onRequest: (ctx) => {
  if (!ctx.headers["authorization"]) {
    return blockRequest({ error: "Unauthorized", status: 401 });
  }
};

modifyBody(body): PluginResult

Sorğu provayderə çatmazdan əvvəl onun gövdəsini dəyişdirin.

onRequest: (ctx) => {
  return modifyBody({ ...ctx.body, temperature: 0.7 });
};

addMetadata(metadata): PluginResult

Sorğu kontekstinə metadata əlavə edin.

onRequest: (ctx) => {
  return addMetadata({ source: "my-plugin", version: "1.0.0" });
};

Plagin konteksti (PluginContext)

Sahə	Tip	Təsvir
requestId	string	Unikal sorğu identifikatoru
model	string	Tələb olunan modelin adı
provider	string	Hədəf provayder ID-si
body	Record<string, unknown>	Sorğu gövdəsi
headers	Record<string, string>	Sorğu başlıqları
metadata	Record<string, unknown>	Dəyişdirilə bilən metadata
timestamp	number	Sorğunun zaman damğası

Manifest (plugin.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 prioriteti

Hook-lar prioritetlə konfiqurasiya edilə bilər (daha aşağı = əvvəl icra olunur):

{
  "hooks": {
    "onRequest": { "enabled": true, "priority": 10 },
    "onResponse": { "enabled": true, "priority": 100 }
  }
}

Yaxud sadə boolean dəyərləri kimi (standart prioritet 100):

{
  "hooks": {
    "onRequest": true,
    "onResponse": true
  }
}

İcazə Sistemi

Plaginlər təcrid olunmuş VM kontekstində işləyir. Xarici resurslara giriş üçün açıq icazələr tələb olunur:

İcazə	Təqdim etdiyi imkanlar
network	fetch, AbortController, Headers, Request, Response
file-read	fs.readFile, fs.readdir, fs.stat
file-write	fs.writeFile, fs.mkdir, fs.rm
env	Yalnız oxuma üçün process.env proksisi
exec	child_process.exec, child_process.execSync

İcazə olmadıqda müvafiq qlobal obyektlər sadəcə olaraq təcrid olunmuş mühitdə əlçatan olmur.

Konfiqurasiya Sxemi

Konfiqurasiya edilə bilən parametrləri configSchema daxilində müəyyənləşdirin:

{
  "configSchema": {
    "apiKey": { "type": "string", "description": "Xarici API açarı" },
    "maxRetries": { "type": "number", "min": 1, "max": 10, "default": 3 },
    "debug": { "type": "boolean", "default": false },
    "mode": { "type": "string", "enum": ["fast", "slow"], "default": "fast" }
  }
}

Sahə növləri: string, number, boolean, select

Sahə seçimləri: default, min, max, enum, description

Konfiqurasiya dəyərləri verilənlər bazasında saxlanılır və idarəetmə panelinin konfiqurasiya səhifəsi vasitəsilə əlçatandır.

Daxili Hadisələr

Hadisə	Nə zaman	Faydalı yük
onRequest	Çat emalçısından əvvəl	Sorğu konteksti
onResponse	Çat emalçısından sonra	Cavab məlumatları
onError	Emalçı xətası zamanı	Xəta obyekti
onModelSelect	Marşrutlaşdırma üçün model seçildikdə	Model məlumatları
onComboResolve	Kombinə edilmiş marşrut həll edildikdə	Kombinasiya hədəfləri
onRateLimit	Tezlik limitinə çatdıqda	Limit məlumatları
onQuotaExhaust	Kvota tükəndikdə	Kvota məlumatları
onProviderError	Provayder xəta qaytardıqda	Xəta təfərrüatları
onStreamStart	SSE axını başladıqda	Axın məlumatları
onStreamEnd	SSE axını bitdikdə	Axın statistikası
onInstall	Plagin quraşdırıldıqda	{ name, version, manifest }
onActivate	Plagin aktivləşdirildikdə	{ name, version, manifest }
onDeactivate	Plagin deaktivləşdirildikdə	{ name, version, manifest }
onUninstall	Plagin silindikdə (fayllar silinməzdən əvvəl)	{ name, version, manifest }

Nümunələr

Sorğu Jurnalı

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}`);
  },
});

Tezlik Məhdudlaşdırıcısı

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 dəqiqə
    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: "Tezlik limiti aşılıb", status: 429 });
    }
  },
});

Cavab Transformatoru

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;
  },
});