{"repo": "caw111/2026-softwarecup", "files": {"README.md": {"990ba46222dd92e4db78e1afaed20b702854650e": {"t": 1785768232.7437904, "n": 6074, "h": "2ca0a20ee539b803", "c": "# LearnMate AI 学习陪练\n\n面向 2026 软件杯赛题的“基于大模型的个性化资源生成与学习多智能体系统”。项目围绕学习画像、课程生成、资料问答、掌握度评估、路径重规划、学习日历和在线测评构建一套可运行的个性化学习闭环。\n\n系统支持两种运行方式：\n\n- 未配置大模型时，使用本地规则和题库完成演示。\n- 配置 OpenAI 兼容接口或讯飞星火大模型后，课程生成、画像访谈、诊断、补救、报告、问答和图谱治理会接入真实 LLM。\n\n## 核心功能\n\n- 对话式学习画像：通过自然语言访谈提取学习主题、背景、时间、偏好和薄弱点，并形成带置信度的六维画像。\n- 个性化课程生成：根据画像、目标、周期、学习资料和模型输出生成每日学习路径、任务、资料和练习。\n- 课程资料库 RAG：支持上传课程资料、语义检索、全文问答、引用校验和课程绑定。\n- 掌握度视图：基于真实概念、任务、测评和先修关系生成可交互图谱，支持布局保存和 LLM 治理增强。\n- 诊断与补救：生成课前诊断、评分、错因分析、补救路径和针对性微讲义。\n- 路径重规划：当诊断或测评暴露风险时，生成可审核、可应用、可回滚的学习路径修订。\n- 自适应测验与代码评测：支持题量、题型、难度配置，代码题可走 Docker/Podman 沙箱判题并自动降级到本地 runner。\n- 学习日历：基于真实学习事件统计热力图、徽章、连续天数和每日活动摘要。\n- 学习报告与陪练问答：汇总进度、掌握度、错题、笔记、考试和综合应用证据，生成复盘报告；导师问答支持资料引用。\n- 多智能体过程展示：展示诊断、规划、资源生成、评估、反馈和治理等协作节点。\n\n## 技术栈\n\n- 前端：原生 HTML、CSS、JavaScript，单页应用。\n- 后端：Node.js 原生 HTTP 服务，ES Modules。\n- 数据库：MySQL 8，版本化 SQL 迁移。\n- LLM：OpenAI Chat Completions 兼容接口，内置讯飞星火 provider 配置。\n- RAG：服务端解析课程资料，检索并构建引用白名单。\n- 判题：Docker/Podman 沙箱优先，本地多语言 runner 兜底。\n- 测试：`node --test`。\n\n## 目录结构\n\n```text\nbackend/\n  server.js                  后端 API 入口\n  src/\n    services/                业务服务层\n    repositories/            MySQL 访问层\n    db/                      连接池与事务\n    learning.js              课程、资料、报告生成核心逻辑\n    adaptive-learning.js     自适应学习与题库\n    learning-graph.js        掌握度图谱构建与治理\n    learning-activity.js     日历、热力图、徽章和连续天数统计\n    rag.js                   资料解析、检索和引用上下文\n    judge.js                 在线判题运行时\n  test/                      后端单元与集成测试\n\nfrontend/\n  index.html                 单页应用结构\n  app.js                     前端交互与 API 调用\n  styles.css                 页面样式\n  *.test.js                  前端结构与行为回归测试\n\ndatabase/\n  migrations/                MySQL 版本化迁移\n\nscripts/\n  dev.js                     同时启动前后端\n  migrate.js                 数据库迁移与状态检查\n```\n\n## 环境要求\n\n- Node.js 18 或更高版本。\n- MySQL 8，可选但推荐。未配置 MySQL 时可进行本地演示。\n- Docker、Podman 或远程 Docker Engine，可选，用于代码题沙箱评测。\n- OpenAI 兼容大模型接口或讯飞星火 APIPassword，可选，用于真实 LLM 能力。\n\n## 快速启动\n\n安装依赖：\n\n```bash\nnpm install\n```\n\n启动前后端：\n\n```bash\nnpm run dev\n```\n\nPowerShell 如果禁止执行 npm 脚本，可以使用：\n\n```bash\ncmd /c npm run dev\n```\n\n默认访问地址：\n\n- 前端：<http://127.0.0.1:5173>\n- 后端健康检查：<http://127.0.0.1:3000/api/health>\n- 大模型连通性测试：<http://127.0.0.1:3000/api/llm-test>\n- 存储状态：<http://127.0.0.1:3000/api/storage/status>\n- 判题状态：<http://127.0.0.1:3000/api/judge/status>\n\n## 推荐完整开发环境\n\n启动项目自带 MySQL：\n\n```bash\ndocker compose up -d mysql\n```\n\n复制环境变量模板：\n\n```bash\ncopy .env.example .env.local\n```\n\n写入本地数据库配置：\n\n```env\nMYSQL_HOST=127.0.0.1\nMYSQL_PORT=3306\nMYSQL_USER=softwarecup\nMYSQL_PASSWORD=softwarecup-dev\nMYSQL_DATABASE=softwarecup\nMYSQL_CONNECTION_LIMIT=6\n```\n\n执行迁移并启动：\n\n```bash\nnpm run db:migrate\nnpm run dev\n```\n\n后端启动时也会检查迁移状态并补齐尚未执行的迁移。匿名用户通过 HttpOnly Session Cookie 隔离数据；已有浏览器本地工作台会在数据库为空时自动导入一次。\n\n## 大模型配置\n\n在 `.env.local` 或 `.env` 中配置：\n\n```env\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_MODEL=gpt-4.1-mini\nOPENAI_API_KEY=sk-your-api-key\nOPENAI_TIMEOUT_MS=180000\nRAG_FULL_CONTEXT_MAX_CHARS=900000\n```\n\n赛题推荐优先使用讯飞相关能力时，可直接使用内置 provider：\n\n```env\nLLM_PROVIDER=iflytek\nIFLYTEK_API_PASSWORD=your-spark-api-password\nIFLYTEK_MODEL=4.0Ultra\nOPENAI_TIMEOUT_MS=180000\nRAG_FULL_CONTEXT_MAX_CHARS=900000\n```\n\n讯飞星火 provider 默认使用 OpenAI 兼容地址 `https://spark-api-open.xf-yun.com/v1`，请求路径为 `/chat/completions`。如果学校或团队账号分配了专用网关，也可以用通用变量覆盖：\n\n```env\nLLM_PROVIDER=iflytek\nLLM_API_KEY=your-api-password\nLLM_BASE_URL=https://spark-api-open.xf-yun.com/v1\nLLM_MODEL=4.0Ultra\nLLM_WIRE_API=chat\nLLM_TIMEOUT_MS=180000\n```\n\n也可以使用其他兼容 OpenAI Chat Completions 的第三方模型服务，只要把 `OPENAI_BASE_URL` 和 `OPENAI_MODEL`，或通用的 `LLM_BASE_URL`、`LLM_MODEL` 换成对应服务的配置即可。\n\n配置完成后重启服务，并在页面右上角点击“测试大模型”。连接成功后，画像访谈、课程生成、诊断补救、路径重规划、学习报告、资料问答和掌握度治理会优先使用真实 LLM；失败时会给出可见降级状态。\n\n## 数据库与迁移\n\n项目使用 MySQL 8 保存用户会话、学习方案、任务进度、测评题、答题记录、资料库、路径修订、掌握度图谱、学习活动等核心状态。结构稳定的数据使用关系表；LLM 生成的课程、题目、图谱等复杂载荷使用 JSON 快照保存。\n\n常用命令：\n\n```bash\nnpm run db:migrate\nnpm run db:status\n```\n\n迁移文件位于 `database/migrations/`。已经执行过的迁移文件不要修改；表结构变化应新增更高编号的 SQL 文件。`schema_migrations` 会记录迁移文件名和 SHA-256 校验值。\n\n## 在线判题\n\n代码题优先使用服务端沙箱运行。默认配置：\n\n```env\nCONTAINER_CLI=docker\nJUDGE_IMAGE=softwarecup-code-judge:latest\nJUDGE_TIMEOUT_MS=10000\nJUDGE_AUTO_BOOTSTRAP=true\n```\n\n如果使用远程 Docker Engine：\n\n```env\nJUDGE_DOCKER_HOST=tcp://judge-server:2375\n```\n\n如果使用 Podman：\n\n```env\nCONTAINER_CLI=podman\n```\n\n后端会自动检查容器运行时并构建判题镜像。沙箱不可用时会降级到服务端本地 runner，确保学生仍然能提交代码并得到评分。\n\n## 常用脚本\n\n| 命令 | 说明 |\n|---|---|\n| `npm run dev` | 同时启动后端和前端 |\n| `npm run backend` | 只启动后端 API |\n| `npm run frontend` | 只启动前端静态服务 |\n| `npm run db:migrate` | 执行 MySQL 迁移 |\n| `npm run db:status` | 查看迁移状态 |\n| `npm test` | 运行全部自动化测试 |\n\n## API 概览\n\n| 接口 | 说明 |\n|---|---|\n| `GET /api/health` | 后端、数据库、模型配置健康检查 |\n| `GET /api/llm-test` | 大模型连通性测试 |\n| `GET /api/workspace` | 当前用户工作区 |\n| `POST /api/plans` | 创建学习方案 |\n| `PUT /api/plans/:planId/tasks/:taskKey` | 更新每日任务进度 |\n| `PUT /api/plans/:planId/notes` | 保存学习笔记 |\n| `POST /api/quiz` | 生成测验 |\n| `POST /api/quiz-questions/:id/attempts` | 提交题目作答 |\n| `POST /api/tutor` | 学习陪练问答 |\n| `POST /api/sources` | 上传课程资料 |\n| `POST /api/sources/search` | 检索课程资料 |\n| `POST /api/sources/ask` | 基于资料全文问答 |\n| `GET /api/plans/:planId/knowledge-graph` | 获取掌握度图谱 |\n| `PATCH /api/plans/:planId/knowledge-graph` | 保存图谱布局 |\n| `POST /api/plans/:planId/knowledge-graph/refine` | 使用 LLM 治理图谱 |\n| `GET /api/activity/summary` | 学习日历、热力图、徽章和连续天数摘要 |\n| `POST /api/learning-report` | 生成学习报告 |\n| `GET /api/judge/status` | 判题运行时状态 |\n\n## 测试\n\n运行：\n\n```bash\nnpm test\n```\n\n当前测试覆盖：\n\n- 数据库迁移、校验和与迁移拆分。\n- MySQL 持久化、用户隔离、课程、任务、测评和资料库。\n- LLM 参数、流式响应、失败降级和诊断补救归一化。\n- 对话式画像、画像 LLM、课程资料 RAG 和引用校验。\n- 路径重规划、掌握度图谱、学习日历、热力图、徽章和连续天数。\n- 前端导航、笔记、课程资料库、画像入口和掌握度/学习日历结构。\n- 代码判题错误处理和浏览器安全字段过滤。\n\n## 故障排查\n\n- 页面提示“后端未连接”：确认 `npm run dev` 正在运行，且后端端口为 `3000`。\n- MySQL 连接失败：先执行 `docker compose up -d mysql`，再检查 `.env.local` 中的账号、密码和数据库名。\n- 迁移失败：不要修改已经执行过的迁移文件；新增迁移时使用新的编号。\n- 大模型不可用：检查 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`，或讯飞配置 `LLM_PROVIDER=iflytek`、`IFLYTEK_API_PASSWORD`、`IFLYTEK_MODEL`，并访问 `/api/llm-test`。\n- Windows 刷新时出现黑色控制台窗口：后端已对 PowerShell 兜底请求设置隐藏窗口；重启 `npm run dev` 后生效。\n- 判题不可用：访问 `/api/judge/status` 查看 Docker/Podman 状态；不可用时系统会自动降级到本地 runner。\n\n## 当前规模\n\n按主要源码统计，项目约 74 个源码文件、2.1 万行代码，主要由 Node.js 后端、原生前端、SQL 迁移和少量 Python 工具组成。\n"}}}}