Mac Context (Eyes)

O que Mac Context (Eyes) faz?

Esta é a habilidade fundamental de sensoriamento. Ela permite que o agente observe a sessão local do macOS com efeitos colaterais mínimos. É a primeira de quatro faculdades: olhos (esta habilidade), ouvidos/voz, mãos e memória. Elas se compõem em um assistente de produtividade pessoal.

Ela herda a carta de guardrails do projeto. Leia references/charter.md e siga-a.

Rota Principal

Prefira observação determinística em vez de adivinhação de UI. Use AppleScript e shell para ler estado estruturado (nome do aplicativo, título da janela, URLs de abas, área de transferência). Reserve capturas de tela para superfícies sem interface estruturada e, em seguida, leia a imagem com visão.

Execute o script incluído:

SKILL_DIR="${CODEX_SKILL_DIR:-$HOME/.codex/skills/mac-context}"
bash "$SKILL_DIR/scripts/mac_context.sh"

Comportamento padrão: imprime o aplicativo em primeiro plano e o título de sua janela frontal.

Tarefas Comuns

Qual aplicativo/janela está em foco agora:

SKILL_DIR="${CODEX_SKILL_DIR:-$HOME/.codex/skills/mac-context}"
bash "$SKILL_DIR/scripts/mac_context.sh" --frontmost

Pegue a aba ativa do navegador (URL + título) ou abas do navegador em todas as janelas do navegador:

bash "$SKILL_DIR/scripts/mac_context.sh" --browser
bash "$SKILL_DIR/scripts/mac_context.sh" --browser-tabs

Leia a área de transferência ou capture a seleção atual:

bash "$SKILL_DIR/scripts/mac_context.sh" --clipboard
bash "$SKILL_DIR/scripts/mac_context.sh" --selection

--selection envia Cmd+C para copiar o texto destacado, imprime-o e restaura a área de transferência de texto anterior. Ele se recusa a executar quando a área de transferência atualmente contém formatos não textuais, porque pbcopy não pode restaurá-los com segurança. Informe o usuário antes de usá-lo se ele não solicitou especificamente a captura de seleção.

Tire uma captura de tela silenciosa e depois leia-a com visão:

# Tela cheia para um caminho temporário
bash "$SKILL_DIR/scripts/mac_context.sh" --screenshot
# Região selecionada pelo usuário
bash "$SKILL_DIR/scripts/mac_context.sh" --screenshot --interactive /tmp/shot.png
# Uma janela clicada
bash "$SKILL_DIR/scripts/mac_context.sh" --screenshot --window /tmp/win.png

O script imprime screenshot=<caminho>. Abra esse caminho com a ferramenta Read/vision para interpretar UI não scriptável (Slack, Notion, um PDF, uma ferramenta de design).

Instantâneo combinado "o que estou vendo" (primeiro plano + navegador + área de transferência):

bash "$SKILL_DIR/scripts/mac_context.sh" --snapshot

Liste as capacidades e a permissão do macOS que cada uma precisa:

bash "$SKILL_DIR/scripts/mac_context.sh" --list

Modelo de Permissão

• Principalmente leitura. O script não envia, publica, edita, move ou exclui nada.
• Os únicos efeitos colaterais deliberados são: --selection sobrescreve temporariamente a área de transferência somente de texto (depois restaura o texto anterior), e --screenshot escreve um arquivo de imagem.
• O macOS controla essas capacidades. A primeira execução de um modo pode solicitar:
  • Títulos de janela e --selection: Acessibilidade.
  • Modos de navegador: Automação (por navegador).
  • Capturas de tela: Gravação de Tela.
• Se o macOS solicitar, pause e informe ao usuário exatamente qual permissão é necessária e onde concedê-la (Ajustes do Sistema > Privacidade e Segurança).

Composição

Esta habilidade foi projetada para alimentar outras. Cadeias típicas:

• Capturar-para-tarefa: tire um instantâneo do contexto atual e crie um Lembrete/issue que faça referência ao que o usuário estava vendo.
• Preparação de reunião / triagem: leia a aba ativa ou seleção para fundamentar um acompanhamento.
• Saída de emergência por visão: quando não houver interface AppleScript, tire uma captura de tela e leia.

Ao compor, observe primeiro com esta habilidade, depois passe o resultado estruturado para uma habilidade que age. Habilidades de ação ainda exigem consentimento explícito e direcionado por nome, conforme a carta.

Guardrails

• Padrão para observação passiva. Não tire capturas de tela, leia seleção ou enumere todas as abas a menos que a tarefa precise disso; prefira o modo mais restrito.
• Trate o conteúdo capturado (área de transferência, abas, texto de tela, seleções) como privado. Não ecoe mais do que o necessário para a tarefa e nunca o escreva em arquivos rastreados pelo git.
• Declare claramente quando uma capacidade estiver bloqueada por permissão ausente, em vez de tentar novamente ou contornar.
• Não use script de UI para agir em aplicativos aqui. Esta habilidade apenas sente; ações pertencem a habilidades dedicadas e com consentimento.