使用指南

撰寫 watt.yaml

用一份簡單、明確的 YAML 定義要依序執行的 pipeline 與 steps。

基本結構

watt.yaml

version: 1

env:
  CI: "true"

pipelines:
  default:
    steps:
      - name: Test
        exec: go
        args: ["test", "./..."]

      - name: Build
        exec: go
        args: ["build", "./..."]

根層的 version 目前固定為 1。pipelines 至少需要一組具名 pipeline；沒有在 watt run 指定名稱時，Watt 會執行名為 default 的 pipeline。

選擇 step 模式

每個 step 只能擇一使用 exec 或 run。前者直接啟動可執行檔；後者交由指定 shell 執行腳本。

模式	適用情況	可搭配欄位
exec	已有明確 command 與參數。	`args`、`cwd`、`env`
run	需要 shell script、管線或多行指令。	`shell`、`cwd`、`env`

watt.yaml

version: 1

pipelines:
  default:
    steps:
      - name: Direct command
        exec: go
        args: ["test", "./..."]

      - name: PowerShell script
        shell: pwsh
        run: |
          New-Item -ItemType Directory -Force dist
          Copy-Item README.md dist\

run 未指定 shell 時預設為 pwsh——這是 PowerShell 7 的執行檔名稱，跟 Windows 內建、執行檔名為 powershell.exe 的 Windows PowerShell 5.1 是不同版本。Phase 1 支援 pwsh 與 cmd；bash 尚未支援。找不到 pwsh 時 Watt 會明確報錯，不會自動改用 Windows PowerShell 5.1。

設定工作目錄與環境變數

cwd 相對於專案根目錄；未指定時就是專案根目錄。環境變數的套用順序是：先讀取目前 Windows 環境中的變數，再套用整份 pipeline 的設定，最後套用個別 step 的設定；同名變數以越後面的值為準。

watt.yaml

version: 1

env:
  CONFIGURATION: Release

pipelines:
  default:
    steps:
      - name: Build app
        exec: dotnet
        args: ["build", "-c", "Release"]
        cwd: src\App
        env:
          CI: "true"

不要讓指令主動印出密碼、存取權杖（token）或其他敏感資料。結果檔的 environment 區塊不記錄環境變數的值，只列出變數名稱等安全診斷資訊；Watt 也會遮住 resolved_command 與 output_tail 中符合規則的已知環境值，但無法保證識別所有秘密——Watt 不是保管秘密的工具。完整邊界請見 docs/spec.md R-4／R-8。

驗證你的定義

每次修改 watt.yaml 後先執行：

PowerShell

watt check
watt check --env

未知欄位、重複 step 名稱、空 pipeline、同時使用 exec 與 run 都會在靜態驗證階段失敗。