wizardlisted

# 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`，任何不可逆動作之前都用 `co