Ir al contenido principal

execute_command

La herramienta execute_command ejecuta comandos de CLI en el sistema del usuario. Permite a AI Cockpit Reasoning realizar operaciones del sistema, instalar dependencias, compilar proyectos, iniciar servidores y ejecutar otras tareas basadas en terminal necesarias para cumplir los objetivos del usuario.

Parámetros​

La herramienta acepta estos parámetros:

  • command (requerido): El comando de CLI a ejecutar. Debe ser válido para el sistema operativo del usuario.
  • cwd (opcional): El directorio de trabajo en el que ejecutar el comando. Si no se proporciona, se usa el directorio de trabajo actual.

Qué Hace​

Esta herramienta ejecuta comandos de terminal directamente en el sistema del usuario, habilitando una amplia gama de operaciones desde manipulaciones de archivos hasta la ejecución de servidores de desarrollo. Los comandos se ejecutan en instancias de terminal gestionadas con captura de salida en tiempo real, integradas con el sistema de terminal de VS Code para un rendimiento y seguridad óptimos.

¿Cuándo se usa?​

  • Al instalar dependencias del proyecto (npm install, pip install, etc.)
  • Al compilar o construir código (make, npm run build, etc.)
  • Al iniciar servidores de desarrollo o ejecutar aplicaciones
  • Al inicializar nuevos proyectos (git init, npm init, etc.)
  • Al realizar operaciones de archivos más allá de lo que otras herramientas proporcionan
  • Al ejecutar pruebas u operaciones de linting
  • Cuando se necesita ejecutar comandos especializados para tecnologías específicas

Características Principales​

  • Se integra con la API de shell de VS Code para una ejecución confiable en terminal
  • Reutiliza instancias de terminal cuando es posible a través de un sistema de registro
  • Captura la salida del comando línea por línea con retroalimentación en tiempo real
  • Admite comandos de larga duración que continúan en segundo plano
  • Permite la especificación de directorios de trabajo personalizados
  • Mantiene el historial y el estado del terminal entre ejecuciones de comandos
  • Maneja cadenas de comandos complejas apropiadas para el shell del usuario
  • Proporciona estado detallado de finalización de comandos e interpretación de códigos de salida
  • Admite aplicaciones de terminal interactivas con bucle de retroalimentación del usuario
  • Muestra terminales durante la ejecución para mayor transparencia
  • Valida comandos para seguridad usando análisis de shell-quote
  • Bloquea patrones de ejecución de subshell potencialmente peligrosos
  • Se integra con el sistema AI CockpitCodeIgnore para control de acceso a archivos
  • Maneja secuencias de escape de terminal para una salida limpia

Limitaciones​

  • El acceso a comandos puede estar restringido por las reglas de AI CockpitCodeIgnore y las validaciones de seguridad
  • Los comandos con requisitos de permisos elevados pueden necesitar configuración del usuario
  • El comportamiento puede variar entre sistemas operativos para ciertos comandos
  • Los comandos de muy larga duración pueden requerir un manejo específico
  • Las rutas de archivos deben escaparse correctamente según las reglas del shell del sistema operativo
  • No todas las características del terminal pueden funcionar con escenarios de desarrollo remoto

Cómo Funciona​

Cuando se invoca la herramienta execute_command, sigue este proceso:

  1. Validación de Comandos y Verificaciones de Seguridad:

    • Analiza el comando usando shell-quote para identificar componentes
    • Valida contra restricciones de seguridad (uso de subshell, archivos restringidos)
    • Verifica contra las reglas de AI CockpitCodeIgnore para permisos de acceso a archivos
    • Garantiza que el comando cumpla con los requisitos de seguridad del sistema

  2. Gestión de Terminal:

    • Obtiene o crea un terminal a través de TerminalRegistry
    • Configura el contexto del directorio de trabajo
    • Prepara oyentes de eventos para la captura de salida
    • Muestra el terminal para visibilidad del usuario

  3. Ejecución y Monitoreo de Comandos:

    • Se ejecuta a través de la API shellIntegration de VS Code
    • Captura la salida con procesamiento de secuencias de escape
    • Regula el manejo de salida (intervalos de 100ms)
    • Monitorea la finalización del comando o errores
    • Detecta procesos "activos" como compiladores para manejo especial

  4. Procesamiento de Resultados:

    • Elimina secuencias de escape ANSI/VS Code para una salida limpia
    • Interpreta códigos de salida con información detallada de señales
    • Actualiza el seguimiento del directorio de trabajo si el comando lo cambia
    • Proporciona el estado del comando con el contexto apropiado

Detalles de Implementación del Terminal​

La herramienta utiliza un sofisticado sistema de gestión de terminal:

  1. Primera Prioridad: Reutilización de Terminal

    • TerminalRegistry intenta reutilizar terminales existentes cuando es posible
    • Esto reduce la proliferación de instancias de terminal y mejora el rendimiento
    • El estado del terminal (directorio de trabajo, historial) se preserva entre comandos

  2. Segunda Prioridad: Validación de Seguridad

    • Los comandos se analizan usando shell-quote para análisis de componentes
    • Los patrones peligrosos como $(...) y las comillas invertidas están bloqueados
    • Los comandos se verifican contra las reglas de AI CockpitCodeIgnore para control de acceso a archivos
    • Un sistema de lista de permitidos basado en prefijos valida los patrones de comandos

  3. Optimizaciones de Rendimiento

    • La salida se procesa en intervalos regulados de 100ms para evitar la sobrecarga de la interfaz
    • La gestión de búfer de copia cero usa seguimiento basado en índices para mayor eficiencia
    • Manejo especial para compilación y procesos "activos"
    • Optimizaciones específicas de plataforma para Windows PowerShell

  4. Manejo de Errores y Señales

    • Los códigos de salida se mapean a información detallada de señales (SIGTERM, SIGKILL, etc.)
    • Detección de volcado de núcleo para fallos críticos
    • Los cambios de directorio de trabajo se rastrean y manejan automáticamente
    • Recuperación limpia de escenarios de desconexión de terminal

Ejemplos de Uso​

  • Al configurar un nuevo proyecto, AI Cockpit Reasoning ejecuta comandos de inicialización como npm init -y seguido de la instalación de dependencias.
  • Al construir una aplicación web, AI Cockpit Reasoning ejecuta comandos de compilación como npm run build para compilar los activos.
  • Al desplegar código, AI Cockpit Reasoning ejecuta comandos git para confirmar y enviar cambios a un repositorio.
  • Al solucionar problemas, AI Cockpit Reasoning ejecuta comandos de diagnóstico para recopilar información del sistema.
  • Al iniciar un servidor de desarrollo, AI Cockpit Reasoning lanza el comando de servidor apropiado (p. ej., npm start).
  • Al ejecutar pruebas, AI Cockpit Reasoning ejecuta el comando del ejecutor de pruebas para el framework de pruebas del proyecto.

Ejemplos de Uso​

Ejecutar un comando simple en el directorio actual:

<execute_command>
<command>npm run dev</command>
</execute_command>

Instalar dependencias para un proyecto:

<execute_command>
<command>npm install express mongodb mongoose dotenv</command>
</execute_command>

Ejecutar múltiples comandos en secuencia:

<execute_command>
<command>mkdir -p src/components && touch src/components/App.js</command>
</execute_command>

Ejecutar un comando en un directorio específico:

<execute_command>
<command>git status</command>
<cwd>./my-project</cwd>
</execute_command>

Compilar y luego iniciar un proyecto:

<execute_command>
<command>npm run build && npm start</command>
</execute_command>