Skip to content
Duke486Public

About

Koi 戀,讓每個人都戀上學習

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

46 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Koi Learn

Koi Learn 项目预览

Koi Learn 是一个 Agent 驱动的 AI 学习工作台。用户创建学习 Project,在统一空间内完成资料收集、RAG 检索、AI 对话诊断、自主搜索和 11 种学习内容生成——从报告、思维导图到播客音频和讲课视频。系统核心是一个 Orchestrator 调度引擎,下辖 Chat/Search/Studio/Media 四个子 Agent,通过统一的 Agent<T,R> 接口协作。

核心理念

  • Project 隔离:每个学习项目拥有独立资料库、对话记录、RAG 向量和生成物。
  • Agent 调度:Orchestrator 接收用户意图 → LLM 解析 → DAG 拓扑排序 → 按依赖顺序调度子 Agent → 汇总结果,而非前端串行调用各 API。
  • 对话即入口:用户可以直接提问、接受学习诊断,也可以让 AI 生成课程讲解。Agent 模式支持自主规划和多步执行。
  • 资料驱动生成:上传资料、搜索结果和课程模板内容都会进入当前 Project 的 RAG 检索范围。
  • Studio 一键产出:右侧功能区统一生成报告、PPT、思维导图、音频、视频、测验、闪卡、信息图、表格等 11 种学习产物。
  • 降级优先设计:每个子 Agent 自带 fallback()——LLM 失败走模板、图片失败走占位图——上层永远能拿到结果。

系统架构

                    POST /api/agent/task
                           │
                           ▼
                 ┌─────────────────────┐
                 │  OrchestratorAgent   │  ← 核心调度器
                 │                     │
                 │ ① perceive(LLM解析)  │
                 │ ② decide(DAG构建)    │
                 │ ③ dispatch(拓扑调度)  │
                 │ ④ aggregate(汇总)    │
                 └──┬──────┬──────┬────┘
                    │      │      │
      ┌─────────────┘      │      └─────────────┐
      ▼                    ▼                    ▼
┌────────────┐    ┌──────────────┐    ┌────────────────┐
│ ChatAgent  │    │ SearchAgent  │    │  StudioAgent   │
│            │    │              │    │                │
│ RAG 对话   │    │ ES 语义搜索  │    │ 11 种内容生成  │
│ 流式 SSE   │    │ 关键词匹配   │    │ Report/MindMap │
│ 引用溯源   │    │ 项目内检索   │    │ Slides/Quiz/...│
└────────────┘    └──────────────┘    └───────┬────────┘
                                              │
                                     ┌────────▼────────┐
                                     │   MediaAgent     │
                                     │                  │
                                     │ 文生图(AI绘画)   │
                                     │ TTS 文字转语音   │
                                     │ ffmpeg 视频合成  │
                                     └──────────────────┘

仓库结构

koi-learn/
├── Backend/                    # Java Spring Boot 后端
│   └── src/main/java/com/koi/learn/
│       ├── agent/              # Agent 框架:统一接口、Orchestrator、注册中心、事件总线
│       │   ├── annotation/     #   @Agent 注解(元注解 @Component)
│       │   ├── chat/           #   ChatAgent 实现(RAG对话+流式SSE)
│       │   ├── controller/     #   AgentController(/api/agent/task + /chat)
│       │   ├── core/           #   Agent<T,R> 接口 + AgentContext/Plan/Meta/Config
│       │   ├── event/          #   AgentEventBus + SSE事件 + StepEvent sealed interface
│       │   ├── media/          #   MediaAgent 实现(文生图/TTS/视频合成)
│       │   ├── orchestration/  #   OrchestratorAgent + ExecutionPlan(DAG) + Prompt
│       │   ├── registry/       #   AgentRegistry 启动自动扫描
│       │   ├── search/         #   SearchAgent 实现(多源链式降级搜索)
│       │   └── studio/         #   StudioAgent 实现(11种内容生成)
│       ├── ai/                 # LLM 调用、Embedding、LocalFallback 降级
│       ├── auth/               # 登录、Token、用户上下文
│       ├── chat/               # 对话 Service + SSE 流式 + 会话管理
│       ├── common/             # 统一响应、异常处理、认证拦截器
│       ├── config/             # Security、S3 配置
│       ├── media/              # 媒体存储 Service
│       ├── project/            # Project CRUD + 课程模板 + 权限校验
│       ├── rag/                # 资料切块、Embedding、pgvector 检索
│       ├── search/             # 搜索 Service + Tavily/DuckDuckGo/Wikipedia Provider
│       └── studio/             # Studio 生成 Service + 后台任务 + 资产仓库
├── Frontend/                   # Vue 3 + Vuetify + Tailwind CSS 前端
│   └── src/
│       ├── components/
│       │   ├── chat/           # ChatPanel + AgentThoughtCard/AgentActionCard
│       │   ├── studio/         # AssetPreviewModal + 各类型渲染器
│       │   └── assets/         # MindMapViewer, QuizRunner, SlideViewer, etc.
│       ├── composables/        # useChat, useAgentChat, useAssets, useSources, useProjectTasks
│       ├── pages/              # LoginPage, ProjectsHome, WorkspacePage
│       ├── services/           # api, auth, chat, agent, sources, search, studio, tasks, projects
│       └── utils/              # asset-payload, project-view-model
├── Docs/                       # 16 篇设计与实施文档
├── Imgs/                       # README 与展示材料图片
├── .gitignore
└── README.md

技术栈

前端:Vue 3 · Vuetify 3 · Tailwind CSS · Axios · markdown-it · mermaid.js · Marp

后端:Java 17 · Spring Boot 3 · Spring AI · PostgreSQL · pgvector · 讯飞星火/TTS · ffmpeg

Agent 框架(自研):统一 Agent<T,R> 接口 · Orchestrator DAG 调度 · AgentRegistry 自动发现 · AgentEventBus 双通道事件总线 · SSE 六类事件流

快速启动

前端

cd Frontend
npm install
npm run dev        # http://localhost:5173

演示入口:

  • /login — Demo 登录
  • /projects — 项目首页(搜索、筛选、视图切换、新建)
  • /projects/{id} — 三栏工作台(来源 + 对话 + 创作)

前端将 /api 代理到 http://localhost:8080。

后端

cd Backend
# 1. 配置 PostgreSQL + pgvector,执行 src/main/resources/db/migration/V1__init.sql
# 2. 复制并编辑 application.example.yml → application.yml
# 3. 启动 Spring Boot
./mvnw spring-boot:run

功能地图

模块 实现方式 状态
对话式学习 RAG 混合检索(pgvector + 关键词 + 自动联网降级)+ SSE 流式逐 token 渲染 ✅
Agent 深度模式 Orchestrator LLM 意图解析 → DAG 拓扑调度子 Agent → SSE 事件流(thought/action/observation/asset/done/error) ✅
自主搜索 Tavily → DuckDuckGo → Wikipedia 三层链式降级,结果自动入库 ✅
RAG 资料库 PostgreSQL + pgvector,按 project_id 隔离,支持上传、勾选引用 ✅
课程讲解/报告 LLM 输出 Markdown,markdown-it 渲染 ✅
思维导图 LLM 输出 Mermaid mindmap,mermaid.js 渲染 ✅
PPT 演示 LLM 输出 Marp Markdown,前端翻页展示 ✅
测验/闪卡 LLM 输出 JSON,三层容错(正则→jsonrepair→LLM 重试) ✅
数据表格 LLM 输出 Markdown Table ✅
信息图 LLM 生成结构化信息图内容 ✅
播客音频 讲稿 LLM 生成 + TTS 合成 ✅
讲课视频 讲稿 + TTS + 生图 + 字幕 + ffmpeg 拼接 ✅
图片生成 AI 绘画 API + Java2D 纯色占位 fallback ✅

Agent 架构详情

统一接口

public interface Agent<T extends AgentInput, R extends AgentOutput> {
    boolean canHandle(AgentContext context);                          // 感知
    AgentPlan plan(AgentContext context, AgentConfig config);         // 决策
    R execute(T input, AgentPlan plan);                              // 执行
    R fallback(T input, AgentPlan plan, Exception error);            // 降级
    AgentMeta getMeta();                                             // 元信息
}

四个子 Agent

Agent Intents 核心能力 Fallback
ChatAgent CHAT, ANSWER, EXPLAIN RAG 检索 + LLM 对话 + SSE 流式 + 引用溯源 中文模板降级回答
SearchAgent SEARCH ES 语义搜索 + 项目内检索 + 三层 Provider 链式降级 空结果 + degraded
StudioAgent GENERATE 11 种内容生成(REPORT/MIND_MAP/SLIDES/QUIZ/FLASHCARDS/TABLE/IMAGE/AUDIO/VIDEO/INFOGRAPHIC) 模板降级
MediaAgent MEDIA 文生图/TTS/视频合成 Java2D 纯色占位图

Orchestrator 调度流程

perceive → decide → dispatch → aggregate
   │          │          │          │
   ▼          ▼          ▼          ▼
LLM 意图解析  DAG 构建   拓扑执行    汇总返回
(专用Prompt) (Kahn算法) (按序调Agent) (收集toSummary)

SSE 事件规范

事件 含义 前端渲染
thought 思考/规划 AgentThoughtCard(黄色灯泡)
action 工具调用开始 AgentActionCard(蓝色齿轮)
observation 工具调用结果 AgentActionCard(绿色对勾)
asset 新生成资产 触发 Studio 面板刷新
done 任务完成 绿色完成卡片
error 错误 红色错误卡片

API 端点

端点 方法 说明
/api/agent/task POST Orchestrator 统一入口(SSE 流式)
/api/agent/chat POST 直接对话(绕过 Orchestrator,SSE)
/api/chat/stream POST 传统流式对话(兼容)
/api/chat POST 传统非流式对话(兼容)
/api/search POST 独立搜索
/api/studio/* POST Studio 生成
/api/sources/* CRUD 资料管理
/api/projects/* CRUD 项目管理

文档导航

文档 内容
总体设计路线 产品定位、技术栈、MVP 范围
登录与 Project 认证、项目管理、课程模板
对话式学习 ChatAgent、RAG 检索、流式对话
自主搜索 SearchAgent、多源搜索 Provider
RAG 资料库 pgvector、chunk 策略、数据隔离
课程讲解与报告 Markdown 报告生成
思维导图 Mermaid mindmap 生成
PPT 演示 Marp 幻灯片生成与预览
测验与闪卡 JSON 测验 + 三层容错
数据表格 Markdown Table 生成
播客音频 讲稿 LLM + TTS 合成
讲课视频 多模态视频合成流程
Studio 前后端契约 资产类型、API 契约、UI 映射
Agent 架构改造实施记录 实际实施的 Agent 架构、文件清单、扩展指南
Agent 架构改造实施计划 改造计划、决策记录、设计方案
Agent 架构与面试纵深深挖 面试准备:概念层→架构层→实现层→边界处理→反思改进
pgvector 指南 pgvector 安装与使用说明

当前进度

  • 前端项目初始化 + 高保真 mock MVP(登录、项目首页、三栏工作台)
  • 后端 Spring Boot 工程(100+ Java 文件,完整 API)
  • pgvector 数据库初始化草案
  • 总体设计 + 各功能模块开发说明(16 篇文档)
  • Agent 架构改造:统一接口 + Orchestrator 调度 + 注册中心 + 事件总线 + 前端集成
  • 登录认证(Token + Session + Demo 用户)
  • Project CRUD + 课程模板 + 权限校验
  • RAG 入库与混合检索(向量 + 关键词 + 自动联网降级)
  • Chat SSE 流式对话 + 引用溯源
  • Search 三层 Provider 链式降级搜索
  • Studio 11 种内容生成 + 后台任务管理
  • Media 文生图 + TTS + 视频合成
  • 前端 Agent 模式切换 + 思考/动作卡片实时渲染

设计原则

  • 降级优先于重试:与其 retry 同一个失败的服务,不如换路走——SearchAgent 的三层 Provider 链式降级就是基于这个哲学。
  • 每个 Agent 自己兜底:上层 Orchestrator 不关心子 Agent 是否失败——每个 Agent 的 fallback() 永远返回结果。
  • 旧 API 保留,新老并行:新 /api/agent/task 与旧 /api/chat/stream 共存,不影响现有功能。
  • MVP 优先:能用 Markdown 展示的不用复杂文件,能前端渲染的不在后端生成图片,能 JSON 传递的不引入复杂协议。
  • 新增 Agent 只需注解 + 接口:@Agent 注解 + 实现 Agent<T,R> → 重启自动发现,不需改 Orchestrator 代码。

About

Koi 戀,讓每個人都戀上學習

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages