内容
# campus-cli
> 通过终端或智能助手访问 **大学校园** — 无需打开浏览器。
非官方的CLI/MCP工具，适用于学生。查询课程、下载资料、查看作业和提交情况，直接从命令行或通过 **MCP** 与智能助手交互。目前支持 **Blackboard Learn**；Canvas 和 Moodle 正在开发中（参见 [Providers](#providers)）。
```bash
npx campus-cli login
```
---
## 安装
```bash
# 选项 1 — 直接使用 npx（无需安装）
npx campus-cli login
# 选项 2 — 全局安装
npm install -g campus-cli
campus login
# 选项 3 — 克隆仓库
git clone https://github.com/alejooroncoy/campus-cli
cd campus-cli
npm install # 自动安装 Chromium（postinstall）
node run.js login
```
> 如果 `npm install` 运行带有 `--ignore-scripts`（或登录时仍缺少浏览器），CLI会在首次需要时自动安装 — 无需手动运行 `playwright install`。
---
## 快速入门
### 1. 登录
```bash
campus login
```
打开一个浏览器窗口，显示Microsoft UPC登录页面。使用您的 `u20XXXXXXX@upc.edu.pe` 账户登录（包括MFA，如果已启用）。窗口将自动关闭，登录会话将保存8小时。
> **重要：** 在登录过程中，Microsoft 将显示 **"保持登录状态？"** 消息，带有 **"不再显示"** 复选框。启用该复选框并单击 **Yes** — 这告诉 Microsoft 保持会话活动，对于 CLI 正确保存 cookie 至关重要。
```
campus-cli
大学校园非官方 CLI · Blackboard · Canvas · Moodle
✓ 会话已保存 — 8小时后过期
用户：Juan Pérez García
现在我可以做什么？
campus courses list 查看本学期的课程
campus assignments list <id> 查看待办作业和成绩
campus courses contents <id> 探索课程资料
campus download-folder <id> <fid> 下载整个文件夹
```
### 2. 查看课程和作业
```bash
campus courses list
_100001_1 微积分 [Ultra]
_100002_1 面向对象编程 [Ultra]
_100003_1 数据库 [Ultra]
_100004_1 算法和数据结构 [Ultra]
campus assignments list _100004_1
_200001_1 作业 1 [手动]
成绩：未提交 · 最高：5 分 · 提交截止日期：2026-04-15（剩余 17 天）
```
---
## 命令
> 注意：命令仅适用于 Blackboard（当前唯一实现的提供商）。`campus` 是主命令 — `blackboard`/`blackboard-upc` 仍作为兼容别名。
### 会话
```bash
campus login # Microsoft SSO 身份验证
campus logout # 删除会话
campus whoami # 当前用户和剩余时间
campus status # Blackboard 服务器版本
```
### 课程
```bash
campus courses list
campus courses get <courseId>
campus courses contents <courseId>
campus courses contents <courseId> --parent <folderId> # 浏览子文件夹
campus courses contents <courseId> --type file|folder|assignment
campus courses announcements <courseId>
campus courses grades <courseId>
```
### 作业
```bash
campus assignments list <courseId> # 作业及截止日期和成绩
campus assignments list <courseId> --pending # 仅待办作业
campus assignments attempts <courseId> <id> # 提交历史
campus assignments submit <courseId> <id> -f tarea.pdf
campus assignments submit <courseId> <id> -t "我的回答" -c "评论"
campus assignments submit <courseId> <id> -f borrador.pdf --draft
```
### 下载
```bash
campus download <courseId> <contentId> # 单个文件
campus download-folder <courseId> <folderId> -o ./dir/ # 整个文件夹
campus download-folder <courseId> <folderId> --filter "parcial"
```
### 原始 API / 脚本
```bash
campus api GET /learn/api/public/v1/users/me
campus api GET /learn/api/public/v1/courses -q "limit=10"
campus endpoints # 所有已知端点的目录
campus endpoints --json # 用于管道
```
所有命令都接受 `--json`。加载动画输出到 `stderr`，因此 `--json 2>/dev/null` 是干净的 JSON。
---
## 与智能助手（MCP）一起使用
`campus-cli` 包括一个标准的 **MCP**（模型上下文协议）服务器 — 通过 `npx campus-cli mcp` 使用 stdio 运行，因此适用于任何支持 MCP 的客户端，而不仅仅是 Claude。该服务器还公开了一个 `instructions` 字段（MCP 的 `initialize` 握手的一部分），提供使用指南，以便任何代理都可以自我引导，即使不阅读此 README。已测试适用于最常见的配置：
### Claude Code
在项目中将以下内容添加到 `.mcp.json` 中：
```json
{
"mcpServers": {
"campus": {
"command": "npx",
"args": ["campus-cli", "mcp"]
}
}
}
```
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"campus": {
"command": "npx",
"args": ["campus-cli", "mcp"]
}
}
}
```
### Cursor
`Settings → MCP → Add new MCP server`，或直接编辑 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（按项目）：
```json
{
"mcpServers": {
"campus": {
"command": "npx",
"args": ["campus-cli", "mcp"]
}
}
}
```
### GitHub Copilot（VS Code）
在项目中创建 `.vscode/mcp.json`（或在命令调色板中使用 `MCP: Add Server` 命令）：
```json
{
"servers": {
"campus": {
"type": "stdio",
"command": "npx",
"args": ["campus-cli", "mcp"]
}
}
}
```
### OpenAI Codex CLI
将以下内容添加到 `~/.codex/config.toml` 中：
```toml
[mcp_servers.campus]
command = "npx"
args = ["campus-cli", "mcp"]
```
### Windsurf
编辑 `~/.codeium/windsurf/mcp_config.json`：
```json
{
"mcpServers": {
"campus": {
"command": "npx",
"args": ["campus-cli", "mcp"]
}
}
}
```
### 其他客户端（Perplexity 等）
任何支持 stdio 上的 MCP 的客户端都适用于相同的模式：`npx` 命令，参数 `["campus-cli", "mcp"]`。如果您的客户端未在此处列出，请查看其“`MCP` 服务器”或“模型上下文协议”的文档 — 配置始终归结为这两个数据（命令 + 参数）。
> **注意：** 如果您使用全局安装（`npm install -g campus-cli`），可以在上述任何配置中将 `npx campus-cli` 替换为二进制文件的绝对路径（`which campus`）。
### 可用的 MCP 工具
所有 Blackboard 工具都带有 `blackboard_` 前缀（避免与 Canvas/Moodle 工具冲突）：
| 工具 | 描述 |
|---|---|
| `blackboard_whoami` | 身份验证学生信息 |
| `blackboard_list_courses` | 已注册课程 |
| `blackboard_get_course` | 课程详情 |
| `blackboard_list_contents` | 材料树 |
| `blackboard_list_announcements` | 课程公告 |
| `blackboard_list_assignments` | 作业及截止日期和成绩 |
| `blackboard_list_attempts` | 提交历史 |
| `blackboard_get_grades` | 学期成绩 |
| `blackboard_list_attachments` | 内容附件 |
| `blackboard_download_attachment` | 下载附件（base64） |
| `blackboard_submit_attempt` | 提交作业（需要确认） |
| `blackboard_get_quiz_questions` | 加载测验问题 |
| `blackboard_save_quiz_answer` | 保存答案（不提交） |
| `blackboard_submit_quiz` | 完成并提交测验（需要确认） |
| `blackboard_get_assignment_feedback` | 作业反馈 |
| `blackboard_raw_api` | 任意 Blackboard 端点 |
使用智能助手（Claude, Cursor, Copilot, Codex...），您可以执行以下操作：
> *"这周我有哪些待办作业？"*
> *"帮我下载金融课程的所有考试。"*
> *"我在软件架构课程中的当前成绩是多少？"*
---
## 身份验证工作原理
UPC 使用 **SAML SSO → Microsoft Azure AD**。CLI：
1. 在 UPC SAML URL 上打开 Chromium（Playwright）
2. 显示 Microsoft 登录页面 — 您输入凭证
3. 自动捕获会话 cookie 重定向到 `/ultra`
4. 将所有内容保存到 `~/.blackboard-cli/session.json`（权限 `600`）
会话持续 **8 小时**。之后，您需要重新登录。
---
## 技术栈
- **TypeScript** + `tsx` — 无构建步骤
- **Playwright** — 处理 SAML/SSO 流
- **Axios** — 使用会话 cookie 调用 REST API
- **Commander.js** — CLI 框架
- **MCP SDK** — 标准 MCP 服务器（Claude, Cursor, Copilot, Codex...）
- **Chalk** + **Ora** — 终端输出
---
## 提供商
`campus-cli` 设计为可扩展到多个大学/LMS — 内部架构（`src/providers/<lms>/`）已将每个提供商分离到其自己的文件夹中（身份验证，API，MCP 工具及其自己的前缀）。
| 大学 | LMS | 状态 |
|---|---|---|
| UPC | Blackboard Learn | ✅ 已实现（`blackboard_*`） |
| UTP, USIL, Norbert Wiener | Canvas | 🗺️ 计划中 — 未实现 |
| UCSM, UNAP | Moodle | 🗺️ 计划中 — 未实现 |
您在 Canvas 或 Moodle 大学有账户，并希望帮助实现？欢迎提交 PR — 在开始前请先创建一个问题进行协调。
---
## 注意
- 在 Blackboard Learn `v4000.10.0`（UPC，2026）上测试。
- **非官方** CLI — 与任何大学、Blackboard Inc.、Canvas 或 Moodle 无关联。
- 仅与您自己的账户一起使用。请尊重您大学的服务条款。
- 会话 cookie 保存在本地。不会发送到外部服务器。
---
## 许可证
MIT
