784697524-ux/aliyun-static-site-deploy-skill

阿里雲靜態網站部署

核心規則

• 將 EMAS Serverless 靜態託管 視為預設的初學者無網域預覽路線。它為用戶提供阿里雲預設 URL，並避免常見的 OSS 預設網域下載問題。
• 將 OSS + GitHub Actions 視為可重複的自動化路線，僅在用戶明確希望 GitHub 到阿里雲自動化、已有或能建立 OSS Bucket，且了解最終 URL 必須驗證為內聯 HTML 時使用。
• 不假裝可以自動化阿里雲登入、實名驗證、付費服務啟用、AccessKey 建立、GitHub 2FA 或帳單確認。請暫停並要求用戶完成這些步驟。
• 絕不要求用戶將 ALIYUN_ACCESS_KEY_SECRET、GitHub 令牌、密碼或付款截圖貼入聊天。請要求用戶直接在 GitHub Secrets 或阿里雲/GitHub 介面中輸入機密。

首次決策

在撰寫部署程式碼之前，先決定路線並明確說明：

路線	使用時機	自動化程度	風險
EMAS 靜態託管	無自訂網域、初學者預覽、用戶可操作阿里雲控制台	代理準備檔案並引導控制台步驟；用戶處理登入/付款/上傳（如有需要）	控制台 UI 可能變更，且可能需要手動上傳
OSS 工作流程	用戶想要 Codex X GitHub X 阿里雲自動化；可準備 OSS Bucket 和 AccessKey	代理可產生工作流程、推送程式碼、觸發 CI 並驗證 URL	OSS 預設網域可能下載 HTML，除非中繼資料/靜態託管設定正確

如果用戶僅說「沒有域名先給客戶看」，請先使用 EMAS 指引。如果用戶說「自動上線」、「XgitX阿里雲」、「GitHub 自動部署」或「以後反覆更新」，請使用 OSS 工作流程腳本，但在繼續前請說明瀏覽器下載驗證風險。

工作流程

1. 檢查專案：

   python3 /Users/likai/.codex/skills/aliyun-static-site-deploy/scripts/check_readiness.py --project .
   

2. 用一句話說明部署路線：
   • OSS：「用 GitHub Actions 上傳到阿里雲 OSS，並驗證瀏覽器不是下載檔案。」
   • EMAS：「先用阿里雲 EMAS 靜態託管拿到無域名預覽地址。」
3. 如果用戶尚未準備阿里雲存取權限，請閱讀 references/secrets-hand-off.md 並要求用戶完成阿里雲登入/付款/AccessKey/GitHub Secrets。在說明點擊位置時使用隨附的螢幕截圖。
4. 僅針對 OSS 自動化，產生 GitHub Actions 工作流程：

   python3 /Users/likai/.codex/skills/aliyun-static-site-deploy/scripts/prepare_oss_workflow.py --project . --force
   

5. 再次驗證產生的 workflow 和本地專案：

   python3 /Users/likai/.codex/skills/aliyun-static-site-deploy/scripts/check_readiness.py --project . --strict
   

6. 如果用戶要求且憑證可用，則將專案提交/推送至 GitHub。如果 Git LFS 安裝不正確，請使用腳本輸出說明修正方法，而非盲目重試。
7. 部署完成後，驗證公開 URL：

   python3 /Users/likai/.codex/skills/aliyun-static-site-deploy/scripts/verify_deployed_url.py "$ALIYUN_SITE_URL"
   

必要 GitHub Secrets

對於內含的 OSS 工作流程，要求用戶在 GitHub 中建立以下儲存庫 Secrets：

• ALIYUN_ACCESS_KEY_ID
• ALIYUN_ACCESS_KEY_SECRET
• ALIYUN_OSS_BUCKET
• ALIYUN_OSS_ENDPOINT

可選：

• ALIYUN_SITE_URL 用於部署時驗證。範例：https://your-bucket.oss-cn-hangzhou.aliyuncs.com/index.html

對於 EMAS，請使用該專案中 EMAS 部署腳本所需的確切 Secret 名稱。如果沒有 EMAS 腳本，請勿捏造虛假的 Secret 名稱；請引導用戶手動上傳 EMAS 靜態託管，或在確認官方 API/SDK 路徑後建立專案專用腳本。

人類邊界

當以下任何項目遺失時，請停止並呼叫使用者：

• 阿里雲帳戶未登入、未實名驗證或要求付款。
• EMAS 服務空間、OSS Bucket 或靜態託管尚未建立。
• AccessKey 尚未建立。
• GitHub Secrets 尚未填寫。
• GitHub 要求使用者名稱/令牌或雙因素驗證。

向使用者顯示確切的填寫欄位，但不要在聊天中接收機密。

部署成功條件

在所有檢查通過之前，部署視為未完成：

• GitHub 儲存庫擁有已提交的網站原始碼和部署說明。
• 對於 OSS 自動化，GitHub 儲存庫在 .github/workflows/deploy-aliyun-static-site.yml 包含產生的 workflow，且 Actions 執行在 main 或 workflow_dispatch 上成功。
• 對於 EMAS 手動/靜態託管上傳，阿里雲控制台顯示已上傳的首頁檔案和公開預設 URL。
• 公開 URL 回傳 HTTP 200 或 3xx 後接 200。
• 回應是 HTML，而非 XML 錯誤文字或強制下載的中繼資料。
• 網頁包含 <html 以及非空的標題或可見主體文字。
• 首頁引用的關鍵資源為公開或遠端 URL。

參考資料

• 當使用者需要逐步阿里雲/GitHub Secrets 協助時，請閱讀 references/secrets-hand-off.md。
• 當部署或 URL 驗證失敗時，請閱讀 references/troubleshooting.md。