Visual UI Understander v2

面向 AI Agent 的通用视觉理解 Skill。

何时使用

用户在以下场景发送图片或截图时触发：

核心工作流程

0. 检查依赖

# 模块检查（脚本会自行判断，但建议提前安装）
pip install tencentcloud-sdk-python Pillow

1. 确认图片路径

检查用户消息或附件中是否包含图片路径，或者询问用户。

2. 选择模式并调用

Agent 根据用户意图，选择合适的命令行调用。

CLI 参考

通用理解

python scripts/understand_image.py <图片路径> "<你的问题>"

UI 设计问题分析

# 自然语言输出
python scripts/understand_image.py --ui-analyze <图片路径>

# 结构化 JSON 输出（推荐 Agent 使用）
python scripts/understand_image.py --ui-analyze --json <图片路径>

返回 JSON 结构：

{
  "issues": [
    {
      "severity": "high",
      "category": "布局",
      "description": "标题与正文间距过小",
      "suggestion": "增加至 16px"
    }
  ],
  "summary": "共发现 N 个问题...",
  "highlights": ["色彩搭配整体协调"]
}

文字提取（OCR）

# 自然语言
python scripts/understand_image.py --ocr <图片路径>

# JSON 输出（推荐 Agent 使用）
python scripts/understand_image.py --ocr --json <图片路径>

返回 JSON：

{
  "blocks": [
    {"region": "顶部导航", "text": "古言今解"},
    {"region": "标题", "text": "望庐山瀑布"}
  ],
  "full_text": "古言今解\n望庐山瀑布\n李白..."
}

无障碍检查（a11y）

python scripts/understand_image.py --accessibility --json <图片路径>

返回 JSON：

{
  "issues": [
    {
      "severity": "high",
      "type": "对比度",
      "description": "灰色文字与白色背景对比度仅 2.3:1",
      "wcag_standard": "WCAG 2.1 AA 1.4.3",
      "suggestion": "加深文字颜色至 #595959"
    }
  ],
  "summary": "发现 2 个无障碍问题",
  "pass_count": 5,
  "fail_count": 2
}

多图片输入

python scripts/understand_image.py --images <图1> <图2> ... <图N> "<问题>"

适合场景：

• 对比设计稿 vs 实现截图
• 分析多页面流程（如注册流程 3 步截图）
• 检查多张截图中的共同问题

一句话总结

python scripts/understand_image.py --summary <图片路径> "<可选问题>"

返回 50 字以内的一句话概括。适合 Agent 快速通知场景（如 Slack 广播）。

多轮对话上下文

# 第一轮
python scripts/understand_image.py --ui-analyze screenshot.png

# 第二轮（带上历史）
python scripts/understand_image.py screenshot.png "那右边那个按钮呢" \
  --history '[{"role":"user","content":"这张图有什么UI问题？"},{"role":"assistant","content":"..."}]'

内部行为（Agent 无需关注，但了解有助于排查）

图片自动压缩

• 最长边 > 2048px 自动缩放
• RGBA/PNG/WebP 自动转 JPG
• 体积 > 2MB 自动降质
• 无需 Polar 或 Pillow 回退原图

自动重试

• 网络超时 → 指数退避重试 3 次
• 限流 → 等待 2s 后重试
• 授权 / 配额错误 → 立即返回 + 修复建议

错误格式

所有错误以 ERROR:类型|说明 格式返回，Agent 可直接解析：

ERROR:AUTH_FAILED|请检查环境变量 ...
ERROR:QUOTA_EXHAUSTED|混元 API 配额不足...
ERROR:TIMEOUT|请求超时，请重试
ERROR:FILE_NOT_FOUND|图片文件不存在...
ERROR:API_RESPONSE|模型返回异常...

注意事项

1. 凭证配置：TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY 配置在 .env 文件或环境变量
2. 服务开通：需要开通腾讯混元大模型服务（控制台 → 混元大模型），并授权 QcloudHunyuanFullAccess
3. JSON 模式：--json 返回的结构化数据更适合 Agent 程序化消费
4. 多图模式：目前第一张图做视觉分析，其余图通过文本描述传入——如需精确分析每张图，建议分别调用
5. 临时文件：压缩后的临时图片在脚本结束后自动清理