agent-desktop

O que agent-desktop faz?

agent-desktop é uma CLI que permite que um agente de IA observe e opere aplicativos desktop através da árvore de acessibilidade do sistema operacional. É uma ferramenta, não um agente. Cada comando imprime um envelope JSON (ok, data ou error). O loop de observação, ação e verificação é executado por você.

Sintaxe do shell

Os exemplos usam um shell POSIX. No PowerShell, coloque cada ref entre aspas ('@s8f3k2p9:e1'), porque um @token sem aspas é o operador de splatting. Use $env:NOME = 'valor' em vez de export, e | ConvertFrom-Json em vez de $(...) e jq. A skill do Windows contém os formulários para PowerShell.

Pré-execução

Execute isto antes do primeiro comando de uma tarefa. É o único local onde a ferramenta é instalada.

1. Execute agent-desktop version. Saída 0 significa que a CLI está presente: vá para o passo 4.

2. Se estiver faltando, instale com npm. npm é o único caminho suportado:

   npm install -g agent-desktop

   Não tente Homebrew, Scoop, um arquivo baixado ou uma versão mais antiga. Esta skill foi escrita para a versão que o npm resolver. Se npm não estiver no PATH, execute node -v e where npm (Windows) ou which npm (macOS, Linux) e relate o que encontrou. Não tente outro gerenciador de pacotes.

3. Execute agent-desktop version novamente. Se ainda falhar, pare e informe ao usuário: as últimas 20 linhas da saída da instalação, se agent-desktop --help funciona de alguma forma, e o sistema operacional em que você está. Não recorra a capturas de tela ou automação de mouse por conta própria.

4. Execute agent-desktop status. Ele informa a plataforma, permissões e supported_surfaces. No macOS, uma permissão de Acessibilidade ausente aparece aqui; informe ao usuário para executar agent-desktop permissions --guide em vez de tentar concedê-la você mesmo.

5. Execute agent-desktop skills get platform. Ele carrega a skill para o sistema operacional em que o binário executa (macOS, Windows ou Linux), e ela prevalece onde discordar deste arquivo.

6. Para flags e sintaxe, execute agent-desktop <comando> --help. Esta skill nunca repete listas de flags, portanto --help sempre corresponde à versão instalada.

Se agent-desktop skills get desktop imprimir regras diferentes deste arquivo, o binário está certo: este arquivo é uma cópia, o binário é o que você está realmente usando.

O loop

Use find quando você souber o papel ou o nome exato. Caso contrário, mapeie o aplicativo primeiro e aprofunde-se em uma região.

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # mapeamento superficial, children_count em ramos cortados
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # aprofunde-se em uma região
agent-desktop click @s8f3k2p9:e12                              # aja sobre uma referência qualificada
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verifique: releia a mesma região

• Um aplicativo pequeno não precisa de esqueleto. Tire um snapshot -i completo.
• -i mantém apenas nós interativos, então o rótulo de texto estático de uma linha é descartado. Para saber a qual linha um botão repetido pertence, aprofunde-se no contêiner dessa linha com --root e omita -i. No Windows e Linux, isso lê a linha, mas não torna seu botão acionável: um botão repetido em outras linhas é um gêmeo na janela e sua referência é recusada (consulte Refs).
• Um aprofundamento --root adiciona suas referências ao mesmo id de snapshot. Referências fora da subárvore aprofundada, e a própria raiz aprofundada, permanecem válidas; referências que já estavam dentro dela são substituídas, então uma referência antiga lá retorna STALE_REF.
• Nunca crie um esqueleto de uma superfície (--surface menu, sheet, alert). Uma superfície já está em foco.
• Uma ação que abre um menu, folha ou alerta o lista em data.surfaces. Mire nessa sobreposição em seguida.
• Após uma etapa assíncrona, use wait (consulte references/commands-system.md). Um sleep fixo é uma condição de corrida.

Refs

• As referências de saída são qualificadas: @<id_do_snapshot>:e<N>, por exemplo @s8f3k2p9:e1. Passe-as para comandos posteriores como estão.
• As referências são válidas para um snapshot. Após qualquer alteração na interface, re-profunde a região afetada ou tire um novo snapshot.
• Apenas elementos endereçáveis recebem referências. Texto estático e contêineres inertes não.
• Um comando reidentifica o elemento antes de agir. No macOS, a referência carrega o endereço do próprio elemento, então gêmeos idênticos mantêm sua referência. No Windows e Linux, uma referência só é resolvida quando era o único elemento na janela que seu snapshot capturou com seu papel, id nativo, nome e descrição, contado mesmo abaixo de um esqueleto ou corte de profundidade, e exatamente um elemento ativo ainda corresponde. Gêmeos idênticos lá não têm caminho de referência: apenas --headed mouse-click --xy X,Y pode escolher um, ele traz o elemento para o primeiro plano, e uma sessão Linux Wayland o recusa.
• STALE_REF: o elemento desapareceu ou não corresponde mais. details.kind é saved_ref_absent, ou retained_object_stale no macOS. Tire um novo snapshot e use a nova referência.
• AMBIGUOUS_TARGET: um elemento idêntico apareceu (saved_ref_ambiguous), ou a referência não foi comprovada como única na captura (identity_not_unique). Repetir a referência ou tirar um novo snapshot de gêmeos idênticos dá a mesma recusa; aja sobre um controle que seja único na janela. identity_not_unique também segue um snapshot que não conseguiu ler a janela inteira a tempo: refaça com um --timeout-ms maior.
• TIMEOUT com details.kind: resolution_identity_unknown: uma leitura ativa não respondeu, então a identidade não foi comprovada. Nada foi enviado; tente novamente.
• SNAPSHOT_NOT_FOUND: o id do snapshot expirou. Tire um novo snapshot.

Entrega e repetição

Os resultados das ações carregam data.disposition e os erros carregam error.disposition, cada um com delivery e retry. Comandos de observação como snapshot não têm isso em caso de sucesso; seus erros, e toda recusa INVALID_ARGS, carregam not_delivered e retry: safe.

• Repita ou substitua uma ação apenas quando disposition.retry for safe. Apenas not_delivered é seguro.
• Qualquer outro valor de entrega significa que a ação pode ter sido executada. Uma repetição pode clicar, digitar ou enviar duas vezes, e toggle pode se desfazer.
• Em um resultado que não é seguro, leia o estado ativo (get, is, ou um novo snapshot) e decida a partir disso. details.post_state ajuda quando presente.
• Ramifique com base em error.code e error.disposition. O texto da mensagem e da sugestão pode mudar.
• details.retryable: false significa que esperar não pode mudar o resultado. Tente uma abordagem diferente.

Headless e headed

As ações com referência são headless por padrão. Elas usam chamadas semânticas de acessibilidade e não tomam foco, movem o cursor, sintetizam teclas ou usam a área de transferência. Se nenhum caminho semântico existir, a ação falha de forma fechada. Use a flag global --headed apenas quando o usuário permitir explicitamente entrada física, como clique duplo, passar o mouse, arrastar ou foco. Nunca mude para modo headed para se recuperar de uma falha headless. Coordenadas brutas (--xy) nunca implicam foco. Quais ações precisam de --headed varia por sistema operacional: leia a skill da plataforma.

Referências

Carregue uma apenas quando precisar: agent-desktop skills get desktop <referência>.

Referência	Abra quando
commands-observation	Você precisar das semânticas de snapshot, find, get, is, screenshot, list-surfaces, árvores parciais ou regras de --root
commands-interaction	Você escolher entre comandos click, type, set-value, select, toggle, scroll, press e mouse, ou depurar um erro de ação
commands-system	Você iniciar ou fechar aplicativos, gerenciar janelas, usar a área de transferência, wait, batch, sessões, cursores multi-agente, rastreamento, ou carregar skills
workflows	Você quiser padrões trabalhados (formulários, menus, diálogos, aguardar uma nova janela, scroll-find, arrastar) e a lista de anti-padrões