该项目旨在搭建了一个山村教育赋能平台。
一、项目名称：远山不远
对于山区学生来说，缺乏的不是梦想，而是缺乏实现梦想的路径。 对于山区教师来说，缺乏的不是资源， 缺的是把资源转化为教学行动的能力和信心。 所以我想做一款产品，在帮助教师日常工作提速的基础上，加入“微课克隆”板块，可以对比山村教师和网络名师课程，给出具体可操作的改进建议，并建立教师个人成长档案和教师论坛，记录与分享每一次的进步。
更重要的是，建立学生成长档案与个性化、阶段性的目标定制与梦想路径规划，同时自动化分析学生的成绩变化，知识点掌握情况和根据作文、日记等内容分析学生的心理状况与变化，帮助教师更好的对不同学生做差异化的帮助和心理的关怀与鼓励。远山不远，帮助学生离梦想不在遥远，拉近名师与乡村教师之间的距离，让他们都成为更好的自己！
**产品核心理念：**让每一位山村教师都被赋能，让每一个孩子的梦想不止被看见，更被实践。。
二、远山不远产品结构
“远山不远”是一个面向乡村教学场景的 AI 教育平台，采用 **FastAPI + SQLAlchemy + 本地/可选在线大模型** 的后端架构，并通过单页前端 `yuanshan.html` 实现教师端与学生端一体化交互。\
当前已落地的核心能力包括：
- 教师端：登录鉴权、智能备课、作业批改、知识库问答、家校沟通、微课克隆、教师成长档案、心理关怀、工作台动态看板。
- 学生端：梦想（职业）模拟器（支持自定义职业与多节点故事）、心理关怀联动、个人成长档案动态展示。
- 数据侧：学生/教师行为数据沉淀、成长指标聚合、勋章系统、待办事项 CRUD、定时任务刷新统计。
具体框架如下：
远山不远-网页/
├─ 登录页
├─ 模块一_全周期教学助手/
│ ├─ 功能1_智能备课（复式课堂）
│ ├─ 功能2_作业批改_成绩录入
│ ├─ 功能3_离线知识库_轻量AI问答
│ ├─ 功能4_家校沟通
│ └─ 功能5_班级管理
├─ 模块二_教师成长模块/
│ ├─ 功能1_微课克隆
│ ├─ 功能2_教师个人成长档案
│ └─ 功能3_学生心理健康和差异化关怀
├─ 模块三_学生成长模块/
│ ├─ 功能1_梦想模拟器
│ └─ 功能2_学生成长档案
三、产品功能与展示
登录页：角色选择——表单输入——登录触发
（一）模块一：全周期教学助手
1.智能备课——加入复试课堂智能备课
解决：一人教3个年级，如何备课？
传统备课工具都是单年级设计的。山区最普遍的是"复式教学"（同一教室同时有2-4个年级）。
创新设计：
-
输入"我有三年级12人+五年级8人，今天语文40分钟"
-
AI自动生成分组轮转教学方案：A组自学任务单 → B组教师直教 → A/B交换，时序精确到分钟
-
内置自学任务单生成器：AI生成配套学生自学卡，教师讲另一组时，另一组有事可做
-
一键打印，低配打印机友好格式
2.作业批改 /成绩录入——记入学生档案
解决：批改作业耗时长，成绩录入繁琐，学情难以追踪
创新设计：
-
拍照上传后，AI自动识别题目类型并判断对错，教师可快速"确认/修改"AI判断，一键归档
-
成绩录入时自动关联"对应考查知识点”，错题自动打标签（如：三年级·数学·进位加法·连续进位）
-
形成全班"知识点掌握热力图"，一眼看出班级薄弱点
-
作业数据自动流入学生成长档案，连续3次同一知识点出错 → 系统主动提醒教师进行个别辅导
3.离线知识库 + 轻量AI问答（支持语音输入）
解决：网络差/无网情况下，教师遇到不会的知识点怎么办？
创新设计：
-
预置K9全学科核心知识图谱，完全离线可用（类似离线地图）
-
教师用语音提问（方言适配）：“五年级分数除法这一块，我不太会讲，给我解释一下，用农村孩子能懂的例子”
-
AI用本地化类比回答（用田地、农作物、赶集等场景举例）
-
周期性低流量同步更新
4.家校沟通
解决：山区家长文化程度低，沟通困难，微信群无效
创新设计：
-
教师语音输入反馈 → AI转化为简明、温暖、无教育术语的家长通知
-
支持一键生成图文版（家长看不懂文字也能理解的图示）
-
添加家访记录手册：以日历形式标注教师的家访记录，教师自己输入家访日期、同学姓名、并以日记形式记录家访内容和注意事项。
-
同时提出家访对象建议，和家访内容建议
5.班级管理
解决：班级未形成系统化管理，全靠简单搜索和教师经验
创新设计：
-
支持Excel一键导入学生的基本情况，基本信息含：姓名、年级、监护人、联系方式、家庭类型（留守/单亲/困难）、民族、健康状况
-
建立每个学生的四维成长档案库，并有个性化、差异化的可视化分析。
-
学习维度：各科成绩趋势 / 知识点掌握图谱 / 作业完成率
-
行为维度：出勤记录 / 课堂参与评价（教师快速打星）
-
心理维度：（联动模块二）情绪状态标记 / 心理健康预警
-
家庭维度：家访记录 / 家长沟通历史
-
-
档案跨年级传递，升级时，档案自动迁移至下一位老师，新老师一键查看"这个班每个孩子的背景和进步史”
（二）模块二：教师成长模块
1.微课克隆——AI对比名师课堂给出具体可操作性意见
解决：好的网络名师课程，山区教师不知道怎么用到自己课堂
创新设计：
-
教师录制自己的10分钟课堂片段（用手机）
-
匹配网上公开同课段的名师课程资源，和教师录制视频进行对比分析
-
AI分析后给出具体、可操作的改进建议（不是"多互动"这种废话，而是"第3分钟你讲概念时没有停顿让学生思考，建议加一个’你们觉得呢？'的停顿"，教学结构（引入-讲解-练习-总结））
-
可对比名师同课段，但用"你的优势"而非"你的不足"作为视角呈现
-
加入跳转按钮，可以一键跳转所匹配到的名师课程进行学习
2.教师个人成长档案
解决：教师的努力不被看见，职称评定缺乏真实证明材料
-
每次使用APP，自动化积累内容，备课记录、微课报告、等数据自动归档。可积累、可分享，支持自动生成符合当地职称评定格式的"教师个人工作总结”
-
生成教师个人成长档案，生成“教学能力成长曲线”，并可以以看到能力雷达图的变化。
-
内置勋章系统（“连续30天备课达人”/“本月互助之星”/“学生进步推手”），勋章可生成精美图片，分享至朋友圈/同事群，可以在没有外部认可的环境中，为教师创造正反馈
3.学生心理健康和差异化关怀
解决：山区留守儿童心理问题隐蔽，教师难以早期发现和干预
创新点：
-
多微信号采集，根据学生的作文、日记或者成绩变化曲线等，分析了解学生的心理健康状况，并采用分级预警机制，对于心理问题尽早且温和的干预。
-
同时做好差异化的关怀与鼓励。（针对不同心理问题的学生，给出恰当的建议）。
-
加入关怀提示与关怀清单，提醒教师。
4.教师互助论坛（仅做展示，并未实现）
（三）模块三：学生成长模块
1.梦想模拟器——游戏中寻找实现路径
解决问题： 山区孩子视野窄，不知道有什么职业，不知道读书和未来的关系，更不知道实现梦想的具体路径
创新点：
-
职业世界探索——发掘孩子的兴趣与梦想
-
梦想模拟器——详细版附后
-
读书-梦想连接器——让孩子看到我现在学的和梦想什么关系
-
梦想成就任务系统——根据学生自身情况，规划真实成长路径，并突出日常学习与任务和梦想之间的关系
-
后续根据三大原则（低门槛、有趣、合理）加入以下功能：
- 低门槛 ：新增故事朗读、语音选项识别（说“选项一/二/三”）、大按钮模式（更大字体与触控区），识字少也能玩。
- 有趣 ：新增“成长经营条”（希望值/挑战值/能力标签），每次选择都会即时更新数值与能力点，并即时反馈。
- 合理 ：每一步选择都显示“现实提示 + 希望提示”，明确“路不轻松，但有人走过”，避免过度美化。
当完成探索时，会出现路径规划（如知识地图、本周可以做的事、可实现路径）：
2.学生成长档案
解决问题**：** 山区孩子缺乏持续的成长记录，好的进步转瞬即逝、无人看见
功能设计：
-
学生档案由四个维度构成：
-
学业成长（联动作业批改和录入成绩分析模块，生成成绩趋势图、知识点掌握雷达图、错题本等）
-
能力成长（由教师记录学生的兴趣爱好与相关能力参与的活动等）
-
情感与心理（除上述的心理健康记录的同时，增加“闪光时刻”正向成就积累）
-
阶段性任务规划（教师/AI协同为每个学生制定阶段目标，差异化，非统一模板）
-
以上及为该产品的具体功能与实现。所有功能后端均可正常运行：
四、具体代码与实现
1.具体代码已在GitHub中开源，链接：https://github.com/SxingheL/yuanshan_agent.git
2.文件目录结构
远山不远/
├─ yuanshan.html
├─ PROJECT_DOCUMENTATION.md
├─ backend/
│ ├─ main.py
│ ├─ requirements.txt
│ ├─ yuanshan_dev.db
│ └─ app/
│ ├─ main.py
│ ├─ config.py
│ ├─ auth.py
│ ├─ db/
│ ├─ routes/
│ └─ services/
3.文件级说明
3.1 根目录与入口
- `yuanshan.html`\
功能：教师端与学生端单页应用，负责登录、面板切换、API 调用、动态渲染。\
技术栈：`HTML/CSS/Vanilla JS`、`fetch`、JWT 本地存储。
- `backend/main.py`\
功能：后端启动入口（运行 `backend.app.main:app`）。\
技术栈：`uvicorn`。
- `backend/requirements.txt`\
功能：项目 Python 依赖清单。\
技术栈：`pip` 依赖管理。
- `backend/yuanshan_dev.db`\
功能：本地开发数据库（SQLite）。\
技术栈：`SQLite`。
- `.tmp_growth_smoke.py`\
功能：临时烟雾测试脚本（成长档案相关）。\
技术栈：`Python/TestClient`。
3.2 应用主干（`backend/app`）
- `backend/app/main.py`\
功能：创建 FastAPI 应用、挂载路由、启动时建表和种子数据、启动调度任务。\
技术栈：`FastAPI`, `SQLAlchemy`, `APScheduler`, `CORS`。
- `backend/app/config.py`\
功能：集中管理环境配置（JWT、数据库、LLM、Redis 等）。\
技术栈：`os.getenv` 配置模式。
- `backend/app/auth.py`\
功能：密码哈希、JWT 签发/校验、角色鉴权依赖。\
技术栈：`passlib[bcrypt]`, `python-jose`, `FastAPI Depends`。
- `backend/app/_init_.py`\
功能：包标记文件。\
技术栈：Python 包机制。
3.3 数据层（`backend/app/db`）
- `backend/app/db/database.py`\
功能：数据库引擎、会话工厂、`get_db` 依赖注入。\
技术栈：`SQLAlchemy Engine/Session`。
- `backend/app/db/models.py`\
功能：定义核心 ORM 模型（用户、学生、备课、作业、家访、微课、心理、成长档案、待办等）。\
技术栈：`SQLAlchemy ORM`, `JSON/DateTime` 字段建模。
- `backend/app/db/_init_.py`\
功能：包标记文件。\
技术栈：Python 包机制。
3.4 路由层（`backend/app/routes`）
- `auth.py`\
功能：注册、登录、`/api/me` 用户信息。\
技术栈：`FastAPI APIRouter`, `Pydantic`, JWT 鉴权。
- `lesson_plan.py`\
功能：智能备课生成、课标检查、档案保存等接口。\
技术栈：`FastAPI`, `LangChain/LLM`, 数据落库。
- `homework.py`\
功能：作业批改任务发起、结果查询、学情数据输出。\
技术栈：`FastAPI`, 异步任务轮询模式。
- `knowledge.py`\
功能：知识库检索、问答与类比输出。\
技术栈：`FastAPI`, 检索服务 + LLM 回答。
- `communication.py`\
功能：通知生成、家访记录 CRUD、家访建议与对象推荐。\
技术栈：`FastAPI`, 规则 + LLM 生成。
- `microcourse.py`\
功能：微课视频分析任务提交、结果查询、名师资源接口。\
技术栈：`FastAPI`, 音视频处理, 向量匹配。
- `legacy_agents.py`\
功能：兼容旧版 Agent 接口，避免新旧路由冲突。\
技术栈：`FastAPI` 兼容层。
- `teacher_growth.py`\
功能：教师成长档案数据、统计刷新、职称材料导出。\
技术栈：`FastAPI`, 统计聚合, `python-docx/reportlab`。
- `psychology.py`\
功能：心理分析、预警列表、今日提醒、周清单 CRUD。\
技术栈：`FastAPI`, LLM 评估, 数据缓存。
- `dream.py`\
功能：梦想模拟器职业列表、故事推进、路径生成、插画生成。\
技术栈：`FastAPI`, LLM 生成, JSON 场景引擎。
- `student_archive.py`\
功能：学生成长档案聚合、能力管理、闪光时刻、目标生成。\
技术栈：`FastAPI`, SQL 聚合, LLM 文本生成。
- `teacher_dashboard.py`\
功能：教师首页看板聚合、待办事项 CRUD。\
技术栈：`FastAPI`, 看板聚合服务。
- `routes/_init_.py`\
功能：包标记文件。\
技术栈：Python 包机制。
3.5 服务层（`backend/app/services`）
- `local_llm.py`\
功能：统一大模型调用入口（本地 ctransformers + Ollama 回退）。\
技术栈：`ctransformers`, `langchain_community.Ollama`。
- `lesson_plan_generator.py`\
功能：生成复式课堂备课方案。\
技术栈：`LangChain/Ollama`, 结构化文本生成。
- `standard_checker.py`\
功能：课标覆盖检查与反馈。\
技术栈：规则 + LLM 校核。
- `homework_corrector.py`\
功能：作业 OCR/判题/统计与学情输出。\
技术栈：OCR + LLM + 规则评分。
- `knowledge_retriever.py`\
功能：知识点检索、类比素材拼接。\
技术栈：SQL 查询 + 简单检索策略。
- `qa_engine.py`\
功能：教学问答生成（基于知识检索上下文）。\
技术栈：检索增强 + `LocalLLM`。
- `notice_generator.py`\
功能：家校通知润色与结构化输出。\
技术栈：提示词工程 + `LocalLLM`。
- `visit_suggestion.py`\
功能：家访对象推荐与家访内容建议。\
技术栈：规则融合 + `LocalLLM`。
- `video_processor.py`\
功能：微课视频转写/提取文本。\
技术栈：`ffmpeg`, `whisper`。
- `master_matcher.py`\
功能：名师课程匹配与相似资源召回。\
技术栈：`sentence-transformers`, 向量/关键词混合检索。
- `comparison_engine.py`\
功能：教师微课与名师课差异分析，输出改进建议。\
技术栈：对比提示词 + `LocalLLM`。
- `microcourse_service.py`\
功能：微课异步任务编排与状态管理。\
技术栈：内存任务池 + 服务编排。
- `teacher_stats.py`\
功能：教师成长维度统计与缓存。\
技术栈：SQL 聚合 + `Redis`（可选）。
- `badge_service.py`\
功能：勋章解锁判定与进度计算。\
技术栈：规则引擎（数据库配置驱动）。
- `title_material_generator.py`\
功能：教师职称材料导出（DOCX/PDF）。\
技术栈：`python-docx`, `reportlab`。
- `psychology_service.py`\
功能：心理材料分析、预警等级判定、建议生成。\
技术栈：规则 + `LocalLLM`。
- `psychology_scheduler.py`\
功能：心理提醒与周清单定时刷新。\
技术栈：`APScheduler`。
- `custom_career.py`\
功能：自定义职业模板生成（故事、技能、知识图谱）。\
技术栈：提示词生成 + `LocalLLM`。
- `story_engine.py`\
功能：梦想故事节点推进、选择反馈、最终路径生成。\
技术栈：状态机式流程 + `LocalLLM`。
- `illustration_generator.py`\
功能：梦想场景 AI 插画（简笔画 SVG）生成。\
技术栈：LLM 元素选择 + SVG 绘制。
- `student_archive.py`\
功能：学生档案聚合（基础信息、成绩趋势、能力、闪光、目标）。\
技术栈：SQL 聚合 + 缓存表刷新。
- `flash_polisher.py`\
功能：闪光时刻文本润色与鼓励语生成。\
技术栈：提示词工程 + `LocalLLM`。
- `goal_generator.py`\
功能：阶段目标 AI 生成并持久化。\
技术栈：`LocalLLM` + SQL 数据驱动。
- `student_archive_scheduler.py`\
功能：学生学期统计定时刷新。\
技术栈：`APScheduler`。
- `dashboard_service.py`\
功能：教师工作台首页聚合数据（统计、提醒、待办、勋章）。\
技术栈：SQL 聚合 + 规则计算。
- `asr.py`\
功能：语音识别封装（用于语音输入场景）。\
技术栈：`whisper`/ASR 封装。
- `standard_checker.py`\
功能：教学方案规范与课标适配检查。\
技术栈：规则校验 + LLM 辅助。
- `services/_init_.py`\
功能：包标记文件。\
技术栈：Python 包机制。
3.6 包初始化文件
- `backend/_init_.py`、`backend/app/routes/_init_.py`、`backend/app/services/_init_.py`、`backend/app/db/_init_.py`\
功能：Python 包初始化/命名空间声明。\
技术栈：Python 模块系统。
五、全流程使用指南
为了能够完整体验“远山不远”项目的所有功能（含 AI 真实生成），请按照以下步骤进行操作：
步骤 1：环境与依赖准备
1. 确保已安装 Python 环境。
2. 进入项目根目录并安装依赖（如需）：
```bash
cd ./yuanshan_Agent/yuanshan_Agent
pip install -r backend/requirements.txt
```
步骤 2：准备本地大模型服务（Ollama）
本项目默认配置推荐使用本地部署的 Qwen 模型：
1. 安装 [Ollama](https://ollama.com/) 并启动。
2. 在终端拉取并运行模型（此过程可能需要下载几十GB文件）：
```bash
ollama run qwen2.5:7b
```
3. 确保 Ollama 服务在 `http://localhost:11434` 正常运行，并可接收请求。
步骤 3：配置并启动后端服务
1. 在终端设置环境变量以启用真实大模型：
```bash
export USE_REAL_LLM=true
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=qwen2.5:7b
```
2. 启动后端服务（推荐使用模块方式启动以避免相对导入报错）：
```bash
python -m backend.main
```
*(服务默认启动在 `http://0.0.0.0:8000`)*
步骤 4：前端交互体验
1. 在浏览器中直接双击打开项目根目录下的 `yuanshan.html` 文件，或者使用 VSCode Live Server 插件打开。
2. 账号登录（后端内置了种子测试账号）：
教师端体验：输入账号 `teacher001`，密码 `123456`
学生端体验：输入账号 `student001`，密码 `123456`
3. 核心功能流转验证：
教师端登录后：进入工作台，可体验**\*\*智能备课\*\***（输入课题生成教案）、**\*\*生成家校通知\*\***（选择学生与情境自动润色）、**\*\*批改作业\*\***等。此时后端会调用 Ollama 进行真实推演并返回结果。
学生端登录后：进入****梦想模拟器****，可以设定自己的梦想职业，系统会根据大模型生成成长故事节点，并支持多分支选择。
