O que show-and-tell faz?
Uma janela do Chrome for Testing que você e o usuário compartilham. Você aponta para coisas na página; o usuário aponta de volta através do painel lateral show-and-tell (Anotar, Gravar, mensagem). Nenhum tour é necessário para nenhum dos dois. Tours guiados e vídeos são camadas opcionais adicionais. O painel é parte da interface do navegador e nunca aparece em capturas de tela da página.
<skill> abaixo é o diretório deste skill (a pasta com este SKILL.md). Os comandos funcionam em qualquer shell.
Peças
- Navegador: Chrome for Testing em seu próprio perfil, CDP
127.0.0.1:9334, extensão pré-carregada.start_browsero inicia (idempotente) e abre o painel; ele sobrevive à sessão. - MCP show-and-tell:
start_browser,status,highlight,clear_highlights,hide_overlays,get_queue,wait_for_action,request_demo,set_step,load_tour,goto_step,end_tour,record_tour,stop_recording. Cada um também existe como CLI:node "<skill>/bridge" <start|status|highlight <css> [--label t] [--gesture g] [--direction d] [--to css] [--url u] [--style s] [--keep]|clear|hide|show|queue [--recent]|wait|cancel|request <prompt>| step <label>|tour <file>|goto <n>|end|record <file> [--name n] [--size s]|record-stop|record-cancel>. - Ferramentas
browser_*do mesmo MCP (Playwright MCP, anexado a este navegador) dirigem a página quando você precisa de mais do quehighlightpode fazer:browser_snapshot,browser_click,browser_type,browser_evaluate,browser_navigate, … Elas iniciam o navegador se necessário e atuam na guia do aplicativo, nunca no painel. Um servidorplaywrightseparado e simples, se o host tiver um, é seu navegador privado que o usuário não vê; use-o apenas para trabalho que o usuário não deve observar.
Trabalhando onde o usuário assiste
O usuário acompanha o navegador compartilhado; o painel mostra cada chamada browser_* ("clicando em …", "solicitando
dados através da página"). Mantenha-o acompanhável:
- Mostrar ou reproduzir algo: use a interface visível (navegue, clique, digite), para que a página mostre.
- Ler muitos dados (logs, listas, JSON): chamar a própria API do aplicativo com
fetchdentro debrowser_evaluateé aceitável e usa a sessão do usuário, mas nada muda na tela. Diga isso no chat primeiro ("Estou lendo os logs através da API do Grafana na sua guia"). - Mantenha tais requisições pequenas (intervalos de tempo curtos,
limit): uma chamada que dura mais de cerca de um minuto é interrompida pelo cliente MCP. Divida intervalos longos em vez de repetir a mesma consulta.
Barreira: hosts permitidos
O navegador compartilhado contém os logins do usuário, então toda ferramenta aqui (apontamento, tours, vídeos e browser_*)
funciona apenas em hosts permitidos. Esta máquina é sempre permitida: localhost, endereços de loopback e nomes que o
arquivo hosts mapeia para loopback. Qualquer outro host, mesmo privado em outra rede, é perguntado no painel
lateral quando você o usar pela primeira vez ("Não", "Esta sessão", "Sempre"); a chamada aguarda até 2 minutos pela resposta.
Não permitido: o usuário não permitiu …: respeite; não repita nem procure uma maneira de contornar.… não respondeu …: diga ao usuário em uma linha que o painel está perguntando, então repita uma vez.- Nunca edite
extension/config.jsonouconfig.local.jsonvocê mesmo; apenas o usuário concede hosts.
O ouvinte: ouvindo o usuário
O usuário pode enviar a qualquer momento. Você o ouve através de um ouvinte, um trabalho em segundo plano no shell.
start_browser,statuse toda ferramenta que dirige o navegador retornamwatcher. Serunningfor falso, iniciewatcher.commandimediatamente como um trabalho em segundo plano (ferramenta de shell, opção background) e não aguarde.- Quando ele completa, carrega
{"actions": [...]}: lide com eles (próxima seção), então inicie o ouvinte novamente. Uma conclusão comtimeoutoucancellede nenhuma ação: inicie-o novamente e não diga nada. - Mantenha-o em execução enquanto você conversa; nunca o cancele para responder a uma mensagem do chat.
- O painel envia para a sessão que dirigiu o navegador por último e mostra "<sessão> está ouvindo".
- Sem trabalhos em segundo plano neste ambiente: quando o usuário disser que enviou, marcou ou gravou algo, chame
get_queue(recent: truetambém retorna os itens entregues na última hora).
Mostrar algo ao usuário
highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }):
urlabre essa página na guia do aplicativo primeiro; nenhum Playwright necessário. Verifiquefound: falseantes de falar.label: uma pequena legenda.style:outline(padrão),spotlight(escurece o resto),none(sem caixa).gesturereproduz uma ilustração no elemento; nunca é executado. Toque:tap,double-tap,long-press,swipe,pinch. Mouse:click,double-click,right-click,hover,drag,scroll.direction: left/right/up/down (swipe, drag, scroll), in/out (pinch).to: CSS de um fim de swipe/drag.keep: trueadiciona aos destaques atuais; caso contrário, eles são substituídos.clear_highlightsos remove.- Prefira seletores estáveis (id,
data-testid, aria) maistext. Explique no chat em 1–3 frases.
O que o usuário envia
Cada item em actions tem um type (e step enquanto um tour está em execução):
question: uma mensagem (text). Responda no chat.annotation: o usuário marcou a página ("Anotar": um clique marca um elemento, arrastar desenha) e escreveutext. Você recebe uma imagem inline que só você vê: as marcas numeradas e coloridas do usuário e notas mais contornos tracejados rotulados1a,1b… ao redor dos elementos a que cada marca se refere.annotations[]é a legenda:n,kind(element/rect/arrow/pen),color,rect, arrowfrom/to,note,elements[](label,selectors,tag,text,rect). As coordenadas são coordenadas do documento;imageAreaé o que a imagem mostra. Refira-se às marcas pelo número ou cor e texto do elemento, nunca pelos rótulos 1a.imagePathé a própria versão do usuário.recording: o usuário demonstrou algo ("Gravar", ou seurequest_demo, então comrequestIdeprompt).recording.stepssegue o formato do Chrome DevTools Recorder (navigate,clickcombutton: "secondary"emodifiers,doubleClick,change,keyDown,scroll) maislongPress,swipeeurlChange; etapas de elemento carregamselectors,tag,text.texté o comentário do usuário.demoDeclined: o usuário descartou sua solicitação.- Eventos de tour e vídeo:
next/back,agentStep,stepError,tourEnd,videoReady,videoError,videoDiscarded(seções abaixo).
request_demo({ prompt }) pede ao usuário que mostre algo; o painel começa a gravar para ele.
Tour guiado
- Planeje as etapas no chat: título e o que cada uma mostra, uma ideia por etapa.
- Roteirize
{ steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:explanation: 2–5 frases, mostradas no painel.url: navegue primeiro. Voltar reproduz a partir da etapa anterior mais próxima com umurl, então dê a cada etapa que muda o estado da página umaurlacessível.actions:{click|fill|waitFor|hover|doubleClick|rightClick|longPress|swipe|drag|scroll: css, text?, value?, to?, direction?, ms?},{scrollBy: px, in?: css},{press: key, on?: css},{wait: ms}.highlights: comohighlight(); o primeiro substitui, os restantes são adicionados.agent: trueapenas para etapas que você deve fazer manualmente: aja,set_step("n/N – título"), destaque, explique, entãogoto_step(n+1)quandonextchegar. Verifique seletores primeiro (browser_evaluate); um ausente se tornastepError.
- Inicie:
start_browser(inicie o ouvinte), verifiquebridge.panelOpen, entãoload_tour({ tour })e diga ao usuário em uma linha que o tour está em execução no painel. - Reaja:
stepError→ corrija a etapa,load_tourcomstart: step.tourEnd→end_toure um breve resumo. Perguntas e marcações durante um tour referem-se à etapacurrent.
Demonstrando alterações de código
- Escopo: alterações não commitadas (
git diff HEAD), caso contrário, o branch contra sua base. Se não estiver claro: pergunte. - Mapeie cada arquivo alterado para a tela e elemento onde seu efeito aparece; alterações sem efeito visível vão para uma etapa de resumo final.
- Aplicativo: se não estiver acessível, inicie seu servidor de desenvolvimento a partir dos scripts do projeto como um trabalho em segundo plano. Então, uma etapa de tour por alteração visível, na ordem natural do aplicativo.
Vídeo de revisão
record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) reproduz um tour roteirizado por conta própria e
grava a guia como MP4 com legendas, rótulos de capítulo, barra de progresso, cartões de introdução/seção/fim, um cursor desenhado
ou dedo para cada ação, um arquivo .vtt e uma lista de capítulos. Ele retorna imediatamente; o ouvinte então recebe
videoReady { path, vtt, chapters, durationMs, … } ou videoError { step, error }. Leia
references/video.md antes de escrever um tour em vídeo.
Capturas de tela de evidência
Chame hide_overlays(true) antes de uma captura de tela que deve mostrar a página limpa, hide_overlays(false) depois.
Solução de problemas
extensionConnected: false:start_browsernovamente; a extensão reconecta em ~15 s e reproduz o que o usuário enviou enquanto isso.bridge not running: o MCP não está anexado; a CLI (start,wait) funciona por conta própria.- Uma chamada
browser_*diz que o navegador está fechado: ele reconecta uma vez por conta própria; se ainda falhar,start_browsere repita. - Um navegador serve um tour ou vídeo por vez. Se
statusmostrar uma etapa que você não definiu, outra sessão está usando-o: pergunte ao usuário primeiro. - Chrome for Testing ausente:
npx playwright install chromium, ou definaDEMO_BROWSER_PATH.