主题
全局人设与音色
本章回答两个问题：怎么给智能体写「性格」（全局人设），怎么让它「用哪种声音说话」（音色）。
- 全局人设：智能体的性格底座，自动拼接到该智能体下所有技能的 prompt 头部。
- 音色：智能体语音回复时使用的声音，涉及多来源、多优先级的生效规则。
入口：产品管理 → 点击目标产品卡片 → 智能体配置详情 → 全局人设编辑区
1. 能力说明
1.1 全局人设
全局人设是智能体的「性格底座」。 在智能体配置详情页编辑的人设提示词，会自动拼接到该智能体下所有技能的 prompt 头部，确保智能体在任何技能场景（闲聊、查天气、AIoT 设备控制等）都保持统一的角色一致性。
核心特征：
| 特征 | 说明 |
|---|---|
| 作用范围 | 智能体下所有技能均自动继承全局人设 |
| 编辑入口 | 产品管理 → 点击目标产品卡片 → 智能体配置详情 → 全局人设编辑区 |
| 变量支持 | 支持插入系统变量，对话时实时渲染 |
| 生效时机 | 保存草稿后即可在调试窗生效；正式生效需点击「发布」 |
系统变量： 在人设编辑框右上角点击变量插入按钮，可选择以下系统变量，每次对话时实时渲染，无需手动更新。
| 变量 | 格式 | 说明 |
|---|---|---|
| 系统时间 | ${systemTime} | 实时渲染为当前对话时刻的系统时间 |
| 设备位置 | ${location} | 设备端上传的地理位置或 IP 解析结果 |
| 长期记忆 | ${memoBaseContent} | 该用户与设备的长期记忆内容 |
1.2 音色
音色即智能体语音回复时使用的声音。平台支持系统音色和自定义音色（音色复刻功能见 音色库）。
生效音色优先级：
| 优先级 | 音色来源 | 说明 | 生效时刻 |
|---|---|---|---|
| 0 ⚠ 当前运营平台不支持多角色配置 | 角色的音色（端侧传输） | 端侧传输 role_code，据此更改音色 | 端侧每次发送 query 时携带 role_code |
| 1 | 设备音色 | 设备管理中的设备音色 | 正常生效 |
对话音色在以上两种音色中二选一生效。四种典型场景：
| 场景 | 是否传 role_code | 是否用音色切换技能 | 本轮对话音色 |
|---|---|---|---|
| 1 | 传 | 否 | 对应角色音色 |
| 2 | 传 | 是 | 切换后的设备音色（技能只改设备音色） |
| 3 | 不传 | 否 | 设备音色 |
| 4 | 不传 | 是 | 切换后的设备音色 |
⚠ 音色切换技能只能改变「设备音色」，不改角色音色。举例：
- 场景 2：设备音色 A、role1 角色音色 B，用切换技能切到 C → 本轮音色为 C，此时【设备音色=C，role1 角色音色=B】。下次建联传 role1 → 音色为 B；不传
role_code→ 音色为 C。- 场景 4：设备音色 A，切到 C → 本轮音色 C，此时【设备音色=C】，下次建联音色仍为 C。
其他音色概念：
| 音色 | 说明 | 作用 |
|---|---|---|
| 人设音色 | 配置详情页全局人设旁的音色选择器中设置，是前台唯一可见的音色入口 | ① 作为该产品新注册设备的设备音色来源（后台自动填充）；② 设备上行 role_code 时作为角色音色生效【⚠ 当前调试窗不支持上行 role_code，调试阶段不生效】 |
| 设备原始音色 | 设备注册时独立存储的字段，用户切换音色后「还原」时使用 | 用户要求「返回原来的音色」时，设备音色恢复为设备原始音色（始终为设备注册时的音色） |
关键规则：
- 人设音色 → 新注册设备（单向、仅新注册）：修改人设音色后，之后该产品新注册的设备，其设备音色默认填充为注册当时的人设音色；已注册的存量设备不受影响。
- 调试窗音色不随人设音色变化：调试窗不上行
role_code，人设音色在调试阶段不生效，因此修改人设音色不会改变调试窗当前的音色。 - 设备原始音色单独存储、逻辑独立：它在设备注册时独立记录，用户要求「返回原来的音色」时始终恢复为设备注册时的音色，不随人设音色的后续修改而变化。
2. 参考模板
2.1 人设撰写模板
markdown
# 角色设定
## 1. 基本信息
- 姓名：
- 背景设定：
- 身份：
- MBTI：
## 2. 性格气质
-
## 3. 语言表达风格
-
## 4. 外观与交互设定
-
## 5. 能力描述
-2.2 人设撰写要点
| 要点 | 说明 |
|---|---|
| 明确角色与设备的关系 | 角色「住在」什么设备里？如何解释自己的存在？ |
| 写出行为边界 | 角色所在的设备有什么能力 |
| 结合产品场景 | 陪伴类设备偏温暖，工具类设备偏专业高效 |
| 用系统变量增强沉浸感 | 如用 ${systemTime} 让角色感知时间（如「这么晚了还不睡？」） |
| 控制 prompt 长度 | 建议 300-800 字，过长会影响模型对核心人设的遵循度 |
2.3 使用系统变量的示例
当前时间是 ${systemTime}，请根据时间段调整问候方式：
- 早上（6:00-11:00）：活力开朗
- 下午（11:00-18:00）：平稳温和
- 晚上（18:00-23:00）：轻松舒缓
- 深夜（23:00-6:00）：关心用户休息
用户所在位置：${location}，可以在聊天中自然融入当地话题。3. 配置流程
3.1 配置全局人设
| 步骤 | 操作 |
|---|---|
| Step 1 进入智能体配置 | 在「产品管理」中点击目标产品卡片进入智能体配置详情页 |
| Step 2 编辑全局人设 | 在页面顶部的全局人设编辑区直接编写角色提示词，支持 Markdown 格式 |
| Step 3 插入系统变量（可选） | 点击编辑框右上角变量按钮，选择变量，以 ${variableName} 格式插入到光标位置 |
| Step 4 保存与发布 | 「保存草稿」：保存但不生效，可在调试窗测试；「发布」：正式生效，所有绑定该应用的设备生效 |
3.2 配置音色
| 音色层级 | 配置方式 |
|---|---|
| 人设音色 | 配置详情页全局人设区域旁的音色选择器中切换；前台唯一可见的音色入口，同时作为该产品新注册设备的设备音色来源 |
| 设备音色 | 「设备管理」中新建 / 编辑设备时为单台设备指定，是设备实际生效的音色，可单独覆盖 |
4. Q&A
Q1：全局人设修改后，是否需要重新发布才能生效？ A：是的。修改人设后需点击「发布」才正式生效。只点「保存草稿」时，修改仅在调试窗可见，不影响线上设备。
Q2：全局人设会拼接到所有技能中吗？包括自定义技能？ A：是的，全局人设会自动拼接到该智能体下所有技能（系统技能 + 自定义技能）的 prompt 头部。
Q3：人设中可以写多长？有字数限制吗？ A：平台暂无硬性字数上限，但建议控制在 300-800 字。过长可能导致模型对核心设定的遵循度下降，且占用上下文窗口。
Q4：音色切换技能切换的音色什么时候会失效？ A：用户通过对话切换的音色在当前会话（session）内持续生效，并更改设备音色。下次建联时根据设备有无上行 role_code 判定使用人设音色还是设备音色；不上行 role_code 时设备音色生效（即切换完的音色生效）。
Q5：多个设备绑定同一智能体，可以使用不同音色吗？ A：可以。在设备管理中为每台设备单独设置音色，设备音色是设备实际生效的音色，优先级高于人设音色。
Q5.1：修改人设音色后，会影响哪些设备？调试窗会跟着变吗？ A：分两种情况：
- 新注册设备：修改人设音色后，之后该产品新注册的设备，其设备音色会默认填充为注册当时的人设音色。
- 存量设备：已注册的设备不受影响，设备音色维持原值。
- 调试窗：不会跟随变化。调试窗不上行
role_code，人设音色在调试阶段不生效，因此修改人设音色不会改变调试窗当前使用的音色。
Q6：系统变量 ${location} 取值来源是什么？ A：优先使用设备端主动上传的地理位置——WS 建联时通过 location 字段上行城市，或通过事件上报通路 CLIENT_UPDATE_COORDINATES_CONTEXT（上报经纬度更新城市地址）；若设备未上传，则使用 IP 解析结果。
相关协议：上行事件 CLIENT_UPDATE_COORDINATES_CONTEXT、建联参数 location（WebSocket 协议）。
Q7：全局人设中可以引用自定义变量吗？ A：可以。通过端侧上行事件 CLIENT_UPDATE_CHAT_CONTEXT 传入自定义字段后，在人设中用 ${(extInfo.[字段名])!""} 格式引用。
⚠ 使用此功能需向 JoyInside 团队 yangyu.270 沟通（可请对接人帮忙联系），配置白名单权限。