frontend-visual-analysis

这是一个面向前端项目的 Codex skill，用于指导 Codex 复用或搭建视觉分析自动化流程。

适用任务

• 自动截图和页面巡检
• UI 视觉回归分析
• Canvas、WebGL、3D 页面渲染检查
• console、network、pageerror、requestfailed 收集
• 生成截图、manifest、baseline 状态和问题报告

设计边界

本 skill 只保留通用流程和判断标准，不包含任何项目专属内容。下面这些信息应写在具体项目的 AGENTS.md 中：

• 项目启动命令
• 默认页面路径
• 调试 query 参数
• artifact 目录
• 视觉基线更新规则
• 项目专属 MCP、Playwright、Cypress 或本地脚本入口

文件说明

• SKILL.md：Codex skill 主文件，包含触发描述、工作流程、校验标准和失败恢复建议。
• scripts/capture-page.mjs：通用单页截图脚本。
• scripts/capture-matrix.mjs：通用场景矩阵截图脚本。
• scripts/lib/visual-capture-utils.mjs：两个截图脚本共用的参数解析、视口解析、遥测收集和 manifest 工具。

依赖要求

skill 本身不需要安装依赖，但如果要运行内置截图脚本，目标前端项目需要安装 Playwright：

npm install -D @playwright/test
node node_modules/@playwright/test/cli.js install chromium

脚本应从目标项目根目录执行。它们会优先加载目标项目中的 @playwright/test。

单页截图

先启动目标项目，例如：

npm run dev

然后运行：

node eye_skill/scripts/capture-page.mjs \
  --url http://127.0.0.1:5173/ \
  --label home-desktop \
  --viewport desktop \
  --out artifacts/visual/current \
  --wait 1000

输出：

• artifacts/visual/current/home-desktop.png
• artifacts/visual/current/home-desktop.json

常用参数：

• --viewport desktop：1440x900
• --viewport mobile：iPhone 13 近似视口
• --viewport 1280x720：自定义尺寸
• --selector "#app"：等选择器出现后截图
• --ready-expression "window.__APP_READY__ === true"：等页面表达式为真
• --diagnostics-expression "window.__APP_DIAGNOSTICS__?.getDiagnostics?.()"：采集项目自定义诊断
• --full-page：截取整页
• --headed：打开可见浏览器

场景矩阵截图

创建项目自己的 visual-scenarios.json：

{
  "baseUrl": "http://127.0.0.1:5173",
  "outDir": "artifacts/visual/current",
  "defaults": {
    "waitMs": 1000,
    "viewport": "desktop",
    "selector": "#app"
  },
  "scenarios": [
    {
      "label": "home-desktop",
      "route": "/",
      "viewport": "desktop"
    },
    {
      "label": "home-mobile",
      "route": "/",
      "viewport": "mobile"
    },
    {
      "label": "settings",
      "route": "/settings",
      "query": {
        "debug": "1"
      },
      "waitMs": 1500
    }
  ]
}

运行：

node eye_skill/scripts/capture-matrix.mjs --config visual-scenarios.json

输出：

• 每个场景的 PNG
• 每个场景的同名 JSON
• manifest.json

遥测与诊断

脚本会自动收集：

• console 消息
• pageerror
• requestfailed
• HTTP 4xx/5xx response

如果页面暴露以下任一诊断桥，脚本会自动读取：

• window.__VISUAL_INSPECTOR__
• window.__APP_DIAGNOSTICS__
• window.__VISUAL_DIAGNOSTICS__

诊断桥可选实现：

window.__APP_DIAGNOSTICS__ = {
  whenReady: async () => {},
  getDiagnostics: () => ({ ready: true })
}

仍需项目自己负责的部分

• 启动 dev server 或 preview server
• 准备登录态、测试数据和环境变量
• 决定要检查哪些页面
• 决定 baseline 更新规则
• 如需像素级差异，接入项目自己的 diff 工具