Criando pacotes

Pacotes não servem apenas para recursos oficiais: você pode escrever o seu próprio para compartilhar uma tarefa repetitiva com o seu time, adicionar uma ferramenta para o agente ou visualizar um formato de arquivo personalizado. Esta página mostra a estrutura do pacote, um pacote mínimo funcional, os principais campos do manifesto, como adicionar uma ferramenta MCP, como desenvolver um pacote com o app em execução e como compartilhá-lo.

O que você precisa#

• O app desktop do AI Game Dev ou a CLI gamedev, versão 0.18.0 ou mais recente.
• Um editor de texto. JavaScript é opcional: um pacote pode conter apenas o manifesto.

Pacotes seguem o modelo das extensões do VS Code: uma pasta com um manifesto, aigd-package.json, e código opcional que exporta activate(ctx) e deactivate(). Seu código alcança o app apenas por meio de ctx.aigd. Ele roda em um processo de host de extensão separado, um por projeto aberto, e inicia de forma tardia quando algo precisa dele.

Estrutura do pacote#

my-first-package/
  aigd-package.json     the manifest (required)
  extension.js          the code named by "main" (optional)
  media/                icons and images (optional)
  LICENSE

Um pacote deve ser autossuficiente: o app nunca executa npm install para ele. Se o seu código usa bibliotecas, empacote-as no arquivo para o qual main aponta.

Um pacote mínimo#

Este pacote adiciona um slash command /my-first, uma entrada na paleta de comandos, um botão na barra de ferramentas do composer, um item na barra de status e uma configuração.

{
  "publisher": "you",
  "name": "my-first-package",
  "version": "0.1.0",
  "displayName": "My First Package",
  "description": "A /my-first slash command, a palette command, a toolbar button and a status bar item.",
  "license": "MIT",
  "main": "extension.js",
  "engines": { "aigd": ">=0.18.0" },
  "activationEvents": ["onSlashCommand:/my-first", "onCommand:you.my-first-package.hello"],
  "contributes": {
    "commands": [
      { "command": "you.my-first-package.hello", "title": "Say hello", "category": "My First Package", "icon": "$(smile)" }
    ],
    "slashCommands": [
      { "name": "/my-first", "description": "Say hello from my first package", "argumentHint": "[name]" }
    ],
    "menus": {
      "composer/toolbar": [{ "command": "you.my-first-package.hello", "group": "navigation" }]
    },
    "statusBar": [
      { "id": "you.my-first-package.status", "text": "My package", "command": "you.my-first-package.hello", "alignment": "left" }
    ],
    "settings": {
      "name": { "type": "string", "default": "game dev", "description": "Who /my-first greets", "scope": "project" }
    }
  }
}

E o código, extension.js (CommonJS):

const ID = "you.my-first-package";

exports.activate = function activate(ctx) {
  const { aigd } = ctx;
  let count = 0;

  ctx.subscriptions.push(
    aigd.commands.registerCommand(`${ID}.hello`, async () => {
      count++;
      await aigd.window.showInformationMessage(`Hello #${count} from my first package!`);
      return count;
    }),
    // Works in the desktop chat and in the CLI.
    aigd.commands.registerSlashCommand("/my-first", (inv) => {
      const who = inv.args.trim() || aigd.settings.get("name") || "game dev";
      inv.say(`Hi ${who}!`);
    }),
  );

  ctx.log.info("activated");
};

exports.deactivate = function deactivate() {};

O slash command, o botão da barra de ferramentas e o item da barra de status aparecem a partir do manifesto antes de qualquer código rodar; activate é chamado na primeira vez que um deles é usado.

Ids e regras de nomenclatura#

• O id do pacote é publisher.name, em minúsculas: aqui you.my-first-package. O publisher tem de 2 a 40 caracteres (letras, dígitos, hífens únicos). Use o seu próprio nome de publisher; aigd é o do AI Game Dev.
• Todo id que um pacote contribui (comandos, views, itens da barra de status, tutoriais) começa com o id do pacote: you.my-first-package.hello.
• engines.aigd é obrigatório: a versão mais antiga do AI Game Dev de que o pacote precisa, por exemplo ">=0.18.0". Um app mais antigo recusa o pacote e informa qual versão ele exige.
• version é semver. As instalações são cacheadas por id e versão, então toda mudança que você publicar precisa de uma versão maior.

Principais campos do manifesto#

Os pontos de contribuição em contributes incluem commands, slashCommands, capabilities (interruptores na linha Tools da sessão), mcpServers, settings, panels, viewsContainers e views (views de árvore ou webview nos painéis laterais), menus e submenus, keybindings, customEditors, statusBar e tutorials. Os menus usam ids fixos, como commandPalette, composer/toolbar, explorer/context, editor/title e view/item/context, cada um com uma cláusula when opcional. A CLI mostra slash commands, linhas Tools, mensagens, quick picks, caixas de entrada e formulários; menus e painéis são exclusivos do desktop.

Dê uma ferramenta ao agente com um servidor MCP#

O motivo mais comum para escrever um pacote é dar novas ferramentas ao agente. Declare um servidor MCP e uma capability que o ativa por sessão:

{
  "publisher": "you",
  "name": "level-tools",
  "version": "0.1.0",
  "engines": { "aigd": ">=0.18.0" },
  "contributes": {
    "capabilities": [
      {
        "id": "you.level-tools",
        "label": "Level tools",
        "description": "Counts collectibles in the level files.",
        "defaultEnabled": false,
        "mcpServer": "you--level-tools"
      }
    ],
    "mcpServers": {
      "you--level-tools": {
        "command": "${node}",
        "args": ["${packageDir}/server.js"]
      }
    }
  }
}

• O nome do servidor deve ser <publisher>--<name> (ou <publisher>--<name>-<suffix>) do id do pacote, com no máximo 96 caracteres, para que nomes de autores diferentes nunca colidam. Um nome não qualificado é um erro.
• Variáveis que você pode usar em um servidor stdio: ${node}, ${packageDir}, ${projectDir} e ${globalStorage}.
• Se um servidor MCP com o mesmo nome já estiver configurado em uma sessão, o servidor do pacote não é adicionado e a sessão exibe um aviso.

Desenvolva com o app em execução#

Aponte um projeto para a sua pasta em vez de uma versão publicada. A pasta é usada no local, recarrega quando um arquivo que ela inclui muda e nunca é atualizada automaticamente. O nível padrão é Local, que nunca é commitado.

cd <your project>
gamedev pkg link <path-to-your-package>      # use the folder (default --local)
gamedev pkg list                             # shows "(local dev)" and which level it overrides
gamedev pkg unlink you.my-first-package      # back to the published version

Se o seu pacote tem uma etapa de build (src/ compilado em dist/), use gamedev pkg dev em vez disso. Ele executa o script dev do pacote, ou reexecuta build após cada mudança no código-fonte, vincula a pasta após o primeiro build bem-sucedido e encerra todos os processos que iniciou quando você pressiona Ctrl+C:

gamedev pkg dev <path-to-your-package>

No app desktop, o mesmo recurso fica na janela Packages: selecione o pacote e escolha Use a local folder…, depois Stop using local folder para voltar. Uma pasta cujo manifesto declara outro id é recusada.

Compartilhe seu pacote#

O registro do AI Game Dev contém os pacotes oficiais. Para compartilhar o seu, publique-o no GitHub ou no npm; assim qualquer pessoa pode adicioná-lo por link:

gamedev pkg add github:you/my-first-package           # not pinned: receives updates
gamedev pkg add github:you/my-first-package@v0.1.0    # a tag (never auto-updated)
gamedev pkg add npm:my-first-package                  # an npm package
gamedev pkg add npm:my-first-package@^0.1.0           # with a version range

Para um time, adicione-o no nível Project para que ele seja commitado em .ai-game-dev/packages.json e todo colega o receba, fixado pelo arquivo de lock do projeto.

Antes de publicar uma nova versão, aumente version em aigd-package.json. Um arquivo alterado sob uma versão inalterada nunca chega a uma instalação que já tem essa versão.

Boas práticas#

• Mantenha as ferramentas focadas. Toda ferramenta que o agente vê ocupa contexto; uma ferramenta pequena e bem descrita é usada corretamente com mais frequência.
• Declare o máximo que puder no manifesto, para que a interface fique visível antes de o seu código iniciar.
• Use scope: "project" para configurações que o time deve compartilhar e scope: "machine" para caminhos em um único computador.
• Pacotes rodam com as permissões do seu usuário e sem sandbox. Não inclua segredos em um pacote e explique aos usuários o que o seu pacote faz.

Saiba mais#

• Pacotes para níveis, atualizações e configurações.
• Catálogo de pacotes para saber o que os pacotes oficiais fazem.
• O post pacotes, plugins do Claude e servidores MCP sobre um servidor MCP adicionado a um chat em tempo real.