Referências de contexto

Digite @ seguido de uma referência para injetar conteúdo direto na sua mensagem. O Hermes expande a referência na hora e anexa o conteúdo numa seção --- Attached Context ---.

Referências suportadas

Sintaxe	Descrição
@file:caminho/do/arquivo.py	Injeta o conteúdo do arquivo
@file:caminho/do/arquivo.py:10-25	Injeta um intervalo de linhas (começando em 1, inclusive)
@folder:caminho/do/diretorio	Injeta a árvore do diretório, com metadados dos arquivos
@diff	Injeta o git diff (mudanças não preparadas)
@staged	Injeta o git diff --staged (mudanças preparadas)
@git:5	Injeta os últimos N commits com os patches (máximo 10)
@url:https://exemplo.com	Busca e injeta o conteúdo de uma página web

Exemplos

Revise @file:src/main.py e sugira melhorias

O que mudou? @diff

Compare @file:config_antigo.yaml e @file:config_novo.yaml

O que tem em @folder:src/components?

Resuma este artigo @url:https://arxiv.org/abs/2301.00001

Várias referências funcionam numa mensagem só:

Veja @file:main.py, e também @file:test.py.

Pontuação no fim (,, ., ;, !, ?) é removida do valor da referência automaticamente.

Autocompletar na CLI

Na CLI interativa, digitar @ abre o autocompletar:

• @ mostra todos os tipos (@diff, @staged, @file:, @folder:, @git:, @url:)
• @file: e @folder: completam caminhos do sistema de arquivos, com o tamanho de cada arquivo
• @ seguido de texto parcial mostra arquivos e pastas do diretório atual que combinam

Intervalos de linha

A referência @file: aceita intervalos, para injetar exatamente o trecho que importa:

@file:src/main.py:42        # só a linha 42
@file:src/main.py:10-25     # da linha 10 à 25 (inclusive)

As linhas começam em 1. Intervalos inválidos são ignorados em silêncio (o arquivo inteiro é devolvido).

Limites de tamanho

As referências têm limite, para não afogar a janela de contexto do modelo:

Limite	Valor	Comportamento
Brando	25% do contexto	Um aviso é anexado, e a expansão segue
Rígido	50% do contexto	A expansão é recusada, e a mensagem original volta sem alteração
Itens de pasta	200 arquivos	O excedente vira - ...
Commits do git	10	O @git:N é limitado ao intervalo de 1 a 10

Segurança

Bloqueio de caminhos sensíveis

Estes caminhos são sempre bloqueados no @file:, para não expor credencial:

• Chaves e configuração de SSH: ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/authorized_keys, ~/.ssh/config
• Perfis de shell: ~/.bashrc, ~/.zshrc, ~/.profile, ~/.bash_profile, ~/.zprofile
• Arquivos de credencial: ~/.netrc, ~/.pgpass, ~/.npmrc, ~/.pypirc
• Ambiente do Hermes: $HERMES_HOME/.env

Estes diretórios são bloqueados por completo (qualquer arquivo dentro): ~/.ssh/, ~/.aws/, ~/.gnupg/, ~/.kube/, $HERMES_HOME/skills/.hub/.

Proteção contra travessia de diretório

Todos os caminhos são resolvidos em relação ao diretório de trabalho. Referências que caem fora da raiz permitida são recusadas.

Detecção de arquivo binário

Arquivos binários são detectados por tipo MIME e varredura de bytes nulos. Extensões de texto conhecidas (.py, .md, .json, .yaml, .toml, .js, .ts etc.) pulam a detecção por MIME. Binários são recusados com um aviso.

Onde funciona

Referências de contexto são principalmente um recurso da CLI. Elas funcionam na CLI interativa, onde o @ abre o autocompletar e a expansão acontece antes da mensagem ir para o agente.

Nas plataformas de mensagem (Telegram, Discord etc.), a sintaxe @ não é expandida pelo gateway — as mensagens passam como estão. O próprio agente ainda consegue acessar arquivos pelas ferramentas read_file, search_files e web_extract.

Relação com a compressão de contexto

Quando o contexto da conversa é comprimido, o conteúdo expandido entra no resumo. Ou seja:

• Arquivos grandes injetados por @file: contam para o uso de contexto
• Se a conversa for comprimida depois, o conteúdo do arquivo é resumido, não preservado literal
• Para arquivos muito grandes, use intervalos de linha (@file:main.py:100-200) e injete só o trecho relevante

Padrões comuns

# Revisão de código
Revise @diff e procure problemas de segurança

# Depurar com contexto
Este teste está falhando. Aqui está o teste @file:tests/test_auth.py
e a implementação @file:src/auth.py:50-80

# Explorar um projeto
O que este projeto faz? @folder:src @file:README.md

# Pesquisa
Compare as abordagens de @url:https://arxiv.org/abs/2301.00001
e @url:https://arxiv.org/abs/2301.00002

Tratamento de erro

Referências inválidas geram avisos em linha, e não falhas:

Situação	Comportamento
Arquivo não encontrado	Aviso: "file not found"
Arquivo binário	Aviso: "binary files are not supported"
Pasta não encontrada	Aviso: "folder not found"
Comando do git falhou	Aviso, com a saída de erro do git
A URL não devolveu conteúdo	Aviso: "no content extracted"
Caminho sensível	Aviso: "path is a sensitive credential file"
Caminho fora do espaço de trabalho	Aviso: "path is outside the allowed workspace"