NeboAI
NeboAI
はじめる

plugin.jsonリファレンス

plugin.jsonは、Neboがプラグインをインストールして実行するために読み込むマニフェストです。キーはcamelCaseです。このページでは、Neboが現在読み込むすべてのフィールドと、それぞれの役割を列挙します。

トップレベルのフィールド

フィールド種類必須意味
idstringはいプラグインのマーケットプレイスでの識別子。開発中はスラッグを使ってください。
slugstringはい安定した識別子。[a-z0-9-]で最大64文字、先頭・末尾のハイフンや連続したハイフンは不可。plugin__<slug>ツールと<SLUG>_BIN変数の名前になります。
namestringはい表示名。接続先のサービスの名前を入れてください。
versionstringはい0.1.0のようなセマンティックバージョン。
platformsmapはいプラットフォームのキーからバイナリへの対応。「プラットフォーム」を参照してください。
descriptionstringいいえ人と社員に向けた1文。
authorstringいいえパブリッシャー名。
categorystringいいえ社員がプラグインを見つけやすくします。
triggers文字列のリストいいえプラグインが当てはまる場面を表す言葉。検索のヒントに使われます。
entrySkills文字列のリストいいえプラグインのツールの説明で最初に挙げる、同梱のスキル。
dependencies{name, version, optional}のリストいいえこのプラグインが実行する他のプラグイン。versionのデフォルトは"*"、optionalのデフォルトはfalseです。それぞれの<SLUG>_BINパスが、すべての呼び出しで設定されます。
authobjectいいえサインインとアカウント。「認証」を参照してください。
capabilitiesobjectいいえconfigSchema, hooks, commands, routes, providers.
permissionsobjectいいえ環境のフィルタリングとタイムアウトの上限。
eventslistいいえ社員のワークフローにデータを送る監視役。
interfaceBindingsmapいいえプラグインが提供する型付きの操作。
channelobjectいいえメッセージングサービスへの常設のブリッジ。
setupobjectいいえステップごとのセットアップウィザード。

Neboはマーケットプレイスからのインストールを検証します。スラッグのルール、セマンティックバージョン、1つ以上のプラットフォーム、パス区切り文字や..を含まないbinaryName、auth.typeがenvでない限りloginコマンド、空でないイベント名とコマンド、そして解析できるバインディングのテンプレートです。ユーザーのpluginsディレクトリにあるプラグインは検証をスキップします。

プラットフォーム

キーはdarwin-arm64、darwin-amd64、linux-arm64、linux-amd64、windows-arm64、windows-amd64です。各エントリーは、下の5つのフィールドをすべて持ちます。公開するとマーケットプレイスが実際のハッシュ、サイズ、署名、ダウンロードURLを書き込むので、アップロードするファイルでは空欄にしておいてください。

"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バイト単位のサイズ。
downloadUrlNeboがパッケージをダウンロードする場所。

認証

フィールド意味
typeoauth_cliはプラグインが実行するブラウザでのサインイン、envは値として入力する認証情報、neboaiは_TOKENで終わるすべてのauth.envキーでオーナーのNeboAIトークンを受け取るためのものです。
env変数名からデフォルト値への対応。Neboがloginに渡す認証情報の名前も、これに限られます。
commands.loginサインインします。typeがenvでない限り必須です。アカウントのフォルダを設定した状態で実行されます。
commands.statusアカウントがサインイン済みかどうかを示すJSONを出力します。
commands.refresh操作なしでトークンを更新します。
commands.logoutサインアウトします。実行できるのはオーナーだけです。
profileDirEnv社員とアカウントごとに別々の認証情報フォルダを受け取る変数。これがない場合、プラグインは共有のアカウントを1つだけ保持します。
label, description接続カードに表示するテキスト。
help接続中に表示される{url, urlLabel, text}。
publicRedirectプロバイダーがhttp://localhostへのリダイレクトを拒否する場合にtrueを設定します。その場合、サインインはNeboAIの公開リダイレクトを経由します。

Neboは、ステータスの出力にあるauthenticated、isAuthenticated、logged_in、loggedIn、token_validのうち最初のものを読み取ります。空でないtoken_error、またはcredential_source、auth_method、storage、statusの値がnoneの場合は、サインアウト状態を意味します。ステータスコマンドの制限時間は45秒です。

{"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の選択肢。

permissions

フィールドデフォルト意味
envAllow[]プラグインが参照できる、引き継がれた変数。空の場合はすべて許可されます。
envDeny[]常に取り除かれる、引き継がれた変数。
maxTimeoutSeconds300すべての呼び出しのタイムアウトの上限。
networkfalseネットワークの利用を宣言します。参考情報であり、強制はされません。

events

イベントとは、長時間動き続ける監視役です。社員のワークフローがそれを監視するとNeboが起動し、終了すると再起動します。監視役がstdoutに書き出す1行が1つのイベントです。イベント名には実行時にスラッグが前に付くので、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スラッグを除いたイベント名。必須。
command監視役を起動する引数。必須。{{key}}は社員の入力値で置き換えられます。
descriptionイベントが起きるきっかけ。
multiplexedtrueの場合、1つの監視役が複数の種類のイベントを発行し、各行が"event"フィールドを持ちます。

ワークフローはwatchトリガーでイベントを購読します。トリガーをご覧ください。

interfaceBindings

バインディングは、インターフェースの操作をあなたのコマンドの1つに対応づけます。各バインディングは社員向けの型付きツールになり、操作名を小文字にし、ドットとハイフンをアンダースコアにした名前が付きます。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}フィールドの値を1語として。そのフィールドはフラグとしては渡されません。
{field[]:--flag}リストのフィールドの各項目について、--flag <item>のペアを1つずつ。
{field?:--flag}フィールドがある場合は--flag <value>、ない場合は何も出力しません。
{field:cents->dollars}セント単位の整数の金額を、ドルで表記したもの。

テンプレートで指定していない入力フィールドは、--field valueとして末尾に追加されます。リストと任意のプレースホルダーは、1語全体である必要があります。承認が必要な操作に、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 を返すと、後続のフックは実行されません。エラーやタイムアウトの場合は直前のペイロードが維持され、ターンがブロックされることはありません。3回連続で失敗したフックは5分間停止されます。

フィールドデフォルト意味
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が直接実行されます。その出力が返信になります。制限時間は30秒です。

routes

ルートは、ボット上の/api/v1/plugins/<slug>/api/<path>へのHTTPリクエストに応答し、pathとmethodで照合されます。リクエスト本文はstdinに渡され、stdoutの出力がレスポンスになります。制限時間は30秒です。

providers

プロバイダーは、チャットモデルの提供元を追加します。id、displayName、providerType、modelsCommand、chatCommandを宣言します。NeboはチャットのリクエストをchatCommandのstdinにJSONで送り、ストリーミングされるイベントを改行区切りのJSONとしてstdoutから最大300秒間読み取ります。現在使われているのはチャットのストリーミングだけです。

channel

チャンネルは、メッセージングサービスとの橋渡しをします。Neboはcommandを動かし続け、受信メッセージをそのstdoutから読み取り、返信をそのstdinに書き込みます。どちらも改行区切りのJSONです。

フィールドデフォルト意味
command必須ブリッジを起動する引数。
name, description""設定に表示されます。
restartDelaySecs5クラッシュ後、再起動するまでの待ち時間。
sharedfalseすべての社員に共通の1つのブリッジ。メッセージは社員名で振り分けられ、返信には各社員の身元が付きます。
needsLocalApifalseブリッジにボットのローカルAPIアドレス、トークン、社員IDを渡します。必要な場合を除きオフです。

setup

セットアップウィザードは、1つのフォームでは扱いきれない手順をオーナーに案内します。form ステップの値は、後続の generate 引数の {{key}} に入ります。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があります。