next-dev-loop
在 next dev 期间的编辑/验证节奏——做出更改,然后确认它在运行时实际生效,而不仅仅是类型或构建正常。
你可以通过两个视图验证同一个运行中的应用:
/_next/mcp—— Next.js 暴露的关于自身的 HTTP 端点。了解框架特定信息:路由、段、RSC、服务器操作、服务器日志以及 Next.js 看到的错误。调用tools/list获取当前可用的工具。agent-browser—— 驱动真实 Chrome 的 CLI。了解与框架无关的浏览器相关事项:DOM、控制台、网络、React fiber、核心性能指标。在驱动之前,先运行agent-browser skills get core一次以获取与版本匹配的使用指南——不要凭记忆猜测子命令。
两个视图相互交叉验证。
要求
- Next.js 16.3+ 搭配 Turbopack —— 需要
/_next/mcp以及通过get_compilation_issues进行主动编译检查。 agent-browser>= 0.31.1 —— React 内省、工作树范围的session id、幂等的--restore以及启动标志协调。
这些是硬性下限,而非软性偏好。如果缺少任何内容,请告知用户如何升级并停止。不要退回到搜索源代码或使用较弱的探测手段——此技能假定两个视图都处于以上版本条件下正常运行。
- 升级 Next.js:
pnpm next upgrade(或npx next upgrade)。 文档:https://nextjs.org/docs/app/getting-started/upgrading (版本 16 指南: https://nextjs.org/docs/app/guides/upgrading/version-16) - 安装或升级
agent-browser:npm i -g agent-browser@latest。 如果 CLI 不在PATH中,请先安装它再继续——预检期望直接调用它。
预检
每个会话执行一次,确认两个视图均正常运行。
-
在目标 URL 打开
agent-browser,并在存在时恢复保存的登录状态。 首先为此代码仓库派生一个稳定的会话 ID,并用于每个agent-browser命令:SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)" export AGENT_BROWSER_SESSION="$SESSION" export AGENT_BROWSER_RESTORE="$SESSION"然后打开目标 URL:
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>--scope worktree可防止并行工作树和复制的仓库冲突。裸--restore将会话 ID 用作持久化键,在导航前加载保存的 cookie/localStorage(如果存在),并在关闭时自动保存状态。始终在open时传递所需的启动标志;agent-browser 会根据需要重用、重新启动或重启其作用域内的后台状态。浏览器是用户的。如果状态未恢复(首次运行、会话过期)且页面需要登录,则由用户驱动登录——暂停直到他们确认。登录后,继续使用同一会话和恢复上下文;
agent-browser close保存 cookie 状态,以便下次open时恢复。 -
探测
/_next/mcp(tools/list)——确认它可达并列出get_compilation_issues:- 不可达 → 要么
next dev未在运行,要么 Next.js 版本低于 16.3。检查package.json以区分,然后拒绝。 get_compilation_issues不在列表中 → Next.js 版本低于 16.3。拒绝并告知用户升级。
- 不可达 → 要么
-
get_compilation_issues同时作为 Turbopack 探测。错误响应"Turbopack project is not available..."表示用户正在使用 webpack。拒绝——需要 Turbopack。 -
get_routes→ 获取会话其余部分的路由映射。
循环
编辑前——缩小范围
询问运行中的应用,而非代码库。/_next/mcp 知道哪些文件渲染了当前路由;将它们用作搜索范围。随着代码库的增长,运行时内省保持低成本;而智能体搜索则不然。
编辑后——验证
四种故障模式。分别检查:
- 编译 ——
get_compilation_issues。 - 运行时无错误 ——
/_next/mcp(服务器和冒泡上来的浏览器错误都会在此处呈现)。 - 行为符合预期 ——
agent-browser驱动页面;断言用户实际看到的内容。 - React 层级行为 —— 启用 react-devtools 的
agent-browser暴露组件树、props、state 和渲染计数。在此处进行框架层级的检查(额外渲染、服务器/客户端边界变化、Suspense 回退)——仅靠 DOM 断言会遗漏它们。
从 tools/list 或 agent-browser 手册中选择特定工具,而非凭记忆。
注意事项
- 每个
agent-browser命令必须知道你的会话和恢复密钥,否则它可能使用空的默认浏览器或无法保存登录状态。 最简单的方法:在你运行 agent-browser 的每个 shell 顶部同时导出AGENT_BROWSER_SESSION="$SESSION"和AGENT_BROWSER_RESTORE="$SESSION"。如果你没有导出它们,请在每个命令上传递--session "$SESSION" --restore。 - 当两个视图不一致时,首先怀疑工具本身。 如果
agent-browser说某个路由有问题,但/_next/mcp和服务器显示它已正常渲染,则更可能的原因是过时或错误的浏览器会话,而非真实 bug——在调试应用程序之前先协调视图。 - 确认点击或导航:页面会有短暂的加载延迟,因此使用
wait --load networkidle等待(无需指定路径容易出错),然后截图/读取以确认页面。避免使用wait --url,除非你传递了链接的确切 href——猜测的或占位符路径不会匹配真实 URL,并在 25 秒后超时。 - 空白读取、空截图、
about:blank或“无浏览器会话”错误——无论是在open之后还是点击之后(即使open报告了页面)——都是浏览器丢弃了页面(会话过时),而非路由损坏。使用--session "$SESSION" --restore在目标 URL 重新打开你的会话并重新截图;如果仍然是空白,运行agent-browser --session "$SESSION" --restore close,然后重新打开。不要退回到使用curl;它会绕过你要测试的浏览器。 - React 内省输出在导航后会过时。重新运行。
/_next/mcp的回复是 SSE 格式——使用sed -n 's/^data: //p'读取data:行上的 JSON(简单的sed 's/^data: //'会保留event:行导致解析失败)。- 非 3000 端口的开发服务器:读取
next dev的横幅;设置NEXT_MCP_URL=http://localhost:<port>/_next/mcp。 get_errors和get_page_metadata需要至少一次导航才能填充数据。
参考
以下所有工具在预检通过后即可使用。如果 tools/list 中缺少其中任何一个,预检应该已经拒绝——请重新检查。
# /_next/mcp 说明
get_project_metadata projectPath、devServerUrl、bundler
get_routes 文件扫描;无需浏览器会话
get_errors 运行时 + 构建;需要浏览器会话;
包括开发服务器捕获的浏览器端错误
get_page_metadata 段 trie + routerType;需要浏览器会话;
用作发现哪个文件驱动路由的快捷方式
get_logs 返回 logFilePath
get_server_action_by_id 哈希 ID → file + functionName
get_compilation_issues 仅 Turbopack;webpack 上报错
("Turbopack project is not available")
清理
使用相同的会话和恢复上下文关闭会话:
agent-browser --session "$SESSION" --restore close。close 保存该会话的 cookie 和存储,以便下一个循环的 --restore open 保持用户登录状态。保留 next dev 运行以供下一个循环使用。
next-dev-loop-<主题> 相关的技能(例如 next-dev-loop-rsc、next-dev-loop-debug)假定此预检已完成;它们直接从循环开始执行。