# Hermes Chrome Bridge

让 Hermes 像 Codex Desktop 一样，安静地控制你正在使用的真实 Chrome：

- 沿用现有 Chrome 登录态、Cookies 和标签页
- 不抢鼠标、不抢键盘、不把窗口切到前台
- 不依赖每次都要确认的 DevTools `autoConnect` 调试弹窗
- 每个活跃 Hermes 任务使用不重复颜色的 Chrome 标签组
- 后台桥接由 launchd 常驻，Hermes 重启后仍可继续使用

![两个 Hermes 任务分别使用蓝色和红色 Chrome 标签组](docs/assets/hermes-colored-tab-groups.png)

<p align="center"><sub>真实运行效果：两个 Hermes 任务在同一个 Chrome 窗口中使用独立颜色和名称，操作过程不抢焦点。</sub></p>

本项目基于 MIT 许可的
[agent-browser-mcp](https://github.com/335234131/agent-browser-mcp)
扩展而来，增加了 Hermes 任务绑定、彩色标签组、常驻服务和可复用安装方案。

## 它解决什么问题

官方 Chrome DevTools 自动连接会显示“允许调试”确认，这是 Chrome 的安全边界，
并不适合无人值守任务。桌面鼠标自动化虽然不需要这个确认，却会抢占用户输入，
也难以并发。

Hermes Chrome Bridge 改用一次性人工安装的本地 Chrome 扩展作为信任边界。
扩展通过 loopback WebSocket/HTTP 桥与 MCP 服务通信，使用 Chrome API 和 CDP
在后台操作页面。Hermes 的当前 `task_id` 会在每次浏览器调用前自动绑定，因此
不同任务不会混用标签页，并会显示为不同颜色的标签组。

## 效果

```text
Hermes 任务 A ── 蓝色标签组 ── 后台操作真实 Chrome
Hermes 任务 B ── 粉色标签组 ── 后台操作真实 Chrome
你本人        ── 普通标签页 ── 鼠标键盘不受影响
```

同一个任务在不同 Chrome 窗口中会创建同名、同色的标签组。新标签默认在后台
打开；接管已有标签时会将其归入当前任务组。

## 系统要求

- macOS
- Google Chrome
- Python 3.10+
- 本地源码安装的 Hermes Agent
- Hermes Python 环境通常位于 `~/.hermes/hermes-agent/venv`

核心 MCP 服务也可用于 Claude Desktop、Cursor 等客户端；自动 `task_id`
绑定和 launchd 安装脚本目前针对 Hermes/macOS。

## 快速安装

```bash
git clone https://github.com/linsipeng/hermes-chrome-bridge.git
cd hermes-chrome-bridge
bash scripts/install-hermes-macos.sh
```

安装器会：

1. 把当前仓库以 editable 模式装入 Hermes Python 环境；
2. 尝试给 Hermes MCP 调度器应用任务绑定补丁；
3. 安装并启动 `com.hermes.chrome-bridge` LaunchAgent。

如果 Hermes 不在默认目录：

```bash
HERMES_SOURCE=/path/to/hermes-agent \
PYTHON=/path/to/hermes/venv/bin/python \
bash scripts/install-hermes-macos.sh
```

## 一次性加载 Chrome 扩展

执行：

```bash
~/.hermes/hermes-agent/venv/bin/agent-browser-mcp extension-path
```

然后：

1. 打开 `chrome://extensions`
2. 开启“开发者模式”
3. 点击“加载已解压的扩展程序”
4. 选择上面命令输出的目录
5. 打开任意正常的 `http://` 或 `https://` 页面

这是一次性的显式授权。之后不需要每次点击“允许调试”。

## Hermes 配置

把 [examples/hermes-config.yaml](examples/hermes-config.yaml) 合并进
`~/.hermes/config.yaml`：

```yaml
mcp_servers:
  agent_browser:
    command: /absolute/path/to/agent-browser-mcp
    session_binding_tool: bind_hermes_session
    timeout: 120
    connect_timeout: 60
    tools:
      exclude:
        - capture_desktop_screenshot
        - mouse_move
        - mouse_click
        - mouse_drag
        - type_text
        - hotkey
        - pointer_info
```

建议排除物理输入工具，让 Hermes 默认只使用后台 DOM/CDP/Chrome API 控制。

重启并验证：

```bash
hermes gateway restart
hermes mcp test agent_browser
agent-browser-mcp doctor
```

## 主要 MCP 工具

- `bind_hermes_session`：绑定 Hermes 任务和标签组
- `list_tabs`：查看真实标签页及任务归属
- `switch_tab`：接管已有标签并加入当前任务组
- `open_new_tab`：后台打开并自动分组
- `release_hermes_session`：释放标签组，可选择关闭组内标签
- `scan_page`：读取简化后的页面内容
- `execute_js`：在真实页面执行 JavaScript
- `cdp_command` / `cdp_batch`：调用 Chrome DevTools Protocol
- `get_cookies`：读取当前真实 Chrome 会话 Cookies
- `capture_page_screenshot`：后台页面截图

## 服务管理

```bash
launchctl print gui/$(id -u)/com.hermes.chrome-bridge
agent-browser-mcp doctor
hermes mcp test agent_browser
```

卸载常驻桥：

```bash
bash scripts/uninstall-hermes-macos.sh
```

卸载脚本不会自动撤销 Hermes 源码补丁，以免覆盖用户的其他本地修改。

## 架构与经验

- [架构说明](docs/ARCHITECTURE.md)
- [这次实现沉淀的经验](docs/LESSONS_LEARNED.md)
- [Hermes 自动会话绑定补丁](patches/hermes-session-binding.patch)

## 安全说明

这个扩展能控制你的真实 Chrome，因此需要 `cookies`、`debugger`、`tabs` 和
`<all_urls>` 等高权限。请只安装你审查过的源码，不要安装来源不明的二次打包版本。

桥接服务只监听 `127.0.0.1:18765/18766`。不要把这些端口转发到局域网或公网。
项目不会上传 Cookies；但任何能在本机调用该 MCP 的程序，都可能获得浏览器操作能力。

## 已知限制

- `chrome://` 等 Chrome 内部页面无法被普通扩展脚本控制。
- Chrome 扩展仍需用户首次手动加载，这是有意保留的安全授权步骤。
- Hermes 上游升级可能导致补丁上下文变化；安装器会停止并提示手动处理，不会强改。
- Windows/Linux 可以运行 MCP 和扩展桥，但常驻服务安装脚本尚未提供。

## 致谢

底层 TMWebDriver、页面简化和扩展桥来自
[335234131/agent-browser-mcp](https://github.com/335234131/agent-browser-mcp)，
原项目使用 MIT License。本仓库保留相同许可证。

## License

[MIT](LICENSE)