XiaoZhi Protols 小智协议

该项目用于统一不同语言下一致的小智交互协议，根据xiaozhi-esp32的protocols构造客户端的交互流程测试

使用方法

使用uv安装项目uv venv && uv sync, tests/instances.py中更改配置参数，如MAC_ADDR等， 通过pytest -s -v --tb=short对全流程进行测试，可以根据不通过的测试查询原因

已经上传的report.html包含了大部分正确的结果和对应日志内容, 交互返回的内容也可以通过basemodel查看定义。

测试实例说明

主要分为两个通信方式, mqtt+udp以及websocket, 需要根据ota信息确定可以使用哪种方式，测试相关代码和文件都位于tests目录下

Instances

定义设备配置信息和通信时需要暂存的所有内容

OTA

测试的Fixture步骤, 需要通过OTA_URL获取ota_info, 分配给后续两种通信协议测试的地址和端口。

MQTT+ UDP / Websocket

两种通信协议有稍许差别，但是交互顺序是完全一致的，根据测试函数来看

Connection

建立连接，参考test_mqtt_connection_mcp和test_handshake

Hello

发起通信，参考test_hello

MCP Declare

MCP主要都是使用JSON-RPC2.0规范进行传输，查看basemodel/jsonrpc或者mcp标准来确定范式。 此处两种通信有些不同

• mqtt+tcp会在建立连接后服务器会主动向设备MCP问询相关功能
• websocket则是hello信息发送后才接收MCP问询。

相同处是都是由服务器主动问询，定义好回复即可，在通信阶段如果大模型判断有必要则会通过tools/call来请求设备返回结果。查看test_start_listen_mcp和basemodel/server/request。

Listen

声明收音，查看test_start_listen和test_start_listen_mcp, 该阶段向服务器发送处于正在收音的状态。

Chat

开始对话，查看test_talk，每次对话来回都以tts stop结尾。

注意

1. 在udp传输下只要是realtime模式必须持续传入listen数据, websocket可以等待。
2. 两种通信方式对音频帧的构造是不同的，可以通过查看basemodel/audio确认。
3. 音频的传输格式只支持opus，不同技术栈下自行实现。

Goodbye

会话结束，查看test_goodbye，一般由服务器主动发起，在音频中明确传达了结束/再见/退下等意图时触发。

注意

• mqtt+udp的断开只有udp断开, mqtt会保持连接
• websocket的断开会断开长连接

时序图

MQTT+UDP 通信时序图

sequenceDiagram
    participant Device as 设备端
    participant MQTT as MQTT服务器
    participant UDP as UDP服务器

    Note over Device,UDP: 1. 连接阶段
    Device->>MQTT: 连接MQTT服务器
    MQTT-->>Device: 连接成功
    Device->>MQTT: 订阅设备P2P消息
    
    Note over Device,UDP: 2. MCP初始化阶段
    MQTT->>Device: MCP初始化请求 (tools/initialize)
    Device-->>MQTT: MCP初始化响应
    MQTT->>Device: MCP工具列表请求 (tools/list)
    Device-->>MQTT: MCP工具列表响应

    Note over Device,UDP: 3. Hello握手阶段
    Device->>MQTT: Hello消息 (包含设备信息)
    MQTT-->>Device: Hello响应 (UDP地址/端口/加密信息)

    Note over Device,UDP: 4. Listen声明阶段
    Device->>MQTT: Listen消息 (state: start, mode: realtime)
    Device->>UDP: 建立UDP连接
    UDP-->>Device: UDP连接确认

    Note over Device,UDP: 5. Chat对话阶段
    loop 多轮对话
        Device->>UDP: 发送音频数据 (opus编码)
        MQTT->>Device: TTS开始消息
        
        opt MCP工具调用
            MQTT->>Device: MCP工具调用请求
            Device-->>MQTT: MCP工具响应
        end
        
        UDP->>Device: 返回音频数据
        MQTT->>Device: TTS结束消息
    end
    
    Note over Device,UDP: 6. Goodbye结束阶段
    alt 设备主动结束
        Device->>MQTT: Goodbye消息
    else 服务器主动结束
        MQTT->>Device: Goodbye消息
    end
    Device->>UDP: 关闭UDP连接

Loading

WebSocket 通信时序图

sequenceDiagram
    participant Device as 设备端
    participant Server as Websocket服务器

    Note over Device,Server: 1. 连接阶段
    Device->>Server: WebSocket握手连接
    Server-->>Device: 连接成功

    Note over Device,Server: 2. Hello握手阶段
    Device->>Server: Hello消息 (包含设备信息)
    Server-->>Device: Hello响应 (包含会话ID)

    Note over Device,Server: 3. Listen声明阶段
    Device->>Server: Listen消息 (state: start, mode: realtime)
    
    Note over Device,Server: 4. MCP初始化阶段
    Server->>Device: MCP初始化请求 (tools/initialize)
    Device-->>Server: MCP初始化响应
    Server->>Device: MCP工具列表请求 (tools/list)
    Device-->>Server: MCP工具列表响应

    Note over Device,Server: 5. Chat对话阶段
    loop 音频数据传输
        Device->>Server: 发送音频数据 (二进制帧)
        Server->>Device: TTS开始消息
        opt MCP工具调用
            Server->>Device: MCP工具调用请求
            Device-->>Server: MCP工具响应
        end
        Server->>Device: 返回音频数据 (二进制帧)
        Server->>Device: TTS结束消息
    end
    
    Note over Device,Server: 6. Goodbye结束阶段
    alt 设备主动结束
        Device->>Server: Goodbye消息
    else 服务器主动结束
        Server->>Device: Goodbye消息
    end
    Device->>Server: 关闭WebSocket连接

Loading