4.3 重要参数介绍

本节把贯穿全程的 5 个核心标识集中讲清：它们是什么、为什么重要、去哪看详情。

这 5 个参数是 JoyInside 协议的「身份证体系」，排查问题时几乎都要用到。建议建连前先建立全局认知。

五大核心参数速查

参数	是什么	出现在哪	关键约束
sessionId	会话 ID，关联对话上下文（短期记忆）	WS 建连参数	可一次建连新设，可多次建连复用
mid	上行消息唯一标识	每条上行事件	每条上行事件独立 mid
uid	用户唯一标识，关联长期记忆与聊天报告	WS 建连 / 小程序绑定	≤128 字节，必须真实
requestId	一次 WebSocket 建连全周期唯一标识	WS 建连参数	一次 WS 建连一个 requestId
roundId	对话轮次标识，下行事件中存在，一次建连后的某一轮次对话	下行事件	生成规则： requestId + 时间戳 + 轮次

参数关系图

sessionId / uid 可跨多次 WS 建连(requestId)复用;roundId 是建连内单轮标识,一轮内每条上行用 mid 标识。

sessionId（会话 ID）

含义：与对话上下文关联，作为短期记忆的重要配置。同一个 sessionId 下的多轮对话，服务端会保持上下文连续。

生命周期：

• 可在一次建连中新设置
• 也可多次建连复用（推荐）

复用推荐：多轮对话场景推荐复用同一 sessionId，保持上下文连续。若每轮都换新 sessionId，对话会「失忆」，服务端按新会话处理。

场景：迁移/续聊/上下文记忆依赖此参数。例如用户中断对话后重新建连，复用原 sessionId 可让对话接续之前的上下文。

mid（消息 ID）

含义：上行消息的唯一标识。每条上行事件（音频帧、心跳、打断、更新配置等）都带独立的 mid。

用途：

• 端到端消息追踪
• 服务端去重（避免同一消息被重复处理）

生成方式：UUID（建议用 uuid.uuid4() 生成）。

uid（用户 ID）

含义：用户唯一标识（如京东用户 pin），关联长期记忆与聊天报告。

⚠ 关键约束

约束	说明
≤128 字节	uid 长度不超过 128 字节，超长会被服务端拒绝
必须真实	禁用固定值（如 123456），否则不同用户的记忆会混在一起
一致性	传了就必须一直传，禁止值与 null 混着来。 如接入有声书技能，无论是否关联用户场景，ws建连以及有声书的全部上行事件，uid要么全部增加，要么全部不增加，且uid必须保持一致。

uid 与设备绑定

一台设备（botId）可绑定一个 uid，绑定后该设备对话归属到该用户名下，产生长期记忆与聊天报告。绑定/解绑走小程序接口，详见 4.2 设备注册与绑定 与 附录 A.6 用户绑定。

uid 在 WS 建连时的传递

WS 建连与上行事件里也可带 uid（非必传）：

• 不传：服务端按匿名会话处理（无长期记忆）
• 传：必须始终传同一真实 uid

requestId（WS 请求 ID）

含义：一次 WebSocket 建连全周期的唯一标识。一个 requestId 对应该次 WS 建连的整个生命周期。

用途：

• 标识一次完整的 WS 建连
• 是 roundId 的组成部分
• 排查 WebSocket 层问题时用 requestId 收窄范围

生成方式：UUID（建议用 uuid.uuid4() 生成）。

requestId 与 roundId 的区别：requestId 是「一次建连」，roundId 是「一次建连里的一轮对话」。一次 WS 建连可包含多轮对话（多个 roundId）。

roundId（对话轮次 ID）

组成：requestId + 时间戳 + 轮次

含义：代表一次对话轮次（用户说一次 + 助手回一次），下行事件中存在。

排查价值（重要）

roundId 是端到端排查的主键。排查单轮对话问题时，用 roundId 可：

• 精确定位某一轮的事件链路（ASR/LLM/TTS 各阶段）
• 不被同一次 WS 建连里的其他轮次干扰

roundId 示例：d45ed439-3fab-4b0d-a6ab-a4662e505d96_141008_7

• 前缀 d45ed439-... 是 requestId
• 中间 141008 是时间戳
• 末尾 7 是轮次序号

roundId 的端到端排查用法详见 4.6 服务端链路设计（进阶阅读）。排查粒度：roundId ≻ requestId ≻ botId。

下一步

• 理解语音对话协议:4.4 WebSocket语音通道
• 理解事件协议明细：附录 B.3
• 用户绑定接口：附录 A.6 用户绑定