如何为yatori-go-console新增一个学习平台:yatori-go-core v3 adapter扩展机制与策略映射实战
如何为yatori-go-console新增一个学习平台:yatori-go-core v3 adapter扩展机制与策略映射实战
Yatori课程助手 yatori-go-console 是一款不依赖浏览器的独立自动刷课程序,支持英华慕课、超星学习通、学习公社、重庆工程学院 CQIE 等数十个平台。本文带你完整走一遍「如何为 yatori-go-console 新增一个学习平台」的实战流程,重点拆解 yatori-go-core v3 的 adapter 扩展机制与 console 侧的策略映射,即使你是 Go 新手也能按步骤上手 🛠️
一、先理解架构变化:平台代码不再写在 console 里
很多老教程还在讲「在 logic 下新建一个平台目录」,那是 v2 时代的做法。从 v3 开始,项目做了一个关键架构调整:
console 已迁移到 yatori-go-core v3 统一 SDK,平台差异全部由 core 的 adapter 处理,console 不再按平台维护刷课代码。
也就是说,新增平台的工作被清晰地切成了两半:
| 分工 | 位置 | 职责 |
|---|---|---|
| 平台驱动(adapter) | yatori-go-core 的 internal/driver/<平台> |
登录、拉课程、拉章节、提交进度、作业、考试等协议细节 |
| 策略映射 | yatori-go-console | 刷课档位、答题来源、课程过滤、日志与通知等「用户侧策略」 |
console 对每个账号只走一条统一的调用链路(见 logic/README.md):
yatori.New -> client.Login -> client.Courses -> client.Tree
-> client.Study -> client.Works / DoWork -> client.Exams / DoExam
这条链路对所有平台完全一致,是理解整个扩展机制的钥匙。
二、准备工作:拿到代码与环境
开始二开前,先克隆仓库并准备环境(完整说明见 README.md):
git clone https://gitcode.com/gh_mirrors/ya/yatori-go-console
- Go 版本要求与 go.mod 保持一致:Go 1.27.3,同时需要 gcc(SQLite 走 CGO)
- console 依赖的 SDK 版本在 go.mod 中锁定为
yatori-go-core/v3 v3.0.12;若需要联调未发布的 core,go.mod 底部预留了replace注释行,可临时指向本地 core 目录(push 前记得删掉) - 只打包发布的可执行文件可用 Dockerfile 参考容器化部署方式
三、第一步:在 core 侧实现平台 adapter
真正要「逆向」的地方在 core 仓库。新增平台时,在 core 的 internal/driver/<平台名> 下实现一个新 adapter,需要覆盖的能力大致是:
- 登录:账密登录,最好同时支持 Cookie 登录(
CapCookieLogin),Web 多账号并发时开销最小 - 课程与章节:实现
Courses(课程列表)和Tree(章节树,展开为视频/文档/作业/考试节点) - 学习提交:实现
Study,支持普通模式的start -> progress -> finish三段式;如果平台一次提交就能完成,直接在驱动里按单次提交处理 - 作业与考试(可选):实现
Works/DoWork、Exams/DoExam,并用能力位(Capability)声明是否支持 - 能力声明:adapter 通过
Capabilities()声明支持哪些能力,console 会先用yatori.Supports(client, ...)探测,不支持的能力会自动跳过,而不是报错
💡 参考旧平台实现:console 的 logic/legacy/ 目录保留了 v2 时代各平台(英华、学习通、CQIE、青书学堂等)的完整代码,虽然不参与编译,但非常适合作为协议逆向的对照资料。
四、第二步:在 console 侧注册平台标识
平台标识的解析集中在 logic/runner/platform.go 的 ParsePlatform 函数里。它底层调用 yatori.ParsePlatform,额外做的事情是兼容旧配置里的套壳平台别名,例如 CANGHUI(仓辉)本质是英华套壳平台,v3 没有独立 adapter,于是直接映射到 yatori.YingHua:
if value == "CANGHUI" {
return yatori.YingHua, nil
}
如果你的新平台也是某个已支持平台的「换皮」版本,不需要新写 adapter,照着这个模式加一条别名映射即可,这也是 README 里建议用户把「CANGHUI」改成「YINGHUA」的底层原因。
同文件里的 NormalizeURL 负责把用户填的完整页面地址统一成 origin(如 https://xxx.haiqikeji.com),新平台如果 URL 规则特殊,可以在这里补充归一化逻辑。
五、第三步:配置 console 的策略映射
这是 console 的核心职责:把「用户配置」翻译成「SDK 行为」。所有策略字段都定义在 config/Config.go 的 CoursesCustom 结构里,执行逻辑在 logic/runner/runner.go 中。
刷课档位 videoModel 映射
| 档位 | 通用语义 | 典型平台行为 |
|---|---|---|
| 0 | 不刷视频 | 只处理作业/考试 |
| 1 | 普通模式 | 顺序学习,节点间隔随机 10-60 秒 |
| 2 | 快速/秒刷 | 英华暴力模式、海旗/CQIE 单次提交秒刷、WeLearn 刷完成度 |
| 3 | 平台特化 | 学习通=多任务点并发、英华=去红模式、其他平台按普通处理 |
平台差异通过一组判断函数收敛:fastStudy(该档位是否走单次提交完成)、singleSubmitPlatform(天然一次提交的平台)、concurrentCourses / concurrentNodes(学习通的多课程/多任务点并发)。新平台如果支持秒刷,只需把平台标识加进对应的 switch 分支。
答题来源 autoExam 映射
| 取值 | 答题来源 | 说明 |
|---|---|---|
| 0 | 不答题 | — |
| 1 | AI 答题 | 使用全局配置的 AI 大模型 |
| 2 | 外置题库 | 海旗特例:使用内置标准答案 |
| 3 | 按 AI 处理 | 学习通内置 AI 暂未开放时的兜底 |
映射逻辑在 answerSource 函数(logic/runner/runner.go),新平台若有特殊的答题来源,在这里加分支即可。
其余策略项
examAutoSubmit:考完是否自动交卷includeCourses/excludeCourses:课程过滤,学习公社等平台支持「项目名-->课程标签」写法,见matchCourse函数- 课程开课时间校验:
courseDateAllowed会自动跳过未在开课期内的课程 - 停止信号、彩色日志、邮件通知(
InformEmails)、完成提示音:跨平台通用,无需按平台适配
六、验证新平台:测试 + Web 模式
- 单元测试:logic/runner/runner_test.go 提供了一个
fakeClient,模拟实现了yatori.Client接口的假客户端,你可以在本地仿照它为新平台写策略映射测试;logic/runner/node_rules_test.go 演示了节点完成/续学的边界判定(如 99.x% 视作完成)。运行:
go test ./logic/runner/...
- Web 模式端到端验证:构建前端后以 Web 模式启动(步骤见 README.md),账号保存在本地
yatori.db(SQLite),在网页「账号管理」中添加新平台账号、课程配置和 AI 配置,观察日志与邮件通知是否正常:
./yatori-go-console --web
- CLI 模式验证:在
config.yaml中填入新平台账号,accountType写平台标识(全大写),首次启动时程序还会交互式引导生成配置,见 logic/Lunch.go
七、常见坑位速查
| 现象 | 原因与处理 |
|---|---|
| 提示「不支持平台」 | ParsePlatform 无法识别标识,检查 core 是否注册了新平台,或补充别名映射 |
| 作业/考试环节被跳过 | adapter 未声明 CapWorks/CapExams 能力,或返回了 IsUnsupported 错误 |
| 视频「学不完」反复重刷 | 平台完成度普遍是 99.x%,console 已按 99% 阈值容错,自定义节点时注意对齐该口径 |
| 并发多账号时登录挤掉会话 | v3 单客户端带锁,并发走多开克隆(buildWorkerClients);APP 登录模式会自动回退为串行 |
| OCR 初始化 panic | onnxruntime 只能初始化一次,console 已做捕获重试(callWithOCRRecover),无需处理 |
总结
为 yatori-go-console 新增学习平台的正确姿势已经非常清晰:协议逆向和平台行为交给 yatori-go-core v3 的 adapter(internal/driver/<平台>),console 只负责平台标识注册与策略映射。理解「统一调用链 + 能力声明 + 策略档位」这三层结构后,无论是接入一个全新平台,还是给已有平台加秒刷/去红能力,都只是在对应层里加一个分支的事。🚀
