thu-learn-cli

命令行工具，用于访问清华大学网络学堂（learn.tsinghua.edu.cn）。

安装

前置要求： Node.js 20+

npm install -g thu-learn-cli
# 或
pnpm add -g thu-learn-cli

也可以从源码构建：

git clone https://github.com/your-username/thu-learn-cli
cd thu-learn-cli
pnpm install && pnpm build
npm link

配置文件位置

| 平台 | 路径 | |------|------| | Linux | ~/.config/thu-learn-cli/config.json | | macOS | ~/Library/Preferences/thu-learn-cli/config.json | | Windows | %APPDATA%\thu-learn-cli\Config\config.json |

[!NOTE] 首次运行 thu-learn auth login 时，若系统中未检测到 Chrome / Chromium，将自动下载 Playwright 内置的 Chromium（约 150 MB）。

登录

thu-learn auth login

首次运行时会先提示输入用户名和密码，然后弹出 Chromium 窗口自动完成 SSO 登录：

1. 表单自动填写并提交
2. 若出现"二次认证/设备信任"页面，点击确认按钮
3. 登录成功后浏览器自动关闭

凭据保存在各平台对应的配置目录下（详见上方安装章节）。

[!CAUTION] 密码以明文形式存储在配置文件中，请确保该文件的访问权限仅限于当前用户，并避免在共享或公共设备上使用本工具。

选项：

| 选项 | 说明 | |------|------| | --no-browser | 跳过浏览器，直接用 HTTP 验证（需要已受信任的 fingerprint） | | -u <用户名>, -p <密码> | 直接传入凭据（同时跳过浏览器） | | -f <uuid> | 指定 fingerprint UUID（默认自动生成并持久化） |

环境变量：

THU_LEARN_USERNAME=xxx
THU_LEARN_PASSWORD=xxx
THU_LEARN_FINGERPRINT=xxx

其他认证命令

thu-learn auth whoami    # 查看当前登录用户
thu-learn auth logout    # 退出登录

命令参考

学期

thu-learn semester list              # 列出所有学期
thu-learn semester current           # 当前学期信息
thu-learn semester use <id>          # 切换学期（如 2024-2025-1）

课程

thu-learn courses [--semester <id>] [--type student|teacher] [--json]

通知

thu-learn notices [--course <id>] [--semester <id>] [--unread] [--important] [--json]
thu-learn notice view <id>

作业

thu-learn assignments [--course <id>] [--semester <id>] [--unfinished] [--submitted] [--json]
thu-learn assignment view <id>
thu-learn assignment submit <id> [--text "答案文字"] [--file ./report.pdf]

文件

thu-learn files [--course <id>] [--semester <id>] [--new] [--json]
thu-learn file download <id> [--output <路径>]   # 路径可为目录或完整文件名
thu-learn file categories <courseId>

讨论 / 答疑

thu-learn discussions [--course <id>] [--semester <id>] [--json]
thu-learn questions   [--course <id>] [--semester <id>] [--json]

问卷

thu-learn questionnaires [--course <id>] [--semester <id>] [--pending] [--json]
thu-learn questionnaire view <id>

搜索

对当前学期的通知、作业、文件进行模糊搜索：

thu-learn search "期中" [--type notification|homework|file] [--limit 20] [--json]

收藏

thu-learn favorites [--type <类型>] [--course <id>] [--json]
thu-learn favorite add    <type> <id>
thu-learn favorite remove <id>
thu-learn favorite pin    <id>
thu-learn favorite unpin  <id>

内容类型：notification file homework discussion question questionnaire

笔记（个人评论）

thu-learn comments [--type <类型>] [--course <id>] [--json]
thu-learn comment set <type> <id> "我的笔记"
thu-learn comment set <type> <id> ""    # 传空字符串删除笔记

日历

thu-learn calendar <start> <end> [--graduate] [--json]
# 日期格式 yyyymmdd，最大跨度 29 天
thu-learn calendar 20250301 20250329

全局选项

| 选项 | 说明 | |------|------| | --json | 输出原始 JSON（多数列表命令支持） | | -h, --help | 显示帮助 | | -V, --version | 显示版本号 |

开发

pnpm install          # 安装依赖
pnpm build            # 打包到 dist/index.mjs
pnpm test             # 运行测试（需要 test/.env，参考 test/template.env）
pnpm exec tsc --noEmit  # 仅类型检查

致谢

• learnX — 清华大学网络学堂 iOS/Android 客户端；本项目的浏览器 SSO 登录流程与 fingerprint 注册逻辑参考了 learnX 的实现。
• thu-learn-lib — 提供所有 API 调用、身份认证与数据解析能力的 JavaScript SDK。

开源协议

本项目以 MIT 许可证开源。