Referência de extensões
Consulte os arquivos, as configurações e as regras de ativação de cada tipo de extensão.
Locais e precedência
| Extensão | Local pessoal | Local do workspace | Precedência |
|---|---|---|---|
| Configurações | ~/.clarvis/settings.json | .clarvis/settings.json | Configurações do workspace sobrescrevem as pessoais |
| Skills | ~/.clarvis/skills/<name>/SKILL.md | .clarvis/skills/<name>/SKILL.md | Skills Clarvis do workspace vencem |
| Skills interoperáveis | ~/.agents/skills/<name>/SKILL.md | .agents/skills/<name>/SKILL.md | Abaixo dos diretórios de skills Clarvis |
| Plugins Clarvis | ~/.clarvis/plugins/<name>/ | .clarvis/plugins/<name>/ | Inventário exato com source: "clarvis" |
| Plugins compartilhados | ~/.agents/plugins/<name>/ | .agents/plugins/<name>/ | Inventário exato com source: "agents" |
| Agentes | ~/.clarvis/agents/<name>.md | .clarvis/agents/<name>.md | Agente do workspace sobrescreve o agente pessoal |
| Extension Profiles | ~/.clarvis/extension-profiles/<name>.json | .clarvis/extension-profiles/<name>.json | Seleção local do workspace, depois padrão global |
Tanto builtin:default quanto Extension Profiles personalizados resolvem cada plugin pela identidade exata { scope, source, name }. Nada substitui uma referência ausente, e selecionar duas instalações de mesmo nome é inválido porque seus namespaces de execução colidem. Contribuições de plugins permanecem abaixo das configurações pessoais e do workspace.
Ativação e confiança
| Superfície | O que a torna ativa |
|---|---|
| Hook pessoal | Presença no settings.json pessoal |
| Hook do workspace | Aprovação do fingerprint exato do workspace |
| Servidor MCP pessoal | Presença no settings.json pessoal |
| Servidor MCP do workspace | Aprovação do fingerprint exato do workspace |
| Unidade de plugin global | Instalada e selecionada pelo Extension Profile ativo |
| Unidade de plugin do workspace | Selecionada e com o inventário completo de plugins do repositório aprovado |
| Hook de plugin | Sua unidade completa de plugin está ativa; não existe aprovação separada do hook |
| Entrada de marketplace | Nunca ativa sozinha; a instalação explícita ativa o plugin completo |
| Agente do workspace | Aprovação do fingerprint exato do workspace |
| Skill independente | Descoberta em um diretório de skills; a visibilidade do comando com barra segue user-invocable |
A confiança no workspace cobre valores executáveis ou de seleção de provedores declarados por um repositório: hooks, mcpServers, enabledPlugins, marketplaces, memory.provider, plans.provider, tasks.provider, agentes do workspace e todos os plugins instalados no workspace pertencentes ao repositório antes da seleção do Extension Profile. Até a aprovação, o Clarvis retém esses valores e plugins do workspace, mas continua usando a configuração pessoal confiável e plugins globais selecionados. Uma aprovação cobre o inventário exato de plugins do workspace ao trocar de Extension Profile; alterar seu conteúdo exige nova revisão. Declarações de provedores de assinatura são uma exceção permanente: o Clarvis as remove das configurações do workspace antes da mesclagem, e a aprovação nunca concede autoridade sobre credenciais ou redirecionamentos. Configure-as globalmente; o workspace pode apenas selecionar um modelo já habilitado nesse escopo.
Configuração guiada de Extensions na TUI
Digite /extensions e pressione Enter para abrir a central. O editor guiado apresenta cinco escolhas:
| Etapa | Decisão | Efeito persistente |
|---|---|---|
| 1 | Seleção local do workspace ou padrão global | Nenhum; prepara o escopo da seleção. |
| 2 | Extension Profile existente, clone do ativo ou nova definição vazia | Nenhum; prepara a definição completa e a revisão esperada. |
| 3 | Plugins do marketplace, plugins instalados exatos e skills independentes | Uma instalação confirmada persiste imediatamente; a participação fica no rascunho. |
| 4 | Agentes, skills de plugin, skills independentes, servidores MCP, hooks e executáveis resolvidos | Nenhum; cria um preview exato e limitado. |
| 5 | Mudanças de ativação e confiança do workspace | Salva juntas a definição e a seleção revisadas e reconecta. |
Na etapa 3, pesquise plugins e skills no mesmo seletor. As origens .agents e .clarvis ficam separadas, inclusive para itens com o mesmo nome. Enter adiciona, remove ou instala o item selecionado; Escape termina a escolha e mantém o rascunho para revisão. Ao instalar pelo marketplace, escolha .agents/plugins ou .clarvis/plugins; a nova instalação será incluída no rascunho.
A etapa 4 mostra todos os recursos que serão disponibilizados. Um plugin é selecionado inteiro: suas skills, ferramentas MCP, hooks e serviços não podem ser ativados separadamente.
A etapa 5 aplica exatamente o que você revisou. Se a definição, o inventário, as seleções ou a aprovação de confiança mudarem, é preciso uma nova prévia. Não é possível aplicar durante uma execução ativa nem quando --extension-profile fixa a seleção do processo.
O rodapé mostra a operação em andamento e o tempo decorrido, sem estimar uma porcentagem. Espere cada operação terminar antes de continuar.
/extensions é a única rota pública. Sua central abre o navegador de Extension Profile para definições, seleção, exclusão e diagnóstico de snapshots; Plugins para coleções horizontais de marketplaces, instalação, atualização, desinstalação e composição; e MCP para ferramentas, prompts e recursos conectados. Plugins usa esquerda/direita para coleções, cima/baixo para linhas, / para pesquisar a coleção e Enter para detalhes e para a ação explícita de instalar e ativar.
Definição de Extension Profile
Uma definição de Extension Profile é um JSON estrito:
{
"schema_version": 1,
"description": "Pesquisa",
"plugins": [{ "scope": "global", "source": "agents", "name": "browser" }],
"skills": [{ "scope": "user", "source": "clarvis", "name": "deep-research" }]
}plugins e skills são allow-lists completas. Os escopos de plugin são global ou workspace, e suas origens são agents ou clarvis. Os escopos de skill independente são user ou workspace, com as mesmas origens. Definições globais podem referenciar apenas plugins globais e skills de usuário; definições de workspace podem combinar os quatro inventários de plugins. As definições têm limite de 1 MiB, 64 plugins e 256 skills independentes.
O builtin:default imutável não tem arquivo e ativa referências exatas de enabledPlugins junto de todas as raízes padrão de skills. A precedência da seleção é: --extension-profile do processo, seleção local do workspace, seleção global local à máquina e builtin:default. Definições podem ser compartilhadas; seleções ficam no estado do Clarvis e não fazem parte do repositório.
As prévias de seleção usam essa mesma precedência e ficam vinculadas aos dois documentos de seleção. Portanto, uma alteração global já sombreada por uma seleção do workspace pré-visualiza o mesmo Extension Profile efetivo; uma alteração concorrente em qualquer seleção exige uma nova prévia.
O fingerprint resolvido cobre definição, status, problemas, estado de confiança aplicável, manifestos exatos dos plugins e declarações complementares, proveniência da instalação e revisão resolvida da origem, arquivos de agentes, corpos e recursos das skills empacotadas e corpos e recursos das skills independentes selecionadas. Divergência nas contribuições retorna unavailable até a reconexão, em vez de consumir bytes alterados sob o fingerprint antigo. Aprovar ou revogar a confiança no workspace é recusado com conflict durante uma execução; quando não há execução ativa, o conjunto de extensões é recomposto antes da próxima execução.
Atualizar ou desinstalar uma instalação exata de plugin selecionada também é recusado com conflict durante uma execução, e o início de uma execução não pode disputar essa mutação. Após uma mutação bem-sucedida de plugin selecionado, o kernel antigo retorna unavailable para novas execuções até a reconexão.
settings.json
settings.json é estrito. Campos desconhecidos de nível superior são rejeitados em vez de ignorados. Os campos relacionados a extensões são:
| Campo | Formato | Finalidade |
|---|---|---|
hooks | Array de objetos de hook | Comandos de ciclo de vida criados pelo operador |
mcpServers | Mapa do nome para o objeto do servidor | Conexões MCP locais e remotas |
marketplaces | Array de URLs Git | Catálogos adicionais exibidos em Plugins |
enabledPlugins | Array exato de { scope, source, name } | Lista de ativação de builtin:default |
Objeto de servidor MCP
| Campo | Tipo | Aplicável a | Observações |
|---|---|---|---|
type | stdio, http ou sse | Todos | O padrão é stdio |
command | String | stdio | Obrigatório |
args | Array de strings | stdio | Argumentos opcionais após o comando |
env | Mapa de strings | stdio | Aceita interpolação ${VAR} |
env_vars | Array de strings | stdio | Encaminha somente as variáveis nomeadas do host |
cwd | String | stdio | Diretório de trabalho opcional |
shared | Booleano | stdio | Reutiliza um processo entre execuções; desativa elicitação |
url | URL HTTP(S) | http, sse | Obrigatório |
headers | Mapa de strings | http, sse | Aceita interpolação ${VAR} |
bearer_token_env_var | Nome de variável | http, sse | Lê bearer token sem persistir o valor |
env_http_headers | Mapa cabeçalho-para-variável | http, sse | Lê valores de cabeçalhos do ambiente |
oauth | Objeto | http, sse | Configuração opcional de cliente, callback e metadados |
resources | Booleano | Todos | Ativo por padrão; false suprime ferramentas de recursos |
startup_timeout_sec | Número positivo | Todos | Timeout de inicialização por servidor, até 3600 segundos |
tool_timeout_sec | Número positivo | Todos | Timeout de ferramenta por servidor, até 3600 segundos |
enabled_tools | Array de strings | Todos | Mantém somente as ferramentas anunciadas nomeadas |
disabled_tools | Array de strings | Todos | Remove ferramentas nomeadas depois da allow-list |
enabled / required | Booleano | Todos | Política de ativação e prontidão obrigatória do servidor |
stdio proíbe url e headers. Transportes remotos proíbem command, args, env e shared.
expandVariables é verdadeiro por padrão e se aplica a env e headers escritos; referências explícitas de credencial ainda são resolvidas quando um plugin portátil desativa a expansão geral. enabled_tools e disabled_tools não podem se sobrepor.
Servidores HTTP/SSE remotos podem solicitar OAuth durante a conexão, a descoberta de catálogo ou uma solicitação posterior. Hosts locais interativos e em modo --print abrem a página de autorização, exigem HTTPS em cada endpoint e redirecionamento OAuth com exceção de HTTP em loopback, validam o estado, usam PKCE e repetem uma vez a solicitação recusada após o callback. Cabeçalhos MCP configurados aplicam-se apenas às solicitações do recurso na origem configurada; trocas OAuth não os herdam, mesmo nessa origem, e cabeçalhos de autorização definidos pelo SDK têm precedência. As credenciais ficam em ~/.clarvis/state/mcp-oauth.json, identificadas por workspace, proprietário e URL canônica do servidor; elas não fazem parte das configurações. Um host sem abridor de navegador informa que a autorização interativa está indisponível. Na TUI interativa, um desafio OAuth nunca mantém uma execução do modelo aberta: o servidor fica inativo naquela execução, um aviso sanitizado transitório aparece fora do histórico da conversa e o fluxo concluído fica disponível para uma execução posterior.
Objeto de hook
| Campo | Tipo | Observações |
|---|---|---|
event | Nome de evento | Obrigatório |
type | command ou mcp_tool | O padrão é command |
command | String | Obrigatório para hooks de comando |
command_windows | String | Override de comando específico do Windows |
async | Booleano | Desanexa hook de comando, exceto run_end / SessionEnd |
status_message | String | Metadado limitado de exibição; não entra no histórico da conversa |
additional_context_limit | Inteiro de 0 a 65536 | Restringe a saída capturada do comando |
plugin_root, plugin_data | Strings de caminho limitadas | Normalmente fornecidas pelo adaptador; exportadas pelos aliases PLUGIN_* e CODEX_PLUGIN_* sem criar um sandbox |
server, tool, input | Alvo e entrada MCP | Alvo obrigatório em mcp_tool; a entrada aceita placeholders do evento |
match.tool | String ou array de strings | Nome exato ou glob *; somente eventos de ferramenta |
match.args | Mapa de strings | Regex JavaScript por argumento; todas devem corresponder; somente eventos de ferramenta |
timeout_ms | Inteiro de 1 a 60000 | Tempo limite opcional |
on_failure | pass ou deny | deny só vale em eventos de controle; inválido em mcp_tool |
Eventos:
| Classe | Eventos | Efeito |
|---|---|---|
| Controle | pre_tool_use, post_tool_use, pre_finalize, pre_delegate_task | Pode permitir, orientar ou negar |
| Observador | run_start, run_end, post_compact, subagent_start, subagent_complete, model_call_error, budget_exhausted, user_steer | A saída não pode bloquear a execução |
| Contexto | session_start | Pode adicionar contexto inicial fixado |
| Contexto de compactação | pre_compact | Pode adicionar contexto àquela sumarização |
| Observador de prompt | user_prompt_expansion | Observa um comando de skill iniciado pelo usuário |
Somente pre_tool_use pode substituir argumentos pendentes de ferramenta por um veredito rewrite. Uma única fonte de configurações ou plugin pode declarar até 64 hooks; uma execução usa no máximo 128 hooks combinados, com hooks do operador antes dos hooks de plugins.
Um hook mcp_tool chama um servidor já conectado à execução. Ele não dispara outros hooks de ferramenta e não bloqueia a execução em caso de falha. Hooks assíncronos compartilham um limite de oito processos em segundo plano. Já run_end sempre aguarda a conclusão, para não perder o comando ao sair.
Payloads de hooks compatíveis escrevem ferramentas integradas com nomes externos como Bash, Read e Skill, e ferramentas MCP como mcp__<servidor>__<ferramenta>. CLARVIS_HOOK_TOOL preserva o nome de wire do Clarvis; CLARVIS_HOOK_TOOL_FULL_NAME contém o nome MCP pontuado estável quando ele existe.
SKILL.md
Cada skill é um diretório que contém SKILL.md com frontmatter YAML e um corpo em Markdown.
| Campo | Obrigatório | Observações |
|---|---|---|
name | Sim | Letras, números, ., _ e -; máximo de 128 caracteres |
description | Sim | Texto curto para descoberta |
agent | Não | Agente para invocação com barra; pode usar <plugin>:<agent> |
version | Não | Metadado da versão da skill |
license | Não | Metadado de licença |
argument-hint | Não | String ou array de strings exibido para o argumento do comando com barra |
user-invocable | Não | O padrão é true |
allowed-tools | Não | Metadado de compatibilidade; não altera permissões durante a execução |
tools | Não | Alias de allowed-tools |
O corpo pode usar $ARGUMENTS ou . Os diretórios convencionais de recursos são scripts, references, assets e examples. Um diretório auxiliar agents é metadado de apresentação para o host e nunca é exposto como recurso da skill. O primeiro YAML nele também pode declarar entradas dependencies.tools de type: mcp; a skill fica ausente de uma execução cuja superfície MCP selecionada não contenha aquele servidor.
Recursos de skill podem ter no máximo 8 MiB por arquivo e 32 MiB no snapshot proprietário. Leituras para o modelo retornam páginas de no máximo 256 KiB e 50.000 caracteres decodificados. A execução de helpers é habilitada por diretório exato da skill e ainda passa pela revisão de comandos e pelo sandbox nativo.
plugin.json
plugin.json é tolerante: o Clarvis relata campos desconhecidos, mas não age sobre eles. name é o único campo obrigatório após a normalização. Uma instalação Git nativa o usa como nome do diretório; um layout estrangeiro já instalado pode omiti-lo, e então o Clarvis o deriva do diretório de instalação. Esse diretório é sempre o namespace de execução controlado pelo host.
O Clarvis usa primeiro um plugin.json legível na raiz que declare o schema portátil de Agent Plugins. Caso contrário, usa .clarvis-plugin/plugin.json quando ele existe. Sem nenhuma dessas formas autoritativas, examina o manifesto raiz e diretórios com o formato .<host>-plugin/plugin.json, seleciona o único manifesto legível com mais diretivas de contribuição compatíveis e usa a ordem raiz-depois-nome para desempatar. Manifestos nunca são combinados.
| Campo | Tipo | Finalidade |
|---|---|---|
name | Identificador em minúsculas | Identidade e namespace do plugin |
version | String não vazia | Versão opcional para exibição |
description | String não vazia | Resumo opcional |
author | String ou { name, email?, url? } | Autor opcional para exibição |
homepage / repository | String não vazia | Links opcionais de descoberta |
license / keywords | String / array de strings | Metadados opcionais de apresentação |
interface | Objeto de apresentação limitado | Nomes, textos, links, prompts, cores e assets visuais |
skills | Diretório relativo ou array de diretórios | Coleções ou skills individuais; até quatro raízes efetivas |
mcpServers | Mapa MCP ou caminho relativo para documento | Servidores fornecidos pelo plugin |
hooks | Array, documento ou caminho relativo de hooks | Hooks fornecidos pelo plugin |
bootstrapSkill | Nome de skill | Injeta uma skill metodológica do plugin antes da resposta |
capabilityExecutables | Mapa de capacidade para executável | Serviços persistentes opcionais de capacidade |
capabilityRunPolicies | Mapa da política de skills de Plans | off, on ou review para execuções de skills do plugin |
Caminhos relativos são resolvidos primeiro a partir do diretório do manifesto selecionado e permanecem confinados à raiz do plugin. Os diretórios convencionais de contribuições são agents/ e skills/. Se mcpServers estiver ausente, o Clarvis tenta .mcp.json e depois mcp.json. Se o manifesto não fornecer hooks, o Clarvis também lê hooks/hooks.json. Documentos de hooks compatíveis e organizados por evento podem estar inline, envolvidos por um objeto hooks ou ser indicados por um ou mais caminhos relativos. Em um documento organizado por evento e traduzido, um comando inicial como ./hooks/session-start.cmd é ancorado à raiz do plugin, enquanto o diretório de trabalho do hook continua sendo o workspace. Arrays de hooks nativos do Clarvis permanecem exatamente como declarados.
Um .mcp.json no estilo Codex pode ser um mapa direto ou envolvê-lo em mcpServers ou mcp_servers; entradas somente com url inferem HTTP, http_headers vira headers e os campos OAuth compatíveis em camel case são normalizados para os campos snake case do motor. Um manifesto de outro host com formato reconhecido pode traduzir o valor inteiro e exato ${user_config.key} de uma variável de ambiente stdio somente quando essa entrada de userConfig tem type: "string". O valor se torna ${DEST_ENV} e lê a variável existente do ambiente do operador; padrões e metadados de segredo nunca são importados. Referências inseguras retêm apenas o servidor MCP afetado.
Declaração de executável de capacidade
{
"capabilityExecutables": {
"memory": {
"command": "quality-memory",
"args": ["serve"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
},
"timeout_ms": 30000,
"platforms": {
"win32": {
"command": "quality-memory.exe"
}
}
}
}
}command é obrigatório. args e env usam coleções vazias por padrão, e timeout_ms usa 30000 milissegundos por padrão. Um serviço de capacidade permanece inerte até que o plugin seja selecionado pelo Extension Profile ativo e como provedor daquela capacidade.
marketplace.json
Uma instalação do Clarvis inclui https://github.com/getclarvis/marketplace.git como sua fonte de marketplace oficial. A fonte fica disponível sem uma entrada nas configurações, mas seu catálogo é buscado somente para navegação e nenhum plugin é instalado, selecionado ou aprovado automaticamente. O settings.json pode adicionar outras fontes de marketplace.
Um repositório de marketplace publica marketplace.json em sua raiz:
| Campo raiz | Obrigatório | Finalidade |
|---|---|---|
name | Não | Identificador do catálogo; o Clarvis fornece um quando ausente |
displayName | Não | Título voltado para pessoas |
description | Não | Resumo do catálogo |
plugins | Não | Array de entradas; o padrão é vazio |
| Campo da entrada | Obrigatório | Finalidade |
|---|---|---|
name | Sim | Identidade esperada do plugin instalado |
source | Sim | String Git/local ou descritor url, git-subdir, local ou npm |
path | Não | Subdiretório Git confinado na sintaxe compatível com origem em string |
description | Não | Resumo da entrada |
displayName | Não | Título do plugin voltado para pessoas |
homepage | Não | Página do projeto |
category | Não | Agrupamento de apresentação |
policy | Não | Política de apresentação de instalação e autenticação |
interface | Não | Metadados limitados de publisher, termos legais, prompts, cores e assets |
Arquivos de marketplace são tolerantes e relatam campos desconhecidos ou preenchidos por padrão. Uma entrada sem name ou source utilizável é omitida. Origens locais relativas confinadas são instaláveis; destinos que escapem ou sejam indeterminados continuam visíveis, mas sem ação de instalação. Descritores Git aceitam no máximo um ref ou sha completo. Descritores npm aceitam uma versão segura opcional e um registry HTTPS sem credenciais. AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL e ON_FIRST_USE são apenas políticas de apresentação: carregar o catálogo nunca instala ou autentica nada.
Namespaces
| Contribuição | Nome efetivo |
|---|---|
| Servidor MCP de configurações | <server> |
| Ferramenta MCP de configurações | <server>.<tool> |
| Servidor MCP de plugin | <plugin>:<server> |
| Ferramenta MCP de plugin | <plugin>:<server>.<tool> |
| Agente de plugin | <plugin>:<agent> |
| Skill de plugin | Nome declarado no manifesto da skill; aplica-se a precedência normal |