add README&&dit actions

2026-07-20 18:38:04 +08:00
parent f9f3ec3a9d
commit c504b98126
3 changed files with 194 additions and 3 deletions
@@ -2,7 +2,10 @@ name: Update Contests & Commit

 on:
  schedule:
-    - cron: '*/5 * * * *'   # 每5分钟执行一次
+    - cron: '7/15 * * * *'  # 每15分钟执行一次，避开整点高峰
+  push:
+    branches:
+      - master
  workflow_dispatch:          # 允许手动触发

 jobs:
@@ -29,8 +32,8 @@ jobs:
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "[email protected]"
-          git add contests.json
+          git add contests.json contests_all.json
          git diff --staged --quiet || (
-            git commit -m "Update contests.json"
+            git commit -m "Update contest data"
            git push
          )
@@ -0,0 +1,94 @@
+# OI Contest Fetch
+
+en/[zh](README_zh.md)
+
+Fetch programming contest schedules from several online judge platforms and export them as JSON files. The repository also includes a small PHP page that can read the generated JSON and display upcoming contests.
+
+## Supported Platforms
+
+- Codeforces
+- AtCoder
+- USACO
+- Luogu
+
+## Output Files
+
+Running the fetch script writes JSON files to the repository root:
+
+- `contests.json`: contests that have not ended yet, including upcoming and currently running contests.
+- `contests_all.json`: contests that finished within the last 30 days.
+
+Each contest item has this shape:
+
+```json
+{
+  "platform": "AtCoder",
+  "title": "AtCoder Beginner Contest 468",
+  "start_time": 1784980800,
+  "end_time": 1784986800,
+  "status": "upcoming",
+  "url": "https://atcoder.jp/contests/abc468"
+}
+```
+
+`start_time` and `end_time` are Unix timestamps in seconds. `status` can be one of:
+
+- `finished`
+- `running`
+- `upcoming`
+
+## Requirements
+
+- Python 3
+- PHP, only if you want to use the page under `server/`
+
+Python packages:
+
+```bash
+pip install requests beautifulsoup4
+```
+
+## Usage
+
+Run the fetch script from the repository root:
+
+```bash
+python fetch_contests.py
+```
+
+After a successful run, the script prints counts similar to:
+
+```text
+Total upcoming contests: 13
+Total contests finished in last 30 days: 139
+```
+
+## Web Page
+
+`server/index.php` reads the public raw GitHub URL for `contests.json`, caches it locally for 5 minutes, and renders upcoming contests with a client-side countdown.
+
+If you deploy it yourself, update this constant in `server/index.php` if your repository path or branch changes:
+
+```php
+define('JSON_URL', 'https://raw.githubusercontent.com/hanyixuanten/OI-contest-fetch/master/contests.json');
+```
+
+The cache file is written next to `index.php` as `contests_cache.json`, so the web server process needs write permission for the `server/` directory.
+
+## Automation
+
+A typical automation flow is:
+
+1. Run `python fetch_contests.py` on a schedule.
+2. Commit the updated JSON files.
+3. Push them to GitHub.
+4. Let `server/index.php` read the latest `contests.json` from GitHub raw content.
+
+For GitHub Actions, install the Python dependencies before running the script.
+
+## Notes
+
+- AtCoder uses the AtCoder Problems API and falls back to the official AtCoder contest page for upcoming contests when needed.
+- Luogu requires a session request and content-only request headers, so the script uses `requests.Session()`.
+- USACO schedule data depends on the current layout of the official USACO contests page. If USACO has no future schedule published, it may produce no upcoming USACO contests.
+- Network or upstream API changes can temporarily reduce the number of fetched contests.
@@ -0,0 +1,94 @@
+# OI Contest Fetch
+
+[en](README.md)/zh
+
+从多个在线评测平台抓取编程竞赛日程，并导出为 JSON 文件。仓库中还包含一个简单的 PHP 页面，可以读取生成的 JSON 并展示即将到来的比赛。
+
+## 支持平台
+
+- Codeforces
+- AtCoder
+- USACO
+- 洛谷
+
+## 输出文件
+
+运行抓取脚本后，会在仓库根目录写入以下 JSON 文件：
+
+- `contests.json`：尚未结束的比赛，包括尚未开始和正在进行中的比赛。
+- `contests_all.json`：最近 30 天内已经结束的比赛。
+
+每条比赛记录的结构如下：
+
+```json
+{
+  "platform": "AtCoder",
+  "title": "AtCoder Beginner Contest 468",
+  "start_time": 1784980800,
+  "end_time": 1784986800,
+  "status": "upcoming",
+  "url": "https://atcoder.jp/contests/abc468"
+}
+```
+
+`start_time` 和 `end_time` 是秒级 Unix 时间戳。`status` 可能是以下值之一：
+
+- `finished`：已结束
+- `running`：进行中
+- `upcoming`：尚未开始
+
+## 环境要求
+
+- Python 3
+- PHP，仅在需要使用 `server/` 下的页面时需要
+
+Python 依赖：
+
+```bash
+pip install requests beautifulsoup4
+```
+
+## 使用方式
+
+在仓库根目录运行抓取脚本：
+
+```bash
+python fetch_contests.py
+```
+
+成功运行后，脚本会输出类似下面的统计信息：
+
+```text
+Total upcoming contests: 13
+Total contests finished in last 30 days: 139
+```
+
+## 网页展示
+
+`server/index.php` 会读取公开的 GitHub Raw 地址中的 `contests.json`，在本地缓存 5 分钟，并渲染带客户端倒计时的比赛列表。
+
+如果你自行部署，并且仓库路径或分支发生变化，需要修改 `server/index.php` 中的这个常量：
+
+```php
+define('JSON_URL', 'https://raw.githubusercontent.com/hanyixuanten/OI-contest-fetch/master/contests.json');
+```
+
+缓存文件会以 `contests_cache.json` 的名字写在 `index.php` 同目录下，因此 Web 服务器进程需要拥有 `server/` 目录的写入权限。
+
+## 自动化
+
+一个常见的自动化流程是：
+
+1. 定时运行 `python fetch_contests.py`。
+2. 提交更新后的 JSON 文件。
+3. 推送到 GitHub。
+4. 让 `server/index.php` 从 GitHub Raw 读取最新的 `contests.json`。
+
+如果使用 GitHub Actions，请在运行脚本前安装 Python 依赖。
+
+## 注意事项
+
+- AtCoder 使用 AtCoder Problems API；在需要时会回退解析 AtCoder 官方比赛页面以获取即将开始的比赛。
+- 洛谷需要先建立会话，并带上 content-only 请求头，因此脚本使用了 `requests.Session()`。
+- USACO 赛程依赖 USACO 官网当前页面结构。如果 USACO 暂未发布未来赛程，可能不会产生即将开始的 USACO 比赛。
+- 网络问题或上游 API/页面结构变化，可能会暂时影响抓取到的比赛数量。