# 314寝室智能助手

**Repository Path**: Sckaro/Singularity

## Basic Information

- **Project Name**: 314寝室智能助手
- **Description**: Java大模型应用项目--学校生活Agent
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2025-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PersionAgent

一个基于 Spring Boot + LangChain4j 的个人/寝室智能助手。集成对话、知识检索（RAG）、日程活动管理、课程表解析、邮件工具等能力，支持流式对话与向量检索，专为“课程与活动/计划冲突检测”和日常信息助理场景而设计。

> 注意：仓库中的 `src/main/resources/application.yaml` 当前包含示例密钥，开源使用时请改为环境变量或本地配置文件，避免提交敏感信息。

## 功能特性

- 会话智能体（SSE 流式输出）：`GET /agent/chat` 支持连续对话
- 向量检索：管理员上传文本入库到向量数据库：`POST /admin/load/vector`
- 课程与活动/计划冲突检测：
  - 根据星期或日期查询当天课程与计划
  - 基于时间段重合判断冲突，过滤历史计划
- 课程表/活动实体与持久化（MySQL + MyBatis-Plus）
- 用户管理基础能力：`/admin/user` 下的增删改查与分页
- 在线接口文档：Knife4j/OpenAPI 3

## 技术栈

- Spring Boot 3.5, Web + WebFlux(SSE)
- MySQL, MyBatis-Plus, MyBatis
- LangChain4j 1.0.0-beta3（聊天、Embedding、Web Search、Reactor）
- DashScope(通义千问) 接入
- Pinecone 向量数据库
- Lombok、Jakarta Mail、Apache POI(课程表Excel解析)

参见 `pom.xml` 依赖：
- `dev.langchain4j:langchain4j-spring-boot-starter`
- `dev.langchain4j:langchain4j-community-dashscope-spring-boot-starter`
- `dev.langchain4j:langchain4j-web-search-engine-searchapi`
- `dev.langchain4j:langchain4j-pinecone`
- `org.mybatis.spring.boot:mybatis-spring-boot-starter`, `com.baomidou:mybatis-plus-spring-boot3-starter`

## 项目结构

```
src/main/
  com/agent/
    PersionAgentApplication.java
    controller/
      AgentController.java         # 对话接口（SSE）
      AdminLoadController.java     # 管理员上传文本入向量库
      UserController.java          # 用户管理 CRUD & 分页
    entity/                        # Activities, CourseSchedule, User, Group, Friend, GroupFriend
    service/                       # 业务接口与 impl（活动、课程、用户、PDF解析等）
    mapper/                        # MyBatis / MP 映射与 XML（见 resources/mappers/）
    config/, interceptor/, utils/, tools/, web/
  resources/
    application.yaml               # 示例配置（请改为环境变量）
    mappers/*.xml                  # Mapper XML
```

## 数据库

- 初始化 SQL：`target/classes/schema.sql`（或自行迁移到 `src/main/resources/`）
- 主要表：
  - `course_schedule`：课程名、周/日期、开始/结束时间、地点、教师、user_id
  - `activities`：事项、地址、日期/星期、开始/结束时间、是否全天、user_id
  - `user`、`groups`、`friends`、`group_friend`

## 快速开始

### 1) 环境准备

- JDK 21+
- Maven 3.9+
- MySQL 8.x

### 2) 配置环境变量（推荐）

将以下敏感配置改为环境变量或 `application-local.yaml`：
- DashScope/LLM API Key
- 向量库（Pinecone 等）配置
- MySQL 连接信息
- 邮件与第三方服务密钥

示例（Windows PowerShell）：

```powershell
$env:DASH_SCOPE_API_KEY="your_key"
$env:MYSQL_URL="jdbc:mysql://localhost:3306/PersionAgent?..."
$env:MYSQL_USER="root"
$env:MYSQL_PWD="123"
```
并在 `application.yaml` 中通过占位符引用，如：`${DASH_SCOPE_API_KEY:}`。

### 3) 初始化数据库

- 执行 `schema.sql` 初始化表结构

### 4) 启动

- IDE 直接运行 `com.agent.PersionAgentApplication`
- 或命令行：
```bash
mvn spring-boot:run
```
服务默认端口：`8080`

## API 速览

- 对话（SSE 流式）
  - `GET /agent/chat?memoryId={id}&message={text}`
  - 响应类型：`text/stream;charset=utf-8`
- 向量入库（管理员）
  - `POST /admin/load/vector`，`multipart/form-data`，字段 `file`
- 用户管理（后台）
  - `POST /admin/user` 新增
  - `GET /admin/user/{id}` 查询
  - `PUT /admin/user` 修改
  - `DELETE /admin/user/{id}` 删除（逻辑）
  - `GET /admin/user/page?page=1&size=10&username=...&stated=...` 分页

更多接口请访问 Knife4j：启动后访问 `/doc.html` 或 `/swagger-ui/index.html`。

## 冲突检测说明（核心能力）

- 数据来源：`course_schedule` 与 `activities`
- 依据字段：日期 `date`、星期 `day_of_week/week`、`start_time`、`end_time`
- 处理逻辑：
  - 按用户维度查询指定日期/星期的课程与活动
  - 过滤历史计划（当前时间之前的记录）
  - 判断时间段是否重叠，给出冲突列表或建议

## 开发指南

- 代码风格：Lombok + 分层（controller/service/mapper/entity）
- 日志与 SQL：`mybatis-plus.configuration.log-impl=StdOutImpl`
- SSE 流：`AgentController.chat()` 使用 `Flux<String>` 推送
- 课程/活动等领域服务见 `service/impl/`

## 贡献

欢迎提交 Issue 与 PR：
- 请勿提交包含真实密钥的配置
- 新增模块请补充单元测试与文档

## 许可证

MIT（可根据实际需要修改）