list_files

A ferramenta list_files exibe os arquivos e diretórios dentro de um local especificado. Ela ajuda o AI Cockpit Reasoning a entender a estrutura do seu projeto e a navegar pela sua base de código de forma eficaz.

Parâmetros

A ferramenta aceita estes parâmetros:

• path (obrigatório): O caminho do diretório para listar o conteúdo, relativo ao diretório de trabalho atual
• recursive (opcional): Se deve listar os arquivos recursivamente. Use true para listagem recursiva, false ou omita para apenas o nível superior.

O Que Faz

Esta ferramenta lista todos os arquivos e diretórios em um local especificado, fornecendo uma visão geral clara da estrutura do seu projeto. Ela pode mostrar apenas o conteúdo de nível superior ou explorar subdiretórios recursivamente.

Quando é usada?

• Quando o AI Cockpit Reasoning precisa entender a estrutura do seu projeto
• Quando o AI Cockpit Reasoning explora quais arquivos estão disponíveis antes de ler arquivos específicos
• Quando o AI Cockpit Reasoning mapeia uma base de código para entender melhor sua organização
• Antes de usar ferramentas mais direcionadas como read_file ou search_files
• Quando o AI Cockpit Reasoning precisa verificar tipos de arquivos específicos (como arquivos de configuração) em um projeto

Principais Características

• Lista arquivos e diretórios com os diretórios claramente marcados
• Oferece modos de listagem recursiva e não recursiva
• Ignora inteligentemente diretórios grandes comuns como node_modules e .git no modo recursivo
• Respeita as regras do .gitignore no modo recursivo
• Marca arquivos ignorados pelo .aicockpitcodeignore com um símbolo de cadeado (🔒) quando showAI CockpitCodeIgnoredFiles está ativado
• Otimiza o desempenho com a travessia de diretórios nível a nível
• Ordena os resultados para mostrar os diretórios antes de seu conteúdo, mantendo uma hierarquia lógica
• Apresenta os resultados em um formato limpo e organizado
• Cria automaticamente um mapa mental da estrutura do seu projeto

Limitações

• A listagem de arquivos é limitada a cerca de 200 arquivos por padrão para evitar problemas de desempenho
• Tem um tempo limite de 10 segundos para a travessia de diretórios para evitar travamentos em estruturas de diretórios complexas
• Quando o limite de arquivos é atingido, adiciona uma nota sugerindo o uso de list_files em subdiretórios específicos
• Não foi projetado para confirmar a existência de arquivos que você acabou de criar
• Pode ter desempenho reduzido em estruturas de diretórios muito grandes
• Não pode listar arquivos nos diretórios raiz ou home por razões de segurança

Como Funciona

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

1. Validação de Parâmetros: Valida o parâmetro obrigatório path e o parâmetro opcional recursive
2. Resolução de Caminho: Resolve o caminho relativo para um caminho absoluto
3. Verificações de Segurança: Impede a listagem de arquivos em locais sensíveis como diretórios raiz ou home
4. Varredura de Diretório:
   • Para o modo não recursivo: Lista apenas o conteúdo de nível superior
   • Para o modo recursivo: Atravessa a estrutura de diretórios nível a nível com um tempo limite de 10 segundos
   • Se ocorrer o tempo limite, retorna os resultados parciais coletados até aquele ponto
5. Filtragem de Resultados:
   • No modo recursivo, pula diretórios grandes comuns como node_modules, .git, etc.
   • Respeita as regras do .gitignore no modo recursivo
   • Lida com padrões .aicockpitcodeignore, ocultando arquivos ou marcando-os com um símbolo de cadeado
6. Formatação:
   • Marca os diretórios com uma barra (/) no final
   • Ordena os resultados para mostrar os diretórios antes de seu conteúdo para uma hierarquia lógica
   • Marca arquivos ignorados com um símbolo de cadeado (🔒) quando showAI CockpitCodeIgnored está ativado
   • Limita os resultados a 200 arquivos por padrão com uma nota sobre o uso de subdiretórios
   • Organiza os resultados para legibilidade

Formato de Listagem de Arquivos

Os resultados da listagem de arquivos incluem:

• Cada caminho de arquivo é exibido em sua própria linha
• Os diretórios são marcados com uma barra (/) no final
• Os arquivos ignorados pelo .aicockpitcodeignore são marcados com um símbolo de cadeado (🔒) quando showAI CockpitCodeIgnored está ativado
• Os resultados são ordenados logicamente com os diretórios aparecendo antes de seu conteúdo
• Quando o limite de arquivos é atingido, uma mensagem aparece sugerindo o uso de list_files em subdiretórios específicos

Formato de saída de exemplo:

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
src/utils/
src/utils/helpers.ts
src/index.ts
...
Listagem de arquivos truncada (mostrando 200 de 543 arquivos). Use list_files em subdiretórios específicos para mais detalhes.

Quando arquivos .aicockpitcodeignore são usados e showAI CockpitCodeIgnored está ativado:

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
🔒 src/secrets.json
src/utils/
src/utils/helpers.ts
src/index.ts

Exemplos de Quando Usado

• Ao iniciar uma nova tarefa, o AI Cockpit Reasoning pode listar os arquivos do projeto para entender sua estrutura antes de mergulhar em um código específico.
• Quando solicitado a encontrar tipos específicos de arquivos (como todos os arquivos JavaScript), o AI Cockpit Reasoning primeiro lista os diretórios para saber onde procurar.
• Ao fornecer recomendações para a organização do código, o AI Cockpit Reasoning examina primeiro a estrutura atual do projeto.
• Ao configurar um novo recurso, o AI Cockpit Reasoning lista os diretórios relacionados para entender as convenções do projeto.

Exemplos de Uso

Listando arquivos de nível superior no diretório atual:

<list_files>
<path>.</path>
</list_files>

Listando recursivamente todos os arquivos em um diretório de origem:

<list_files>
<path>src</path>
<recursive>true</recursive>
</list_files>

Examinando um subdiretório específico do projeto:

<list_files>
<path>src/components</path>
<recursive>false</recursive>
</list_files>