awwwards-section-loop

Awwwards 分区循环 — 逐个构建分区、逐个验证并锁定

一次性构建整页会带来问题：注意力分散在八个分区上，早期错误会悄然传递到后续所有分区，而且只有全部完成后才能收到反馈——这时再追溯偏差源自哪个决策已经太迟。分区循环能解决这三个问题：全神贯注于一个分区；每个分区都要先验证并锁定，再开始下一个；偏差会在发生之处被发现。

运行这个循环所需的工具已经存在。本技能规定了运行顺序，以及工具输出无法替你做出的判断。

**配置说明：**本技能使用的工具有 analyze_page_structure、 capture_component、analyze_stack、capture_pose_3d、 analyze_scroll_map、analyze_hover_census、audit_url、analyze_bundle、 build_gsap_stub，以及保留的 build_project / verify_build。以下示例使用 1.x 名称（默认值为 full）。在 AWWWARDS_MCP_PROFILE=v2 上，使用 inspect_page {request:{kind:"structure", url}}、 capture_page {request:{kind:"component", url}}、 inspect_page {request:{kind:"stack", url}}、 capture_page {request:{kind:"pose", url}}、 analyze_motion {request:{kind:"scroll", url}}、 analyze_motion {request:{kind:"hover", url}}、 audit_page {request:{kind:"performance", url, compact:true}}、 audit_page {request:{kind:"bundle", url}} 和 build_motion {request:{kind:"gsap_stub", scrollCensus}}；build_project 和 verify_build 仍使用扁平格式。传给 build_motion 的滚动普查结果需设置 compact:false。完整映射见：v2-routing.md。

循环

PLAN          analyze_page_structure(reference)   → band map = section plan
FOR EACH      capture_component(section selector) → section pack (recipe)
              build that section                  → in your output, fully
              gate that section                   → geometry + screenshots + checks
              iterate until every check passes    → then LOCK it
NEXT SECTION  (do not touch locked sections again)
FINALLY       whole-page verify_build             → aggregate + coherence pass

步骤 0 — 根据分区映射规划

首先调用 analyze_stack（一次调用）：获取网站的框架、CSS 框架和 标记库。Webflow 或 WordPress 源码意味着要沿用其约定并重新设计； Next 源码则意味着可以仿照组件结构。然后， analyze_page_structure 会返回有序分区及其 top、height、 bg 和文本速览。将分区列表作为构建顺序：

• 数量较少，高度合理（每个分区 ≤ ~3,000 px）→ 分区与构建分区一一对应。
• 一个超大分区（5,000 px+）→ 这个分区合并了多个实际分区（重复的 <section class="…"> 同级元素就会造成这种情况）。不要把它构建成一个超大组件。 转而查看原始页面 HTML，为实际分区选择明确的选择器 （.section、[role=…]、header、footer 或 #id），每个逻辑分区选一个。 实际捕获案例：一个 20,631 px 的分区包含了整个主要内容区域；其中四个实际分区 按类名捕获都正常。
• 跨越多个分区的共享画布 / WebGL 主视觉区 → **页面不能切分。**将该画布区域视为一个整体： 使用 capture_pose_3d 捕获画布帧并合成摄像机指引，将其重建为单个组件， 然后再按正常流程处理后续所有内容。对于 Three.js 场景， 使用 capture_scene_3d 并设置 adapters:["three"]，只添加可访问的节点／摄像机／灯光； build_scene_stub 会重建受支持的基础图元子集和精确捕获的摄像机矩阵，但父级变换会丢失， 控件也不会重建。对于着色器证据，adapters:["spector"] 会捕获一个绘制帧，其中包含命令计数和受限的着色器源码——不包含 参数、状态或原始捕获数据。将共享画布页面切分为逐分区捕获，会导致每个分区都引用一个并不属于它的画布。

步骤 1 — 按分区捕获

按分区顺序，在每个分区调用 capture_component(selector)。选择器 应遵循以下优先级（根据实际捕获经验总结）：

1. 从分区或 HTML 中获取 section 类名或 id（.process、.pricing、 .footer）——最可靠。
2. role 属性（[role="banner"]、[role="contentinfo"]）。
3. 标签名（header、footer、nav）——最后手段：实际网站 经常根本没有 <header> 元素（某个 Webflow 网站的实际捕获返回了 selector not found: header，但 nav 和 .footer 均可用）。

如果选择器未能匹配，请先尝试其他选项，再缩减计划。 捕获失败并提示 selector not found，说明是选择器问题，而不是 分区缺失。

步骤 2 — 完整构建一个分区

根据该分区的采集包构建：布局参考采集包中的几何信息，设计令牌（字体／颜色／间距） 参考捕获到的计算样式，动效参考该分区范围内的人口统计（analyze_scroll_map

• analyze_hover_census，遵循 awwwards-motion-study）。内容由你决定—— 你要匹配的是结构、动效和设计令牌。

把它做完。 未完成的分区会影响下一次验证。在准备锁定的分区内， 不要留下“以后再做”的占位区块。

步骤 3 — 根据捕获结果验收分区

不要指望 verify_build 为单个分区给出结论。它会比较两张 完整页面，并返回一个聚合分区分数—— bands: { score, matched, refOnly, buildOnly }——而不是每个分区的分数。 它无法单独评估第 N 个分区，而且每完成一个分区就运行一次，大多只是在衡量 尚未构建的分区。

使用第 N 个分区自身的证据来验收：

• 几何信息： 分区映射（analyze_page_structure）提供该分区的 offsetTop、height 和 background；分区采集包 （capture_component）提供根节点和子节点的 rect（x、y、w、h） 以及计算样式。在你的构建版本中测量相同节点（Playwright getBoundingClientRect / evaluate），并在容差范围内断言—— 例如，分区高度误差 ±2%，子节点位置和列数必须完全一致。这可以发现整页平均值 会掩盖的高度变为 3 倍和分区塌缩等问题。
• 截图： 在相同视口下捕获参考分区和你的构建版本，并将画面固定在分区中心， 然后并排比较。按页面比例均匀截取会落在过渡中间，无法说明任何问题。
• 设计令牌和动效： 检查捕获到的计算样式（字体、颜色、间距），以及用于构建的 分区范围内人口统计值（触发条件、时长、缓动、错开）。
• 明确检查项： 在开始构建前，写下该分区的通过条件（高度容差、列数、可见子节点、 动效节拍），然后逐项标记通过／失败。“看起来差不多”不算验收标准。

只有所有局部检查均通过后，才锁定第 N 个分区。完成几个分区后以及最后， 使用 verify_build 获取聚合证据：其 bands.score 显示整页相似度， matched / refOnly / buildOnly 列出匹配或缺失的分区标签；动效分数、 perf: 行（fps=… dropped=… longTasks=…）和 anti-patterns: 数量则是页面级证据。 如果性能数据显示丢帧，通常是动效开销过大所致——例如过渡动画使用 filter: blur、 无限循环，或动画改变布局属性。应修复问题本身，而不是分数。聚合分数再好，也不能 证明第 N 个分区在局部达标；局部通过，也不能证明整页协调一致。

为什么分区验收很重要： 没有验收标准的逐分区构建，不过是分段猜测。 逐分区检查几何信息和截图，可以将“看起来差不多”转化为明确的数值以及每个分区的 通过／未通过结论；随后 verify_build 提供页面级分数，而不会假装能定位问题。

第 4 步——锁定后再继续

锁定 = 本节的标记、样式和动效均已冻结。如果后续章节发现了确实需要修改已锁定章节的问题，必须明确重新开启：修复、重新运行该节的关卡检查，再次锁定。构建其他章节时，绝不能暗中修改已锁定的章节。

第 5 步——最终一致性检查

最后一节锁定后：运行整页 verify_build，作为汇总证据检查——查看 bands.score、matched / refOnly / buildOnly、动效评分、性能和反模式行。它不会报告各带区的评分；使用各节的几何信息和截图，定位汇总比较标记出的章节。还要运行一次 analyze_page_structure，并设置 compare: "mobile"：mobileBands + diff（bandsAdded、bandsRemoved、reordered、heightDelta）会指出仅在 390×844 下存在或顺序发生变化的章节——仅针对桌面端重建的问题会在移动端冒烟测试前在这里显现。现在要检查逐节循环无法发现的跨章节问题：共享间距节奏、一致的页眉行为、滚动连贯性，以及各章节采用同一套缓动体系（或有意打破这一体系）。在页面层级（令牌、共享 CSS）修复一致性问题；除非汇总带区比较显示回归，否则不要重新开启章节——如果出现回归，使用其中的 refOnly / buildOnly 标签和你自己的几何信息定位章节。

第 6 步——仅在用户要求时转换

单文件重建是有效的交付成果。用户要求提供项目（或选择框架）时，再进行转换：已锁定的章节正是 build_project --target vite|astro|next 所需的内容——带区拆分将转化为组件。如果用户还想要手工编写动效，添加 --authored --motion census.json，并按章节编写（参见 motion-authoring），同时遵循相同的锁定纪律：编写第 N 节，重新运行该节的关卡检查，锁定，再继续下一节。最后确保桌面端整页与 390 像素移动端一致。

此技能可防止的失败模式

失败	你会看到的情况	防止该问题的规则
将巨大且折叠的带区作为一个组件构建	一个包含 6 种子布局的“章节”，效果都平平	第 0 步：明确拆分选择器
将选择器未命中视为章节缺失	重建时跳过整个区域	第 1 步：备选方案阶梯
切分共享画布页面	各章节都需要一个无人渲染的画布	第 0 步：单元规则
在“完成”的章节中遗留占位内容	章节关卡检查始终无法通过	第 2 步：完成规则
漂移在页面中不断累积	每个章节都比上一个稍差	第 3–4 步：关卡检查 + 锁定
锁定后暗中修改	已锁定章节悄然退化	第 4 步：明确重新开启
各节彼此格格不入	页面看起来像拼接起来的截图	第 5 步：一致性检查

配套工具

• awwwards-motion-study — 每个分区的动效方案（记录 → 清点 → 构建 → 重新记录）。
• verify_build — 汇总证据（步骤 3 和 5），不是每个分区的 门槛：一个整页评分（bands.score + matched/refOnly/ buildOnly 标签）和一个动效评分，以及实测性能（fps、丢帧、 长任务）和来自检测探针的反模式计数。 运行真实浏览器——每次调用预计约 2 分钟。对于共享 WebGL 画布， 可选择启用 scene3d，在构建画布上重放一个 capture_scene_3d 数据包，将其作为单独门槛，并给出自己的 状态/判定；它不会提升旧版分区检查结果，不稳定的捕获帧会被拒绝， 且其构建 URL 必须可公开访问（拒绝回环地址）。它会在旧版扫描前 预检两个 URL，只要其中任意一个为私有地址，就不会发出任何请求； 截止时间为重放的检查点等待时间 + 10 秒余量（下限 15 秒，上限 45 秒），画布还会获得一个每次运行独有的标记，以拒绝重复或预先 标记的伪造对象。
• audit_url compact:true — 仅需摘要而非完整证据时，用于快速检查性能和反模式。
• capture_pose_3d - 共享画布单元的画布帧 + 合成的摄像机指引（步骤 0）；不会还原摄像机变换，生成的存根会对相同索引的帧加载去重，并丢弃过时的解码结果。
• capture_scene_3d + build_scene_stub - 适用于共享画布的可选 Three.js 适配器：仅使用可访问的全局对象，包括基本图元、标准/基础材质，以及根据其精确矩阵重建的透视摄像机。 不会重新创建捕获到的控件，它们仍处于未解析状态。模块局部场景、父级变换和未绑定纹理会丢失，且 scene.json 的帧引用是从 Windows 或 POSIX 路径中提取的基本文件名。
• capture_scene_3d spector 适配器 - 可选的 [email protected]；捕获一帧 WebGL 内容，包含命令计数/状态和经过截断的着色器源代码。需要有绘制帧，不会传输参数/状态/原始捕获内容；若缺少此软件包，仅会导致适配器功能降级。
• analyze_scroll_map / analyze_hover_census - 用于构建的逐分区动效清点结果。analyze_scroll_map 的行现在包含关键帧值对和站点级 gsapTriggers 列表（数值型像素起始/结束位置、实时进度、补间变量）——根据测量值构建， 不要凭空编造。悬停样本包含悬停期间捕获的动画（activeAnims），这样才能检测到事件驱动的补间动画。
• build_gsap_stub - 将捕获的清点结果转换为可运行的 GSAP+ScrollTrigger 存根（时长、缓动、scrub/pin、来自 capture_pose_3d 的合成摄像机指引、减少动态效果保护）——自动生成步骤 2 的动效连接代码。
• build_project — 构建 → 转换 → 自行实现动效：--target vite|astro|next 提供原生结构（分区组件、外壳、拆分后的 CSS、有序的库）； --authored --motion census.json 会移除站点逻辑，并生成 motion.manifest.json + 每个分区/页面的动效钩子，供编写代码时参考（搭配 motion-authoring）；转换后务必重新验证。
• analyze_bundle - 机制还原（步骤 2 的备用方案）：如果无法根据清点证据解释某个分区的效果，就在该分区站点的脚本包中搜索机制关键词；清点结果说明动画是什么，脚本包则说明动画如何实现。