# referência de plugin da CLI GitHub Copilot Encontre comandos e detalhes de configuração para plug-ins da CLI. > \[!NOTE] > Você pode encontrar ajuda para usar plug-ins entrando `copilot plugin [SUBCOMMAND] --help` no terminal. Para obter uma visão geral do que são plug-ins e como eles funcionam entre Copilot clientes, consulte [Sobre plug-ins GitHub Copilot](/pt/copilot/concepts/agents/about-plugins). ## Comandos da CLI Você pode usar os seguintes comandos no terminal para gerenciar plug-ins para CLI do Copilot. `copilot plugin` e `copilot plugins` são equivalentes — use o que soar melhor para o subcomando. | Command | Descrição | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `copilot plugin install SPECIFICATION` | Instale um plug-in. Consulte [Especificação do plugin para `install` o comando](#plugin-specification-for-install-command) abaixo. | | `copilot plugin uninstall NAME` | Remover um plug-in | | `copilot plugin list` | Listar plug-ins instalados | | `copilot plugin update NAME` | Atualize um plug-in nomeado. Use `--all` para atualizar todos os plug-ins instalados ao mesmo tempo. | | `copilot plugin enable NAME` | Habilitar um plug-in desabilitado anteriormente | | `copilot plugin disable NAME` | Desabilitar um plug-in sem desinstalá-lo | | `copilot plugin marketplace add SPECIFICATION` | Registre um mercado. O próprio nome do marketplace, a partir de seu `marketplace.json` manifesto, torna-se sua chave de registro— não há nenhuma opção para definir um nome local personalizado. | | `copilot plugin marketplace list` | Listar marketplaces registrados | | `copilot plugin marketplace browse NAME` | Navegue pelos plugins do marketplace | | `copilot plugin marketplace update [NAME]` (também conhecido como `refresh`) | Buscar novamente o catálogo de plug-ins do marketplace. Omita `NAME` para atualizar os catálogos de cada marketplace registrado. | | `copilot plugin marketplace remove NAME` | Cancelar o registro de um marketplace. Será recusado se plugins do Marketplace ainda estiverem instalados; passe `--force` para também desinstalar esses plugins. | De forma não interativa, `copilot plugins enable NAME --plugin`, `copilot plugins disable NAME --plugin` e `copilot plugins remove NAME --plugin` fornecem as mesmas operações de habilitar, desabilitar e desinstalar. `--plugin` é o tipo padrão e pode ser omitido para esses três comandos. Consulte [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-plugins-list) para os tipos `--mcp` não interativos `--skill`, que estendem esses comandos para servidores MCP e habilidades. ### Especificação do plug-in para `install` comando | Formato | Exemplo | Descrição | | ---------------------------- | ---------------------------- | ------------------------------------ | | Marketplace | `plugin@marketplace` | Plug-in de um marketplace registrado | | GitHub | `OWNER/REPO` | Raiz de um GitHub repositório | | GitHub subdiretório | `OWNER/REPO:PATH/TO/PLUGIN` | Subdiretório em um repositório | | Git URL | `https://github.com/o/r.git` | Qualquer URL do Git | | Caminho local | | | | `./my-plugin` ou `/abs/path` | Diretório local | | ### `copilot plugins install` opções Além de instalar um plug-in a partir de uma especificação, o `copilot plugins install` pode instalar uma skill individual a partir de um arquivo, de uma URL ou de um diretório com `--skill`. A instalação de uma skill não é uma instalação de plug-in e não passa por uma loja — consulte [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#skills-reference) para ver detalhes sobre as skills em si. | Opção | Descrição | | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | | `--plugin` | Instale um plug-in (padrão). | | | `--skill` | Instale uma habilidade de um caminho ou URL local. | | | `--scope SCOPE` | Para instalar um arquivo ou uma URL `--skill`: `user` (padrão) ou `project`. | | | `project` limita a instalação ao diretório `.github/skills` do repositório atual, em vez de à sua conta de usuário, e se aplica apenas a instalações de habilidades por arquivo ou URL. | | | | `--config-dir=DIRECTORY` | Caminho para o diretório de configuração. Essa opção foi preterida. Use `COPILOT_HOME` em seu lugar. | | Instalar um diretório registra-o como uma fonte de habilidade personalizada em vez de copiá-lo; A instalação de um arquivo ou URL copia o conteúdo da habilidade no diretório de habilidades pessoais ou de projeto. Os servidores MCP são instalados a partir de um registro configurado por política, que requer autenticação e entrada de segredo interativa. Use o `/plugins` dashboard (modo Online) ou o `/mcp` comando de barra para adicionar servidores MCP em vez de `copilot plugins install`. ### `copilot plugins update` opções | Opção | Descrição | | ------- | -------------------------------- | | `--all` | Atualizar cada plug-in instalado | ### `copilot plugins marketplace` Subcomandos Os marketplaces padrão integrados acompanham o runtime e não podem ser removidos. | Subcommand | Descrição | | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `list [--json]` | Listar todos os marketplaces registrados, incluindo padrões internos | | `add SOURCE` | Adicionar um marketplace (`owner/repo`, `owner/repo#ref`uma URL ou um caminho local) | | `remove NAME [--force]` | Remover um marketplace; `--force` também desinstala plug-ins provenientes dele | | `browse NAME [--json]` | Listar os plug-ins oferecidos pelo catálogo de um marketplace | | `update [NAME]` (também conhecido como `refresh`) | Atualizar o catálogo de plugins para um marketplace ou para todos, se `NAME` for omitido | ## `plugin.json` Todos os plug-ins consistem em um diretório de plug-in contendo, no mínimo, um arquivo de manifesto chamado `plugin.json` localizado na raiz do diretório do plug-in. Consulte [Criando um plug-in para CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating). ### Campo obrigatório | Campo | Tipo | Descrição | | ------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | cadeia | Nome do plugin Kebab-case (apenas letras, números e hífens). Máximo de 64 chars. Plug-ins que optam pelo [suporte ao Open Plugin Spec](#open-plugin-spec-support) também podem usar os pontinhos (por exemplo, `acme.tools`). | ### Campos de metadados opcionais | Campo | Tipo | Descrição | | ----------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `$schema` | cadeia | Defina para a URL canônica do esquema Agent Plugins (Especificação Aberta de Plug-ins) v1.0.0 para adotar a semântica da especificação. Consulte [o suporte ao Open Plugin Spec](#open-plugin-spec-support). | | `description` | cadeia | Breve descrição. Máximo de 1024 caracteres. | | `version` | cadeia | Versão semântica (por exemplo, `1.0.0`). | | `author` | objeto | | | `name` (obrigatório), `email` (opcional), `url` (opcional). | | | | `homepage` | cadeia | URL da página inicial do plugin. | | `repository` | cadeia | URL do repositório de origem. | | `license` | cadeia | Identificador de licença (por exemplo, `MIT`). | | `keywords` | cadeia de caracteres\[] | Pesquisar palavras-chave. | | `category` | cadeia | Categoria de plug-in. | | `tags` | cadeia de caracteres\[] | Etiquetas adicionais. | ### Campos de caminho do componente Elas indicam à CLI onde encontrar os componentes do seu plug-in. Todos são opcionais. A CLI usa convenções padrão se omitidas. | Campo | Tipo | Default | Descrição | | ------------ | ----------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agents` | cadeia de caracteres \| cadeia de caracteres\[] | `agents/` | Caminhos para diretórios de agente (`.agent.md` arquivos). | | `skills` | cadeia de caracteres \| cadeia de caracteres\[] | `skills/` | Caminhos para diretórios de habilidades (`SKILL.md` arquivos). | | `commands` | cadeia de caracteres \| cadeia de caracteres\[] | — | Caminhos para diretórios de comando. | | `hooks` | objeto string \| | — | Caminho para um arquivo de configuração de ganchos ou um objeto de ganchos embutido. | | `extensions` | string \| string\[] \| object | — | Caminhos para diretórios de extensão. Use `{ paths: [...], exclusive: true }` para suprimir extensões internas. No [modo de Especificação do Plug-in Aberto](#open-plugin-spec-support), esse campo tem um significado diferente. | | `mcpServers` | objeto string \| | — | Caminho para um arquivo de configuração MCP (por exemplo, `.mcp.json`) ou definições de servidor embutido. | | `lspServers` | objeto string \| | — | Caminho para um arquivo de configuração do LSP, ou definições de servidor em linha. | ### Arquivo de exemplo `plugin.json` ```json copy { "name": "my-dev-tools", "description": "React development utilities", "version": "1.2.0", "author": { "name": "Jane Doe", "email": "jane@example.com" }, "license": "MIT", "keywords": ["react", "frontend"], "agents": "agents/", "skills": ["skills/", "extra-skills/"], "hooks": "hooks.json", "mcpServers": ".mcp.json" } ``` ## Suporte à Especificação Aberta de Plugins Declarar o `$schema` canônico em `plugin.json` faz com que um plug-in adote o formato [Agent Plugins (Open Plugin Spec)](https://agent-plugins.org) v1.0.0, de forma adicional ao carregamento padrão de plug-ins: ### Configuração do servidor LSP Para incluir servidores LSP (Language Server Protocol) em um plug-in, crie um `lsp-config/servers.json` arquivo no diretório do plug-in ou especifique um caminho ou objeto embutido usando o `lspServers` campo em `plugin.json`. Exemplo `lsp-config/servers.json` (ou em linha via `lspServers` em `plugin.json`): ```json { "lspServers": { "my-lsp": { "command": "my-language-server", "fileExtensions": { ".myext": "mylang" } } } } ``` Para suporte multiplataforma, use `bash` e `powershell` , em vez de `command`: ```json { "lspServers": { "my-lsp": { "bash": "${PLUGIN_ROOT}/scripts/start-lsp.sh", "powershell": "${PLUGIN_ROOT}/scripts/start-lsp.ps1", "fileExtensions": { ".myext": "mylang" } } } } ``` | Campo | Tipo | Obrigatório | Descrição | | ----------------------- | ----------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- | | `command` | cadeia | \* | Executável para iniciar o servidor de idiomas. | | `bash` | cadeia | \* | Script bash para iniciar o servidor (Linux/macOS); executado por meio de `bash -c SCRIPT`. | | `powershell` | cadeia | \* | Script do PowerShell para iniciar o servidor (Windows); executado por meio de `pwsh -c SCRIPT`. | | `cwd` | cadeia | No | Diretório de trabalho. Absoluto ou relativo ao arquivo de configuração. Oferece suporte para `${PLUGIN_ROOT}`. | | `args` | cadeia de caracteres\[] | No | Argumentos a serem passados para `command` (ignorados para `bash` e `powershell`). | | `env` | objeto | No | Variáveis de ambiente a serem definidas ao gerar o servidor. | | `fileExtensions` | objeto | Sim | Mapa de extensões de arquivo para IDs de idioma (por exemplo, `{ ".ts": "typescript" }`). | | `rootUri` | cadeia | No | Raiz do projeto em relação à raiz do Git (padrão: `.`). | | `initializationOptions` | any | No | Opções enviadas ao servidor na solicitação LSP `initialize` . | (\*) Pelo menos um de `command`, `bash`ou `powershell` é necessário. Quando `bash` e `powershell` são especificados, o apropriado para a plataforma é selecionado automaticamente (PowerShell no Windows, Bash em outro lugar). Use `${PLUGIN_ROOT}` para referenciar caminhos no diretório do plug-in. ## `marketplace.json` Você pode criar um marketplace de plug-ins, que as pessoas podem usar para descobrir e instalar seus plug-ins, criando um `marketplace.json` arquivo e salvando-o no `.github/plugin/` diretório do repositório. Você também pode armazenar o `marketplace.json` arquivo em seu sistema de arquivos local. Por exemplo, salvar o arquivo como `/PATH/TO/my-marketplace/.github/plugin/marketplace.json` permite adicioná-lo à CLI usando o seguinte comando: ```shell copilot plugin marketplace add /PATH/TO/my-marketplace ``` > \[!NOTE] > O CLI do Copilot também procura o arquivo `marketplace.json` no diretório `.claude-plugin/`. Para obter mais informações, consulte [Criando um marketplace de plugin para CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace). ### Arquivo de exemplo `marketplace.json` ```json copy { "name": "my-marketplace", "owner": { "name": "Your Organization", "email": "plugins@example.com" }, "metadata": { "description": "Curated plugins for our team", "version": "1.0.0" }, "plugins": [ { "name": "frontend-design", "description": "Create a professional-looking GUI ...", "version": "2.1.0", "source": "./plugins/frontend-design" }, { "name": "security-checks", "description": "Check for potential security vulnerabilities ...", "version": "1.3.0", "source": "./plugins/security-checks" } ] } ``` > \[!NOTE] > O valor do `source` campo para cada plug-in é o caminho para o diretório do plug-in, em relação à raiz do repositório. Não é necessário usar `./` no início do caminho. Por exemplo, `"./plugins/plugin-name"` e `"plugins/plugin-name"` resolvem para o mesmo diretório. ### Campos `marketplace.json` #### Campos de nível superior | Campo | Tipo | Obrigatório | Descrição | | ---------------------------------------------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | cadeia | Sim | Nome do mercado de kebabs. Máximo de 64 chars. Pontos também são aceitos (por exemplo, `acme.tools`) para plug-ins da [Especificação Aberta de Plug-ins](#open-plugin-spec-support). | | `owner` | objeto | Sim | | | `{ name, email? }` — informações do proprietário do marketplace. | | | | | `plugins` | matriz | Sim | Lista de entradas de plug-in (consulte a tabela abaixo). | | `metadata` | objeto | No | `{ description?, version?, pluginRoot? }` | #### Campos de entrada de plug-in (objetos dentro da `plugins` matriz) | Campo | Tipo | Obrigatório | Descrição | | ------------- | ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | cadeia | Sim | Nome do plugin Kebab-case. Máximo de 64 chars. Os pontos também são aceitos para [plug-ins Open Plugin Spec](#open-plugin-spec-support). | | `source` | objeto string \| | Sim | Onde buscar o plug-in (caminho relativo GitHub ou URL). | | `description` | cadeia | No | Descrição do plug-in. Máximo de 1024 caracteres. | | `version` | cadeia | No | Versão do plug-in. | | `author` | objeto | No | `{ name, email?, url? }` | | `homepage` | cadeia | No | URL da página inicial do plugin. | | `repository` | cadeia | No | URL do repositório de origem. | | `license` | cadeia | No | Identificador de licença. | | `keywords` | cadeia de caracteres\[] | No | Pesquisar palavras-chave. | | `category` | cadeia | No | Categoria de plug-in. | | `tags` | cadeia de caracteres\[] | No | Etiquetas adicionais. | | `commands` | cadeia de caracteres \| cadeia de caracteres\[] | No | Caminhos para diretórios de comando. | | `agents` | cadeia de caracteres \| cadeia de caracteres\[] | No | Caminhos para diretórios de agente. | | `skills` | cadeia de caracteres \| cadeia de caracteres\[] | No | Caminhos para diretórios de habilidades. | | `hooks` | objeto string \| | No | Caminho para a configuração de ganchos ou objeto de ganchos embutidos. | | `mcpServers` | objeto string \| | No | Servidores MCP a serem ativados quando o plugin é instalado. Aceita um mapa de servidor embutido ou um caminho para um arquivo de configuração JSON. Usado quando a origem do plug-in não envia sua própria configuração de MCP. | | `lspServers` | objeto string \| | No | Caminho para a configuração do LSP ou definições de servidor em linha. | | `strict` | boolean | No | Quando `true` (o padrão), os plug-ins devem estar em conformidade com o esquema completo e as regras de validação. Quando `false` a validação relaxada é usada, permite mais flexibilidade, especialmente para instalações diretas ou plugins legados. | #### Tipos de origem de plug-in O campo `source` em uma entrada de plugin aceita uma string de caminho relativo ou um objeto que descreve um repositório GitHub ou uma origem de URL do Git: ```json { "source": { "source": "github", "repo": "owner/repo", "ref": "v1.0.0", "path": "plugins/my-plugin" } } ``` Os tipos de origem `github` e `url` aceitam um campo opcional `sha` para fixar as instalações em um commit exato, além de (ou em vez de) `ref`: ```json { "source": { "source": "github", "repo": "owner/repo", "sha": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3", "path": "plugins/my-plugin" } } ``` `sha` deve ser um SHA completo de commit com 40 caracteres. Fixe em um `sha` para instalações reproduzíveis que são imunes a pushes forçados ou movimentos de marca/ramificação. ## Locais de arquivos | Item | Caminho | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Plug-ins instalados | | | `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME` (instalado por meio de um marketplace) e `~/.copilot/installed-plugins/_direct/SOURCE-ID/` (instalado diretamente) | | | Cache do Marketplace | Diretório de cache de plataforma: `~/.cache/copilot/marketplaces/` (Linux) `~/Library/Caches/copilot/marketplaces/` (macOS). Substituível por `COPILOT_CACHE_HOME`. | | Manifesto do Plugin | | | `.plugin/plugin.json`, `plugin.json`ou `.github/plugin/plugin.json``.claude-plugin/plugin.json` (verificado nesta ordem) | | | Manifesto do Marketplace | | | `marketplace.json`, `.plugin/marketplace.json`ou `.github/plugin/marketplace.json``.claude-plugin/marketplace.json` (verificado nesta ordem) | | | Agentes | | | `agents/` (padrão, substituível no manifesto) | | | Habilidades | | | `skills/` (padrão, substituível no manifesto) | | | Configuração de ganchos | | | `hooks.json` ou `hooks/hooks.json` | | | Configuração do MCP | | | `.mcp.json`, `.github/mcp.json` | | | Configuração de LSP | | | `lsp.json` ou `.github/lsp.json` | | | Dados de plug-in | | | `${COPILOT_PLUGIN_DATA}` (também disponível como `${CLAUDE_PLUGIN_DATA}`). Aponta para um diretório persistente, com permissão de gravação, exclusivo para cada plug-in instalado. Use isso para dados de runtime específicos do plug-in em vez de caminhos dentro do diretório de cache de plug-ins instalados. | | ## Ordem e precedência de carregamento Se você instalar vários plug-ins, é possível que alguns agentes personalizados, habilidades, servidores MCP ou ferramentas fornecidas por meio de servidores MCP tenham nomes duplicados. Nessa situação, a CLI determina qual componente usar com base em uma ordem de precedência. * **Agentes e habilidades** use a precedência do primeiro encontrado. Se você tiver um agente personalizado no nível do projeto ou uma habilidade cujo nome ou ID sejam iguais a os de um plug-in que você instalar, o agente ou habilidade do plug-in será ignorado sem aviso. O plug-in não pode substituir configurações pessoais ou no nível do projeto. Os agentes personalizados são desduplicados usando seu ID, que é derivado de seu nome de arquivo (por exemplo, se o arquivo for nomeado `reviewer.agent.md`, a ID do agente será `reviewer`). As habilidades são desduplicadas pelo campo do nome dentro do arquivo `SKILL.md`. * **Os servidores MCP** usam a precedência "último a vencer". Se você instalar um plug-in que define um servidor MCP com o mesmo nome de servidor que um servidor MCP já instalado, a definição do plug-in terá precedência. Você pode usar a opção `--additional-mcp-config` de linha de comando para substituir uma configuração de servidor MCP com o mesmo nome, instalado usando um plug-in. Se dois ou mais plug-ins declararem um servidor MCP com o mesmo nome, a CLI usará a versão do plug-in que carregou por último e mostrará um aviso nomeando cada plug-in anterior que o definiu. * **Ferramentas e agentes internos** estão sempre presentes e não podem ser substituídos por componentes definidos pelo usuário. O diagrama a seguir ilustra as regras de ordem e precedência de carregamento. ```text ┌──────────────────────────────────────────────────────────────────┐ │ BUILT-IN - HARDCODED, ALWAYS PRESENT │ │ • tools: bash, view, apply_patch, glob, rg, task, ... │ │ • agents: explore, task, code-review, general-purpose, research │ └────────────────────────┬─────────────────────────────────────────┘ │ ┌──────────────────────▼──────────────────────────────────────────────┐ │ CUSTOM AGENTS - FIRST LOADED IS USED (dedup by ID) │ │ 1. ~/.copilot/agents/ (user, .github convention) │ │ 2. /.github/agents/ (project) │ │ 3. /.github/agents/ (inherited, monorepo) │ │ 4. /.claude/agents/ (project) │ │ 5. /.claude/agents/ (inherited, monorepo) │ │ 6. PLUGIN: agents/ dirs (plugin, by install order) │ │ 7. Remote org/enterprise agents (remote, via API) │ └──────────────────────┬──────────────────────────────────────────────┘ │ ┌──────────────────────▼──────────────────────────────────────────────┐ │ AGENT SKILLS - FIRST LOADED IS USED (dedup by name) │ │ 1. /.github/skills/ (project) │ │ 2. /.agents/skills/ (project) │ │ 3. /.claude/skills/ (project) │ │ 4. /.github/skills/ etc. (inherited) │ │ 5. ~/.copilot/skills/ (personal-copilot) │ │ 6. ~/.agents/skills/ (personal-agents) │ │ 7. PLUGIN: skills/ dirs (plugin) │ │ 8. COPILOT_SKILLS_DIRS env + config (custom) │ │ --- then commands (.claude/commands/), skills override commands ---│ └──────────────────────┬──────────────────────────────────────────────┘ │ ┌──────────────────────▼──────────────────────────────────────────────┐ │ MCP SERVERS - LAST LOADED IS USED (dedup by server name) │ │ 1. ~/.copilot/mcp-config.json (lowest priority) │ │ 2. PLUGIN: MCP configs (plugins) │ │ 3. --additional-mcp-config flag (highest priority) │ └─────────────────────────────────────────────────────────────────────┘ ``` ## Leitura adicional * [Sobre os padrões de plug-in gerenciados pela empresa](/pt/copilot/concepts/agents/about-enterprise-plugin-standards) * [CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli) * [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference) * [referência programática do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-programmatic-reference)