Pular para o conteúdo principal

execute_command

A ferramenta execute_command executa comandos CLI no sistema do usuário. Ela permite que o AI Cockpit Reasoning realize operações de sistema, instale dependências, compile projetos, inicie servidores e execute outras tarefas baseadas em terminal necessárias para atingir os objetivos do usuário.

Parâmetros​

A ferramenta aceita estes parâmetros:

  • command (obrigatório): O comando CLI a ser executado. Deve ser válido para o sistema operacional do usuário.
  • cwd (opcional): O diretório de trabalho no qual o comando será executado. Se não for fornecido, o diretório de trabalho atual será usado.

O Que Faz​

Esta ferramenta executa comandos de terminal diretamente no sistema do usuário, permitindo uma ampla gama de operações, desde manipulações de arquivos até a execução de servidores de desenvolvimento. Os comandos são executados em instâncias de terminal gerenciadas com captura de saída em tempo real, integradas ao sistema de terminal do VS Code para desempenho e segurança ideais.

Quando é usada?​

  • Ao instalar dependências do projeto (npm install, pip install, etc.)
  • Ao construir ou compilar código (make, npm run build, etc.)
  • Ao iniciar servidores de desenvolvimento ou executar aplicações
  • Ao inicializar novos projetos (git init, npm init, etc.)
  • Ao realizar operações de arquivo além do que outras ferramentas fornecem
  • Ao executar testes ou operações de linting
  • Quando é necessário executar comandos especializados para tecnologias específicas

Principais Características​

  • Integra-se com a API de shell do VS Code para execução confiável de terminal
  • Reutiliza instâncias de terminal quando possível através de um sistema de registro
  • Captura a saída do comando linha por linha com feedback em tempo real
  • Suporta comandos de longa duração que continuam em segundo plano
  • Permite a especificação de diretórios de trabalho personalizados
  • Mantém o histórico do terminal e o estado entre as execuções de comandos
  • Lida com cadeias de comandos complexas apropriadas para o shell do usuário
  • Fornece status de conclusão de comando detalhado e interpretação de código de saída
  • Suporta aplicações de terminal interativas com ciclo de feedback do usuário
  • Mostra os terminais durante a execução para transparência
  • Valida comandos para segurança usando a análise de shell-quote
  • Bloqueia padrões de execução de subshell potencialmente perigosos
  • Integra-se com o sistema AI CockpitCodeIgnore para controle de acesso a arquivos
  • Lida com sequências de escape de terminal para uma saída limpa

Limitações​

  • O acesso a comandos pode ser restringido pelas regras do AI CockpitCodeIgnore e validações de segurança
  • Comandos com requisitos de permissão elevada podem precisar de configuração do usuário
  • O comportamento pode variar entre os sistemas operacionais para certos comandos
  • Comandos de longa duração podem exigir tratamento específico
  • Os caminhos dos arquivos devem ser devidamente escapados de acordo com as regras do shell do SO
  • Nem todos os recursos do terminal podem funcionar com cenários de desenvolvimento remoto

Como Funciona​

Quando a ferramenta execute_command é invocada, ela segue este processo:

  1. Validação de Comando e Verificações de Segurança:

    • Analisa o comando usando shell-quote para identificar componentes
    • Valida contra restrições de segurança (uso de subshell, arquivos restritos)
    • Verifica as regras do AI CockpitCodeIgnore para permissões de acesso a arquivos
    • Garante que o comando atenda aos requisitos de segurança do sistema

  2. Gerenciamento do Terminal:

    • Obtém ou cria um terminal através do TerminalRegistry
    • Configura o contexto do diretório de trabalho
    • Prepara os ouvintes de eventos para a captura de saída
    • Mostra o terminal para visibilidade do usuário

  3. Execução e Monitoramento de Comandos:

    • Executa através da API shellIntegration do VS Code
    • Captura a saída com processamento de sequência de escape
    • Limita o manuseio da saída (intervalos de 100ms)
    • Monitora a conclusão ou erros do comando
    • Detecta processos "quentes" como compiladores para tratamento especial

  4. Processamento do Resultado:

    • Remove as sequências de escape ANSI/VS Code para uma saída limpa
    • Interpreta os códigos de saída com informações detalhadas do sinal
    • Atualiza o rastreamento do diretório de trabalho se alterado pelo comando
    • Fornece o status do comando com o contexto apropriado

Detalhes da Implementação do Terminal​

A ferramenta usa um sistema sofisticado de gerenciamento de terminal:

  1. Primeira Prioridade: Reutilização do Terminal

    • O TerminalRegistry tenta reutilizar terminais existentes quando possível
    • Isso reduz a proliferação de instâncias de terminal e melhora o desempenho
    • O estado do terminal (diretório de trabalho, histórico) é preservado entre os comandos

  2. Segunda Prioridade: Validação de Segurança

    • Os comandos são analisados usando shell-quote para análise de componentes
    • Padrões perigosos como $(...) e crases são bloqueados
    • Os comandos são verificados em relação às regras do AI CockpitCodeIgnore para controle de acesso a arquivos
    • Um sistema de lista de permissões baseado em prefixo valida os padrões de comando

  3. Otimizações de Desempenho

    • A saída é processada em intervalos limitados de 100ms para evitar sobrecarga da interface do usuário
    • O gerenciamento de buffer de cópia zero usa rastreamento baseado em índice para eficiência
    • Tratamento especial para compilação e processos "quentes"
    • Otimizações específicas da plataforma para o Windows PowerShell

  4. Tratamento de Erros e Sinais

    • Os códigos de saída são mapeados para informações detalhadas do sinal (SIGTERM, SIGKILL, etc.)
    • Detecção de despejo de memória para falhas críticas
    • As alterações no diretório de trabalho são rastreadas e tratadas automaticamente
    • Recuperação limpa de cenários de desconexão do terminal

Exemplos de Quando Usado​

  • Ao configurar um novo projeto, o AI Cockpit Reasoning executa comandos de inicialização como npm init -y seguidos da instalação de dependências.
  • Ao construir uma aplicação web, o AI Cockpit Reasoning executa comandos de compilação como npm run build para compilar os ativos.
  • Ao implantar código, o AI Cockpit Reasoning executa comandos git para confirmar e enviar alterações para um repositório.
  • Ao solucionar problemas, o AI Cockpit Reasoning executa comandos de diagnóstico para coletar informações do sistema.
  • Ao iniciar um servidor de desenvolvimento, o AI Cockpit Reasoning executa o comando de servidor apropriado (por exemplo, npm start).
  • Ao executar testes, o AI Cockpit Reasoning executa o comando do executor de testes para o framework de testes do projeto.

Exemplos de Uso​

Executando um comando simples no diretório atual:

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

Instalando dependências para um projeto:

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

Executando múltiplos comandos em sequência:

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

Executando um comando em um diretório específico:

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

Construindo e depois iniciando um projeto:

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