docs: 新增 README.en.md 英文文档，更新 README.md 语言切换链接
This commit is contained in:
WJZ_P
263
README.en.md
Normal file
263
README.en.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Gemini Skill
|
||||
|
||||
English | [中文](./README.md)
|
||||
|
||||
Automate Gemini web (gemini.google.com) via CDP (Chrome DevTools Protocol) — AI image generation, conversations, image extraction, and more.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- 🎨 **AI Image Generation** — Send prompts to generate images, with full-size high-res download support
|
||||
- 💬 **Text Conversations** — Multi-turn dialogue with Gemini
|
||||
- 🖼️ **Image Upload** — Upload reference images for image-to-image generation
|
||||
- 📥 **Image Extraction** — Extract images from sessions via base64 or CDP full-size download
|
||||
- 🔄 **Session Management** — New chat, temp chat, model switching, navigate to historical sessions
|
||||
- 🧹 **Auto Watermark Removal** — Downloaded images automatically have the Gemini watermark stripped
|
||||
- 🤖 **MCP Server** — Standard MCP protocol interface, callable by any MCP client (Claude, CodeBuddy, etc.)
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ MCP Client (AI) │
|
||||
│ Claude / CodeBuddy / ... │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│ stdio (JSON-RPC)
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ mcp-server.js (MCP Protocol Layer) │
|
||||
│ Registers all MCP tools, orchestrates │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ index.js → browser.js (Connection Layer) │
|
||||
│ ensureBrowser() → auto-start Daemon → CDP link │
|
||||
└──────────┬──────────────────────────────┬───────────┘
|
||||
│ HTTP (acquire/status) │ WebSocket (CDP)
|
||||
▼ ▼
|
||||
┌──────────────────────┐ ┌─────────────────────────┐
|
||||
│ Browser Daemon │ │ Chrome / Edge │
|
||||
│ (standalone process)│───▶│ gemini.google.com │
|
||||
│ daemon/server.js │ │ │
|
||||
│ ├─ engine.js │ │ Stealth + anti-detect │
|
||||
│ ├─ handlers.js │ └─────────────────────────┘
|
||||
│ └─ lifecycle.js │
|
||||
│ 30-min idle TTL │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
**Core Design Principles:**
|
||||
|
||||
- **Daemon Mode** — The browser process is managed by a standalone Daemon. After MCP calls finish, the browser stays alive; it auto-terminates only after 30 minutes of inactivity.
|
||||
- **On-demand Auto-start** — If the Daemon isn't running, MCP tools will automatically spawn it. No manual startup required.
|
||||
- **Stealth Anti-detect** — Uses `puppeteer-extra-plugin-stealth` to bypass website bot detection.
|
||||
- **Separation of Concerns** — `mcp-server.js` (protocol) → `gemini-ops.js` (operations) → `browser.js` (connection) → `daemon/` (process management)
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js** ≥ 18
|
||||
- **Chrome / Edge / Chromium** — Any one of these must be installed on your system (or specify a path via `BROWSER_PATH`)
|
||||
- The browser must be **logged into a Google account** beforehand (Gemini requires authentication)
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourname/gemini-skill.git
|
||||
cd gemini-skill
|
||||
npm install
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
All configuration is done via environment variables or a `.env` file. Create a `.env` file in the project root:
|
||||
|
||||
```env
|
||||
# Browser executable path (auto-detects Chrome/Edge/Chromium if unset)
|
||||
# BROWSER_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe
|
||||
|
||||
# CDP remote debugging port (default: 40821)
|
||||
# BROWSER_DEBUG_PORT=40821
|
||||
|
||||
# Headless mode (default: false — keep it off for first-time login)
|
||||
# BROWSER_HEADLESS=false
|
||||
|
||||
# Image output directory (default: ./gemini-image)
|
||||
# OUTPUT_DIR=./gemini-image
|
||||
|
||||
# Daemon HTTP port (default: 40225)
|
||||
# DAEMON_PORT=40225
|
||||
|
||||
# Daemon idle timeout in ms (default: 30 minutes)
|
||||
# DAEMON_TTL_MS=1800000
|
||||
```
|
||||
|
||||
`.env.development` is also supported (takes priority over `.env`).
|
||||
|
||||
**Priority order:** `process.env` > `.env.development` > `.env` > code defaults
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Option 1: As an MCP Server (Recommended)
|
||||
|
||||
Add the following to your MCP client configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "node",
|
||||
"args": ["<absolute-path-to-project>/src/mcp-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Once started, the AI can invoke all tools via the MCP protocol.
|
||||
|
||||
### Option 2: Command Line
|
||||
|
||||
```bash
|
||||
# Start MCP Server (stdio mode, for AI clients)
|
||||
npm run mcp
|
||||
|
||||
# Start Browser Daemon standalone (usually unnecessary — MCP auto-starts it)
|
||||
npm run daemon
|
||||
|
||||
# Run the demo
|
||||
npm run demo
|
||||
```
|
||||
|
||||
### Option 3: As a Library
|
||||
|
||||
```javascript
|
||||
import { createGeminiSession, disconnect } from './src/index.js';
|
||||
|
||||
const { ops } = await createGeminiSession();
|
||||
|
||||
// Generate an image
|
||||
const result = await ops.generateImage('Draw a cute cat', { fullSize: true });
|
||||
console.log('Image saved to:', result.filePath);
|
||||
|
||||
// Disconnect when done (browser stays alive, managed by Daemon)
|
||||
disconnect();
|
||||
```
|
||||
|
||||
## 🔧 MCP Tools
|
||||
|
||||
### Image Generation
|
||||
|
||||
| Tool | Description | Key Parameters |
|
||||
|------|-------------|----------------|
|
||||
| `gemini_generate_image` | Full image generation pipeline (takes 60–120s) | `prompt`, `newSession`, `referenceImages`, `fullSize`, `timeout` |
|
||||
|
||||
### Session Management
|
||||
|
||||
| Tool | Description | Key Parameters |
|
||||
|------|-------------|----------------|
|
||||
| `gemini_new_chat` | Start a new blank conversation | — |
|
||||
| `gemini_temp_chat` | Enter temporary chat mode (no history saved) | — |
|
||||
| `gemini_navigate_to` | Navigate to a specific Gemini URL (e.g. a saved session) | `url`, `timeout` |
|
||||
|
||||
### Model & Conversation
|
||||
|
||||
| Tool | Description | Key Parameters |
|
||||
|------|-------------|----------------|
|
||||
| `gemini_switch_model` | Switch model (pro / quick / think) | `model` |
|
||||
| `gemini_send_message` | Send text and wait for reply (takes 10–60s) | `message`, `timeout` |
|
||||
|
||||
### Image Operations
|
||||
|
||||
| Tool | Description | Key Parameters |
|
||||
|------|-------------|----------------|
|
||||
| `gemini_upload_images` | Upload images to the input box | `images` |
|
||||
| `gemini_get_images` | List all images in the current session (metadata only) | — |
|
||||
| `gemini_extract_image` | Extract image base64 data and save locally | `imageUrl` |
|
||||
| `gemini_download_full_size_image` | Download full-size high-res image | `index` |
|
||||
|
||||
### Text Responses
|
||||
|
||||
| Tool | Description | Key Parameters |
|
||||
|------|-------------|----------------|
|
||||
| `gemini_get_all_text_responses` | Get all text responses in the session | — |
|
||||
| `gemini_get_latest_text_response` | Get the latest text response | — |
|
||||
|
||||
### Diagnostics & Management
|
||||
|
||||
| Tool | Description | Key Parameters |
|
||||
|------|-------------|----------------|
|
||||
| `gemini_check_login` | Check Google login status | — |
|
||||
| `gemini_probe` | Probe page element states | — |
|
||||
| `gemini_reload_page` | Reload the page | `timeout` |
|
||||
| `gemini_browser_info` | Get browser connection info | — |
|
||||
|
||||
## 🔄 Daemon Lifecycle
|
||||
|
||||
```
|
||||
First MCP call
|
||||
│
|
||||
├─ Daemon not running → auto-spawn (detached + unref)
|
||||
│ → poll until ready (up to 15s)
|
||||
│
|
||||
├─ GET /browser/acquire → launch/reuse browser + reset 30-min countdown
|
||||
│
|
||||
├─ MCP tool finishes → disconnect() (closes WebSocket, keeps browser alive)
|
||||
│
|
||||
├─ Another call within 30 min → countdown resets (extends TTL)
|
||||
│
|
||||
└─ 30 min with no activity → close browser + stop HTTP server + exit process
|
||||
(next call will auto-respawn)
|
||||
```
|
||||
|
||||
**Daemon API Endpoints:**
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /browser/acquire` | Acquire browser connection (resets TTL) |
|
||||
| `GET /browser/status` | Query browser status (does NOT reset TTL) |
|
||||
| `POST /browser/release` | Manually destroy the browser |
|
||||
| `GET /health` | Daemon health check |
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
gemini-skill/
|
||||
├── src/
|
||||
│ ├── index.js # Unified entry point
|
||||
│ ├── mcp-server.js # MCP protocol server (registers all tools)
|
||||
│ ├── gemini-ops.js # Gemini page operations (core logic)
|
||||
│ ├── operator.js # Low-level DOM operation wrappers
|
||||
│ ├── browser.js # Browser connector (Skill-facing)
|
||||
│ ├── config.js # Centralized configuration
|
||||
│ ├── util.js # Utility functions
|
||||
│ ├── watermark-remover.js # Image watermark removal (via sharp)
|
||||
│ ├── demo.js # Usage examples
|
||||
│ ├── assets/ # Static assets
|
||||
│ └── daemon/ # Browser Daemon (standalone process)
|
||||
│ ├── server.js # HTTP micro-service entry
|
||||
│ ├── engine.js # Browser engine (launch/connect/terminate)
|
||||
│ ├── handlers.js # API route handlers
|
||||
│ └── lifecycle.js # Lifecycle control (lazy shutdown timer)
|
||||
├── references/ # Reference documentation
|
||||
├── SKILL.md # AI invocation spec (read by MCP clients)
|
||||
├── package.json
|
||||
└── .env # Environment config (create manually)
|
||||
```
|
||||
|
||||
## ⚠️ Notes
|
||||
|
||||
1. **First-time login required** — On the first run, the browser will open the Gemini page. Complete Google account login manually. Login state is persisted in `userDataDir`, so subsequent runs won't require re-login.
|
||||
|
||||
2. **Single instance only** — Only one browser instance can use a given CDP port. Running multiple instances will cause port conflicts.
|
||||
|
||||
3. **Windows Server considerations** — Path normalization and Safe Browsing bypass are built-in, but double-check:
|
||||
- Chrome/Edge is properly installed
|
||||
- The output directory is writable
|
||||
- The firewall is not blocking localhost traffic
|
||||
|
||||
4. **Image generation takes time** — Typically 60–120 seconds. Set your MCP client's `timeoutMs` to ≥ 180000 (3 minutes).
|
||||
|
||||
## 📄 License
|
||||
|
||||
ISC
|
||||
Reference in New Issue
Block a user