# 套件 API — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

AI Game Dev 套件的 ctx.aigd API：每個命名空間、穩定與提案中的成員、僅桌面版可用的呼叫，以及工具、UI 與狀態的實用範例。

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

你的套件程式碼透過交給 `activate(ctx)` 的一個物件 `ctx.aigd` 與應用程式溝通。本頁列出它的命名空間、說明哪些成員是穩定的、哪些是提案中的，並展示大多數套件都會用到的呼叫範例：命令、斜線命令、agent 工具、設定、訊息、webview、樹狀檢視、自訂編輯器、教學與儲存的狀態。套件 API 版本為 0.4.0。

## 型別

`gamedev pkg init` 會把整套 API 寫成一個自成一體的檔案 `src/types/aigd.d.ts`，它由應用程式自身的契約產生，並與產生它的應用程式版本相符。TypeScript 可直接匯入；JavaScript 則透過 JSDoc 使用：

```typescript
import type { PackageContext } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  ctx.subscriptions.push(ctx.aigd.commands.registerCommand("acme.level-tools.hello", () => "hi"));
}

export function deactivate(): void {}
```

```javascript
/** @param {import("./types/aigd").PackageContext} ctx */
exports.activate = function activate(ctx) { /* … */ };
```

在暫存資料夾中執行較新的 `gamedev pkg init`，就能取得較新版本的型別副本。npm 型別套件（`@ai-game-dev/package-api`）已備妥但尚未發佈。

每次呼叫都會跨越行程邊界（你的程式碼在應用程式的 Extension Host 中執行），因此引數與結果都必須是 JSON 值，而每個與應用程式溝通的 method 都是 async。少數同步成員（`env`、`project.path`、`settings.get`）讀取的是套件啟動時應用程式推送的狀態。

## context 物件

| 成員 | 說明 |
| --- | --- |
| `ctx.aigd` | API（如下） |
| `ctx.package` | 本套件：`id`、`publisher`、`name`、`version`、`displayName`、`dir`、`manifest` |
| `ctx.subscriptions` | 把每個 `Disposable` 推到此處；套件停止時應用程式會處置它們 |
| `ctx.globalState`, `ctx.projectState` | 小型鍵值儲存區，分別對應這台電腦，以及這台電腦上的這個專案 |
| `ctx.globalStoragePath`, `ctx.projectStoragePath` | 你的套件可寫入的資料夾 |
| `ctx.log` | `debug`、`info`、`warn`、`error`：在應用程式日誌中標記為 `pkg:<id>` 的訊息 |
| `ctx.asAbsolutePath(rel)` | 套件資料夾內的路徑 |
| `ctx.reportError(err, subject?)` | 在 Packages 視窗的 Errors 清單中記錄錯誤 |

## 命名空間

| 命名空間 | 功能 | 狀態 |
| --- | --- | --- |
| `env` | Host（`desktop` 或 `cli`）、應用程式版本、平台、`nodeCommand`、透過系統代理的 `fetch`、`openExternal`、剪貼簿（桌面版） | 穩定 |
| `commands` | 註冊並執行命令與斜線命令，設定 `when` context 鍵 | 穩定 |
| `capabilities` | Tools 開關的狀態、啟用，以及各對話的附加情形 | 穩定 |
| `mcp` | 為此專案註冊 MCP 伺服器 | 穩定 |
| `agent` | 在記憶體中提供 agent 工具（`registerProvider`） | 穩定 |
| `gameEngines` | 實作遊戲引擎（`registerEngine`、`host`） | 自 0.4.0 起穩定 |
| `settings` | 讀寫你的設定，監看變更 | 穩定 |
| `project` | 專案路徑與 `getInfo()`（引擎、引擎版本、資料夾中的引擎專案） | 穩定 |
| `packages` | 其他套件及其 exports（`all`、`get`、`getExports`） | 穩定 |
| `claude` | 將 Claude Code 外掛資料夾加入此專案的對話（`registerPlugin`） | 穩定 |
| `editor` | 已連線引擎編輯器的工具，適用於你的 provider 所附加的對話 | 穩定 |
| `account` | 已登入帳號的能力目錄（`getSnapshot`） | 穩定 |
| `media` | 註冊在 `contributes.mediaProviders` 中宣告的本地媒體生成器（`registerProvider`） | 穩定 |
| `window` | 訊息、快速選取、輸入框、進度、狀態列、webview、樹狀檢視、自訂編輯器 | 穩定，桌面版 |
| `tutorials` | 請求並追蹤應用程式內的提示 | 穩定，桌面版 |
| `sessions` | `list()`、`active()` 與即時事件為穩定；逐字稿、prompt 與各對話設定則為提案中 | 混合 |
| `storage`, `downloads`, `hardware` | 應用程式的 blob 儲存、驗證下載與硬體探測 | 提案中 |
| `tasks`, `subscriptions`, `work` | 背景任務觀察、長時間執行的工作、工作保留 | 提案中 |

在 `aigd.d.ts` 中標記為 `@desktop` 的成員在 CLI 上不會有任何作用：它們會解析為 `undefined` 或回傳一個無作用的物件，而 host 會記錄一行日誌。當你的套件在終端機中應有不同的行為時，請檢查 `aigd.env.host`。

## 穩定與提案中的 API

**穩定**成員在每個應用程式版本中都維持相同語意。變更僅限於新增；穩定成員只有在至少兩個 minor 應用程式版本發出棄用警告（在 `gamedev pkg logs` 中每個套件每 session 一行）之後，並伴隨提高應用程式可載入的最舊 `engines.aigd` 版本，才會被移除。

**提案中**成員可能在任何版本中變更或消失。若要呼叫，必須宣告其提案；未宣告就呼叫會失敗，並在訊息中指明該提案：

```json
{ "enabledApiProposals": ["forms"] }
```

| 提案 | 成員 |
| --- | --- |
| `forms` | `window.showForm` |
| `alerts` | `window.showAlert` |
| `sessions` | `sessions.getTranscript`, `sendPrompt`, `create`, `focusComposer` |
| `sessionConfiguration` | 每個對話的套件設定與 Tools 模組（`sessions.getConfiguration`、`updateConfiguration`、`registerToolStateProvider`、…） |
| `appFocus` | `window.keepInFront` |
| `storage`、`downloads`、`hardware` | blob 儲存區、下載管理員、硬體探測 |
| `backgroundTasks`、`subscriptions`、`workHolds` | `tasks.*`、`subscriptions.open`、`work.hold` |
| `paidOperations`、`mockJobs` | 付費伺服器工作（僅限 AI Game Dev 自家的供應商套件）及其開發模擬 |

**警告**

社群註冊表會拒絕每一個宣告了 proposal 的套件。需要 proposal 的套件仍可從 GitHub、npm 或本機資料夾分享；請參閱 [發佈套件](https://ai-game.dev/zh-hant/docs/wiki/app/publishing-packages#other-sources)。

## 指令與斜線指令

```typescript
const ID = "acme.level-tools";

ctx.subscriptions.push(
  aigd.commands.registerCommand(`${ID}.count`, async (...args) => {
    const n = await countCollectibles();
    await aigd.window.showInformationMessage(`${n} collectibles in this level`);
    return n;
  }),
  aigd.commands.registerSlashCommand("/collectibles", async (inv) => {
    inv.say("Counting…");                       // a system line in the chat, live
    const n = await countCollectibles(inv.args.trim());
    inv.say(`${n} collectibles.`);
  }),
);

await aigd.commands.setContext(`${ID}.hasLevel`, true);   // usable in when clauses
await aigd.commands.executeCommand("aigd.packages.open", { packageId: ID });
```

斜線指令會取得其名稱後面的文字（`inv.args`）、輸入該指令的對話（`inv.sessionId`）、用於即時訊息的 `say()`，以及 `cancelled`——一個在使用者按下 Esc 或 Stop 時會完成的 promise。斜線指令在桌面版對話與 CLI 中的運作方式相同。你的套件可執行的應用程式指令包括 `aigd.packages.open`、`aigd.packages.reload`、`aigd.packages.checkForUpdates`、`aigd.session.focus`、`aigd.settings.open` 與 `aigd.tutorials.show`。

## 讓代理具備工具

**宣告式 MCP 伺服器。** 最簡單的方式：宣告伺服器，以及一個可依對話啟用它的能力。不需要寫任何程式碼；伺服器就是你用應用程式的 Node 啟動的自家指令碼：

```json
{
  "contributes": {
    "capabilities": [
      { "id": "acme.level-tools", "label": "Level tools", "description": "Counts collectibles in level files.", "mcpServer": "acme--level-tools" }
    ],
    "mcpServers": {
      "acme--level-tools": { "command": "${node}", "args": ["${packageDir}/server.js"] }
    }
  }
}
```

**在執行階段註冊的 MCP 伺服器。** 適用於必須等某個東西啟動後才知道位址的伺服器（例如外部應用程式的連接埠）：

```typescript
await aigd.mcp.registerServer("acme--level-tools", { type: "http", url: `http://127.0.0.1:${port}/mcp` });
```

**由你的程式碼提供工具。** 代理供應商會把工具保存在你的套件中，不需要伺服器程序。用其能力宣告，然後註冊它：

```json
{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
```

```typescript
ctx.subscriptions.push(await aigd.agent.registerProvider("acme.helper.agent", {
  getTools: () => [{
    name: "status",
    description: "Read the helper's status",
    inputSchema: { type: "object", properties: {}, additionalProperties: false },
  }],
  getInstructions: () => "Use the helper's status tool when working in this project.",
  invokeTool: async (name, args, context) => ({ content: [{ type: "text", text: context.project.path }] }),
}));
```

工具的輸入結構描述必須以物件為根，且頂層不得有 `oneOf`、`anyOf` 或 `allOf`。結果可以包含文字與圖片（`{ type: "image", data, mimeType }`，PNG、JPEG 或 WebP）；未通過應用程式檢查的圖片會被替換成一則提示，而不會造成錯誤。預設的工具期限為 60 秒（`executionTimeoutMs`，最長一小時）。

**附帶狀態的能力。** 當啟用某項能力需要一番工夫（例如啟動外部應用程式）時，請在該能力上設定 `statusful: true`。應用程式接著會在開關上顯示你的狀態，並呼叫你的啟用處理常式：

```typescript
ctx.subscriptions.push(
  aigd.capabilities.registerStatusProvider("acme.level-tools", async () =>
    (await isRunning()) ? { phase: "connected", detail: "Editor 4.2" } : { phase: "idle" }),
  aigd.capabilities.registerActivationHandler("acme.level-tools", async (req) => {
    req.progress("Starting the level server…");
    try { await start(); return { ok: true }; }
    catch (e) { return { ok: false, failure: { code: "start-failed", text: String(e) } }; }
  }),
);
```

## 設定

```typescript
const quality = aigd.settings.get<string>("quality") ?? "draft";
await aigd.settings.update("quality", "final", "project");   // user, project or local
ctx.subscriptions.push(aigd.settings.onDidChange((e) => ctx.log.info(`${e.key} is now ${String(e.value)}`)));
```

鍵值由你自己決定（不帶套件前綴），且必須在 `contributes.settings` 中宣告。每次寫入都會依據宣告進行驗證。

## 訊息、選取器與進度

```typescript
const choice = await aigd.window.showWarningMessage("Overwrite the export?", { modal: true }, "Overwrite", "Keep");
const level = await aigd.window.showQuickPick(["forest", "cave", "castle"], { title: "Export which level?" });
const name = await aigd.window.showInputBox({ prompt: "File name", value: "level-1" });

await aigd.window.withProgress({ title: "Exporting", cancellable: true }, async (progress, cancelled) => {
  progress.report({ message: "Meshes", increment: 50 });
  progress.report({ message: "Textures", increment: 50 });
});

const item = aigd.window.createStatusBarItem("acme.level-tools.status", { alignment: "left" });
item.text = "3 levels";
item.command = "acme.level-tools.count";
item.show();
ctx.subscriptions.push(item);
```

在 CLI 上，訊息會以系統列印出；當你的斜線指令執行時，模態訊息、快速選取或輸入框會變成終端機提示。在斜線指令之外，CLI 會以 `PromptRefusedError`（代碼 `prompt_refused`）拒絕提示，因此會向使用者提問的套件應從斜線指令中提問，或檢查 `aigd.env.host`。

## Webview：面板、側邊檢視與視窗

Webview 是應用程式（桌面版）中屬於你自己的 HTML 頁面。同一個頁面可用於窗格、側邊面板分頁或獨立視窗：

```typescript
const panel = aigd.window.createWebviewPanel("acme.level-tools.map", "Level map");
const script = panel.webview.asWebviewUri(ctx.asAbsolutePath("dist/map.js"));
panel.webview.html = `<!doctype html><html><body><canvas id="map"></canvas>
  <script type="module" src="${script}"></script></body></html>`;
panel.webview.onDidReceiveMessage((msg) => ctx.log.info(`page says ${JSON.stringify(msg)}`));
await panel.webview.postMessage({ type: "level", tiles });
```

```javascript
// dist/map.js, inside the page
const api = acquireAigdApi();
api.postMessage({ type: "ready" });
window.addEventListener("message", (e) => draw(e.data));
api.setState({ zoom: 2 });             // restored with the pane after a relaunch
```

- **側邊面板分頁：** 在 `contributes.views.right` 下宣告 `{ "id": "acme.level-tools.side", "name": "Levels", "type": "webview" }`，並註冊 `aigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } })`。`"titleBar": "hidden"` 可讓你的頁面自行繪製標題列。
- **獨立視窗：** `aigd.window.createWebviewWindow(viewType, title)` 會開啟可調整大小的原生視窗，每個專案的每種檢視類型各一個。其頁面在嚴格的內容安全政策下執行：僅限套件自己的檔案，不得連網，也不得使用 `eval`。
- **主題：** 頁面會取得 `<html data-theme="light|dark">`，並以 `--aigd-*` CSS 變數（`--aigd-bg`、`--aigd-surface`、`--aigd-text`、`--aigd-primary`、…）提供應用程式的調色盤，並在每次切換主題時重新傳送。
- **頁面 API：** `acquireAigdApi()` 會提供 `postMessage`、`getState`、`setState`、`executeCommand`（你自己的指令與應用程式指令）、`getContext()` 與 `close()`。

## 樹狀檢視

```typescript
const tree = aigd.window.createTreeView("acme.level-tools.levels", {
  treeDataProvider: {
    getChildren: async (parent) => parent
      ? listObjects(parent.id).map((o) => ({ id: o.id, label: o.name, icon: "$(box)" }))
      : listLevels().map((l) => ({ id: l.id, label: l.name, collapsible: "collapsed", contextValue: "level" })),
  },
});
tree.message = "3 levels";
ctx.subscriptions.push(tree);
```

檢視會在 `contributes.views` 中以 `"type": "tree"` 宣告。`contextValue` 會成為 `view/item/context` 選單的 `viewItem`；項目可帶有核取方塊、徽章與點擊指令。

## 自訂編輯器

```json
{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
```

```typescript
ctx.subscriptions.push(aigd.window.registerCustomEditorProvider("acme.level-tools.level", {
  resolveCustomEditor(document, panel) {
    panel.webview.html = renderLevel(fs.readFileSync(document.path, "utf8"));
  },
}));
```

`default` 編輯器會取代應用程式對相符檔案的預覽；`option` 編輯器則會出現在「打開方式」下。文件從應用程式端來看是唯讀的：你的套件會自行寫入檔案，而當磁碟上的檔案變更時，窗格會重新載入。`aigd.window.openPreview(path)` 會在預覽中顯示專案檔案，就像在 Explorer 中點擊一樣。

## 教學課程

```json
{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
```

```typescript
ctx.subscriptions.push(aigd.tutorials.request("acme.level-tools.intro"));
```

提示對每位使用者只顯示一次，會在適當的時機出現，並指向它的錨點：`capability:`、`statusBar:`、`view:`、`slashCommand:`、`command:` 或 `menu:` 加上一個 id、`composer`，或 `none`。`markdown` 最多可搭配 8 個 `media` 檔案，或以 `webview` 頁面呈現豐富內容。`request(id, { force: true })` 會讓它再次顯示；`isSeen` 與 `setSeen` 則用來讀取與設定已看過的狀態。

## 儲存的狀態

```typescript
const DATA = 2;
if ((ctx.globalState.dataVersion ?? 0) < DATA) {
  await migrate(ctx.globalState);
  await ctx.globalState.setDataVersion(DATA);
}
await ctx.projectState.update("lastExport", new Date().toISOString());
const last = ctx.projectState.get<string>("lastExport");
```

`globalState` 由這台電腦上的每個專案共用；`projectState` 則屬於這台電腦上的這個專案。兩者在更新與移除後都會保留（重新加入套件即可還原）；Packages 視窗中的 **Remove data** 會將它們刪除。應用程式從不遷移你的資料：`dataVersion` 由你自行比較與調升。

## 相關頁面

- [套件資訊清單參考](https://ai-game.dev/zh-hant/docs/wiki/app/package-manifest)，了解這些呼叫所搭配的宣告。
- [生命週期、主機與權限](https://ai-game.dev/zh-hant/docs/wiki/app/package-lifecycle)，了解你的程式碼何時執行以及它可以做什麼。
- [遊戲引擎套件](https://ai-game.dev/zh-hant/docs/wiki/app/game-engine-packages)，了解 `aigd.gameEngines`。

---

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

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