Communitygithub.com

JayFarei/opentraces

將所有網站相關的修復合併到 main 分支,把 opentraces.ai 部署到 Vercel 正式環境,並驗證其在所有頁面(桌面 + 行動裝置)以及電子郵件擷取流程中皆能正常運作,持續修正並重新部署直到一切正常。以目標導向的方式運作:合併 -> 部署 -> 驗證 -> 分類 -> 重複直到安全。當使用者說「deploy site」、「deploy to vercel」、「push site」、「ship the site」、「deploy-site」或「land and verify the site」時使用。如需進行完整的協調發布(同時版本更新並發布 Python 套件),請改用 /release-pack。

opentraces 是什麼?

此技能將部署 Next.js 行銷網站(`web/site/`)至 Vercel 正式環境視為一個循環目標,而非單一指令。它會自動化一個閉環流程:將所有網站相關的修正合併到 `main` 分支、部署至 Vercel、在正式環境中驗證所有路由和電子郵件擷取功能是否正常運作,並持續修正與重新部署,直到所有檢查點都通過。此技能支援 Vercel 平台上的 `opentraces` 專案,其架構為 Next.js 16(App Router),根目錄設定為 `web/site/`,網域為 `opentraces.ai`。其運作流程分為四個階段:範圍界定與合併(Phase 0)、建置與部署(Phase 1)、使用 JIT 測試框架進行生產驗證(Phase 2,由一個獨立的 `.workflow.js` 檔案驅動,涵蓋桌面與行動裝置的多個 viewport、路由、控制台錯誤檢查以及電子郵件擷取測試),以及分類與迭代(Phase 3)。此技能明確防止對正式環境的電子郵件清單造成污染,並包含強固的失敗處理機制,若連續三次嘗試失敗或遇到憑證/環境問題,將會報告為「BLOCKED」狀態。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JayFarei/opentraces/tree/HEAD/.claude/skills/deploy-site

在你喜歡的 AI 中提問

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

說明文件

部署網站

將 Next.js 行銷網站 (web/site/) 部署到 Vercel 正式環境,但將其視為一個目標,而非單一指令:將所有網站相關的修正合併到 main 分支、部署它、證明它在所有頁面和電子郵件擷取流程(桌面與行動裝置)的正式環境中都能運作,並持續修正與重新部署,直到一切都綠燈通過。

目標合約

將此技能當作一個閉環來執行。請勿僅憑 Vercel 部署成功就宣告任務完成;一個部署可能成功,但某個頁面卻回傳 500 錯誤、行動裝置版型跑掉,或 waitlist 寫入無聲地失敗。

  • 完成 (DONE) 當:所有網站相關的修正都已提交並推送到 main、正式環境部署成功、以下每個路由在桌面 與 行動裝置上都回傳 200 且正確渲染(無控制台/網路錯誤),而且電子郵件擷取流程能接受提交並持續儲存(透過管理員讀取驗證),且不留任何測試資料。
  • 未完成 (NOT DONE,再次循環) 當:任何一個路由無法渲染、在某個 viewport 下版型跑掉、控制台出現錯誤,或電子郵件擷取無法完整來回。請修正來源碼,重新合併、重新部署、重新驗證。
  • 受阻 (BLOCKED,停止並回報) 當:修正需要你沒有的憑證或決策(例如 KV 儲存服務掛掉、管理員 token 遺失、Vercel 認證過期),或者同一個失敗在 3 次修正嘗試後依然存在。請回報確切的失敗原因與你嘗試過的方法;不要無限循環。

保留每次迭代的簡短執行記錄(失敗內容、你修改了什麼、重新驗證的結果),以便循環過程可供審計。如果使用者希望將其設為持續性的 /goal,請將目標指向此技能並使用相同的 DONE/BLOCKED 條件。

循環

階段 0  範圍界定與合併    收集網站修正 -> 本地驗證 -> 提交 -> 推送到 main
階段 1  部署              建置 -> npx vercel@latest --prod (從儲存庫根目錄)
階段 2  驗證 (正式環境)    工作流程擴散:路由 x viewports + 電子郵件擷取
階段 3  分類              有任何紅燈?修正來源碼 -> 回到階段 0
                          全部綠燈?-> DONE

背景資訊

  • 專案:Vercel 上的 opentraces(scope jayfareis-projects)
  • 框架:Next.js 16 (App Router)
  • 根目錄:Vercel 設定根目錄為 web/site/
  • 網域:opentraces.ai(正式環境:https://opentraces.ai)
  • 建置:next build(從 web/site/ 執行)
  • 版本:在建置時經由 next.config.ts 從 src/opentraces/__init__.py 自動讀取
  • 電子郵件擷取:EarlyAccessForm 將資料 POST 到 /api/waitlist(正式環境使用 Upstash/KV)。在 /(透過 HubTeaser)和 /hub 頁面上渲染。請參閱參考章節了解選擇器和管理員讀取方式。

階段 0 — 範圍界定並合併網站修正

  1. 找出哪些是網站相關且尚未合併的內容。 工作目錄通常同時包含網站與非網站的變更。這裡只合併網站的修正(其餘部分屬於另一個關注領域)。

    git status --short web/site/
    git status --short -- ':!web/site/'   # 非網站的變更,通常保留這些
    git log --oneline origin/main..HEAD -- web/site/   # 尚未推送的網站提交
    
  2. 合併前進行本地驗證(關卡)。 針對已在執行的開發伺服器執行網站,並使用 agent-browser 檢查變更過的表面:淺色 + 深色模式、桌面 + 行動裝置、你修改的特定互動,以及控制台/網路是否乾淨。這是合併前的最終關卡;請勿提交有視覺回歸的變更。(如果開發伺服器未啟動,請在一個閒置 port 上執行 cd web/site && npm run dev,驗證完後再停止它。)

  3. 本地建置(捕捉開發伺服器隱藏的型別/建置錯誤):

    cd web/site && npm run build
    

    在建置失敗時先修正錯誤再繼續。

  4. 提交到 main 並推送。 依照專案慣例,直接提交到 main(除非被要求,否則不要自動建立功能分支)。將提交範圍限制在網站修正上;根據儲存庫的 footer 規則,共同撰寫提交訊息。

    git add web/site/   # 只加入你驗證過的網站修正
    git commit -m "fix(site): <修改內容>"
    git push origin main
    

階段 1 — 建置與部署

從儲存庫根目錄(而非 web/site/)進行部署,因為 Vercel 會從其專案設定(rootDirectory=web/site)解析根目錄。如果從 web/site/ 內部執行,路徑會雙層巢狀化。請始終固定使用最新的 CLI(npx vercel@latest)。

cd /path/to/repo/root
rm -rf web/site/.next kb/app/.next   # 清除過時的建置輸出;它們會導致上傳肥大
npx vercel@latest --prod --yes

不要使用 --archive=tgz(2026-06-26 在 CLI 54.x 版本上測量)。--archive=tgz 會將整個工作目錄樹打包成 tar 檔案,並繞過 .vercelignore,因此它會將 .git(幾乎包含所有內容)加上 kb/、.otbox/、web/site/.next-test/ 等一併上傳 — 這是一個約 3 GB / 1998 個檔案的上傳,耗時數分鐘,且曾經在建置機器上的「Extracting deployment files」階段掛起約 20 分鐘(我們實際遇到過的正式環境停滯問題)。相反地,在 vercel@latest 上預設的逐檔上傳路徑則:

  • 遵守 .vercelignore → 約 628 個檔案 / 約 40 MB,
  • 上傳時間約 2 秒,且從頭到尾達到 READY 狀態約需 60 秒,
  • 不會遇到當初為了規避而加入 --archive=tgz 的 Error: Upload aborted 錯誤(那個錯誤是 brew 41.x 版本的端點問題;vercel@latest 已經修復,所以這個變通方案現在弊大於利)。

如果未來某個 CLI 版本使得逐檔上傳路徑再次出現問題,而你必須退回使用 --archive=tgz,請預期會有一個約 3 GB 的壓縮檔以及一次耗時數分鐘(有時會停滯)的解壓縮過程 — 如果部署在解壓縮階段卡住,請重試部署。

從輸出中擷取部署 URL/id;你將在驗證報告中引用它。

提示:你可以先驗證 Vercel 預覽部署(省略 --prod),在提升到正式環境前,針對預覽 URL 執行階段 2。這樣可以完全避免在正式環境的郵件清單上執行電子郵件擷取測試。


階段 2 — 在正式環境中驗證(透過 Workflow / ultracode 進行的即時測試框架)

證明即時網站可以運作。這個階段是一個即時測試框架:你(規劃者)為本次部署設定執行的範圍,Workflow 工具(確定性執行環境)執行它,而短暫的瀏覽器工作程序各自依型別化的 schema 回傳結果。中間狀態存在於測試框架的變數中,而非你的上下文中,因此完整的矩陣可以在不塞滿你視窗的情況下執行。此技能明確選擇使用 Workflow 編排(ultracode)。

此測試框架已與此技能一起打包並凍結:verify-site-deploy.workflow.js。不要內聯貼上腳本;請直接執行該檔案。

要檢查的項目

  • 路由(每個都必須回傳 200 + 正確渲染、無控制台/網路錯誤): /, /explorer, /hub, /schema, /docs,以及一些深層頁面的抽查: /schema/0.6.0, /docs/getting-started/installation, /docs/cli/commands, /docs/schema/trace-record。
  • Viewport:桌面 1440x900 與行動裝置 390x844(iPhone 等級)。如果修正影響了主題,也要檢查淺色 + 深色模式。
  • 每個頁面:HTTP 200、主要內容可見、在該 viewport 下無版面溢出/裁切、控制台乾淨、無失敗的網路請求、導航正常。
  • 電子郵件擷取(其自己的代理,請參閱下方說明)。

電子郵件擷取驗證(請勿污染正式環境清單)

/api/waitlist 會寫入一個即時儲存服務,且沒有 DELETE 端點,因此請謹慎操作:

  • 真正的完整來回測試(執行一次,桌面環境):提交一個帶有標籤的地址,例如 deploy-verify-<timestamp>@opentraces.ai。預期會收到 HTTP 200 {ok:true} 且按鈕切換為成功狀態。使用管理員讀取(GET /api/waitlist + Authorization: Bearer $WAITLIST_ADMIN_TOKEN)確認資料已持續儲存,記錄前後的計數。然後清理它,從儲存服務中移除該行(Upstash ZREM),並重新讀取以確認計數已恢復。保持清單的原始狀態。
  • 重複路徑:提交相同的地址兩次,預期會看到「你已在清單上」的訊息,且計數不變。
  • 行動裝置 + 不寫入資料的重複 UI 檢查:在提交時填入隱藏的蜜罐陷阱(input[name=company])。端點會回傳一個無聲的假成功訊息,且永遠不會儲存該行,因此你可以在行動裝置上確認成功 UI 而不會產生垃圾資料。(如果你看到「成功」但計數沒有變動,那是蜜罐陷阱在正常運作,並非錯誤。)
  • 如果端點回傳 503(「waitlist is not configured」),則表示 KV 儲存服務在該部署上未正確連接:這是 BLOCKED 狀態(環境/儲存服務問題),而非程式碼修正。請回報此問題。

執行測試框架

使用 Workflow 工具呼叫打包好的工件。根據部署情況使用 args 設定其範圍(這是即時「規劃者」步驟):

Workflow({
  scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
  args: {
    baseUrl: "https://www.opentraces.ai",  // 正式主機;或預覽 URL 以避免將電子郵件寫入正式環境
    changed: ["/hub", "/"],             // 本次部署修改的路由 -> 深度檢查;其餘路由僅快速檢查
    pagesOnly: false                    // true = 跳過電子郵件寫入(僅執行唯讀驗證)
  }
})

它會回傳 { base, scoped, failures, allGreen }。allGreen: true 表示階段 2 通過;否則 failures 會列出階段 3 需要修正的項目。

測試框架如何應用即時原語(請參閱 kb/docs/concept-jit-harnesses-generic.md):

  • 分類與路由:如果你傳遞了 changed,那些路由會進行完整的瀏覽器檢查(控制台、溢出、螢幕截圖);其他所有路由則僅以快速的 curl 檢查狀態。由執行環境控制的純 JS 流程,模型中沒有接縫,因此範圍限定的部署可以保持低成本。
  • 每個 viewport 一個確定性掃描工作程序(2 個工作程序,而非約 18 個):每個工作程序在一個便宜的模型(haiku)上執行一個單一的固定 bash 批次(每個路由執行 curl + 一組有界的 agent-browser 呼叫),並回傳解析後的 JSON。沒有開放式的「驗證所有內容」提示,因此模型無法循環;每個批次只開啟一個瀏覽器 session 並執行 close --all 關閉它,因此 Chrome 處理程序不會堆積。(2026-06-09 驗證:完整深度 viewport 掃描約 16 秒,遺留 1 個處理程序,而原始基於每個儲存格的設計則有 54 個處理程序 / 15 分鐘以上。)
  • 獨立對抗性確認:任何被掃描工作程序標記為失敗的路由,都會由一個獨立的工作程序使用全新的 session(預設模型)重新檢查,嘗試重現該錯誤;只有當確認工作程序也失敗時,該失敗才會被視為存活,因此 agent-browser 的操作失誤不會偽裝成網站錯誤。
  • 型別化合約:每個工作程序都會根據 PAGE_VERDICT / EMAIL_VERDICT 回傳結果,因此結果可以機械性地合併。
  • 電子郵件擷取有自己的工作程序,透過獨立的管理員讀取證實寫入成功,並清理測試資料列(請參閱上述無污染規則)。

若要更改矩陣、深度策略或判決 schema,請編輯 .js 檔案,它是唯一的真實來源。如果變更只涉及一個頁面且你不想使用編排,你仍然可以在主 session 中使用 agent-browser 技能依序執行該頁面的檢查。


階段 3 — 分類與迭代

讀取 workflow 的 failures:

  • 空 -> 目標已達成。回報:部署 id/URL、驗證過的路由、viewports、電子郵件完整來回測試已驗證且已清理。完成 (DONE)。
  • 非空 -> 對於每個失敗,在 web/site/ 的來源碼中找到根本原因,修正它,然後回到階段 0(本地驗證 -> 提交 -> 推送 -> 部署 -> 重新驗證)。首先針對失敗的路由執行範圍限定的重新驗證,待它們都綠燈後再進行一次完整的全面檢查。
  • 在對同一個失敗進行 3 次不成功的嘗試後,或者遇到憑證/儲存服務/驗證阻礙時,請停止並以 BLOCKED 狀態回報,同時附上確切的錯誤資訊與你嘗試過的方法。

在執行記錄中記錄每次迭代,以便循環過程可供審計。


.vercelignore

位置很重要:生效的檔案是儲存庫根目錄下的 .vercelignore。 即使專案的根目錄是 web/site,整個儲存庫仍會被上傳(建置時會讀取 ../../src/opentraces/__init__.py 和 ../../skill/SKILL.md),而且逐檔上傳路徑只會遵循儲存庫根目錄下的 .vercelignore — 模式的比對是相對於儲存庫根目錄進行的。web/site/.vercelignore 會被忽略;請不要建立一個(2026-06-26 透過 npx vercel@latest --debug 驗證)。

這是一個正面排除清單(明確列舉目錄,而非使用帶有 ! 否定模式的 * 全部捕獲 — 否定模式很脆弱且會在不同 CLI 版本間失效)。沒有它的話,上傳內容會包含龐大的儲存庫資料樹。必須排除的大目錄(每個都是我們修正過的實際洩漏):

  • kb/ (~2.4 G), .claude/ (~1.5 G), tests/ (~1.4 G), .venv*/ (~0.8 G)
  • .otbox/ (~613 M 的快照 tar 檔)
  • web/site/.next-test/ (~98 M / 1000 多個檔案 — 注意 **/.next/ 不會匹配到 -test 後綴,因此 .next-test/ 需要自己的規則)
  • web/viewer/, web/coming-soon/, web/metrics-worker/

警告:.vercelignore 只會過濾逐檔上傳路徑。--archive=tgz 標誌會繞過它(參閱階段 1 — 這是另一個不使用它的原因)。

若要在編輯 .vercelignore 後檢查上傳內容是否合理,請從儲存庫根目錄執行 npx vercel@latest --debug,並讀取 Found N files … M required to upload 這行,然後按 Ctrl-C — 無需完整部署。一個健康的網站部署約有 628 個檔案,而非約 2000 個。

不得被忽略的檔案(在建置時會被讀取):

檔案被誰讀取用途
src/opentraces/__init__.pynext.config.ts為 version.json 進行版本偵測
skill/SKILL.mdlib/docs.ts (getSkillContent())文件頁面上的機器檢視內容

如果你新增了一個網站會在建置時透過相對路徑(例如 ../../foo)讀取的檔案,請確保它沒有被 .vercelignore 排除。

參考資料

路由(階段 2 矩陣):/, /explorer, /hub, /schema, /schema/[version], /docs, /docs/[[...slug]](來自 lib/doc-nav.ts 的約 36 個文件 slug)。API:/api/waitlist(POST 新增,GET 管理員讀取)、/api/stars。

電子郵件表單選擇器(EarlyAccessForm.tsx):電子郵件輸入框 input[type=email] / aria-label="email address" / .ea-input;提交按鈕 button.ea-btn(「get early access」 -> 載入中 -> 成功);隱藏的蜜罐陷阱 input[name=company](填入它 -> 無聲的假成功,永遠不會儲存)。

Waitlist 管理員讀取:GET /api/waitlist 附帶 Authorization: Bearer $WAITLIST_ADMIN_TOKEN。回傳一個包含 count、emails(物件陣列,每個物件有 id 和 email)的 JSON 物件。使用 count 來驗證寫入/刪除,使用 emails 來尋找並清理測試資料列(Upstash ZREM list emails {id})。

快取清除:Vercel 正式部署會使 CDN 邊緣快取失效。但是,如果一個靜態路徑(例如 /)在你定址一個動態路由(例如 /api/waitlist)時沒有更新,請考慮在 Vercel 專案儀表板中「清除 CDN 快取」,或者重新部署。不需要手動瀏覽器硬重新整理(那是代表使用者端的問題)。

相關技能