Pular para o conteúdo principal

codebase_search

Recurso Experimental

A ferramenta codebase_search é um recurso que requer configuração adicional, incluindo um provedor de embedding e um banco de dados vetorial.

A ferramenta codebase_search realiza buscas semânticas em toda a sua base de código usando embeddings de IA. Diferente da busca tradicional baseada em texto, ela entende o significado de suas consultas e encontra código relevante mesmo quando as palavras-chave exatas не correspondem.

Parâmetros​

A ferramenta aceita estes parâmetros:

  • query (obrigatório): Consulta de busca em linguagem natural descrevendo o que você está procurando
  • path (opcional): Caminho do diretório para limitar o escopo da busca a uma parte específica da sua base de código

O Que Faz​

Esta ferramenta pesquisa em sua base de código indexada usando similaridade semântica em vez de correspondência exata de texto. Ela encontra blocos de código que são conceitualmente relacionados à sua consulta, mesmo que não contenham as palavras exatas que você pesquisou. Os resultados incluem trechos de código relevantes com caminhos de arquivo, números de linha e pontuações de similaridade.

Quando é usada?​

  • Quando o AI Cockpit Reasoning precisa encontrar código relacionado a uma funcionalidade específica em seu projeto
  • Ao procurar por padrões de implementação ou estruturas de código semelhantes
  • Ao pesquisar por tratamento de erros, autenticação ou outros padrões de código conceituais
  • Ao explorar bases de código desconhecidas para entender como os recursos são implementados
  • Ao encontrar código relacionado que pode ser afetado por alterações ou refatoração

Principais Características​

  • Compreensão Semântica: Encontra código pelo significado em vez de correspondências exatas de palavras-chave
  • Busca em Todo o Projeto: Pesquisa em toda a sua base de código indexada, não apenas nos arquivos abertos
  • Resultados Contextuais: Retorna trechos de código com caminhos de arquivo e números de linha para fácil navegação
  • Pontuação de Similaridade: Resultados classificados por relevância com pontuações de similaridade (escala de 0 a 1)
  • Filtragem de Escopo: Parâmetro de caminho opcional para limitar as buscas a diretórios específicos
  • Classificação Inteligente: Resultados ordenados por relevância semântica para sua consulta
  • Integração com a UI: Resultados exibidos com destaque de sintaxe e links de navegação
  • Otimizado para Desempenho: Busca rápida baseada em vetores com limites de resultados configuráveis

Requisitos​

Esta ferramenta só está disponível quando o recurso experimental de Indexação da Base de Código está configurado corretamente:

  • Recurso Habilitado: A Indexação da Base de Código deve estar habilitada nas configurações experimentais
  • Provedor de Embedding: Chave de API da OpenAI ou configuração do Ollama necessária
  • Banco de Dados Vetorial: Instância do Qdrant em execução e acessível
  • Status do Índice: A base de código deve estar indexada (status: "Indexado" ou "Indexando")

Limitações​

  • Recurso Experimental: Parte do sistema experimental de indexação da base de código
  • Requer Configuração: Depende de serviços externos (provedor de embedding + Qdrant)
  • Dependência do Índice: Pesquisa apenas em blocos de código indexados
  • Limites de Resultados: Máximo de 50 resultados por busca para manter o desempenho
  • Limite de Similaridade: Retorna apenas resultados acima de 0.4 de pontuação de similaridade
  • Limites de Tamanho de Arquivo: Limitado a arquivos com menos de 1MB que foram indexados com sucesso
  • Suporte a Idiomas: A eficácia depende do suporte de idioma do Tree-sitter

Como Funciona​

Quando a ferramenta codebase_search é invocada, ela segue este processo:

  1. Validação de Disponibilidade:

    • Verifica se o CodeIndexManager está disponível e inicializado
    • Confirma se a indexação da base de código está habilitada nas configurações
    • Verifica se a indexação está configurada corretamente (chaves de API, URL do Qdrant)
    • Valida se o estado atual do índice permite a busca

  2. Processamento da Consulta:

    • Pega sua consulta em linguagem natural e gera um vetor de embedding
    • Usa o mesmo provedor de embedding configurado para a indexação (OpenAI ou Ollama)
    • Converte o significado semântico de sua consulta em uma representação matemática

  3. Execução da Busca Vetorial:

    • Pesquisa no banco de dados vetorial Qdrant por embeddings de código semelhantes
    • Usa a similaridade de cosseno para encontrar os blocos de código mais relevantes
    • Aplica o limite mínimo de similaridade (0.4) para filtrar os resultados
    • Limita os resultados a 50 correspondências para um desempenho ideal

  4. Filtragem de Caminho (se especificado):

    • Filtra os resultados para incluir apenas arquivos dentro do caminho do diretório especificado
    • Usa a comparação de caminhos normalizados para uma filtragem precisa
    • Mantém a classificação de relevância dentro do escopo filtrado

  5. Processamento e Formatação de Resultados:

    • Converte caminhos de arquivo absolutos em caminhos relativos ao espaço de trabalho
    • Estrutura os resultados com caminhos de arquivo, intervalos de linhas, pontuações de similaridade e conteúdo do código
    • Formata tanto para o consumo da IA quanto para a exibição na interface do usuário com destaque de sintaxe

  6. Formato de Saída Duplo:

    • Saída para a IA: Formato de texto estruturado com consulta, caminhos de arquivo, pontuações e trechos de código
    • Saída para a UI: Formato JSON com destaque de sintaxe e capacidades de navegação

Melhores Práticas de Consulta de Busca​

Padrões de Consulta Eficazes​

Bom: Conceitual e específico

<codebase_search>
<query>autenticação de usuário e validação de senha</query>
</codebase_search>

Bom: Focado em recursos

<codebase_search>
<query>configuração do pool de conexões do banco de dados</query>
</codebase_search>

Bom: Orientado a problemas

<codebase_search>
<query>tratamento de erros para solicitações de API</query>
</codebase_search>

Menos eficaz: Muito genérico

<codebase_search>
<query>função</query>
</codebase_search>

Tipos de Consulta que Funcionam Bem​

  • Descrições Funcionais: "processamento de upload de arquivos", "lógica de validação de e-mail"
  • Padrões Técnicos: "implementação do padrão singleton", "uso do método de fábrica"
  • Conceitos de Domínio: "gerenciamento de perfil de usuário", "fluxo de trabalho de processamento de pagamento"
  • Componentes de Arquitetura: "configuração de middleware", "scripts de migração de banco de dados"

Escopo de Diretório​

Use o parâmetro path opcional para focar as buscas em partes específicas da sua base de código:

Buscar em módulos de API:

<codebase_search>
<query>middleware de validação de endpoint</query>
<path>src/api</path>
</codebase_search>

Buscar em arquivos de teste:

<codebase_search>
<query>padrões de configuração de dados simulados</query>
<path>tests</path>
</codebase_search>

Buscar em diretórios de recursos específicos:

<codebase_search>
<query>gerenciamento de estado de componente</query>
<path>src/components/auth</path>
</codebase_search>

Interpretação de Resultados​

Pontuações de Similaridade​

  • 0.8-1.0: Correspondências altamente relevantes, provavelmente exatamente o que você está procurando
  • 0.6-0.8: Boas correspondências com forte similaridade conceitual
  • 0.4-0.6: Potencialmente relevante, mas pode exigir revisão
  • Abaixo de 0.4: Filtrado por ser muito dissimilar

Estrutura do Resultado​

Cada resultado de busca inclui:

  • Caminho do Arquivo: Caminho relativo ao espaço de trabalho para o arquivo que contém a correspondência
  • Pontuação: Pontuação de similaridade indicando relevância (0.4-1.0)
  • Intervalo de Linhas: Números de linha inicial e final para o bloco de código
  • Trecho de Código: O conteúdo do código real que correspondeu à sua consulta

Exemplos de Quando Usado​

  • Ao implementar um novo recurso, o AI Cockpit Reasoning busca por "middleware de autenticação" para entender os padrões existentes antes de escrever um novo código.
  • Ao depurar um problema, o AI Cockpit Reasoning busca por "tratamento de erros em chamadas de API" para encontrar padrões de erro relacionados em toda a base de código.
  • Ao refatorar o código, o AI Cockpit Reasoning busca por "padrões de transação de banco de dados" para garantir a consistência em todas as operações de banco de dados.
  • Ao se familiarizar com uma nova base de código, o AI Cockpit Reasoning busca por "carregamento de configuração" para entender como a aplicação é inicializada.

Exemplos de Uso​

Buscando por código relacionado à autenticação em todo o projeto:

<codebase_search>
<query>lógica de login e autenticação de usuário</query>
</codebase_search>

Encontrando código relacionado ao banco de dados em um diretório específico:

<codebase_search>
<query>conexão com banco de dados e execução de consulta</query>
<path>src/data</path>
</codebase_search>

Procurando por padrões de tratamento de erros no código da API:

<codebase_search>
<query>respostas de erro HTTP e tratamento de exceções</query>
<path>src/api</path>
</codebase_search>

Buscando por utilitários de teste e configurações de mock:

<codebase_search>
<query>configuração de teste e criação de dados simulados</query>
<path>tests</path>
</codebase_search>

Encontrando código de configuração e de ambiente:

<codebase_search>
<query>variáveis de ambiente e configuração da aplicação</query>
</codebase_search>