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

OmniRoute Plugin SDK (Filipino)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 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 · 🇵🇱 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

---

Mabilisang Pagsisimula

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

Sanggunian ng API

definePlugin(def: PluginDefinition): Plugin

Factory function na gumagawa ng Plugin object na may mga default na halaga.

Mga Parameter:

• name (string, kinakailangan) — Pangalan ng plugin sa kebab-case
• priority (number, opsyonal, default: 100) — Nauunang tumakbo ang mas mababang halaga
• enabled (boolean, opsyonal, default: true) — Magsisimula bang naka-enable?
• onRequest (function, opsyonal) — Tumatakbo bago ang chat handler
• onResponse (function, opsyonal) — Tumatakbo pagkatapos ng chat handler
• onError (function, opsyonal) — Tumatakbo kapag may error ang handler

blockRequest(response?): BlockingHookResult

I-block ang request at opsyonal na magbalik ng custom na response.

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

modifyBody(body): PluginResult

Baguhin ang request body bago ito makarating sa provider.

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

addMetadata(metadata): PluginResult

Maglakip ng metadata sa request context.

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

Context ng Plugin (PluginContext)

Field	Uri	Paglalarawan
requestId	string	Natatanging identifier ng request
model	string	Pangalan ng hiniling na model
provider	string	ID ng target na provider
body	Record<string, unknown>	Body ng request
headers	Record<string, string>	Mga header ng request
metadata	Record<string, unknown>	Nababagong metadata
timestamp	number	Timestamp ng request

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" }
  }
}

Priyoridad ng Hook

Maaaring i-configure ang mga hook gamit ang priority (mas mababa = nauunang tumakbo):

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

O bilang mga simpleng boolean (default na priority na 100):

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

Sistema ng Pahintulot

Tumatakbo ang mga plugin sa isang naka-sandbox na konteksto ng VM. Nangangailangan ng tahasang mga pahintulot ang pag-access sa mga panlabas na resource:

Pahintulot	Ipinagkakaloob
network	fetch, AbortController, Headers, Request, Response
file-read	fs.readFile, fs.readdir, fs.stat
file-write	fs.writeFile, fs.mkdir, fs.rm
env	Read-only na process.env proxy
exec	child_process.exec, child_process.execSync

Kung walang pahintulot, hindi magagamit sa sandbox ang kaukulang mga global.

Schema ng Config

Tukuyin ang mga nako-configure na setting sa configSchema:

{
  "configSchema": {
    "apiKey": { "type": "string", "description": "External na API key" },
    "maxRetries": { "type": "number", "min": 1, "max": 10, "default": 3 },
    "debug": { "type": "boolean", "default": false },
    "mode": { "type": "string", "enum": ["fast", "slow"], "default": "fast" }
  }
}

Mga uri ng field: string, number, boolean, select

Mga opsyon ng field: default, min, max, enum, description

Iniimbak sa database ang mga value ng config at maa-access ang mga ito sa pamamagitan ng page ng config sa dashboard.

Mga Built-in na Event

Event	Kailan	Payload
onRequest	Bago ang chat handler	Konteksto ng request
onResponse	Pagkatapos ng chat handler	Data ng response
onError	Kapag may error sa handler	Object ng error
onModelSelect	Napili ang model para sa routing	Impormasyon ng model
onComboResolve	Nalutas ang combo routing	Mga target ng combo
onRateLimit	Naabot ang rate limit	Impormasyon ng limit
onQuotaExhaust	Naubos ang quota	Impormasyon ng quota
onProviderError	Nagbalik ng error ang provider	Mga detalye ng error
onStreamStart	Nagsimula ang SSE stream	Impormasyon ng stream
onStreamEnd	Natapos ang SSE stream	Mga estadistika ng stream
onInstall	Na-install ang plugin	{ name, version, manifest }
onActivate	Na-activate ang plugin	{ name, version, manifest }
onDeactivate	Na-deactivate ang plugin	{ name, version, manifest }
onUninstall	Na-uninstall ang plugin (bago burahin ang mga file)	{ name, version, manifest }

Mga Halimbawa

Logger ng Request

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

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 minuto
    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 ng Response

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