Tomada de Controle da Área de Trabalho

Visão Geral

Orquestra de forma unificada todo o fluxo de "fazer o Agente assumir a área de trabalho para concluir operações GUI": primeiro, roteamento para determinar o melhor caminho, depois garantir que as permissões de uso do computador estejam prontas e, finalmente, despachar a tarefa e verificar. O uso do computador é o caminho de último recurso, não o preferencial – é usado apenas quando a tarefa deve ser concluída exclusivamente via GUI.

Árvore de Decisão do Fluxo de Trabalho

Ao receber uma solicitação de operação do tipo área de trabalho, julgue o caminho na seguinte ordem, pare ao acertar:

1. Conector/MCP pode acessar diretamente?
   O aplicativo de destino possui um conector conectado (GitHub, Base de Conhecimento WPS, WeCom, etc.)
   → Siga pelo conector, não toque na GUI
   Exemplo: Consultar PR no GitHub → conector gh; Ler documento da biblioteca WPS → wps-knowledgebase

2. Operação puramente no navegador?
   A tarefa ocorre em uma página da web (preencher formulários, clicar em páginas da web, comparar capturas de tela)
   → Siga pela habilidade de browser-use, não mexa na GUI do sistema
   Exemplo: Fazer login em um site para alterar configurações → browser-use

3. Leitura/gravação de arquivos Office/WPS?
   O alvo é conteúdo de arquivos doc/docx/xls/xlsx/ppt/pptx
   → Siga pela família de habilidades office (workbuddy-docx / sheetagent / local-office-edit)
   Exemplo: Modificar uma tabela no Word → local-office-edit

4. Linha de comando/script acessível?
   A tarefa é essencialmente operação de arquivos, processamento de dados, configuração do sistema e existe um caminho CLI ou script
   → Use Bash/script diretamente
   Exemplo: Renomear em lote → script; Consultar informações do sistema → comando

5. Nenhum dos itens acima funciona → tomada de controle da área de trabalho por uso do computador
   A tarefa deve operar elementos de interface de algum aplicativo GUI (botões, menus, formulários não web)
   Exemplo: Alterar uma configuração que só tem entrada GUI em um software nacional

Princípio de julgamento: a cada nível descendente, confiabilidade e velocidade diminuem, e a incerteza aumenta. As operações GUI envolvem múltiplas incertezas, como localização de elementos, foco de janela, idioma da interface, sendo o último recurso.

Nota: A dependência de visibilidade do nível 5 (enumeração de janelas + captura de tela) é uma deficiência estrutural quando o Stage Manager está ativado (veja o item 2 de Pre-flight e a "Armadilha da Janela Invisível"). As ferramentas da série AX (percepção da árvore de acessibilidade) leem geometria lógica, não sendo enganadas pelo deslocamento em miniatura do Stage Manager, sendo um caminho alternativo/complementar – a reavaliação na versão 27.0.1 confirmou parcialmente (veja a descoberta 5 na subseção da armadilha), com a condição limitante: janelas recém-iniciadas, que nunca estiveram no palco, também são invisíveis para a árvore AX. A ferramenta de suporte AX incorporada nesta habilidade: tools/axctl (uso na seção "Camada de Suporte AX").

Ao rotear, se não tiver certeza se o aplicativo de destino possui um conector, primeiro consulte list_installed_plugins, não afirme com base na memória.

Pré-voo: Verificação Dupla de Permissões e Ambiente

Antes de usar o uso do computador, duas verificações devem ser concluídas, nenhuma pode ser pulada:

1. Verificação de Permissão

Chame gui_permission_status:

all_granted: true → Prossiga para a segunda verificação
Faltando permissões → Siga o fluxo em references/authorization-macos.md para orientar o usuário na autorização (macOS)
Windows → A versão atual suporta apenas macOS, informe claramente ao usuário

2. Verificação do Stage Manager (obrigatório, o Stage Manager do usuário geralmente está ativado)

Execute defaults read com.apple.WindowManager GloballyEnabled:

Retorna 1 (ativado) → Antes de despachar, primeiro open -a <nome do aplicativo> para ativar o aplicativo de destino e trazê-lo de volta ao palco atual (pode brevemente roubar o foco, avise o usuário primeiro), depois gui_list_windows para confirmar que a janela de destino está visível, e só então create_task. Se a janela ainda não estiver na lista após a ativação, vá diretamente para a sequência de diagnóstico da "Armadilha da Janela Invisível" abaixo – não tente create_task novamente, não conclua que o aplicativo está com defeito
Retorna 0 (desativado) → Siga o fluxo de despacho normal diretamente

Esta verificação prévia eleva a armadilha do Stage Manager de "diagnóstico posterior" para "desvio antecipado". O Stage Manager não é incomum entre usuários do macOS 15+, e para aqueles que o têm ativado, esta rota é o caminho padrão para cada despacho, não uma exceção. O mecanismo de ativação-visualização foi revalidado no macOS 27.0.1, mas existem dois novos detalhes: "a primeira ativação não gruda" e "a visualização se retrai", veja a subseção de reavaliação da 'Armadilha da Janela Invisível'.

Despacho de Tarefas

Após as permissões estarem prontas, siga o fluxo de trabalho padrão da habilidade de uso do computador incorporada:

gui_list_windows para localizar a janela do aplicativo de destino; se não for encontrada, open_app para iniciar
Verifique a visibilidade após o início: Após open_app, deve-se executar gui_list_windows novamente para confirmar que a janela realmente aparece na lista. Se não aparecer, não tire conclusões precipitadas de "aplicativo quebrado", primeiro veja a "Armadilha da Janela Invisível" abaixo
Quando o Stage Manager está ativado (confirmado na verificação prévia): Primeiro open -a para ativar o aplicativo de destino, depois despache – veja o item 2 de Pre-flight, não repita o julgamento aqui
create_task(window_id, task) para despachar a tarefa

Armadilha da Janela Invisível (cenário do Stage Manager)

Escopo da conclusão: Estabelecida pela primeira vez em experimentos de controle no macOS 15; já reavaliada no macOS 27.0.1 (sonda de canal duplo Swift + teste binário nativo da API AX, o mecanismo é confirmado e novos detalhes são descobertos, veja abaixo). A conclusão da camada AX foi confirmada por medição real após autorização na versão 27.0.1 (caminho AXError=0), não mais dependendo de inferência.

Condição de gatilho: Stage Manager ativado, não relacionado ao início em segundo plano. Quando ativado, as janelas de aplicativos que não estão no palco atual existem realmente, mas não podem ser capturadas normalmente por enumeração de janelas e captura de tela – o processo está vivo, a janela foi criada (por exemplo, Cmd+N funcionou), mas gui_list_windows não vê a janela normal. Uma vez que o aplicativo é ativado (a janela retorna ao palco atual), a janela aparece imediatamente.

Novas descobertas na reavaliação do macOS 27.0.1:

Mecanismo de barra de miniaturas visualizado: As janelas de aplicativos que saem do palco são reduzidas a miniaturas laterais (medido: a janela principal do Calculator foi reduzida a 39×100pt colada à borda esquerda, além disso, 4 janelas de espaço de palco com largura total de 34pt são derivadas). Se gui_list_windows filtrar por "janelas de tamanho normal", essas miniaturas podem ser perdidas ou mal interpretadas
Ativação e visualização ainda funcionam, mas existe o fenômeno de 'a primeira ativação não gruda': Na medição real, após a primeira open -a, a janela principal ainda estava em estado de miniatura (quando o primeiro plano estava ocupado por outro aplicativo), apenas a segunda open -a expandiu para o tamanho completo (405, 517, 230×408). Tratamento: Após a ativação, execute imediatamente gui_list_windows para verificar; se não aparecer, execute open -a novamente (no máximo 2 vezes); se ainda não aparecer, entre na sequência de diagnóstico
Possibilidade de retração após visualização: Quando o primeiro plano é retomado por outro aplicativo, dentro de cerca de 5 segundos, a janela pode retrair para o estado de miniatura (reproduzido na medição real). Inferência: A verificação por captura de tela tem uma janela de tempo – quando o primeiro plano é tomado durante a execução de create_task, a tarefa em si não é afetada, mas se gui_screenshot for capturada após a retração, a janela de destino não estará na imagem. Tratamento: Se houve uma troca de primeiro plano antes da captura de tela, primeiro open -a e depois capture
O canal CGWindowList não é afetado: optionOnScreenOnly e a lista completa podem enumerar a janela (apenas o título requer permissão de gravação de tela) – mas observe que a lista onScreenOnly contém janelas em miniatura, não a janela principal. Ferramentas que dependem de coordenadas de janela para cliques podem clicar no lugar errado (clicando na miniatura em vez do botão real)
A leitura da árvore AX lê geometria lógica, imune ao deslocamento em miniatura, mas tem pontos cegos (medição real após autorização na versão 27.0.1): O frame da janela retornado pelo AX são coordenadas lógicas de tamanho completo (por exemplo, (405,517,230×408)), enquanto o estado de renderização do CGWindowList ao mesmo tempo é uma miniatura de 39×100pt – o deslocamento geométrico do Stage Manager não engana o AX. Mas ponto cego: janelas recém-iniciadas, que nunca estiveram no palco, o AX tree reporta windows=0; após estar no palco, quando iniciado em segundo plano, o AX continua visível. Inferência: A percepção AX não é incondicionalmente imune; aplicativos iniciados pela primeira vez ainda precisam ser ativados e colocados no palco. Além disso: enviar eventos de mouse sintéticos para a tela com base nas coordenadas lógicas do AX pode clicar no aplicativo errado (posição lógica ≠ posição de renderização atual) – ferramentas da série AX para ações devem usar APIs de ações de acessibilidade, como AXPress (por exemplo, axctl), não cliques por coordenadas

Ordem de julgamento (quando o aplicativo de destino não está na lista de janelas):

Primeiro verifique se o processo está vivo (pgrep): vivo → provavelmente é um problema de visibilidade, não uma falha do aplicativo
Confirme se o usuário tem o Stage Manager ativado (macOS 15+, defaults read com.apple.WindowManager GloballyEnabled, 1=ativado): ativado → vá para o passo 3; não ativado → pode ser que a janela tenha desaparecido repentinamente ou outra razão
Ative o aplicativo para torná-lo visível: open -a <nome do aplicativo> (pode brevemente roubar o foco, avise o usuário primeiro); na versão 27, a primeira ativação pode não grudar, após a ativação verifique imediatamente, se não aparecer, ative novamente (limite de 2 vezes)
Reexecute gui_list_windows, geralmente você pode obter o window_id

Sinal adicional: Quando o Stage Manager está ativado, open_app normalmente não obtém o window_id (retorna hint para uma segunda enumeração); quando desativado, retorna o window_id normalmente.

Inferências importantes:

Reportar nenhuma janela visível ≠ janela não existe, muito menos que a operação anterior falhou – a tarefa "falhou" anterior pode realmente ter sido bem-sucedida (a janela foi criada, apenas não está visível)
Janelas do tipo diálogo (como diálogo "Abrir" arquivo) após serem fechadas pela própria tarefa, seu window_id se torna inválido e capturas de tela subsequentes gerarão erro – isso é normal, reenumere para obter um novo ID
Alguns aplicativos (como Editor de Texto) quando iniciados sem documento não têm janela, isso é comportamento normal, é necessário abrir com arquivo

Descrição da Tarefa em Três Partes (Chave para o Sucesso ou Fracasso)

O parâmetro task deve conter três partes:

Objetivo: Descreva passo a passo o que deve ser concluído
Limites: Especifique claramente o que não pode ser tocado, como "Não clique em nenhum item na lista de histórico"
Tratamento de falha: Se uma operação não responder, registre com precisão o que aconteceu e prossiga para o próximo passo, não tente novamente ou mude de método

A regra de tratamento de falha não pode ser omitida – sem ela, uma única falha pode acionar repetidas tentativas, esgotando a cota de passos de toda a rodada.

A descrição não deve incluir coordenadas de pixel ou posições numéricas, use texto visível na interface e nomes de controles para se referir aos alvos.

Exemplo

Solicitação do usuário: "Me ajude a abrir o aplicativo XX e mudar o formato de exportação para CSV"

Objetivo: 1. Encontre e clique na entrada "Configurações" ou "Preferences" na barra de menus ou barra de ferramentas
2. No painel de configurações, encontre a opção "Formato de Exportação" ou "Export Format"
3. Altere seu valor para CSV
4. Salve as configurações e feche o painel
Limites: Não modifique nenhuma outra configuração; Não clique no botão "Redefinir"
Tratamento de falha: Se não encontrar os controles acima, registre os nomes dos controles realmente vistos e termine a tarefa, não clique especulativamente

Camada de Suporte AX (axctl)

Quando o uso do computador incorporado não está disponível (não ativado, ferramentas gui_* ausentes, tarefa muito pequena para valer a pena despachar) ou operações de elementos em nível semântico são necessárias, use a ferramenta de suporte AX incorporada nesta habilidade tools/axctl. Implementação pura da API de Acessibilidade, não toca no mouse, não rouba foco, não está sujeita às restrições de sandbox do AppleEvents (o sandbox do WorkBuddy proíbe o envio de eventos de controle ao System Events, a rota osascript foi descontinuada, não tente mais).

Localização e instalação: Binário tools/axctl, código fonte tools/axctl.swift (arquivo único Swift), ambos distribuídos com a habilidade. Antes do primeiro uso, execute sh tools/install.sh: se detectar swiftc, compila no local (recomendado, o código fonte é auditável e adaptado à arquitetura da máquina), caso contrário, usa o binário pré-compilado incluído no pacote (apenas Apple Silicon). Após modificar o código fonte, execute swiftc -O -o axctl axctl.swift no diretório tools para recompilar.

Pré-condição: O host deve ter a permissão TCC de "Acessibilidade" (em Configurações do Sistema → Privacidade e Segurança → Acessibilidade, marque o host e reinicie o host para que a permissão faça efeito; use o retorno AXError=0 da chamada AX como indicador de prontidão).

Subcomandos

axctl list <bundle-id|pid>        Lista janelas: título + frame geométrico lógico
axctl tree <target> [depth]       Lê árvore UI: função/título/descrição/valor/frame (padrão depth=2)
axctl actions <target> <título>   Lista ações disponíveis para elementos correspondentes
axctl press <target> <título>     Pressiona AXPress (clique semântico, nível de elemento, sem coordenadas)
axctl activate <target>           Ativa aplicativo (NSRunningApplication.activate)

<target> suporta bundle id (recomendado, por exemplo, com.apple.calculator), PID numérico ou nome de aplicativo localizado (correspondência em minúsculas – em sistemas em chinês é "计算器", não "Calculator"; correspondência de nomes é propensa a erros, prefira bundle id).

Regras de Uso

Localização de Elementos: Primeiro tree ou, com base no título do botão conhecido, diretamente actions para confirmar a existência de AXPress, depois press. press só funciona em elementos com ação AXPress; itens de menu são AXPick, julgue por tipo
Verificação de Ação: Após press retornar PRESSED, use tree para ler o novo valor do elemento de destino ou área de exibição associada como evidência (referência da medição real da calculadora: após press "3", o valor de StaticText muda para 3) – semelhante à verificação por captura de tela do uso do computador, auto-relato textual não conta
Cenário do Stage Manager: A árvore AX lê geometria lógica, janelas em miniatura podem ser lidas e operadas (medido); mas janelas recém-iniciadas que nunca estiveram no palco têm árvore AX vazia – primeiro axctl activate ou open -a para colocar no palco, depois opere
Limites de aplicabilidade: axctl é adequado para leitura/gravação em nível de elemento (botões/menus/campos de texto); para cliques em barra de menus entre aplicativos, simulação de teclado/mouse em nível de sistema ou fluxos GUI complexos de vários passos, ainda use o despacho de uso do computador incorporado
Limitações conhecidas: Sem monitoramento de mudanças na UI (capacidade observe_changes do axmcp, avalie após a adaptação upstream ao Swift 6.4); operações elemento único por vez, sem transações em lote

Registro de Medição Real (macOS 27.0.1, Stage Manager ativado)

axctl press com.apple.calculator "3" → PRESSED path=w/0/0/0/1/0/15 → tree leu de volta o valor AXStaticText como 3 – leitura de árvore, localização, clique semântico, verificação de efeito, todos os quatro anéis funcionaram.

Verificação de Resultados

O auto-relato textual do agente GUI não é suficiente como evidência de conclusão – o estado antigo da interface residual pode ser erroneamente interpretado como sucesso. Deve-se:

Após a tarefa retornar done=true, chame gui_screenshot(window_id) para obter a captura de tela final
Use o conteúdo da captura de tela para determinar se o objetivo foi alcançado
Ao relatar ao usuário, indique que a conclusão é baseada na captura de tela

Entre rodadas, por padrão, não faça captura de tela (o valor de retorno de continue_task já contém o histórico de execução); apenas tire uma captura de tela adicional se o agente não mudar seu reasoning/action_desc por várias rodadas consecutivas para determinar se está travado.

Referência Rápida de Solução de Problemas

Sintoma	Tratamento
`permission_denied`	Veja references/authorization-macos.md
Várias rodadas consecutivas travadas no mesmo passo	`continue_task` com parâmetro `hint` fornecendo texto visível preciso do controle
Interface sem alterações, mas relatando sucesso	Dependa de `gui_screenshot`; confirme que o window_id está correto
`conflict`	Esta janela já tem uma tarefa, primeiro `delete_task`
`window_not_found`	Janela fechada ou ID expirado, reexecute `gui_list_windows`
`nenhuma janela visível` (quando o processo está vivo)	Ativação do Stage Manager torna a janela não capturável: `open -a` para ativar → reenumere imediatamente; se não aparecer, ative novamente (na versão 27, a primeira ativação pode não grudar, limite de 2 vezes), veja "Armadilha da Janela Invisível" (confirmado experimentalmente tanto no 15 quanto no 27.0.1)
A janela capturada na captura de tela está anormalmente pequena/grudada na borda da tela	A janela de destino está em estado de miniatura do Stage Manager (descoberta na reavaliação do 27): primeiro `open -a` para ativar e restaurar o tamanho completo, depois capture, veja os itens 1 e 3 da subseção de reavaliação do 27 da "Armadilha da Janela Invisível"
Status como `call_user`	Requer intervenção manual, transmita `reasoning` ao usuário, não chame `continue_task`

Suporte de Plataforma

macOS: Suporte completo. O fluxo de autorização está em references/authorization-macos.md
Windows: Não verificado por enquanto, a versão atual não promete suporte. Ao encontrar um ambiente Windows, informe honestamente ao usuário sobre essa limitação, não tente aplicar o modelo de permissão do macOS

Recursos

references/authorization-macos.md — Fluxo completo de autorização no macOS, incluindo registros de problemas reais (não funcionamento após seleção, pop-up Quit & Reopen, etc.)
tools/axctl — Ferramenta de suporte AX (código fonte tools/axctl.swift no mesmo diretório; antes do primeiro uso, execute sh tools/install.sh), uso na seção "Camada de Suporte AX"

GreenWich-art/agent-skills

O que é agent-skills?

Perguntar na sua IA favorita

Documentação