# 配置选项

助手配置界面包含多个标签页，每个标签页负责不同方面的配置。

## 全局设置

全局设置定义助手的核心对话能力。

| 配置项 | 说明 | 建议值 |
|-------|------|--------|
| 助手名称 | 用于标识和管理 | 简洁明确 |
| 系统提示词 | 定义角色、任务和约束 | 详见[提示词指南](prompts.md) |
| 开场白 | 对话开始时的问候语 | 简短友好 |
| 温度参数 | 控制回复随机性 | 0.7（通用）/ 0.3（严谨） |
| 上下文长度 | 保留的历史消息数 | 10-20 |

### 高级选项

- **首轮模式** - 设置首次对话的触发方式
- **打断检测** - 用户打断时的处理策略
- **超时设置** - 无响应时的处理

## 语音配置

配置语音识别和语音合成参数。

### TTS 语音合成

| 配置 | 说明 |
|------|------|
| TTS 引擎 | 选择语音合成服务（阿里/火山/Minimax） |
| 音色 | 选择语音风格和性别 |
| 语速 | 语音播放速度（0.5-2.0） |
| 音量 | 语音输出音量（0-100） |
| 音调 | 语音音调高低（0.5-2.0） |

### ASR 语音识别

| 配置 | 说明 |
|------|------|
| ASR 引擎 | 选择语音识别服务 |
| 语言 | 识别语言（中文/英文/多语言） |
| 热词 | 提高特定词汇识别准确率 |

## 工具绑定

配置助手可调用的外部工具。

### 可用工具类型

| 工具 | 说明 |
|------|------|
| 搜索工具 | 网络搜索获取信息 |
| 天气查询 | 查询天气预报 |
| 计算器 | 数学计算 |
| 知识库检索 | RAG 知识检索 |
| 自定义工具 | HTTP 回调外部 API |

### 配置步骤

1. 在工具列表中勾选需要的工具
2. 配置工具参数（如有）
3. 测试工具调用是否正常

## 知识关联

关联 RAG 知识库，让助手能够回答专业领域问题。

### 配置参数

| 参数 | 说明 | 建议值 |
|------|------|--------|
| 知识库 | 选择要关联的知识库 | - |
| 相似度阈值 | 低于此分数不返回 | 0.7 |
| 返回数量 | 单次检索返回条数 | 3 |
| 检索策略 | 混合/向量/关键词 | 混合 |

### 多知识库

支持关联多个知识库，系统会自动合并检索结果。

## 外部链接

配置第三方服务集成和 Webhook 回调。

### Webhook 配置

| 字段 | 说明 |
|------|------|
| 回调 URL | 接收事件的 HTTP 端点 |
| 事件类型 | 订阅的事件（对话开始/结束/工具调用等） |
| 认证方式 | API Key / Bearer Token / 无 |

### 支持的事件

- `conversation.started` - 对话开始
- `conversation.ended` - 对话结束
- `tool.called` - 工具被调用
- `human.transfer` - 转人工

## 配置持久化与运行时覆盖

助手配置分为两层：

1. **数据库持久化配置（基线配置）**：通过助手管理 API 保存，后续会话默认读取这一层。
2. **会话级覆盖配置（runtime overrides）**：仅对当前 WebSocket 会话生效，不会写回数据库。

### 哪些配置会存到数据库

以下字段会持久化在 `assistants` / `assistant_opener_audio` 等表中（通过创建/更新助手写入）：

| 类别 | 典型字段 |
|------|---------|
| 对话行为 | `name`、`prompt`、`opener`、`firstTurnMode`、`generatedOpenerEnabled` |
| 输出与打断 | `voiceOutputEnabled`、`voice`、`speed`、`botCannotBeInterrupted`、`interruptionSensitivity` |
| 工具与知识库 | `tools`、`knowledgeBaseId` |
| 模型与外部模式 | `configMode`、`apiUrl`、`apiKey`、`llmModelId`、`asrModelId`、`embeddingModelId`、`rerankModelId` |
| 开场音频 | `openerAudioEnabled` 及音频文件状态（`ready`、`durationMs` 等） |

> 引擎在连接时通过 `assistant_id` 从后端读取该助手的 `sessionStartMetadata` 作为默认运行配置。

### 哪些配置可以在会话中覆盖

客户端可在 `session.start.metadata.overrides` 中覆盖以下白名单字段（仅当前会话有效）：

- `systemPrompt`
- `greeting`
- `firstTurnMode`
- `generatedOpenerEnabled`
- `output`
- `bargeIn`
- `knowledgeBaseId`
- `knowledge`
- `tools`
- `openerAudio`

以下字段不能由客户端覆盖：

- `services`（模型 provider / apiKey / baseUrl 等）
- `assistantId` / `appId` / `configVersionId`（及下划线变体）
- 包含密钥语义的字段（如 `apiKey`、`token`、`secret`、`password`、`authorization`）

### 覆盖示例（代码）

下面示例展示「数据库基线配置 + 会话 overrides」的最终效果。

```json
// 1) 数据库存储的基线配置（示意）
// GET /api/v1/assistants/asst_demo/config -> sessionStartMetadata
{
  "systemPrompt": "你是电商客服助手，回答要简洁。",
  "greeting": "你好，我是你的客服助手。",
  "firstTurnMode": "bot_first",
  "output": { "mode": "audio" },
  "knowledgeBaseId": "kb_orders",
  "tools": [
    { "type": "function", "function": { "name": "query_order" } }
  ]
}
```

```json
// 2) 客户端发起会话时的覆盖
{
  "type": "session.start",
  "metadata": {
    "channel": "web",
    "history": { "userId": 1001 },
    "overrides": {
      "greeting": "你好，我来帮你查订单进度。",
      "output": { "mode": "text" },
      "knowledgeBaseId": "kb_vip_orders",
      "tools": [
        { "type": "function", "function": { "name": "query_vip_order" } }
      ]
    }
  }
}
```

```json
// 3) 引擎合并后的有效配置（示意）
{
  "assistantId": "asst_demo",
  "systemPrompt": "你是电商客服助手，回答要简洁。",
  "greeting": "你好，我来帮你查订单进度。",
  "firstTurnMode": "bot_first",
  "output": { "mode": "text" },
  "knowledgeBaseId": "kb_vip_orders",
  "tools": [
    { "type": "function", "function": { "name": "query_vip_order" } }
  ],
  "channel": "web",
  "history": { "userId": 1001 }
}
```

合并规则可简化为：

```python
effective = {**db_session_start_metadata, **metadata.overrides}
```

当 `WS_EMIT_CONFIG_RESOLVED=true` 时，服务端会返回 `config.resolved`（公开、安全裁剪后的快照）用于前端调试当前生效配置。

## 配置导入导出

### 导出配置

1. 在助手详情页点击 **更多**
2. 选择 **导出配置**
3. 下载 JSON 格式的配置文件

### 导入配置

1. 点击 **新建助手**
2. 选择 **从配置导入**
3. 上传配置文件