shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsAPI key required

codeforces-api

Codeforces 竞赛平台数据查询与分析。支持：比赛查询（列表/排名/rating变化/提交/hack）、 用户查询（信息/rating历史/提交记录/博客）、题库检索（按标签/rating筛选）、 博客阅读、最近动态。公开端点通过 WebFetch 直接调用，需认证端点（user.friends、group.isManager） 通过 scripts/cf_api.py 计算 apiSig 签名。 当用户提到 Codeforces/CF/CF比赛/CF rating/CF提交/CF题目 时触发。 不适用于非 Codeforces 平台（如 AtCoder/洛谷/LeetCode）。

personAuthor: user_e267c873hubcommunity
downloadDownload package

Codeforces API 查询与分析

通过 Codeforces 官方 API 查询比赛、用户、题库、博客等数据。 全部 18 个 API 端点均可用（16 公开 + 2 需认证）。

触发条件

以下任意关键词或场景均触发本 Skill：

  • 提到 Codeforces / CF / CF比赛 / CF rating / CF提交 / CF题目 / CF用户 / CF博客
  • 查询比赛排名、rating 变化、Hack 记录
  • 查询用户信息、rating 历史、提交记录
  • 搜索或推荐题目（按标签、rating 范围）
  • 查看博客内容或评论
  • 需要调用 user.friends（好友列表）

不触发: 其他 OJ 平台（AtCoder / 洛谷 / LeetCode / CodeChef 等）。

工作流决策树

根据用户意图选择端点分组，详细参数查阅 references/api_endpoints.md：

用户意图
├── 比赛相关 ─────────── contest.* 端点
│   ├── 比赛列表                → contest.list
│   ├── 比赛排名                → contest.standings
│   ├── 比赛后 rating 变化      → contest.ratingChanges
│   ├── 比赛提交状态            → contest.status
│   └── 比赛 Hack 记录          → contest.hacks
│
├── 用户相关 ─────────── user.* 端点
│   ├── 用户信息 / rating       → user.info
│   ├── rating 变化历史          → user.rating
│   ├── 用户提交记录             → user.status
│   ├── 用户博客列表             → user.blogEntries
│   ├── 有 rating 用户列表      → user.ratedList
│   └── 好友列表（需认证）       → user.friends
│
├── 题库相关 ─────────── problemset.* 端点
│   ├── 搜索题目                 → problemset.problems
│   └── 最近提交                 → problemset.recentStatus
│
├── 博客相关 ─────────── blogEntry.* 端点
│   ├── 博客内容                 → blogEntry.view
│   └── 博客评论                 → blogEntry.comments
│
├── 系统与群组 ───────── 其他端点
│   ├── CF 最近动态              → recentActions
│   ├── 系统健康状态             → system.status
│   └── 群组成员管理（需认证）   → group.isManager
│

公开端点速查表

以下 16 个端点直接用 WebFetch 调用，无需任何脚本：

| 方法 | 必需参数 | WebFetch URL | |---|---|---| | blogEntry.comments | blogEntryId | https://codeforces.com/api/blogEntry.comments?blogEntryId={id} | | blogEntry.view | blogEntryId | https://codeforces.com/api/blogEntry.view?blogEntryId={id} | | contest.hacks | contestId | https://codeforces.com/api/contest.hacks?contestId={id} | | contest.list | — | https://codeforces.com/api/contest.list | | contest.ratingChanges | contestId | https://codeforces.com/api/contest.ratingChanges?contestId={id} | | contest.standings | contestId | https://codeforces.com/api/contest.standings?contestId={id} | | contest.status | contestId | https://codeforces.com/api/contest.status?contestId={id} | | problemset.problems | — | https://codeforces.com/api/problemset.problems | | problemset.recentStatus | count | https://codeforces.com/api/problemset.recentStatus?count={n} | | recentActions | maxCount | https://codeforces.com/api/recentActions?maxCount={n} | | system.status | — | https://codeforces.com/api/system.status | | user.blogEntries | handle | https://codeforces.com/api/user.blogEntries?handle={h} | | user.info | handles | https://codeforces.com/api/user.info?handles={h} | | user.ratedList | — | https://codeforces.com/api/user.ratedList | | user.rating | handle | https://codeforces.com/api/user.rating?handle={h} | | user.status | handle | https://codeforces.com/api/user.status?handle={h} |

可选参数、多值格式、返回结构详见 references/api_endpoints.md。

WebFetch 环境注意事项（Claude Code 特有）

⚠️ 本节仅适用于 Claude Code 环境。WorkBuddy、OpenClaw 等其他 agent 不受影响—— 它们的 fetch 实现不做 claude.ai 预检查,可直接访问 codeforces.com,无需任何额外配置。

公开端点默认通过 WebFetch 调用。Claude Code 的 WebFetch 在抓取目标 URL 前,会先请求 https://claude.ai/api/web/domain_info?domain=<目标域名> 做一次安全校验:

  • 若网络环境中 claude.ai 被墙或被企业防火墙拦截,该预检查失败,WebFetch 报错 Unable to verify if domain ... is safe to fetch,即使目标站(codeforces.com)本身可正常访问。
  • 即便开启全局代理,只要代理未正确处理对 claude.ai 的请求,WebFetch 仍会失败。

解决方案(任选其一):

  1. 关闭预检查(推荐):在用户级 settings.json 加入: 
    { "skipWebFetchPreflight": true }
    修改后需重启 Claude Code 生效。
  2. curl 兜底:WebFetch 不可用时,改用 Bash 执行 curl 直连 API,返回与 WebFetch 一致: 
    curl -s "https://codeforces.com/api/user.info?handles=tourist"
    返回 JSON 形如 {"status":"OK","result":[...]},其中 result 字段即各端点文档描述的结构。

认证端点(user.friends、group.isManager)在任何 agent 下都不受影响——它们走 scripts/cf_api.py, 用 urllib 直接请求 codeforces.com,不经过 WebFetch 预检查。

认证端点

以下 2 个端点需要认证，调用 scripts/cf_api.py 计算 SHA512 签名：

user.friends — 好友列表

python scripts/cf_api.py user.friends --key YOUR_KEY --secret YOUR_SECRET
python scripts/cf_api.py user.friends onlyOnline=true --key YOUR_KEY --secret YOUR_SECRET

group.isManager — 群组管理权限

判断指定用户是否为某个 Codeforces 群组（Group）的管理员。

python scripts/cf_api.py group.isManager groupCode=GROUP_CODE handles=username1 --key YOUR_KEY --secret YOUR_SECRET

| 参数 | 类型 | 说明 | |---|---|---| | groupCode | string | 必填，群组代码（群组 URL 中的标识） | | handles | string | 必填，分号分隔的用户 handle 列表，最多 10000 个 |

返回: 一个 map，key 为 handle，value 为 boolean（是否管理员）。

前置条件: 用户需要 Python 3.11+（使用 uv 管理，脚本仅依赖标准库）。

获取 API Key:

  1. 登录 https://codeforces.com/settings/api
  2. 点击 "Generate" 获取 key 和 secret
  3. 将 key 和 secret 通过命令行参数传入（不要写入任何文件）

详细的 apiSig 签名原理见 references/auth_guide.md。

频率限制

Codeforces API 限制：

  • 公开请求：每 2 秒最多 1 次请求
  • 认证请求（带 apiKey + apiSig）：最高 每秒 5 次请求

当需要多次请求时（如批量查多个用户、翻页查提交记录）：

  • 公开请求每次 WebFetch 调用后等待至少 2 秒
  • 认证请求（cf_api.py）可更快，但仍建议至少间隔 200ms
  • 如果收到 HTTP 429 或 status=FAILED 带限流提示，等待 5 秒后重试

领域知识参考

以下知识用于增强查询质量和结果解读，详见 references/domain_knowledge.md：

| 知识领域 | 用途 | |---|---| | Rating 分段（灰绿青蓝紫橙红） | 解读用户水平，输出时标注颜色 | | 题目标签中文解释 | 理解 dfs and similar = 深度优先搜索等 | | 比赛类型（Div1–4 / Edu / Global） | 理解比赛难度定位 | | 提交状态（OK / WA / TLE / ...） | 解读提交结果 | | 练习推荐策略 | 按 rating±200、薄弱标签推荐题目 |

输出格式约定

  • 用户信息用表格展示：handle、rating（配颜色标记）、rank、maxRating
  • 提交记录用表格展示：题目、状态（✅ OK / ❌ WA / ⏱ TLE 等）、语言、时间
  • 比赛排名展示前 10 名，超过则说明总数
  • 题目推荐列表格式：题目链接（contestId/index）、名称、rating、标签、通过人数
  • rating 变化如数据超过 20 条，只展示最近 20 场
  • 所有 API 返回的 creationTimeSeconds 转为可读日期（YYYY-MM-DD HH:MM）