GeiserX/Website-Diff
GitHub: GeiserX/Website-Diff
一个智能网页对比 CLI 工具，支持 Wayback Machine 存档清理、显著性评分和多浏览器视觉回归测试，专为 CI/CD 集成而设计。
Stars: 0 | Forks: 0
检测网页之间的实质性差异——具备 Wayback Machine 工件清理、视觉对比和显著性评分功能。
## 为什么选择 Website-Diff？
比较网页听起来很简单，直到你需要处理 Wayback Machine 注入的工件、无关紧要的空白噪音，以及 DOM 无法察觉的视觉回归。**Website-Diff** 是一个专用 CLI 工具，解决了这三个问题：
- **Wayback Machine 清理** -- 自动剥离横幅、分析脚本、播放代码和 URL 重写，以便你比较*实际*内容。
- **显著性评分** -- 每个变更都会标记为 High（高）、Medium（中）或 Low（低），让你专注于重要事项。
- **多浏览器视觉对比** -- 在 Chrome、Firefox、Edge 和 Opera 中截取屏幕截图，然后生成像素差异图像。
- **适配 CI/CD 的退出代码** -- 直接集成到流水线中（`0` = 无更改，`1` = 低/中，`2` = 高）。
## 目录
- [快速开始](#quick-start)
- [安装](#installation)
- [用法](#usage)
- [视觉对比](#visual-comparison)
- [Markdown 报告](#markdown-reports)
- [CI/CD 集成](#cicd-integration)
- [工作原理](#how-it-works)
- [输出格式](#output-formats)
- [与类似工具的比较](#comparison-with-similar-tools)
- [贡献](#contributing)
- [许可证](#license)
## 快速开始
```
pip install -e .
# 比较两个页面
website-diff https://example.com/old https://example.com/new
# 比较 Wayback 快照与在线网站
website-diff https://web.archive.org/web/20230101/https://example.com/ https://example.com/
# 完整报告：visual diff + markdown
website-diff https://old.example.com https://new.example.com --visual --markdown
```
## 安装
### 从源码安装
```
git clone https://github.com/GeiserX/Website-Diff.git
cd Website-Diff
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
```
如需视觉对比支持：
```
pip install -e ".[visual]"
```
### Docker
```
docker build -t website-diff .
docker run --rm website-diff https://example.com/a https://example.com/b
```
## 用法
### 基本比较
```
website-diff https://example.com/page1 https://example.com/page2
```
### Wayback Machine 支持
该工具会自动检测 Wayback Machine URL，并在比较前清理注入的工件：
```
# 存档 vs. 在线网站
website-diff https://web.archive.org/web/20230101/https://example.com/ https://example.com/
# 两个存档快照
website-diff \
https://web.archive.org/web/20230101/https://example.com/ \
https://web.archive.org/web/20230601/https://example.com/
```
### 输出格式
```
# 保存到文件
website-diff url1 url2 -o diff.txt
# JSON (用于程序化消费)
website-diff url1 url2 --format json
# Unified diff
website-diff url1 url2 --format unified
```
### 全站遍历
```
# 对关联页面进行爬取和比较 (限制深度)
website-diff url1 url2 --traverse --depth 2
```
### 高级选项
| 标志 | 描述 |
|------|-------------|
| `--no-clean-wayback` | 禁用 Wayback Machine 工件移除 |
| `--no-ignore-whitespace` | 将空白更改视为显著 |
| `--timeout N` | 设置 HTTP 超时时间（秒）（默认：30） |
| `--verbose` | 启用详细日志 |
## 视觉对比
在一个或多个浏览器中截取屏幕截图并生成并排差异图像：
```
# Auto-detect 所有已安装的浏览器
website-diff url1 url2 --visual
# Specific browsers
website-diff url1 url2 --visual --browsers chrome firefox edge opera
# Custom viewport
website-diff url1 url2 --visual --viewport-width 1280 --viewport-height 720
# Non-headless mode (用于调试)
website-diff url1 url2 --visual --no-headless
# Custom 截图输出
website-diff url1 url2 --visual --screenshot-dir ./my-screenshots
```
视觉对比会生成：
- 每个浏览器的两个页面截图
- 并排对比图像
- 像素级差异高亮（红色覆盖层标记变化）
## Markdown 报告
生成包含所有内容的综合 Markdown 报告，方便审阅：
```
website-diff url1 url2 --visual --markdown --report-dir ./reports
```
每个报告包含：
- 带有变更统计的执行摘要
- 视觉对比截图（当使用 `--visual` 时）
- 按显著性分组的变更（High / Medium / Low）
- 全站结果（当使用 `--traverse` 时）
- 可操作的建议
## CI/CD 集成
Website-Diff 返回专为流水线关卡设计的有意义的退出代码：
| 退出代码 | 含义 |
|-----------|---------|
| `0` | 未检测到差异 |
| `1` | 低或中等显著性更改 |
| `2` | 检测到高显著性更改 |
### GitHub Actions 示例
```
name: Visual Regression Check
on:
pull_request:
jobs:
diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install Website-Diff
run: |
pip install -r requirements.txt
pip install -e ".[visual]"
- name: Compare staging vs production
run: |
website-diff \
https://staging.example.com \
https://production.example.com \
--visual --markdown --format json -o diff.json
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: diff-report
path: reports/
```
### Shell 脚本关卡
```
website-diff "$OLD_URL" "$NEW_URL" --format json -o result.json
EXIT_CODE=$?
if [ $EXIT_CODE -eq 2 ]; then
echo "BLOCKING: high-significance changes detected"
exit 1
elif [ $EXIT_CODE -eq 1 ]; then
echo "WARNING: minor changes detected"
fi
```
## 工作原理
### Wayback Machine 清理
当检测到 Wayback Machine URL 时，工具会自动：
1. **移除头部工件** -- 剥离 Wayback Machine 注入的分析脚本、播放脚本和横幅 CSS。
2. **移除页脚注释** -- 移除归档元数据和版权声明。
3. **还原 URL** -- 将带有 `web.archive.org/web/…/` 前缀的 URL 转换回原始 URL。
4. **标准化内容** -- 处理归档引入的空白和格式差异。
### 显著性评分
每个检测到的变更都会被分类：
| 级别 | 示例 |
|-------|----------|
| **High** | 结构变更、内容文本、meta 标签、脚本、样式表 |
| **Medium** | 属性变更、内联样式、div/span 修改 |
| **Low** | 空白、注释、细微格式 |
### 智能对比
Diff 引擎：
- 专注于有意义的内容变更
- 忽略时间戳和自动生成的 ID 等噪音
- 提供每个变更的上下文
- 按显著性分组结果以便快速审查
## 输出格式
### 文本（默认）
摘要统计、显著性细分以及带有上下文行的详细变更。
### JSON
用于程序化处理的结构化输出：
```
{
"summary": {
"total_changes": 15,
"added": 5,
"removed": 3,
"modified": 7,
"high_significance": 2,
"medium_significance": 8,
"low_significance": 5
},
"changes": [
{
"type": "modified",
"old_text": "...",
"new_text": "...",
"significance": "high"
}
]
}
```
### 统一 Diff
标准统一 diff 格式，兼容 `patch` 和代码审查工具。
## 与类似工具的比较
| 功能 | **Website-Diff** | [htmldiff](https://github.com/ian-ross/htmldiff) | [diff2html](https://github.com/rtfpessoa/diff2html) | [BackstopJS](https://github.com/garris/BackstopJS) | [Percy](https://percy.io) |
|---------|:-:|:-:|:-:|:-:|:-:|
| HTML 感知语义 Diff | Yes | Yes | No | No | No |
| Wayback Machine 工件清理 | **Yes** | No | No | No | No |
| 显著性评分 | **Yes** | No | No | No | No |
| 视觉（截图）对比 | Yes | No | No | Yes | Yes |
| 多浏览器支持 | Yes | N/A | N/A | Yes | Yes |
| 全站爬取和比较 | Yes | No | No | Yes | No |
| Markdown 报告生成 | Yes | No | No | No | No |
| CI/CD 退出代码 | Yes | No | No | Yes | Yes |
| 自托管 / 无 SaaS | Yes | Yes | Yes | Yes | No |
| 免费且开源 | GPL-3.0 | MIT | MIT | MIT | Freemium |
## 测试
```
pip install -r requirements-dev.txt
# Run tests
pytest tests/ -v
# Run with coverage
pytest tests/ -v --cov=website_diff --cov-report=html
```
## 许可证
本项目基于 **GNU General Public License v3.0** (GPL-3.0) 授权。详情请参阅 [LICENSE](LICENSE) 文件。
本软件**不**用于商业用途。
标签：CI/CD 集成, DevOps 工具, Docker, Java RMI, Python, Selenium, Wayback Machine, 代码清洁, 像素差异检测, 内容变更监控, 反汇编, 多浏览器测试, 安全防御评估, 快照比对, 文档结构分析, 无后门, 版本对比, 网站历史分析, 网页差异比对, 网页截图, 视觉回归测试, 请求拦截, 逆向工具