支援

排錯指引

Watt 用 0～5 的 exit code 區分結果類別。先從 exit code 判斷錯誤類別，再處理該類別真正的原因；不要把所有非零結果都當成測試失敗。

Exit code 對照

Code	名稱	先做什麼
0	success	指令成功；對 `watt run` 而言，代表所有執行的 steps 成功。
1	step failed	讀取 result，找出 failed step 的輸出尾段。
2	invalid pipeline / usage	修正 watt.yaml、指令名稱或旗標；不要直接重試。
3	environment unavailable	安裝或修正缺少的 command / shell；不是驗證失敗。
4	cancelled	執行被中途取消，結果不具成敗判定效力，不能當作驗證失敗；視需要重新執行。
5	internal error	保留輸出並回報 Watt 問題；不是驗證失敗。

找不到或無效的 watt.yaml

確認目前終端機所在位置就是專案根目錄，且其中有名為 watt.yaml 的檔案。接著執行 watt check，依訊息修正 YAML 語法、未知欄位、空 pipeline、重複 step 名稱，或 exec／run 的錯誤組合。

PowerShell

Get-Location
Get-ChildItem watt.yaml
watt check

缺少 command 或 shell

watt check --env 會列出缺少的 command 或 shell。確認其安裝位置在目前 PowerShell 的 PATH 中，然後重新開啟終端機再檢查。

PowerShell

watt check --env
Get-Command go
Get-Command pwsh

若使用 run 而未設定 shell，預設需要 PowerShell 7 的 pwsh——這是 PowerShell 7 的執行檔名稱，和 Windows 內建、執行檔名為 powershell.exe 的 Windows PowerShell 5.1 不同。找不到 pwsh 時，Watt 會明確報錯，不會自動改用 Windows PowerShell 5.1；可安裝 PowerShell 7，或在你的 step 明確使用支援的 cmd shell。

Step 失敗

exit code 1 代表某個 step 非零結束，或該 step 的工作目錄等執行前置條件無效。開啟 .watt/result.json，檢查 failed step 的名稱與 output_tail，再直接修正該專案的 test、build 或 package 指令。

Pipeline 中途失敗時，Watt 仍會記錄已經開始執行的 step（partial result；不保證寫入一定成功）；尚未開始的 step 不會出現在結果檔中，也不會用 skipped 佔位。

取消或內部錯誤

按 Ctrl+C 後，Watt 會終止目前正在執行的 step 所啟動的所有相關程序（process tree）。若安全終止已確認，會回傳 code 4；若無法確認清理完成或 result 寫入失敗，會回傳 code 5。遇到 code 5 時，請保留終端輸出與可取得的 result，再到 GitHub Issues 回報。