wizard 是做什麼的？
Wizard 是一個 Bash 腳本，它能逐步引導人類完成一個手動程序 — 那些用手操作很繁瑣、每次都要重新向 AI 解釋也很煩人的步驟。它會開啟每個 URL，精確指出要點選和複製的內容，擷取值，將值寫入正確的位置（.env、GitHub Secrets），在每個階段要求確認，並顯示剩餘階段數。它可能用來設定第三方服務、執行一次性遷移，或將專案從一種狀態轉換到另一種狀態。
愉快的使用者體驗已經由 template.sh 解決：階段式進度、確認關卡、跨平台 URL 開啟（包含 WSL）、隱藏機密輸入、冪等 .env 更新、gh secret/gh variable 寫入，以及最終總結。您的工作僅是規劃程序並編寫其階段。 在 STAGES 標記上方的函式庫在所有精靈中都相同；一致性是重點：永遠不要手動編輯它。
Wizard 預設是短暫的：為一次性執行而建立，儲存到暫存或 scripts/ 路徑，工作完成後刪除。僅在使用者希望將可重複的設定路徑保留在儲存庫中時才進行提交。
流程
1. 規劃程序
找出人類必須執行的每個手動步驟，以及在過程中會擷取的每個值。先閱讀儲存庫，不要貿然提問：
- 對於設定：
.env、.env.example、.env.*、README、docker-compose*、框架設定檔，以及.github/workflows/*（每個secrets.*/vars.*的引用都是 Wizard 必須產生的值）。 - 對於遷移或轉換：當前狀態、目標狀態，以及兩者之間的不可逆操作。
然後向使用者展示有序的階段列表以及每個階段產生的值，並請使用者確認：他們可以新增、刪除或重新排序。
完成條件： 每個階段都已依序命名，且對於每個擷取的值，您都清楚 (a) 人類從何處取得它，(b) 它會被寫入何處（.env、GitHub Secret、兩者皆寫，或無；有些階段僅是純操作），以及 (c) 它是否為機密（需要隱藏輸入）或公開。
2. 規劃每個階段的操作路徑
針對每個階段，撰寫人類需要遵循的精確路徑：要開啟哪個 URL、在那裡做什麼、值顯示在哪裡、填入哪個變數：例如「儀表板 → 開發者 → API 金鑰 → 顯示測試金鑰 → 複製」。當您不確定目前的 UI 或確切指令時，請說明並詢問使用者或查閱文件：切勿發明可能不存在的步驟。
完成條件： 每個階段都對應到陌生人也能遵循的具體指示。
3. 編寫 Wizard
將 template.sh 複製到目標路徑。將範例階段替換為您的步驟，每個步驟一個 stage，並按依賴順序排列。使用函式庫輔助工具：stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm。將 TOTAL_STAGES 設定為您編寫的階段數量。
維持範本設定的標準：在要求輸入值之前先開啟 URL；對機密內容使用 ask_secret；對所有持久化值使用 write_env；僅對 CI 實際需要的值使用 set_secret；在任何不可逆操作前使用 confirm。每個 stage 會清除畫面，僅顯示當前步驟：讓一個階段專注於一個任務，這樣人類需要的資訊就不會滾動消失。請勿觸碰標記上方的函式庫。
4. 驗證與交接
- 執行
bash -n <script>；如果可以，執行shellcheck。 - 執行
chmod +x <script>。 - 不要親自端到端執行它：它會開啟瀏覽器並等待人類輸入。請改為靜態追蹤：步驟 1 中的每個值都被擷取並寫入步驟 1 指定的位置，且每個
set_secret的名稱都與 CI 中的secrets.*引用完全相符。 - 告知使用者如何執行它。如果這是一條可重複的設定路徑，請將它提交並在 README 中連結，這樣下一個人就能執行腳本，而不是詢問 AI。