# 助手 (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;         // 助手名称
  callCount: number;   // 调用次数
  firstTurnMode: string;  // 首轮模式: "bot_first" | "user_first"
  opener: string;       // 开场白
  generatedOpenerEnabled: boolean;  // 是否启用生成式开场白
  openerAudioEnabled: boolean;  // 是否启用预生成开场音频
  openerAudioReady: boolean;    // 开场音频是否已生成
  openerAudioDurationMs: number; // 开场音频时长(ms)
  prompt: string;       // 系统提示词/人格设定
  knowledgeBaseId?: string;  // 关联知识库ID
  language: string;     // 语言: "zh" | "en"
  voiceOutputEnabled: boolean;  // 是否启用语音输出
  voice?: string;       // 声音ID
  speed: number;        // 语速 (0.5-2.0)
  hotwords: string[];   // 热词列表
  tools: string[];     // 启用的工具ID列表
  botCannotBeInterrupted: boolean;  // 是否禁止打断
  interruptionSensitivity: number;  // 打断灵敏度 (ms)
  configMode: string;  // 配置模式: "platform" | "dify" | "fastgpt" | "none"
  apiUrl?: string;    // 外部API URL
  apiKey?: string;    // 外部API Key
  // 模型关联
  llmModelId?: string;       // LLM模型ID
  asrModelId?: string;       // ASR模型ID
  embeddingModelId?: string; // Embedding模型ID
  rerankModelId?: 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}/config
```

获取助手的运行时引擎配置，包含 LLM、ASR、TTS、知识库等服务的完整配置信息。

**Response:**

```json
{
  "assistantId": "abc12345",
  "configVersionId": "asst_abc12345_20240115103000",
  "assistant": {
    "systemPrompt": "你是一个专业的客服人员...",
    "firstTurnMode": "bot_first",
    "greeting": "您好，请问有什么可以帮助您？",
    "generatedOpenerEnabled": false,
    "output": {"mode": "audio"},
    "bargeIn": {"enabled": true, "minDurationMs": 500},
    "services": {
      "llm": {"provider": "openai", "model": "gpt-4o", "apiKey": "...", "baseUrl": "..."},
      "asr": {"provider": "openai_compatible", "model": "paraformer-realtime-v2", "apiKey": "..."},
      "tts": {"enabled": true, "provider": "dashscope", "model": "qwen3-tts-flash-realtime", "voice": "Cherry", "speed": 1.0}
    },
    "tools": [...],
    "knowledgeBaseId": "kb_001",
    "openerAudio": {"enabled": true, "ready": true, "pcmUrl": "/api/assistants/abc12345/opener-audio/pcm"}
  },
  "sessionStartMetadata": {...},
  "sources": {
    "llmModelId": "llm_001",
    "asrModelId": "asr_001",
    "voiceId": "voice_001",
    "knowledgeBaseId": "kb_001"
  },
  "warnings": []
}
```

---

### 7. 获取助手开场音频状态

```http
GET /api/v1/assistants/{id}/opener-audio
```

**Response:**

```json
{
  "enabled": true,
  "ready": true,
  "encoding": "pcm_s16le",
  "sampleRateHz": 16000,
  "channels": 1,
  "durationMs": 2500,
  "textHash": "abc123...",
  "ttsFingerprint": "def456...",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

---

### 8. 下载开场音频 PCM 文件

```http
GET /api/v1/assistants/{id}/opener-audio/pcm
```

返回 PCM 音频文件 (application/octet-stream)。

---

### 9. 生成开场音频

```http
POST /api/v1/assistants/{id}/opener-audio/generate
```

**Request Body:**

```json
{
  "text": "您好，请问有什么可以帮助您？"
}
```

**Response:**

```json
{
  "enabled": true,
  "ready": true,
  "encoding": "pcm_s16le",
  "sampleRateHz": 16000,
  "channels": 1,
  "durationMs": 2500,
  "textHash": "abc123...",
  "ttsFingerprint": "def456..."
}
```

---

## 建议的 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
```