diff --git a/README.md b/README.md index ec46a83..112ecc0 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,13 @@ - 💾 保存页面完整内容供离线查阅 - ⏰ 支持增量同步,只获取上次同步后的新变更 - 🔍 支持按时间点或特定页面进行同步 -- 📁 自动组织输出文件到时间戳目录 +- 📁 智能文件组织,区分新页面和变更页面 - 🌐 **新增**:自动同步中文翻译版本 - 🎯 **新增**:精确的行号映射,点击英文行自动定位到中文对应行 - 📊 **新增**:生成精美的双语对比网页 - 🎨 **新增**:现代化的UI设计,支持同步滚动和高亮显示 +- 🧭 **新增**:导航浮窗功能,快速跳转到变更点 +- 🗂️ **新增**:分类存储,主文件和参考文件分开管理 ## 安装 @@ -90,36 +92,64 @@ python sync.py --help ## 输出文件 -每次运行都会在 `wiki_sync_output` 目录下创建一个以时间戳命名的子目录,包含生成的文件: +每次运行都会在 `wiki_sync_output` 目录下创建一个以时间戳命名的子目录,并按照以下结构组织文件: -- `页面标题-时间戳-revid.diff.html` - MediaWiki原生HTML diff文件 -- `页面标题-时间戳-revid.diff.txt` - 文本格式的diff(类似git diff) -- `页面标题-时间戳-revid.full.txt` - 页面的最新完整内容 -- `页面标题-时间戳-revid.old.txt` - 页面的历史版本内容(如果有变更) -- `页面标题-时间戳-revid.cn.txt` - 中文翻译内容(如果找到) -- `页面标题-时间戳-revid.comparison.html` - **双语对比网页**(如果找到中文翻译) +``` +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. **精确行号映射**: +1. **导航浮窗** 🧭 + - 左侧浮窗显示所有变更点的导航列表 + - 点击导航项可快速跳转到对应位置 + - 滚动页面时自动高亮当前可见的变更 + - 支持使用 Ctrl+1~9 快速跳转到对应编号的变更 + +2. **精确行号映射**: - 英文diff中的每一行都标注了对应的中文行号 - 点击英文任意行,自动高亮并滚动到对应的中文行 -2. **交互式体验**: +3. **交互式体验**: - 鼠标悬停时预览对应的中文行 - 点击时高亮显示对应关系 - 平滑滚动动画效果 -3. **视觉设计**: +4. **视觉设计**: - 现代化的UI设计 - 标准的diff配色(绿色新增、红色删除、灰色未变更) - 响应式布局,支持移动端查看 -4. **同步滚动**: - - 左右两栏滚动位置自动同步 - - 便于对比相同位置的内容 +5. **字符级diff高亮**: + - 显示精确到字符级别的变更差异 + - 新增内容使用绿色背景高亮 + - 删除内容使用红色背景高亮 ### Diff 文件示例 @@ -144,6 +174,18 @@ HTML diff特性: ## 技术细节 +### 智能文件组织策略 + +工具根据页面是否为新建来组织文件: + +- **新页面**:判断依据是diff文本以"新创建页面"开头 + - 只保存 `.full.txt` 文件 + - 不生成中英对比(因为不存在变更) + +- **变更页面**: + - 保存主要文件在 `changed_pages` 目录 + - 将技术细节文件放在 `files` 子目录 + ### 行号解析机制 工具使用自定义的diff解析器,能够精确提取: @@ -151,24 +193,58 @@ HTML diff特性: - 每一行变更对应的旧版本和新版本行号 - 增删改上下文行的准确位置 +### 导航系统实现 + +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_152702/ -│ ├── Amazon_Basin-20251211_152645-12345.diff.html -│ ├── Amazon_Basin-20251211_152645-12345.diff.txt -│ ├── Amazon_Basin-20251211_152645-12345.full.txt -│ ├── Amazon_Basin-20251211_152645-12345.old.txt -│ ├── Amazon_Basin-20251211_152645-12345.cn.txt -│ └── Amazon_Basin-20251211_152645-12345.comparison.html -└── 20251211_153127/ +├── 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/ └── ... ```