257 lines
7.1 KiB
Markdown
257 lines
7.1 KiB
Markdown
# Wiki Sync Tool - Enhanced Version
|
||
|
||
一个用于同步和跟踪 MediaWiki 网站变更的 Python 工具，支持双语对比和精确的行号定位。
|
||
|
||
## 功能特点
|
||
|
||
- 🔄 自动同步 MediaWiki 网站的最新更改
|
||
- 📝 生成带语法高亮的 HTML diff 文件，清晰展示变更内容
|
||
- 💾 保存页面完整内容供离线查阅
|
||
- ⏰ 支持增量同步，只获取上次同步后的新变更
|
||
- 🔍 支持按时间点或特定页面进行同步
|
||
- 📁 智能文件组织，区分新页面和变更页面
|
||
- 🌐 **新增**：自动同步中文翻译版本
|
||
- 🎯 **新增**：精确的行号映射，点击英文行自动定位到中文对应行
|
||
- 📊 **新增**：生成精美的双语对比网页
|
||
- 🎨 **新增**：现代化的UI设计，支持同步滚动和高亮显示
|
||
- 🧭 **新增**：导航浮窗功能，快速跳转到变更点
|
||
- 🗂️ **新增**：分类存储，主文件和参考文件分开管理
|
||
|
||
## 安装
|
||
|
||
1. 确保你已经安装了 Python 3.6+
|
||
2. 克隆此仓库：
|
||
```bash
|
||
git clone <repository-url>
|
||
cd wiki-sync-tool
|
||
```
|
||
3. 安装依赖：
|
||
```bash
|
||
pip install requests python-dotenv
|
||
```
|
||
|
||
## 配置
|
||
|
||
创建一个 `.env` 文件并配置你的 MediaWiki API 地址：
|
||
|
||
```env
|
||
# 英文版 Project Diablo 2 Wiki API 地址
|
||
WIKI_API_URL_EN=https://wiki.projectdiablo2.com/w/api.php
|
||
|
||
# 中文版 Project Diablo 2 Wiki API 地址
|
||
WIKI_API_URL_CN=https://wiki.projectdiablo2.cn/w/api.php
|
||
```
|
||
|
||
或者复制提供的示例配置文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本全量同步
|
||
|
||
同步自上次运行以来的所有更改：
|
||
|
||
```bash
|
||
python sync.py --run
|
||
```
|
||
|
||
首次运行时，会同步过去 24 小时内的更改。
|
||
|
||
### 指定时间起点同步
|
||
|
||
从指定时间开始同步：
|
||
|
||
```bash
|
||
python sync.py --since 2025-11-28T00:00:00Z --run
|
||
```
|
||
|
||
### 同步特定页面
|
||
|
||
只同步特定页面的最新更改：
|
||
|
||
```bash
|
||
python sync.py --title "Amazon Basin" --run
|
||
```
|
||
|
||
### 同步特定页面并更新时间戳
|
||
|
||
同步特定页面并在完成后更新全局时间戳：
|
||
|
||
```bash
|
||
python sync.py --title "Amazon Basin" --update-timestamp --run
|
||
```
|
||
|
||
### 查看帮助
|
||
|
||
```bash
|
||
python sync.py --help
|
||
```
|
||
|
||
## 输出文件
|
||
|
||
每次运行都会在 `wiki_sync_output` 目录下创建一个以时间戳命名的子目录，并按照以下结构组织文件：
|
||
|
||
```
|
||
wiki_sync_output/[时间戳]/
|
||
├── new_pages/ # 新创建的页面目录
|
||
│ └── [页面名].full.txt # 只保存页面的完整内容
|
||
│
|
||
└── changed_pages/ # 有变更的页面目录
|
||
├── [页面名].full.txt # 页面的最新完整内容
|
||
├── [页面名].cn.txt # 对应的中文翻译内容
|
||
├── [页面名].comparison.html # 双语对比页面（带导航功能）
|
||
│
|
||
└── files/ # 参考文件目录
|
||
├── [页面名].diff.html # 官方 MediaWiki diff HTML
|
||
├── [页面名].diff.txt # 文本格式的 diff
|
||
└── [页面名].old.txt # 历史版本内容
|
||
```
|
||
|
||
### 文件说明
|
||
|
||
**主要文件（日常使用）**：
|
||
- `.full.txt` - 页面的完整内容（新页面和变更页面都有）
|
||
- `.cn.txt` - 中文翻译内容（仅变更页面）
|
||
- `.comparison.html` - 双语对比网页（仅变更页面）
|
||
|
||
**参考文件（技术细节）**：
|
||
- `.diff.html` - MediaWiki原生HTML diff
|
||
- `.diff.txt` - 文本格式的diff（类似git diff）
|
||
- `.old.txt` - 页面的历史版本内容
|
||
|
||
### 双语对比网页特性
|
||
|
||
生成的双语对比网页具有以下高级功能：
|
||
|
||
1. **导航浮窗** 🧭
|
||
- 左侧浮窗显示所有变更点的导航列表
|
||
- 点击导航项可快速跳转到对应位置
|
||
- 滚动页面时自动高亮当前可见的变更
|
||
- 支持使用 Ctrl+1~9 快速跳转到对应编号的变更
|
||
|
||
2. **精确行号映射**：
|
||
- 英文diff中的每一行都标注了对应的中文行号
|
||
- 点击英文任意行，自动高亮并滚动到对应的中文行
|
||
|
||
3. **交互式体验**：
|
||
- 鼠标悬停时预览对应的中文行
|
||
- 点击时高亮显示对应关系
|
||
- 平滑滚动动画效果
|
||
|
||
4. **视觉设计**：
|
||
- 现代化的UI设计
|
||
- 标准的diff配色（绿色新增、红色删除、灰色未变更）
|
||
- 响应式布局，支持移动端查看
|
||
|
||
5. **字符级diff高亮**：
|
||
- 显示精确到字符级别的变更差异
|
||
- 新增内容使用绿色背景高亮
|
||
- 删除内容使用红色背景高亮
|
||
|
||
### Diff 文件示例
|
||
|
||
文本diff格式示例：
|
||
|
||
```
|
||
--- old_version
|
||
+++ new_version
|
||
@@ -10,7 +10,7 @@
|
||
This is line 10
|
||
-This line will be removed
|
||
+This line will be added
|
||
This is line 12
|
||
```
|
||
|
||
HTML diff特性：
|
||
- 绿色背景表示新增内容
|
||
- 红色背景表示删除内容
|
||
- 左侧彩色竖线标识变更类型
|
||
- +/- 标记清晰显示变更位置
|
||
- 删除内容带有删除线效果
|
||
|
||
## 技术细节
|
||
|
||
### 智能文件组织策略
|
||
|
||
工具根据页面是否为新建来组织文件：
|
||
|
||
- **新页面**：判断依据是diff文本以"新创建页面"开头
|
||
- 只保存 `.full.txt` 文件
|
||
- 不生成中英对比（因为不存在变更）
|
||
|
||
- **变更页面**：
|
||
- 保存主要文件在 `changed_pages` 目录
|
||
- 将技术细节文件放在 `files` 子目录
|
||
|
||
### 行号解析机制
|
||
|
||
工具使用自定义的diff解析器，能够精确提取：
|
||
- Hunk头部的行号范围信息
|
||
- 每一行变更对应的旧版本和新版本行号
|
||
- 增删改上下文行的准确位置
|
||
|
||
### 导航系统实现
|
||
|
||
1. **动态生成导航项**：
|
||
- 扫描所有 `.change-block` 元素
|
||
- 自动提取变更类型（新增/替换/删除）
|
||
- 生成预览文本和行号信息
|
||
|
||
2. **模板字符串修复**：
|
||
- 使用正确的 `"${changeId}"` 语法
|
||
- 确保选择器能够正确匹配DOM元素
|
||
|
||
### 中文页面搜索策略
|
||
|
||
1. 首先尝试精确匹配页面标题
|
||
2. 如果失败，则进行模糊搜索
|
||
3. 支持标题中的空格和特殊字符处理
|
||
|
||
### 使用说明
|
||
|
||
**查看新页面**：
|
||
- 进入 `new_pages` 目录
|
||
- 查看对应的 `.full.txt` 文件获取页面完整内容
|
||
|
||
**处理变更页面**：
|
||
- 主要查看 `changed_pages` 目录下的文件
|
||
- 使用 `.comparison.html` 进行双语对比和导航
|
||
- 查阅 `.cn.txt` 获取中文翻译参考
|
||
- 参考 `.full.txt` 获取最新的英文内容
|
||
|
||
**技术细节参考**：
|
||
- 查看 `files` 目录了解详细的变更信息
|
||
- 包含官方diff、文本diff和历史版本
|
||
|
||
### 目录组织示例
|
||
|
||
```
|
||
wiki_sync_output/
|
||
├── 20251211_221150/
|
||
│ ├── new_pages/ # 新创建的页面
|
||
│ │ └── New_Page-20251211_220123-12345.full.txt
|
||
│ │
|
||
│ └── changed_pages/ # 有变更的页面
|
||
│ ├── To Do-20251211_124712-21941.full.txt
|
||
│ ├── To Do-20251211_124712-21941.cn.txt
|
||
│ ├── To Do-20251211_124712-21941.comparison.html
|
||
│ │
|
||
│ └── files/ # 参考文件
|
||
│ ├── To Do-20251211_124712-21941.diff.html
|
||
│ ├── To Do-20251211_124712-21941.diff.txt
|
||
│ └── To Do-20251211_124712-21941.old.txt
|
||
│
|
||
└── 20251211_193512/
|
||
└── ...
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request。 |