# Cenários manuais de extensões Chrome {/* #manual-chrome-extension-scenarios */}

A gravação manual executa como trabalho Admin: **Desktop → Web Extension**. O ambiente interno é `WebExtension`; metadados e MCP público usam `web-extension`. O agente baixa a extensão selecionada da Chrome Web Store e abre perfil Chromium descartável com ela e a extensão Reconstruct. O operador navega; telas e transições observadas são salvas como [`reconstruct.scene.v1`](/docs/pt/data-format).

## Criar e executar um trabalho {/* #create-and-run-a-job */}

1. Em Admin → Jobs → Create, selecione **Desktop → Web Extension**. Desmarque Web se quiser só a extensão. Ambientes mobile continuam Web, iOS e Android.
2. Em Environment Settings → Web Extension, cole o link da Chrome Web Store. Diretórios locais e perfis pessoais não são entradas.
3. Enfileire o trabalho. Um Capture Agent habilitado e atribuído a **Desktop / Web Extension** o assume. Workers Web e Web Extension não assumem trabalhos um do outro.
4. O agente baixa CRX3 assinado pelo serviço Google e verifica ID e assinatura do editor antes de extrair no diretório privado. O pacote mantém ID de loja quando carregado sem empacotar. Metadados incluem `browserExtension` com ID verificado, nome localizado, versão e SHA-256; o nome do catálogo vem do pacote. Caminhos, contagem e tamanho expandido são verificados antes do uso.
5. Chromium abre a introdução própria da extensão; caso contrário usa opções ou popup declarados. Extensão sem entrada UI falha.
6. Abra **Reconstruct Agent Browser Bridge** no menu de extensões. O popup mostra ID ativo e telas salvas. Em cada tela, use **Capture screen** (Capturar tela). Use ali **Pause** (Pausar), **Resume** (Retomar) e **Finish recording** (Concluir gravação).

Não há CLI de gravação separado nem MCP adicional para iniciar. Controles estão vinculados ao trabalho e token privado local; não aceitam valores, rótulos arbitrários ou origens. Admins podem assistir/controlar em Admin → Jobs → job → **Live browser**; entrada só é aceita enquanto aguarda operador. Outra extensão/trabalho é rejeitado. Se abrir outra aba, ative antes de capturar; a identidade é verificada na troca. Senhas, criação de carteira, acordos e cadastro continuam manuais.

## Trabalhos de login e exploração automática {/* #sign-in-jobs-and-automatic-exploration */}

Extensões com introdução, como criar carteira MetaMask, podem gravar semiautomaticamente. Em Environment Settings → Web Extension, defina **Sign-in** como **Operator registers** (Operador se cadastra) ou **Operator signs in** (Operador entra).

1. O trabalho espera o operador. Conclua a introdução em Admin → Jobs → job → **Live browser** ou no navegador do trabalho. Salve com **Capture screen**; telas de senha/frase de recuperação nunca são salvas.
2. Selecione **Finish sign-in** (Concluir login, console), **Continue** (Continuar, Admin) ou **Finish sign-in and explore** (Concluir login e explorar, popup).
3. Depois, Reconstruct visita popup, opções, painel lateral e rotas dos controles de navegação, salvando uma tela por rota. Nunca clica em controles que possam enviar, assinar, confirmar, revelar, exportar, bloquear, excluir ou criar algo.
4. Se a extensão bloquear, aguarda como **Signed out** até o operador desbloquear e escolher **Finish sign-in** novamente. Ao acabar rotas ou atingir limite de páginas, conclui e envia para revisão.

Web tem o mesmo **Sign-in**: telas de login viram etapas, o rastreio pula sair e pausa ao terminar a sessão. CAPTCHA, SMS e aceite sempre ficam com o operador. Veja `backend/docs/operator-sign-in.md`.

## Configuração do agente {/* #agent-setup */}

Compile o adaptador com `yarn nx run chrome:build` em `backend/agent-browser-extensions`. O host exige Node.js 24+, Python 3 e Chromium com extensões. Configure o Capture Agent existente por ajustes locais ignorados ou ambiente:

```json
{
  "Agent": {
    "Id": "extension-worker",
    "ApiUrl": "https://internal-admin-api.example",
    "ChromiumPath": "/Applications/Chromium.app/Contents/MacOS/Chromium",
    "ExtensionDir": "/checkout/backend/agent-browser-extensions/chrome"
  },
  "WebExtension": {
    "RecorderDirectory": "/checkout/backend/tools/manual-recorder",
    "NodePath": "node",
    "PythonPath": "python3"
  }
}
```

Forneça `ApiTokens:Agent` por configuração secreta. O listener Web Kestrel existente deve ser loopback. Inicie Capture Agent com `extension serve` e atribua a **Desktop / Web Extension** no Admin. Cada modo possui listener/bloqueio; não inicie dois workers no endpoint. Remotos exigem host isolado gerenciado e declaração explícita `WebExtension:ManagedBrowserIsolated`, pois extensões executam sua rede/código de fundo. O flag não cria isolamento. `Agent:AllowHttpApi` explícito existente aplica à API loopback de desenvolvimento.

O worker gerencia aquisição, heartbeat, cancelamento e reenvios. O filho Node usa pipes privados, sem TCP de depuração. Ao terminar, fecha navegador e apaga perfil temporário. Use carteira de teste vazia: cenário não preserva credenciais nem carteira utilizável.

## Segredos e revisão de imagens {/* #secrets-and-image-review */}

Pause antes de senhas, recuperação, chaves ou códigos. Retome após sair da tela sensível. Telas de texto protegido são bloqueadas com segurança e criam lacuna. Editáveis/descendentes são mascarados antes de imagens; valores não entram na Scene. Verificações antes/depois rejeitam captura se estado protegido, máscara, navegação ou conteúdo mudarem durante ela.

Canvas e pixels opacos ficam visíveis na **mídia privada de revisão**. DOM não prova ausência de segredos. Inspeção/máscara são síncronas em uma avaliação de mundo isolado; JavaScript continua habilitado no screenshot para renderizar canvas.

**Finish recording** empacota e envia automaticamente como não publicado. Cada checkpoint possui página, Scene e imagem; o índice referencia sem copiar texto. No Admin, revise cada imagem em **Hide personal data**, desfoque regiões ou exclua mídia insegura e publique após revisão. Ocultação também limpa texto Scene, nomes acessíveis, valores repetidos e referências cobertos. Originais separados exigem revisão própria. Controles não publicam nem retornam imagens brutas.

## Reconstrução por MCP {/* #reconstruction-through-mcp */}

Após revisar/publicar, agentes descobrem a versão no catálogo normal Capture MCP. Use `get_scenario_scene` para quadros, perfis e transições montados dos dados atuais das páginas, incluindo ocultações Admin. Imagens aprovadas usam ferramentas publicadas normais. Verifique cada tela/perfil exigido; sucesso das ferramentas não prova fidelidade visual.

## Evidências e limites {/* #evidence-and-limits */}

Checkpoints são observações estáticas. Capture após navegação, menus, modais, outros conteúdos revelados e em cada viewport necessário. Observações adjacentes medem mudança/sem mudança; não provam clique automático. Pausas/bloqueios criam lacunas explícitas. O modo não captura cada clique silenciosamente, reproduz cadastro, captura permissões nativas do SO ou infere animação de imagens. Segredos permanecem manuais e ausentes da publicação. Limite de páginas restringe checkpoints (seleção automática padrão 200); Scene tem 100.000 nós/trabalho. Limites de tempo/elementos também valem.

## Disponibilidade de solicitações {/* #request-availability */}

Em **Admin → Requests → Job defaults → Request submissions**, configure pares tipo/ambiente. Padrões: Desktop/Web, Desktop/Web Extension, Mobile/Web. **Allow new requests** fecha/reabre novos envios; salvar mantém seleções quando fechado. Existentes e publicados ficam disponíveis. A mesma política persistida vale para API/MCP autenticado, inclusive formulários desatualizados. Fechado, opções não retorna plataformas. Seletores de catálogo só exibem ambientes capturados do produto; disponibilidade de solicitação não oculta evidência publicada.