docs/AI_API.md

# InterConnect-Server AI API Documentation

本文档描述了 InterConnect-Server 的 AI 聊天功能相关 API 接口。

## 概述

AI 功能允许 Minecraft 服务器通过 InterConnect-Client 插件/模组调用 OpenAI 格式的 API，实现游戏内 AI 聊天功能。

**基础路径**: `/api/ai`

---

## 认证

所有 API 请求需要在 Header 中携带 API Key：

```
Authorization: Bearer <your_api_key>
```

### 权限要求

| 接口 | 权限要求 |
|------|----------|
| `GET /api/ai/config` | Admin Key |
| `POST /api/ai/config` | Admin Key |
| `PATCH /api/ai/config` | Admin Key |
| `DELETE /api/ai/config` | Admin Key |
| `POST /api/ai/config/test` | Admin Key |
| `POST /api/ai/chat` | Server Key 或 Admin Key |

---

## AI 配置接口

### 获取 AI 配置

获取当前的 AI 配置信息（API Key 会被部分隐藏）。

**请求**

```http
GET /api/ai/config
Authorization: Bearer <admin_key>
```

**成功响应** `200 OK`

```json
{
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "modelId": "gpt-3.5-turbo",
  "apiKey": "sk-x****xxxx",
  "enabled": true,
  "systemPrompt": "You are a helpful assistant for Minecraft players.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}
```

**错误响应** `404 Not Found`

```json
{
  "detail": "AI configuration not found"
}
```

---

### 创建 AI 配置

创建新的 AI 配置。

**请求**

```http
POST /api/ai/config
Authorization: Bearer <admin_key>
Content-Type: application/json
```

**请求体**

```json
{
  "api_url": "https://api.openai.com/v1/chat/completions",
  "model_id": "gpt-3.5-turbo",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "enabled": true,
  "system_prompt": "You are a helpful assistant for Minecraft players."
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `api_url` | string | ✅ | OpenAI 格式的 API URL |
| `model_id` | string | ✅ | 模型 ID (如 gpt-3.5-turbo, gpt-4) |
| `api_key` | string | ✅ | API Key |
| `enabled` | boolean | ❌ | 是否启用，默认 `true` |
| `system_prompt` | string | ❌ | 系统提示词，可选 |

**成功响应** `201 Created`

```json
{
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "modelId": "gpt-3.5-turbo",
  "apiKey": "sk-x****xxxx",
  "enabled": true,
  "systemPrompt": "You are a helpful assistant for Minecraft players.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

**错误响应** `400 Bad Request`

```json
{
  "detail": "api_url, model_id, and api_key are required"
}
```

---

### 更新 AI 配置

更新现有的 AI 配置，只需提供要更新的字段。

**请求**

```http
PATCH /api/ai/config
Authorization: Bearer <admin_key>
Content-Type: application/json
```

**请求体**

```json
{
  "model_id": "gpt-4",
  "enabled": false
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `api_url` | string | ❌ | OpenAI 格式的 API URL |
| `model_id` | string | ❌ | 模型 ID |
| `api_key` | string | ❌ | API Key（不提供则保持原值） |
| `enabled` | boolean | ❌ | 是否启用 |
| `system_prompt` | string | ❌ | 系统提示词 |

**成功响应** `200 OK`

```json
{
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "modelId": "gpt-4",
  "apiKey": "sk-x****xxxx",
  "enabled": false,
  "systemPrompt": "You are a helpful assistant for Minecraft players.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T14:00:00.000Z"
}
```

---

### 删除 AI 配置

删除 AI 配置。

**请求**

```http
DELETE /api/ai/config
Authorization: Bearer <admin_key>
```

**成功响应** `204 No Content`

无响应体

**错误响应** `404 Not Found`

```json
{
  "detail": "AI configuration not found"
}
```

---

### 测试 AI 连接

测试当前 AI 配置是否能正常连接。

**请求**

```http
POST /api/ai/config/test
Authorization: Bearer <admin_key>
```

**成功响应** `200 OK`

```json
{
  "success": true,
  "message": "Connection successful",
  "model": "gpt-3.5-turbo",
  "response": "OK"
}
```

**错误响应** `400 Bad Request`

```json
{
  "success": false,
  "message": "Connection failed",
  "error": "Invalid API key"
}
```

---

## AI 聊天接口

### 发送聊天消息

发送消息到 AI 并获取回复。此接口供 Minecraft 服务器的 InterConnect-Client 插件/模组调用。

**请求**

```http
POST /api/ai/chat
Authorization: Bearer <server_key>
Content-Type: application/json
```

**请求体**

```json
{
  "message": "你好，请介绍一下 Minecraft 的红石系统",
  "player_name": "Steve",
  "server_id": "my-server-1"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `message` | string | ✅ | 用户发送的消息内容 |
| `player_name` | string | ❌ | 发送消息的玩家名称 |
| `server_id` | string | ❌ | 服务器 ID（Admin Key 可指定，Server Key 使用绑定的 server_id） |

**成功响应** `200 OK`

```json
{
  "success": true,
  "reply": "红石是 Minecraft 中的一种特殊材料，可以用来创建各种机械装置...",
  "model": "gpt-3.5-turbo",
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
```

**错误响应**

`404 Not Found` - AI 配置不存在

```json
{
  "detail": "AI configuration not found"
}
```

`403 Forbidden` - AI 功能已禁用

```json
{
  "detail": "AI feature is disabled"
}
```

`400 Bad Request` - 缺少必填字段

```json
{
  "detail": "message is required"
}
```

`500 Internal Server Error` - AI 请求失败

```json
{
  "success": false,
  "detail": "AI request failed",
  "error": "Rate limit exceeded"
}
```

---

## 事件类型

当 AI 聊天发生时，会产生 `ai_chat` 类型的事件，通过 WebSocket 广播给所有连接的客户端。

**事件格式**

```json
{
  "type": "minecraft_event",
  "event": {
    "event_type": "ai_chat",
    "server_name": "my-server-1",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
      "player_name": "Steve",
      "message": "你好",
      "reply": "你好！有什么我可以帮助你的吗？",
      "model": "gpt-3.5-turbo"
    }
  },
  "source_key_id_prefix": "abc12345"
}
```

---

## Minecraft 插件/模组集成示例

### 命令格式

在 Minecraft 服务器中，玩家可以使用以下命令调用 AI：

```
/ic chat <消息内容>
```

### 插件实现流程

1. 玩家执行 `/ic chat 你好` 命令
2. 插件捕获命令，提取消息内容
3. 插件向 InterConnect-Server 发送 POST 请求：

```http
POST /api/ai/chat
Authorization: Bearer <server_key>
Content-Type: application/json

{
  "message": "你好",
  "player_name": "Steve",
  "server_id": "my-server-1"
}
```

4. 收到响应后，将 AI 回复发送给玩家

### 响应处理示例（伪代码）

```java
// 发送请求
Response response = httpClient.post("/api/ai/chat", {
    "message": playerMessage,
    "player_name": player.getName(),
    "server_id": serverId
});

// 处理响应
if (response.success) {
    player.sendMessage("[AI] " + response.reply);
} else {
    player.sendMessage("[AI] 请求失败: " + response.error);
}
```

---

## 支持的 API 提供商

本系统支持所有兼容 OpenAI Chat Completions API 格式的服务：

| 提供商 | API URL 示例 |
|--------|-------------|
| OpenAI | `https://api.openai.com/v1/chat/completions` |
| Azure OpenAI | `https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-02-01` |
| Anthropic (via proxy) | 需要兼容层 |
| 本地模型 (Ollama) | `http://localhost:11434/v1/chat/completions` |
| 其他兼容服务 | 根据服务商文档配置 |

---

## 错误码参考

| HTTP 状态码 | 说明 |
|-------------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 204 | 删除成功（无内容） |
| 400 | 请求参数错误 |
| 401 | 未认证或 API Key 无效 |
| 403 | 权限不足或功能已禁用 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |