前言¶

在 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。