AI Skills
next-dev-loop

next-dev-loop

熱門

驗證編輯應用程式程式碼後的 Next.js 執行時期行為。使用此技能來確認變更在實際運行的應用程式中確實有效，而不僅僅是編譯或型別檢查通過。結合 /_next/mcp（Next.js 的視角）與 agent-browser（瀏覽器的視角）。需要正在運行的 `next dev`。

14萬星標
3.1萬分支
更新於 2026/7/22
獲取技能源代碼

相關技能

frontend-code-review15萬design-system11萬implementing-agent-modes3.7萬
SKILL.md
readonlyread-only
name
next-dev-loop
description

Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `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，並在存在時還原已儲存的登入狀態。
    首先為此 checkout 推導一個穩定的工作階段 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 可防止平行的工作樹和複製的 checkout
    互相衝突。單純的 --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            區段 trie + routerType；需要瀏覽器
                             工作階段；用作發現捷徑，了解哪些檔案
                             驅動路由
get_logs                     回傳 logFilePath
get_server_action_by_id      雜湊 ID → 檔案 + functionName
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）
假設此預檢已經執行；它們從迴圈開始接手。