# Extension Profiles

> Selecione um conjunto determinístico de plugins já instalados e skills standalone sem misturá-lo
> com perfis de agentes, configurações, permissões ou segredos.

Um Extension Profile responde a uma pergunta: **quais extensões instaladas devem ficar disponíveis
nas próximas execuções?** Ele é uma allow-list nomeada e determinística que você pode revisar,
compartilhar, selecionar e diagnosticar. Ele não escolhe modelo ou agente, altera sandbox ou
permissões, guarda segredos nem fixa versões de plugins.

Descoberta e instalação são separadas da ativação. O compositor de `/extensions` pode instalar um
plugin do marketplace durante a criação do rascunho, mas esse plugin permanece inativo até você
revisar e aplicar o delta completo do perfil.

## Comece pelo padrão builtin

`builtin:default` é virtual e imutável:

- `enabledPlugins` seleciona instalações exatas de plugins por `{ scope, source, name }`;
- plugins habilitados fornecem todos os seus agentes, skills, servidores MCP, serviços de capacidade
  e hooks;
- as ferramentas anunciadas por esses servidores MCP ficam disponíveis para todos os agentes
  efetivos nas próximas execuções, sem editar o agent profile salvo;
- as quatro raízes de skills standalone ficam disponíveis com a precedência existente.

Use um Extension Profile customizado quando precisar de uma allow-list isolada que não herde um plugin da
lista de ativação builtin.

## Componha e selecione na TUI

Abra `/extensions` e pressione Enter. O Clarvis conduz a mudança completa em cinco decisões:

1. escolha se a seleção será local deste workspace ou o padrão global;
2. edite um Extension Profile existente, clone o snapshot ativo ou comece uma definição vazia;
3. pesquise listagens do marketplace, plugins instalados exatos e skills standalone em um picker;
4. revise cada agente, skill de plugin, skill standalone, servidor MCP, hook e executável de
   capacidade;
5. revise o delta completo de ativação, aprove o fingerprint exato do workspace quando necessário,
   aplique e reconecte.

<figure class="tui-shot">
  <img src="/images/tui/environment-step-1-scope.svg" alt="Compositor de Extension Profile do Clarvis perguntando se a seleção será global ou local ao workspace" loading="lazy" decoding="async" />
  <figcaption><strong>Etapa 1 — escopo.</strong> Decida onde a seleção pertence antes de editar qualquer definição.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/environment-step-2-definition.svg" alt="Compositor de Extension Profile do Clarvis oferecendo a definição ativa, um clone e uma definição vazia" loading="lazy" decoding="async" />
  <figcaption><strong>Etapa 2 — definição.</strong> Edite, clone ou comece com uma allow-list vazia.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/environment-step-3-picker.svg" alt="Seletor de extensões do Clarvis combinando listagens do marketplace, plugins instalados e skills standalone" loading="lazy" decoding="async" />
  <figcaption><strong>Etapa 3 — extensões.</strong> Pesquise um único inventário e prepare plugins ou skills standalone exatos.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/environment-step-4-capabilities.svg" alt="Revisão de capacidades do Clarvis com agentes, skills, servidores MCP, hooks e executáveis fornecidos pelo Extension Profile em preparação" loading="lazy" decoding="async" />
  <figcaption><strong>Etapa 4 — capacidades.</strong> Revise a superfície executável completa, não apenas os nomes dos plugins.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/environment-step-5-delta.svg" alt="Prévia de ativação de Extension Profile no Clarvis listando cada contribuição que entra no snapshot ativo" loading="lazy" decoding="async" />
  <figcaption><strong>Etapa 5 — delta exato.</strong> Confirme a prévia antes de o Clarvis gravar, reconectar e ativar o snapshot nas próximas execuções.</figcaption>
</figure>

A etapa 3 mantém o rascunho em memória. Enter adiciona ou remove um plugin instalado ou uma skill
standalone; em uma listagem do marketplace, primeiro pergunta por `.agents/plugins` ou
`.clarvis/plugins`, instala o plugin e prepara a instalação exata retornada. A instalação é
imediata, mas nada fica ativo antes da etapa 5. Escape volta um nível; se o rascunho mudou, o Clarvis
confirma antes de descartá-lo.

Aplicar grava a definição completa do Extension Profile e a seleção local como uma única operação presa
ao preview. Se a definição, os documentos de seleção ou os bytes de uma contribuição instalada
mudarem após a revisão, o Clarvis recusa o preview obsoleto. Uma aplicação bem-sucedida reconecta o
backend e vale apenas para novas execuções; uma execução em andamento preserva o snapshot original.
Hooks de plugins acompanham atomicamente o plugin selecionado.

Instalação, resolução de capacidades, Apply, reconexão e atualização final mostram um spinner
animado com tempo decorrido. O texto avança somente quando a operação correspondente do host
termina; o Clarvis não inventa progresso percentual. As ações locais ficam suspensas até a operação
ser concluída.

A partir de `/extensions`, pressione `e` para abrir o navegador de diagnóstico e seleção. Ele mostra
o Extension Profile ativo, fingerprint, origem da seleção, contagens de itens instalados e ativos, cada
contribuição resolvida e qualquer problema. Pressione `/` para pesquisar definições e Enter para
abrir o snapshot selecionado em detalhes roláveis.

| Tecla | Ação                                                                                |
| ----- | ----------------------------------------------------------------------------------- |
| `w`   | Pré-visualiza o delta e usa o Extension Profile selecionado apenas neste workspace. |
| `g`   | Pré-visualiza o delta e torna uma seleção global ou builtin o padrão global.        |
| `n`   | Inicia o compositor guiado para um novo Extension Profile.                          |
| `e`   | Configura a definição selecionada ou personaliza um clone de `builtin:default`.     |
| `x`   | Limpa a seleção local deste workspace e pré-visualiza o fallback.                   |
| `d`   | Exclui o Extension Profile customizado inativo selecionado após confirmação.        |
| `r`   | Atualiza definições e diagnósticos.                                                 |

O preview de seleção do navegador avançado lista cada plugin, skill, servidor MCP e hook que entra
ou sai, enquanto o rodapé mantém `y` para aplicar e `n` para cancelar visíveis. Nenhuma seleção muda
antes de `y`.

As prévias usam a mesma precedência da ativação. Se uma seleção do workspace já sombrear o padrão
global, alterar esse padrão global pré-visualiza o mesmo Extension Profile efetivo, sem delta ativo. Uma
prévia fica vinculada aos dois documentos de seleção; se qualquer um deles mudar antes da
confirmação, o Clarvis exige uma nova prévia.

Use o compositor guiado para adicionar ou remover plugins e skills standalone exatos. As
contribuições de um plugin são atômicas: selecioná-lo seleciona todos os agentes, skills de plugin,
servidores MCP, hooks e executáveis de capacidade. O Extension Profile é o limite de ativação do plugin.

## Crie uma allow-list completa

Definições globais ficam em `~/.clarvis/extension-profiles/<nome>.json`. Definições de workspace ficam em
`<workspace>/.clarvis/extension-profiles/<nome>.json` e podem ser versionadas no repositório.

```json
{
  "schema_version": 1,
  "description": "Pesquisa com navegador e documentação",
  "plugins": [
    { "scope": "global", "source": "agents", "name": "browser" },
    { "scope": "global", "source": "clarvis", "name": "github" }
  ],
  "skills": [{ "scope": "user", "source": "clarvis", "name": "deep-research" }]
}
```

`plugins` e `skills` são allow-lists completas, não adições a `builtin:default`. Referências de
plugins qualificam escopo (`global` ou `workspace`) e origem (`agents` para `.agents/plugins`,
`clarvis` para `.clarvis/plugins`); outra instalação de mesmo nome nunca é substituída. Referências
de skills standalone qualificam tanto o escopo (`user` ou `workspace`) quanto a origem (`agents` ou
`clarvis`). Um Extension Profile global pode referenciar apenas plugins globais e skills de usuário. Um
Extension Profile de workspace pode combinar os quatro inventários de plugins.

Definições não herdam. Clone um Extension Profile quando quiser uma variação.

## Entenda a seleção e o compartilhamento

O Clarvis resolve o Extension Profile ativo nesta ordem:

1. `--extension-profile` para este processo;
2. a seleção local deste workspace;
3. a seleção global padrão;
4. `builtin:default`.

Use um seletor qualificado quando o escopo importar:

```bash
clarvis --extension-profile global:research
clarvis --extension-profile workspace:project -p "Revise esta alteração"
```

Um nome sem escopo procura primeiro a definição de workspace e depois a global. `--extension-profile` não persiste
uma escolha, e o processo em execução não pode sobrescrever sua seleção local ou global enquanto o
override estiver ativo.

Definições de workspace são compartilháveis, mas a escolha ativa é sempre local à máquina, no
estado do Clarvis. Clonar um repositório, portanto, não ativa seu Extension Profile sozinho.

## Diagnostique confiança e divergências

Um Extension Profile fica `ready`, `degraded` ou `invalid`:

- um plugin ou uma skill standalone ausente fica `degraded` e permanece visivelmente inativo;
- uma definição ou seleção inválida fica `invalid` e nunca cai para um padrão mais amplo;
- um Extension Profile que selecione um plugin ainda não aprovado pertencente ao repositório fica
  `degraded`, enquanto plugins globais selecionados continuam ativos.

Depois que o compositor leve de startup é exibido, o Clarvis calcula proativamente o fingerprint de
todos os plugins instalados no workspace, selecionados ou não pelo Extension Profile ativo. Uma aprovação
cobre esse inventário exato ao trocar de Extension Profile. Alterar qualquer byte ou modo executável de
um plugin do workspace que pertença à superfície de contribuições incluída no fingerprint muda o
fingerprint e exige nova revisão; editar apenas a allow-list do Extension Profile não muda essa aprovação.
Plugins globais pertencem ao operador e não exigem uma segunda aprovação do workspace. Recusar abre
Extensions para remover contribuições indesejadas, e `/workspace-trust` permanece como fallback
posterior de revisão ou revogação.

<figure class="tui-shot">
  <img src="/images/tui/workspace-trust-review.svg" alt="Diálogo de confiança no workspace do Clarvis mostrando o fingerprint exato do inventário de plugins e as contribuições executáveis" loading="lazy" decoding="async" />
  <figcaption>A confiança no workspace identifica o fingerprint e o inventário executável exatos antes da aprovação.</figcaption>
</figure>

O Clarvis recusa aprovar ou revogar a confiança no workspace enquanto uma execução estiver ativa,
antes de alterar o registro de confiança. Quando não há execução ativa, essa decisão faz o Clarvis
recompor o Extension Profile de workspace selecionado, ou as partes de `builtin:default` derivadas do
workspace, antes da próxima execução.

O kernel fixa o snapshot resolvido de extensões. Seu fingerprint cobre manifestos exatos dos plugins
e declarações MCP/hooks complementares, proveniência da instalação e revisão resolvida da origem,
arquivos de agentes, corpos e recursos das skills empacotadas, corpos e recursos das skills
standalone selecionadas e o estado de confiança aplicável. Se qualquer contribuição selecionada
mudar após a resolução, acessos posteriores a contribuições são recusados até `/reconnect`; bytes
alterados de plugin ou skill nunca entram sob o fingerprint antigo. Execuções, traces e turnos de
sessão registram o id e o fingerprint do Extension Profile. Retomar uma sessão sob outro fingerprint
mostra um aviso em vez de fingir que a superfície de extensões não mudou.

## Veja também

- [Visão geral de extensões](/pt-BR/guide/extensions)
- [Plugins](/pt-BR/guide/plugins)
- [Skills](/pt-BR/guide/skills)
- [Escopos e confiança no workspace](/pt-BR/explanation/scopes-and-trust)
- [Referência de extensões](/pt-BR/reference/extensions)
- [Comandos](/pt-BR/reference/commands)

---

[HTML canônico](https://clarvis.dev/pt-BR/guide/extension-profiles)

[Índice da documentação](https://clarvis.dev/pt-BR/llms.txt)