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 | ✅ |
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 | 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 纯色占位图 |
perceive → decide → dispatch → aggregate
│ │ │ │
▼ ▼ ▼ ▼
LLM 意图解析 DAG 构建 拓扑执行 汇总返回
(专用Prompt) (Kahn算法) (按序调Agent) (收集toSummary)
| 事件 | 含义 | 前端渲染 |
|---|---|---|
thought |
思考/规划 | AgentThoughtCard(黄色灯泡) |
action |
工具调用开始 | AgentActionCard(蓝色齿轮) |
observation |
工具调用结果 | AgentActionCard(绿色对勾) |
asset |
新生成资产 | 触发 Studio 面板刷新 |
done |
任务完成 | 绿色完成卡片 |
error |
错误 | 红色错误卡片 |
| 端点 | 方法 | 说明 |
|---|---|---|
/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 代码。
