プラグインの仕組み
プラグインは、実行ファイルとマニフェストからなります。Neboは呼び出しの合間にプラグインのプロセスを動かし続けることはありません。社員がプラグインを使うたびに、Neboはコマンドと引数を付けてバイナリを起動し、終了を待ち、出力を社員に返します。
- コマンドは引数です。社員は
notes searchのようなコマンドと、名前付きの引数を選びます。Neboは各引数を--name valueとして渡します。シェルは使われないので、パイプやリダイレクトは一切適用されません。 - 出力はstdoutです。結果はstdoutに書き出してください。JSONが適しています。
- 通常の呼び出しでは標準入力は閉じています。フック、ルート、チャットプロバイダーはstdinを使います。plugin.jsonリファレンスをご覧ください。
インストールされ有効になっているプラグインはそれぞれ、plugin__<slug>という名前の1つのツールとして社員に見えます。社員は次のように呼び出します:
{
"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 | 待機する秒数。デフォルトは120で、マニフェストのpermissions.maxTimeoutSecondsが上限です。 |
display | string | 呼び出しに承認が必要なときにオーナーに表示される文。 |
最初のプラグインを作る
引数からコマンドを読み取って結果を出力するバイナリを、任意の言語で書きます。それを、ボットのユーザーpluginsディレクトリにある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は必須です。ユーザーのpluginsディレクトリでは、platformsのマップは空でもかまいません。Neboはplugin.jsonの横、次にtarget/release/とtarget/debug/で、スラッグと同じ名前のバイナリを探します。公開すると、アップロードしたすべてのバイナリについて、マーケットプレイスがplatformsを埋めます。
<data>は、macOSでは~/Library/Application Support/Nebo、Windowsでは%APPDATA%\Nebo、Linuxでは~/.local/share/nebo、またはNEBO_HOMEの値です。ユーザーディレクトリにあるプラグインは、同じスラッグのマーケットプレイスのプラグインより優先されるので、新しいビルドを試す場所に最適です。
社員に使い方を教える
plugin.jsonの横にskills/フォルダを置きます。その中の各スキルは、プラグインがインストールされている間すべての社員が使え、プラグインを依存関係として自動で記載します。スキルを使って、どんなコマンドがあり、何を返し、それぞれをいつ使うかを伝えましょう。最も役立つスキルをentrySkillsに指定すると、プラグインのツールの説明で最初にそれが示されます。
マーケットプレイスの掲載ページは、別のファイルPLUGIN.mdです。Neboは実行時にはこれを読みません。インストール前にユーザーが目にするページです。プラグインの出荷をご覧ください。
環境
各呼び出しは、ローダーやシェルインジェクション用の変数を取り除いたボットの環境を引き継ぎ、そのうえで次の値を追加します。後のエントリーが優先されます。
| 変数 | 値 |
|---|---|
auth.envのキー | マニフェストのデフォルト値。 |
<SLUG>_BIN | このプラグインのバイナリと、依存する各プラグインのバイナリのパス。スラッグは大文字にし、ハイフンはアンダースコアにします。 |
NEBO_DATA_DIR | プラグイン専用のデータフォルダ、<data>/appdata/plugins/<slug>/。作業ディレクトリでもあり、アンインストール後も残ります。 |
PATH | まずプラグインのフォルダ、次に引き継がれたパス。 |
| 設定 | オーナーがconfigSchemaのフィールドに保存した値。 |
NEBO_AGENT_ID | 呼び出しを行っている社員。 |
profileDirEnv | プラグインがアカウントに対応している場合の、この社員とアカウント用のアカウントフォルダ。 |
permissions.envAllowとpermissions.envDenyは、プラグインがボットから引き継ぐものを絞り込みます。プラグイン自身の認証用の変数が取り除かれることはありません。
アカウントと認証情報
サービスにサインインするプラグインは、社員ごとに1つのアカウントを保持してください。経理担当は経理用のログインで、アシスタントは自分のログインでサインインし、互いのトークンを目にすることはありません。これはマニフェストで宣言するだけで、あとは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は社員とアカウントごとに1つのフォルダを作り、すべての呼び出しでその変数を設定します。- オーナーがアカウントを接続すると、Neboはオーナーが入力した値とアカウントのフォルダを設定して、
loginコマンドを実行します。プラグインは必要なものをそのフォルダに保存します。Neboはその値を保持しません。 statusコマンドは{"authenticated": true}のようなJSONを出力します。トークンの有効期限が切れると、refreshを宣言していればNeboがそれを実行します。
ブラウザでのサインインの場合は、typeをoauth_cliに設定し、loginでプロバイダーのサインインURLを表示するか開くようにします。社員が自分でサインインすることはありません。呼び出しにログインが必要なときは、オーナーに接続カードが表示されます。複数のアカウントを持つ社員は、コマンドに--account <label>を付けて1つを選びます。Neboは、バイナリに渡す前にそのフラグを取り除きます。
形ではなく、サービスの名前を付けましょう。プラグインの名前は、「Example Notes」のように接続先を表します。プラグイン名に「CLI」を入れないでください。社員とオーナーにとって、それはコマンドラインではなく接続です。
次へ
- plugin.jsonリファレンス: イベント、フック、型付きの操作を含むすべてのフィールド。
- プラグインの出荷: プラットフォーム、バイナリ、署名、アップデート。
- 公開: すべてのアイテムに共通のマーケットプレイスの流れ。