> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> Instale e compartilhe pacotes de skills de um repo, URL do git ou pasta local.

<Note>
  Os plugins estão em **beta**. O comportamento e a configuração podem mudar em versões futuras.
</Note>

Um **plugin** é um pacote de [skills](/pt-BR/cli/extensibility/skills/overview) que você pode
instalar de um repo do GitHub, de uma URL do git ou de uma pasta local e reutilizar em diferentes
projetos. Ao instalar um plugin, suas skills ficam disponíveis como
comandos de barra `/<plugin>:<skill>`, e ele também pode incluir automaticamente outros plugins dos quais depende.

Um plugin é simplesmente uma origem que contém:

```
my-plugin/
├── .devin-plugin/
│   └── plugin.json     # O manifesto do plugin
├── AGENTS.md           # Regras opcionais
└── skills/
    └── review/
        └── SKILL.md    # Um skill comum
```

O diretório `skills/` armazena skills comuns — os plugins não introduzem nenhum novo
formato de skill. Consulte [Criando Skills](/pt-BR/cli/extensibility/skills/creating-skills) para ver o
formato `SKILL.md`.

Um plugin também pode incluir **regras**: um `AGENTS.md` na raiz do plugin é
injetado como uma regra sempre ativa em toda sessão, junto com as
regras do seu projeto. Arquivos Markdown em uma pasta `rules/` também são carregados, com o mesmo
frontmatter `trigger` e os mesmos [tipos de ativação](/pt-BR/cli/extensibility/rules#rule-activation-types)
das [regras do Windsurf](/pt-BR/cli/extensibility/rules#rules-from-other-tools).

***

<div id="installing-a-plugin">
  ## Instalando um plugin
</div>

A origem de um plugin pode ser um `owner/repo` do GitHub, uma URL do git ou um caminho local:

```bash theme={null}
# Do GitHub
devin plugins install acme/review-tools

# De qualquer host git
devin plugins install https://gitlab.com/acme/review-tools.git

# De uma pasta local (ótimo para criação)
devin plugins install ./my-plugin
```

Antes de instalar, o Devin mostra o que o plugin adiciona — os skills que ele fornece,
quais plugins obrigatórios serão instalados automaticamente e quaisquer políticas que ele introduza
(por exemplo, se ele proíbe outros plugins). Use `-y` / `--yes` para pular o
prompt.

Os plugins são instalados no nível de **usuário** e ficam disponíveis em todos os seus
projetos.

***

<div id="managing-plugins">
  ## Gerenciamento de plugins
</div>

```bash theme={null}
# Lista os plugins instalados, suas versões e se algum está bloqueado por política
devin plugins list

# Exibe as skills de um plugin e suas listas de obrigatórios/opcionais/proibidos
devin plugins info review-tools

# Rebusca um plugin (ou todos os plugins) na versão mais recente
devin plugins update review-tools
devin plugins update

# Remove um plugin (plugins obrigatórios instalados automaticamente são mantidos no lugar)
devin plugins remove review-tools
```

Plugins locais ficam vinculados diretamente à pasta de origem, então as edições entram em vigor em tempo real:
`devin plugins install ./my-plugin` → edite `skills/<name>/SKILL.md` → as alterações
são aplicadas na próxima sessão, sem precisar de `update`.

***

<div id="the-manifest">
  ## O manifesto
</div>

`.devin-plugin/plugin.json` descreve o plugin. Apenas `name` é obrigatório, e
ele deve ser único entre os plugins instalados (é o namespace `/<name>:…`).

```jsonc theme={null}
{
  "name": "review-tools",
  "version": "1.0.0",
  "description": "Code-review skills for our team",
  "requiredPlugins": [
    "acme/secure-base",
    { "source": "github", "repo": "acme/audit-logging" }
  ],
  "optionalPlugins": [
    "acme/deploy-tools",
    { "source": "url", "url": "https://gitlab.com/acme/extra.git" }
  ],
  "forbiddenPlugins": ["sketchy-org/bad-plugin", "acme/*", "*"]
}
```

Campos de metadados suportados: `name`, `version`, `description`, `author`
(`{ name, email }`), `homepage`, `repository`, `license` e `keywords`.

Uma entrada de dependência é uma **origem** — pode ser uma string abreviada ou um objeto:

| Forma                                                              | Significado                                               |
| ------------------------------------------------------------------ | --------------------------------------------------------- |
| `"owner/repo"`                                                     | repositório GitHub                                        |
| `"https://…"`, `"git@…"`, `"ssh://…"`                              | qualquer URL do git                                       |
| `{ "source": "github", "repo": "owner/repo" }`                     | GitHub, em formato de objeto                              |
| `{ "source": "url", "url": "https://gitlab.com/team/plugin.git" }` | URL do git, em formato de objeto                          |
| `{ "source": "git-subdir", "url": "…", "path": "sub/dir" }`        | um plugin em uma subpasta de um repositório compartilhado |

Todas as formas do GitHub para o mesmo repositório (`owner/repo`, a URL HTTPS, a URL `.git` e a forma SSH) se referem à mesma identidade do plugin.

***

<div id="dependencies-and-governance">
  ## Dependências e governança
</div>

Um plugin pode declarar três listas, permitindo que um único plugin funcione como uma coleção curada e governada
de outros plugins.

<div id="requiredplugins">
  ### `requiredPlugins`
</div>

Instalado automaticamente (de forma recursiva) quando o plugin é instalado. Se um plugin obrigatório
for bloqueado por uma política, a instalação inteira falha — não há instalação parcial.

<div id="optionalplugins">
  ### `optionalPlugins`
</div>

Uma **lista de permissões** de plugins que este plugin aprova. Eles **não** são
instalados automaticamente; a lista só serve como uma exceção para uma entrada proibida
(veja abaixo).

<div id="forbiddenplugins">
  ### `forbiddenPlugins`
</div>

Uma **lista de bloqueio** de identidades de plugin e padrões glob.

As entradas de `forbiddenPlugins` são comparadas com identidades de plugin:

* Uma **identidade exata**, escrita como `owner/repo` ou uma URL do git. Todas as formas do GitHub para o mesmo repo (`owner/repo`, a URL HTTPS, a URL `.git`, a forma SSH) se referem à mesma identidade.
* Um **padrão glob** — qualquer entrada que contenha `*`. O `*` corresponde a qualquer sequência de caracteres, incluindo `/`: `acme/*` corresponde a todos os repos do GitHub de `acme`, `*/secrets` corresponde a um repo chamado `secrets` em qualquer owner, e `https://gitlab.com/acme/*` corresponde a qualquer repo nesse caminho.
* Um `"*"` isolado, que corresponde a todo o restante (um bloqueio total).

As listas são combinadas com precedência da negação:

* **A negação prevalece.** Um plugin é bloqueado se qualquer manifesto ativo ou plugin instalado o proibir. Se nada proíbe nada, nada é bloqueado.
* **Auto-override.** Os `requiredPlugins` e `optionalPlugins` de um manifesto (ou plugin) — e, no caso de um plugin, o próprio plugin — ficam isentos da sua **própria** lista de proibidos. Assim, `"forbiddenPlugins": ["*"]` mais `"optionalPlugins": ["acme/approved"]` significa "permitir apenas o que este manifesto lista; proibir todo o restante". A exceção cobre apenas essas entradas diretas, não as dependências transitivas de um plugin obrigatório — liste-as explicitamente em um bloqueio total.
* **Sem repermissão entre escopos.** A lista de permissões de um manifesto ou plugin não pode voltar a permitir o que **outro** proíbe. Um bloqueio total com `"forbiddenPlugins": ["*"]` não pode ser contornado a partir de um escopo inferior.

A aplicação ocorre em dois momentos:

* **No momento da instalação** — a instalação de um plugin bloqueado (ou de um cujos plugins obrigatórios não possam ser atendidos, ou cujo nome colida com o de um plugin instalado) é recusada.
* **No momento do carregamento** — um plugin bloqueado depois de já estar instalado permanece no disco, mas suas skills são ignoradas no início da sessão, com um aviso informando quem fez o bloqueio.

Uma identidade proibida também pode ser um **caminho local** (para plugins instalados a partir de uma pasta local), além das formas `owner/repo` e URL do git acima.

***

<div id="inheritance-and-levels">
  ## Herança e níveis
</div>

Os plugins não são declarados em um único lugar. Além das instalações que você faz, os plugins podem ser
obrigatórios, recomendados ou proibidos pelo seu repo e pelo administrador da sua organização.
Cada origem é um **nível**, e os níveis são classificados por **autoridade**, da mais alta
para a mais baixa:

1. **Enterprise** — o manifesto gerenciado em nível da conta, configurado por um administrador.
2. **Org** — um manifesto gerenciado no nível da organização, em uma camada abaixo da conta (uma organização
   pode acrescentar ao que a conta declara, mas não pode se sobrepor a isso). Isso se aplica
   apenas a **sessões em nuvem do Devin**: a CLI autentica no nível da conta
   e não tem contexto de organização, portanto exigências e proibições no nível da organização não alcançam usuários da CLI.
   Coloque tudo o que precisar ser aplicado na CLI no manifesto da Enterprise/conta.
3. **Repo** — os `requiredPlugins` / `optionalPlugins` / `forbiddenPlugins` em um
   `.devin/config.json` de um checkout, encontrados ao subir a partir do seu diretório de trabalho.
4. **User** — plugins que você instala com `devin plugins install`.

Cada nível declara as mesmas três listas e, dentro de um nível, elas se combinam com
as mesmas [regras em que a negação prevalece e de override próprio](#dependencies-and-governance) de um
único manifesto. O que os níveis acrescentam além disso é uma regra: **a autoridade mais alta
prevalece**.

<div id="higher-authority-wins">
  ### A autoridade superior prevalece
</div>

* Um nível inferior nunca pode **voltar a permitir** o que um nível superior proíbe.
* Um nível inferior nunca pode **proibir** o que um nível superior exige — a proibição é
  ignorada e o plugin ainda é carregado.

Assim, um admin pode tornar obrigatório um plugin do qual nenhum repo ou user pode abrir mão e proibir um
plugin que nenhum nível inferior pode reabilitar.

<div id="a-denylist-is-only-overridden-at-its-own-level">
  ### Uma lista de bloqueio só é sobrescrita no próprio nível
</div>

Como as listas de permissão não se aplicam entre níveis, a **única** maneira de criar uma exceção
a uma lista de bloqueio é no mesmo nível que a declarou. O `forbiddenPlugins`
de um nível só é sobrescrito pelo próprio `optionalPlugins` (ou
`requiredPlugins`) desse mesmo manifesto — nunca por uma lista em um nível inferior.

Por exemplo, um manifesto gerenciado em nível Enterprise pode restringir a conta a um
único plugin aprovado:

```jsonc theme={null}
// Manifest gerenciado em nível Enterprise
{
  "forbiddenPlugins": ["*"],
  "optionalPlugins": ["acme/approved"]
}
```

Isso significa "em toda a conta, permitir apenas `acme/approved` e proibir
qualquer outro plugin." Nenhuma org, repo ou usuário pode ampliar essa
lista de permissões — nem instalando um plugin, nem adicionando-o ao
`optionalPlugins` de um nível inferior. A exceção também cobre apenas as
entradas que este manifesto lista diretamente; as dependências transitivas de
um plugin obrigatório não estão isentas, portanto liste-as explicitamente em
um bloqueio.

<div id="conflicts-and-dependencies">
  ### Conflitos e dependências
</div>

* Um require e um forbid para o mesmo plugin no **mesmo nível**, mas em
  **manifestos diferentes** (por exemplo, dois plugins de nível de usuário
  instalados separadamente) resultam na prevalência do forbid — uma lista de permissões
  só isenta entradas do seu *próprio* manifesto, então não pode livrar um
  plugin que outro manifesto proíbe. (Dentro de um único manifesto, seus próprios
  require/optional continuam isentos de seus próprios forbids,
  como [acima](#a-denylist-is-only-overridden-at-its-own-level).)
* Um plugin bloqueado por governança **falha de forma não fatal**: no início da sessão, suas skills são
  ignoradas com um aviso que identifica quem aplicou o forbid, em vez de abortar a sessão.
* Ser usado como dependência não concede isenção. Um plugin incluído apenas como uma
  dependência transitiva ainda está sujeito a todo forbid aplicável a ele e
  herda o nível de autoridade mais alto de qualquer plugin que o exija.