NeboAI
NeboAI
شروع کنید

App Sidecar

sidecar یک فایل اجرایی است که کنار یک برنامه اجرا می‌شود. API صفحه را ارائه می‌دهد، داده‌های برنامه را نگه می‌دارد و به کارمند برنامه ابزار می‌دهد. Nebo آن را اجرا می‌کند، درخواست‌ها را از طریق یک سوکت محلی به آن می‌فرستد و وقتی از کار بیفتد دوباره راه‌اندازی‌اش می‌کند.

قرارداد

sidecar یک سرور gRPC روی سوکت Unix است. روی مسیر NEBO_APP_SOCK گوش بدهید و apps.v0.UIService را پیاده‌سازی کنید. Nebo برای هر درخواست HandleRequest را فرا می‌خواند؛ HealthCheck و Configure بخشی از سرویس‌اند اما امروز فراخوانی نمی‌شوند. سوکت باید ظرف startup_timeout مشخص‌شده در manifest ظاهر شود که پیش‌فرض آن ۱۰ ثانیه و حداکثر ۱۲۰ است.

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

sidecarها روی macOS و Linux اجرا می‌شوند.

Nebo فایل اجرایی را کجا پیدا می‌کند

در پوشه برنامه، Nebo از اولین مورد موجود از این‌ها استفاده می‌کند:

  1. فایلی به نام binary
  2. فایلی به نام app
  3. اولین فایل در tmp/
  4. اولین فایل در bin/
  5. اولین فایل اجرایی در sidecar/target/release/، برای توسعه محلی

فایل اجرایی باید یک فایل معمولی و قابل اجرا باشد، نه symlink، و حداکثر 500 MB. برنامه‌های منتشرشده آن را در bin/<name> دارند. وقتی فایل روی دیسک تغییر کند، Nebo sidecar را دوباره راه‌اندازی می‌کند.

محیط

sidecar با یک محیط خالی و این متغیرها شروع می‌شود:

متغیرمقدار
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_URLAPI محلی بات، http://127.0.0.1:<port>.
NEBO_APP_TOKENتوکنی برای فراخوانی API برنامه‌های بات.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZبدون تغییر منتقل می‌شود.

خروجی استاندارد و خطای استاندارد به sidecar.log در پوشه داده می‌روند. ورودی استاندارد یک pipe است؛ پایان فایل یعنی Nebo رفته و sidecar باید خارج شود. sidecar در گروه فرایند خودش اجرا می‌شود.

درخواست‌های صفحه

درخواستی به /apps/<id>/api/<path> که صفحه با neboFetch و یک مسیر نسبی می‌فرستد، با path برابر <path> به HandleRequest می‌رسد. مسیرهایی که با _ شروع شوند رد می‌شوند. بدنه درخواست‌ها حداکثر 10 MB و پاسخ‌ها حداکثر 32 MB است.

ابزارهای کارمند

ابزارها را در agent.json برنامه اعلام کنید. هر کدام به ابزاری با نام app__<app>__<name> تبدیل می‌شود که هر وقت کارمند لازمش داشته باشد بارگذاری می‌شود. هر فراخوانی به درخواستی به sidecar با 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

sidecar می‌تواند با فراخوانی $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}. پاسخ‌های استریمی به‌صورت server-sent events هستند.
POST /janus/complete, POST /janus/streamفراخوانی مستقیم مدل: {messages, model, temperature, max_tokens, system}.
POST /http/proxyیک درخواست بیرونی، {url, method, headers, body}، که مجوزهای network: برنامه آن را مجاز کرده باشند.
GET /identityکارمند برنامه.

چرخه عمر

  • Nebo هر سه ثانیه سوکت را بررسی می‌کند.
  • sidecar ناموفق پس از یک ثانیه دوباره راه‌اندازی می‌شود و این فاصله هر بار دو برابر می‌شود تا حداکثر ۶۰ ثانیه. پس از پنج شکست پیاپی، ناموفق علامت می‌خورد. sidecarی که ۶۰ ثانیه سرپا بماند دوباره سالم است.
  • درخواست به sidecar متوقف‌شده آن را اجرا می‌کند و تا ۱۵ ثانیه منتظر می‌ماند. درخواست‌های GET و HEAD دوباره تلاش می‌شوند.
  • برای متوقف کردن sidecar، Nebo سیگنال SIGTERM را به گروه فرایندش می‌فرستد و پس از دو ثانیه آن را می‌کشد.