Communitygithub.com

show-and-tell

雙向指引頻道,讓您在共享瀏覽器中的即時網頁上與使用者互動。您可以顯示內容(重點標示、標籤、手勢插圖如點擊/滑動/拖曳),使用者則可透過側邊面板標記、傳送訊息或錄製操作。

show-and-tell 是什麼?

show-and-tell 提供一個 Chrome for Testing 瀏覽器視窗,讓 AI 代理與使用者能即時共享同一頁面並互動。代理可以使用高亮、標籤、手勢動畫等方式指向頁面元素,使用者則透過專用側面板進行標註、錄製或傳送訊息。該工具支援引導式導覽(可設定步驟、自動播放動作),並能產出含字幕、章節與卡片的 MP4 回顧影片。此外,代理還可透過 playright MCP 工具執行點擊、輸入、導航等瀏覽操作,所有動作都會顯示於使用者面板以維持可跟隨性。安全機制限定僅允許的主機能被存取,並在使用者首次使用時請求授權。此技能適用於展示、除錯、程式碼變更示範、客戶回顧影片等場景。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Knyrps/agent-skills/tree/main/skills/show-and-tell

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 }) 要求使用者向您展示某些東西;面板會為他們開始錄製。

引導式導覽

  1. 規劃 在聊天中規劃步驟:標題以及每個步驟要展示的內容,一個步驟一個想法。
  2. 編寫腳本 { 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。
  3. 啟動:start_browser(啟動監聽器),檢查 bridge.panelOpen,然後 load_tour({ tour }) 並用一行話告訴使用者導覽正在面板中執行。
  4. 反應:stepError → 修正步驟,load_tour 帶上 start: step。tourEnd → end_tour 並提供簡短摘要。導覽期間的問題和標記會參照目前的 step。

示範程式碼變更

  1. 範圍:未提交的變更(git diff HEAD),否則就是分支相對於其基礎分支的變更。如果不清楚:詢問。
  2. 映射 將每個變更過的檔案對應到螢幕上顯示其效果的元素;沒有可見效果的變更改進入一個總結步驟。
  3. 應用程式:如果應用程式無法存取,請從專案的腳本中以背景工作啟動其開發伺服器。 然後針對每個可見的變更,依照應用程式的自然順序建立一個導覽步驟。

回顧影片

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。

相關技能