# contex-ai

**Repository Path**: lijunnew/contex-ai

## Basic Information

- **Project Name**: contex-ai
- **Description**: 基于Ruoyi v3.9.2和hermes理念，设计的适合B端快速接入AI的平台
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-09-19
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CortexAI — 企业级 AI Agent 开发平台

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.5.x-brightgreen.svg" alt="Spring Boot">
  <img src="https://img.shields.io/badge/Vue-3.5.26-blue.svg" alt="Vue 3">
  <img src="https://img.shields.io/badge/Element%20Plus-2.13.1-409EFF.svg" alt="Element Plus">
  <img src="https://img.shields.io/badge/JDK-17+-orange.svg" alt="JDK">
  <img src="https://img.shields.io/badge/LangChain4j-0.36.2-purple.svg" alt="LangChain4j">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
</p>

<p align="center">
  基于若依框架构建的全栈 AI Agent 平台，提供完整的 Agent 运行时引擎、插件生态、知识库 RAG 和技能包管理能力，
  支持 SSE 流式响应、MCP 协议、工具审批、语音交互和嵌入式小窗。
</p>

## 界面展示
![img.png](img.png)
![img_1.png](img_1.png)
![img_4.png](img_4.png)
---

## 📋 目录

- [项目简介](#-项目简介)
- [核心特性](#-核心特性)
- [技术架构](#-技术架构)
- [项目结构](#-项目结构)
- [快速开始](#-快速开始)
- [功能详解](#-功能详解)
  - [Agent 运行时引擎](#1-agent-运行时引擎)
  - [插件生态系统](#2-插件生态系统)
  - [知识库系统](#3-知识库系统)
  - [技能包管理](#4-技能包管理)
  - [语音交互](#5-语音交互)
  - [嵌入式小窗](#6-嵌入式小窗)
  - [MCP 协议支持](#7-mcp-协议支持)
  - [工具审批机制](#8-工具审批机制)
  - [待办任务系统](#9-待办任务系统)
- [配置说明](#-配置说明)
- [部署指南](#-部署指南)
- [项目截图](#-项目截图)
- [许可证](#-许可证)

---

## 📖 项目简介

CortexAI 是一个基于 **若依（RuoYi）** 框架二次开发的企业级 AI Agent 智能对话平台。项目核心参考了 Hermes Agent 的
`conversation_loop` 设计理念，在国内开源生态基础上构建了一套完整的 Agent 运行时，具备以下能力：

- **开箱即用**：内置 13 个插件、完整的前端管理后台、SQL 一键初始化
- **模型无关**：兼容所有 OpenAI 协议供应商（OpenAI、Claude、Qwen、DeepSeek、本地 Ollama 等）
- **工具调用完整**：支持多工具并发执行、工具去重、名称模糊修复、截断重试
- **流式响应**：SSE 实时输出，`<think>` 块自动剥离，前端打字机效果
- **企业安全**：工具审批三级管控、API Key 多租户隔离、RBAC 权限体系

> 默认账号：`admin / admin123`
> 后端默认端口：`8080`，前端默认端口：`80`

---

## ✨ 核心特性

### 🤖 Agent 运行时引擎

- **ConversationLoop**：完整的多轮对话循环，最大迭代次数可配置（默认 20 次），支持预算控制
- **SSE 流式响应**：基于 Server-Sent Events 的实时输出，支持内容增量推送、工具执行状态推送
- **上下文压缩**：自适应压缩阈值（可用上下文的 70%），压缩后工作上下文独立于历史记录
- **错误分类与重试**：ErrorClassifier 自动分类 LLM 错误，支持 jitter backoff 退避重试（最多 3 次）
- **Fallback 模型**：主模型失败后自动切换到备用模型列表
- **会话管理**：会话隔离、并行处理、用户打断、标题 AI 自动生成
- **消息队列**：新消息自动排队，用户可手动中断当前对话
- **图片处理**：多模态消息支持，自动识别 Provider 不支持图片时退回纯文本
- **Token 追踪**：实时统计 prompt/completion tokens，上下文使用百分比前端实时展示
- **执行日志**：完整链路追踪，包含每轮迭代、工具调用参数、LLM 响应详情

### 🔌 插件生态系统

- **13 个内置插件**：涵盖网络搜索、文件管理、代码执行、终端命令、数据库查询、知识库检索等
- **MCP 协议**：兼容 Model Context Protocol，通过 stdio/SSE 接入海量 MCP 生态插件
- **工具审批**：三种审批模式（always / auto / never），高风险操作走人工审批流
- **插件环境变量**：每个插件独立配置 API Key 等环境变量，安全隔离

### 📚 知识库（RAG）

- **向量检索**：基于 Milvus 的 Embedding + 相似度搜索
- **Rerank**：LangChain4j 集成重排序，精排检索结果
- **多格式文档**：PDF、Word、Excel、TXT、Markdown，Apache Tika 统一解析
- **召回测试**：内置召回测试工具，可验证知识库检索效果
- **权限隔离**：按业务系统和用户隔离知识库访问

### 🎯 技能包管理

- **层级结构**：技能包 → 技能文件（.md / .py / .js / .json / .txt）
- **双层权限**：全局技能（管理员维护）+ 个人技能（用户自管理）
- **拉取模型（Pull Model）**：系统提示词只注入技能索引，按需 `skill_read` 读取全文，降低 token 消耗
- **AI 自学习**：Agent 执行复杂任务后主动询问是否保存为技能，发现技能过时立即 patch

### 🎙️ 语音交互

- **ASR**：Sherpa-ONNX 离线语音识别，支持 SenseVoice 中英日韩粤多语言模型
- **TTS**：VITS 语音合成，多音色支持
- **跨平台**：Windows / Linux 原生库，随 Maven 依赖自动加载（见 `tts/` 目录）

### 🪟 嵌入式小窗（Widget）

- **零依赖**：纯 JavaScript 实现，一行 `<script>` 标签即可嵌入任意页面
- **Shadow DOM 隔离**：样式完全不污染宿主页面
- **API Key 认证**：外部系统通过 API Key 安全接入，权限独立控制
- **响应式**：完整移动端适配

### 🔐 企业级安全

- **多租户隔离**：业务系统（businessSystem）维度数据隔离
- **RBAC 权限**：继承若依完整的角色-权限-菜单体系
- **JWT 认证**：无状态 Token，Redis 存储在线会话
- **操作审计**：全量操作日志记录

---

## 🏗️ 技术架构

### 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.5.x | 核心框架 |
| Spring Security | 3.x | 认证授权 |
| MyBatis | 3.0.5 | ORM 持久层 |
| Druid | 1.2.28 | 数据库连接池 + 监控 |
| Redis | 7.x | 缓存 / Session / SSE 广播 |
| PostgreSQL | 13+ | 主关系数据库 |
| Milvus | 2.3+ | 向量数据库（知识库） |
| LangChain4j | 0.36.2 | AI 编排框架（Embedding / Rerank） |
| Sherpa-ONNX | 1.13.3 | 离线语音识别与合成 |
| Apache Tika | 2.9.2 | 文档内容解析 |
| FastJson2 | 2.0.62 | JSON 序列化 |
| SpringDoc | 2.8.17 | OpenAPI 文档 |
| JWT | 0.9.1 | Token 认证 |
| Quartz | 2.x | 定时任务调度 |

### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | 3.5.26 | 渐进式 UI 框架 |
| Vite | 6.4.1 | 构建工具 |
| Element Plus | 2.13.1 | UI 组件库 |
| Pinia | 3.0.4 | 状态管理 |
| Vue Router | 4.6.4 | 路由管理 |
| Axios | 1.13.2 | HTTP 客户端 |
| ECharts | 5.6.0 | 数据可视化（Dashboard） |
| Monaco Editor | 0.52.2 | 代码编辑器（技能文件编辑） |
| md-editor-v3 | 4.20.0 | Markdown 编辑器 |
| markdown-it | 14.0.0 | Markdown 渲染 |
| highlight.js | 11.11.1 | 代码高亮 |
| @vue-office | - | Office 文档在线预览 |

---

## 📁 项目结构

```
CortexAI/
├── cortex-admin/                   # 启动模块（Spring Boot 入口）
│   └── src/main/resources/
│       ├── application.yml         # 主配置（Redis、端口、文件上传等）
│       ├── application-druid.yml   # 数据源配置
│       └── logback.xml             # 日志配置
│
├── cortex-common/                  # 公共工具模块
│   └── src/main/java/com/cortex/
│       ├── common/annotation/      # 自定义注解（日志、数据权限等）
│       ├── common/core/            # 核心基类（BaseEntity、AjaxResult、Page）
│       ├── common/exception/       # 统一异常体系
│       ├── common/utils/           # 工具类集合
│       └── common/xss/            # XSS 防护
│
├── cortex-framework/               # 框架支撑模块
│   └── src/main/java/com/cortex/
│       ├── framework/aspectj/      # AOP 切面（权限、日志、数据隔离）
│       ├── framework/config/       # Spring 全局配置
│       ├── framework/security/     # Spring Security 配置
│       └── framework/web/          # Web 层过滤器、拦截器
│
├── cortex-system/                  # 核心业务模块（最重要）
│   └── src/main/java/com/cortex/
│       │
│       ├── agent/                  # Agent 核心领域
│       │   ├── domain/             # 实体类
│       │   │   ├── AiAgent.java              # Agent 配置实体
│       │   │   ├── AiAgentSession.java       # 会话实体
│       │   │   ├── AiAgentMessage.java       # 消息实体
│       │   │   ├── AiAgentExecutionLog.java  # 执行日志
│       │   │   ├── AiAgentMemory.java        # 跨会话记忆
│       │   │   ├── AiAgentFile.java          # 上传文件
│       │   │   ├── AiAgentPlugin.java        # Agent-插件关联
│       │   │   ├── AiAgentSkill.java         # Agent-技能关联
│       │   │   ├── AiAgentDelegation.java    # Agent 委派配置
│       │   │   ├── AiAgentApprovalGrant.java # 审批授权
│       │   │   ├── AiTaskPlan.java           # 待办任务计划
│       │   │   └── AiTaskStep.java           # 待办任务步骤
│       │   │
│       │   ├── runtime/            # Agent 运行时引擎
│       │   │   ├── AgentRuntime.java         # 运行时入口
│       │   │   ├── ApiRateLimiter.java       # API 速率限制
│       │   │   ├── approval/                 # 工具审批流
│       │   │   ├── context/                  # 运行时上下文
│       │   │   │   ├── AgentSessionContext   # 会话级上下文
│       │   │   │   └── RuntimeContextHolder  # ThreadLocal 上下文
│       │   │   ├── event/                    # SSE 事件分发
│       │   │   ├── file/                     # 文件索引与处理
│       │   │   ├── llm/                      # LLM 客户端
│       │   │   │   ├── OpenAiCompatibleClient # HTTP 调用
│       │   │   │   ├── LlmRequest / Response  # 请求/响应模型
│       │   │   │   └── ErrorClassifier        # 错误分类重试
│       │   │   ├── loop/                     # 对话循环核心
│       │   │   │   ├── ConversationLoop      # 主循环（最核心）
│       │   │   │   ├── ContextCompressor     # 上下文压缩
│       │   │   │   ├── MessageSanitizer      # 消息清理
│       │   │   │   ├── ToolCallValidator     # 工具调用校验
│       │   │   │   ├── ThinkBlockStripper    # <think> 块剥离
│       │   │   │   ├── AnsiStripper          # ANSI 颜色码清理
│       │   │   │   └── BackgroundSkillReview # 异步技能复盘
│       │   │   ├── model/                    # 数据模型
│       │   │   │   ├── ChatMessage           # 消息模型（含多模态）
│       │   │   │   ├── SSEEvent              # SSE 事件模型
│       │   │   │   ├── AgentRunRequest       # 运行请求
│       │   │   │   └── ToolCallResult        # 工具调用结果
│       │   │   ├── prompt/                   # Prompt 构建
│       │   │   │   ├── PromptBuilder         # 系统提示词构建器
│       │   │   │   └── AgentConfigLoader     # 模型选择与配置加载
│       │   │   └── tool/                     # 工具执行器
│       │   │       └── ToolExecutor          # 并发工具执行
│       │   │
│       │   └── service/            # Agent 业务服务
│       │       ├── IAiAgentService
│       │       ├── IAgentRuntimeService
│       │       ├── IAiAgentFileService
│       │       └── ITaskPlanService
│       │
│       ├── plugin/                 # 插件系统
│       │   ├── builtin/            # 内置插件框架
│       │   │   ├── IBuiltinPlugin.java       # 插件接口
│       │   │   ├── PluginInfo.java           # 插件元信息
│       │   │   ├── ToolDefinition.java       # 工具定义
│       │   │   ├── ToolResult.java           # 工具返回
│       │   │   └── impl/                     # 13 个内置插件实现
│       │   │       ├── WebSearchPlugin       # 网络搜索（多引擎）
│       │   │       ├── SkillManagerPlugin    # 技能管理（3 工具）
│       │   │       ├── TaskPlanManagerPlugin # 待办任务（5 工具）
│       │   │       ├── KnowledgeSearchPlugin # 知识库检索
│       │   │       ├── DifyKnowledgePlugin   # Dify 知识库接入
│       │   │       ├── FileManagerPlugin     # 文件管理
│       │   │       ├── FileOperationPlugin   # 文件读写操作
│       │   │       ├── CodeExecutionPlugin   # 代码执行
│       │   │       ├── TerminalPlugin        # 终端命令
│       │   │       ├── DatabaseQueryPlugin   # 数据库查询
│       │   │       ├── ScheduledTaskPlugin   # 定时任务管理
│       │   │       ├── SubAgentPlugin        # Sub-Agent 委派
│       │   │       └── VoiceManagerPlugin    # 语音交互
│       │   ├── mcp/                # MCP 协议实现
│       │   │   ├── McpClient         # MCP 客户端
│       │   │   ├── McpProcessManager # 进程生命周期管理
│       │   │   └── McpSessionManager # 会话管理
│       │   └── service/            # 插件业务服务
│       │
│       ├── knowledge/              # 知识库（RAG）
│       │   ├── domain/             # 知识库、文档、分片实体
│       │   ├── rag/                # RAG 核心
│       │   │   ├── KnowledgeIngestService    # 文档入库
│       │   │   ├── KnowledgeSearchService    # 向量检索
│       │   │   ├── KnowledgeContextInjector  # 上下文注入
│       │   │   ├── KnowledgeRecallTestService # 召回测试
│       │   │   ├── MilvusStoreManager        # Milvus 管理
│       │   │   ├── EmbeddingModelFactory     # Embedding 模型工厂
│       │   │   └── RerankModelFactory        # Rerank 模型工厂
│       │   └── service/
│       │
│       ├── skill/                  # 技能包管理
│       │   ├── domain/SkillNode   # 技能节点（树形结构）
│       │   ├── service/
│       │   │   ├── ISkillCrudService   # 增删改查（带权限校验）
│       │   │   └── ISkillNodeService   # 树形查询
│       │   └── util/SkillMetadataParser # YAML frontmatter 解析
│       │
│       ├── supplier/               # AI 供应商与模型管理
│       │   ├── domain/
│       │   │   ├── AiSupplier    # 供应商（OpenAI/Claude/Qwen 等）
│       │   │   └── AiModel       # 模型（含 contextLength / maxTokens）
│       │   └── service/
│       │
│       └── system/                 # 若依系统模块（用户/角色/菜单等）
│
├── cortex-generator/               # 代码生成器模块
├── cortex-quartz/                  # 定时任务模块（Quartz）
│
├── Cortex-Vue3/                    # 前端（Vue 3 + Vite）
│   └── src/
│       ├── api/                    # 后端 API 请求
│       │   ├── agent/              # Agent / 文件 / 任务 API
│       │   ├── plugin/             # 插件 / 包 / 运行时 API
│       │   ├── runtime/            # 审批 / 执行日志 / 会话 API
│       │   ├── knowledge/          # 知识库 API
│       │   ├── skill/              # 技能 API
│       │   └── supplier/           # 供应商 / 模型 API
│       │
│       ├── views/                  # 页面视图
│       │   ├── agent/              # Agent 核心页面
│       │   │   ├── AgentChat.vue        # 主对话界面（最复杂）
│       │   │   ├── AgentChatPage.vue    # 独立对话页
│       │   │   ├── WidgetChat.vue       # 嵌入式小窗对话页
│       │   │   ├── index.vue            # Agent 管理列表
│       │   │   ├── components/          # 对话子组件
│       │   │   │   ├── ApprovalDialog   # 工具审批弹窗
│       │   │   │   ├── TaskPlanView     # 待办任务进度面板
│       │   │   │   ├── ExecLogDrawer    # 执行日志抽屉
│       │   │   │   └── FilePreview      # 文件预览
│       │   │   ├── approval/        # 审批管理页
│       │   │   ├── execlog/         # 执行日志页
│       │   │   ├── file/            # 文件管理页
│       │   │   └── session/         # 会话管理页
│       │   ├── knowledge/           # 知识库管理（文档上传/召回测试）
│       │   ├── skill/               # 技能包管理（树形编辑器）
│       │   ├── plugin/              # 插件管理（列表/包/运行时配置）
│       │   ├── supplier/            # 供应商与模型管理
│       │   └── system/              # 若依系统管理
│       │
│       ├── components/             # 公共组件
│       │   ├── DocViewer/          # 多格式文档预览
│       │   ├── Editor/             # 富文本编辑器
│       │   └── TreePanel/          # 通用树面板
│       │
│       └── store/modules/          # Pinia 状态
│           ├── user.js             # 用户信息
│           ├── permission.js       # 动态路由权限
│           └── settings.js         # 全局设置
│
├── sql/
│   ├── 结构.sql                    # 数据库表结构
│   └── 数据.sql                    # 初始化数据
│
├── docker/milvus/                  # Milvus Docker Compose 配置
│   ├── docker-compose.yml
│   └── .env.example
│
├── tts/                            # TTS 本地依赖
│   ├── sherpa-onnx-v1.13.3.jar
│   ├── sherpa-onnx-native-lib-win-x64-v1.13.3.jar
│   ├── sherpa-onnx-native-lib-linux-x64-v1.13.3.jar
│   └── models/
│       ├── sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17/  # ASR 模型
│       └── vits-zh-aishell3/                                     # TTS 模型
│
├── doc/                            # 详细功能文档（60+ 篇）
├── cortex.bat                      # Windows 启动脚本
├── cortex.sh                       # Linux 启动脚本
└── pom.xml                         # 父 POM（多模块管理）
```

---

## 🚀 快速开始

### 环境要求

| 组件 | 版本要求 | 说明 |
|------|----------|------|
| JDK | 17+ | 必须 |
| Node.js | 18+ | 前端构建 |
| PostgreSQL | 13+ | 主数据库 |
| Redis | 7.0+ | 缓存与会话 |
| Milvus | 2.3+ | 可选，知识库功能需要 |
| Maven | 3.8+ | 后端构建 |

---

### 一、启动后端

#### 1. 克隆仓库

```bash
git clone https://gitee.com/Alete/contex-ai.git
cd CortexAI
```

#### 2. 初始化数据库

```sql
-- 创建数据库
CREATE DATABASE cortex_vue WITH ENCODING 'UTF8';
```

```bash
# 导入表结构
psql -U postgres -d cortex_vue -f sql/结构.sql

# 导入初始数据（包含菜单、角色、用户等）
psql -U postgres -d cortex_vue -f sql/数据.sql
```

#### 3. 修改配置文件

编辑 `cortex-admin/src/main/resources/application-druid.yml`：

```yaml
spring:
  datasource:
    druid:
      master:
        url: jdbc:postgresql://localhost:5432/cortex_vue?useUnicode=true&characterEncoding=utf8
        username: postgres
        password: cortexai@2026
```

编辑 `cortex-admin/src/main/resources/application.yml` 中的 Redis 配置：

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: cortexai@2026
```

#### 4. 编译并启动

```bash
# 根目录下编译全部模块
mvn clean install -DskipTests

# 启动后端服务
cd cortex-admin
mvn spring-boot:run

# 或者使用脚本（先在根目录 mvn package）
cortex.bat          # Windows
./cortex.sh start   # Linux
```

访问后端：`http://localhost:8080`

> **API 文档**：启动后访问 `http://localhost:8080/swagger-ui/index.html`
> **Druid 监控**：`http://localhost:8080/druid/index.html`

---

### 二、启动前端

```bash
cd Cortex-Vue3

# 安装依赖
npm install

# 开发模式启动（默认 80 端口）
npm run dev

# 构建生产版本
npm run build:prod
```

访问前端：`http://localhost:80`
默认账号：`admin / admin123`

---

### 三、启动 Milvus（知识库功能）

如需使用知识库 RAG 功能，需要先启动 Milvus：

```bash
cd docker/milvus

# 复制环境变量配置
cp .env.example .env

# 一键启动（Milvus + MinIO + etcd）
docker-compose up -d

# 或使用脚本
start.bat       # Windows
./start.sh      # Linux
```

Milvus 默认端口 `19530`，管理界面（Attu）可选安装。

---

## 📚 功能详解

### 1. Agent 运行时引擎

Agent 运行时是整个平台的核心，位于 `cortex-system/src/main/java/com/cortex/agent/runtime/`。

#### ConversationLoop 对话循环

完整复刻了 Hermes `conversation_loop.py run_conversation()` 的设计，关键流程如下：

```
用户消息
    │
    ├─ 1. 添加用户消息到上下文，重置迭代预算
    │
    └─ 2. 主循环（while budget > 0 && iteration < maxIterations）
           │
           ├─ 2a. 消息清理（MessageSanitizer）
           │       - 孤儿 tool_result 消息清理
           │       - 角色交替校验
           │       - 代理字符清理
           │       - 历史图片剥离（只保留最新用户消息的图片）
           │
           ├─ 2b. 上下文压缩判断（估算 token > 可用上下文 70%）
           │       - 完整历史保留用于前端展示和持久化
           │       - 压缩后的工作上下文独立存储于 workingContext
           │
           ├─ 2c. 构建 LLM 请求（buildLlmRequest）
           │
           ├─ 2d. 重试循环调用 LLM（最多 3 次，jitter backoff）
           │       - 流式：SSE 实时推送 content delta
           │       - 非流式：直接返回
           │       - <think> 块实时过滤（StreamingThinkScrubber）
           │       - 图片 rejection 自动降级为纯文本
           │       - 主模型失败后切换 fallback 模型
           │
           ├─ 2e. finish_reason 分支处理
           │       - content_filter → 直接返回安全提示
           │       - length（截断）→ 工具调用截断重试 / 文本续写
           │       - stop → 继续处理
           │
           ├─ 2f. 工具调用处理（hasToolCalls）
           │       - 工具名去重（ToolCallValidator.deduplicate）
           │       - 工具名模糊匹配修复（Levenshtein 距离）
           │       - JSON 参数校验
           │       - 并发执行所有工具（ToolExecutor）
           │       - 审批检查（ApprovalChecker）
           │       - 工具结果回填到上下文
           │
           └─ 2g. 纯文本回复 → ThinkBlockStripper 最终剥离 → 返回
```

#### AgentSessionContext 会话上下文

每个会话拥有独立的 `AgentSessionContext`，包含：
- `messages`：完整消息历史（用于前端展示与持久化）
- `workingContext`：压缩后的 LLM 工作上下文（独立于完整历史）
- `iterationBudget`：迭代预算计数器
- `totalTokenUsage`：累计 token 用量
- `interruptRequested`：用户中断标志

#### PromptBuilder 系统提示词构建

`PromptBuilder` 按以下顺序组装系统提示词：

1. **用户上下文**：当前用户昵称、登录名、业务系统
2. **Agent 系统提示词**：管理员配置的 systemPrompt
3. **技能索引**（拉取模型）：仅注入技能包名称 + 技能名称 + 简短描述，不注入全文
4. **技能学习引导**：告诉 AI 何时保存、更新、删除技能（仅 skill-manager 插件启用时）
5. **待办任务引导**：告诉 AI 何时创建待办任务（仅 todo_task_manager 插件启用时）
6. **跨会话记忆**：用户的长期偏好与记忆内容

---

### 2. 插件生态系统

插件系统支持两类插件：**内置插件**（Java 实现）和 **MCP 插件**（外部进程）。

#### 内置插件一览

| 插件 | 插件 ID | 工具数量 | 说明 |
|------|---------|---------|------|
| 🔍 网络搜索 | `web-search` | 1 | 多引擎（Tavily/SerpAPI/Brave/SearXNG/DuckDuckGo/Vvhan） |
| 📚 技能管理 | `skill-manager` | 3 | skill_tree / skill_read / skill_manager |
| ✅ 待办任务 | `todo_task_manager` | 5 | 创建/查询/更新/取消/列表 |
| 📖 知识库检索 | `knowledge-search` | 2 | 向量检索 + Rerank |
| 🌊 Dify 知识库 | `dify-knowledge` | 1 | 接入 Dify 外部知识库 |
| 📁 文件管理 | `file-manager` | 多个 | 文件浏览、读写、搜索 |
| 📄 文件操作 | `file-operation` | 多个 | 文件创建、编辑、删除 |
| 💻 代码执行 | `code-execution` | 1 | 安全沙箱执行 Python/JS |
| 🖥️ 终端命令 | `terminal` | 1 | 执行 Shell 命令 |
| 🗄️ 数据库查询 | `database-query` | 1 | SQL 查询执行 |
| ⏰ 定时任务 | `scheduled-task` | 多个 | Quartz 定时任务管理 |
| 🤝 Sub-Agent | `sub-agent` | 2 | delegate_task / delegate_parallel |
| 🎙️ 语音管理 | `voice-manager` | 多个 | ASR / TTS 交互 |

#### 网络搜索插件（WebSearchPlugin）

搜索引擎优先级策略：
1. **智能优先级缓存**：记录上次成功的引擎，下次优先使用
2. **失败标记**：10 分钟内不重试已失败的引擎，10 分钟后自动重置
3. **降级顺序**：商业 API（Tavily/SerpAPI/Brave）→ 免费 API（SearXNG/DuckDuckGo/Vvhan）

配置插件环境变量（在插件管理页面的 "运行时配置" 中设置）：

```json
{
  "TAVILY_API_KEY": "tvly-xxx",
  "SERPAPI_KEY": "xxx",
  "BRAVE_SEARCH_API_KEY": "xxx"
}
```

> 无需任何 API Key 也可使用，SearXNG 公共实例和 DuckDuckGo 免费可用。

#### MCP 插件

MCP（Model Context Protocol）插件通过 `stdio` 子进程通信，支持所有标准 MCP 生态插件。

配置示例（在前端插件管理页面）：

```json
{
  "command": "uvx",
  "args": ["awslabs.aws-documentation-mcp-server@latest"],
  "env": {
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```

`McpProcessManager` 负责管理子进程生命周期，`McpSessionManager` 维护会话状态，`McpClient` 处理 JSON-RPC 通信。

---

### 3. 知识库系统

知识库基于 **RAG（检索增强生成）** 架构，核心组件位于 `cortex-system/src/main/java/com/cortex/knowledge/rag/`。

#### 文档处理流程

```
上传文档（PDF/Word/Excel/TXT/MD）
    │
    ├─ Apache Tika 解析文档内容
    ├─ 文本分片（Chunk）
    ├─ EmbeddingModelFactory 生成向量
    └─ MilvusStoreManager 存储到 Milvus
```

#### 检索流程

```
用户问题
    │
    ├─ EmbeddingModelFactory 生成查询向量
    ├─ Milvus 相似度搜索（Top-K）
    ├─ RerankModelFactory 重排序（精排）
    └─ KnowledgeContextInjector 注入到系统提示词
```

#### 知识库管理（前端）

- **知识库列表**：创建/删除知识库，查看文档数量与状态
- **文档管理**：上传文档、查看分片、删除文档
- **召回测试**：输入问题，查看检索结果和相关度分数，验证知识库质量
- **搜索测试**：直接测试向量检索效果

---

### 4. 技能包管理

技能包是 Agent 的知识载体，采用**拉取模型（Pull Model）**设计：系统提示词只注入轻量索引，按需读取全文。

#### 目录结构示意

```
技能包（全局/个人）
├── DESCRIPTION.md              # 技能包描述（可选）
├── Python爬虫技能.md            # 具体技能文件
├── 数据库查询模板.md
├── deploy-checklist.md
└── config.json
```

#### SKILL.md 标准格式

```markdown
---
description: 简短描述（约 80 字以内，显示在技能索引中）
tags: [python, crawler, http]
---

# 技能标题

## 触发条件
- 什么时候使用这个技能

## 步骤
1. 第一步（附命令）
2. 第二步
3. 验证步骤

## 常见陷阱
- 注意事项 1
- 注意事项 2
```

#### 三个核心工具

| 工具 | 用途 |
|------|------|
| `skill_tree` | 查看技能包树形结构（全局 + 个人），支持按节点 ID 获取子树 |
| `skill_read` | 读取指定 ID 技能文件的完整内容 |
| `skill_manager` | 管理个人技能（create / edit / delete） |

#### AI 自学习机制

当 `SkillManagerPlugin` 被授权后，`PromptBuilder` 会注入技能学习引导，Agent 会在以下场景主动保存技能：
- 复杂任务完成后（5 次以上工具调用）
- 修复了棘手错误
- 发现了非平凡的工作流程
- 用户明确说"记住这个"

`BackgroundSkillReview` 在每轮对话结束后异步运行，判断是否有需要更新的技能。

---

### 5. 语音交互

语音功能基于 **Sherpa-ONNX** 实现完全离线的语音识别和合成。

#### 依赖配置

TTS 相关 jar 包已放置在 `tts/` 目录，在父 `pom.xml` 中通过 `system` 依赖引入：

```xml
<dependency>
    <groupId>com.k2fsa.sherpa</groupId>
    <artifactId>sherpa-onnx</artifactId>
    <version>1.13.3</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/../tts/sherpa-onnx-v1.13.3.jar</systemPath>
</dependency>
```

#### 语音模型

| 模型 | 目录 | 用途 |
|------|------|------|
| SenseVoice | `tts/models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17/` | 多语言 ASR（中英日韩粤） |
| VITS-zh-aishell3 | `tts/models/vits-zh-aishell3/` | 中文 TTS 多音色 |

---

### 6. 嵌入式小窗

在任意 HTML 页面中嵌入 CortexAI 对话框，只需引入一段 JavaScript：

```html
<!-- 引入 Widget -->
<script src="http://your-server/widget/chat-widget.js"></script>
<script>
  CortexChat.init({
    serverUrl: 'http://your-server',
    apiKey: 'your-api-key',         // 在后台管理页面创建
    theme: 'light'                  // 主题
  });
</script>
```

Widget 通过 Shadow DOM 完全隔离样式，不影响宿主页面，支持暗色主题和移动端。

API Key 在**后台 → Agent 管理 → API Key 授权**中创建，每个 Key 绑定特定 Agent 和业务系统，支持启用/禁用。

---

### 7. MCP 协议支持

CortexAI 完整实现了 MCP（Model Context Protocol）规范，作为 MCP Host：

- **进程管理**：`McpProcessManager` 负责启动/停止 MCP 服务器进程（stdio 模式）
- **会话管理**：`McpSessionManager` 维护 MCP 会话生命周期
- **工具扫描**：`IMcpPackageScanService` 扫描 MCP 服务器提供的工具列表，自动注册到插件系统
- **调用代理**：`McpClient` 通过 JSON-RPC 2.0 协议转发工具调用请求

MCP 插件和内置插件在 Agent 运行时中统一处理，对 LLM 完全透明。

在前端**插件管理 → MCP 插件**页面可以：
- 添加 MCP 服务器配置（命令、参数、环境变量）
- 测试连接
- 查看扫描到的工具列表
- 分配给 Agent 使用

---

### 8. 工具审批机制

工具审批是企业安全的核心保障。在**Agent 管理 → 审批授权**中为每个插件配置审批模式：

| 模式 | 说明 |
|------|------|
| `never` | 从不需要审批（低风险工具，如搜索、读取） |
| `auto` | 系统自动判断（低风险自动通过，高风险人工审批） |
| `always` | 每次必须人工审批（高风险工具，如终端命令、数据库写入） |

审批流程：
1. Agent 发起工具调用 → `ApprovalChecker` 检查审批模式
2. 需要审批时 → SSE 推送 `approval_required` 事件到前端
3. 前端弹出 `ApprovalDialog`，展示工具名称和参数
4. 用户**批准** → 继续执行；用户**拒绝** → 返回拒绝原因给 Agent
5. 超时未处理 → 根据配置自动批准或拒绝

---

### 9. 待办任务系统

待办任务（TODO Task）是 Agent 将复杂任务拆解可视化的机制，由 `TaskPlanManagerPlugin` 提供。

#### 工作流程

```
用户提出复杂需求
    │
    ├─ Agent 判断需要多步骤执行
    ├─ 调用 create_todo_task，传入 title + steps 数组
    ├─ 后端创建 AiTaskPlan + AiTaskStep 记录
    ├─ SSE 推送 task_plan_created 事件到前端
    ├─ 前端 TaskPlanView 组件展示进度面板（输入框上方）
    ├─ 后台异步执行每个步骤
    │   ├─ 步骤开始 → status: running（转圈动画）
    │   ├─ 步骤完成 → status: completed（对号）
    │   └─ 步骤失败 → status: failed（错误信息）+ 停止后续
    └─ 全部完成 → status: completed
```

#### 五个工具

| 工具 | 用途 |
|------|------|
| `create_todo_task` | 创建待办任务并拆解步骤 |
| `get_todo_task` | 查询任务状态和进度（planId） |
| `update_todo_status` | 手动更新步骤状态 |
| `cancel_todo_task` | 取消进行中的任务 |
| `list_todo_tasks` | 列出当前会话的所有任务 |

---

## ⚙️ 配置说明

### 供应商与模型配置

进入**前端 → 供应商管理**，添加 AI 供应商：

```
供应商名称：OpenAI
API Base URL：https://api.openai.com/v1
API Key：sk-xxx
```

然后在**模型管理**中添加具体模型：

```
模型代码：gpt-4o
模型名称：GPT-4o
上下文长度：128000
最大输出 Token：16384
```

支持所有兼容 OpenAI 协议的服务商，包括：
- OpenAI、Azure OpenAI
- Anthropic Claude（通过代理层）
- 阿里云通义千问（Qwen）
- DeepSeek
- 本地 Ollama

### Agent 创建

在**Agent 管理**中创建 Agent，主要配置项：

| 配置项 | 说明 |
|--------|------|
| Agent 名称 | 显示名称 |
| Agent Code | 唯一标识符（用于 Sub-Agent 委派） |
| 系统提示词 | Agent 的角色和行为定义 |
| 绑定模型 | 选择使用的 AI 模型 |
| 最大迭代次数 | 单次对话最多调用 LLM 次数（默认 20） |
| 最大 Token | 每次回复的最大 token 数 |
| 温度 | 创造性参数（0~2） |
| 绑定插件 | 勾选允许使用的插件 |
| 绑定技能包 | 勾选可访问的技能包 |
| 绑定知识库 | 勾选可检索的知识库 |

### 多模型 Fallback

在 Agent 配置中可以设置备用模型列表。当主模型出现以下情况时自动切换：
- 速率限制（429）
- 服务不可用（503）
- 上下文溢出（context overflow）

### 环境变量配置

`application.yml` 中与 AI 功能相关的关键配置：

```yaml
cortex:
  # 文件上传路径
  profile: /home/cortex/uploadPath
  
  # 知识库配置
  knowledge:
    milvus:
      host: localhost
      port: 19530
      token: root:Milvus
    
  # 语音配置
  voice:
    asr:
      modelDir: ./tts/models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17
    tts:
      modelDir: ./tts/models/vits-zh-aishell3
```

---

## 🚢 部署指南

### 方式一：本地 JAR 部署

```bash
# 1. 打包（跳过测试）
mvn clean package -DskipTests

# 2. 运行
java -jar cortex-admin/target/cortex-admin.jar \
  --spring.profiles.active=prod \
  --server.port=8080
```

### 方式二：使用自带脚本

```bash
# Windows
cortex.bat start
cortex.bat stop
cortex.bat restart

# Linux
./cortex.sh start
./cortex.sh stop
./cortex.sh status
```

### 方式三：Docker（Milvus 套件）

```bash
# 仅启动基础设施（Milvus + Redis + PostgreSQL 可选）
cd docker/milvus
cp .env.example .env
# 编辑 .env 配置密码和端口
docker-compose up -d
```

`docker/milvus/docker-compose.yml` 包含：
- Milvus standalone
- MinIO（Milvus 对象存储）
- etcd（Milvus 元数据存储）
- Redis（可选，也可使用已有实例）

### 生产环境建议

- PostgreSQL 开启连接池（Druid 已配置，默认最大 50 连接）
- Redis 配置持久化（AOF 推荐）
- Milvus 建议独立部署，配置充足内存（向量索引内存占用较大）
- 前端 `nginx` 反向代理后端，配置 SSE 超时为 0（`proxy_read_timeout 0`）
- JVM 推荐 `-Xms2g -Xmx4g`，启用语音功能时适当增加

---