browser-relay

# Browser Relay Skill

通过 HTTP relay 控制用户本地 Chromium，用于操作会封锁数据中心 IP 的网站（如小红书）。

## 架构

```
AI → HTTP (port 18792) → relay.py → CDP (port 9222) → 用户本地 Chromium
```

所有请求从用户本地 IP 发出，绕过反爬。

## 安全说明

- relay 仅监听 `127.0.0.1`（localhost），不会暴露到外部网络
- 每次启动自动生成随机 auth token，所有 API 请求必须携带
- token 文件 (`/tmp/browser-relay-token`) 以 `0600` 权限写入，仅文件所有者可读
- `/evaluate` 端点允许在浏览器上下文中执行 JS，可访问 DOM、cookies、localStorage 等。仅限本地可信调用方使用，不应暴露给不受信任的客户端
- 建议在隔离环境（虚拟机、容器）中运行，使用专用浏览器 profile（不含敏感站点的登录态）
- `start.sh` 仅通过 PID 文件精确停止 relay 进程，不会影响其他进程

## Agent 行为约束

使用此 skill 的 agent 必须遵守以下规则：

### exec 使用范围

`exec` 仅允许用于以下操作：
- 向 `127.0.0.1:18792`（relay）和 `127.0.0.1:9222`（CDP）发送 HTTP 请求
- 运行 `start.sh` 启动/停止 relay
- 读取 `/tmp/browser-relay-token`
- 保存截图到 `./screenshots/`
- 通过 Telegram Bot API 发送截图（仅限用户明确要求时）

禁止使用 `exec` 执行上述范围之外的命令。

### /evaluate 使用范围

`/evaluate` 仅允许用于 UI 自动化目的：
- 查询 DOM 元素位置、文本内容、页面标题
- 等待元素加载、检查页面状态
- 模拟用户交互（滚动、表单填写）

**禁止**通过 `/evaluate` 提取以下敏感数据：
- `document.cookie`
- `localStorage` / `sessionStorage` 中的 token 或凭据
- 页面中的密码字段值
- 任何认证相关的 header 或 token

### 数据外发限制

- 仅允许向 Telegram Bot API 发送截图图片，且仅在用户明确要求时
- 禁止向任何外部端点发送从浏览器提取的文本数据、cookies、token 或凭据
- 禁止将浏览器敏感数据写入 session_state 或 memory（auth token 除外，指 relay 自身的 token）

## 文件位置

> 以下路径均相对于项目安装目录，请根据实际位置调整。

- Relay 代码: `./relay.py`
- 启动脚本: `./start.sh`
- Token 文件: `/tmp/browser-relay-token`
- PID 文件: `/tmp/browser-relay.pid`
- 日志: `/tmp/relay.log`
- 截图目录: `./screenshots/`

## 启动流程

每次会话开始使用 relay 前，按以下步...

# Browser Relay for Xiaohongshu

[![GitHub](https://img.shields.io/badge/GitHub-browser--relay--xiaohongshu-blue)](https://github.com/esojourn/browser-relay-xiaohongshu)

Lightweight HTTP relay that lets AI assistants control a local Chromium browser via Chrome DevTools Protocol (CDP), bypassing data center IP blocks from Chinese platforms like Xiaohongshu (小红书).

## Why This Exists

AI assistants typically run on cloud servers. Chinese platforms aggressively block data center IPs. This relay bridges the gap — the AI sends HTTP commands to a local relay server, which forwards them to your Chromium via CDP. All web requests originate from your local IP.

## Architecture

```
AI Agent → HTTP (port 18792) → relay.py → CDP WebSocket (port 9222) → Local Chromium
```

## Features

- **Full browser control**: navigate, click, type, scroll, screenshot, JS execution
- **Tab management**: create, switch, close tabs
- **DOM queries**: find elements by CSS selector, get coordinates
- **Screenshot to Telegram**: capture screenshots and send directly to Telegram via Bot API
- **Auth token**: auto-generated per session for security
- **Chromium auto-launch**: supports launching Chromium with correct flags

## Quick Start

### 1. Launch Chromium with remote debugging

```bash
chromium --remote-debugging-port=9222 --remote-allow-origins=*
```

> **Important**: `--remote-allow-origins=*` is required, otherwise WebSocket connections will be rejected.

### 2. Install dependencies and start relay

```bash
cd browser-relay
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python3 relay.py
```

Or use the launcher script:

```bash
bash start.sh          # start
bash start.sh restart  # restart
bash start.sh stop     # stop
```

### 3. Use the API

All endpoints require `Authorization: Bearer <token>` header. The token is auto-generated at startup and saved to `/tmp/browser-relay-token`.

```bash
TOKEN=$(cat /tmp/browser-relay-token)

# Health check
curl -...