show-and-tell 是做什麼的?
一個您與使用者共享的 Chrome for Testing 視窗。您可以在頁面上指向某些內容;使用者則透過 show-and-tell 側邊面板(標註、錄製、訊息)回指。雙方都不需要導覽。引導式導覽和影片是選用的附加功能。面板是瀏覽器 UI,永遠不會出現在頁面截圖中。
<skill> 指的是此技能的目錄(包含此 SKILL.md 的資料夾)。指令可在任何 shell 中執行。
組成
- 瀏覽器:使用自有設定檔的 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>。 browser_*工具(同一個 MCP,即 Playwright MCP,附加於此瀏覽器)用於當您需要比highlight更複雜的操作時驅動頁面:browser_snapshot,browser_click,browser_type,browser_evaluate,browser_navigate, … 它們會在需要時啟動瀏覽器,並在應用程式標籤頁中操作,永遠不會影響面板。如果主機有獨立的playwright伺服器,那會是您私有的、使用者看不到的瀏覽器;僅用於不應讓使用者觀看的工作。
在使用者觀看時工作
使用者會跟隨共享瀏覽器;面板會顯示每個 browser_* 呼叫(「正在點擊…」、「正在透過頁面請求資料」)。請保持跟隨性:
- 顯示或重現某個東西時:使用可見的 UI(導航、點擊、輸入),讓頁面顯示變更。
- 讀取大量資料(日誌、列表、JSON):在
browser_evaluate中使用fetch呼叫應用程式自己的 API 是可以的,因為它使用使用者的 session,但畫面上不會有任何變化。先在聊天中告知使用者(「我正在透過 Grafana 的 API 在您的分頁中讀取日誌」)。 - 保持這類請求小型(短時間範圍、
limit):執行時間超過約一分鐘的呼叫會被 MCP 用戶端截斷。將長範圍分割,而不是重試同一查詢。
護欄:允許的主機
共享瀏覽器保存了使用者的登入資訊,因此這裡的每個工具(指向、導覽、影片以及 browser_*)只能在允許的主機上運作。此機器永遠允許:localhost、loopback 位址以及 hosts 檔案映射到 loopback 的名稱。任何其他主機,即使是另一個網路上的私有主機,都會在您首次使用時在側邊面板中詢問(「否」、「此次工作階段」、「永遠」);呼叫會等待最多 2 分鐘以取得回答。
不允許:使用者未允許…:尊重它;不要重試或尋找繞過的方法。…未回答…:用一行話告訴使用者面板正在詢問,然後重試一次。- 切勿自行編輯
extension/config.json或config.local.json;只有使用者可以授予主機權限。
監聽器:聽取使用者意見
使用者可以隨時發送訊息。您可以透過 監聽器(watcher)聽到,這是一個背景 shell 工作。
start_browser,status以及每個驅動瀏覽器的工具都會回傳watcher。如果running為 false,請立即以背景工作(shell 工具,background 選項)啟動watcher.command,且不要等待它。- 當它完成時,會攜帶
{"actions": [...]}:處理它們(下一節),然後重新啟動監聽器。如果完成時帶有timeout或cancelled且沒有動作:重新啟動監聽器,並且什麼也別說。 - 在您聊天時保持它執行;永遠不要為了回覆聊天訊息而取消它。
- 面板會傳送到最後驅動瀏覽器的 session,並顯示「 正在監聽」。
- 此 harness 中沒有背景工作:當使用者說他們已發送、標記或錄製了某些東西時,呼叫
get_queue(加上recent: true也會回傳過去一小時內傳送的項目)。
向使用者顯示某些東西
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, 箭頭from/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),否則就是分支相對於其基礎分支的變更。如果不清楚:詢問。 - 映射 將每個變更過的檔案對應到螢幕上顯示其效果的元素;沒有可見效果的變更改進入一個總結步驟。
- 應用程式:如果應用程式無法存取,請從專案的腳本中以背景工作啟動其開發伺服器。 然後針對每個可見的變更,依照應用程式的自然順序建立一個導覽步驟。
回顧影片
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顯示您未設定的步驟,表示有其他 session 正在使用它:先詢問使用者。 - Chrome for Testing 缺失:執行
npx playwright install chromium,或設定DEMO_BROWSER_PATH。