Cara kerja plugin
Plugin adalah executable ditambah manifes. Nebo tidak menjaga proses plugin tetap berjalan di antara panggilan. Setiap kali karyawan menggunakan plugin, Nebo memulai biner dengan perintah dan argumen, menunggu hingga selesai, lalu menyerahkan outputnya kembali ke karyawan.
- Perintah adalah argumen. Karyawan memilih perintah, seperti
notes search, dan argumen bernama. Nebo meneruskan setiap argumen sebagai--name value. Tidak ada shell, jadi pipe dan pengalihan tidak pernah berlaku. - Output adalah stdout. Tulis hasil ke stdout. JSON sangat cocok.
- Input standar ditutup untuk panggilan biasa. Hook, rute, dan penyedia chat menggunakan stdin; lihat referensi plugin.json.
Setiap plugin yang terinstal dan aktif tampil bagi karyawan sebagai satu alat bernama plugin__<slug>. Karyawan memanggilnya seperti ini:
{
"command": "notes search",
"args": { "query": "quarterly plan", "limit": "5" },
"display": "Search notes for the quarterly plan"
} Nebo menjalankan:
notes-sync notes search --query "quarterly plan" --limit 5
| Parameter | Tipe | Arti |
|---|---|---|
command | string, wajib | Perintah plugin dan kata posisional apa pun. |
args | objek string | Argumen bernama. Masing-masing menjadi --key value. |
timeout | integer | Detik untuk menunggu. Bawaan 120, dibatasi oleh permissions.maxTimeoutSeconds di manifes. |
display | string | Kalimat yang dilihat pemilik saat panggilan memerlukan persetujuan. |
Buat plugin pertama Anda
Tulis biner dalam bahasa apa pun yang membaca perintahnya dari argumen dan mencetak hasil. Lalu letakkan di samping plugin.json di direktori plugin pengguna sebuah bot.
<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, dan platforms wajib diisi. Di direktori plugin pengguna, peta platforms boleh kosong: Nebo mencari biner yang dinamai sesuai slug di samping plugin.json, lalu di target/release/ dan target/debug/. Saat Anda menerbitkan, marketplace mengisi platforms untuk setiap biner yang Anda unggah.
<data> adalah ~/Library/Application Support/Nebo di macOS, %APPDATA%\Nebo di Windows, dan ~/.local/share/nebo di Linux, atau nilai NEBO_HOME. Plugin di direktori pengguna menggantikan plugin marketplace dengan slug yang sama, sehingga di sanalah tempat menguji build baru.
Ajari karyawan cara menggunakannya
Letakkan folder skills/ di samping plugin.json. Setiap skill di dalamnya tersedia untuk semua karyawan selama plugin terinstal, dan otomatis mencantumkan plugin sebagai dependensi. Gunakan skill untuk menjelaskan perintah apa saja yang ada, apa hasilnya, dan kapan masing-masing digunakan. Sebutkan skill yang paling berguna di entrySkills agar deskripsi alat plugin menunjuk ke skill tersebut lebih dulu.
Listing marketplace adalah file terpisah, PLUGIN.md. Nebo tidak membacanya saat berjalan; itu adalah halaman yang dilihat orang sebelum menginstal. Lihat Merilis plugin.
Lingkungan
Setiap panggilan mewarisi lingkungan bot dengan variabel loader dan injeksi shell dihapus, lalu menambahkan nilai-nilai ini. Entri yang lebih akhir yang berlaku.
| Variabel | Nilai |
|---|---|
Kunci auth.env | Nilai bawaan dari manifes. |
<SLUG>_BIN | Path biner plugin ini, dan setiap plugin yang menjadi dependensinya. Slug ditulis dalam huruf besar dengan tanda hubung diganti garis bawah. |
NEBO_DATA_DIR | Folder data milik plugin, <data>/appdata/plugins/<slug>/. Ini juga merupakan direktori kerja, dan tetap ada setelah pencopotan instalasi. |
PATH | Folder plugin lebih dulu, lalu path yang diwarisi. |
| Pengaturan | Nilai yang disimpan pemilik untuk kolom configSchema. |
NEBO_AGENT_ID | Karyawan yang melakukan panggilan. |
profileDirEnv | Folder akun untuk karyawan dan akun ini, jika plugin mendukung akun. |
permissions.envAllow dan permissions.envDeny mempersempit apa yang diwarisi plugin dari bot. Keduanya tidak pernah menghapus variabel autentikasi milik plugin.
Akun dan kredensial
Plugin yang masuk ke sebuah layanan sebaiknya menyimpan satu akun per karyawan. Pemegang pembukuan masuk dengan login keuangan dan asisten dengan login miliknya sendiri, dan tidak satu pun melihat token yang lain. Anda menyatakannya di manifes; Nebo mengurus sisanya.
"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.envmenamai kredensial.capabilities.configSchemamemberinya label dan mengatur urutannya di formulir hubungkan.auth.profileDirEnvmenamai variabel yang dibaca plugin Anda untuk folder kredensialnya. Nebo membuat satu folder untuk setiap karyawan dan akun, lalu mengatur variabel tersebut pada setiap panggilan.- Saat pemilik menghubungkan akun, Nebo menjalankan perintah
loginAnda dengan nilai yang diketik pemilik dan folder akun yang sudah diatur. Plugin Anda menyimpan apa yang dibutuhkannya di folder itu. Nebo tidak menyimpan nilai-nilai tersebut. - Perintah
statusAnda mencetak JSON seperti{"authenticated": true}. Saat token kedaluwarsa, Nebo menjalankanrefreshjika Anda mendeklarasikannya.
Untuk proses masuk lewat browser, atur type ke oauth_cli dan buat login mencetak atau membuka URL masuk penyedia. Karyawan tidak pernah masuk sendiri: saat panggilan memerlukan login, pemilik melihat kartu hubungkan. Karyawan dengan beberapa akun memilih salah satunya dengan menambahkan --account <label> ke perintah. Nebo menghapus flag itu sebelum biner Anda melihatnya.
Sebutkan layanannya, bukan bentuknya. Nama plugin menyatakan apa yang dihubungkannya, seperti "Example Notes". Jangan pernah mencantumkan "CLI" di nama plugin; bagi karyawan dan pemilik, plugin adalah koneksi, bukan baris perintah.
Berikutnya
- Referensi plugin.json: setiap kolom, termasuk event, hook, dan operasi bertipe.
- Merilis plugin: platform, biner, penandatanganan, dan pembaruan.
- Penerbitan: alur marketplace untuk setiap artefak.