chaoxing-subtitles
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
超星课程回放字幕导出
适用于西安电子科技大学的超星录直播页面。使用有课程回放权限的个人账号登录,通过 HTTP 查询课表和下载字幕。首次安装请参阅 安装说明。(其实完全可以交给codex等安装配置...)
项目结构
chaoxing-subtitles/
download_date.py 按日期查询和批量导出入口
download_live.py HTTP 会话、回放解析及单回放下载
search_subtitles.py 关键语句定位入口
server.py MCP 服务入口(已注册路径)
export_worker.py 后台导出进程
mcp_jobs.py 后台任务状态和进度
export_storage.py 输出锁和历史字幕清理
project_core.py 共享配置与错误类型
subtitle_format.py 下载、清理、TXT 和定位共用的 VTT 解析器
session_manager.py 会话检查、Cookie 更新及登录任务管理
login_worker.py 专用 Edge 静默恢复和扫码等待
manage_login.py 登录与续期命令行入口
requirements.txt 依赖版本
tests/ 离线自动测试
scripts/check_mcp.py MCP 连接和流程检查
.local/ 本地登录态、专用浏览器配置、任务状态及锁(不提交)
subtitles/ 导出的字幕和结果清单(不提交)Related MCP server: WeChat Local Agent MCP
自动登录与按需续期
python manage_login.py先验证 .local/auth.json 中的现有会话;需要恢复时,使用 .local/browser-profile/ 中的专用 Edge 配置尝试静默 SSO。已有的登录态会自动导入该专用配置。静默恢复不成功时打开登录窗口,由你扫码或完成验证;程序检测成功后会自动保存并关闭专用窗口,不需要手工复制 Cookie 或正常关闭录制窗口。
日常按日期导出及单回放下载会在任务前自动检查会话,保存服务器返回的更新 Cookie。任务中遇到明确的未登录响应(包括 HTTP 200 的“请先登录”页面)时,会恢复会话并将该请求重试一次。导出任务等待验证时显示 waiting_login,验证完成后继续原任务;关闭窗口或超时会报告失败并保留历史字幕。权限不足的 HTTP 403 不会被当作登录过期反复尝试。
正在进行静默恢复时再次请求交互登录,会复用该进程并允许它在需要时打开验证窗口,避免请求被静默模式吞掉。
不保存账号密码;会话文件和浏览器配置仅在本机 .local/ 内保存,并由 .gitignore 排除。登录状态以超星服务器为准,按需更新,不人为延长 Cookie 有效期,也不在闲置时定时访问网站。
python manage_login.py --status
python manage_login.py --refresh
python manage_login.py --refresh --silent--status 查看最近一次恢复任务;--refresh 即使 HTTP 会话有效也刷新专用浏览器会话;--silent 不打开扫码窗口,无法静默恢复时返回 login_required。交互验证默认等待 10 分钟。自定义 --auth 文件可继续用于下载,但自动网页登录仅管理默认的 .local/auth.json。
查看指定日期的课程
python download_date.py 2026-10-26 --list-only下载指定日期的全部回放字幕
python download_date.py 2026-10-26替换日期即可查询其他日期。程序从课程实际时间戳计算周次,并与课表日期核对。同名课程的不同回放编号分别处理。尚未开始或正在直播的课程不尝试下载。
结果位于 subtitles/日期/:每个节次及课程目录下包含 VTT 和 TXT,manifest.json 记录逐项结果。重复执行会跳过已有有效 VTT;失败项重新尝试。使用 --overwrite 可以重新下载。
VTT 的文件头、时间轴和有效字幕片段使用同一解析器校验,损坏的缓存会重新下载;不会仅凭文件头或 --> 就判为成功。目标文件、临时文件及其上级目录的链接也会在写入前检查。
默认在本次日期的全部课程字幕成功导出、且 VTT/TXT 文件校验通过后,清理更早日期的程序生成目录及其中的字幕、清单。失败、无字幕、暂无回放或空课表时保留历史文件。更晚日期、未识别的目录、含用户额外文件的目录及链接目标不清理。早期单课脚本写在输出根目录的数字文件名样本,仅在确认与生成字幕内容重复时删除。清理详情记录在清单的 cleanup 字段中。
如果某次需要保留历史:
python download_date.py 2026-10-26 --keep-history所有按日期的导出共用输出锁,避免一个任务清理另一个仍在写入的目录。登录态、专用浏览器配置、项目代码和后台任务状态不参与字幕清理。
默认查询网页当前选中的学期。其他学期可指定 --semester-id 编号;编号来自课表学期下拉框的实际值。日期超出选定学期或接口结构无法识别时会报错,避免导出错误日期。
按单个编号下载
python download_live.py 12828087状态与检查
complete:回放字幕已保存或已有有效文件。unavailable:当前课表没有可用回放入口。no_subtitle:字幕接口返回不含时间轴的空 VTT。failed:网络、权限、响应格式或文件保存失败。pending:尚未执行,例如任务被中断。
退出码:0 表示执行完成且无失败项;1 表示查询或整体执行失败;2 表示批次中存在失败项;3 表示字幕已导出但历史清理出错。空课表和无可用回放会明确显示数量。
python -m unittest discover -s tests -v离线测试使用系统临时目录与模拟 HTTP,不依赖真实登录态,也不把测试用的锁文件留在项目运行目录。
临时定位关键语句
python search_subtitles.py "网络安全" --date 2026-10-26 --limit 10不指定 --date 时,搜索最近一次导出的日期。返回课程、节次、原文、字幕起止时间、前后文、VTT/TXT 行号及回放链接。匹配忽略标点、空白和英文大小写,支持一句话跨多个字幕片段;当前采用文字匹配,不做语义改写匹配。
如果 TXT 被手工修改或已不存在,仍返回 VTT 原文、时间点和行号,但不返回未经验证的 TXT 行号;text_mapping_warnings 提示这些文件。个别字幕损坏时继续检索其他有效文件,并通过 invalid_files 返回损坏数量。
时间点精度为字幕片段级。回放链接打开对应页面后,可按显示的时间定位;尚未验证播放器的自动跳转参数。
搜索结果临时返回,不另建长期标注库或索引。对应日期的字幕删除后,本地不再保留其关键句追踪数据。清理正在进行时,搜索会等待短暂的输出锁,超时后可重试。
在 Codex 中使用 MCP
按 安装说明 将 chaoxing-subtitles 注册为 Codex 的本地 STDIO 服务。重启 Codex 后,可以直接说:
用 chaoxing-subtitles 检查超星登录态,然后下载 2026-10-26 的所有课程回放字幕。
工具 | 用途 |
| 检查并更新会话,失效时启动后台静默恢复 |
| 查询某天的课程和回放状态 |
| 启动后台导出,全部成功后默认清理更早日期的结果 |
| 查询进度、失败项和结果位置 |
| 临时定位关键语句的时间点、前后文和文件行号 |
| 启动后台登录恢复,必要时打开扫码或验证窗口 |
| 查询恢复进度、是否需要用户验证及完成状态 |
导出阶段只返回统计和文件位置,字幕正文保存在本地。同一日期已有任务执行时会返回现有任务。任务状态保存在 .local/jobs/;若后台进程被宿主结束,查询时会标记为中断,可重新发起导出并跳过已有有效文件。
多个登录请求会共用同一个恢复进程,避免重复打开浏览器。check_session 和只读课表查询不会长时间等待扫码;Agent 可以调用 start_login 后查询 get_login_status。后台导出会自行等待并恢复,其进度中的 login 字段会提示需要完成的验证。
例如可以对 Agent 说:“下载 2026-10-29 的全部字幕,成功后清理旧日期的字幕。”或者:“在 2026-10-26 的字幕中定位‘网络安全’,给我时间点、前后文和回放链接。”每个后台任务独立保存统计,清单也带有精确的 job_id。同一天后续导出不会覆盖旧任务的进度和错误;结果被清理或已由后续任务替代时,旧任务的 output_available 为 false。
MCP STDIO 由客户端启动和管理,直接运行 python server.py 时等待输入且无普通终端输出是正常现象。
需要真实查询课表并测试导出时:
python scripts/check_mcp.py --date 2026-10-26协议连接不调用模型 API,无需额外配置 API Key。Codex 的 MCP 配置方式见官方文档。会话、原始诊断样本、任务状态及导出文件通过 .gitignore 排除。
许可证
本项目以 MIT 许可证 发布。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server providing attendance data queries via the CloudTime API.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseAqualityCmaintenanceLocal MCP server that indexes public YouTube captions into a searchable SQLite FTS5 database, enabling timestamped search and transcript retrieval without an API key.6MIT
- AlicenseBqualityCmaintenanceA local-first MCP server that lets agents search and summarize a user's own WeChat history, with stable pagination, bulk chat workflows, unread/event queries, and gated enrichment tools.193MIT
- AlicenseNot gradedqualityDmaintenanceAn out-of-the-box multi-tenant MCP server that lets MCP clients access knowledge retrieval, task dispatch, deliverable management, and multi-agent consultation services via SSE or stdio.MIT
- AlicenseAqualityDmaintenanceMCP server for parsing Douyin links to fetch video info/download links, transcribing audio locally, and organizing transcripts into polished spoken copy.51Apache 2.0