Gemini Image CLI

通过命令行调用 Gemini Web UI 生成 AI 图片，自动下载保存到本地。

支持 opencli 浏览器适配器和 CDP Proxy 两种模式。

v2.0 新特性

• CDP Proxy 直连模式 — 不依赖 opencli Browser Bridge，直接通过 Chrome DevTools Protocol 操控 Gemini，更稳定
• 自动质量自检 — 下载后自动检查图片质量（标题、布局、颜色、文字等 12 项），不通过则自动迭代
• 迭代直到通过 — 自检发现问题后自动修正 prompt、开新对话重新生成，循环直到全部通过
• Preflight 环境检测 — 自动检查 CDP proxy / 系统代理 / 输出目录，缺一则自动修复
• Prompt 工程最佳实践 — 总结 7 条从实战中提炼的规则，避免常见翻车（乱码、两列布局、文字泄露等）
• 版本号追踪 — 每次迭代自动 _v1 → _v2 → _v3 递增，方便对比
• 禁用截图下载 — 明确禁止用 CDP 截图获取图片（质量差），只允许点击原生下载按钮

功能

• 一行命令生图 — 输入 prompt，自动打开 Gemini、激活图片生成模式、等待结果、下载图片
• 自动下载 — 点击 Gemini 内置"下载完整尺寸的图片"按钮，触发 Chrome 原生下载
• 代理自动切换 — 被 Google 限流时，自动切换 Clash/mihomo 代理节点重试
• 加载状态检测 — 自动跳过 "正在加载 Nano Banana"、"Creating your image..." 等过渡状态
• 调试工具 — inspect 命令截图 + 转储 UI 元素，方便排查 Gemini 页面变化

两种运行模式

模式 A：CDP Proxy 直连（推荐）

不需要 opencli，直接通过 CDP proxy (localhost:3456) 操控 Chrome。最可靠的方式。

# 1. 打开 Gemini 新对话
TARGET=$(NO_PROXY="*" curl -s "http://localhost:3456/new?url=https://gemini.google.com/app" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['targetId'])")
sleep 5

# 2. 激活图片生成模式
NO_PROXY="*" curl -s -X POST "http://localhost:3456/eval?target=$TARGET" -d '
(function() {
    for (const b of document.querySelectorAll("button")) {
        if (b.textContent.includes("制作图片")) { b.click(); return "ok"; }
    }
    return "not found";
})()'
sleep 2

# 3. 输入 prompt
NO_PROXY="*" curl -s -X POST "http://localhost:3456/eval?target=$TARGET" -d '
(function() {
    const ta = document.querySelector("[contenteditable=true],[role=textbox],textarea");
    if (ta) { ta.focus(); ta.textContent = "你的 prompt"; ta.dispatchEvent(new Event("input",{bubbles:true})); return "ok"; }
    return "no input";
})()'
sleep 1

# 4. 发送
NO_PROXY="*" curl -s -X POST "http://localhost:3456/eval?target=$TARGET" -d '
(function() {
    for (const b of document.querySelectorAll("button")) {
        if ((b.getAttribute("aria-label")||"").includes("发送")) { b.click(); return "sent"; }
    }
    return "no send";
})()'

# 5. 等待生成 (90-120 秒)
sleep 110

# 6. 点击下载按钮
NO_PROXY="*" curl -s -X POST "http://localhost:3456/eval?target=$TARGET" -d '
(function() {
    for (const b of document.querySelectorAll("button,[role=button]")) {
        const label = (b.getAttribute("aria-label")||"") + (b.textContent||"");
        if (label.includes("下载完整尺寸")) { b.click(); return "clicked"; }
    }
    return "no download button";
})()'

# 7. 复制到目标目录
sleep 6
LATEST=$(ls -t ~/Downloads/Gemini_Generated_Image_*.png | head -1)
cp "$LATEST" ~/Downloads/Gemini生图/output_v1.png

# 8. 关闭标签页
NO_PROXY="*" curl -s "http://localhost:3456/close?target=$TARGET"

模式 B：opencli 命令（可能失败）

OPENCLI_BROWSER_COMMAND_TIMEOUT=300 opencli gemini generate \
  "你的 prompt" --timeout 200 --prefix "name" --outdir ~/Downloads/Gemini生图

已知问题：opencli 经常报 attach failed，且三种下载策略经常全部失败。推荐使用模式 A。

命令列表

命令	功能
opencli gemini generate "prompt"	生成图片并自动下载
opencli gemini download	从当前 Gemini 对话下载已生成的图片
opencli gemini inspect	调试：截图 + 转储 Gemini 页面 UI 元素

前置要求

CDP Proxy 模式（推荐）

1. Chrome 以远程调试模式运行（--remote-debugging-port=9222）
2. CDP Proxy 服务运行在 localhost:3456
3. 系统代理指向 Clash (127.0.0.1:7892)，使 Chrome 能访问 gemini.google.com
4. 在 Chrome 中登录 gemini.google.com

opencli 模式

1. 安装 opencli：npm install -g @jackwener/opencli
2. 安装 Browser Bridge Chrome 扩展
3. 验证：opencli doctor

自动质量自检（v2 新增）

下载图片后，AI Agent 会自动进行 12 项质量检查：

#	检查项	说明
1	标题文字正确	无乱码/mojibake
2	布局匹配请求	垂直/水平是否符合
3	无重复步骤	每个元素只出现一次
4	所有步骤完整	与 prompt 对照
5	步骤顺序正确	流程逻辑无误
6	判断框标签正确	菱形框内容
7	循环箭头可见	回环路径清晰
8	颜色编码正确	各阶段颜色区分
9	标签语言正确	中文/英文
10	无指令文字泄露	无 "RIGHT"/"LEFT" 等
11	单一输出端点	终点框唯一
12	成功/失败颜色	绿=通过，红=淘汰

不通过则自动修正 prompt 并重新生成，循环直到全部通过。

Prompt 工程最佳实践（v2 新增）

从多轮实战迭代中提炼的 7 条规则：

1. 英文指令 + 目标语言标签 — Gemini 理解英文结构指令更好，但可以渲染中文文字
2. 禁止位置词作箭头标签 — "RIGHT"/"LEFT"/"UP"/"DOWN" 会被渲染成图片文字
3. 明确禁止不想要的布局 — 如 "MUST be single column, do NOT split into two columns"
4. 编号每个元素 — "Box 1: ..., Box 2: ..." 帮助 Gemini 保持顺序
5. 指定每个框的样式 — "Blue FILLED rounded box"，不要笼统地说 "use colors"
6. 指定背景色带 — 每个阶段用不同颜色的 background band
7. 每次迭代开新对话 — 同对话追加修改会导致 Gemini 退回文本模式

下载方式可靠性

方式	可靠性	说明
CDP 点击"下载完整尺寸的图片"按钮	✅ 最可靠	Chrome 原生下载，100% 成功
opencli local_paths	⚠️ 偶尔成功	三种策略经常全部失败
CDP 截图	❌ 禁止	质量差、有浏览器边框、非原始分辨率
curl 直接下载图片 URL	❌ 不可用	Google CDN 需认证，返回 HTML

关键注意事项

NO_PROXY

所有 CDP proxy 的 curl 请求必须加 NO_PROXY="*" 前缀，否则请求会走系统代理导致 502：

# 正确
NO_PROXY="*" curl -s "http://localhost:3456/..."

# 错误 (502)
curl -s "http://localhost:3456/..."

并发限制

一次只能控制一个 Chrome 标签页。多个实例并行会互相冲突。必须串行执行。

代理要求

Gemini 需要通过代理访问。系统已配置 PAC 自动代理（~/.config/proxy/auto.pac），Clash HTTP 端口 7892。

环境变量

变量	默认值	说明
OPENCLI_BROWSER_COMMAND_TIMEOUT	60	浏览器命令超时（秒），建议 300
OPENCLI_GEMINI_PROXY_SOCKET	空	mihomo API Unix socket 路径
OPENCLI_GEMINI_PROXY_GROUP	openAI	代理组名称
OPENCLI_GEMINI_PROXY_NODES	空	备选节点列表，逗号分隔

使用示例

科学机制图

# CDP 模式
NO_PROXY="*" curl -s "http://localhost:3456/new?url=https://gemini.google.com/app" ...

# opencli 模式
OPENCLI_BROWSER_COMMAND_TIMEOUT=300 opencli gemini generate \
  "Create a scientific mechanism diagram showing soil carbon cycle..." \
  --timeout 200 --prefix soil_carbon --outdir ~/Downloads/Gemini生图

学术流程图（中文）

使用英文指令 + 中文标签的 prompt 模板：

Create a COLORFUL vertical flowchart with ALL Chinese text on WHITE background.
Title: 你的标题
Single column top-to-bottom. Each phase has colored background band.
【阶段A 名称】blue background band
Blue filled rounded boxes: 步骤1 → 步骤2 → 步骤3
...

常见问题

问题	解决方案
CDP curl 返回 502	缺少 NO_PROXY="*" 前缀
Gemini 页面 about:blank	Chrome 无法访问 gemini.google.com，启用系统代理
"制作图片"按钮找不到	UI 语言不匹配，用 opencli gemini inspect 检查
下载按钮没出现	多等 10 秒，图片渲染完成后才出现按钮
追加消息返回文本不生成图	Gemini 在同对话追加时退回文本模式，必须开新对话
text_only	图片生成工具未激活，确保点击了"制作图片"
"目前不支持你所在的地区"	代理节点地区受限，切换 Clash 节点
google.com/sorry	被限流，切换代理节点
图片标题乱码	prompt 中明确写出完整标题，加 "Title text must be exactly: ..."
图片两列布局而非单列	prompt 加 "MUST be single column, do NOT split into two columns"
"RIGHT"/"LEFT" 出现在图中	禁止在 prompt 中用位置词作标签

项目结构

src/
├── generate.ts   # 核心：图片生成 + 自动下载 + 代理切换
├── download.ts   # 独立下载命令
└── inspect.ts    # 调试工具：截图 + UI 元素转储

License

Apache-2.0