gemini-web 1.0.0__tar.gz

gemini_web-1.0.0/.env.example

@@ -0,0 +1,17 @@
+# 瀏覽器
+HEADLESS=false
+# PROFILE_DIR=~/.gemini-web/profiles  # 預設值，通常不需要改
+GEMINI_URL=https://gemini.google.com/app
+
+# Stealth
+STEALTH_LANGUAGE=zh-TW,zh,en-US,en
+STEALTH_TIMEZONE=Asia/Taipei
+
+# 服務
+HOST=0.0.0.0
+PORT=8070
+QUEUE_MAX_SIZE=10
+DEFAULT_TIMEOUT=180
+
+# 心跳
+HEARTBEAT_INTERVAL=300

gemini_web-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gemini_web-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

gemini_web-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.env
+profiles/
+*.egg-info/
+dist/
+.venv/
+logs/
+bin/

gemini_web-1.0.0/AGENTS.md

@@ -0,0 +1,101 @@
+# Gemini Image — AI Agent 使用指引
+
+本工具讓 AI Agent 能透過 Gemini 網頁版進行**文字對話**和**圖片生成**（含自動去水印）。
+
+## 前置需求
+
+確認 `gemini-web` 已安裝且已登入：
+
+```bash
+gemini-web health  # API 模式：檢查服務是否運行
+# 或
+which gemini-web   # CLI 模式：確認指令存在
+```
+
+## 使用方式
+
+### 文字對話
+
+```bash
+# CLI
+gemini-web chat "<prompt>"
+
+# HTTP API
+curl -X POST http://localhost:8070/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "<prompt>"}'
+```
+
+回傳 JSON：`{"success": true, "text": "..."}`
+
+### 圖片生成
+
+```bash
+# CLI
+gemini-web generate "<prompt>" -o <output_path> --no-watermark
+
+# HTTP API
+curl -X POST http://localhost:8070/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "<prompt>"}'
+```
+
+回傳 JSON：`{"success": true, "images": ["data:image/png;base64,..."]}`
+
+### 參數說明
+
+- `<prompt>`：圖片描述，**建議用英文**效果最好
+- `-o`：輸出檔案路徑（支援 .png / .jpg）
+- `--no-watermark`：移除 Gemini 水印（建議始終加上）
+- 文字對話耗時約 5-30 秒，圖片生成約 30-120 秒
+
+## Prompt 撰寫規則
+
+**重要：不要原封不動轉發用戶的請求。** 你應該：
+
+1. 理解用戶意圖
+2. 擴寫為詳細的英文 prompt
+3. 描述主體、風格、構圖、色彩、氛圍
+4. 如果需要圖片中出現中文文字，用引號標明：`with text "歡迎光臨"`
+
+### 範例
+
+用戶說「畫一隻貓」→ 你應該送：
+```
+A cute fluffy orange tabby cat sitting on a windowsill, warm afternoon sunlight streaming in, cozy atmosphere, soft watercolor illustration style, gentle expression with bright curious eyes
+```
+
+用戶說「做一張開幕海報」→ 你應該送：
+```
+A modern grand opening poster design with bold typography showing text "盛大開幕" at the top, celebratory confetti and ribbons, red and gold color scheme, professional marketing design, clean layout
+```
+
+## 錯誤處理
+
+| 錯誤 | 意義 | 建議 |
+|------|------|------|
+| `content_blocked` | Gemini 拒絕生成 | 換一個不涉及敏感內容的 prompt |
+| `no_image` | 沒有生成圖片 | prompt 更具體，確認包含「draw」「generate」等關鍵字 |
+| `no_response` | 文字對話無回應 | 稍後再試 |
+| `timeout` | 生成超時 | 稍後再試 |
+| `browser_error` | 瀏覽器問題 | 檢查 `gemini-web health` |
+
+## 安裝（如果尚未安裝）
+
+> ⚠️ **不要用 `pip install`** — 必須用 uv 或 pipx，否則 Playwright 安裝會失敗。
+
+```bash
+# 1. 安裝 uv（如果還沒有）
+# macOS / Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows PowerShell:
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 2. 安裝 gemini-web + Chromium
+uv tool install gemini-web && gemini-web install
+
+# 3. 登入 Google（⚠️ 此步驟需要人類手動操作，會彈出瀏覽器）
+gemini-web login
+```
+
+如果之前用 pip 裝過，先移除：`pip uninstall gemini-web -y`

gemini_web-1.0.0/CLAUDE.md

@@ -0,0 +1,21 @@
+# CLAUDE.md
+
+## 發佈流程
+
+不要用 `uv publish` 手動發佈。本專案使用 GitHub Release 觸發自動發佈：
+
+1. bump `pyproject.toml` 中的 version
+2. commit + push
+3. 在 GitHub 上建立 Release（tag 格式：`v0.4.0`）
+4. GitHub Actions（`.github/workflows/publish.yml`）自動 build + publish 到 PyPI
+
+## 開發
+
+```bash
+uv sync --extra dev
+uv run python -m pytest -v
+```
+
+## 安裝方式
+
+必須用 `uv tool install` 或 `pipx install`，不要用 `pip install`。

gemini_web-1.0.0/GEMINI.md

@@ -0,0 +1,93 @@
+# Gemini Image — AI Agent 使用指引
+
+本工具讓 AI Agent 能透過 Gemini 網頁版進行**文字對話**和**圖片生成**（含自動去水印）。
+
+## 安裝
+
+> **不要用 `pip install`** — 必須用 uv 或 pipx，否則 Playwright 安裝會失敗。
+
+```bash
+# 1. 安裝 uv（如果還沒有）
+# macOS / Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows PowerShell:
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 2. 安裝 gemini-web + Chromium
+uv tool install gemini-web && gemini-web install
+
+# 3. 登入 Google（需要人類手動操作，會彈出瀏覽器）
+gemini-web login
+```
+
+如果之前用 pip 裝過，先移除：`pip uninstall gemini-web -y`
+
+## 確認安裝成功
+
+```bash
+which gemini-web       # 確認指令存在
+gemini-web health      # API 模式：檢查服務是否運行
+```
+
+## 使用方式
+
+### 文字對話
+
+```bash
+# CLI
+gemini-web chat "<prompt>"
+
+# HTTP API
+curl -X POST http://localhost:8070/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "<prompt>"}'
+```
+
+回傳 JSON：`{"success": true, "text": "..."}`
+
+### 圖片生成
+
+```bash
+# CLI
+gemini-web generate "<prompt>" -o <output_path> --no-watermark
+
+# HTTP API
+curl -X POST http://localhost:8070/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "<prompt>"}'
+```
+
+回傳 JSON：`{"success": true, "images": ["data:image/png;base64,..."]}`
+
+- 文字對話耗時約 5-30 秒，圖片生成約 30-120 秒
+
+## Prompt 撰寫規則
+
+**重要：不要原封不動轉發用戶的請求。** 你應該：
+
+1. 理解用戶意圖
+2. 擴寫為詳細的英文 prompt
+3. 描述主體、風格、構圖、色彩、氛圍
+4. 如果需要圖片中出現中文文字，用引號標明：`with text "歡迎光臨"`
+
+### 範例
+
+用戶說「畫一隻貓」→ 你應該送：
+```
+A cute fluffy orange tabby cat sitting on a windowsill, warm afternoon sunlight streaming in, cozy atmosphere, soft watercolor illustration style, gentle expression with bright curious eyes
+```
+
+用戶說「做一張開幕海報」→ 你應該送：
+```
+A modern grand opening poster design with bold typography showing text "盛大開幕" at the top, celebratory confetti and ribbons, red and gold color scheme, professional marketing design, clean layout
+```
+
+## 錯誤處理
+
+| 錯誤 | 意義 | 建議 |
+|------|------|------|
+| `content_blocked` | Gemini 拒絕生成 | 換一個不涉及敏感內容的 prompt |
+| `no_image` | 沒有生成圖片 | prompt 更具體，確認包含「draw」「generate」等關鍵字 |
+| `no_response` | 文字對話無回應 | 稍後再試 |
+| `timeout` | 生成超時 | 稍後再試 |
+| `browser_error` | 瀏覽器問題 | 檢查 `gemini-web health` |

gemini_web-1.0.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: gemini-web
+Version: 1.0.0
+Summary: Gemini 網頁版自動化 — 文字對話、圖片生成、Google GenAI API 相容
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10.0
+Requires-Dist: playwright>=1.49
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

gemini_web-1.0.0/README.md

@@ -0,0 +1,283 @@
+# Gemini Image
+
+> **快速安裝：** `uv tool install gemini-web && gemini-web install`
+
+使用 Playwright 自動化 Gemini 網頁版，提供**圖片生成**和**文字對話**功能。支援 **CLI 工具**和 **HTTP API** 兩種使用方式。
+
+自動移除 Gemini 可見水印（Reverse Alpha Blending，基於 [gemini-watermark-remover](https://github.com/journey-ad/gemini-watermark-remover)）。
+
+## 安裝
+
+> ⚠️ **不要用 `pip install`** — pip 不會建立隔離環境，會導致 Playwright 安裝失敗。請用 uv 或 pipx。
+
+```bash
+# 1. 安裝 uv（如果還沒有）
+curl -LsSf https://astral.sh/uv/install.sh | sh              # macOS / Linux
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
+
+# 2. 安裝 gemini-web
+uv tool install gemini-web && gemini-web install
+```
+
+備選方式（效果相同）：
+```bash
+pipx install gemini-web && gemini-web install
+```
+
+`gemini-web install` 會安裝 Chromium 瀏覽器（Playwright）。
+
+### 已經用 pip 裝過？
+
+```bash
+pip uninstall gemini-web -y
+uv tool install gemini-web && gemini-web install
+```
+
+## 首次登入 Google
+
+```bash
+gemini-web login
+```
+
+在彈出的瀏覽器中登入 Google 帳號，確認進入 Gemini 頁面，按 Enter 關閉。登入狀態存在 `~/.gemini-web/profiles/`，之後不需要重新登入。
+
+## 使用方式
+
+### CLI 工具
+
+```bash
+# 文字對話
+gemini-web chat "解釋量子力學"
+
+# 生成圖片（自動 headless）
+gemini-web generate "A cute cat sitting on a windowsill" -o cat.png
+
+# 生成 + 去水印
+gemini-web generate "A poster with text '歡迎光臨'" -o poster.png --no-watermark
+
+# 詳細 log
+gemini-web generate "畫一隻柴犬" -o shiba.png --no-watermark -v
+```
+
+Prompt 不含「畫」「draw」「generate」等關鍵字時，會自動加上 `Generate an image:` 前綴。
+
+### HTTP API
+
+```bash
+# 啟動服務
+gemini-web serve
+# 或
+gemini-web serve --host 0.0.0.0 --port 8070
+```
+
+API 模式自動去水印、自動下載原尺寸圖片。
+
+#### POST /api/chat
+
+```bash
+curl -X POST http://localhost:8070/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "解釋量子力學"}'
+```
+
+回傳：
+
+```json
+{
+  "success": true,
+  "text": "量子力學是...",
+  "prompt": "...",
+  "elapsed_seconds": 8.3
+}
+```
+
+#### POST /api/generate
+
+```bash
+curl -X POST http://localhost:8070/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "畫一張台北101海報"}'
+```
+
+回傳：
+
+```json
+{
+  "success": true,
+  "images": ["data:image/png;base64,..."],
+  "prompt": "...",
+  "elapsed_seconds": 45.2
+}
+```
+
+#### POST /v1beta/models/{model}:generateContent（Google GenAI API 相容）
+
+完全相容 `google-genai` SDK 格式，可做為 Google Gemini API 的 drop-in replacement。
+
+```bash
+# 文字對話
+curl -X POST "http://localhost:8070/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"contents": [{"parts": [{"text": "什麼是量子力學"}]}]}'
+
+# 圖片生成
+curl -X POST "http://localhost:8070/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"contents": [{"parts": [{"text": "a cute cat"}]}], "generationConfig": {"responseMimeType": "image/png"}}'
+```
+
+回傳格式與 Google API 完全一致：
+
+```json
+{
+  "candidates": [{
+    "content": {
+      "parts": [{"text": "量子力學是..."}],
+      "role": "model"
+    },
+    "finishReason": "STOP"
+  }]
+}
+```
+
+搭配 `google-genai` SDK 使用：
+
+```python
+from google import genai
+client = genai.Client(
+    api_key="YOUR_KEY",
+    http_options={"api_version": "v1beta", "base_url": "http://localhost:8070"}
+)
+response = client.models.generate_content(model="gemini-2.5-flash", contents="Hello")
+print(response.text)
+```
+
+#### GET /api/health
+
+```json
+{
+  "status": "ok",
+  "browser_alive": true,
+  "logged_in": true,
+  "queue_size": 0,
+  "uptime_seconds": 3600
+}
+```
+
+#### POST /api/new-chat
+
+手動重置 Gemini 對話（除錯用）。
+
+### systemd 服務部署
+
+```bash
+sudo bash scripts/install-service.sh
+```
+
+## 去水印
+
+使用 **Reverse Alpha Blending** 演算法，數學精確還原被水印覆蓋的像素：
+
+```
+original = (watermarked - alpha × logo) / (1 - alpha)
+```
+
+- 純 Python 實作（Pillow + NumPy），跨平台
+- 大圖（寬高 > 1024）：96×96 水印，64px 邊距
+- 小圖：48×48 水印，32px 邊距
+- API 模式自動去水印
+- CLI 模式加 `--no-watermark`
+- 不可見的 SynthID 浮水印無法移除
+
+基於 [gemini-watermark-remover](https://github.com/journey-ad/gemini-watermark-remover) 和 [Python 版本](https://github.com/VimalMollyn/Gemini-Watermark-Remover-Python)。
+
+## AI Agent 整合
+
+讓你的 AI Agent 能用 `/gemini-web` 指令生圖。
+
+### 安裝（一行搞定）
+
+> ⚠️ **不要用 `pip install`**，必須用 uv 或 pipx。
+
+```bash
+uv tool install gemini-web && gemini-web install
+```
+
+`gemini-web install` 會自動：
+1. 安裝 Chromium 瀏覽器（Playwright）
+2. 偵測 Claude Code（`~/.claude/`）→ 安裝 slash commands
+3. 偵測 Gemini CLI（`~/.gemini/`）→ 安裝 slash commands
+
+安裝後可用：`/gemini-web <自然語言描述>`、`/generate <英文 prompt>`、`/chat <提問>`
+
+### 登入（需人工操作）
+
+```bash
+gemini-web login
+```
+
+會彈出瀏覽器，手動登入 Google 帳號後按 Enter 關閉。登入狀態存在 `~/.gemini-web/profiles/`。
+
+### 支援的 AI Agent
+
+| Agent | 自動支援 | 說明 |
+|-------|:--------:|------|
+| **Claude Code** | ✓ | install 自動安裝 commands 到 `~/.claude/commands/gemini-web/` |
+| **Gemini CLI** | ✓ | install 自動安裝 commands 到 `~/.gemini/commands/gemini-web/` |
+| **Cursor / Windsurf** | — | 把 `AGENTS.md` 內容加入 rules 設定 |
+| **其他 Agent** | — | 讓 Agent 讀取 `AGENTS.md` 作為系統指引 |
+
+### CLI 呼叫
+
+```bash
+gemini-web generate "detailed english prompt" -o /path/to/output.png --no-watermark
+```
+
+### HTTP API
+
+```python
+import httpx
+resp = httpx.post("http://localhost:8070/api/generate", json={"prompt": "..."}, timeout=200)
+data = resp.json()
+if data["success"]:
+    images = data["images"]  # base64 list
+```
+
+## 環境變數
+
+| 變數 | 說明 | 預設 |
+|------|------|------|
+| `HEADLESS` | 無頭模式 | `false`（CLI generate 強制 `true`） |
+| `PROFILE_DIR` | 瀏覽器 session 目錄 | `~/.gemini-web/profiles` |
+| `GEMINI_URL` | Gemini 網址 | `https://gemini.google.com/app` |
+| `PORT` | API 服務埠 | `8070` |
+| `DEFAULT_TIMEOUT` | 生圖超時秒數 | `180` |
+| `QUEUE_MAX_SIZE` | 最大排隊數 | `10` |
+| `API_KEYS` | API 金鑰（逗號分隔多組，空 = 不驗證） | 無 |
+
+## 從原始碼安裝
+
+```bash
+git clone https://github.com/yazelin/gemini-web.git
+cd gemini-web
+bash scripts/setup.sh
+```
+
+## 開發
+
+```bash
+uv sync --extra dev
+uv run pytest -v
+```
+
+## 已知限制
+
+- 一次只能處理一個請求（生圖或對話，其他排隊等待）
+- Google 登入過期需手動重新登入（`gemini-web login`）
+- Gemini 改版可能導致 DOM selector 失效，需更新 `src/selectors.py`
+- 違反 Google 服務條款，帳號有被封風險
+- 生圖耗時約 30-120 秒，視 Gemini 伺服器負載而定
+
+## 授權
+
+MIT License