サインインブリーフィングを予約

第 2.18 章

拡張モデル

設定からドメインパックまで Nexus を拡張する6つの方法、それぞれの制限、および信頼レベルと分離レベルがコードの実行場所をどのように決定するかについて説明します。ソフトウェア開発キット(SDK)を開く前に必ずお読みください。

このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

読了時間 16 分

私がCorrán OrbitalでNexus上に初めて構築したものは、プラグインではありませんでした。当社のフライトダイナミクスチームは、「Svalbardアンテナがメンテナンスで停止した場合、どの地上局のパスが失われるか?」という質問に対し、アシスタントが毎回同じ形式で、最初にパスの表を、その下に通信時間(分)でのコストを示して回答することを求めていました。私は半日かけてソフトウェア開発キット(SDK)を読み込みましたが、同僚から、私が必要としているのはスキル、つまりSKILL.mdを含むフォルダーであり、それをSkills Engineにアップロードし、テストに合格してレビュアーが承認すれば公開されるものだと指摘されました。それにかかった時間は40分でした。

2つのプラグインと1つのドメインパックを構築した今でも、私が最初に伝えるアドバイスは変わりません。Nexusを拡張する方法は6つあり、それらは労力の段階(ラダー)に並んでいます。負荷の低い段階は人々の予想以上に多くのことができ、負荷の高い段階には過小評価しがちな義務が伴います。この章では、その段階について説明します。目的を果たせる最も低い段階を選んでください。続く各章では、それぞれについて詳しく解説します。第2.19章「すべての拡張機能が継承するルール」、第2.20章「スキル」、第2.21章「Plugin SDK」、第2.22章「プラグインランタイム」、そして第2.23章「ドメインパック」です。

6つのビルディングブロック

検討すべき順序でそれらを以下に示します。

  1. 設定とポリシー。これらは、管理者がライセンスの許容範囲内で、組織、ユニット、または個人のためにコンソールで設定する値です。コードを記述する必要は一切ありません。
  2. Skills Engineスキル。指示とスキルが呼び出すことのできるツールを保持し、オプションのファイルやスクリプトを伴うSKILL.mdパッケージです。アシスタント、エージェント、ワークフロー、および画面上のAI(人工知能)ボタンはすべて同じスキルを実行し、お使いのIDE(統合開発環境)も同様です。
  3. プラグイン。マニフェストによって宣言され、SDKのツールでビルドされる独自のコードです。プラグインには、skills-only、ui-only、またはfull-serviceの3つのティアのいずれかがあります。
  4. ドメインパック。ある業界のレンズとテンプレート、そのスキルとナレッジモデル、コネクタ、およびスマートフォン画面であり、1つの単位としてライセンス供与されます。Adverantは10個を提供しており、独自に構築することも可能です。
  5. レンズ。パックまたはプラットフォーム内で1つのロールに表示される内容です。レンズはベースレンズを絞り込むものであり、広げることは決してありません。
  6. MCP接続とコネクタ。プラグインが公開する、またはAIコーディングツールが接続に用いるModel Context Protocol(MCP)ツール、および稼働中の既存システムからレコードを取り込む読み取り専用コネクタです。

2つの言葉が重複して使われがちなので、ここで明確にしておきます。Skills Engineスキルは、ライブラリ内のSKILL.mdパッケージです。マニフェストスキルは、プラグインのskills[]配列内の型付き行であり、プラットフォームのスキルレジストリにコンパイルされ、ワークフローエンジンであるUNOを介して実行されます。画面上ではどちらもスキルと呼ばれます。これらは記述方法もガバナンスも異なり、このドキュメントでは常にどちらを意味しているかを明記します。

新しいプロジェクトを開始
新しいプロジェクトを開始
「新しいプロジェクトを開始」では、拡張機能の種類ごとに1つずつ、計6つのゴールデンパスが提供されます。それぞれが、必要なものを宣言するマニフェストを備えたバージョン管理されたテンプレートからリポジトリを作成し、テスト、開発スペース、およびデータブランチをセットアップします。

それぞれができること、できないこと

この表は簡略版です。「できないこと」の列は意図的に入れてあります。各制限は設計上の特性であり、その一つひとつが私を何らかのトラブルから救ってくれたからです。

ビルディングブロック できること できないこと 作成者
設定またはポリシー 組織から個人までのあらゆるレベルで機能の動作を変更する、値をロックする、下位に委任する、変更時に2人目の承認を求める 画面やルートを追加する、新しいテーブルを保存する、または新しい種類の処理を開始する 管理者(コンソール内)
Skills Engineスキル アシスタントやエージェント、ワークフロー、AIボタンに対し、独自の指示とテストケースを用いて1つのジョブを反復可能な方法で実行させる 認証情報を保持する、実行者の許可リスト外にあるツールを呼び出す(SKILL_CANNOT_WIDEN_TOOLS)、テストと承認なしに本番稼働させる 権限を持つすべての人(クリエイター内または自身のIDEから)
プラグイン、skills-only プラットフォーム上で実行されるマニフェストスキルを公開する:ホストコールバック、キューに入れられた処理、リストに対するマップ処理、およびトラストcoreまたはverifiedでのモデルを活用したスキル 独自のページを提供する 開発者(SDKを使用)
プラグイン、ui-only シェル内にフロントエンドサーフェスを追加する 独自のデータを保存する、またはコンピュートを実行する 開発者(SDKを使用)
プラグイン、full-service 独自のバックエンドとフロントエンド、Postgresスキーマ、権限付きのルートテーブル、およびスキルとMCPツール モデルプロバイダーを呼び出す、モデルキーを保持する、記録された付与を介さずに他の組織の行を読み取る、UNOディスパッチ外でコンピュートを実行する 開発者(SDKを使用)
ドメインパック 業界のレンズとテンプレート、スキルとワークフロー、ナレッジモデル、エビデンスマップ、およびスマートフォン画面を、管理者が選択したユニットに導入する シェルやそのコンポーネント、または記述ルールを変更する、組織のライセンスに含まれていない状態で実行する Adverant、またはEnterprise上の貴社独自の開発者
レンズ パックまたはプラットフォーム内で1つのロールに表示されるカードとフィールド、および提供するアクションを選択する ベースレンズが非表示にしているものを表示する(LENS_CANNOT_WIDEN)、ロールが実行できる内容を変更する パック作成者が構築し、管理者がユニットごとに付与する
MCPツールとコネクタ プラグインのツールをエージェントやコーディングツールに公開する、ポリシーシステムやテレメトリアーカイブからナレッジモデルにレコードを読み取る コネクタを介してソースシステムに書き戻す、サインインしているユーザー自身の権限を超えて動作する 開発者がMCPツールを宣言し、管理者がコネクタをセットアップする

これらのセルのいくつかについては、もう少し補足する価値があります。

設定はフレームワークであり、すべてのプラグインが同じものを使用します。マニフェストでsettingsブロックを宣言するプラグインは、設定テーブルを記述することなく、レベル(プラットフォーム、組織、パック、ユニット、グループ、リポジトリ、個人)、ロックと委任、変更ログ、および2人目の承認をすべて取得します。最も負荷の低い段階で十分であることが多い理由はここにあります。必要な動作がすでに存在し、Rotterdamユニット向けに別の値が必要なだけであれば、それは設定で対応できます。

Skills Engineスキルは、そのユーザー自身として実行されます。キーを保持することは決してなく、実行者の許可リスト内にあるツールにのみ到達でき、そのユーザーが開くことのできるものだけを読み取ることができます。書き込みを行うツールを追加するスキルは、2人が承認するまで保留され、その後シャドウ、カナリア、そして全員の順で本番稼働します。

skills-onlyプラグインは中間の段階です。決定論的な計算、キューワーカー、リストに対するファンアウトなど、処理が独自に所有するコードである場合に必要になります。プラットフォームが貴社のコードを呼び出すのであり、貴社のコードがモデルを呼び出すことは決してありません。

full-serviceプラグインは小さな製品です。Postgresスキーマ、権限レジスタ付きのルートテーブル、フロントエンド、一連のデータベースロール、および第2.19章「すべての拡張機能が継承するルール」にあるすべての分離義務を所有します。これは、人々が恐れている以上に正しい選択であることが多く、人々が期待している以上に間違った選択であることも多いものです。

どれが必要ですか?

この表の一番上から始めて、条件に合う最初の行で止まってください。

やりたいこと… 使用するもの より軽量なものではだめな理由
値や制限、または誰が何を実行できるかを変更する 設定またはポリシー これより軽量なものは存在しないため
アシスタントに1つのジョブを毎回同じ方法で実行させる Skills Engineスキル 設定は指示を保持できないため
そのジョブを実行する「AIボタン」を画面に配置する ボタンにバインドされたSkills Engineスキル ボタンはスキルのみを実行し、構築すべきものはないため
AIコーディングツールをNexusに到達させる Workbenchを介したMCP接続 記述するものはなく、ユーザーはブラウザーからサインインするため
既存のシステムからナレッジモデルにレコードを読み取る 読み取り専用コネクタ コネクタは何も書き戻さないため、書き込みリスクを伴わない
所有する決定論的コードをプラットフォームのスケジュールで実行する host_callbackまたはplugin_queueスキルを持つskills-onlyプラグイン Skills Engineスキルは独自のコードを実行できないため
シェル内に1つか2つの画面を追加する ui-onlyプラグイン 画面を追加できるのはプラグインのみであるため
独自のルートと権限の背後に独自のレコードを保持する full-serviceプラグイン スキーマを所有するのはこのティアのみであるため
業界の画面のより絞り込まれたビューを1つのロールに提供する 既存のパック上のレンズ レンズはコードではなくデータであるため
業界のナレッジモデルとレンズを、スマートフォン画面とともに複数のユニットに導入する ドメインパック プラグイン単体にはレンズやライセンスゲートがないため

Corrán Orbitalでは、パス計画の質問はSkills Engineスキルのままでした。それに必要な軌道伝播は、1つのhost_callbackスキルを持つskills-onlyプラグインになりました。数値計算は当社独自のものであり、2回実行して同じ答えを出す必要があるためです。当社のアノマリーレビューボードはfull-serviceプラグインになりました。誰がどのテレメトリ逸脱を確認し、何を決定したかという独自のレコードを保持するためです。パックは最後に、2つ目のユニットが同じものを求めたときに導入されました。

各要素の組み合わせ方

ビルディングブロックは上に向かって構成されます。ドメインパックは、他のブロックのバンドルにライセンスゲートを加えたものであるため、最も明確な例です。

  • ナレッジモデル(業界が把握している事物の種類とそれらのリンク方法であり、多くの場合、別のパックのベースモデル上に構築されます)、
  • レンズ(ロールごとに1つあり、それぞれがベースレンズを絞り込みます)、
  • テンプレートとワークフロー、およびそれらが呼び出すSkills Engineスキル、
  • パックが独自のコードを必要とする箇所のプラグイン、
  • すでにレコードを保持しているシステムへの読み取り専用コネクタ、
  • どのカードとキャプチャステップをスマートフォンに表示するかを指定するモバイルオーバーレイ、
  • そしてエンタイトルメント(これらのいずれかが有効になる前にライセンスが保持していなければならない機能グループ)。
水平な帯のスタックを描きます。一番下に「Nexusコア機能」(アシスタント、ファイル、メモリ、ジョブ)、その横に「UNOディスパッチ」と「AI Provider Router」を配置します。その上に、「skills-only」と「full-service」の2つのボックスを持つ帯「プラグイン」、および帯「Skills Engineスキル」を配置します。それらの上に、4つの小さなボックス(「ナレッジモデル」、「レンズ」、「テンプレートとワークフロー」、「モバイルオーバーレイ」)を含む幅広のボックス「ドメインパック」を配置します。パックの左側に、ボックス「読み取り専用コネクタ」を配置し、「ナレッジモデル」へ向かう矢印を引きます。一番上に、3つのユニットボックス(「Rotterdam」、「Felixstowe」、「Head office」)を配置し、パックから下向きに「ロールごとに付与されるレンズ」というラベルの付いた矢印を引きます。パックの端にある南京錠には「ライセンス:domain_packs」というラベルが付いています。
ドメインパックが他のビルディングブロックをバンドルする仕組み。

これらはどれもアプリごとの配管作業ではありません。パックは独自の分離コードも、モデルクライアントも、ライセンスチェックも備えておらず、プラットフォームのものを継承します。それが次の章の主題であり、銀行のパック作成者と港湾のパック作成者が記述するセキュリティコードの量が同じ(つまりゼロ)である理由です。

ドメインパック
ドメインパック
「ドメインパック」ページには、10個のパックすべてが、それぞれに必要なものと実行される場所とともに一覧表示されます。ライセンスに含まれていないパックはグレー表示で一覧に残り、何が必要になるかが示されます。

信頼レベル

すべてのプラグインは、マニフェストでtrustレベルを宣言します。トラストは、SDKが交渉して通り抜けられるゲートではありません。プラグインのコントリビューションをどの程度分離して実行するか、およびそのスキルが触れることのできる最も機密性の高いデータを決定するためにプラットフォームが読み取る、アドバイザリメタデータです。ライブゲート(分類とレジデンシー、エクスポートと支出)は、本来の場所にそのまま留まります。

トラスト 対象となる方 分離ポスチャ 分類の上限
core プラットフォームに同梱されるファーストパーティコード none:同一オリジン、追加の分離なし restricted
verified レビュー済みのサードパーティ、検証済みのパブリッシャー same-originサーフェス、仲介されるスキル restricted
community 未レビューのサードパーティ、新しいプラグインのデフォルト sandboxedサーフェス、仲介されるスキル tenant
untrusted 不明なソースからのすべてのもの strict:サンドボックス化されたサーフェス、仲介されるスキルのみ、ホストトラストなし public

その表から2つのルールが導き出され、create-nexus-plugin validateは何らかのビルドが行われる前にその両方を強制します。

第1に、スキルのclassificationはそのプラグインの上限を超えることはできません。分類はpublic、次にtenant、その次にrestrictedの順でランク付けされます。restrictedスキルを宣言するcommunityプラグインはビルドに失敗します。

第2に、AI Provider Routerに到達するスキルを宣言できるのは、coreおよびverifiedプラグインのみです。それらはtool_usingおよびllm_onlyティアです。communityまたはuntrustedプラグインは、決定論的な処理(host_callback、plugin_queue、およびそれらに対するmap)を仲介し、モデルを必要とする処理はすべてプラットフォームに依頼します。私の最初のプラグインはcommunityでしたが、拒否されること自体が意図されたものであると理解するまで、llm_only要約スキルを宣言しようとして午後の時間を無駄にしました。

trustを省略した場合、SDKはそのプラグインをcommunityとして扱います。省略されたフィールドが昇格になることは決してありません。

分離レベル 1 から 4

トラストとは別に、マニフェストのruntimeブロックはプラグインの実行方法を指定します。isolationLevelは1から4までの整数であり、実行モードはそれに従います。この2つを個別に選択することはできません。バリデーターが一方から他方を導き出し、ペアが一致しないマニフェストを拒否します。

isolationLevel executionMode 意味
1 external_https プラグインはインストールの外部で実行され、HTTPS経由で到達します
2 mcp_container MCPツールを公開するコンテナ
3 hardened_docker プラグイン独自のポッド内の堅牢化されたコンテナ(テンプレートのデフォルト)
4 firecracker マイクロVM、最も強力な分離
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

entrypointは必須です。エントリーポイントは出荷されたアーティファクトであり、実行時にフェッチされることは決してありません。SDKには動的インポートやリモートロードのパスが一切ないため、トラストは書き留められて一度チェックされた後、凍結され、ダウンロードされることは決してありません。

各段階で引き受ける要件

設定より上のすべての段階には、維持するためのコストがかかります。それぞれにかかるコストは以下のとおりです。

  • Skills Engineスキルには、テストケース、あなた以外のレビュアー、および異常動作した際に尋ねられるバージョン履歴が必要です。同じバイト列が2回公開されることは決してないため(CONTENT_HASH_ALREADY_PUBLISHED)、「ただ再アップロードする」ことは修正にはなりません。
  • プラグインには、コードが登録するルートと双方向で一致するルートテーブルを持つマニフェストが必要です。存在するが宣言されていないルートは適合性エラーであり、宣言されているがコードが決して登録しないルートも同様です。
  • full-serviceプラグインは、5つのデータベースロール、すべてのテーブルに強制される行レベルセキュリティ、および境界が機能していることをデータベースが証明するまでリッスンを拒否するブートを備えたスキーマを所有します。また、マニフェスト内で3つのプラットフォーム法則を一字一句そのまま再記述します。
  • ドメインパックはライセンス供与されます。パイロットを通じて一度に1つのユニットずつ有効になり、組織のライセンスがそれを保持している必要があります。顧客がそれを持っているかどうかをあなたが決めることはできません。
  • レンズは取り除くことしかできません。あるロールがより多くのものを表示する必要がある場合は、ベースレンズを変更する必要があり、それにはそのベースの所有者との話し合いが必要になります。

これらのコストはいずれもアプリごとに交渉することはできず、それがトレードオフとなります。最初のプラグインでいくらかの自由を手放し、それ以降のすべてのプラグインでそれを取り戻すのです。

サードパーティプラグインのインストール
サードパーティプラグインのインストール
サードパーティプラグインのインストールは、アプリの権限のように機能します。マニフェストが宣言する各スコープはユニットごとに付与または保留され、宣言していないものに対する呼び出しはCONNECTION_SCOPE_EXCEEDEDで拒否されます。

MCP ツールと接続

MCPは3つの場所に現れ、それらは混同しがちです。

プラグインは、mcpTools[]内で宣言することでMCPツールを公開できます(name、description、およびinputSchema)。バリデーターが追加する唯一のルールは、inputSchemaがトップレベルのoneOf、allOf、またはanyOfを使用できないということです。スキーマのトップにあるコンビネーターは、そのツールをインポートするすべてのMCPクライアントを400エラーで失敗させるためです。isolationLevel 2のプラグインはmcp_containerとして実行されます。

Skills EngineのライブラリにはMCP経由で到達可能です。Claude Codeとエージェントは、13個のMCPツールを使用してスキルを検索および照合し、それらを実行して実行を記録し、作成、インポート、または同期します。各呼び出しは、それを開始したユーザー自身として、その許可リスト内で実行されます。

そして、AIコーディングツールはWorkbenchを介して接続します。インストールごとに1つのアドレス、ユーザーのブラウザーを介したサインイン、保存されたキーの代わりの1時間有効なパス、そしてそのユーザーがチェックを入れたツールのみが使用されます。第2.26章「AIコーディングツールを用いた構築」でその手順を説明します。

コネクタはより静かな隣人です。ドメインパックのナレッジモデルには、契約管理システムや請求システムなどのシステムへの読み取り専用コネクタによってデータが供給され、それぞれにスケジュールとテストボタンがあります。ソースに書き戻されるものは何もありません。

プラグインとMCP同期
プラグインとMCP同期
「プラグインとMCP同期」には、どのプラグインがスキルをもたらすか、どの同期が全体的に拒否されたか、およびClaude Codeとエージェントがライブラリに到達するために使用する13個のMCPツールが表示されます。

ブランチからユーザーの画面まで

どの段階にいても、本番環境へのルートは同じです。すべてのリリースは、開発スペースからステージングへ、次にパイロットユニットへ、そしてすべてのユニットへと移動し、各ステップにはゲート(テスト、広がっていないマニフェスト、マスクされたコピーでのドライラン、および作成者ではない指名されたレビュアー)があります。ステップを飛び越えようとする昇格はGATE_CANNOT_BE_SKIPPEDで拒否されます。各環境は前のバージョンを30日間保持し、1つのユニットのロールバックはレビューを伴う変更であり、約1分で完了します。

デプロイ自体は、インストールのリリースチャネルのみを介して行われます。ユニットは自身のチャネルを選択し、その管理者が各移行に同意します。「チャネルとインストール」ページではユニットごとのカウントとエラー率を確認できますが、誰があなたの拡張機能を使って何をしたかは決して表示されません。第2.28章「拡張機能のリリース」では、リリース側をエンドツーエンドでカバーしています。

エディションに関する注意事項

この段階の大部分は両方のエディションに存在します。Communityでは、設定とSkills Engineスキル、すべてのティアのプラグイン、および独自のGitホストにコードを置く1台のサーバー上での同じゴールデンパスを利用できます。Enterpriseでは、開発スペースからステージングを経てパイロットユニットに至るゲート付きの昇格に加え、パブリッシャークラスターとライブデータのマスクされたコピーが追加されます。また、独自のプライベートカタログとドメインパックも追加されます。詳細については、第2.25章「各エディション向けの構築」を参照してください。

次の章は、コードを書き始める前に読むべき章です。選択肢については短く、ルールについては長く書かれており、そのルールは最初の拡張機能でも1000番目の拡張機能でも同じです。