NeboAI
NeboAI
شروع کنید

افزونه‌ها

یک افزونه چیزی به کارمندان می‌دهد که روی آن کار کنند: یک سرویس آنلاین، یک سیستم کسب‌وکار یا برنامه‌ای روی رایانه. آن را به‌صورت یک فایل اجرایی خط فرمان می‌سازید و با یک مانیفست plugin.json توصیفش می‌کنید. کارمندان فرمان‌های آن را فراخوانی می‌کنند، و Nebo نصب، حساب‌های جداگانه هر کارمند و به‌روزرسانی‌ها را انجام می‌دهد.

افزونه‌ها چگونه کار می‌کنند

یک افزونه یک فایل اجرایی به‌علاوه یک مانیفست است. Nebo بین فراخوانی‌ها هیچ فرایند افزونه‌ای را در حال اجرا نگه نمی‌دارد. هر بار که کارمندی از افزونه استفاده می‌کند، Nebo فایل اجرایی را با یک فرمان و آرگومان‌ها اجرا می‌کند، منتظر می‌ماند تا تمام شود، و خروجی را به کارمند برمی‌گرداند.

  • فرمان‌ها آرگومان هستند. کارمند یک فرمان، مانند notes search، و آرگومان‌های نام‌دار را انتخاب می‌کند. Nebo هر آرگومان را به شکل --name value می‌فرستد. هیچ پوسته‌ای در کار نیست، بنابراین پایپ‌ها و تغییر مسیرها هرگز اعمال نمی‌شوند.
  • خروجی همان stdout است. نتایج را در stdout بنویسید. JSON به‌خوبی کار می‌کند.
  • ورودی استاندارد بسته است برای فراخوانی‌های معمولی. هوک‌ها، مسیرها و ارائه‌دهندگان گفتگو از stdin استفاده می‌کنند؛ مرجع plugin.json را ببینید.

هر افزونه نصب‌شده و فعال برای کارمندان به‌صورت یک ابزار به نام plugin__<slug> ظاهر می‌شود. یک کارمند آن را این‌طور فراخوانی می‌کند:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo اجرا می‌کند:

notes-sync notes search --query "quarterly plan" --limit 5
پارامترنوعمعنی
commandرشته، الزامیفرمان افزونه و هر واژه موقعیتی.
argsشیئی از رشته‌هاآرگومان‌های نام‌دار. هر کدام به --key value تبدیل می‌شود.
timeoutintegerثانیه‌های انتظار. پیش‌فرض ۱۲۰، با سقف permissions.maxTimeoutSeconds در مانیفست.
displaystringجمله‌ای که مالک وقتی فراخوانی نیاز به تأیید دارد می‌بیند.

نخستین افزونه خود را بسازید

به هر زبانی یک فایل اجرایی بنویسید که فرمانش را از آرگومان‌ها بخواند و یک نتیجه چاپ کند. سپس آن را کنار یک plugin.json در پوشه افزونه‌های کاربر یک ربات قرار دهید.

<data>/user/plugins/notes-sync/
├── plugin.json      # runtime manifest
├── notes-sync       # your binary, named after the slug
└── skills/          # optional: skills that teach employees to use it
    └── notes-sync/
        └── SKILL.md
{
  "id": "notes-sync",
  "slug": "notes-sync",
  "name": "Notes Sync",
  "version": "0.1.0",
  "description": "Search, read and create notes in Example Notes.",
  "platforms": {}
}

id، slug، name، version و platforms الزامی هستند. در پوشه افزونه‌های کاربر، نگاشت platforms می‌تواند خالی باشد: Nebo به دنبال فایل اجرایی‌ای به نام slug در کنار plugin.json می‌گردد، سپس در target/release/ و target/debug/. هنگام انتشار، فروشگاه platforms را برای هر فایل اجرایی که بارگذاری می‌کنید پر می‌کند.

<data> در macOS برابر ~/Library/Application Support/Nebo، در Windows برابر %APPDATA%\Nebo و در Linux برابر ~/.local/share/nebo است، یا مقدار NEBO_HOME. افزونه‌ای در پوشه کاربر بر افزونه فروشگاه با همان slug اولویت دارد، و همین آن را جای مناسبی برای آزمایش یک نسخه جدید می‌کند.

استفاده از آن را به کارمندان یاد بدهید

یک پوشه skills/ کنار plugin.json قرار دهید. هر مهارت در آن، تا وقتی افزونه نصب است، برای همه کارمندان در دسترس است و افزونه را به‌طور خودکار به‌عنوان وابستگی فهرست می‌کند. از مهارت استفاده کنید تا بگویید چه فرمان‌هایی وجود دارند، چه برمی‌گردانند و هر کدام کی به کار می‌آید. مفیدترین مهارت‌ها را در entrySkills نام ببرید تا توضیح ابزار افزونه اول به آن‌ها اشاره کند.

فهرست فروشگاه یک فایل جداگانه است، PLUGIN.md. Nebo آن را هنگام اجرا نمی‌خواند؛ این صفحه‌ای است که افراد پیش از نصب می‌بینند. عرضه یک افزونه را ببینید.

محیط

هر فراخوانی محیط ربات را به ارث می‌برد، با حذف متغیرهای بارگذار و تزریق پوسته، سپس این مقادیر را اضافه می‌کند. ورودی‌های بعدی اولویت دارند.

متغیرمقدار
کلیدهای auth.envمقادیر پیش‌فرض از مانیفست.
<SLUG>_BINمسیر فایل اجرایی این افزونه و هر افزونه‌ای که به آن وابسته است. slug با حروف بزرگ و با زیرخط به جای خط تیره نوشته می‌شود.
NEBO_DATA_DIRپوشه داده خود افزونه، <data>/appdata/plugins/<slug>/. این پوشه دایرکتوری کاری هم هست و پس از حذف نصب باقی می‌ماند.
PATHابتدا پوشه‌های افزونه، سپس مسیر ارث‌برده.
تنظیماتمقادیری که مالک برای فیلدهای configSchema ذخیره کرده است.
NEBO_AGENT_IDکارمندی که فراخوانی را انجام می‌دهد.
profileDirEnvپوشه حساب برای این کارمند و حساب، وقتی افزونه از حساب‌ها پشتیبانی می‌کند.

permissions.envAllow و permissions.envDeny آنچه را افزونه از ربات به ارث می‌برد محدود می‌کنند. آن‌ها هرگز متغیرهای احراز هویت خود افزونه را حذف نمی‌کنند.

حساب‌ها و اطلاعات ورود

افزونه‌ای که به یک سرویس وارد می‌شود باید برای هر کارمند یک حساب نگه دارد. حسابدار با ورود مالی وارد می‌شود و دستیار با ورود خودش، و هیچ‌کدام توکن‌های دیگری را نمی‌بیند. این را در مانیفست اعلام می‌کنید؛ بقیه کار با Nebo است.

"auth": {
  "type": "env",
  "label": "Example Notes account",
  "env": { "EXAMPLE_NOTES_TOKEN": "" },
  "commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
  "profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
  "configSchema": [
    { "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
  ]
}
  1. auth.env اطلاعات ورود را نام می‌برد. capabilities.configSchema به آن‌ها برچسب می‌زند و ترتیبشان را در فرم اتصال تعیین می‌کند.
  2. auth.profileDirEnv متغیری را نام می‌برد که افزونه شما برای پوشه اطلاعات ورودش می‌خواند. Nebo برای هر کارمند و حساب یک پوشه می‌سازد و آن متغیر را در هر فراخوانی تنظیم می‌کند.
  3. وقتی مالک یک حساب را متصل می‌کند، Nebo فرمان login شما را با مقادیری که مالک تایپ کرده و پوشه حساب تنظیم‌شده اجرا می‌کند. افزونه شما آنچه لازم دارد را در آن پوشه ذخیره می‌کند. Nebo این مقادیر را نگه نمی‌دارد.
  4. فرمان status شما JSON‌ای مانند {"authenticated": true} چاپ می‌کند. وقتی توکنی منقضی می‌شود، اگر refresh را تعریف کرده باشید، Nebo آن را اجرا می‌کند.

برای ورود از طریق مرورگر، type را روی oauth_cli بگذارید و کاری کنید که login نشانی ورود ارائه‌دهنده را چاپ کند یا باز کند. کارمندان هرگز خودشان وارد نمی‌شوند: وقتی یک فراخوانی به ورود نیاز دارد، مالک یک کارت اتصال می‌بیند. کارمندی که چند حساب دارد با افزودن --account <label> به یک فرمان یکی را انتخاب می‌کند. Nebo پیش از آنکه فایل اجرایی شما آن پرچم را ببیند حذفش می‌کند.

سرویس را نام ببرید، نه شکل آن را. نام یک افزونه می‌گوید به چه چیزی متصل می‌شود، مانند «Example Notes». هرگز «CLI» را در نام افزونه نگذارید؛ برای کارمندان و مالکان این یک اتصال است، نه یک خط فرمان.

بعدی

  • مرجع plugin.json: همه فیلدها، از جمله رویدادها، هوک‌ها و عملیات تایپ‌شده.
  • عرضه یک افزونه: پلتفرم‌ها، فایل‌های اجرایی، امضا و به‌روزرسانی‌ها.
  • انتشار: روند فروشگاه برای همه محصولات.