# API de pacotes — App e CLI do AI Game Dev · AI Game Developer Wiki

A API ctx.aigd dos pacotes do AI Game Developer: namespaces, membros estáveis e propostos, chamadas exclusivas do desktop e exemplos de uso.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/app/package-api).

O código do seu pacote chega ao app por meio de um único objeto, `ctx.aigd`, entregue a `activate(ctx)`. Esta página lista seus namespaces, informa quais membros são estáveis e quais são propostos, e mostra exemplos funcionais das chamadas que a maioria dos pacotes faz: comandos, slash commands, ferramentas de agente, configurações, mensagens, webviews, tree views, editores customizados, tutoriais e estado armazenado. A API de pacotes está na versão 0.4.0.

## Tipos

`gamedev pkg init` grava toda a API em um único arquivo autocontido, `src/types/aigd.d.ts`, gerado a partir do contrato do próprio app e correspondente à versão do app que o gerou. O TypeScript o importa; o JavaScript o usa a partir do 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) { /* … */ };
```

Um `gamedev pkg init` mais recente em uma pasta de rascunho fornece uma cópia mais nova dos tipos. Um pacote npm de tipos (`@ai-game-dev/package-api`) está preparado, mas ainda não foi publicado.

Toda chamada atravessa uma fronteira de processo (seu código roda no Extension Host do app), então argumentos e resultados devem ser valores JSON, e todo método que conversa com o app é assíncrono. Os poucos membros síncronos (`env`, `project.path`, `settings.get`) leem o estado que o app enviou quando o pacote iniciou.

## O contexto

| Membro | O que é |
| --- | --- |
| `ctx.aigd` | A API (abaixo) |
| `ctx.package` | Este pacote: `id`, `publisher`, `name`, `version`, `displayName`, `dir`, `manifest` |
| `ctx.subscriptions` | Coloque todo `Disposable` aqui; o app os descarta quando o pacote para |
| `ctx.globalState`, `ctx.projectState` | Pequenos armazenamentos chave-valor para este computador e para este projeto neste computador |
| `ctx.globalStoragePath`, `ctx.projectStoragePath` | Pastas nas quais seu pacote pode gravar |
| `ctx.log` | `debug`, `info`, `warn`, `error`: linhas marcadas com `pkg:<id>` no log do app |
| `ctx.asAbsolutePath(rel)` | Um caminho dentro da pasta do pacote |
| `ctx.reportError(err, subject?)` | Registra um erro na lista de Erros da janela Packages |

## Namespaces

| Namespace | O que faz | Status |
| --- | --- | --- |
| `env` | Host (`desktop` ou `cli`), versão do app, plataforma, `nodeCommand`, `fetch` através do proxy do sistema, `openExternal`, área de transferência (desktop) | Estável |
| `commands` | Registrar e executar comandos e slash commands, definir chaves de contexto `when` | Estável |
| `capabilities` | Status, ativação e anexação por chat dos seus switches de Ferramentas | Estável |
| `mcp` | Registrar servidores MCP para este projeto | Estável |
| `agent` | Servir ferramentas de agente em memória (`registerProvider`) | Estável |
| `gameEngines` | Implementar uma engine de jogo (`registerEngine`, `host`) | Estável desde 0.4.0 |
| `settings` | Ler e gravar suas configurações, observar alterações | Estável |
| `project` | O caminho do projeto e `getInfo()` (engine, versão da engine, os projetos de engine na pasta) | Estável |
| `packages` | Outros pacotes e suas exportações (`all`, `get`, `getExports`) | Estável |
| `claude` | Adicionar uma pasta de plugin do Claude Code aos chats deste projeto (`registerPlugin`) | Estável |
| `editor` | As ferramentas do editor de engine conectado, para chats aos quais seu provider está anexado | Estável |
| `account` | O catálogo de capacidades da conta conectada (`getSnapshot`) | Estável |
| `media` | Registrar um gerador de mídia local declarado em `contributes.mediaProviders` (`registerProvider`) | Estável |
| `window` | Mensagens, quick picks, caixas de entrada, progresso, barra de status, webviews, tree views, editores customizados | Estável, desktop |
| `tutorials` | Solicitar e acompanhar dicas no app | Estável, desktop |
| `sessions` | `list()`, `active()` e eventos ao vivo são estáveis; transcrições, prompts e configuração por chat são propostos | Misto |
| `storage`, `downloads`, `hardware` | O armazenamento de blobs do app, downloads verificados e sondagem de hardware | Proposto |
| `tasks`, `subscriptions`, `work` | Observação de tarefas em segundo plano, trabalho de longa duração, retenções de trabalho | Proposto |

Membros marcados com `@desktop` em `aigd.d.ts` não fazem nada na CLI: eles resolvem para `undefined` ou retornam um objeto inerte, e o host registra uma linha. Verifique `aigd.env.host` quando seu pacote precisar se comportar de forma diferente no terminal.

## API estável e proposta

Um membro **estável** mantém seu significado em todas as versões do app. As mudanças são apenas aditivas; um membro estável só é removido depois de pelo menos duas versões menores do app com avisos de depreciação (uma linha por pacote por sessão em `gamedev pkg logs`), junto com um aumento da versão mais antiga de `engines.aigd` que o app carrega.

Um membro **proposto** pode mudar ou desaparecer em qualquer versão. Para chamar um, declare sua proposta; uma chamada sem a declaração falha com uma mensagem que nomeia a proposta:

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

| Proposta | Membros |
| --- | --- |
| `forms` | `window.showForm` |
| `alerts` | `window.showAlert` |
| `sessions` | `sessions.getTranscript`, `sendPrompt`, `create`, `focusComposer` |
| `sessionConfiguration` | configuração de pacote por chat e módulos de Tools (`sessions.getConfiguration`, `updateConfiguration`, `registerToolStateProvider`, …) |
| `appFocus` | `window.keepInFront` |
| `storage`, `downloads`, `hardware` | o armazenamento de blobs, o gerenciador de downloads, a sondagem de hardware |
| `backgroundTasks`, `subscriptions`, `workHolds` | `tasks.*`, `subscriptions.open`, `work.hold` |
| `paidOperations`, `mockJobs` | jobs pagos no servidor (apenas os pacotes de provedor do próprio AI Game Dev) e sua simulação de desenvolvimento |

**Aviso**

O registro da comunidade recusa todo pacote que declara uma proposta. Um pacote que precise de uma ainda pode ser compartilhado pelo GitHub, pelo npm ou por uma pasta; veja [Publicação de pacotes](https://ai-game.dev/pt-br/docs/wiki/app/publishing-packages#other-sources).

## Comandos e comandos de barra

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

Um comando de barra recebe o texto depois do nome (`inv.args`), o chat em que foi digitado (`inv.sessionId`), `say()` para linhas ao vivo e `cancelled`, uma promise que é resolvida quando o usuário pressiona Esc ou Stop. Os comandos de barra funcionam do mesmo jeito no chat do desktop e na CLI. Entre os comandos do app que seu pacote pode executar estão `aigd.packages.open`, `aigd.packages.reload`, `aigd.packages.checkForUpdates`, `aigd.session.focus`, `aigd.settings.open` e `aigd.tutorials.show`.

## Dê ferramentas ao agente

**Um servidor MCP, declarado.** O jeito mais simples: declare o servidor e uma capacidade que o ativa por chat. Nenhum código é necessário; o servidor é seu próprio script iniciado com o Node do app:

```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"] }
    }
  }
}
```

**Um servidor MCP, registrado em tempo de execução.** Para um servidor cujo endereço você só descobre depois que algo foi iniciado (a porta de um app externo):

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

**Ferramentas servidas pelo seu código.** Um provedor de agente mantém as ferramentas no seu pacote, sem processo de servidor. Declare-o com sua capacidade e depois registre-o:

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

O schema de entrada de uma ferramenta precisa ter uma raiz do tipo objeto, sem `oneOf`, `anyOf` ou `allOf` no nível superior. Os resultados podem conter texto e imagens (`{ type: "image", data, mimeType }`, PNG, JPEG ou WebP); uma imagem que não passa nas verificações do app é substituída por uma nota, nunca por um erro. O prazo padrão da ferramenta é de 60 segundos (`executionTimeoutMs`, até uma hora).

**Uma capacidade com status.** Defina `statusful: true` na capacidade quando ativá-la exigir trabalho (iniciar um app externo). O app então mostra seu status no interruptor e chama seu handler de ativação:

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

## Configurações

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

As chaves são suas (sem o prefixo do pacote) e precisam ser declaradas em `contributes.settings`. Toda gravação é validada conforme a declaração.

## Mensagens, seletores e progresso

```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);
```

Na CLI, as mensagens são impressas como linhas de sistema; uma mensagem modal, um quick pick ou uma caixa de entrada viram um prompt de terminal enquanto seu comando de barra é executado. Fora de um comando de barra, a CLI recusa prompts com um `PromptRefusedError` (código `prompt_refused`), então um pacote que faz perguntas deve fazê-las a partir de um comando de barra ou verificar `aigd.env.host`.

## Webviews: painéis, visões laterais e janelas

Uma webview é sua própria página HTML dentro do app (desktop). A mesma página funciona em um painel, em uma aba do painel lateral ou em sua própria janela:

```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
```

- **Aba do painel lateral:** declare `{ "id": "acme.level-tools.side", "name": "Levels", "type": "webview" }` em `contributes.views.right` e registre `aigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } })`. `"titleBar": "hidden"` permite que sua página desenhe o próprio cabeçalho.
- **Janela própria:** `aigd.window.createWebviewWindow(viewType, title)` abre uma janela nativa redimensionável, uma por tipo de visão por projeto. A página dela roda sob uma política de segurança de conteúdo estrita: apenas os arquivos do próprio pacote, sem rede, sem `eval`.
- **Tema:** a página recebe `<html data-theme="light|dark">` e a paleta do app como variáveis CSS `--aigd-*` (`--aigd-bg`, `--aigd-surface`, `--aigd-text`, `--aigd-primary`, …), reenviadas a cada troca de tema.
- **API da página:** `acquireAigdApi()` fornece `postMessage`, `getState`, `setState`, `executeCommand` (seus próprios comandos e comandos do app), `getContext()` e `close()`.

## Visões em árvore

```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);
```

A visão é declarada com `"type": "tree"` em `contributes.views`. O `contextValue` se torna `viewItem` para os menus `view/item/context`; os itens podem ter checkboxes, badges e um comando de clique.

## Editores personalizados

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

Um editor `default` substitui a pré-visualização do próprio app para os arquivos correspondentes; um editor `option` aparece em Open With. Os documentos são somente leitura do lado do app: seu pacote grava os arquivos por conta própria, e o painel recarrega quando o arquivo muda no disco. `aigd.window.openPreview(path)` mostra um arquivo do projeto na pré-visualização, como um clique no Explorer faz.

## Tutoriais

```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"));
```

Uma dica é exibida uma vez por usuário, em um momento tranquilo, apontando para sua âncora: `capability:`, `statusBar:`, `view:`, `slashCommand:`, `command:` ou `menu:` seguido de um id, `composer` ou `none`. `markdown` com até 8 arquivos `media`, ou uma página `webview` para conteúdo rico. `request(id, { force: true })` exibe novamente; `isSeen` e `setSeen` leem e definem o estado de visualização.

## Estado armazenado

```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` é compartilhado por todos os projetos neste computador; `projectState` pertence a este projeto neste computador. Ambos sobrevivem a atualizações e à remoção (readicionar o pacote os restaura); **Remove data** na janela Packages os exclui. O app nunca migra seus dados: `dataVersion` é seu para comparar e incrementar.

## Páginas relacionadas

- [Referência do manifesto do pacote](https://ai-game.dev/pt-br/docs/wiki/app/package-manifest) para as declarações com as quais essas chamadas se combinam.
- [Ciclo de vida, hosts e permissões](https://ai-game.dev/pt-br/docs/wiki/app/package-lifecycle) para saber quando seu código é executado e o que ele pode fazer.
- [Pacotes de engines de jogos](https://ai-game.dev/pt-br/docs/wiki/app/game-engine-packages) para `aigd.gameEngines`.

---

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

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