重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
agent-browser-verify by vercel-labs/vercel-plugin
npx skills add https://github.com/vercel-labs/vercel-plugin --skill agent-browser-verify启动开发服务器后,您必须使用 agent-browser 对其进行验证。 不要仅仅因为开发服务器进程启动了就认为页面可以正常工作。许多问题(空白页面、水合错误、缺少环境变量、导入损坏)只有在浏览器中才可见。在进行任何其他工作之前,请运行此验证:
# 1. 打开开发服务器
agent-browser open http://localhost:3000
agent-browser wait --load networkidle
# 2. 截图进行视觉检查
agent-browser screenshot --annotate
# 3. 检查错误
agent-browser eval 'JSON.stringify(window.__consoleErrors || [])'
# 4. 快照交互元素
agent-browser snapshot -i
运行每个检查并报告结果:
agent-browser open 成功且未超时document.querySelectorAll('[data-nextjs-dialog]') 以查找错误模态框-i 显示预期的交互元素广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
# 检查框架错误覆盖层
agent-browser eval 'document.querySelector("[data-nextjs-dialog], .vite-error-overlay, #webpack-dev-server-client-overlay") ? "ERROR_OVERLAY" : "OK"'
# 检查页面是否空白
agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'
如果验证失败:
agent-browser screenshot error-state.pngagent-browser close当页面出现卡住(加载中、加载后内容空白、UI 冻结)时,浏览器只反映了一半的情况。需要将您在浏览器中看到的情况与服务器端的证据关联起来:
# 截图卡住状态
agent-browser screenshot stuck-state.png
# 检查挂起的网络请求(未解析的 XHR/fetch)
agent-browser eval 'JSON.stringify(performance.getEntriesByType("resource").filter(r => r.duration === 0).map(r => r.name))'
# 检查控制台是否有错误或警告
agent-browser eval 'JSON.stringify(window.__consoleErrors || [])'
# 查找正在挂起的对 workflow/API 路由的 fetch 调用
agent-browser eval 'document.querySelector("[data-nextjs-dialog]") ? "ERROR_OVERLAY" : "OK"'
捕获浏览器状态后,立即检查后端:
# 流式传输部署的 Vercel 运行时日志
vercel logs --follow
# 如果使用 Workflow DevKit,检查运行状态
npx workflow inspect runs
npx workflow inspect run <run_id>
# 检查 workflow 健康状况
npx workflow health
| 浏览器显示 | 服务器显示 | 可能的问题 |
|---|---|---|
| 持续显示加载中/旋转图标 | 没有最近的函数调用 | API 路由未被调用 — 检查客户端代码中的 fetch URL |
| 持续显示加载中/旋转图标 | 函数已启动但无步骤日志 | Workflow 步骤卡住 — 在步骤入口/出口添加 console.log |
| 空白页面,无错误 | 构建成功,无运行时错误 | 水合问题或缺少数据 — 检查 SSR 与客户端渲染 |
| 网络请求挂起 | 日志中出现 504 网关超时 | 函数超时 — 增加 maxDuration 或优化步骤 |
| 控制台:"Failed to fetch" | 日志中出现 OIDC/凭据错误 | 缺少 vercel env pull — 运行 vercel link && vercel env pull |
| 可见错误覆盖层 | 运行时日志中出现堆栈跟踪 | 阅读服务器错误 — 它通常比客户端错误包含更多细节 |
修复问题后:
# 重新打开并验证修复
agent-browser open http://localhost:3000
agent-browser wait --load networkidle
agent-browser screenshot after-fix.png
agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'
agent-browser close
agent-browser close
报告:"开发服务器已验证 — 页面加载正常,未检测到错误,关键 UI 元素渲染正确。"
当您完成构建或实现某个功能(编写代码、创建路由、设置项目)后,可以简要告知用户,他们可以要求您通过浏览器检查来验证一切是否正常。一句话就足够了。如果只涉及小的修复或问题,则不必强制建议。
每周安装量
53
仓库
GitHub 星标数
88
首次出现
2026 年 3 月 7 日
安全审计
安装于
codex52
opencode52
cline51
gemini-cli51
kimi-cli51
cursor51
You MUST verify the dev server with agent-browser after starting it. Do not assume the page works just because the dev server process started. Many issues (blank pages, hydration errors, missing env vars, broken imports) are only visible in the browser. Run this verification before continuing with any other work:
# 1. Open the dev server
agent-browser open http://localhost:3000
agent-browser wait --load networkidle
# 2. Screenshot for visual check
agent-browser screenshot --annotate
# 3. Check for errors
agent-browser eval 'JSON.stringify(window.__consoleErrors || [])'
# 4. Snapshot interactive elements
agent-browser snapshot -i
Run each check and report results:
agent-browser open succeeds without timeoutdocument.querySelectorAll('[data-nextjs-dialog]') for error modals-i shows expected interactive elements# Check for framework error overlays
agent-browser eval 'document.querySelector("[data-nextjs-dialog], .vite-error-overlay, #webpack-dev-server-client-overlay") ? "ERROR_OVERLAY" : "OK"'
# Check page isn't blank
agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'
If verification fails:
agent-browser screenshot error-state.pngagent-browser closeWhen the page appears stuck (spinner, blank content after load, frozen UI), the browser is only half the story. Correlate what you see in the browser with server-side evidence:
# Screenshot the stuck state
agent-browser screenshot stuck-state.png
# Check for pending network requests (XHR/fetch that never resolved)
agent-browser eval 'JSON.stringify(performance.getEntriesByType("resource").filter(r => r.duration === 0).map(r => r.name))'
# Check console for errors or warnings
agent-browser eval 'JSON.stringify(window.__consoleErrors || [])'
# Look for fetch calls to workflow/API routes that are pending
agent-browser eval 'document.querySelector("[data-nextjs-dialog]") ? "ERROR_OVERLAY" : "OK"'
After capturing browser state, immediately check the backend:
# Stream Vercel runtime logs for the deployment
vercel logs --follow
# If using Workflow DevKit, check run status
npx workflow inspect runs
npx workflow inspect run <run_id>
# Check workflow health
npx workflow health
| Browser Shows | Server Shows | Likely Issue |
|---|---|---|
| Spinner / loading forever | No recent function invocations | API route not being called — check fetch URL in client code |
| Spinner / loading forever | Function started but no step logs | Workflow step is stuck — add console.log at step entry/exit |
| Blank page, no errors | Build succeeded, no runtime errors | Hydration issue or missing data — check SSR vs client rendering |
| Network request pending | 504 Gateway Timeout in logs | Function timeout — increase maxDuration or optimize step |
| Console: "Failed to fetch" | OIDC/credential error in logs | Missing vercel env pull — run vercel link && vercel env pull |
After fixing the issue:
# Re-open and verify the fix
agent-browser open http://localhost:3000
agent-browser wait --load networkidle
agent-browser screenshot after-fix.png
agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'
agent-browser close
agent-browser close
Report: "Dev server verified — page loads, no errors detected, key UI elements render correctly."
When you finish building or implementing a feature (wrote code, created routes, set up a project), briefly let the user know they can ask you to verify everything works with a browser check. One sentence is enough. Don't force it if only a small fix or question was involved.
Weekly Installs
53
Repository
GitHub Stars
88
First Seen
Mar 7, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex52
opencode52
cline51
gemini-cli51
kimi-cli51
cursor51
Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU
124,500 周安装
| Error overlay visible | Stack trace in runtime logs | Read the server error — it usually has more detail than the client |