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中,請先安裝它再繼續 — preflight 會預期能直接調用它。
預檢
在每個工作階段執行一次,確認兩個視角都在運行中。
-
在目標 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 --headed --enable react-devtools open <url>--scope worktree可防止平行 worktree 和複製的 checkout 發生碰撞。單純的--restore使用 session id 作為 持久化金鑰,在導航前載入已儲存的 cookies/localStorage(如果存在), 並在關閉時自動儲存狀態。始終在open命令上傳遞所需的 啟動標誌;agent-browser 將根據需要重複使用、重新啟動或重啟 其範圍內的背景狀態。瀏覽器是使用者的。如果狀態未還原(首次執行、 session 過期)且頁面需要登入,由使用者驅動登入 — 暫停直到他們確認。登入後,繼續使用同一個 session 和 restore 上下文;
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 層級行為 —
agent-browser啟用 react-devtools 後,可以暴露元件樹、props、state 和渲染 計數。在此錨定框架層級的檢查(額外渲染、 伺服器/客戶端邊界變動、Suspense fallback)— 僅靠 DOM 斷言 會遺漏它們。
從 tools/list 或 agent-browser
手冊中選擇特定的工具,而不是憑記憶。
注意事項
- 每個
agent-browser命令都必須知道您的 session 和 restore 金鑰,否則它可能會使用空的預設瀏覽器或無法儲存登入 狀態。 最簡單的方法:在您運行 agent-browser 的每個 shell 頂部 同時匯出AGENT_BROWSER_SESSION="$SESSION"和AGENT_BROWSER_RESTORE="$SESSION"。如果您不匯出它們, 請在每個命令上傳遞--session "$SESSION" --restore。 - 當兩個視角不一致時,首先懷疑工具本身。 如果
agent-browser說路由壞了,但/_next/mcp和伺服器 說它渲染無誤,那麼過時或錯誤導向的瀏覽器 session 比真正的錯誤更可能是原因 — 在除錯應用程式之前, 先調和這兩個視角。 - 確認點擊或導航:頁面會稍後才穩定下來,因此
使用
wait --load networkidle(沒有可能會搞錯的路徑)等待, 然後快照/讀取以確認頁面。避免使用wait --url,除非您傳遞 連結的確切 href — 猜測或佔位符路徑不會匹配 真實 URL,並會在 25 秒後超時。 - 空白讀取、空快照、
about:blank或 "no browser session" 錯誤 — 可能在open之後或點擊之後(即使open回報了頁面)— 是瀏覽器丟棄了頁面(過期的 session),而不是路由壞了。使用--session "$SESSION" --restore在該 URL 重新開啟您的 session 並重新快照;如果仍然是空白, 執行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 檔案系統掃描;不需要瀏覽器 session
get_errors 執行時 + 建置;需要瀏覽器 session;
包含開發伺服器捕獲的瀏覽器端錯誤
get_page_metadata 區段 Trie + routerType;需要瀏覽器
session;用作發現哪個檔案驅動路由的快捷方式
get_logs 回傳 logFilePath
get_server_action_by_id 雜湊 id → 檔案 + functionName
get_compilation_issues 僅限 Turbopack;webpack 上會報錯
("Turbopack project is not available")
結束
使用相同的 session 和 restore 上下文關閉 session:
agent-browser --session "$SESSION" --restore close。close 會儲存
該 session 的 cookies 和儲存空間,以便下次循環的 --restore open
讓使用者保持登入狀態。讓 next dev 保持運行以備下次循環使用。
next-dev-loop-<主題> 的兄弟技能(例如 next-dev-loop-rsc、next-dev-loop-debug)
假設此預檢已執行過;它們會從循環階段開始執行。