Ejecutar una herramienta CLI compleja desde scripts y comprobar el éxito en su informe JSON

## Juzgar el éxito de la CLI con datos estructurados, no con el texto de progreso Cuando un script, una canalización o un agente de programación controle una herramienta compleja de línea de comandos, trate la CLI como una interfaz para máquinas con versión, no como un intérprete interactivo. Separe la planificación, la ejecución y la verificación para que cada etapa consuma datos estructurados y produzca pruebas que la siguiente etapa pueda validar. - No analice texto de progreso dirigido a personas para decidir si una ejecución tuvo éxito. - No deduzca de memoria las tareas compatibles, las clases de salida ni los requisitos de licencia. - Registre la versión de la herramienta, la configuración de ejecución resuelta, el alcance solicitado y los artefactos producidos. - Aplique un fallo seguro cuando falten las pruebas estructuradas obligatorias o sean incoherentes. ## Revisar las tareas y clases de la herramienta antes de planificar Use el comando ligero de información o de registro de la herramienta antes de construir un trabajo costoso. Prefiera una vista JSON generada a partir del mismo registro que valida la CLI principal, porque las listas copiadas del código fuente y los nombres codificados pueden desviarse de la versión instalada. El descubrimiento debe exponer: - las tareas disponibles y su modalidad de entrada; - si cada tarea requiere una licencia o autorización; - la correspondencia exacta entre índices y nombres de clase que aceptan los filtros de clases; - la versión instalada de la herramienta y las restricciones específicas de cada tarea. Prefiera una vía de descubrimiento que no cargue dependencias pesadas de inferencia, no inicialice un acelerador, no descargue pesos de modelos ni modifique el estado local. Limite la consulta a una tarea o a una vista de clases cuando no sea necesario consultar todo el registro. ## Indicar todas las entradas, salidas y opciones para poder repetir la ejecución Construya cada ejecución con valores explícitos: entrada, salida, tarea, política de dispositivo, subconjunto opcional de clases, representación de salida y ruta del informe. Acepte solo formas de entrada documentadas, como un archivo de volumen, un directorio de cortes ordenados o un archivo comprimido de cortes, y valide el destino elegido según el modo de salida seleccionado. Antes de ejecutar: 1. Confirme que la tarea y las clases solicitadas existen en el registro de capacidades actual. 2. Confirme que la forma de entrada es compatible y que la ruta de salida no es ambigua. 3. Resuelva la licencia antes de iniciar una tarea restringida. 4. Seleccione deliberadamente el dispositivo y el modo de rendimiento. 5. Reserve una ruta única para el informe de ejecución legible por máquina. No reutilice un directorio de salida si artefactos antiguos podrían confundirse con los resultados actuales. Conserve los parámetros resueltos del comando junto con las pruebas de la ejecución. ## Elegir el dispositivo y el modo rápido, y revisar la licencia antes de una tarea que la exige Trate la selección del dispositivo y las opciones de velocidad como parte del contrato de reproducibilidad. Registre el dispositivo resuelto, no solo el solicitado, porque la falta de aceleración disponible puede provocar una alternativa en CPU con un tiempo de ejecución sustancialmente distinto. Cuando los recursos sean limitados, reduzca el coste mediante controles documentados: - use un modo rápido de menor resolución cuando su pérdida de precisión sea aceptable; - solicite solo las clases necesarias para el trabajo posterior; - use un índice de acelerador concreto cuando haya varios dispositivos; - seleccione explícitamente el motor de plataforma compatible cuando sea necesario. Nunca sustituya silenciosamente un modo por otro más rápido o más limitado si cambia la calidad o el alcance del resultado. Si una tarea requiere licencia, deténgase antes de la inferencia salvo que ya exista una autorización válida. ## Comprobar el informe JSON y cada archivo que enumera Exija que la CLI escriba un informe estructurado después de completarse correctamente. El informe es el artefacto de traspaso autoritativo para la automatización y debe incluir: - versiones de la herramienta, el entorno de ejecución, el marco y las dependencias; - tarea, modalidad y requisito de licencia; - dispositivo resuelto e indicadores de rendimiento; - ubicaciones normalizadas de entrada y salida; - subconjunto de clases solicitado y correspondencia final entre índices y nombres de clase; - tiempo real transcurrido y lista exacta de archivos de salida producidos. Verifique que el informe exista, pueda analizarse como JSON, identifique la tarea esperada y enumere todos los artefactos que necesita la etapa siguiente. Después, compruebe que exista cada archivo enumerado. Use resultados estadísticos específicos para el volumen, la intensidad, el número de vóxeles, la dispersión, los extremos, los centroides o los cuadros delimitadores de cada clase; no deduzca estos valores de los nombres de archivo ni del texto de progreso. ## Separar los fallos por código de salida y reintentar en una carpeta nueva Interprete el estado de salida del proceso antes de leer cualquier artefacto opcional. Distinga entre finalización correcta, fallo durante la ejecución y fallo de argumentos o uso, para que los reintentos no repitan comandos inválidos. - Si la ejecución tiene éxito, valide el informe y los archivos de salida declarados. - Ante un fallo de ejecución, capture el error estándar de diagnóstico y clasifique causas como falta de autorización, recursos no disponibles, entrada dañada o un error no gestionado de la herramienta. - Ante un fallo de argumentos, corrija la tarea, la entrada, la salida o el conjunto de opciones antes de reintentar. - Use el modo silencioso para reducir el ruido habitual y el modo de depuración solo cuando necesite contexto de diagnóstico adicional. No considere un éxito los archivos parciales, un mensaje de progreso ni un directorio de salida vacío. Un reintento debe usar un destino nuevo o limpio para que los artefactos del intento fallido no puedan satisfacer la verificación. ## Usar la API pública y encadenar los pasos siguientes con la lista de archivos del informe Use la API de programación de alto nivel compatible cuando sea necesaria la ejecución dentro del proceso, pero mantenga el mismo contrato explícito de tarea, entrada, salida y verificación que en el flujo de la CLI. Para planificar y validar, prefiera un módulo de registro ligero que pueda enumerar tareas y clases sin importar todo el entorno de inferencia. Mantenga la orquestación independiente de los detalles internos de implementación: descubra capacidades en el registro oficial, ejecute mediante la CLI o API documentada y encadene el procesamiento posterior a partir de la lista de salidas del informe estructurado. Esto preserva la automatización entre versiones y evita analizar de forma frágil la salida estándar o duplicar tablas de capacidades.