dsh-verify

dsh-verify

中文 | 英語

Witness — ブラウザ仕様書に記述された動作を確認します。 ブラウザでのアサーションによって実装上の不足が見つかることはありますが、アプリが完成していることや、独立したレビューを受けていることを証明するものではありません。 （Witness は製品名、dsh-verify はパッケージ名です。同じものを指しています。）

Witness が何かを見つけてくれたら、⭐ リポジトリにスターを付けてください — それがこのプロジェクトを存続させる力になります。

AI にウェブアプリの構築を頼みました。AI は「完了しました」と言いました。本当に動作するのでしょうか？

dsh-verify は実際のブラウザを起動して動作を確認するため、エージェントの言葉を信じる必要はありません。

まずは動かしてみる — API キー不要

Node.js 20 以降と、初回のみ Chromium のダウンロードが必要です。現在の npm リリースを npm install --save-dev [email protected] でインストールし、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] が書き込むのは、ローカルのフィクスチャと 2 つの JSON 仕様書だけです。LLM の呼び出し、ブラウザの起動、ダウンロードは行いません。保存先は新規である必要があります（親ディレクトリは存在している必要があります）。既存のディレクトリ、ファイル、シンボリックリンクがある場合は変更せずに拒否されます。強制実行／上書きオプションはありません。GitHub パッケージとブラウザのインストールにはインターネット接続が必要です。これらのスターターチェックでは localhost のみを使用します。gen と MCP の generate_and_verify はオプション機能で、LLM キーが必要です。

自分のアプリを確認するには、JSON のステップを編集してください。静的ファイルには serve を、既存の URL には base を使用します。serve のパスは仕様書の場所ではなく、コマンドの実行時のカレントディレクトリを基準に解決されます。PASS が適用されるのは、その実行で指定されたチェックのみです。網羅性、セキュリティ、アクセシビリティ、独立した作成者を保証するものではありません。アプリと仕様書が同じエージェントによって作成されている場合もあります。独立性が重要な場合は、仕様書を別途レビューしてください。レポートに保持されるのは、アサーションの詳細と明示的に要求されたスクリーンショットであり、完全な監査証跡ではありません。

エージェントが構築したウェブアプリの品質ゲートです。DeepSeek Harness（dsh）、Claude Code、Cursor、Copilot、Codex など、あらゆるエージェントで、またあらゆる CI で動作します。ブラウザで人が確認する内容を書けば、実際のブラウザが実行し、証拠（スクリーンショットと差分画像）とともに PASS／FAIL の判定を返します。

結果を判定する LLM はありません。判定するのはブラウザです。

同じタスク。同じ AI。2 つのビルド。CSS ルールが 1 つ不足していました — エージェント自身のレビューでは問題なしでしたが、実際のブラウザが見つけました。

---

これが存在する理由

4つのエージェントで構成されたウェブチーム（仕様作成 → フロントエンド開発 → QA → レビュー）を運用しました。チーム自身のレビューは次のとおりでした。

✅ 「すべての要件を満たしています。問題は見つかりませんでした。」

実際のブラウザーでは、ダークモードの切り替えは何も起こしませんでした。.dark クラスは切り替わっていましたが、CSS ルールが記述されていなかったのです。ページにはエージェントが実行できるものが何もなかったため、すべてのエージェントのセルフテストは合格しました。実際のブラウザーを開いた人は誰もいませんでした。

これがギャップです。エージェントは、ユーザーが実際に体験する内容ではなく、自分たちが構築したと考えている内容に対して検証します。 こうしたチェックでは、レンダリングされた CSS の動作を検証できませんでした。ブラウザーでのアサーションなら検証できます。

ビルド	エージェントの評価	実際のブラウザーの評価
demo/buggy	「問題は見つかりませんでした」	❌ 失敗 — 背景色が変わりません
demo/fixed	CSS ルールを1つ追加	✅ 合格 — テーマが切り替わります

同じページ。同じ JS。足りない CSS ルールは1つ。評価は2通りです。

他のツールとの関係

• Playwright スクリプトは汎用的なブラウザー API を提供します。このパッケージでは、一般的なチェックをレビュー可能な JSON 仕様とレポートとして提供します。このスキーマでは扱えないフローには、カスタムスクリプトも引き続き役立ちます。
• LLM 評価ツールは自由形式の出力を評価でき、ブラウザーと連携することもあります。このパッケージは、LLM に結果を判断させずに、明示的なブラウザーアサーションを評価します。
• エージェント向けブラウザーツールを使うと、エージェントがページを操作できます。保存された仕様により、繰り返し実行した結果を確認できます。独立したレビューができるかどうかは、仕様を作成してレビューする人に左右されます。
• ビジュアルリグレッションツールはピクセルの変化を検出します。このパッケージは、スクリーンショットの比較と動作アサーションを組み合わせます。カバレッジは選択したチェックによって異なります。

3通りの使い方

エントリーポイント	用途	1行のコマンド
MCP サーバー	AI エージェントがセッション中に自分の成果物を検証します	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 エージェントから（MCP）

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

次に、エージェントに自然な言葉で指示します。

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 テストとして、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 です。グロブを使って複数を一度に実行できます。すべてが合格した場合に限り、終了コードは 0 になります。

レポート

画像ファイルが隣接する HTML レポートです。各ステップの合否バッジ、セレクター、詳細に加え、スクリーンショットも表示されます。

Agent Arena — エージェントを参加させる

エージェントが構築した 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 — エージェントは動作する Web アプリをリリースできるか？

過去のスナップショットであり、現在のモデルランキングではありません。コミット済みの記録は2026-08-17–18 UTCのもので、48 件の記録、44 件の合格、2 件の不合格、2 件のエラーです。ブラウザー判定がある 46 件のうち、44 件が合格し、2 件が不合格でした。2 件のエラーはランナーの失敗です。記録は、2 つのモデルラベル × 2 つの戦略 × 3 つの静的タスクを対象としています（各組み合わせにつき 4 件）。セルフチェックでは最大 2 回の修正ラウンドが許可されるため、計算予算は異なります。モデルラベルは記録された識別子であり、個別に検証された身元ではありません。

記録には、当時の検証ツール／依存関係のバージョンが固定されていません。生成されたアプリ、モデルの応答、ローカルのレポートファイルはコミットされていないため、完全な再現には限界があります。0.9.5 または 0.9.6 のリリースにあたり、新たな LLM 実行は行われていません。方法論と制約をご覧ください。

docs/ARENA.mdでは、方法論、タスク、独自のエージェントを実行する方法について説明しています。

エージェントが構築したアプリにバッジを付ける

以下の静的画像は説明用にすぎません。特定のアプリ、コミット、仕様、実行成功のいずれにも紐づいていません：

[![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 — 公開ベンチマーク：異なるエージェント構成に同じタスクを与え、実ブラウザーで評価して、リーダーボードを公開します
• 仕様レコーダー（ブラウザー拡張機能：一度操作するだけで仕様を生成）
• クラウド実行 + 共有可能なレポートリンク + PR コメント

関連プロジェクト

• dsh-doublecheck — DeepSeek Harness（/gate）向けのデリバリー品質ゲート：要件の厳密な確認 + エビデンスの徹底。相互補完の関係にあり、/gate はエビデンスの信頼性を守り、dsh-verify はブラウザーでの動作を検証します。
• falsify — AI エージェント向けの科学的思考プロトコル（仮説 → 反証 → エビデンス → 確度を調整した結論）。相互に補完し、falsify は誤った結論を見つけ、dsh-verify は壊れた出力を見つけます。
• DeepSeek Harness コミュニティで紹介されました — プラグインを紹介しよう：dsh-verify（スレッド内に Agent Arena の 48 件の実行結果を掲載）

ライセンス

MIT