啃完一门课，带你过期末
面向中国本科生的课程级 AI 学习 Copilot
材料优先 · 来源引用 · 透明补充 · 诚实边界
FoxSay 不是通用问答工具，是以**「课程」为原子单位**的 AI 学习 Copilot。每门课完全隔离——材料、向量检索、骨架图、对话历史、复习计划都绑定 course_id。AI 优先基于你上传的课程材料回答，材料不足时透明补充通用知识并标注来源可信度，每条回答都带来源引用。
|
🎯
材料优先回答课程内问题 |
📚
每条回答带来源引用 |
🦊
不是冷冰冰的问答机器 |
|
📥
CSV/Excel 课程表导入，自动建立书架和考试倒计时；也支持手动创建课程作为兜底。 |
📄
MinerU V4 云端解析（公式/表格/图片 OCR），语义感知切块，支持 PDF/PPT/Word/图片/文本，Ctrl+V 直接粘贴截图。 |
|
🗺️
材料处理完成后自动生成章节、核心概念、难点和先修链路，一眼看清知识结构。 |
💬
CRAG 置信度门控 + 全语义检索；材料充足时精确引用，不足时透明补充并标注来源。 |
|
🧠
7 个静态工具 + 4 个动态 Skill：讲义生成、练习题、闪卡、概念图谱，随叫随到。 |
🕸️
ReactFlow + dagre 可视化章节知识网络，概念之间的先修关系一目了然。 |
|
📝
聊天回答一键保存为笔记，自动进入向量索引，后续问答可检索引用。 |
🔥
根据考试日期生成复习计划，状态化陪伴复习，讲一节、练一题、总结一下；支持 |
三栏 NotebookLM 风格布局：左边书架和课程列表，中间对话工作区，右边来源面板和 Studio 工具。材料消化完后，骨架图、知识图谱、笔记随时切换。
考试倒计时挂在顶部。狐狸根据剩余天数帮你拆复习计划，每天带你过几个概念，讲完就出题，做完再总结。临时想到什么问题，输入 /btw 随时插，不打断复习节奏。
# 1. 复制环境变量模板，填入 DeepSeek API Key + MinerU Token
cp examples/env.example .env
# 2. 一键启动（前端 + 后端 + Qdrant）
docker compose -f infra/docker-compose.yml up --build启动后访问：
| 服务 | 地址 |
|---|---|
| 前端 | http://localhost:3000 |
| 后端 API 文档 | http://localhost:8000/docs |
| Qdrant 面板 | http://localhost:6333/dashboard |
# 后端（FastAPI + uv）
cd backend && uv sync && uv run uvicorn app.main:app --reload
# 前端（Vite + React）
cd frontend && npm install && npm run devQdrant 向量数据库默认使用本地文件模式（无需 Docker）。如需远程模式，设置
QDRANT_URL=http://host:port。
|
⚛️
Frontend
Vite + React |
→ |
⚡
Backend
FastAPI + Python 3.12 |
→ |
🔍
Vector Store
Qdrant |
→ |
📄
Doc Parser
MinerU V4 |
- LLM：DeepSeek API（V4 Flash / V4 Pro）
- Embedding：BAAI/bge-m3（via SiliconFlow，1024 维）
- 文档解析：MinerU V4 云端（公式 OCR + 表格识别 + 图片提取）→ Docling（本地电子版 PDF）→ pdfplumber（兜底）
- 切块：LangChain MarkdownHeaderTextSplitter（语义感知，表格不可分割）
- 部署基线：Docker Compose（Qdrant 可选，默认本地文件模式）
[用户输入]
│
├── PDF ──────────→ MinerU V4（云端 OCR + 公式 + 表格）→ Docling → pdfplumber
├── DOCX/DOC ─────→ MinerU V4（原生支持）→ MarkItDown
├── PPTX/PPT ─────→ MinerU V4（原生支持）→ python-pptx
├── XLSX ──────────→ MarkItDown
├── TXT/MD ────────→ 直接读取
└── PNG/JPG ───────→ MinerU V4（OCR）
│
▼
[归一化引擎] → 页面锚定 · 表格保护 · 公式对齐 · 全局编号
│
▼
[语义切块] → LangChain MarkdownHeaderTextSplitter（标题层级 + 表格不可分割）
│
▼
[Embedding + Qdrant] → BGE-M3 1024 维 · heading_path 上下文
│
▼
[CRAG 检索] → 全层 embedding cosine 相似度 · 置信度门控
FoxSay 用 CRAG（Confidence-based RAG）做检索置信度门控：
|
🟢
score ≥ 0.72
材料充分 |
🟡
0.55 ≤ score < 0.72
材料部分相关 |
🔵
score < 0.55
材料未覆盖 |
材料不足时 AI 不会冷冰冰地拒答，而是基于通用知识给出有帮助的回答，同时明确声明「课程材料中未覆盖此内容，建议对照教材确认」。
fox-say/
├── frontend/ # Vite + React + TypeScript + Tailwind
│ └── src/
│ ├── features/ # bookshelf / course / onboarding
│ ├── components/ui/ # 基础 UI 组件
│ └── shared/ # API 客户端、类型、文案
├── backend/ # FastAPI + Python (uv + pyproject.toml)
│ └── app/
│ ├── api/ # 12 个 API 路由模块
│ ├── services/ # 21 个 service（agent/pipeline/retrieval/mineru/...）
│ ├── core/ # 配置、依赖
│ └── db/ # SQLite 存储
├── infra/ # Docker Compose（Qdrant + backend + frontend）
├── docs/ # 架构文档、CRAG 策略、管线重构计划
├── scripts/ # 工具脚本
└── assets/readme/ # README 用图
所有工程约束和架构文档以这些文件为准：
| 文件 | 内容 |
|---|---|
| AGENTS.md | 最高优先级工程与产品约束，任何 agent 操作前必读 |
| HANDOFF.md | 交接文档，记录当前状态、架构、已知问题 |
| docs/architecture.md | MVP 架构总览（API 端点、Agent、管线、测试策略） |
| docs/crag-policy.md | 检索置信度阈值与回答策略细节 |
| docs/product-boundaries.md | MVP 范围与优先级原则 |
| docs/pipeline-refactor-plan.md | 文档管线重构计划（已完成） |
🦊
"材料扔进来，剩下的交给狐狸。"