AI Skills
next-dev-loop

next-dev-loop

热门

验证编辑应用代码后的 Next.js 运行时行为。使用此技能确认更改在实际运行的应用中有效——而不仅仅是编译或类型检查通过。结合 /_next/mcp（Next.js 的视角）和 agent-browser（浏览器的视角）。需要正在运行的 `next dev`。

14万Star
3.1万Fork
更新于 2026/7/22
获取 Skill源代码

相关 Skills

frontend-code-review15万design-system11万implementing-agent-modes3.7万
SKILL.md
readonly只读
name
next-dev-loop
description

验证编辑应用代码后的 Next.js 运行时行为。使用此技能 确认更改在实际运行的应用中有效——而不仅仅是编译或类型检查通过。 结合 /_next/mcp（Next.js 的视角）和 agent-browser（浏览器的视角）。 需要正在运行的 `next dev`。

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 以及启动标志协调。

这些是硬性下限，而非软性偏好。如果缺少任何一项，请告知用户如何升级并停止。不要回退到 grep 源代码或使用较弱的探测——此技能假定两个视角都以以上版本运行。

预检

每个会话一次，确认两个视角都处于活动状态。

  1. 在目标 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 恢复。

  2. 探测 /_next/mcp（tools/list）——确认它可访问并列出 get_compilation_issues：

    • 不可访问 → 要么 next dev 未运行，要么 Next.js 低于 16.3。检查 package.json 以区分，然后拒绝。
    • get_compilation_issues 不在列表中 → Next.js 低于 16.3。拒绝并告知用户升级。

  3. get_compilation_issues 同时作为 Turbopack 探测。错误响应 "Turbopack project is not available..." 表示用户在使用 webpack。拒绝——需要 Turbopack。

  4. 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 和服务器说它渲染正常，则过时或错误定向的浏览器会话更可能是原因，而非真正的错误——在调试应用前先协调视角。
  • 确认点击或导航：页面稍后才会稳定，因此使用 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            片段树 + routerType；需要浏览器
                             会话；用作发现哪些文件驱动路由的快捷方式
get_logs                     返回 logFilePath
get_server_action_by_id      哈希 ID → 文件 + 函数名
get_compilation_issues       仅 Turbopack；webpack 上报错
                             （"Turbopack project is not available"）

清理

使用相同的会话和恢复上下文关闭会话：agent-browser --session "$SESSION" --restore close。close 保存该会话的 cookie 和存储，以便下一个循环的 --restore 打开保持用户登录状态。保持 next dev 运行以供下一个循环使用。

next-dev-loop-<topic> 兄弟技能（例如 next-dev-loop-rsc、next-dev-loop-debug）假定此预检已运行；它们从循环开始。