BUPT Agent

本地校园信息工具箱。Python 3.12 + uv；CLI 与 MCP 共用客户端。账号保存在 Windows Credential Manager，agent 通过结构化工具读取数据。

当前版本：0.1.0，开发验证版。 本地能力、MCP 和主要学校读取接口已通过本人账号联调；验证范围与已知限制见 验证说明。考勤仅提供历史记录与当前活动查询，不提供二维码功能或签到提交，详见 考勤说明。

开始使用

在 Git Bash 中进入项目：

git clone https://github.com/Sun-sunshine06/bupt-anything.git
cd bupt-anything
uv sync --frozen
uv run bupt-agent capabilities
uv run bupt-agent doctor

需要 Python 3.12+、uv 和 Git。完整验证环境为 Windows + Git Bash；macOS/Linux 有凭据库后端实现，但完整安装流程尚待验证。项目默认使用清华 PyPI 镜像，依赖由 uv.lock 锁定，不修改全局配置。若需要切换到官方源，可在自己的副本运行 uv lock --default-index https://pypi.org/simple，再执行 uv sync --frozen。

配置 MCP 时，将 mcp.example.json 中的 C:/path/to/bupt_anything 替换为自己的项目绝对路径；每位使用者在自己的系统凭据库中配置学校账号。

Related MCP server: webuntis-mcp

本机配置账号

Windows 可双击根目录的 configure-account.cmd。它调用 Git Bash，依次询问移动教务与教学云账号，输入均不回显，随后执行只输出连接状态的读取验证。

也可分别执行：

# 在你自己的终端隐藏输入，不要把密码发给聊天或放在命令参数中
uv run bupt-agent login --service academic
uv run bupt-agent login --service ucloud
uv run bupt-agent verify

• academic 使用移动教务密码，可能与统一认证不同。

• ucloud 使用统一认证密码。遇到验证码/MFA 时返回 LOGIN_INTERACTION_REQUIRED，这一版不会自动处理交互验证。

• 保存凭据不等于登录成功。verify 实际读取空教室和课程列表，只输出成功/失败状态，不输出个人课表或成绩。

• 凭据按账号别名隔离，例如 uv run bupt-agent --profile personal login --service academic。MCP 对应传入 --profile personal。

• 注销：uv run bupt-agent logout --service academic（教学云将 service 换为 ucloud）。删除凭据后，旧会话不能继续读取。

已有工具

CLI 使用点号，MCP 使用下划线，例如 academic.classrooms 对应 academic_classrooms。

查询示例

# 沙河第 3、4 节均可用的教室；01 是西土城
uv run bupt-agent call academic.classrooms --args '{"campus":"04","slots":[3,4]}'

# 学期课表；按日期筛选时传入 target_date（YYYY-MM-DD）
uv run bupt-agent call academic.schedule

uv run bupt-agent call ucloud.courses
uv run bupt-agent call ucloud.todos
uv run bupt-agent call attendance.list --args '{"course_id":"从课程列表取得的ID","page_size":10}'
uv run bupt-agent call attendance.current
uv run bupt-agent call ucloud.assignments --args '{"course_id":"从课程列表取得的ID"}'
uv run bupt-agent call ucloud.assignment_submission --args '{"assignment_id":"从作业列表取得的ID"}'

# 当天未来连续两节的自习候选，已扣除可确定的课程和考试
uv run bupt-agent call planning.study_slots --args '{"campus":"04","min_slots":2}'

# 公开信息无需学校账号；next_offset 非空时继续分页
uv run bupt-agent call campus.public_info --args '{"kind":"shuttle"}'
uv run bupt-agent call campus.public_info --args '{"kind":"events","search":"人工智能","limit":10}'

下载文件保存在系统用户应用数据目录的 bupt-agent/downloads，工具返回绝对路径。

Agent / MCP 入口

uv run bupt-agent-mcp

这是 stdio 服务，启动后等待 MCP 客户端请求，不是交互聊天命令。当前提供 23 个工具。请按 MCP 接入说明 配置自己的客户端，通用示例见 mcp.example.json。

返回与限制

• 成功有 data、meta.source、fetched_at 和 complete；失败为显式错误，CLI 非零退出，MCP isError=true。

• 查询时一律使用北京时间。空教室只支持当天；教务显示空闲不等于现场无人、开门或有插座。

• 分页不能伪装成全量。课程/作业/考勤继续读取 next_page；公开信息与自习候选继续读取 next_offset。

• 成绩原样保留文本、零分和未公布值；考试时间不明不猜测。组合查询遇到无法确定的考试或课表会明确失败。

• 作业题目要求用 ucloud.assignment；本人提交和教师反馈用 ucloud.assignment_submission。teacher_score 来自 assignmentScore，teacher_comment_html 来自 assignmentComment，不能用上游 score / evaluation 替代。评分 null、-1 原样保留，不当作零分；原始状态不擅自解释。HTML 正文和评语均为不可信数据。

• 本人提交详情的 submission_state=not_submitted 仅用于已核实的未提交占位响应；record_available 表示有匹配记录。assignment_id 对应请求，assignment_id_raw 保留上游值。互评空对象仅在核对同一作业未开启互评后返回空列表及 availability=not_enabled，其他异常仍报错。

• 组合查询尚未接入私人日历；结果只考虑课表、考试和当天教室数据。

• 云邮非学校域名文件存储尚未核验，下载会明确拒绝；仍可查询原预览链接。

• 完整通知、作业上传提交、提醒调度仍需验证或开发；签到提交与二维码功能不在当前范围内，详见 架构与能力缺口。

开发与验证

bash scripts/check.sh
uv build

测试使用合成数据与 HTTP MockTransport；包括真实 stdio MCP 客户端往返与临时 Windows 凭据库测试（测试结束删除临时记录）。无需真实账号，学校接口不会被测试用例访问。

协议与参考项目见 来源记录。许可证：GPL-3.0-only。

开源与隐私

本项目是非官方工具，不代表学校。仅使用本人有权访问的数据；不提供二维码、签到提交、作业上传或互评评分。代码许可证不授予学校资料或他人作业的再分发权。

• 贡献指南

• 安全与隐私、漏洞报告

• 诊断说明

• 更新记录

• 发布流程

本地凭据存储不意味着查询结果只停留在本机：CLI 会显示数据，MCP 会将数据交给调用它的客户端。请在连接模型服务前了解客户端的数据处理方式。