浏览器自动化（Windows + Edge）

概述

本机只有 Edge 没有 Chrome。四条浏览器自动化路径：

agent-browser（Hermes 原生浏览器后端）

Hermes 默认浏览器方案，无需装系统 Chrome。自动管理 Chromium 运行时。

当前状态（2026-07-10）：Windows 上暂不可用。Chrome 150.0.7871.115 在 Windows 上启动报"无法在单独的会话中打开"（会话隔离问题），Lightpanda 引擎所有导航超时。详见 windows-master 技能 references/agent-browser-setup.md。

已知命令：

• agent-browser.exe open <url> — 导航（推荐，替代 navigate）
• agent-browser.exe doctor — 诊断环境、Chrome、启动测试
• agent-browser.exe --proxy <url> — 设置代理
• agent-browser.exe --engine lightpanda — 使用 Lightpanda 引擎（Windows 导航超时）

Playwright + Edge 无头模式

依赖

pip install playwright

不需要 playwright install chromium——直接用系统已安装的 Edge。

使用

必须用 venv Python（已装 playwright）：

# 百度搜索
/d/Hermes/hermes-agent/.venv/Scripts/python.exe D:/Hermes/scripts/browser_agent.py "搜索词"

# 打开网页取内容
/d/Hermes/hermes-agent/.venv/Scripts/python.exe D:/Hermes/scripts/browser_agent.py --url https://example.com

# 截图
/d/Hermes/hermes-agent/.venv/Scripts/python.exe D:/Hermes/scripts/browser_agent.py --screenshot https://example.com

不要用系统 Python（python/python3），它没装 playwright 会报 ModuleNotFoundError: No module named 'playwright'。

输出 JSON，{success: true, title: ..., text: ..., results: [...]}

注意事项

• Edge 路径：C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
• 百度在 headless 模式下搜索框不可见——不要用 page.fill('#kw')，改用 URL 参数：https://www.baidu.com/s?wd=关键词
• 设置自定义 UA 避免反爬：browser.new_context(user_agent="...Edg/120...")
• page.goto() 用 wait_until="domcontentloaded" 并额外 wait_for_timeout(2000) 等 JS 渲染

mcp-chrome-bridge + Edge

架构

mcp-chrome-bridge = npm 桥接服务（127.0.0.1:12306）+ 浏览器扩展（CRX）。扩展通过原生消息协议启动 bridge 的 HTTP server，Hermes gateway 通过 stdio 子进程连接 bridge。

Hermes config.yaml（stdio 模式）：

mcp_servers:
  chrome:
    command: D:/sofeware/node/node.exe
    args:
    - C:/Users/28672/AppData/Roaming/npm/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js
    timeout: 120
    connect_timeout: 30

安装要点

1. npm install -g mcp-chrome-bridge（已装 v1.0.31）
2. 扩展 ID：hbdgbgagpkpjffpklnamcljpakneikee
3. mcp-chrome-bridge 的 register 命令只支持 chrome/chromium，Edge 需手动注册（复制 Chromium manifest + 添加 Edge 注册表键）
4. 允许用户级原生消息：HKLM\Software\Policies\Microsoft\Edge\NativeMessagingUserLevelHosts = 1
5. 扩展 zip 从 GitHub 下载在国内经常损坏——手动解析 ZIP local file headers 提取文件（见 references/damaged-zip-extraction.md）
6. 装完跑 hermes mcp test chrome 验证（27 个工具），会话中 /reload 加载

完整部署步骤见 references/mcp-chrome-edge-setup.md。

config.yaml 配置

mcp-chrome-bridge 的 HTTP server（127.0.0.1:12306）使用 StreamableHTTP 协议，但只支持单个 MCP transport 连接。Edge 扩展已占用该连接，外部 HTTP/SSE 客户端无法再接入。因此必须用 stdio 模式——gateway 启动 mcp-server-stdio.js 子进程，由它内部连接 bridge：

# ✅ 正确：stdio 模式（gateway 启动子进程，内部连 bridge）
mcp_servers:
  chrome:
    command: D:/sofeware/node/node.exe
    args:
    - C:/Users/28672/AppData/Roaming/npm/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js
    timeout: 120
    connect_timeout: 30

# ❌ 错误：URL/SSE 模式（bridge 只接受一个 transport，已被扩展占用）
# 会报 "Already connected to a transport. Call close() before connecting..."
mcp_servers:
  chrome:
    transport: sse  # 或 streamableHttp
    url: http://127.0.0.1:12306/mcp
    timeout: 60

修改 config.yaml 的注意事项：patch 工具和 yaml.dump() 都不能用来编辑 config.yaml。正确做法是用 terminal + Python 字符串替换。

修改后必须在 Hermes 会话中输入 /reload 重新加载 MCP 配置。

故障排查

调试原则：遇到 mcp_chrome 连不上时，先诊断后动手。不要反复改 config + /reload。按下面顺序排查，80% 的情况 bridge 根本没在跑。

症状：mcp_chrome 工具报 "Failed to connect to MCP server"

完整调试记录见 references/bridge-debug-session-20260704.md。

按以下顺序排查：

1. 确认 bridge 在运行：

   curl -s http://127.0.0.1:12306/ping
   # 返回 {"status":"ok","message":"pong"} = bridge 正常运行
   # 返回 "Connection refused" = bridge 没启动

2. 直接测试 chrome MCP server（验证 server 本身没问题）：

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
     D:/sofeware/node/node.exe "C:/Users/28672/AppData/Roaming/npm/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js"
   # 应返回 27 个工具的 JSON 列表

3. 检查 config.yaml 是 stdio 模式（不是 URL/SSE 模式），确认 command + args 字段存在
4. 确认 gateway 已加载 chrome：gateway_list_servers 应包含 chrome
5. 如果 config 刚改过，执行 /reload 重新加载

症状：stdio 测试报 "Already connected to a transport"

bridge 只接受一个 MCP transport，被占用后新连接失败。修复：

# 1. 找到 bridge 进程 PID
netstat -ano | grep "LISTENING.*12306"
# 找到 PID 后杀掉
taskkill /PID <pid> /F
# 3. 等待 Edge 扩展自动重启 bridge（通常 5-10 秒）
sleep 5
curl -s http://127.0.0.1:12306/ping  # 确认重启成功
# 4. 重新加载 Hermes MCP
# 在 Hermes 中输入 /reload

症状：bridge 杀了后不自动重启

Edge 扩展不一定立即重连 bridge。等 10 秒后 curl -s http://127.0.0.1:12306/ping 仍无响应：

• 确认 Edge 浏览器在运行：tasklist | grep msedge
• 打开 edge://extensions 确认 mcp-chrome 扩展处于启用状态
• 触发扩展活动（如切换标签页）促使其重连
• 如果扩展长期 idle，bridge 不会重启——此时改用 Playwright 方案更可靠

症状：修改 config.yaml 被拒绝

patch 工具和 yaml.dump() 都不能编辑 config.yaml。正确做法：

python -c "
with open('D:/Hermes/config.yaml', 'r') as f:
    c = f.read()
c = c.replace('old_string', 'new_string')
with open('D:/Hermes/config.yaml', 'w') as f:
    f.write(c)
"

工具速览（27个）

• 标签：get_windows_and_tabs, switch_tab, close_tabs
• 导航：navigate
• 交互：click_element, fill_or_select, keyboard
• 内容：get_web_content, read_page, screenshot
• 脚本：javascript
• 网络：network_request, network_capture
• 数据：history, bookmark_search/add/delete
• 其他：upload_file, handle_download, console, handle_dialog, gif_recorder

方案选择