Lesson Workflow CLI

中文说明 / Chinese Version

Lesson Workflow CLI is a local workflow tool for university smart-teaching platform scenarios. It uses Playwright to collect course and lesson entry points, then connects downstream steps such as PPT download, OCR, keyword extraction, audio transcription, and review-material generation.

This repository is suitable for publishing source code, but not real runtime data. Course assets, account sessions, transcripts, browser profiles, and API keys should remain local and must not be committed.

Public Repository Notes

• This repository is intended to publish source code, example configuration, and documentation only.
• The root .gitignore excludes .env, .env.local, env.local.ps1, runtime/, html/, .venv/, and other local-only files.
• Use .env.example and env.local.ps1.example as templates. Do not commit real credentials.
• You are responsible for ensuring that your access to the target platform, course content, audio/video material, and transcription data is authorized and compliant with your institution's policies and the relevant platform and vendor terms.

Features

• Reuse a local browser session for authenticated access
• Collect course lists, lesson lists, and playback page URLs
• Probe stream URLs and download lesson audio
• Download PPT assets and merge them into PDF
• Extract keywords from OCR text and refine them with an LLM
• Submit offline transcription jobs to Alibaba Cloud Tingwu
• Generate review outlines, memory notes, and practice material from transcripts and keywords
• Support both CLI and Qt GUI workflows

Requirements

• Python 3.10+
• uv
• Microsoft Edge or Chromium
• Windows is recommended for the GUI and some local tooling

Install dependencies:

uv sync
uv run playwright install msedge

If msedge is unavailable, install Chromium instead:

uv run playwright install chromium

Configuration

Recommended local project configuration:

Copy-Item .\.env.example .\.env.local
notepad .\.env.local

The program automatically loads .env.local, or falls back to .env if it exists. Public repositories should keep templates only, not real secrets.

If you prefer loading environment variables through PowerShell:

Copy-Item .\env.local.ps1.example .\env.local.ps1
notepad .\env.local.ps1
.\env.local.ps1

Main variable groups:

• LLM settings: ZHJX_LLM_BASE_URL, ZHJX_LLM_API_KEY, ZHJX_LLM_MODEL
• Tingwu settings: ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, TINGWU_APP_KEY

See .env.example for the full list.

Quick Start

Log in once and reuse the local browser session:

uv run zhjx-ai login

Start the GUI workflow:

uv run zhjx-ai gui

List courses:

uv run zhjx-ai courses

List lessons for one course:

uv run zhjx-ai lessons --course 1

Resolve the playback page for one lesson:

uv run zhjx-ai resolve --course 1 --lesson 2

Common Commands

Acquisition and download:

uv run zhjx-ai streams --course 1 --lesson 2 --probe-seconds 10
uv run zhjx-ai download-audio --course 1 --lesson 2 --stream 1 --format mp3
uv run zhjx-ai ppt --course 1 --lesson 2
uv run zhjx-ai download-ppt --course 1 --lesson 2 --pdf --ocr

Keywords and transcription:

uv run zhjx-ai hotwords --course 1 --lesson 2 --top-k 100 --global-top-k 120
uv run zhjx-ai hotwords --course 1 --lesson 2 --llm
uv run zhjx-ai tingwu-submit --file "runtime/zhjx/audio/xxx.mp3" --oss-bucket "your-bucket" --oss-endpoint "oss-cn-hangzhou.aliyuncs.com" --wait
uv run zhjx-ai tingwu-task --task-id "<task_id>"
uv run zhjx-ai tingwu-fetch --task-id "<task_id>" --result-key Transcription

Review generation:

uv run zhjx-ai review-plan --task-id "<task_id>" --hotwords-file runtime/zhjx/last_hotwords.json
uv run zhjx-ai full-review --ocr-file runtime/zhjx/ppt/test_l1/slides_ocr.txt --file runtime/zhjx/audio/test_full.mp3 --course-title "Forest Protection" --lesson-title "Insect Morphology"

Task management:

uv run zhjx-ai task-reset --list
uv run zhjx-ai task-reset --task-key "1:2026-03-16:Lesson7:Room208" --from-step hotwords
uv run zhjx-ai wizard

Output Directory

Runtime output is written to runtime/zhjx/, including:

• courses.json, lessons_*.json
• last_resolve.json, last_streams.json
• audio/, ppt/, hotwords/
• tingwu/, review/
• pw-profile/
• courses/

These are local runtime artifacts and are excluded from version control by default.

Project Layout

src/zhjx_ai_guide/    core source code
tools/                helper scripts
runtime/              local runtime artifacts, ignored by default
html/                 local page snapshots, ignored by default
.env.example          environment template
env.local.ps1.example PowerShell environment template

License

This project is released under GPL-3.0. See LICENSE for the full text.