套件 API
AI Game Dev 套件的 ctx.aigd API:每個命名空間、穩定與提案中的成員、僅桌面版可用的呼叫,以及工具、UI 與狀態的實用範例。
你的套件程式碼透過交給 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.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 版本,才會被移除。
提案中成員可能在任何版本中變更或消失。若要呼叫,必須宣告其提案;未宣告就呼叫會失敗,並在訊息中指明該提案:
{ "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 自家的供應商套件)及其開發模擬 |
指令與斜線指令
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 由你自行比較與調升。
相關頁面
- 套件資訊清單參考,了解這些呼叫所搭配的宣告。
- 生命週期、主機與權限,了解你的程式碼何時執行以及它可以做什麼。
- 遊戲引擎套件,了解
aigd.gameEngines。