Shield FZE — AI-Powered 408 Postgraduate Exam Preparation System

One-stop AI preparation platform for China's 408 Computer Science Postgraduate Entrance Exam
Gitee · 架构文档 · PRD · CCF 参赛书

Overview

Shield FZE is a full-stack, AI-native learning platform designed for the 408 National Unified Computer Science Postgraduate Entrance Exam in China. It integrates 6 LangGraph agents, RAG knowledge retrieval, knowledge graph visualization, spaced repetition flashcards, full mock exams, and AI-powered essay grading into a single system.

Why Shield FZE?

Pain Point	Shield FZE Solution
No AI grading for essay questions	AI scoring-point grading engine with detailed feedback
No integrated flashcard system	Built-in SM-2 spaced repetition + auto-generate from mistakes
Knowledge points scattered	164-node knowledge graph with hierarchical visualization
Can’t practice real exam conditions	Full mock exam with countdown timer, answer sheet, anti-cheat detection
No personalized learning plan	Multi-agent AI provides diagnosis, tutoring, and planning
School selection is manual	Smart recommendation engine based on mock exam scores

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Frontend (Vue 3 + Vite)                  │
│  Dashboard │ Real Exams │ Quiz │ Flashcards │ Mock Exam │ Uni │
├─────────────────────────────────────────────────────────────┤
│                     Backend (FastAPI)                        │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐  │
│  │ Auth     │ Quiz     │ Chat     │ Study    │ KG       │  │
│  ├──────────┼──────────┼──────────┼──────────┼──────────┤  │
│  │ Flashcard│ Exam     │ University│ Grading │ Export   │  │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘  │
├─────────────────────────────────────────────────────────────┤
│               AI Engine (LangGraph + 百炼 API)               │
│  ┌──────┬──────┬──────────┬──────┬────────┬──────┐        │
│  │Tutor │Quiz  │Diagnosis │Code  │Mentor  │Chat  │        │
│  └──────┴──────┴──────────┴──────┴────────┴──────┘        │
├─────────────────────────────────────────────────────────────┤
│              Data Layer                                      │
│  SQLite │ ChromaDB (Vector) │ Neo4j (Graph) │ Session Memory │
└─────────────────────────────────────────────────────────────┘

Key Features

1. Multi-Agent AI Chat (Core Innovation)

6 Agents: Tutor, Quiz, Diagnosis, Code, Mentor, Chat
LangGraph State Machine: Intent classification → agent routing → formatted response
SSE Streaming: Real-time typing effect with fallback
RAG Integration: Semantic search over uploaded PDF/textbooks via ChromaDB + text-embedding-v3

2. Real Exam Question Bank (80+ Questions)

2009-2025 authentic 408 exam style questions
4 subjects: Data Structures, Computer Organization, OS, Computer Networks
Difficulty 1-5, with tags (high-frequency, error-prone, key)
Subjective questions with AI grading

3. AI Essay Grading

Scoring-point decomposition and per-point evaluation
Partial credit for partially correct answers
Detailed feedback and improvement suggestions
Supports algorithm design, short answer, and calculation questions

4. Three-Level Wrong Question System

Level 1 (first error) → Level 2 (second error) → Level 3 (hard error)
Ebbinghaus forgetting curve scheduling (1/3/7/15/30 day intervals)
Wrong question regrouping into new quizzes
Export to Markdown/HTML for printing

5. Flashcard Memorization

SM-2 spaced repetition algorithm
5 preset deck types (terminology, Q&A, formulas, protocols, algorithms)
Auto-generate cards from wrong questions via LLM
Card flip animation with 6-level quality rating

6. Full Mock Exam

180-minute countdown timer with real exam UI
Answer sheet with question marking
Tab-switch detection for focus tracking
Auto-save every 30 seconds
Instant scoring report

7. University Recommendation

15 universities with historical score lines
Smart recommendation: “冲刺” (reach) / “稳” (target) / “保” (safe)
Filter by tier, province, score

8. Knowledge Graph

164 nodes across 4 subjects, 3-level hierarchy
Interactive visualization with search and relation highlighting
AI explanation and related exam question lookup per node

Tech Stack

Layer	Technology
Frontend	Vue 3, Vite, Element Plus, ECharts, Pinia
Backend	FastAPI (Python 3.9+), LangGraph, SQLAlchemy Async
AI/LLM	百炼 API (deepseek-v3), text-embedding-v3, Ollama (optional)
Database	SQLite (dev), ChromaDB (vector), Neo4j (graph, optional)
Auth	JWT with bcrypt password hashing
Deployment	Docker Compose (planned)

Quick Start

Docker (Recommended) 🐳

git clone https://gitee.com/yu-man-tian-xia/shield-fze.git
cd shield-fze
echo "DASHSCOPE_API_KEY=your_key" > .env
docker compose up -d
# Visit http://localhost

Manual Setup

Prerequisites

Python 3.9+
Node.js 18+
Git

Backend Setup

cd edu-408-backend
pip install -r requirements.txt

# Configure API key
cp .env.example .env
# Edit .env: set DASHSCOPE_API_KEY=your_key

# Start server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

cd edu-408-frontend
npm install
npm run dev

Visit http://localhost:5173 and register an account.

Seeding Data

On first startup, the system automatically:

Creates all database tables
Imports 80 real exam questions
Initializes the knowledge graph with 164 nodes

University data can be seeded by calling POST /api/uni/seed (admin only).

Project Structure

edu-408-backend/
├── app/
│   ├── agents/          # LangGraph 6-agent system
│   │   ├── orchestrator_agent.py  # Central router + SSE streaming
│   │   ├── tutor_agent.py        # Knowledge tutoring with RAG
│   │   ├── quiz_agent.py         # Quiz generation
│   │   ├── diagnosis_agent.py    # Learning diagnosis
│   │   ├── code_agent.py         # C code debugging
│   │   └── mentor_agent.py       # Study planning & mentoring
│   ├── models/          # SQLAlchemy models (9 tables + V2.0 additions)
│   ├── routers/         # FastAPI route handlers (11 routers)
│   ├── services/        # Business logic (11 services)
│   ├── schemas/         # Pydantic validation schemas
│   └── utils/           # LLM client, config
├── data/                # Seed data, knowledge graph cache
├── scripts/             # Utility scripts
└── tests/               # Unit tests (106 passing)

edu-408-frontend/
├── src/
│   ├── views/           # 14 page components
│   │   ├── quiz/        # QuizPage, RealExamPage
│   │   ├── flashcard/   # FlashcardPage
│   │   ├── exam/        # MockExamPage
│   │   ├── university/  # UniversityPage
│   │   └── ...
│   ├── layouts/         # MainLayout, Sidebar, HeaderBar
│   ├── router/          # Vue Router config (16 routes)
│   └── stores/          # Pinia state management
└── public/

API Documentation

After starting the backend, visit:

Swagger UI: http://localhost:8000/docs
Health Check: GET /api/health

V2.0 Endpoints

Prefix	Description
`/api/quiz/real-exams`	Real exam question bank (search, filter, import)
`/api/quiz/grade`	AI subjective answer grading
`/api/study/wrong-book/due-today`	Due review items (Ebbinghaus)
`/api/study/wrong-book/regroup`	Regroup wrong questions into quiz
`/api/study/wrong-book/export`	Export wrong book (Markdown/HTML)
`/api/flashcards/*`	Flashcard deck CRUD + SM-2 review
`/api/exam/*`	Mock exam lifecycle (start → save → submit → report)
`/api/uni/*`	University search, detail, recommendations

Testing

# Backend tests
cd edu-408-backend
pytest tests/ -v   # 106 tests

# Frontend tests
cd edu-408-frontend
npm run test

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Ways to Contribute

Add more real exam questions to data/real_exam_seed.json
Improve AI agent prompts in app/agents/
Add new flashcard deck types
Expand university database
Fix bugs and improve documentation

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Team

Xiao Yu (@yu-man-tian-xia) — Project Lead, Full-stack Development
Claude (Anthropic) — AI Co-development

Acknowledgments

百炼 (DashScope) API for LLM capabilities
LangGraph for agent orchestration framework
Element Plus for Vue 3 component library
The 408 exam community for inspiration and feedback

Shield FZE — AI护航每一分