قرارداد
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 از اولین مورد موجود از اینها استفاده میکند:
- فایلی به نام
binary - فایلی به نام
app - اولین فایل در
tmp/ - اولین فایل در
bin/ - اولین فایل اجرایی در
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_URL | API محلی بات، 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 را به گروه فرایندش میفرستد و پس از دو ثانیه آن را میکشد.