🐱 BJTU Desktop Pet Assistant — 北京交通大学全能助手桌宠

一只会聊天、会查课表、会看贴吧的 Doro 桌宠 🍊

Doro桌宠

📖 项目介绍

BJTU Desktop Pet Assistant 是一款面向北京交通大学学生的桌面宠物应用。

Doro（一只喜欢橘子、爱钻纸箱的粉色小生物）栖息在你的桌面上，它能：

💬 AI 对话 — 通过 DeepSeek 大模型跟你聊天，话题自带北交内幕
📚 教务助手 — 自动抓取课表、考试安排、成绩，考前提醒不挂科
📧 邮件检查 — 通过 CAS SSO 自动检查学校邮箱（Coremail）
🌐 贴吧监控 — 实时爬取北交贴吧热门帖子，结合 AI 生成校园话题
🔔 智能通知 — 新邮件、考试倒计时、作业 DDL 一个不漏

✨ 核心功能

功能	说明	状态
🪟 桌宠窗口	置顶、透明、可拖拽的宠物窗口，GIF 动画	✅
📌 系统托盘	最小化到托盘，后台持续工作	✅
🤖 AI 聊天	DeepSeek 大模型对话，流式输出	✅
🎭 Doro 人设	呆萌搞事的粉色小生物人格	✅
💬 自动聊天	基于贴吧热帖 + 考试信息自动发起话题	✅
🎨 漫画气泡	渐入渐出的漫画风格对话气泡	✅
📅 课表查看	CAS 登录后自动抓取并展示课程表	✅
📝 成绩查询	查看各学期成绩与 GPA	✅
✉️ 邮件提醒	通过 MIS SSO 检查邮箱（Coremail）	✅
🗺️ 贴吧爬取	Playwright + stealth 绕过反爬	✅

🚀 快速开始

前置要求

Python 3.9+
Playwright 浏览器（首次运行自动提示安装）

安装

# 1. 克隆仓库
git clone https://github.com/your-org/bjtu-pet.git
cd bjtu-pet

# 2. 安装依赖
pip install -r requirements.txt

# 3. 安装 Playwright 浏览器
playwright install chromium

# 4. 配置 DeepSeek API Key（可选，用于 AI 聊天）
# 在项目根目录创建 .env 文件：
# DEEPSEEK_API_KEY=sk-your-key-here
cp .env.example .env
# 编辑 .env 填入你的 API Key

运行

python main.py

首次运行 Doro 会出现在屏幕右下角！右键点击 Doro 打开功能菜单。

🏗️ 项目架构

bjtu-pet/
├── main.py                 # 入口
├── config/                 # 配置层 (YAML + dataclass)
│   ├── settings.py         # ConfigManager + 9 个 Config dataclass
│   └── default_config.yaml # 默认配置
├── core/                   # 核心层
│   ├── app.py              # PetApplication — 主控制器 (600行)
│   ├── auto_chat.py        # AI 自动聊天话题生成器
│   ├── scheduler.py        # APScheduler 定时任务调度
│   ├── notifier.py         # 通知分发
│   └── plugin_base.py      # 模块基类
├── storage/                # 持久化层
│   ├── database.py         # SQLite + 12 张表 + ORM
│   ├── credential_vault.py # Fernet 加密凭据存储
│   └── models.py           # 数据模型
├── integration/            # 外部集成层
│   ├── deepseek.py         # DeepSeek API (流式/非流式)
│   ├── tieba.py            # 贴吧爬虫 (Playwright + stealth)
│   ├── auth.py             # CAS 统一认证 (两阶段登录)
│   ├── captcha.py          # 验证码对话框
│   └── http_client.py      # HTTP 会话管理
├── modules/                # 业务模块
│   ├── courses/            # 课表解析
│   ├── homework/           # 作业解析
│   ├── email/              # 邮件解析 (Coremail)
│   └── exams/              # 考试+成绩解析
├── ui/                     # 表现层 (13 个 widget)
│   ├── pet_window.py       # 桌宠主窗口
│   ├── speech_bubble.py    # 漫画风格气泡
│   ├── chat_window.py      # AI 对话窗口
│   └── ...                 # 各功能视图
├── sdd/                    # 📐 SDD 规格文档
│   ├── requirements/       # 需求全景图 + 可追溯矩阵
│   ├── specs/              # 6 份功能规格说明书
│   ├── harness/            # 行为穿刺测试
│   └── design/             # 架构设计文档
├── tests/                  # pytest 自动化测试
├── docs/                   # 用户手册
└── .github/workflows/      # CI/CD

详见架构设计文档

🔧 配置说明

配置文件位于 ~/.bjtu-pet/user_config.yaml，首次运行后自动生成。

关键配置项：

deepseek:
  api_key: "sk-xxx"       # DeepSeek API Key

tieba:
  enabled: true           # 是否启用贴吧爬取
  scrape_interval: 60     # 爬取间隔(分钟)

auto_chat:
  enabled: true           # 是否启用自动聊天
  interval: 2             # 话题生成间隔(分钟)
  use_tieba: true         # 是否使用贴吧数据
  use_exam: true          # 是否使用考试信息

🧪 测试

# 运行 Harness 穿刺测试（无需网络）
python sdd/harness/harness_database.py
python sdd/harness/harness_deepseek.py
python sdd/harness/harness_tieba.py

# 运行 pytest 单元测试
pytest tests/ -v

# 带覆盖率
pytest tests/ -v --cov=. --cov-report=html

📐 SDD 开发流程

本项目采用 Specification Driven Development:

需求全景地图 — 5 Epics / 20+ Features
可追踪矩阵 — Feature → Code → Test 映射
6 份功能 Spec — 输入/输出/边界条件/验收标准
3 份 Harness 穿刺测试 — 可独立运行的 Spec 一致性验证

🧑‍💻 AI 工具应用实践

本项目在全开发周期中系统性地使用了 AI 工具：

阶段	工具	贡献
需求分析	CodeBuddy	Epic 拆解、User Story 编目
架构设计	CodeBuddy	分层架构图、数据流图
编码实现	Copilot / Cursor	~70% 代码有 AI 辅助
测试生成	CodeBuddy	Harness + pytest 用例
文档撰写	CodeBuddy	README、SDD、用户手册

详见 AI 工具使用报告

🧭 项目路线图

Phase 1 (v0.2.0): 基础框架 + 教务集成 + AI 对话 + 贴吧爬取
Phase 2 (v0.3.0): 考试解析器完善、作业抓取、更多通知类型
Phase 3 (v0.4.0): 多模型适配（通义千问、豆包）、插件市场
Phase 4 (v1.0.0): 跨平台打包自动更新、社区反馈闭环

📄 许可证

MIT License — 详见 LICENSE

🙏 致谢

PySide6 — Qt Python 绑定
DeepSeek — AI 大模型 API
Playwright — 浏览器自动化
北京交通大学贴吧的同学们 — 话题来源 🍊

Doro: “Dororo~ 这个项目是不是超棒？！(从纸箱里探出头)”