ViewportWitness by Apex Labs

Apex Labs 推出的 ViewportWitness

签字验收前检查已部署的网站。 无需设置浏览器，即可获取涵盖三种屏幕尺寸的截图、无障碍和布局证据。仅支持公开 HTTPS 页面。

免费示例报告 · 从无需付款的预算预览开始

该示例是一个静态的本地测试演示。部署此更改后，即可访问其公开 URL。

两款资源占用低的付费 Agent 工具可补充浏览器 QA：extract_page 将一个公开 HTML 页面转换为确定性 Markdown，费用为 $0.005 USDC；web_release_gate 被动检查一个公开页面的发布安全控制，费用为 $0.05 USDC。两者共用 Base/Solana x402 支付通道、幂等保护、单工作器队列和七天报告生命周期。它们不接受调用方提供的 HTML、凭据、Cookie、自定义标头、上传内容或私有网络目标。

用于 AI Agent 浏览器 QA 的远程 MCP 服务和 x402 API。提交一个公开 HTTPS URL，即可获取涵盖手机和桌面视口的截图、无障碍问题、布局分析和结构化 JSON。

线上服务位于 **https://qa.honeygate.app**。标准报告费用为 $0.08 USDC，只读断言费用为 $0.10，基线比较费用为 $0.12。本地实例可在测试模式下运行，无需付款。

• 官方 MCP Registry 条目
• ChatGPT、Claude、Codex、Cursor 和 VS Code 的 MCP 设置
• 隐私政策 · 条款 · 支持

---

线上服务

# Probe the live service (returns 402 with payment requirements)
curl -s -X POST https://qa.honeygate.app/v1/checks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

# Payment discovery
curl -s https://qa.honeygate.app/.well-known/x402 | jq .

# Agent skill manifest
curl -s https://qa.honeygate.app/skill.md

付费请求请使用支持 x402 的客户端（例如搭配已充值钱包的 @x402/fetch）。 完整的 Agent 使用指南请参阅 llms.txt。

---

付费产品示例

向任何付费端点发送普通 HTTP 请求都会返回 HTTP 402——其中包含网络、资产、金额和目标地址的 x402 挑战。支持 x402 的客户端（例如搭配已充值钱包的 @x402/fetch）会支付该挑战并自动重试；你的代码会收到成功的 JSON 结果。以下示例仅展示请求格式——开发期间请勿调用线上服务或发送付款；请在本地使用 PAYMENT_MODE=test（参见本地开发）。

POST /v1/checks — 0.08 USDC

提交一个公开 HTTPS URL，即可获取涵盖手机和桌面视口的截图、无障碍问题、布局分析和浏览器错误。

// x402-aware client pays the 402 challenge and retries automatically
const { id, pollUrl } = await fetch402('https://qa.honeygate.app/v1/checks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' }),
}).then((r) => r.json())
// Poll GET pollUrl until { status: 'complete' }

POST /v1/verify — 0.10 USDC

针对线上公开 HTTPS URL 运行明确的只读断言。工作器只执行非修改性检查——不会提交表单，也不会点击购买或删除控件。

const { id, pollUrl } = await fetch402('https://qa.honeygate.app/v1/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://example.com',
    assertions: [
      { type: 'selectorVisible', selector: 'h1' },
      { type: 'titleIncludes', value: 'Example Domain' },
    ],
  }),
}).then((r) => r.json())

POST /v1/compare — 0.12 USDC

将当前渲染结果与基线任务进行比较。baselineJobId 必须指向一个已完成且未过期的 ViewportWitness 检查任务，并且该任务须包含全部三个视口（phonePortrait、phoneLandscape、desktop）的截图。基线会在七天后过期。如果基线任务仍在等待处理、已失败，或缺少任一视口的截图，则请求会被拒绝。

const { id, pollUrl } = await fetch402('https://qa.honeygate.app/v1/compare', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://example.com',
    baselineJobId: 'JOB_ID_FROM_PREVIOUS_CHECKS',
  }),
}).then((r) => r.json())

安全性：仅接受公开 HTTPS URL。每一跳都会拦截回环、私有、链路本地和元数据地址。浏览器工作器不会修改目标内容——不会提交表单，也不会执行任何会改变状态的交互。

---

本地开发

npm install
npx playwright install chromium
cp .env.example .env
npm run dev

# Create a check (test mode — no payment required)
curl -s -X POST http://localhost:3000/v1/checks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}' | jq .

# Poll result
curl -s http://localhost:3000/v1/checks/JOB_ID | jq .status

# Get screenshot
curl -o desktop.png http://localhost:3000/v1/checks/JOB_ID/screenshots/desktop

本地默认使用 PAYMENT_MODE=test。测试模式无需 CDP 密钥。结果会标记为 paymentMode: "test"，且不代表真实支付结算。

---

API

Method	Path	Description
GET	/	服务信息
GET	/health	存活探测
GET	/ready	就绪探测（数据库 + 工作器）
GET	/openapi.json	OpenAPI 3.1 规范
GET	/llms.txt	Agent 使用指南
GET	/skill.md	精简的 Agent 技能清单
GET	/privacy	隐私政策
GET	/terms	服务条款
GET	/logo.png	目录和集成徽标
GET	/.well-known/x402	支付发现
POST	/v1/checks	创建 QA 检查任务
POST	/v1/verify	检查明确的只读断言
POST	/v1/compare	与未过期的基线任务进行比较
POST	/mcp	提供 x402 付费工具的远程 MCP 接口
GET	/v1/checks/:id	轮询任务状态 / 获取报告
GET	/v1/checks/:id/screenshots/:viewport	下载截图 PNG
GET	/v1/checks/:id/diffs/:viewport	下载对比差异 PNG

页面历史归档（默认关闭）

启用 ARCHIVE_ENABLED=true 后，每个已完成的 check、verify 和 compare 报告也会被复制到单独的归档（ARCHIVE_DIR）中，其保留时间超过七天的任务保留期。Agent 随后可以请求某个确切公开 URL 的历史快照。归档副本仅保存公开页面证据（截图、问题发现、判定结果）；不保存任务 ID、付款数据、调用方断言和基线引用。

Method	Path	Description
GET	/v1/history/availability?url=	免费：快照数量及其时间范围
POST	/v1/history	付费（HISTORY_PRICE_USDC，默认 0.02）：列出快照
GET	/v1/history/snapshots/:id	完整归档快照（ID 来自付费列表）
GET	/v1/history/snapshots/:id/screenshots/:viewport	归档截图 PNG

POST /v1/history 接受 { "url": "https://example.com", "limit": 5, "before": "<ISO time>" }，并按从新到旧的顺序返回快照，同时提供 nextBefore 游标。对于没有快照的 URL，已签名请求会在任何付款结算前返回 404 no_snapshots。限制在 .env 中设置：ARCHIVE_RETENTION_DAYS（90）、ARCHIVE_MAX_STORAGE_GB（5）、ARCHIVE_MAX_SNAPSHOTS_PER_URL（30）、HISTORY_MAX_RESULTS（10）。

视口：phonePortrait（375×812）、phoneLandscape（812×375）、desktop（1440×900）

---

付款模式

模式	是否需要付款	网络
test	否	—（仅用于本地开发）
testnet	是（x402）	Base Sepolia；Solana Devnet 可选
production	是（x402，$0.08 USDC）	Base 主网；Solana 主网可选

生产模式要求设置 ENABLE_MAINNET_PAYMENTS=true，并使用经过审核的版本。 默认情况下，Solana 也处于单独关闭状态。启用它需要设置 ENABLE_SOLANA_PAYMENTS=true、提供公开的测试和收入收款地址、确认支付促进方具备相应能力，并完成单独的结算测试。 应用会根据 PAYMENT_MODE 选择正确的收款地址。 付费模式还要求提供至少 32 个字符的私密 CUSTOMER_HASH_SECRET。该密钥会生成稳定的单向客户标识，用于衡量重复使用情况；不会存储付款方的钱包地址原文。 归因尽力而为，验证付款后绝不会阻碍交付。更改此密钥会开启新的衡量周期，不会改写旧任务。 启用步骤请参阅 docs/RUNBOOK.md。

---

运行测试

npm test              # unit tests (no browser required)
npm run test:e2e      # local e2e (requires Playwright Chromium)
npm run typecheck     # TypeScript strict check

---

Docker

docker compose build
docker compose up -d
curl http://localhost:3000/health

---

延伸阅读

• 构建规范 — 完整的产品与安全规范
• 运行手册 — 运维、备份、升级和主网启用
• Agent 指南 — 机器可读的使用说明
• 技能清单 — 精简的 Agent 技能指南
• MCP 安装指南 — 连接 ChatGPT、Claude、Codex、Cursor 和 VS Code
• 隐私政策和条款
• 客户反馈 — 请求新增能力或报告结果，无需公开机密信息
• 构建证据 — 测试结果和已知限制

---

MIT 许可证