# softcup

**Repository Path**: renyuan233/softcup

## Basic Information

- **Project Name**: softcup
- **Description**: 软件杯
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ouroboros · 衔尾蛇

> **数据结构个性化学习多智能体系统**
> 第十六届中国软件杯大学生软件设计大赛 · A3 赛题
> 《基于大模型的个性化资源生成与学习多智能体系统》

以「数据结构」课程为切入点，通过多智能体协同为每位学生生成个性化、多模态的学习资源，
并让学习行为反哺画像，形成自我强化的数据飞轮 —— 这正是项目取名「衔尾蛇」的由来。

---

## 目录

- [核心能力](#核心能力)
- [系统架构](#系统架构)
- [快速开始](#快速开始)
- [第三方组件与开源协议](#第三方组件与开源协议)
- [AI 辅助开发工具说明](#ai-辅助开发工具说明)
- [课程知识库与版权说明](#课程知识库与版权说明)
- [项目结构](#项目结构)
- [文档](#文档)

---

## 核心能力

| 能力 | 说明 |
|---|---|
| **对话式学习画像** | 摒弃表单，学生用自然语言（支持讯飞语音输入）自述，大模型抽取 7 个硬维度 + 1 个软维度，并随学习过程持续更新 |
| **多智能体协同生成** | 7 个智能体分工协作产出 5 类资源：思维导图、讲解文档、练习题库、拓展阅读、代码案例；另有规划智能体调度、质检智能体复核 |
| **个性化学习路径** | 薄弱点强制前置 + 大模型规划进阶步骤，每步挂载知识点深链直达资源 |
| **智能辅导** | 基于 RAG 与画像的答疑，回答含 Mermaid 图解与知识点延伸入口 |
| **学习效果评估** | 知识点掌握热力图、趋势分析、难度双向自适应 |
| **多模态教学视频** | AI 讲稿 → 讯飞语音配音 → 代码高亮同步 → 一键导出 MP4 |
| **游戏化代码闯关** | 8 类数据结构 19 个关卡，浏览器内写真代码、后端沙箱判题，结果回写画像 |
| **双学习路线** | 自主学习（思维导图枢纽）与系统推荐（多智能体编排台）并行，随时切换 |

### 两处值得一提的设计

**质检智能体与回炉机制** —— 多数系统的「多智能体」停留在并行调用。本系统引入独立质检角色，
且赋予其打回重做的权力：不合格产出携带质检意见回炉，由原智能体针对性修正后重新提交。
防幻觉由此从提示词层面的软约束，升级为架构层面的硬保障。

**贯穿全场景的数据飞轮** —— 课后练习、专项刷题、代码闯关、错题复习，
所有产生学习结果的场景都回写同一份画像，画像又反向驱动全部资源生成。

---

## 系统架构

```
展现层    Vue 3 + Vite 单页应用（22 条路由）
           ↓
接口层    Spring Boot REST（14 个控制器）· 内容安全前置拦截 · SSE 流式推送
           ↓
智能体层  AgentOrchestrator 编排器
           ├─ 规划智能体      （DeepSeek）
           ├─ 思维导图智能体   （讯飞星火 Spark-X2-Flash）
           ├─ 讲解 / 题库 / 阅读 / 代码智能体（DeepSeek）
           └─ 质检智能体      （DeepSeek）· 不合格回炉
           ↓
能力层    大模型客户端 · RAG 知识库 · 讯飞语音（TTS/IAT）· 判题沙箱
           ↓
数据层    MySQL + MyBatis-Plus · 内存向量库
```

按任务特性分派不同模型本身也是多智能体架构的体现：思维导图要求严格的层次化结构输出与响应速度，
由讯飞星火承担；长文本生成与代码理解由 DeepSeek 承担。

---

## 快速开始

### 环境要求

| 组件 | 版本 | 备注 |
|---|---|---|
| JDK | 17+ | |
| Node.js | 20+（推荐 22） | 前端构建；判题沙箱依赖其权限模型 |
| MySQL | 8.0+ | 字符集 utf8mb4 |
| 浏览器 | Chrome / Edge 最新版 | 语音输入与视频导出依赖较新 Web API |

### 1. 建库

表结构由应用启动时自动创建，**无需手工执行 SQL**。

```sql
CREATE DATABASE learning_agent CHARACTER SET utf8mb4;
```

### 2. 配置密钥

密钥通过**环境变量**注入，不写入代码仓库。完整清单与申请渠道见
[`softcup_houduan/src/main/resources/application-example.yml`](softcup_houduan/src/main/resources/application-example.yml)。

```bash
DB_PASSWORD              # MySQL 密码
DEEPSEEK_API_KEY         # DeepSeek 模型密钥
XF_SPARK_API_PASSWORD    # 讯飞星火 APIPassword
XF_APP_ID                # 讯飞 AppID       ┐
XF_API_KEY               # 讯飞 APIKey      ├ 语音合成与语音听写共用同一组
XF_API_SECRET            # 讯飞 APISecret   ┘
```

> 在 IntelliJ IDEA 的 Run Configurations → Environment variables 中配置时，
> **变量之间必须用英文分号分隔**。漏写分号会让多个变量粘成一个，
> 表现为「密钥明明填了却仍报鉴权失败」。

不配置密钥系统仍可启动，界面完全可浏览，仅大模型与语音功能不可用。

### 3. 启动

```bash
# 后端（务必在项目根目录执行，否则知识库语料路径解析不到）
cd softcup_houduan && ./mvnw spring-boot:run

# 前端
cd softcup_qianduan && npm install && npm run dev
```

启动成功的标志：

```
✅ 库表结构已就绪（schema.sql）
✅ 知识库已就绪：灌入 58 份语料
🛡️ 内容安全词库已加载
```

### 4. 打包发布

```bash
python build-release.py <团队编号>
```

一条命令完成：前端构建 → 产物嵌入后端 → 打可执行 jar → 组装提交包，
并自动扫描包内是否残留密钥（检出即中止）。

---

## 第三方组件与开源协议

本项目使用了以下开源软件与第三方服务，使用方式均符合相应协议要求。

### 开源软件

| 名称 | 版本 | 用途 | 来源 | 协议 |
|---|---|---|---|---|
| Vue.js | 3.5 | 前端框架 | vuejs.org | MIT |
| Vite | 8.x | 前端构建 | vite.dev | MIT |
| Vue Router | 4.6 | 前端路由 | router.vuejs.org | MIT |
| Pinia | 3.0 | 状态管理 | pinia.vuejs.org | MIT |
| Spring Boot | 3.5 | 后端框架 | spring.io | Apache-2.0 |
| MyBatis-Plus | 3.x | ORM | baomidou.com | Apache-2.0 |
| LangChain4j | 1.x | 大模型编排与 RAG | github.com/langchain4j | Apache-2.0 |
| Apache PDFBox | 3.x | PDF 语料解析 | pdfbox.apache.org | Apache-2.0 |
| ONNX Runtime | 1.20 | 向量模型本地推理 | onnxruntime.ai | MIT |
| BGE-small-zh-v1.5 | 1.5 | 中文向量化模型 | huggingface.co/BAAI | MIT |
| MySQL | 8.0+ | 数据库 | mysql.com | GPL-2.0 / 商业双许可 |
| markmap | 0.18 | 思维导图渲染 | markmap.js.org | MIT |
| markdown-it | 14.x | Markdown 渲染 | github.com/markdown-it | MIT |
| highlight.js | 11.x | 代码高亮 | highlightjs.org | BSD-3-Clause |
| Mermaid | 11.x | 图表渲染 | mermaid.js.org | MIT |
| Monaco Editor | 0.55 | 在线代码编辑器 | microsoft.github.io/monaco-editor | MIT |
| Node.js | 22.x | 判题沙箱运行时 | nodejs.org | MIT |

### AI 大模型与云服务

| 服务 | 提供方 | 用途 | 接入方式 |
|---|---|---|---|
| 讯飞星火 Spark-X2-Flash | 科大讯飞 | 思维导图智能体推理 | OpenAI 兼容 HTTP 接口，官方授权 |
| 讯飞在线语音合成（TTS） | 科大讯飞 | 讲解朗读、AI 老师配音 | WebSocket 流式接口，官方授权 |
| 讯飞语音听写（IAT） | 科大讯飞 | 画像构建的语音输入 | WebSocket 流式接口，官方授权 |
| DeepSeek | DeepSeek | 讲解 / 题库 / 阅读 / 代码 / 规划 / 质检智能体 | 官方 API |

---

## AI 辅助开发工具说明

依据赛事提交要求，声明本项目开发过程中使用的 AI Coding 工具：

| 工具 | 用途 |
|---|---|
| **Claude Code**（Anthropic） | 架构方案讨论、模块代码生成与重构、缺陷排查、测试脚本编写、文档撰写辅助 |
| **讯飞星火** | 既是系统运行时组件，亦用于开发期的提示词调优验证 |

**团队的工作方式与责任边界：**

- 所有 AI 生成代码均经过编译、实机运行与端到端测试后方可合入，不接受「看起来正确」的产出
- 架构分层、数据模型、安全策略等关键决策由团队成员自主判断，AI 仅提供方案对比
- AI 提出的风险与缺陷需经团队复现确认后处理。开发过程中据此发现并修复了两处重要问题：
  判题沙箱缺失导致的服务器配置泄露风险，以及判题结果封装的空值缺陷（会使正确实现被误判失败）
- 团队对交付代码的正确性与安全性负责，测试记录见系统开发说明书第 8 章

---

## 课程知识库与版权说明

`data/knowledge/` 下的 58 篇课程讲义为**团队自行编纂**：

- 以《数据结构》课程大纲的知识体系为组织框架（8 章 58 个知识点）
- 每个知识点按「是什么 / 关键点 / 复杂度 / 易错点」四段结构逐点改写
- 全部文字为团队自有表达，**不包含任何受版权保护教材的原文**

系统同时支持接入使用者自备的教材文档（PDF / TXT / Markdown）以增强检索效果，
该能力通过 `KB_PATH` 配置项开放，**受版权保护的资料不随源码分发**。

若未配置任何语料，系统仍可正常运行 —— 智能体会自动切换提示词策略，
退回纯模型生成模式，仅失去教材引用溯源。

---

## 项目结构

```
softcup/
├── softcup_houduan/                 后端（Spring Boot 3.5 + Java 17）
│   └── src/main/
│       ├── java/softcup_houduan/
│       │   ├── controller/          14 个 REST 控制器
│       │   ├── service/
│       │   │   ├── agent/impl/      7 个智能体实现
│       │   │   ├── safety/          内容安全过滤
│       │   │   ├── game/            判题沙箱与闯关进度
│       │   │   └── ...              画像 / 路径 / 答疑 / 报告 / 错题本
│       │   ├── ingest/              知识库灌入
│       │   └── model/               知识树等领域模型
│       └── resources/
│           ├── application.yml       配置（密钥走环境变量）
│           ├── application-example.yml  环境变量说明
│           ├── schema.sql            建表脚本（启动时自动执行）
│           ├── sensitive-words.txt   内容安全词库
│           └── game-testcases/       19 关判题用例
├── softcup_qianduan/                前端（Vue 3 + Vite）
│   └── src/
│       ├── views/                   页面（工作台 / 编排台 / 实验室 / 报告 …）
│       ├── components/              组件（导图 / PPT / 题目 / 错题本 …）
│       ├── games/                   19 个算法闯关游戏
│       └── data/                    算法可视化数据
├── data/knowledge/                  自建课程知识库（58 篇 + 说明）
├── release-assets/                  发布包内的启动脚本与说明
└── build-release.py                 一键打包脚本
```

---

## 文档

| 文档 | 位置 |
|---|---|
| 系统开发说明书（需求 / 设计 / 实现 / 测试 / 部署） | 随赛事**配套文档**单独提交 |
| 环境变量与配置说明 | `softcup_houduan/src/main/resources/application-example.yml` |
| 可执行包运行说明 | `release-assets/启动说明.md` |
| 知识库说明 | `data/knowledge/README.md` |

---

<div align="center">

**Ouroboros · 衔尾蛇**
画像驱动生成，行为反哺画像 —— 让每个学生都有自己的讲法

</div>