UCAS Score Query

简体中文 | English

An unofficial, bilingual Python command-line tool that signs in to UCAS SEP/JWXK, uses a CSTCloud-compatible multimodal LLM to recognize the login captcha, retrieves graduate course scores, prints them in the terminal, and exports CSV/JSON files.

• SEP login with RSA password encryption
• Optional captcha recognition through a CSTCloud-compatible multimodal LLM API
• Automatic transition from SEP to JWXK
• Graduate score table parsing
• UTF-8 CSV export that opens correctly in Excel
• Optional JSON export
• Bounded captcha retries, network timeouts, TLS verification, and no hard-coded secrets
• Unit tests and GitHub Actions CI without accessing real accounts
• Tag-triggered GitHub Release workflow that builds wheel and source distributions

• Python 3.10 or later (tested in CI through Python 3.14)
• A valid UCAS account
• A CSTCloud-compatible API token when SEP asks for a captcha
• Network access to the relevant UCAS and LLM endpoints

Before publishing, replace the repository URL placeholders in one command:

python scripts/configure_repository.py --github-user YOUR_USERNAME --author "YOUR_PUBLIC_NAME"

The author argument is optional. Review the resulting diff before committing.

git clone https://github.com/YOUR_GITHUB_USERNAME/ucas-score-query.git
cd ucas-score-query
python -m venv .venv

Activate the environment:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

Install:

python -m pip install --upgrade pip
python -m pip install -e .

The safest default is to enter secrets interactively. The password and token are hidden while typing.

You may also set environment variables:

# macOS / Linux
export UCAS_USERNAME="your_username"
export UCAS_PASSWORD="your_password"
export CSTCLOUD_API_TOKEN="your_token"

# Windows PowerShell
$env:UCAS_USERNAME="your_username"
$env:UCAS_PASSWORD="your_password"
$env:CSTCLOUD_API_TOKEN="your_token"

Optional variables:

CSTCLOUD_MODEL=qwen3.5
CSTCLOUD_API_URL=https://uni-api.cstcloud.cn/v1/chat/completions

Do not commit .env, passwords, API tokens, cookies, screenshots containing personal information, or generated score files.

ucas-score-query

Export both CSV and JSON:

ucas-score-query --output output/scores.csv --json-output output/scores.json

Specify a username and model:

ucas-score-query --username YOUR_USERNAME --llm-model qwen3.5

Show all options:

ucas-score-query --help

Run without installation:

PYTHONPATH=src python -m ucas_score_query --help

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m ruff format --check .
python -m mypy src
python -m build
python -m twine check dist/*

Or use the included Makefile on compatible systems:

make install-dev
make test
make lint
make typecheck
make build

ucas-score-query/
├── src/ucas_score_query/    # application package
├── tests/                   # offline unit tests and fixtures
├── docs/                    # architecture and publishing guides
├── examples/                # safe usage examples
├── .github/                 # CI, issue forms, PR template, Dependabot
├── pyproject.toml           # package metadata and tool configuration
├── LICENSE                  # MPL-2.0
└── NOTICE                   # upstream attribution and trademark notice

• Secrets are never required in source code.
• The program does not intentionally persist passwords, tokens, or cookies.
• CSV/JSON outputs contain personal academic records; protect or delete them after use.
• --insecure disables TLS certificate verification and should only be used temporarily for diagnosis.
• Review the source and dependencies before running software that handles credentials.
• Report vulnerabilities according to SECURITY.md, not through a public issue.

• SEP/JWXK HTML and authentication flows are private implementation details and may change without notice.
• Captcha recognition is probabilistic and may fail.
• The parser currently targets graduate score pages and may not support every account type.
• No live integration test is included because CI must not handle real credentials.

The SEP/JWXK authentication flow references wirsbf/traintime_pda_ucas, including the JWXK toUrl construction logic. The referenced project is licensed under MPL-2.0. See NOTICE for attribution details.

This repository is licensed under the Mozilla Public License 2.0. Source files derived from or modifying MPL-covered logic must remain available under the MPL-2.0 terms.

Read CONTRIBUTING.md and the Code of Conduct before opening a pull request. Please do not include account credentials, cookies, real score pages, or identifiable screenshots in issues or tests.