TechSpecs搜尋

Theme / v1.2.3

Matt Pocock's Engineering Skills

可組合的 AI 工程工作流技能庫

主題首頁GitHub ↗
實戰範例

實戰範例 009：用 /wizard 一次設定好 Stripe CI Secrets

新人首次接 Stripe，用互動式 bash 精靈把只有人類能做的步驟引導一遍，產生可驗證腳本。

情境背景

你是新加入團隊的工程師，第一次要把專案接上 Stripe 付款。你需要：申請 Stripe 帳號、在 dashboard 拿 API key、設定 webhook 驗證、把 secrets 寫進 .env 與 GitHub Actions。這些步驟只能你做，因為涉及點擊、審批、儀表板導航。

/wizard 是設計來引導這類「只有人類能做的步驟」的工具。它會產生一個互動式 bash 腳本，內建進度條、確認閘道、隱藏式 secret 輸入，並用 bash -n 與 shellcheck 驗證產出。

第 1 步：呼叫 wizard 並界定程序範圍

目標：讓 wizard 讀取你的設定檔並提案 stages

/wizard 第一個動作是讀取 .env*、docker-compose*、framework config，以及 .github/workflows/ 內所有 secrets.* 與 vars.* 參考，來劃定程序範圍。

AI 對話：

  • You:

    /wizard
我要把這個專案接上 Stripe，需要設定 API key 與 webhook secret。

  • AI:

    我讀過你的 .env.example 和 .github/workflows/deploy.yml。需要這些 secrets：

    • STRIPE_SECRET_KEY
    • STRIPE_WEBHOOK_SECRET
    • STRIPE_PUBLISHABLE_KEY

    提議的 stages：

    1. 開 Stripe 帳號（開啟 URL）
    2. 取得 API keys（說明在 dashboard 哪裡）
    3. 設定 webhook（開啟 URL、填 endpoint）
    4. 寫入 .env 與 gh secret

    確認 stage 清單嗎？確認後我產精靈。

第 2 步：確認 stage 清單

目標：理解 wizard 的提案階段為什麼是必要的

wizard 不會跳過這個確認直接寫腳本。stage 清單確認兼作模型觸發時的提案，避免 agent 在你沒注意時自動產生不正確的精靈。

AI 對話：

  • You:

    確認。但我想加一個 stage，先在 Stripe dashboard 切到 test mode 再拿 key。

  • AI:

    收到。更新後的 stages：

    1. 開 Stripe 帳號（開啟 URL）
    2. 切換到 test mode（說明 toggle 位置）
    3. 取得 API keys（說明在 dashboard 哪裡）
    4. 設定 webhook（開啟 URL、填 endpoint）
    5. 寫入 .env 與 gh secret

第 3 步：產生精靈並驗證

目標：理解內建 template.sh 已經解決了哪些 UX

wizard 用內建的 template.sh 作為基底，這個檔案之上是一個固定的 library，永不手改。skill 的工作只有劃定程序、撰寫它的 stages。

template.sh 已經處理好的事：

  • 以 stage 名稱與已完成數量呈現進度，不提供剩餘時間預估
  • 每個關鍵步驟前的確認閘道
  • 跨平台 URL 開啟（含 WSL）
  • 隱藏式 secret 輸入，密鑰輸入不回顯
  • 冪等的 .env upsert，重複執行不會重複寫
  • gh secret 與 gh variable 寫入，沒裝 gh 就跳過並說明
  • 結尾的跳過摘要，列出哪些 stage 被跳過

AI 對話：

  • AI:

    精靈已產生：scripts/setup-stripe.sh。

    驗證結果：

    $ bash -n scripts/setup-stripe.sh
# 語法檢查通過
$ shellcheck scripts/setup-stripe.sh
# 沒有 warning

    你可以執行 bash scripts/setup-stripe.sh 開始走流程。

第 4 步：執行精靈

目標：理解人類與精靈的互動方式

執行時，精靈會在每個 stage 開始前暫停並等你確認。secret 輸入時不會回顯到螢幕。

終端機互動範例（精簡呈現）：

$ bash scripts/setup-stripe.sh

[Stage 1/5] 開 Stripe 帳號
即將開啟 https://dashboard.stripe.com/register 在你的瀏覽器。
按 Enter 繼續，或 s 跳過這個 stage：> [Enter]

[Stage 2/5] 切換到 test mode
在 Stripe dashboard 左側欄找「Test mode」toggle 並打開。按 Enter 繼續：> [Enter]

[Stage 3/5] 取得 API keys
請輸入 STRIPE_PUBLISHABLE_KEY（輸入時不會顯示）：> ************
請輸入 STRIPE_SECRET_KEY（輸入時不會顯示）：> ************

[Stage 4/5] 設定 webhook
即將開啟 https://dashboard.stripe.com/webhooks。
請輸入 STRIPE_WEBHOOK_SECRET（輸入時不會顯示）：> ************

[Stage 5/5] 寫入 .env 與 gh secret
正在 upsert .env ... 完成
正在寫入 STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PUBLISHABLE_KEY ... 完成

完成。所有 stages 都已執行。

注意 secret 從頭到尾不出現在螢幕或腳本內容裡。

第 5 步：處理冪等性與跳過

目標：理解重複執行的行為

精靈設計成可以重複跑。如果你中斷再跑，已寫入的 secret 會被 upsert（不重複寫），未完成的 stage 會從上次中斷處繼續。如果你某次故意跳過某個 stage，結尾摘要會列出「Skipped: Stage 2」。

常見誤解

  • wizard 不會做代理能做的事：修改 config 檔或跑 migration 是 /implement 的事。wizard 專為「點擊、審批、儀表板導航」這類代理做不來的步驟。
  • secret 永遠由人類輸入：wizard 不會把密碼、token 或 secrets 寫進腳本本身。它只在執行時引導你輸入，並用隱藏輸入保護。
  • template.sh 不需要你手改：精靈的愉悅 UX 已經被 template.sh 預先解決。skill 的工作只有劃定程序範圍、撰寫 stages。

工具使用摘要

Skill 用途 在本例的作用
wizard 互動式 bash 精靈 引導設定 Stripe secrets 的 5 個 stage
implement 程式碼變更 之後接 Stripe SDK 的程式碼屬於 implement

結果

  • 拿到一份通過 bash -n 與 shellcheck 的互動式腳本
  • Stripe 三個 secrets 都已寫入 .env 與 GitHub Actions
  • 整個過程 secret 從未出現在螢幕或腳本內容裡

關鍵學習點

  • /wizard 只處理「只有人類能做的步驟」，代理能做的就交給代理。
  • secret 永遠由人類在執行時輸入，不會被寫進腳本本身。
  • 內建 template.sh 已解決進度條、確認閘道、隱藏輸入、冪等 upsert 等 UX，你只需撰寫 stages。
  • stage 清單必須先與你確認才寫腳本，避免 agent 在你沒注意時自動產生不正確的精靈。