JoyInside 接入手册

主题

运营平台高级功能 ​

跑通第 3 章 + 场景扩展后，你可能还需要在运营平台配置一些高级功能：复刻专属音色、配置交互策略（开场白/静默推送）、设置情绪、传自定义变量。

本章讲这些运营平台侧的配置能力。它们不涉及端侧协议改动，是在运营平台配置后生效的。A2A 协议与自定义技能见 第7章 §7.1，AI 角色管理接口见 附录 A.4。

1 音色复刻 ​

通过「音色库」上传一段语音，快速复刻成"专属音色"，在应用或设备中直接使用，打造符合品牌气质的声音。

复刻流程 ​

步骤要点
Step 1 进入音色库资源管理 > 音色库 > 新建
Step 2 上传语音单段音频，时长 3~15 秒，需整段连续音频（不能有较长停顿静音）；上传后可下载原音频或删除重传
Step 3 填写信息与授权音色名称（同企业内唯一，可与系统音色同名，以"音色类型"区分）；勾选"我已获得录音素材的合法授权"（未勾选无法提交）
Step 4 复刻并保存点"确定"发起复刻；完成后支持试听/编辑/删除（系统内置音色不可编辑不可删除；删除前确认未被应用或设备使用，被占用无法删除）
Step 5 在应用与设备中使用应用管理 > 配置详情 > 音色选择框（系统与自定义统一展示，直接切换）；设备管理 > 新建/编辑设备同样可选

建议先在在线调试中体验对话效果，再决定是否发布。

音色使用位置 ​

位置说明
应用配置应用 > 配置详情 > 音色（默认音色）
设备配置设备管理 > 新建/编辑 > 音色（单设备覆盖应用默认）

⚠ 切换音色后，已在对话中的设备需重建 WebSocket 连接才能生效（见 第9章 §9.6）。

音色列表接口 ​

小程序可通过接口查询音色列表（/soulmate/timbre/findAllByVendorId），详见 附录 A.5 音色。

2 交互策略 ​

应用创建/编辑时，可配置三类交互策略：

2.1 开场白 ​

首次建立连接时主动下发的问候语。

配置项说明
是否开启创建/编辑应用时，【是否开启开场白】选"开"才能编辑
轮播话术支持轮播，最多 5 条
示例"你好！今天有什么有趣的事情吗?"

⚠ 调试工具中开场白不播放，可能是建联后未收音触发——调试窗左边有"录音按钮"，开启后收到音才会播放开场白（端到端模式，语音入语音出）。见 第9章 §9.6。

2.2 静默消息推送 ​

对话过程中用户保持沉默一段时间后，设备自动向用户推送唤醒信息，重新激活交互。

配置项说明
是否开启【是否开启静默推送】选"开"才能编辑
提示词系统内置，暂不支持自定义，但允许在静默推送提示词中拼接全局人设信息，使推送符合人设
时段控制最多 5 组控制规则；推送时间段（如 7:00-20:00 才开启）
时间间隔静默推送时间阈值（沉默超过该阈值启动推送）

2.3 事件反馈 ​

通过变量引用，让 AI 根据不同输入动态生成个性化回复。在应用配置中开启，配合自定义变量 extInfo 使用（见 §7.4）。

3 情绪选择与自定义 ​

设备可通过情绪策略，在对话中表达不同情绪。情绪通过 CALL_SKILL_EVENT 事件的 args.EMOTION 字段下发。

3.1 开启情绪策略 ​

在应用编辑页面开启情绪策略后，设备对话时会收到情绪事件。

查看开启情绪策略截图(应用编辑页 > 情绪策略开关)

开启情绪策略

3.2 系统内置情绪（7 种基础） ​

情绪EMOTION
愤怒angry_1
恐惧fear_1
开心happy_1
厌恶hate_1
平静peace_1
悲伤sorrowful_1
震惊shock_1
查看系统内置情绪截图(应用编辑页 > 系统内置情绪列表)

系统内置情绪

3.3 自定义情绪（23 种） ​

自定义情绪的范围不超出这 23 种。

情绪EMOTION情绪EMOTION
愤怒angry_1好奇inquisitive_1
担忧anxious_1平静peace_1
谴责blamed_1伤心sad_1
疑惑confused_1震惊shock_1
撒娇coquetry_1害羞shy_1
失望disappoint_1厌倦sick_1
鄙视disdainful_1悲伤sorrowful_1
兴奋exciting_1委屈wronged_1
期待expect_1摇头disagree_1
恐惧fear_1点头nod_1
开心happy_1
厌恶hate_1
犹豫hesitate_1
查看自定义情绪配置截图(应用编辑页 > 自定义情绪)

自定义情绪配置

3.4 情绪事件示例 ​

情绪事件示例(点击展开)
json
{
    "code": 200,
    "msg": "Event success",
    "requestId": "d45ed439-3fab-4b0d-a6ab-a4662e505d96",
    "contentType": "EVENT",
    "content": {
        "roundId": "d45ed439-3fab-4b0d-a6ab-a4662e505d96_141008_7",
        "eventType": "CALL_SKILL_EVENT",
        "eventData": {
            "msg": "技能调用事件",
            "data": {
                "args": {
                    "EMOTION": "exciting_1"
                },
                "intentClassify": "其他指令"
            },
            "type": "CALL_SKILL_EVENT"
        }
    }
}

设备端收到情绪事件后，可根据 EMOTION 值驱动双目屏幕表情、指示灯等硬件表现对应情绪。

4 自定义变量 extInfo（非标准能力） ​

⚠ 非标准能力：extInfo 不推荐常规使用，仅在确有动态上下文需求时使用。需向 JoyInside 运营团队申请权限。

对话链路中，支持端侧在请求时自定义传入扩展信息，并在提示词中按固定格式取用。

提示词取用格式 ​

在提示词内需要插入的位置，按以下格式撰写即可渲染：

${(extInfo.[字段名])!""}

多层级：

${(extInfo.app1.key1)!""}

示例（下棋场景取对手信息）：

${(extInfo.chessAnalysis.opponent)!""}

上行事件：主动更新对话上下文 ​

通过 CLIENT_UPDATE_CHAT_CONTEXT 事件更新对话上下文（短期记忆）：

json
{
  "mid": "1",
  "contentType": "ACTIVITY",
  "content": {
    "activityType": "CLIENT_UPDATE_CHAT_CONTEXT",
    "effectiveTimeMinutes": 5,
    "kvData": {
      "自定义字段名": "自定义值"
    }
  }
}
字段说明
effectiveTimeMinutes记忆时长（分钟），取值范围 1~1440
kvData自定义扩展信息，在提示词中用 ${extInfo.字段名} 取用

服务端收到后，下发 CLIENT_CHAT_CONTEXT_RECEIVED 下行事件确认：

json
{
  "code": 200,
  "msg": "Activity success",
  "contentType": "EVENT",
  "content": {
    "roundId": "1_3",
    "activityType": "CLIENT_CHAT_CONTEXT_RECEIVED",
    "activityData": {}
  }
}

extInfo 与 CLIENT_UPDATE_CHAT_CONTEXT 配合：端侧按需上报上下文 → 提示词用 ${extInfo.字段} 取用 → 智能体结合动态信息生成个性化回复。也作为 A2A 接口的 ext_info 透传字段。