NeboAI
NeboAI
شروع کنید

مرجع plugin.json

plugin.json مانیفستی است که Nebo برای نصب و اجرای یک افزونه می‌خواند. کلیدها به شکل camelCase هستند. این صفحه همه فیلدهایی را که Nebo امروز می‌خواند و کار هر کدام را فهرست می‌کند.

فیلدهای سطح بالا

فیلدنوعالزامیمعنی
idstringبلهشناسه افزونه در فروشگاه. هنگام توسعه از slug استفاده کنید.
slugstringبلهشناسه پایدار. [a-z0-9-]، حداکثر ۶۴ نویسه، بدون خط تیره در ابتدا، انتها یا خط تیره دوتایی. ابزار plugin__<slug> و متغیر <SLUG>_BIN با آن نام‌گذاری می‌شوند.
namestringبلهنام نمایشی. سرویسی را که به آن متصل می‌شود نام ببرید.
versionstringبلهنسخه معنایی، مانند 0.1.0.
platformsmapبلهکلید پلتفرم به فایل اجرایی. بخش Platforms را ببینید.
descriptionstringخیریک جمله برای افراد و کارمندان.
authorstringخیرنام ناشر.
categorystringخیربه کارمندان کمک می‌کند افزونه را پیدا کنند.
triggersفهرستی از رشته‌هاخیرواژه‌هایی که توضیح می‌دهند افزونه چه زمانی کاربرد دارد. در راهنمایی‌های جستجو استفاده می‌شوند.
entrySkillsفهرستی از رشته‌هاخیرمهارت‌های همراهی که باید اول در توضیح ابزار افزونه نام برده شوند.
dependenciesفهرستی از {name, version, optional}خیرافزونه‌های دیگری که این افزونه اجرا می‌کند. مقدار پیش‌فرض version برابر "*" و optional برابر false است. مسیرهای <SLUG>_BIN آن‌ها در هر فراخوانی تنظیم می‌شوند.
authobjectخیرورود و حساب‌ها. بخش Auth را ببینید.
capabilitiesobjectخیرconfigSchema, hooks, commands, routes, providers.
permissionsobjectخیرفیلتر کردن متغیرهای محیطی و سقف زمان انتظار.
eventslistخیرناظرهایی که گردش‌کارهای کارمندان را تغذیه می‌کنند.
interfaceBindingsmapخیرعملیات تایپ‌شده‌ای که افزونه ارائه می‌دهد.
channelobjectخیریک پل پایدار به یک سرویس پیام‌رسان.
setupobjectخیریک راهنمای راه‌اندازی گام‌به‌گام.

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 بسته را از آن دانلود می‌کند.

احراز هویت

فیلدمعنی
typeoauth_cli برای ورود از طریق مرورگر که افزونه آن را اجرا می‌کند؛ env برای اطلاعات ورودی که به‌صورت مقدار وارد می‌شوند؛ neboai برای دریافت توکن NeboAI مالک در هر کلید auth.env که با _TOKEN تمام می‌شود.
envنگاشت نام متغیر به مقدار پیش‌فرض. همچنین تنها نام‌های اطلاعات ورودی است که Nebo به login می‌دهد.
commands.loginوارد می‌شود. الزامی است مگر اینکه type برابر env باشد. با پوشه حساب تنظیم‌شده اجرا می‌شود.
commands.statusJSON چاپ می‌کند که نشان می‌دهد آیا حساب وارد شده است یا نه.
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 هم آمده‌اند، این طرح‌واره فیلدهای فرم اتصال هر کارمند را برچسب‌گذاری می‌کند.

فیلدنوعپیش‌فرضمعنی
keystringالزامینام متغیر محیطی.
labelstringالزامیبرچسب فیلد.
descriptionstring""متن راهنما.
fieldTypestring"string"نوع ورودی، مانند string، number، boolean، select یا password.
defaultstringهیچمقدار ازپیش‌پرشده.
requiredbooleanfalseافزونه تا وقتی مقدار تنظیم نشود آماده نیست.
secretbooleanfalseمقدار هنگام بازخوانی پوشانده می‌شود.
optionsفهرستی از رشته‌هاهیچگزینه‌ها برای select.

مجوزها

فیلدپیش‌فرضمعنی
envAllow[]متغیرهای ارث‌برده‌ای که افزونه می‌تواند ببیند. خالی بودن یعنی همه مجازند.
envDeny[]متغیرهای ارث‌برده‌ای که همیشه حذف می‌شوند.
maxTimeoutSeconds300حد بالای زمان انتظار هر فراخوانی.
networkfalseاستفاده از شبکه را اعلام می‌کند. اطلاعاتی است؛ اجباری نیست.

رویدادها

یک رویداد یک ناظر طولانی‌مدت است. 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الزامیآرگومان‌ها برای فایل اجرایی شما.
priority100عدد کمتر زودتر اجرا می‌شود.
timeoutMs500محدودیت زمانی به میلی‌ثانیه.

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""در تنظیمات نمایش داده می‌شود.
restartDelaySecs5مدت انتظار پیش از راه‌اندازی دوباره پس از خرابی.
sharedfalseیک پل برای همه کارمندان؛ پیام‌ها بر اساس نام کارمند مسیریابی می‌شوند و پاسخ‌ها هویت هر کارمند را دارند.
needsLocalApifalseنشانی 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" }
  ]
}
نوع مرحلهفیلدها
formtitle, description, fields
generatetitle، description، command، args، outputFormat (yaml، json، toml، text)، buttonLabel. خروجی فرمان را برای کپی نشان می‌دهد.
externaltitle, description, url, urlLabel, instructions
credentialstitle، description، fields، verifyCommand. مرحله وقتی کامل می‌شود که verifyCommand موفق شود.

فیلدها شامل key، label، default، placeholder، maxLength، help، inputType (text، textarea، password) و required هستند.