Hermes Agent Wiki 非公式・日本語wiki

プラグインカタログへの登録申請

目次

プラグインカタログは、人の手でレビューされた Hermes プラグインの一覧です。掲載されていること自体が信頼の目印になります。ユーザーは カタログのプラグインを名前でインストールし、そのときに入るのはメンテナーが読んだのと同じコミットです。 このページには、プラグインを掲載してもらい、掲載され続けるためのガイドラインをすべてまとめています。

登録ルールの正本は、リポジトリにある plugin-catalog/README.md です。下のルールの節はその内容を一語一句そのまま写したもので、 両者が食い違うとテストが失敗してビルドが通らなくなります。

申請する前に

  • 公開リポジトリであること。 repo の URL は、誰でもクローンできる https:// の URL

（GitHub または GitLab）にします。

  • 固定するコミットで読み込めるプラグインであること。 ツリーには plugin.yaml

マニフェストに加えて、Hermes が読み込むエントリーポイントが少なくとも1つ必要です。__init__.py（Python）、 desktop/plugin.js（Desktop）、plugin.json（ポータブルな Agent Plugin）、 dashboard/manifest.json（Web ダッシュボード）のいずれかです。プラグインがモノレポの中にある場合は、 subdir でそのディレクトリを指定します。構成については プラグイン開発者ガイドで説明しています。

  • 公開されている接続面だけを使うこと。 Hermes の拡張は、フック、ミドルウェア、

ctx.register_* API、プロバイダープラグイン、 Desktop プラグイン SDK を通して行います。Hermes の コードや Desktop のマークアップを実行時に書き換えてはいけません。必要なフックが無い場合は、 フックを依頼するを参照してください。

  • 手元で検証が通ること。 カタログの CI が走らせるのと同じチェックを、

固定しようとしているコミットをチェックアウトした状態で実行します。

hermes plugins validate /path/to/your-plugin --install-deps

このコマンドが調べるのは、マニフェストと requires_hermes、プラグインが読み込めるか、 宣言した capabilities が実際に登録されるものと一致するか、config_schema と requires_env、Python の依存関係が Hermes のコアの制約に収まるか、 インストール時のセキュリティスキャン、そして desktop surface と no core override の ルールです。PR を出す前に失敗はすべて直し、警告にも目を通してください。 レビュアーも読みます。

PR を出す

  1. NousResearch/hermes-agent に、

ファイルを1つだけ、plugin-catalog/<name>.yaml として追加します。 各フィールドの説明は README の エントリーのスキーマ と掲載項目の中身にあります。 sha は40文字の完全なコミットで固定し、version は引用符で囲みます。

  1. PR の説明には、プラグインが何をするか、Hermes のどの接続面を使うか、

そしてルール13で開示を求められている事項をすべて書きます。UI があるものには スクリーンショットを付けます。

  1. カタログの CI ジョブが成功するのを待ちます。このジョブは固定したコミットでリポジトリをクローンし、

hermes plugins validate を実行します。

  1. メンテナーが固定されたツリーをレビューし、マージするか、修正を求めるか、

お断りします。ルール3とルール9に関わる問題は、バグ修正の依頼ではなくお断りになります。 掲載するには、プラグインの設計そのものを変える必要があるからです。

/docs/plugins/<name> にできるプラグインのページは、同じファイルから作られます。 既定では固定したコミットの README がそこに表示され、screenshots: がギャラリーを 埋めます。別に管理する掲載情報はありません。

登録ルール

<!-- admission-rules:start (mirrored in website/docs/developer-guide/plugins/catalog-submission.md; tests/website/test_catalog_rules_mirror.py keeps them identical) -->

  1. 人がマージする関門。 掲載項目の追加は、hermes-agent リポジトリへの PR を

メンテナーがレビューしてマージする方法*だけ*で行われます。 自分で登録できるレジストリも、自動の取り込みもありません。

  1. SHA の完全な固定は必須です。 すべての掲載項目は、40文字の完全な

コミット SHA で固定します。ブランチ、タグ、短縮 SHA はローダーが拒否します。 インストール時にはリポジトリをクローンし、まさにそのコミットをチェックアウトします。

  1. 自己更新するコードは不可。 掲載されたプラグインは、自分のファイルを取得して

置き換えてはいけません（アプリ内の「アップデートを確認」、署名付きリリースのダウンローダー、 リモートの plugin.js ローダーなど）。SHA の完全な固定*こそ*が信頼の仕組みであり、 自己更新の仕組みがあると、インストール済みのコピーが誰もレビューしていないコミットへ移れてしまいます。 更新がユーザーに届く経路は、ここでの SHA 更新 PR と hermes plugins update <name> だけです。更新の仕組みが欲しい場合は、単体配布版に残し、 カタログ向けのビルドからは外してください。

  1. SHA の更新は新しい PR で。 掲載項目の固定先を更新する PR は新しい PR として扱われ、

その差分（旧 SHA → 新 SHA）はほかの変更と同じように改めてレビューされます。レビュアーは、 取り込まれる上流のコミット範囲に目を通すことになっています。

  1. 申請者は所有者か主要な貢献者、またはメンテナーによる一括収録。

掲載項目を申請できるのは、プラグインのリポジトリの所有者か、その主要な 貢献者です。第三者のリポジトリを通りすがりに申請したものはお断りします。 Hermes のメンテナーが、コミュニティのプラグインをレビューしたうえで まとめて掲載項目を追加することもあります（すべての固定先を固定したコミットで検証・スキャンし、 自己更新の仕組みと認証情報の保存先のチェックを行い、UI は英語を基本とします）。 一括収録された項目の作者も主導権を持ち続けます。所有者からの、自分の項目を調整または 削除する PR は依頼に応じて受け付けます。SHA の更新は、ルール4のとおり 所有者かメンテナーの PR で行います。

  1. 宣言した機能は実態と一致しなければなりません。 capabilities: ブロック

（ツール、フック、ミドルウェア、環境変数）は、固定したコミットでプラグインが実際に 登録するものと一致している必要があります。一致しない場合、検証でその項目は不合格になります。 宣言していない機能が増えていくことは、セキュリティ上の問題として扱います。

  1. 登録時にインストールスキャナーが走ります。 hermes plugins validate には

security scan チェックが含まれます。dangerous が出た項目は不合格になり、caution の指摘は CI のログに警告として表示され、レビュアーがマージ前に読みます。 その代わり、固定した SHA でのインストールでは、caution は確認なしで受け入れられます （dangerous は引き続きブロックされます）。警告は確認し、見過ごしたままマージしないでください。

  1. Desktop プラグインは SDK の範囲内にとどめます。 desktop/plugin.js は

Desktop のレンダラー内で、アプリと同じ全権限で動きます（ローダーが隔離するのは エラーであって、権限ではありません）。そのため掲載されるものはプラグイン SDK しか使えません。 プロトタイプの書き換え（X.prototype.y =、Object.defineProperty(...prototype）は禁止、 eval/new Function も禁止、import() で読み込めるのは @hermes/plugin-sdk / react だけです（アプリのバンドルのチャンク、blob や http の URL も対象）。script タグの 注入も禁止で、アプリ内部のストアや、アプリ自身のマークアップに手を伸ばすことも禁止です （コアの UI のスタイルを変える、隠す、クリックする、書き換える目的で、document から data-slot / data-tour / data-sidebar / data-testid の要素を取得することや、document.body の MutationObserver を使うこと）。 hermes plugins validate は登録時にこれらを拒否します（desktop surface チェック）。 SDK に無い機能が必要なプラグインは、回避策で書き換えるのではなく SDK のフックを依頼してください。

  1. Hermes のコアを実行時に上書きしないこと。 掲載されるプラグインが Hermes を拡張できるのは、

公開されている接続面だけです。フック、ミドルウェア、プロバイダープロファイル、その他の register_* API、そして Desktop SDK のスロットとルートです。コアの関数、メソッド、 モジュールの属性、内部の辞書を、その場で置き換えたり、包んだり、差し替えたりしてはいけません （AIAgent.<method> = ...、setattr(server, ...)、 sys.modules[...]、コアのモジュールのテーブルへの書き込み）。同じ継ぎ目を2つのプラグインが 書き換えると、互いに気づかないまま壊し合い、コアのリリースのたびに両方が 壊れるおそれがあります。hermes plugins validate は登録時にこれらを拒否します（no core override チェック）。また、ドキュメントに載っていないコアのモジュールを import している箇所があれば、 その1つごとにファイルと行を示して警告します（警告だけで、不合格にはしません）。 必要なフックが無い場合は、その内容を書いた issue を立ててください。 書き換えを掲載するより、継ぎ目を追加するほうを選びます。

  1. 依存関係のセキュリティ方針はプラグイン側が持ちます。 Hermes の3日間の

exclude-newer による公開からの経過日数の検査が対象にするのは、Hermes 自身の依存関係だけで、 それも Hermes が依存関係をロックする時点に限られます。プラグインの python_dependencies / pyproject.toml は、プラグイン側の方針でインストールされます （公開からの経過日数の検査はありません）。ただし、Hermes 本体の制約の範囲内です。Hermes が厳密に固定した バージョンは動かせません。レビュアーは 固定した SHA での依存関係の一覧を読みます。下限だけの指定（上限の無い >=X）や、 最新リリースを下限にした指定には、API 互換を保てる最も古い下限と上限を付けるよう 依頼します。また作者には、自分でもリリースの隔離期間を設けること（CI で uv --exclude-newer を使う） を強くおすすめします。開発者ガイドの *Dependency security policy* を参照してください。 下限が新しいというだけでは、掲載を保留する理由になりません。

  1. 認証情報は Hermes を通して受け取り、ファイルからは決して読みません。 プラグインが

秘密情報を受け取るのは、Hermes が用意した経路からだけです。宣言した requires_env と config_schema の秘密情報は agent.secret_scope.get_secret(NAME) で読みます。 この関数は有効なプロファイルに従います（os.environ を直接読むと、複数のプロファイルを 同時に動かしているときに、別のプロファイルのキーを拾うことがあります）。サブスクリプションの サインイン（現時点では Codex / ChatGPT）は、requires_auth を付けた credentialed_provider_request を通してだけ使います。こうすると Hermes がトークンを付けて送るので、 プラグインがトークンを手元に持つことはありません。プラグインは .env ファイル、Hermes の auth.json、 ほかのツールのログイン情報（ベンダーの CLI のトークンファイル、ブラウザのプロファイル、キーチェーン）、 そのほかの認証情報の保管場所を直接読むことはなく、OAuth トークンを更新、ローテーション、 書き込みすることも、ほかのベンダーのクライアントとして振る舞うこともしません。プラグインに必要な 認証情報の経路が Hermes に無い場合は、Hermes の issue か PR で用意を求めてください。 プラグインの側で回避策を作ることはしません。

  1. 承認と無人実行を尊重します。 プラグインは Hermes の承認の仕組みを

迂回してはいけません。自動承認や、ガードの無効化は禁止です。YOLO や非対話モードを 引き継ぐ Hermes やシェルの子プロセスを起動して、誰も承認していないコマンドを実行することも禁止です。 人を待つもの（確認のプロンプト、ブラウザでの OAuth の流れ）は、cron、メッセージング ゲートウェイ、その他の無人実行のもとでは、エージェントを止めたままにせず、きれいに失敗するかタイムアウトします。

  1. リスクのある挙動は開示します。 ユーザーがインストール前に知っておきたいことは、

PR の説明とプラグインの README に書きます。第三者のサービスへの ネットワーク通信、プラグイン自身のデータ以外の読み取り、シェルコマンド、 長時間動き続けるバックグラウンドプロセス、保存される認証情報などです。テレメトリーや利用状況の 送信は、ユーザーが有効にしたときだけ行います。レビュアーはこれらを、掲載項目の PR に開示事項として要約します。レビューで開示されていない挙動が見つかった場合は、修正を依頼します。

  1. 互換性のメタデータは正確に書きます。 requires_hermes は SemVer の下限

（">=0.21.5"）で書き、CalVer の日付にはしません。また現在のリリースより新しい値にもしません （そうなっているとローダーがプラグインを読み飛ばします）。version は固定したコードと一致させ、 Python の依存関係は Hermes のコアの制約のもとで解決できるようにします （CI が実行するのは hermes plugins validate --install-deps です）。

  1. 同梱プラグインのスキンやフォークは掲載しません。 同梱プラグインへの変更は

hermes-agent への PR として出すもので、競合する掲載項目にはしません。また、ベンダーに似せたスキンを Nous のブランド名のもとで掲載することもありません。

  1. 1つのプラグインの系譜につき掲載は1件です。 掲載済みのコミュニティプラグインのフォークは、

元のプラグインと実質的に異なる場合にだけ掲載します。たとえば、通信方式やアーキテクチャが違う場合や、 元のプラグインにない機能を備えていて、その機能を元の作者が断ったか、PR に30日間応答していない場合です。 掲載済みプラグインへの改善は、その作者への PR として上流に出します。名前の変更、ブランドの付け替え、小さな変更を 加えただけのフォークは、元のプラグインを優先して掲載を見送ります。掲載されたフォークは、開示行に由来を 明記します（Derived from <entry>）。

  1. スキャンできない実行ペイロードは含めません。 レビュアーとインストール時のスキャナーが、固定したコミットで

読むものはすべて、読めるソースでなければなりません。プラグインには、コンパイル済みのバイナリ（どの OS 向けでも、 ネイティブの実行ファイルやライブラリ。拡張子ではなくファイルヘッダーで判定します: ELF、Mach-O、PE/MZ、 WebAssembly）、コミットされた Python バイトコード（.pyc/.pyo。隣の .py の代わりに実行される、ソースなしの キャッシュやハッシュを偽装したキャッシュも含みます）、中身がレビューできるソースではないアーカイブを含めてはいけません。 プレーンテキストのソースをまとめたもの（プラグインが展開する、.py/.ts/.md の .tar.gz）は、 ほかのソースと同じように読みます。バイナリを隠したアーカイブは認めません。スキャナーは機械語を読めませんし、 同じコミットに含めたチェックサムが証明するのは、そのコミット以降にファイルが変更されていないことだけで、 どこから来たファイルかは証明できません。プラグインにどうしてもネイティブのコンポーネントが必要な場合、そのバイナリは、 プラグインのリポジトリ自身の公開 GitHub Actions が同じリポジトリのソースからビルドし、そのワークフローとコミットに 結びつける GitHub のビルド証明（actions/attest-build-provenance）を付けたものに限ります。ゲートは、その証明を 固定したコミットと照合します（gh attestation verify --repo <owner/repo> --source-digest <pinned sha>）。ユーザーの端末がセットアップ時に取得するバイナリは、上流ツールの公式な配布元から取得し、 チェックサムで固定し、開示している（ルール13）場合にだけ認めます。同梱することも、非公式のミラーから取得することも認めません。 <!-- admission-rules:end -->

掲載項目を更新する

固定先の更新（sha を新しいコミットへ進めること）も、同じ PR とレビューの 流れを通ります。レビュアーは、取り込もうとしているコミット範囲を読みます。同じ PR で version も 上げて、ユーザーに見える表示がコードと一致するようにしてください。また、古い sha を含んでいる image / screenshots の URL も、固定し直してください。

インストール済みのプラグインは、記録している sha を現在の固定先と比べます。 hermes plugins list --json は update_available を返し、Desktop の Plugins タブには Update to 1.4.0 ボタンが表示されます。hermes plugins update <name> を実行すると、 新しい固定先をそのままチェックアウトします。

メンテナーがプラグインをカタログに一括収録していて、その項目を 変更または削除してほしい場合は、そのファイルに対して PR を出してください。項目の主導権は所有者にあります。

掲載の取り下げと削除

  • 掲載の取り下げは、掲載項目のファイルを消すことです。対象は、メンテナンスされていないもの、

後継に置き換わったもの、名前を占有しているだけのもの、ルールを満たさなくなったものです。 すでにプラグインをインストールしたユーザーはそのまま使い続けられ、問題が直れば再掲載も 歓迎します。新しいルールがすでに掲載中のプラグインに影響する場合は、 作者のリポジトリに変更を説明する issue を立て、何かを削除する前に更新のための 時間を設けます。

  • 削除は、プラグインを

removed.yaml に追加することです。このリストはセキュリティやポリシー上の問題が起きたときのためのものです。インストーラーは このリストにあるものを拒否し、インストール済みのコピーは更新されなくなり、有効にすることも できなくなります。

フックを依頼する

プラグインの接続面に無い機能が必要な場合は、 hermes-agent に issue を立て、 何が必要で、なぜ必要なのかを書いてください。書き換えを掲載するより、きちんとした継ぎ目を 追加するほうをずっと好みます。そのフックを使うプラグインは、新しいフックに必要な具体的な 利用者そのものです。