Visual reviewer

视觉审查 (Visual Reviewer)

在 AI 产出一个可视化结果后，自动进行视觉层面的质量审查和自主修复。

触发条件

本 Skill 在以下产出物完成后应自动触发，无需用户手动要求：

• HTML 页面 / Web 应用界面
• Markdown 文档（含表格、代码块等富文本）
• PPT / 演示文稿
• 任何用户可见的视觉产出物

截图策略（按产物类型）

策略 A — Web 页面 (HTML/Web应用)

首选方案：精确窗口截图（Python，推荐）

1. 用 preview_url 打开页面 → 页面在 WorkBuddy 内置浏览器面板中渲染
2. 用 Python 截图脚本按 WorkBuddy 窗口标题精确截取客户区：

   python "<skill_path>/scripts/capture_screenshot.py" \
       --output "<screenshot_path>" \
       --mode window \
       --title "WorkBuddy"
   

   • 自动查找标题含 "WorkBuddy" 的窗口 → 置顶 → 截取客户区（不含标题栏/边框）
   • 使用 ctypes 调用 Win32 API + mss 高速截屏，无环境块限制

备选方案：外部浏览器截图

1. 启动本地 HTTP 服务器：python -m http.server 8765 -d <产物目录>
2. 打开浏览器访问 http://localhost:8765/<file>.html
3. 等待 2-3 秒页面加载，按浏览器进程名截图：

   python "<skill_path>/scripts/capture_screenshot.py" -o "<path>" -m window -p "chrome"
   # 或
   python "<skill_path>/scripts/capture_screenshot.py" -o "<path>" -m window -p "msedge"
   

策略 B — 文档 / PPT

1. 用 open_result_view 打开文档
2. 按窗口标题或进程名精确截图：

   # 按窗口标题部分匹配（文档名在窗口标题中）
   python "<skill_path>/scripts/capture_screenshot.py" -o "<path>" -m window -t "<文档名关键字>"
   
   # 按进程名截图
   python "<skill_path>/scripts/capture_screenshot.py" -o "<path>" -m window -p "WINWORD"
   

策略 C — 屏幕区域（指定坐标）

需要截取屏幕特定区域时（如 WorkBuddy 内置浏览器面板的精确位置）：

python "<skill_path>/scripts/capture_screenshot.py" -o "<path>" -m region -r "X,Y,W,H"

截图脚本参数速查

参数	简写	说明	示例
--mode window -t	-m window -t	按窗口标题截取特定程序窗口	-m window -t "stock-watcher"
--mode window -p	-m window -p	按进程名截取特定程序窗口	-m window -p "chrome"
--mode region -r	-m region -r	按屏幕坐标截取指定区域	-m region -r "100,200,800,600"
--mode activewindow	-m activewindow	截取当前前台窗口	-m activewindow
--mode fullscreen	-m fullscreen	截取整个主屏幕（兜底）	-m fullscreen
--client-only false		截取含标题栏/边框的整窗	默认 true（仅客户区）

输出格式：成功时最后一行输出 OK:<mode>:<path>，失败时输出错误信息和可见窗口列表方便调试。

依赖：需要 Python + mss + pygetwindow（已随 Skill 安装说明提供 requirements.txt）。

工作流程

Step 1 — 打开/预览结果

产出类型	打开方式
HTML / Web 页面	preview_url 打开本地文件或 localhost URL
文档 / PPT / 其他	open_result_view 打开结果文件

Step 2 — 选择截图策略并执行

根据产物类型选择上述策略 A/B/C，调用截图脚本。

截图保存为 PNG 格式后，使用 Read 工具读取截图进行视觉分析。

Step 3 — 视觉检查清单

逐项检查以下维度，每个维度 0-3 分（0=严重问题 / 1=有问题 / 2=可接受 / 3=良好）：

维度	检查项
布局	元素对齐（水平/垂直）、重叠、响应式断点、空白分布
间距	padding/margin 一致性、元素间距匀称、边界留白
排版	字体层级（h1-h6 视觉差）、行高/字间距、文字截断/溢出
颜色	对比度（WCAG AA）、配色协调、暗色/亮色模式适配
交互	按钮可点击区域、hover/active 状态、焦点可见性
数据展示	表格列宽合理性、数字对齐、图表标签完整性
边界情况	空数据状态、超长文字截断、极端窗口尺寸（320px / 4K）

详细清单见 references/visual_checklist.md。

Step 4 — 自主修复

对每个发现的问题：

1. 确定根本原因（CSS 属性 / 布局逻辑 / 数据格式问题）
2. 修改对应代码或样式
3. 修复后重新预览 / 截图确认

Step 5 — 审查报告

## 视觉审查报告

### 发现的问题 (共 N 个)
| # | 严重度 | 问题 | 原因 | 修复 | 状态 |
|---|--------|------|------|------|------|
| 1 | 严重 | 导航栏与内容区重叠 | z-index 缺失 | 添加 z-index: 100 | ✓ |
| 2 | 中等 | 按钮间距不一致 | margin 值不统一 | 统一为 8px | ✓ |
| 3 | 轻微 | 标题字体偏小 | font-size 16px | 建议改为 20px | 待确认 |

### 审查覆盖率
布局: ✓ | 间距: ✓ | 排版: ✓ | 颜色: ✓ | 交互: ✓ | 数据展示: N/A | 边界: ✓

工作原则

1. 自动触发: 产出可视化结果后必须执行审查流程，不等待用户指令
2. 截图优先: 必须通过截图分析视觉效果，不凭代码推断
3. 精确截图: 优先使用按窗口标题/进程名的精确截图，全屏截图仅作兜底
4. 主动修复: 明显的视觉问题直接修复，不"只报告不行动"
5. 分级处理: 严重/中等问题 → 立即修复；轻微问题 → 修复 + 标注可回滚
6. 不破坏功能: 视觉修复只改样式和布局，不改变业务逻辑
7. 循环验证: 修复后必须重新截图确认，修复 → 验证最多循环 3 次
8. 报告完整: 每次审查结束后输出完整报告，含修复前后对比