hongnoul/hwatu 源: https://github.com/hongnoul/hwatu # hwatu 最新版本(https://github.com/hongnoul/hwatu/releases) 许可证: MIT CI (https://github.com/hongnoul/hwatu/actions/workflows/ci.yml) 面向编码代理的轻量级验证浏览器。 - 别再让代理声称“像素级完美”——让它证明达到 97.49%。 - 别再让浏览器窗口抢占焦点——默认无头运行，你继续打字。 - 别再下载 170 MB 的 Chromium——一个静态二进制文件 + 你发行版里的 webkitgtk 就够了。 ## 文档 - 代理指南 — 协议、原语、验证循环 - 人类指南 — 平铺窗口管理浏览器端 - 基准测试 — 每个数字都经过测量并有方法论 - 路线图 — 记录计划、优先级、非目标 ## 快速开始 安装 → 检测工作流 → 连接代理 → 验证页面 → 移交给人类 bash curl -fsSL https://raw.githubusercontent.com/hongnoul/hwatu/main/scripts/install.sh | bash hwatu setup 一个静态二进制文件加上你发行版的 webkitgtk-6.0（安装程序会检查）。在 Arch 上：yay -S hwatu。从源码：cargo build --release。安装程序只安装二进制文件。hwatu setup 会检测受支持的编码代理并打印可用连接，而不会修改它们的配置。当你准备好时，明确选择一个客户端： sh hwatu doctor hwatu setup --client claude --scope project --dry-run hwatu setup --client claude --scope project hwatu demo - 安装： 下载两个二进制文件并检查 WebKitGTK。 - 检测： 找到 Claude Code、Cursor、Jcode 或通用 MCP 工作流。 - 连接： 使用 Jcode 的原生 socket、MCP 或 CLI 备选方案。 - 验证： 用 doctor 或 demo 运行一次无头渲染烟雾测试。 - 移交： 仅在需要人工介入时才会物化同一个实时会话。 安装是可预览、幂等、可逆的，使用相同的客户端和作用域加上 --undo 即可撤销。项目作用域创建可共享的配置；用户作用域保持个人化。Claude Code 会在下次启动时要求每个用户批准项目作用域的 MCP 服务器。手动 MCP 配置仍然是一个可移植的条目： json { "mcpServers": { "hwatu": { "command": "hwatu", "args": ["mcp"] } } } 或者完全跳过 MCP：每个命令都是一个简短的 CLI 调用，或者通过 Unix socket 传输的一行以换行符分隔的 JSON。 sh hwatu localhost:3000 # 像打开终端一样打开一个窗口 ## 特性 - [x] 像素差异评分：匹配百分比 + 差异区域 + 热力图（diff） - [x] 动画数据化：持续时间、缓动函数、速度（motion） - [x] 确定性动画帧：将所有动画固定在时间 t（seek） - [x] 页面状态为 JSON，符号而非像素（snapshot） - [x] 带有结构化错误信息的真实输入事件（click / type / scroll / upload） - [x] JS 错误、控制台输出、失败请求（console） - [x] 带轮询的一次调用页面断言（expect） - [x] 无头/后台/聚焦作为每个窗口的属性，可实时切换 - [x] 人工移交：hwatu focus 将活动会话放到你的平铺窗口管理器中 - [x] CAPTCHA / 反机器人检测，带结构化等待/恢复（challenge） - [x] MCP 服务器、纯 CLI 以及 1 行 JSON socket 协议 - [x] 给人类用的极简 WebKit 浏览器：原生广告拦截、vim 风格栏、崩溃恢复 ## 为什么不是 Playwright 或 chrome-devtools-mcp？ Playwright 和 chrome-devtools-mcp 本质上都是自动化 API：它们让代理驱动浏览器，然后将原始截图和 DOM 交还给代理自行判断。hwatu 不同。它是一个验证浏览器：测量原语是内置的，浏览器本身是一个温热的守护进程，窗口只消耗 13 毫秒，而无头是一个窗口属性，而非启动模式。这就是循环的样子，真实的命令，真实的输出： sh hwatu --headless localhost:3000 # 它的窗口；你永远不会看到 hwatu --headless staging.example.com # 参考页面 hwatu diff --id 2 --other 1 --heatmap /tmp/heat.png # {"match_percent":85.13,"regions":[{"x":0,"y":160,"w":2048,...}]} hwatu motion --id 1 # 参考页面的动画，以数字表示 # easing cubic-bezier(0.25,1,0.5,1), 300ms, marquee 29.78px/s ... # ...代理编辑代码... hwatu diff --id 2 --other 1 # {"match_percent":97.49} # 攀升胜过猜测 我们在 stripe.com 落地页的一个克隆上运行了这个循环：一个代理将其从 85.1% 提升到 98.8% 的像素匹配。复现它：scripts/demo/。一次完整的验证过程（打开、加载、评估、截图、关闭）中位时间为 87 ms（基准测试）。当代理遇到 CAPTCHA 或需要判断时，hwatu focus 会物化它的实时会话，保留 cookies 和状态，放到你的平铺窗口管理器中。你操作十秒钟。它再接管回来。没有其他工具能做到这一点，因为其他工具的无头模式都是在启动时决定的。 ## hwatu 对比说明 图例： ✅ 是 / 内置 · 🟡 部分 / 有限 · ❌ 否 | 能力 | Playwright | chrome-devtools-mcp | hwatu | | — | :—: | :—: | :—: | | 像素差异评分 + 区域 + 热力图 | 🟡 1 | ❌ | ✅ | | 动画以数字表示，中途固定 | ❌ 2 | 🟡 3 | ✅ | | 实时会话中无头 ↔ 有头切换 | ❌ | ❌ | ✅ | | 会话中人工移交，状态完整 | ❌ | ❌ | ✅ | | N 个并行代理时不抢焦点 | 🟡 4 | 🟡 4 | ✅ | | CAPTCHA 检测 + 结构化等待/恢复 | ❌ | ❌ | ✅ | | 无需 Node，无需按版本下载浏览器 | ❌ | ❌ | ✅ | 1 toHaveScreenshot 与存储的金色截图比较：测试套件的通过/失败，而非代理可以逐步提升的分数。 2 标准做法是禁用动画或快进到结束状态以避免不稳定。 3 原始 CDP 可以查询动画状态，但没有缓动/速度/关键帧的数值摘要。 4 无头没问题；每个有头窗口都会弹出并抢占焦点。 > 对比反映的是每个项目撰写时的情况； > 欢迎更正。诚实的说明：原始温热延迟与 Playwright 持平（83 vs 82 毫秒），hwatu 渲染的是 WebKit 而非 Chromium（在 CI 中保留一个 Playwright 矩阵以应对特定引擎的错误），并且目前仅限 Linux。完整的正面数据： > docs/benchmarks.md。 — MIT 许可。Linux。WebKitGTK 6。