AgentBuild：30 個 AI 代理在觀眾眼前建構頁面
進站效果：頁面的每個區塊都隱藏在線框後方，一群有名字的游標飛入，拖曳選取框並「建構」出區塊內容。僅使用 DOM 和 CSS transition（無 Canvas、無函式庫），30 個游標幾乎不耗費資源。
assets/ 中的檔案：
| 檔案 | 用途時機 |
|---|---|
agent-build.js | 核心。透過 <script>（建立 window.AgentBuild）或經由 bundler import（CommonJS）使用。 |
agent-build.css | 必要，需與核心一同引入。透過 --ab-* 變數更改顏色。 |
agent-build.d.ts | 核心的 TypeScript 型別定義。 |
AgentBuild.tsx | React/Next（客戶端元件）的封裝版本。 |
demo.html | 可直接於瀏覽器開啟的範例頁面。 |
如何嵌入
一般 Web HTML
- 將
agent-build.js和agent-build.css複製到專案中。 - 在
<head>中引入 CSS，在<body>結尾處引入 script，然後在 DOM 內容載入後呼叫start：
<link rel="stylesheet" href="agent-build.css" />
<script src="agent-build.js"></script>
<script>
AgentBuild.start({
root: "main", // 要建構的區域；游標層會位於此區域內
targets: "main h1, main p, .card", // 區塊，依優先順序排列
seenKey: "home", // 每個頁面一個金鑰
labels: { status: "{agents} agent · {edits} 編輯中", building: "正在建構頁面", done: "建構完成", skip: "跳過" },
});
</script>
React / Next.js (App Router)
- 將
agent-build.js、agent-build.d.ts、AgentBuild.tsx複製到同一個目錄，例如src/components/agent-build/。 - 在通用樣式表中一次性引入
agent-build.css（@import "../components/agent-build/agent-build.css";）。 - 將元件放在需要建構區域的第一個子元素位置。元件會將父元素作為 root：
<div className="landing">
<AgentBuild targets=".landing h1, .landing p, .card" seenKey="landing" />
...
</div>
伺服端渲染的頁面仍可正常運作，因為元件僅在客戶端執行，並在 useLayoutEffect（首次繪製之前）中隱藏區塊，因此不會有內容閃爍的問題。
正確選擇 targets
這是決定效果美觀或雜亂的關鍵。
- 選擇有意義的區塊：標題、段落、按鈕、卡片、圖片。不要選擇包覆整個 section 的
div，因為一個巨大的線框看起來就像錯誤。 - 按優先順序列出。位於已選取區塊內的元素會自動被忽略。例如已選取
.card，則卡片內的p不會被單獨建構。若想同時建構整個卡片，請將.card放在p之前。 - 使用
skipInside: ".tagline"跳過已有獨立效果（如捲動動畫、Canvas）的區域。 - 開始時寬度或高度為零的元素會被忽略。
- 大約 30 到 140 個區塊效果最佳。
maxTargets預設值為 140。 - 如果專案中已有「隨捲動漸顯」的效果，請在代理運作期間將其關閉，否則兩種效果會疊加。例如：
[data-agent-build] .reveal { opacity: 1; transform: none; transition: none; }（data-agent-build屬性會在運作期間附加在 root 上）。
選項
| 選項 | 預設值 | 說明 |
|---|---|---|
root | document.body | 元素或選擇器。運作期間會被設為 position: relative。 |
targets | h1, h2, h3, p, img, figure, li, button, .card | 區塊列表。 |
count | 30（螢幕寬度小於 640px 時為 16） | 代理數量。 |
once / seenKey | true / "agent-build" | 每個分頁僅執行一次。 |
forceParam | "agents" | 在 URL 中加入 ?agents 可強制重新執行，方便錄製影片。 |
respectReducedMotion | true | 若使用者開啟減少動畫效果，則不執行。 |
pill | true | 顯示包含「跳過」按鈕的狀態列。 |
labels | 英文 | status（包含 {agents}、{edits}）、building、done、skip。 |
colors、roles | 8 種顏色、10 種角色 | 游標的顏色與名稱（layout-07）。 |
start() 會回傳 { skip(), destroy(), started }。destroy() 會將頁面還原為原始狀態。在離開頁面時（SPA）或元件卸載時呼叫。
使用 CSS 變數自訂外觀：--ab-wire（線框顏色）、--ab-pill-bg、--ab-pill-text、--ab-pill-muted、--ab-mono、--ab-ease。
以數字測試，無需頻繁截圖
使用 Playwright 開啟帶有 ?agents 的頁面，然後讀取：
({
cursors: document.querySelectorAll(".ab-cursor:not([data-hidden])").length, // 初始時約 30
waiting: document.querySelectorAll('[data-ab="wait"]').length, // 隨著捲動逐漸減少
on: !!document.querySelector("[data-agent-build]"), // 完成時為 false
})
使用 window.scrollTo 逐步捲動（如果頁面使用 Lenis 平滑捲動，請不要使用 mouse.wheel），等待數秒。正確結果：waiting 變為 0，on 變為 false。測試「跳過」按鈕：點擊 .ab-skip，之後不應存在任何 [data-ab]。僅在需要評估視覺效果時拍攝一張截圖。
已知問題
- 線框或游標位置偏移：root 未涵蓋所有區塊。請選擇包含所有
targets的元素作為 root。 fill圖片（Next/Image）覆蓋整個頁面：非本技巧的錯誤。fill圖片的父容器需要position: relative。- 效果未重新執行：已在分頁中執行過一次。請在 URL 中加入
?agents或開啟新分頁。 - React StrictMode（開發模式會執行兩次 effect）：核心會在 1.2 秒後才標記「已執行」，因此第二次掛載時仍會正常執行。