Pular para o conteúdo principal

read_file

A ferramenta read_file examina o conteúdo dos arquivos em um projeto. Ela permite que o AI Cockpit Reasoning entenda o código, os arquivos de configuração e a documentação para fornecer uma assistência melhor.

Parâmetros​

A ferramenta aceita estes parâmetros:

  • path (obrigatório): O caminho do arquivo a ser lido em relação ao diretório de trabalho atual
  • start_line (opcional): O número da linha inicial para ler (indexação baseada em 1)
  • end_line (opcional): O número da linha final para ler (baseado em 1, inclusivo)
  • auto_truncate (opcional): Se deve truncar automaticamente arquivos grandes quando o intervalo de linhas não é especificado (verdadeiro/falso)

O Que Faz​

Esta ferramenta lê o conteúdo de um arquivo especificado e o retorna com números de linha para fácil referência. Ela pode ler arquivos inteiros ou seções específicas, e até mesmo extrair texto de PDFs e documentos do Word.

Quando é usada?​

  • Quando o AI Cockpit Reasoning precisa entender a estrutura do código existente
  • Quando o AI Cockpit Reasoning precisa analisar arquivos de configuração
  • Quando o AI Cockpit Reasoning precisa extrair informações de arquivos de texto
  • Quando o AI Cockpit Reasoning precisa ver o código antes de sugerir alterações
  • Quando números de linha específicos precisam ser referenciados em discussões

Principais Características​

  • Exibe o conteúdo do arquivo com números de linha para fácil referência
  • Pode ler porções específicas de arquivos especificando intervalos de linhas
  • Extrai texto legível de arquivos PDF e DOCX
  • Trunca inteligentemente arquivos grandes para focar nas seções mais relevantes
  • Fornece resumos de métodos com intervalos de linhas para arquivos de código grandes
  • Transmite eficientemente apenas os intervalos de linhas solicitados para melhor desempenho
  • Facilita a discussão de partes específicas do código com numeração de linhas

Limitações​

  • Pode não lidar eficientemente com arquivos extremamente grandes sem usar parâmetros de intervalo de linhas
  • Para arquivos binários (exceto PDF e DOCX), pode retornar conteúdo que não é legível por humanos

Como Funciona​

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

  1. Validação de Parâmetros: Valida o parâmetro obrigatório path e os parâmetros opcionais
  2. Resolução de Caminho: Resolve o caminho relativo para um caminho absoluto
  3. Seleção da Estratégia de Leitura:
    • A ferramenta usa uma hierarquia de prioridade estrita (explicada em detalhes abaixo)
    • Ela escolhe entre leitura de intervalo, truncamento automático ou leitura de arquivo completo
  4. Processamento de Conteúdo:
    • Adiciona números de linha ao conteúdo (por exemplo, "1 | const x = 13") onde 1 | é o número da linha.
    • Para arquivos truncados, adiciona um aviso de truncamento e definições de método
    • Para formatos especiais (PDF, DOCX, IPYNB), extrai texto legível

Prioridade da Estratégia de Leitura​

A ferramenta usa uma hierarquia de decisão clara para determinar como ler um arquivo:

  1. Primeira Prioridade: Intervalo de Linha Explícito

    • Se start_line ou end_line for fornecido, a ferramenta sempre realiza uma leitura de intervalo
    • A implementação transmite eficientemente apenas as linhas solicitadas, tornando-a adequada para o processamento de arquivos grandes
    • Isso tem precedência sobre todas as outras opções

  2. Segunda Prioridade: Truncamento Automático para Arquivos Grandes

    • Isso só se aplica quando TODAS estas condições são atendidas:
      • Nem start_line nem end_line são especificados
      • O parâmetro auto_truncate está definido como true
      • O arquivo não é um arquivo binário
      • O arquivo excede o limite de linha configurado (normalmente 500-1000 linhas)
    • Quando o truncamento automático é ativado, a ferramenta:
      • Lê apenas a primeira parte do arquivo (determinada pela configuração maxReadFileLine)
      • Adiciona um aviso de truncamento mostrando o número de linhas exibidas vs. o total
      • Fornece um resumo das definições de método com seus intervalos de linhas

  3. Comportamento Padrão: Ler o Arquivo Inteiro

    • Se nenhuma das condições acima for atendida, ele lê o conteúdo do arquivo inteiro
    • Para formatos especiais como PDF, DOCX e IPYNB, ele usa extratores especializados

Exemplos de Quando Usado​

  • Quando solicitado a explicar ou melhorar o código, o AI Cockpit Reasoning primeiro lê os arquivos relevantes para entender a implementação atual.
  • Ao solucionar problemas de configuração, o AI Cockpit Reasoning lê os arquivos de configuração para identificar possíveis problemas.
  • Ao trabalhar com documentação, o AI Cockpit Reasoning lê os documentos existentes para entender o conteúdo atual antes de sugerir melhorias.

Exemplos de Uso​

Aqui estão vários cenários demonstrando como a ferramenta read_file é usada e a saída típica que você pode receber.

Lendo um Arquivo Inteiro​

Para ler o conteúdo completo de um arquivo:

Entrada:

<read_file>
<path>src/app.js</path>
</read_file>

Saída Simulada (para um arquivo pequeno como example_small.txt):

1 | Esta é a primeira linha.
2 | Esta é a segunda linha.
3 | Esta é a terceira linha.

(A saída irá variar com base no conteúdo real do arquivo)

Lendo Linhas Específicas​

Para ler apenas um intervalo específico de linhas (por exemplo, 46-68):

Entrada:

<read_file>
<path>src/app.js</path>
<start_line>46</start_line>
<end_line>68</end_line>
</read_file>

Saída Simulada (para as linhas 2-3 de example_five_lines.txt):

2 | Conteúdo da linha dois.
3 | Conteúdo da linha três.

(A saída mostra apenas as linhas solicitadas com seus números de linha originais)

Lendo um Arquivo Grande (Truncamento Automático)​

Ao ler um arquivo grande sem especificar linhas e com auto_truncate ativado (ou com o padrão true com base nas configurações):

Entrada:

<read_file>
<path>src/large-module.js</path>
<auto_truncate>true</auto_truncate> <!-- Opcional se o padrão for verdadeiro -->
</read_file>

Saída Simulada (para large_file.log com 1500 linhas, limite de 1000):

1 | Entrada de log 1...
2 | Entrada de log 2...
...
1000 | Entrada de log 1000...
[... 500 linhas truncadas ...]

(A saída é limitada ao máximo de linhas configurado, com um aviso de truncamento)

Tentando Ler um Arquivo Inexistente​

Se o arquivo especificado não existir:

Entrada:

<read_file>
<path>arquivo_inexistente.txt</path>
</read_file>

Saída Simulada (Erro):

Erro: Arquivo não encontrado no caminho 'arquivo_inexistente.txt'.

Tentando Ler um Arquivo Bloqueado​

Se o arquivo for excluído por regras em um arquivo .aicockpitcodeignore:

Entrada:

<read_file>
<path>.env</path>
</read_file>

Saída Simulada (Erro):

Erro: Acesso negado ao arquivo '.env' devido às regras do .aicockpitcodeignore.