# webagent

**Repository Path**: stdin2/webagent

## Basic Information

- **Project Name**: webagent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# DeepMaker

### 基于多模态大模型的数字化教学资源制作系统

**让课程资料成为可检索的知识，让教学想法成为可复用的资源。**

私有知识库 · RAG 辅助生成 · 交互式 PPT · 多模态创作 · 教学资源管理

**DeepBug 团队 · 中国软件杯 A1 赛题项目**

[功能概览](#功能概览) · [技术亮点](#技术亮点) · [系统架构](#系统架构) · [本地运行](#本地运行)

</div>

---

## 项目简介

DeepMaker 面向教师与学生，将课程资料整理、教案编写、习题生成、课件制作和资源管理整合到同一个工作台。用户可以上传自己的教材与讲义，建立私有知识库，再围绕课程主题生成教案、习题、PPT、教学配图和讲解语音。

项目采用 **Vue 3 + Spring Boot + Spring AI** 的前后端分离架构，通过 **PostgreSQL / pgvector** 支持结构化数据与知识检索，通过 **阿里云 OSS** 保存原始文件和生成成果，串联起“资料输入 → 内容创作 → 资源沉淀”的教学工作流程。

> **一个典型场景：** 为一节课程上传参考讲义，建立知识索引，生成配套教案与练习题；确认并修改 PPT 大纲后选择模板生成课件，再补充教学插图与讲解音频，最后按学科、年级等标签管理成果。

## 功能概览



| 模块 | 核心能力 | 教学场景 |
| --- | --- | --- |
| 用户与权限 | 注册登录、JWT 认证、角色划分与数据归属校验 | 为教师与学生提供个人工作空间 |
| 私有知识库 | 知识库组织、文档上传、分块处理、异步向量化 | 按课程或专题积累教材、讲义与参考资料 |
| 教案与习题 | 结合生成参数与知识库上下文，流式返回内容 | 编写教学设计、准备课后练习 |
| 交互式 PPT | 创建会话、生成和编辑大纲、选择模板、生成课件 | 先打磨课程结构，再制作演示文稿 |
| 多模态交互 | 图像生成与理解、文字转语音、语音转文字 | 制作教学插图、讲解音频，辅助表达创作需求 |
| 资源管理 | 统一归档、标签分类、条件检索、编辑、预览与下载 | 查找、调整并复用已有教学成果 |

## 技术亮点

### 1. 让生成内容结合自己的课程资料

私有知识库采用“**上传文档 → 建立向量索引**”的两步式流程，将文件管理与 AI 处理分开。文档经解析、分块与嵌入后进入向量存储，生成时检索相关内容作为模型上下文，为教案和习题提供课程依据。

原始文件、文档元数据和向量索引分别由 OSS、业务数据表和 pgvector 承担，便于组织资料及管理文档生命周期。

### 2. PPT 创作过程可编辑、可分步推进

PPT 制作围绕会话组织：**填写需求 → 生成大纲 → 修改大纲 → 选择模板 → 生成课件**。用户在生成最终文件前即可调整内容结构，系统通过任务记录中的 `session_data` 保存会话中间数据，衔接大纲与课件生成阶段。

课件生成后，可继续制作配图与讲解语音，作为教学附件使用。

### 3. 用不同交互方式承接不同生成任务

| 任务类型 | 交互方式 | 作用 |
| --- | --- | --- |
| 习题、教案、PPT 大纲 | SSE 流式响应 | 在生成过程中逐步呈现内容 |
| 图片、语音等耗时任务 | 异步执行 + 任务状态查询 | 通过任务 ID 跟踪处理结果 |
| 生成后的教学资源 | 元数据入库 + 文件存储 | 支持后续分类、检索、编辑与下载 |

### 4. 从一次生成延伸到持续复用

生成成果进入统一的教学资源管理流程，通过资源类型、学科、年级等标签组织。用户可以调整名称、描述和内容，在后续备课时继续查找与复用，逐步积累自己的教学资料库。

## 系统架构

![DeepMaker 系统架构图](docs/images/system-architecture.png)

系统按照客户端、服务层、业务层、公共技术层与基础设施层划分职责：前端承接创作交互，后端编排知识库、生成任务和资源管理，模型服务提供文本、图像与语音能力。

| 层次 | 技术组成 | 主要职责 |
| --- | --- | --- |
| 前端交互 | Vue 3、Vite、Element Plus、Pinia、Vue Router | 页面展示、状态管理与创作流程 |
| 后端服务 | Java 21、Spring Boot 3.4.6、Spring Security、JWT | 业务接口、身份认证与访问控制 |
| AI 集成 | Spring AI、Spring AI Alibaba、DashScope SDK | 模型调用、文本生成、嵌入与多模态处理 |
| 数据持久化 | MyBatis-Plus、PostgreSQL、pgvector | 用户与资源数据、任务状态、向量检索 |
| 文件与课件 | 阿里云 OSS、文多多 API | 文件存储与 PPT 生成 |
| 设计部署环境 | Nginx、Docker、龙芯平台 | 反向代理、容器部署与国产平台适配方案 |

> 架构图保留开发设计文档中的技术规划；具体依赖、模型名称和部署方式以当前代码与运行配置为准。图中的部署组件及平台适配不代表本次已完成环境验证。

## 数据流设计

![用户认证、私有知识库、内容生成与教学资源管理之间的数据流](docs/images/data-flow.png)

整个流程围绕四个业务环节展开：

1. **身份认证**：用户登录后获取令牌，后续请求携带身份信息。
2. **知识准备**：上传文件并保存元数据，按需执行文档向量化，形成可检索的课程知识。
3. **内容生成**：接收创作需求，结合知识库上下文调用模型，通过流式响应或异步任务返回结果。
4. **资源沉淀**：将成果文件和资源元数据保存，支持标签检索、内容编辑、下载与删除。

## 展示建议

演示时可以围绕同一门课程展开，完整呈现资料如何变成教学成果：

1. **建一个课程知识库**：上传讲义，展示文档列表与向量化状态。
2. **生成一组教案或习题**：选择课程资料与生成参数，展示内容逐步返回。
3. **制作一份 PPT**：生成大纲，现场修改一个章节，再选择模板生成课件。
4. **补充教学附件**：围绕同一主题生成配图或讲解语音。
5. **回到资源库**：通过标签找到成果，展示预览、编辑与下载。

## 目录结构

```text
deepbug/
├── README.md                         # 项目展示入口
├── docs/images/                      # 功能结构、系统架构与数据流图
├── front/zhongruan-cup-web-agent/      # Vue 前端
│   └── src/
│       ├── api/                      # 业务接口封装
│       ├── components/               # 公共组件
│       └── views/                    # 知识库、资源创作与管理页面
└── back/zhongruan-cup-web-agent/       # Spring Boot 后端
    ├── pom.xml                       # Java 与依赖版本
    ├── src/main/java/                # 接口、业务服务与基础配置
    ├── src/main/resources/           # 应用配置与 SQL 脚本
    └── postman_*.json                # 按业务场景组织的接口测试集合
```

上方列出教学资源系统相关目录。

## 本地运行

### 环境准备

- **JDK 21、Maven**：后端构建与运行。
- **Node.js 与 npm**：安装前端依赖，版本需兼容项目使用的 Vite 4。
- **PostgreSQL + pgvector**：保存业务数据与文本向量。
- **模型与云服务配置**：按使用功能准备 DashScope、阿里云 OSS 和文多多服务凭据。

### 配置后端

在本地配置中设置以下项目，配置入口为 [`application.yml`](back/zhongruan-cup-web-agent/src/main/resources/application.yml)：

| 配置项 | 配置内容 |
| --- | --- |
| `spring.datasource` | PostgreSQL 地址、数据库、账号及使用的 schema |
| `spring.ai.dashscope` | 模型服务凭据、文本生成与嵌入等模型配置 |
| `spring.ai.vectorstore.pgvector` | 向量存储参数；向量维度需与实际嵌入模型一致 |
| `aliyun.oss` | Endpoint、Bucket 与访问凭据 |
| `jwt` | 本地 JWT 签名与过期时间配置 |
| `wenduoduo` | PPT 服务配置 |

数据库脚本位于 [`src/main/resources/sql/`](back/zhongruan-cup-web-agent/src/main/resources/sql/)，包含多个版本。初始化前应核对目标 schema、表结构与向量维度，选择适用脚本，不要将所有版本重复执行。真实服务凭据请保存在本地配置或环境变量中。

在仓库根目录打开终端：

```powershell
cd back/zhongruan-cup-web-agent
mvn spring-boot:run
```

默认后端地址为 `http://localhost:8080`，API 前缀为 `/api`。

### 启动前端

另开终端，在仓库根目录执行：

```powershell
cd front/zhongruan-cup-web-agent
npm install
npm run dev
```

访问 `http://localhost:3000`。Vite 默认将 `/api` 请求代理到 `http://localhost:8080`；部分接口包含直连地址，修改后端端口时需同时核对相应请求配置。

前端构建命令：

```powershell
npm run build
```