Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Empacotar o plugin

Aula 10 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Por que empacotar
  2. Estrutura de um pacote portátil
  3. Declarar o servidor MCP
  4. Metadados específicos da OpenAI
  5. A via rápida: @plugin-creator
  6. Mercados locais
  7. Ganchos: apenas para ambiente de trabalho
  8. Pontos-chave

Lição reescrita em 3 de novembro de 2026 com base na página Package your plugin da documentação de Plugins da OpenAI. A lição anterior descrevia a criação de um “pacote” para uma “Loja do ChatGPT” inexistente, utilizando um manifesto ausente. Um plugin é empacotado com um manifesto plugin.json que segue o esquema de Agent Plugins. Fonte: Package your plugin.

Por que empacotar

Depois de escrever as suas competências (skills) e, se necessário, construir o servidor MCP, o passo final consiste em reuni-las numa unidade instalável. O empacotamento confere ao seu plugin uma identidade estável e informa o ChatGPT e o Codex sobre quais competências, ligações a servidores MCP e recursos pertencem ao mesmo conjunto. A lógica da interface de utilizador e de autenticação permanece dentro do servidor MCP; o manifesto limita-se a ligar essa integração ao restante pacote.

Estrutura de um pacote portátil

Um plugin portátil possui um manifesto plugin.json na sua raiz, declarando o esquema de Agent Plugins. A pasta pode também conter um diretório skills/, um ficheiro mcp.json para servidores MCP distribuídos com o plugin e recursos visuais em assets/.

mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│   └── compte-rendu/
│       └── SKILL.md
└── assets/
    ├── icon.png
    └── logo.png

O manifesto mínimo cabe em apenas algumas linhas. O nome, estável e em kebab-case, serve simultaneamente como identificador e espaço de nomes para os componentes; as competências são descobertas automaticamente em skills/ sem necessidade de declaração explícita.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "notes-equipe",
  "version": "0.1.0",
  "description": "Team notes and meeting minutes"
}

Cada competência reside em skills/<nome>/SKILL.md, com um cabeçalho que fornece o seu nome e descrição, seguido das instruções:

---
name: compte-rendu
description: Drafts meeting minutes from team notes.
---

Retrieve meeting notes using list_notes, group them by topic,
then draft a summary: decisions, action items with owners, and open points.

Declarar o servidor MCP

Os servidores MCP distribuídos com o plugin são declarados em mcp.json na raiz, utilizando o esquema correspondente e especificando um tipo de transporte para cada servidor:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "notes": {
      "type": "streamable-http",
      "url": "https://notes.example.com/mcp"
    }
  }
}

A autenticação do servidor é declarada neste mesmo ficheiro, sob extensions["com.openai"].auth para cada servidor — pertence ao servidor, não ao manifesto. Para submissão pública, submete o endpoint HTTPS remoto; os servidores locais seguem um caminho separado, reservado a plugins de ambiente de trabalho.

Metadados específicos da OpenAI

A apresentação do diretório, os mapeamentos para servidores MCP já registados e os ganchos (hooks) são declarados no objeto extensions.com.openai do ficheiro plugin.json da raiz, enquanto a identidade portátil (name, version, description) permanece na raiz:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "notes-equipe",
  "version": "0.1.0",
  "description": "Team notes and meeting minutes",
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Team Notes",
        "shortDescription": "Notes and meeting minutes",
        "developerName": "Your Team",
        "category": "Productivity",
        "capabilities": ["Read", "Write"],
        "websiteURL": "https://example.com",
        "privacyPolicyURL": "https://example.com/privacy",
        "termsOfServiceURL": "https://example.com/terms",
        "defaultPrompt": ["Use Team Notes to draft Monday's meeting minutes."],
        "composerIcon": "./assets/icon.png",
        "logo": "./assets/logo.png"
      }
    }
  }
}

Os caminhos neste objeto são relativos à raiz do plugin e começam por ./. Os recursos visuais (composerIcon, logo, screenshots) devem preferencialmente ficar em ./assets/. O campo apps utiliza-se apenas para apontar para um ficheiro .app.json contendo mapeamentos para servidores MCP já registados no ChatGPT.

Pode também declarar uma competência de integração (onboarding skill) através de extensions.com.openai.onboardingSkill (por exemplo, ./skills/setup/SKILL.md): esta guia o utilizador após a instalação para escolher um espaço de trabalho ou definir preferências. Teste-a numa nova conversa e durante uma instalação em curso.

Um formato mais antigo, com um manifesto em .codex-plugin/plugin.json, ainda é aceite para compatibilidade: só é utilizado se o objeto extensions.com.openai estiver ausente, pois os dois não se fundem. Os novos pacotes devem utilizar o plugin.json da raiz.

A via rápida: @plugin-creator

O ChatGPT e o Codex incluem uma competência, @plugin-creator, que gera a estrutura para si — atualmente no formato de compatibilidade .codex-plugin/. Para ligar um servidor MCP ao mesmo, ligue primeiro esse servidor no ChatGPT (Add custom MCP server, depois Create as a plugin), anote o ID técnico da ligação a partir do URL do navegador — começa por plugin_asdk_app — e forneça-o ao @plugin-creator no modo Work (ou ao $plugin-creator no Codex). A competência pode também criar uma entrada de mercado pessoal, permitindo-lhe instalar e testar o plugin a partir da sua origem de diretório local.

Mercados locais

Um mercado é um catálogo JSON de plugins. Serve para escrita, testes e distribuição em equipa, paralelamente ao diretório público: no modo Work ou no Codex, cada mercado aparece como uma fonte selecionável no diretório de plugins. É assim que testará o plugin completo antes de o submeter (Lição 9).

Ganchos: apenas para ambiente de trabalho

Os ganchos de ciclo de vida (lifecycle hooks) são suportados apenas para plugins instalados manualmente na aplicação de ambiente de trabalho Codex, e um plugin que os contenha não é elegível para o diretório público. Se o seu plugin tiver como alvo a publicação, omita-os.

Pontos-chave

  • Um pacote portátil: plugin.json (esquema Agent Plugins), skills/, mcp.json, assets/
  • O servidor MCP é declarado em mcp.json com o seu tipo de transporte; a autenticação também vai para lá
  • A apresentação, os mapeamentos e a competência de integração vão para extensions.com.openai
  • @plugin-creator gera a estrutura; um mercado local serve para testes
  • Um plugin com ganchos não é elegível para o diretório público