# tmwebdriver-go

**Repository Path**: cfh008/tmwebdriver-go

## Basic Information

- **Project Name**: tmwebdriver-go
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tmwebdriver-go

Go 语言重写的浏览器控制守护进程，参考 **[GenericAgent](https://github.com/lsdefine/GenericAgent)**
的 Chrome 浏览器自动化功能，以单一二进制形式独立发布。

## 与 GenericAgent 的关系

GenericAgent 是一个 Python 自主 Agent 框架，其浏览器控制能力由以下组件构成：

- `TMWebDriver.py` — WebSocket + HTTP 双通道服务端，管理浏览器标签页会话
- `assets/tmwd_cdp_bridge/` — Chrome MV3 扩展，注入用户浏览器实现 CDP 桥接
- `simphtml.py` — HTML 优化、DOM diff、智能截断

本项目用 **Go 语言完整重写**上述三个组件，消除 Python 运行时依赖，编译为 ~10MB 单一二进制。

## 特性

| | Python 版 (GenericAgent) | Go 版 (本项目) |
|---|---|---|
| **运行时** | Python 3.10+ + venv + 5 个 pip 包 | 无，单一静态链接二进制 |
| **分发** | `pip install` | 下载即用 |
| **HTML 处理** | BeautifulSoup4 | goquery（纯 Go） |
| **WS 库** | simple-websocket-server (select) | gorilla/websocket (epoll/kqueue) |
| **HTTP 服务** | bottle + wsgiref | net/http 标准库 |
| **并发模型** | threading + GIL | goroutine + channel |

## 快速开始

### 安装

从 [Gitee Releases](https://gitee.com/cfh008/tmwebdriver-go/releases) 下载对应平台的安装包，解压后按以下步骤安装。

```bash
# 下载二进制（Windows / Linux / macOS 均提供）
# 放到 PATH 目录，或运行安装脚本：
# Windows
powershell -ExecutionPolicy Bypass -File install.ps1

# Linux
bash install.sh

# macOS
bash install_mac.sh

# （可选）注册为系统服务，开机自启：
# Windows
powershell -ExecutionPolicy Bypass -File install.ps1 -Service

# Linux
sudo bash install.sh --service

# macOS
bash install_mac.sh --service
```

### 安装 Chrome 扩展

```bash
tmwebdriver-go install-ext
# 扩展输出到 ~/.tmwebdriver/extension/
```

Chrome → `chrome://extensions/` → 开发者模式 → 加载已解压 → 选择上述目录。

### 启动

```bash
tmwebdriver-go start
# WS:  ws://127.0.0.1:18865
# HTTP: http://127.0.0.1:18866
```

### 调用

```bash
# CLI
tmwebdriver-go status
tmwebdriver-go exec "document.title"
tmwebdriver-go scan
tmwebdriver-go rich-exec "document.querySelector('#btn').click()"

# HTTP API
curl http://127.0.0.1:18866/api/status
curl -X POST http://127.0.0.1:18866/link \
  -H "Content-Type: application/json" \
  -d '{"cmd":"execute_js","code":"document.title","timeout":"10"}'
```

## API 端点

| 端点 | 方法 | 用途 |
|---|---|---|
| `/link` | POST | 远程命令代理（execute_js / get_all_sessions / find_session） |
| `/api/status` | GET | 服务状态 + 会话列表 |
| `/api/longpoll` | POST | 浏览器 HTTP 长轮询 |
| `/api/result` | POST | 结果投递 |
| `/api/v1/optimize-html` | POST | HTML 优化 |
| `/api/v1/smart-truncate` | POST | DOM 树 budget 截断 |
| `/api/v1/diff` | POST | HTML 变化检测 |
| `/api/v1/rich-execute` | POST | 一站式 execute + diff |

## AI Agent 使用指南

tmwebdriver-go 为任何支持 HTTP 工具调用的 AI Agent 提供了完整的浏览器控制能力。
Agent 通过 HTTP API 调用，无需安装 SDK 或依赖特定框架。

### 前置条件

```bash
# 1. 启动服务
tmwebdriver-go start

# 2. 确保 Chrome 扩展已加载且浏览器有打开页面
curl http://127.0.0.1:18866/api/status | grep sessions
```

### 基本工具调用

Agent 直接使用 HTTP 工具向 `http://127.0.0.1:18866` 发送 JSON 请求：

#### 列出标签页
```http
POST /link
{"cmd":"get_all_sessions"}
```
返回：`{"r":[{"id":"123","url":"https://example.com","type":"ext_ws","title":""}]}`

#### 执行 JavaScript
```http
POST /link
{"cmd":"execute_js", "code":"document.title", "timeout":15}
```
返回：`{"r":"My Page Title"}`

#### 查找标签页
```http
POST /link
{"cmd":"find_session", "url_pattern":"github"}
```
返回匹配的 session ID 和 URL。

#### 获取优化后的 HTML
```http
# 步骤 1: 获取原始 HTML
POST /link
{"cmd":"execute_js", "code":"document.documentElement.outerHTML"}

# 步骤 2: 优化 HTML
POST /api/v1/optimize-html
{"html":"<raw HTML from step 1>"}

# 步骤 3: 如需截断
POST /api/v1/smart-truncate
{"html":"<optimized HTML>", "budget":35000}
```

### 典型 Agent 工作流

#### 工作流 1：打开页面 → 点击 → 读取

```
1. POST /api/status                          → 确认服务在线及标签页列表
2. POST /link {"cmd":"execute_js","code":"location.href='https://target.com'","sessionId":"123"}
3. POST /link {"cmd":"execute_js","code":"document.querySelector('#btn').click()","sessionId":"123"}
4. POST /link {"cmd":"execute_js","code":"document.querySelector('.result').innerText","sessionId":"123"}
```

#### 工作流 2：获取页面 → 操作 → 检测变化

```
1. POST /link {"cmd":"execute_js","code":"document.documentElement.outerHTML"}
   → 保存原始 HTML
2. POST /api/v1/optimize-html {"html":"<raw>"}
   → 保存优化后 HTML
3. POST /link {"cmd":"execute_js","code":"...操作 JS..."}
4. POST /link {"cmd":"execute_js","code":"document.documentElement.outerHTML"}
   → 获取操作后 HTML
5. POST /api/v1/diff {"before":"<before>","after":"<after>"}
   → 返回 changed 数量 + top_change
```

#### 工作流 3：CDP 截图

```
POST /link {"cmd":"execute_js","code":"{\"cmd\":\"cdp\",\"method\":\"Page.captureScreenshot\",\"params\":{\"format\":\"png\"}}"}
→ 返回 base64 PNG
```

### CDP 桥协议

通过 `execute_js` 传递 JSON 字符串可调用 Chrome DevTools Protocol：

| 命令 | 示例 |
|---|---|
| 截图 | `{"cmd":"cdp","method":"Page.captureScreenshot","params":{"format":"png"}}` |
| 获取 Cookie | `{"cmd":"cookies"}` |
| 创建标签页 | `{"cmd":"tabs","method":"create","url":"https://...","active":false}` |
| 切换标签页 | `{"cmd":"tabs","method":"switch","tabId":123}` |
| 批量命令 | `{"cmd":"batch","commands":[{"cmd":"cookies"},{"cmd":"cdp",...}]}` |
| 绕过下载拦截 | `{"cmd":"contentSettings","type":"automaticDownloads","setting":"allow"}` |

CDP 点击需三事件序列：`mouseMoved → mousePressed → mouseReleased`，间隔 50-100ms。

### 工具描述（供 Agent 集成）

`docs/tmwebdriver-go-tools.json` 定义了 12 个 Agent 工具，可直接追加到 Agent 的 tools/functions schema 中调用。
安装包内附带该文件，或从仓库直接获取。

详见 [AI Agent 操作 SOP](docs/tmwebdriver_go_sop.md#http-api-工具映射)。

### 完整 SOP 参考

详细的 AI Agent 操作手册参见 [AI Agent 操作 SOP](docs/tmwebdriver_go_sop.md)，包含：
- 完整 API 参数说明
- CDP 高级用法（iframe、Shadow DOM 穿透）
- 故障排查流程
- 与 Python 版差异对照


## 项目结构

```
tmwebdriver-go/
├── main.go              # CLI 入口 (start / install-ext / exec / scan / rich-exec / status / version)
├── install.go           # Chrome 扩展安装 (embed.FS)
├── Makefile             # Go 编译（ldflags 注入版本号）
├── install.ps1          # Windows 安装脚本
├── install.sh           # Linux 安装脚本
├── install_mac.sh       # macOS 安装脚本
├── uninstall.ps1        # Windows 卸载脚本
├── install_test.go      # 安装功能测试
├── compare_verify.py    # Python/Go 行为一致性验证脚本
├── reasonix.toml        # 项目配置文件
├── version/
│   └── version.go       # 版本号变量（ldflags 注入点）
├── scripts/
│   ├── release.py             # 发行版一键打包+上传
│   ├── release-notes-template.md
│   ├── skill-frontmatter.txt
│   └── ...
├── docs/                # 文档目录
├── driver/
│   ├── session.go       # Session 管理 (sync.RWMutex)
│   ├── session_test.go
│   ├── execute.go       # JS 执行调度 (chan + timeout + ACK)
│   └── execute_test.go
├── server/
│   ├── ws.go            # WebSocket 服务 (gorilla/websocket)
│   ├── ws_test.go
│   ├── ws_execute_test.go
│   ├── ws_disconnect_test.go
│   ├── http.go          # HTTP API (net/http)
│   └── http_test.go
├── simphtml/
│   ├── optimize.go      # HTML 属性清洗
│   ├── optimize_test.go
│   ├── truncate.go      # DOM 树智能截断
│   ├── truncate_test.go
│   ├── diff.go          # HTML 变化检测
│   ├── diff_test.go
│   ├── processor.go     # rich-execute 流水线
│   └── processor_test.go
└── extension/           # Chrome MV3 扩展 (embed.FS)
    ├── manifest.json
    ├── background.js     # CDP 桥 + 标签页管理
    ├── content.js        # 内容脚本代理
    ├── disable_dialogs.js
    ├── config.js.tpl     # 配置模板
    ├── popup.html        # 扩展弹出页
    └── popup.js          # 弹出页逻辑
```

## 文档

- [AI Agent 操作 SOP](docs/tmwebdriver_go_sop.md)
- [详细操作流程](docs/tmwebdriver-go-sop-detailed.md)
- [发行版打包方案](docs/release-packaging-plan.md)
- [Gitee Release 发布指南](docs/gitee-release-publisher-skill.md)
- [部署指南 (Windows 10+ / Ubuntu 24 LTS+ / macOS 12+)](docs/deployment.md)
- [Go vs Python 架构对比](docs/go_binary_vs_python_pkg_analysis.md)
- [Go vs Python 功能一致性验证](docs/go_vs_python_verification.md)
- [Python → Go 重写：性能分析与决策](docs/python_vs_golanguage_perf_analysis.md)
- [TMWebDriver 剥离方案决策记录](docs/tmwebdriver_extraction_plan.md)
- [GenericAgent 浏览器控制能力分析](docs/GenericAgent_browser_control_analysis.md)
- [OCR 操作手册](docs/ocr-sop.md)

## 许可

MIT License

## 致谢

本项目参考了 [GenericAgent](https://github.com/lsdefine/GenericAgent) 的 Chrome 浏览器控制实现（TMWebDriver + CDP Bridge + simphtml）。