NeboAI
NeboAI
ابدأ الآن

المكوّن المرافق للتطبيقات

المكوّن المرافق ملف تنفيذي يعمل بجوار التطبيق. يقدّم واجهة API للصفحة، ويحتفظ ببيانات التطبيق، ويمنح موظف التطبيق أدوات. يشغّله Nebo، ويوجّه الطلبات إليه عبر مقبس محلي، ويعيد تشغيله عند فشله.

العقد

المكوّن المرافق خادم gRPC على مقبس Unix. استمع على المسار الموجود في NEBO_APP_SOCK ونفّذ apps.v0.UIService. يستدعي Nebo الدالة HandleRequest لكل طلب، أما HealthCheck وConfigure فهما جزء من الخدمة لكنهما لا يُستدعيان حاليًا. يجب أن يظهر المقبس خلال startup_timeout المحدد في ملف البيان، وقيمته الافتراضية 10 ثوانٍ وحدّها الأقصى 120.

syntax = "proto3";
package apps.v0;

service UIService {
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Configure(SettingsMap) returns (Empty);
  rpc HandleRequest(HttpRequest) returns (HttpResponse);
}

message HttpRequest {
  string method = 1;               // GET, POST, PUT, DELETE, ...
  string path = 2;                 // relative to /apps/{id}/api/
  string query = 3;                // raw query string
  map<string, string> headers = 4;
  bytes body = 5;
}

message HttpResponse {
  int32 status_code = 1;
  map<string, string> headers = 2;
  bytes body = 3;
}

تعمل المكوّنات المرافقة على macOS وLinux.

أين يعثر Nebo على الملف التنفيذي

في مجلد التطبيق، يستخدم Nebo أول ما يوجد مما يلي:

  1. ملف باسم binary
  2. ملف باسم app
  3. أول ملف في tmp/
  4. أول ملف في bin/
  5. أول ملف تنفيذي في sidecar/target/release/، للتطوير المحلي

يجب أن يكون الملف التنفيذي ملفًا عاديًا قابلًا للتنفيذ، لا رابطًا رمزيًا، وبحجم 500 MB كحد أقصى. تحمله التطبيقات المنشورة في bin/<name>. وعندما يتغير الملف على القرص، يعيد Nebo تشغيل المكوّن المرافق.

البيئة

يبدأ المكوّن المرافق ببيئة فارغة مع هذه المتغيرات:

المتغيرالقيمة
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONهوية التطبيق.
NEBO_APP_DIRمجلد التطبيق.
NEBO_APP_SOCKالمقبس الذي يُستمع عليه، <app folder>/<id>.sock. يضبط Nebo وضعه على 0600.
NEBO_DATA_DIRمجلد بيانات التطبيق، <data>/appdata/agents/<id>/. وهو أيضًا مجلد العمل.
NEBO_API_URLواجهة API المحلية للبوت، http://127.0.0.1:<port>.
NEBO_APP_TOKENرمز لاستدعاء واجهة API للتطبيقات في البوت.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZيُمرَّر كما هو.

يذهب الإخراج القياسي والخطأ القياسي إلى sidecar.log في مجلد البيانات. والإدخال القياسي أنبوب، ونهاية الملف تعني أن Nebo قد توقف وينبغي للمكوّن المرافق أن ينهي عمله. ويعمل المكوّن المرافق في مجموعة عمليات خاصة به.

الطلبات من الصفحة

الطلب إلى /apps/<id>/api/<path>، الذي تُجريه الصفحة عبر neboFetch ومسار نسبي، يصل إلى HandleRequest مع ضبط path على <path>. وتُرفض المسارات التي تبدأ بـ _. حجم نص الطلب محدود بـ 10 MB والاستجابات بـ 32 MB.

أدوات للموظف

صرّح بالأدوات في agent.json الخاص بالتطبيق. تصبح كل واحدة أداة باسم app__<app>__<name>، تُحمَّل عندما يحتاج إليها الموظف. ويصبح الاستدعاء طلبًا إلى المكوّن المرافق على method وpath.

"tools": [
  {
    "name": "list_deals",
    "description": "List open deals, optionally filtered by stage.",
    "method": "GET",
    "path": "/deals",
    "input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
  }
]

استدعاء Nebo

يستطيع المكوّن المرافق استخدام الخدمات نفسها التي تستخدمها الصفحة عبر استدعاء $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... مع الترويسة Authorization: Bearer $NEBO_APP_TOKEN.

المسارما يفعله
GET /storage, GET|PUT|DELETE /storage/<key>مخزن مفاتيح وقيم التطبيق.
POST /agents/invoke, POST /agents/streamيسأل موظفًا: {message, agent, data}. استجابات البث أحداث مُرسَلة من الخادم.
POST /janus/complete, POST /janus/streamاستدعاء مباشر للنموذج: {messages, model, temperature, max_tokens, system}.
POST /http/proxyطلب خارجي، {url, method, headers, body}، تسمح به أذونات network: الخاصة بالتطبيق.
GET /identityموظف التطبيق.

دورة الحياة

  • يفحص Nebo المقبس كل ثلاث ثوانٍ.
  • يُعاد تشغيل المكوّن المرافق الفاشل بعد ثانية واحدة، وتتضاعف المدة حتى 60 ثانية كحد أقصى. وبعد خمسة إخفاقات متتالية يُعلَّم بأنه فاشل. والمكوّن المرافق الذي يبقى يعمل 60 ثانية يعود سليمًا.
  • الطلب إلى مكوّن مرافق متوقف يشغّله وينتظر حتى 15 ثانية. وتُعاد محاولة طلبات GET وHEAD.
  • لإيقاف مكوّن مرافق، يرسل Nebo الإشارة SIGTERM إلى مجموعة عملياته، ثم ينهيه قسرًا بعد ثانيتين.