可用工具

核心生图（封装完整流程）：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_generate_image | 完整生图流程：新建会话→发prompt→等待→提取图片→保存本地（耗时约 60~120 秒） | prompt，newSession（默认false），referenceImages（参考图路径数组），fullSize（默认true，高清原图；false则预览图），timeout（默认120000ms） |

会话管理：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_new_chat | 新建一个空白对话 | 无 | | gemini_temp_chat | 进入临时对话模式（不保留历史记录） | 无 |

模型切换：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_switch_model | 切换 Gemini 模型 | model（pro / quick / think） |

文本对话：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_send_message | 发送文本消息并等待回答完成，直接返回 Gemini 的回复文本 | message，timeout（默认120000ms） |

图片操作：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_upload_images | 上传图片到输入框（仅上传不发送，可配合 send_message） | images（路径数组） | | gemini_get_images | 获取会话中所有已加载图片的元信息 | 无 | | gemini_extract_image | 提取指定图片的 base64 并保存到本地 | imageUrl（从 get_images 获取） | | gemini_download_full_size_image | 下载完整尺寸的高清图片，默认最新一张，可指定索引 | index（可选，从0开始，从旧到新） | | gemini_share_latest_image | 为图片创建公开分享链接并直接返回链接，默认最新一张 | index（可选），timeout，copyToClipboard，closeDialog |

文字回复提取：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_get_all_text_responses | 获取会话中所有文字回复（仅文字，不含图片） | 无 | | gemini_get_latest_text_response | 获取最新一条文字回复 | 无 |

登录状态：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_check_login | 检查是否已登录 Google 账号 | 无 |

页面导航：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_navigate_to | 打开指定的 Gemini 页面 URL（如历史会话链接），仅允许 gemini.google.com 域名 | url（目标 URL），timeout（默认30000ms） |

诊断 & 恢复：

| 工具名 | 说明 | 入参 | |--------|------|------| | gemini_probe | 探测页面各元素状态（输入框、按钮、模型等） | 无 | | gemini_reload_page | 刷新页面（卡住或异常时使用） | timeout（默认30000ms） | | gemini_browser_info | 获取浏览器连接信息（CDP 端口、wsEndpoint 等） | 无 |

典型用法

快速生图（一步到位）：

1. 调用 gemini_generate_image，传入 prompt → 返回本地图片路径

生图并拿分享链接：

1. 调用 gemini_generate_image 生成图片
2. 调用 gemini_share_latest_image 返回公开链接

灵活组合（细粒度控制）：

1. gemini_new_chat — 新建会话
2. gemini_switch_model → pro — 切换到高质量模型
3. gemini_upload_images — 上传参考图
4. gemini_send_message — 发送描述词
5. gemini_get_images → gemini_extract_image — 获取并保存图片

排障：

1. gemini_probe — 看看页面元素有没有就位
2. gemini_reload_page — 页面卡了就刷新
3. gemini_browser_info — 获取 CDP 信息自行连接调试

MCP 客户端配置

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["<项目绝对路径>/src/mcp-server.js"]
    }
  }
}

也可通过 npm run mcp 手动启动。

失败处理

工具内部已包含重试逻辑。若仍然失败，返回值的 isError: true 和错误信息会告知原因：

• 生成超时 — 建议用户简化描述词后重试
• Daemon 未启动 — 工具会自动拉起，若仍失败可手动 npm run daemon
• 页面异常 — 可调用 gemini_browser_info 查看浏览器状态排查

参考

• 详细执行与回退：references/gemini-flow.md
• 关键词与路由：references/intent-routing.md

核心设计理念：

• Daemon 模式 — 浏览器进程由独立 Daemon 管理，MCP 调用结束后浏览器不关闭，30 分钟无活动才自动释放
• 按需自启 — Daemon 未运行时 MCP 工具会自动拉起，无需手动启动
• Stealth 反爬 — 使用 puppeteer-extra-plugin-stealth 绕过网站检测
• 职责分离 — mcp-server.js（协议层）→ gemini-ops.js（操作层）→ browser.js（连接层）→ daemon/（进程管理）

📦 安装

前置条件

• Node.js ≥ 18
• Chrome / Edge / Chromium — 系统上需安装任一浏览器（或通过 BROWSER_PATH 指定路径）
• 浏览器需提前 登录 Google 账号（Gemini 需要登录才能使用）

安装依赖

git clone https://github.com/WJZ-P/gemini-skill.git
cd gemini-skill
npm install

⚙️ 配置

所有配置通过环境变量或 .env 文件设置。项目根目录已提供 .env 模板，可直接修改。

配置优先级： process.env > .env.development > .env > 代码默认值

.env.development 不会被 git 追踪，适合存放本地私有配置（如浏览器路径）。

浏览器配置

| 变量 | 默认值 | 说明 | |------|--------|------| | BROWSER_PATH | 自动检测 | 浏览器可执行文件路径，支持 Chrome / Edge / Chromium。不设则自动按优先级检测系统已安装的浏览器 | | BROWSER_DEBUG_PORT | 40821 | CDP 远程调试端口。多个 skill（如 douyin-upload-mcp-skill）共享同一端口即共享同一浏览器实例 | | BROWSER_HEADLESS | false | 是否无头模式。首次使用建议关闭（false），方便登录 Google 账号 | | BROWSER_USER_DATA_DIR | 自动解析 | 浏览器用户数据目录，保存登录态、cookies 等。不设则自动解析：~/.wjz_browser_data → 浏览器默认目录 | | BROWSER_PROTOCOL_TIMEOUT | 60000 | CDP 协议超时时间（毫秒）。生图等长操作可适当增大 |

Daemon 配置

| 变量 | 默认值 | 说明 | |------|--------|------| | DAEMON_PORT | 40225 | Daemon HTTP 服务端口 | | DAEMON_TTL_MS | 1800000 | 闲置超时时间（毫秒），默认 30 分钟。超时后自动关闭浏览器并退出 Daemon，下次调用时自动重新拉起 |

其他配置

| 变量 | 默认值 | 说明 | |------|--------|------| | OUTPUT_DIR | ./gemini-image | 图片输出目录 |

关于 OpenClaw 浏览器复用

OpenClaw 的默认 CDP 端口是 18800。如果你希望复用 OpenClaw 已启动的浏览器会话，可以将 BROWSER_DEBUG_PORT 改为 18800：

BROWSER_DEBUG_PORT=18800

但请注意：OpenClaw 自带的浏览器会话没有集成 Stealth 反爬插件，在反检测能力上不如本项目自行维护的浏览器实例。本项目使用 puppeteer-extra-plugin-stealth 提供了完整的反爬保护（隐藏 webdriver 标记、模拟真实浏览器指纹等），能更好地规避网站的自动化检测。

建议：除非有特殊需求，推荐使用默认端口 40821，让项目自行管理浏览器实例以获得最佳的反爬效果。

🚀 使用

方式一：作为 MCP Server（推荐）

在 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["<项目绝对路径>/src/mcp-server.js"]
    }
  }
}

启动后 AI 即可通过 MCP 协议调用所有工具。

方式二：命令行启动

# 启动 MCP Server（stdio 模式，供 AI 客户端调用）
npm run mcp

# 单独启动 Browser Daemon（通常不需要，MCP 会自动拉起）
npm run daemon

# 运行 Demo 示例
npm run demo

方式三：作为库调用

import { createGeminiSession, disconnect } from './src/index.js';

const { ops } = await createGeminiSession();

// 生图
const result = await ops.generateImage('画一只可爱的猫咪', { fullSize: true });
console.log('图片保存至:', result.filePath);

// 用完断开（不关浏览器，由 Daemon 继续守护）
disconnect();

🔧 MCP 工具列表

核心生图

| 工具名 | 说明 | 主要参数 | |--------|------|----------| | gemini_generate_image | 完整生图流程（耗时 60~120s） | prompt, newSession, referenceImages, fullSize, timeout |

会话管理

| 工具名 | 说明 | 主要参数 | |--------|------|----------| | gemini_new_chat | 新建空白对话 | 无 | | gemini_temp_chat | 进入临时对话模式 | 无 | | gemini_navigate_to | 导航到指定 Gemini URL（如历史会话） | url, timeout |

模型与对话

| 工具名 | 说明 | 主要参数 | |--------|------|----------| | gemini_switch_model | 切换模型（pro/quick/think） | model | | gemini_send_message | 发送文本并等待回复（耗时 10~60s） | message, timeout |

图片操作

| 工具名 | 说明 | 主要参数 | |--------|------|----------| | gemini_upload_images | 上传图片到输入框 | images | | gemini_get_images | 获取会话中所有图片元信息 | 无 | | gemini_extract_image | 提取图片 base64 并保存本地 | imageUrl | | gemini_download_full_size_image | 下载完整尺寸高清图片 | index | | gemini_share_latest_image | 为图片创建公开分享链接并返回 https://gemini.google.com/share/... | index, timeout, copyToClipboard, closeDialog |

文字回复

| 工具名 | 说明 | 主要参数 | |--------|------|----------| | gemini_get_all_text_responses | 获取所有文字回复 | 无 | | gemini_get_latest_text_response | 获取最新一条文字回复 | 无 |

诊断与管理

| 工具名 | 说明 | 主要参数 | |--------|------|----------| | gemini_check_login | 检查 Google 登录状态 | 无 | | gemini_probe | 探测页面元素状态 | 无 | | gemini_reload_page | 刷新页面 | timeout | | gemini_browser_info | 获取浏览器连接信息 | 无 |

🔄 Daemon 生命周期

首次 MCP 调用
  │
  ├─ Daemon 未运行 → 自动 spawn（detached + unref）
  │                    → 轮询等待就绪（最多 15s）
  │
  ├─ GET /browser/acquire → 启动/复用浏览器 + 重置 30 分钟倒计时
  │
  ├─ MCP 工具执行完毕 → disconnect()（断开 WebSocket，不关浏览器）
  │
  ├─ 30 分钟内再次调用 → 重置倒计时（续命）
  │
  └─ 30 分钟无人使用 → 关闭浏览器 + 关闭 HTTP 服务 + 退出进程
                         （下次调用时自动重新拉起）

Daemon API 端点：

| 端点 | 说明 | |------|------| | GET /browser/acquire | 获取浏览器连接（会续命） | | GET /browser/status | 查询浏览器状态（不续命） | | POST /browser/release | 主动销毁浏览器 | | GET /health | Daemon 健康检查 |

📁 项目结构

gemini-skill/
├── src/
│   ├── index.js               # 统一入口
│   ├── mcp-server.js          # MCP 协议服务（注册所有工具）
│   ├── gemini-ops.js          # Gemini 页面操作（核心逻辑）
│   ├── operator.js            # 底层 DOM 操作封装
│   ├── browser.js             # 浏览器连接器（面向 Skill）
│   ├── config.js              # 统一配置中心
│   ├── util.js                # 工具函数
│   ├── watermark-remover.js   # 图片去水印（基于 sharp）
│   ├── demo.js                # 使用示例
│   ├── assets/                # 静态资源
│   └── daemon/                # Browser Daemon（独立进程）
│       ├── server.js          # HTTP 微服务入口
│       ├── engine.js          # 浏览器引擎（launch/connect/terminate）
│       ├── handlers.js        # API 路由处理器
│       └── lifecycle.js       # 生命周期控制（惰性销毁倒计时）
├── references/                # 参考文档
├── SKILL.md                   # AI 调用规范（MCP 客户端读取）
├── package.json
└── .env                       # 环境配置（需自行创建）

⚠️ 注意事项

1. 首次使用需登录 — 第一次运行时浏览器会打开 Gemini 页面，请手动完成 Google 账号登录。登录状态会保存在 userDataDir 中，后续无需重复登录。

2. 不要同时运行多个实例 — 同一个 CDP 端口只能有一个浏览器实例，否则会端口冲突。

3. Windows Server 注意 — 已内置路径规范化和 Safe Browsing 绕过，但仍建议检查：

   • Chrome/Edge 已正确安装
   • 输出目录有写入权限
   • 防火墙未阻断 localhost 通信

4. 生图耗时较长 — 通常 60~120 秒，MCP 客户端的 timeoutMs 建议设为 ≥ 180000（3 分钟）。

📝 To Do List

• [x] MCP 协议全量工具注册
• [x] Daemon 进程按需自启
• [x] 高清原图 CDP 下载
• [x] 自动去水印
• [x] 参考图上传 & 图生图
• [x] 历史会话导航
• [ ] 多浏览器实例并行支持
• [ ] 支持音乐生成
• [ ] 支持视频生成

📄 License

该项目签署了 MIT 授权许可，详情请参阅 [LICENSE](https://github