StudyCoach Agent

StudyCoach 是一个面向初中数学错题辅导的 AI 学习反馈 Agent。它不只回答题目，还会完成知识点识别、知识检索、错因诊断、分层提示、变式练习、学生画像更新和遗忘曲线复习。

核心能力

• ReAct-Reflection 单 Agent：Planner、Act、Reflect、Final Feedback 职责分离。
• 7 个学习工具：分类、检索、诊断、提示、练习、画像、复习计划。
• 多格式 RAG：Markdown、PDF、CSV 等资料统一解析和 Chunk 切分。
• 混合检索：Keyword + Dense 召回，支持 Milvus 和 qwen3-rerank。
• 工程化：FastAPI、SQLite、SSE、Agent Trace 和用户反馈日志。
• 自动评测：15 条 Tools case，覆盖 4 类数学场景，当前 15/15 通过。

系统流程

学生请求
-> Planner 选择下一步工具
-> Guard 检查流程完整性
-> Act 执行工具
-> Reflector 检查结果
-> 写入 Agent Trace
-> Final Feedback 生成学习反馈
-> SQLite 保存画像、错题、复习任务和用户反馈

快速开始

1. 安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -r deep_research/requirements.txt

2. 配置模型

cp deep_research/.env.example deep_research/.env

在 deep_research/.env 中填写 DASHSCOPE_API_KEY。默认使用本地 Hashing Embedding，不需要启动 Milvus。

3. 启动服务

uvicorn deep_research.api:app --host 127.0.0.1 --port 8000

打开：

• Demo：http://127.0.0.1:8000/demo
• RAG Debug：http://127.0.0.1:8000/rag-debug
• API 文档：http://127.0.0.1:8000/docs

启用完整 Milvus RAG

将 .env 中的 RAG 配置切换为 DashScope Embedding、Milvus 和 qwen3-rerank，然后执行：

docker compose -f docker-compose.milvus.yml up -d
python -m deep_research.rag_index --index-milvus --reset-milvus
uvicorn deep_research.api:app --host 127.0.0.1 --port 8000

知识库未发生变化时，不需要重复执行 --reset-milvus。

自动评测

快速验证工具、RAG 和 SQLite 链路：

python -m deep_research.evaluate --mode tools

运行单条完整 Agent 评测：

python -m deep_research.evaluate \
  --mode agent \
  --case-id linear_equation_wrong_answer \
  --max-steps 8

当前硬指标包括工具链完整性、知识点识别、RAG 命中、错因诊断、复习计划和工具级反剧透。Tools 模式 15/15 不代表最终生成质量已经完全解决；最终回答级反剧透仍在继续完善。

项目结构

deep_research/       Agent、工具、RAG、存储、API 和评测代码
web/                 Demo 与 RAG Debug 页面
knowledge_base/      可公开的示例知识库
eval_cases/          JSONL 自动评测用例
docker-compose.milvus.yml
ROADMAP.md
docs/项目开发笔记.md

公开仓库不包含本地 .env、SQLite 数据库、Milvus 数据目录、课程归档和可能受版权保护的 PDF。Markdown 与 CSV 示例资料可以直接用于本地检索。

当前边界

• 第一版主要覆盖一元一次方程、一元二次方程、分数运算和函数图像场景。
• 数学诊断器仍以规则实现为主，不是通用数学求解器。
• SQLite 和线程模型适合本地 Demo，生产环境需要进一步升级。
• Final Feedback 的输出级反剧透评测仍需补充。

更完整的设计过程见 项目开发笔记 和 升级路线图。