review-ui-with-openrouter

name	review-ui-with-openrouter
description	Use when Codex has 1-6 UI screenshots, especially from chrome-devtools, and needs a senior UI review that first removes obvious dev-ui traits and unfinished baseline issues before discussing higher-level polish.

用 OpenRouter 做 UI 评审

概述

把 1-6 张本地界面截图整理成一份统一的多模态评审请求，使用 google/gemini-3.5-flash 通过 OpenRouter 输出 Markdown 评审报告。

这个 skill 的重点不是先聊“高级审美”，而是先把基础问题挑出来，尤其是界面里明显像“开发者内部工具”的部分，以及那些说明页面还没进入正式交付状态的成品边界问题。

这里的 dev-ui 感 固定定义为：

先把界面中明显像“开发者内部工具”的视觉与交互特征去掉，使其看起来像正式产品界面。

使用时优先复用自带脚本，不要手写多模态请求。

何时使用

适用于这些场景：

• 手里已经有 1-6 张本地截图，希望快速拿到一份结构统一的 UI/UX 评审。
• 你怀疑界面“还像开发阶段页面”，想先排查基础质量问题，而不是直接追求风格升级。
• 需要同时参考多个模型的判断，避免单一评审角度过窄。
• 需要评审一个页面，或一组连续页面在同一流程中的一致性。

不适用于这些场景：

• 没有截图，只有口头描述。
• 想做代码级前端 review，而不是基于截图做界面体验评审。
• 截图超过 6 张，或流程太长，已经不适合一次评审。

评审原则

调用模型时，要把评审重心收在下面这条顺序上：

1. 先判断界面第一眼是否整洁、清爽、易读，是否已经像正式产品。
2. 优先找出 dev-ui 级别的问题，也就是那些会让界面看起来像内部工具、临时拼接页面、还没收尾的基础问题。
3. 除 dev-ui 外，还要明确识别成品边界问题，尤其是是否把内部提示语、心理对话、备注文字或过程性说明写进最终页面。
4. 同时检查信息优先级是否失控，例如无关标签过多、无关说明堆积，导致真正有用的信息被压到很后面。
5. 只有基础达标后，才展开更高阶的审美、品牌感和精致度建议。

重点关注的问题包括：

• 对齐是否混乱
• 留白是否失控
• 层级是否清楚
• 控件样式是否统一
• 页面是否拥挤、噪音过多
• 文案是否像占位稿或开发态文案
• 是否把内部提示语、心理对话、备注文字写进成品
• 是否有过多无关标签或说明，压后真正有效的信息
• 跨页面的视觉和交互是否一致

使用步骤

1. 确认截图已经保存在本地。
2. 选择最小但足够说明问题的一组截图，最多 6 张。
3. 准备 --context：必须说明页面/流程的功能；可补充少量模型从截图里看不出的场景背景，但不要重复描述截图肉眼可见内容。
4. 准备 --goal：必须说明开发者/产品意图，例如希望用户感受到什么、当前优先优化什么、这版更看重什么取舍。
5. 运行 scripts/review_ui.py，必要时可重复传多个 --context。
6. 如果只是想检查提示词，可先用 --dry-run，但 --context 和 --goal 仍然必须提供。
7. 默认返回 Markdown 报告，包含 评委1 一个部分。

必要输入

• 1-6 张本地图片文件
• --context：必填。用于承载功能说明，可带少量流程/场景背景
• --goal：必填。用于承载开发者/产品意图说明
• OPEN_ROUTER_KEY

OPEN_ROUTER_KEY 优先从当前工作目录的 conf/.env 读取；如果没有，再回退到 shell 环境变量。

可选环境变量：

• OPEN_ROUTER_BASE
• OPENROUTER_HTTP_REFERER
• OPENROUTER_X_TITLE

推荐命令

可以从任意目录运行，推荐用 python3 或 uv run python：

python3 ~/.agents/skills/review-ui-with-openrouter/scripts/review_ui.py \
  path/to/shot-1.png \
  path/to/shot-2.png \
  --context "这是播客详情页和导出弹窗，用户会从列表进入这里完成收听与导出" \
  --goal "希望用户第一眼觉得信息可信、重点明确；这版优先降低理解成本，不先追求品牌包装" \
  --save-prompt /tmp/review-ui/ui-review-prompt.md \
  --save-response /tmp/review-ui/ui-review-response.md

如果保存路径直接写到 /tmp/文件名.md，脚本会自动改写到 /tmp/review-ui/文件名.md，避免临时文件散落在 /tmp 根目录。

输出要求

每个评委都要以资深 UI/UX 工程师的口径输出，并使用下面这组固定结构：

• 总评
• 基础达标检查
• 高优先级问题
• 中优先级问题
• 亮点
• 高级审美改进项目
• 可执行改进建议
• 需补充验证的交互假设

其中有几个硬要求：

• 基础达标检查 必须先判断界面是否已经摆脱 dev-ui 感。
• 基础达标检查 必须逐项点名检查：
  • 是否存在明显 dev-ui 问题
  • 是否存在内部提示语 / 心理对话 / 备注文字进入最终页面
  • 是否存在无关标签过多、有效信息被压后
• 只要出现内部提示语、心理对话、备注文字进入成品，通常就应判定 基础达标检查 不通过。
• 无关标签过多、有效信息后置通常应进入 高优先级问题；只有特别严重时才升格为基础不通过。
• 高优先级问题 必须优先放基础没做好的问题，而不是品牌或风格层面的加分项。
• 如果结论里包含交互推断，必须明确标注“推断”。
• 如果有多张截图，必须额外评审流程一致性和跨页面体验是否顺畅。

最终报告默认必须包含：

• ## 评委1 对应 google/gemini-3.5-flash

注意事项

• 一次不要传超过 6 张截图。
• 截图越少越好，但要能完整说明问题。
• --context 和 --goal 缺一不可；脚本会直接报错退出，即使使用 --dry-run 也一样。
• 上下文只补充“模型从截图里看不出来、但会影响判断”的信息，不要重复描述截图内容。
• 如果界面基础质量明显不过关，评审应继续盯住基础问题，不要漂到品牌包装和风格探索上。
• 如果缺少 OPEN_ROUTER_KEY，应停止真实请求；如果只是检查提示词，可在提供 --context 与 --goal 的前提下使用 --dry-run。
• 如果模型输出偏空泛，优先收紧上下文或更换截图后再试，不要先加更多空泛说明。