Community生產力與協作github.com

執行

在本地啟動網站或應用程式,並在真實瀏覽器中查看。它能從 package.json、設定檔或純 index.html 中偵測技術棧,選擇空閒連接埠,啟動開發伺服器或靜態伺服器,等待實際回應,截圖或開啟瀏覽器,並可透過一個旗標將其停止。

執行 是什麼?

此技能旨在簡化從原始碼到可檢視網頁的流程。它能自動偵測專案的技術棧(例如透過 package.json 偵測 npm 腳本,或透過 index.html 偵測靜態伺服器),在空閒連接埠上啟動相應的開發伺服器,並提供開啟瀏覽器、截圖(透過 Playwright)以及停止伺服器等功能。技能會將進程 ID、連接埠和 URL 等狀態資訊記錄在專案目錄的 `.run/` 資料夾中,確保啟動與停止的流程完整且可管理。對於無法自動處理的專案(如需要 Docker 或特定執行命令),它會明確報告並停止,避免造成混亂。它支援多種 Agent 平台,如 Claude Code, Cursor, 與 Codex,並強調伺服器必須在檢查完成後停止,以及應先讀取日誌再進行故障排除等最佳實踐。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/itsdanylol/claude-sitecraft/tree/HEAD/skills/run

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

執行 是做什麼的?

一個網站只有在被實際運行看到後才算完成。原始碼告訴你別人想表達什麼;瀏覽器則告訴你使用者實際得到什麼。此技能是從資料夾到渲染頁面的最短途徑。

執行方式

node <skill 資料夾>/scripts/serve.mjs <目錄> [--port 4173] [--open] [--shot 輸出.png] [--stop] [--detect]
  • --detect 僅列印偵測到的資訊而不啟動任何服務。當目錄不熟悉時,請先執行此選項。
  • --port 從指定連接埠開始尋找,並使用下一個空閒連接埠,因此可以同時執行兩個專案。
  • --open 開啟預設瀏覽器。
  • --shot 輸出.png 透過 Playwright 以 1440 寬度、全頁高度渲染頁面。
  • --stop 從 .run/state.json 終止進程樹。

它會在專案旁邊寫入 .run/state.json(包含 pid、port、url、command)和 .run/server.log。這兩個檔案是啟動與停止之間完整的交接檔案。

偵測項目

找到的內容執行方式
包含 dev、start、serve 或 preview 腳本的 package.json在空閒連接埠上執行 npm run <該腳本>,並設定 PORT 環境變數
根目錄下的 index.html對該資料夾執行 python -m http.server
public/index.html、dist/index.html、build/index.html以建置輸出目錄為根的靜態伺服器
有設定檔但無腳本報告並停止:該專案需要自己的命令
go.mod、Cargo.toml、pubspec.yaml報告並停止:請使用專案自身的執行命令

框架特定細節、預設連接埠以及值得了解的失敗模式:請參閱 references/stacks.md。

解讀結果

該腳本僅證明三件事:進程已啟動、連接埠有回應、頁面已渲染。它無法告訴你的是:

  • 佈局在 375、768 和 1440 寬度下是否正確(請使用 sitecraft/scripts/verify.mjs 進行驗證)
  • 主控台是否乾淨(此處未擷取;verify.mjs 會擷取)
  • 截圖的頁面是否為使用者想要的頁面(請檢查 URL 是否與你要求的路由相符)

因此循環是:serve.mjs --shot,用你自己的眼睛查看圖片,修正,再次截圖。單次通過最多渲染三次;超過這個次數,問題在於計劃,而非 CSS。

規則

  • 絕不讓伺服器持續運行。 檢查完成後請停止它,或者明確說明它仍在運行以及在哪個連接埠上。使用者機器上殘留的開發伺服器會造成他們需要清理的混亂。
  • 不要啟動你無法停止的東西。 如果專案需要 Docker、資料庫或付費 API 金鑰,請在啟動任何東西之前說明。
  • 回報真實的 URL。 使用 localhost:4173,而不是「應用程式」。如果因為 4173 被佔用而導致連接埠變更,請說明新的連接埠。
  • 在猜測前先讀取日誌。 啟動失敗幾乎總是因為缺少依賴項、缺少環境變數或連接埠已被佔用。.run/server.log 中有答案,引用實際錯誤勝過理論推測。
  • 未經說明不要安裝。 如果缺少 node_modules,npm install 通常是正確的,但這也是對他們專案的修改。請先執行,然後說明已執行,或者當安裝內容較大時徵詢一次同意。
  • 靜態優先於框架。 當建置輸出存在且為最新時,提供 dist/ 目錄比開發伺服器更快且更真實。

無法啟動時的處理

  1. 讀取 .run/server.log 並引用第一個真正的錯誤,而不是最後一行。
  2. 缺少依賴項:在專案中執行 npm install,然後重試。
  3. 缺少環境變數:尋找 .env.example,說明需要哪些變數,且如果某個值是秘密且不存在則停止。
  4. 連接埠已被佔用:腳本會自動移至下一個空閒連接埠;若仍失敗,通常原因是框架設定中寫死了連接埠。
  5. 需要建置步驟:先執行 npm run build,然後提供 dist/ 目錄。
  6. 原生或容器化:請參考專案的說明文件來執行命令。並非所有技術棧都能用腳本處理。

檢查清單

  • 偵測了技術棧而非假設一個
  • 啟動了服務並看到了真實的 HTTP 回應,而不僅是產生了進程
  • 回報了確切的 URL 和連接埠
  • 查看了截圖,而不僅是日誌
  • 確認路由與預期的頁面相符
  • 停止了服務,或說明它仍在運行及其位置
  • 在失敗時引用了真正的錯誤

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能