Executar uma ferramenta CLI complexa a partir de scripts e confirmar o sucesso no relatório JSON

## Julgar o sucesso da CLI por dados estruturados, não pelo texto de progresso Quando um script, uma cadeia de processamento ou um agente de programação controlar uma ferramenta complexa de linha de comando, trate a CLI como uma interface versionada para máquinas, e não como um interpretador interativo. Separe planejamento, execução e verificação para que cada etapa consuma dados estruturados e produza evidências que a etapa seguinte possa validar. - Não analise texto de progresso destinado a pessoas para decidir se uma execução foi bem-sucedida. - Não deduza de memória as tarefas compatíveis, as classes de saída nem os requisitos de licença. - Registre a versão da ferramenta, as configurações de execução resolvidas, o escopo solicitado e os artefatos produzidos. - Adote falha segura quando as evidências estruturadas obrigatórias estiverem ausentes ou forem incoerentes. ## Conferir as tarefas e classes da ferramenta antes de planejar Use o comando leve de informações ou de registro da ferramenta antes de montar um trabalho dispendioso. Prefira uma visualização JSON gerada pelo mesmo registro que valida a CLI principal, pois listas copiadas do código-fonte e nomes fixados no código podem divergir da versão instalada. A descoberta deve apresentar: - as tarefas disponíveis e suas modalidades de entrada; - se cada tarefa exige licença ou direito de uso; - o mapeamento exato entre índices e nomes de classe aceito pelos filtros de classe; - a versão instalada da ferramenta e as restrições específicas de cada tarefa. Prefira um caminho de descoberta que não carregue dependências pesadas de inferência, não inicialize um acelerador, não baixe pesos de modelos nem altere o estado local. Restrinja a consulta a uma tarefa ou visualização de classes quando o registro completo não for necessário. ## Indicar todas as entradas, saídas e opções para poder repetir a execução Monte cada execução com valores explícitos: entrada, saída, tarefa, política de dispositivo, subconjunto opcional de classes, representação da saída e caminho do relatório. Aceite apenas formas de entrada documentadas, como um arquivo de volume, um diretório de fatias ordenadas ou um arquivo compactado de fatias, e valide o destino escolhido em relação ao modo de saída selecionado. Antes da execução: 1. Confirme que a tarefa e as classes solicitadas existem no registro de capacidades atual. 2. Confirme que a forma de entrada é compatível e que o caminho de saída não é ambíguo. 3. Resolva a licença antes de iniciar uma tarefa restrita. 4. Selecione deliberadamente o dispositivo e o modo de desempenho. 5. Reserve um caminho exclusivo para o relatório de execução legível por máquina. Não reutilize um diretório de saída se artefatos antigos puderem ser confundidos com os resultados atuais. Preserve os parâmetros resolvidos do comando junto às evidências da execução. ## Escolher o dispositivo e o modo rápido e conferir a licença antes de uma tarefa que a exige Trate a seleção do dispositivo e as opções de velocidade como parte do contrato de reprodutibilidade. Registre o dispositivo efetivamente resolvido, não apenas o solicitado, pois a indisponibilidade de aceleração pode provocar uma alternativa em CPU com tempo de execução significativamente diferente. Quando os recursos forem limitados, reduza o custo por meio de controles documentados: - use um modo rápido de menor resolução quando a perda de precisão for aceitável; - solicite apenas as classes necessárias ao processamento posterior; - use um índice específico de acelerador quando houver vários dispositivos; - selecione explicitamente o módulo de plataforma compatível quando necessário. Nunca troque silenciosamente para um modo mais rápido ou mais restrito se ele alterar a qualidade ou o escopo do resultado. Se uma tarefa exigir licença, interrompa antes da inferência, a menos que já exista uma autorização válida configurada. ## Conferir o relatório JSON e cada arquivo listado nele Exija que a CLI grave um relatório estruturado após a conclusão bem-sucedida. O relatório é o artefato de transferência oficial para a automação e deve incluir: - versões da ferramenta, do ambiente de execução, da estrutura de software e das dependências; - tarefa, modalidade e requisito de licença; - dispositivo resolvido e indicadores de desempenho; - locais normalizados de entrada e saída; - subconjunto de classes solicitado e mapeamento final entre índices e nomes de classe; - tempo real de execução e lista exata dos arquivos de saída produzidos. Verifique se o relatório existe, pode ser interpretado como JSON, identifica a tarefa esperada e lista todos os artefatos necessários à etapa seguinte. Depois, confirme que cada arquivo listado existe. Use resultados estatísticos específicos para volume, intensidade, número de voxels, dispersão, extremos, centroides ou caixas delimitadoras de cada classe; não deduza esses valores de nomes de arquivo nem de texto de progresso. ## Separar falhas pelo código de saída e tentar de novo em uma pasta nova Interprete o estado de saída do processo antes de ler qualquer artefato opcional. Diferencie conclusão bem-sucedida, falha de execução e falha de argumentos ou uso, para que novas tentativas não repitam comandos inválidos. - Em caso de sucesso, valide o relatório e os arquivos de saída declarados. - Em caso de falha de execução, capture o erro padrão de diagnóstico e classifique causas como falta de autorização, recursos indisponíveis, entrada corrompida ou erro não tratado da ferramenta. - Em caso de falha de argumentos, corrija a tarefa, a entrada, a saída ou o conjunto de opções antes de tentar novamente. - Use o modo silencioso para reduzir o ruído habitual e o modo de depuração apenas quando precisar de mais contexto diagnóstico. Não considere arquivos parciais, uma mensagem de progresso nem um diretório de saída vazio como sucesso. Uma nova tentativa deve usar um destino novo ou limpo, para que os artefatos da tentativa malsucedida não possam satisfazer a verificação. ## Usar a API pública e ligar as próximas etapas pela lista de arquivos do relatório Use a API de programação de alto nível compatível quando a execução dentro do processo for necessária, mas mantenha o mesmo contrato explícito de tarefa, entrada, saída e verificação do fluxo da CLI. Para planejamento e validação, prefira um módulo de registro leve que possa listar tarefas e classes sem importar todo o ambiente de inferência. Mantenha a orquestração independente dos detalhes internos de implementação: descubra capacidades no registro oficial, execute pela CLI ou API documentada e encadeie o processamento posterior a partir da lista de saídas do relatório estruturado. Isso preserva a automação entre versões, evitando a análise frágil da saída padrão e tabelas de capacidades duplicadas.