Day 02｜換到全新資料夾後，網站還能不能跑？

本文同步自 2026 iThome 鐵人賽原文 。完整系列可見 iThome 系列頁 。

安安～我是ChiYu～

昨天才把完成版的 Agent trace 端上桌，今天我做的第一件事，卻是把它收起來。

我另外開了一個空資料夾，重新 git clone，沒有沿用原本的 node_modules，也不把環境裡 那些「反正我的電腦已經有」的東西算進專案。這個動作看起來很不像在追新技術，甚至有點像 才剛跑到終點，又自己走回起跑線。

但昨天那張成功畫面留下了一個更現實的問題：它是專案真的可以重現，還是只在作者電腦的 溫室裡活得特別健康？

Demo 最會做的事，就是在展示當下表現得像模範生。換一台電腦、少一個環境變數，或是 main 多了幾個 commit，它可能立刻裝作不認識你。讀者若連同一份網站都拿不到，後面再多 Inspector 截圖，也只是在參觀我的桌面。

所以今天不寫 WebMCP、不裝 Inspector，也不設定 Gemini API Key。我只處理一件事：把 「我這裡能跑」變成「你可以取得同一個版本，照著相同步驟再跑一次」。

可重播的基線，需要版本、環境與驗收結果

我把共同基線拆成三部分：程式停在哪個版本、需要什麼執行環境，以及跑完後應該看到什麼。 少掉任何一項，重播都可能變成猜謎。

圖 1：版本、執行環境與驗證結果缺一不可。今天使用的第一個程式 tag 是 v3-day-02。

版本座標回答「拿到哪一份程式」；環境座標回答「它在哪些條件下執行」；測試與 build 則 確認專案不是只有首頁剛好開得起來。這些事情都很基本，也正因如此，最容易在 Demo 趕著 往前衝時被省略。

用固定 tag 保留文章版本，不跟著 main 一起變動

正式動手前，先確認 Git、Node.js 與 npm。專案要求 Node.js 22.12.0 以上：

git --version
node --version
npm --version

接著取得公開專案，切到今天使用的固定 tag：

git clone https://github.com/eric861129/AgentReady-Events.git
Set-Location AgentReady-Events
git fetch --tags
git switch --detach v3-day-02
git rev-parse --short HEAD

最後一行預期得到 7aa4e64。v3-day-02 對應的 branch 是 day-02-reproducible-baseline。

為什麼不直接 clone 最新的 main？因為今天的 main 和十天後的 main，很可能已經不是 同一個網站。文章若只寫「請下載最新版」，後半段的讀者回來操作時，可能會拿到五支 Tool 都做完的版本，然後對著文章找一個早已消失的起點。

branch 適合繼續開發，tag 適合替文章釘住時間。這篇使用 annotated tag 當固定引用；只跟著 文章操作時，停在 detached HEAD 沒有問題。想自己修改，再從這裡開一條練習 branch：

git switch -c practice/day-02

不用修改作者保留的 Day branch，也別把 main 當成永遠不動的書籤。Git 已經很努力替我們 記錄歷史了，沒必要逼它假裝今天永遠是今天。

這些 refs 都已推送到公開 Repository。我在 2026-07-30 另外用全新資料夾做過匿名 clone， 切到相同的 v3-day-02，完成 47 個 Vitest 檔、138 項測試與 production build。這筆紀錄 只用來證明驗證沒有借用原本工作目錄的殘留狀態。

同時啟動 Web 與 API，不能只看首頁亮起來

專案有 package-lock.json，安裝時使用 npm ci：

npm ci
npx playwright install chromium
npm run dev

npm run dev 會同時啟動 Web 與 API：

/events 開得起來，不代表整個網站都醒了。前端由 Vite 提供，活動資料與 session 操作會 透過 /api proxy 到 3000。API 沒啟動時，頁面外框可能還好端端地站著，等到按下搜尋才 突然翻臉。

因此打開活動搜尋頁後，也要直接確認 http://127.0.0.1:3000/health/live。前端與 API 都有回應，這個基線才算完整。

npm ci 也不是我對 npm 的個人儀式感。它會依 lockfile 重建 node_modules，並在 package.json 與 package-lock.json 不一致時直接失敗。若這時改用 npm install <套件>@latest 硬闖，lockfile 可能跟著變動，讀者跑的便不是文章驗證過的 依賴樹。

本系列不要求全域安裝 Vite 或 Playwright。需要的版本都跟著專案走，否則「我電腦剛好有裝」 很快又會從後門溜回來。

圖 2：啟動成功後可由首頁進入活動搜尋、我的報名與 Labs。今天先確認 Web、API 與共同工程基線都能重播。

這張畫面目前只回答「人類網站已經跑起來」。今天還沒有 WebMCP Tool，也沒有 Agent invocation；這個空白是刻意保留的。後面加入 WebMCP 時，我們才看得出自己是在原網站上 增加能力，而不是另蓋一套只有 Demo 當天會用的流程。

npm test 與 npm run build 通過，只代表工程基線

網站開得起來後，再另開一個終端機：

npm test
npm run build

這次共有 47 個 Vitest 檔、138 項測試通過。npm run build 接著完成 TypeScript no-emit 檢查、Vite client build 與 esbuild server bundle。

兩個指令各管一件事。npm test 檢查既有規則、contract、API 與安全測試； npm run build 確認 production 產物真的生得出來。兩邊都綠，至少能排除「首頁剛好載入， 專案卻無法完整建置」這種很會挑場合出現的問題。

這層結果在系列內部歸為 E2：程式與 deterministic tests 已通過。它不能直接升級成 「Chrome 已經看見 Tool」，也不能替 Agent invocation 簽收。今天得獎的是工程基線， WebMCP 還在觀眾席。

最後確認工作目錄：

git status --short

全新 clone 完成安裝與驗證後，這裡應保持乾淨。若出現 package-lock.json、原始碼或測試檔 差異，先查是哪個指令改了它們。帶著一包沒有交代的修改往後走，之後做按鈕文案實驗時， 就很難確定誰才是唯一變因。

從空資料夾重跑一次，才知道專案不是只認作者電腦

完成前面的操作後，今天只驗收四件事：

1. 活動搜尋頁正常顯示。
2. 搜尋表單與活動資料可以讀取。
3. http://127.0.0.1:3000/health/live 回傳正常。
4. npm test 與 npm run build 都成功。

如果啟動失敗，不必先重裝整台電腦。從兩個最早的條件查起：

• 執行 Get-Location，確認目前位於含有 package.json 的專案根目錄。
• 確認 3000 與 5173 沒有被先前啟動的服務占用。

這兩項是排錯入口，不是預言每位讀者都會踩坑。環境正常時，照前面的流程跑完即可，不用 為了和文章一樣辛苦，特地先把 port 占滿。

到這裡，我們拿到的是一個固定 commit、可啟動、能測試，也能 build 的人類網站。沒有 Inspector、沒有 Gemini API Key，也沒有 WebMCP Tool。這反而讓昨天的成功多了一點可信度： 完成版是從同一個基線逐步長出去的。

不過網站能重播，還不代表我們知道該把哪些能力交給 Agent。看到搜尋欄、收藏按鈕和報名頁， 很容易順手把每顆按鈕都包成 Tool；那只是替 UI 元件取英文名字，還不算理解使用者任務。

明天先不碰 Agent。我會用一般使用者身分走完搜尋、收藏、報名與取消，確認網站原本替人 完成哪些事情，又有哪些步驟不能因為自動化方便，就一路幫人按到底。