引言

“指向一个 URL，运行 /clone-website，AI Agent 会检查网站、提取设计 Token 和资源、写组件规格，然后派遣并行 Builder 重建每一个区块。”

这是"每日一个开源项目"系列的第144篇文章。今天的主角是 ai-website-cloner-template——一个用 AI 编程 Agent 把任意网站逆向成 Next.js 代码库的 GitHub 模板仓库。

把"网站截图"变成"可运行代码"是一个经典的 Vibe Coding 场景，但大多数实现都浅尝辄止：让 LLM 看一张截图、近似还原布局、用占位符代替真实内容。这个模板的思路截然不同：它设计了一套严格的多阶段 Agent 工作流，核心原则是"完整性优于速度"——每一个 Builder Agent 在动手之前，必须拿到精确的 getComputedStyle() 值、真实下载的资源文件、完整的交互状态规格。

22k Stars 说明这个方向有真实需求，但更值得关注的是它的工程设计——特别是用 git worktree 实现真正的 Agent 并行构建。

你将学到什么

• 五阶段克隆流水线：侦察 → 基础建设 → 组件规格 → 并行构建 → 汇总 QA
• git worktree 并行 Agent 模式：每个 Builder Agent 在独立分支上工作的完整流程
• 组件规格文件的设计原则：为什么规格文件是"合同"而非"参考"
• 交互模型识别：区分点击驱动、滚动驱动、时间驱动的关键步骤
• 跨平台 Agent 支持：13 种 AI 编程工具的适配方式（单一源文件 → 自动同步）

前置知识

• 使用过 Claude Code 或 Cursor 等 AI 编程工具
• 了解 Next.js 的基本概念
• 了解 git 分支的基本操作

---

项目背景

项目简介

ai-website-cloner-template 是一个 GitHub 模板仓库（is_template: true），预置了 Next.js 16 + shadcn/ui + Tailwind v4 的项目脚手架，以及一个名为 /clone-website 的 AI Agent Skill（技能）。

使用方式：在 GitHub 上用"Use this template"创建自己的仓库，启动 AI Agent，执行 /clone-website <目标URL>，Agent 自动完成从侦察到出码的整个流程。

项目的核心工程贡献不是技术栈选择，而是那套 /clone-website Skill 背后的多 Agent 协作规范——特别是用 git worktree 实现真正并行的组件构建，以及强制要求"先写规格、再派 Builder"的流程约束。

作者/团队介绍

• 作者: JCodesMore
• 主要语言: TypeScript
• License: MIT
• 社区: Discord（1400896964597383279）

项目数据

• ⭐ GitHub Stars: 22,100+
• 🍴 Forks: 3,173+（大量用于创建独立项目）
• 📄 License: MIT
• 📅 创建时间: 2026-03-13

---

主要功能

核心作用

传统"截图克隆"方式：
截图 → 让 LLM 近似还原 → 占位符内容 → 手动修正颜色/间距 → 反复迭代

ai-website-cloner-template 方式：
/clone-website https://example.com
    ↓
阶段1 侦察：截图 + 滚动/点击/悬停交互扫描 + 提取设计 Token
    ↓
阶段2 基础建设：更新字体/颜色/globals.css + 下载所有资源 + 提取 SVG 图标
    ↓
阶段3 组件规格：逐区块写 spec 文件（精确 CSS 值 + 真实内容 + 交互状态）
    ↓
阶段4 并行构建：git worktree 为每个区块开独立分支 + 派 Builder Agent 并行工作
    ↓
阶段5 汇总 QA：合并所有 worktree + 接线 + npm run build 验证

使用场景

1. 平台迁移：把自己运营的 WordPress/Webflow/Squarespace 网站重建为 Next.js 代码库，获得完整的代码控制权
2. 源码丢失：网站在线运行，但仓库没了、开发者离开了、或者技术栈太老——用 AI 从线上版本找回代码
3. 学习参考：通过逆向真实生产网站理解特定布局、动画、响应式行为的实现方式（拿到真正可运行的代码而不只是截图）

不适用场景

README 明确列出：

• 钓鱼或仿冒：用于欺骗性目的、冒充他人、或任何违法行为
• 侵权：Logo、品牌资源、原创文案属于原作者所有
• 违反 ToS：部分网站明确禁止抓取或复制——使用前自行确认

快速开始

1. 创建自己的仓库

在 GitHub 项目页面点击 Use this template → Create a new repository（不要直接 clone 模板仓库）。

2. 克隆并安装

git clone https://github.com/YOUR-USERNAME/YOUR-NEW-REPO.git
cd YOUR-NEW-REPO
npm install

3. 启动 Claude Code（推荐）

claude --chrome   # --chrome 启动 Chrome MCP，用于浏览器自动化

4. 执行克隆技能

/clone-website https://target-website.com

支持多 URL 并行处理：

/clone-website https://site1.com https://site2.com

5. 开发预览

npm run dev        # 启动开发服务器
npm run check      # 运行 lint + typecheck + build

支持的 AI Agent 平台

Agent	状态
Claude Code	推荐（Opus 4.7）
Codex CLI	支持
OpenCode	支持
GitHub Copilot	支持
Cursor	支持
Windsurf	支持
Gemini CLI	支持
Cline	支持
Roo Code	支持
Continue	支持
Amazon Q	支持
Augment Code	支持
Aider	支持

跨平台支持的实现方式：AGENTS.md 是单一真相来源，执行 bash scripts/sync-agent-rules.sh 自动为所有平台生成各自格式的指令文件（CLAUDE.md、GEMINI.md、.cursor/、.windsurf/ 等）。

---

项目详细剖析

五阶段流水线

阶段 1：侦察（Reconnaissance）

这不只是截图。侦察阶段要完成三个强制任务：

截图：在 1440px（桌面）和 390px（移动端）两个视口各取一张全页截图，存入 docs/design-references/，作为整个流程的视觉基准。

强制交互扫描（最容易被忽略的步骤）：

滚动扫描：从头到尾慢速滚动，记录：
  - 导航栏在什么滚动位置改变外观？
  - 哪些元素滚入视口时有动画？
  - 哪些区块有 scroll-snap？
  - 是否有 Lenis/Locomotive Scroll 等平滑滚动库？

点击扫描：点击每个看起来可交互的元素：
  - 每个 Tab/Pill 切换显示哪些内容？
  - 哪里弹出 Modal？哪里展开 Dropdown？

悬停扫描：悬停每个可能有 hover 状态的元素：
  - 颜色变化、缩放、阴影、透明度…

响应式扫描：在 1440px / 768px / 390px 三个视口验证，记录布局变化点

所有发现存入 docs/research/BEHAVIORS.md——这是整个克隆过程的"行为圣经"。

页面拓扑图：从上到下列出页面所有区块，记录每个区块的交互模型（静态/点击驱动/滚动驱动/时间驱动），存为 docs/research/PAGE_TOPOLOGY.md。

阶段 2：基础建设（Foundation Build）

由 Orchestrator Agent 亲自完成，不派给子 Agent：

1. 更新 src/app/layout.tsx：配置目标网站的真实字体（next/font/google 或 next/font/local）
2. 更新 src/app/globals.css：把目标网站的颜色 Token（背景、前景、主色、静音色…）映射到 shadcn 变量系统，用 oklch 色彩空间
3. 提取所有 SVG 图标 → 保存为命名 React 组件存入 src/components/icons.tsx
4. 执行资源下载脚本（scripts/download-assets.mjs）：批量下载页面上所有图片、视频到 public/
5. 验证：npm run build 通过

资源发现用浏览器 MCP 执行 JavaScript，精确枚举所有 <img>、<video>、CSS background-image，包括绝对定位的叠加层（一个看起来像单图片的区块往往是背景图 + 前景 UI 截图 + 悬浮图标的多层叠加，遗漏任何一层都会让克隆版本看起来是空的）。

阶段 3：组件规格（Component Specs）

每个区块构建之前，必须先写规格文件（docs/research/components/<name>.md）。规格文件是 Builder Agent 的"合同"，包含：

• 该区块的视口截图（本地路径）
• 用 getComputedStyle() 提取的精确 CSS 值（不是目测估算）
• 下载后的资源文件路径（本地 public/ 路径，不是原始 URL）
• 真实文字内容（从 element.textContent 提取，不是占位符）
• 所有交互状态（Tab 切换时每个状态的内容、滚动前后的 CSS 差异、过渡动画参数）
• 响应式断点行为

CSS 提取脚本（通过浏览器 MCP 执行）：

// 对每个组件容器执行
(function(selector) {
  const el = document.querySelector(selector);
  const computed = getComputedStyle(el);
  const props = [
    'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing',
    'color','backgroundColor','background',
    'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
    'margin','borderRadius','boxShadow','display','flexDirection',
    'gap','alignItems','justifyContent','position','zIndex',
    // ... 完整属性列表
  ];
  return Object.fromEntries(props.map(p => [p, computed[p]]));
})(selector)

复杂度预算规则：如果一个区块的规格文件超过约 150 行，说明太复杂，需要拆分。这是机械性检查，不允许用"但它们是相关的"来绕过。

阶段 4：并行构建（Parallel Build via git worktrees）

这是最关键的设计——用 git worktree 为每个 Builder Agent 创建独立的工作分支：

# Orchestrator 为每个区块创建 worktree
git worktree add .worktrees/hero-section feature/hero-section
git worktree add .worktrees/features-grid feature/features-grid
git worktree add .worktrees/pricing-section feature/pricing-section
# ...以此类推

# 每个 worktree 里派一个 Builder Agent 工作
# Builder 接收完整的规格文件内容作为 prompt 的一部分
# Builder 完成后验证 npx tsc --noEmit 通过

每个 Builder Agent 的"工作包"包含：

• 规格文件的完整内容（inline 进 prompt，不是路径引用）
• 区块截图路径
• 已下载资源的本地路径
• 全局样式系统（字体变量、颜色 Token）

Builder Agent 不需要读其他区块的代码，不需要理解整体页面结构，只需要根据规格文件实现这一个组件，并确保 TypeScript 编译通过。

阶段 5：汇总 QA（Assembly & QA）

# Orchestrator 把所有 worktree 分支合并回主分支
git merge feature/hero-section feature/features-grid feature/pricing-section ...
# 解决合并冲突（Orchestrator 有全局上下文，可以合理处理）

# 在 src/app/page.tsx 里按正确顺序组装所有区块组件

# 最终验证
npm run build    # 必须通过，没有任何妥协

交互模型识别：最贵的错误

SKILL 文件花了大篇幅强调这一点，原因是：把点击驱动的 UI 建成滚动驱动（或反之）意味着完全重写，而不是 CSS 调整。

识别方法：

1. 先不要点击。慢速滚动，观察是否有元素自动变化
2. 如果有 → 滚动驱动。提取机制（IntersectionObserver / scroll-snap / sticky / animation-timeline / JS 滚动监听）
3. 如果没有 → 再测试点击/悬停驱动
4. 在规格文件里明确标注：INTERACTION MODEL: scroll-driven with IntersectionObserver 或 INTERACTION MODEL: click-to-switch with opacity transition

项目结构

src/
  app/              # Next.js 路由
  components/
    ui/             # shadcn/ui 原语组件
    icons.tsx       # 从目标网站提取的 SVG 图标（React 组件）
  lib/utils.ts      # cn() 工具函数
  types/            # TypeScript 接口
  hooks/            # 自定义 React Hooks
public/
  images/           # 从目标网站下载的图片
  videos/           # 从目标网站下载的视频
  seo/              # favicon、OG 图、webmanifest
docs/
  research/         # 提取输出：组件规格、行为文档、拓扑图
  design-references/ # 截图（桌面 + 移动端）
scripts/
  sync-agent-rules.sh  # 同步 AGENTS.md 到各平台格式
  sync-skills.mjs      # 同步 /clone-website 到各平台
AGENTS.md           # Agent 指令的单一真相来源
CLAUDE.md           # Claude Code 配置（导入 AGENTS.md）
GEMINI.md           # Gemini CLI 配置（导入 AGENTS.md）

---

项目地址与资源

官方资源

• 🌟 GitHub: JCodesMore/ai-website-cloner-template
• 🎬 Demo 视频: YouTube（项目 README 内链接）
• 💬 Discord: discord.gg/hrTSX5yTpB

---

总结

ai-website-cloner-template 的价值不在于技术栈选型（Next.js + shadcn + Tailwind 是常规选择），而在于那套经过思考的多 Agent 协作规范。

几个值得记住的设计决定：

“完整性优于速度”：Builder Agent 必须拿到完整的规格才能开工，中间没有猜测环节。这个约束让结果更可靠，代价是侦察阶段更慢——作者认为这个权衡是对的。

复杂度预算（150 行规格 = 拆分信号）：用一个机械性规则控制每个 Builder 任务的范围，而不是让 Orchestrator 凭感觉判断。这是工程纪律，不是灵感。

git worktree 并行：每个 Builder Agent 在独立分支工作，Orchestrator 最后合并。并行不只是"同时跑多个任务"，而是有明确的隔离边界和合并策略。

单一源文件 + 同步脚本：AGENTS.md 是所有 Agent 平台指令的单一来源，修改一次，脚本自动同步到 13 个平台的格式。这是跨平台工具链设计的一个值得借鉴的模式。

---

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。