# educoder-cli

**Repository Path**: iceeey/educoder-cli

## Basic Information

- **Project Name**: educoder-cli
- **Description**: EduCoder / 头歌 CLI and reusable Skill
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EduCoder CLI + Skill

这是一个用于头歌（EduCoder / TouGe）的全自动刷题 Skill。准备好登录凭证后，它可以自动筛选未截止且未完成的实验，读取题目，生成和修复代码，处理多文件与多关卡任务，并提交评测。

## 一键安装

在 PowerShell 中执行：

```powershell
git clone https://github.com/hecongnan/educoder-cli.git
Set-Location educoder-cli
py -3 -m pip install -e .
educoder version
```

如果 `educoder` 找不到，可以用：

```powershell
py -3 .\main.py version
```

## 前置条件：登录凭证

安装并使用 Skill 前，必须先准备有效的头歌登录凭证。先验证现有凭据：

```powershell
educoder status --json
```

没有凭据时，在本机终端执行：

```powershell
educoder login --login 你的手机号或邮箱
```

密码只在本机终端输入，不要粘贴到聊天中。凭据默认保存到：

```text
%APPDATA%\educoder-cli\credentials.json
```

如果密码登录被头歌风控拦截，请先在浏览器登录 `https://www.educoder.net`，再按本地文档配置 `_educoder_session` 和 `autologin_trustie` Cookie。不要把 Cookie 写入仓库或聊天记录。

## 本地答案缓存

评测通过的答案会自动保存到仓库的 `cache/` 目录。缓存同时记录课堂、实验、关卡标题、远程路径、使用次数和时间，下次遇到同一关卡时可以直接复用，不必重新读取完整题目或生成答案。

缓存是索引式结构，不会每次都扫描全部答案文件：

- `cache/index.json`：索引、课堂/实验别名、使用次数、最近使用时间和关卡分组。
- `cache/entries/<key>.json`：单个关卡的答案与元数据。

默认最多保存 **66 个实验**；一个实验可以包含多个关卡答案，淘汰时按整个实验处理。超过上限后会删除使用次数最少的实验；次数相同时优先删除最久未使用的实验。新写入的实验在本次淘汰中受到保护。

`cache/` 已加入 `.gitignore`，其中包含答案内容，不要提交到仓库或发送到聊天中。

常用命令：

```powershell
# 先查缓存（--no-code --peek 只判断是否存在，不输出答案、不增加使用次数）
educoder cache lookup --course "课程名称" --homework "实验名称" --no-code --peek --json

# 命中后直接提交缓存答案：不传 --file 时，CLI 会按当前关卡自动匹配缓存
educoder submit --course "课程名称" --homework "实验名称" --timeout 90 --json

# 查看缓存
educoder cache list --json
educoder cache stats --json

# 把之前已经通过、但当时还没启用缓存的关卡补进缓存
educoder cache save --course "课程名称" --homework "实验名称" --json

# 删除某个实验的缓存，或清空全部缓存
educoder cache remove --course "课程名称" --homework "实验名称"
educoder cache clear --yes
```

多关卡实验可用 `--challenge <关卡 ID 或标题>` 精确查看某一关的缓存。`--no-cache` 可以临时关闭本次提交的缓存读写；`--cache-dir` 或环境变量 `EDUCODER_CACHE_DIR` 可以覆盖缓存目录。

首次使用实验时，不要默认先手动点击“评测”。Skill 会先保存代码并调用 `game_build`，再根据接口业务结果和任务轮询状态判断是否已经进入评测：

- `had_done: 0` 只表示该关卡之前没有完成过评测，本身不是失败；如果 `game_build` 返回成功并且任务可以排队，Skill 会继续等待编译和测试结果。
- 只有接口明确返回“需要首次评测”或类似的首次评测拒绝，才需要在头歌网页端打开该实验并手动点击一次“评测”，然后重新执行 Skill。
- 如果任务没有 `game_identifier` 或其他必要的评测上下文，需要先在头歌网页端打开该实验完成初始化；这属于任务上下文缺失，不是答案代码错误。

## 安装 Skill

确认 `educoder status --json` 返回已认证后，再安装 Skill。仓库里的 `skills/educoder-cli` 是 Skill 本体，安装到 Codex 的本地 Skill 目录：

```powershell
$skillRoot = Join-Path $env:USERPROFILE ".codex\skills\educoder-cli"
New-Item -ItemType Directory -Force $skillRoot | Out-Null
Copy-Item .\skills\educoder-cli\* $skillRoot -Recurse -Force
```

重启或刷新 Codex 后，可以在聊天中直接说：

```text
使用 educoder-cli，完成我当前课程中尚未截止且未完成的头歌实验。
```

也可以这样使用：

```text
使用 educoder-cli，查看我所有课程中还没完成的实验，只处理尚未截止的实验。
```

```text
使用 educoder-cli，完成“软件设计模式_24级”课程里未完成的实验，遇到失败先根据编译输出修复。
```

```text
使用 educoder-cli，检查当前实验是否还有下一关，全部通过后告诉我每一关的结果。
```

Skill 会自动检查登录状态、筛选未截止实验、读取题目、生成或修复代码并提交评测。它会保留远程文件路径和多关卡顺序，并在每个关卡通过后继续下一关。

需要手动运行 CLI 命令时，请查看 cli原项目 GitHub：[hecongnan/educoder-cli](https://github.com/hecongnan/educoder-cli)。