AgentBuild: 30个AI代理在观众面前构建页面
进入页面特效：页面的每个区块都隐藏在线框之后，一群带名字的光标飞来，拖拽选择框并“构建”出该区块。仅使用 DOM 和 CSS transition（无 canvas，无库），30个光标的资源消耗几乎为零。
assets/ 中的文件：
| 文件 | 使用场景 |
|---|---|
agent-build.js | 核心。可通过 <script> 使用（创建 window.AgentBuild）或通过打包工具 import（CommonJS）。 |
agent-build.css | 必选，与核心配套。通过 --ab-* 变量更改颜色。 |
agent-build.d.ts | 核心的 TypeScript 类型定义。 |
AgentBuild.tsx | React/Next 包装器（客户端组件）。 |
demo.html | 可直接在浏览器中打开的示例页面。 |
如何集成
常规 HTML 网页
- 将
agent-build.js和agent-build.css复制到项目中。 - 在
<head>中引入 CSS，在</body>之前引入脚本，然后在 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} edits", building: "Building page", done: "Page built", skip: "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
这是决定效果好坏的关键。
- 选择有意义的区块：标题、段落、按钮、卡片、图片。不要选择包裹整个部分的
div，因为巨大的线框看起来像是个 bug。 - 按优先级顺序列出。位于已选中元素内部的元素会被自动忽略。例如，如果选择了
.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 秒后标记“已运行”，因此第二次挂载仍会正常运行。