show-and-tell (보여주고-말하기)은(는) 무엇을 하나요?
당신과 사용자가 공유하는 Chrome for Testing 창입니다. 당신은 페이지의 무언가를 가리키고, 사용자는 show-and-tell 사이드 패널 (주석, 녹화, 메시지)을 통해 응답합니다. 어떤 기능도 투어 없이 바로 사용할 수 있습니다. 가이드 투어와 비디오는 선택적인 추가 기능입니다. 패널은 브라우저 UI의 일부이며 페이지 스크린샷에는 절대 포함되지 않습니다.
<skill>은 이 스킬의 디렉토리(이 SKILL.md가 있는 폴더)를 나타냅니다. 명령어는 모든 셸에서 작동합니다.
구성 요소
- 브라우저: 자체 프로필을 사용하는 Chrome for Testing, CDP
127.0.0.1:9334, 확장 프로그램이 미리 로드되어 있습니다.start_browser가 이를 실행(멱등)하고 패널을 엽니다; 브라우저는 세션보다 오래 지속됩니다. - show-and-tell MCP:
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. 각 도구는 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>. - 동일 MCP의
browser_*도구 (이 브라우저에 연결된 Playwright MCP)는highlight만으로는 부족할 때 페이지를 제어하는 데 사용합니다:browser_snapshot,browser_click,browser_type,browser_evaluate,browser_navigate, … 이 도구들은 필요하면 브라우저를 시작하고 앱 탭에서만 작동하며, 패널에서는 절대 동작하지 않습니다. 호스트에 별도의 일반playwright서버가 있다면 그것은 사용자가 보지 못하는 개인 브라우저입니다; 사용자가 보면 안 되는 작업에만 사용하세요.
사용자가 지켜보는 곳에서 작업하기
사용자는 공유 브라우저를 따라가며, 패널은 각 browser_* 호출("클릭 중…", "페이지를 통해 데이터 요청 중…")을 표시합니다. 따라올 수 있도록 유지하세요:
- 무언가를 보여주거나 재현할 때: 보이는 UI를 사용하세요 (이동, 클릭, 입력). 그러면 페이지에 그 내용이 표시됩니다.
- 많은 데이터(로그, 목록, JSON)를 읽을 때:
browser_evaluate내에서fetch로 앱 자체 API를 호출해도 괜찮으며 사용자 세션을 사용하지만, 화면에는 아무 변화가 없습니다. 채팅으로 먼저 말하세요 ("Grafana의 API를 통해 사용자 탭에서 로그를 읽고 있습니다"). - 이러한 요청은 작게 유지하세요 (짧은 시간 범위,
limit): 약 1분 이상 실행되는 호출은 MCP 클라이언트에 의해 중단됩니다. 동일한 쿼리를 재시도하지 말고 긴 범위를 나누세요.
가드레일: 허용된 호스트
공유 브라우저는 사용자의 로그인 정보를 보유하므로, 여기의 모든 도구(포인팅, 투어, 비디오 및 browser_*)는 허용된 호스트에서만 작동합니다. 이 머신은 항상 허용됩니다: localhost, 루프백 주소 및 호스트 파일이 루프백에 매핑하는 이름. 다른 호스트(다른 네트워크의 개인 호스트라도)는 처음 사용할 때 사이드 패널에서 사용자에게 확인을 요청합니다("아니요", "이 세션", "항상"); 호출은 최대 2분 동안 응답을 기다립니다.
허용되지 않음: 사용자가 …을(를) 허용하지 않았습니다: 이를 존중하세요. 재시도하거나 우회 방법을 찾지 마세요.…이(가) 응답하지 않았습니다: 사용자에게 패널이 묻고 있다고 한 줄로 알린 다음, 한 번 재시도하세요.extension/config.json또는config.local.json을 직접 편집하지 마세요; 호스트를 허용하는 것은 사용자만이 할 수 있습니다.
감시자: 사용자 듣기
사용자는 언제든지 보낼 수 있습니다. 당신은 감시자라는 백그라운드 셸 작업을 통해 이를 듣습니다.
start_browser,status및 브라우저를 구동하는 모든 도구는watcher를 반환합니다.running이 false이면watcher.command를 즉시 백그라운드 작업(셸 도구, background 옵션)으로 시작하고 기다리지 마세요.- 완료되면
{"actions": [...]}를 전달합니다: 이를 처리한 다음(다음 섹션), 감시자를 다시 시작하세요.timeout또는cancelled로 완료되고 액션이 없으면: 다시 시작하고 아무 말도 하지 마세요. - 채팅 중에는 계속 실행 상태로 두세요; 채팅 메시지에 응답하기 위해 절대 취소하지 마세요.
- 패널은 마지막으로 브라우저를 구동한 세션으로 전송하며 "이 듣고 있습니다"를 표시합니다.
- 이 툴킷에서는 백그라운드 작업이 없습니다: 사용자가 무언가를 보냈다고 말하면,
get_queue를 호출하세요(recent: true는 지난 1시간 동안 전달된 항목도 반환합니다).
사용자에게 무언가 보여주기
highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }):
url: 먼저 앱 탭에서 해당 페이지를 엽니다; Playwright가 필요하지 않습니다. 말하기 전에found: false인지 확인하세요.label: 짧은 설명문입니다.style:outline(기본값),spotlight(나머지 영역을 어둡게),none(박스 없음).gesture: 요소에 애니메이션 일러스트레이션을 반복합니다; 실제로 수행되지는 않습니다. 터치:tap,double-tap,long-press,swipe,pinch. 마우스:click,double-click,right-click,hover,drag,scroll.direction: left/right/up/down(swipe, drag, scroll), in/out(pinch).to: 스와이프/드래그 끝 지점의 CSS 선택자.keep: true: 현재 하이라이트에 추가합니다; 그렇지 않으면 교체됩니다.clear_highlights로 제거합니다.- 안정적인 선택자(id,
data-testid, aria) +text를 선호하세요. 채팅에서 1~3문장으로 설명하세요.
사용자가 보내는 것
actions의 각 항목에는 type(및 투어가 실행 중인 동안 step)이 있습니다:
question: 메시지(text)입니다. 채팅으로 답변하세요.annotation: 사용자가 페이지에 표시를 했습니다("주석": 클릭으로 요소를 표시하거나, 드래그로 그리기) 그리고text를 작성했습니다. 당신만 볼 수 있는 인라인 이미지를 받습니다: 사용자의 번호가 매겨진 색상 표시와 메모, 그리고 각 마크가 참조하는 요소 주위에1a,1b…로 레이블이 지정된 점선 윤곽선.annotations[]은 범례입니다:n,kind(element/rect/arrow/pen),color,rect, arrowfrom/to,note,elements[](label,selectors,tag,text,rect). 좌표는 문서 좌표입니다;imageArea는 이미지가 보여주는 영역입니다. 마크를 참조할 때는 1a 레이블이 아닌 번호나 색상 및 요소 텍스트로 참조하세요.imagePath는 사용자 자신의 버전입니다.recording: 사용자가 무언가를 시연했습니다("녹화", 또는 당신의request_demo에 응답,requestId와prompt포함).recording.steps는 Chrome DevTools Recorder 형식을 따릅니다(navigate,click(button: "secondary"및modifiers포함),doubleClick,change,keyDown,scroll) +longPress,swipe,urlChange; 요소 단계에는selectors,tag,text가 포함됩니다.text는 사용자의 코멘트입니다.demoDeclined: 사용자가 요청을 거부했습니다.- 투어 및 비디오 이벤트:
next/back,agentStep,stepError,tourEnd,videoReady,videoError,videoDiscarded(아래 섹션 참조).
request_demo({ prompt })는 사용자에게 무언가를 보여달라고 요청합니다; 패널이 녹화를 시작합니다.
가이드 투어
- 계획: 채팅에서 단계를 계획하세요: 제목과 각 단계가 보여줄 내용, 단계당 하나의 아이디어.
- 스크립트:
{ steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:explanation: 2~5문장, 패널에 표시됩니다.url: 먼저 이동합니다. 뒤로 가기는 가장 가까운 이전url단계부터 재생되므로, 페이지 상태를 변경하는 모든 단계에 접근 가능한url을 제공하세요.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:highlight()와 동일; 첫 번째는 교체하고 나머지는 추가됩니다.agent: true: 당신이 직접 수행해야 하는 단계에만 사용하세요: 실행,set_step("n/N – title"), 하이라이트, 설명, 그리고next가 도착하면goto_step(n+1). 먼저 선택자를 확인하세요(browser_evaluate); 누락된 선택자는stepError가 됩니다.
- 시작:
start_browser(감시자 시작),bridge.panelOpen확인, 그런 다음load_tour({ tour })를 호출하고 사용자에게 투어가 패널에서 실행 중이라고 한 줄로 알리세요. - 반응:
stepError→ 단계를 수정하고load_tour를start: step과 함께 호출.tourEnd→end_tour및 간단한 요약. 투어 중 질문과 표시는 현재step을 참조합니다.
코드 변경 시연하기
- 범위: 커밋되지 않은 변경사항(
git diff HEAD), 또는 그렇지 않으면 브랜치의 베이스와 비교. 불명확하면 물어보세요. - 매핑: 각 변경된 파일을 그 효과가 나타나는 화면과 요소에 매핑하세요; 가시적인 효과가 없는 변경사항은 하나의 마무리 요약 단계에 넣으세요.
- 앱: 도달할 수 없으면 프로젝트 스크립트에서 dev 서버를 백그라운드 작업으로 시작하세요. 그런 다음 보이는 변경사항당 하나의 투어 단계, 앱의 자연스러운 순서로 진행하세요.
리뷰 비디오
record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? })는 스크립트된 투어를 자동으로 재생하고 탭을 MP4로 녹화합니다. 캡션, 챕터 레이블, 진행 막대, 도입/섹션/종료 카드, 모든 동작에 대한 그려진 커서 또는 손가락, .vtt 및 챕터 목록이 포함됩니다. 즉시 반환하며, 감시자는 videoReady { path, vtt, chapters, durationMs, … } 또는 videoError { step, error }를 받습니다. 비디오 투어를 작성하기 전에 references/video.md를 읽으세요.
증거 스크린샷
일반 페이지를 보여주는 스크린샷을 찍기 전에 hide_overlays(true)를 호출하고, 이후에 hide_overlays(false)를 호출하세요.
문제 해결
extensionConnected: false:start_browser를 다시 실행하세요; 확장 프로그램이 약 15초 내에 재연결되고 그동안 사용자가 보낸 내용을 재생합니다.bridge not running: MCP가 연결되지 않았습니다; CLI(start,wait)는 자체적으로 작동합니다.browser_*호출이 브라우저가 닫혔다고 말함: 자체적으로 한 번 재연결을 시도합니다; 여전히 실패하면start_browser를 실행하고 재시도하세요.- 하나의 브라우저는 한 번에 하나의 투어 또는 비디오만 처리합니다.
status가 설정하지 않은 단계를 표시하면 다른 세션이 사용 중인 것입니다: 사용자에게 먼저 물어보세요. - Chrome for Testing이 없음:
npx playwright install chromium을 실행하거나DEMO_BROWSER_PATH를 설정하세요.