dota2-match-calendar/README.md

Dota 2 Calendar Sync v4.4

自动从 Liquipedia 获取 Dota 2 Tier 1 比赛信息并同步到 Google Calendar，支持自动更新比赛结果、时间变更、智能管理TBD占位事件、自动清理过期和重复比赛。

功能

• 自动获取 Liquipedia 上的 Tier 1 级别 Dota 2 比赛
• 包括 The International、Major、Premier 级别赛事
• 自动创建 Google Calendar 事件
• 自动更新已完成比赛的结果和比分
• 检测并更新比赛时间变更（赛程调整时自动同步）
• 智能管理TBD占位事件（自动更新队伍信息，删除过期和被取代的事件）
• 自动清理重复比赛（优先保留已完成的比赛记录）
• 增强的TBD事件清理（删除已结束但仍包含TBD的事件，删除与确认比赛同时间的TBD占位符）
• 避免重复添加已存在的比赛
• 支持 dry-run 模式进行测试

前置要求

1. Google Calendar 设置

你需要将你的 Google Calendar 分享给服务账号：

1. 打开 Google Calendar
2. 进入日历设置
3. 在"与特定人员共享"部分，添加：
   • Email: calendar-bot@tunpok.iam.gserviceaccount.com
   • 权限: "进行更改"（Make changes to events）

2. Python 环境

使用 pyenv 和虚拟环境：

pyenv activate test-venv
pip install -r requirements.txt

使用方法

基本用法

# 激活虚拟环境
source $(pyenv prefix test-venv)/bin/activate

# 运行同步（使用默认的 primary 日历）
python sync_dota2_matches.py

# 指定特定的 Google Calendar
python sync_dota2_matches.py --calendar-id "091325d4ea74ad78387402db1a428390c4779dff573322863b6fca00194da024@group.calendar.google.com"

# 使用调试模式查看详细日志
python sync_dota2_matches.py --log-level DEBUG

Dry Run 模式

在实际添加事件之前，先测试看看会添加哪些比赛：

python sync_dota2_matches.py --dry-run

命令行参数

• --calendar-id: Google Calendar ID 或邮箱地址（默认: primary）
• --dry-run: 只显示将要添加的比赛，不实际创建事件
• --no-results: 跳过更新已完成比赛的结果
• --no-time-updates: 跳过更新比赛时间变更
• --credentials: 服务账号凭据文件路径（默认: credentials.json）
• --log-level: 设置日志级别 (DEBUG, INFO, WARNING, ERROR)

文件说明

• sync_dota2_matches.py: 主同步脚本（v4版本 - 优化版）
• legacy/: 历史版本脚本存档
• credentials.json: Google 服务账号凭据（需要自行添加）
• requirements.txt: Python 依赖包
• run_sync.sh: 便捷运行脚本
• TIMEZONE_INFO.md: 时区转换说明
• CHANGELOG.md: 版本更新历史
• legacy/: 旧版本脚本存档

功能特点

1. 智能匹配识别：

   • 自动识别 Tier 1、Premier、Major 级别赛事
   • 支持 The International (TI) 赛事
   • 提取比赛格式（Bo1、Bo3、Bo5）
   • 智能去重：相同时间、相同轮次的 TBD 比赛只保留一个代表
   • TBD比赛保护：确保TBD vs TBD的比赛不会被错误标记为已完成
   • 改进的TBD匹配：1小时时间窗口匹配，更好处理赛程调整
   • 重复比赛清理：自动检测并删除同队伍的重复事件
   • TBD事件自动删除：当队伍确定后自动删除对应的TBD占位符
   • 增强的过期事件清理：自动删除已结束但仍包含TBD的事件
   • 智能TBD vs TBD处理：删除与确认比赛在同一时间段的TBD vs TBD占位符

2. 日历事件管理：

   • 自动设置比赛时长（根据 Bo 格式估算）
   • 添加 30 分钟提醒
   • 使用蓝色标记 Dota 2 事件
   • 避免重复添加
   • 自动更新已完成比赛的结果
   • 在标题添加完成标记（✓ + 比分）
   • TBD 比赛队伍确定后自动更新
   • 自动清理过期的TBD占位事件

3. 错误处理：

   • 网络请求超时处理
   • API 错误重试
   • 详细的错误日志
   • 改进的比分解析：避免将时间(19:00)误识别为比分

定时运行

可以设置 cron job 定期运行同步：

# 编辑 crontab
crontab -e

# 每天早上 9 点运行同步
0 9 * * * cd /Users/ching/develop/dota2-calendar && /Users/ching/.pyenv/versions/3.10.14/envs/test-venv/bin/python sync_dota2_matches.py --calendar-id your-email@gmail.com

注意事项

1. 确保已经将日历分享给服务账号邮箱
2. 首次运行建议使用 --dry-run 测试
3. Liquipedia 页面结构可能会变化，如果解析失败需要更新解析逻辑

故障排查

如果没有找到比赛：

1. 检查 Liquipedia 页面是否可以访问
2. 运行 python fetch_liquipedia.py 查看页面结构
3. 确认是否有正在进行的 Tier 1 赛事

如果无法添加到日历：

1. 确认已经正确分享日历给服务账号
2. 检查 credentials.json 文件是否有效
3. 确认使用了正确的 calendar-id