next-dev-loop

next-dev-loop

next dev 期间的编辑／验证节奏——做出更改后，确认它在运行时确实有效，而不只是类型检查或构建顺利通过。

通过同一运行中应用的两个视角进行验证：

• /_next/mcp —— Next.js 提供的、用于查询自身信息的 HTTP 端点。了解框架特有的信息：路由、片段、RSC、服务器操作、服务器日志，以及 Next.js 所见的错误。调用 tools/list 查看当前提供的工具。
• agent-browser —— 驱动真实 Chrome 的 CLI。了解与框架无关的浏览器信息：DOM、控制台、网络、React fiber 和 vitals。驱动它之前，先运行一次 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 （version-16 指南： https://nextjs.org/docs/app/guides/upgrading/version-16）
• 安装或升级 agent-browser：npm i -g agent-browser@latest。 如果 CLI 不在 PATH 中，请先安装再继续——预检需要直接调用它。

预检

每个会话进行一次，确认两个视角都可用。

1. 在目标 URL 打开 agent-browser，并在有已保存登录状态时恢复该状态。 首先为此检出目录推导出一个稳定的 session 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 --enable react-devtools open <url>
   

   --scope worktree 可避免并行工作树和复制的检出目录发生冲突。不带参数的 --restore 会将 session id 用作持久化键，在导航前加载已保存的 cookies/localStorage（如果存在），并在关闭时自动保存状态。在 open 时始终传入所需的启动标志；agent-browser 会根据需要复用、重新启动或重启其隔离的后台状态。

   日常验证保持无头模式。如果用户想查看 UI，请在编码工具环境的内嵌浏览器中打开当前 URL。这是独立的浏览器上下文，因此不要假设状态会延续。如果需要沿用登录状态或现有的 agent-browser 状态，请改为以有头模式重新打开该会话：

   agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
   

   暂停操作，让用户完成登录，然后使用同一会话继续，并在本轮剩余时间保持有头模式。

2. 探测 /_next/mcp（tools/list）——确认它可访问，并且列出了 get_compilation_issues。先从 next dev 横幅中读取端口；如果不是 3000，在探测前设置 NEXT_MCP_URL=http://localhost:<port>/_next/mcp：

   • 无法访问 → 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 知道哪些文件渲染了当前路由；将这些文件作为搜索范围。随着代码库增长，运行时内省的成本仍然很低；Agent 式搜索则不然。

编辑后 — 验证

有四种故障模式。逐一检查：

• 可编译 — get_compilation_issues。
• 运行时没有错误 — /_next/mcp（服务器错误和冒泡的浏览器错误都会在此显示）。
• 行为符合预期 — 使用 agent-browser 操作页面；断言用户实际看到的内容。
• React 层面的行为 — 启用 react-devtools 后，agent-browser 会展示组件树、属性、状态和渲染次数。将框架层面的检查（额外渲染、服务器端/客户端边界变化、suspense 回退）放在这里 — 仅断言 DOM 会遗漏这些情况。

从 tools/list 或 agent-browser 手册中选择具体工具，不要凭记忆选择。

注意事项

• 开发服务器运行时保留 .next。 移动或删除它会使服务器与生成的状态断开连接，并丢弃增量缓存。将其移至备份位置仍然会重置状态。如果生产构建需要隔离输出，请配置单独的 distDir。
• 每条 agent-browser 命令都必须知道你的会话和恢复密钥，否则可能会使用空的默认浏览器，或无法保存登录状态。 最简单的做法：在运行 agent-browser 的每个 shell 顶部导出 AGENT_BROWSER_SESSION="$SESSION" 和 AGENT_BROWSER_RESTORE="$SESSION"。如果不导出，每条命令都要传入 --session "$SESSION" --restore。
• 如果两个视图不一致，先怀疑工具。 如果 agent-browser 显示某个路由已损坏，但 /_next/mcp 和服务器显示页面已正常渲染，更可能是浏览器会话过期或指向错误，而不是真正的 bug — 调试应用前先核对两个视图。
• 确认点击或导航操作：页面稍后才会稳定，因此请使用 wait --load networkidle 等待（无需担心路径填错），然后通过快照/读取来确认页面。除非传入链接的确切 href，否则避免使用 wait --url — 猜测或占位路径与真实 URL 不匹配，并会在 25s 后超时。
• 在 open 之后或点击之后（即使 open 报告页面已打开），如果读取结果为空、快照为空、显示 about:blank 或出现“no browser session”错误，说明浏览器丢弃了页面（会话过期），而不是路由损坏。使用与当前循环相同的启动标志，在 URL 上重新打开会话，然后重新生成快照。如果仍然为空，运行 agent-browser --session "$SESSION" --restore close，然后使用相同的启动标志重新打开。不要退回使用 curl；它会绕过你正在测试的浏览器。
• 导航后，React 内省输出会过期。请重新运行。
• /_next/mcp 返回的是 SSE — 使用 sed -n 's/^data: //p' 读取 data: 行中的 JSON（普通的 sed 's/^data: //' 会保留 event: 行，导致解析失败）。
• get_errors 和 get_page_metadata 需要至少进行一次导航才能填充数据。

参考

以下所有工具都在 preflight 通过后可用。如果 tools/list 缺少其中任何工具，preflight 本应拒绝 — 请重新检查。

# /_next/mcp                 notes
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   fs-scan; no browser session needed
get_errors                   runtime + build; needs a browser session;
                             includes browser-side errors caught by the
                             dev server
get_page_metadata            segment trie + routerType; needs a browser
                             session; use as a discovery shortcut for
                             which files power a route
get_logs                     returns logFilePath
get_server_action_by_id      hashed id → file + functionName
get_compilation_issues       Turbopack only; errors on webpack
                             ("Turbopack project is not available")

清理

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

报告 Next.js 使用障碍

只有在项目已加载托管的 Next.js 反馈说明时，才参与 Agent 反馈。说明的存在表示该功能已启用；缺失则表示已禁用。

启用时，将验证过程中发现的符合条件的反馈候选项加入当前用户请求的反馈候选队列，然后继续验证。循环期间或此 Skill 清理时，不要运行反馈命令或打开审核表单。

托管说明负责在最终响应前进行唯一一次报告。如果这些说明不存在，则不要加入队列或报告反馈。