Communitygithub.com

tenshowinnovation/tenshow-se-skills

一個精心設計的端到端工作流程,用於將雙語(中文/英文)靜態公司行銷網站部署至火山引擎。

tenshow-se-skills 是什麼?

此技能提供一個高度結構化且「有意見」的流程,專為需要將雙語(中文/英文)靜態公司行銷網站部署至火山引擎(Volcengine)的團隊或開發者設計。它整合了 Astro 6(搭配 React 19 島架構,僅用於行動選單)和 Tailwind 4 作為前端框架,並透過 `ve` CLI 和 Node SDK 自動化部署至 TOS(物件儲存)、CDN、HTTPS 憑證及安全強化。此技能的核心價值在於其「基礎設施即程式碼」的理念,所有部署步驟(如建立儲存桶、設定 CDN、申請憑證)皆以冪等(Idempotent)的 Node 腳本管理,確保每次執行結果一致。使用者只需執行約 6 個指令,即可獲得一個具備 HTTPS、HTTP 強制重導、HSTS、HTTP/2 及邊緣快取功能的正式環境網站。它特別適合目標用戶在中國大陸、已擁有或計畫申請 ICP 備案的專案,並會在使用者情境不符時(如個人網站或僅面向海外用戶),主動建議更簡單的替代方案(如 Vercel 或 GitHub Pages),避免過度工程化。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tenshowinnovation/tenshow-se-skills/tree/HEAD/marketing-site-dev

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

行銷網站開發 (火山引擎)

用於建置並將雙語靜態公司行銷網站部署至火山引擎的端到端技能。分為兩個階段:

  1. 建置 — Astro 6 + React 19 島架構(僅行動選單) + Tailwind 4。全面使用內嵌 SVG。單一內容檔案(src/content/site.ts)為唯一事實來源。
  2. 部署 — TOS 儲存桶 + CDN + 免費 DV 憑證 + HTTPS 強化,全部透過 ve CLI 和火山引擎 OpenAPI(透過 volc-api.mjs 使用 SigV4 簽署,用於 ve 未提供的操作)在冪等的 Node 腳本中編寫。

成功的定義: 使用者執行約 6 個指令端到端,即可獲得 https://<他們的網域>/ 提供一個具備 HTTPS、HTTP 強制重導至 HTTPS、HSTS、HTTP/2、邊緣快取和自動快取失效的生產級雙語網站。每個基礎設施步驟都作為一個冪等腳本保存在版本控制中。


這個技能合適嗎?

這是一個刻意設計、帶有強烈意見的工作流程,針對一個特定情境進行了最佳化。在深入之前,請確認該情境確實符合使用者的情況。如果不符合,請提出更好的替代方案,而不是強迫使用者走一條更複雜的路。

在以下情況使用此技能:

  • 網站是為中國公司或目標用戶在中國大陸的產品而建置 — 從中國大陸連線至非中國 CDN 的延遲相當高(200-400 毫秒,尖峰時段更糟),訪客會明顯感覺到並可能因此跳出。
  • 需要或已擁有 ICP 備案 — 在中國合法分發內容需要與託管在中國雲端上的網域進行備案綁定。火山引擎提供備案協助,並可為您在此部署的網域提供服務。
  • 使用者已處於火山引擎生態系統中(使用其他火山引擎服務、現有 TOS 儲存桶等),整合具有價值。
  • 需要中英文雙語模式 — 內容層(site.ts)正是為此設計的。

在以下情況使用更簡單的替代方案:

情境建議的替代方案原因
個人網站 / 作品集 / 副業專案,無中國觀眾需求GitHub Pages免費、自動 HTTPS、git push 即可部署,無需管理基礎設施。零個火山引擎的潛在問題。
僅面向國際觀眾(美國/歐盟/東南亞),無中國市場計畫Vercel(或 Cloudflare Pages / Netlify)免費方案、從 Git 即時部署、每個 PR 有預覽 URL、自動 HTTPS、全球邊緣網路。完全跳過 ve CLI + ICP 工作流程。
網站需要無伺服器函數(表單、驗證、動態內容)Vercel 或 Cloudflare Pages 搭配其邊緣函數此技能僅提供靜態內容 — 火山引擎有無伺服器產品,但此工作流程未涵蓋。
你需要每個分支 / PR 的預覽 URL 進行審查VercelVercel 的預覽 URL 體驗是同類最佳。此技能每次推送僅產生一個生產部署;沒有分支預覽。

如果使用者的情況符合「建議的替代方案」欄位,請在建置任何東西之前明確告知他們。當使用者不需要火山引擎提供的功能時,花 2 分鐘用 Vercel 部署會比花 30 分鐘引導使用火山引擎更好。不要因為他們呼叫了這個技能就讓他們投入錯誤的技術棧。

如有疑問,請詢問:「中國大陸的用戶會是您觀眾群中的重要部分嗎?您是否擁有(或計畫申請)該網域的 ICP 備案?」如果兩個答案都是「否」,請直接指向 Vercel / GitHub Pages 並停止。


步驟 1:捕捉意圖(永遠先問)

在從使用者那裡獲得以下六項輸入之前,請不要編寫任何程式碼。如果提示中缺少這些資訊,請透過 AskUserQuestion 提問。大多數團隊會擁有所有資訊,可能除了公安備案號 — 該項可以先用佔位符代替。

#輸入用途備註
1公司名稱(中文 + 英文)site.ts 中的 COMPANY.nameZh / COMPANY.nameEn;頁尾;SEO
2網域(例如 example.com)任何地方 — 儲存桶綁定、CDN、DNS、憑證 SAN必須已經 ICP 備案,且最好託管在火山引擎 DNS 上。如果託管在其他地方,使用者需要手動新增 CNAME 和 TXT 記錄。
3品牌資產目錄(SVG 標誌檔案的路徑)內嵌 BrandMark.astro 提取(短版標誌 SVG 的最後 3 個路徑)通常是類似 assets/logo/svg/Tenshow_short1.svg 的短版 / 僅圖示的變體。
4產品列表site.ts 中的 PRODUCTS[]每個產品需要雙語名稱 + 描述、URL、強調色十六進位碼、圖示列舉值。
5ICP 備案號頁尾工信部核發的備案號。
6工作目錄專案根目錄應該是全新(空的)目錄,否則你必須協調現有檔案。

可選:

  • 公安備案號 — 在建置時通常用佔位符代替。請在 README 中明確標記,以便使用者在啟動前替換它。
  • 品牌強調色 — 從標誌 SVG 的十六進位值中提取。如果無法決定,預設使用主色中非中性的顏色。

步驟 2:建置靜態網站

完整細節請參閱 references/phase-1-static-site.md。摘要如下:

  1. 建置腳手架 — 將 assets/templates/package.json 和 assets/templates/astro.config.mjs 複製到專案根目錄。更新 package.json 中的 name 和 astro.config.mjs 中的 site。
  2. 安裝套件 — pnpm install。
  3. 安裝 Astro 代理技能 — 僅在 pnpm install 成功後執行:
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    如果技能安裝失敗,請繼續進行網站建置,並記錄失敗訊息,讓使用者稍後重試;不要因此阻塞工作流程。
  4. 建立源代碼目錄樹 — 使其符合 phase-1-static-site.md 中的佈局(src/content/site.ts、src/components/、src/layouts/BaseLayout.astro、src/pages/index.astro、src/pages/en/index.astro、src/styles/global.css)。
  5. 提取品牌標記 — 從使用者的 SVG 中提取,使用 assets/templates/BrandMark.astro 作為起點。短版標誌 SVG 的最後 3 個 <path> 元素即為標記;逐字複製它們並從品牌色板中選取填充色。
  6. 建置章節 — Hero(使用 phase-1-static-site.md 中的精確配方 — 網格背景 + 徑向光暈 + 漸層標題 + 狀態標籤 + 2 個 CTA 按鈕)、關於我們、產品、焦點、最新消息、聯絡我們、頁尾。頁首固定,行動選單 = 唯一的 React 島。
  7. 在本地驗證 — pnpm dev 進行開發,pnpm build && pnpm preview 在接觸基礎設施前檢查靜態輸出是否正常。

技術棧鎖定(請勿偏離)

Astro 6、React 19(僅行動選單)、透過 @tailwindcss/vite 使用的 Tailwind 4、pnpm 10、Node 22+、TypeScript 嚴格模式、零外部圖片、零 UI 函式庫、零字型服務、系統字型堆疊。理由和完整細節請參閱 phase-1-static-site.md。


步驟 3:設定部署基礎設施

完整細節請參閱 references/phase-2-volcengine-deploy.md。請先閱讀 references/landmines.md — 在此階段,你一半的時間都在避免踩雷,而不是執行指令。

  1. 複製腳本 — 將整個 assets/scripts/ 目錄和 assets/cdn-payloads/ 分別複製到使用者的 scripts/ 和 scripts/cdn-payloads/ 目錄。將 assets/templates/deploy.config.mjs 複製到專案根目錄,並填入 bucket、region、endpoint、cdnDomains。
  2. 取代 Payload 中的佔位符 — 取代 scripts/cdn-payloads/apex.json 和 www.json 中的 {{DOMAIN}}、{{BUCKET}}、{{REGION}}。OriginHost 必須是網域本身,不能為空 — 模板預設是正確的;如果你編輯它們,請保留 OriginHost。請參閱 landmines.md #3。
  3. 建立 .env 檔案於專案根目錄(已加入 gitignore):
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    火山引擎 AK/SK 需要 TOSFullAccess、CDNFullAccess、DNSFullAccess、CertificateFullAccess(或最小權限等價設定)。
  4. 確認 ve 已安裝:ve version — 需要 1.0.x 或更高版本。如果缺少,請依照火山引擎官方文件安裝。

步驟 4:執行首次部署

pnpm install                        # 如果尚未完成
npx skills add https://github.com/astrolicious/agent-skills --skill astro  # 如果尚未完成
pnpm build                          # 驗證本地建置是否正常
pnpm run setup:bucket               # 冪等:建立儲存桶 + 網站路由 + 自訂網域綁定
pnpm run deploy:upload              # 同步 dist/ → 儲存桶
# 此時:https://<bucket>.tos-<region>.volces.com/index.html 應該回傳 200
pnpm run setup:cdn                  # 驗證所有權 → 新增 CDN → CNAME → 憑證 → HTTPS 強化
# 等待 1-3 分鐘讓 DNS 傳播
pnpm run cdn:refresh                # 清除邊緣快取,確保首次訪問不會回傳儲存桶列表 JSON

在這次初始執行之後,日常迭代只需一個指令:

pnpm run deploy && pnpm run cdn:refresh

務必使用 pnpm run,而不是單純的 pnpm

pnpm deploy 是 pnpm 的內建工作區指令 — 它會在非工作區的環境中報錯 ERR_PNPM_CANNOT_DEPLOY。請使用 pnpm run deploy 和 pnpm run cdn:refresh。在專案的 README 中記錄此點。請參閱 landmines.md #6。


步驟 5:驗證

執行 references/verification.md 中的 curl + openssl 檢查清單。預期結果:關鍵路由上 5 次 HTTP 200,HTTP → HTTPS 上 1 次 301 重導,有效憑證其 SAN 涵蓋頂級網域和 www 子網域,確認 HTTP/2 + HSTS,Cache-Control 標頭符合 deploy.config.mjs 規則。

如果任何檢查失敗,verification.md 會將每種失敗模式對應到根本原因和修復方法。


執行前必須知道的關鍵地雷

完整列舉請參閱 landmines.md。如果你跳過閱讀,你可能會遇到以下問題:

  1. HTTPS_PROXY 污染 — TOS SDK + 本地 HTTP Proxy = Protocol "http:" not supported。assets/scripts/ 中的每個腳本已在頂部刪除了 Proxy 環境變數 — 如果你複製或改編它們,請保留該前綴程式碼。
  2. TOS SDK 怪癖 — headBucket(string) 而非 headBucket({bucket});當 continuationToken: undefined 存在於輸入中時,listObjectsType2 簽章會中斷;putObject 即使在公開讀取的儲存桶上也預設為私有 — 務必設定 acl: 'public-read'。
  3. TOS 沒有單獨的網站端點主機名稱 — 同一個 <bucket>.tos-<region>.volces.com 會根據 Host 標頭回傳儲存桶列表 JSON 或 index.html。你必須 (a) 為每個頂級/www 網域呼叫 putBucketCustomDomain,並且 (b) 在 CDN AddCdnDomain payload 中將 OriginHost 設定為使用者的網域(不能為空)。
  4. 驗證時 CDN ≠ DCDN — CDN(內容分發網路)想要 TXT 主機記錄 volccdnauth,並使用 cdn:CheckCdnDomain(不在 ve CLI 中 — 使用 volc-api.mjs)。DCDN(全站加速)使用 _dnsauth 和 ve dcdn VerifyDomainOwnership。混淆它們 = 無止盡的驗證循環。
  5. TXT 變更需要約 10 分鐘傳播到火山引擎的驗證器。第一次寫入時就讓值正確;不要反覆修改。
  6. pnpm deploy 是內建指令。 請使用 pnpm run deploy。
  7. 免費 DV 憑證的申請僅限控制台。 使用永久 AK/SK 透過 API 簽發會失敗 (OperationDenied.RequestFreeInstance)。但列出已簽發的憑證是可行的 — 免費 DV 憑證通常會在網域註冊時自動簽發。務必先呼叫 CertificateGetInstanceList;在 Result.Instances[] 中尋找(不是 InstanceList,也不是 Data),尋找一個其 San 涵蓋頂級網域和 www 子網域的憑證。

行為規則

  • 先計畫;在執行破壞性操作前確認。 在執行 createBucket、AddCdnDomain、DeleteRecord(針對現有 TXT 記錄)或 BatchDeployCert 之前,先總結即將發生的操作並向使用者確認。
  • 在寫入之前先讀取現有狀態。 務必先執行 ListRecords / ListCdnDomains / CertificateGetInstanceList — 免費憑證通常已預先簽發、CDN 網域可能已存在、DNS 記錄可能已指向正確位置。冪等性是重點。
  • 當 ve 缺少某個操作時,使用 volc-api.mjs,而不是告訴使用者升級 ve 或使用控制台。唯一真正的僅限控制台路徑是免費 DV 憑證簽發(landmines.md #4)。
  • 不要頻繁修改 DNS 記錄。 每次 TXT 修改都會增加約 10 分鐘的快取時間。第一次就讓主機/值正確 — CDN 用 volccdnauth,DCDN 用 _dnsauth,它們不能互換。
  • 將每個設定決策都放在 deploy.config.mjs 中, 永遠不要硬編碼在腳本裡。儲存桶、區域、端點、CDN 網域、快取規則 — 全部放在設定檔中,這樣使用者可以編輯一個檔案來改變所有設定。
  • /usr/bin/curl 比單純的 curl 更可靠,在長時間指令後於同一個 shell 中執行檢查時 — bash 的 PATH 查找偶爾會出問題。CI 腳本中的測試也是如此。

打包的資產和參考資料

assets/scripts/(逐字複製到使用者的 scripts/ 目錄)

  • lib/volc-api.mjs — SigV4 簽署器,無依賴。用於 ve CLI 缺少的任何操作。
  • setup-bucket.mjs — 冪等:建立儲存桶 + 網站設定 + 自訂網域綁定。
  • deploy.mjs — TOS 同步上傳器,支援按前綴設定 Cache-Control,以及孤兒檔案刪除。
  • cdn-setup.mjs — CDN 編排:所有權驗證 → AddCdnDomain → CNAME → 憑證 → HTTPS 強化。
  • cdn-refresh.mjs — 透過 cdn:SubmitRefreshTask 進行快取失效(由 volc-api.mjs 簽署,可在沒有 ve 的 CI 環境中運作)。

assets/cdn-payloads/(複製到 scripts/cdn-payloads/)

…[為翻譯而截斷]

相關技能