用途
UX Review 是一个多智能体 UX 审查系统，会使用 Playwright CLI 浏览线上 Web 应用，面向独立开发者和小型团队产出按优先级排序、可执行的报告。
前置条件
需要安装 Playwright CLI。如果不可用，运行：
npm install -g @playwright/cli@latest playwright-cli install-browser playwright-cli install --skills
用 playwright-cli --help 验证。
输入
用户提供以下内容：
- 目标 URL（必填）——应用入口点（落地页、登录页、仪表盘等）。
- 关键用户流程（可选）——要测试的具体路径，例如“注册 → 创建项目 → 邀请团队”。
- 目标受众（可选）——谁使用该应用以及他们的期望。
- 关注领域（可选）——哪些审查维度最重要（见下方智能体名单）。
- 上下文文件（可选）——包含应用描述、已知问题、约束条件的 markdown 文件。
如果用户未提供可选输入，使用合理的默认值并注明假设。
智能体名单
每个智能体有专门的视角。所有智能体都使用 Playwright CLI 与线上应用交互。
- 第一印象（First Impression）：落地页清晰度、价值主张、CTA、信任信号、加载感知，参考 agents/first-impression.md。
- 信息架构（Information Architecture）：导航、页面层级、命名、可发现性、心智模型，参考 agents/information-architecture.md。
- 用户流程（User Flow）：任务完成路径、摩擦、死胡同、错误恢复、引导，参考 agents/user-flow.md。
- 视觉设计（Visual Design）：间距、排版、颜色、组件一致性、响应式提示，参考 agents/visual-design.md。
- 可访问性（Accessibility）：WCAG 合规、键盘导航、ARIA、对比度、表单标签、错误状态，参考 agents/accessibility.md。
- 文案与微文案（Copy & Microcopy）：按钮标签、错误消息、空状态、引导文案、语气，参考 agents/copy-review.md。
- 综合（Synthesizer）：读取所有智能体报告，产出按优先级排序的行动计划，参考 agents/synthesizer.md。
工作流程
阶段 1：设置
- 确认目标 URL 以及用户提供的任何上下文。
- 确保已安装 Playwright CLI（playwright-cli --help）。
- 打开浏览器会话：playwright-cli open <url>。
- 截取初始截图以确认页面已加载：playwright-cli screenshot --filename=landing.png。
- 捕获快照用于结构分析：playwright-cli snapshot --filename=landing-snapshot.txt。
- 为输出创建 workspace 目录。
阶段 2：发现（主智能体）
在生成审查智能体之前，先做一次快速站点爬取以了解范围：
- 捕获落地页快照。
- 从快照中识别主导航链接。
- 访问 3-5 个关键页面（跟随导航链接）并分别快照。
- 构建已发现页面的简单站点地图。
- 将发现结果保存到 workspace/discovery.md。
该发现输出会作为上下文共享给所有审查智能体。
阶段 3：并行审查（子智能体）
并行生成智能体 1-6。每个智能体接收：
- 目标 URL
- 发现文件（workspace/discovery.md）
- 其专属智能体指令（来自 agents/*.md）
- Playwright CLI 参考（references/playwright-guide.md）
- 启发式参考（references/heuristics.md）
- 用于存放其发现的输出目录
每个智能体：
- 在自己的 Playwright CLI 会话中打开应用（-s=<agent-name>）。
- 浏览相关页面。
- 截取快照和截图作为证据。
- 将发现写入其输出文件。
如果子智能体不可用，则在主循环中依次运行每个审查。
阶段 4：综合
所有审查完成后，综合智能体：
- 读取全部 6 份智能体报告。
- 对重复发现去重。
- 按严重程度分类（Critical / High / Medium / Low）。
- 按影响与工作量排序（对独立开发者至关重要）。
- 产出最终报告。
阶段 5：输出
按照 references/report-template.md 中的模板生成最终交付物，格式为 markdown 报告。保存到 workspace 并呈现给用户。
智能体的 Playwright CLI 快速参考
每个智能体应使用命名会话以避免冲突：
Agent opens its own session
playwright-cli -s=first-impression open <url>
Navigate
playwright-cli -s=first-impression goto <url>
Capture page structure (element refs, text, layout)
playwright-cli -s=first-impression snapshot --filename=<name>.txt
Take visual screenshot
playwright-cli -s=first-impression screenshot --filename=<name>.png
Interact with elements (using refs from snapshot)
playwright-cli -s=first-impression click <ref> playwright-cli -s=first-impression type <text> playwright-cli -s=first-impression fill <ref> <text>
Check navigation
playwright-cli -s=first-impression tab-list
Close when done
playwright-cli -s=first-impression close
完整命令参考见 references/playwright-guide.md。
输出结构
workspace/ ├── discovery.md # Site structure from Phase 2 ├── screenshots/ # Visual evidence │ ├── landing.png │ ├── nav-*.png │ └── ... ├── agents/ │ ├── first-impression.md │ ├── information-architecture.md │ ├── user-flow.md │ ├── visual-design.md │ ├── accessibility.md │ └── copy-review.md └── ux-review-report.md # Final synthesized report
协调者职责
- 需要时处理 Playwright CLI 安装。
- 运行发现阶段以构建共享上下文。
- 并行生成审查智能体（如果没有子智能体则依次运行）。
- 确保每个智能体使用自己的命名会话（-s=<name>）。
- 收集所有智能体报告。
- 运行综合器以产出最终报告。
- 清理浏览器会话：playwright-cli close-all。
- 将最终报告呈现给用户。
自定义
用户可以通过以下方式自定义审查：
- 跳过智能体：“跳过可访问性，聚焦用户流程和文案”。
- 添加竞品 URL：包含对比分析。
- 指定用户故事：“专门测试结账流程”。
- 设置优先级：“我最关心转化，不太关心可访问性”。
- 提供上下文：“这是一个面向项目经理的 B2B SaaS”。
据此调整智能体名单和指令。