# Data-Assistant

**Repository Path**: lusasky0323/data-assistant

## Basic Information

- **Project Name**: Data-Assistant
- **Description**: chatbot--chatbot
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, 智能问数, chatbot

## README

# 海事监管AI助手

基于 **AgentScope Java 1.0.10** 框架构建的海事局指挥中心多智能体系统，用于海事监管、风险评估、应急响应等业务场景。

## 项目简介

本项目是一个多智能体协作系统，采用 **Supervisor ReActAgent 模式** 实现 LLM 智能路由和多轮协调：

| 智能体 | 核心职责 | 关联技能 |
|-------|---------|---------|
| **supervisor** | LLM 智能路由决策、多轮协调、任务分发 | - |
| **task** | 任务管理、任务查询、智能委托、个性化问候 | - |
| **general** | 智能问答、法律法规咨询、规范操作咨询等 | `maritime-law` |
| **risk** | 风险识别、风险分析、处置方案生成、处置执行等 | `risk-assessment` |
| **emergency** | 应急资源分析、应急方案生成、应急咨询等 | `emergency-response` |
| **review** | 历史风险/事故复盘总结、输出总结报告等 | `data-analysis` |

## 技术栈

- **Java 17**
- **Spring Boot 3.5.7**
- **AgentScope Java 1.0.10** (智能体框架核心)
- **Spring AI 1.1.2** (向量存储、文档处理、Embedding)
- **Spring WebFlux** (响应式编程)
- **Spring Data JPA** (数据持久化)
- **PostgreSQL + pgvector** (向量数据库)
- **Lombok**
- **OpenAI 兼容接口** (支持智谱 AI、阿里云通义千问等)

## 项目结构

```
src/main/java/com/huihai/ai/data_assistant/
├── config/                          # 配置类
│   ├── agentscope/                  # AgentScope 配置模块
│   │   ├── AgentFactory.java        # Agent 工厂（动态创建 Agent）
│   │   ├── AgentOrchestrationService.java # 智能体编排服务
│   │   ├── AgentScopeConfiguration.java  # 基础设施配置
│   │   ├── AgentSessionRegistry.java # Agent-Session 映射管理
│   │   ├── HumanInTheLoopManager.java # Human-in-the-Loop 管理
│   │   ├── ModelConfiguration.java  # AgentScope Model 配置
│   │   ├── SessionCleanupScheduler.java # 会话定时清理
│   │   ├── SessionMemoryManager.java # 会话级 Memory 管理
│   │   ├── StreamingHook.java       # 流式输出 Hook
│   │   ├── SubAgentSessionManager.java # SubAgent Session 管理
│   │   └── ToolkitConfiguration.java # Toolkit 工具配置
│   ├── ChatModelConfiguration.java  # Spring AI ChatModel 配置
│   ├── SkillConfiguration.java      # Skill 配置
│   └── MaxKBProperties.java         # MaxKB 知识库配置
├── common/                          # 通用模块
│   └── exception/                   # 异常处理
│       ├── BusinessException.java   # 业务异常基类
│       ├── ErrorCode.java           # 错误码枚举
│       └── GlobalExceptionHandler.java # 全局异常处理
├── controller/                      # 控制器
│   ├── ChatController.java          # 聊天接口控制器
│   └── TaskAssistantController.java # 任务助手接口控制器
├── service/                         # 服务层
│   ├── TaskService.java             # 任务服务接口
│   ├── impl/TaskServiceImpl.java    # 任务服务实现
│   └── TaskAssistantService.java    # 任务助手服务
├── model/                           # 数据模型
│   ├── ChatRequest.java             # 聊天请求
│   ├── ChatResponse.java            # 聊天响应
│   ├── AgentInfo.java               # Agent 信息
│   ├── Task.java                    # 任务实体
│   └── GreetingResponse.java        # 问候响应
├── knowledge/                       # 知识库模块
│   ├── model/                       # 知识库模型
│   └── service/                     # 知识库服务
├── skills/                          # 技能模块
│   ├── service/                     # 技能服务
│   └── tools/                       # 技能工具管理
├── agent/                           # Agent 模块
│   └── StructuredOutputAgent.java   # 结构化输出 Agent
├── tools/                           # 工具模块
│   └── agentscope/                  # AgentScope 工具
│       ├── DataTools.java           # 数据统计工具
│       ├── DataQueryTools.java      # 数据查询工具
│       ├── TaskTools.java           # 任务工具
│       ├── KnowledgeTools.java      # 知识库工具
│       └── ShipRiskTools.java       # 船舶风险工具
├── document/                        # 文档对话系统模块
│   ├── config/                      # 配置
│   ├── controller/                  # 控制器
│   ├── model/                       # 数据模型
│   ├── repository/                  # 数据仓库
│   ├── service/                     # 服务层
│   ├── scheduler/                   # 定时任务
│   └── exception/                   # 异常处理
└── DataAssistantApplication.java    # 应用入口

src/main/resources/
├── prompts/                         # 提示词模板
│   ├── task-system.st               # 任务助手提示词
│   ├── general-system.st            # 通用智能体提示词
│   ├── risk-system.st               # 风险智能体提示词
│   ├── emergency-system.st          # 应急智能体提示词
│   └── review-system.st             # 复盘智能体提示词
├── skills/                          # 技能定义
│   ├── maritime-law/SKILL.md        # 海事法规查询技能
│   ├── risk-assessment/SKILL.md     # 风险评估技能
│   ├── emergency-response/SKILL.md  # 应急响应技能
│   └── data-analysis/SKILL.md       # 数据分析技能
├── db/                              # 数据库脚本
│   └── schema.sql                   # 数据库初始化脚本
└── application.yml                  # 应用配置
```

## 架构设计

### AgentScope ReActAgent 架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         用户请求                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      ChatController                              │
│                   /api/chat/* 端点                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│              AgentOrchestrationService                           │
│                (智能体编排服务)                                   │
│   - @Qualifier("supervisorAgent") 注入 Supervisor               │
│   - 管理会话级 Memory (SessionMemoryManager)                     │
│   - 协调 ReActAgent 调用链                                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                   supervisorAgent (ReActAgent)                   │
│                        监督者智能体                               │
│              (LLM 智能路由 + Toolkit 工具调用)                    │
│                                                                  │
│   路由规则 (JSON 数组输出):                                       │
│   - 任务/待办/委托 → ["task"]                                    │
│   - 通用问题/你好 → ["general"]                                  │
│   - 风险/评估 → ["risk"]                                         │
│   - 应急/紧急 → ["emergency"]                                    │
│   - 分析/报告 → ["review"]                                       │
│   - 完成/谢谢 → ["FINISH"]                                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    ▼                       ▼
        ┌──────────────────┐    ┌──────────────────┐
        │   Toolkit        │    │   专业 Agent     │
        │  (路由工具)       │───▶│  (ReActAgent)    │
        └──────────────────┘    └──────────────────┘
                    │                       │
                    └───────────┬───────────┘
                                │
        ┌───────────┬───────┼───────┬───────────┬───────────┐
        ▼           ▼       ▼       ▼           ▼           ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│   Task    │ │  General  │ │   Risk    │ │ Emergency │ │  Review   │
│   Agent   │ │   Agent   │ │   Agent   │ │   Agent   │ │   Agent   │
│ (ReAct)   │ │ (ReAct)   │ │ (ReAct)   │ │ (ReAct)   │ │ (ReAct)   │
│ 任务助手  │ │ 通用智能体 │ │ 风险智能体 │ │ 应急智能体 │ │ 复盘智能体 │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
      │             │             │             │             │
      └─────────────┴─────────────┴─────────────┴─────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Toolkit     │       │  Hooks List   │       │   Memory      │
│  (共享工具集)  │       │  (钩子链)      │       │ (会话级记忆)   │
└───────────────┘       └───────┬───────┘       └───────────────┘
                                │
                                ▼
                        ┌───────────────┐
                        │ SkillService  │
                        │   技能服务     │
                        └───────────────┘
```

### AgentScope 核心组件

| 组件 | 类名 | 说明 |
|------|------|------|
| **ReActAgent** | `io.agentscope.core.ReActAgent` | ReAct 模式智能体，支持推理-行动循环 |
| **Toolkit** | `io.agentscope.core.tool.Toolkit` | 工具集管理，支持动态工具注册 |
| **Model** | `io.agentscope.core.model.Model` | LLM 模型抽象接口 |
| **Memory** | `io.agentscope.core.memory.Memory` | 会话记忆管理 |
| **Hook** | `io.agentscope.core.hook.Hook` | 生命周期钩子，支持流式输出、日志等 |
| **Msg** | `io.agentscope.core.message.Msg` | 消息抽象，支持多模态内容 |

### 会话与文件系统架构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                            会话与文件系统架构                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────┐         ┌──────────────┐         ┌──────────────┐       │
│   │   Session    │────────<│   Message    │────────<│  MessageFile │       │
│   │   (会话)      │  1:N    │   (消息)      │  1:N    │  (消息文件)   │       │
│   └──────────────┘         └──────────────┘         └──────────────┘       │
│          │                                                            │    │
│          │                                                            │    │
│          │ 1:N                                                       │ N:1│
│          ▼                                                            ▼    │
│   ┌──────────────┐                                             ┌──────────┐│
│   │ SessionFile  │                                             │   File   ││
│   │ (会话文件索引)│                                             │ (文件存储)││
│   └──────────────┘                                             └──────────┘│
│                                                                             │
│   数据关系说明：                                                             │
│   - SessionFile: 会话与文件的关联表，记录文件与会话的关系                       │
│   - MessageFile: 消息与文件的关联表，记录文件被哪条消息引用                     │
│   - File: 文件实体表，存储文件元数据和存储路径                                 │
└─────────────────────────────────────────────────────────────────────────────┘
```

**会话生命周期管理**：

| 场景 | 处理策略 | 实现方式 |
|------|---------|---------|
| 空会话 | 自动清理 | 预创建后30分钟无消息，后端自动删除 |
| 会话过期 | 30天后删除 | 定时任务清理 `last_access_time > 30天` 的会话 |
| 会话上限 | 单用户最多10个 | 创建新会话时检查，超限提示删除旧会话 |

**文件安全校验**：

| 校验类型 | 说明 |
|---------|------|
| 扩展名白名单 | 仅允许: pdf, txt, md, doc, docx, xls, xlsx |
| 魔数校验 | 验证文件头与扩展名是否匹配，防止伪造扩展名 |
| 文件名清理 | 移除路径穿越字符，防止目录遍历攻击 |
| 大小限制 | 单文件最大2MB，单次请求最大10MB |

### Skill 系统

Skill 系统提供可复用的指令与上下文包，智能体在相关任务时会自动发现并使用。

**核心特性**：
- **渐进式披露**：系统提示中只注入技能列表，模型按需调用 `read_skill` 加载完整内容
- **工具绑定**：支持将工具与 Skill 绑定（groupedTools），实现按需披露
- **热加载**：支持运行时重新加载技能定义

**已定义技能**：

| 技能名称 | 描述 | 适用场景 |
|---------|------|---------|
| `maritime-law` | 海事法规查询技能 | 海事法律法规、政策文件、操作规程查询 |
| `risk-assessment` | 风险评估技能 | 风险识别、评估、处置建议 |
| `emergency-response` | 应急响应技能 | 突发事件处置、资源调度、应急预案 |
| `data-analysis` | 数据分析技能 | 历史数据分析、统计报告、趋势分析 |

**SKILL.md 格式**：
```markdown
---
name: skill-name
description: 当用户需要...时使用此技能
---

# 技能名称
功能说明、使用方法、可用资源列表等
```

### 核心特性

1. **ReActAgent 模式**：采用 AgentScope 的 ReAct (Reasoning + Acting) 模式，支持推理-行动循环
2. **LLM 智能路由**：Supervisor 使用 LLM 进行意图识别和路由决策，输出 JSON 数组格式
3. **任务助手智能体**：提供任务管理、个性化问候、智能委托等功能，可委托给其他专业智能体
4. **Skill 系统**：支持可复用的技能包，智能体自动发现并使用相关技能
5. **知识库集成**：集成 MaxKB 知识库，支持海事法规检索，服务不可用时自动降级
6. **会话级 Memory**：SessionMemoryManager 为每个会话维护独立的 Memory 实例，支持 TTL 自动清理
7. **Human-in-the-Loop**：支持工具执行前的用户确认流程，可批准/拒绝/编辑参数
8. **Hook 机制**：支持 StreamingHook、HumanConfirmationHook 等生命周期钩子
9. **厂商无关**：使用 OpenAI 兼容接口，支持智谱 AI、阿里云通义千问等多种 LLM 提供商
10. **流式响应**：支持 SSE 流式输出，提升用户体验

### 会话与文件系统特性

1. **会话级文件管理**：文件与会话绑定，切换会话自动清空当前文件列表
2. **会话预创建**：用户开始输入或上传文件时即创建会话，而非发送时才创建
3. **文件安全校验**：魔数校验防止伪造扩展名，文件名清理防止路径穿越
4. **同会话去重**：基于 MD5 校验，同一会话内重复上传自动复用已有文件
5. **会话生命周期**：
   - 空会话清理：30分钟无消息自动删除
   - 过期会话删除：30天未访问自动清理
   - 会话上限：单用户最多10个会话
6. **文件快捷操作**：支持"详细总结文档"、"提取关键要点"等快捷按钮

## API 接口

### 基础接口

```bash
# 流式聊天（Supervisor 智能路由）
POST /api/chat/stream
Content-Type: application/json

{
  "message": "请分析最近的海上风险情况",
  "sessionId": "your-session-id"
}

# 非流式聊天
POST /api/chat/non-stream
Content-Type: application/json

{
  "message": "请分析最近的海上风险情况",
  "sessionId": "your-session-id"
}

# 获取已注册的智能体列表
GET /api/chat/agents
```

### 文档对话接口

```bash
# 上传文档
POST /api/documents/upload
Content-Type: multipart/form-data
X-User-Id: user001

file=@/path/to/document.pdf

# 获取文档列表
GET /api/documents
X-User-Id: user001

# 获取文档详情
GET /api/documents/{documentId}
X-User-Id: user001

# 删除文档
DELETE /api/documents/{documentId}
X-User-Id: user001

# 同步对话
POST /api/documents/{documentId}/chat
Content-Type: application/json
X-User-Id: user001

{
  "message": "文档的主要内容是什么？",
  "threadId": "optional-thread-id"
}

# 流式对话 (SSE)
POST /api/documents/{documentId}/chat/stream
Content-Type: application/json
X-User-Id: user001

{
  "message": "总结文档要点"
}

# 获取会话列表
GET /api/documents/{documentId}/sessions
X-User-Id: user001

# 获取消息历史
GET /api/sessions/{threadId}/messages
X-User-Id: user001

# 删除会话
DELETE /api/sessions/{threadId}
X-User-Id: user001

# 导出对话为 Word
GET /api/sessions/{threadId}/export/word
X-User-Id: user001
```

### 任务助手接口

```bash
# 用户登录时获取个性化问候（LLM 增强的问候语）
POST /api/task-assistant/greeting
Content-Type: application/json

{
  "userId": "user001",
  "userName": "张三"
}

# 响应示例
{
  "greeting": "早上好，张三，记得更新船员培训记录哦，逾期任务可要抓紧啦！",
  "todayTasks": [],
  "overdueTasks": [
    {
      "id": "T004",
      "title": "更新船员培训记录",
      "description": "更新船员安全培训记录档案",
      "dueDate": "2026-03-04",
      "priority": "LOW",
      "status": "PENDING",
      "category": "报告"
    }
  ],
  "summary": "今日任务: 0个 | 逾期任务: 1个"
}
```

### 会话与文件系统接口

#### 文件管理

```bash
# 上传文件
POST /api/v1/files/upload?userId=user001
Content-Type: multipart/form-data

file=@/path/to/document.pdf

# 响应示例
{
  "fileId": "file-41d32971ea294b6d",
  "fileName": "document.pdf",
  "fileSize": 1751,
  "fileType": "application/pdf",
  "downloadUrl": "/api/v1/files/file-41d32971ea294b6d/download",
  "uploadedAt": "2026-03-12T16:23:26.5495149",
  "checksum": "0cd6e519ddc435eeae7fa8efb0aacadddfc2085888fe169d7ad01d723b986163"
}

# 获取文件信息
GET /api/v1/files/{fileId}

# 下载文件
GET /api/v1/files/{fileId}/download

# 删除文件
DELETE /api/v1/files/{fileId}
```

#### 会话文件关联

```bash
# 关联文件到会话
POST /api/v1/sessions/{sessionId}/files
Content-Type: application/json

{
  "fileId": "file-41d32971ea294b6d",
  "userId": "user001"
}

# 获取会话的文件列表
GET /api/v1/sessions/{sessionId}/files

# 响应示例
[
  {
    "fileId": "file-41d32971ea294b6d",
    "fileName": "document.pdf",
    "fileSize": 1751,
    "fileType": "application/pdf",
    "uploadedAt": "2026-03-12T16:26:20.464798",
    "status": "pending",
    "isActive": true,
    "downloadUrl": "/api/v1/files/file-41d32971ea294b6d/download"
  }
]

# 从会话移除文件
DELETE /api/v1/sessions/{sessionId}/files/{fileId}

# 确认会话文件（发送消息后调用）
POST /api/v1/sessions/{sessionId}/files/confirm

# 清理会话的孤立文件
DELETE /api/v1/sessions/{sessionId}/files/cleanup
```

## 快速开始

### 1. 环境要求

- JDK 17+
- Maven 3.6+
- PostgreSQL 14+ (需安装 pgvector 扩展)
- LLM API Key（智谱 AI / 阿里云通义千问等）

### 2. 数据库初始化

```bash
# 连接 PostgreSQL
psql -U postgres

# 创建数据库
CREATE DATABASE data_assistant;

# 切换到数据库
\c data_assistant

# 执行初始化脚本
\i src/main/resources/db/schema.sql
```

**数据库脚本说明**：

| 脚本路径 | 说明 |
|---------|------|
| `src/main/resources/db/schema.sql` | 完整数据库初始化脚本 |

**脚本内容概览**：

- **扩展安装**：pgvector (向量)、uuid-ossp (UUID生成)、hstore (键值存储)
- **核心文档表**：doc_document (文档元数据)、doc_session (会话)、doc_message (消息)
- **文件管理表**：file_metadata (文件元数据)、session_file (会话文件关联)、message_file (消息文件关联)
- **向量存储表**：doc_vector_store (1024维向量，适配智谱embedding-2模型)
- **触发器**：自动更新 updated_at 字段

### 3. 配置

编辑 `src/main/resources/application.yml`，配置你的 API Key 和数据库：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/data_assistant
    username: postgres
    password: your_password
  ai:
    openai:
      base-url: https://open.bigmodel.cn/api/paas
      api-key: ${ZHIPU_API_KEY}
      chat:
        completions-path: /v4/chat/completions
        options:
          model: glm-4-flash
          temperature: 0.3
          max-tokens: 2000
```

或使用环境变量：

```bash
export ZHIPU_API_KEY=your_api_key_here
export POSTGRES_PASSWORD=your_password
```

### 4. 运行

```bash
# 编译
mvn clean package -DskipTests

# 运行
java -jar target/data-assistant-0.0.1-SNAPSHOT.jar

# 或使用 Maven
mvn spring-boot:run
```

### 5. 测试

```bash
# 测试流式接口
curl -X POST http://localhost:8081/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "sessionId": "test-001"}'

# 测试文件上传
curl -X POST http://localhost:8081/api/v1/files/upload \
  -H "X-User-Id: test-user" \
  -F "file=@test.pdf"

# 测试会话文件关联
curl -X POST http://localhost:8081/api/v1/sessions/{sessionId}/files \
  -H "Content-Type: application/json" \
  -d '{"fileId": "file-xxx", "userId": "test-user"}'

# 测试文档对话（带文件）
curl -X POST http://localhost:8081/api/v1/sessions/{sessionId}/messages \
  -H "Content-Type: application/json" \
  -H "X-User-Id: test-user" \
  -d '{"content": "请分析这个文件", "fileIds": ["file-xxx"]}'

# 测试获取会话文件列表
curl -X GET http://localhost:8081/api/v1/sessions/{sessionId}/files \
  -H "X-User-Id: test-user"
```

## 配置说明

### AgentScope 配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `agentscope.model.base-url` | LLM API 基础 URL | `https://open.bigmodel.cn/api/paas/v4` |
| `agentscope.model.model-name` | 模型名称 | `glm-4-flash` |
| `agentscope.agent.max-iters` | 专业 Agent 最大迭代次数 | 10 |
| `agentscope.agent.supervisor.max-iters` | Supervisor 最大迭代次数 | 3 |

### Spring AI 模型配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `spring.ai.openai.base-url` | API基础URL | 智谱AI |
| `spring.ai.openai.api-key` | API密钥 | 环境变量 `ZHIPU_API_KEY` |
| `spring.ai.openai.chat.options.model` | 模型名称 | glm-4-flash |
| `spring.ai.openai.chat.options.temperature` | 温度参数 | 0.3 |
| `spring.ai.openai.chat.options.max-tokens` | 最大Token数 | 2000 |

### 服务器配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `server.port` | 服务端口 | 8081 |
| `logging.level.com.huihai.ai` | 应用日志级别 | DEBUG |

### 数据库配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `spring.datasource.url` | 数据库连接URL | `jdbc:postgresql://localhost:5432/data_assistant` |
| `spring.datasource.username` | 数据库用户名 | `postgres` |
| `spring.datasource.password` | 数据库密码 | `123` |
| `spring.ai.vectorstore.pgvector.dimensions` | 向量维度 | 1536 |
| `spring.ai.vectorstore.pgvector.index-type` | 索引类型 | HNSW |
| `spring.ai.vectorstore.pgvector.distance-type` | 距离类型 | COSINE_DISTANCE |

### 文档对话配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `document.storage-path` | 文件存储路径 | `./uploads/documents` |
| `document.max-file-size` | 最大文件大小 | 52428800 (50MB) |
| `document.allowed-types` | 支持的文件类型 | pdf,txt,md,doc,docx,xls,xlsx |
| `document.chunk.size` | 分块大小 (tokens) | 800 |
| `document.chunk.overlap` | 分块重叠 (tokens) | 100 |
| `document.retrieval.top-k` | 检索返回数量 | 5 |
| `document.retrieval.similarity-threshold` | 相似度阈值 | 0.7 |

### 会话与文件配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `app.file.max-size-per-file` | 单个文件大小限制 | 2MB |
| `app.file.max-size-per-request` | 单次请求总大小限制 | 10MB |
| `app.file.max-files-per-session` | 单会话最大文件数 | 20 |
| `app.session.max-sessions-per-user` | 单用户最大会话数 | 10 |
| `app.session.empty-session-timeout` | 空会话超时时间 | 30分钟 |
| `app.session.session-expiration-days` | 会话过期天数 | 30天 |

### MaxKB 知识库配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `maxkb.enabled` | 是否启用知识库 | `false` |
| `maxkb.base-url` | MaxKB 服务地址 | `http://localhost:8080` |
| `maxkb.api-key` | API 密钥 | 空 |
| `maxkb.workspace-id` | 工作空间 ID | 空 |
| `maxkb.knowledge-base-id` | 默认知识库 ID | 空 |
| `maxkb.search.top-n` | 返回结果数量 | 5 |
| `maxkb.search.similarity` | 相似度阈值 | 0.5 |
| `maxkb.search.search-mode` | 搜索模式 | `blend` |

**启用知识库**（环境变量方式）：

```bash
export MAXKB_ENABLED=true
export MAXKB_BASE_URL=http://your-maxkb-server:8080
export MAXKB_API_KEY=your_api_key
export MAXKB_WORKSPACE_ID=your_workspace_id
export MAXKB_KB_ID=your_knowledge_base_id
```

**容错设计**：
- MaxKB 未部署时，应用正常启动，日志显示 "MaxKB 知识库服务已禁用"
- 知识库不可用时，Tool 返回友好提示，不会抛出异常影响系统运行

## 扩展指南

### 添加新智能体

1. 创建系统提示词模板 `prompts/new-agent-system.st`

2. 在 `AgentScopeConfiguration.java` 中添加 ReActAgent Bean：

```java
@Bean
public ReActAgent newAgent() {
    return ReActAgent.builder()
            .name("new_agent")
            .sysPrompt(loadPrompt("new-agent-system.st"))
            .model(model)
            .toolkit(sharedToolkit)
            .memory(sessionMemoryManager.getOrCreateMemory("new-default"))
            .hooks(hooks)
            .maxIters(defaultMaxIters)
            .build();
}
```

3. 更新 `AgentOrchestrationService` 构造函数，将新 Agent 注入 `agents` 映射

4. 更新 Supervisor 的系统提示词，添加新 Agent 的路由信息

### 添加新工具

创建独立的 Tool 类或在 `ToolkitConfiguration.java` 中添加：

```java
@Component
public class CustomTools {

    @Tool(description = "工具描述。参数：param1(说明), param2(说明)。")
    public String newTool(String param1, String param2) {
        // 实现逻辑
        return result;
    }
}
```

然后在 Toolkit 配置中注册：

```java
@Bean
public Toolkit sharedToolkit(CustomTools customTools) {
    return Toolkit.builder()
            .tools(List.of(customTools))
            .build();
}
```

### 知识库工具

系统提供 3 个知识库检索工具（在 `KnowledgeTools.java` 中定义）：

| 工具名称 | 说明 | 参数 |
|---------|------|------|
| `searchKnowledge` | 检索默认知识库 | `queryText` |
| `searchKnowledgeWithLimit` | 检索默认知识库（指定数量） | `queryText`, `topN` |
| `searchSpecificKnowledgeBase` | 检索指定知识库 | `kbId`, `queryText`, `topN` |

### 添加新技能

1. 创建技能目录和 SKILL.md 文件：

```
src/main/resources/skills/new-skill/
└── SKILL.md
```

2. SKILL.md 文件格式：

```markdown
---
name: new-skill
description: 当用户需要...时使用此技能
---

# 技能名称

## 功能说明
详细描述技能的功能...

## 使用方法
1. 步骤一
2. 步骤二

## 注意事项
- 注意点1
- 注意点2
```

3. （可选）注册技能专属工具：

```java
@Autowired
private SkillToolManager skillToolManager;

// 在应用启动时注册
skillToolManager.registerSkillTools("new-skill", List.of(tool1, tool2));
```

## 注意事项

1. **API Key 安全**：生产环境中请使用环境变量或密钥管理服务存储 API Key
2. **会话管理**：会话数据持久化存储到数据库，支持多用户隔离
3. **路由决策**：Supervisor 使用 JSON 数组格式输出路由决策，如 `["general"]` 或 `["FINISH"]`
4. **知识库容错**：MaxKB 知识库默认关闭，服务不可用时不影响系统正常运行
5. **文件安全**：系统通过魔数校验确保文件内容与扩展名匹配，防止恶意文件上传
6. **会话限制**：单用户最多10个活跃会话，超限需删除旧会话才能创建新会话
7. **文件清理**：定时任务自动清理未关联消息的孤立文件和过期会话数据

## License

MIT License