فیلدهای سطح بالا
| فیلد | نوع | الزامی | معنی |
|---|---|---|---|
id | string | بله | شناسه افزونه در فروشگاه. هنگام توسعه از slug استفاده کنید. |
slug | string | بله | شناسه پایدار. [a-z0-9-]، حداکثر ۶۴ نویسه، بدون خط تیره در ابتدا، انتها یا خط تیره دوتایی. ابزار plugin__<slug> و متغیر <SLUG>_BIN با آن نامگذاری میشوند. |
name | string | بله | نام نمایشی. سرویسی را که به آن متصل میشود نام ببرید. |
version | string | بله | نسخه معنایی، مانند 0.1.0. |
platforms | map | بله | کلید پلتفرم به فایل اجرایی. بخش Platforms را ببینید. |
description | string | خیر | یک جمله برای افراد و کارمندان. |
author | string | خیر | نام ناشر. |
category | string | خیر | به کارمندان کمک میکند افزونه را پیدا کنند. |
triggers | فهرستی از رشتهها | خیر | واژههایی که توضیح میدهند افزونه چه زمانی کاربرد دارد. در راهنماییهای جستجو استفاده میشوند. |
entrySkills | فهرستی از رشتهها | خیر | مهارتهای همراهی که باید اول در توضیح ابزار افزونه نام برده شوند. |
dependencies | فهرستی از {name, version, optional} | خیر | افزونههای دیگری که این افزونه اجرا میکند. مقدار پیشفرض version برابر "*" و optional برابر false است. مسیرهای <SLUG>_BIN آنها در هر فراخوانی تنظیم میشوند. |
auth | object | خیر | ورود و حسابها. بخش Auth را ببینید. |
capabilities | object | خیر | configSchema, hooks, commands, routes, providers. |
permissions | object | خیر | فیلتر کردن متغیرهای محیطی و سقف زمان انتظار. |
events | list | خیر | ناظرهایی که گردشکارهای کارمندان را تغذیه میکنند. |
interfaceBindings | map | خیر | عملیات تایپشدهای که افزونه ارائه میدهد. |
channel | object | خیر | یک پل پایدار به یک سرویس پیامرسان. |
setup | object | خیر | یک راهنمای راهاندازی گامبهگام. |
Nebo نصبهای فروشگاه را اعتبارسنجی میکند: قواعد slug، یک نسخه معنایی، دستکم یک پلتفرم، یک binaryName بدون جداکننده مسیر یا ..، یک فرمان login مگر اینکه auth.type برابر env باشد، نام رویدادها و فرمانهای غیرخالی، و الگوهای اتصالی که قابل تجزیه باشند. افزونههای موجود در پوشه افزونههای کاربر از اعتبارسنجی معافاند.
پلتفرمها
کلیدها darwin-arm64، darwin-amd64، linux-arm64، linux-amd64، windows-arm64 و windows-amd64 هستند. هر ورودی همه پنج فیلد زیر را دارد. هنگام انتشار، فروشگاه هش، اندازه، امضا و نشانی دانلود واقعی را مینویسد، پس آنها را در فایلی که بارگذاری میکنید خالی بگذارید.
"platforms": {
"darwin-arm64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"linux-amd64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
} | فیلد | معنی |
|---|---|
binaryName | نام فایل اجرایی. در Windows پسوند .exe را اضافه کنید. |
sha256 | هش فایل اجرایی. هنگام نصب بررسی میشود. |
signature | امضای فایل اجرایی. هنگام نصب، اگر کلید امضا در دسترس باشد، بررسی میشود. |
size | اندازه به بایت. |
downloadUrl | جایی که Nebo بسته را از آن دانلود میکند. |
احراز هویت
| فیلد | معنی |
|---|---|
type | oauth_cli برای ورود از طریق مرورگر که افزونه آن را اجرا میکند؛ env برای اطلاعات ورودی که بهصورت مقدار وارد میشوند؛ neboai برای دریافت توکن NeboAI مالک در هر کلید auth.env که با _TOKEN تمام میشود. |
env | نگاشت نام متغیر به مقدار پیشفرض. همچنین تنها نامهای اطلاعات ورودی است که Nebo به login میدهد. |
commands.login | وارد میشود. الزامی است مگر اینکه type برابر env باشد. با پوشه حساب تنظیمشده اجرا میشود. |
commands.status | JSON چاپ میکند که نشان میدهد آیا حساب وارد شده است یا نه. |
commands.refresh | یک توکن را بدون تعامل تمدید میکند. |
commands.logout | خارج میشود. فقط مالک میتواند آن را اجرا کند. |
profileDirEnv | متغیری که برای هر کارمند و حساب یک پوشه اطلاعات ورود جداگانه دریافت میکند. بدون آن، افزونه یک حساب مشترک نگه میدارد. |
label, description | متن روی کارت اتصال. |
help | {url, urlLabel, text} که هنگام اتصال نمایش داده میشود. |
publicRedirect | وقتی ارائهدهنده تغییر مسیر به http://localhost را نمیپذیرد، true قرار دهید؛ در این صورت ورود از طریق تغییر مسیر عمومی NeboAI انجام میشود. |
Nebo نخستین مورد از authenticated، isAuthenticated، logged_in، loggedIn یا token_valid را در خروجی وضعیت میخواند. یک token_error غیرخالی، یا مقدار none در credential_source، auth_method، storage یا status، به معنی خارجشده است. فرمان وضعیت ۴۵ ثانیه فرصت دارد.
{"authenticated": true, "account": "finance@example.com"} configSchema
capabilities.configSchema مقادیری را توصیف میکند که مالک برای افزونه تنظیم میکند. هر مقدار بهصورت یک متغیر محیطی با نامی که key تعیین میکند به فایل اجرایی میرسد. برای کلیدهای اطلاعات ورودی که در auth.env هم آمدهاند، این طرحواره فیلدهای فرم اتصال هر کارمند را برچسبگذاری میکند.
| فیلد | نوع | پیشفرض | معنی |
|---|---|---|---|
key | string | الزامی | نام متغیر محیطی. |
label | string | الزامی | برچسب فیلد. |
description | string | "" | متن راهنما. |
fieldType | string | "string" | نوع ورودی، مانند string، number، boolean، select یا password. |
default | string | هیچ | مقدار ازپیشپرشده. |
required | boolean | false | افزونه تا وقتی مقدار تنظیم نشود آماده نیست. |
secret | boolean | false | مقدار هنگام بازخوانی پوشانده میشود. |
options | فهرستی از رشتهها | هیچ | گزینهها برای select. |
مجوزها
| فیلد | پیشفرض | معنی |
|---|---|---|
envAllow | [] | متغیرهای ارثبردهای که افزونه میتواند ببیند. خالی بودن یعنی همه مجازند. |
envDeny | [] | متغیرهای ارثبردهای که همیشه حذف میشوند. |
maxTimeoutSeconds | 300 | حد بالای زمان انتظار هر فراخوانی. |
network | false | استفاده از شبکه را اعلام میکند. اطلاعاتی است؛ اجباری نیست. |
رویدادها
یک رویداد یک ناظر طولانیمدت است. Nebo وقتی گردشکار یک کارمند آن را زیر نظر بگیرد اجرایش میکند و اگر متوقف شود دوباره راهاندازیاش میکند. هر خطی که ناظر در stdout مینویسد یک رویداد است. نام رویداد هنگام اجرا با slug پیشوند میگیرد، بنابراین note.created به notes-sync.note.created تبدیل میشود.
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | فیلد | معنی |
|---|---|
name | نام رویداد، بدون slug. الزامی. |
command | آرگومانهایی که ناظر را اجرا میکنند. الزامی. {{key}} با مقادیر ورودی کارمند جایگزین میشود. |
description | آنچه باعث رویداد میشود. |
multiplexed | وقتی true باشد، یک ناظر چند نوع رویداد تولید میکند و هر خط یک فیلد "event" دارد. |
گردشکارها با یک تریگر watch مشترک رویدادها میشوند. تریگرها را ببینید.
interfaceBindings
یک اتصال، یک عملیات رابط را به یکی از فرمانهای شما نگاشت میکند. هر اتصال به یک ابزار تایپشده برای کارمندان تبدیل میشود که به نام عملیات با حروف کوچک و با زیرخط به جای نقطه و خط تیره نامگذاری میشود: notes.search به notes_search تبدیل میشود. اتصالها راهی هستند که یک افزونه قابلیتهای مورد نیاز یک کارمند را تأمین میکند؛ قابلیتها را ببینید.
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | جاینگهدار | تبدیل میشود به |
|---|---|
{field} | مقدار فیلد بهصورت یک واژه. فیلد دیگر بهعنوان پرچم هم ارسال نمیشود. |
{field[]:--flag} | یک جفت --flag <item> برای هر مورد در یک فیلد فهرستی. |
{field?:--flag} | --flag <value> وقتی فیلد وجود دارد؛ هیچ چیز وقتی وجود ندارد. |
{field:cents->dollars} | یک مقدار صحیح به سنت که به دلار نوشته میشود. |
فیلدهای ورودی که یک الگو نامشان را نمیبرد به شکل --field value به انتها افزوده میشوند. جاینگهدارهای فهرستی و اختیاری باید واژههای کامل باشند. به عملیاتی که نیاز به تأیید دارد نمیتوان با فراخوانی همان فرمان از طریق plugin__<slug> دسترسی پیدا کرد.
هوکها، فرمانهای اسلش و مسیرها
"capabilities": {
"hooks": [
{ "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
],
"commands": [
{ "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
],
"routes": [
{ "path": "/callback", "method": "GET", "command": "http callback" }
]
} hooks
هوک فرمان شما را در نقطهای از نوبت یک کارمند اجرا میکند. Nebo یک محمولهٔ JSON در stdin مینویسد. خروجی هوک action نادیده گرفته میشود. هوک filter مقدار {"payload": ..., "handled": false} را برمیگرداند؛ "handled": true هوکهای بعدی را متوقف میکند. خطاها و پایان مهلت، محمولهٔ قبلی را نگه میدارند و هرگز نوبت را متوقف نمیکنند. پس از سه شکست پشت سر هم، هوک به مدت پنج دقیقه متوقف میشود.
| فیلد | پیشفرض | معنی |
|---|---|---|
hook | الزامی | یکی از tool.pre_execute، tool.post_execute، message.post_receive، session.message_append، steering.generate، agent.turn، agent.should_continue. |
hookType | "action" | action یا filter. |
command | الزامی | آرگومانها برای فایل اجرایی شما. |
priority | 100 | عدد کمتر زودتر اجرا میشود. |
timeoutMs | 500 | محدودیت زمانی به میلیثانیه. |
commands
با "slash": true، تایپ /name args در گفتگو مستقیماً command args را اجرا میکند، بدون کارمند. خروجی همان پاسخ است. محدودیت زمانی ۳۰ ثانیه است.
routes
یک مسیر به درخواستهای HTTP در /api/v1/plugins/<slug>/api/<path> روی ربات پاسخ میدهد و بر اساس path و method تطبیق داده میشود. بدنه درخواست به stdin میرود و stdout شما پاسخ است. محدودیت زمانی ۳۰ ثانیه است.
providers
یک ارائهدهنده یک منبع مدل گفتگو اضافه میکند. id، displayName، providerType، modelsCommand و chatCommand را اعلام کنید. Nebo یک درخواست گفتگو را بهصورت JSON از طریق stdin به chatCommand میفرستد و رویدادهای جریانی را بهصورت JSON جداشده با خط جدید از stdout میخواند، حداکثر تا ۳۰۰ ثانیه. امروز فقط جریان گفتگو استفاده میشود.
channel
یک کانال یک سرویس پیامرسان را متصل میکند. Nebo فرمان command را در حال اجرا نگه میدارد، پیامهای ورودی را از stdout آن میخواند و پاسخها را در stdin آن مینویسد، هر دو بهصورت JSON جداشده با خط جدید.
| فیلد | پیشفرض | معنی |
|---|---|---|
command | الزامی | آرگومانهایی که پل را اجرا میکنند. |
name, description | "" | در تنظیمات نمایش داده میشود. |
restartDelaySecs | 5 | مدت انتظار پیش از راهاندازی دوباره پس از خرابی. |
shared | false | یک پل برای همه کارمندان؛ پیامها بر اساس نام کارمند مسیریابی میشوند و پاسخها هویت هر کارمند را دارند. |
needsLocalApi | false | نشانی API محلی ربات، یک توکن و شناسه کارمند را به پل بدهید. خاموش است مگر اینکه به آن نیاز داشته باشید. |
setup
دستیار راهاندازی، مالک را گامبهگام در مراحلی پیش میبرد که یک فرم تنها از پس آنها برنمیآید. مقادیر مراحل form جای {{key}} را در آرگومانهای بعدی generate پر میکنند. مقادیر مراحل credentials بهعنوان متغیرهای محیطی افزونه ذخیره میشوند.
"setup": {
"title": "Connect Example Chat",
"steps": [
{ "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
{ "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
{ "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
{ "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
]
} | نوع مرحله | فیلدها |
|---|---|
form | title, description, fields |
generate | title، description، command، args، outputFormat (yaml، json، toml، text)، buttonLabel. خروجی فرمان را برای کپی نشان میدهد. |
external | title, description, url, urlLabel, instructions |
credentials | title، description، fields، verifyCommand. مرحله وقتی کامل میشود که verifyCommand موفق شود. |
فیلدها شامل key، label، default، placeholder، maxLength، help، inputType (text، textarea، password) و required هستند.