本頁面由英文機器翻譯而成。閱讀英文原文。

套件生命週期、主機與權限

AI Game Dev 如何執行套件:Extension Host、延遲啟用、桌面版與 CLI 的差異、層級與更新、錯誤與日誌、權限,以及 API 版本管理。

更新於 2026年11月19日 以 Markdown 檢視

本頁說明套件從安裝到移除之間發生什麼事:它的程式碼在哪裡執行、何時啟動與停止、被允許做什麼、錯誤如何傳到你手上,以及它依據撰寫的 API 如何保持相容。這是你發佈一個讓別人安裝的套件之前必須先了解的背景知識。

套件在哪裡執行

應用程式會在 Extension Host(一個獨立行程)中執行套件程式碼,做法與 VS Code 執行擴充功能相同。應用程式的背景服務(Kernel)會為每個開啟的專案執行一個 Extension Host,並由所有開啟該專案的桌面視窗與 CLI 共用。你的程式碼只能透過 ctx.aigd、經由訊息通道與應用程式溝通。

桌面應用程式gamedev CLI
顯示的 UI全部:選單、面板、檢視、自訂編輯器、狀態列、教學、webview斜線命令、Tools 列、訊息、快速選取、輸入框、表單、進度列
僅限桌面版的呼叫運作方式解析為 undefined 或無作用的物件,並記錄一次
Extension Host 行程每個專案共用每個專案共用

沒有開啟專案的視窗不會執行任何主機。安裝在使用者層級的套件會在每個開啟的專案中執行,除非該專案將它排除。

延遲啟用

  1. 安裝。 應用程式會讀取 manifest,並一次註冊所有宣告的貢獻項目:斜線命令、Tools 開關、選單項目與檢視會立即出現,而不會執行任何程式碼。
  2. 啟用。 第一次有東西需要這段程式碼時(命令執行、檢視開啟、能力被開啟、符合的檔案開啟、找到引擎專案),主機會載入 main 並呼叫 activate(ctx)。相依套件會先啟用。activate 有 30 秒的時間。
  3. 執行。 你的處理常式會回應應用程式的呼叫。你註冊的所有內容都會放在 ctx.subscriptions 中。
  4. 停止。 在移除、套件被停用、更新或主機重新啟動時,主機會呼叫 deactivate()(選用)並處置 ctx.subscriptions。

只有 main 而完全沒有任何事件的套件,會在第一輪繪製之後啟動(onStartupFinished)。完整的事件清單請見 manifest 參考文件。

當作用中的套件集合改變時,以及發生當機之後(分別在 1 秒、5 秒與 30 秒後),主機會重新啟動。若五分鐘內當機三次,主機會保持停止,直到使用者在 Packages 視窗中點選 Reload。

層級、鎖定與更新

使用者可以用三種層級之一加入套件:

層級宣告於共用範圍
使用者~/.ai-game-dev/packages.json此使用者的每個專案
專案<project>/.ai-game-dev/packages.json會提交:每位隊友都會取得
本機<project>/.ai-game-dev/packages.local.json僅限這台電腦,永不提交

本機優先於專案,專案優先於使用者。每個層級旁都有一個鎖定檔,固定確切的版本、tarball 與雜湊值,讓隊友安裝到完全相同的位元組。自動更新預設為開啟(依套件、依電腦):每隔四小時,應用程式會把每個套件移到其宣告範圍內、應用程式能執行的最新版本,並針對整次執行顯示一則通知。file: 連結與固定在特定標籤的 GitHub 來源永遠不會自動更新。

錯誤與日誌

主機會把每一次失敗歸屬於它所屬的套件:activate、deactivate 或處理常式中的拋出、來自你檔案卻未被攔截的例外或未處理的 rejection、ctx.reportError(err) 以及 ctx.log.error(msg, err)。每個套件在 Packages 視窗中的 Errors 分頁會顯示「N 個錯誤 · M 次當機」,以及含堆疊的近期清單。

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 的模式:沒有沙箱,也沒有權限提示。套件的程式碼會以使用者本身的權限執行:它可以讀寫檔案、啟動行程並使用網路,就像使用者安裝的任何程式一樣。取而代之,讓使用者知情的方式是:

  • 所有可見內容都先宣告。 套件顯示的所有內容都會在 manifest 中宣告,並在其程式碼執行前就可見。
  • 所有權會強制執行。 套件只能註冊或變更自己擁有的 id(<package id>.<local> 命令、檢視與 context 鍵,<publisher>--<name> 伺服器),並在載入時與每次呼叫時檢查。它可以執行任何命令,無論是自己的、其他套件的或應用程式的命令;而 webview 頁面只能執行自己套件的命令與應用程式命令。
  • 宣告的內容都會顯示。 安裝前,Packages 視窗會顯示 registry index 所記載的內容:原生程式碼、Claude 外掛、相依套件。安裝後,還會顯示該套件是否執行程式碼、啟動工具伺服器或提供遊戲引擎。這些都只是資訊,絕不是門檻。
  • Registry 檢查。 社群 registry 中的每個版本都通過了自動檢查,涵蓋憑證、針對 agent 的提示注入、惡意軟體與壓縮檔手法;請參閱 Registry 規則與檢查。
  • 撤銷。 AI Game Dev 可以撤銷惡意版本;每個應用程式會在下一次讀取索引時將其停用(約半小時內)。
  • Webview 頁面是隔離的。 頁面在沒有 Node.js 的沙箱框架中執行;webview 視窗則完全沒有網路存取權。

身為作者:不要夾帶機密資訊,讓套件的用途從 README 與 manifest 就能一目了然,並在任何具破壞性的操作前先詢問使用者。

版本管理與相容性

API 的版本由兩個數字決定,兩者都不是你套件的 version:

  • 套件 API 版本(目前為 0.4.0)只會透過新增而成長:新的成員與貢獻點。你的 aigd.d.ts 會標明它是針對哪個版本撰寫的。
  • 最舊支援的 engines.aigd(目前為 0.18.0)是應用程式仍會載入的最低下限。調高它是移除穩定成員的唯一途徑,且必須先經過至少兩個 minor 版本的棄用警告。

給你的規則:

  • 將 engines.aigd 設為你測試過的最舊應用程式版本。比該版本更舊的應用程式會拒絕此套件,並提示使用者更新。
  • 若想支援比該成員更舊的應用程式,請對選用成員做功能偵測(aigd.gameEngines?、item.pulse?.())。
  • 提案中的成員不受以上任何規則保障。請參閱穩定與提案中的 API。
  • 你儲存的資料屬於你:用 dataVersion 標記版本,並在 activate 中進行移轉。