browser-automation

浏览器自动化

关键规则——违反规则会破坏工作流：

1. 绝不要在后台运行 midscene 命令。 每条命令都必须同步运行，这样你才能读取其输出（尤其是截图），再决定下一步操作。在后台运行会破坏“截图—分析—操作”的循环。
2. 每次只运行一条 midscene 命令。 等待上一条命令完成，读取截图，然后再决定下一步操作。绝不要串联多条命令。
3. 为每条命令留出充足的完成时间。 Midscene 命令涉及 AI 推理和屏幕交互，耗时可能比常见的 Shell 命令更长。通常一条命令需要约 1 分钟；复杂的 act 命令可能需要更久。
4. 结束前务必汇报任务结果。 自动化任务完成后，必须主动向用户总结结果，包括发现的关键信息、已完成的操作、拍摄的截图以及任何相关发现。绝不能在最后一步自动化操作后就悄然结束；用户希望在一次交互中获得完整答复。

使用 npx -y @midscene/web@1 自动化网页浏览。默认情况下，它会通过 Puppeteer 启动一个无头 Chrome，并在 CLI 调用之间保持运行状态，不会丢失会话。也支持 CDP 模式和 Bridge 模式，以连接现有的 Chrome 浏览器。

act 可以执行的操作

在浏览器中进行一次 act 调用时，Midscene 可以点击、右键单击、双击、悬停、输入或清除文本、按键、滚动、拖动、长按，并根据当前可见内容完成多步骤页面流程。启用触控输入后，它还可以处理面向触控页面中的滑动或捏合操作。

适用场景

此技能有三种模式。请根据用户意图选择：

模式选择指南

模式	适用场景	工作方式
Puppeteer（默认）	用户想要浏览 URL、抓取数据或测试 UI，且不需要使用自己的浏览器	启动一个与用户浏览器隔离的全新无头 Chrome
CDP 模式	用户说“连接到我的 Chrome”“控制我的浏览器”“CDP”“远程调试”，或希望操作自己现有的浏览器。任务隐含要求登录状态时也使用此模式（例如“查看我的订单”“打开我的仪表板”“查看我的账户”）	通过 DevTools Protocol 连接到用户的 Chrome。需要启用远程调试（chrome://inspect >“Allow remote debugging”）。无需安装扩展
Bridge 模式	用户明确提到“bridge”或“扩展”，或者已安装 Midscene Chrome Extension 并希望使用它	通过 Midscene Chrome Extension 连接到用户的 Chrome

CDP 与 Bridge 的区别：两者都可以控制保留登录会话的用户真实 Chrome。CDP 只需切换一项 Chrome 设置；Bridge 则需要安装 Chrome Extension。如果用户没有指定，优先使用 CDP 模式，因为它的前置条件更少。

预检查：检测可用的 CDP 目标

使用 CDP 模式前，先运行快速预检查，确认 Chrome 的远程调试端口是否可访问。这样可以避免用户尚未启用远程调试时出现长时间超时。

# CDP precheck (port 9222, 2s timeout) — returns "101" if Chrome is listening for DevTools
curl -s --max-time 2 -o /dev/null -w "%{http_code}" -H "Upgrade: websocket" -H "Connection: Upgrade" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" http://127.0.0.1:9222/devtools/browser

如何使用预检查结果：

• 返回 101 → CDP 模式可用，请使用 --cdp
• 失败（curl 退出码为 7 或 HTTP 000）→ Chrome 未在启用远程调试的情况下运行。使用 --remote-debugging-port=9222 启动 Chrome，等待 2-3 秒，然后重新运行预检查。如果仍然失败，请切换到 Puppeteer 模式（如果已安装 Midscene Chrome Extension，也可以使用 Bridge 模式）。

Bridge 模式没有可用的预检查。 尽管涉及端口 3766，但 Bridge 服务由 CLI 启动（npx ... --bridge connect 会自行打开 3766）；扩展是接入的客户端。在 CLI 运行前检查 3766 总是得不到结果。直接运行 --bridge connect 即可——其第一条日志（waiting for bridge to connect... → one client connected）会告诉你扩展是否已连接。

前置条件

Midscene 需要具备强视觉定位能力的模型。必须配置以下环境变量——可以将其设为系统环境变量，也可以放在当前工作目录下的 .env 文件中（Midscene 会自动加载 .env）：

MIDSCENE_MODEL_API_KEY="your-api-key"
MIDSCENE_MODEL_NAME="model-name"
MIDSCENE_MODEL_BASE_URL="https://..."
MIDSCENE_MODEL_FAMILY="family-identifier"

示例：Gemini（Gemini-3-Flash）

MIDSCENE_MODEL_API_KEY="your-google-api-key"
MIDSCENE_MODEL_NAME="gemini-3-flash"
MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_FAMILY="gemini"

示例：Qwen 3.5

MIDSCENE_MODEL_API_KEY="your-aliyun-api-key"
MIDSCENE_MODEL_NAME="qwen3.5-plus"
MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_FAMILY="qwen3.5"
MIDSCENE_MODEL_REASONING_ENABLED="false"
# If using OpenRouter, set:
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

示例：Doubao Seed 2.0 Lite

MIDSCENE_MODEL_API_KEY="your-doubao-api-key"
MIDSCENE_MODEL_NAME="doubao-seed-2-0-lite"
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_FAMILY="doubao-seed"

常用模型：Doubao Seed 2.0 Lite、Qwen 3.5、Zhipu GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

如果尚未配置模型，请让用户进行配置。支持的提供方请参阅模型配置。

CDP 模式（连接到现有浏览器）

使用 CDP 模式控制用户现有的 Chrome 浏览器。默认 CDP 端点为 ws://127.0.0.1:9222/devtools/browser（端口 9222 是 Chrome 的标准远程调试端口）。如果用户指定了其他端口，请相应替换 9222。

在每条命令中添加 --cdp <ws-endpoint>：

npx -y @midscene/web@1 connect --cdp ws://127.0.0.1:9222/devtools/browser --url https://example.com
npx -y @midscene/web@1 act --cdp ws://127.0.0.1:9222/devtools/browser --prompt "click the button"
npx -y @midscene/web@1 take_screenshot --cdp ws://127.0.0.1:9222/devtools/browser
npx -y @midscene/web@1 disconnect --cdp ws://127.0.0.1:9222/devtools/browser

CDP 模式下的自定义 HTTP 请求头

如果用户在 CDP 模式下需要自定义请求头，例如将请求路由到 PPE 环境，请通过单独的 --extra-http-header 'Name:Value' 选项传入每个请求头。重复此选项即可发送多个请求头。请使用用户提供的准确请求头名称和值；不要猜测环境名称或身份验证值。

npx -y @midscene/web@1 connect \
  --cdp ws://127.0.0.1:9222/devtools/browser \
  --extra-http-header 'x-use-ppe:1' \
  --extra-http-header 'x-tt-env:ppe_example' \
  --url https://example.com

npx -y @midscene/web@1 act \
  --cdp ws://127.0.0.1:9222/devtools/browser \
  --extra-http-header 'x-use-ppe:1' \
  --extra-http-header 'x-tt-env:ppe_example' \
  --prompt "click the button"

每条 CLI 命令都会创建新的 CDP 会话。在每条可能发出请求的 CDP 命令中（包括 connect、act 和 assert），都要重复添加所有必需的 --extra-http-header 'Name:Value' 选项。从第一个冒号处分割每个条目，因此值中可以包含额外的冒号。请求头会在 connect --url 导航前应用，因此初始文档请求也会包含这些请求头。不要在任务摘要中打印请求头的值，并避免将敏感身份验证值直接写入 shell 历史记录。

CDP 模式的重要说明

• 浏览器由外部管理——disconnect 会释放连接，但不会关闭浏览器。CDP 模式没有 close 命令。
• 在 CDP 模式下，connect --url 会导航到现有活动标签页，而不是打开新标签页。
• 不带 --url 的 connect 会连接到当前活动标签页，但不会导航。
• 如果连接失败，请让用户启用远程调试：在 Chrome 中打开 chrome://inspect，然后开启“Allow remote debugging”。

Bridge 模式（通过 Chrome 扩展连接）

当用户明确提到“bridge”或“extension”，或者已安装 Midscene Chrome Extension 时，使用 Bridge 模式。在每条命令中添加 --bridge：

npx -y @midscene/web@1 --bridge connect --url https://example.com
npx -y @midscene/web@1 --bridge act --prompt "click the button"
npx -y @midscene/web@1 --bridge take_screenshot
npx -y @midscene/web@1 --bridge disconnect

Bridge 模式的重要说明

• 用户必须打开 Chrome（或任何支持 Chrome 扩展的基于 Chromium 的浏览器，例如 Edge、Arc、Dia），并安装和启用 Midscene Extension。
• 从 Chrome 网上应用店安装扩展程序：https://chromewebstore.google.com/detail/midscenejs/gbldofcpkknbggpkmbdaefngejllnief
• 握手方向：CLI 是服务端（监听 127.0.0.1:3766）；扩展程序是客户端，负责连接 CLI。扩展程序面板中显示的“Listening”状态表示“已准备好连接 CLI”，而不是扩展程序本身打开了端口。实际操作时：先启动 --bridge connect；扩展程序会在一两秒内连接。
• 活动标签页必须是普通网页。 扩展程序无法操作 chrome://、chrome-extension://、Chrome 网上应用店或其他受限 URL。如果活动标签页是其中之一，CLI 会返回 Cannot access a chrome:// URL。请让用户先切换到常规的 http(s):// 标签页，再重新连接。
• 文件上传权限：Bridge 模式下上传本地文件需要启用 Midscene 扩展程序的“Allow access to file URLs”权限。请让用户打开 chrome://extensions，找到 Midscene，点击“Details”，启用开关，然后切回目标 http(s):// 标签页再重新连接。如果上传因权限问题失败，或出现 Not allowed 错误，请先检查此项。
• 不带 --url 的 connect 会连接当前活动标签页；connect --url <href> 会在该标签页中导航。Bridge 模式下，CLI 不会打开新标签页。
• disconnect 只会关闭 CLI 端的 Bridge 连接，不会关闭浏览器或标签页。
• 如果未安装扩展程序，请引导用户安装，或建议改用 CDP 模式。
• 请参阅 Bridge 模式文档。

命令

连接到网页

npx -y @midscene/web@1 connect --url https://example.com

截图后，请读取保存的图像文件，了解当前页面状态，再决定下一步操作。

截图

npx -y @midscene/web@1 take_screenshot

执行操作

使用 act 与页面交互并获取结果。它会在内部自主处理所有 UI 交互，包括点击、输入、滚动、悬停、等待和导航，因此应将复杂的高级任务作为整体交给它，而不要拆分成多个小步骤。请用自然语言描述你想做什么以及期望达到的效果：

# specific instructions
npx -y @midscene/web@1 act --prompt "click the Login button and fill in the email field with '[email protected]'"
npx -y @midscene/web@1 act --prompt "scroll down and click the Submit button"

# or target-driven instructions
npx -y @midscene/web@1 act --prompt "click the country dropdown and select Japan"

上传文件

当提示 Midscene 上传文件时，act 需要显式指定 --file-chooser-allowed-dir。请使用包含测试夹具的最小目录；不要授予项目根目录或主目录的访问权限。在提示词中使用相对于该目录的路径来引用文件。

在 Bridge 模式下，还要确认 Midscene 扩展程序已在 chrome://extensions > Midscene > “Details” 中启用“Allow access to file URLs”，并在更改开关后，从目标 http(s):// 标签页重新连接。

npx -y @midscene/web@1 act \
  --file-chooser-allowed-dir ./fixtures \
  --prompt "click the upload button and upload avatar.png"

断言当前页面状态

使用 assert 验证当前页面是否满足自然语言条件。它不会执行 UI 操作；它只检查可见的页面状态，并且仅当断言为真时才会通过。可用于验证、QA 检查以及在 act 后验证最终状态。

npx -y @midscene/web@1 assert --prompt "there is a login button visible"
npx -y @midscene/web@1 assert --prompt "the checkout page shows the order total and a Pay button"

在 CDP 或 Bridge 模式下，传入与其他命令相同的连接标志：

npx -y @midscene/web@1 assert --cdp ws://127.0.0.1:9222/devtools/browser --prompt "the dashboard is loaded"
npx -y @midscene/web@1 --bridge assert --prompt "the profile page shows the user's avatar"

默认情况下，断言失败会抛出 AI 生成的原因。传入 --message 可改为抛出自定义错误消息，这有助于在 QA 和 CI 日志中显示预期结果。

npx -y @midscene/web@1 assert \
  --prompt "the checkout page shows an order confirmation" \
  --message "the order should be confirmed after clicking Pay"

当断言需要与参考图像（图标、徽标、屏幕截图）进行比较时，传入 --image 指定 URL/路径，并传入 --image-name 指定其显示名称。每个 --image 都可以是 http(s) 链接、data: URI 或本地文件路径。如果需要附加多张图像，请按相同顺序重复这两个标志。当模型无法直接访问 URL 时，添加 --convertHttpImage2Base64 true。需要 @midscene/[email protected]+。

npx -y @midscene/web@1 assert \
  --prompt "the page shows the same logo as the reference image" \
  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
  --image-name "logo" \
  --convertHttpImage2Base64 true

# or with a local file
npx -y @midscene/web@1 assert \
  --prompt "the visible header matches the supplied screenshot" \
  --image "./fixtures/header.png" \
  --image-name "header"

# multiple reference images — pair --image and --image-name by order
npx -y @midscene/web@1 assert \
  --prompt "the page shows both the logo and the header" \
  --image "./fixtures/logo.png"   --image-name "logo" \
  --image "./fixtures/header.png" --image-name "header"

录制并断言短暂的 UI 状态

如果要验证的状态可能在当前屏幕断言运行前消失（例如 toast、加载横幅、动画或过渡），请使用录制功能。在专用的交互式终端中运行录制器：

# Terminal 1: keep this foreground command running
npx -y @midscene/web@1 record start \
  --output ./submission-observation.json

# Terminal 2, while Terminal 1 records
npx -y @midscene/web@1 act --prompt "click the Submit button"

# Send Ctrl+C to Terminal 1 and wait for the saved-path message, then assert
npx -y @midscene/web@1 assert \
  --record ./submission-observation.json \
  --prompt "a success toast appeared during submission"

将常规目标标志和 --output 传入 record start，然后等待 Recording. Press Ctrl+C to stop and save.。让录制器在其终端中以前台进程运行；切勿添加 shell &。手动或从第二个终端执行交互，向录制器发送 Ctrl+C，并等待它打印已保存路径后再进行断言。在 CDP 模式下，在 record start、操作和 assert 命令中重复传入 --cdp ws://127.0.0.1:9222/devtools/browser。在 Bridge 模式下，前台录制器会占用唯一的 Bridge 连接，因此请手动交互，不要启动第二个 Bridge CLI 操作。

record start 的可选捕获标志包括 --interval-ms、--max-frames 和 --watchdog-ms；--max-frames 会限制采样帧数，清单中可能还会额外包含一帧最终代表性画面。默认看门狗会在五分钟后完成并保存录制，而 --watchdog-ms 0 会禁用此安全限制。输出是一个 JSON 清单及其相邻的 <name>.frames 图像目录，而不是编码后的视频或归档文件。清单包含相对 JPEG/PNG 路径，不包含 base64 图像内容。请将 JSON 文件和图像目录放在一起保留或移动，并将 JSON 路径传给 assert --record。如果只关心当前页面，请使用不带 --record 的常规 assert。

使用参考图像进行精确定位

当用户提供屏幕截图、图标、徽标或参考图像并要求精确视觉匹配时，优先使用 tap --locate，而不是通用的 act --prompt。将 JSON 传给 --locate。prompt 描述目标，images 提供带名称的参考图像；当模型可能无法直接访问图像 URL 时，convertHttpImage2Base64: true 会很有用。

npx -y @midscene/web@1 tap --locate '{
  "prompt": "tap the area contains the image",
  "images": [
    {
      "name": "target image",
      "url": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
    }
  ],
  "convertHttpImage2Base64": true
}'

接受 locate 参数的其他命令也适用相同的 locate JSON 结构。

断开连接

断开与页面的连接，但保持浏览器运行：

npx -y @midscene/web@1 disconnect

关闭浏览器

完成后彻底关闭浏览器（仅限 Puppeteer 模式）：

npx -y @midscene/web@1 close

使用报告文件

建议先通过生成的 HTML 报告供人阅读。报告包含逐步执行详情和每项操作的回放视频，因此更容易了解发生了什么并排查问题。

如果其他技能或工具需要读取报告，请先使用同一平台 CLI 包中的 report-tool 转换报告。对于基于 LLM 的工作流，优先使用 Markdown。如果需要以编程方式处理报告，请使用 JSON。

npx -y @midscene/web@1 report-tool --action to-markdown --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-markdown
npx -y @midscene/web@1 report-tool --action split --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-data

工作流模式

浏览器会通过后台 Chrome 进程在 CLI 调用之间保持运行。请遵循以下模式：

1. 连接到一个 URL，以打开新标签页
2. 截图查看当前状态，确保页面已加载。
3. 执行操作：使用 act 执行所需操作或基于目标的指令。使用 assert 验证操作后的页面状态；对于瞬时状态工作流，也可以在专用终端中持续运行 record start --output ...，按 Ctrl+C 停止录制，然后使用 assert --record。
4. 完成后关闭浏览器（或断开连接，以便之后继续使用）
5. 报告结果——总结已完成的工作，展示任务中发现的要点和提取的数据，并列出生成的文件（截图、日志等）及其路径

最佳实践

1. 始终先连接：交互前，使用 connect --url 导航到目标 URL。
2. 检查可见状态：导航或执行会触发页面变化的操作后，先截图并阅读，再决定下一步。
3. 使用自然、具体的提示：描述可见的 UI 和期望结果，例如 "click the blue Submit button in the contact form"，不要使用 "#submit" 这类选择器。
4. 将相关操作批量放入单个 act 命令：例如，在一条提示中填写电子邮件和密码，然后点击 Log In。需要检查中间状态时，使用单独的命令。
5. 选择合适的验证窗口：对于当前页面，使用 assert --prompt "..."。对于 toast、横幅、动画或过渡效果，在专用终端中运行 record start --output ...，执行交互后按 Ctrl+C 停止录制，等待保存路径消息，然后将录制文件传给 assert --record。
6. 提供参考图片时，优先使用 tap --locate：如果用户分享了截图、图标或徽标，并希望定位到该视觉目标，请使用 tap --locate 并提供多模态 locate JSON 对象，例如 { "prompt": "...", "images": [...] }，不要只依赖 act --prompt。

示例——下拉菜单选择：

npx -y @midscene/web@1 act --prompt "click the country dropdown and select Japan"
npx -y @midscene/web@1 take_screenshot

示例——表单交互：

npx -y @midscene/web@1 act --prompt "fill in the email field with '[email protected]' and the password field with 'pass123', then click the Log In button"
npx -y @midscene/web@1 take_screenshot

提升精度（Deep Locate / Deep Think）

当 Midscene 难以完成任务时，可以使用两个可选的全局标志。可将它们放在命令中的任意位置（子命令前后均可）；设置后，相关操作会默认使用它们，因此无需传入单次调用参数。

• --deep-locate ——额外进行一轮视觉推理，以精确定位目标元素。当操作点错位置（位置漂移／偏移）时使用。它适用于所有需要定位元素的操作，包括 tap --locate 以及 act 中的定位操作。
• --deep-think ——使用更深入的推理规划 act（提供更丰富的上下文并拆解子目标）。适用于复杂的多步骤 act 指令；它只影响规划。

这两个标志会稍微降低速度，但能提升效果，也可以同时使用。

# more accurate element location (helps act's internal locating too)
npx -y @midscene/web@1 act --deep-locate --prompt "click the tiny gear icon in the top-right toolbar"

# deeper planning for a complex, multi-step act
npx -y @midscene/web@1 act --deep-think --prompt "complete the multi-step checkout form"

# combine both
npx -y @midscene/web@1 act --deep-locate --deep-think --prompt "open the settings menu, go to Preferences, and enable dark mode"

在 CDP 或 Bridge 模式下，请同时保留常用的 --cdp / --bridge 标志。

故障排除

连接失败

• 确保系统已安装 Chrome/Chromium（Puppeteer 默认会自行下载）。
• 检查防火墙是否阻止了本地 Chrome 调试端口。

API 密钥错误

• 检查 .env 文件是否包含 MIDSCENE_MODEL_API_KEY=<your-key>。
• 验证该密钥是否适用于已配置的模型提供方。

超时

• 网页可能需要一些时间才能加载。连接后，先截图确认页面已就绪，再进行交互。
• 对于加载较慢的页面，请在步骤之间稍作等待。

@midscene/* 依赖版本过旧

• 检查本地版本：npm ls @midscene/web @midscene/core @midscene/shared（或 pnpm why @midscene/web）。
• 检查最新版本：npm view @midscene/web version、npm view @midscene/core version、npm view @midscene/shared version。
• 升级依赖：npm i @midscene/web@latest @midscene/core@latest @midscene/shared@latest。

截图无法显示

• 截图路径是本地文件的绝对路径。使用 Read 工具查看。