# 助手 (Assistant) API

助手 API 用于管理 AI 小助手的创建、配置和操作。

## 基础信息

| 项目 | 值 |
|------|-----|
| Base URL | `/api/v1/assistants` |
| 认证方式 | Bearer Token (预留) |

---

## 数据模型

### Assistant

```typescript
interface Assistant {
  id: string;           // 助手唯一标识 (8位UUID)
  user_id: number;      // 所属用户ID
  name: string;         // 助手名称
  call_count: number;   // 调用次数
  opener: string;      // 开场白
  prompt: string;       // 系统提示词/人格设定
  knowledge_base_id?: string;  // 关联知识库ID
  language: string;     // 语言: "zh" | "en"
  voice?: string;      // 声音ID
  speed: number;        // 语速 (0.5-2.0)
  hotwords: string[];  // 热词列表
  tools: string[];      // 启用的工具ID列表
  interruption_sensitivity: number;  // 打断灵敏度 (ms)
  config_mode: string;  // 配置模式: "platform" | "dify" | "fastgpt" | "none"
  api_url?: string;    // 外部API URL
  api_key?: string;     // 外部API Key
  // 模型关联 (新增)
  llm_model_id?: string;       // LLM模型ID
  asr_model_id?: string;       // ASR模型ID
  embedding_model_id?: string; // Embedding模型ID
  rerank_model_id?: string;    // Rerank模型ID
  created_at: string;
  updated_at: string;
}
```

---

## API 端点

### 1. 获取助手列表

```http
GET /api/v1/assistants
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 50 | 每页数量 |

**Response:**

```json
{
  "total": 100,
  "page": 1,
  "limit": 50,
  "list": [
    {
      "id": "abc12345",
      "user_id": 1,
      "name": "客服助手",
      "call_count": 128,
      "opener": "您好，请问有什么可以帮助您？",
      "prompt": "你是一个专业的客服人员...",
      "language": "zh",
      "voice": "voice_001",
      "speed": 1.0,
      "hotwords": ["帮助", "退款"],
      "tools": ["query_order", "refund"],
      "interruption_sensitivity": 500,
      "config_mode": "platform",
      "llm_model_id": "llm_001",
      "asr_model_id": "asr_001",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### 2. 获取单个助手详情

```http
GET /api/v1/assistants/{id}
```

**Path Parameters:**

| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 助手ID |

**Response:**

```json
{
  "id": "abc12345",
  "user_id": 1,
  "name": "客服助手",
  "call_count": 128,
  "opener": "您好，请问有什么可以帮助您？",
  "prompt": "你是一个专业的客服人员...",
  "knowledge_base_id": "kb_001",
  "language": "zh",
  "voice": "voice_001",
  "speed": 1.0,
  "hotwords": ["帮助", "退款"],
  "tools": ["query_order", "refund"],
  "interruption_sensitivity": 500,
  "config_mode": "platform",
  "api_url": "https://api.example.com",
  "llm_model_id": "llm_001",
  "asr_model_id": "asr_001",
  "embedding_model_id": "emb_001",
  "rerank_model_id": "rerank_001",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

---

### 3. 创建助手

```http
POST /api/v1/assistants
```

**Request Body:**

```json
{
  "name": "客服助手",
  "opener": "您好，请问有什么可以帮助您？",
  "prompt": "你是一个专业的客服人员，擅长解答产品问题和处理投诉。",
  "knowledgeBaseId": "kb_001",
  "language": "zh",
  "voice": "voice_001",
  "speed": 1.0,
  "hotwords": ["帮助", "退款", "物流"],
  "tools": ["query_order", "refund", "track_order"],
  "interruptionSensitivity": 500,
  "configMode": "platform",
  "llmModelId": "llm_001",
  "asrModelId": "asr_001",
  "embeddingModelId": "emb_001",
  "rerankModelId": "rerank_001"
}
```

**Fields 说明:**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 助手名称 |
| opener | string | 否 | 开场白，默认空字符串 |
| prompt | string | 否 | 系统提示词，默认空字符串 |
| knowledgeBaseId | string | 否 | 关联知识库ID |
| language | string | 否 | 语言，默认 "zh" |
| voice | string | 否 | 声音资源ID |
| speed | number | 否 | 语速，默认 1.0 |
| hotwords | string[] | 否 | 热词列表 |
| tools | string[] | 否 | 启用的工具ID列表 |
| interruptionSensitivity | number | 否 | 打断灵敏度(ms)，默认 500 |
| configMode | string | 否 | 配置模式，默认 "platform" |
| llmModelId | string | 否 | LLM模型ID |
| asrModelId | string | 否 | ASR模型ID |
| embeddingModelId | string | 否 | Embedding模型ID |
| rerankModelId | string | 否 | Rerank模型ID |

---

### 4. 更新助手

```http
PUT /api/v1/assistants/{id}
```

**Request Body:** (部分更新)

```json
{
  "name": "高级客服助手",
  "prompt": "你是一个高级客服人员...",
  "speed": 1.2
}
```

---

### 5```http
DELETE. 删除助手

 /api/v1/assistants/{id}
```

**Response:**

```json
{
  "message": "Deleted successfully"
}
```

---

### 6. 获取助手调用统计

```http
GET /api/v1/assistants/{id}/stats
```

**Response:**

```json
{
  "assistant_id": "abc12345",
  "total_calls": 128,
  "connected_calls": 120,
  "missed_calls": 8,
  "avg_duration_seconds": 180,
  "today_calls": 15
}
```

---

## 建议的 Schema 改进

基于 web/types.ts 的分析，建议在 `schemas.py` 中补充以下字段：

```python
class AssistantBase(BaseModel):
    # ... 现有字段 ...
    llm_model_id: Optional[str] = None
    asr_model_id: Optional[str] = None
    embedding_model_id: Optional[str] = None
    rerank_model_id: Optional[str] = None
```
