Midscene.js 调试工具速通：Playground 实时调试 + Chrome 扩展录制回放完整指南
【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene
你写了一条自然语言指令，AI 浏览器脚本在 headless 浏览器里点飞了目标，你只能盯着终端日志，猜它卡在哪一步——Midscene.js 调试工具就是为这个瞬间准备的：Playground 负责让你实时看见 AI 每一步，Chrome 扩展负责在你自己的浏览器里录制回放、把操作变成脚本。
从 0 到第一张实时截图，3 条命令
先 clone 仓库，装好依赖，再跑起来：
git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene && pnpm install然后两条命令：
# 1. 终端 A：启动 demo 服务器（puppeteer 页面 + Playground Server，端口 5870） cd apps/playground && npm run demo:server# 2. 终端 B：启动 Playground 前端，连上 5870 cd apps/playground SERVER_URL=http://localhost:5870 npm run dev打开http://localhost:3000。界面左侧显示 Playground Server 连接状态和 UI 上下文截图，右侧是当前页面实时画面。在 Prompt 框输入Click the search bar，点 Run——直接看效果：AI 的点击位置、页面变化、执行结果都在这一个页面上。
为什么端口要手动指定：demo 服务器起在 5870（见apps/playground/demo/server.ts），而 Playground Server 的默认端口是 5800，不通过SERVER_URL指定，前端会连默认地址，状态栏一直显示离线。
按"你现在在做什么"选工具
Midscene.js 调试工具的两件东西分工很清楚，按你手上的活对号入座：
| 你正在做的事 | 用什么 | 为什么是它 |
|---|---|---|
| 验证一条自然语言指令的效果 | Playground | 实时截图 + UI 上下文，远程执行，不用碰自己的浏览器 |
| 调试跑飞的 AI 浏览器自动化脚本 | Playground | 逐步看 AI 每一步做了什么，聊天式追加指令 |
| 在自己浏览器的真实标签页复现问题 | Chrome 扩展 | 本地执行，登录态、Cookie 都在 |
| 快速把操作步骤变成用例 | Chrome 扩展录制 | 录一次，AI 直接生成脚本 |
| 脚本和手动操作混跑同一页面 | Bridge 模式 | 扩展侧允许连接，本地 SDK 接管标签页 |
接力的典型路径：用扩展录制产出脚本 → 脚本丢进 Playground 跑 → 跑飞的那步回到扩展里重录。Playground 客户端核心在packages/playground-app/src/，服务器状态按 5 秒间隔轮询，离线时整页显示占位提示。
录一次操作，直接导出 YAML 或 Playwright
扩展侧边栏的 Recorder 面板点 New Recording 开始录制，操作你的页面，停止后点导出。产物有两种：
- YAML：喂给 Midscene.js 运行时，保持自然语言风格，适合继续用 AI 驱动；
- Playwright：直接进你现有的 Playwright 测试工程。
两个生成器都在apps/chrome-extension/src/extension/recorder/generators/下。注意：生成走 AI 模型，扩展设置里的 In-Browser Model Config 要先配好；复杂交互产出的断言建议手动校对一遍再入库。
Bridge 混合执行：脚本跑一半，人接着跑
有些页面脚本不好走（验证码、二次验证），Bridge 模式让你和 AI 操作同一个标签页：
- 扩展菜单选 Bridge Mode，状态行出现 listening；
- 本地跑你的 Midscene SDK 脚本连接；
- 终端提示连接请求时，点扩展里的 Allow Connection。
脚本执行期间你随时可以手动接管，状态行会如实记录 listening / closed 的切换。UI 实现在apps/chrome-extension/src/extension/bridge/index.tsx。
截图不刷新、扩展没反应、导出报错的 30 秒排查
按症状查，每条只给最可能的原因和一条验证动作：
| 症状 | 最可能的原因 | 30 秒验证 |
|---|---|---|
| Playground 截图不刷新，一直离线 | 前端连的端口和服务器不一致 | 看左侧 Playground Server 状态；终端 A 确认输出started on port 5870，前端用SERVER_URL指向同端口 |
| 扩展点了没反应 | 扩展没装成功或当前标签页没激活 | 打开chrome://extensions/看 service worker 日志；确认 manifest 的activeTab权限只在你主动打开的标签页生效（apps/chrome-extension/static/manifest.json） |
| 导出脚本报错 | 模型配置缺失，AI 生成失败 | 看扩展设置 In-Browser Model Config 三项是否有值，缺 API key 先补齐再重试 |
| Bridge 连着又断开 | 本地脚本进程退出 | 扩展状态行会打印 closed 时间戳；脚本侧重连，再点一次 Allow Connection |
更多配置项参考官方文档 apps/site/docs/zh/。
明天开工就能做的 3 件事
- 跑通 demo：按"3 条命令"一节把
npm run demo:server+npm run dev跑起来，看到第一张实时截图。 - 录一条真实用例：扩展里录一遍你登录页的操作，导出 YAML，存进项目
tests/目录。 - 配好模型再玩 Bridge：给扩展补上模型配置，用 Bridge 模式让脚本和手动操作混跑一次登录页，体会混合执行。
【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
