ShipCheck v0

面向编码代理的独立预览 URL 质量保证。代理将公开的 https 预览 URL 和验收故事 POST 给我们。我们运行 Playwright 启发式检查，为每个故事截图，并返回通过/失败的证据包。失败项保持 needs_review 状态，直到人工（或查看页面的本代理）添加简短备注。

编写 UI 的同一个模型是糟糕的 UI 评判者。这就是产品本身。

Playwright MCP 是免费的；这不是托管浏览器。这是一项独立检查，失败时有人工介入。截图 API 提供像素。ShipCheck 回答“故事 3 真的有效吗？”

运行

cd /workspace/shipcheck
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/playwright install chromium
.venv/bin/python -m shipcheck serve --host 0.0.0.0 --port 8787

此机器上已存在 venv。默认情况下：API 进程也会处理磁盘队列（内联 worker）。若要拆分：

SHIPCHECK_INLINE_WORKER=0 .venv/bin/python -m shipcheck serve --port 8787
.venv/bin/python -m shipcheck worker
.venv/bin/python -m shipcheck run-job sc_xxxxxxxxxxxx

健康检查：GET http://127.0.0.1:8787/health

公开地址（Cloudflare quick tunnel，本机，2026 年 8 月 19 日星期三）：https://realtor-all-enclosed-altered.trycloudflare.com 同一进程提供 GET /（着陆页）、REST 和 POST /mcp。URL 也位于 PUBLIC_URL.txt 中。如果 cloudflared 停止，quick tunnel 会失效。

作业位于 /workspace/shipcheck/queue/{job_id}.json。报告和截图位于 /workspace/shipcheck/reports/。

示例请求 / 响应

curl -sS -X POST https://realtor-all-enclosed-altered.trycloudflare.com/qa_preview \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "stories": [
      {"id": "home", "steps": ["open homepage"], "expect": "Example Domain"}
    ],
    "viewport": "desktop"
  }'

响应：

{
  "job_id": "sc_ab12cd34ef56",
  "status": "queued",
  "price_usd": 6,
  "billed": false,
  "message": "queued. poll GET /qa_status/{job_id}; fetch GET /qa_get_report/{job_id} when status is pass or needs_review."
}

curl -sS https://realtor-all-enclosed-altered.trycloudflare.com/qa_status/sc_ab12cd34ef56
curl -sS https://realtor-all-enclosed-altered.trycloudflare.com/qa_get_report/sc_ab12cd34ef56

终态状态：pass（所有启发式检查通过，无需人工）或 needs_review（列出启发式失败项；后续轮次通过 POST /qa_note/{job_id} 或 MCP qa_note 添加 human_note）。error 属于我们的基础设施问题（超时、崩溃、不安全的 URL），不计费。

供后续计费的可选请求头：Authorization: Bearer <key> 或 X-Api-Key。v0 接受缺失的密钥，且不扣费。

可选的故事步骤（否则视为备注）：click:css=.buy、click:text=Sign in、fill:#email|user@example.com、wait:1000、see:Order total。

证据包格式见 examples/sample_report.json。

安全

仅限 https。拒绝 Localhost、RFC1918、链路本地、CGNAT、元数据 IP（169.254.169.254）、file://、内嵌凭据以及重定向到私有地址。每个 Playwright 请求都会重新检查。导航超时 20 秒，作业上限 4 分钟。详见 PRODUCT.md。

SSRF 测试（无需在线目标）：

cd /workspace/shipcheck
python -m pytest tests/test_ssrf.py tests/test_api.py -q

Cursor mcp.json

Streamable-HTTP MCP 在 POST /mcp 提供（与 REST 同一进程）。工具：qa_preview、qa_status、qa_get_report、qa_note。将其添加到 .cursor/mcp.json 或 ~/.cursor/mcp.json（省略 type；Cursor 将 url 视为 streamable HTTP）：

{
  "mcpServers": {
    "shipcheck": {
      "url": "https://realtor-all-enclosed-altered.trycloudflare.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

v0 接受缺失的密钥，且不扣费。相同文件位于 examples/mcp.json。服务器必须正在运行（python -m shipcheck serve --host 127.0.0.1 --port 8787）。公开 URL 是该进程前面的 Cloudflare quick tunnel。

着陆页：GET /（HTML 位于 shipcheck/landing.html）。公开预览速率限制：每 IP 每天 20 个 qa_preview 作业（回环地址无限制）。SHIPCHECK_PREVIEW_LIMIT_PER_IP 可覆盖；0 表示禁用。

定价

意图，尚未收费：每次运行 $6 桌面版 / $10 双视口（或 5–8 个故事）。后续使用 Polar 预付积分。挂钩：shipcheck/billing.py。

后续步骤

1. Polar 积分包 + 许可证密钥作为 Authorization: Bearer；仅在成功时扣费。

2. 当状态为 needs_review 时通过 Slack/Telegram 发送通知；人工编写 human_note（REST POST /qa_note/{job_id} 和 MCP qa_note 已接受该备注）。

3. 在 PulseMCP / Glama / 官方 MCP 注册表中列出（用于发现，而非市场）。

4. 公开示例报告 + 30 行的 llms.txt。

不要添加仪表板、GitHub App 或加密货币通道。