前言¶
智能体在开发 Web 应用后，往往会给出“任务完成”的反馈。然而，代码层面的自检可能通过，但页面实际表现（交互、样式、视觉）可能存在问题。单元测试难以覆盖视觉回归或真实用户交互场景。
dsh-verify 是一个为智能体构建的 Web 应用提供质量门控的工具。它提供真实浏览器的验收测试能力，支持 CLI、MCP 服务器和 GitHub Action 三种运行方式，确保应用在真实浏览器环境中表现符合预期。
插件简介¶
dsh-verify 是一个基于 Playwright 的质量检查插件，旨在解决智能体自测与真实用户体验之间的鸿沟。它维护者为 263311487-ux，采用 MIT 许可证。
插件核心价值在于将“浏览器”作为独立的裁决者。它不依赖 LLM 的主观判断，而是通过执行真实的点击、输入、样式检查和截图对比，返回确定的 PASS 或 FAIL 结果。
核心能力¶
基于已核实的事实，该插件包含以下核心功能：
- 真实浏览器验收测试：基于 Playwright 引擎，执行人类在浏览器中的常规操作（点击、填表、检查样式）。
- MCP 服务器支持：可与 Claude Code、Cursor、Copilot 等工具集成，允许智能体在会话中调用浏览器验证。
- GitHub Action 集成：支持在 CI 流程中运行，每次 Push 都可触发真实浏览器检查。
- AI 起草检查清单：提供
gen命令，允许 AI 根据页面 URL 和 Prompt 生成测试规范并自动执行。 - 视觉回归：支持截图对比和差异检测，用于捕获视觉漂移。
- 多浏览器支持：支持 Chromium、Firefox、WebKit。
- JSON 规范化测试：测试逻辑以 JSON 格式编写，便于复用和版本控制。
安装与启用¶
使用前需安装 Node.js 环境及 Playwright 浏览器。
- 全局安装插件
npm install -g dsh-verify
- 安装 Playwright 浏览器
首次使用需下载 Chromium 浏览器：
npx playwright install chromium
使用方式¶
插件提供 CLI、MCP 和 GitHub Action 三种主要使用方式。
CLI 命令行¶
在命令行中运行测试规范文件或 glob 匹配：
npx dsh-verify --spec 'specs/*.json'
MCP 服务器集成¶
将 MCP 服务器添加到 Claude Code 或 Cursor 中，以便智能体调用：
claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp
GitHub Action 集成¶
在 CI 配置文件中使用官方 Action：
- uses: 263311487-ux/dsh-verify/.github/actions/dsh-verify@main
with:
spec: demo/fixed.json # 指定规范文件或 glob
# url: https://staging.example.com # 可选：覆盖规范中的 base
注意事项¶
- 运行环境：插件依赖
@modelcontextprotocol-sdk、playwright和pngjs。 - Node.js 版本：需要 Node.js 版本大于等于 18。
- 权限与安全：插件以当前 dsh 进程的权限运行，安装前请检查源码与许可证。
- 浏览器依赖：每次首次使用或更新 Playwright 版本后，可能需要重新执行
npx playwright install。
总结¶
dsh-verify 作为一个独立的浏览器验收工具，通过 JSON 规范与真实浏览器执行解耦，为 Agent 构建的应用提供了可靠的回归测试能力。无论是 CI 流水线中的自动化检查，还是开发过程中的交互验证，它都能提供客观的通过/失败反馈。
