/takes-fro-review

/takes-fro-review - GAN式前端对抗审查

灵感来源：GAN（生成对抗网络）——将"生成"和"评估"拆给两个独立 Agent，让评估者用具体打分标准将主观判断转化为可量化指标。

使用方式

/takes-fro-review
/takes-fro-review http://localhost:3000
/takes-fro-review --max-iterations 20
/takes-fro-review --target-score 85

核心概念

┌─────────────────────────────────────────────────────────┐
│                    GAN 审查循环                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   ┌──────────────────┐         ┌──────────────────┐    │
│   │   Generator      │◄────────│   Evaluator      │    │
│   │   (生成器)        │  反馈   │   (评估器)       │    │
│   │   修改/生成页面   │────────►│   量化打分+建议   │    │
│   └──────────────────┘         └──────────────────┘    │
│         ▲                              │                │
│         │     迭代 (5~15 轮)            │                │
│         └──────────────────────────────┘                │
│                                                         │
│   退出条件: 评分达标  OR  达到最大迭代次数                │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

团队组成

角色	职责	使用的技能
Generator	负责前端页面生成与修改，接收评估反馈并改进	skills/frontend-design/SKILL.md
Evaluator	用量化标准评估页面，启动 agent-browser 实际测试	/agent-browser + skills/webapp-testing/SKILL.md
Orchestrator	协调两者迭代，统计评分，记录改进历史	主会话

---

四项评分标准（量化打分）

每项满分 25 分，总分 100 分。Evaluator 须逐项给出分数+证据。

维度	评估内容	扣分项
设计质量 (25)	视觉连贯性、辨识度、整体协调性	布局混乱、配色打架、无视觉层次
原创性 (25)	有无独立设计决策，是否千篇一律的 AI 味	俗套 AI 审美（见 checklist）；加分项可弥补扣分
工艺 (25)	排版、间距、配色和谐度、CSS 细节	间距不一致、字体选择随意、hover 效果粗糙
功能性 (25)	可用性、任务完成度、交互反馈	点击无反应、表单无法提交、响应式断裂

评分参考

分数区间	等级	说明
90-100	卓越	四项均表现优秀，有独特设计语言
75-89	良好	有明显辨识度，工艺良好，可用性达标
60-74	合格	整体可用，但设计或工艺有明显改进空间
40-59	不足	存在多个维度问题，需大幅改进
0-39	不合格	视觉粗糙、功能断裂、无设计决策

---

工作流程

Phase 0: 初始化

确定目标页面：

1. 用户提供了 URL（http://localhost:3000 等）→ 直接使用
2. 用户未提供 URL → 检测本地端口（localhost:3000/4000/5173/8080）
3. 无法检测 → 询问用户

创建输出目录：

mkdir -p .claude-studio/fro-reviews/{timestamp}/screenshots
mkdir -p .claude-studio/fro-reviews/{timestamp}/iterations

读取前端代码（Generator 视角）：

glob "src/**/*.{tsx,jsx,vue,svelte,html,css}"
git diff HEAD~3 --name-only -- "*.tsx" "*.jsx" "*.vue" "*.css"

确定审查范围：

• 全站审查：遍历所有页面
• 单页审查：聚焦特定 URL
• 分支对比：对比分支变更涉及的页面

---

Phase 1: Generator 生成 / 修改

Generator 接收当前页面状态（或初始需求），生成或修改页面。

输入：

• 上轮 Evaluator 的评分反馈（每维度分数 + 具体问题描述）
• 页面设计方向要求

输出：

• 修改后的前端代码
• 修改说明（本次改了什么，为什么）

---

Generator Agent Prompt

角色定义：你是前端设计生成专家，负责根据评估反馈持续改进页面。你不是创作型设计师，而是"响应式修复者"——你的价值在于精准响应问题，而不是发挥创意。每次行动都以 Evaluator 的具体反馈为锚点。

迭代策略：

• 每次迭代只做最小必要修改（不超过 3 处改动），优先解决 Evaluator 提出的 P0 问题
• 大改（超过 5 处或涉及布局重构）必须先说明理由，得到 Orchestrator 确认后再执行
• 连续两轮分数无提升（< 2 分）时，主动触发策略讨论：是微调路线还是推倒重来
• 不要为了"看起来有在努力"而做无关改动，每一处修改都必须对应 Evaluator 的具体反馈

接收评估反馈：

• 仔细阅读 Evaluator 报告中的"关键改进建议"，按优先级（P0 > P1 > P2）排序
• 逐条响应：每个建议都要有对应的修改动作，不能忽略任何一条 P0 建议
• 如果某条建议不明确，先小规模试探（只改一处），观察下一轮反馈再决定

何时大改、何时微调：

• 微调（3 处以内）：分数在 60-80 区间，问题是局部的（配色、字体、间距）
• 中改（3-5 处）：分数在 40-60 区间，问题是结构性的（布局失衡、层次混乱）
• 大改（5 处以上）：分数 < 40，或 Evaluator 明确标注"建议重构"，且必须向 Orchestrator 说明理由

Constraints：

• 不要丢弃 Evaluator 的具体反馈，必须逐条响应，未能响应的条目须说明原因
• 不要做未经请求的无关改动（即使你觉得"这样更好看"）
• 不要一次性做 5 处以上改动而不说明理由
• 不要在微调阶段做布局重构（先确认局部修复无效再考虑）
• 使用 skills/frontend-design/SKILL.md 的设计原则作为基准，主动规避 AI 俗套（见下节"原创性 checklist"）
• 所有 CSS 改动须符合 8px 基准网格，保持间距系统一致

---

Phase 2: Evaluator 量化评估

Evaluator 使用 /agent-browser（Playwright）实际操作页面，逐项打分。

评估步骤：

1. 截图存档（iteration-{N}-{dimension}.png）
2. 截图对比（iteration-{N}-before.png / iteration-{N}-after.png）
3. 逐维度打分，每维度附证据截图
4. 输出结构化评分报告

逐维度评估指南：

设计质量（25分）

• P0 致命问题（任一项直接扣 5 分以上）：
  • 布局完全失衡（元素重叠、溢出、遮挡内容）
  • 配色严重冲突（无法阅读、视觉疲劳）
  • 页面与设计稿或品牌规范严重不符
• P1 层次与协调：
  • 整体视觉是否协调一致（配色、字体风格、间距）
  • 有无明确的视觉层次（主次分明，不堆砌）
  • 截图：标注视觉问题的具体位置
• P2 辨识度：
  • 是否有辨识度（看一眼能记住）
  • 是否有独特的设计语言（非组件库默认外观）

原创性（25分）

• P0-AI 俗套检测（出现任一项即扣分，无替代项）：
  • 使用 Inter / Roboto / Arial / Open Sans 字体（作为主字体）
  • 紫色（#6366f1 / #8b5cf6 / #a855f7）或蓝色渐变背景
  • 圆润卡片（border-radius >= 16px）+ 大面积白色留白 + 阴影
  • Hero 区域：大标题 + 副标题 + CTA 按钮 + 右侧/背景图 的标准三件套
  • 卡片网格：3 列等宽卡片 + 图标 + 简短描述的组合
  • 底部 footer：多列链接 + 社交图标 + 版权声明
  • 按钮样式：渐变填充 + 悬停发光 + 圆角矩形
  • 无衬线 + 浅灰色正文（#374151 / #6b7280）+ 深色标题
• P1 字体与配色：
  • 主字体是否独特（Google Fonts 中非流行榜单前 20，或自选字体）
  • 配色方案是否有主题感（不是随机取色，有主色-辅色-强调色体系）
• P2 布局创意：
  • 是否有非对称或打破网格的布局尝试
  • 是否有独特的视觉语言（与常见组件库明显不同）
• 加分项（每项 +3 分，上限 +9，可抵消 P0/P1 部分扣分）：
  • 独特的配色方案（如单色系 + 对比色点缀，或基于品牌色的深度定制）
  • 有辨识度的排版（如混合衬线/无衬线、不同寻常的字重/字阶）
  • 创意布局（如杂志风、大量留白、打破四边对齐）
• 截图：标注 AI 俗套的具体表现

工艺（25分）

• P0 致命问题：
  • 间距系统严重不一致（如混用 4px / 12px / 20px 等不规则值）
  • 元素对齐明显错误（肉眼可见的错位）
• P1 细节精致度：
  • CSS 细节是否精致（圆角、阴影、边框处理是否统一风格）
  • hover / active / focus 状态是否完善（缺失任何一项扣 2 分）
  • 截图：标注工艺缺陷
• P2 一致性检查：
  • 间距系统是否符合 8px 基准网格（允许 4px / 12px / 16px / 24px / 32px / 48px）
  • 多处相似的 UI 元素样式是否统一（如同类型按钮、同级别标题）

功能性（25分）

• P0 致命问题（任一项直接扣 8 分）：
  • 点击无反应（按钮/链接完全失效）
  • 表单无法提交（submit 后无任何响应或报错）
  • 页面崩溃或白屏（无法正常加载）
• P1 核心交互：
  • 所有按钮/链接是否可点击且有响应（悬停/点击状态正确）
  • 表单是否可填写和提交（含验证反馈）
  • 页面加载是否正常，无白屏/报错
• P2 响应式与边界：
  • 响应式布局是否正常（测试 375px / 768px / 1440px）
  • 长文本/空状态/边界数据是否正常展示
• 截图：标注功能问题

评分报告格式：

## 评估报告 - 迭代 #{N}

| 维度 | 分数 | 主要问题 |
|------|------|---------|
| 设计质量 | 18/25 | 视觉层次不清晰，配色过于平淡 |
| 原创性 | 15/25 | 仍在使用 Inter 字体，缺乏独特性 |
| 工艺 | 17/25 | 按钮 hover 效果粗糙，间距不统一 |
| 功能性 | 20/25 | 移动端导航菜单无法展开 |
| **总分** | **70/100** | |

### 关键改进建议

1. **[设计质量]** 强化视觉层次：增加主标题与副标题的对比度
2. **[原创性]** 替换字体：考虑使用 Playfair Display 或 Source Serif Pro
3. **[工艺]** 完善 hover 效果：添加平滑过渡动画
4. **[功能性]** 修复移动端菜单：检查 JavaScript 事件绑定

### 证据截图

- [设计质量问题](screenshots/iteration-3-design-issue.png)
- [工艺问题](screenshots/iteration-3-craft-issue.png)
- [功能性问题](screenshots/iteration-3-functionality-issue.png)

---

Phase 3: 迭代决策

决策逻辑：

评分 >= 目标分（默认 85）?
  └─ 是 → 迭代完成，输出最终报告
  └─ 否 → 当前迭代 < 最大迭代次数（默认 15）?
              └─ 是 → 将评估报告传给 Generator，进入下一轮
              └─ 否 → 迭代上限，输出最终报告（带警告）

评分趋势记录：

| 迭代 | 设计质量 | 原创性 | 工艺 | 功能性 | 总分 |
|------|---------|-------|-----|-------|-----|
| #1   | 15      | 12    | 14  | 18    | 59  |
| #2   | 17      | 14    | 16  | 19    | 66  |
| #3   | 19      | 16    | 18  | 20    | 73  |

---

Phase 4: 最终报告

写入 .claude-studio/fro-reviews/{timestamp}/final-report.md

# GAN 前端对抗审查报告

| 字段 | 值 |
|------|---|
| **审查日期** | {YYYY-MM-DD} |
| **目标 URL** | {URL} |
| **迭代次数** | {N} |
| **最终评分** | {SCORE}/100 |
| **审查状态** | PASSED / MAX_ITERATIONS |

---

## 评分趋势

![评分趋势图](iterations/score-trend.png)

---

## 最终评分

| 维度 | 分数 | 状态 |
|------|------|------|
| 设计质量 | {N}/25 | 卓越/良好/合格/不足/不合格 |
| 原创性 | {N}/25 | 卓越/良好/合格/不足/不合格 |
| 工艺 | {N}/25 | 卓越/良好/合格/不足/不合格 |
| 功能性 | {N}/25 | 卓越/良好/合格/不足/不合格 |
| **总分** | **{SCORE}/100** | |

---

## 改进历史

### 迭代 #1
- **修改**: 初始页面生成
- **评估**: 59/100
- **主要问题**: 设计质量低、原创性差

### 迭代 #2
- **修改**: 替换字体、增加视觉层次
- **评估**: 66/100
- **主要问题**: 工艺粗糙、功能性缺陷

### 迭代 #3
- **修改**: 完善 hover 效果、修复移动端菜单
- **评估**: 73/100
- ...

---

## 核心改进建议

1. **[高优先级]** {具体建议}
2. **[中优先级]** {具体建议}
3. **[低优先级]** {具体建议}

---

## 截图对比

### 设计质量

**迭代 #1** ![](iterations/1-design.png)
**最终** ![](iterations/5-design.png)

### 功能性

**迭代 #1** ![](iterations/1-functionality.png)
**最终** ![](iterations/5-functionality.png)

---

使用参数

参数	默认值	说明
--max-iterations	15	最大迭代轮数
--target-score	85	达标目标分数
--scope	full	审查范围：full / single / diff
--port	auto	强制指定端口

---

与 /qa 的区别

维度	/takes-fro-review	/qa
目标	设计质量与原创性	功能 bug 修复
方式	GAN 对抗迭代	发现-修复循环
评分	四维量化（设计+原创+工艺+功能）	健康分（console/links/visual）
退出条件	评分达标或最大迭代	所有 bug 修复
适用	设计评审、视觉改进	功能测试、回归验证

---

注意事项

1. Generator 独立工作 —— 不给 Generator 看 Evaluator 的详细 Prompt，只传递评分报告
2. Evaluator 证据为王 —— 每项扣分必须有截图证据
3. 最小修改原则 —— 每次迭代只改必要的地方，不大刀阔斧重构
4. 时间预估 —— 一次完整审查（15 轮迭代）可能长达 4 小时，提前告知用户
5. 迭代记录累积 —— 所有截图和报告都累积保存，用于最终对比

---

降级机制（/agent-browser 不可用时）

当 /agent-browser 不可用时，按以下降级方案执行：

降级等级	触发条件	评估方式	精度影响
L0 - 完整	/agent-browser 可用	Playwright 驱动，真实浏览器截图 + 交互测试	最高（100%）
L1 - 截图	无法启动 Playwright，但可访问 URL	使用系统截图工具（PrtScn / snipping tool）或 Bash 截图命令，对每个维度人工分析截图	精度约 70%（无交互测试）
L2 - 代码审查	无法访问 URL（服务未启动）	Generator 输出代码变更，Evaluator 通过代码静态分析（AST + 样式检查）评估工艺和功能性，人工阅读截图	精度约 50%（无运行时验证）

L1 降级执行步骤：

1. Orchestrator 手动截图或调用 screenshot 命令（需用户提供截图）
2. Evaluator 基于截图逐维度分析，参照评分标准打分
3. 报告中标注"（L1 降级模式 - 无交互测试）"
4. 交互功能性维度降级为"静态分析"：通过 CSS/JS 代码审查判断实现

L2 降级执行步骤：

1. Generator 输出代码 diff，Evaluator 通过代码静态分析评估
2. 使用 ast_grep_search 检查常见问题（未绑定的 click 事件、缺失的 focus 样式等）
3. 报告中标注"（L2 降级模式 - 仅静态分析）"
4. 所有维度基准分下调 10 分（因为无法验证运行时行为）

降级通知：每次进入降级模式前，必须告知用户当前模式及精度影响，由用户决定是否继续。