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

安安～我是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 與共同工程基線都能重播。

這張畫面目前只能回答「人類網站已經跑起來」。它沒有證明 Chrome 偵測到 WebMCP，也
沒有證明 Agent 呼叫過任何 Tool。事實上，今天本來就不該看見 Tool。

這個空白很重要。昨天那句自然語言可以找到活動，表示完成版中確實多了一層能力契約；
現在把它拿掉，人類介面仍然能工作。後面加入 WebMCP 時，我們才看得出自己是在原網站上
增加 Agent 能力，沒有偷偷另蓋一套只有 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 已通過。句號就停在這裡。
它不能往上膨脹成「瀏覽器已經看到 Tool」，更不能替 Agent invocation 簽收。測試全綠
當然值得高興，只是今天得獎的是工程基線，WebMCP 還在觀眾席。

最後看一次工作目錄：

git status --short

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

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

完成前面的操作後，開啟：

http://127.0.0.1:5173/events

今天只驗收這四件事：

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。我會用一般使用者身分走完搜尋、收藏、報名與取消，看看這個活動網站
到底替人完成哪些事情，又有哪些步驟不能因為自動化很方便，就一路幫人按到底。