プラグインを配布する

Git リポジトリやフォルダでプラグインを共有し、バージョンを付け、Agentty が変わっても動き続けるようにする方法。

中央のレジストリはありません。プラグインはマニフェストの入ったフォルダなので、配布とはそのフォルダを人が入手できる場所に置くことです。

Git リポジトリで共有する#

agentty-plugin.json をリポジトリの直下に置きます。利用者は自分で作る → Git からインストールに https:// の URL を貼り付けます。

text

your-plugin/
├── agentty-plugin.json
├── main.mjs
├── agentty-plugin.mjs     同梱した SDK
├── README.md
└── LICENSE

Important

SDK と必要な node_modules を含め、動作に必要なものをすべて同梱してください。 Agentty は npm install を実行せず、エントリポイントをそのまま起動します。依存関係が欠けたプラグインは利用者の環境でモジュールが見つからず、ログにエラーを残して失敗します。

できるだけ依存関係のないコードを書いてください。SDK 自体に依存関係がないのも同じ理由です。

フォルダで共有する#

フォルダからインストール… はフォルダを ~/.agentty/plugins/ にコピーします。正しい名前のフォルダに展開される zip も同じように使えます。フォルダ名はマニフェストの id と一致している必要があります。

バージョン#

version は major.minor.patch です。Agentty はこれをカードに表示し、内蔵プラグインの新しいバージョンが同梱されたときに更新を提示するのに使います。

Git やフォルダから入れたプラグインは、利用者が入れ直して更新します。その手順を README に書き、マニフェストの links が変更履歴を見られる場所を指すようにしてください。

apiVersion はどのプラグイン API を基準に書いたかを示し、現在は 1 です。新しい数字を闇雲に追わず、実際に試したバージョンを書いてください。

役に立つ README#

ストアカードには description と最大 6 件の links が表示されます。それ以外に必要なことは README に書きます。

何と連携するか、動かすには何が入っている必要があるか
どの権限を求め、その理由は何か — 書けるもっとも有用な 1 行です
何をどこに保存するか
問題をどこに知らせればよいか

他のアプリと連携するなら、カードが検出状況を示せるように宣言してください。

json

{
  "requires": {
    "name": "Cosmica",
    "url": "https://www.cosmica.ink/",
    "note": "Needed to read and write notes"
  },
  "detect": ["~/Applications/Cosmica.app", "/Applications/Cosmica.app"]
}

detect が一致すると、その利用者にはカードがおすすめと表示されます。

配布前のテスト#

開発用にフォルダをリンク… は作業中のコピーからプラグインを実行するので、入れ直さずに編集して再起動を押すだけで済みます。
カードのログは stderr、プロトコルエラー、クラッシュ、終了コードを表示します。
テストハーネスから直接動かしてください。stdin の JSON 行を読み stdout に書く普通のプログラムなので、initialize と試したい通知を送り、返ってくる内容を検証できます。
実際に宣言した権限で試してください。権限のない呼び出しは -32001 で失敗しますが、開発中に余分な権限を持っていると見落としがちです。
両方のテーマと長いパネルを確認してください。パネルは幅 360px でスクロールします。

動き続けるようにする#

shutdown を処理して終了してください。1.5 秒後も生きていると強制終了されます。
プロトコルのメッセージ以外を stdout に書かないでください。plugin.log(...) か console.error(...) を使います。
コンテキストのすべての項目を省略可能なものとして扱ってください。何が入るかは権限とウィンドウの状態が決めます。
今後のバージョンで新しい UI 要素やコンテキスト項目が増えることがあります。知らないものは失敗させず無視してください。

内蔵プラグイン#

Agentty に同梱されるプラグインはアプリケーションと一緒に更新され、連携先のアプリが入っていればカードにおすすめが付きます。作ったプラグインがここにふさわしいと思ったら、何をするもので誰のためのものかを説明して Agentty のリリースリポジトリに issue を立ててください。