Communitygithub.com

show-and-tell(展示与指导)

一个双向指示频道,你与用户在共享浏览器中的实时网页上互动。你可以展示内容(高亮、标签、手势示意图,如点击/滑动/拖拽),用户也能从侧面板向你展示内容(带备注的标记、录制的点击和手势、消息)。

show-and-tell(展示与指导) 是什么?

show-and-tell 是一个 AI 技能,通过共享的 Chrome for Testing 浏览器窗口,在 AI 代理与用户之间建立双向指示频道。它主要用于需要实时协作的场景:AI 代理可以在页面上高亮元素、显示手势动画或导航到特定 URL,而用户则可以通过侧面板发送注释、录制演示或直接发消息。该技能支持可选的分步引导(通过 JSON 配置的步骤实现)和录制回溯视频(输出为带字幕的 MP4)。它要求代理在共享浏览器中操作时保持透明——每次 browser_* 调用都会在面板中显示——并且通过一个后台观察进程实时轮询用户操作。为了确保安全,所有操作都限制在用户明确允许的主机上。总之,show-and-tell 非常适合用于“展示给我看”、“这是哪里?”、“看看我标记/发送/录制了什么”、交互式演示、代码变更展示以及客户回顾视频等场景。

兼容平台✓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 是允许的,并且会复用用户的会话,但屏幕上不会有任何变化。请先在聊天中告知用户(例如“我正在通过 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 }) 要求用户向你展示某些内容;面板会开始为用户录制。

引导式游览

  1. 规划步骤:在聊天中规划标题以及每个步骤要展示的内容,每一步只表达一个想法。
  2. 编写脚本 { 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。
  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 显示了一个不是你设置的步骤,说明有其他会话正在使用它:请先询问用户。
  • 缺少 Chrome for Testing:运行 npx playwright install chromium,或设置环境变量 DEMO_BROWSER_PATH。

相关技能