{"meta":{"title":"Diretórios de plug-in","intro":"Um plug-in é um diretório que agrupa extensões do SDK — habilidades, ganchos, servidores MCP, agentes personalizados e configuração de LSP — por trás de um único manifesto. Apontar o SDK para um diretório de plug-ins carrega tudo o que os plug-ins fornecem, para que você possa disponibilizar pacotes reutilizáveis de recursos sem precisar escrever a integração específica de cada extensão em cada aplicação host.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos","title":"Instruções"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/plugin-directories","title":"Diretórios de plugin"}],"documentType":"article"},"body":"# Diretórios de plug-in\n\nUm plug-in é um diretório que agrupa extensões do SDK — habilidades, ganchos, servidores MCP, agentes personalizados e configuração de LSP — por trás de um único manifesto. Apontar o SDK para um diretório de plug-ins carrega tudo o que os plug-ins fornecem, para que você possa disponibilizar pacotes reutilizáveis de recursos sem precisar escrever a integração específica de cada extensão em cada aplicação host.\n\n\n\n\n\nEste guia explica o layout da pasta do plug-in, como carregar um plug-in de um diretório, quando usar diretórios de plug-in versus registrar extensões individuais e como tornar os conjuntos de plug-in determinísticos.\n\n## Quando usar diretórios de plug-in\n\nUse um diretório de plug-in quando quiser:\n\n* **Distribua um pacote de capacidades** como uma única unidade — por exemplo, um pacote \"revisor TypeScript\" com uma habilidade, um `preToolUse` hook que aplica a verificação de lint e um agente personalizado que executa o revisor.\n* **A funcionalidade do fornecedor é empacotada em um repositório** para que cada clone do aplicativo host carregue as mesmas extensões deterministicamente.\n* **Desenvolva um plug-in localmente** antes de publicá-lo em um marketplace.\n* **Substitua ou estenda** um plug-in instalado no marketplace com um check-out local para teste.\n\nSe você precisar adicionar apenas um servidor MCP, um único gancho ou um único agente personalizado, você poderá registrá-lo embutido por meio da configuração do SDK (`mcpServers`, `hooks`, `customAgents`). Os diretórios de plug-in são mais úteis quando você tem três ou mais extensões relacionadas que são enviadas juntas.\n\n## Estrutura da pasta do plugin\n\nA CLI do Copilot verifica cada diretório de plug-in para um manifesto `plugin.json` ou um `SKILL.md` de nível raiz. Um plug-in mínimo tem esta aparência:\n\n```text\nmy-plugin/\n├── plugin.json # manifest (required unless using SKILL.md only)\n├── SKILL.md # optional: top-level skill\n├── hooks.json # optional: hooks config\n├── .mcp.json # optional: MCP server config\n├── agents/ # optional: custom agents (one .md file per agent)\n│ └── code-reviewer.md\n└── skills/ # optional: additional skills\n └── lint-fix/\n └── SKILL.md\n```\n\nO manifesto também pode ficar em `.github/plugin.json` ou `.github/plugin/plugin.json`, para que os plug-ins possam ficar dentro de um repositório existente sem alterar sua estrutura raiz. Cada subsistema (ganchos, MCP, LSP, habilidades, agentes) tem seu próprio carregador e é opcional – um plug-in só precisa das partes que ele contribui.\n\nPara obter o esquema de manifesto completo, consulte a documentação de runtime referenciada no comando de barra da `/plugin` CLI.\n\n## Carregando um diretório de plug-in do SDK\n\nOs diretórios de plug-in são carregados passando `--plugin-dir ` para a CLI do Copilot quando o SDK o gera. Cada idioma expõe isso por meio da opção extra-args da conexão de runtime. A flag pode ser repetida para carregar vários plugins.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient, RuntimeConnection } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n connection: RuntimeConnection.forStdio({\n args: [\n \"--plugin-dir\", \"./plugins/code-reviewer\",\n \"--plugin-dir\", \"./plugins/lint-fix\",\n ],\n }),\n});\n\nawait client.start();\n```\n\n
\n\n
Python
\n\n\n\n```python\nfrom copilot import CopilotClient, StdioRuntimeConnection\n\nclient = CopilotClient(\n connection=StdioRuntimeConnection(\n args=(\n \"--plugin-dir\", \"./plugins/code-reviewer\",\n \"--plugin-dir\", \"./plugins/lint-fix\",\n ),\n ),\n)\nawait client.start()\n```\n\n
\n\n
Go
\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n Connection: copilot.StdioConnection{\n Args: []string{\n \"--plugin-dir\", \"./plugins/code-reviewer\",\n \"--plugin-dir\", \"./plugins/lint-fix\",\n },\n },\n})\nif err := client.Start(ctx); err != nil {\n return err\n}\n```\n\n
\n\n
.NET
\n\n```csharp\nusing GitHub.Copilot;\n\nawait using var client = new CopilotClient(new CopilotClientOptions\n{\n Connection = RuntimeConnection.ForStdio(args: new[]\n {\n \"--plugin-dir\", \"./plugins/code-reviewer\",\n \"--plugin-dir\", \"./plugins/lint-fix\",\n }),\n});\n\nawait client.StartAsync();\n```\n\n
\n\n
Java
\n\n```java\nvar options = new CopilotClientOptions()\n .setCliArgs(new String[] {\n \"--plugin-dir\", \"./plugins/code-reviewer\",\n \"--plugin-dir\", \"./plugins/lint-fix\",\n });\n\nvar client = new CopilotClient(options);\nclient.start().get();\n```\n\n
\n\n
Rust
\n\n```rust\nuse github_copilot_sdk::{Client, ClientOptions};\n\nlet client = Client::start(\n ClientOptions::new().with_extra_args([\n \"--plugin-dir\", \"./plugins/code-reviewer\",\n \"--plugin-dir\", \"./plugins/lint-fix\",\n ]),\n)\n.await?;\n```\n\n
\n\n
\n\n> O exemplo acima usa uma conexão de runtime stdio – o padrão quando o SDK agrupa a CLI. Se você se conectar a um runtime externo via uma URL (`forUri` / `ForUri`), passe `--plugin-dir` para o servidor CLI de longa duração ao iniciá-lo; o SDK não encaminha `--plugin-dir` para runtimes que ele não iniciou.\n\n## Diretórios de plug-in em pacote de host confiáveis\n\nOs aplicativos que enviam seus próprios plug-ins confiáveis podem registrá-los como uma opção de inicialização do cliente. O SDK envia o conjunto ordenado completo após se conectar e verificar o protocolo, antes que `start` retorne ou que qualquer sessão possa ser criada. Os caminhos devem ser absolutos; deixar a opção não definida ou vazia não realiza nenhuma chamada RPC.\n\nA opção equivalente em cada SDK é:\n\n| SDK | Opção de inicialização |\n| ------------------ | ----------------------------------------------------- |\n| Node.js/TypeScript | `builtinPluginDirectories: string[]` |\n| Python | `builtin_plugin_directories=[...]` |\n| Go | `BuiltinPluginDirectories: []string{...}` |\n| .NET | `BuiltinPluginDirectories = [...]` |\n| Java | `.setBuiltinPluginDirectories(List.of(Path.of(...)))` |\n| Rust | `.with_builtin_plugin_directories([...])` |\n\nEsse é um limite de confiança para plug-ins agrupados e controlados pelo aplicativo host. É diferente de `--plugin-dir`, que é um argumento de inicialização de processo da CLI para carregar explicitamente diretórios comuns de plug-ins. A opção de inicialização também funciona ao se conectar a um runtime existente porque é enviada por JSON-RPC em vez de encaminhada como um argumento de processo.\n\n## O que um plug-in pode contribuir\n\nCarregar um diretório de plug-in torna suas extensões visíveis para cada sessão criada pelo cliente. O tempo de execução mescla as extensões fornecidas pelo plug-in com tudo o que você registra diretamente no código:\n\n| O plugin contribui | Visível para a sessão como |\n| --------------------------------------------- | --------------------------------------------------------------- |\n| Habilidades (`SKILL.md`, `skills/*/SKILL.md`) | Itens no `session.skills.list()`; passíveis de injeção por nome |\n| Agentes personalizados (`agents/*.md`) | Pode ser enviado pela ferramenta `task(agent_type=...)` |\n| Ganchos (`hooks.json`) | Acionado junto com ganchos registrados por meio do SDK |\n| Servidores MCP (`.mcp.json`) | Ferramentas e recursos acessíveis por meio de `session.mcp.*` |\n| Servidores LSP (`.lsp.json`) | Inicializado por meio de `session.lsp.initialize(...)` |\n\nOs agentes de plugin são subagentes de primeira classe em [Modo de frota](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/fleet-mode): um agente pai pode despachá-los por `agent_type`, e o ambiente de execução dispara os hooks `subagentStart` / `subagentStop` para eles como faz com qualquer outro subagente.\n\n## Plug-ins do diretório vs plug-ins do marketplace\n\nO ambiente de execução tem duas maneiras de instalar plug-ins, e ambas acabam parecendo iguais para uma sessão:\n\n* Os **plugins do Marketplace / de repositório direto** são instalados de forma persistente por meio do comando de barra da `/plugin` CLI ou da `installedPlugins` configuração de usuário subjacente. Eles são *globais* — toda sessão executada com a mesma configuração de usuário consegue vê-los, e eles participam das regras de descoberta de plug-ins.\n* **`--plugin-dir` os plug-ins** são *explícitos e efêmeros* – eles se aplicam apenas ao processo da CLI que você iniciou com esse sinalizador. Eles têm precedência sobre a descoberta no ambiente e são desduplicados em relação às entradas do marketplace com o mesmo caminho de cache, de modo que o mesmo plug-in não seja carregado duas vezes quando ambas as origens fizerem referência a ele.\n\nPara aplicativos baseados em SDK, `--plugin-dir` geralmente é a escolha certa: mantém o conjunto de plug-ins sob o controle da sua aplicação, em vez de depender do estado do usuário em cada máquina.\n\n## Tornando os conjuntos de plug-in determinísticos\n\nQuando a máquina host puder ter outros plug-ins instalados (do marketplace ou personalizados), defina `COPILOT_PLUGIN_DIR_ONLY=true` no ambiente de execução para suprimir a descoberta automática de plug-ins. Somente os diretórios que você informar por meio de `--plugin-dir` serão carregados.\n\n
\n\nNode.js/TypeScript\n\n```typescript\nprocess.env.COPILOT_PLUGIN_DIR_ONLY = \"true\";\n\nconst client = new CopilotClient({\n connection: RuntimeConnection.forStdio({\n args: [\"--plugin-dir\", \"./plugins/code-reviewer\"],\n }),\n});\nawait client.start();\n```\n\n
\n\nUse isso em CI, em implantações de servidor sem cabeça e em qualquer lugar que você queira um conjunto de plug-in reproduzível que não dependa da configuração do usuário do host.\n\n## Inspecionando quais plug-ins foram carregados\n\nDepois que uma sessão for criada, liste os plug-ins ativos para confirmar se um diretório foi selecionado corretamente:\n\n
\n\nNode.js/TypeScript\n\n```typescript\nconst plugins = await session.rpc.plugins.list();\nfor (const plugin of plugins.plugins) {\n console.log(`${plugin.name} (${plugin.enabled ? \"enabled\" : \"disabled\"})`);\n}\n```\n\n
\n\nPlugins carregados via `--plugin-dir` aparecem nesta lista com o caminho do cache definido como o diretório que você forneceu. As instalações do Marketplace são marcadas com seu registro de origem.\n\n## Troubleshooting\n\n* **\"nenhum plugin.json ou SKILL.md encontrado no \\\"** – o diretório existe, mas não se qualifica como um plug-in. Adicione um `plugin.json` manifesto na raiz (ou abaixo `.github/`) ou inclua um nível `SKILL.md`superior.\n* **Plugin carregado, mas agentes/habilidades não estão visíveis** — verifique se o manifesto do plugin declara os agentes/habilidades que ele fornece ou use o layout implícito (`agents/*.md`, `skills/*/SKILL.md`). Em seguida, chame `session.rpc.skills.reload()` para pegar as alterações sem reiniciar.\n* **Hooks executados em duplicidade** — o runtime elimina duplicatas por `cache_path`, mas somente quando o mesmo diretório é referenciado tanto como uma instalação via marketplace quanto como um `--plugin-dir`. Se dois diretórios diferentes contiverem o mesmo plug-in, ambos serão carregados. Remova um ou use `COPILOT_PLUGIN_DIR_ONLY=true`.\n* **`--plugin-dir` ignorado ao se conectar a um runtime externo** – o SDK só encaminha args extras quando gera a própria CLI. Para runtimes externos (`forUri`/`ForUri`), passe `--plugin-dir` na linha de comando que inicia o servidor de runtime.\n\n## Related\n\n* [Agentes personalizados e orquestração de subagentes](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/custom-agents): escreva agentes que são distribuídos na pasta de um plug-in `agents/`.\n* [Habilidades personalizadas](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/skills): como `SKILL.md` arquivos são carregados e as regras de ordenação por nível de habilidade.\n* [Trabalhando com ganchos](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/hooks): hooks definidos por um plugin são acionados junto com hooks registrados no SDK.\n* [Usando servidores MCP com o SDK do GitHub Copilot](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp): os servidores MCP fornecidos pelo plug-in integram-se da mesma maneira que os registros embutidos.\n* [Modo de frota](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/fleet-mode): agentes fornecidos por plug-in podem ser despachados como subagentes."}