AIWebsiteClonerTemplate - 完整学习教程

**教程级别：** 从零到一
**预计学习时间：** 4-6 小时
**前置知识：** 命令行基础（git、npm）、至少一种 AI 编码 Agent 的基本使用、Next.js 和 React 基础概念
**基于版本：** v0.3.1（2026-03-30 发布）

AIWebsiteClonerTemplate - 完整学习教程

教程级别： 从零到一 预计学习时间： 4-6 小时 前置知识： 命令行基础（git、npm）、至少一种 AI 编码 Agent 的基本使用、Next.js 和 React 基础概念 基于版本： v0.3.1（2026-03-30 发布）

环境搭建指南

系统要求

操作系统： macOS、Linux 或 Windows（WSL2 推荐）
Node.js： 24.0 或更高版本
Git： 2.20 或更高版本（需支持 Worktree）
AI 编码 Agent： 至少安装以下之一：Claude Code（推荐）、Cursor、Windsurf、Gemini CLI、GitHub Copilot 等
推荐 AI 模型： Claude Opus 4.6（项目官方推荐，视觉理解和代码生成能力最佳）

安装步骤

# 第一步：检查 Node.js 版本（需要 24.0+）
node --version
# 预期输出：v24.x.x

# 如果版本低于 24，使用 nvm 安装最新版本
nvm install 24
nvm use 24

# 第二步：检查 Git 版本（需要 2.20+）
git --version
# 预期输出：git version 2.x.x

# 第三步：克隆模板仓库（使用你自己的项目名称替换 my-clone）
git clone https://github.com/JCodesMore/ai-website-cloner-template.git my-clone

# 第四步：进入项目目录并安装依赖
cd my-clone
npm install

执行结果：

v24.0.0
git version 2.47.1
Cloning into 'my-clone'...
remote: Enumerating objects: 234, done.
remote: Counting objects: 100% (234/234), done.
remote: Compressing objects: 100% (156/156), done.
remote: Total 234 (delta 78), reused 198 (delta 62), pack-reused 0
Receiving objects: 100% (234/234), 1.23 MiB | 2.45 MiB/s, done.
Resolving deltas: 100% (78/78), done.

added 327 packages in 12s

验证安装

# 验证项目结构
ls -la

# 验证关键文件存在
ls AGENTS.md CLAUDE.md package.json

# 验证脚本可执行
ls scripts/sync-agent-rules.sh scripts/sync-skills.mjs

# 启动开发服务器验证 Next.js 项目可以运行
npm run dev

执行结果：

# ls -la 输出关键文件
drwxr-xr-x  .claude/
-rw-r--r--  AGENTS.md
-rw-r--r--  CLAUDE.md
-rw-r--r--  package.json
drwxr-xr-x  scripts/
drwxr-xr-x  src/

# ls 验证关键文件
AGENTS.md  CLAUDE.md  package.json

# ls 验证脚本
scripts/sync-agent-rules.sh  scripts/sync-skills.mjs

# npm run dev 输出
> next dev
  ▲ Next.js 16.x.x
  - Local:        http://localhost:3000
  - Environments: .env
 ✓ Starting...
 ✓ Ready in 1.2s

第一部分：入门篇

1.1 理解项目结构与核心文件

概念讲解：

AIWebsiteClonerTemplate 不是传统的 npm 包或 CLI 工具，而是一个 Next.js 项目模板。它通过预配置的指令文件（AGENTS.md、CLAUDE.md 等）告诉 AI 编码 Agent 如何系统化地克隆网站。理解项目结构是使用模板的第一步。

项目中有两类核心文件： - 指令文件（AGENTS.md、CLAUDE.md 等）：定义了 5 阶段流水线的执行逻辑，AI Agent 读取这些文件来了解如何执行克隆任务 - 同步脚本（scripts/ 目录）：将 AGENTS.md 这个唯一指令源转换为各平台特定的配置格式

代码示例：

# 查看项目目录结构（关键部分）
# 进入项目根目录
cd my-clone

# 查看顶层文件和目录
ls -1

# 查看 AI Agent 指令文件（最重要的文件）
head -30 AGENTS.md

# 查看同步脚本
ls -1 scripts/

执行结果：

# ls -1 输出
.claude/
.github/
AGENTS.md
CLAUDE.md
Dockerfile
GEMINI.md
LICENSE
README.md
docker-compose.yml
package.json
public/
scripts/
src/
tailwind.config.ts

# head -30 AGENTS.md 输出（指令文件的前 30 行）
# 这将显示 5 阶段流水线的定义、质量标准和验收条件

# ls -1 scripts/ 输出
sync-agent-rules.sh
sync-skills.mjs

练习题： 1. 打开 AGENTS.md 文件，找到 5 阶段流水线的定义部分，列出每个阶段的名称 2. 查看 CLAUDE.md 文件的内容，对比它与 AGENTS.md 的关系和差异

1.2 执行第一次网站克隆

概念讲解：

网站克隆的核心入口是 /clone-website <target-url> 命令。这个命令是一个"技能（Skill）"，预定义在 .claude/skills/clone-website/SKILL.md 中。当你输入这个命令时，AI Agent 会按照 AGENTS.md 中定义的 5 阶段流水线自动执行克隆任务。

5 个阶段分别是： 1. Reconnaissance（侦察）：截图、提取设计令牌、分析布局 2. Foundation（基础）：配置字体、颜色、下载资源 3. Component Specs（组件规格）：为每个组件生成详细规格文档 4. Parallel Build（并行构建）：多个 Agent 并行构建各组件 5. Assembly & QA（组装质检）：合并代码、视觉对比、质量检查

代码示例：

# 确保在项目目录中
cd my-clone

# 启动 Claude Code（推荐使用 --chrome 标志启用浏览器扩展）
claude --chrome

# 在 Claude Code 交互界面中执行克隆命令
# 以下是你在 Claude Code 提示符下输入的命令：

# 在 Claude Code 中输入：
/clone-website https://example.com

# 如果需要克隆多个页面（v0.3.0+ 支持）：
/clone-website https://example.com https://example.com/about https://example.com/contact

# 克隆完成后，启动开发服务器查看结果
npm run dev

# 在浏览器中打开 http://localhost:3000 查看克隆结果

执行结果：

# /clone-website 执行过程中 Claude Code 的输出（示意）
> Phase 1: Reconnaissance
  - Screenshotting target site (desktop + mobile breakpoints)
  - Extracting design tokens (colors, fonts, spacing)
  - Scanning interactions (scroll, hover, click)

> Phase 2: Foundation
  - Configuring fonts
  - Setting up color system (oklch)
  - Downloading images and assets

> Phase 3: Component Specs
  - Generating spec for: Header
  - Generating spec for: HeroSection
  - Generating spec for: Features
  - Generating spec for: Footer

> Phase 4: Parallel Build
  - Building Header in worktree
  - Building HeroSection in worktree
  - Building Features in worktree
  - Building Footer in worktree

> Phase 5: Assembly & QA
  - Merging all worktrees
  - Running lint + typecheck + build
  - Visual diff comparison

✓ Clone complete! Run `npm run dev` to preview.

练习题： 1. 选择一个简单的静态网站（如 https://example.com），执行克隆并观察每个阶段的输出 2. 在克隆过程中，检查 docs/research/ 目录下生成了哪些文件

1.3 理解输出代码结构

概念讲解：

克隆完成后，AIWebsiteClonerTemplate 会生成一个完整的 Next.js 16 项目。理解输出代码的结构有助于你后续修改和定制克隆结果。输出代码遵循以下约定： - TypeScript 严格模式 - shadcn/ui 组件复用 - Tailwind CSS v4 样式 - 响应式断点设计 - Next.js App Router 架构

代码示例：

# 查看克隆完成后的项目结构
ls -1 src/

# 查看组件目录
ls -1 src/components/

# 查看页面路由
ls -1 src/app/

# 查看全局样式（包含提取的设计令牌）
head -40 src/app/globals.css

执行结果：

# ls -1 src/ 输出
app/
components/
lib/

# ls -1 src/components/ 输出（示意，实际取决于目标网站）
Header.tsx
HeroSection.tsx
Features.tsx
Footer.tsx
icons.tsx
ui/

# ls -1 src/app/ 输出
favicon.ico
globals.css
layout.tsx
page.tsx

# head -40 src/app/globals.css 输出（示意）
/* 设计令牌（Design Tokens）- 从目标网站提取 */
@theme {
  --color-primary: oklch(0.55 0.2 260);
  --color-secondary: oklch(0.65 0.15 280);
  --font-sans: 'Inter', sans-serif;
  --font-heading: 'Plus Jakarta Sans', sans-serif;
}

练习题： 1. 打开 src/app/page.tsx，分析它是如何引入和组装各组件的 2. 查看 src/components/ui/ 目录，了解 shadcn/ui 组件的使用方式

第二部分：进阶篇

2.1 指令同步机制与多 Agent 支持

概念讲解：

AIWebsiteClonerTemplate 的核心设计之一是"Agent 无关（Agent-Agnostic）"。它通过 AGENTS.md 作为唯一的指令源（Single Source of Truth），使用同步脚本自动生成各平台特定的配置文件。

这意味着： - 维护者只需编辑 AGENTS.md 一个文件 - 运行 sync-agent-rules.sh 可自动生成 CLAUDE.md、GEMINI.md、.cursor/rules 等 13+ 种平台配置 - 运行 sync-skills.mjs 可自动生成各平台的技能/命令文件

代码示例：

# 查看当前支持的所有 Agent 配置文件
echo "=== Agent 配置文件 ==="
ls -1 CLAUDE.md GEMINI.md .cursor/rules/ .windsurfrules 2>/dev/null

# 编辑指令源（修改流水线行为时编辑此文件）
# 例如：vim AGENTS.md

# 将修改后的 AGENTS.md 同步到所有平台配置
bash scripts/sync-agent-rules.sh

# 同步技能文件（/clone-website 命令定义）
node scripts/sync-skills.mjs

# 验证同步结果：对比 CLAUDE.md 和 AGENTS.md 的核心内容
echo "=== CLAUDE.md 前 10 行 ==="
head -10 CLAUDE.md
echo ""
echo "=== GEMINI.md 前 10 行 ==="
head -10 GEMINI.md

执行结果：

=== Agent 配置文件 ===
CLAUDE.md
GEMINI.md
.cursor/rules/:
ai-website-cloner-template.mdc
.windsurfrules

# 同步脚本执行输出（示意）
Syncing AGENTS.md to platform configs...
  ✓ CLAUDE.md updated
  ✓ GEMINI.md updated
  ✓ .cursor/rules/ai-website-cloner-template.mdc updated
  ✓ .windsurfrules updated
  ✓ .github/copilot-instructions.md updated
  ... 8 more platform configs updated

Syncing skills...
  ✓ .claude/skills/clone-website/SKILL.md updated
  ✓ .github/copilot-instructions.md updated
  ... 6 more platform skills updated

=== CLAUDE.md 前 10 行 ===
# AI Website Cloner Template - Agent Instructions
This file is auto-generated from AGENTS.md...

=== GEMINI.md 前 10 行 ===
# AI Website Cloner Template - Agent Instructions
This file is auto-generated from AGENTS.md...

注意事项： - 不要直接编辑 CLAUDE.md 或 GEMINI.md：这些文件由同步脚本自动生成，手动修改会在下次同步时被覆盖。所有修改应该通过编辑 AGENTS.md 然后运行同步脚本来完成。 - 同步前确保 AGENTS.md 格式正确：AGENTS.md 的格式变更可能影响所有平台的配置生成。修改前建议备份原文件。

练习题： 1. 在 AGENTS.md 中找到质量标准定义部分，尝试修改某个验收条件，然后运行同步脚本观察变化 2. 对比同步前后的 CLAUDE.md 文件，验证你的修改是否正确同步

2.2 Component Specs 深入理解

概念讲解：

Component Specs（组件规格）是 AIWebsiteClonerTemplate 的核心创新。在构建代码之前，AI Agent 会为每个识别到的 UI 组件生成一份详细的 Markdown 规格文档。这些文档包含： - 精确的 CSS 计算值（通过 getComputedStyle() 提取） - 所有交互状态（hover、focus、active、disabled） - 响应式断点下的行为变化 - 内容文本和资源路径

这个阶段相当于"先画建筑蓝图，再施工"，避免了 Agent 在构建时"猜测"样式值。

代码示例：

# 克隆完成后，查看生成的组件规格文档
ls -1 docs/research/components/

# 查看某个组件的规格文档（以 HeroSection 为例）
cat docs/research/components/HeroSection.md

<!-- docs/research/components/HeroSection.md 示例内容 -->

# HeroSection 组件规格

## 布局（Layout）
- 容器宽度：max-width 1280px, margin 0 auto
- 垂直间距：padding-top 96px, padding-bottom 80px
- 内容对齐：text-align center
- 背景：background-color #ffffff

## 排版（Typography）
- 标题（H1）：
  - font-size: 60px
  - font-weight: 700 (bold)
  - line-height: 1.1
  - color: #111827
  - font-family: 'Plus Jakarta Sans', sans-serif
- 副标题（Paragraph）：
  - font-size: 20px
  - font-weight: 400 (regular)
  - line-height: 1.6
  - color: #6b7280

## 交互状态（Interactive States）
- 主按钮（CTA Primary）：
  - 默认：background #2563eb, color #ffffff, border-radius 8px
  - hover：background #1d4ed8, transition 150ms ease
  - focus：outline 2px solid #2563eb, outline-offset 2px
- 次按钮（CTA Secondary）：
  - 默认：background transparent, border 1px solid #d1d5db, color #374151
  - hover：background #f9fafb, border-color #9ca3af

## 响应式断点（Responsive Breakpoints）
- md (768px)：
  - 标题 font-size: 48px
  - 副标题 font-size: 18px
  - padding-top: 64px, padding-bottom: 56px
- sm (640px)：
  - 标题 font-size: 36px
  - 按钮容器从水平排列改为垂直堆叠
  - padding-top: 48px, padding-bottom: 40px

## 内容（Content）
- 标题文本："Build modern web apps faster"
- 副标题文本："The complete platform for..."
- 主按钮文本："Get Started"
- 次按钮文本："Watch Demo"

执行结果：

# ls -1 docs/research/components/ 输出
Header.md
HeroSection.md
Features.md
Testimonials.md
Footer.md

# cat docs/research/components/HeroSection.md 输出如上所示

注意事项： - 规格文档质量直接影响克隆效果：如果 Component Specs 阶段的输出不准确，后续构建阶段的代码也会偏离目标。建议在流水线运行后检查关键组件的规格文档。 - 规格文档是可编辑的：如果发现自动生成的规格有误，可以手动修正后再重新运行构建阶段，不需要重新开始整个流程。

练习题： 1. 克隆一个网站后，打开某个组件的规格文档，验证其中记录的 CSS 值是否与目标网站一致 2. 尝试手动修改某个组件规格中的字体大小值，然后重新构建该组件，观察变化

2.3 使用不同 AI Agent 执行克隆

概念讲解：

AIWebsiteClonerTemplate 支持 13+ 种 AI 编码 Agent。切换 Agent 不需要修改项目代码——只需使用对应平台的 Agent 工具即可。不同 Agent 的体验可能有差异，因为各 Agent 的视觉理解能力和代码生成质量不同。

以下展示如何在几个主流 Agent 中使用模板：

代码示例：

# 方式 1：使用 Claude Code（官方推荐）
# Claude Code 会自动读取 CLAUDE.md 配置
cd my-clone
claude --chrome
# 在 Claude Code 中输入：/clone-website https://example.com

# 方式 2：使用 Cursor
# Cursor 会自动读取 .cursor/rules/ 配置
# 在 Cursor 中打开 my-clone 项目文件夹
# 在 Cursor 的 Agent/Chat 中输入：clone https://example.com

# 方式 3：使用 Gemini CLI
# Gemini CLI 会自动读取 GEMINI.md 配置
cd my-clone
gemini
# 在 Gemini CLI 中描述克隆任务

# 方式 4：使用 GitHub Copilot（VS Code）
# Copilot 会读取 .github/copilot-instructions.md 配置
# 在 VS Code 中打开 my-clone 项目
# 使用 Copilot Chat 输入克隆指令

执行结果：

# 不同 Agent 的执行方式不同，但最终输出结构一致
# 都会生成 src/components/*.tsx 和 src/app/ 下的页面文件

注意事项： - 克隆质量因 Agent 而异：Claude Code + Opus 4.6 的视觉效果最佳。其他 Agent 可能需要额外的手动调整。 - 部分 Agent 可能不支持浏览器交互：Reconnaissance 阶段需要截取目标网站截图，某些 Agent（如非 Chrome MCP 配置的 Agent）可能需要手动提供截图。 - 首次使用新 Agent 时先同步配置：运行 bash scripts/sync-agent-rules.sh && node scripts/sync-skills.mjs 确保配置是最新的。

练习题： 1. 如果你有 Cursor 或其他 Agent 环境，尝试用两种不同的 Agent 克隆同一个网站，对比输出质量 2. 查看同步脚本生成的不同平台配置文件，理解各平台的配置格式差异

第三部分：高级篇

3.1 自定义 AGENTS.md 指令

概念讲解：

AGENTS.md 是项目的"大脑"，定义了完整的流水线执行逻辑、质量标准和验收条件。通过自定义 AGENTS.md，你可以： - 调整流水线的阶段行为（如跳过某些阶段、修改阶段输出要求） - 修改代码质量标准（如添加新的 lint 规则、组件规范） - 添加自定义的验收条件 - 调整并行构建的策略

代码示例：

# 查看当前 AGENTS.md 的结构
wc -l AGENTS.md

# 备份原始文件
cp AGENTS.md AGENTS.md.backup

# 编辑 AGENTS.md（以修改质量标准为例）
# 使用你喜欢的编辑器

# 同步修改到所有平台
bash scripts/sync-agent-rules.sh

# 同步技能文件
node scripts/sync-skills.mjs

# 验证修改已同步到各平台配置
# 对比 CLAUDE.md 和 AGENTS.md 的差异
diff <(head -20 AGENTS.md) <(head -20 CLAUDE.md)

执行结果：

# wc -l AGENTS.md 输出（示意）
487 AGENTS.md

# sync-agent-rules.sh 输出
Syncing AGENTS.md to platform configs...
  ✓ CLAUDE.md updated
  ✓ GEMINI.md updated
  ... all platforms updated

# diff 输出（通常只有头部注释不同，因为核心内容来自同一源）
1c1
< # AI Website Cloner Template - Main Instructions
---
> # AI Website Cloner Template - Agent Instructions (auto-generated)

注意事项： - 修改 AGENTS.md 前务必备份：错误的修改可能导致所有平台的克隆流程异常。 - 测试修改后再批量使用：建议先用一个简单的目标网站测试修改后的效果，确认无误后再用于正式克隆任务。 - 同步后检查目标平台配置：不同 Agent 对指令格式的解析可能有差异，修改后建议在目标 Agent 中做一次端到端测试。

3.2 多 URL 克隆与页面路由管理

概念讲解：

从 v0.3.0 开始，AIWebsiteClonerTemplate 支持一次性克隆多个 URL。这对于需要克隆完整网站（首页、关于页、产品页等）的场景非常有用。多 URL 克隆时，Agent 会为每个 URL 独立执行流水线，但在 Foundation 阶段共享设计令牌和资源。

代码示例：

# 克隆多个 URL（v0.3.0+）
# 在 Claude Code 中执行：

# 克隆一个网站的多页面
/clone-website https://example.com https://example.com/about https://example.com/pricing https://example.com/contact

# 克隆完成后，查看生成的页面路由
ls -1 src/app/

# 查看各页面的组件引用关系
head -20 src/app/about/page.tsx

执行结果：

# ls -1 src/app/ 输出
favicon.ico
globals.css
layout.tsx
page.tsx          # 首页
about/
  page.tsx        # 关于页
pricing/
  page.tsx        # 定价页
contact/
  page.tsx        # 联系页

# head -20 src/app/about/page.tsx 输出（示意）
import { Header } from "@/components/Header";
import { Footer } from "@/components/Footer";
import { AboutHero } from "@/components/AboutHero";
import { TeamSection } from "@/components/TeamSection";
// ...

注意事项： - 多 URL 克隆耗时更长：每个页面都需独立执行流水线，组件数量线性增加。建议优先克隆最重要的页面。 - 共享组件自动复用：多个页面共享的组件（如 Header、Footer）只会生成一次，在 Assembly 阶段自动连接。

3.3 Docker 容器化部署

概念讲解：

项目内置了 Docker Compose 配置，可以将克隆结果一键容器化部署。这对于以下场景有用： - 将克隆结果快速部署到测试环境 - 在 CI/CD 流水线中自动构建和部署 - 团队成员快速预览克隆结果

代码示例：

# 查看 Docker 配置文件
cat docker-compose.yml

# 使用 Docker 构建和运行
docker compose up --build

# 后台运行
docker compose up --build -d

# 查看运行状态
docker compose ps

# 停止容器
docker compose down

执行结果：

# docker compose up --build 输出（示意）
[+] Building 45.2s
 => [internal] load build definition
 => => transferring dockerfile: 523B
 => [1/5] FROM node:24-alpine
 => [2/5] WORKDIR /app
 => [3/5] COPY package*.json ./
 => [4/5] RUN npm ci
 => [5/5] COPY . .
 => exporting to image

[+] Running 1/0
 ✔ Container my-clone-web  Started  0.3s

# docker compose ps 输出
NAME              STATUS          PORTS
my-clone-web      Up 30 seconds   0.0.0.0:3000->3000/tcp

# 访问 http://localhost:3000 即可查看克隆结果

注意事项： - 确保 Docker 已安装并运行：Docker Desktop（macOS/Windows）或 Docker Engine（Linux）需要事先安装。 - 端口冲突：默认使用 3000 端口，如果已被占用需要修改 docker-compose.yml 中的端口映射。

第四部分：实战项目

项目需求

克隆 Stripe 官网首页（https://stripe.com），这是一个包含多个复杂组件区域的典型企业官网： - 顶部导航栏（含下拉菜单和动画效果） - Hero 区域（含渐变文字和动态背景） - Features 展示区（卡片网格布局） - 支付流程演示区 - 底部导航和 Footer

目标： 使用 AIWebsiteClonerTemplate 完整克隆该页面，生成可运行的 Next.js 项目，并通过 CI Quality Gates 验证。

项目设计

技术选型：
- AI Agent: Claude Code + Opus 4.6（推荐配置）
- 目标框架: Next.js 16 + React 19
- UI 组件库: shadcn/ui
- 样式系统: Tailwind CSS v4（oklch 色彩空间）
- 类型系统: TypeScript 严格模式

预期组件拆分：
1. Header          → 导航栏（Logo + 菜单 + CTA 按钮）
2. HeroSection     → 主视觉区（渐变标题 + 描述 + 按钮）
3. Features        → 功能展示（卡片网格 + 图标）
4. PaymentDemo     → 支付流程演示
5. Testimonials    → 用户评价（轮播或网格）
6. CTASection      → 行动号召区域
7. Footer          → 底部导航（多列链接 + 版权信息）

流水线阶段预估：
- Phase 1 (侦察):  5-10 分钟
- Phase 2 (基础):  3-5 分钟
- Phase 3 (规格):  5-8 分钟
- Phase 4 (构建):  10-20 分钟（并行）
- Phase 5 (组装):  3-5 分钟
总计：约 25-50 分钟

完整实现代码

# ===== 第一步：环境准备 =====
# 确保 Node.js 版本符合要求
node --version
# 预期输出：v24.x.x

# 克隆模板（使用项目名 stripe-clone）
git clone https://github.com/JCodesMore/ai-website-cloner-template.git stripe-clone
cd stripe-clone
npm install

# ===== 第二步：启动 Claude Code =====
# 使用 --chrome 标志启用浏览器交互
claude --chrome

# ===== 第三步：执行克隆 =====
# 在 Claude Code 交互界面中输入以下命令：

/clone-website https://stripe.com

# ===== 第四步：等待流水线执行完成 =====
# Agent 会自动执行 5 个阶段，期间可能需要你确认一些权限
# 例如：允许浏览器导航、确认资源下载等

# ===== 第五步：验证结果 =====
# 启动开发服务器
npm run dev

# 在浏览器中打开 http://localhost:3000

# 运行质量检查（与 CI Quality Gates 相同）
npm run lint
npx tsc --noEmit
npm run build

# ===== 第六步：查看生成的文件结构 =====
echo "=== 页面文件 ==="
ls -1 src/app/

echo "=== 组件文件 ==="
ls -1 src/components/

echo "=== 设计令牌 ==="
head -30 src/app/globals.css

echo "=== 组件规格文档 ==="
ls -1 docs/research/components/

# ===== 第七步：容器化部署（可选） =====
docker compose up --build -d

执行结果：

# npm run lint 输出
> next lint
✔ No ESLint warnings or errors

# npx tsc --noEmit 输出
（无输出表示类型检查通过）

# npm run build 输出
> next build
  ▲ Next.js 16.x.x
   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types
 ✓ Collecting page data
 ✓ Generating static pages (7/7)
 ✓ Finalizing page optimization

Route (app)              Size     First Load JS
┌ ○ /                    12.3 kB      89.2 kB
├ ○ /_not-found          0 kB        82.1 kB
└ λ /api/health          0 kB        82.1 kB

# 文件结构输出
=== 页面文件 ===
favicon.ico
globals.css
layout.tsx
page.tsx

=== 组件文件 ===
Header.tsx
HeroSection.tsx
Features.tsx
PaymentDemo.tsx
Testimonials.tsx
CTASection.tsx
Footer.tsx
icons.tsx
ui/

=== 设计令牌 ===
@theme {
  --color-primary: oklch(0.55 0.22 265);
  --color-secondary: oklch(0.65 0.18 280);
  --font-sans: 'Inter', sans-serif;
  ...
}

=== 组件规格文档 ===
Header.md
HeroSection.md
Features.md
PaymentDemo.md
Testimonials.md
CTASection.md
Footer.md

代码解析

知识点 1：5 阶段流水线（Multi-Phase Pipeline） - /clone-website 命令触发了完整的 5 阶段流水线，每个阶段按顺序自动执行 - 可以在 docs/research/components/ 目录中看到 Phase 3 生成的组件规格文档

知识点 2：Component Specs（组件规格） - Phase 3 为每个组件生成了详细的 Markdown 规格文档 - 这些规格包含精确的 CSS 值、交互状态和响应式断点 - 打开 docs/research/components/HeroSection.md 可以看到提取的颜色值（如 oklch 色彩空间）、字体大小、hover 效果等

知识点 3：Git Worktree 并行构建（Parallel Build） - Phase 4 使用 Git Worktree 为每个组件创建独立的工作目录 - 多个 Agent 并行构建不同组件，大幅缩短了总构建时间 - Phase 5 将所有 Worktree 的结果合并为完整的 Next.js 项目

知识点 4：CI Quality Gates（质量门禁） - npm run lint、npx tsc --noEmit、npm run build 三项检查确保代码质量 - 这是 Assembly & QA 阶段的自动化验收标准

扩展挑战

多页面克隆：使用 /clone-website https://stripe.com https://stripe.com/docs https://stripe.com/pricing 克隆 Stripe 的多个页面，观察组件复用情况
自定义质量标准：编辑 AGENTS.md 添加自定义的验收条件（如要求所有图片使用 Next.js Image 组件），同步后重新克隆
跨 Agent 对比：分别用 Claude Code 和 Cursor 克隆同一个页面，对比两种 Agent 的输出差异

第五部分：常见问题与排查指南

常见错误及解决方案

错误信息	原因	解决方案
`error: node --version v20.x.x` (低于 v24)	Node.js 版本不符合最低要求（v24+）	安装 Node.js 24 或更高版本：`nvm install 24 && nvm use 24`
`Chrome extension isn't connected`	Claude Code 的 Chrome MCP 扩展未正确安装或未连接	重新启动 `claude --chrome`，在浏览器中确认扩展已安装并启用
`git worktree add failed`	Git 版本过低或存在未清理的 Worktree	更新 Git 到 2.20+：`git worktree list` 检查现有 Worktree，`git worktree prune` 清理无效条目
`Error: Cannot take screenshot`	目标网站有反爬虫机制或页面加载超时	选择无反爬虫的静态网站作为目标，或在 Reconnaissance 阶段手动提供截图
`npm run build` 类型错误	生成的组件代码中存在 TypeScript 类型不匹配	检查 `docs/research/components/` 中的规格是否准确，手动修正规格后重新构建
`Merge conflict in Assembly phase`	多个 Worktree 修改了同一文件（如 globals.css）	手动解决冲突，保留两个分支的必要修改，或修改 AGENTS.md 中的组件拆分策略
`Error: Port 3000 already in use`	开发服务器端口被其他进程占用	终止占用端口的进程：`lsof -i :3000` 找到 PID 后 `kill <PID>`，或修改启动端口
`CRLF line ending errors` (Windows)	Windows 使用 CRLF 行尾导致脚本执行失败	v0.3.1 已修复此问题。确保使用最新版本，或在 Git 中配置 `core.autocrlf`

调试技巧

分阶段调试：如果某个阶段失败，可以检查该阶段的输出目录。例如 Reconnaissance 阶段失败时检查 docs/research/ 目录是否有截图文件；Component Specs 阶段失败时检查 docs/research/components/ 是否有规格文档。根据缺失的文件定位问题发生在哪个具体步骤。
查看 Agent 执行日志：Claude Code 和其他 Agent 通常会输出详细的执行过程日志。如果克隆结果不理想，回溯日志找到偏差发生的阶段（通常是 Component Specs 或 Parallel Build 阶段），针对性修正该阶段的输出。
手动提供截图作为输入：如果 Reconnaissance 阶段因反爬虫机制无法截图，可以手动使用浏览器截取目标网站的全页面截图，保存到 docs/design-references/ 目录，然后重新运行后续阶段。

第六部分：学习路线推荐

官方文档推荐阅读顺序

GitHub README - 重点关注"Quick Start"和"Pipeline"章节，了解安装和基本使用流程
AGENTS.md - 阅读 5 阶段流水线的完整定义，理解每阶段的输入、输出和验收标准
CLAUDE.md - 查看从 AGENTS.md 同步生成的 Claude Code 配置，理解指令同步机制
scripts/ - 阅读 sync-agent-rules.sh 和 sync-skills.mjs 的源码，理解多平台同步的实现细节

信息来源

GitHub 仓库 JCodesMore/ai-website-cloner-template - 获取日期：2026-04-12
Incrypted: How to Clone Any Website With a Single Command - 获取日期：2026-04-12
Augment Code: Git Worktrees for Parallel AI Agent Execution - 获取日期：2026-04-12
LobeHub: AI Website Cloner Template Skill - 获取日期：2026-04-12
Reddit: I Made This Claude Code Skill to Clone Any Website - 获取日期：2026-04-12

AIWebsiteClonerTemplate - 完整学习教程

环境搭建指南

系统要求

安装步骤

验证安装

第一部分：入门篇

1.1 理解项目结构与核心文件

1.2 执行第一次网站克隆

1.3 理解输出代码结构

第二部分：进阶篇

2.1 指令同步机制与多 Agent 支持

2.2 Component Specs 深入理解

2.3 使用不同 AI Agent 执行克隆

第三部分：高级篇

3.1 自定义 AGENTS.md 指令

3.2 多 URL 克隆与页面路由管理

3.3 Docker 容器化部署

第四部分：实战项目

项目需求

项目设计

完整实现代码

代码解析

扩展挑战

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

第六部分：学习路线推荐

官方文档推荐阅读顺序

推荐进阶资源

信息来源