# software_cup **Repository Path**: wjstya/software_cup ## Basic Information - **Project Name**: software_cup - **Description**: A3-基于大模型的个性化资源生成与学习多智能体系统开发 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-18 - **Last Updated**: 2026-06-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 基于大模型的个性化资源生成与学习多智能体系统 > 第十五届中国软件杯大赛 A 组赛题 | 出题企业：科大讯飞股份有限公司 ## 项目简介 本系统是一个面向高等教育的**个性化学习智能体平台**，通过多智能体协作（LangGraph）实现智能化、精准化的学习引导。系统以对话式交互驱动学生画像构建，自动生成 6 类个性化学习资源（文档/思维导图/练习题/阅读材料/代码示例/视频脚本），并规划科学的个性化学习路径。 核心创新点： - **CIDPP 五维评估**：从清晰度、完整性、深度、实用性、针对性五个维度科学评估学习效果 - **对抗协作闭环**：Evaluator Agent 与 Optimizer Agent 形成评估-优化迭代，持续改进学习内容 - **Skill-Tree 知识建模**：树形知识点结构表达先修关系和掌握度，驱动学习路径拓扑排序 - **VARK 学习风格适配**：视觉/听觉/读写/动手四种学习风格深度整合到各 Agent 输出 ## 系统架构 ``` +-------------------+ SSE +-------------------+ | Vue3 Frontend | <--------------> | FastAPI Backend | | (localhost:5173) | /api/v1/* | (localhost:8080) | +-------------------+ +-------------------+ | +---------+---------+ | | +-----+-----+ +------+------+ | LangGraph | | MySQL 8 | | Multi-Agent| | (SQLAlchemy)| +-----+-----+ +-------------+ | +-------+-------+-------+-------+ | | | | | +-----+--+ +--+-----+ +--+---+ +------+--+ +--------+ | Profile | |Resource| | Path | | Tutor | |Evaluate| | Agent | | Agent | | Agent| | Agent | | Agent | +---------+ +--------+ +------+ +--------+ +----+---+ | +-------+-------+ | Optimizer | | Agent(对抗协作)| +-------+-------+ | +-------+-------+ | Skill-Tree | | Service | +---------------+ | +--------+--------+ | 讯飞星火 API | | (Spark LLM) | | FAISS + ONNX (RAG) | +-----------------+ ``` ### LangGraph 节点链路 ``` safety → rag → router → feedback_enrich → [profile→resource→path | tutor | evaluate→optimizer→feedback] ``` ### 多智能体协作闭环 ``` EvaluateAgent (CIDPP五维评估) ↓ 评估反馈 + 优化建议 OptimizerAgent (针对性优化) ↓ 驱动资源/路径/辅导再生成 ResourceAgent / PathAgent / TutorAgent ↓ 生成改进内容 EvaluateAgent (再次评估) ← 闭环迭代（最多2轮） ``` ## 技术栈 | 层级 | 技术 | 版本 | |------|------|------| | 前端 | Vue 3 + TypeScript | 3.5 | | UI 框架 | Element Plus + Tailwind CSS v4 | 2.14 | | 状态管理 | Pinia | 3.x | | 后端 | Python + FastAPI | 3.11+ / 0.115 | | 智能体 | LangGraph | 0.2+ | | ORM | SQLAlchemy | 2.0 | | 数据库 | MySQL 8 | 8.x | | 向量库 | FAISS + ONNX MiniLM-L6-v2 | 1.14+ | | LLM | 讯飞星火 Open API | generalv3.5 | | 包管理 | pnpm (前端) / uv (后端) | - | ## 核心功能 ### 功能一：对话式学习画像自主构建 - 自然语言对话自动抽取学习特征，无需繁琐表单 - 10 维度动态画像：知识基础、认知风格、易错点偏好、学习节奏、兴趣标签、薄弱点、学习目标、偏好资源类型、情感状态、时间偏好 - 置信度自评机制：每个维度附带 0-1 置信度，低置信度时主动追问 - 画像随学随新：评估结果、资源浏览、路径完成等行为自动触发增量更新 ### 功能二：多智能体协同的资源生成 7 个专业智能体分工协作： | 智能体 | 职责 | 核心能力 | |--------|------|---------| | CoordinatorAgent | 意图识别与路由 | LLM 意图分析 + 多策略回退 | | ProfileAgent | 学习画像提取 | 10 维度画像 + 置信度评估 | | ResourceAgent | 资源生成 | 6 类资源 + VARK 风格适配 | | PathAgent | 路径规划 | Skill-Tree 拓扑排序 + 先修优先 | | TutorAgent | 智能辅导 | 多模态解答(Mermaid/代码/步骤) | | EvaluateAgent | 效果评估 | CIDPP 五维评估 + 结构化测验 | | OptimizerAgent | 优化迭代 | 对抗协作闭环 + 针对性改进建议 | 支持 6 类个性化资源： 1. **专业课程讲解文档** (document) — Markdown 格式 2. **知识点思维导图** (mindmap) — Mermaid mindmap 语法 3. **练习题目** (exercise) — 选择题+简答题 4. **拓展阅读材料** (reading) — Markdown 格式 5. **代码实操案例** (code) — 带语法高亮的代码块 6. **视频脚本** (video) — 分镜描述+旁白脚本+关键帧 ### 功能三：个性化学习路径规划 - 基于 Skill-Tree 拓扑排序，先修知识点优先 - 薄弱点强化：掌握度低于阈值的知识点增加复习步骤 - VARK 风格适配：视觉型推荐思维导图+图表，听觉型推荐对话式讲解，读写型推荐文档+笔记，动手型推荐代码+实操 - 动态调整：评估结果驱动路径修改 ### 功能四：CIDPP 五维评估（核心创新） 借鉴 EduPlanner 论文的 CIDPP 评估框架： | 维度 | 英文 | 评估内容 | 示例评语 | |------|------|---------|---------| | 清晰度 | Clarity | 知识点理解是否清晰 | "对核心概念理解较清晰，但部分术语混淆" | | 完整性 | Integrity | 知识体系覆盖是否全面 | "基础知识覆盖较全，但进阶内容有盲区" | | 深度 | Depth | 理解是否深入，能否举一反三 | "表面理解尚可，缺乏举一反三能力" | | 实用性 | Practicality | 能否应用到实际场景 | "理论掌握但实践应用能力不足" | | 针对性 | Pertinence | 学习是否针对目标和薄弱点 | "学习方向基本正确，时间分配不够优化" | ### 功能五：智能辅导 - 多模态解答：Mermaid 图表、代码高亮、步骤推导 - Socratic 教学法：循循善诱，不直接给答案 - VARK 风格适配：根据认知风格调整解答方式 - 知识薄弱点针对性强化 ### 功能六：对抗协作优化（EduPlanner 创新） - Evaluator 产出五维评分 → Optimizer 生成改进建议 → 内容再生成 - 闭环迭代最多 2 轮，防止无限循环 - 优化建议持久化到 optimization_iterations 表 ## 目录结构 ``` software_cup/ ├── backend/ # Python 后端 │ ├── app/ │ │ ├── agents/ # 多智能体系统 │ │ │ ├── base.py # BaseAgent 抽象基类 │ │ │ ├── coordinator.py # 协调者 Agent │ │ │ ├── graph.py # LangGraph 编排图 │ │ │ ├── state.py # LearningState TypedDict │ │ │ ├── profile_agent.py # 画像 Agent │ │ │ ├── resource_agent.py # 资源生成 Agent │ │ │ ├── path_agent.py # 路径规划 Agent │ │ │ ├── tutor_agent.py # 辅导答疑 Agent │ │ │ ├── evaluate_agent.py # CIDPP 评估 Agent │ │ │ └── optimizer_agent.py # 对抗优化 Agent │ │ ├── api/ # FastAPI 路由 │ │ │ ├── auth.py # JWT 认证 │ │ │ ├── chat.py # SSE 对话 │ │ │ ├── profile.py # 学习画像 │ │ │ ├── resource.py # 学习资源 │ │ │ ├── learning_path.py # 学习路径 │ │ │ ├── evaluation.py # 学习评估 │ │ │ ├── skill_tree.py # Skill-Tree API │ │ │ ├── knowledge.py # 知识库管理 │ │ │ ├── activity.py # 学习行为 │ │ │ └── oss.py # OSS 存储 │ │ ├── llm/ # LLM 调用层 │ │ │ ├── spark_client.py # 讯飞星火 WebSocket │ │ │ ├── mimo_client.py # MiMo 备用客户端 │ │ │ └── llm_factory.py # LLM 工厂 │ │ ├── models/ # SQLAlchemy ORM │ │ │ ├── student.py, course.py, profile.py │ │ │ ├── resource.py, learning_path.py, evaluation.py │ │ │ ├── conversation.py, knowledge_point.py │ │ │ ├── learning_activity.py │ │ │ └── skill_tree.py # Skill-Tree 模型 │ │ ├── schemas/ # Pydantic 模型 │ │ ├── services/ # 业务逻辑 │ │ │ ├── auth_service.py │ │ │ ├── chat_service.py │ │ │ ├── profile_service.py │ │ │ ├── resource_service.py │ │ │ ├── path_service.py │ │ │ ├── evaluation_service.py # CIDPP + 推荐策略 │ │ │ ├── confidence_service.py │ │ │ ├── knowledge_service.py │ │ │ └── skill_tree_service.py # Skill-Tree 业务 │ │ ├── rag/ # RAG 知识检索 │ │ │ ├── document_loader.py │ │ │ ├── retriever.py │ │ │ └── vector_store.py │ │ ├── utils/ # 工具函数 │ │ │ ├── content_filter.py # 双层内容安全 │ │ │ ├── json_parser.py │ │ │ ├── logger.py │ │ │ └── learning_styles.py # VARK 学习风格 │ │ ├── config.py │ │ ├── database.py │ │ ├── deps.py │ │ └── main.py │ ├── database/ │ │ ├── schema.sql # 完整建表脚本 │ │ ├── migrate_v2.sql # v2 迁移（画像字段扩展） │ │ └── migrate_v3.sql # v3 迁移（CIDPP+Skill-Tree） │ ├── knowledge_base/ # 知识库原始文档 │ ├── tests/ │ ├── pyproject.toml # uv 依赖管理 │ └── .env.example ├── frontend/ # Vue 3 前端 │ ├── src/ │ │ ├── api/ # HTTP 请求封装 │ │ ├── components/ # Vue 组件 │ │ │ ├── chat/ # 对话组件 │ │ │ │ ├── ChatWindow.vue │ │ │ │ ├── MessageBubble.vue │ │ │ │ ├── OnboardingGuide.vue │ │ │ │ └── ProgressStepper.vue │ │ │ ├── common/ # 通用组件 │ │ │ ├── evaluation/ # 评估组件（QuizPanel） │ │ │ ├── learning/ # 路径组件 │ │ │ ├── profile/ # 画像组件（ProfileRadar） │ │ │ └── resource/ # 资源组件（Mermaid/RecommendCard） │ │ ├── composables/ # Vue Composables │ │ ├── router/ # Vue Router │ │ ├── stores/ # Pinia 状态管理 │ │ ├── types/ # TypeScript 类型 │ │ ├── utils/ # 工具函数 │ │ └── views/ # 页面视图 │ │ ├── Home.vue, Login.vue, Chat.vue │ │ ├── Profile.vue, Resources.vue │ │ ├── LearningPath.vue, Evaluation.vue │ │ ├── Knowledge.vue, UserSettings.vue │ │ └── NotFound.vue │ ├── package.json │ ├── pnpm-lock.yaml │ ├── vite.config.ts │ └── tailwind.config.js ├── docker/ │ └── docker-compose.yml # Docker Compose 配置 ├── docs/ # 设计文档 │ ├── design/ # 设计文档 │ └── oss-cors-setup.md ├── 项目需求文档.md # 赛题需求文档 ├── CLAUDE.md # AI 开发指引 ├── API.md # API 文档 └── README.md # 本文档 ``` ## 快速开始 ### 前置条件 - Python 3.11+ - Node.js 18+ - pnpm 8+ - MySQL 8.0 - 讯飞星火 API 密钥（[申请地址](https://www.xfyun.cn/)） ### 后端启动 ```bash # 1. 安装依赖 cd backend uv sync # 2. 配置环境变量 cp .env.example .env # 编辑 .env，填入讯飞星火 API 密钥等信息 # 3. 创建数据库并初始化 mysql -u root -proot < database/schema.sql mysql -u root -proot < database/migrate_v2.sql # 画像字段扩展 mysql -u root -proot < database/migrate_v3.sql # CIDPP + Skill-Tree # 4. 启动服务 uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8080 ``` ### 前端启动 ```bash cd frontend pnpm install pnpm dev # 开发服务器 http://localhost:5173 pnpm build # 生产构建 pnpm type-check # TypeScript 类型检查 ``` ### Docker 部署（可选） ```bash cd docker docker-compose up -d ``` ### 环境变量 | 变量 | 说明 | 默认值 | |------|------|--------| | `MYSQL_HOST` | MySQL 主机 | `localhost` | | `MYSQL_PORT` | MySQL 端口 | `3306` | | `MYSQL_USER` | MySQL 用户 | `root` | | `MYSQL_PASSWORD` | MySQL 密码 | `123456` | | `MYSQL_DATABASE` | MySQL 数据库 | `learning_db` | | `SPARK_APP_ID` | 讯飞星火应用 ID | *(必填)* | | `SPARK_API_KEY` | 讯飞星火 API Key | *(必填)* | | `SPARK_API_SECRET` | 讯飞星火 API Secret | *(必填)* | | `SPARK_API_URL` | 讯飞 API 地址 | `wss://spark-api.xf-yun.com/v3.5/chat` | | `SECRET_KEY` | JWT 签名密钥 | `smart-learning-secret-key-change-in-production` | | `APP_PORT` | 后端服务端口 | `8080` | ## API 概览 | 模块 | 路由前缀 | 说明 | |------|---------|------| | 认证 | `/api/auth` | 注册、登录、JWT | | 对话 | `/api/chat` | SSE 流式对话、历史记录 | | 学习画像 | `/api/profile` | 画像 CRUD、置信度管理 | | 学习资源 | `/api/resources` | 资源列表、AI 生成 | | 学习路径 | `/api/learning-paths` | 路径生成、步骤管理 | | 学习评估 | `/api/evaluations` | CIDPP 评估、在线答题、趋势 | | 知识能力树 | `/api/skill-tree` | Skill-Tree 查询、薄弱点、学习顺序 | | 知识库 | `/api/knowledge` | 知识库导入、查询 | | 学习行为 | `/api/activities` | 行为记录、统计 | | OSS | `/api/oss` | 文件上传、CORS | 详细 API 文档参见 [API.md](./API.md) 或启动后访问 `http://localhost:8080/docs`。 ## 核心创新点 ### 1. CIDPP 五维评估（借鉴 EduPlanner） 传统评估只给出一个总分，我们的 EvaluateAgent 从五个维度全面评估： ``` Clarity (清晰度) → 知识点理解是否清晰、表述是否准确 Integrity (完整性) → 知识体系是否完整、覆盖是否全面 Depth (深度) → 理解是否深入、能否举一反三 Practicality (实用性) → 能否应用到实际场景 Pertinence (针对性) → 学习是否针对目标和薄弱点 ``` 每个维度提供：评分(0-100) + 评语 + 改进建议，驱动后续 Optimizer 优化迭代。 > 参考论文：Zhang et al., "EduPlanner: LLM-Based Multi-Agent Systems for Customized and Intelligent Instructional Design", IEEE TLT 2025 ### 2. 对抗协作优化闭环 ``` EvaluateAgent ─→ CIDPP五维评分 + 知识缺口识别 │ ↓ 评估反馈 + 改进建议 OptimizerAgent ─→ 生成针对性优化计划 │ ↓ 优化建议驱动内容调整 ResourceAgent / PathAgent / TutorAgent ─→ 重新生成改进内容 │ ↓ (可选：再次评估) EvaluateAgent ─→ 二次评估确认改进效果 ``` > 参考论文：EduPlanner 的 Evaluator↔Optimizer 对抗协作机制 ### 3. Skill-Tree 知识建模 ``` AI概述 (mastery=0.5) ├── ML基础 (mastery=0.4) ← 薄弱点! │ ├── 监督学习 (mastery=0.3) │ ├── 无监督学习 (mastery=0.3) │ └── 模型评估 (mastery=0.3) ├── 深度学习 (mastery=0.2) ← 先修: ML基础 │ ├── CNN (mastery=0.1) │ ├── RNN/LSTM (mastery=0.1) │ └── Transformer (mastery=0.1) └── ... ``` - 树形结构表达知识点先修关系 - 每个节点有 mastery(0-1) 掌握度和 importance 权重 - 评估结果动态更新掌握度 - PathAgent 基于拓扑排序规划路径（先修优先） ### 4. VARK 学习风格适配 | 风格 | 中文 | 资源偏好 | 辅导方式 | |------|------|---------|---------| | Visual | 视觉型 | 思维导图、图表、流程图 | Mermaid 图示、代码高亮 | | Auditory | 听觉型 | 视频、对话式讲解 | 类比、记忆口诀、问答式引导 | | Reading | 读写型 | 文档、笔记、拓展阅读 | 结构化文本、定义精读 | | Kinesthetic | 动手型 | 代码实操、练习、案例 | 案例分析、调试技巧、实操引导 | ## 测试 ```bash # 后端测试 cd backend uv run pytest # 前端类型检查 cd frontend pnpm type-check ``` ## 编码规范 - **后端**: Python 3.11+, 类型注解, docstring 中文注释, async/await - **前端**: Vue3 Composition API + `