Wizard

---
name: wizard
description: 產生一個互動式 bash wizard，引導人類走過只有他們能做的步驟。用於佈建基礎設施、設定憑證或 CI secrets、走訪陌生的第三方儀表板，或執行一次性遷移或切換。不要為代理自己能做的步驟叫用它。
---

# Wizard

**wizard** 是一個 bash 腳本，一步步引導人類走過一個手動程序——這個程序用手做很繁瑣，每次都要向 AI 重新解釋也很繁瑣。它開啟每個 URL、明確說要點擊和複製什麼、捕捉這些值、把它們寫到該去的地方（`.env`、GitHub secrets）、在每個階段確認，並顯示還剩多少。它可能設定第三方服務、執行一次性遷移，或把專案從一個狀態移到另一個。

討喜的 UX 已經由 [template.sh](template.sh) 解決了——附剩餘時間的進度、確認關卡、跨平台 URL 開啟（含 WSL）、隱藏式機密輸入、冪等的 `.env` upserts、`gh secret`／`gh variable` 寫入，以及結束摘要。**你的工作只是界定程序的範圍並撰寫它的階段。** `STAGES` 標記以上的程式庫在每個 wizard 中都是相同的；那個一致性正是重點——絕不手動編輯它。

wizard 預設是短暫的——為一次運行而建，存到暫存或 `scripts/` 路徑，工作完成時刪除。只有當使用者想要一個應該留在 repo 中的可重複設定路徑時，才 commit 它。

## 流程

### 1. 界定程序範圍

理出人類必須採取的每個手動步驟，以及一路上被捕捉的每個值。先讀 repo——不要冷不防就問：

- 對設定而言：`.env`、`.env.example`、`.env.*`、`README`、`docker-compose*`、框架設定，以及 `.github/workflows/*`（每一個 `secrets.*`／`vars.*` 引用都是一個 wizard 必須產出的值）。
- 對遷移或過渡而言：目前狀態、目標狀態，以及兩者之間不可逆的動作。

然後向使用者展示有序的階段清單與每個階段產出的值，並確認——他們可以新增、刪除或重新排序。

**完成當：** 每個階段都依序命名，而且對每個捕捉的值你都知道（a）人類從哪裡取得它、（b）它被寫到哪裡（`.env`、GitHub secret、兩者，或哪裡都不是——有些階段是純動作），以及（c）它是機密（隱藏輸入）還是公開的。

### 2. 描繪每個階段的旅程

對每個階段，寫下人類遵循的精確路徑：要開啟哪個 URL、在那裡做什麼、值顯示在哪裡、它填入哪個變數——例如「Dashboard → Developers → API keys → Reveal test key → copy」。在你實際上不知道目前的 UI 或確切指令的地方，說出來並詢問使用者或查閱文件——絕不發明可能不存在的步驟。

**完成當：** 每個階段都能追溯到陌生人也能遵循的具體指示。

### 3. 撰寫 wizard

把 `template.sh` 複製到目標路徑。以依依賴順序、每個步驟一個 `stage`，取代範例階段。使用程式庫輔助函式——`stage`、`say`／`step`、`open_url`、`ask`／`ask_secret`、`write_env`、`set_secret`／`set_var`、`pause`／`confirm`——並把 `TOTAL_STAGES` 與 `TOTAL_MINUTES` 設為誠實的估計值（這會驅動剩餘時間顯示）。

維持範本設定的標準：在詢問值之前先開啟 URL，任何機密都用 `ask_secret`，每個要持久化的值都用 `write_env`，只有 CI 真正需要的值才用 `set_secret`，任何不可逆動作之前都用 `confirm`。每個 `stage` 會清除畫面，讓只有目前的步驟可見——把一個 stage 保持為單一聚焦的任務，這樣人類需要的東西就不會捲走。別碰標記以上的程式庫。

### 4. 驗證並交接

- `bash -n <script>`；如果有 `shellcheck` 就執行它。
- `chmod +x <script>`。
- 不要自己端對端執行它——它會開啟瀏覽器並阻塞等待人類輸入。改以靜態追蹤它：第 1 步的每個值都被捕捉、落在第 1 步所說的地方，而且每個 `set_secret` 名稱都精確對應 CI 中的 `secrets.*` 引用。
- 告訴使用者怎麼執行它。如果它是可重複的設定路徑，就 commit 它並從 README 連結它，讓下一個人執行腳本，而不是問 AI。