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

套件 API

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

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

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

型別

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

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

命名空間

命名空間功能狀態
envHost(desktop 或 cli)、應用程式版本、平台、nodeCommand、透過系統代理的 fetch、openExternal、剪貼簿(桌面版)穩定
commands註冊並執行命令與斜線命令,設定 when context 鍵穩定
capabilitiesTools 開關的狀態、啟用,以及各對話的附加情形穩定
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請求並追蹤應用程式內的提示穩定,桌面版
sessionslist()、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 版本,才會被移除。

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

{ "enabledApiProposals": ["forms"] }
提案成員
formswindow.showForm
alertswindow.showAlert
sessionssessions.getTranscript, sendPrompt, create, focusComposer
sessionConfiguration每個對話的套件設定與 Tools 模組(sessions.getConfiguration、updateConfiguration、registerToolStateProvider、…)
appFocuswindow.keepInFront
storage、downloads、hardwareblob 儲存區、下載管理員、硬體探測
backgroundTasks、subscriptions、workHoldstasks.*、subscriptions.open、work.hold
paidOperations、mockJobs付費伺服器工作(僅限 AI Game Dev 自家的供應商套件)及其開發模擬

指令與斜線指令

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 啟動的自家指令碼:

{
  "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 伺服器。 適用於必須等某個東西啟動後才知道位址的伺服器(例如外部應用程式的連接埠):

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

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

{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
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。應用程式接著會在開關上顯示你的狀態,並呼叫你的啟用處理常式:

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) } }; }
  }),
);

設定

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 中宣告。每次寫入都會依據宣告進行驗證。

訊息、選取器與進度

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 頁面。同一個頁面可用於窗格、側邊面板分頁或獨立視窗:

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 });
// 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()。

樹狀檢視

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;項目可帶有核取方塊、徽章與點擊指令。

自訂編輯器

{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
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 中點擊一樣。

教學課程

{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
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 則用來讀取與設定已看過的狀態。

儲存的狀態

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 由你自行比較與調升。