前言¶

在 Cursor、Claude Code 或 OpenClaw 里做前端或设计相关任务时，常见路径是：用户丢一张界面截图，再问「哪里不对」「把字提出来」「和设计稿差多少」。若只靠对话模型「看」附件，输出往往偏叙述、难被后续脚本或工作流消费；若自己接多模态 API，又要处理压缩、重试、JSON 形态和凭证配置。

下面介绍 SkillHub 社区 Skill 视觉理解-UI设计分析（坐标 @user_ae22680b/visual-ui-understander，当前版本 2.0.0）。它用通用 SKILL.md 约定 Agent 何时触发，并通过 scripts/understand_image.py 调用腾讯混元多模态能力，覆盖 UI 分析、OCR、无障碍检查与多图输入，并支持 --json 结构化结果。

这是什么¶

视觉理解-UI设计分析 是面向 CodeBuddy / WorkBuddy / OpenClaw 等 Agent 的视觉理解 Skill，由社区发布者 user_ae22680b 维护，分类为 design-media，来源为 community。

Skill 简介（与 SkillHub 检索结果一致）：让 AI Agent 具备视觉理解能力，支持 UI 设计分析、文字提取、无障碍检查、多图分析、结构化 JSON 输出。页面侧标注 requires_api_key=true，实际依赖腾讯云密钥与混元服务开通（见下文配置）。

在 SkillHub 上，该 Skill 评分 100000，下载 1410 次（抓取时点数据；安装计数为 0）。

• 技能页：https://www.skillhub.cn/skills/user_ae22680b/visual-ui-understander
• 官方入口：https://api.skillhub.cn/user_ae22680b/visual-ui-understander

核心功能¶

以下能力均来自 Skill 包内 SKILL.md 与 references/usage_guide.md，经 skillhub install 安装后可核对。

底层调用 腾讯混元 多模态接口（脚本注释与文档均写明）。错误以 ERROR:类型|说明 返回，便于 Agent 解析（如 AUTH_FAILED、QUOTA_EXHAUSTED、TIMEOUT）。

安装与启用¶

1. 安装 SkillHub CLI¶

若尚未安装，按 SkillHub 官方安装文档检查或安装 CLI：

command -v skillhub && skillhub --version

未安装时可执行（完整安装，含默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

说明文档：https://skillhub.cn/install/skillhub.md

2. 安装本 Skill 到当前 Agent 的 skills 目录¶

安装时必须用 --dir 指向当前 Agent 实际读取的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。

SkillHub 技能页给出的安装方式为：根据上述安装文档，安装 @user_ae22680b/visual-ui-understander。CLI 检索结果中的等价命令为：

skillhub install visual-ui-understander --namespace user_ae22680b --dir <你的 skills 目录>

各环境常用 skills 路径（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex CLI：~/.codex/skills/ 或项目下 .agents/skills/
• WorkBuddy：~/.workbuddy/skills/

安装完成后，按你所用客户端要求重启或重新加载 Agent，使 Skill 生效。

3. Python 依赖与腾讯云凭证¶

进入 Skill 安装目录（例如 .../@user_ae22680b/visual-ui-understander），安装脚本依赖：

pip install tencentcloud-sdk-python Pillow

Pillow 用于压缩与格式转换；未安装时文档说明会跳过压缩步骤。

在 Skill 目录下的 .env 或系统环境变量中配置：

TENCENTCLOUD_SECRET_ID=你的SecretId
TENCENTCLOUD_SECRET_KEY=你的SecretKey

并在 混元大模型控制台 开通服务，为密钥授予 QcloudHunyuanFullAccess。密钥可在 腾讯云 API 密钥管理 创建。

SKILL.md 的 OpenClaw 元数据将 TENCENTCLOUD_SECRET_ID 标为 primaryEnv，与 requires_api_key 标签一致。

典型用法¶

以下命令均在 Skill 根目录执行，scripts/understand_image.py 为入口。

UI 设计分析（推荐给 Agent 的 JSON 模式）：

python scripts/understand_image.py --ui-analyze --json screenshot.png

提取图中文字：

python scripts/understand_image.py --ocr --json receipt.jpg

无障碍（a11y）检查：

python scripts/understand_image.py --accessibility --json page.png

多图对比或流程分析：

python scripts/understand_image.py --images design.png actual.png "还原度如何？"

带历史的追问：

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

Agent 侧可复现的工作流（来自官方使用指南）：

1. 用户发送截图并询问 UI 问题 → 确认文件路径 → 执行 --ui-analyze --json → 解析 issues 并按严重程度展示。
2. 用户给出多张截图问共同问题 → --images 加自然语言问题 → 汇总模型回答。
3. 用户需要图中文字做后续处理 → --ocr --json → 取 full_text 再交给下游步骤。

触发关键词在 SKILL.md 中列出，例如「截图」「UI」「OCR」「对比」「无障碍 / a11y」等，便于 Agent 路由到本 Skill。

适用场景与注意¶

适合谁

• 在 Agent 工作流里需要稳定、可脚本化的截图分析，而不是单次闲聊式描述。
• 前端 / 设计协作：UI 评审、设计稿与实现对齐、小程序或 Web 的无障碍粗检、票据或界面 OCR。
• 已具备或可申请腾讯云混元账号与 API 配额的团队。

限制与注意

1. 必须配置密钥并开通混元；未配置时脚本会返回 AUTH_FAILED 等明确错误。
2. 多图模式：文档写明当前以第一张图做视觉分析，其余图通过文本描述传入；若需逐张精细分析，应分别调用。
3. 格式与体积：支持 PNG、JPG、WebP 等常见格式，上传前会压到最长边 ≤ 2048px、体积 ≤ 2MB。
4. 成本与配额：调用走混元 API，需关注控制台余额与 QUOTA_EXHAUSTED 类错误。
5. Skill 面向 CodeBuddy / WorkBuddy / OpenClaw 等生态描述；在 Cursor 等客户端上使用时，安装路径与重启行为以各自文档为准，命令行部分与 Skill 包内说明相同。

结尾¶

视觉理解-UI设计分析 把「看截图」收敛成 Agent 可执行的 CLI：--ui-analyze、--ocr、--accessibility 与 --json 组合，便于在自动化流程里接 UI 评审、文字提取与无障碍检查。安装与优先源配置见 https://skillhub.cn/install/skillhub.md；Skill 详情与安装提示见 https://www.skillhub.cn/skills/user_ae22680b/visual-ui-understander 或 https://api.skillhub.cn/user_ae22680b/visual-ui-understander。