Descripción General del Uso de Herramientas

AI Cockpit Reasoning implementa un sofisticado sistema de herramientas que permite a los modelos de IA interactuar con tu entorno de desarrollo de manera controlada y segura. Este documento explica cómo funcionan las herramientas, cuándo se invocan y cómo se gestionan.

Conceptos Fundamentales

Grupos de Herramientas

Las herramientas están organizadas en grupos lógicos según su funcionalidad:

Categoría	Propósito	Herramientas	Uso Común
Grupo de Lectura	Lectura y búsqueda en el sistema de archivos	read_file, search_files, list_files, list_code_definition_names	Exploración y análisis de código
Grupo de Edición	Modificaciones del sistema de archivos	apply_diff, write_to_file	Cambios de código y manipulación de archivos
Grupo de Navegador	Automatización web	browser_action	Pruebas e interacción web
Grupo de Comandos	Ejecución de comandos del sistema	execute_command	Ejecución de scripts, compilación de proyectos
Grupo MCP	Integración de herramientas externas	use_mcp_tool, access_mcp_resource	Funcionalidad especializada a través de servidores externos
Grupo de Flujo de Trabajo	Gestión de modos y tareas	switch_mode, new_task, ask_followup_question, attempt_completion, update_todo_list	Cambio de contexto y organización de tareas

Herramientas Siempre Disponibles

Ciertas herramientas son accesibles independientemente del modo actual:

• ask_followup_question: Recopilar información adicional de los usuarios
• attempt_completion: Señalar la finalización de una tarea
• switch_mode: Cambiar modos operativos
• new_task: Crear subtareas
• update_todo_list: Gestionar el seguimiento paso a paso de tareas

Herramientas Disponibles

Herramientas de Lectura

Estas herramientas ayudan a AI Cockpit Reasoning a comprender tu código y proyecto:

• read_file - Examina el contenido de los archivos
• search_files - Encuentra patrones en múltiples archivos
• list_files - Mapea la estructura de archivos de tu proyecto
• list_code_definition_names - Crea un mapa estructural de tu código

Herramientas de Edición

Estas herramientas ayudan a AI Cockpit Reasoning a realizar cambios en tu código:

• apply_diff - Realiza cambios precisos y quirúrgicos en tu código
• write_to_file - Crea nuevos archivos o reescribe completamente los existentes

Herramientas de Navegador

Estas herramientas ayudan a AI Cockpit Reasoning a interactuar con aplicaciones web:

• browser_action - Automatiza interacciones del navegador

Herramientas de Comandos

Estas herramientas ayudan a AI Cockpit Reasoning a ejecutar comandos:

• execute_command - Ejecuta comandos y programas del sistema

Herramientas MCP

Estas herramientas ayudan a AI Cockpit Reasoning a conectarse con servicios externos:

• use_mcp_tool - Utiliza herramientas externas especializadas
• access_mcp_resource - Accede a fuentes de datos externas

Herramientas de Flujo de Trabajo

Estas herramientas ayudan a gestionar la conversación y el flujo de tareas:

• ask_followup_question - Obtiene información adicional de ti
• attempt_completion - Presenta los resultados finales
• switch_mode - Cambia a un modo diferente para tareas especializadas
• new_task - Crea una nueva subtarea
• update_todo_list - Realiza seguimiento del progreso de tareas con listas de verificación paso a paso

Mecanismo de Invocación de Herramientas

Cuándo Se Invocan las Herramientas

Las herramientas se invocan bajo condiciones específicas:

1. Requisitos Directos de la Tarea

   • Cuando se necesitan acciones específicas para completar una tarea según lo decidido por el LLM
   • En respuesta a solicitudes del usuario
   • Durante flujos de trabajo automatizados

2. Disponibilidad Basada en Modo

   • Los diferentes modos habilitan diferentes conjuntos de herramientas
   • Los cambios de modo pueden desencadenar cambios en la disponibilidad de herramientas
   • Algunas herramientas están restringidas a modos específicos

3. Invocaciones Dependientes del Contexto

   • Basadas en el estado actual del espacio de trabajo
   • En respuesta a eventos del sistema
   • Durante el manejo y recuperación de errores

Proceso de Decisión

El sistema utiliza un proceso de múltiples pasos para determinar la disponibilidad de herramientas:

1. Validación de Modo

   isToolAllowedForMode(
       tool: string,
       modeSlug: string,
       customModes: ModeConfig[],
       toolRequirements?: Record<string, boolean>,
       toolParams?: Record<string, any>
   )

2. Verificación de Requisitos

   • Verificación de capacidades del sistema
   • Disponibilidad de recursos
   • Validación de permisos

3. Validación de Parámetros

   • Presencia de parámetros requeridos
   • Verificación de tipos de parámetros
   • Validación de valores

Implementación Técnica

Procesamiento de Invocaciones de Herramientas

1. Inicialización

   • Se validan el nombre y los parámetros de la herramienta
   • Se verifica la compatibilidad con el modo
   • Se verifican los requisitos

2. Ejecución

   const toolCall = {
       type: "tool_call",
       name: chunk.name,
       arguments: chunk.input,
       callId: chunk.callId
   }

3. Manejo de Resultados

   • Determinación de éxito/fallo
   • Formateo de resultados
   • Manejo de errores

Seguridad y Permisos

1. Control de Acceso

   • Restricciones del sistema de archivos
   • Limitaciones de ejecución de comandos
   • Controles de acceso a la red

2. Capas de Validación

   • Validación específica de herramientas
   • Restricciones basadas en modo
   • Verificaciones a nivel de sistema

Integración con Modos

Acceso a Herramientas Basado en Modo

Las herramientas se ponen a disposición según el modo actual:

• Modo Code: Acceso completo a herramientas del sistema de archivos, capacidades de edición de código, ejecución de comandos
• Modo Ask: Limitado a herramientas de lectura, capacidades de recopilación de información, sin modificaciones del sistema de archivos
• Modo Architect: Herramientas orientadas al diseño, capacidades de documentación, derechos de ejecución limitados
• Modos Personalizados: Se pueden configurar con acceso específico a herramientas para flujos de trabajo especializados

Cambio de Modo

1. Proceso

   • Preservación del estado del modo actual
   • Actualizaciones de disponibilidad de herramientas
   • Cambio de contexto

2. Impacto en las Herramientas

   • Cambios en el conjunto de herramientas
   • Ajustes de permisos
   • Preservación del contexto

Mejores Prácticas

Directrices de Uso de Herramientas

1. Eficiencia

   • Usa la herramienta más específica para la tarea
   • Evita invocaciones redundantes de herramientas
   • Agrupa operaciones cuando sea posible

2. Seguridad

   • Valida las entradas antes de invocar herramientas
   • Usa los permisos mínimos necesarios
   • Sigue las mejores prácticas de seguridad

3. Manejo de Errores

   • Implementa una verificación adecuada de errores
   • Proporciona mensajes de error significativos
   • Maneja los fallos con elegancia

Patrones Comunes

1. Recopilación de Información

   [ask_followup_question](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files)

2. Modificación de Código

   [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion)

3. Gestión de Tareas

   [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command)

4. Seguimiento de Progreso

   [update_todo_list](/features/tools/update-todo-list) → [execute_command](/features/tools/execute-command) → [update_todo_list](/features/tools/update-todo-list)

Manejo de Errores y Recuperación

Tipos de Errores

1. Errores Específicos de Herramientas

   • Fallos de validación de parámetros
   • Errores de ejecución
   • Problemas de acceso a recursos

2. Errores del Sistema

   • Permiso denegado
   • Recurso no disponible
   • Fallos de red

3. Errores de Contexto

   • Modo inválido para la herramienta
   • Requisitos faltantes
   • Inconsistencias de estado

Estrategias de Recuperación

1. Recuperación Automática

   • Mecanismos de reintento
   • Opciones de respaldo
   • Restauración de estado

2. Intervención del Usuario

   • Notificaciones de error
   • Sugerencias de recuperación
   • Opciones de intervención manual