Skip to content

feat: add optional browser extension bridge backend #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
sleepyy-dog wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat: add optional browser extension bridge backend #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 32 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,17 @@ AI Agent 原本的联网能力（WebSearch、WebFetch）缺少调度策略和浏
| 能力 | 说明 |
|------|------|
| 联网工具自动选择 | WebSearch / WebFetch / curl / Jina / CDP，按场景自主判断，可任意组合 |
| 浏览器扩展后端 | 可选的本地 Browser Bridge，一次性安装扩展后通过 `chrome.debugger` / `chrome.tabs` 操作 Chrome / Edge，避免日常使用依赖 remote-debugging 授权 |
| CDP Proxy 浏览器操作 | 直连用户日常浏览器（Chrome / Edge / Chromium 系），天然携带登录态，支持动态页面、交互操作、视频截帧 |
| 三种点击方式 | `/click`（JS click）、`/clickAt`（CDP 真实鼠标事件）、`/setFiles`（文件上传） |
| 本地浏览器书签/历史检索 | `find-url.mjs` 跨 Chrome / Edge 查询公网搜不到的目标（内部系统）或用户访问过的页面，支持关键词/时间窗/访问频度排序 |
| 并行分治 | 多目标时分发子 Agent 并行执行，共享一个 Proxy，tab 级隔离 |
| 站点经验积累 | 按域名存储操作经验（URL 模式、平台特征、已知陷阱），跨 session 复用 |
| 媒体提取 | 从 DOM 直取图片/视频 URL，或对视频任意时间点截帧分析 |

**未发布更新：**
- **浏览器扩展后端（可选）** — 新增 `extension/`、`scripts/webext-proxy.mjs` 和 `scripts/check-webext.mjs`。一次性 Load unpacked 并授权扩展后，默认使用 `127.0.0.1:3457`，日常浏览器操作不再需要 Chrome / Edge remote-debugging 授权弹窗。CDP Proxy 保留为兜底。

**v2.5.2 更新：**
- **Microsoft Edge 支持** — CDP Proxy 不再绑定 Chrome，新增 Edge 适配（及 Chromium、Chrome Canary 等 Chromium 系，通过同一套自动发现机制接入）。在 `edge://inspect/#remote-debugging` 勾选 "Allow remote debugging for this browser instance" 即可
- **浏览器偏好持久化** — 新增 `config.env`（gitignored，首次运行从模板创建），通过 `WEB_ACCESS_BROWSER` 固定默认浏览器；多浏览器同时开启 toggle 时 Agent 会询问偏好。也支持单次覆盖 `--browser <chrome|edge>`
Expand Down Expand Up @@ -109,7 +113,17 @@ claude plugin install web-access@web-access --scope user
git clone https://github.com/eze-is/web-access ~/.claude/skills/web-access
```

## 前置配置（CDP 模式）
## 前置配置（浏览器模式）

优先使用可选浏览器扩展后端：

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-webext.mjs"
```

如果扩展未连接，打开 `chrome://extensions` 或 `edge://extensions`，启用 Developer mode，Load unpacked 选择本 skill 的 `extension/` 目录。安装后扩展会连接本地 `webext-proxy.mjs`，后续浏览器操作无需再点 remote-debugging 授权弹窗。

### CDP 兜底

CDP 模式需要 **Node.js 22+** 和浏览器（Chrome / Edge）开启远程调试：

Expand Down Expand Up @@ -149,28 +163,31 @@ node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
# 手动运行请替换为实际路径，如 ~/.claude/skills/web-access
```

## CDP Proxy API
## Proxy API

Proxy 通过 WebSocket 直连浏览器（兼容 `chrome://inspect` / `edge://inspect` 方式，无需命令行参数启动），提供 HTTP API：
扩展后端端口是 `3457`，CDP 兜底端口是 `3456`。两者都提供常用 HTTP API：

```bash
# 启动（Agent 会自动管理 Proxy 生命周期，无需手动启动）
node "${CLAUDE_SKILL_DIR}/scripts/cdp-proxy.mjs" &
# 扩展后端
BASE=http://127.0.0.1:3457

# CDP 兜底时改为
# BASE=http://127.0.0.1:3456

# 页面操作
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new # 新建 tab（v2.5.3 起 URL 走 POST body）
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title' # 执行 JS
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit' # JS 点击
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d '.upload-btn' # 真实鼠标点击
curl -s -X POST "http://localhost:3456/setFiles?target=ID" \
curl -s -X POST --data-raw 'https://example.com' "$BASE/new" # 新建 tab（v2.5.3 起 URL 走 POST body）
curl -s -X POST "$BASE/eval?target=ID" -d 'document.title' # 执行 JS
curl -s -X POST "$BASE/click?target=ID" -d 'button.submit' # JS 点击
curl -s -X POST "$BASE/clickAt?target=ID" -d '.upload-btn' # 真实鼠标点击
curl -s -X POST "$BASE/setFiles?target=ID" \
-d '{"selector":"input[type=file]","files":["/path/to/file.png"]}' # 文件上传
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png" # 截图
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom" # 滚动
curl -s "http://localhost:3456/close?target=ID" # 关闭 tab
curl -s "http://localhost:3456/health" # 查看状态（含 managedTabs 数量）
curl -s "$BASE/screenshot?target=ID&file=/tmp/shot.png" # 截图
curl -s "$BASE/scroll?target=ID&direction=bottom" # 滚动
curl -s "$BASE/close?target=ID" # 关闭 tab
curl -s "$BASE/health" # 查看状态
```

Proxy 会自动追踪通过 `/new` 创建的 tab，闲置 15 分钟后自动关闭，防止 Agent 异常退出时留下孤儿 tab。可通过环境变量 `CDP_TAB_IDLE_TIMEOUT`（单位毫秒）调整超时时间。
CDP Proxy 会自动追踪通过 `/new` 创建的 tab，闲置 15 分钟后自动关闭，防止 Agent 异常退出时留下孤儿 tab。可通过环境变量 `CDP_TAB_IDLE_TIMEOUT`（单位毫秒）调整超时时间。

## ⚠️ 使用前提醒

Expand Down
69 changes: 47 additions & 22 deletions SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,24 @@ metadata:

## 前置检查

在开始联网操作前，先检查 CDP 模式可用性：
在开始联网操作前，优先检查浏览器扩展后端可用性：

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
node "${CLAUDE_SKILL_DIR}/scripts/check-webext.mjs"
```

**Node.js 22+** 必需（使用原生 WebSocket）。

按脚本输出处理：
- `exit 0` → 扩展后端已连接，后续浏览器操作使用 `http://127.0.0.1:3457`
- `exit 1` 且提示 extension not connected → 这是一次性安装步骤。引导用户打开 `chrome://extensions` 或 `edge://extensions`，启用 Developer mode，Load unpacked 选择 `${CLAUDE_SKILL_DIR}/extension`，然后重跑检查。安装并授权扩展后，日常使用不再需要浏览器 remote-debugging 授权弹窗。

扩展后端不可用、目标页无法 attach，或需要扩展未覆盖的底层 CDP 能力时，再检查 CDP 兜底：

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

按脚本输出处理：
- `exit 0` → 继续
- `exit 2` → 需询问用户偏好，写入 `${CLAUDE_SKILL_DIR}/config.env` 的 `WEB_ACCESS_BROWSER`
Expand All @@ -31,7 +41,7 @@ node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"

切换浏览器时，proxy 是长驻进程，需先 `pkill -f cdp-proxy.mjs` 再重跑 check-deps。

检查通过后并必须在回复中向用户直接展示以下须知，再启动 CDP Proxy 执行操作：
检查通过后并必须在回复中向用户直接展示以下须知，再启动浏览器自动化执行操作：

```
温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。
Expand Down Expand Up @@ -96,58 +106,72 @@ node "${CLAUDE_SKILL_DIR}/scripts/find-url.mjs" [关键词...] [--only bookmarks

**站点内交互产生的链接是可靠的**：通过用户视角中的可交互单元（卡片、条目、按钮）进行的站点内交互，自然到达的 URL 天然携带平台所需的完整上下文。而手动构造的 URL 可能缺失隐式必要参数，导致被拦截、返回错误页面、甚至触发反爬。

## 浏览器 CDP 模式
## 浏览器模式

通过 CDP Proxy 直连用户日常浏览器（Chrome / Edge / Chromium 等 Chromium 系），天然携带登录态，无需启动独立浏览器。
通过浏览器扩展后端或 CDP Proxy 直连用户日常浏览器（Chrome / Edge / Chromium 等 Chromium 系），天然携带登录态，无需启动独立浏览器。
若无用户明确要求，不主动操作用户已有 tab，所有操作都在自己创建的后台 tab 中进行，保持对用户环境的最小侵入。不关闭用户 tab 的前提下，完成任务后关闭自己创建的 tab，保持环境整洁。

### 启动
### 扩展后端（优先）

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-webext.mjs"
```

扩展后端由本地 `scripts/webext-proxy.mjs` 暴露 HTTP API，再由 `extension/` 中的 Manifest V3 扩展通过 `chrome.debugger` / `chrome.tabs` 操作浏览器。一次性安装并授权扩展后，日常使用不再依赖 `chrome://inspect/#remote-debugging` 的授权弹窗。细节见 `references/browser-extension.md`。

### CDP 兜底

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

脚本会依次检查 Node.js、浏览器调试端口，并确保 Proxy 已连接（未运行则自动启动并等待）。Proxy 启动后持续运行。
只有扩展后端不可用、扩展无法 attach 当前页面，或确实需要扩展后端未覆盖的底层 CDP 能力时，才运行 CDP 检查。脚本会依次检查 Node.js、浏览器调试端口，并确保 Proxy 已连接（未运行则自动启动并等待）。Proxy 启动后持续运行。

### Proxy API

所有操作通过 curl 调用 HTTP API：
所有操作通过 curl 调用 HTTP API。扩展后端端口是 `3457`，CDP 兜底端口是 `3456`：

```bash
# 扩展后端
BASE=http://127.0.0.1:3457

# CDP 兜底时改为
# BASE=http://127.0.0.1:3456

# 列出用户已打开的 tab
curl -s http://localhost:3456/targets
curl -s "$BASE/targets"

# 创建新后台 tab（自动等待加载）— URL 走 POST body，避免目标 URL 含 query 时被切分
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
curl -s -X POST --data-raw 'https://example.com' "$BASE/new"

# 页面信息
curl -s "http://localhost:3456/info?target=ID"
curl -s "$BASE/info?target=ID"

# 执行任意 JS：可读写 DOM、提取数据、操控元素、触发状态变更、提交表单、调用内部方法
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
curl -s -X POST "$BASE/eval?target=ID" -d 'document.title'

# 捕获页面渲染状态（含视频当前帧）
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
curl -s "$BASE/screenshot?target=ID&file=/tmp/shot.png"

# 导航（URL 走 POST body，target 走 query）、后退
curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
curl -s "http://localhost:3456/back?target=ID"
curl -s -X POST --data-raw 'https://example.com' "$BASE/navigate?target=ID"
curl -s "$BASE/back?target=ID"

# 点击（POST body 为 CSS 选择器）— JS el.click()，简单快速，覆盖大多数场景
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
curl -s -X POST "$BASE/click?target=ID" -d 'button.submit'

# 真实鼠标点击 — CDP Input.dispatchMouseEvent，算用户手势，能触发文件对话框
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
# 真实鼠标点击 — 浏览器级鼠标事件，算用户手势，能触发文件对话框
curl -s -X POST "$BASE/clickAt?target=ID" -d 'button.upload'

# 文件上传 — 直接设置 file input 的本地文件路径，绕过文件对话框
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'
curl -s -X POST "$BASE/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'

# 滚动（触发懒加载）
curl -s "http://localhost:3456/scroll?target=ID&y=3000"
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
curl -s "$BASE/scroll?target=ID&y=3000"
curl -s "$BASE/scroll?target=ID&direction=bottom"

# 关闭 tab
curl -s "http://localhost:3456/close?target=ID"
curl -s "$BASE/close?target=ID"
```

### 页面内导航
Expand Down Expand Up @@ -261,5 +285,6 @@ updated: 2026-03-19

| 文件 | 何时加载 |
|------|---------|
| `references/browser-extension.md` | 需要扩展后端安装、端口、能力边界或安全说明时 |
| `references/cdp-api.md` | 需要 CDP API 详细参考、JS 提取模式、错误处理时 |
| `references/site-patterns/{domain}.md` | 确定目标网站后，读取对应站点经验 |
Loading