一个可在本机或 Linux 服务器运行的雨课堂课堂监听与 LLM 辅助答题面板。它支持多账号扫码登录,在用户通过雨课堂 App 手动签到后监听课堂事件,从课件中解析题目,调用 OpenAI 兼容模型生成答案,并可按题目截止时间选择是否自动提交。
Warning
本项目不会代替用户签到,且默认关闭自动提交。自动答题或自动提交可能违反学校规定、课程要求或平台条款。请只在获得明确授权的测试、研究或个人学习场景中使用,并自行承担使用后果。
- 多账号扫码登录、隔离会话与服务重启后恢复
- 同一课堂的多个账号共享解题结果,每道题只请求模型一次
- 设置页可选择雨课堂、荷塘雨课堂、长江雨课堂或黄河雨课堂,默认长江雨课堂
- 通过课堂 WebSocket 实时接收发题、延时、切换课件与下课事件
- 解析单选、多选、投票、填空、主观和判断题
- 支持 OpenAI 兼容的文字模型与视觉模型
- 根据真实截止时间、延时事件和提交请求余量安排提交
- 对模型 JSON、选项标识和填空数量进行校验
- 模型等待超时时,选择题随机选择合法选项兜底并标明来源;提前发生的图片、模型或答案格式错误仍跳过
- 账号授权失效、连续监课异常和课堂连接异常邮件提醒
- 服务器管理员账号登录、远程访问、一键部署和安全更新检测
- 浏览器面板仅显示账号状态、配置和运行日志
- 运行日志独立保存到
logs/panel.jsonl,重启和重连后恢复最近记录并保留原始时间
| 组件 | 职责 |
|---|---|
static/index.html |
本地控制面板、账号登录、模型配置与实时日志 |
server.py |
aiohttp Web 服务、多账号生命周期、课堂监听、截止时间与提交调度 |
ykt_core.py |
雨课堂 HTTP 客户端、课件题目解析、图片处理、LLM 请求与答案校验 |
email_notifier.py |
SMTP 配置校验、异常通知、冷却去重和测试邮件 |
scripts/ |
Linux systemd 一键部署、版本检测、更新和失败回滚 |
test_ykt_web.py |
不访问雨课堂和模型服务的离线单元测试 |
核心流程如下:
扫码登录 -> 雨课堂 App 手动签到 -> 连接课堂 WebSocket -> 同步课件 -> 解析题目
-> 调用 LLM -> 校验答案 -> 仅预览或按截止时间提交
每个账号拥有独立的 Cookie、课堂令牌、监听器、题目状态和提交时序;所有账号共享当前模型配置。同一雨课堂部署中,处于相同 lessonId 的账号会按题目 ID 和内容版本复用同一份模型答案,各账号仍使用自己的凭据分别提交。题干、选项顺序或图片改变后会重新解题。不同课堂和不同题目不会共享答案。停止全部监课或退出全部账号时,共享解题任务和缓存会一并清理。
- Python 3.10 或更高版本
- 可用的雨课堂账号,以及用于扫码登录和手动签到的雨课堂 App/微信
- 支持
/models和/chat/completions的 OpenAI 兼容模型服务 - 图片题需要模型服务支持
image_url多模态消息和 Data URI 图片
进入项目目录后创建虚拟环境并安装依赖:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item config.example.json config.json
python server.py在 Linux 或 macOS 上,将激活和复制命令替换为:
source .venv/bin/activate
cp config.example.json config.json随后打开 http://127.0.0.1:8765/。本机手动运行默认监听回环地址;监听非本机地址时必须通过环境变量配置至少 12 位的管理员密码。
也可以不预先创建 config.json:程序会使用内置安全默认值启动,并在首次通过面板保存配置时写入该文件。复制示例文件主要用于提前查看和调整高级参数。
Debian 12(含 12.1)可按 Debian 12 部署指南 操作,包含 HTTPS、SSH 隧道、首次配置和后续更新步骤。
有公网域名时,推荐让部署脚本同时配置 Caddy 和 HTTPS。开始前先完成以下准备:
- 将域名的
A记录指向服务器公网 IPv4;只有服务器确实可通过 IPv6 访问时才保留AAAA记录 - 在云安全组和服务器防火墙中放行 TCP
80、443 - 确认没有其他 Web 服务占用
80、443;已有 Nginx、Apache 或 Caddy 的服务器应改用下文的“已有反向代理”方式 - 确认服务器可以访问软件源、Caddy 官方签名仓库和公开证书签发服务
随后在支持 systemd 的 Linux 服务器上执行。--domain 只填写域名,不要包含 https://、端口或路径:
git clone https://github.com/zhu961212/ykt_web.git
cd ykt_web
sudo bash scripts/deploy.sh --domain panel.example.com域名模式会安装并配置 Caddy;系统软件源没有 caddy 时,部署器会核对官方仓库签名密钥指纹并添加 Caddy stable 软件源。Caddy 监听公网 80/443、申请并自动续期证书,再将 HTTP 和 WebSocket 请求转发到 127.0.0.1:8765。Python 服务仍以非 root 账号运行,不会直接监听特权端口 443;部署器还会自动启用安全 Cookie 和本机反向代理信任。完成后访问 https://panel.example.com/,无需附加端口。首次签发证书可能需要短暂等待。
不要把应用的 --port 设置为 443。公网只需开放 80/443,不应开放后端端口 8765。
如果暂时没有域名,并且只在可信内网中使用,可以不传 --domain:
sudo bash scripts/deploy.sh此模式默认监听 0.0.0.0:8765,通过 http://服务器IP:8765 访问且不提供传输加密,不建议直接暴露到公网。
两种模式都会创建独立服务账号、虚拟环境和 systemd 服务,并生成管理员账号与强随机密码。首次凭据保存在仅 root 可读的 /opt/ykt-web/admin/service.env,更新不会覆盖。
已经使用旧版脚本部署的服务器,需要先完成一次普通更新,让服务器取得支持 --domain 的新版部署器,再配置域名:
sudo /opt/ykt-web/admin/update.sh
sudo /opt/ykt-web/admin/deploy.sh --domain panel.example.com旧版部署器不认识 --domain,因此不要把域名参数加到第一次更新命令中。第二条命令只需配置现有版本,不要求使用 --force,并会保留账号、模型配置、登录状态和管理员凭据。完成迁移后,应从云安全组和服务器防火墙中关闭原先对公网开放的 8765。
需要停用安装器管理的 HTTPS 并恢复直接端口访问时执行:
sudo /opt/ykt-web/admin/deploy.sh --no-domain该命令只移除本项目管理的 Caddy 站点,不会删除 Caddy 或改动其他站点;随后应按实际网络边界重新配置防火墙。
登录后可在“设置 -> 管理员密码”直接设置新密码,无需再次输入旧密码;为降低会话被盗风险,改密要求管理员在最近 10 分钟内登录。新密码需为 12-256 个可见字符,支持常见符号、空格和中文。密码使用随机盐 PBKDF2 哈希保存,修改后所有旧管理会话和 WebSocket 立即失效。service.env 中的密码仅作为首次部署和紧急恢复凭据。
忘记面板密码时,编辑环境文件,将 YKT_ADMIN_RESET=1,重启后用文件中的管理员账号密码登录并在设置页更新密码;随后把 YKT_ADMIN_RESET 改回 0 再重启:
sudoedit /opt/ykt-web/admin/service.env
sudo systemctl restart ykt-web手动运行时也可以启用远程管理:
YKT_HOST=0.0.0.0 YKT_PORT=8765 \
YKT_ADMIN_USERNAME=admin YKT_ADMIN_PASSWORD='StrongPass_2026' \
python server.py如果服务器已有统一管理的 Nginx、Caddy 或其他 HTTPS 入口,请不要让自动部署覆盖其站点配置。应让 ykt_web 只监听回环地址,并由现有代理转发请求;在 service.env 同时设置 YKT_SECURE_COOKIE=1 和 YKT_TRUST_PROXY=1,传递 X-Forwarded-Proto、X-Forwarded-Host,并让 X-Forwarded-For 的最后一项为代理实际看到的客户端 IP,然后重启服务。程序只信任来自本机回环地址的这些代理头。
先确认 DNS、端口监听和两个服务的状态:
getent ahosts panel.example.com
sudo ss -lntp | grep -E ':(80|443|8765)\b'
sudo systemctl status ykt-web caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager
curl -fsS http://127.0.0.1:8765/api/health
curl -I https://panel.example.com/后端健康检查成功但 HTTPS 仍失败时,通常是域名尚未解析到当前服务器、不可达的 AAAA 记录、云安全组或防火墙未放行 80/443,或者端口已被其他服务占用。证书签发依赖公网能够通过域名访问服务器,单纯把域名解析到 IP 并不会绕过这些条件。
首次部署如果在 Caddy 安装或 HTTPS 配置阶段失败,安装器会停止服务并保留失败候选。修复网络或更新安装器后,回到最初克隆的项目目录执行 git pull,再重新运行同一条 sudo bash scripts/deploy.sh --domain ... 命令即可;无需删除 /opt/ykt-web。首次部署成功前,/opt/ykt-web/admin/deploy.sh 可能尚不存在。
只检查远端是否有新版本,不修改运行中的服务:
sudo /opt/ykt-web/admin/update.sh --check工具会区分 up-to-date、update-available、local-ahead 和 diverged,并显示当前与远端提交。确认有可快进更新后执行:
sudo /opt/ykt-web/admin/update.sh候选版本会先在隔离目录安装依赖并运行编译和测试,随后才切换服务;config.json、session.json、logs/ 和管理员凭据会保留。启动或健康检查失败时自动恢复上一版本,成功后只保留最近 1 个完整回滚版本。
通过 --domain 配置的域名会保存在部署元数据中。以后正常执行 update.sh 无需再次传入域名,更新后仍使用原来的 HTTPS 地址;证书申请和续期由 Caddy 独立管理。--check 只检查项目版本,不会重新配置代理或申请证书。
- 在“雨课堂服务器”中选择学校使用的部署;默认是长江雨课堂。
- 在“模型配置”中填写 API 地址和 API Key,点击“获取模型”,选择模型后保存。
- 点击“添加账号”,使用微信扫码登录。
- 在雨课堂 App 中手动完成签到。
- 保持“自动答题并提交”关闭,先通过日志确认课程、题目解析和模型返回均正常。
- 只有在你确认有权这样做时,才开启自动提交。
“登录后自动开始监课”默认关闭;开启后也只会启动课程检测,不会自动签到。可从面板单独启动、停止、检测或移除账号,也可以统一控制全部账号。
- API 地址可以是服务基础地址,也可以是完整的
/chat/completions地址。 - 远程 API 必须使用 HTTPS;HTTP 只允许
localhost、127.0.0.1或::1。 - 同一 API 服务下,保存时将 Key 留空会保留现有值;切换 API 服务时必须填写对应的新 Key。
- API Key 写入本机
config.json,状态接口和网页不会回显其内容。 - “图片输入”默认开启,切换 API 地址或模型后也默认开启。所选服务和模型需要支持图片输入;可取消勾选并保存来关闭,已有配置中显式保存的关闭值会保留。
- “思考强度”默认使用模型服务的设置,不额外发送参数。接口支持
reasoning_effort时可主动选择强度;较低强度可用于测试延迟,但应同时核对准确率。不同兼容服务和模型支持的取值可能不同,不支持时请恢复默认。
在“邮件通知”中填写 SMTP 地址、端口、加密方式、用户名、授权码、发件地址和收件地址,保存后先发送测试邮件。仅支持 SSL/TLS 或 STARTTLS,不支持明文 SMTP。
SMTP 授权码只写入本机 config.json,接口与网页不会回显。修改 SMTP 主机、端口、加密方式或用户名时必须重新填写授权码。相同账号的同类故障按配置间隔去重,避免重连期间重复发信。
config.example.json 中的主要设置:
| 设置 | 说明 |
|---|---|
server |
雨课堂部署,可选 yuketang、pro、changjiang、huanghe,默认 changjiang |
llm.base_url |
OpenAI 兼容 API 的基础地址或 Chat Completions 地址 |
llm.api_key |
模型服务 API Key;不要提交真实值 |
llm.model |
用于解题的模型 ID |
llm.reasoning_effort |
可选思考强度;空字符串为服务默认,显式选择后才发送,需当前模型/API 支持 |
llm.vision_enabled |
是否启用图片输入,默认开启;显式设为 false 可关闭 |
lesson.poll_interval |
课程和手动签到状态的轮询间隔 |
lesson.enter_delay_seconds |
发现新课堂后等待多久再检测签到并连接课堂,默认 5 秒;设为 0 可立即检测,仍需先在 App 手动签到 |
email.enabled |
是否发送账号与监课异常邮件 |
email.smtp_host / email.smtp_port |
SMTP 服务器地址与端口 |
email.security |
ssl 或 starttls |
email.password |
SMTP 授权码;不会通过接口回显 |
email.cooldown_seconds |
相同故障邮件的最短间隔 |
bot.dry_run |
true 时只记录建议答案,不提交 |
bot.auto_start_watching |
登录或恢复会话后是否自动开始监课 |
bot.answer_delay_seconds |
相对出题时间的最短作答延迟 |
bot.request_margin_seconds |
在真实截止前为提交 HTTP 请求预留的时间,默认 1.5 秒 |
雨课堂的课件页通常都带有 cover,因此项目不会仅凭 cover 判断为图片题。解析器会综合题干、选项和课件页内容:
- 题干和选项均有完整文字时,忽略通用课件封面并发送纯文本请求。
- 题干或选项直接包含图片、文字明确引用图表、文字内容缺失,或课件页存在显著视觉元素时,才附带相关图片。
- 题干兼容课件中的
body、title、content和stem等字段。
来自受信任雨课堂 CDN 的图片会在本机下载、校验实际格式并转换为 Data URI 后发送给模型,避免模型服务无法访问课件 CDN。当前限制为最多 8 张图片、单张最多 4 MiB、合计最多 12 MiB;下载不跟随重定向。
图片输入被手动关闭、图片提前下载失败、模型提前返回错误或答案未通过结构校验时,该题会被跳过。只有模型等待预算耗尽时,才对具备合法选项的选择题随机兜底;不会固定选择首项。
文字解析会保留数学比较符和字典选项的原始标识。某一题的选项字段损坏时,只阻止该题解题,不中断其他题的解析。
每道题单独维护时间窗口:
题目开始 = 服务端 WebSocket 事件时间(异常或缺失时使用本机接收时间)
真实截止 D = 题目开始 + 题目限时 + 累计延时
模型等待截止 = D - 提交请求余量(默认 1.5 秒)
当前可用解题预算 = 模型等待截止 - 当前时间
仅保留提交请求余量。以限时 45 秒、余量 1.5 秒为例,若在题目开始时立即处理,理想解题预算为 43.5 秒。课件获取、图片准备、网络传输和此前已经消耗的时间都会占用这份预算,实际可用时间可能更短。
使用默认余量时,模型最多等待到 D - 1.5 秒。模型在此之前返回有效答案就安排提交;如果仍未返回,单选、投票和判断题从真实选项中随机选择一项,多选题随机选择非空合法子集,随即使用剩余请求时间提交。填空、主观、选项缺失或解析失败的题目不编造随机答案。模型接口、图片下载或答案格式在等待截止前提前失败时,仍跳过该题,不会提前随机提交。
日志和题目事件会标明“随机兜底”及 source=random_timeout,不能据此认为模型已解出答案。晚到账号优先复用在模型等待截止前已经完成的同题答案;否则同题多账号共用一次随机结果,迟到的模型答案或错误不会覆盖它。最短作答延迟如果会占用请求余量,则忽略该延迟;随机兜底始终立即提交。仅预览模式仍只展示答案,不提交。
所有答案都只能在真实截止 D 之前发起请求,提交 HTTP 请求也只在真实截止前的剩余时间内等待。预留 1.5 秒不能保证网络请求一定完成。提交请求超时、连接中断或没有明确回执时记录“结果未确认”。当前课堂中该题会暂停自动提交,即使重放事件补上或改变时间戳也不自动重发,需要先核对平台记录。
教师在等待课件或模型期间延长答题时间时,当前等待会跟随新的真实截止和解题窗口继续,不重复调用模型。没有收到延时事件时仍按原窗口停止;模型接口自身的请求超时仍然有效。
面板历史日志独立保留最近 1000 条,文件最多约 4 MiB,不再被状态事件挤出。日志写入 logs/panel.jsonl,重新打开页面或重启服务后可恢复,时间显示为事件发生的日期和时间,重连不重复添加同一条记录。安装此功能以前的记录不会自动补入,可通过 journalctl -u ykt-web --no-pager 查看系统保留的历史。提交返回 code=0 只表示服务器接收请求,不能据此判断答案正确。
运行完整离线测试:
python -m unittest discover -v测试使用模拟 HTTP、WebSocket、模型和时间事件,不需要真实账号、课堂或 API Key。GitHub Actions 会在受支持的 Python 版本上执行同一测试命令。
config.json含 API Key,session.json含登录 Cookie;两者只能保存在可信设备上,且不应提交到 Git。- 远程管理必须设置
YKT_ADMIN_USERNAME和至少 12 位的YKT_ADMIN_PASSWORD;部署脚本会自动配置。 - 管理员登录能阻止未授权操作,但 HTTP 本身不加密;公网域名必须使用 HTTPS 反向代理。
config.json、session.json和/opt/ykt-web/admin/service.env应保持0600权限。- 建议为模型服务使用权限受限、额度受限且可随时撤销的 Key。
- 如果凭据曾被提交或泄露,应立即撤销并重新生成;只从 Git 历史删除文件并不能使旧凭据失效。
- 安全漏洞请按 SECURITY.md 私下报告,不要在公开 Issue 中披露利用细节或凭据。
- 雨课堂使用非公开接口,平台升级后可能需要更新协议解析。
- 不同 OpenAI 兼容服务对模型列表、JSON 输出和图片消息的支持并不完全一致。
- 模型答案可能错误;启用自动提交前应先在仅预览模式验证。
- 本项目不保证适用于所有学校的私有化部署或所有题型变体。
扫码会话迁移和课堂令牌处理流程参考了 AneryCoft/course_helper,课程发现与课件解析则结合当前客户端行为进行了适配。感谢相关公开源码项目提供的研究基础。
本项目采用 GNU General Public License v3.0 only 发布,以保持与参考项目的许可证兼容性。版权与第三方来源说明见 NOTICE;上游项目仍分别适用其各自许可证。
本项目是非官方项目,与雨课堂、学堂在线及任何学校或课程方均无隶属、授权或背书关系。项目按“原样”提供,不保证可用性、准确性、兼容性或不会造成数据、账号、学业及其他损失。使用者有责任遵守适用法律、平台服务条款、学校规章、课程诚信要求和教师要求。