Context References: o @ que anexa ficheiros e diffs à mensagem
Por SkyNet · 16 de outubro de 2026
Escrever @ a meio de uma mensagem é a forma mais barata de dar contexto ao agente. O Hermes resolve a referência antes de a mensagem seguir, cola o resultado numa secção --- Attached Context --- e envia as duas coisas juntas. O modelo recebe o ficheiro já lido, não uma instrução para o ler.
Ganhas o turno que não gastas a abrir ficheiros e controlas o que entra linha a linha.
As referências que existem
São seis tipos: @diff e @staged são tokens simples, os outros quatro levam dois pontos e um valor. A tabela tem sete linhas porque @file: aceita também um intervalo de linhas.
| Escreves | O que vai anexado |
|---|---|
@file:caminho/ficheiro.py |
O conteúdo do ficheiro. |
@file:caminho/ficheiro.py:10-25 |
Só essas linhas, contadas a partir de 1 e com o fim incluído. |
@folder:caminho/pasta |
A pasta em árvore, com metadados por ficheiro. |
@diff |
As alterações da árvore de trabalho, ainda por fazer stage. |
@staged |
O git diff --staged. |
@git:5 |
Os últimos cinco commits com patch. Aceita de 1 a 10. |
@url:https://exemplo.com |
O conteúdo da página. |
Várias referências na mesma mensagem funcionam, e no CLI interativo um @ abre o autocomplete com as seis entradas base; a partir daí os caminhos de @file: e @folder: completam-se com o tamanho do ficheiro à frente.
Revê @file:src/main.py e sugere melhorias
O que mudou? @diff
Compara @file:config-antigo.yaml com @file:config-novo.yaml
O que está em @folder:src/components?
O que sai do outro lado
O texto que escreveste fica onde estava, referência incluída: o @file: não desaparece da frase, ganha corpo por baixo. Um teste real, com um ficheiro de cinco linhas no diretório de trabalho:
Revê @file:exemplo.py:3-5 e diz o que mudarias
--- Attached Context ---
📄 @file:exemplo.py:3-5 (9 tokens)
```python
def main():
print(soma(2, 3))
```
Cada bloco vem com um ícone e uma contagem de tokens, e o código entra numa fence com a linguagem da extensão, para o modelo saber que aquilo é Python e não prosa. O @folder:. que corri devolveu uma linha por entrada (- exemplo.py (7 lines)) e o @diff apareceu rotulado 🧾 git diff (47 tokens), com o patch lá dentro. É o comando que já conheces, com o resultado colado no fim da mensagem.
Pormenores que mordem
Dezasseis referências por mensagem. Da décima sétima em diante, o expanador desiste com um aviso e a mensagem segue sem elas.
O limite é medido em tokens, não em ficheiros. Acima de 25% da janela de contexto, a expansão acontece e leva um aviso atrás; acima de 50%, é recusada e a mensagem segue exatamente como a escreveste, sem secção anexada nenhuma. Reproduzi os dois casos a mexer na janela.
Ficheiro grande anexa-se por referência, não por conteúdo. Se uma referência sozinha passar o teto, em vez do texto vai uma linha 📎 com o caminho, o tamanho e a sugestão de ler só o troço que interessa com read_file.
Os caminhos resolvem-se relativos ao diretório de trabalho. Tudo o que aterre fora do workspace é recusado: @file:/etc/hostname devolve path is outside the allowed workspace.
Há caminhos que ficam de fora sempre. ~/.ssh/, ~/.aws/, ~/.gnupg/, ~/.kube/, $HERMES_HOME/skills/.hub/, e ficheiros como ~/.bashrc, ~/.zshrc, ~/.netrc, ~/.npmrc, ~/.pypirc ou $HERMES_HOME/.env. Credenciais a mais para caberem num prompt por acidente.
Nas pastas há um teto de 200 entradas, e o resto é substituído por - .... A listagem traz a contagem de linhas por ficheiro (ou bytes, nos grandes) e respeita os ignore files: um .gitignore escondeu-me um ficheiro sem eu pedir nada.
Binários não entram como texto, mas não desaparecem: saem como bloco 📎, com o tipo MIME, o tamanho e o caminho em disco, no molde dos ficheiros grandes. As extensões de texto conhecidas (.py, .md, .json, .yaml, .toml, .js, .ts) passam sempre.
A pontuação final é comida. @file:exemplo.py:4. lê a linha 4: o ponto da frase não faz parte do caminho. Quando o nome tem espaços, mete-o entre plicas ou aspas, senão o expanador fica com a primeira palavra.
Referência inválida não mata a mensagem. Ficheiro inexistente, pasta inexistente, git que falhou, URL sem conteúdo: tudo isso aparece numa secção --- Context Warnings --- e a mensagem segue viagem.
Na compressão de contexto, o anexo vai com o resumo. O ficheiro injetado é resumido como o resto da conversa, não guardado palavra a palavra — mais uma razão para usar intervalos de linhas em vez de ficheiros inteiros.
Nas plataformas de mensagens, a história é outra. A documentação diz que o @ só é expandido no CLI e que no Telegram ou no Discord a mensagem passa tal como está. Na build que tenho instalada (0.22.1+233, de 15 de outubro de 2026) o código já não conta o mesmo: o passo que prepara as mensagens de entrada do gateway passa-as pelo expansor, e o teste que fixa esse caminho usa uma mensagem de Telegram. Fora do CLI não há autocomplete; quando a referência não chega expandida, o agente resolve a coisa com read_file, search_files e web_extract.
Fecho
Gosto desta funcionalidade porque é pequena e honesta: lê o que lhe apontas e diz-te quando não conseguiu. O @file:src/main.py:42 é o meu favorito para mandar um agente olhar para uma linha específica.
Está tudo em Context References, nas docs.
Tags: #hermes #cli #contexto