# 角色定义

NavTalk 支持通过 `session.update` 请求中的 `instructions` 字段，自定义数字人的人格、语言风格、欢迎语、自动响应规则与上下文记忆能力，从而实现高度定制化的数字生命体行为模式。

通过配置 instructions，你可以设定：

* 数字人的行为风格与专业背景
* 响应语言（中英文、日语等）
* 初始欢迎语
* 函数调用触发规则
* 上下文记忆与个性化偏好
* 音色情感

## 配置入口：`session.update` 请求体

在与OpenAI Realtime AP建立时，发送的session中配置 instructions：

```javascript
const instructions = `
  ${activeCharacter.characterDefinition}.
  Please respond in ${userLanguage}.
  Please greet the user with: "${activeCharacter.greeting}".
  When encountering requests beyond conversational capabilities, 
  automatically trigger function calls for:
  - Multimedia 内容生成（images/audio/video）
  - 实时数据查询（weather/stocks 等）
  - 业务系统交互（CRM/ERP 等）

  Current context: ${messageConfig}
`;

const sessionConfig = {
  type: "session.update",
  session: {
    instructions,
    voice: "nova", // 可选音色（详见下方 voice 列表）
    temperature: 1,
    modalities: ["text", "audio"],
    input_audio_format: "pcm16",
    output_audio_format: "pcm16",
    input_audio_transcription: {
      model: "whisper-1"
    }
  }
};

socket.send(JSON.stringify(sessionConfig));
```

## 参数说明

| 参数字段                  | 类型     | 示例                     | 说明                        |
| --------------------- | ------ | ---------------------- | ------------------------- |
| `characterDefinition` | string | 你是一位温柔理性的心理咨询师         | 用于设定人格、语气、专业背景等           |
| `userLanguage`        | string | zh-CN / en-US / ja-JP  | 控制输出语言                    |
| `greeting`            | string | “您好，我是您的智能助理。”         | 可选欢迎语，支持变量                |
| `function call rules` | string | 自然语言描述调用时机             | 描述在何种场景下自动调用函数            |
| `messageConfig`       | object | 包含历史对话摘要、用户偏好等 JSON 对象 | 用于注入当前上下文信息（支持 AI + 用户内容） |
| `voice`               | string | "nova"                 | 指定语音风格（见下方）               |

### 数字人的行为风格与专业背景

通过配置 `characterDefinition`，你可以定义数字人的人格设定、语气风格、知识背景与交流习惯。

| 示例设定                             | 描述          |
| -------------------------------- | ----------- |
| `你是一位温柔理性的心理咨询师，擅长倾听和共情。`        | 用于心理健康类应用   |
| `你是一位风趣幽默的虚拟主持人，擅长调动氛围。`         | 适合直播互动、娱乐内容 |
| `你是一名拥有20年经验的商务顾问，沟通时逻辑清晰、简洁专业。` | 用于企业客服、知识问答 |

### 响应语言设置（userLanguage）

您可以通过 `userLanguage` 参数指定数字人的对话语言，支持多种语种，如中文、英文、日文等。

| 语言 | 参数值     |
| -- | ------- |
| 中文 | `zh-CN` |
| 英文 | `en-US` |
| 日文 | `ja-JP` |

📌 **注意事项**：

* 设置后，所有响应内容都将使用该语言生成。
* 若 instructions 中无此设置，系统默认按用户输入语言自动识别。

### 初始欢迎语（greeting）

数字人可通过设置欢迎语，在建立连接后主动发起首次对话。

| 参数名        | 类型     | 示例                       |
| ---------- | ------ | ------------------------ |
| `greeting` | string | `"您好，我是您的智能助理，有什么可以帮您？"` |

### 函数调用触发规则（function call rules）

NavTalk 支持结合 OpenAI Function Calling 技术，实现数字人与外部系统的无缝对接（如数据库、天气API、订单查询等）。

> 详见Function调用章节：<https://app.gitbook.com/o/r5pQJkfNa9uW4Okhy7UX/s/vtnbUdtLjPoqnztbz3AV/~/changes/37/shi-shi-shu-zi-ren-api/images-and-media>

### 上下文记忆策略（messageConfig vs conversation.item.create）

NavTalk 支持上下文记忆功能，使数字人能够理解之前的对话背景。

> 详见维持历史对话章节：<https://app.gitbook.com/o/r5pQJkfNa9uW4Okhy7UX/s/vtnbUdtLjPoqnztbz3AV/~/changes/37/shi-shi-shu-zi-ren-api/images-and-media-1>

### 支持语音风格（voice）

NavTalk 提供多种高质量的语音合成风格，您可以通过 `voice` 参数自由选择数字人音色：

| 语音名称      | 风格描述         | 试听链接                                                            |
| --------- | ------------ | --------------------------------------------------------------- |
| `alloy`   | 中性权威，适合商务/科普 | [试听 🔊](https://cdn.openai.com/API/voice-previews/alloy.flac)   |
| `shimmer` | 明亮活力女声，适合客服  | [试听 🔊](https://cdn.openai.com/API/voice-previews/shimmer.flac) |
| `ballad`  | 温暖叙事型男声      | [试听 🔊](https://cdn.openai.com/API/voice-previews/ballad.flac)  |
| `coral`   | 专业清晰播音腔      | [试听 🔊](https://cdn.openai.com/API/voice-previews/coral.flac)   |
| `echo`    | 有混响的演绎音      | [试听 🔊](https://cdn.openai.com/API/voice-previews/echo.flac)    |
| `ash`     | 稳重可信的男声      | [试听 🔊](https://cdn.openai.com/API/voice-previews/ash.flac)     |
| `sage`    | 知性温柔女声       | [试听 🔊](https://cdn.openai.com/API/voice-previews/sage.flac)    |
| `verse`   | 富有韵律，适合诗歌朗诵  | [试听 🔊](https://cdn.openai.com/API/voice-previews/verse.flac)   |
