# llm-agent-study **Repository Path**: wangdan22/llm-agent-study ## Basic Information - **Project Name**: llm-agent-study - **Description**: 大模型应用开发学习，脚手架。nodejs - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-09 - **Last Updated**: 2026-04-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 教育多智能体协同平台 > **项目定位**：以 Agent 系统性学习为核心的全栈工程，采用 NestJS + Vue3 技术栈，聚焦智能体开发核心能力 > **技术栈**：NestJS 10.x + Vue3 3.5.x + TypeScript 5.x + MySQL 8.0 + Qdrant > **架构特色**：三层分层架构（AI层/系统层/业务层）+ 插件化能力系统 + 依赖注入解耦 --- ## 📋 目录 - [快速开始](#-快速开始) - [技术栈总览](#-技术栈总览) - [核心功能](#-核心功能) - [架构设计](#-架构设计) - [三层分层架构](#1-三层分层架构) - [核心概念详解](#2-核心概念详解) - [设计模式应用](#3-设计模式应用) - [项目结构](#-项目结构) - [模块详解](#-模块详解) - [AI 核心能力层](#1-ai-核心能力层-aitech) - [系统支撑层](#2-系统支撑层-systemtech) - [教育业务层](#3-教育业务层-businesstech) - [数据流总览](#-数据流总览) - [环境配置](#-环境配置) - [API 文档](#-api-文档) - [开发指南](#-开发指南) - [默认账号](#-默认账号) - [注意事项](#-注意事项) - [许可证](#-许可证) --- ## 🚀 快速开始 ### 一键启动（推荐） **Windows 用户：** ```bash # 双击运行 start-all.bat # 或命令行 cd c:\Users\WD\Desktop\agent学习\education-ai start-all.bat ``` **停止所有服务：** ```bash stop-all.bat ``` 脚本会自动检测服务状态、询问是否重启、检查数据库连接。 --- ## 🛠️ 技术栈总览 | 层级 | 技术 | 版本 | 用途 | |------|------|------|------| | **后端框架** | NestJS | 10.x | 企业级 Node.js 框架 | | **后端语言** | TypeScript | 5.x | 类型安全 | | **数据库** | MySQL | 8.0+ | 关系型存储（云端部署） | | **ORM** | TypeORM | 0.3.x | 对象关系映射 | | **前端框架** | Vue 3 | 3.5.x | 渐进式前端框架 | | **构建工具** | Vite | 5.x | 快速开发服务器 | | **UI 组件** | Element Plus | 2.x | Vue3 组件库 | | **状态管理** | Pinia | 2.x | 轻量状态管理 | | **大模型** | DeepSeek | API | 默认模型 | | **其他模型** | 通义千问 / Yi / OpenAI | API | 多模型切换 | | **认证** | JWT + Passport | - | 无状态认证 | | **密码加密** | bcrypt | 10轮 | 安全哈希 | | **任务队列** | BullMQ | Latest | 异步任务处理 | | **缓存** | Redis | Latest | 会话/缓存 | --- ## ✨ 核心功能 1. **用户认证** - JWT Token 登录，bcrypt 密码加密 2. **AI 对话** - SSE 流式输出，逐字显示效果 3. **多模型切换** - 支持 DeepSeek、通义千问、Yi、OpenAI 四种大模型 4. **多智能体** - Teacher/Tutor/Homework/Evaluate/Knowledge Agent 5. **记忆系统** - WindowMemory 滑动窗口记忆，自动管理上下文 6. **能力插件** - 可插拔的能力系统（Tools、Prompt优化等） 7. **多租户** - 支持多租户隔离，中间件自动注入租户ID 8. **API Key 动态配置** - 运行时动态切换模型 API Key --- ## 🏗️ 架构设计 ### 1. 三层分层架构 ``` ┌─────────────────────────────────────────────┐ │ 业务层 (business/) │ │ - 教育领域逻辑 │ │ - 业务Agent实现（TeacherAgent等） │ │ - 依赖 ai/ 和 system/ │ ├─────────────────────────────────────────────┤ │ 系统层 (system/) │ │ - 身份认证、用户管理 │ │ - 多租户、任务调度 │ │ - 跨业务通用服务 │ ├─────────────────────────────────────────────┤ │ AI层 (ai/) │ │ - AI技术基础设施 │ │ - Agent框架、模型服务、记忆系统 │ │ - 无业务依赖，可被任何业务复用 │ └─────────────────────────────────────────────┘ ``` **分层原则**： - **ai/** = 技术基础设施（类似ORM、缓存） - **system/** = 通用服务（类似用户中心、权限中心） - **business/** = 业务逻辑（真正的领域代码） **依赖方向**： ``` business → system ✅ 正确：业务依赖系统服务 business → ai ✅ 正确：业务使用AI能力 system → ai ✅ 可选：系统可能调用Agent ai → business ❌ 禁止：AI层不能依赖业务 ai → system ❌ 禁止：AI层不能依赖系统 system → business ❌ 禁止：系统不能依赖具体业务 ``` --- ### 2. 核心概念详解 #### 2.1 Token（标签系统） **Token 就像快递单号或图书馆的 ISBN 编号**，用于唯一标识一个服务。 ```typescript // ai/agent-framework/tokens.ts export const AGENT_PROVIDER = Symbol('AGENT_PROVIDER'); ``` **为什么用 Symbol？** - ✅ **唯一性**：每个 Symbol 都是唯一的，不可能重复 - ✅ **类型安全**：IDE 可以自动补全和检查 - ✅ **语义清晰**：一眼就知道这是什么 **工作流程**： ``` 1. 定义 Token（创建标签） ↓ 2. 使用 Token 注册服务（贴标签） ↓ 3. NestJS 内部存储映射表 ↓ 4. 使用 Token 注入服务（找标签） ↓ 5. 拿到所有 Agent，可以注册、管理、调用 ``` **记忆口诀**： > Token 就像快递单号 > - 每个包裹（服务）都有一个唯一的单号（Token） > - 寄件人（Provider）贴上单号 > - 收件人（Consumer）凭单号取件 > - 单号唯一，不会搞混 --- #### 2.2 IAgentProvider（提供者接口） **IAgentProvider 就像"供应商合同"**，任何想提供 Agent 的类都必须实现这个接口。 ```typescript // ai/agent-framework/agent-provider.interface.ts export interface IAgentProvider { /** * 提供该领域的所有 Agent 实例 */ provideAgents(): BaseAgent[]; /** * 获取提供者的元数据（用于监控和管理） */ getMetadata(): AgentProviderMetadata; } ``` **为什么要这个接口？** ❌ **没有接口的做法（紧耦合）**： ```typescript // 每次加新领域都要修改 AI 层的代码 import { TeacherAgentFactory } from '../../business/education/...'; import { CounselorAgentFactory } from '../../business/psychology/...'; // ← 硬编码 ``` ✅ **有接口的做法（松耦合）**： ```typescript // AI 层只依赖接口，不知道具体实现 import { IAgentProvider } from '../../ai/agent-framework/agent-provider.interface'; { provide: AGENT_PROVIDER, useFactory: (...providers: IAgentProvider[]) => { // 自动遍历所有 Provider，不需要知道具体是谁 return providers.flatMap(p => p.provideAgents()); }, inject: [TeacherAgentFactory, CounselorAgentFactory], } ``` **餐厅供应商类比**： > - 你开了一家大餐厅（AI 框架） > - 需要从不同的供应商（Agent Provider）采购食材（Agent） > - 任何想给你供货的供应商，都必须签合同（实现接口） > - 餐厅老板不关心供应商具体是谁，只关心是否签了合同 --- #### 2.3 能力插件系统 **能力插件就像手机的 APP**，可以为 Agent 添加各种功能扩展。 ``` Agent = 手机系统（基础功能） Capability = APP（扩展功能） 例如： - RAG 能力 = 知识检索 APP - Tools 能力 = 工具箱 APP - Prompt 优化能力 = 智能助手 APP ``` **能力和工具的区别**（重要！）： | 概念 | 说明 | 生活类比 | 代码示例 | |------|------|----------|----------| | **能力 (Capability)** | Agent 的"技能包" | "我会做饭" | `ToolsCapability` | | **工具 (Tool)** | 能力的具体实现 | "用锅炒菜"、"用烤箱烘焙" | `CalculatorTool`, `SearchTool` | | **LLM** | 大脑，自主决策 | "今天想吃炒菜，所以用锅" | 根据任务选择工具 | **关键洞察**： - 🎯 **能力是"能不能做"**：Agent 拥有哪些技能（如"能调用工具"） - 🛠️ **工具是"用什么做"**：具体的实现方式（如"用计算器"还是"用搜索引擎"） - 🧠 **LLM 是"什么时候做"**：根据任务自主决策（如"这道题需要计算，所以用计算器"） **实际场景举例**： ``` 用户问："234 * 567 等于多少？" 1. Agent 有能力：ToolsCapability（能调用工具）✅ 2. LLM 分析：这是个数学计算题，需要用计算器 3. LLM 选择工具：CalculatorTool 4. 执行工具：234 * 567 = 132678 5. 返回结果给用户 ``` **这就是为什么叫"智能 Agent"而不是"脚本程序"！** - ❌ **脚本程序**：硬编码"如果遇到数字就用计算器" - ✅ **智能 Agent**：LLM 自己判断"这个问题需要计算，我应该用计算器" --- ### 3. 设计模式应用 | 模式 | 位置 | 说明 | |------|------|------| | **抽象工厂** | `ai/base/` | BaseAgent、BaseMemory 定义产品族 | | **适配器模式** | `ai/llms/adapters/` | 统一不同模型的接口 | | **注册表模式** | `AgentRegistry` | 集中管理 Agent 实例 | | **模板方法** | `BaseAgent.initialize()` | 定义算法骨架 | | **依赖注入** | 全局 | NestJS IoC 容器 | | **策略模式** | `system/identity/auth/` | JWT 认证策略 | | **守卫模式** | `system/identity/auth/` | 路由权限控制 | | **观察者模式** | SSE 流式输出 | 实时推送数据 | | **插件化架构** | `ai/capabilities/` | 即插即用的能力系统 | --- ## 📁 项目结构 ``` education-ai/ ├── docs/ # 📚 课程学习文档 │ ├── learning-roadmap.md # 学习路线 │ └── lesson-01-memory-system.md # 第一课：记忆系统 │ ├── blog/ # 📝 学习博客 │ ├── README.md # 博客索引和分类体系 │ └── 01-Agent核心技术/ # Agent 核心技术系列 │ └── 01-记忆系统实战-从零实现WindowMemory.md │ ├── edu-multi-agent-server/ # 🔧 后端工程 │ ├── src/ │ │ ├── main.ts # 应用入口：启动 NestJS 服务器 │ │ ├── app.module.ts # 根模块：导入所有功能模块 │ │ │ │ │ ├── ai/ # ★ AI核心能力层 │ │ │ │ │ │ │ ├── agent-framework/ # Agent 运行时框架 │ │ │ │ ├── base-agent.ts # BaseAgent：Agent 抽象基类，定义通用接口 │ │ │ │ ├── agent.controller.ts # Agent HTTP 控制器：提供 Agent 列表、执行等接口 │ │ │ │ ├── agent.module.ts # Agent 模块配置：注册 Factory 和 Provider │ │ │ │ ├── tokens.ts # Token 定义：Symbol 标签系统（AGENT_PROVIDER） │ │ │ │ ├── registry/ │ │ │ │ │ └── agent.registry.ts # AgentRegistry：Agent 注册中心，管理所有 Agent 实例 │ │ │ │ └── supervisor/ │ │ │ │ └── supervisor.service.ts # SupervisorService：监督者服务，协调多 Agent 协作 │ │ │ │ │ │ │ ├── capabilities/ # 能力插件系统 │ │ │ │ ├── index.ts # 导出索引 │ │ │ │ ├── capabilities.module.ts # 能力模块配置 │ │ │ │ ├── capability.interface.ts # IAgentCapability：能力接口定义 │ │ │ │ ├── capability.registry.ts # CapabilityRegistry：能力注册表 │ │ │ │ ├── rag/ # RAG 检索增强能力 │ │ │ │ │ └── rag.module.ts # RagModule：RAG 模块（待开发） │ │ │ │ └── tools/ # 工具调用能力 │ │ │ │ ├── tool.interface.ts # ITool：工具接口定义 │ │ │ │ ├── tool.registry.ts # ToolRegistry：工具注册表 │ │ │ │ ├── tools.capability.ts # ToolsCapability：工具能力实现 │ │ │ │ └── impl/ │ │ │ │ └── calculator.tool.ts # CalculatorTool：计算器工具实现 │ │ │ │ │ │ │ ├── chat/ # 对话会话管理 │ │ │ │ ├── chat-message.entity.ts # ChatMessage：聊天消息实体（TypeORM） │ │ │ │ ├── chat-session.entity.ts # ChatSession：聊天会话实体（TypeORM） │ │ │ │ ├── chat.controller.ts # ChatController：聊天 HTTP 控制器 │ │ │ │ ├── chat.service.ts # ChatService：聊天业务逻辑（会话管理、消息持久化） │ │ │ │ └── chat.module.ts # Chat 模块配置 │ │ │ │ │ │ │ ├── llms/ # LLM 模型服务层 │ │ │ │ ├── llm.adapter.ts # LLMAdapter：LLM 适配器接口，统一模型调用 │ │ │ │ ├── llm.service.ts # LLMService：LLM 服务，统一管理模型调用 │ │ │ │ ├── llm.controller.ts # LLMController：LLM HTTP 控制器（生成、切换） │ │ │ │ ├── llm-config.controller.ts # LLMConfigController：API Key 动态配置 │ │ │ │ ├── llm.module.ts # LLMModule：LLM 模块配置 │ │ │ │ └── adapters/ # 模型适配器实现 │ │ │ │ ├── deepseek.adapter.ts # DeepSeekAdapter：DeepSeek 模型适配器 │ │ │ │ ├── qwen.adapter.ts # QwenAdapter：通义千问模型适配器 │ │ │ │ ├── yi.adapter.ts # YiAdapter：零一万物模型适配器 │ │ │ │ └── openai.adapter.ts # OpenAIAdapter：OpenAI 模型适配器 │ │ │ │ │ │ │ ├── memory/ # 记忆系统实现 │ │ │ │ ├── memory.base.ts # BaseMemory：记忆系统抽象基类 │ │ │ │ ├── window-memory.ts # WindowMemory：滑动窗口记忆实现 │ │ │ │ └── memory.module.ts # Memory 模块配置 │ │ │ │ │ │ │ └── multimodal/ # 多模态处理（待开发） │ │ │ └── multimodal.module.ts # Multimodal 模块占位 │ │ │ │ │ ├── system/ # ★ 系统支撑层 │ │ │ ├── identity/ # 身份认证与用户管理 │ │ │ │ ├── auth/ # 认证授权 │ │ │ │ │ ├── auth.controller.ts # AuthController：登录、修改密码接口 │ │ │ │ │ ├── auth.service.ts # AuthService：JWT 签发、密码验证逻辑 │ │ │ │ │ ├── auth.module.ts # Auth 模块配置 │ │ │ │ │ ├── jwt.strategy.ts # JwtStrategy：JWT 认证策略 │ │ │ │ │ ├── jwt-auth.guard.ts # JwtAuthGuard：JWT 守卫，保护路由 │ │ │ │ │ └── token.service.ts # TokenService：Token 管理服务 │ │ │ │ │ │ │ │ │ └── user/ # 用户管理 │ │ │ │ ├── user.entity.ts # User：用户实体（TypeORM） │ │ │ │ └── user.module.ts # User 模块配置 │ │ │ │ │ │ │ ├── tenant/ # 多租户支持 │ │ │ │ └── tenant.middleware.ts # TenantMiddleware：多租户中间件，自动注入租户ID │ │ │ │ │ │ │ ├── task-center/ # 任务中心（待开发） │ │ │ │ └── task-center.module.ts # TaskCenter 模块占位（BullMQ 异步任务） │ │ │ │ │ │ │ └── system/ # 系统配置（待开发） │ │ │ └── system.module.ts # System 模块占位 │ │ │ │ │ ├── business/ # ★ 教育业务层 │ │ │ ├── core/ # 核心通用逻辑 │ │ │ │ └── agents/ # 通用智能体实现 │ │ │ │ ├── universal.agent.ts # UniversalAgent：元数据驱动的通用 Agent │ │ │ │ └── universal.strategy.ts # UniversalStrategy：通用创建策略 │ │ │ │ │ │ │ └── education/ # 教育核心业务（待迁移） │ │ │ ├── education.module.ts # Education 根模块 │ │ │ │ │ │ │ ├── agents/ # 业务 Agent 实现 │ │ │ │ ├── teacher/ # 教师 Agent（✅ 已实现） │ │ │ │ │ ├── teacher.agent.ts # TeacherAgent：教师 Agent 核心逻辑 │ │ │ │ │ ├── teacher.factory.ts # TeacherAgentFactory：工厂模式创建 Agent │ │ │ │ │ └── teacher.config.ts # TeacherConfig：教师 Agent 配置（System Prompt 等） │ │ │ │ │ │ │ │ │ ├── tutor/ # 辅导 Agent（🔲 占位） │ │ │ │ │ └── README.md # 占位说明文档 │ │ │ │ │ │ │ │ │ ├── homework/ # 作业 Agent（🔲 占位） │ │ │ │ │ └── README.md # 占位说明文档 │ │ │ │ │ │ │ │ │ ├── evaluate/ # 评估 Agent（🔲 占位） │ │ │ │ │ └── README.md # 占位说明文档 │ │ │ │ │ │ │ │ │ ├── knowledge/ # 知识 Agent（🔲 占位） │ │ │ │ │ └── README.md # 占位说明文档 │ │ │ │ │ │ │ │ │ └── tool-agents/ # 工具 Agent（🔲 占位） │ │ │ │ └── README.md # 占位说明文档 │ │ │ │ │ │ │ ├── course/ # 课程管理（待开发） │ │ │ │ └── course.module.ts # Course 模块占位 │ │ │ │ │ │ │ ├── homework/ # 作业管理（待开发） │ │ │ │ └── homework.module.ts # Homework 模块占位 │ │ │ │ │ │ │ └── study/ # 学习管理（待开发） │ │ │ └── study.module.ts # Study 模块占位 │ │ │ │ │ ├── common/ # 公共模块 │ │ │ └── logger/ # 日志模块 │ │ │ ├── app.logger.ts # AppLogger：自定义日志服务（带颜色、级别） │ │ │ └── logger.module.ts # Logger 模块配置 │ │ │ ├── database/ # SQL 初始化脚本 │ │ └── init.sql # 数据库初始化脚本（建表、初始数据） │ ├── .env # 环境变量配置（数据库、API Key 等） │ ├── package.json # 依赖管理 │ ├── tsconfig.json # TypeScript 配置 │ └── nest-cli.json # NestJS CLI 配置 │ ├── edu-multi-agent-web/ # 🎨 前端工程 │ ├── src/ │ │ ├── main.ts # 应用入口 │ │ ├── App.vue # 根组件 │ │ ├── api/ # API 请求封装 │ │ │ └── request.ts # Axios 封装 + 拦截器 │ │ ├── components/ # 组件 │ │ │ ├── ai/ # AI 核心组件 │ │ │ ├── business/ # 业务组件（空） │ │ │ └── common/ # 通用组件（空） │ │ ├── composables/ # 组合式函数 │ │ │ └── useStreamChat.ts # 流式对话逻辑 │ │ ├── modules/ # 功能模块 │ │ │ ├── ai/ # AI 模块 │ │ │ │ ├── api/ # API 调用（5个文件） │ │ │ │ └── views/ # 页面（4个文件） │ │ │ ├── education/ # 教育模块 │ │ │ │ ├── course/ # 课程（空） │ │ │ │ ├── homework/ # 作业（空） │ │ │ │ ├── knowledge/ # 知识库（空） │ │ │ │ ├── student/ # 学生（空） │ │ │ │ └── teacher/ # 教师（空） │ │ │ └── system/ # 系统模块 │ │ │ ├── auth/ # 认证（空） │ │ │ ├── settings/ # 设置（空） │ │ │ ├── task-center/ # 任务中心（空） │ │ │ └── user/ # 用户（空） │ │ ├── views/ # 页面（旧版，部分已迁移到 modules） │ │ │ ├── login/ # ✅ 登录页 │ │ │ ├── dashboard/ # ✅ 控制台 │ │ │ ├── settings/ # ✅ 设置页 │ │ │ ├── agent/ # ✅ Agent 管理 │ │ │ ├── course/ # 🔲 课程页 │ │ │ ├── homework/ # 🔲 作业页 │ │ │ ├── knowledge/ # 🔲 知识库页 │ │ │ ├── study/ # 🔲 学情页 │ │ │ └── task-center/ # 🔲 任务中心页 │ │ ├── router/ # 路由配置 │ │ ├── store/ # Pinia 状态 │ │ │ └── agent.ts # Agent 状态 │ │ ├── hooks/ # 组合式函数（空） │ │ ├── layouts/ # 布局组件 │ │ │ └── MainLayout.vue # 主布局组件 │ │ ├── types/ # 类型定义（空） │ │ └── utils/ # 工具函数（空） │ ├── vite.config.ts # Vite 配置（含代理） │ ├── package.json │ └── tsconfig.json │ ├── start-all.bat # 一键启动脚本 ├── stop-all.bat # 一键停止脚本 └── README.md # 项目说明（本文档） ``` --- ## 📦 模块详解 ### 1. AI 核心能力层 (`ai/`) **职责**：提供 AI 技术基础设施，无业务依赖，可被任何业务复用 #### 1.1 Agent 框架 (`agent-framework/`) - `base-agent.ts` - BaseAgent 抽象基类 - `agent-provider.interface.ts` - IAgentProvider：Agent 提供者接口（解耦关键） - `registry/` - Agent 注册表，管理所有 Agent 实例 - `supervisor/` - 监督者 Agent，协调多 Agent 协作 - `tokens.ts` - Token 定义（Symbol 标签系统） - `agent.controller.ts` - Agent HTTP 控制器 - `agent.module.ts` - Agent 模块配置 #### 1.2 LLM 模型服务 (`llms/`) - `llm.adapter.ts` - LLMAdapter 适配器接口 - `llm.service.ts` - LLMService：统一管理模型调用 - `llm.controller.ts` - LLM HTTP 控制器 - `llm-config.controller.ts` - API Key 动态配置控制器 - `adapters/` - 模型适配器实现 - `deepseek.adapter.ts` - DeepSeek 模型适配器 - `qwen.adapter.ts` - 通义千问模型适配器 - `yi.adapter.ts` - 零一万物模型适配器 - `openai.adapter.ts` - OpenAI 模型适配器 - `llm.module.ts` - LLM 模块配置 #### 1.3 能力插件系统 (`capabilities/`) - `tools/` - 工具调用能力 - `tool.interface.ts` - ITool 接口定义 - `tool.registry.ts` - 工具注册表 - `impl/` - 具体工具实现（CalculatorTool 等） - `capability.interface.ts` - IAgentCapability 接口 - `capability.registry.ts` - 能力注册表 - `capabilities.module.ts` - 能力模块配置 #### 1.4 对话会话 (`chat/`) - `chat-message.entity.ts` - 聊天消息实体 - `chat-session.entity.ts` - 聊天会话实体 - `chat.controller.ts` - 聊天控制器 - `chat.service.ts` - 聊天服务 - `chat.module.ts` - 聊天模块 #### 1.5 记忆系统 (`memory/`) - `memory.base.ts` - BaseMemory 抽象基类 - `window-memory.ts` - WindowMemory：滑动窗口记忆实现 - `memory.module.ts` - Memory 模块配置 #### 1.6 多模态处理 (`multimodal/`) - `multimodal.module.ts` - Multimodal 模块占位（待开发） --- ### 2. 系统支撑层 (`system/`) **职责**：提供跨业务的通用服务 #### 2.1 身份认证 (`identity/`) - `auth/` - 认证授权 - `auth.controller.ts` - 登录/登出接口 - `auth.service.ts` - JWT 签发、密码验证 - `jwt.strategy.ts` - JWT 策略 - `jwt-auth.guard.ts` - JWT 守卫 - `token.service.ts` - Token 服务 - `auth.module.ts` - 认证模块 - `user/` - 用户管理 - `user.entity.ts` - 用户实体 - `user.module.ts` - 用户模块 #### 2.2 多租户 (`tenant/`) - `tenant.middleware.ts` - 多租户中间件，自动注入租户ID #### 2.3 任务中心 (`task-center/`) - `task-center.module.ts` - TaskCenter 模块（待开发） #### 2.4 系统配置 (`system/`) - `system.module.ts` - System 模块（待开发） --- ### 3. 教育业务层 (`business/education/`) **职责**：实现教育领域的业务逻辑 #### 3.1 业务 Agent (`agents/`) - `teacher/` - 教师 Agent（✅ 已实现） - `teacher.agent.ts` - TeacherAgent 实现 - `teacher.factory.ts` - TeacherAgent 工厂 - `teacher.config.ts` - TeacherAgent 配置 - `tutor/` - 辅导 Agent（🔲 占位） - `homework/` - 作业 Agent（🔲 占位） - `evaluate/` - 评估 Agent（🔲 占位） - `knowledge/` - 知识 Agent（🔲 占位） - `tool-agents/` - 工具 Agent（🔲 占位） #### 3.2 课程管理 (`course/`) - `course.module.ts` - Course 模块（待开发） #### 3.3 作业管理 (`homework/`) - `homework.module.ts` - Homework 模块（待开发） #### 3.4 学习管理 (`study/`) - `study.module.ts` - Study 模块（待开发） --- ## 🔄 数据流总览 ### 1. 用户认证流 ``` 前端 LoginView → POST /api/v1/auth/login ↓ 后端 AuthController → AuthService.login() ↓ TypeORM 查询 MySQL → 获取用户记录 ↓ bcrypt.compare() → 验证密码 ↓ jwt.sign() → 生成 Token ↓ 返回 Token → 前端 localStorage 存储 ↓ 后续请求 Header: Authorization: Bearer {token} ``` ### 2. 智能体对话流 ``` 前端 AgentChatView → POST /api/v1/agent/execute { input: "你好", agentName: "math-teacher" } ↓ AgentController.execute() ↓ AgentRegistry.getAgent('math-teacher') ↓ TeacherAgent.execute(input, context) ↓ WindowMemory.addMessage('user', input) WindowMemory.getContextMessages(4000, systemPrompt) ↓ ModelService.generate(context) ↓ DeepSeekAdapter.generate() → 调用 DeepSeek API ↓ WindowMemory.addMessage('assistant', response) ↓ 返回 { content, metadata: { memorySize, memoryTokens } } ``` ### 3. 流式对话流 ``` 前端 AgentChatView → POST /api/v1/agent/execute-stream ↓ AgentController.executeStream() ↓ res.setHeader('Content-Type', 'text/event-stream') ↓ for await (const chunk of agent.executeStream()) ↓ res.write(`data: ${JSON.stringify({ data: chunk })}\n\n`) ↓ 前端 ReadableStream 逐块接收 ↓ 逐字更新 UI → 打字机效果 ``` --- ## ⚙️ 环境配置 ### 后端 `.env` 文件 ```env # 应用配置 PORT=3000 API_PREFIX=/api/v1 NODE_ENV=development # 数据库（云端 MySQL） DB_HOST=101.133.128.1 DB_PORT=3306 DB_USERNAME=root DB_PASSWORD=your_password DB_DATABASE=education_ai DB_SYNCHRONIZE=true # DeepSeek API DEEPSEEK_API_KEY=sk-xxx # DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 (默认) # 前端地址（CORS） FRONTEND_URL=http://localhost:5173 # 多租户 DEFAULT_TENANT_ID=1 TENANT_MODE=true # Redis（BullMQ） BULLMQ_REDIS_URL=redis://localhost:6379 ``` ### 前端 Vite 代理 已在 `vite.config.ts` 中配置代理： - `/api` → `http://localhost:3000` --- ## 📖 API 文档 启动后端后访问: http://localhost:3000/api/docs ### 主要接口 #### 认证接口 (`/api/v1/auth`) - `POST /login` - 用户登录 - `POST /change-password` - 修改密码 #### 模型接口 (`/api/v1/model`) - `GET /available` - 获取可用模型列表 - `GET /current` - 获取当前模型 - `POST /generate` - 同步生成 - `POST /generate-stream` - 流式生成（SSE） - `POST /switch` - 切换模型 #### 模型配置接口 (`/api/v1/model-config`) - `POST /update-key` - 动态更新 API Key - `GET /status` - 获取配置状态 - `POST /test-key` - 测试 API Key #### Agent 接口 (`/api/v1/agent`) - `GET /list` - 获取智能体列表 - `POST /execute` - 执行 Agent（同步） - `POST /execute-stream` - 执行 Agent（流式） - `GET /memory` - 获取 Agent 记忆 #### 聊天接口 (`/api/v1/chat`) - `GET /sessions` - 获取会话列表 - `POST /session` - 创建或获取会话 - `GET /messages` - 获取会话消息 - `POST /message` - 发送消息 - `POST /message-stream` - 发送消息（流式） - `POST /clear` - 清空会话 --- ## 💻 开发指南 ### 添加新智能体 1. 在 `business/education/agents/` 创建新目录（如 `tutor/`） 2. 创建 `tutor.agent.ts`，继承 `BaseAgent` 3. 实现 `getName()`、`getDescription()`、`execute()` 方法 4. 覆盖 `initialize()` 初始化记忆系统 5. 创建 `tutor.factory.ts`，实现 `IAgentProvider` 接口 6. 在 `AgentModule.providers` 中注册 Factory 7. AgentRegistry 自动发现并注册 ### 添加新模型 1. 在 `ai/llms/adapters/` 创建新适配器（如 `claude.adapter.ts`） 2. 实现 `LlmAdapter` 接口 3. 在 `ModelModule.providers` 中注册 4. ModelService 自动纳入可用模型列表 ### 添加工具 1. 在 `ai/capabilities/tools/impl/` 创建新工具（如 `search.tool.ts`） 2. 实现 `ITool` 接口 3. 在 `ToolRegistry` 中注册 4. 配置到对应 Agent 的能力列表中 ### 添加新能力 1. 创建能力类，实现 `IAgentCapability` 接口 2. 实现 `preprocess()` 或 `postprocess()` 方法 3. 在 `CapabilityRegistry` 中注册 4. 配置到对应 Agent --- ## 👤 默认账号 - **用户名**: `admin` - **密码**: `admin123` - **租户ID**: `1`（自动填充，无需输入） --- ## ⚠️ 注意事项 1. **API密钥**: `.env` 中配置有效的 DeepSeek API Key 2. **数据库**: 已配置云端 MySQL，无需本地 Docker 3. **流式输出**: 使用 SSE 协议，前端实时接收逐字响应 4. **CORS**: 后端已配置允许前端跨域 5. **多租户**: 中间件自动注入租户ID，无需手动传递 6. **记忆系统**: Agent 重启后会丢失内存中的记忆，需从数据库加载历史 --- ## 📄 许可证 UNLICENSED --- *最后更新：2026-04-15* *作者：WD* *项目地址：https://github.com/yourusername/education-ai*