gemini-visual

Gemini Visual - 前端与视觉开发助手

概述

这是一套全面的工具包，利用 Google Gemini 先进的视觉推理能力完成前端开发和设计任务。Gemini 提供业界领先的多模态理解能力，支持空间推理、文档理解和高分辨率图像处理。

适用场景

• UI/UX 分析：分析屏幕截图中的布局问题、视觉层次和设计模式
• 无障碍审查：检查对比度、文本可读性和 WCAG 合规性
• 设计对比：比较模型图、前后截图或不同的设计方案
• 调色板提取：从图像中提取颜色，并提供 HEX、RGB 和 HSL 值
• 从屏幕截图生成代码：根据设计截图生成 HTML/CSS
• UI 素材生成：创建图标、背景、渐变和 UI 图形
• 响应式设计审查：分析多设备截图的一致性
• 视觉调试：识别渲染问题、布局错乱或视觉错误
• 根据需求说明进行设计：根据文字描述生成设计、代码和组件
• 交互式设计会话：通过多轮对话迭代完善设计

前置条件

• Python 3.9+
• google-genai 包
• GEMINI_API_KEY 环境变量

安装

pip install google-genai

获取 API 密钥

1. 前往 Google AI Studio
2. 登录 Google 账号
3. 点击“Create API Key”
4. 复制密钥并将其设为环境变量：

export GEMINI_API_KEY="your-api-key"

将其添加到 shell 配置文件（~/.zshrc 或 ~/.bashrc），以便持久保存：

echo 'export GEMINI_API_KEY="your-api-key"' >> ~/.zshrc

脚本概览

脚本	用途
analyze_ui.py	分析 UI 屏幕截图中的问题、模式并提供建议
generate_ui_assets.py	生成图标、背景和 UI 图形
compare_designs.py	比较两种设计并突出显示差异
extract_colors.py	从图像中提取调色板
screenshot_to_code.py	将屏幕截图转换为 HTML/CSS 代码
design_from_brief.py	根据文字需求说明生成设计和代码（无需图像）

可用模型

模型	最适合的用途	备注
gemini-2.5-flash	视觉分析、代码生成、快速推理	分析任务中性价比最佳
gemini-2.5-pro	复杂视觉推理、代码生成	分析质量最高
gemini-2.5-flash-image-preview	素材生成、图像编辑	原生图像输出
gemini-3.1-flash-image-preview	高质量图像生成、4K 输出	最新的图像生成模型
gemini-3-pro-image-preview	专业图像生成	上一代高质量模型

**注意：**对于图像分析任务（analyze_ui、compare_designs、screenshot_to_code、extract_colors），请使用文本+视觉模型（gemini-2.5-flash 或 gemini-2.5-pro）。对于图像生成任务（generate_ui_assets），请使用图像输出模型。

媒体分辨率选项

使用 --resolution 控制 token 用量和细节级别：

分辨率	每张图像的 Token 数	最适合的用途
low	70	快速扫描、缩略图
medium	560	标准屏幕截图、OCR
high	1120	详细的 UI 分析
ultra_high	2240+	精细文本、复杂布局

---

脚本参考

1. analyze_ui.py - UI 分析

分析 UI 屏幕截图中的设计问题、无障碍问题并提供改进建议。

python scripts/analyze_ui.py [options] IMAGE

Required:
  IMAGE                    Path to UI screenshot to analyze

Options:
  -m, --mode MODE          Analysis mode (default: comprehensive)
                           Modes: comprehensive, accessibility, layout, ux
  -r, --resolution RES     Media resolution (default: high)
  -o, --output FILE        Save analysis to file (JSON or text)
  -f, --format FORMAT      Output format: text, json, markdown (default: text)
  --thinking LEVEL         Thinking level: low, high (default: high)
  -v, --verbose            Show detailed progress

示例：

# Comprehensive UI analysis
python scripts/analyze_ui.py screenshot.png

# Accessibility-focused analysis
python scripts/analyze_ui.py -m accessibility app_screen.png

# Layout analysis with JSON output
python scripts/analyze_ui.py -m layout -f json -o report.json mockup.png

# Quick UX review
python scripts/analyze_ui.py -m ux --thinking low mobile_app.png

分析模式：

• comprehensive：全面分析，包括布局、颜色、排版、无障碍和 UX
• accessibility：WCAG 合规性、对比度、屏幕阅读器兼容性、触控目标
• layout：视觉层次、间距、对齐、响应式问题
• ux：用户流程、可供性、认知负荷、交互模式

---

2. generate_ui_assets.py - 资源生成

生成图标、背景、图案和图形等 UI 资源。

python scripts/generate_ui_assets.py [options]

Required:
  -p, --prompt TEXT        Description of asset to generate

Options:
  -t, --type TYPE          Asset type (default: icon)
                           Types: icon, background, pattern, illustration, badge
  -s, --style STYLE        Design style (default: modern)
                           Styles: modern, minimal, flat, gradient, glassmorphism,
                                   neumorphism, material, ios, outlined
  -c, --colors COLORS      Color palette (comma-separated HEX or names)
  -a, --aspect-ratio RATIO Aspect ratio (default: 1:1)
  --size SIZE              Resolution: 1K, 2K, 4K (default: 1K)
  -o, --output FILE        Output file path
  -r, --reference IMAGE    Reference image for style guidance
  -v, --verbose            Show detailed progress

示例：

# Generate app icon
python scripts/generate_ui_assets.py -p "Weather app icon with sun and clouds" -t icon

# Create gradient background
python scripts/generate_ui_assets.py -p "Soft gradient for login screen" -t background \
  -c "#667eea,#764ba2" -a 9:16 -o login_bg.png

# Generate pattern for UI
python scripts/generate_ui_assets.py -p "Subtle geometric pattern for card backgrounds" \
  -t pattern -s minimal -o pattern.png

# Create illustration from reference
python scripts/generate_ui_assets.py -p "Onboarding illustration, person using phone" \
  -t illustration -r brand_style.png -o onboarding.png

# Generate badge/label
python scripts/generate_ui_assets.py -p "Premium badge with star" -t badge \
  -c "gold,white" -s gradient

---

3. compare_designs.py - 设计比较

比较两张设计截图并分析差异。

python scripts/compare_designs.py [options] IMAGE1 IMAGE2

Required:
  IMAGE1                   First design image (before/version A)
  IMAGE2                   Second design image (after/version B)

Options:
  -m, --mode MODE          Comparison mode (default: full)
                           Modes: full, visual, content, accessibility
  -f, --format FORMAT      Output format: text, json, markdown (default: text)
  -o, --output FILE        Save comparison to file
  -r, --resolution RES     Media resolution (default: high)
  -v, --verbose            Show detailed progress

示例：

# Full design comparison
python scripts/compare_designs.py before.png after.png

# Visual-only comparison
python scripts/compare_designs.py -m visual old_design.png new_design.png

# Compare for accessibility changes
python scripts/compare_designs.py -m accessibility v1.png v2.png -o report.md

# A/B test comparison as JSON
python scripts/compare_designs.py -m full variant_a.png variant_b.png -f json

比较模式：

• full：全面比较所有视觉和功能方面
• visual：重点关注颜色、排版、间距和视觉层次
• content：文本变化、布局偏移、信息架构
• accessibility：对比度、可读性、触控目标和 WCAG 合规性变化

---

4. extract_colors.py - 提取配色方案

从图像中提取配色方案，并提供多种输出格式。

python scripts/extract_colors.py [options] IMAGE

Required:
  IMAGE                    Image to extract colors from

Options:
  -n, --count COUNT        Number of colors to extract (default: 6)
  -f, --format FORMAT      Output format: text, json, css, tailwind, scss (default: text)
  -o, --output FILE        Save palette to file
  --named                  Include closest CSS color names
  --contrast               Calculate contrast ratios between colors
  -v, --verbose            Show detailed progress

示例：

# Extract 6 main colors
python scripts/extract_colors.py screenshot.png

# Extract palette as CSS variables
python scripts/extract_colors.py -f css -o colors.css brand_image.png

# Get Tailwind config
python scripts/extract_colors.py -f tailwind -o tailwind.config.js design.png

# Detailed palette with contrast info
python scripts/extract_colors.py -n 8 --named --contrast hero_image.jpg

# SCSS variables output
python scripts/extract_colors.py -f scss -o _colors.scss mockup.png

---

5. screenshot_to_code.py - 截图转代码

将 UI 截图转换为 HTML/CSS 代码。

python scripts/screenshot_to_code.py [options] IMAGE

Required:
  IMAGE                    UI screenshot to convert

Options:
  -f, --framework FRAME    CSS framework (default: tailwind)
                           Frameworks: tailwind, css, bootstrap, vanilla
  -c, --components         Extract as reusable components
  --responsive             Generate responsive code
  -o, --output DIR         Output directory for files
  -r, --resolution RES     Media resolution (default: ultra_high)
  --thinking LEVEL         Thinking level: low, high (default: high)
  -v, --verbose            Show detailed progress

示例：

# Convert to Tailwind HTML
python scripts/screenshot_to_code.py landing_page.png

# Generate vanilla CSS
python scripts/screenshot_to_code.py -f vanilla -o ./output mockup.png

# Create responsive Bootstrap components
python scripts/screenshot_to_code.py -f bootstrap -c --responsive card.png

# Full page conversion with components
python scripts/screenshot_to_code.py -f tailwind -c --responsive -o ./components page.png

---

6. design_from_brief.py - 文本设计助手

根据文本描述生成前端设计、代码和组件，无需视觉输入。

python scripts/design_from_brief.py [options]

Input (one required):
  -p, --prompt TEXT      Design brief or prompt text
  -b, --brief-file FILE  Read brief from a file
  --interactive          Start interactive design session

Options:
  -m, --mode MODE        Generation mode (default: code)
                         Modes: design, code, component, review, brainstorm
  -fw, --framework FW    Framework for code generation (default: tailwind)
                         Frameworks: tailwind, css, bootstrap, react, vue, svelte, vanilla
  -c, --context TEXT     Additional context (existing code, constraints)
  -f, --format FORMAT    Output format: text, json, markdown (default: text)
  -o, --output FILE      Save output to file
  -v, --verbose          Show detailed progress

示例：

# Generate code from a brief
python scripts/design_from_brief.py -p "Create a pricing table with 3 tiers" -m code -fw tailwind

# Get design advice and guidance
python scripts/design_from_brief.py -p "Design a modern SaaS landing page" -m design

# Generate a React component
python scripts/design_from_brief.py -p "A toggle switch with smooth animation" -m component -fw react

# Review a design idea
python scripts/design_from_brief.py -p "Is a hamburger menu good for desktop navigation?" -m review

# Brainstorm creative ideas
python scripts/design_from_brief.py -p "Ideas for a fitness app dashboard" -m brainstorm

# Read brief from file
python scripts/design_from_brief.py -b project_brief.txt -m code -fw vue

# Interactive multi-turn session
python scripts/design_from_brief.py --interactive -m code -fw tailwind

生成模式：

• design：获取设计指导，包括颜色、排版、布局和 UX 建议
• code：生成完整且可用于生产环境的前端代码
• component：设计并编写可复用 UI 组件，包含 props 和变体
• review：获取有关设计构思或代码的反馈和建议
• brainstorm：生成创意构思和多个设计方向

支持的框架：

框架	描述
tailwind	Tailwind CSS 实用类
css	使用变量和 BEM 的自定义 CSS
bootstrap	Bootstrap 5 组件
react	使用 TypeScript 的 React 函数组件
vue	使用 TypeScript 的 Vue 3 Composition API
svelte	Svelte 组件
vanilla	原生 HTML/CSS/JavaScript

交互会话命令：

使用 --interactive 时，可以使用以下命令：

命令	描述
/mode <mode>	更改生成模式
/framework <fw>	更改框架
/save <file>	将上次响应保存到文件
/clear	清除对话历史
/quit	退出会话

---

使用场景

前端开发工作流

# 1. Analyze a design mockup
python scripts/analyze_ui.py mockup.png -f markdown -o analysis.md

# 2. Extract brand colors
python scripts/extract_colors.py mockup.png -f tailwind -o colors.js

# 3. Generate code from screenshot
python scripts/screenshot_to_code.py mockup.png -f tailwind -c -o ./src

# 4. Generate placeholder icons
python scripts/generate_ui_assets.py -p "Settings gear icon" -t icon -s outlined

设计评审流程

# Compare design iterations
python scripts/compare_designs.py v1.png v2.png -f markdown -o review.md

# Check accessibility
python scripts/analyze_ui.py final_design.png -m accessibility -o a11y_report.json

资源制作流程

# Generate icon set
for icon in "home" "search" "profile" "settings"; do
  python scripts/generate_ui_assets.py -p "${icon} icon" -t icon -s outlined -o icons/${icon}.png
done

# Generate backgrounds for different screens
python scripts/generate_ui_assets.py -p "Auth screen gradient" -t background -a 9:16 -o bg_auth.png
python scripts/generate_ui_assets.py -p "Dashboard header" -t background -a 21:9 -o bg_header.png

根据文本简报进行设计

# Start with design exploration
python scripts/design_from_brief.py -p "E-commerce product page for sneakers" -m design -o design_spec.md

# Generate the code
python scripts/design_from_brief.py -p "E-commerce product page with image gallery,
size selector, add to cart button, and reviews section" -m code -fw react -o product_page.tsx

# Create reusable components
python scripts/design_from_brief.py -p "Star rating component, 1-5 stars,
supports half stars, shows count" -m component -fw react

# Interactive refinement session
python scripts/design_from_brief.py --interactive -m code -fw tailwind
# Then iterate: "Add a sticky header", "Make the CTA more prominent", etc.

完整项目工作流（无需图像）

# 1. Brainstorm ideas
python scripts/design_from_brief.py -p "Modern dashboard for analytics SaaS" -m brainstorm

# 2. Get detailed design spec
python scripts/design_from_brief.py -p "Analytics dashboard with sidebar nav,
KPI cards, charts, and data tables" -m design -f markdown -o design.md

# 3. Generate components
python scripts/design_from_brief.py -p "KPI card showing metric, trend, and sparkline" \
  -m component -fw react -o components/KPICard.tsx

python scripts/design_from_brief.py -p "Data table with sorting, filtering, pagination" \
  -m component -fw react -o components/DataTable.tsx

# 4. Generate full page layout
python scripts/design_from_brief.py -p "Dashboard layout combining sidebar, header,
and main content area with the KPI cards and data table" -m code -fw react

---

API 能力摘要

Gemini 3 视觉功能

• 空间推理：理解元素的位置、对齐方式和相互关系
• 文档理解：OCR、文本提取、布局解析
• 高分辨率：支持超高分辨率，可呈现精细细节和小号文本
• 多图输入：每次请求最多比较 3,600 张图像
• 思维签名：为多轮编辑保留推理上下文

图像支持

• 输入格式：PNG、JPEG、WebP、HEIC、HEIF
• 最大文件大小：内联文件为 20MB，通过 File API 可处理更大的文件
• 输出格式：PNG（生成的图像）
• 分辨率：1K、2K、4K（生成），输入分辨率可配置

---

故障排除

“未设置 GEMINI_API_KEY 环境变量”

设置 API 密钥：

export GEMINI_API_KEY="your-api-key"

“超出速率限制”

等待几分钟后重试。对于批量操作，请在请求之间添加延迟。

分析质量较低

使用更高分辨率：

python scripts/analyze_ui.py -r ultra_high screenshot.png

缺少精细细节

如需详细分析 UI，请使用 ultra_high 分辨率：

python scripts/analyze_ui.py -r ultra_high -m comprehensive app.png

代码生成问题

使用 high 思考级别和 ultra_high 分辨率：

python scripts/screenshot_to_code.py --thinking high -r ultra_high mockup.png

资产生成被内容审核拦截

如果看到“No image content returned. The request may have been blocked by content moderation”，请尝试：

• 简化或改写提示词
• 移除特定品牌名称或受版权保护的内容
• 使用更通用的描述

这是 Gemini API 的安全过滤机制，并非所有提示词都会被接受。

分辨率会影响令牌用量

--resolution 参数控制图像处理所用的令牌数量：

• low：约 70 个令牌/张图像——快速扫描、缩略图
• medium：约 560 个令牌/张图像——标准截图、OCR
• high：约 1120 个令牌/张图像——详细的 UI 分析（默认）

更高的分辨率能提高准确度，但会使用更多令牌。

---

最佳实践

1. 选择合适的分辨率：分辨率越高，令牌用量越多，但准确度也越高
2. 根据任务选择模型：分析使用 gemini-3-pro-preview，生成使用 gemini-3-pro-image-preview
3. 提供上下文：在提示词中添加相关细节，以获得更好的结果
4. 迭代处理素材：使用多轮对话进行优化
5. 组合使用脚本：将提取与生成结合起来，打造一致的设计系统
6. 保存输出：使用 -o 标志保存报告，以便编写文档
7. 批量处理相似任务：将多个相似项目放在一起处理，以提高效率

来源

• Gemini 模型参考
• 图像理解
• 图像生成
• Google AI Studio