Dev Browser Perfil Local

O que Dev Browser Perfil Local faz?

Use esta skill quando a automação do navegador deve se conectar a um perfil de navegador local de longa duração em vez de iniciar um estado de navegador novo.

Este projeto foi adaptado de dev-browser, mas a skill atual é executada de forma independente e não requer dev-browser.

Regras Principais

• Use os scripts Playwright via CDP empacotados em vez de dev-browser.
• Considere que um perfil de navegador persistente é a fonte da verdade para o estado de login.
• Prefira uma porta fixa de depuração remota. Padrão é 9222, a menos que o usuário especifique o contrário.
• Mantenha os caminhos de perfil relativos ao usuário. Nunca codifique nomes de usuário específicos da máquina.
• Abra uma nova aba por padrão em vez de substituir a aba atual do usuário, a menos que solicitado.

Fluxo de Configuração

1. Instalar dependências

Execute uma vez dentro do diretório da skill:

npm install

Isso instala apenas playwright-core. Não baixa um navegador gerenciado separado.

2. Iniciar Chrome ou Chromium com um perfil persistente

Use um diretório de dados de usuário fixo sob o diretório home do usuário atual:

• Windows: Join-Path $env:USERPROFILE 'chrome-dev-browser-profile'
• macOS/Linux: ~/chrome-dev-browser-profile

Use o script de inicialização empacotado para iniciar em várias plataformas:

python scripts/start_chrome_debug.py

Opções úteis:

python scripts/start_chrome_debug.py --port 9222
python scripts/start_chrome_debug.py --profile-dir "C:\Users\nome\chrome-dev-browser-profile"
python scripts/start_chrome_debug.py --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

3. Usar as ferramentas de navegador independentes

Abrir uma URL em uma nova aba:

node scripts/browser_tools.mjs open --url "http://localhost:9800/h5-bzzx/"

Listar abas atuais:

node scripts/browser_tools.mjs list

Tirar uma captura de tela:

node scripts/browser_tools.mjs screenshot --url "http://localhost:9800/h5-bzzx/" --output "./page.png"

4. Executar tarefas de automação personalizadas

Use o executor de tarefas genérico para fluxos mais complexos do que simples abertura/listagem/captura:

node scripts/run_task.mjs --task ./my-task.mjs --url "http://localhost:9800/h5-bzzx/" --task-arg mode=debug

Módulos de tarefa devem exportar uma função assíncrona padrão ou uma função run nomeada.

Exemplo:

export default async function ({ page, helpers, taskArgs }) {
  await page.waitForLoadState("domcontentloaded");
  return {
    title: await page.title(),
    url: page.url(),
    taskArgs
  };
}

Tratamento de Rotas com Hash

Não confie em fluxos de abertura direta do DevTools como json/new?... para URLs com hash. A parte #... pode ser removida.

Para rotas com hash, os scripts empacotados já usam uma estratégia de navegação em duas etapas:

1. Abra a URL base primeiro.
2. Em seguida, defina window.location.href dentro da página.

Exemplo:

node scripts/browser_tools.mjs open --url "http://localhost:9527/#/inspection/log/list?book_id=352"

Lista de Verificação de Verificação

Depois de abrir uma página, verifique o sucesso explicitamente:

• Verifique se a saída JSON url corresponde à rota esperada.
• Verifique o title ou um seletor conhecido se a página tiver títulos dinâmicos.
• Se a ação parecer silenciosa, execute node scripts/browser_tools.mjs list antes de tentar novamente.
• Se o login estiver faltando, confirme que o Chrome foi iniciado com o perfil persistente e não um perfil temporário.

Modos de Falha

Ferramentas do navegador não conseguiram conectar

Causa provável: Chrome não está executando com --remote-debugging-port=<porta>.

Correção:

• Reinicie o Chrome com python scripts/start_chrome_debug.py.
• Confirme que a porta corresponde à passada para os scripts.

Nova aba aberta, mas a rota estava errada

Causa provável: truncamento de hash de rota em uma ferramenta externa ou URL manualmente encurtada.

Correção:

• Use o comando open empacotado.
• Passe a URL completa com hash.

Estado de login ausente

Causa provável: Chrome iniciado com um diretório de perfil diferente.

Correção:

• Reinicie o Chrome com o --user-data-dir persistente.
• Reutilize esse mesmo diretório de perfil de forma consistente.

Escopo

Esta skill é intencionalmente focada em fluxo de trabalho. Ela padroniza uma configuração de automação de navegador independente para estado de login local persistente usando Playwright via CDP.