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.

Etapa 1 — escopo. Decida onde a seleção pertence antes de editar qualquer definição.

Etapa 2 — definição. Edite, clone ou comece com uma allow-list vazia.

Etapa 3 — extensões. Pesquise um único inventário e prepare plugins ou skills standalone exatos.

Etapa 4 — capacidades. Revise a superfície executável completa, não apenas os nomes dos plugins.

Etapa 5 — delta exato. Confirme a prévia antes de o Clarvis gravar, reconectar e ativar o snapshot nas próximas execuções.

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.

{
  "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:

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.

A confiança no workspace identifica o fingerprint e o inventário executável exatos antes da aprovação.

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
• Plugins
• Skills
• Escopos e confiança no workspace
• Referência de extensões
• Comandos