Desktop Control para Windows

Controle de Desktop para Windows

Visão Geral

Use esta skill para operar a UI visível do Windows como um humano rápido: captura de tela, raciocine a partir de pixels, ative uma janela alvo, então emita ações de teclado/mouse através dos scripts incluídos. O fluxo de trabalho ativo é apenas automação Python local.

Esta skill tem dois papéis:

• Coordenador: qualquer agente em qualquer profundidade que não seja o worker de UI, decide se o controle de UI visível é necessário, delega uma tarefa de UI delimitada a um worker quando a delegação está disponível, e relata um bloqueador de ferramenta/política apenas quando a delegação está genuinamente indisponível.
• Worker de UI: o agente já delegado que tira capturas de tela, inspeciona pixels e executa scripts/ui_control.py diretamente.

Portão de delegação obrigatório: para qualquer tarefa de controle de UI do Windows ao vivo, primeiro decida seu papel a partir do prompt que você recebeu. Se você não foi explicitamente gerado como o worker de UI/worker de controle de tela para esta tarefa de UI, você é o coordenador mesmo se já for um subagente de uma tarefa maior. Não tire capturas de tela, visualize capturas de tela, chame scripts/ui_control.py ou inspecione imagens da tela ao vivo você mesmo. Delegue exatamente um worker de UI dedicado. Quando spawn_agent ou uma ferramenta de delegação equivalente estiver disponível, o uso ativo desta skill é a autorização para criar o worker; não peça ao usuário para enviar uma palavra mágica, senha ou confirmação extra. Pule a delegação apenas quando você já é o worker de UI ou quando está depurando/editando esta skill em si.

Nunca permita delegação recursiva de worker de UI. Agentes de tarefas comuns podem ser aninhados dois ou três níveis de profundidade e ainda assim criar um worker de UI dedicado para sua própria fase de UI visível. O worker de UI folha em si não deve gerar, delegar, enviar mensagens ou esperar por qualquer outro agente. Faça o trabalho de UI localmente com o script incluído e retorne um relatório de texto conciso.

Bloqueio global de UI: todos os workers de UI ao vivo compartilham um arquivo de bloqueio através de scripts/ui_control.py. Um worker de UI deve adquirir o bloqueio no início de sua fase de UI, passar o --lock-token retornado para cada comando de captura de tela/janela/mouse/teclado/área de transferência e liberar o bloqueio antes de retornar. Se outro worker já estiver com o bloqueio, espere por ele ou retorne parcial com os detalhes do bloqueio ocupado. Isso impede que agentes paralelos briguem pelo mouse, teclado, janela em primeiro plano ou área de transferência.

Entrada de texto sensível ao idioma: antes de procurar um alvo de UI nomeado como o Assistente de Transferência de Arquivos do WeChat, primeiro inspecione o idioma do aplicativo/rótulos visíveis enquanto segura o bloqueio de UI. Se a UI for chinesa, passe o rótulo chinês como escapes Unicode ASCII para type ... --decode-unicode-escapes --method paste ou clipboard set ... --decode-unicode-escapes, por exemplo \u6587\u4ef6\u4f20\u8f93\u52a9\u624b; não digite chinês bruto através de prompts aninhados, argumentos de shell ou arquivos de comando. Se a UI for inglesa, use o rótulo em inglês ou um alias seguro para ASCII como filehelper. Se o idioma não puder ser determinado, prefira entrada Unicode-escape através do script em vez de texto não-ASCII bruto e verifique o alvo resultante antes de agir.

Fonte migrada do ClawHub breckengan/control v1.0.0 para padrões de controle de desktop local.

Escopo da Migração

Capacidades de Controle local migradas: movimento absoluto/relativo do mouse, movimento com duração suave via PyAutoGUI, clique esquerdo/direito/meio/duplo, mouse para baixo/cima, pressionar e segurar mouse, arrastar, rolagem vertical/horizontal, posição do mouse, entrada de texto por teclas ou colar da área de transferência, teclas de atalho, tecla para baixo/cima, segurar tecla, capturas de tela, capturas de região, cor do pixel, correspondência de imagem, tamanho da tela, lista de janelas/ativa/ativar/informações/minimizar/maximizar/restaurar/fechar, definir/obter área de transferência, failsafe, aprovação opcional, verificações de limites estritos, registro de ações JSONL e planos em lote.

Intencionalmente não copiado: os scripts de demonstração upstream e o aplicativo de demonstração baseado em regras ai_agent.py. No Codex, o raciocínio de alto nível deve permanecer no loop ativo do agente, com plan para agrupamento determinístico.

Protocolo do Coordenador (Qualquer Agente Não-Worker de UI)

Para cada tarefa real de controle de UI, o coordenador deve delegar a um único worker de UI sempre que a política de tempo de execução atual permitir delegação de agente. O worker realiza capturas de tela, inspeção visual e execução de UI. O coordenador não deve tirar capturas de tela, visualizar capturas de tela, executar scripts/ui_control.py ou inspecionar imagens da tela por si mesmo, a menos que esteja depurando a implementação da skill. Isso mantém os pixels da tela, conteúdo privado da janela e raciocínio visual fora do contexto principal da conversa.

Fallback de controle direto não permitido: se o coordenador não puder gerar ou enviar mensagens para um worker de UI porque a política de tempo de execução ou disponibilidade de ferramenta realmente impede a delegação, ele deve parar antes de tocar na UI e relatar esse bloqueador. Não peça ao usuário uma frase de autorização ritualística; isso não cria ferramentas ausentes nem substitui a política de tempo de execução. Ele não deve continuar fazendo trabalho local de captura de tela/inspeção de imagem/controle de UI em seu próprio contexto.

Se você já está dentro de um contexto de worker de UI delegado, pule este protocolo e siga o Protocolo do Worker de UI abaixo. Não chame spawn_agent, send_input, wait_agent, close_agent, ferramentas de delegação do OpenSpace ou qualquer mecanismo equivalente de worker aninhado.

Leia references/subagent-workflow.md antes de delegar trabalho de UI. O coordenador deve:

• Esclarecer o objetivo internamente e definir uma tarefa de UI estreita para o subagente.
• Incluir o aplicativo/janela alvo exato, resultado desejado, limites de segurança e se ações irreversíveis são permitidas.
• Declarar explicitamente no prompt do worker: "Você é o worker de UI. Não gere ou delegue para outro agente."
• Dizer ao subagente para adquirir o bloqueio global de UI antes de tocar na UI, passar --lock-token para cada comando de scripts/ui_control.py e liberar o bloqueio antes de retornar.
• Dizer ao subagente para usar apenas scripts/ui_control.py local; não use modelos visuais remotos, extensões de navegador ou serviços externos.
• Dizer ao subagente para inspecionar o idioma da UI antes de escolher o texto de pesquisa/entrada; UI chinesa precisa de --decode-unicode-escapes, UI inglesa pode usar aliases ingleses/ASCII.
• Pedir ao subagente para retornar um relatório de texto conciso com comandos usados, estado final, caminhos de arquivo de captura de tela e qualquer incerteza não resolvida.
• Evitar solicitar capturas de tela brutas na resposta final do subagente, a menos que o usuário precise especificamente delas.

Protocolo do Worker de UI

Use esta seção apenas quando o prompt explicitamente diz que você é o worker de controle de tela, worker de UI ou worker delegado para uma tarefa de UI do Windows, ou quando você já está executando dentro de um agente gerado especificamente para controle de UI do Windows. Ser um subagente de propósito geral de uma tarefa maior não faz de você o worker de UI; nesse caso, siga o Protocolo do Coordenador quando o controle de UI ao vivo for necessário.

Regras rígidas:

• Não gere outro agente, delegue para outro agente ou use o OpenSpace para criar um worker aninhado.
• Não reexecute o Protocolo do Coordenador.
• Use apenas o scripts/ui_control.py desta skill e comandos de shell local comuns necessários para inspecionar saídas.
• Mantenha as capturas de tela em uma pasta temporária como $env:TEMP\codex-ui-subagent\.
• Inspecione as capturas de tela dentro do seu próprio contexto e retorne apenas texto mais caminhos de captura.
• Se você não puder concluir a tarefa de UI localmente, relate parcial ou falhou com o bloqueador. Não escale gerando outro agente.

Loop do worker:

1. Adquira o bloqueio global de UI com lock acquire --owner "<rótulo da tarefa>" e mantenha o token retornado privado no seu contexto de worker.
2. Passe --lock-token <token> para cada comando não-simulado de scripts/ui_control.py até a liberação.
3. Execute status --windows e tire uma captura de tela nova enquanto segura o bloqueio.
4. Inspecione as capturas de tela localmente e escolha a menor ação segura.
5. Prefira teclas de atalho e colar da área de transferência em vez de coordenadas do mouse quando confiável.
6. Use --dry-run antes de planos longos ou arriscados.
7. Execute com scripts/ui_control.py.
8. Verifique com outra captura de tela ou comando de status sem imagem.
9. Libere o bloqueio com lock release --token <token> na limpeza.
10. Retorne resultado, ações resumidas, estado final observado, caminhos de captura e incertezas não resolvidas.

Regras de Decisão

• Prefira APIs normais, comandos CLI, automação de navegador ou ferramentas específicas de aplicativo quando existirem e forem confiáveis.
• Para controle de UI ao vivo do Windows, aplique o portão de delegação obrigatório antes de qualquer captura de tela, inspeção de imagem ou chamada a scripts/ui_control.py.
• Use scripts/ui_control.py para controle rápido local do Windows: teclas de atalho, colar/digitar texto, clique do mouse, arrastar, rolar, capturas de tela, área de transferência, ativação de janela, verificação de pixels, correspondência de imagem e planos de ação.
• Tire uma captura de tela antes de agir, a menos que as coordenadas/estado alvo já sejam conhecidos do mesmo loop de interação.
• Use teclas de atalho e colar da área de transferência antes da navegação por mouse quando for mais rápido e seguro.
• Agrupe ações conhecidas com plan para velocidade, mas mantenha os loops de decisão visual passo a passo: capturar, inspecionar, agir, verificar.
• Para aplicativos localizados como WeChat, decida se a UI visível é chinesa ou inglesa antes de pesquisar. Use --decode-unicode-escapes para rótulos/mensagens chineses em contextos de worker aninhados; nunca confie que texto chinês bruto sobreviverá às camadas de prompt, CLI, PowerShell ou redirecionamento de log.

Controle Local

Esta seção é apenas para workers de UI e depuração da skill. Um coordenador não deve executar esses comandos para uma tarefa de UI ao vivo; ele deve delegar para um worker de UI primeiro ou relatar o bloqueador de delegação se a delegação não estiver disponível.

Execute a partir do diretório da skill:

python scripts\ui_control.py lock acquire --owner "wechat-file-transfer"
python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\screen.png"
python scripts\ui_control.py --lock-token <token> hotkey ctrl l
python scripts\ui_control.py --lock-token <token> type '\u6587\u4ef6\u4f20\u8f93\u52a9\u624b' --decode-unicode-escapes --method paste
python scripts\ui_control.py --lock-token <token> click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> right-click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> drag 100 100 700 450 --duration 0.5
python scripts\ui_control.py --lock-token <token> scroll -6 --x 900 --y 500
python scripts\ui_control.py --lock-token <token> hold-mouse --x 500 --y 300 --seconds 1.2
python scripts\ui_control.py lock release --token <token>

Todos os comandos imprimem JSON. Verifique ok, error, caminhos de saída, janela ativa e coordenadas antes de continuar.

Comportamento do bloqueio: comandos sem --lock-token adquirem um bloqueio transitório para aquele único comando. Um worker fazendo uma tarefa de UI visível com várias etapas deve usar lock acquire e passar --lock-token por toda a fase para que outros workers não possam intercalar ações entre seu loop de captura/ação/verificação. Opções globais como --lock-token devem aparecer antes do subcomando, por exemplo ui_control.py --lock-token <token> type ..., não depois. Use --lock-timeout <segundos> em comandos comuns para controlar quanto tempo esperar por outro worker; use lock status para inspecionar o detentor atual sem obter o bloqueio. Bloqueios expirados são tratados como obsoletos e removidos automaticamente.

No Windows, scripts/ui_control.py ativa a consciência de DPI na inicialização. Trate capturas de tela, coordenadas do mouse, leituras de pixel e retângulos de janela como o mesmo sistema de coordenadas de pixels físicos. Se status relatar um tamanho de tela que não corresponda ao tamanho da área de trabalho/janela ativa, pare e relate a incompatibilidade antes de clicar.

Para sintaxe completa da CLI, leia references/control-api.md.

Fluxo de Trabalho

1. Adquira o bloqueio global de UI:

python scripts\ui_control.py lock acquire --owner "short task label"

Use o token retornado como --lock-token <token> para cada comando até a liberação.

2. Inspecione o estado:

python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-ui.png"
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-active.png" --active
python scripts\ui_control.py --lock-token <token> snapshot --out "$env:TEMP\codex-state.png" --windows --active

3. Traga o alvo para frente:

python scripts\ui_control.py --lock-token <token> window activate "Notepad"

4. Use a primitiva mais rápida e confiável:

• Campos de texto: type --method paste, usando --decode-unicode-escapes para texto com escape chinês, depois press enter ou hotkey.
• Menus e atalhos: hotkey, press, key-hold.
• Botões e canvas: click, double-click, right-click, drag, scroll, hold-mouse.
• Alvos conhecidos de aplicativo/janela: use snapshot --active, screenshot --active, screenshot --window "<título>", find-image --active ou find-image --window "<título>" antes de captura/pesquisa em tela cheia. Use snapshot --windows quando o worker precisar de metadados de janela e uma captura de tela no mesmo passo. Alvos de janela são limitados à tela primária visível quando o Windows relata deslocamentos de borda invisíveis.
• Sequências determinísticas repetidas: escreva um arquivo de ação JSON e execute plan --file.
• Alvo visível desconhecido: o worker de UI deve capturar a tela e inspecionar, então usar coordenadas ou correspondência de imagem.

5. Verifique com outra captura de tela ou chamada de status.

No PowerShell, prefira plan --file em vez de plan --json para JSON gerado. JSON complexo passado como argumento de comando nativo pode ser requotado pelo PowerShell antes que o Python o receba.

As ações do plano podem definir apenas campos específicos da ação. Não coloque campos globais/de controle como dry-run, require-approval, no-failsafe, strict-bounds, pause-after, log-file, lock-token, lock-timeout, lock-ttl, lock-owner, plan-file, plan-json, func ou stdin dentro de ações de plano individuais; o controlador os rejeita para que sub-ações não possam ignorar o bloqueio e as configurações de segurança do worker. Para entrada de texto no plano, use um valor text ou file. Escolhas e booleanos fornecidos pelo plano são validados como argumentos diretos da CLI.