AI Website Cloner Template 学习教程

一、环境准备

前置知识

学习 AI Website Cloner Template 需要以下基础：

安装步骤

1. 确保 Node.js 环境

# 检查 Node.js 版本（需要 24+）
node -v

# 使用 nvm 安装
nvm install 24
nvm use 24

2. 克隆模板

# 克隆到你的项目目录
git clone https://github.com/JCodesMore/ai-website-cloner-template.git my-clone
cd my-clone

# 安装依赖
npm install

3. 验证基础构建

# 确认项目能构建
npm run build

# 启动开发服务器
npm run dev

4. 配置 AI Agent

Claude Code（推荐）:

# 启动 Claude Code（带 Chrome 浏览器集成）
claude --chrome

其他 Agent: 项目已内置 14 个平台的配置文件，直接启动对应 Agent 即可。

环境验证

# 在 Claude Code 中测试
claude --chrome

# 输入
> /clone-website https://example.com

# 如果看到侦察阶段开始执行，说明环境配置成功

二、快速开始

Hello World

第一步: 启动 AI Agent

cd my-clone
claude --chrome

第二步: 运行克隆命令

> /clone-website https://stripe.com

AI Agent 会自动执行完整的五阶段流水线。

第三步: 观察执行过程

Phase 1: 侦察
├── 截图保存到 docs/design-references/
├── 提取字体、颜色保存到 docs/research/
├── 执行滚动/点击/悬停/响应式扫描
└── 生成 PAGE_TOPOLOGY.md 和 BEHAVIORS.md

Phase 2: 基础构建
├── 更新 src/app/layout.tsx（字体）
├── 更新 src/app/globals.css（颜色令牌）
├── 提取 SVG 图标到 src/components/icons.tsx
└── 下载资产到 public/images/

Phase 3: 组件规格
└── 为每个页面部分生成规格文件到 docs/research/components/

Phase 4: 并行构建
├── Builder Agent 1 → Hero Section
├── Builder Agent 2 → Features Section
├── Builder Agent 3 → Pricing Section
└── Builder Agent N → ...

Phase 5: 组装 & QA
├── 合并所有 Worktree
└── 视觉对比验证

第四步: 查看结果

# 启动开发服务器查看结果
npm run dev

# 查看生成的文件
ls docs/research/components/
ls src/components/
ls public/images/

多网站克隆

# 一次克隆多个网站
> /clone-website https://stripe.com https://linear.app

# 每个网站的产出隔离在独立目录
# docs/research/stripe.com/
# docs/research/linear.app/

三、核心概念

概念图谱

AI Website Cloner 核心概念
├── 五阶段流水线
│   ├── 侦察 (Reconnaissance) — 截图 + 全局提取 + 交互扫描
│   ├── 基础构建 (Foundation) — 字体 + 颜色 + 类型 + 图标 + 资产
│   ├── 组件规格 (Component Specs) — 每个组件的详细规格文件
│   ├── 并行构建 (Parallel Build) — Worktree + Builder Agent
│   └── 组装 QA (Assembly) — 合并 + 视觉对比
│
├── 设计令牌提取
│   ├── 颜色 — getComputedStyle() 精确值
│   ├── 字体 — family + weight + style
│   ├── 间距 — 比例尺识别
│   ├── 排版 — h1-h6 + body + caption
│   ├── 圆角 — border-radius
│   └── 阴影 — box-shadow
│
├── 交互行为提取
│   ├── 滚动扫描 — 触发器 + 前后状态 + 过渡
│   ├── 点击扫描 — 点击行为 + 内容变化
│   ├── 悬停扫描 — 颜色/缩放/阴影变化
│   └── 响应式扫描 — 1440px/768px/390px
│
├── 并行构建
│   ├── Git Worktree 隔离
│   ├── Builder Agent（每个组件一个）
│   ├── 规格文件作为契约
│   └── 原子编译验证
│
├── 核心原则
│   ├── 完整性优于速度
│   ├── 小任务完美结果（~150 行规格上限）
│   ├── 真实内容和资产
│   ├── 基础先行
│   ├── 提取外观和行为
│   ├── 识别交互模型
│   ├── 提取所有状态
│   ├── 规格文件是真相来源
│   └── 构建必须编译
│
└── 多平台支持
    ├── AGENTS.md（真相来源）
    ├── SKILL.md（技能定义）
    └── 同步脚本（14 个平台）

核心概念详解

1. 交互模型识别

克隆中最昂贵的错误：把滚动驱动的 UI 当作点击驱动来构建。

如何判断交互模型:

步骤 1: 不要先点击！先缓慢滚动
  └── 如果元素随滚动自动变化 → 滚动驱动
       └── 提取: IntersectionObserver / scroll-snap / sticky / animation-timeline
  └── 如果滚动无变化 → 进入步骤 2

步骤 2: 点击/悬停测试
  └── 记录每个交互行为和对应的内容变化

步骤 3: 在规格文件中明确标注
  └── "INTERACTION MODEL: scroll-driven with IntersectionObserver"
  └── 或 "INTERACTION MODEL: click-to-switch with opacity transition"

2. 多状态提取

很多组件有多个视觉状态，必须全部提取：

标签/有状态内容: - 点击每个标签/按钮 - 提取每个状态的内容、图片、卡片数据 - 记录内容属于哪个状态 - 记录状态间过渡动画

滚动依赖元素: - 捕获滚动位置 0 的样式（初始状态） - 滚动过触发阈值后再次捕获（滚动状态） - 对比两套 CSS 找出变化属性 - 记录过渡 CSS（时长、缓动、属性）

3. 规格文件（组件契约）

每个组件在构建前必须有规格文件：

# docs/research/components/hero-section.md

## Component: HeroSection

### 截图参考
[附上该区域的截图]

### 交互模型
INTERACTION MODEL: static（无交互）

### 布局
- 外层容器: max-width 1440px, padding 80px 24px
- 内容区: flex, flex-col, items-center, gap 24px
- 标题: font-size 64px, font-weight 700, line-height 1.1
- 副标题: font-size 20px, font-weight 400, color #6b7280
- CTA 按钮: bg #7c3aed, text white, rounded-lg, px 8, py 4

### 资产
- 背景图: public/images/hero-bg.webp (1920x1080)
- Logo SVG: src/components/icons.tsx → LogoIcon

### 响应式
- 768px: 标题 48px, 布局不变
- 390px: 标题 32px, padding 40px 16px, 按钮全宽

### TypeScript 类型
interface HeroSectionProps {
  title: string;
  subtitle: string;
  ctaText: string;
  ctaHref: string;
  backgroundImage: string;
}

4. 复杂度预算规则

如果 Builder Prompt 超过 ~150 行规格内容 → 组件太复杂 → 拆分

示例:
"构建整个 Features 区域" → 太复杂 ❌

拆分为:
├── Builder A → Features 区域容器 + 布局
├── Builder B → Feature Card 变体 1（带图标）
└── Builder C → Feature Card 变体 2（带图片）

术语表

四、功能详解

4.1 侦察阶段详解

侦察是整个流水线最关键的阶段：

截图采集

自动采集:
├── 全页桌面截图 (1440px) → docs/design-references/desktop-full.png
├── 全页手机截图 (390px)  → docs/design-references/mobile-full.png
└── 后续每个组件还会采集区域截图

全局提取

// 通过浏览器 MCP 提取的颜色
const colors = {
  background: getComputedStyle(body).backgroundColor,
  primary: getComputedStyle(primaryBtn).backgroundColor,
  text: getComputedStyle(h1).color,
  // ...映射到 shadcn 令牌
};

// 提取的字体
const fonts = {
  heading: 'Inter, sans-serif',
  body: 'Inter, sans-serif',
  mono: 'JetBrains Mono, monospace'
};

强制交互扫描

四种扫描覆盖所有交互：

页面拓扑

# docs/research/PAGE_TOPOLOGY.md

1. Navbar (fixed, z-50) — 滚动后背景变化
2. Hero Section (static) — 无交互
3. Features Grid (static) — 3 列 → 1 列响应式
4. Pricing Cards (click-driven) — 月/年切换
5. Testimonials (time-driven) — 自动轮播
6. CTA Banner (static) — 无交互
7. Footer (static) — 多列布局

4.2 基础构建详解

基础构建是顺序执行的（不能并行），因为后续所有 Builder 都依赖它：

// 更新 layout.tsx 字体
import { Inter } from 'next/font/google';
const inter = Inter({ subsets: ['latin'] });

// 更新 globals.css 设计令牌
:root {
  --background: oklch(1 0 0);
  --primary: oklch(0.702 0.183 293.541);
  --secondary: oklch(0.968 0.007 264.542);
  // ...
}

// 提取 SVG 图标
// src/components/icons.tsx
export function SearchIcon(props: SVGProps<SVGSVGElement>) {
  return <svg {...props}>...</svg>;
}

4.3 资产下载

自动生成并执行下载脚本：

// scripts/download-assets.mjs
const assets = [
  { url: 'https://target.com/images/hero.jpg', dest: 'public/images/hero.jpg' },
  { url: 'https://target.com/images/logo.svg', dest: 'public/images/logo.svg' },
  // ...
];

4.4 并行构建详解

主 Agent（Foreman 角色）
│
├── 发现 Hero Section → 写规格文件 → 派发 Builder A
│   └── Builder A 在 worktree-1 中工作
│       └── 完成: src/components/hero-section.tsx
│
├── 发现 Features Section → 写规格文件 → 派发 Builder B
│   └── Builder B 在 worktree-2 中工作
│       └── 完成: src/components/features-grid.tsx
│       └── 完成: src/components/feature-card.tsx
│
├── 发现 Pricing Section → 写规格文件 → 派发 Builder C
│   └── Builder C 在 worktree-3 中工作
│       └── 完成: src/components/pricing-section.tsx
│
└── 所有 Builder 完成
    └── 合并 worktree
    └── 验证 npm run build

4.5 多平台同步

修改两个真相来源文件后，运行同步脚本：

# 修改 AGENTS.md 后
bash scripts/sync-agent-rules.sh

# 修改 SKILL.md 后
node scripts/sync-skills.mjs

同步脚本自动为每个平台生成特定配置： - .claude/ → Claude Code - .cursor/ → Cursor - .windsurf/ → Windsurf - .gemini/ → Gemini CLI - .codex/ → Codex CLI - .cline/ → Cline - 等等...

4.6 Docker 部署

# 生产模式
docker compose up app --build
# → http://localhost:3000

# 开发模式（热重载）
docker compose up dev --build
# → http://localhost:3001

五、CLI 完整参考

命令

# 开发
npm run dev          # 启动开发服务器

# 构建
npm run build        # 生产构建

# 检查
npm run lint         # ESLint 检查
npm run typecheck    # TypeScript 类型检查
npm run check        # 完整检查（lint + typecheck + build）

# 同步
bash scripts/sync-agent-rules.sh  # 同步平台指令
node scripts/sync-skills.mjs      # 同步克隆技能

# Docker
docker compose up app --build     # 生产
docker compose up dev --build     # 开发

AI Agent 命令

# 克隆网站（核心命令）
/clone-website <url1> [<url2> ...]

# 从规格文件构建
/build-from-spec

# 定制化修改
/customize

常用工作流

工作流 1: 完整克隆
1. git clone ... && cd my-clone && npm install  设置项目
2. claude --chrome                               启动 Agent
3. /clone-website https://target.com             克隆
4. npm run dev                                   预览
5. 根据需要修改定制                               定制

工作流 2: 多网站克隆
1. /clone-website https://a.com https://b.com    并行克隆
2. 每个网站的产出隔离在 docs/research/<hostname>/

工作流 3: 存量项目集成
1. 将模板的 docs/ 和 scripts/ 复制到现有项目
2. 调整 AGENTS.md 中的技术栈配置
3. 运行 /clone-website

工作流 4: 自定义技能
1. 编辑 .claude/skills/clone-website/SKILL.md    修改技能
2. node scripts/sync-skills.mjs                  同步到所有平台

六、进阶主题

6.1 自定义克隆行为

可以通过修改 SKILL.md 调整克隆行为：

## Scope Defaults
- **Fidelity level:** Pixel-perfect  → 改为 "Close match" 降低精度
- **In scope:** Visual layout...    → 添加 "Dark mode variant"
- **Out of scope:** Real backend... → 移除 "SEO optimization" 以包含 SEO

6.2 添加新的设计令牌

在 src/app/globals.css 中添加自定义令牌：

:root {
  /* shadcn 默认令牌 */
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);

  /* 自定义令牌 */
  --accent-gradient: linear-gradient(135deg, #7c3aed, #2563eb);
  --card-glow: 0 0 20px rgba(124, 58, 237, 0.15);
}

6.3 处理复杂交互

平滑滚动库（Lenis）:

# 如果目标网站使用 Lenis
npm install lenis

// src/hooks/use-smooth-scroll.ts
import Lenis from 'lenis';

export function useSmoothScroll() {
  useEffect(() => {
    const lenis = new Lenis({ duration: 1.2 });
    function raf(time: number) {
      lenis.raf(time);
      requestAnimationFrame(raf);
    }
    requestAnimationFrame(raf);
    return () => lenis.destroy();
  }, []);
}

滚动驱动动画:

// 使用 IntersectionObserver 实现入场动画
'use client';
import { useEffect, useRef } from 'react';

export function useScrollReveal() {
  const ref = useRef<HTMLDivElement>(null);
  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          entry.target.classList.add('revealed');
        }
      },
      { threshold: 0.1 }
    );
    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);
  return ref;
}

6.4 优化 Token 消耗

并行 Builder Agent 消耗大量 Token，优化策略：

6.5 检查产出质量

# 查看生成的规格文件
ls docs/research/components/
cat docs/research/BEHAVIORS.md
cat docs/research/PAGE_TOPOLOGY.md

# 验证构建
npm run check

# 视觉对比（手动）
# 在浏览器中打开克隆结果和原网站对比

6.6 使用其他 AI Agent

# Cursor
cursor .

# Windsurf
windsurf .

# Gemini CLI
gemini

# Codex CLI
codex

# 每个平台会自动读取对应的配置文件

七、常见问题

Q1: 必须使用 Claude Code 吗？

不必须。项目支持 14 个 AI 编码 Agent。但 Claude Code + Opus 4.6 是推荐组合，效果最好。其他 Agent 也能工作，但精确度可能有差异。

Q2: 为什么需要浏览器 MCP？

浏览器 MCP（Chrome MCP / Playwright MCP 等）是核心依赖。没有浏览器自动化，就无法提取精确的 CSS 值、执行交互扫描、下载资产。这是项目"像素级精确"的基础。

Q3: 能克隆 JavaScript 渲染的网站吗？

能。通过浏览器 MCP 访问的是完全渲染后的 DOM，包括 JavaScript 动态生成的内容。这是比静态截图工具（如 screenshot-to-code）的重要优势。

Q4: 克隆一个网站需要多长时间？

取决于目标网站的复杂度： - 简单单页: 5-15 分钟 - 中等复杂度: 15-30 分钟 - 复杂多页: 30-60 分钟 - 多个网站（并行）: 与最复杂的那个相当

Q5: Token 消耗大吗？

比较大。并行 Builder + 详细规格生成 + 多次浏览器 MCP 调用。建议使用 Anthropic API 按 Token 计费，避免使用固定价格的订阅。

Q6: 克隆的代码能直接部署吗？

能。生成的代码是标准的 Next.js 项目，可以直接部署到 Vercel 或其他平台。但需要注意： - 只包含前端代码 - 表单、认证等后端功能需要自己实现 - 使用的是目标网站的真实资产，上线前需要替换

Q7: 如何处理目标网站的自定义字体？

项目会自动检测目标网站的字体来源： - Google Fonts → 使用 next/font/google 加载 - 自托管字体 → 下载到 public/fonts/ 并使用 next/font/local - 系统字体 → 直接在 CSS 中使用

Q8: 多人团队如何使用？

• 模板本身是 Git 仓库，可以 Fork
• 每个开发者克隆不同的目标网站
• 通过 Git PR 合并各自的克隆结果
• 规格文件（docs/research/）可以团队共享和审查

八、参考资料

官方资源

• GitHub 仓库: https://github.com/JCodesMore/ai-website-cloner-template
• YouTube Demo: https://youtu.be/O669pVZ_qr0
• Discord 社区: https://discord.gg/hrTSX5yTpB

相关技术

• Next.js 16: https://nextjs.org
• shadcn/ui: https://ui.shadcn.com
• Tailwind CSS v4: https://tailwindcss.com
• Chrome MCP: Chrome DevTools Protocol 集成
• Claude Code: https://docs.anthropic.com/en/docs/claude-code

竞品参考

• screenshot-to-code: https://github.com/abi/screenshot-to-code
• v0 (Vercel): https://v0.dev
• bolt.new: https://bolt.new
• websim.ai: https://websim.ai

学习路线图

第1天: 基础入门
├── 克隆模板并安装依赖
├── 配置 Claude Code + Chrome MCP
├── 尝试克隆一个简单网站
└── 理解五阶段流水线

第2-3天: 核心概念
├── 理解设计令牌提取
├── 学习交互行为提取（四种扫描）
├── 理解组件规格文件
└── 掌握并行 Builder Agent 机制

第4-5天: 进阶实践
├── 克隆复杂交互网站
├── 学习多 URL 克隆
├── 理解 Worktree 并行构建
└── 定制克隆行为

第6-7天: 扩展集成
├── 使用其他 AI Agent（Cursor/Windsurf 等）
├── Docker 部署
├── 自定义技能和平台同步
└── 建立完整的网站克隆工作流