dsh-verify（Witness）· 智能体说做完了，浏览器来证明

你让 DeepSeek Harness（或其他 AI）帮你写了个网页。它说"做完了"。你敢直接上线吗？

dsh-verify 会打开一个真实的浏览器，把你写好的检查清单一步步执行一遍：点击、输入、看样式、查控制台报错、对比截图。通过就是 PASS，不通过就是 FAIL，还附带截图证据。

评判者不是 AI，是真实浏览器。

如果 Witness 帮你抓到了问题，⭐ 给仓库点个星——这是这个项目活下去的方式。

---

为什么需要它

我们跑了一个 4-agent 网页开发团队（需求 → 前端 → QA → 评审）。团队的自我评审结果是：

✅ "所有需求均已满足，无问题。"

但用真实浏览器打开后，暗色模式切换按钮完全没有反应——JS 切换了 .dark 类，但 .dark 的 CSS 规则根本没写。

每个 agent 的"自测"都通过了，因为页面上根本没有可运行的东西。没有人打开过真实浏览器。

构建	agent 自评	真实浏览器结论
demo/buggy（少一条 CSS 规则）	"无问题"	❌ FAIL —— 背景色永远不变
demo/fixed（补上一条 CSS 规则）	已修复	✅ PASS —— 主题正常切换

同一页面、同一段 JS，只差一条 CSS 规则，两种完全不同的结论。

单元测试和静态检查抓不到"少了一条 CSS 规则"这种问题。 agent 是在验证"自己以为做出来的东西"，不是在验证"用户真正体验到的页面"。

怎么用（三种方式）

① 命令行（最直接）

▼
bash
复制代码
# 一条命令：写个 JSON 检查清单，真实浏览器跑一遍
npx dsh-verify --spec spec.json

检查清单长这样（都是"人会在浏览器里检查什么"）：

▼
json
复制代码
[
  { "action": "goto", "url": "http://localhost:3000" },
  { "action": "click", "selector": "#color-btn" },
  { "action": "expect_style_changed", "selector": "#page", "prop": "backgroundColor" }
]

跑完输出 PASS (6/6) 或 FAIL (4/6)，并生成一份带截图的 HTML 报告。

② MCP 服务（给 Claude Code / Cursor / Copilot 用）

让 AI 自己也能"打开真实浏览器自查"：

• verify_spec —— 按 JSON 规范跑真实浏览器检查
• verify_url —— 直接检查一个网址
• generate_and_verify —— AI 起草检查清单，真实浏览器强制执行（AI 永远不给自己打分）

已收录于 glama.ai 与 awesome-dsh-plugin。

③ GitHub Action（接入 CI）

一个步骤跑完验收，带报告产物：

▼
yaml
复制代码
- uses: 263311487-ux/dsh-verify@v0.9.0
  with:
    spec: demo/fixed.json
    out: dsh-verify-out

实测数据（48 次真实浏览器运行）

模型	单次生成	自检循环
DeepSeek V4 Flash	11/12 通过	11/12 通过
DeepSeek V4 Pro	10/12 通过	12/12 通过

最有说服力的一个结果：最不稳的"待办清单"任务，加上自检循环后从 6/8 提到 8/8——差的不是智力，是验证。

• 完整排行榜（开放提交，带上你的 agent 上榜）：Agent Arena
• 演示站：https://263311487-ux.github.io/dsh-verify/

特性一览

• ✅ JSON 规范，无框架：goto → click → expect_text → capture_style → expect_style_changed
• ✅ 真实 Chromium（Playwright 驱动，默认无头）
• ✅ 校验计算样式而不是 class 列表（正是能抓到"class 切了但 CSS 没写"的那类问题）
• ✅ 视觉回归：像素级截图对比 + 红色高亮差异图
• ✅ AI 起草检查清单：dsh-verify gen --url <url> --run
• ✅ MCP 服务 + GitHub Action + HTML 报告 + 退出码 0/1
• ✅ 多浏览器（Chromium / Firefox / WebKit）

快速开始

▼
bash
复制代码
git clone https://github.com/263311487-ux/dsh-verify
cd dsh-verify
npm install
npx playwright install chromium
npm run demo:buggy   # FAIL —— 本仓库最想展示的那个 bug
npm run demo:fixed   # PASS

常见问题

Q：和手写 Playwright 脚本有什么区别？ A：JSON 规范本身就是"需求文档"，一次编写，agent 和 CI 都能复用；而且不用每个项目重写一遍样板代码。

Q：和 LLM 裁判（promptfoo 之类的评测）有什么区别？ A：LLM 说"看起来没问题"，它没有运行你的应用、没有看到像素。真实浏览器会执行点击、输入、样式断言，并返回截图证据。

Q：agent 自己也有浏览器工具，为什么还要它？ A：agent 的浏览器工具是 agent 自己的"手"——和它刚写出来的代码共享同一个盲区。dsh-verify 是独立的见证者，不属于被测试的 agent。

生态收录

• awesome-dsh-plugin · DeepSeek Harness 插件商店 · glama.ai MCP 目录 · unStone/dsh-xray

License

MIT