Grafo de Código e Base de Conhecimento

O grafo de código é experimental. A interface, o formato dos dados e o comportamento da indexação podem mudar em versões futuras.

O grafo de código usa o CodeGraph para analisar os símbolos de um projeto e as relações entre eles. A Base de Conhecimento de Sessões armazena decisões de projeto, restrições e lições aprendidas. As referências ao código ligam as duas coisas, para que você veja tanto a estrutura atual do código quanto os motivos por trás dela.

Páginas

O grafo de código é aberto como uma caixa de diálogo com as abas "Visão geral", "Símbolos", "Explorar código" e "Arquivos". O botão "Base de conhecimento" dessa caixa de diálogo abre a base de conhecimento.

Visão geral: o número de arquivos, símbolos e relações, a distribuição de linguagens e de tipos de símbolo e o estado da sincronização ("Sincronização automática ativa" ou "Sincronizar antes das consultas"). Clique em um item da distribuição para ver os resultados correspondentes.
Símbolos: busca por nome ou caminho de arquivo ("Buscar símbolos ou caminhos de arquivos…"). A página de um símbolo mostra o código-fonte com realce de sintaxe e as "Relações de entrada" e "Relações de saída", agrupadas por tipo de relação e por arquivo. As relações inferidas pela análise são marcadas como "Relação inferida", e os números de linha levam ao local da chamada.
Explorar código: descreva uma funcionalidade ou um fluxo, ou informe um arquivo ou símbolo, e veja o código-fonte e as relações relevantes. Essa consulta é executada localmente e não usa nenhum modelo de IA.
Arquivos: navegue pelos arquivos indexados; clique em um arquivo para listar os símbolos dele.
Símbolos que chamam e Símbolos chamados: na página de um símbolo, mostram vários níveis de chamadas. A "Profundidade da busca" é 3 por padrão e no máximo 6. São exibidos até 500 resultados; quando há mais, aparecem o total e um aviso.
Análise de impacto: na página de um símbolo, mostra os símbolos e arquivos que uma alteração pode afetar, até a profundidade escolhida (3 por padrão, no máximo 6). São exibidos até 500 símbolos e 2.000 relações, com o total e um aviso quando o resultado é cortado.
Caminho de chamadas: na página de um símbolo, busque um símbolo de destino ("Buscar um símbolo de destino…") para ver o caminho mais curto pelas relações de chamada. "Nenhum caminho de chamadas direcionado foi encontrado no índice." significa apenas que o índice não contém esse caminho.

Troque o diretório de trabalho pelo menu de diretórios, que também mostra o caminho completo. A página, a pergunta em Explorar código, o símbolo, a profundidade, o destino e a linha do código-fonte fazem parte da URL; assim, você pode atualizar a página, abri-la em uma nova aba ou usar os botões voltar e avançar do navegador. Um link funciona no mesmo backend, com um login válido.

Ativação do índice de um projeto

Clique com o botão direito em um projeto ou em uma coleção na barra lateral e escolha "Experimental" → "Grafo de código".
Na primeira vez, clique em "Baixar CodeGraph". O backend ao qual você está conectado baixa do GitHub a versão fixa 1.6.0 do CodeGraph e a confere com uma soma de verificação SHA-256 embutida ("A soma de verificação do download não corresponde. O ambiente de execução não foi instalado." significa que a verificação falhou). Não é preciso instalar o Node.js separadamente.
Escolha o "Diretório de trabalho" e clique em "Ativar indexação". O diretório do projeto e os outros diretórios de trabalho usados pelas sessões e pelos grupos dele são listados separadamente; cada worktree do Git tem um índice próprio. Uma coleção precisa ter pelo menos uma sessão com um diretório de trabalho válido.
Aguarde até que o status seja "Pronto" e então busque símbolos ou caminhos de arquivos. A indexação é executada em segundo plano ("Uma tarefa de indexação está em andamento. Você pode fechar esta página ou desativar a indexação para interrompê-la."), e fechar a página não a cancela.

"Sincronizar" atualiza o índice manualmente ou tenta de novo após uma falha. Antes de cada consulta de código, o VelaTerm também atualiza o índice. Para o mesmo backend e o mesmo diretório de trabalho, um único processo de consultas é reutilizado e, enquanto está em execução, incorpora as alterações nos arquivos à medida que elas acontecem. Esse processo é encerrado após cinco minutos sem consultas; a consulta seguinte reabre o índice e incorpora as alterações pendentes. A Visão geral atualiza o estado da sincronização a cada 30 segundos; quando a sincronização automática não está disponível, o VelaTerm continua sincronizando antes de cada consulta e nunca apresenta um resultado desatualizado como atual.

"Desativar indexação" interrompe uma tarefa de indexação em andamento e mantém os arquivos do índice e os vínculos com as entradas de conhecimento, para que você possa ativá-la de novo depois. Quando uma tarefa é interrompida, o estado dela passa a ser, em cerca de dois minutos, uma falha que pode ser repetida ("A tarefa anterior foi interrompida. Sincronize para tentar novamente."). Cada tarefa de indexação pode durar no máximo 30 minutos.

Os índices ficam em uma pasta .codegraph/ em cada diretório de trabalho e são gerenciados pelo CodeGraph. O próprio VelaTerm executa a indexação; ele não executa o instalador de agentes do CodeGraph nem instala hooks do Git. Se o diretório do projeto for uma subpasta de um repositório, apenas essa pasta é indexada.

Visualização das relações do código

Os resultados da busca mostram o nome, o tipo e a localização de cada símbolo. A página de um símbolo mostra o código-fonte, as relações de entrada e de saída e as entradas de conhecimento vinculadas; clique em um símbolo vizinho para continuar.

As relações vêm de análise estática e podem estar incompletas ou ser incertas ("As relações vêm de análise estática e podem ser incompletas ou incertas."); elas não substituem a execução do código. A página de um símbolo mostra no máximo 200 relações em cada direção e 600 linhas de código-fonte, com um aviso quando há mais. Arquivos de código-fonte com mais de 4 MiB não são exibidos. Se um arquivo mudar enquanto você o visualiza, o VelaTerm pede que você sincronize novamente antes de confiar nos números de linha.

Vínculo e revisão de entradas

Na página de um símbolo, escolha "Vincular artigo de conhecimento", selecione uma entrada existente, compare o texto dela com o código e salve. Na página da entrada, "Referências ao código" leva de volta ao código, e os links de entradas no grafo de código abrem a entrada completa.

Um vínculo armazena o projeto, o diretório de trabalho, o caminho do arquivo, a identidade do símbolo e o hash SHA-256 do arquivo no momento da revisão. Quando o arquivo muda, o vínculo mostra "Requer revisão"; quando o arquivo não pode mais ser lido ou foi excluído, mostra "Indisponível"; nos demais casos, mostra "Sem alterações". A verificação é feita por arquivo; assim, qualquer alteração no mesmo arquivo exige uma revisão. Uma página de entrada aberta verifica as referências dela periodicamente.

Escolha "Revisar código e artigo" para ver o código atual e "Confirmar revisão" quando a entrada continuar válida. O backend verifica de novo se o arquivo e a entrada não mudaram nesse meio-tempo e, se tiverem mudado, pede que você recarregue. A confirmação apenas atualiza a referência ao código; ela não altera o texto da entrada. Para mudar a conclusão, edite a entrada normalmente.

Quando um símbolo é excluído ou renomeado, o vínculo não passa para outro símbolo com o mesmo nome. Use "Remover vínculo" e vincule o símbolo correto. Excluir uma entrada remove os vínculos dela; excluir um projeto remove os registros de índice e os vínculos dele, mas não as outras entradas nem os arquivos de índice nos diretórios de trabalho.

Consultas a partir de uma sessão

Toda sessão de terminal e de agente iniciada pelo VelaTerm tem o comando vkb. Outros agentes capazes de executar comandos no terminal também podem usá-lo. Se uma sessão existente não encontrar vkb depois de uma atualização, reinicie a sessão.

Com as "Vela Skills" instaladas (Configurações ▸ Geral), o Claude pode usar /vkb e o Codex, $vkb. A habilidade só é executada quando você a pede explicitamente; os agentes não a chamam por conta própria durante outros trabalhos. Se um agente não listar a habilidade depois de uma atualização, clique em "Reinstall" e reinicie a sessão desse agente.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore retorna o mesmo resultado que Explorar código.
callers, callees e impact aceitam uma profundidade opcional; os resultados incluem relations, total, depth e truncated.
path recebe dois IDs exatos de símbolos obtidos nos resultados da busca, e files pode filtrar por caminho.
search retorna separadamente resultados de código (ordenados por relevância, com hasMore quando há mais), entradas de conhecimento e notas locais.
node retorna o código-fonte, as relações e as entradas vinculadas de um símbolo.
memories e memory pesquisam e leem entradas da base de conhecimento de sessões, incluindo fontes, revisões e referências ao código.
notes e note pesquisam e leem as bases de conhecimento locais (consulte Bases de Conhecimento Locais).

As consultas de código usam o índice do diretório em que o comando é executado. Uma subpasta usa o índice do projeto dela, e um worktree separado aninhado nunca usa o índice do checkout principal. Quando nenhum índice está ativado ou uma consulta falha, o resultado informa que o código não está disponível, e as consultas de conhecimento continuam funcionando. Esses comandos não instalam nada, não ativam a indexação e não alteram entradas.

Onde os dados ficam

O ambiente de execução do CodeGraph é instalado em codegraph/1.6.0/, no diretório de dados do aplicativo. As tarefas de indexação e os vínculos de entradas são armazenados no banco de dados do aplicativo (tabelas knowledge_*). A indexação é executada no backend onde está o código; clientes no navegador e conexões SSH leem os resultados pela conexão que já existe, então nenhuma porta adicional é aberta. Cada backend mantém as próprias configurações de índice e a própria base de conhecimento.

A telemetria, a verificação de atualizações e o serviço separado em segundo plano do CodeGraph ficam desativados. O VelaTerm gerencia o processo de consultas e se comunica com ele por um canal privado de entrada e saída padrão, sem escutar em nenhuma porta. A indexação em si não usa IA. O código ou as entradas que um agente lê com vkb podem ser enviados ao serviço de modelos configurado para esse agente, da mesma forma que acontece quando o agente lê arquivos de código-fonte.

Os eventos do grafo de código são gravados em logs/runtime-*.log, no diretório de dados do aplicativo. Quando VLX_LOG_DIR não está definida, VLX_KNOWLEDGE_LOG_DIR define o diretório deles. VLX_KNOWLEDGE_LOG_LEVEL os filtra (por exemplo, error ou off). O log não contém código-fonte, texto de consultas, texto de entradas nem credenciais.

O CodeGraph é desenvolvido em github.com/colbymchenry/codegraph e distribuído sob a licença MIT.