Ir al contenido principal

list_files

La herramienta list_files muestra los archivos y directorios dentro de una ubicación especificada. Ayuda a AI Cockpit Reasoning a comprender la estructura de tu proyecto y navegar por tu base de código de manera efectiva.

Parámetros​

La herramienta acepta estos parámetros:

  • path (requerido): La ruta del directorio cuyos contenidos se listarán, relativa al directorio de trabajo actual
  • recursive (opcional): Si se deben listar los archivos de forma recursiva. Usa true para listado recursivo, false u omite para solo el nivel superior.

Qué Hace​

Esta herramienta lista todos los archivos y directorios en una ubicación especificada, proporcionando una visión general clara de la estructura de tu proyecto. Puede mostrar solo el contenido del nivel superior o explorar recursivamente los subdirectorios.

¿Cuándo se usa?​

  • Cuando AI Cockpit Reasoning necesita comprender la estructura de tu proyecto
  • Cuando AI Cockpit Reasoning explora qué archivos están disponibles antes de leer los específicos
  • Cuando AI Cockpit Reasoning mapea una base de código para comprender mejor su organización
  • Antes de usar herramientas más específicas como read_file o search_files
  • Cuando AI Cockpit Reasoning necesita verificar tipos de archivos específicos (como archivos de configuración) en un proyecto

Características Principales​

  • Lista tanto archivos como directorios con los directorios claramente marcados
  • Ofrece modos de listado recursivo y no recursivo
  • Ignora inteligentemente los directorios grandes comunes como node_modules y .git en modo recursivo
  • Respeta las reglas de .gitignore en modo recursivo
  • Marca los archivos ignorados por .aicockpitcodeignore con un símbolo de candado (🔒) cuando showAI CockpitCodeIgnoredFiles está habilitado
  • Optimiza el rendimiento con recorrido de directorios nivel por nivel
  • Ordena los resultados para mostrar los directorios antes que su contenido, manteniendo una jerarquía lógica
  • Presenta los resultados en un formato limpio y organizado
  • Crea automáticamente un mapa mental de la estructura de tu proyecto

Limitaciones​

  • El listado de archivos está limitado a aproximadamente 200 archivos por defecto para evitar problemas de rendimiento
  • Tiene un tiempo de espera de 10 segundos para el recorrido de directorios para evitar bloqueos en estructuras de directorios complejas
  • Cuando se alcanza el límite de archivos, agrega una nota sugiriendo usar list_files en subdirectorios específicos
  • No está diseñado para confirmar la existencia de archivos que acabas de crear
  • Puede tener rendimiento reducido en estructuras de directorios muy grandes
  • No puede listar archivos en directorios raíz o de inicio por razones de seguridad

Cómo Funciona​

Cuando se invoca la herramienta list_files, sigue este proceso:

  1. Validación de Parámetros: Valida el parámetro requerido path y el parámetro opcional recursive
  2. Resolución de Ruta: Resuelve la ruta relativa a una ruta absoluta
  3. Verificaciones de Seguridad: Previene el listado de archivos en ubicaciones sensibles como directorios raíz o de inicio
  4. Escaneo de Directorio:
    • Para modo no recursivo: Lista solo el contenido del nivel superior
    • Para modo recursivo: Recorre la estructura de directorios nivel por nivel con un tiempo de espera de 10 segundos
    • Si se agota el tiempo de espera, devuelve los resultados parciales recopilados hasta ese momento
  5. Filtrado de Resultados:
    • En modo recursivo, omite los directorios grandes comunes como node_modules, .git, etc.
    • Respeta las reglas de .gitignore en modo recursivo
    • Maneja los patrones de .aicockpitcodeignore, ya sea ocultando archivos o marcándolos con un símbolo de candado
  6. Formateo:
    • Marca los directorios con una barra diagonal al final (/)
    • Ordena los resultados para mostrar los directorios antes que su contenido para una jerarquía lógica
    • Marca los archivos ignorados con un símbolo de candado (🔒) cuando showAI CockpitCodeIgnored está habilitado
    • Limita los resultados a 200 archivos por defecto con una nota sobre el uso de subdirectorios
    • Organiza los resultados para facilitar la lectura

Formato de Listado de Archivos​

Los resultados del listado de archivos incluyen:

  • Cada ruta de archivo se muestra en su propia línea
  • Los directorios están marcados con una barra diagonal al final (/)
  • Los archivos ignorados por .aicockpitcodeignore están marcados con un símbolo de candado (🔒) cuando showAI CockpitCodeIgnored está habilitado
  • Los resultados están ordenados lógicamente con los directorios apareciendo antes que su contenido
  • Cuando se alcanza el límite de archivos, aparece un mensaje sugiriendo usar list_files en subdirectorios específicos

Formato de salida de ejemplo:

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
src/utils/
src/utils/helpers.ts
src/index.ts
...
Listado de archivos truncado (mostrando 200 de 543 archivos). Usa list_files en subdirectorios específicos para más detalles.

Cuando se usan archivos .aicockpitcodeignore y showAI CockpitCodeIgnored está habilitado:

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

Ejemplos de Uso​

  • Al comenzar una nueva tarea, AI Cockpit Reasoning puede listar los archivos del proyecto para comprender su estructura antes de profundizar en el código específico.
  • Al pedir encontrar tipos específicos de archivos (como todos los archivos JavaScript), AI Cockpit Reasoning primero lista los directorios para saber dónde buscar.
  • Al proporcionar recomendaciones para la organización del código, AI Cockpit Reasoning examina primero la estructura actual del proyecto.
  • Al configurar una nueva característica, AI Cockpit Reasoning lista los directorios relacionados para comprender las convenciones del proyecto.

Ejemplos de Uso​

Listar los archivos del nivel superior en el directorio actual:

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

Listar recursivamente todos los archivos en un directorio fuente:

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

Examinar un subdirectorio específico del proyecto:

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