辩证智学 · Dialectical Learning Agent

把唯物辩证法装进 Multi-Agent 的 AI 学习平台 — 从「题」到「本质」，逐层逼近。 FastAPI + WebSocket 后端 × 单页前端。5 个 Agent 协同，驱动「五层逻辑链」学习引擎。

---

一句话定位

一个以 唯物辩证法（矛盾论 / 量变质变 / 否定之否定 / 对立统一 / 实践论） 为教育理念骨架的 多智能体（Multi-Agent）AI 学习平台。它不是直接给出答案的刷题工具，而是用一个「协调者」Agent 调度 题目分析 / 辩证导师 / 知识图谱 / 学情追踪 等多个专职 Agent，带学生自己发现题目背后的核心矛盾，逐步从「具体题目」上升到「知识体系」。

---

✨ 核心亮点

• 多 Agent 架构：5 个职责单一的专业 Agent 协同，由 协调者 依据意图路由（意图识别 → 编排调用链），每一层的分工都给用户可见。
• 哲学驱动教学法：不直接给答案。题目分析 Agent 拆「五层逻辑链」，辩证导师 Agent 用提问引导学生发现矛盾，学情追踪 Agent 记录「量变到质变」的临界点并触发升级。
• 轻量 RAG：知识图谱 Agent 内置 数学 / 物理 / 化学 3 科的关键词-知识点索引，作为本地检索的"冷启动知识库"，无需向量数据库即可运行。
• 实时交互：后端通过 WebSocket 推送「正在思考 · Agent 状态 · 最终结果」，前端实时点亮各 Agent 状态点。
• 竹青风界面：单文件 HTML，绿色系（竹青）配极客字体，主题化 CSS 变量，无需构建工具。

---

🏗️ 架构总览

┌────────────────────────── 前端 (frontend/index.html, 单页) ──────────────────────────┐
│  五层逻辑链  ·  学科选择  ·  辩证法卡片  ·  实时 Agent 状态点  ·  聊天面板 (WebSocket) │
└──────────────────────────────────────┬──────────────────────────────────────────────┘
                                       │  REST: /api/chat   WebSocket: /ws/{session}
┌──────────────────────────────────────▼──────────────────────────────────────────────┐
│                              FastAPI 后端 (backend/main.py, :8088)                    │
│  协调者 Coordinator ──(意图路由)──▶ 职责链编排                                          │
└──────────────────────────────────────┬──────────────────────────────────────────────┘
                                       │
        ┌──────────────┬──────────────┼──────────────┬──────────────┐
        ▼              ▼              ▼              ▼              ▼
  题目分析 Agent   辩证导师 Agent   知识图谱 Agent   学情追踪 Agent   (协调者)
  Analyzer         Tutor            Graph           Tracker
  「五层拆解」     「提问式引导」     「关键词RAG」    「量变质变诊断」
        └──────────────┴──────────────┴──────────────┴──────────────┘
                                       │
                              DeepSeek API (大模型推理)
                              (config.py 集中配置 · 密钥读 .env / 环境变量)

意图路由示例（协调者 _analyze_intent）：

触发词（示例）	意图	调用链
「这道题怎么做 / 求解」	analyze_question	Analyzer → Tutor → Tracker
「什么是导数 / 原理」	ask_concept	Graph → Tutor
「想学 / 教我 / 学习」	learn_subject	Graph → Tutor → Tracker
「进度 / 学情 / 做了多少」	check_progress	Tracker
其他	兜底	Tutor

---

🤖 五个 Agent

Agent	角色	职责
协调者 Coordinator	orchestrator	分析用户意图，路由到合适的 Agent，编排多 Agent 协作流程
题目分析 Analyzer	parser	把题目拆到「五层逻辑链」，识别核心矛盾、归类题型、定位底层知识点
辩证导师 Tutor	explainer	用唯物辩证法引导学生学习，不直接给答案，带学生自己发现矛盾
知识图谱 Graph	rag-retriever	内置关键词-知识点索引的轻量检索，管理知识点 / 真题 / 方法论
学情追踪 Tracker	analytics	记录学习进度、统计薄弱点、判断「量变到质变」临界并建议升级难度

每个 Agent 都继承自 Agent 基类，execute() 为统一入口，status/call_count 暴露给前端实时可视化。

---

🧭 教学法：五层逻辑链

系统把任何一道题拆解为 递进五层，每一层对应一个辩证法原理，顺流为"学"、逆流为"教"：

层	内容	辩证法原理
L01 题目	已知 vs 未知的具体矛盾	矛盾的特殊性
L02 题型	从同类题归纳共性	特殊到一般
L03 方法	通用的解题路径	矛盾的解决
L04 知识点	原理背后的本质联系	本质联系 / 对立统一
L05 体系	知识构成的有机整体	对立统一的整体

配套的引导式反馈：做错是「肯定」、纠正是否定、再次做对是否定之否定 —— 螺旋上升。

---

🚀 快速开始

需要 Python 3.10+。首次运行需一个 DeepSeek API Key（platform.deepseek.com 获取）。

# 1. 进入后端目录
cd backend

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置密钥（复制模板并填入你的 Key）
cd ..                     # 回到项目根
cp .env.example .env      # Windows: copy .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY=sk-xxxx

# 4. 启动后端（FastAPI + WebSocket，监听 :8088）
cd backend
python main.py

浏览器打开 http://localhost:8088/ 即可使用（后端会自动托管 frontend/index.html）。

未配置 API Key 时后端仍可运行，聊天会返回提示信息（用来演示前端与 Agent 编排，但不会产生真实 AI 回复）。知识图谱、学情追踪等无需 API 也可工作。

环境变量一览（见 backend/config.py）

变量	默认值	说明
DEEPSEEK_API_KEY	—	必填，API 密钥（读自环境变量或项目根 .env）
DEEPSEEK_MODEL	deepseek-v4-pro	模型名
DEEPSEEK_BASE_URL	https://api.deepseek.com/v1/chat/completions	API 端点
DEEPSEEK_MAX_TOKENS	3000	单次回复最大 token
DEEPSEEK_TEMPERATURE	0.8	采样温度
DEEPSEEK_TIMEOUT	60	请求超时（秒）
APP_PORT	8088	后端监听端口

---

🔌 API 一览

方法	路径	说明
GET	/	返回前端页面
GET	/api/agents	获取所有 Agent 状态与调用次数
GET	/api/subjects	获取知识图谱涵盖的学科
POST	/api/chat	通过协调者处理一条请求（{message, subject, mode, session_id}）
WS	/ws/{session_id}	实时对话：接收消息，推送「thinking → agent_status → response」

---

📁 目录结构

AI智学/
├── backend/
│   ├── config.py         # 集中配置（端口 / 模型 / 前端路径 / 密钥读取）
│   ├── main.py           # FastAPI 入口（REST + WebSocket）
│   ├── agents.py         # 5 个 Agent 的定义与编排逻辑
│   └── requirements.txt  # Python 依赖
├── frontend/
│   └── index.html        # 单页前端（竹青风 UI + 实时聊天）
├── .env.example          # 密钥模板（复制为 .env 使用）
├── .gitignore            # 忽略 __pycache__ / .env / 运行时数据
└── README.md

---

🗂️ 知识图谱内容

内置 3 科的「知识点 → 辩证法原理 → 关键词」索引，作为检索冷启动：

• 数学：函数、导数、三角函数、数列、立体几何、解析几何、概率统计、不等式
• 物理：力学、电学、磁学、光学、热学
• 化学：化学反应、化学平衡、有机化学、电化学

前端还展示了语文 / 英语 / 生物 / 历史 / 地理 / 政治的占位科目卡片，但其图谱索引可按需在 agents.py 的 _load_subjects() 中扩展。

---

📝 说明

• DeepSeek API Key 只读取，绝不写入 / 提交仓库——密钥集中在 config.py 处理，任何时刻都从环境变量或项目根 .env 读取（.env 已加入 .gitignore）。
• 本项目为原创教学实验项目，可自由 fork / 改造。