Que fait show-and-tell ?
Une fenêtre Chrome for Testing que vous et l'utilisateur partagez. Vous pointez vers des éléments dans la page ; l'utilisateur pointe en retour via le panneau latéral show-and-tell (Annoter, Enregistrer, Message). Aucune visite guidée n'est nécessaire pour l'un ou l'autre. Les visites guidées et les vidéos sont des couches optionnelles supplémentaires. Le panneau fait partie de l'interface du navigateur et n'apparaît jamais dans les captures d'écran de la page.
<skill> ci-dessous est le répertoire de cette compétence (le dossier contenant ce SKILL.md). Les commandes fonctionnent dans n'importe quel shell.
Composants
- Navigateur : Chrome for Testing avec son propre profil, CDP
127.0.0.1:9334, extension préchargée.start_browserle lance (idempotent) et ouvre le panneau ; il survit à la session. - 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. Chacun existe aussi en 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>. - Outils
browser_*du même MCP (Playwright MCP, attaché à ce navigateur) pilotent la page lorsque vous avez besoin de plus que ce quehighlightpeut faire :browser_snapshot,browser_click,browser_type,browser_evaluate,browser_navigate, … Ils démarrent le navigateur si nécessaire et agissent dans l'onglet de l'application, jamais dans le panneau. Un serveurplaywrightdistinct, si l'hôte en possède un, est votre navigateur privé que l'utilisateur ne voit pas ; utilisez-le uniquement pour un travail que l'utilisateur ne doit pas regarder.
Travailler là où l'utilisateur regarde
L'utilisateur suit le navigateur partagé ; le panneau montre chaque appel browser_* (« clic sur … », « demande de données via la page »). Maintenez-le compréhensible :
- Pour montrer ou reproduire quelque chose : utilisez l'interface visible (naviguer, cliquer, taper) afin que la page l'affiche.
- Pour lire beaucoup de données (journaux, listes, JSON) : appeler l'API propre de l'application avec
fetchdansbrowser_evaluateest acceptable et utilise la session de l'utilisateur, mais rien ne change à l'écran. Dites-le d'abord dans le chat (« Je lis les journaux via l'API Grafana dans votre onglet »). - Gardez ces requêtes petites (plages de temps courtes,
limit) : un appel qui dure plus d'une minute environ est interrompu par le client MCP. Divisez les longues plages plutôt que de réessayer la même requête.
Garde-fou : hôtes autorisés
Le navigateur partagé contient les connexions de l'utilisateur, donc chaque outil ici (pointage, visites guidées, vidéos et browser_*) ne fonctionne que sur les hôtes autorisés. Cette machine est toujours autorisée : localhost, les adresses de boucle locale et les noms que le fichier hosts associe à la boucle locale. Tout autre hôte, même privé sur un autre réseau, est demandé dans le panneau latéral lors de la première utilisation (« Non », « Cette session », « Toujours ») ; l'appel attend jusqu'à 2 minutes la réponse.
Non autorisé : l'utilisateur n'a pas autorisé …: respectez-le ; ne réessayez pas et ne cherchez pas de contournement.… n'a pas répondu …: dites à l'utilisateur en une ligne que le panneau demande, puis réessayez une fois.- Ne modifiez jamais
extension/config.jsonouconfig.local.jsonvous-même ; seuls les utilisateurs accordent l'accès aux hôtes.
Le watcher : écouter l'utilisateur
L'utilisateur peut envoyer à tout moment. Vous l'entendez via un watcher, un job shell en arrière-plan.
start_browser,statuset chaque outil qui pilote le navigateur renvoientwatcher. Sirunningest faux, démarrezwatcher.commandimmédiatement en tant que job d'arrière-plan (outil shell, option background) et n'attendez pas.- Lorsqu'il se termine, il contient
{"actions": [...]}: gérez-les (section suivante), puis redémarrez le watcher. Une fin avectimeoutoucancelledsans actions : redémarrez-le et ne dites rien. - Gardez-le actif pendant que vous discutez ; ne l'annulez jamais pour répondre à un message du chat.
- Le panneau envoie à la session qui a piloté le navigateur en dernier et affiche « écoute ».
- Pas de jobs d'arrière-plan dans ce contexte : lorsque l'utilisateur dit avoir envoyé, marqué ou enregistré quelque chose, appelez
get_queue(recent: truerenvoie également les éléments livrés de la dernière heure).
Montrer quelque chose à l'utilisateur
highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }) :
urlouvre cette page dans l'onglet de l'application d'abord ; pas besoin de Playwright. Vérifiezfound: falseavant de parler.label: une courte annotation.style:outline(par défaut),spotlight(assombrit le reste),none(pas de boîte).gestureboucle une illustration sur l'élément ; elle n'est jamais exécutée. Tactile :tap,double-tap,long-press,swipe,pinch. Souris :click,double-click,right-click,hover,drag,scroll.direction: left/right/up/down (swipe, drag, scroll), in/out (pinch).to: CSS d'une fin de swipe/drag.keep: trueajoute aux surlignages actuels ; sinon ils sont remplacés.clear_highlightsles supprime.- Préférez les sélecteurs stables (id,
data-testid, aria) plustext. Expliquez dans le chat en 1 à 3 phrases.
Ce que l'utilisateur envoie
Chaque élément dans actions a un type (et step pendant une visite guidée) :
question: un message (text). Répondez-y dans le chat.annotation: l'utilisateur a marqué la page (« Annoter » : un clic marque un élément, un glissement dessine) et a écrittext. Vous recevez une image en ligne que vous seul voyez : les marques numérotées et colorées de l'utilisateur, les notes, ainsi que des contours en pointillés étiquetés1a,1b… autour des éléments auxquels chaque marque se réfère.annotations[]est la légende :n,kind(element/rect/arrow/pen),color,rect, arrowfrom/to,note,elements[](label,selectors,tag,text,rect). Les coordonnées sont des coordonnées du document ;imageAreaest ce que l'image montre. Référez-vous aux marques par numéro ou couleur et texte de l'élément, jamais par les étiquettes 1a.imagePathest la version de l'utilisateur.recording: l'utilisateur a démontré quelque chose (« Enregistrer », ou votrerequest_demo, puis avecrequestIdetprompt).recording.stepssuit le format de Chrome DevTools Recorder (navigate,clickavecbutton: "secondary"etmodifiers,doubleClick,change,keyDown,scroll) pluslongPress,swipeeturlChange; les étapes d'élément portentselectors,tag,text.textest le commentaire de l'utilisateur.demoDeclined: l'utilisateur a rejeté votre demande.- Événements de visite et vidéo :
next/back,agentStep,stepError,tourEnd,videoReady,videoError,videoDiscarded(sections ci-dessous).
request_demo({ prompt }) demande à l'utilisateur de vous montrer quelque chose ; le panneau commence l'enregistrement pour lui.
Visite guidée
- Planifiez les étapes dans le chat : titre et ce que chacune montre, une idée par étape.
- Scénarisez
{ steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:explanation: 2 à 5 phrases, affichées dans le panneau.url: naviguer d'abord. Le retour reprend depuis l'étape antérieure la plus proche avec uneurl, donc donnez à chaque étape qui change l'état de la page uneurlaccessible.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: commehighlight(); la première remplace, les suivantes s'ajoutent.agent: trueuniquement pour les étapes que vous devez faire à la main : agissez,set_step("n/N – title"), mettez en surbrillance, expliquez, puisgoto_step(n+1)lorsquenextarrive. Vérifiez d'abord les sélecteurs (browser_evaluate) ; un sélecteur manquant devientstepError.
- Démarrez :
start_browser(démarrez le watcher), vérifiezbridge.panelOpen, puisload_tour({ tour })et dites à l'utilisateur en une ligne que la visite guidée s'exécute dans le panneau. - Réagissez :
stepError→ corrigez l'étape,load_touravecstart: step.tourEnd→end_touret un court résumé. Les questions et les marques pendant une visite se réfèrent à l'étapestepen cours.
Démontrer des modifications de code
- Périmètre : modifications non validées (
git diff HEAD), sinon la branche par rapport à sa base. Si ce n'est pas clair, demandez. - Mappez chaque fichier modifié à l'écran et à l'élément où son effet apparaît ; les modifications sans effet visible vont dans une étape récapitulative de clôture.
- Application : si elle n'est pas accessible, démarrez son serveur de développement à partir des scripts du projet en tant que job d'arrière-plan. Ensuite, une étape de visite par changement visible, dans l'ordre naturel de l'application.
Vidéo de révision
record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) joue une visite scénarisée toute seule et enregistre l'onglet en MP4 avec sous-titres, étiquettes de chapitre, barre de progression, cartes d'intro/section/outro, un curseur dessiné ou un doigt pour chaque action, un fichier .vtt et une liste de chapitres. Elle retourne immédiatement ; le watcher reçoit ensuite videoReady { path, vtt, chapters, durationMs, … } ou videoError { step, error }. Lisez references/video.md avant d'écrire une visite vidéo.
Captures d'écran de preuve
Appelez hide_overlays(true) avant une capture d'écran qui doit montrer la page brute, hide_overlays(false) après.
Dépannage
extensionConnected: false: relancezstart_browser; l'extension se reconnecte dans environ 15 s et rejoue ce que l'utilisateur a envoyé entre-temps.bridge not running: le MCP n'est pas attaché ; la CLI (start,wait) fonctionne seule.- Un appel
browser_*indique que le navigateur est fermé : il se reconnecte une fois tout seul ; si cela échoue encore,start_browseret réessayez. - Un navigateur sert une visite ou une vidéo à la fois. Si
statusmontre une étape que vous n'avez pas définie, une autre session l'utilise : demandez d'abord à l'utilisateur. - Chrome for Testing manquant :
npx playwright install chromium, ou définissezDEMO_BROWSER_PATH.