mcpField
F
frontend-visualqa

frontend-visualqa

github.com/yutori-ai测试与质量1058 次安装4 周前更新
代码仓库

关于 frontend-visualqa

这是一项在代码更改后通过截图证据检查前端实际渲染效果的技能，适合 Agent 验证指定路由、视觉状态和响应式行为。它优先使用浏览器工具，MCP 工具不可用时可改用命令行。

主要功能

  1. 01依据截图核验视觉声明
  2. 02检查裁切、溢出、可见性和响应式表现
  3. 03测试菜单、模态框等交互状态
  4. 04支持认证流程的持久浏览器会话
  5. 05MCP 工具不可用时提供命令行备用方案

适用场景

  1. 01确认页面处于预期路由或界面状态
  2. 02检查更改后的布局裁切与文本截断
  3. 03验证菜单、标签页、提示或禁用按钮
  4. 04为视觉 QA 报告留存截图证据

MCP 相关

该技能优先使用 frontend-visualqa MCP 工具，包括 verify_visual_claims、take_screenshot 和 manage_browser。MCP 服务不可用时，说明可使用命令行备用方案。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/yutori-ai/frontend-visualqa --skill frontend-visualqa

安装后在 Claude Code 中输入/frontend-visualqa确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
claim-writing.md
install.md
protocol.md

详细介绍

前端视觉 QA

在更改 UI 代码后，如果 DOM 断言不足以验证结果，且需要通过截图确认页面的实际渲染效果，请使用此技能。

适用于：

  • 确认 Agent 是否位于正确的路由或 UI 状态
  • 检查可见性、裁切、溢出、z-index、截断和响应式行为
  • 验证交互状态，例如模态框、菜单、Toast、标签页和禁用按钮

不适用于：

  • 启动开发服务器
  • “让它看起来更好”这类模糊请求
  • 对大型应用界面进行大范围视觉差异比较

快速开始

  1. 确保前端已在本地运行。
  2. 如果可用，优先使用 frontend-visualqa MCP 工具。它们可以在多次调用间保留浏览器状态。
  3. 如果页面需要身份验证，且用户可以协助，请使用 action="login" 和登录 URL 调用 manage_browser。这会打开一个持久的有头浏览器，供用户完成身份验证。之后重复使用相同的 session_key，并在完成身份验证会话后调用 manage_browser(action="close", ...)。
  4. 如果用户提供了 URL 和明确的断言，请直接使用 verify_visual_claims——它会在内部截取截图，因此无需另行调用 take_screenshot。
  5. 只有在尚无断言、需要先查看页面再编写断言时，才先调用 take_screenshot。
  6. 修复前端，然后重复运行相同的断言，直到全部通过。

断言规范

断言必须能从像素中观察到。示例和反面案例请参阅 references/claim-writing.md。

如果断言需要交互后才能判断真假，请传入 navigation_hint。断言应聚焦于最终可见状态，不要把多步骤脚本塞进断言文本。

对于只有部分断言需要设置步骤的多断言流程，优先使用断言文件，并将各断言的元数据放在对应的条目下，例如：

- After logging in, the dashboard shows "Welcome back, Developer"
  - navigation_hint: Type "[email protected]" in the email field, type "password123" in the password field, then click Continue.
- The API Calls Today stat card shows the value 1,247

使用 MCP 时，如果各断言的设置不同，请分多次连续调用 verify_visual_claims 来验证暖会话。不要期望单个全局导航提示能在一个批次中有选择地应用。

会话策略

对于公开页面和快速检查，使用临时模式。

对于需要身份验证的应用、多步骤流程，或任何需要在多次运行间保留 Cookie 和本地存储的情况，使用持久模式。在 MCP 驱动的工作流中，运行断言前，先使用 manage_browser(action="login", ...) 完成身份验证初始化。

设置和客户端专用的安装命令位于 references/install.md。 详细的 QA 操作指南、状态含义和恢复步骤位于 references/protocol.md。

向用户展示证明材料

每个工具响应都包含截图证据的文件路径。务必展示这些证明材料，不要只总结文本结果。

verify_visual_claims 会返回一个 artifacts_dir；对每条断言，还会返回 results[].proof.screenshot_path（关键截图）和 results[].proof.text（文本摘要）。中间步骤的其他截图位于 results[].trace.screenshot_paths。

take_screenshot 会返回一个 screenshot_path。

验证完成后：

  1. 对于失败或结果不确定的断言，读取其证明截图文件，以便描述视觉问题。
  2. 向用户展示截图路径；如果客户端支持，请直接打开或以内嵌形式显示图片。
  3. 总结结果时，请引用具体的视觉证据，不要只重复文本结论。

如果客户端无法内嵌显示图片，请打印绝对路径，以便用户手动打开。

工具优先级

按以下顺序优先使用工具：

  • 用户提供断言时使用 verify_visual_claims——这是主要工具，会自行截取截图
  • 只有在编写断言前需要先查看页面时，才使用 take_screenshot
  • 共享浏览器状态过期、尺寸不正确或需要重置时，使用 manage_browser

如果 MCP 服务不可用，请使用 references/install.md 中的 CLI 回退方案。

$ARGUMENTS

评论

支持 Markdown