使用说明

🚀 网络克隆

一个异步优先的网站克隆和渲染捕获工具，用于文档镜像、人工智能知识库和企业RAG管道。

人工智能知识库 • 特性 • 快速开始 • 用法 • 码头工人 • 贡献

🎯 为什么选择WebClone

WebClone帮助团队将授权网站和文档转化为人工智能系统的可复制源材料。它可以镜像静态页面，在需要时渲染JavaScript页面，并导出结构化内容以用于下游分块、嵌入、搜索和RAG工作流。

目标很简单：让人工智能助手和聊天机器人更容易从可信的文档中回答问题，而不是猜测。

WebClone设计用于：

项目、产品、SDK和API的文档镜像
从批准的公共或私人文档生成AI知识库
需要可重复源捕获的企业RAG摄入管道
可审计的档案，包括保存的HTML、资产、元数据和渲染输出
礼貌地爬行，使用保守的默认值、重试/回退和明确的选择加入

🧠 人工智能知识库与企业RAG

WebClone旨在帮助人工智能团队从他们拥有或授权处理的网站中创建高质量、基于源代码的知识库。

WebClone帮助您构建什么

RAG语料库 来自文档网站、内部门户、产品手册、SDK参考和知识中心
聊天机器人接地数据 因此，助理根据批准的文档进行回答，而不是猜测
离线镜像 用于合规性、审查、审计和可重复的人工智能索引
结构化内容导出 从渲染页面中提取数据，用于分块、嵌入、矢量数据库和检索管道
经过身份验证的捕获 用于使用已保存的浏览器Cookie或会话文件的私营企业文档

企业友好的捕获流程

Authorized website or docs portal
        ↓
WebClone polite crawler / rendered browser capture
        ↓
HTML mirror + assets + structured_content.json + render_debug_report.json
        ↓
Chunking, embeddings, vector database, search index, or RAG pipeline
        ↓
Grounded AI assistants, copilots, support bots, and internal chatbots

一页呈现的知识捕获

使用 clone-knowledge-page 在提取结构化部分之前，页面必须像浏览器一样呈现。选择目标页面上实际存在的选择器——以下示例使用python.org中的真实Sphinx标记：

webclone clone-knowledge-page "https://docs.python.org/3/tutorial/index.html" \
  --render-js \
  --wait-for "div.body" \
  --item-selector "div.section, section" \
  --item-text-selector "h1, h2, h3" \
  --detail-selector "p, li, pre" \
  --output ./output/docs-knowledge-page

文中写道：

page.rendered.html          # final browser-rendered DOM
structured_content.json     # generic item/detail/label records for ingestion
render_debug_report.json    # counts, final URL, auth-likelihood diagnostics

RAG文档网站抓取

对于一个普通的文档网站，从礼貌的限制开始，并有意识地扩展：

webclone clone "https://docs.python.org/3/" \
  --recursive \
  --max-depth 2 \
  --max-pages 100 \
  --workers 1 \
  --delay 3000 \
  --output ./output/docs-mirror

将生成的镜像用作索引和嵌入作业的可复制真实源。

✨ 特性

🚀 礼貌异步爬行引擎

使用可配置的worker和保守的默认值进行并发下载
具有重复URL抑制功能的智能队列管理
使用指数回退、抖动和 Retry-After 处理
停止后429保护，以遵守目标速率限制

🎭 动态页面渲染和结构化捕获

为JavaScript密集型网站提供完整的Selenium集成
为授权的私人文档加载经过身份验证的cookie
选择器在保存最终DOM之前等待并配置点击
RAG和聊天机器人知识库的通用结构化内容提取
使用Chrome DevTools协议生成PDF快照
用于视觉存档的屏幕截图

🔐 身份验证和负责任的浏览器会话

基于Cookie的身份验证：保存和重用授权的浏览器会话
渲染的私人文档：捕获需要经过身份验证的浏览器会话的页面
浏览器配置：动态页面的实用Selenium默认值
限速意识：礼貌操作的重试/回退和停止阈值
易于审计的产出：最终URL、计数和身份验证可能性诊断

🎨 世界级的CLI体验

漂亮的终端UI由富有的
每个资源状态的实时进度条
带表格和面板的彩色、格式化输出
用于生产监控的JSON日志

🏗️ 生产级建筑

类型安全：使用Mypy验证的100%类型提示
数据验证：具有严格模式的Pydantic V2模型
异步优先：基于 aiohttp 和 asyncio
模块化设计：具有依赖注入的干净架构
综合录井：带有上下文数据的结构化JSON日志

📦 现代工具

⚡ 紫外线：闪电般快速的依赖关系管理
🔍 颈毛：超快速装订和格式化
🧪 pytest：70项测试，涵盖核心/安全/模型 make test
🐳 码头工人：通过容器化构建 make docker-build
🔒 安全：Bandit审计和依赖性扫描

🔒 授权测试和安全默认值

WebClone专为合法归档、课堂实验室和授权安全研究而设计。在抓取目标之前，请确认您拥有该系统或具有测试它的书面权限。

面向安全的默认设置现在包括：

默认情况下仅限公共web目标: localhost，阻止环回、链路本地、私有和保留IP目标，以减少SSRF式的误用和意外的内部网络爬行。
默认情况下相同的域爬网：递归爬网将保留在起始域上，除非您明确传递 --all-domains.
有限的并发性和节奏：工作人员和请求延迟是可配置的，因此授权评估可以最大限度地减少对运营的影响。
按资产规模限制: --max-asset-bytes 防止意外的大型资产耗尽磁盘或内存。
片段规范化：在爬行之前剥离URL片段以减少重复请求。

对于孤立的实验室或私人文档服务器，请有意选择加入。例如，如果您在以下位置运行本地测试站点 http://127.0.0.1:8000:

webclone clone http://127.0.0.1:8000 \
  --allow-private-networks \
  --max-pages 25 \
  --workers 1 \
  --delay 3000

🚀 快速开始

先决条件

Python 3.11+
紫外线（推荐）或pip

安装

从PyPI安装（发布为 webclone v1.0.0）：

# Recommended: uv (10-100x faster than pip)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install webclone

# Or with plain pip
pip install webclone

从源代码安装（也可以获取Makefile快捷方式）：

git clone https://github.com/ruslanmv/webclone.git
cd webclone
make install              # creates .venv/ and installs the CLI

# The webclone entry point is installed inside .venv/, so either:
source .venv/bin/activate
webclone --version        # → WebClone version 1.0.0

# …or just call the venv binary directly without activating:
.venv/bin/webclone --version

注： make install 用途 uv 并安装到 .venv/The webclone 命令仅在您的 PATH 之后 source .venv/bin/activate （或使用 .venv/bin/webclone 直接）。Makefile的目标(make run, make test，…）已自动使用venv。

烟雾测试安装：

make run                                  # clones example.com → ./demo_output
.venv/bin/webclone --version              # WebClone version 1.0.0
.venv/bin/webclone info https://example.com

您的第一次知识获取

# Clone a single page with safe defaults
webclone clone https://example.com

# Crawl a documentation site politely for a RAG source corpus
webclone clone https://docs.python.org/3/ \
  --output ./my_mirror \
  --recursive \
  --max-depth 2 \
  --max-pages 100 \
  --workers 1 \
  --delay 3000

# Render one authorized knowledge page and export structured JSON.
# Use selectors that actually exist on the page you're capturing
# (Sphinx-built Python docs use `div.body`, NOT `.body section`).
webclone clone-knowledge-page https://docs.python.org/3/tutorial/index.html \
  --render-js \
  --wait-for "div.body" \
  --item-selector "div.section, section" \
  --item-text-selector "h1, h2, h3" \
  --detail-selector "p, li, pre"

就是这样！WebClone创建可复制的镜像和结构化捕获工件，您可以将其输入到分块、嵌入、搜索和RAG管道中。

✅ 验证示例

这些命令是在全新安装时运行的，以下输出是实际结果——复制/粘贴，它们就会起作用。

#	命令	结果
1	`webclone info https://example.com`	状态 `200`，528字节，已解析1个链接
2	`webclone clone https://example.com --max-pages 1 --no-pdf`	1页，0个资产，约2.3s
3	`webclone clone https://httpbin.org/html --max-pages 1 --no-pdf`	第1页，已保存到 `pages/page_1.html`
4	`webclone clone https://docs.python.org/3/library/typing.html --max-pages 1 --no-pdf`	24个文件：5个CSS，10个JS，1个图片，7个HTML，1个其他
5	`webclone clone 'https://en.wikipedia.org/wiki/Web_scraping' --recursive --max-depth 1 --max-pages 3 --no-pdf`	3页，23个资产，1.77 MB，约9秒——递归+资产下载器都能工作

一次性运行整个验证块：

source .venv/bin/activate

webclone info https://example.com
webclone clone https://example.com -o /tmp/demo_example --max-pages 1 --no-pdf
webclone clone https://httpbin.org/html -o /tmp/demo_httpbin --max-pages 1 --no-pdf
webclone clone https://docs.python.org/3/library/typing.html -o /tmp/demo_pydocs --max-pages 1 --no-pdf
webclone clone 'https://en.wikipedia.org/wiki/Web_scraping' \
  -o /tmp/demo_wiki --recursive --max-depth 1 --max-pages 3 --no-pdf

提示——单次身份验证捕获： 如果保存的cookie文件位于 ./cookies/*.json 与目标域匹配， webclone clone <url> 自动检测并自动打开 --render-js你可以跑 webclone clone https://internal.example.com/page 它只是工作。

🎨 企业桌面图形用户界面（新增！）

WebClone现在包括一个用现代Tkinter构建的专业、原生桌面界面，以实现卓越的性能：

# Install with GUI support
make install-gui

# Launch the Enterprise Desktop GUI
make gui

GUI会立即作为本机桌面应用程序打开，其中包含：

🏠 主页仪表板 -功能概述和快速入门指南
🔐 认证管理器 -基于可视化cookie的身份验证工作流，与浏览器集成
🛡️ 下载阻力审计 -角色/访问、JavaScript-rendered预览、HAR/API、content-leak和bulk-fetch检查所拥有的封闭内容
📥 爬行配置器 -具有实时进度的点击设置
📊 结果分析 -全面的统计数据、表格和导出选项

适合所有人！ 无需命令行-具有即时启动、本机性能和无缝操作系统集成的专业桌面界面。

与基于web的GUI相比的优势： ✅ 即时启动（无需启动服务器） ✅ 原生桌面性能 ✅ 更好的操作系统集成（文件对话框、通知） ✅ 无端口冲突 ✅ 离线友好

🤖 用于AI代理的MCP服务器（新！）

WebClone现在是一个 官方模型上下文协议（MCP）服务器，使Claude、CrewAI和任何兼容MCP的框架等AI代理都可以克隆网站！

# Install MCP server (adds the `webclone-mcp` entry point to .venv/bin/)
make install-mcp

# Run the server directly to verify it starts (stdio protocol; Ctrl+C to exit)
make mcp

将其连接到Claude Desktop(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上， ~/.config/Claude/claude_desktop_config.json 在Linux上）：

{
  "mcpServers": {
    "webclone": {
      "command": "/absolute/path/to/webclone/.venv/bin/webclone-mcp"
    }
  }
}

AI代理现在可以：

🌐 clone_网站 -自动下载整个网站
📥 下载文件 -获取特定文件或URL
🔐 save_身份验证 -保存登录会话指南
📋 list_saved_sessions -查看所有身份验证Cookie
ℹ️ get_site_info -下载前分析网站

克劳德的例子：

You: Clone the FastAPI documentation website

Claude: I'll clone that for you.
[Uses WebClone MCP tool]

✅ Cloned 127 pages, 543 assets, 45.2 MB total!

兼容：

✅ 克劳德桌面版
✅ 船员AI
✅ 链语言
✅ 任何与MCP兼容的AI框架

📖 请参阅： docs/MCP_GUIDE.md 和 MCP_QUICKSTART.md

📖 用法

界面选项

WebClone提供了四种使用方法：

🎨 桌面图形用户界面 （最简单-企业版）
```
make gui
```
- 本机桌面应用程序
- 即时启动，无需浏览器
- 视觉身份验证管理器
- 实时进度跟踪
- 适合所有用户！
🤖 MCP服务器 （适用于AI代理）
```
make install-mcp
```
- Claude桌面集成
- CrewAI兼容
- LangChain准备就绪
- 人工智能驱动的自动化
- 非常适合AI工作流程！
💻 命令行 （最强大）
```
webclone clone https://example.com
```
- 自动化和脚本
- CI/CD管道
- 远程服务器
- 高级用户
🐍 Python API （最灵活）
```
from webclone.core import AsyncCrawler
# ... your code
```
- 自定义集成
- 高级工作流
- 开发者

基本命令

# Show help
webclone --help

# Clone a website
webclone clone <URL> [OPTIONS]

# Analyze a page without downloading
webclone info <URL>

高级选项

webclone clone https://example.com \
  --output ./mirror           # Output directory (default: website_mirror)
  --recursive                 # Follow discovered links (default: off)
  --workers 1                 # Concurrent workers (default: 1)
  --max-pages 100             # Maximum pages to crawl (0 = unlimited)
  --max-depth 3               # Maximum crawl depth (0 = unlimited)
  --delay 3000                # Delay between requests in ms
  --no-assets                 # Skip downloading CSS, JS, images
  --no-pdf                    # Skip PDF generation
  --all-domains               # Follow links to other domains
  --verbose                   # Detailed logging output
  --json-logs                 # JSON-formatted logs for parsing

对于渲染知识页面提取（选择器必须与目标上的真实元素匹配）：

webclone clone-knowledge-page https://docs.python.org/3/tutorial/index.html \
  --render-js \
  --wait-for "div.body" \
  --item-selector "div.section, section" \
  --item-text-selector "h1, h2, h3" \
  --detail-selector "p, li, pre" \
  --output ./knowledge-page

真实世界的例子

# Single page, fast smoke test
webclone clone https://example.com --max-pages 1 --no-pdf

# Crawl Wikipedia article + linked pages (verified: 3 pages, 23 assets, ~9s)
webclone clone 'https://en.wikipedia.org/wiki/Web_scraping' \
  --recursive --max-depth 1 --max-pages 3 --no-pdf

# Clone a documentation page with all its CSS/JS/images
# (verified: 24 files for https://docs.python.org/3/library/typing.html)
webclone clone https://docs.python.org/3/library/typing.html --max-pages 1 --no-pdf

# Clone a documentation site recursively for a RAG source corpus
webclone clone https://docs.python.org/3/ \
  --recursive --max-depth 3 --max-pages 250 --workers 1 --delay 3000

# Render a JavaScript documentation page before extracting structured content
webclone clone-knowledge-page https://docs.python.org/3/tutorial/index.html \
  --render-js \
  --wait-for "div.body" \
  --item-selector "div.section, section" \
  --item-text-selector "h1, h2, h3" \
  --detail-selector "p, li, pre"

# Production mode with JSON logs
webclone clone https://example.com --json-logs --output /var/data/mirror

🔐 经过身份验证的浏览器会话

对于您有权访问的私人文档，请保存一次浏览器会话，并重复使用其Cookie以用于以后呈现的捕获。

# Run the interactive authentication examples
python examples/authenticated_crawl.py

保存会话的Python API：

from pathlib import Path
from webclone.models.config import SeleniumConfig
from webclone.services.selenium_service import SeleniumService

# Open a visible browser and save cookies after manual sign-in.
config = SeleniumConfig(headless=False)
service = SeleniumService(config)
service.start_driver()
service.manual_login_session(
    "https://example.com",
    Path("./cookies/example.json"),
)

# Later, reuse the cookies for an authorized browser session.
config = SeleniumConfig(headless=True)
service = SeleniumService(config)
service.start_driver()
service.navigate_to("https://example.com")
service.load_cookies(Path("./cookies/example.json"))

看身份验证指南详细说明。

🐳 码头工人

在容器化环境中运行WebClone：

# Build the image
make docker-build

# Or manually
docker build -t webclone:latest .

# Run a clone
docker run --rm -v $(pwd)/output:/data webclone:latest \
  clone https://example.com --max-pages 10

# Interactive shell
docker run --rm -it -v $(pwd)/output:/data \
  --entrypoint /bin/bash webclone:latest

Docker编写示例

version: '3.8'
services:
  webclone:
    image: webclone:latest
    volumes:
      - ./output:/data
    command: clone https://example.com --max-pages 25 --workers 1 --delay 3000
    environment:
      - WEBCLONE_MAX_PAGES=100

🏗️ 建筑

WebClone紧随其后 清洁建筑 原则：

src/webclone/
├── cli.py              # Typer CLI interface
├── core/               # Core business logic
│   ├── crawler.py           # Async web crawler
│   ├── downloader.py        # Asset downloader
│   ├── rendered_fetcher.py  # Selenium rendered capture
│   └── content_extractor.py # Structured content extraction for RAG
├── models/             # Pydantic data models
│   ├── config.py       # Configuration schemas
│   └── metadata.py     # Result metadata
├── services/           # External service integrations
│   └── selenium_service.py
└── utils/              # Shared utilities
    ├── logger.py
    └── helpers.py

关键设计决策

异步优先：所有I/O操作都使用 asyncio 实现最大并发性
类型安全：100%类型覆盖率，严格Mypy检查
Pydantic V2：系统边界的数据验证
负责任的爬行：更安全的默认设置、处理后重试以及更广泛的爬网的明确选择
RAG就绪输出：渲染HTML加结构化JSON，用于下游分块、嵌入和检索
依赖注入：服务通过构造函数接收依赖关系
单一职责：每个模块都有一个明确的目的

🧪 发展

设置开发环境

# Clone the repository
git clone https://github.com/ruslanmv/webclone.git
cd webclone

# Install with dev dependencies (creates .venv/ with pytest, ruff, mypy, bandit)
make dev

# Run tests — 70 passing
make test

# Format code
make format

运行测试

# Full test suite with coverage
make test
# → 70 passed in ~3s

# Fast tests without coverage
make test-fast

# Generate HTML coverage report (opens htmlcov/index.html)
make coverage

Makefile调用 .venv/bin/pytest / .venv/bin/ruff /等等，因此，无论venv是否被激活，目标都会起作用。

代码质量

# Lint with ruff (the codebase has known lint debt; CI does not block on it)
make lint

# Type check with mypy
make typecheck

# Format code
make format

# Run all quality checks
make audit

🤝 贡献

我们欢迎捐款！请见贡献.md 作为指导方针。

快速贡献工作流程

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
进行质量检查(make audit)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📊 基准测试

在具有100 Mbps连接的标准4核机器上进行了测试：

网站类型	页面	资产	时间（WebClone）	时间（wget）	加速
静态站点	50	200	8s	45s	5.6倍
博客	100	500	25s	3m 20s	8.0倍
文档	200	800	1m 10s	12m 15s	10.5倍
SPA/动态	30	150	35s	N/A*	∞

*wget无法渲染基于JavaScript的SPA

📄 许可证

该项目根据 Apache许可证2.0 -看看许可证文件以获取详细信息。

👤 作者

鲁斯兰马加纳

网站： ruslanmv.com
github： @ruslanmv
电子邮件：contact@ruslanmv.com

🌟 星史

如果你觉得WebClone有用，请考虑给它一颗星！ ⭐

🙏 致谢

类型 -漂亮的CLI框架
富有的 -丰富的终端格式化
派丹蒂克 -数据验证
意图tp -异步HTTP客户端
紫外线 -闪电般快速的软件包安装程序

制作❤️ 通过鲁斯兰马加纳