# class-advisor-ai

**Repository Path**: ftliang/class-advisor-ai

## Basic Information

- **Project Name**: class-advisor-ai
- **Description**: 班主任 AI 智能体系统
本科新生班主任四年完整周期的 AI 智能体系统，通过 QQ 官方机器人与班主任交互，提供学生档案管理、学情分析、谈心谈话记录、通知公告、日程管理等功能。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 青禾 · 班主任 AI 智能体助手

> **把最繁琐的班主任日常，交给一群懂班级、能动手的 AI 助手。**
> **青禾**，一名"带过班"的 AI 班主任助理，为你守住每一个学生的成长节点。

<p align="center">
  <a href="https://gitee.com/ftliang/class-advisor-ai"><img src="https://gitee.com/ftliang/class-advisor-ai/widgets/widget_5.svg" alt="Gitee 服务端仓库" width="150"></a>
  &nbsp;&nbsp;
  <a href="https://gitee.com/ftliang/class-advisor-pc"><img src="https://gitee.com/ftliang/class-advisor-pc/widgets/widget_5.svg" alt="Gitee 桌面端仓库" width="150"></a>
  &nbsp;&nbsp;
  <a href="https://qh.write2.me"><img src="https://img.shields.io/badge/项目详情-qh.write2.me-2dd4bf" alt="项目详情页"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/license-AGPL--3.0-green" alt="License">
  <img src="https://img.shields.io/badge/端-QQ机器人%20%2B%20桌面客户端-teal" alt="双端">
  <img src="https://img.shields.io/badge/智能体-8位-blue" alt="8智能体">
</p>

> 想要更完整、持续更新的项目介绍与体验入口，请访问 **项目详情页 [https://qh.write2.me](https://qh.write2.me)**。

---

## 一、它是什么

**青禾** 是一套面向高校辅导员 / 班主任的 **AI 班主任智能体系统**——以 **QQ 机器人** 7×24 小时贴身服务，以 **桌面客户端** 提供可视化工作台，把档案、学情、谈心、通知、巡检等繁杂事务，交给一群分工明确的 AI 智能体并行完成。

> "不只是聊天机器人，而是你班级事务的 AI 团队。"

---

## 二、为什么需要青禾

大学班主任（辅导员）的日常，被大量"低价值、高频率"的事务淹没：

| 痛点 | 传统方式 | 青禾的做法 |
|------|---------|-----------|
| 学生档案散乱 | 翻表格、翻文件夹 | AI 档案管家随时调取、自动更新 |
| 学情掌握滞后 | 考试后才后知后觉 | 学情分析 AI 主动预警 |
| 谈心记录流于形式 | 记完就忘、难追踪 | 谈话记录自动归档、持续追踪 |
| 通知反复手动群发 | 复制粘贴、易错漏 | 通知助手起草 + 定时发布 |
| 班级状态靠人盯 | 靠经验和"感觉" | 巡检 Agent 自动扫描、生成报告 |

**青禾的核心价值：把班主任从"事务员"解放回"育人者"。**

---

## 三、核心卖点

### 1. 一群懂班级的 AI 智能体，各司其职

不是一个大模型硬扛所有事，而是 **8 位分工明确的智能体** 组成的"班级工作团队"：

| 智能体 | 职责 | 场景示例 |
|--------|------|---------|
| 🎓 **班主任总管** (main) | 统一入口，调度全局 | "班级今天整体情况如何？" |
| 📂 **学生档案管家** (archive) | 档案查询与管理 | "查一下张三的档案" |
| 📢 **通知公告助手** (notices) | 通知起草与发布 | "帮我写一条调课通知" |
| 📅 **日程管家** (schedule) | 班级日程与事件管理 | "本周有什么安排？" |
| 📄 **文档处理专家** (docs) | PDF/Word/Excel 处理 | "把这份名单生成统计表" |
| 📊 **学情分析师** (analysis) | 成绩分析与预警 | "有哪些学生需要预警？" |
| 💬 **谈心谈话记录员** (talks) | 谈话记录与追踪 | "记录今天与李四的谈话" |
| 🛰️ **巡检 Agent** (patrol) | 自动扫描班级状态 | "执行一次班级巡检" |

### 2. 开放式架构：第三方智能体，按说明书即装即用

青禾基于 **开放式多智能体框架** 构建，这是它最可贵的扩展性：

- **即插即用**：每一位智能体都是一套**独立、可插拔的单元**，自带一份"能力说明书"（智能体定义 + 职责说明）。只要你提供一份新智能体的能力说明书，系统即可**自动装载上线**，立刻投入班级事务。
- **按需增添功能**：你可以**根据班级管理的实际需求，自行增添新的职能角色**——新增一个智能体，就等于新增一项班级管理能力，**无需改动核心代码**。
- **多模型接入**：每个智能体可**独立选用不同的大模型**（科大 LLM、硅基流动等），按场景选最合适、最经济的模型。
- **开放生态**：支持接入、复用第三方开源的智能体定义与技能，让青禾的"班级团队"随你的需要持续壮大。

> 想为青禾增添一个新角色？写一份能力说明书，装进去，它就开始干活。

### 3. 双端协同：QQ 机器人 + 桌面工作台

- **QQ 机器人端**：学生、老师在任何 QQ 场景即可对话，7×24 小时在线，事务处理随手完成。
- **桌面客户端「青禾」**：原生桌面应用（Tauri 2 + Vue 3），提供学生档案、课表中心、数据看板、定时任务等可视化工作台。

### 4. 主动服务，而不只是被动应答

系统内置 **主动推送机制**：学情预警、通知提醒、定时任务、巡检报告，会**主动**推送到 QQ 与客户端，而非等你去问。

### 5. 深度数据能力

- 学生档案结构化存储（PostgreSQL），支持批量查询、统计、筛选
- 课表中心可视化呈现，班级课表、学生人数一目了然
- 数据看板实时掌握班级全貌

### 6. 自主可部署、可扩展

- 开源（AGPL-3.0），服务端一键 Docker 部署
- 支持内网/外网双模式，数据可自主掌控
- 敏感凭据单独管理，充分保护学生数据隐私

---

## 四、技术架构

```
QQ用户 → OpenClaw QQ Bot(官方机器人) → OpenClaw Gateway(端口18789)
           → 总管Agent(调度全局)
             ├── dispatch → archive(学生档案管家) → 直查PostgreSQL
             ├── dispatch → analysis(学情分析师)   → 直查PostgreSQL
             ├── dispatch → talks(谈心谈话记录员)   → 直查PostgreSQL
             ├── dispatch → notices(通知公告助手)   → 直查PostgreSQL
             ├── dispatch → schedule(日程管家)     → 直查PostgreSQL
             ├── dispatch → docs(文档处理专家)      → LLM能力
             ├── dispatch → patrol(巡检Agent)      → 全量扫描班级状态
             └── bff_dashboard → advisor-bff API(仅回环 127.0.0.1:5050)

cron → patrol_trigger.sh → patrol Agent → 巡检报告存档
PC端(青禾) / Web端 → Web入口(nginx，对外 8090) → advisor-bff API → PostgreSQL + 巡检报告 + 记忆查询 + 课表
```

> **端口与入口（当前部署）**：对外只暴露 **8090（HTTP）/ 8443（HTTPS）** 一个入口（`advisor-web` nginx），`/api`、`/v1`、`/health` 统一反代到 `advisor-bff`。`advisor-bff`（`127.0.0.1:5050`）、`ocr-server`（`127.0.0.1:9100`）、PostgreSQL（`127.0.0.1:5432`）**均只绑定回环**，不对外；`/v1` 由 BFF 再转发到 OpenClaw 网关（18789）并注入网关密钥，前端不持有密钥。PC 端内外网均走 Web 入口 8090（`http://<服务器IP>:8090/v1`）。

---

## 五、快速开始 / 部署

- **部署指南**：请阅读工程内 [部署指南.md](部署指南.md)，内含从环境准备到客户端配置的完整步骤。
- **桌面客户端**：`class-advisor-pc`（[Gitee 仓库](https://gitee.com/ftliang/class-advisor-pc)），Tauri 2 打包，安装即用。

```bash
# 服务端快速上手（完整步骤见部署指南.md）
cp server-configs/.secrets.example /opt/class-advisor/.secrets   # 填写真实配置
cd server-configs/db  && docker compose up -d                     # PostgreSQL + Redis
cd server-configs/bff && docker compose up -d --build             # advisor-bff(仅回环 127.0.0.1:5050)
docker compose -f server-configs/web/docker-compose.yml up -d --build  # advisor-web(对外 8090/8443，唯一入口)
# 再按部署指南配置 OpenClaw Gateway + 定时任务
```

---

## 六、适用场景

- **高校辅导员 / 班主任**：日常学生事务管理、学情跟踪、谈心谈话
- **班级管理**：通知发布、日程安排、考勤巡检、文档归档
- **学生成长档案**：建立与持续更新学生全周期档案

---

## 七、常见问题

**Q：需要很强的技术能力才能用吗？**
A：不需要。PC 端「青禾」安装即用，连上服务器即可对话；技术细节由服务端 Docker 编排完成。

**Q：数据安全吗？**
A：支持私有化部署，数据存放在你自己掌控的服务器上，支持内网/外网双模式，敏感凭据单独管理。

**Q：可以用我们自己的大模型吗？**
A：可以。系统接入多种 LLM 提供商（科大 LLM、硅基流动等），每个智能体可在设置中独立切换模型。

**Q：智能体能扩展吗？**
A：能。系统基于开放式多智能体架构，支持**第三方智能体按说明书自动安装**，你可**根据管理需求自行增添功能角色**，无需改动核心代码。

---

## 八、推广文案短句（可用于海报 / 社交传播）

1. **"你负责育人，AI 负责琐事。"**
2. **"8 位 AI 班助，24 小时在线守候你的班级。"**
3. **"档案、学情、谈心、通知、巡检——一个青禾全搞定。"**
4. **"第三方智能体按说明书即装即用，能力随你扩展。"**
5. **"让每一次谈话都有记录，让每一个学生都被看见。"**
6. **"从'事务员'到'育人者'，只差一个青禾。"**

---

## 了解更多

- **服务端源码**：[https://gitee.com/ftliang/class-advisor-ai](https://gitee.com/ftliang/class-advisor-ai)
- **桌面端源码**：[https://gitee.com/ftliang/class-advisor-pc](https://gitee.com/ftliang/class-advisor-pc)
- **项目详情页（推荐）**：[https://qh.write2.me](https://qh.write2.me)

*青禾 · 让班级管理更从容*