Skip to content

README_CN.md

Latest commit

 

History

History
167 lines (117 loc) · 4.68 KB

README_CN.md

File metadata and controls

167 lines (117 loc) · 4.68 KB
Raw

Lesson Workflow CLI

English Version

Lesson Workflow CLI 是一个面向高校智慧教学平台场景的本地化工作流工具。它使用 Playwright 采集课程与课时入口，并衔接 PPT 下载、OCR、热词提取、音频转写和复习材料生成等后续流程。

这个仓库适合公开代码，不适合公开真实运行数据。课程资源、账号会话、转写结果、浏览器持久化目录和 API 密钥都应保留在本地，不应提交。

公开仓库说明

  • 本仓库默认只发布源码、示例配置和文档。
  • 根目录 .gitignore 已忽略 .env、.env.local、env.local.ps1、runtime/、html/、.venv/ 等本地文件。
  • 请只使用 .env.example 和 env.local.ps1.example 作为配置模板，不要提交真实密钥。
  • 使用本项目时，应自行确认你对目标平台、课程内容、音视频和转写数据具备合法访问与处理权限，并遵守所在机构、平台和服务商的使用条款。

功能概览

  • 登录并复用本地浏览器会话
  • 获取课程列表、课时列表和播放页地址
  • 探测课时流地址并下载音频
  • 下载 PPT 资源并合并为 PDF
  • 对本地 OCR 结果做热词提取与 LLM 精炼
  • 调用阿里云听悟完成离线转写
  • 基于转写与热词生成复习提纲、记忆材料和练习材料
  • 提供 CLI 与 Qt GUI 两种工作流入口

环境要求

  • Python 3.10+
  • uv
  • Microsoft Edge 或 Chromium
  • Windows 环境下运行 GUI 与部分本地工具更方便

安装依赖：

uv sync
uv run playwright install msedge

如果 msedge 不可用，可改装 Chromium：

uv run playwright install chromium

配置

推荐用项目根目录的本地配置文件：

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

程序会自动加载 .env.local，若不存在则读取 .env。公开仓库中只保留示例文件，不保留真实凭据。

如果你习惯在 PowerShell 中统一注入环境变量，可以使用：

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

主要环境变量分两类：

  • LLM 接口：ZHJX_LLM_BASE_URL、ZHJX_LLM_API_KEY、ZHJX_LLM_MODEL
  • 听悟接口：ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET、TINGWU_APP_KEY

更完整的变量列表见 .env.example。

快速开始

首次登录并复用本地会话：

uv run zhjx-ai login

启动图形界面工作流：

uv run zhjx-ai gui

命令行查看课程：

uv run zhjx-ai courses

查看某门课的课时：

uv run zhjx-ai lessons --course 1

解析某个课时的播放页：

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

常用命令

采集与下载：

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

热词与转写：

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

复习材料生成：

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"

任务管理：

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

输出目录

运行结果默认写入 runtime/zhjx/，例如：

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

这些内容属于本地运行产物，默认不会纳入 Git 版本控制。

项目结构

src/zhjx_ai_guide/    核心源码
tools/                辅助脚本
runtime/              本地运行产物，默认忽略
html/                 本地网页快照，默认忽略
.env.example          环境变量模板
env.local.ps1.example PowerShell 环境变量模板

许可证

本项目采用 GPL-3.0 许可发布，完整文本见 LICENSE。