Skip to content
BranchesTags

Repository files navigation

THEIA

THEIA v0.7.7：北京化工大学校园工作台使用说明

下载 Windows x64 v0.7.7 · GitHub 源码 · Android 客户端 · 用户指南 · 发行说明

THEIA 是面向北京化工大学学生的本地优先 Windows 校园工作台。它把教务系统、北化在线 THEOL、校园邮箱和本地学习工具放到同一个桌面应用中，负责读取、整理、计算、提醒和准备操作；学校系统中的最终提交、选课决定和成绩认定仍由用户确认。

THEIA 面向所有人开放协作，任何人都可以 Fork 项目、参与开发并提交 Pull Request；直接 commit 和发布 Release 需要获得仓库协作者权限。提交前请遵守贡献者指南中的测试、安全和审查约定。

文档入口

本文件 README.md 是 THEIA 当前的正式综合说明。它取代旧版 README，具体开发流程和稳定接口以现行文档及源码为准。

前言

进入大学，来到一个全新的地方，有着不一样的规则。或许你会迷茫，或许你会不知所措。但是没关系，因为大家都是这样过来的，即便了解以及适应的过程或许有些不好受。

所以我决定完成这样的东西，尝试帮助你简单且快速的了解。

THEIA - 光明神之母

我希望它完成的事情和祂的名字一样。大学是光明的，在大学里的大家是光明的。不要被阴影或雾霾遮蔽了双眼，如果有，那么就请祂来驱散吧。

北京化工大学是一所很棒的学校！但昌平校区建设的太过早了。你可以看到校园建设目前仅有设计图的一半，校外也几乎是山野，公共交通更不算便捷。加上之前黑车猖獗，我想体验过的同学一定深有体会。

但大学生是不能被束缚在校园里的。尤其是这样一个地理位置极其偏僻的校园建设优化不算完善的理科综合类院校。宿舍教学楼食堂两点一线会让人愈发迷茫。起码我是这样觉得的。

我想去玉屏山上拍日出日落，带着花香露水味道的冉冉升起的红日，蜜蜂和蝴蝶飞舞的晚霞；我想去柳湖拍苍鹭；我想去杏坛苑拍小猫咪。

  • 昌平校区是很美的。真希望你有时间能多看看。
  • 北京的秋天是很美的。真希望你有时间能多看看。
  • 祖国是很美的。真希望你有时间能多看看。

有时间要多和重要的人在一起；有时间要多做些自己想做的事。如果我刚到大学时能够明白这些就好了。

因此我喜欢花一天，感觉一切是爱

--《今天只做一件事》 陈奕迅

祂会给你一天。

祂会驱散侵蚀你时间的一切。

一、快速上手

当你安装并启动 THEIA 后，可以先快速浏览界面以便熟悉。放心，祂比教务系统要简易且快速得多。THEIA 的完整功能需要 Windows 桌面客户端；浏览器预览只用于查看前端，不提供学校认证、Windows 加密存储、文件选择、内置浏览器或本地模型密钥能力。

当然你也可以直接接入你的账号。

点击“设置与接入”，会有弹窗显示设置界面。点击“数据”。

在这里可以看到各种数据源接入选项。

数据源接入

  1. 统一身份认证：这是学校的统一身份认证，也叫 CAS。在此填写学号和统一身份认证密码，然后点击“登录”。登录后，THEIA 会分别检查教务系统（JWGLXT）和北化在线 THEOL 的会话；一个来源失败不会清空另一个来源已经成功取得的数据。
  2. 教务系统 API：这是可选的 API 优先同步通道，需要单独填写教务系统账号和密码。它与 CAS 浏览器会话隔离，也不是 CAS 密码的替代品；未启用或请求失败时，THEIA 会按来源尝试使用已认证的浏览器会话。
  3. 校园邮箱：在这里输入邮箱账号、邮箱密码以及“客户端授权”密码。授权密码需登录校园邮箱，在“设置”“邮箱设置”“客户端设置”中生成。邮箱使用 IMAP 收信，邮件正文和附件按需读取。

校园邮箱

邮箱只可收件而不可发件。这适合不常用校园邮箱、但又需要查看通知的同学；你可以快速查看邮件并下载附件。

功能 北化在线 THEOL 教务管理系统
统一身份认证 支持 支持
教务系统 API 不支持 支持且很快速！

日志、导出与同步

数据接入部分的下方是日志区域，方便有自行 debug 能力的同学排查问题。我显然无法保证其没有任何 bug，但如果有且你需要，可以联系我，只需要以任何你喜欢的方式发送“问题描述 + 日志截图”。

关于导出部分，THEIA 支持多种导出方式，但其实我觉得并没有什么应用面，但不管怎么说，还是留下了各种接口。

当你连接了账号之后，你可以点击“设置与接口”中的“同步”，你可以在这里看到所有同步到本地的数据状态。当然，你也可以手动的同步数据。

首次同步后，课表、考试、成绩、学业进度、课程、作业和通知会按来源逐步出现。短暂的单域失败会保留上一次有效的本地结果；空结果也不能脱离来源状态被理解为“学校没有数据”。

数据安全边界

默认数据目录为 %APPDATA%\THEIA，也可以使用 THEIA_DATA_ROOT 指定隔离目录。账号密码、教务系统 API 凭据、邮箱密码和模型 API Key 由 Electron safeStorage 加密保存（Windows 下通常由 DPAPI 提供支持）。

  • 校园源站请求限定在 buct.edu.cn 及其子域名。
  • 模型服务使用你配置的 HTTPS 地址或本机回环 HTTP。
  • 本机 API 只绑定 127.0.0.1。
  • 外部客户端应从 api-runtime.json 发现当前端口和令牌。
  • 凭据、Cookie、浏览器存储、认证页面、绝对路径和运行期缓存不会进入普通校园快照、AI 导出、本地 API 或诊断日志。
  • 模型请求只包含当前问题和 Agent 实际读取到的最小数据切片。THEIA 不创建云端账号，也不会把学校密码、Cookie 或已认证页面发送给模型服务。
  • “导出给 AI”是用户主动生成的静态阅读包，不是实时校园会话，也不能导回或写入学校系统；其中可能包含成绩、课程或邮件等敏感信息。

Android 客户端

THEIA-Android 是独立的 Android 10+ 客户端，提供课表、成绩、考试、作业、学业进度、地图、空闲教室和公开场馆查询。它保持本地优先和只读校园数据边界，不执行选课、申请、上传、预约等学校侧操作。

二、外观设置

你一定可以看到 THEIA 超前的外观设计！（好吧我开玩笑的）

点击“设置与接口”或者界面右上角的涂鸦板按钮，你可以随心配置外观。

THEIA 提供主题、缩放、3D 背景、动效、色板和渐变映射等设置，并将选择保存在本机。应用启动时会先显示 THEIA 品牌加载画面，再自动切换为主界面；校历、培养计划等离线资产会在后台刷新，不阻塞窗口出现。

我的私货

使用 Three.js 加载 glb 模型。模型由 2dto3d 得来，另外加入了鼠标视差以及动视等特效。

古典

这是最初版 THEIA 的外观，灵感来源于 Hermes 的设计。后来添加了类似 PS“双色映射”的效果，可以将双色图片映射成喜欢的颜色。

北化风情

这是由某位北区办、建设办、校学生会特邀摄影师拍摄的一组四季柳湖；当季节变化时，“北化风情”也会随季节变化。

背景的透明度以及其它参数均可在“背景效果”中调整。

三、整体界面

侧边栏已经比较完善，下面只简述一些值得注意的功能。

1. 概览

快速查看常用信息，点击即可跳转至对应栏目查看详情。

2. 学业顾问

Agent 部分可以看作内置的 AI chat。

要使用学业顾问，请打开“设置与接入 -> 模型服务”，选择协议，填写服务地址、API Key 和模型 ID，先检测连接再保存。当前支持 OpenAI Responses、Anthropic Messages、Gemini GenerateContent 和 Ollama Chat。

默认 read-only 模式

默认是受限权限的 read-only Agent：模型先收到当前问题、快照版本和工具边界，再按需读取课程、课表、考试、成绩、学业进度、作业、通知、邮箱和体测等数据。它没有通用文件系统、命令或任意网页工具，但保留以下已声明的受控操作：

  • 同步校园数据。
  • 发起公开 HTTPS 请求。
  • 打开校园来源页面。
  • 更新 THEIA 设置。
  • 启动或停止已保存目标的选课控制。

这里的“只读”仅指不提供通用文件系统、Shell 或任意网页能力，并不表示所有操作都没有副作用。

“完全访问”模式

显式切换到“完全访问”后，才会额外提供：

  • 本地文件和目录的读写、创建、删除。
  • 执行命令。
  • 任意 HTTP(S) 请求。
  • 打开网页。

运行时不会主动把浏览器会话、Cookie、已解密保存凭据或模型 API Key 注入模型，但完全访问的文件与命令能力可能读取或操作本机敏感文件。

作业、在线测试等学校侧最终提交仍由用户自行完成；已保存的抢课目标可由 Agent 通过受控工具启动。抢课请求只会在用户明确启动并设置的时间窗口内执行，因此课程、教学班、时间窗口和请求参数仍应由用户自行核对。

预算档位为 High、XHigh、Max 和实验性的 Ultra，用于控制探索步数、输出长度和超时，不代表模型一定会使用全部预算。只有在用户发送问题后，Agent 才会发起模型请求；工具调用、回答和使用量会在会话中显示并保存在本机。没有配置模型服务、API Key 无法由当前 Windows 账户解密或流式接口不可用时，Agent 会停止并显示可操作的错误，不会生成伪造的本地答案。

3. 课表

已实现课表 PDF 输出：通过教务系统原生流程请求并保存 PDF；是否成功仍取决于教务会话和学校页面状态。（虽然估计没人会这样用。）

4. 作业

作业与在线测试支持 THEOL 任务读取、本地工作包、答案草稿和测试答案准备；测试答案可以写入内置浏览器中的题目，最终内容仍需逐题核对并由用户在学校页面提交。不同课程页面和附件的实际格式可能不同。

5. 通知与校园邮箱

通知页面集中展示教务系统和北化在线 THEOL 的通知，支持搜索和查看详情。校园邮箱单独使用 IMAP 收信；列表信息先保存在本机，邮件正文按需读取，附件是否打开由用户决定。

6. 成绩

点击可以切换“阶段”和“累计” GPA，查看每个学期的学分、成绩以及 GPA 趋势。页面保留学校返回的 GPA，也可能展示按本地规则计算的辅助 GPA；两者不等同于学校最终认定。

7. 学业

不同教务通道返回的培养方案层级可能不一致。THEIA 会进行归一化和补全；如果只能根据已同步成绩归类，或详情不完整，数据域可能标记为“部分”或“推断”。学业页用于查看培养方案、课程完成情况、学分缺口和已选课程，毕业判断仍应以学校正式培养方案为准。

8. 课程

课程页面显示北化在线 THEOL 课程，支持按课程名、课程代码或教师搜索，并可按学期和课程类别筛选。进入课程详情后，可以查看课程基本信息、教学资料、课程资源和抓取状态；资料在本地预览，打开学校原站仍是独立的明确操作。

9. 抢课

THEIA 会从本地工作周历的规则解析结果中尝试预填选课窗口，实际开放状态仍以选课门户返回的状态为准。

用户从下方全校课表明确选择目标并保存后，显式启动哨兵和时间窗口，应用才会在运行期间对已配置目标执行有限尝试；电脑关机、网络断开或应用未运行时不会发出选课请求。THEIA 不会自动退课、评教或提交其它学校业务。

下方全校课表可供提前查询课程以及教学班。

10. 学习工具

文档

由“校历”“工作周历”“教学进程表”构成，内容来自教务处通知的离线资料。切换至“培养计划”可以查看 THEIA 尝试匹配并保留的当前专业培养计划 PDF；匹配不确定或未获取时，以教务系统为准。

空闲教室

查询空闲教室。桌面端可以直接查看，Iris 也可以按节次返回空闲教室图片（见后文）。

体测评分

在桌面端主动导入或更新体测档案时，可以通过统一身份认证从 tygl 系统读取体测成绩；也支持本地估算。

场馆状态

读取 MOTION 的公开场馆状态，只读，不提供预约操作。也可以使用 Iris 获取（见后文）。

创新学分

页面可以登记课程、竞赛、大创、论文、专利、讲座、认证和创业等项目并进行本地估算。当前页面按手册口径展示创新创业教育要求；只有学校正式认定并入账的项目才能计入毕业要求，具体学分要求以学校最新规定为准。

学业预警

根据 GPA 和已获学分估算页面显示的升年级及预警提示。它是本地计算工具，不替代学校正式的学业预警或学籍认定。

第二课堂

按德、智、体、美、劳五个维度估算基础分、拓展分和相关门槛，并查看分值表。计算结果仅供整理和提醒，最终以第二课堂平台的正式记录和认定为准。

11. 地图

北京化工大学昌平校区平面图以及卫星图，同时附有第一教学楼和第二教学楼各楼层的平面图。

四、数据接口

你可以在“设置与接口”中的“接口”页面找到以下内容。

1. 原生 API

THEIA 为本机集成预留了数据接口。桌面客户端运行时会启动只绑定 127.0.0.1 的 loopback 服务；数据端点只读。课程资料、作业和测试使用明确数据域的 POST /v1/sync，直接调用本地同步器，不经过模型；POST /v1/agent/chat 仅用于顾问对话，不执行学校侧写入。

每次请求都需要使用 api-runtime.json 中的令牌，可通过 Authorization: Bearer <token> 或 ?token=<token> 传递。请求还必须使用精确的 Host: 127.0.0.1:<port>；服务只接受受限的本机来源。API 不读取或暴露学校密码、Cookie、认证页面、学校原始 HTML 或模型 API Key。

  • 默认首选端口为 8765。
  • 端口被占用时会在有限范围内回退。
  • 实际 127.0.0.1 地址、端口和每次启动重新生成的令牌会写入数据目录中的 api-runtime.json。
  • 外部客户端应读取该文件并携带令牌，不要硬编码端口或令牌。

常用端点包括：

GET /v1/health
GET /v1/feed
GET /v1/snapshot
GET /v1/terms
GET /v1/schedule
GET /v1/exams
GET /v1/grades
GET /v1/academic-progress
GET /v1/selected-courses
GET /v1/assignments
GET /v1/notices
GET /v1/emails
GET /v1/calendar.ics
GET /v1/venue-catalog
GET /v1/venue-status?detailUrl=<详情页>&date=YYYY-MM-DD&venue=<场馆组>
GET /v1/venue-statuses?activity=<项目>&date=YYYY-MM-DD
GET /v1/motion-table-image?activity=<项目>&date=YYYY-MM-DD
GET /v1/free-classroom-image?periods=<节次>&weekdays=<星期>&termId=<学期ID>
GET /v1/table-image?domain=<域>&title=<标题>&limit=<行数>
GET /v1/school-schedule?keyword=<课程>&termId=<学期ID>&page=<页>&pageSize=<每页数>
POST /v1/sync  {"domains":["theol-course-details","assignments"]}
POST /v1/agent/chat

完整参数和响应契约见API 与 IPC 参考。

2. MCP

支持向 Codex / Claude Code 接入本机只读 MCP。标准桥接位于 integration/theia-mcp.mjs，它通过本机 API 读取当前快照，并复用 Agent 的有界、脱敏投影。只暴露数据健康、校园记录搜索、截止事项、学业进度、学业分析、课程分析、单封邮件正文和用户明确放入本机资料目录的文档读取；不暴露凭据、Cookie、浏览器会话、绝对路径、任意网络或学校侧写入。

使用外部 MCP 时，THEIA 桌面端需要运行并启用本机 API。完整配置、令牌认证和工具边界见本地数据接口。

3. Iris

Iris 是 THEIA 便携性的一大进步。

你可以在 QQ 开放平台申请一个 QQ Bot 账号，免费且只要有一个 QQ 号即可申请。

然后在 THEIA 设置里输入 AppID 以及 AppSecret，点击启动，即可启动 THEIA 内置的 Iris。Iris 是可选的本地 QQ 桌面伴侣，不是独立的云端校园服务。

点击控制面板可以发送测试消息或自定义发送格式内容。

当确认运行正常之后，需要保持电脑开机、THEIA 桌面端和 Iris 运行，并确保网络可用。无论身处何地，都可以使用 QQ 给 Bot 发送消息，查询 THEIA 提供的校园信息。

Iris 指令

theia status/状态/s                 查看桌面端、本机接口、同步和数据状态
theia today/今天/今日/now             查看今天的课程、考试和作业截止事项
theia agent/顾问/问问/a <问题>        与当前 THEIA Agent 对话
theia motion/运动/场馆/m <项目>       查询今天指定运动项目的场馆状态表
theia classroom/教室/空闲/c <节次>    查看指定节次的空闲教室图片

场馆查询和教室查询正常情况下输出图片；图片渲染不可用时，Iris 可能返回文字版或提示回到 THEIA 桌面端查看。

五、自动更新

支持范围

自 v0.6.1 版本之后，正式 Windows 安装包便支持了自动更新功能；浏览器预览和开发模式不支持自动更新。

更新流程

  1. THEIA 通过 electron-updater 优先检查腾讯云 COS 的公开更新目录。
  2. 打包版启动时会自动检查，在右下角提示新版本；“更新”按钮开始下载，“跳过版本”会记住当前版本。
  3. 关于页会显示下载进度、实际文件大小和速度；更新下载完成后，退出应用时会自动安装。

如果 COS 元数据落后或暂时不可用，客户端会自动回退到 GitHub Release，并使用回退源继续下载；GitHub 同时保留源码和发行存档。

因此，校园网无法稳定直连 GitHub 时，THEIA 仍优先从 COS 检查、下载和安装更新；COS 异常时则使用 GitHub 作为可用回退源。

当前 v0.7.7 的安装包、源码归档和 SHA-256 校验值见发行说明。安装包未配置可公开验证的 Authenticode 证书，Windows 可能显示未知发布者或 SmartScreen 提示。

本机发布到 COS

COS 发布不需要每次登录控制台。首次在本机运行 npm run cos:configure，填入腾讯云 API 密钥；THEIA 会将凭据用当前 Windows 用户的 DPAPI 保存到 %APPDATA%\\THEIA\\cos-publish.json，不会写入仓库。完成配置后，npm run dist:installer 会自动将 stable/ 更新目录中的安装包、blockmap、latest.yml 和源码归档上传到 COS；已有 release-bin 文件时也可以单独运行 npm run cos:publish 重传。

六、杂项

关于我

北京化工大学非信院专业本科在读。

找到我：

北化心理

另外附心理咨询预约方式。相关时间和联系方式可能随学校安排变化，请以北化心理最新通知为准。

  • 网络预约网址：http://psy.buct.edu.cn（校园网环境）
  • 预约时限：可预约 7 日内咨询
  • 昌平校区接待时间：周一至周日 9:00-18:00
  • 昌平校区现场预约：大学生活动中心 231
  • 昌平校区电话预约：80191033

本人及 THEIA 项目与北化心理不存在隶属、授权、代理或官方合作关系。本项目不代表北化心理的官方立场，相关功能与信息仅供参考，不构成心理咨询、诊断或治疗建议；如有需要，请通过学校官方渠道或专业机构寻求帮助。仅在此附带以便有需。

如有需要请务必联系北化心理，老师和同学都是极好极好的人。 不在这个时间就去找导员，找导员也没用可以找我。我应该没睡。 我可能帮不了你什么，但是你如果想的话我可以陪你喝一杯。

结语

真希望真希望能够帮到你。

你应该学习人类的正义 按照伦理生活 按照指示做事，这样才是正确的。 但是啊，一定不仅仅如此吧？

--《不可解》 花譜

About

北京化工大学校园工作台，整合教务管理系统、北化在线THEOL、邮箱、校历与本地 AI 辅助。Android：https://github.com/bakahuiii/THEIA-Android

Topics

academic-advisorbeijing-university-of-chemical-technologybuctcampus-servicescourse-selectionelectronjwglxtlocal-firstreacttheoltypescriptunified-authentication

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Contributors

Languages