افزونهها چگونه کار میکنند
یک افزونه یک فایل اجرایی بهعلاوه یک مانیفست است. 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 تبدیل میشود. |
timeout | integer | ثانیههای انتظار. پیشفرض ۱۲۰، با سقف permissions.maxTimeoutSeconds در مانیفست. |
display | string | جملهای که مالک وقتی فراخوانی نیاز به تأیید دارد میبیند. |
نخستین افزونه خود را بسازید
به هر زبانی یک فایل اجرایی بنویسید که فرمانش را از آرگومانها بخواند و یک نتیجه چاپ کند. سپس آن را کنار یک 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 }
]
} auth.envاطلاعات ورود را نام میبرد.capabilities.configSchemaبه آنها برچسب میزند و ترتیبشان را در فرم اتصال تعیین میکند.auth.profileDirEnvمتغیری را نام میبرد که افزونه شما برای پوشه اطلاعات ورودش میخواند. Nebo برای هر کارمند و حساب یک پوشه میسازد و آن متغیر را در هر فراخوانی تنظیم میکند.- وقتی مالک یک حساب را متصل میکند، Nebo فرمان
loginشما را با مقادیری که مالک تایپ کرده و پوشه حساب تنظیمشده اجرا میکند. افزونه شما آنچه لازم دارد را در آن پوشه ذخیره میکند. Nebo این مقادیر را نگه نمیدارد. - فرمان
statusشما JSONای مانند{"authenticated": true}چاپ میکند. وقتی توکنی منقضی میشود، اگرrefreshرا تعریف کرده باشید، Nebo آن را اجرا میکند.
برای ورود از طریق مرورگر، type را روی oauth_cli بگذارید و کاری کنید که login نشانی ورود ارائهدهنده را چاپ کند یا باز کند. کارمندان هرگز خودشان وارد نمیشوند: وقتی یک فراخوانی به ورود نیاز دارد، مالک یک کارت اتصال میبیند. کارمندی که چند حساب دارد با افزودن --account <label> به یک فرمان یکی را انتخاب میکند. Nebo پیش از آنکه فایل اجرایی شما آن پرچم را ببیند حذفش میکند.
سرویس را نام ببرید، نه شکل آن را. نام یک افزونه میگوید به چه چیزی متصل میشود، مانند «Example Notes». هرگز «CLI» را در نام افزونه نگذارید؛ برای کارمندان و مالکان این یک اتصال است، نه یک خط فرمان.
بعدی
- مرجع plugin.json: همه فیلدها، از جمله رویدادها، هوکها و عملیات تایپشده.
- عرضه یک افزونه: پلتفرمها، فایلهای اجرایی، امضا و بهروزرسانیها.
- انتشار: روند فروشگاه برای همه محصولات.