パッケージのライフサイクル、ホスト、権限
AI Game Devがパッケージを実行する仕組み(Extension Host、遅延アクティベーション、デスクトップとCLI、レベルと更新、エラーとログ、権限、APIバージョニング)を解説します。
このページでは、パッケージがインストールされてから削除されるまでの間に何が起こるかを説明します。コードがどこで実行され、いつ開始・停止され、何が許可され、エラーがどうやって届き、パッケージが対象とするAPIがどう互換性を保つのか。他の人がインストールするパッケージを公開する前に知っておくべき背景です。
パッケージが実行される場所
アプリはパッケージのコードをExtension Hostで実行します。これはVS Codeが拡張機能を実行するのと同じく、別プロセスです。アプリのバックグラウンドサービス(Kernel)は、開いているプロジェクトごとに1つのExtension Hostを実行し、そのプロジェクトを開いているすべてのデスクトップウィンドウとCLIで共有されます。あなたのコードは、メッセージチャネルを介してctx.aigdを通じてのみアプリとやり取りします。
| デスクトップアプリ | gamedev CLI | |
|---|---|---|
| 表示されるUI | すべて: メニュー、パネル、ビュー、カスタムエディタ、ステータスバー、チュートリアル、webview | スラッシュコマンド、Toolsの行、メッセージ、クイックピック、入力ボックス、フォーム、進捗行 |
| デスクトップ専用の呼び出し | 動作 | undefinedまたは不活性オブジェクトに解決され、1回だけログに記録される |
| Extension Hostプロセス | プロジェクトごとに共有 | プロジェクトごとに共有 |
プロジェクトを開いていないウィンドウではホストは実行されません。ユーザーレベルでインストールされたパッケージは、そのプロジェクトが除外していない限り、開いているすべてのプロジェクトで実行されます。
遅延アクティベーション
- インストール。 アプリはマニフェストを読み取り、宣言されたすべてのコントリビューションを一度に登録します。スラッシュコマンド、Toolsスイッチ、メニュー項目、ビューは、コードを一切実行せずに表示されます。
- アクティブ化。 何かがコードを必要とした最初の時点(コマンドの実行、ビューの表示、機能の有効化、対象ファイルのオープン、エンジンプロジェクトの検出)で、ホストは
mainを読み込み、activate(ctx)を呼び出します。依存関係が先にアクティブ化されます。activateの制限時間は30秒です。 - 実行。 ハンドラーがアプリからの呼び出しに応答します。登録したものはすべて
ctx.subscriptionsに入っています。 - 停止。 削除、パッケージの無効化、更新、ホストの再起動の際に、ホストは
deactivate()(任意)を呼び出し、ctx.subscriptionsを破棄します。
mainを持ち、イベントを一切宣言していないパッケージは、最初のレンダリング後に開始されます(onStartupFinished)。イベントの完全なリストはマニフェストリファレンスにあります。
ホストは、アクティブなパッケージの集合が変わったとき、およびクラッシュ後(1秒後、5秒後、30秒後)に再起動します。5分間に3回クラッシュすると、ユーザーがPackagesウィンドウでReloadをクリックするまで停止したままになります。
レベル、ロック、更新
ユーザーは3つのレベルのいずれかでパッケージを追加します:
| レベル | 宣言される場所 | 共有範囲 |
|---|---|---|
| ユーザー | ~/.ai-game-dev/packages.json | このユーザーのすべてのプロジェクト |
| プロジェクト | <project>/.ai-game-dev/packages.json | コミット済み: チームメイト全員に配布される |
| ローカル | <project>/.ai-game-dev/packages.local.json | このコンピューターのみ、コミットされない |
ローカルはプロジェクトに、プロジェクトはユーザーに優先します。各レベルの隣にあるロックファイルが正確なバージョン、tarball、ハッシュを固定するため、チームメイトは同じバイト列をインストールします。自動更新はデフォルトで有効です(パッケージごと、コンピューターごと)。4時間ごとに、アプリは各パッケージを、アプリが実行可能な、宣言された範囲内の最新バージョンへ移行し、その実行全体に対して1件の通知を表示します。file:リンクと、タグに固定されたGitHubソースは自動更新されません。
エラーとログ
ホストはすべての失敗をそのパッケージに帰属させます。activate、deactivate、ハンドラー内でのスロー、あなたのファイルからの未捕捉例外や未処理のPromise拒否、ctx.reportError(err)、ctx.log.error(msg, err)などです。Packagesウィンドウの各パッケージのErrorsタブには「N errors · M crashes」と、スタック付きの最近のリストが表示されます。
gamedev pkg logs acme.level-tools # its last 100 lines
gamedev pkg logs acme.level-tools -f # and every new one until Ctrl+Cログはすべてのプラットフォームで~/.ai-game-dev/daemon/logs/にあります。サードパーティパッケージのエラーがAI Game Devのクラッシュレポートに送信されることはありません。AI Game Dev自身のパッケージだけがそこに報告し、それもユーザーがクラッシュレポートに同意した場合に限られます。
権限と信頼
AI Game DevはVS Codeのモデルに従います。サンドボックスも権限プロンプトもありません。パッケージのコードはユーザー自身の権限で実行され、ユーザーがインストールする他のプログラムと同様に、ファイルの読み書き、プロセスの起動、ネットワークの利用ができます。代わりにユーザーへ情報を提供するのは次の仕組みです:
- すべてを最初に見せる。 パッケージが表示するものはすべてマニフェストで宣言され、コードが実行される前に確認できます。
- 所有権は強制されます。 パッケージは、自分が所有する ID(
<package id>.<local>のコマンド、ビュー、コンテキストキー、<publisher>--<name>のサーバー)しか登録・変更できず、ロード時とすべての呼び出し時にチェックされます。コマンドは、自パッケージのもの、他パッケージのもの、アプリのものを問わず実行できますが、webview ページが実行できるのは自パッケージのコマンドとアプリのコマンドだけです。 - 宣言された内容は表示されます。 インストール前に、Packages ウィンドウにはレジストリインデックスに書かれている内容(ネイティブコード、Claude プラグイン、依存関係)が表示されます。インストール後は、そのパッケージがコードを実行するか、ツールサーバーを起動するか、ゲームエンジンを提供するかも表示されます。これは情報であり、決してゲートではありません。
- レジストリのチェック。 コミュニティレジストリのすべてのバージョンは、認証情報、エージェントを狙ったプロンプトインジェクション、マルウェア、アーカイブの細工について自動チェックに合格しています。詳しくはレジストリのルールとチェックを参照してください。
- 失効。 AI Game Dev は悪意のあるバージョンを失効させることができます。各アプリは次回インデックスを読み込んだとき(およそ30分以内)にそれを無効化します。
- webview ページは分離されています。 ページは Node.js のないサンドボックス化されたフレーム内で動作します。webview ウィンドウにはネットワークアクセスが一切ありません。
作者として:シークレットを同梱せず、パッケージが何をするのかを README とマニフェストから分かるようにし、破壊的なことをする前にはユーザーに確認してください。
バージョニングと互換性
API のバージョンを示す数字は2つあり、どちらもあなたのパッケージの version ではありません:
- パッケージ API バージョン(現在 0.4.0)は追加のみで増えていきます。新しいメンバーやコントリビューションポイントです。あなたの
aigd.d.tsは、それが書かれたバージョンを示します。 - サポートされる最も古い
engines.aigd(現在 0.18.0)は、アプリがまだロードできる最も古い下限です。これを引き上げることが、安定したメンバーが削除される唯一の方法であり、少なくとも2つのマイナーリリースにわたる非推奨警告の後に行われます。
あなたに向けたルール:
engines.aigdには、テストした中で最も古いアプリを設定してください。それより古いアプリはパッケージを拒否し、ユーザーにアップデートを促します。- そのメンバーより古いアプリをサポートしたい場合は、オプションのメンバーをフィーチャーテストしてください(
aigd.gameEngines?、item.pulse?.())。 - proposed メンバーはこのいずれの対象にもなりません。安定版と proposed APIを参照してください。
- 保存されたデータはあなたのものです。
dataVersionでバージョン管理し、activateでマイグレーションしてください。
関連ページ
- 呼び出しについてはパッケージ APIを参照してください。
- レベルとユーザー側からの更新についてはパッケージを参照してください。
pkg logs、link、devについてはパッケージ CLI リファレンスを参照してください。