Ir al contenido principal

read_file

La herramienta read_file examina el contenido de los archivos de un proyecto. Permite a AI Cockpit Reasoning comprender el código, los archivos de configuración y la documentación para brindar una mejor asistencia.

Parámetros​

La herramienta acepta estos parámetros:

  • path (requerido): La ruta del archivo a leer, relativa al directorio de trabajo actual
  • start_line (opcional): El número de línea inicial desde donde comenzar a leer (indexación basada en 1)
  • end_line (opcional): El número de línea final hasta donde leer (basado en 1, inclusivo)
  • auto_truncate (opcional): Si se deben truncar automáticamente los archivos grandes cuando no se especifica un rango de líneas (true/false)

Qué Hace​

Esta herramienta lee el contenido de un archivo especificado y lo devuelve con números de línea para facilitar la referencia. Puede leer archivos completos o secciones específicas, e incluso extraer texto de archivos PDF y documentos Word.

¿Cuándo se usa?​

  • Cuando AI Cockpit Reasoning necesita comprender la estructura del código existente
  • Cuando AI Cockpit Reasoning necesita analizar archivos de configuración
  • Cuando AI Cockpit Reasoning necesita extraer información de archivos de texto
  • Cuando AI Cockpit Reasoning necesita ver el código antes de sugerir cambios
  • Cuando se necesita hacer referencia a números de línea específicos en las discusiones

Características Principales​

  • Muestra el contenido del archivo con números de línea para facilitar la referencia
  • Puede leer porciones específicas de archivos especificando rangos de líneas
  • Extrae texto legible de archivos PDF y DOCX
  • Trunca inteligentemente los archivos grandes para enfocarse en las secciones más relevantes
  • Proporciona resúmenes de métodos con rangos de líneas para archivos de código grandes
  • Transmite eficientemente solo los rangos de líneas solicitados para un mejor rendimiento
  • Facilita la discusión de partes específicas del código con numeración de líneas

Limitaciones​

  • Puede no manejar eficientemente archivos extremadamente grandes sin usar parámetros de rango de líneas
  • Para archivos binarios (excepto PDF y DOCX), puede devolver contenido que no es legible por humanos

Cómo Funciona​

Cuando se invoca la herramienta read_file, sigue este proceso:

  1. Validación de Parámetros: Valida el parámetro path requerido y los parámetros opcionales
  2. Resolución de Ruta: Resuelve la ruta relativa a una ruta absoluta
  3. Selección de Estrategia de Lectura:
    • La herramienta usa una jerarquía de prioridad estricta (explicada en detalle a continuación)
    • Elige entre lectura por rango, truncado automático o lectura completa del archivo
  4. Procesamiento de Contenido:
    • Agrega números de línea al contenido (p. ej., "1 | const x = 13") donde 1 | es el número de línea
    • Para archivos truncados, agrega un aviso de truncado y definiciones de métodos
    • Para formatos especiales (PDF, DOCX, IPYNB), extrae texto legible

Prioridad de Estrategia de Lectura​

La herramienta usa una jerarquía de decisión clara para determinar cómo leer un archivo:

  1. Primera Prioridad: Rango de Líneas Explícito

    • Si se proporciona start_line o end_line, la herramienta siempre realiza una lectura por rango
    • La implementación transmite eficientemente solo las líneas solicitadas, lo que la hace adecuada para procesar archivos grandes
    • Esto tiene prioridad sobre todas las demás opciones

  2. Segunda Prioridad: Truncado Automático para Archivos Grandes

    • Esto solo aplica cuando se cumplen TODAS estas condiciones:
      • No se especifica ni start_line ni end_line
      • El parámetro auto_truncate está establecido en true
      • El archivo no es un archivo binario
      • El archivo supera el umbral de líneas configurado (típicamente 500-1000 líneas)
    • Cuando se activa el truncado automático, la herramienta:
      • Lee solo la primera porción del archivo (determinada por la configuración maxReadFileLine)
      • Agrega un aviso de truncado que muestra el número de líneas mostradas vs. el total
      • Proporciona un resumen de las definiciones de métodos con sus rangos de líneas

  3. Comportamiento Predeterminado: Leer el Archivo Completo

    • Si no se cumple ninguna de las condiciones anteriores, lee el contenido completo del archivo
    • Para formatos especiales como PDF, DOCX e IPYNB, usa extractores especializados

Ejemplos de Uso​

  • Al pedir que se explique o mejore el código, AI Cockpit Reasoning primero lee los archivos relevantes para comprender la implementación actual.
  • Al solucionar problemas de configuración, AI Cockpit Reasoning lee los archivos de configuración para identificar posibles problemas.
  • Al trabajar con documentación, AI Cockpit Reasoning lee los documentos existentes para comprender el contenido actual antes de sugerir mejoras.

Ejemplos de Uso​

Aquí hay varios escenarios que demuestran cómo se usa la herramienta read_file y la salida típica que podrías recibir.

Leer un Archivo Completo​

Para leer el contenido completo de un archivo:

Entrada:

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

Salida Simulada (para un archivo pequeño como example_small.txt):

1 | Esta es la primera línea.
2 | Esta es la segunda línea.
3 | Esta es la tercera línea.

(La salida variará según el contenido real del archivo)

Leer Líneas Específicas​

Para leer solo un rango específico de líneas (p. ej., 46-68):

Entrada:

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

Salida Simulada (para las líneas 2-3 de example_five_lines.txt):

2 | Contenido de la línea dos.
3 | Contenido de la línea tres.

(La salida muestra solo las líneas solicitadas con sus números de línea originales)

Leer un Archivo Grande (Truncado Automático)​

Al leer un archivo grande sin especificar líneas y con auto_truncate habilitado (o predeterminado en true según la configuración):

Entrada:

<read_file>
<path>src/large-module.js</path>
<auto_truncate>true</auto_truncate> <!-- Opcional si el predeterminado es true -->
</read_file>

Salida Simulada (para large_file.log con 1500 líneas, límite 1000):

1 | Entrada de registro 1...
2 | Entrada de registro 2...
...
1000 | Entrada de registro 1000...
[... truncadas 500 líneas ...]

(La salida está limitada al máximo de líneas configurado, con un aviso de truncado)

Intentar Leer un Archivo Inexistente​

Si el archivo especificado no existe:

Entrada:

<read_file>
<path>non_existent_file.txt</path>
</read_file>

Salida Simulada (Error):

Error: Archivo no encontrado en la ruta 'non_existent_file.txt'.

Intentar Leer un Archivo Bloqueado​

Si el archivo está excluido por reglas en un archivo .aicockpitcodeignore:

Entrada:

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

Salida Simulada (Error):

Error: Acceso denegado al archivo '.env' debido a las reglas de .aicockpitcodeignore.