# AI模块前端API接口文档

> 更新时间：2025-11-04  
> 作者：AI Assistant

## 📁 文件结构

### TypeScript类型定义
```
schoolNewsWeb/src/types/ai/
└── index.ts                 # 完整的AI模块类型定义（含19个接口）
```

### API接口文件
```
schoolNewsWeb/src/apis/ai/
├── index.ts                 # API模块导出
├── agent-config.ts          # 智能体配置API（10个方法）
├── knowledge.ts             # 知识库API（14个方法）
├── file-upload.ts           # 文件上传API（8个方法）
├── chat.ts                  # 对话API（14个方法）
└── chat-history.ts          # 对话历史API（16个方法）
```

---

## 📘 类型定义说明

### 核心实体类型

#### 1. AiAgentConfig（智能体配置）
```typescript
interface AiAgentConfig extends BaseDTO {
  name?: string;              // 智能体名称
  avatar?: string;            // 头像
  description?: string;       // 描述
  systemPrompt?: string;      // 系统提示词
  modelName?: string;         // 模型名称
  modelProvider?: string;     // 模型提供商
  temperature?: number;       // 温度值（0.0-1.0）
  maxTokens?: number;         // 最大tokens
  topP?: number;              // Top P值
  difyAppId?: string;         // Dify应用ID
  difyApiKey?: string;        // Dify API Key
  status?: number;            // 状态（0禁用 1启用）
}
```

#### 2. AiKnowledge（知识库）
```typescript
interface AiKnowledge extends BaseDTO {
  name?: string;              // 知识库名称
  description?: string;       // 描述
  indexingTechnique?: string; // 索引方式
  embeddingModel?: string;    // Embedding模型
  difyDatasetId?: string;     // Dify数据集ID
  syncStatus?: number;        // 同步状态
  documentCount?: number;     // 文档数量
  characterCount?: number;    // 字符数
  creatorDept?: string;       // 创建者部门
  status?: number;            // 状态
}
```

#### 3. AiUploadFile（上传文件）
```typescript
interface AiUploadFile extends BaseDTO {
  knowledgeId?: string;       // 知识库ID
  fileName?: string;          // 文件名
  filePath?: string;          // 文件路径
  fileSize?: number;          // 文件大小
  fileType?: string;          // 文件类型
  difyDocumentId?: string;    // Dify文档ID
  uploadStatus?: number;      // 上传状态
  vectorStatus?: number;      // 向量化状态
  segmentCount?: number;      // 分片数
  errorMessage?: string;      // 错误信息
}
```

#### 4. AiConversation（对话会话）
```typescript
interface AiConversation extends BaseDTO {
  userID?: string;            // 用户ID
  agentID?: string;           // 智能体ID
  title?: string;             // 会话标题
  summary?: string;           // 会话摘要
  difyConversationId?: string;// Dify会话ID
  status?: number;            // 状态
  isFavorite?: boolean;       // 是否收藏
  isPinned?: boolean;         // 是否置顶
  messageCount?: number;      // 消息数量
  totalTokens?: number;       // Token总数
  lastMessageTime?: string;   // 最后消息时间
}
```

#### 5. AiMessage（对话消息）
```typescript
interface AiMessage extends BaseDTO {
  conversationID?: string;    // 会话ID
  userID?: string;            // 用户ID
  agentID?: string;           // 智能体ID
  role?: string;              // 角色（user/assistant/system）
  content?: string;           // 消息内容
  fileIDs?: string;           // 关联文件ID
  knowledgeIDs?: string;      // 引用知识ID
  knowledgeRefs?: string;     // 知识库引用详情
  tokenCount?: number;        // Token数量
  difyMessageId?: string;     // Dify消息ID
  rating?: number;            // 评分（1好评/-1差评）
  feedback?: string;          // 反馈内容
}
```

### 请求/响应类型

#### ChatRequest（对话请求）
```typescript
interface ChatRequest {
  agentId: string;            // 智能体ID（必需）
  conversationId?: string;    // 会话ID（可选）
  query: string;              // 用户问题（必需）
  knowledgeIds?: string[];    // 知识库ID列表（可选）
  stream?: boolean;           // 是否流式返回
}
```

#### ConversationSearchParams（会话搜索）
```typescript
interface ConversationSearchParams {
  agentId?: string;           // 智能体ID
  keyword?: string;           // 关键词
  isFavorite?: boolean;       // 是否收藏
  startDate?: string;         // 开始日期
  endDate?: string;           // 结束日期
  pageParam?: PageParam;      // 分页参数
}
```

#### StreamCallback（流式回调）
```typescript
interface StreamCallback {
  onMessage?: (message: string) => void;      // 接收消息片段
  onMessageEnd?: (metadata: string) => void;  // 消息结束
  onComplete?: () => void;                    // 完成
  onError?: (error: Error) => void;           // 错误
}
```

---

## 🔌 API接口说明

### 1. 智能体配置API（aiAgentConfigApi）

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `createAgent` | 创建智能体 | `AiAgentConfig` | `ResultDomain<AiAgentConfig>` |
| `updateAgent` | 更新智能体 | `AiAgentConfig` | `ResultDomain<AiAgentConfig>` |
| `deleteAgent` | 删除智能体 | `agentId: string` | `ResultDomain<boolean>` |
| `getAgentById` | 获取智能体详情 | `agentId: string` | `ResultDomain<AiAgentConfig>` |
| `listEnabledAgents` | 获取启用的智能体列表 | - | `ResultDomain<AiAgentConfig[]>` |
| `listAgents` | 获取智能体列表（支持过滤） | `filter?: Partial<AiAgentConfig>` | `ResultDomain<AiAgentConfig[]>` |
| `pageAgents` | 分页查询智能体 | `filter, pageParam` | `PageDomain<AiAgentConfig>` |
| `updateAgentStatus` | 更新智能体状态 | `agentId, status` | `ResultDomain<boolean>` |
| `updateDifyConfig` | 更新Dify配置 | `agentId, difyAppId, difyApiKey` | `ResultDomain<boolean>` |
| `checkNameExists` | 检查名称是否存在 | `name, excludeId?` | `ResultDomain<boolean>` |

### 2. 知识库API（knowledgeApi）

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `createKnowledge` | 创建知识库 | `AiKnowledge` | `ResultDomain<AiKnowledge>` |
| `updateKnowledge` | 更新知识库 | `AiKnowledge` | `ResultDomain<AiKnowledge>` |
| `deleteKnowledge` | 删除知识库 | `knowledgeId: string` | `ResultDomain<boolean>` |
| `getKnowledgeById` | 获取知识库详情 | `knowledgeId: string` | `ResultDomain<AiKnowledge>` |
| `listUserKnowledges` | 获取用户可见的知识库列表 | - | `ResultDomain<AiKnowledge[]>` |
| `listKnowledges` | 获取知识库列表（支持过滤） | `filter?: Partial<AiKnowledge>` | `ResultDomain<AiKnowledge[]>` |
| `pageKnowledges` | 分页查询知识库 | `filter, pageParam` | `PageDomain<AiKnowledge>` |
| `syncToDify` | 同步知识库到Dify | `knowledgeId: string` | `ResultDomain<boolean>` |
| `syncFromDify` | 从Dify同步知识库状态 | `knowledgeId: string` | `ResultDomain<AiKnowledge>` |
| `setPermissions` | 设置知识库权限 | `KnowledgePermissionParams` | `ResultDomain<boolean>` |
| `getPermissions` | 获取知识库权限 | `knowledgeId: string` | `ResultDomain<any>` |
| `checkPermission` | 检查用户权限 | `knowledgeId: string` | `ResultDomain<boolean>` |
| `getStats` | 获取知识库统计 | `knowledgeId: string` | `ResultDomain<any>` |

### 3. 文件上传API（fileUploadApi）

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `uploadFile` | 上传单个文件 | `knowledgeId, file: File` | `ResultDomain<FileUploadResponse>` |
| `batchUploadFiles` | 批量上传文件 | `knowledgeId, files: File[]` | `ResultDomain<FileUploadResponse[]>` |
| `deleteFile` | 删除文件 | `fileId: string` | `ResultDomain<boolean>` |
| `getFileById` | 获取文件详情 | `fileId: string` | `ResultDomain<AiUploadFile>` |
| `listFilesByKnowledge` | 获取知识库的文件列表 | `knowledgeId: string` | `ResultDomain<AiUploadFile[]>` |
| `pageFiles` | 分页查询文件 | `filter, pageParam` | `PageDomain<AiUploadFile>` |
| `syncFileStatus` | 同步文件状态 | `fileId: string` | `ResultDomain<AiUploadFile>` |
| `batchSyncFileStatus` | 批量同步文件状态 | `fileIds: string[]` | `ResultDomain<number>` |

### 4. 对话API（chatApi）

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `streamChat` | 流式对话（SSE） | `ChatRequest, StreamCallback?` | `Promise<ResultDomain<AiMessage>>` |
| `blockingChat` | 阻塞式对话 | `ChatRequest` | `ResultDomain<AiMessage>` |
| `stopChat` | 停止对话生成 | `messageId: string` | `ResultDomain<boolean>` |
| `createConversation` | 创建新会话 | `agentId, title?` | `ResultDomain<AiConversation>` |
| `getConversation` | 获取会话信息 | `conversationId: string` | `ResultDomain<AiConversation>` |
| `updateConversation` | 更新会话 | `AiConversation` | `ResultDomain<AiConversation>` |
| `deleteConversation` | 删除会话 | `conversationId: string` | `ResultDomain<boolean>` |
| `listUserConversations` | 获取用户会话列表 | `agentId?: string` | `ResultDomain<AiConversation[]>` |
| `listMessages` | 获取会话消息列表 | `conversationId: string` | `ResultDomain<AiMessage[]>` |
| `getMessage` | 获取单条消息 | `messageId: string` | `ResultDomain<AiMessage>` |
| `regenerateAnswer` | 重新生成回答 | `messageId, StreamCallback?` | `ResultDomain<AiMessage>` |
| `generateSummary` | 异步生成会话摘要 | `conversationId: string` | `ResultDomain<boolean>` |
| `rateMessage` | 评价消息 | `messageId, rating, feedback?` | `ResultDomain<boolean>` |

### 5. 对话历史API（chatHistoryApi）

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `pageUserConversations` | 分页查询用户会话 | `ConversationSearchParams` | `PageDomain<AiConversation>` |
| `searchConversations` | 搜索会话（全文） | `MessageSearchParams` | `PageDomain<AiConversation>` |
| `searchMessages` | 搜索消息内容 | `MessageSearchParams` | `PageDomain<AiMessage>` |
| `toggleFavorite` | 收藏/取消收藏 | `conversationId, isFavorite` | `ResultDomain<boolean>` |
| `togglePin` | 置顶/取消置顶 | `conversationId, isPinned` | `ResultDomain<boolean>` |
| `batchDeleteConversations` | 批量删除会话 | `conversationIds: string[]` | `ResultDomain<number>` |
| `getUserChatStatistics` | 获取用户对话统计 | `userId?: string` | `ResultDomain<UserChatStatistics>` |
| `getConversationStatistics` | 获取会话详细统计 | `conversationId: string` | `ResultDomain<ConversationStatistics>` |
| `exportConversationAsMarkdown` | 导出为Markdown | `conversationId: string` | `ResultDomain<string>` |
| `exportConversationAsJson` | 导出为JSON | `conversationId: string` | `ResultDomain<string>` |
| `batchExportConversations` | 批量导出会话 | `BatchExportParams` | `ResultDomain<string>` |
| `downloadExport` | 下载导出文件 | `conversationId, format` | `void` |
| `batchDownloadExport` | 批量下载导出 | `conversationIds, format` | `void` |
| `cleanExpiredConversations` | 清理过期会话 | `days: number` | `ResultDomain<number>` |
| `getRecentConversations` | 获取最近对话 | `limit?: number` | `ResultDomain<AiConversation[]>` |
| `getPopularConversations` | 获取热门对话 | `limit?: number` | `ResultDomain<AiConversation[]>` |

---

## 💡 使用示例

### 1. 创建智能体并进行流式对话

```typescript
import { aiAgentConfigApi, chatApi } from '@/apis/ai';

// 1. 创建智能体
const agentResult = await aiAgentConfigApi.createAgent({
  name: '智能助手',
  description: '帮助用户解答问题',
  systemPrompt: '你是一个智能助手...',
  modelName: 'gpt-3.5-turbo',
  status: 1
});

const agentId = agentResult.data?.ID;

// 2. 流式对话
await chatApi.streamChat(
  {
    agentId: agentId!,
    query: '你好，请介绍一下你自己',
    stream: true
  },
  {
    onMessage: (chunk) => {
      console.log('接收到消息片段：', chunk);
    },
    onMessageEnd: (metadata) => {
      console.log('消息结束，元数据：', metadata);
    },
    onComplete: () => {
      console.log('对话完成');
    },
    onError: (error) => {
      console.error('对话出错：', error);
    }
  }
);
```

### 2. 创建知识库并上传文件

```typescript
import { knowledgeApi, fileUploadApi } from '@/apis/ai';

// 1. 创建知识库
const knowledgeResult = await knowledgeApi.createKnowledge({
  name: '产品文档知识库',
  description: '包含所有产品相关文档',
  indexingTechnique: 'high_quality',
  embeddingModel: 'text-embedding-ada-002'
});

const knowledgeId = knowledgeResult.data?.ID;

// 2. 上传文件
const files = document.querySelector('input[type="file"]').files;
const uploadResult = await fileUploadApi.batchUploadFiles(
  knowledgeId!,
  Array.from(files)
);

console.log('上传成功：', uploadResult.data);
```

### 3. 搜索对话历史

```typescript
import { chatHistoryApi } from '@/apis/ai';

// 搜索包含关键词的会话
const searchResult = await chatHistoryApi.pageUserConversations({
  keyword: '产品',
  isFavorite: true,
  startDate: '2024-01-01',
  pageParam: {
    pageNumber: 1,
    pageSize: 20
  }
});

console.log('搜索结果：', searchResult.dataList);
```

### 4. 导出对话记录

```typescript
import { chatHistoryApi } from '@/apis/ai';

// 导出为Markdown
const markdownResult = await chatHistoryApi.exportConversationAsMarkdown(
  conversationId
);

// 创建下载链接
const blob = new Blob([markdownResult.data!], { type: 'text/markdown' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = `conversation_${conversationId}.md`;
a.click();

// 或者直接使用下载方法
chatHistoryApi.downloadExport(conversationId, 'markdown');
```

---

## 📊 统计数据

| 类别 | 数量 | 说明 |
|------|------|------|
| **TypeScript接口** | 19个 | 完整的类型定义 |
| **API模块** | 5个 | 智能体、知识库、文件、对话、历史 |
| **API方法** | 62个 | 涵盖所有业务功能 |
| **文件总数** | 6个 | 1个类型文件 + 5个API文件 |

---

## ✅ 完成清单

- [x] TypeScript类型定义完整
- [x] 智能体配置API
- [x] 知识库管理API
- [x] 文件上传API
- [x] 对话功能API（含流式SSE）
- [x] 对话历史API
- [x] 搜索功能API
- [x] 统计功能API
- [x] 导出功能API
- [x] 权限控制API
- [x] 向后兼容处理

---

## 📝 备注

1. **SSE流式对话**：使用EventSource实现，支持实时消息推送
2. **文件上传**：支持FormData multipart/form-data格式
3. **分页查询**：统一使用PageParam和PageDomain
4. **权限控制**：集成在知识库API中，支持部门和角色级别
5. **导出功能**：支持Markdown和JSON两种格式，支持批量导出
6. **统计分析**：用户级和会话级双维度统计
7. **向后兼容**：保留了conversationApi和messageApi别名

---

**前端API接口已全部完成！可以直接在Vue组件中使用。** ✨