dsh-verify

dsh-verify

中文 | English

Witness — 检查浏览器规格描述的行为。 浏览器断言可以暴露一些实现缺漏，但不能证明应用已完整，也不能证明它经过了独立审查。 （Witness 是产品名称；dsh-verify 是包名称——指的是同一产品。）

如果 Witness 帮你发现了问题，⭐ 给仓库点个星——这是项目得以延续的方式。

你让 AI 构建一个 Web 应用，它说“完成了”。它真的能用吗？

dsh-verify 会打开真实浏览器进行检查——这样你就不必只听 Agent 一面之词。

首次成功——无需 API 密钥

需要 Node.js 20+，并且需要一次性下载 Chromium。使用 npm install --save-dev [email protected] 安装当前 npm 版本，然后运行 npx dsh-verify init。也可以从克隆的仓库中运行：

git clone https://github.com/263311487-ux/dsh-verify && cd dsh-verify
npm ci
npx playwright install chromium
node bin/verify.mjs init
cd dsh-verify-starter
node ../bin/verify.mjs --spec dsh-verify.spec.json
# PASS (5/5), exit 0 -> dsh-verify-out/report.html
node ../bin/verify.mjs --spec dsh-verify.fail.json --out failed-report
# Intentional FAIL (4/5), exit 1 -> failed-report/report.html

打开任一 HTML 报告及其同目录下的 PNG 文件。失败的规格会故意预期错误文本；请检查断言和截图。现有的缺失 CSS 故障报告是另一个可供检查的示例。

init [directory] 只会写入本地夹具和两个 JSON 规格。它不会调用 LLM、启动浏览器或下载任何内容。目标目录必须是新目录（其父目录必须存在）；如果目录、文件或符号链接已存在，则会拒绝操作且不做任何更改。没有强制覆盖选项。安装 GitHub 包和浏览器需要互联网；这些入门检查仅使用 localhost。gen 和 MCP generate_and_verify 是可选的独立功能，需要 LLM 密钥。

要检查自己的应用，请编辑 JSON 步骤；静态文件使用 serve，已有 URL 则使用 base。serve 路径相对于命令的当前目录解析，而不是规格文件所在目录。PASS 仅适用于本次运行中提供的检查；这并不代表覆盖完整，也不能证明安全性、无障碍性或作者身份独立。应用和规格可能来自同一个 Agent；如果独立性很重要，请单独审查规格。报告会保留断言详情和明确要求的截图，但不会提供完整审计记录。

Agent 构建的 Web 应用的质量门禁。适用于任何 Agent——DeepSeek Harness（dsh）、Claude Code、Cursor、Copilot、Codex——也适用于任何 CI。你编写人们会在浏览器中检查的内容；真实浏览器会执行检查，并返回带有凭据（截图 + 差异图像）的 PASS/FAIL 判定。

没有 LLM 来评判结果。浏览器才是评判者。

相同的任务。相同的 AI。两种构建结果。少了一条 CSS 规则——Agent 的自我审查通过了，真实浏览器却发现了问题。

---

为什么会有这个项目

我们运行了一个由 4 个 Agent 组成的 Web 团队（规格编写者 → 前端开发者 → QA → 审核者）。他们的自我审核结论是：

✅ “所有要求均已满足。未发现问题。”

但在真实浏览器中，深色模式切换毫无作用——.dark 类虽然切换了，但从未编写对应的 CSS 规则。所有 Agent 的自测都通过了，因为页面上根本没有可供 Agent 执行的内容。没有人打开真实浏览器。

这就是问题所在：Agent 验证的是它们认为自己构建的内容，而不是用户实际体验到的内容。 这些检查没有测试渲染后的 CSS 行为；浏览器断言可以覆盖这一点。

构建	Agent 的说法	真实浏览器的结果
demo/buggy	“未发现问题”	❌ 失败 — 背景始终不会变化
demo/fixed	添加了一条 CSS 规则	✅ 通过 — 主题成功切换

同一页面。同一段 JS。只差一条 CSS 规则。结果却截然不同。

与其他工具的配合方式

• Playwright 脚本提供通用的浏览器 API。这个包将常见检查封装为便于审核的 JSON 规格和报告；对于此架构之外的流程，自定义脚本仍然很有用。
• LLM 评估工具可以评估开放式输出，也可能集成浏览器。这个包评估明确的浏览器断言，不由 LLM 判定结果。
• Agent 浏览器工具让 Agent 能操作页面。保存的规格让重复运行过程可供检查；是否进行独立审核，仍取决于谁编写和审核规格。
• 视觉回归工具可检测像素变化。这个包将截图比较与行为断言结合起来；覆盖范围取决于所选检查项。

三种使用方式

入口	用途	单行命令
MCP 服务	AI Agent 在会话中途验证自己的交付成果	claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp
CLI	你或你的 CI 验证构建/URL	npx dsh-verify init
GitHub Action	每次推送都会运行真实浏览器检查	uses: 263311487-ux/dsh-verify/.github/actions/dsh-verify@main

在任意 AI Agent 中使用（MCP）

claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp

然后用自然语言告诉你的 Agent：

验证 http://localhost:3000 — 点击 #dark-toggle，然后检查 body 的 background-color 是否发生变化。截取截图。

提供的工具：verify_spec（运行一个规格 JSON）、verify_url（内联检查，无需文件）、generate_and_verify（AI 起草检查清单，由真实的 Chromium 执行）、health。

在 CI 中使用（GitHub Action）

- uses: 263311487-ux/dsh-verify/.github/actions/dsh-verify@main
  with:
    spec: demo/fixed.json       # spec file or glob
    # url: https://staging.example.com   # optional override
    # out: dsh-verify-out               # report output dir (default)

该仓库也用它来验证自身：dogfood 工作流会在每次推送时断言修复版构建通过、有缺陷的构建失败。

在命令行中使用

npm install -g dsh-verify          # or: npx dsh-verify
npx playwright install chromium    # one-time browser download
npx dsh-verify --spec 'specs/*.json'
# [PASS] specs/home.json (5/5)
# [FAIL] specs/cart.json (4/5)
#   ❌ expect_text #total: got "0" want "99"

包含的功能

• 确定性断言 — Chromium、Firefox 或 WebKit 执行提供的检查：点击、填写、文本、类名、计算样式、URL、控制台/网络错误和像素。覆盖范围取决于规格和浏览器。
• 可检查的报告 — 执行相关操作时，会生成 HTML 结果以及截图和差异图像文件；CI 可使用 --json。仅凭退出码 1 无法区分断言失败和运行时错误；请像发布检查器一样检查结构化判定结果和失败的操作。
• 视觉回归 — 截图基线、带阈值的像素差异比较（expect_screenshot），以及使用 --update-baselines 刷新基线。
• 由 AI 起草的检查清单 — dsh-verify gen --url ... --prompt "..." 会在真实浏览器中探索页面，让 LLM 起草检查清单，然后确定性地执行。AI 负责起草，绝不负责判定。
• 多浏览器 — 可在每个规格中或通过 --browser 指定 chromium | firefox | webkit。
• 不绑定任何框架 — 只需一个 JSON 规格。无需配置语言、SDK 或供应商。

规格示例

{
  "title": "my app",
  "serve": "dist",
  "browser": "chromium",
  "steps": [
    { "action": "goto", "path": "/index.html" },
    { "action": "click", "selector": "#count-btn", "count": 3 },
    { "action": "expect_text", "selector": "#count-btn", "text": "Clicked: 3" },
    { "action": "capture_style", "selector": "#page", "prop": "backgroundColor", "var": "bg_before" },
    { "action": "click", "selector": "#color-btn" },
    { "action": "expect_class", "selector": "#page", "class": "dark", "present": true },
    { "action": "expect_style_changed", "selector": "#page", "prop": "backgroundColor", "var": "bg_before" },
    { "action": "screenshot", "name": "final-state" }
  ]
}

顶层字段：title、serve（静态目录）或 base（目标 URL）、browser、steps。使用 glob 一次运行多个规格；仅当全部通过时，退出码才为 0。

报告

包含相邻图片文件的 HTML 报告——每个步骤都带有通过／失败徽章、选择器和详情，并附有截图：

Agent Arena——带上你的 Agent

针对 Agent 构建的 Web 应用的真实浏览器基准测试：相同的 3 个任务、相同的人工检查、开放参赛。约 10 分钟内即可让你的模型参与测试：

git clone https://github.com/263311487-ux/dsh-verify && cd dsh-verify
npm install && npx playwright install chromium
export LLM_API_KEY=sk-...          # any OpenAI-compatible model
node arena/run.mjs --agent "gpt-5/single" --task all --repeat 1 --submitter yourname

提交结果文件供维护者审核，通过后才会显示在排行榜上： agent-arena。 完整规则见 docs/ARENA.md。

亲自验证（自行运行）

git clone https://github.com/263311487-ux/dsh-verify && cd dsh-verify
npm install && npx playwright install chromium
npm run demo:fixed    # → PASS (11/11)
npm run demo:buggy    # → FAIL (exit 1) — the missing .dark rule, caught
npm test              # engine self-tests

仓库自身的 CI 正是这样运行的——先进行引擎自测，再断言固定的通过项和有缺陷的失败项——因此该工具会在每次推送时验证自身。

Agent Arena——Agent 能交付可用的 Web 应用吗？

这是历史快照，并非当前模型排名。已提交的记录覆盖 2026-08-17–18 UTC：48 条记录，44 条 PASS、2 条 FAIL、2 条 ERROR。在有浏览器判定的 46 条记录中，44 条通过，2 条失败；两条 ERROR 记录属于运行器故障。这些记录涵盖两个模型标签 × 两种策略 × 三个静态任务（每个组合 4 条记录）。自检最多允许两轮修复，因此计算预算各不相同。模型标签是记录的标识符，并非经过独立验证的身份。

记录未锁定历史验证器／依赖项版本。生成的应用、模型回复和本地报告文件均未提交，因此无法精确复现。0.9.5 或 0.9.6 版本发布时均未进行新的 LLM 运行。请参阅方法与局限。

请参阅 docs/ARENA.md——方法、任务，以及如何运行你自己的 Agent。

为 Agent 构建的应用添加徽章

以下静态图片仅作示意，不绑定任何特定应用、提交、规格或成功运行：

[![agent deliverable: browser-verified](https://img.shields.io/badge/agent_deliverable-browser_verified-brightgreen?logo=playwright&logoColor=white)](https://github.com/263311487-ux/dsh-verify)

若要让结果与特定构建关联，请一并发布提交、规格、操作运行、判定结果和报告。请参阅 docs/verified-badge.md。

路线图

• MCP 服务 · AI 起草的检查清单 · 视觉回归 · 多浏览器 · GitHub Action · dsh 插件
• Agent Arena——公开基准测试：向不同的 Agent 配置提供相同任务，在真实浏览器中评测并发布排行榜
• 规格录制器（浏览器扩展：操作一遍 → 生成规格）
• 云端运行 + 可分享的报告链接 + PR 评论

相关项目

• dsh-doublecheck——DeepSeek Harness (/gate) 的交付质量关卡：需求审查 + 证据规范。二者相辅相成：/gate 确保证据可信，dsh-verify 确保浏览器结果可信。
• falsify——面向 AI Agent 的科学思维协议（假设 → 证伪 → 证据 → 校准后的结论）。二者配合：falsify 发现错误结论，dsh-verify 发现有问题的输出。
• 入选 DeepSeek Harness 社区精选——Show Your Plugins: dsh-verify（帖子内包含 48 次运行的 Agent Arena 结果）

许可证

MIT