study-tool
666 lines
33 KiB
Markdown
666 lines
33 KiB
Markdown
# 学习平台插件开发指南
|
||
|
||
欢迎来到学习平台插件开发指南！本章节将会引导你如何开发学习平台的插件，在这之前你需要具备以下基础知识：
|
||
|
||
- 1. 一定的 Python 开发编程经验
|
||
- 2. 一定的 Git / GitHub 使用经验
|
||
- 3. 会用浏览器开发者工具看请求、Cookie 和页面结构
|
||
|
||
> **文档定位**：本文只讲「怎么接入一个平台」——目录怎么放、类怎么写、每个槽位返回什么、怎么联调。
|
||
> 分层与整体结构见 [architecture.md](architecture.md)，仓库级开发约束见 [AGENTS.md](../AGENTS.md)。
|
||
>
|
||
> **一句话原则**：插件只回答「这一步在这个站点怎么做」，流程编排只有一份，在引擎里。
|
||
> 新增平台不需要改 `engine.py`、`routes/`、前端，也不需要改 `load_builtin()`。
|
||
|
||
## 环境准备
|
||
|
||
### 1. Python 与依赖
|
||
|
||
- Python **3.10 ~ 3.14**。`ddddocr` 依赖 `onnxruntime`，后者只对这些版本的正式版发轮子；
|
||
3.15 / free-threaded / ARM 上会装不上。缺 `ddddocr` 只影响需要图形验证码识别的平台。
|
||
- 推荐用 uv（依赖版本已锁在 `uv.lock`）：
|
||
|
||
```bat
|
||
uv sync
|
||
```
|
||
|
||
- 没有 uv 就用 pip：
|
||
|
||
```bat
|
||
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
|
||
```
|
||
|
||
依赖清单见 [requirements.txt](../requirements.txt)，其中 `requests`、`beautifulsoup4`、`lxml`、`playwright`
|
||
是插件开发最常用的几个；标准协议、解析、编码一律优先用它们，不要手写底层实现。
|
||
|
||
### 2. 启动服务
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bat
|
||
uv run app.py
|
||
```
|
||
|
||
或者：
|
||
|
||
```bat
|
||
python app.py
|
||
```
|
||
|
||
默认监听 `127.0.0.1:8848`，浏览器打开 <http://127.0.0.1:8848>。
|
||
换端口 / 对外开放用环境变量，或把 `.env.example` 复制成根目录 `.env` 再改：
|
||
|
||
```bat
|
||
set PORT=8849 && python app.py
|
||
set HOST=0.0.0.0 && python app.py
|
||
```
|
||
|
||
`AUTH_TOKEN` 非空时页面和接口都要带 `?token=<值>`（浏览器会记住 cookie）；本机开发一般不用设。
|
||
|
||
启动日志里出现插件加载失败时，先看控制台 / 右上角「系统日志」，再按
|
||
[加载与启停](#加载与启停) 一节排查。
|
||
|
||
### 3. 只在改前端时才需要
|
||
|
||
前端源码在 `web/`（React + TypeScript + Vite + Tailwind），构建产物输出到 `static/` 并提交进仓库。
|
||
**插件开发通常不需要碰前端**；确实要改界面时，改完必须执行：
|
||
|
||
```bat
|
||
cd web
|
||
pnpm build
|
||
```
|
||
|
||
不要直接改 `static/` 里的产物。
|
||
|
||
### 4. 联调工具
|
||
|
||
| 工具 | 用途 |
|
||
| --- | --- |
|
||
| 浏览器 DevTools → Network | 看登录 / 列表 / 上报接口的 URL、请求体、返回体 |
|
||
| 浏览器 DevTools → Application → Cookies | 确认域名、`Path`、`HttpOnly`、会话 cookie 名 |
|
||
| 内置抓包（顶栏「抓包」） | 把真实页面 HTML 存成快照，用 `/api/snapshot/{sid}` 回看，适合分析服务端渲染页面 |
|
||
| `data/study.db`（SQLite） | 只读排查账号 / 设置 / 日志；不要手改表结构 |
|
||
| `plugins/<名字>/script/` | 该插件专属的探测 / 自测脚本，随插件一起删；通用的参考实现放根目录 `script/reference/` |
|
||
|
||
## 插件是什么
|
||
|
||
一个插件 = `../src/study_tool/plugins` 目录；一个平台 = 一个 `Platform` 子类 + 一次注册。
|
||
|
||
- **元数据**用类属性声明：`id`、`label`、`entries`。
|
||
- **能力**用「实现同名方法」绑定：实现了 `study` 就有学习能力，没实现就保持基类的 `None`。
|
||
- **注册**在模块末尾执行一次：`PLATFORM = registry.register(X())`。
|
||
|
||
### 一次学习的调用链
|
||
|
||
```
|
||
添加账号（GET /api/platforms 取平台下拉）
|
||
│
|
||
▼
|
||
POST /api/login ──────────► Platform.login(username, password)
|
||
│ └─► Platform.list_courses(s)（登录后顺手缓存课程）
|
||
▼
|
||
POST /api/courses ────────► Platform.session(cookies) → Platform.list_courses(s)
|
||
▼
|
||
POST /api/discover ───────► Platform.session(cookies) → Platform.discover(s, plan_id, project_id, name)
|
||
▼
|
||
POST /api/study ──────────► engine.study_worker
|
||
└─► Platform.session(cookies)
|
||
Platform.discover(...) # 重新拿最新进度
|
||
Platform.dump_cookies(s) # 回写会话
|
||
Platform.study(key, s, d, **opts)
|
||
▼
|
||
POST /api/stop ───────────► 置 RUNS[key]["status"] = "stopped"，插件在循环里自行退出
|
||
```
|
||
|
||
### 三条设计原则
|
||
|
||
1. **流程在引擎，站点细节在插件**：课程循环、会话续期、停止、日志格式都由引擎 / `runtime` 统一处理，
|
||
插件只写「这个站点怎么登录、怎么拿列表、怎么上报进度」。
|
||
2. **缺能力就不写**：平台没有反馈表就不要写反馈逻辑，没有密码登录就不要写 `login`；
|
||
前端按 `capabilities()` 决定显示哪些按钮。
|
||
3. **不反向依赖**：插件不能 import `engine` / `routes` / 前端；插件之间也不要互相 import。
|
||
|
||
## 插件项目结构
|
||
|
||
```
|
||
src/study_tool/plugins/
|
||
__init__.py 加载器：load_plugins / discover / set_enabled / reload
|
||
<名字>/
|
||
__init__.py 包说明（必需，写一句本插件的职责即可）
|
||
plugin.json 注册信息：id / title / name（只放元数据，不写能力绑定）
|
||
main.py class <名字>(Platform)：槽位实现 + 末尾 registry.register
|
||
utils/ 可选：按阶段拆的工具（http / login / course / learn / feedback / spa ...）
|
||
<实现模块>.py 可选：页面代际、复杂流程等，按需再拆
|
||
```
|
||
|
||
- **目录名就是插件名**：`GET /api/plugins` 的 `name`、启停 / 重载接口的 `{name}` 都用它。
|
||
- `main.py` 放平台类与注册；实现较复杂时按阶段拆到 `utils/` 或同目录模块
|
||
（登录、课程解析、学习上报各一块），保持单个文件可读。
|
||
- `../src/study_tool/platforms/` 只放运行时（`base` / `contract` / `errors` / `registry`），
|
||
**不要**把具体平台放回去；也不要为某个插件改 `platforms/`。
|
||
- 插件目录内互相引用用相对导入（`from .utils import course`）；跨插件不要引用。
|
||
- 目录内可以按需增加 `models/` 等子目录；没有实际代码的空目录不会参与加载。
|
||
|
||
## 插件元数据：`plugin.json`
|
||
|
||
`plugin.json` **只是注册信息**，不是配置 Schema，也不参与能力绑定。加载器只读 `id`、`title` 和 `kind`：
|
||
|
||
```json
|
||
{
|
||
"id": "gdgxk",
|
||
"title": "广东省教师继续教育管理平台",
|
||
"name": "gdgxk"
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | 是 | 平台 id，必须与 `Platform.id` 完全一致；会写进 `accounts.platform` / `course["platform"]`，**上线后不要改** |
|
||
| `title` | 是 | 插件名称，显示在「插件管理」弹窗里；建议写平台全称 |
|
||
| `name` | 否 | 人类可读的插件名；当前加载器不读取，实际以**目录名**为准，建议与目录名保持一致 |
|
||
| `kind` | 否 | 插件类型：缺省 `platform`（学习平台，注册到 `registry`）；`notify` = 推送渠道（注册到 `notify`，见「推送渠道插件」） |
|
||
|
||
补充说明：
|
||
|
||
- `id` 用稳定的英文小写标识（如 `guanyixue`、`gdgxk`），不要用中文、空格或会变动的版本号。
|
||
- 目录名、`plugin.json.name`、`Platform.id` 三者保持一致，最省心。
|
||
- 旧的 `description` / `link` 字段目前**不会被读取**：写了不报错，但插件清单、账号下拉里都不会显示。
|
||
需要描述就写在 `title` 或目录的 `README` / `__init__.py` 文档字符串里。
|
||
- 插件需要持久化自己的配置时，用 `database.get_setting(name)` / `database.set_setting(name, value)`，
|
||
键名加插件前缀（如 `"gdgxk.something"`），不要改系统设置 `llm`，也不要新建表。
|
||
- 缺少 `plugin.json` 的目录不会被扫描到；`id` 与类不一致时加载失败，日志里会出现
|
||
`插件 <目录名> 加载失败：插件 <目录名> 没有注册 id='...'`。
|
||
|
||
## 插件骨架
|
||
|
||
### `__init__.py`
|
||
|
||
```python
|
||
"""<平台名>插件：实现在 main.py，注册信息在 plugin.json。"""
|
||
```
|
||
|
||
### `main.py`
|
||
|
||
```python
|
||
"""<平台名>：登录 → 课程 → 发现 → 学习。"""
|
||
|
||
import requests
|
||
|
||
from study_tool import runtime
|
||
from study_tool.platforms import registry
|
||
from study_tool.platforms import Platform
|
||
from study_tool.platforms.errors import SessionExpired
|
||
|
||
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
|
||
DOMAINS = ("<平台域名>",) # cookie 域名过滤；和 entries 用同一组域名
|
||
|
||
|
||
class MyPlatform(Platform):
|
||
id = "<平台 id>" # 必须与 plugin.json 的 id 一致
|
||
label = "展示名" # 添加账号下拉、日志、插件管理里显示
|
||
entries = ("<登录入口域名>", "<学习入口域名>") # 识别页面属于本平台
|
||
|
||
# ---- 会话 ----------------------------------------------------------
|
||
def session(self, cookies=None):
|
||
s = requests.Session()
|
||
s.headers.update({"User-Agent": UA})
|
||
for c in cookies or []:
|
||
domain = c.get("domain") or ""
|
||
if not any(d in domain for d in DOMAINS):
|
||
continue
|
||
s.cookies.set(c["name"], c.get("value") or "", domain=domain.lstrip("."), path=c.get("path") or "/")
|
||
return s
|
||
|
||
def dump_cookies(self, s):
|
||
return [{"name": c.name, "value": c.value, "domain": c.domain, "path": c.path} for c in s.cookies]
|
||
|
||
# ---- 登录 / 账号级 --------------------------------------------------
|
||
def login(self, username, password):
|
||
s = self.session()
|
||
# 登录失败：raise RuntimeError("账号或密码错误")
|
||
# 会话失效：raise SessionExpired("...")
|
||
return s, (self.profile(s) if self.profile else "")
|
||
|
||
def list_courses(self, s):
|
||
# -> [{"name": ..., "plan_id": ..., "project_id": ..., "in_study": True}]
|
||
...
|
||
|
||
def profile(self, s):
|
||
return "<显示名>"
|
||
|
||
def renew_session(self, s):
|
||
# 无密码续期：成功 True，失败 False（不要抛异常）
|
||
return False
|
||
|
||
# ---- 发现 / 学习 ----------------------------------------------------
|
||
def discover(self, s, plan_id, project_id, name=""):
|
||
return {
|
||
"platform": self.id,
|
||
"course": name,
|
||
"progress": "0/0",
|
||
"info": "",
|
||
"user": "",
|
||
"courseware": [],
|
||
"feedback": [],
|
||
"test": [],
|
||
}
|
||
|
||
def study(self, key, s, d, **opts):
|
||
for cw in d["courseware"]:
|
||
if self._stopped(key):
|
||
return
|
||
runtime.log(key, "开始：%s" % cw["title"])
|
||
# ... 调接口上报进度；被踢回登录页时 raise SessionExpired("...")
|
||
runtime.log(key, "完成：%s" % cw["title"])
|
||
|
||
# ---- 私有辅助（_ 开头，不属于契约）-----------------------------------
|
||
def _stopped(self, key):
|
||
with runtime.RUNS_LOCK:
|
||
return (runtime.RUNS.get(key) or {}).get("status") == "stopped"
|
||
|
||
|
||
PLATFORM = registry.register(MyPlatform())
|
||
```
|
||
|
||
平台确实没有的阶段**不要写**，保持基类的 `None`；`capabilities()` 按「子类是否把它覆盖成方法」
|
||
推导能力名，前端据此决定显示哪些按钮。
|
||
|
||
## 槽位契约
|
||
|
||
| 槽位 | 方法签名 | 调用方 | 缺失时 |
|
||
| --- | --- | --- | --- |
|
||
| `study` | `(self, key, s, d, **opts)` | `engine.run_one_course` | 学习时报「平台 X 没有可用的学习实现」 |
|
||
| `discover` | `(self, s, plan_id, project_id, name)` | `run_one_course`、`/api/discover` | 报「平台 X 没有可用的课程发现实现」 |
|
||
| `session` | `(self, cookies) -> requests.Session` | 引擎与各路由 | 报「平台 X 没有实现 session」 |
|
||
| `dump_cookies` | `(self, s) -> [cookie]` | 登录 / 刷新 / 发现后回写前端 | 不回写 cookie，后续请求可能丢会话 |
|
||
| `login` | `(self, username, password) -> (session, user)` | `/api/login` | 不能密码登录，`/api/login` 报 `no_platform` |
|
||
| `list_courses` | `(self, s) -> [course]` | 登录后、`/api/courses` | 登录后课程为空，`/api/courses` 报 `no_platform` |
|
||
| `renew_session` | `(self, s) -> bool` | `SessionExpired` 时无密码续期 | 直接走密码重登 |
|
||
| `profile` | `(self, s) -> 显示名` | 登录后卡片显示 | 显示名为空 |
|
||
|
||
> 对「能完整跑起来」的平台，实际必需的是 `session` + `discover` + `study`。
|
||
> 想支持「添加账号 → 登录 → 自动带出课程」，再补 `login` / `list_courses` / `dump_cookies` / `profile`。
|
||
|
||
### `session` / `dump_cookies`
|
||
|
||
- `cookies` 是前端传回的列表，元素形如 `{"name", "value", "domain", "path"}`，`domain` 可能带前导点。
|
||
- 只接收本平台的 cookie（按 `DOMAINS` 过滤），否则会把别的站点 cookie 塞进来；
|
||
域名过滤**必须**在插件里做，引擎不兜底。
|
||
- 恢复时 `domain=domain.lstrip(".")`；`path` 缺省用 `/`。
|
||
- 过滤后为空时，`/api/courses` 会返回 `no_cookie`「保存的 cookie 全部被过滤」，
|
||
这通常说明 `DOMAINS` 写错或登录域与学习域不是同一个父域。
|
||
- `dump_cookies` 把 `requests.Session` 里的 cookie 原样导出即可；域名不要改写，
|
||
下次 `session()` 还要按它恢复。
|
||
|
||
### `login`
|
||
|
||
- 返回 `(session, user)`：`session` 是**已登录**的会话，`user` 是卡片上显示的名字。
|
||
- 登录失败抛 `RuntimeError`（带可读原因），路由会记进登录记录并回显给前端。
|
||
- 会话失效抛 `SessionExpired`，不要自己弹窗、不要自己重试整轮流程。
|
||
- 登录成功后引擎 / 路由会立刻调 `list_courses` 缓存课程；`list_courses` 失败不会让登录失败，
|
||
只会把 `warn` 带回去。
|
||
|
||
### `list_courses`
|
||
|
||
返回列表，每个课程至少包含：
|
||
|
||
```python
|
||
{
|
||
"name": "课程名",
|
||
"plan_id": "...", # 引擎 / 路由都按它定位课程
|
||
"project_id": "...", # 同上
|
||
"in_study": True, # 是否在学；False 表示已结束，前端会折叠
|
||
}
|
||
```
|
||
|
||
可附加 `section` / `status_label` / `info` / `progress` 等展示字段。
|
||
`in_study` 缺失会让 `/api/courses` 的计数直接报 `KeyError`，必须给。
|
||
|
||
### `discover`
|
||
|
||
签名 `(self, s, plan_id, project_id, name="")`，返回课程描述。**以下键引擎会直接取，必须存在**：
|
||
|
||
| 键 | 说明 |
|
||
| --- | --- |
|
||
| `platform` | 本平台 id；引擎据此再次 `registry.get()` 取学习实现 |
|
||
| `course` | 课程名 |
|
||
| `progress` | 进度文本，如 `"3/10"` |
|
||
| `info` | 说明文本（可为空串） |
|
||
| `user` | 显示名 |
|
||
| `courseware` | 课件列表 |
|
||
| `feedback` | 反馈表列表 |
|
||
| `test` | 测验列表 |
|
||
|
||
可选键：`generation`（`legacy` / `spa`，用于同一平台多代页面分发）、`train_id`、`page_url`、`need_join`。
|
||
|
||
三类活动列表的元素结构由插件自己定义（前端不依赖明细，学习时由插件消费），
|
||
建议统一成 `{"title", "done", ...}`，并带上学习所需的定位字段（`href` 或 `period_id`）。
|
||
三类都为空时引擎会直接报「课程里没有任何可识别的活动」。
|
||
|
||
`discover` 里如果切换了域名 / 换了新会话，记得让后续 `study` 用同一个 `s`；
|
||
引擎会在 `discover` 之后调用 `dump_cookies(s)` 把新会话存回去。
|
||
|
||
### `study`
|
||
|
||
- 收到的是 `discover` 的返回值 `d`，**不要重新发现**；需要最新数据可在内部再取一次页面。
|
||
- `s` 是已恢复的会话，所有请求都走它；不要自己新建裸 `requests` 会话。
|
||
- 循环里必须检查停止（见下一节），否则「停止」按钮无效。
|
||
- 会话失效抛 `SessionExpired`；其它可预期错误抛 `RuntimeError`，引擎会记到该账号的运行状态里。
|
||
- 全部活动处理完后正常返回即可，不需要返回值。
|
||
|
||
### `renew_session` / `profile`
|
||
|
||
- `renew_session(s)`：无密码续期（例如 SSO 票据仍有效）。成功返回 `True`，失败返回 `False`，
|
||
**不要抛异常**——引擎会把它当成一次尝试，失败后继续走密码重登。
|
||
- `profile(s)`：只读显示名；`/api/courses` 里异常会被吞掉、显示为空，不影响主流程。
|
||
如果在 `login` 内部直接调用它，自己兜底（`self.profile(s) if self.profile else ""`）。
|
||
|
||
## 返回值与 `opts`
|
||
|
||
### `study` 的 `opts`
|
||
|
||
引擎固定传入以下参数，插件只取自己需要的：
|
||
|
||
| 参数 | 含义 |
|
||
| --- | --- |
|
||
| `workers` | 并发数（路由已夹到 1~95） |
|
||
| `cap` | 单门课程最长学习分钟数 |
|
||
| `enable_quiz` | 是否自动交测验（默认关） |
|
||
| `enable_feedback` | 是否自动交反馈表（默认开） |
|
||
| `mode` | `fast` = 只调接口；`normal` = 开浏览器真播 |
|
||
| `parallel` | `normal` 模式下的并发播放路数 |
|
||
| `quiz_key` | 答题用的大模型配置（`dict` 或 `None`） |
|
||
| `cookies` | 进入本轮学习前的 cookie 列表；网络请求请用 `s`，不要用它新建会话 |
|
||
| `plan` / `project` | `plan_id` / `project_id` |
|
||
| `name` | 课程名 |
|
||
|
||
## 日志、停止与错误
|
||
|
||
### 日志
|
||
|
||
所有日志只走 `runtime.log(key, msg, level="info")`：
|
||
|
||
- `key` 用引擎传进来的账号 id；全局 / 系统事件才用 `"system"`。
|
||
- 时间戳、级别、格式由 `runtime.log` 统一拼，插件里**不要**自己加时间前缀。
|
||
- 不要 `print()`，不要直接调 `database.run_log_add()`。
|
||
- 级别用 `info` / `warn` / `error`；正常流程用 `info`，可恢复异常用 `warn`，失败用 `error`。
|
||
|
||
```python
|
||
runtime.log(key, "开始：%s" % title)
|
||
runtime.log(key, "心跳上报失败，稍后重试：%s" % e, level="warn")
|
||
```
|
||
|
||
日志会同时进控制台、`/api/log`（实时）和 `/api/log/history`（历史），三处内容一致。
|
||
|
||
### 停止
|
||
|
||
引擎不会强杀线程，插件必须在循环里主动响应：
|
||
|
||
```python
|
||
def _stopped(self, key):
|
||
with runtime.RUNS_LOCK:
|
||
return (runtime.RUNS.get(key) or {}).get("status") == "stopped"
|
||
```
|
||
|
||
在每门课程、每个课件、每次等待前都检查一次；长等待拆成小段（如 `time.sleep(1)` 循环），
|
||
保证点「停止」后几秒内能退出。
|
||
|
||
### 错误
|
||
|
||
| 情况 | 抛什么 | 结果 |
|
||
| --- | --- | --- |
|
||
| 账号密码错误、页面结构变化、接口返回异常 | `RuntimeError("可读原因")` | 登录失败 / 该门课程失败，原因进日志与卡片 |
|
||
| 会话失效（被踢回登录页、接口返回未登录） | `SessionExpired("...")` | 引擎尝试 `renew_session`，失败再用密码重登 |
|
||
| 可恢复的瞬时错误（超时、5xx） | 插件内部重试，重试耗尽再抛 | 同上 |
|
||
|
||
不要在插件里 `sys.exit` / 杀线程 / 清空 `RUNS`；不要吞掉 `SessionExpired` 后继续请求。
|
||
|
||
## 推送渠道插件（`kind: notify`）
|
||
|
||
插件目录同样放 `plugins/<名字>/`，但 `plugin.json` 写 `"kind": "notify"`，`main.py` 实现
|
||
`notify.Channel` 子类而不是 `Platform`：
|
||
|
||
```json
|
||
{ "id": "daidai_push", "title": "呆呆面板推送", "name": "daidai_push", "kind": "notify" }
|
||
```
|
||
|
||
```python
|
||
from study_tool import notify
|
||
from study_tool.config.settings import load_settings
|
||
|
||
|
||
class DaidaiPush(notify.Channel):
|
||
id = "daidai_push"
|
||
label = "呆呆面板推送"
|
||
|
||
def send(self, title, content, context=None):
|
||
cfg = load_settings()["notify"] # base_url / app_key / app_secret / channel_name
|
||
... # 失败直接抛异常，消息会写进账号日志
|
||
|
||
|
||
NOTIFY = notify.register(DaidaiPush())
|
||
```
|
||
|
||
- 核心只调 `notify.fault(kind, key, title, content)` / `notify.retry(key, what)`；
|
||
渠道插件不参与学习流程，也不要 import `engine` / `routes`。
|
||
- 配置一律读设置项 `notify`（「系统设置 → 故障推送」里编辑），不要在插件里写死地址或密钥；
|
||
换 token 之类需要缓存的东西放模块级变量，重启后自动重取。
|
||
- 停用 / 重载由加载器统一处理：`kind=notify` 的插件从 `notify` 注册表摘除，不会残留。
|
||
- `POST /api/notify/test` 会走 `notify.send()`，等价于点「测试推送」。
|
||
|
||
## 加载与启停
|
||
|
||
加载器在 `plugins/__init__.py`，对外四个函数 + 对应 HTTP 接口：
|
||
|
||
| 函数 | 接口 | 作用 |
|
||
| --- | --- | --- |
|
||
| `load_plugins()` | 启动时自动调用 | 按启用清单 import 全部插件 |
|
||
| `discover()` | `GET /api/plugins` | 磁盘清单 + 是否启用 / 已加载 / label / sites / capabilities |
|
||
| `set_enabled(name, bool)` | `POST /api/plugins/{name}/enable`、`/disable` | 立即加载或从注册表摘掉，并落库 |
|
||
| `reload(name=None)` | `POST /api/plugins/reload`、`/api/plugins/{name}/reload` | 重新 import，改完插件代码不用重启 |
|
||
|
||
行为细节：
|
||
|
||
- 启用清单存在设置项 `plugins`（`{"disabled": [...]}`）：没列进去的默认启用，
|
||
新丢进目录的插件会自动生效。
|
||
- 停用的插件会 `registry.unregister()`，从 `/api/platforms` 消失，账号平台下拉里也不会出现。
|
||
- 启动时单个插件加载失败只记一条 `system` 级别的 `warn` 日志，不会拖垮服务；
|
||
`GET /api/plugins` 里该插件 `loaded=false`，可以修好后单独 `reload`。
|
||
- 热重载先把旧实现从注册表摘掉再 import；正在跑的学习任务持有的是旧实例，跑到结束不受影响。
|
||
- 重载已停用的插件会报错（先启用再重载）；重载不存在的插件会报「没有这个插件」。
|
||
- 前端顶栏的「插件管理」弹窗（`web/src/components/PluginsDialog.tsx`）就是这几个接口的界面。
|
||
|
||
## 开发流程（从零接入一个平台）
|
||
|
||
1. **摸清站点**：用浏览器完成一次「登录 → 课程列表 → 进入课程 → 上报进度」，
|
||
在 Network 里记下每个接口的 URL、方法、请求体、返回体、必要 header 和 cookie 域名。
|
||
服务端渲染的页面把 HTML 存下来，用 `bs4` / `lxml` 解析。
|
||
2. **建目录**：
|
||
|
||
```bat
|
||
mkdir src\study_tool\plugins\<名字>
|
||
```
|
||
|
||
放 `__init__.py`、`plugin.json`、`main.py` 三个文件；实现复杂再拆 `utils/`。
|
||
3. **先写 `session` / `dump_cookies`**：能恢复出带登录态的 `requests.Session`，
|
||
这是后面所有槽位的基础。
|
||
4. **再写 `login` / `list_courses` / `profile`**：能在「添加账号」里登录成功，
|
||
卡片显示名字，刷新课程能拿到列表。
|
||
5. **写 `discover`**：把课程页解析成统一的课程描述（三类活动列表）。
|
||
6. **最后写 `study`**：按活动类型逐个处理，循环里检查停止，日志用账号 key。
|
||
7. **注册并启动**：`PLATFORM = registry.register(<类名>())`；启动服务，
|
||
`GET /api/platforms` 应出现该平台。
|
||
8. **联调**：按 `/api/login` → `/api/courses` → `/api/discover` → `/api/study` 的顺序走一遍，
|
||
详细检查项见[联调检查表](#联调检查表)。
|
||
9. **收尾**：同步更新 [architecture.md](architecture.md) 的目录说明；按仓库规范更新
|
||
`CHANGELOG.md` / `OPTIMIZATION.md`；不要顺手改无关文件。
|
||
|
||
不需要改 `load_builtin()`、`engine.py`、`routes/` 或前端——加载器扫目录时会自动 import 各插件。
|
||
|
||
## 联调与调试
|
||
|
||
### 接口一览
|
||
|
||
| 接口 | 方法 | 主要参数 | 用到的插件槽位 |
|
||
| --- | --- | --- | --- |
|
||
| `/api/platforms` | GET | — | `capabilities()` |
|
||
| `/api/plugins` | GET | — | 插件清单（不 import 插件代码） |
|
||
| `/api/plugins/{name}/enable` `/disable` | POST | — | 加载 / 卸载 |
|
||
| `/api/plugins/reload`、`/api/plugins/{name}/reload` | POST | — | 重新 import |
|
||
| `/api/login` | POST | `account_id` 或 `username` / `password` / `platform` | `login` → `list_courses` → `dump_cookies` |
|
||
| `/api/courses` | POST | `platform`、`cookies` | `session` → `list_courses` → `profile` |
|
||
| `/api/discover` | POST | `platform`、`cookies`、`plan_id`、`project_id`、`name` | `session` → `discover` |
|
||
| `/api/study` | POST | `key`、`cookies`、`courses[]`、`workers`、`cap_minutes`、`enable_quiz`、`enable_feedback` | 后台线程：`session` → `discover` → `study` |
|
||
| `/api/stop` | POST | `key` | 置停止标记 |
|
||
| `/api/log` | GET | `key`、`since` | 实时日志 |
|
||
| `/api/log/history` | GET | `key`、`tail` | 历史日志 |
|
||
| `/api/runs` | GET | — | 各账号运行状态快照 |
|
||
| `/api/loginlog` | GET | `tail` | 登录尝试回放 |
|
||
|
||
`/api/study` 是异步的：立即返回，进度看 `/api/runs` 和 `/api/log`；同一账号正在跑时再调会返回
|
||
「该账号正在学习中」。
|
||
|
||
### curl 示例
|
||
|
||
```bash
|
||
# 平台是否注册成功
|
||
curl http://127.0.0.1:8848/api/platforms
|
||
|
||
# 插件清单（enabled / loaded / sites / capabilities）
|
||
curl http://127.0.0.1:8848/api/plugins
|
||
|
||
# 改完代码热重载单个插件
|
||
curl -X POST http://127.0.0.1:8848/api/plugins/<名字>/reload
|
||
|
||
# 用账号密码登录（platform 填插件 id）
|
||
curl -X POST http://127.0.0.1:8848/api/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"username":"...","password":"...","platform":"<id>"}'
|
||
|
||
# 用已保存的 cookie 刷新课程（cookie 从上一步返回里取）
|
||
curl -X POST http://127.0.0.1:8848/api/courses \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"platform":"<id>","cookies":[...]}'
|
||
```
|
||
|
||
Windows 下把 `\` 换成一行写完，或使用 PowerShell 的 `Invoke-RestMethod`。
|
||
|
||
### 常见错误码
|
||
|
||
| code | 含义 | 排查方向 |
|
||
| --- | --- | --- |
|
||
| `no_credential` | 没有可用账号密码 | 添加账号时填密码，或传 `account_id` |
|
||
| `no_platform` | 平台未注册 / 没实现该槽位 | `/api/plugins` 看 `loaded`；确认方法名拼写 |
|
||
| `login_failed` | 登录抛了异常 | `/api/loginlog` 看平台返回；检查验证码 / 加密 / 表单字段 |
|
||
| `no_cookie` | cookie 为空或全被过滤 | `session` 的域名过滤；重新登录 |
|
||
| `session_expired` | 会话失效 | 实现 / 修好 `renew_session` 或确认密码可重登 |
|
||
| `fetch_failed` | 列表接口异常 | 页面结构变化、接口参数、header |
|
||
| `no_course` | 登录有效但没课程 | 课程页选择器 / 板块参数 |
|
||
|
||
### 排查顺序
|
||
|
||
1. `GET /api/plugins`：插件是否 `loaded=true`；失败先看系统日志里的加载错误。
|
||
2. `GET /api/platforms`：`label` 和 `capabilities` 是否符合预期（少了能力 = 方法没被识别）。
|
||
3. `/api/login`：登录是否成功；失败看 `/api/loginlog` 的 `stage` 和错误。
|
||
4. `/api/courses`：cookie 是否恢复成功、列表选择器是否正确。
|
||
5. `/api/discover`：返回的三类活动数量与页面是否一致。
|
||
6. `/api/study` + `/api/log?key=<账号 id>`：日志是否出现在该账号卡片、进度是否递增。
|
||
7. `/api/stop`：几秒内循环是否退出。
|
||
|
||
## 把已有实现改成子类
|
||
|
||
老写法（自由函数 + 逐项注册）已经废弃，迁移步骤：
|
||
|
||
1. 保留模块级纯函数（`_b64` / `_ocr` / `_parse_courses` 等），它们不属于契约。
|
||
2. 把原来的槽位自由函数改成同名方法：加 `self`，模块内互相调用改成 `self.xxx`，
|
||
平台私有的重登逻辑改成 `_relogin` 这类私有方法。
|
||
3. 加类属性 `id` / `label` / `entries`，删掉模块末尾的逐项注册。
|
||
4. 模块末尾改成 `PLATFORM = registry.register(<类名>())`。
|
||
5. 实现模块一起搬进 `plugins/<名字>/`，目录内互相引用改成相对导入；
|
||
外部（如 `plugins/guanyixue/quiz.py`）如果引用了平台实现，同步改路径或改成走 `registry.get()`。
|
||
6. 逐个验证槽位行为与迁移前一致；同一平台的不同代际由 `study` 里按
|
||
`course["generation"]` 分发（参见 `plugins/guanyixue/main.py`）。
|
||
|
||
## 硬约束
|
||
|
||
- 日志只走 `runtime.log(key, msg, level=...)`，`key` 用引擎传进来的账号 id；不要自己加时间前缀。
|
||
- 循环里要响应停止：`(runtime.RUNS.get(key) or {}).get("status") == "stopped"` 时返回。
|
||
- 会话失效抛 `SessionExpired`；自动续期 / 用密码重登由引擎统一处理（`renew_session` 里除外）。
|
||
- 不 import `engine` / `routes` / 前端；插件之间只允许同平台不同代际互相引用，
|
||
模块级互相 import 成环时改用函数内延迟导入。
|
||
- cookie 域名过滤在平台自己的 `session` 里做，引擎不兜底：漏写 `session` 会直接报
|
||
「平台没有实现 session」，不会静默过滤。
|
||
- 时间、解析、编码这类通用能力用现成库（`requests` / `bs4` / `lxml` / `datetime`），不要手写。
|
||
- 新代码的 import 一律显式（如 `from study_tool.runtime import log`），不要新增 `from xxx import *`。
|
||
- 不改 `engine.py` / `routes/` / 前端来适配单个平台；平台差异只能落在插件目录里。
|
||
|
||
## 常见坑
|
||
|
||
- **`plugin.json.id` 与类 `id` 不一致**：加载时抛「没有注册 id=...」，插件不会出现在
|
||
`/api/platforms`；改完记得 `reload`。
|
||
- **插件目录缺 `__init__.py` / `plugin.json`**：`plugin.json` 缺失会直接扫描不到；
|
||
`__init__.py` 是仓库约定（现有插件都有），补上能避免打包 / 热重载时的导入歧义。
|
||
- **自由函数改方法后忘加 `self`**：模块内原来的 `_relogin(key)` 必须写成 `self._relogin(key)`，
|
||
否则运行时才报错；提交前可扫一遍模块的未定义全局名。
|
||
- **注册写两遍**：既在类里又在模块末尾逐项注册，会导致同一个 id 被覆盖，`capabilities`
|
||
也可能和实际方法不一致。只保留 `registry.register(<类名>())`。
|
||
- **cookie 域写错**：`session` 里过滤的是保存下来的 cookie，域名不匹配会得到空会话，
|
||
表现为「登录成功但刷新课程提示未登录」。
|
||
- **日志 key 用错**：平台用自己拼的字符串当 key，日志会跑进别的卡片或 `system` 弹窗。
|
||
- **把代际当平台**：旧版 / 新版注册成两个平台，账号绑定会漂移；应该在
|
||
`discover` 里写 `generation`，由 `study` 分发。
|
||
- **在 `study` 里重新 `discover`**：会重复请求、重复解析，还可能把引擎已经算好的进度覆盖掉；
|
||
需要最新数据时在插件内部按需取。
|
||
- **忽略 `dump_cookies`**：`discover` 里换了会话却不让引擎回写，下一门课又会掉登录。
|
||
- **长 `sleep` 不检查停止**：点「停止」后要等几分钟才退出；把等待拆成小段。
|
||
- **加载失败只看页面**：启动时的加载异常只写日志、不弹窗；先看控制台或系统日志。
|
||
|
||
## 联调检查表
|
||
|
||
- [ ] `GET /api/platforms` 里能看到该平台，`label` 与 `capabilities` 正确
|
||
- [ ] `GET /api/plugins` 里 `loaded=true`，`title` 正确
|
||
- [ ] 停用 → 平台从 `/api/platforms` 消失；启用 → 重新出现
|
||
- [ ] 修改代码后 `POST /api/plugins/{name}/reload` 生效，不需要重启
|
||
- [ ] 添加账号 → 选平台 → 登录成功，卡片显示 `profile` 名字
|
||
- [ ] 刷新课程返回非空列表，`in_study` 标记正确
|
||
- [ ] 发现课程返回的活动数与页面一致
|
||
- [ ] 开始学习：日志出现在该账号卡片里，进度递增
|
||
- [ ] 点停止后几秒内循环退出
|
||
- [ ] 会话失效时能走到续期 / 重登，不需要手动刷新
|
||
- [ ] 平台没实现 `session` 时，`/api/courses` 报「还没有实现 session」
|
||
- [ ] 日志里没有插件自己加的时间前缀，也没有 `print` 输出
|
||
|
||
## 提交前
|
||
|
||
- 只改插件目录（以及确有必要同步的 `docs/architecture.md`）；不要顺手重构无关文件。
|
||
- 按仓库规范更新 `CHANGELOG.md` 的 `Unreleased`；需要用户测试确认的事项写进 `OPTIMIZATION.md`。
|
||
- 插件依赖的平台接口、验证码、加密方式如果是逆向得到的，把关键结论写进插件目录的
|
||
`__init__.py` 文档字符串或 `main.py` 顶部注释，方便下次维护。
|
||
- 不提交 `__pycache__`、临时抓包、`data/study.db`。
|
||
|
||
## 方案演进
|
||
|
||
1. 早期：平台实现直接写在 `engine.py` 里。
|
||
2. 拆包：`platforms/base.py` 定义 `Platform` 契约 + `registry` 注册表，引擎按
|
||
`course["platform"]` 分发；平台用自由函数 + 逐项注册；学习流程仍在引擎。
|
||
3. 契约补全：`contract.py` 推导 `capabilities`；`SessionExpired` 移到 `platforms/errors.py`；
|
||
各平台学习流程从引擎搬回平台模块（`engine.py` 只剩账号级编排）。
|
||
4. 类式：`Platform` 变成普通基类，平台写成子类（类属性 + 方法），禁止逐项传函数注册。
|
||
5. 插件目录（当前）：平台全部迁到 `plugins/<名字>/`（`plugin.json` + `main.py`，实现复杂的
|
||
再拆同目录模块），`load_plugins()` 扫目录加载，支持启停与热重载；
|
||
`gdgxk`、`guanyixue` 都已完成迁移。
|
||
|
||
## 附录：现有插件对照
|
||
|
||
| 插件 | 目录 | 入口域名 | 已实现能力 | 实现拆分 | 值得参考 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 广东公需课 | `plugins/gdgxk/` | `jsglpt.gds.edu.cn`、`jsxx.gds.edu.cn` | 登录 / 会话 / 课程 / 发现 / 学习 / 续期 / 显示名 | `utils/`：`http` / `login` / `course` / `learn` | 双域名 SSO 换票、base64 账号密码、验证码、心跳上报 |
|
||
| 莞易学 | `plugins/guanyixue/` | `jspx.dgjy.net`、`study.dgjy.net` | 登录 / 会话 / 课程 / 发现 / 学习 / 续期 / 显示名 | `utils/`：`http` / `login` / `course` / `feedback` / `learn` / `spa`；`detect.py` 识别页面代际 | 同一平台 `legacy` / `spa` 两代页面按 `generation` 分发 |
|
||
|
||
看代码时的推荐顺序：
|
||
|
||
1. `plugins/guanyixue/main.py`：最短的完整子类，能看清类属性 + 槽位 + 代际分发。
|
||
2. `plugins/guanyixue/utils/course.py`：`discover` 的返回值长什么样。
|
||
3. `plugins/gdgxk/main.py` + `utils/learn.py`：登录换票、学习循环与停止检查。
|
||
4. `platforms/base.py` / `contract.py`：契约的最终定义（有疑问以代码为准）。
|