Visual Feedback Loop 是一个用于网页应用迭代开发的智能体视觉反馈闭环技能，核心目标是让 AI 智能体能够捕获、查看和比较运行中网页应用的视觉输出。
用途
当你在迭代视觉相关代码（UI、canvas、3D、SVG、图表、动画）并需要真正看到渲染结果时使用该技能。它解决的是智能体无法直接访问浏览器的问题，通过服务端进行中转。
工作原理
智能体（CLI）无法直接访问浏览器，服务端承担中转角色：
- 智能体发起 GET /api/dev-screenshot（可带参数）。
- 服务端通过 SSE 向浏览器发送 "capture" 通知。
- 浏览器捕获 canvas 并 POST 回传 { dataUrl }。
- 服务端写入 .screenshots/{UTC}.webp、.screenshots/{UTC}.json（元数据）、.screenshots/latest.webp（便利副本）。
- GET 请求返回 { ok, path, latest }。
使用方式
捕获当前视图：
curl http://localhost:3000/api/dev-screenshot
带参数捕获（参数由应用特定的浏览器客户端解释）：
curl 'http://localhost:3000/api/dev-screenshot?component=header&theme=dark' curl 'http://localhost:3000/api/dev-screenshot?letter=б&depth=0.8'
读取结果：Read .screenshots/latest.webp
视觉回归（像素差异）
使用 ImageMagick 与基准截图比较：
magick compare -metric RMSE .screenshots/ground-truth.webp .screenshots/latest.webp .screenshots/diff.webp
RMSE 输出说明：0.01 表示约 1% 差异（渲染噪声），0.03+ 表示可见变化。保存 diff 图像以供检查。
元数据附属文件
每张截图都会生成同名 UTC 时间戳的 JSON 附属文件：
{ "timestamp": "2026-02-25T08:22:12.655Z", "git": { "commit": "0a5726f", "dirty": true }, "params": { "letter": "о", "chamferModel": "membrane", "cameraView": "front" }, "format": "webp", "file": "2026-02-25T08-22-12-655Z.webp" }
可用于追溯某张截图对应的代码状态与参数，在多次代码变更间迭代时尤为关键。
A/B 比较工作流
- 捕获基准：curl '...?letter=о'，记下 {UTC}.webp 文件名。
- 修改代码，刷新浏览器。
- 再次捕获：curl '...?letter=о'。
- 比较：magick compare -metric RMSE .screenshots/{ground-truth}.webp .screenshots/latest.webp .screenshots/diff.webp。
- 读取 diff 图像并检查 RMSE 数值。
控制台后备方案：await window.__takeDevScreenshot()
规则
- 捕获后始终 Read .screenshots/latest.webp，绝不假设渲染正确。
- 浏览器标签页必须停留在应用 URL。超时即意味着没有 SSE 连接，需请用户刷新。
- 一次只允许一个请求。第二个 GET 返回 409。需等待第一个请求完成（成功/错误/10 秒超时）。
- 错误会立即返回，而非以超时形式出现。客户端会把错误 POST 回来：{ ok: false, error: "..." }。
- HMR 容错：把服务端 SSE 状态存放在 globalThis 上，以便在模块重载后存活。EventSource 在客户端会自动重连。若代码变更后截图仍失败，请用户刷新。
- HMR 不会更新离屏渲染路径。useEffect 中的闭包会捕获过时的模块引用。修改渲染逻辑后，始终请用户硬刷新（macOS 为 Cmd+Shift+R，Windows/Linux 为 Ctrl+Shift+R）。
故障排查
- 超时：浏览器未响应 → 在浏览器中打开/刷新应用。
- 409：已有请求进行中 → 等待超时（10 秒）。
- 黑色/空白图像 → 刷新浏览器标签页。
- 能用一次后超时 → HMR 破坏了 SSE，刷新标签页（若使用 globalThis 模式则较少出现）。
- 代码变更未反映在截图中 → HMR 不更新离屏渲染器，需硬刷新。
- 比较不同代码状态的截图 → 检查 JSON 附属文件中的 git commit 与 dirty 标志。
完整错误参考见 references/errors.md。
安装/集成设置
该模式与框架无关，只要求具有 GET/POST 路由和 SSE 的 HTTP 服务器。参考实现使用 Next.js，但同样适用于 Express、Fastify、Hono、Vite 开发服务器插件或任何 Node.js HTTP 服务器。完整 Next.js 实现（API 路由、SSE 监听器、WebMCP 注册）见 references/setup-nextjs.md。将路由处理器适配到你的框架即可，客户端 SSE 监听器与捕获逻辑无论服务端框架如何都相同。
限制
官方资料未提供收费、价格或具体平台支持范围等信息，暂未提供。