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 是允许的,并且会复用用户的会话,但屏幕上不会有任何变化。请先在聊天中告知用户(例如“我正在通过 Grafana 的 API 读取你标签页中的日志”)。 - 保持此类请求规模较小(设置较短的时间范围,使用
limit):超过一分钟左右的调用会被 MCP 客户端截断。对于较长的时间范围,应分段查询,而不是重复同样的查询。
安全规则:允许的主机
共享浏览器保存了用户的登录信息,因此此处的所有工具(指向、游览、视频以及 browser_*)只能在允许的主机上工作。本机始终允许:localhost、回环地址以及 hosts 文件映射到回环的域名。任何其他主机,即使是另一网络上的私有主机,在首次使用时都会通过侧面板询问用户(选项包括“不允许”、“本次会话”、“始终允许”);调用会等待用户回答最多 2 分钟。
不允许:用户未允许……:请尊重此决定;不要重试或寻找绕过方法。……用户未回答……:用一句话告知用户面板正在询问,然后重试一次。- 切勿自行编辑
extension/config.json或config.local.json;只有用户才能授权主机。
观察者:监听用户
用户可以随时发送内容。你通过一个观察者(一个后台 shell 作业)来接收。
start_browser、status以及所有驱动浏览器的工具都会返回watcher。如果running为false,请立即以后台作业(shell 工具,使用 background 选项)启动watcher.command,且不要等待它。- 当观察者完成时,它会携带
{"actions": [...]}:请处理这些动作(参见下一节),然后重新启动观察者。如果完成时带有timeout或cancelled且没有动作:重新启动观察者,不要发言。 - 在聊天过程中保持观察者运行;切勿为了回复聊天消息而取消它。
- 面板会发送给上次驱动浏览器的会话,并显示“<会话> 正在监听”。
- 在此框架中没有后台作业:当用户表示他们发送、标记或录制了内容时,请调用
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(用于滑动、拖拽、滚动)、in/out(用于捏合)。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、带button: "secondary"和modifiers的click、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的步骤开始回放,因此请为每个改变了页面状态的步骤提供一个可访问的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显示了一个不是你设置的步骤,说明有其他会话正在使用它:请先询问用户。 - 缺少 Chrome for Testing:运行
npx playwright install chromium,或设置环境变量DEMO_BROWSER_PATH。