mcpField
C
chrome-bridge-automation

chrome-bridge-automation

github.com/hainrixz生产力28448 次安装4 天前更新
代码仓库

关于 chrome-bridge-automation

通过 Midscene Extension 的 Bridge 模式操作用户真实 Chrome 浏览器的自动化技能。它以截图和自然语言指令驱动页面交互，并保留浏览器会话及登录状态。

主要功能

  1. 01通过 Chrome Bridge 连接
  2. 02基于截图检查页面
  3. 03用自然语言执行界面操作
  4. 04保留 Cookie 和登录会话
  5. 05按同步命令流程操作

适用场景

  1. 01浏览并操作网页
  2. 02在现有浏览器会话中填写表单
  3. 03提取页面信息并汇报结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hainrixz/claude-webkit --skill chrome-bridge-automation

安装后在 Claude Code 中输入/chrome-bridge-automation确认已加载。

详细介绍

Chrome Bridge 自动化

关键规则 — 违反规则会导致工作流中断：

  1. 绝不要在后台运行 midscene 命令。 每条命令都必须同步运行，以便你在决定下一步操作之前读取其输出（尤其是截图）。后台执行会破坏截图-分析-操作循环。
  2. 一次只运行一条 midscene 命令。 等待上一条命令完成，读取截图，然后再决定下一步操作。绝不要串联多条命令。
  3. 为每条命令留出足够的完成时间。 Midscene 命令涉及 AI 推理和屏幕交互，耗时可能比一般的 shell 命令更长。通常一条命令需要约 1 分钟；复杂的 act 命令可能需要更久。
  4. 结束前务必报告任务结果。 完成自动化任务后，你必须主动向用户总结结果，包括找到的关键数据、完成的操作、截取的屏幕截图及任何相关发现。绝不要在最后一个自动化步骤后悄然结束；用户期望在一次交互中获得完整回复。

通过 Midscene Chrome Extension（Bridge 模式）自动化操作用户实际使用的 Chrome 浏览器，同时保留 Cookie、会话和登录状态。你（AI Agent）负责判断应执行哪些操作，并以截图为依据。

命令格式

关键 — 每条命令都必须严格遵循以下格式。请勿修改命令前缀。

npx @midscene/web@1 --bridge <subcommand> [args]
  • 此处必须使用 --bridge 标志 — 它会激活 Bridge 模式，以连接到用户桌面上的 Chrome 浏览器

前提条件

用户已准备好 Chrome 和 Midscene Extension。连接前请勿检查浏览器或扩展程序的状态 — 直接连接即可。

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。

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

命令

连接到网页
npx @midscene/web@1 --bridge connect --url https://example.com
截取屏幕截图
npx @midscene/web@1 --bridge take_screenshot

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

执行操作

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

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

# or target-driven instructions
npx @midscene/web@1 --bridge act --prompt "click the country dropdown and select Japan"
断开连接
npx @midscene/web@1 --bridge disconnect

工作流模式

Bridge 模式会连接到用户实际使用的 Chrome 浏览器。每条 CLI 命令都会建立自己的临时连接，但无论是否断开连接，浏览器、标签页以及所有状态（Cookie、登录会话）都会始终保留。因此，重新连接轻松又不会丢失任何状态。

请遵循以下流程：

  1. 连接到某个 URL 以建立会话
  2. 截取屏幕截图以查看当前状态，并确认页面已加载。
  3. 使用 act 执行操作，完成所需操作或基于目标的指令。
  4. 报告结果 — 总结已完成的工作，呈现任务期间提取的关键发现和数据，并列出生成的文件（屏幕截图、日志等）及其路径
  5. 仅当用户的整体任务全部完成后才断开连接。如果用户可能还会提出后续操作，请勿断开连接 — 保留会话，以便在后续对话轮次中继续交互。

最佳实践

  1. 始终先连接：进行任何交互前，先使用 connect --url 导航到目标 URL。
  2. 明确描述 UI 元素：不要说“那个按钮”，而要说“联系表单中的蓝色提交按钮”。
  3. 使用自然语言：描述你在页面上看到的内容，而不是 CSS 选择器。说“红色的立即购买按钮”，而不是 "#buy-btn"。
  4. 处理加载状态：导航或执行会触发页面加载的操作后，截取屏幕截图以确认页面已加载。
  5. 仅在任务全部完成后断开连接：只有在用户的整体任务已完全完成且预计不会有后续操作时，才断开连接。在多轮对话中，跳过断开连接，以便继续进行浏览器交互。断开连接是安全的——它只会关闭 CLI 端的桥接连接，不会关闭浏览器或标签页——但如果用户还想继续操作，重新连接会产生不必要的开销。
  6. 绝不在后台运行：每条 midscene 命令都必须同步运行——后台执行会打断“截图—分析—操作”循环。
  7. 将相关操作合并到一条 act 命令中：在同一页面上连续执行操作时，将它们合并到一条 act 提示中，而不是拆分成多条命令。例如，“填写电子邮件和密码字段，然后点击登录按钮”应作为一次 act 调用，而不是三次。这样可以减少往返次数，避免不必要的截图—分析循环，并显著提升速度。
  8. 完成后始终报告结果：完成自动化任务后，你必须主动向用户展示结果，不要等用户询问。这包括：(1) 对用户原始问题的回答或所请求任务的结果；(2) 执行期间提取或观察到的关键数据；(3) 截图和其他生成文件及其路径；(4) 对所采取步骤的简要总结。不要在最后一条自动化命令执行后就默默结束——用户期望在一次交互中获得完整结果。

示例 — 下拉菜单选择：

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

示例 — 表单交互：

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

故障排除

桥接模式连接失败
超时
  • 网页可能需要一些时间才能加载。连接后，先截取屏幕截图以确认页面已就绪，再进行交互。
  • 对于加载较慢的页面，请在步骤之间稍作等待。
截图未显示
  • 截图路径是本地文件的绝对路径。使用 Read 工具查看。

评论

支持 Markdown