Samueli924/chaoxing: a command line runner for Chaoxing task points

What problem chaoxing solves, and for whom

Chaoxing (also branded 超星学习通, 超星尔雅 and 泛雅超星) presents a course as a sequence of task points: video segments, documents, and chapter quizzes. A student has to click through each one, and some items are locked behind a chapter test. The repository describes itself as an unattended task point runner, and the stated end goal is to eliminate paid course-farming platforms by open-sourcing the same capability. That framing tells you the intended audience: people who already have a Chaoxing account and want the clicking done by a script they run themselves, rather than by a service they pay.

The tool is a console program, not a browser extension. It authenticates with a phone number and password, then works through the course list. Two optional subsystems extend it: a question bank provider for the quizzes that gate task points, and an external notification provider that pushes a message when all courses finish or when the program errors out. The README is blunt that the notification feature is "有用但不多" (useful but not much), which is an unusually honest note in a project README.

Because it drives the account directly, the scope is personal automation, not a platform. There is no multi-user dashboard, no scheduling service, and no admin interface. One config file, one account.

How the runner authenticates and walks the course tree

The entry point is main.py, which parses arguments and hands off to the api/ package. Dependencies in requirements.txt point at the mechanism: requests and httpx for HTTP, beautifulsoup4 and lxml for parsing course pages, pyaes for the login encryption that Chaoxing's web front end uses, and ddddocr for the captcha that appears during sign-in. tenacity is present for retry logic and loguru for logging. There is no Selenium or Playwright in the dependency list, so this is a request-level client rather than a browser driver.

The course selection is explicit. You either let the program enumerate your courses, or you pass a comma-separated list of course IDs with -l. Within a course, the runner checks each task point in order. When it hits one that is already closed, the notopen_action setting decides what happens: retry re-attempts the previous task point and gives up after three consecutive failures, ask prompts you interactively, and continue skips the closed run and moves to the next open item. The same choice is exposed on the command line as -a or --notopen-action.

Chapter learning counts are a separate pass. With add_learning_count = true, the program finishes the selected courses' task points first, then polls chapters until it reaches target_count, which the template sets to 100. The README is explicit that this is an appended step after the main run, not an independent mode, so you cannot ask for counts alone.

Quizzes are where the architecture gets interesting. The [tiku] section names a provider, and that name must match a class implementing the Tiku interface in answer.py, for example TikuYanxi for the 言溪 question bank. Matching is case-sensitive. If no provider is configured, chapter tests are skipped automatically. The submit flag controls whether the program sends answers once the question bank coverage threshold is met; the README warns that correct rate is not guaranteed and that any invalid submit value is treated as false.

Installing chaoxing and running a first course

The README targets Python 3.13 or newer, and pyproject.toml enforces requires-python = ">=3.13,<4.0". Clone the repository and install the dependency list:

git clone --depth=1 https://github.com/Samueli924/chaoxing
cd chaoxing
pip install -r requirements.txt

Alternatively, pyproject.toml declares the dependencies dynamically from requirements.txt, so `pip install .` installs the same set. If your system Python is older, the README suggests uv as a runner.

You can start with no configuration at all:

python main.py

The interactive path will prompt you for what it needs. For repeat runs, copy the template and fill in credentials:

cp config_template.ini config.ini
python main.py -c config.ini

A single command can also carry everything, including a course ID list and a policy for closed task points:

python main.py -u 手机号 -p 密码 -l 课程ID1,课程ID2 -a ask

Expect a log stream from loguru as the runner walks each course. If a chapter test appears and no [tiku] provider is configured, the README says that task is skipped rather than failed, so a run can finish while leaving quiz-gated points untouched.

There is also a packaged executable path. The releases page carries an exe; the README shows `./chaoxing.exe -c config.ini` for the config-file form and the same -u/-p/-l/-a flags for the command-line form. Docker is the third option. The Dockerfile is based on python:3.13-slim, installs requirements from the Tsinghua PyPI mirror, copies config_template.ini to /config/config.ini, declares /config as a volume, and sets the entrypoint to `python3 main.py -c /config/config.ini`. Build and run it like this:

docker build -t chaoxing .
docker run -it -v /本地路径/config.ini:/config/config.ini chaoxing

The README notes that a first run without a mount will materialize the template at /config/config.ini inside the container.

Where the automation breaks: closed task points, quizzes and captchas

The most visible failure mode is the closed task point. The default policy is retry, which re-attempts the previous item and stops after three consecutive failures, or immediately if no question bank and auto-submit are configured. In practice that means a course with several locked chapters can halt the run early, and the log will show the retry loop rather than progress. The ask and continue policies exist precisely because retry is not always what you want, but neither is a fix: they move past the obstacle, leaving those points incomplete.

Quizzes are the second boundary. The README states that for courses with chapter detection and locked task points, a question bank is mandatory. Without one, the runner skips those items. With one, the submit flag governs whether answers are sent at all, and the README explicitly declines to guarantee correctness. Coverage is defined as the share of questions the provider found an answer for, so a low-coverage provider produces a low submit rate. The provider names are class names in answer.py, which means support depends on what contributors have implemented, not on a plugin registry.

Login is the third constraint. ddddocr is in the dependency list, which means captcha recognition runs locally and pulls in its own model and native libraries. That is a heavier install than a pure-requests tool, and it is the part most likely to break on an unusual platform. The README does not document rollback, resume-from-checkpoint, or what happens to partial state if you kill a run mid-course, so plan for a full re-run rather than a resume.

chaoxing versus a browser automation script

The obvious alternative is driving the site with Selenium or Playwright, which is what many one-off course scripts do. The difference is where the logic lives. A browser script reproduces clicks on whatever the page renders, so it survives markup changes only as long as its selectors do, and it consumes a full browser per session. chaoxing instead speaks to the same endpoints the page calls, using pyaes for the login payload and beautifulsoup4/lxml to parse responses. That is lighter and faster per course, and it can run headless in a container with no display server.

The trade-off is fragility of a different kind. A request-level client encodes assumptions about endpoints and parameters, and when Chaoxing changes them, there is no rendered page to fall back on. A browser script degrades more gracefully because the UI is the contract. chaoxing also has no visible browser state, so when something goes wrong you are reading loguru output rather than watching a page. If your goal is to observe and intervene, a browser-driven approach is easier to debug; if your goal is unattended runs on a server, this project's model fits better. Neither approach is sanctioned by the platform, and the repository's own disclaimer limits use to study and discussion.

Maintenance, versioning and the GPL-3.0 obligation

The repository is not archived, and the last push was on 2026-09-05. Releases are tagged: v3.1.2 in March 2025, v3.1.3 in May 2025, and v3.1.4 in October 2025. Note that pyproject.toml still declares version 3.1.3 while the newest release tag is v3.1.4, so the packaged metadata and the release tag disagree; if you install from source, do not read the version string as authoritative. The README also records a 2024-10-21 update crediting a contributor for question bank support, which is the kind of change that arrives through pull requests rather than a fixed cadence.

The upgrade cost is mostly dependency drift. requirements.txt pins lower bounds rather than exact versions for most packages (requests>=2.32.5, httpx[socks]>=0.28.1, ddddocr>=1.6.1, openai>=1.109.1), with only chardet constrained to a range. A fresh `pip install -r requirements.txt` months from now can resolve to a different set than the author tested. The openai dependency is notable: the README does not document an LLM-backed feature, so its role is not explained anywhere in the repository files visible at the top level.

Licensing is GPL-3.0. The README's disclaimer states that open and free use, citation, modification and derivative code are allowed, that modified or derived code may not be released as closed-source commercial software, that using the code for profit is prohibited, and that any program built on it must also follow GPL-3.0. It also states the code is for study and discussion and disclaims responsibility for illegal use by others. That is the project's own wording, not legal advice; if you plan to redistribute anything built on this, read the LICENSE file and get your own counsel.

Editorial conclusion

Adopt this if you already run Python 3.13 or newer and want a scripted, self-hosted way to walk Chaoxing task points, and if you are willing to supply a question bank provider for chapter quizzes. Do not adopt it if your courses are mostly graded quizzes, if you cannot install ddddocr and its dependencies, or if you need a supported product with a roadmap: this is a GPL-3.0 community project, the README says it exists to undercut paid course-farming services, and it carries an explicit disclaimer that the code is for study and discussion only. Before committing, verify that config.ini parses with your provider name spelled exactly as the Tiku class in answer.py, and confirm that a single dry run reaches the task points you expect rather than stopping at a closed one.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Samueli924/chaoxing on GitHub