Local Server

local-server — 自動啟本地 server

觸發時機（必須主動觸發，不等使用者要求）

任一條件成立就執行：

1. 使用者語意表達「想看本地版」「測試一下」「打開來看」「給我連結試試」「跑起來」「本地端」等
2. 你準備在對話中給出 http://localhost:<port> 形式的連結
3. 使用者明示 /local-server 或 /serve 等指令
4. 已給過連結但使用者反應「打不開 / 連不上」→ 重新驗證並重啟

不要做的事：

• 不要在沒驗證 server 已起來前就把連結貼給使用者
• 不要因為「我覺得使用者自己會跑」就跳過——使用者已經明確說過想要這個自動化

工作流程

Step 1 — 檢查目前是否已有 server 跑著

對常見埠依序試打（preferred: 8000, 5173, 3000, 4321, 8080）：

for port in 8000 5173 3000 4321 8080; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 1 "http://localhost:$port/" 2>/dev/null)
  if [ "$code" = "200" ] || [ "$code" = "301" ] || [ "$code" = "302" ]; then
    echo "FOUND $port $code"
    break
  fi
done

有命中 → 跳到 Step 4（直接給連結，不要重複啟 server）。

Step 2 — 偵測專案型態，選對啟動指令

讀工作目錄下的 package.json（若有）：

Windows 注意： C:\Users\<u>\AppData\Local\Microsoft\WindowsApps\python.exe 是 Microsoft Store stub，跑會 exit 49。優先用 npx serve。

Step 3 — 背景啟動 + 等待就緒

用 Bash 的 run_in_background: true 啟動（不要前景，會卡住）：

Bash(command="npx serve -p 8000 .", run_in_background=true)

然後輪詢直到就緒（單一通知模式，注意 timeout）：

until curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/ | grep -qE "200|301|302"; do
  sleep 0.3
done
echo "READY"

如果 30 秒內沒就緒：

• 讀 background task 的 output 找錯誤（埠衝突 / 缺套件 / 寫死路徑錯誤）
• 報告錯誤給使用者，不要假裝成功

Step 4 — 把連結交給使用者

格式：

Server 已啟動 → http://localhost:

（若有特定頁面）建議直接打開 http://localhost:/

順便：

• 若這個 server 是新啟的，提一句「跑在背景，要關掉跟我說一聲」
• 若是沿用之前的，提一句「沿用既有 server」

Step 5 — 後續維護

• 同一 session 內不要重啟已經健康的 server
• 若使用者改了程式碼，靜態站需要重新整理瀏覽器；Vite/Next 有 HMR 不用重啟
• 使用者明確說「停掉 server / 關掉」→ 用 TaskStop 收掉背景任務

反例（不要這樣做）

❌ 直接說「請執行 npx serve -p 8000 . 然後打開 http://localhost:8000」 → 使用者要的就是自動化，這違背 skill 目的

❌ 啟動後不驗證就貼連結 → 啟動失敗（埠佔用 / 缺依賴）使用者會打不開

❌ 同 session 重複 spawn 多個 server → 浪費埠 + 混淆

常見 troubleshooting