# 套件生命週期、主機與權限 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

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

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/app/package-lifecycle)。

本頁說明套件從安裝到移除之間發生什麼事：它的程式碼在哪裡執行、何時啟動與停止、被允許做什麼、錯誤如何傳到你手上，以及它依據撰寫的 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 參考文件](https://ai-game.dev/zh-hant/docs/wiki/app/package-manifest#activation-events)。

當作用中的套件集合改變時，以及發生當機之後（分別在 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 次當機」，以及含堆疊的近期清單。

```bash
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 規則與檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-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](https://ai-game.dev/zh-hant/docs/wiki/app/package-api#stable-vs-proposed)。
- 你儲存的資料屬於你：用 `dataVersion` 標記版本，並在 `activate` 中進行移轉。

## 相關頁面

- [Package API](https://ai-game.dev/zh-hant/docs/wiki/app/package-api)：各項呼叫的說明。
- [Packages](https://ai-game.dev/zh-hant/docs/wiki/app/packages)：從使用者角度看的層級與更新。
- [Package CLI 參考](https://ai-game.dev/zh-hant/docs/wiki/app/package-cli)：`pkg logs`、`link` 與 `dev`。

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/app/package-lifecycle

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/app/package-lifecycle
