cloning-websites-to-weaverse

将网站克隆到 Weaverse

概述

使用此项目专属工作流，将参考网站转换为易于维护的 Weaverse 页面。重点优化可复用区块、准确匹配区块以及清晰的架构边界，而不是一次性的截图克隆。

源文件是 Figma 文件？ 请改用 figma-to-weaverse。它会将 Firecrawl 抓取替换为 Figma MCP，并添加 Figma 专属步骤；下文的区块匹配、清单和预览规则仍然适用。

优先级顺序： 在视觉冲突时，品牌指南优先于源网站。源网站决定页面结构、内容流、交互模式和商品展示逻辑。

冲突规则

.guides/brand-guideline.md 是权威依据。

如果线上网站与品牌指南冲突，MUST 遵循品牌指南。 此规则为强制要求，即使：

• 利益相关方表示 make it look like the live site
• 管理层会对比截图
• 线上网站看起来更新或更精致

请遵循以下规则：

1. 在没有冲突的地方匹配源网站。
2. 在存在冲突的地方遵循品牌指南。
3. 如果不确定，默认遵循品牌指南。

如遇冲突，请明确说明：我会尽可能匹配线上网站，但在存在冲突的决策中，以品牌指南为权威依据。

适用场景

• 将营销页面、首页或品牌中心克隆到此项目中
• 在 app/sections/ 和 Weaverse 中重建线上页面
• 在现有区块、新区块、app/styles/app.css 和 app/weaverse/schema.server.ts 之间做出选择
• 将参考网站的区块系统映射到此项目中已注册的 Weaverse 组件

请勿将此流程用于仅修改少量文案或修复独立错误。

必需输入

• 要迁移的参考 URL 或源网站
• .guides/brand-guideline.md
• sections.md
• app/weaverse/components.ts

必需输出

• 克隆预览路由：单个 Hydrogen 路由（app/routes/clone-preview.$page.tsx），使用 React + Tailwind 渲染完整的克隆页面——开始拆分区块前，用户必须先批准此路由
• 设计规范：区块映射、交互模型、架构边界、实现方向
• 内容清单：按区块列出真实资源 URL、文本内容、链接目标、Shopify 引用和媒体类型的表格——所有内容均来自 Firecrawl 抓取结果

克隆预览路由是验证检查点。设计规范与内容清单共同构成传递给 generating-weaverse-project-json 的完整交接资料。

权威依据

需求	来源
颜色、字体、徽标、形状语言、法律规则	.guides/brand-guideline.md
区块顺序、内容层级、CTA 流程、商品展示	抓取的参考网站
现有可复用区块匹配项和子区块约束	sections.md
当前可用 Weaverse 组件的注册表	app/weaverse/components.ts
共享设计令牌和跨区块重复样式	app/styles/app.css
全站可编辑控件	app/weaverse/schema.server.ts
区块本地内容和控件	app/sections/* 中的区块 schema

工作流

1. 首先阅读 .guides/brand-guideline.md。

2. 在进行版块匹配之前，确保 sections.md 存在且内容可信。

3. 使用 Firecrawl 抓取源页面，在单次调用中同时获取 markdown 和 HTML 格式：

   firecrawl scrape "<url>" --format markdown,html -o .firecrawl/<site>-<page>.json
   

   这样会在一次请求中同时返回整洁的 markdown（用于提取内容）和原始 HTML（用于分析布局与媒体）。对于包含 JS 渲染内容的页面，请添加 --wait-for 3000。

4. 如果页面链接到会影响版块系统的辅助子页面，也请一并抓取：

   firecrawl crawl "<url>" --include-paths <relevant-paths> --limit 10 --max-depth 1 --wait -o .firecrawl/<site>-crawl.json
   

5. 根据 markdown + HTML 输出提取源页面的 DNA：

   • 设计令牌：颜色、字体排版、间距、边框圆角、容器宽度
   • 页面结构：版块顺序、重复模式、CTA 流程、商品展示流程
   • 内容资源：标题、文案块、图片、视频、产品／系列模块
   • 媒体来源：从 HTML 中提取 <video>、<source>、<iframe>、<embed> URL（参见 Firecrawl Rules → 媒体来源提取）

6. 构建内容清单（参见下文的内容清单部分）。这是必需的交付内容；没有它，设计规范就不完整。

7. 生成克隆预览路由（参见下文的克隆预览路由部分）。将抓取的页面转换为 app/routes/clone-preview.$page.tsx 中的单个 Hydrogen 路由，使用 React + Tailwind 渲染整个页面。这是一个文件，所有视觉区块都需内联渲染，不得创建单独的组件文件。包含适用于桌面端和移动端的响应式样式。该路由必须在视觉上忠实于源页面，同时使用仓库的 Tailwind 配置，并在与源页面冲突时应用品牌指南中的令牌。使用清晰的注释标记各个版块（例如 {/* === HERO === */}、{/* === PRODUCT GRID === */}），这些标记之后将作为版块拆分的边界。

8. 用户审批检查点——在此处停止并等待。 向用户提供：

   • 预览 URL（例如：http://localhost:3456/clone-preview/<page-slug>）
   • 克隆页面覆盖内容的摘要（版块数量、关键视觉区块，以及已知缺失内容或应用的品牌指南覆盖项）
   • 明确说明：“请在上方 URL 查看克隆预览。确认它与源页面相符后，请回复 ‘approved’ 或 ‘proceed to sections’ 以继续。如果有问题，请描述需要修改的内容。”

   在用户明确确认审批之前，不得继续执行第 9 步。

   如果用户要求修改：

   • 更新预览路由
   • 再次提供 URL 并请求审批
   • 重复此流程，直到获得批准

9. 将源页面拆分为按区块划分的内容。对每个区块进行分类：

   • 主要媒体类型：static-image、video、animation、product-media、collection-image 或 external-embed。
   • 排版构成：文本与媒体的关系——background-overlay（文本叠加在铺满区域的媒体上）、side-by-side（文本与媒体分列显示）、stacked（文本位于媒体上方或下方）、card-grid（重复卡片，每张卡片含图片和文本）、card-slider（轮播中一次显示一张卡片）。
   • 布局机制：single-full-bleed、split-columns、grid、slider/carousel、overflow-rail、flex-wrap、marquee/ticker。
   • 交互方式：static、autoplay-carousel、snap-scroll、arrow-navigation、fade-transition、auto-scroll-marquee。 这些分类依据原始 HTML输出确定——查找滑块组件（Swiper、Flickity、Slick、自定义 <slider-component>、data-slider）、网格类、弹性布局模式、<video> 元素以及绝对定位的文本叠加层。

10. 按照 sections.md 中定义的布局匹配优先级，逐个区块进行对比：

11. 优先匹配排版构成（叠加 vs. 并排 vs. 堆叠 vs. 卡片网格 vs. 卡片滑块）

12. 其次匹配布局机制（铺满区域 vs. 滑块 vs. 网格 vs. 横向轨道 vs. 分栏）

13. 再匹配交互方式（静态 vs. 轮播 vs. 滚动）

14. 最后匹配内容模型（商品、系列、手动内容） 然后分类为： - REUSE_EXISTING - ADAPT_EXISTING - CREATE_NEW_REUSABLE_SECTION 如果源区块的排版构成、布局机制或媒体类型与候选区块不匹配，就必须解决这种不匹配——改选其他区块，或标明需要适配。在完整搜索整个区块注册表、寻找更合适的匹配项之前，绝不能将布局不匹配视为一种“权衡”。 深度结构验证（每个 REUSE 或 ADAPT 分类都必须执行）： 将区块分类后，阅读候选区块的源代码（app/sections/<section>/index.tsx 及其子文件），并验证其 schema 设置能否生成源区块要求的精确视觉效果。检查： - 宽高比枚举——schema 是否包含源区块使用的比例（例如 9:16、3:2），还是比例已硬编码？ - 响应式图片支持——区块是否接受单独的移动端／桌面端图片，还是仅有一个图片字段？ - 分栏比例——图片／文本比例能否匹配源区块（例如 75/25），还是最大宽度上限较低？ - 子区块类型——区块是否接受源区块所需的子区块（例如按钮、徽章、倒计时器）？ - 动画／交互能力——区块是否支持源区块使用的跑马灯、视差或过渡效果？ - 文本可读性辅助——对于文字叠加在图片上的布局，区块是否支持背景渐变、叠加层或文字阴影？ 如果缺少任何 schema 能力，请从 REUSE_EXISTING 重新分类为 ADAPT_EXISTING，并记录具体差距。如果缺少多项能力，请考虑改为 CREATE_NEW_REUSABLE_SECTION。

15. 仅当现有区块系统无法支持目标结构或数据模型，且不采用别扭的妥协方案时，才创建新区块。

16. 使用清晰的 schema 边界进行实现：

    • 全局共享令牌 -> app/styles/app.css
    • 全站可编辑控件 -> app/weaverse/schema.server.ts
    • 区块本地内容和控件 -> 区块 schema

17. 在 app/weaverse/components.ts 中注册每个新区块。

18. 从落地页扩展到子页面之前，先验证桌面端和移动端效果。

19. 清理预览路由：Weaverse 页面验证并正常运行后，清理预览路由。预览路由是临时产物——构建区块时将其作为并排参考，等最终由 Weaverse 渲染的页面与获批预览一致后将其移除。该路由通常通过 $page 提供多个页面：只移除已完成页面对应的分支及其数据；只有当其中不再有任何页面时，才删除 app/routes/clone-preview.$page.tsx（以及其在 app/routes.ts 中的条目）。

内容清单

内容清单是此技能与 generating-weaverse-project-json 之间的桥梁。没有它，JSON 生成器就会猜测内容，生成填满占位内容、与源页面不匹配的导出结果。

爬取并提取源页面的 DNA 后，在进行区块匹配之前，先按区块创建一份具体表格。清单必须涵盖源页面上的每个视觉区块。

必填列

列	说明
区块编号	页面上的顺序位置
区块名称	简短标签（例如“主视觉”“Netflix 推广”“连接 CTA”）
媒体类型	static-image、video、animation、product-media、collection-image 或 external-embed
图片／视频 URL	该区块的每个真实资源 URL，直接取自爬取结果。全部列出——主图、辅助图片、Logo 叠加层、背景图片。使用爬取结果中的完整 CDN URL。
文本内容	标题、副标题、正文文案、CTA 标签——与源内容完全一致
链接目标	该区块链接到的每个 URL（内部路径或外部 URL）
Shopify 引用	如果区块由产品或产品系列驱动，则填写产品 handle／ID 或产品系列 handle／ID
备注	任何特殊情况：外部嵌入、带外部链接的合作伙伴 Logo、视频自动播放等

规则

• 图片 URL 必须来自 Firecrawl 抓取输出（Markdown 格式），不要凭记忆填写或猜测。Markdown 输出会捕获 <img> 的 src 属性和可见图片 URL；请使用这些准确的值。
• 对于 video 或 external-embed 块，请在 Image/video URLs 列中填写从 HTML 格式输出中提取的实际视频源 URL（MP4、WebM、HLS、YouTube 嵌入等），不要填写海报或缩略图图片。如果缩略图也有用（例如作为备用），请用清晰的标签同时列出两者（Video (MP4): ...、Thumbnail: ...）。
• 如果一个块包含多张图片（例如，产品卡片同时包含生活方式主图和产品图片），请用标签列出所有图片。
• 如果抓取未返回可用的资源 URL，请将单元格标记为 MISSING — [describe what should be here]，以便 JSON 生成器将其标记出来，而不是悄悄替换成占位内容。
• 清单是此技能的必需交付物。设计规范（区段映射、架构边界、交互模型）与内容清单共同构成向 generating-weaverse-project-json 提交的完整交接内容。
• 如果同一概念（例如“Connect”）在页面上的多个位置以不同的视觉样式呈现，则必须在清单中分别列出每个实例，并在映射中分别建立区段块。

存储位置

将内容清单作为设计规范文件（例如 design.md）中的一个章节，或另存为同一规范文件夹中的 content-manifest.md。

克隆预览路由

克隆预览路由是抓取与区段拆解之间的验证检查点。它允许用户在开始任何 Weaverse 映射工作之前，以视觉方式确认克隆结果是否准确。

内容

一个 Hydrogen 路由文件 app/routes/clone-preview.$page.tsx，以 React + Tailwind 渲染整个克隆页面。它具有以下特点：

• 单个文件 — 所有视觉区块均内嵌，无需单独的组件文件
• 响应式 — 包含桌面和移动端布局，并匹配源页面的断点
• 区段标记 — 每个视觉区块都由注释标记分隔，以便后续拆解
• 品牌调整 — 当源页面与品牌指南冲突时，应用品牌规范标记（颜色、字体、Logo 用法）
• 临时文件 — 在构建区段期间保留为参考，Weaverse 页面验证通过后删除

路由结构

import type {MetaFunction} from '@remix-run/react';

export const meta: MetaFunction = () => {
  return [{title: 'Clone Preview — <page name>'}];
};

export default function ClonePreview() {
  return (
    <div className="clone-preview">
      {/* === HERO === */}
      <section className="relative w-full h-screen ...">
        {/* hero content */}
      </section>

      {/* === PRODUCT GRID === */}
      <section className="max-w-7xl mx-auto py-16 ...">
        {/* product grid content */}
      </section>

      {/* === NEWSLETTER CTA === */}
      <section className="bg-primary text-white py-12 ...">
        {/* CTA content */}
      </section>
    </div>
  );
}

规则

• 所有内容均以内容清单为准。 使用第 6 步中记录的准确资源 URL、文本和链接。不要使用占位图片或无意义文本——此预览的核心就是还原视觉效果。
• 使用仓库的 Tailwind 配置。 预览应使用仓库中提供的相同 Tailwind 类和自定义主题令牌。不要添加一次性 CSS 文件或内联 <style> 块。
• 应用品牌指南中的覆盖规则。 如果源网站的颜色、字体或徽标样式与 .guides/brand-guideline.md 冲突，预览必须采用品牌版本，而不是源网站版本。这样可以避免用户批准后又发生变化。
• 标记每个视觉区块。 使用 {/* === BLOCK NAME === */} 注释划分每个章节级区块。这些标记是第 9 步（章节分段）的拆分边界。区块名称应与内容清单中的“Block name”列一致。
• 在可行时加入交互行为。 如果源网站有轮播图，请实现基础的 Swiper 或滚动吸附版本。如果有视频自动播放，请加入带有 autoplay 的 <video> 标签。预览不需要完全复刻交互细节，但应展示核心行为，以便用户判断效果。
• 不要导入 Weaverse 组件。 此路由独立于 Weaverse 章节系统，使用纯 React + Tailwind。Weaverse 章节将在批准后处理。
• 每个路由参数对应一个页面。 如果要克隆多个页面，每个页面都应有自己的 $page slug（例如 /clone-preview/homepage、/clone-preview/about）。不要在一个路由中放置多个页面。

批准检查点

生成预览路由后，停止并等待用户确认：

1. 告知用户预览 URL 和访问方式
2. 总结预览内容：视觉区块数量、主要章节、已知缺漏以及已应用的品牌覆盖规则
3. 明确询问：“请检查克隆预览。满意后回复‘approved’或‘proceed to sections’。如需修正，请描述问题。”
4. 在用户明确批准之前，不要继续进行章节拆解（第 9 步）
5. 如果用户要求修改，请更新路由并重新提交审核

生命周期

阶段	预览路由状态
步骤 1-6（抓取 + 清单）	尚不存在
步骤 7（生成预览）	创建于 app/routes/clone-preview.$page.tsx
步骤 8（批准检查点）	用户审核，可要求迭代修改
步骤 9-14（章节拆解 + 构建）	保留为并排参考
步骤 15（清理）	Weaverse 页面验证通过后删除

Firecrawl 规则

• 使用 Firecrawl 抓取源网站，不要依赖截图或记忆。
• 单次抓取调用中始终同时请求 markdown 和 HTML 格式（--format markdown,html）。markdown 用于提取内容；HTML 用于布局分类和媒体来源提取。
• 对于落地页链接的辅助子页面，使用 Firecrawl crawl，并通过 --include-paths 将抓取范围限定为相关路径。
• 记录重复布局、导航模式、CTA 位置和内容层级。
• 将 Firecrawl 输出视为参考网站的结构来源，而非品牌令牌来源。
• 将输出保存到 .firecrawl/ 目录，并使用描述性名称（例如 .firecrawl/example-homepage.json）。

媒体来源提取

Markdown 输出会剥除 <video>、<source>、<iframe> 和 <embed> 元素。这些元素在 Markdown 中不可见，但包含关键的资源 URL。因此，两种格式都不可或缺。

从HTML 格式输出中提取：

• <video> 和 <source src="...">——MP4、WebM、HLS 流 URL
• <iframe src="...">——YouTube、Vimeo 或其他嵌入内容的 URL
• 媒体容器上的 data-src、data-video-url 或其他延迟加载属性

在 HTML 中搜索 .mp4、.webm、.m3u8、youtube.com/embed、vimeo.com、player. 等模式，查找 Markdown 输出遗漏的视频来源。

如果某个与章节对应的内容块在 HTML 中含有视频或嵌入内容，但在 Markdown 输出中只有图片（缩略图／海报图），则该内容块的主要媒体类型是 video 或 external-embed，而不是 static-image。在内容清单中记录实际的视频／嵌入 URL，而不是缩略图。

布局结构提取

此外，还要从HTML 格式输出中提取每个章节的布局结构：

• 滑块／轮播组件：查找 Swiper、Flickity、Slick 或自定义滑块元素（<slider-component>、data-slider、data-slider-fullwidth、data-dots、JSON 属性中的自动播放选项）。
• 网格模式：查找 CSS grid 类、列数变量（--COLUMNS）、响应式断点类。
• Flex／砖块布局：查找 brick__section、拆分宽度类（brick__block--three-quarters）、反转顺序类。
• 叠加布局与并排布局：查找媒体上方文本容器的绝对定位，以及分开的网格／Flex 列。
• 跑马灯／滚动条：查找 <ticker-bar>、跑马灯自动播放属性、连续滚动行为。

必须分析 HTML——不要只根据 Markdown 输出判断布局行为。对于含有滑块、叠加层或交互组件的页面，Markdown 输出不足以作为依据。

sections.md 规则

sections.md 是迁移指南，用于从本仓库中选择最合适的现有 Weaverse 章节。

其中必须列出已注册的 Weaverse 章节系统及子块，并说明：

• 用途
• 视觉结构
• 适用场景与不适用场景
• 有实际架构定义支持的选项
• 布局与数据约束

如果缺少 sections.md，请先创建该文件，再映射源站章节。

如果 sections.md 已过时或不完整，请先根据实际注册表和架构文件更新，再决定是否复用。

不要仅根据当前样式猜测章节的功能。请使用实际架构和组合约束。

迁移分析模型

按照 app/skill.md 中的分析顺序执行：

1. 原子分析与标记化

• 提取源站的设计标记和全局布局常量。
• 仅记录与迁移决策相关的内容：调色板的使用、排版行为、间距节奏、容器宽度、按钮样式、圆角样式。

2. 语义区块划分

• 将源页面拆分为逻辑清晰、可复用的区块。
• 对每个区块，识别布局、组件、内容类型和可能的数据源。
• 为每个区块划分主要媒体类型：static-image、video、animation、product-media、collection-image 或 external-embed。此分类决定匹配的区块能否直接支持该区块，还是需要调整。
• 为每个区块划分构图方式：background-overlay、side-by-side、stacked、card-grid 或 card-slider。根据 HTML 判断：查看文本是位于媒体上的绝对定位叠加层中、位于媒体旁的独立 flex/grid 列中，还是堆叠在媒体上方或下方。
• 为每个区块划分布局机制：single-full-bleed、split-columns、grid、slider/carousel、overflow-rail、flex-wrap 或 marquee/ticker。在 HTML 中查找滑块组件、grid CSS、flex 模式和滚动容器。
• 为每个区块划分交互方式：static、autoplay-carousel、snap-scroll、arrow-navigation、fade-transition 或 auto-scroll-marquee。查找 autoplay 属性、导航箭头/圆点和 scroll-snap CSS。
• 如果页面上同一概念多次出现，且视觉呈现方式不同（例如，网格中的“Connect”中心卡片，以及之后的全宽“Connect” CTA 横幅），则将每次出现分别视为独立的区块。

3. 智能架构匹配

• 将每个源区块与 sections.md 进行比较。
• 按照 sections.md 中定义的布局匹配优先级进行匹配：
  1. 先看构图方式——区块的构图方式字段是否匹配？background-overlay 区块不得匹配到 side-by-side 区块。
  2. 再看布局机制——区块是否采用相同的布局类型？slider/carousel 区块不得匹配到 grid 区块。
  3. 接着看交互方式——区块是否支持所需交互？autoplay-carousel 区块需要基于 Swiper 的区块，而非静态网格。
  4. 最后看内容模型——区块是否支持相应的数据类型（产品、合集、手动）？
• 如果结构、内容模型和约束均已匹配，优先复用。
• 如果区块契合度较高，但需要扩展架构或样式，则选择调整。
• 只有当前系统无法良好匹配时，才新建区块。
• 媒体类型门槛：如果源区块的主要媒体类型（来自第 2 步）不受匹配区块支持，则不得接受此不匹配并继续。应改为：
  1. 在 sections.md 和 app/weaverse/components.ts 中查找支持该区块媒体类型的其他区块（例如，如果区块类型为 video，则查找包含 videoURL、video 或 react-player 支持的区块）。
  2. 如果存在匹配区块，则改用该区块。
  3. 如果没有区块支持该媒体类型，则将其标记为需要调整，或作为新建/扩展区块的理由。
  4. 如果注册表中存在支持视频的区块，绝不能在不作说明的情况下将视频降级为静态图片。
• 布局门槛：如果源区块的构图方式或布局机制与候选区块不匹配，则不得接受此不匹配。应在注册表中查找布局行为匹配的区块。例如：
  • card-slider（一次显示一个项目，并带导航）必须匹配 slideshow，而非 product-spotlight-rail（网格）
  • background-overlay（全宽出血图片上的文本）必须匹配 hero-image 或 promotion-grid，而非 image-with-text（并排）
  • stacked 布局（图片在上、文本在下，居中）可能需要 columns-with-images 或富文本区块，而非 image-with-text（桌面端采用并排布局）

3b. 深入结构对比

通过架构匹配找到候选区块后，先阅读该区块的实际源代码（app/sections/<section>/index.tsx 和子文件），再接受匹配结果。根据原始区块的需求逐项核实：

检查项	核实内容
宽高比支持	架构是否提供宽高比选择器，且包含原始区块使用的比例？许多区块会将比例硬编码为单一值（例如 aspect-square）。
媒体类型匹配	仅支持图片的区块不能替代视频区块。检查是否支持 videoURL、<video> 或播放器组件。
响应式图片变体	如果原始区块使用 <picture>，并通过单独的 <source> 元素适配移动端和桌面端，那么单个 image 字段并不匹配。检查是否有 imageMobile、imageDesktop 或响应式断点逻辑。
分栏比例	检查架构中的宽度限制。如果原始区块使用 75/25 的图文分栏，但该区块将图片宽度限制为 60%，则需要进行适配。
子区块类型	确认该区块的 childTypes 或 inspector.children 是否允许原始区块所需的子区块（按钮、徽章、倒计时、评分星级等）。
动画 / 交互	静态区块无法实现跑马灯滚动、视差或自动切换过渡效果。检查是否支持动画属性、Swiper 配置或 CSS 动画。
文本可读性辅助功能	如果原始区块将文本置于图片上，并配有渐变背景或颜色叠层，则该区块必须支持 overlayColor、overlayOpacity 或等效功能。不支持叠层的纯图片区块并不匹配。

如果任何一项检查未通过，该区块就不能归类为 REUSE_EXISTING。应重新归类为 ADAPT_EXISTING，并记录具体差距；如果有多项检查未通过，则归类为 CREATE_NEW_REUSABLE_SECTION。

4. 组件合成与数据生成

• 对于复用的区块，将源内容映射到现有的 Weaverse 架构中。
• 对于新建区块，创建可复用的区块代码和架构，不要将整个页面克隆为一个专属组件。
• 内容清单（在工作流中构建）是所有内容字段的数据来源。不要凭记忆填充内容——应使用清单中的准确 URL、文本和链接。

决策规则

• 如果已有相同模式，且只需调整样式、内容或架构，则复用现有区块。
• 如果模式在视觉或结构上与众不同，且可能会重复使用，则创建新区块。
• 仅当样式属于共享基础组件时，才将其放入 app/styles/app.css：变量、字体钩子、重复使用的背景样式或可复用工具类。
• 仅当设置应可在整个店面中编辑时，才将其放入 app/weaverse/schema.server.ts。
• 将页面专属的间距、文案、行动号召和切换项放在相关区块架构中。
• 从落地页开始；先稳定基础区块系统，再克隆子页面。
• 尽可能匹配线上网站；如果品牌决策存在冲突，则以品牌指南为准。

仓库相关文件

• app/routes/clone-preview.$page.tsx（临时——预览检查点）
• app/sections/
• app/weaverse/components.ts
• app/styles/app.css
• app/weaverse/schema.server.ts
• sections.md

危险信号

• 当线上网站与 .guides/brand-guideline.md 冲突时，仍然照搬线上网站
• 为整个页面构建一个庞大的定制区块
• 将页面专属样式全部塞进 app/styles/app.css
• 将区块局部控件放入 app/weaverse/schema.server.ts
• 跳过 Firecrawl 抓取，仅凭截图进行映射
• 跳过 sections.md，凭猜测判断哪个区块最接近
• 在落地页基础框架尚未正常运行前，就开始制作所有子页面
• 以截图匹配为由覆盖品牌规范
• 跳过内容清单，交付不含具体资源 URL 的设计规范
• 当抓取结果中包含真实资源 URL 时，仍使用通用占位图片
• 将视频区块映射到仅支持图片的区块，却不指出媒体类型不匹配
• 将滑块/轮播映射到网格区块（例如，将全屏幻灯片映射到 product-spotlight-rail）
• 将全出血覆盖式主视觉映射到并排分栏区块（例如，将图片上方叠加文字的全宽主视觉映射到 image-with-text）
• 将纵向堆叠布局映射到并排分栏区块（例如，将图片居中置于文字上方的区块映射到 image-with-text）
• 将来源页面中彼此独立的区块合并为一个（例如，将仅含背景视频的主视觉与独立文字区块合并成一个带文字的主视觉区块）
• 跳过原始 HTML 抓取，仅依赖 Markdown 抓取结果进行布局分类
• 未阅读区块的 schema 源代码，就将区块归类为 REUSE_EXISTING——区块名称和 sections.md 摘要只描述用途，并未涵盖全部功能
• 假定仅支持图片的区块可以处理视频背景——检查是否支持 videoURL 或播放器组件
• 未指出来源页面中的动画元素被映射为静态区块——跑马灯、视差和自动轮播都需要特定的组件支持
• 跳过克隆预览路由——未生成预览并获得用户批准，就直接开始分解区块
• 未经用户明确确认，就越过审批节点继续操作——Agent 认为“看起来合理”，不能替代用户审查实际渲染页面
• 在预览路由中使用占位内容——预览必须使用内容清单中的真实资源 URL，而不是 lorem ipsum 或素材图片
• 忘记在预览中添加区块标记——缺少 {/* === BLOCK NAME === */} 注释，预览就无法作为分解区块时的拆分参考
• 将预览路由永久留在代码仓库中——它是临时产物，必须在 Weaverse 页面验证后删除
• 将仅适用于某种页面类型的区块映射到其他类型的页面——检查候选 schema 的 enabledOn（例如，collection-filters 仅适用于 COLLECTION 页面，并读取集合路由的 loader）。对于 CUSTOM 落地页，请使用或构建能够自行加载数据的区块。
• 对整个应用运行格式化工具——biome check --write app/ 会重新格式化无关文件，掩盖真正的差异。只格式化修改过的文件，并在提交前撤销仅由格式化造成的改动。
• 调整区块时更改其现有默认值——新增设置必须默认呈现当前效果；其他页面已经按旧 schema 保存了数据。

合理化检查

借口	实际情况
“领导会对比截图”	截图一致性不能凌驾于仓库的品牌规范之上。布局与源站匹配；设计令牌与品牌指南匹配。
“线上网站比指南更新”	除非仓库中的指导文档已更新，否则 .guides/brand-guideline.md 仍是实现的权威依据。
“我先照搬线上配色，之后再清理”	这通常会留下不当的全局样式。先设置正确的设计令牌，再据此设置各个区块的样式。
“我看 UI 就能判断哪个区块匹配”	视觉相似还不够。使用 sections.md 和实际的 schema 约束。检查构成、布局机制和交互方式——不要只看颜色。
“我只需要截图，不需要抓取网站”	凭截图记忆会遗漏层级、重复模块和链接页面的模式。先用 Firecrawl 抓取源站。
“我之后再补真实图片”	JSON 生成器无法找回你没有捕获的素材 URL。现在就根据抓取结果构建内容清单。
“这个区块只需要图片，视频可有可无”	如果源站区块使用视频，匹配的区块就必须支持视频，否则必须标记不匹配。不要悄悄降低媒体类型。
“概念相同，用一个区块就够了”	如果同一概念在页面上以两种不同的视觉样式呈现，就需要两个独立的区块。
“基本上就是网格，只是样式不同”	一次显示一个项目并带有箭头或圆点的滑块，绝不是“基本上就是网格”。在归类布局之前，检查 HTML 中是否有滑块组件。
“只要有图片和文字，image-with-text 就适用”	image-with-text 专指并排分栏布局。它不适用于全幅叠加、垂直堆叠布局或卡片网格。先匹配构成。
“源站的区块相邻，所以我可以合并”	如果源站有两个独立的 HTML 区块（例如背景视频和单独的富文本区块），就要将它们保留为两个独立的 Weaverse 区块。合并会改变布局行为。
“区块名称匹配，所以应该能用。”	区块名称描述的是用途，而非能力。请阅读 schema 源代码，确认每项视觉要求都受支持——包括宽高比、响应式图片、分栏宽度、子类型和动画支持。
“区块有图片字段，所以支持图片。”	有一个图片字段不代表支持响应式图片。如果源站使用响应式变体，请检查是否有独立的移动端／桌面端图片字段，或是否支持 <picture> 元素。
“预览看起来够接近了，我就跳过用户审批”	设置审批检查点，是因为 Agent 无法像人类一样判断视觉还原度。务必停下来等待明确确认。
“我完成区块映射后再生成预览”	预览必须先于区块分解。它的目的是在确定区块映射之前发现抓取错误、内容缺失和品牌冲突，以免映射基于错误假设。
“预览里用占位内容没关系，我之后再换成真实 URL”	预览用于检查还原度。占位内容会让预览失去意义——用户无法根据占位内容验证准确性。请使用内容清单中的真实 URL。

示例

利益相关方说：让它看起来和线上网站一样。

正确回应：我会尽可能匹配线上网站，但对于相互冲突的品牌决策，以 .guides/brand-guideline.md 为准。

常见错误

• Exact screenshot thinking -> 匹配结构和观感，但要确保实现可复用。
• Global junk drawer -> 如果某个部分专属一个区块，就将其保留在该区块中。
• Over-customizing old sections -> 如果改造起来很别扭，就创建一个干净的新区块。
• Skipping registration -> 必须将新区域添加到 app/weaverse/components.ts。
• Ignoring the registry -> 创建新区域前，请先查看 sections.md 和 app/weaverse/components.ts。
• Missing content manifest -> 如果没有按区域整理的清单，列出从抓取结果中获取的真实资源 URL、文本和链接，设计规范就不完整。缺少该清单时，JSON 生成器会填入占位内容。
• Media type blindness -> 将视频主视觉映射到仅支持图片的区域，或将动画区块映射到静态区域，却不标记其中的差异。
• Concept merging -> 将同一概念的两个视觉上不同的实例合并到一个区域区块中。
• Layout blindness -> 只按内容类型进行匹配，不检查构图（叠加、并排或堆叠）、布局机制（滑块、网格或全幅）和交互方式（静态、轮播或滚动）。这是导致区域渲染效果与原始页面完全不同的最常见原因。
• Section merging -> 将原页面中两个独立区域（例如，仅含背景的视频 + 独立的文本区块）合并为一个 Weaverse 区域，从而改变视觉层级。
• Skipping HTML analysis -> 仅根据 Markdown 抓取结果判断布局。Markdown 会剥离滑块组件、网格类、叠加定位和交互元素。准确判断布局必须查看原始 HTML。
• Name-matching without schema verification -> 名为 "hero-image" 的区域并不意味着它能复现所有主视觉布局。将其分类为 REUSE 前，请阅读区域源代码并核实架构设置（宽高比、响应式图片字段、叠加选项、子项类型）。
• Assuming aspect ratios are configurable -> 许多区域会将宽高比硬编码（例如 aspect-square）。不要想当然地认为区域可以生成原始页面所用的宽高比；请检查实际架构枚举值或 CSS 类。
• Ignoring responsive image requirements -> 如果原始页面使用 <picture>，并包含独立的移动端／桌面端 <source> 元素，那么只有单个 image 字段的区域就不匹配。该区域需要 imageMobile/imageDesktop 字段或等效字段。
• Skipping the preview checkpoint -> 克隆预览路由的存在是为了让用户能在开始拆分区域前发现问题。跳过预览意味着要等 Weaverse 映射工作完成很大一部分后才发现布局错误。
• Auto-approving the preview -> Agent 不得将自己的判断视为批准。只有用户明确回复（"approved"、"proceed" 等）后，才能开始拆分区域。
• Preview without section markers -> 忘记添加 {/* === BLOCK NAME === */} 注释，会导致预览无法同时用作拆分指南。务必添加这些注释。
• Zombie preview route -> 验证 Weaverse 页面后，忘记删除 app/routes/clone-preview.$page.tsx。它是临时文件，不是永久路由。