Py-Xiaozhi 项目架构

基于 Python 实现的小智语音客户端，采用模块化设计，支持多种通信协议和设备集成

核心架构

核心架构图：展示了应用核心、插件管理器、MCP服务器、通信协议层、音频编解码、音频处理、IoT设备管理等模块的关系及数据流向

模块详情

src/application.py

应用主类，单例模式管理全局状态
异步事件驱动架构，基于asyncio
设备状态机(IDLE/LISTENING/SPEAKING)
统一任务池管理和生命周期控制
插件化架构，通过PluginManager协调各模块

src/plugins/

插件管理器，按优先级排序注册插件
统一生命周期管理(setup/start/stop/shutdown)
事件广播机制(协议连接、JSON消息、音频数据)
插件隔离，错误不传播
包含Audio、MCP、IoT、UI、WakeWord等核心插件

src/mcp/

基于MCP协议的工具服务器
丰富的工具生态(系统、日历、音乐、地图、八字等)
Property/Method抽象，支持异步调用
类型安全的参数验证和默认值处理
工具分类管理(camera/calendar/timer/music等)

src/protocols/

抽象Protocol基类，定义统一接口
WebSocket和MQTT双协议实现
WSS/TLS加密传输，自动重连机制
支持文本/音频/IoT/MCP消息类型
连接状态管理和错误回调

src/audio_codecs/

Opus编解码器(16kHz编码/24kHz解码)
WebRTC AEC回声消除处理器
SoXR实时音频重采样(支持任意采样率)
智能声道转换(下混/上混)
设备原生格式自适应
低延迟流式缓冲(5ms处理)
观察者模式解耦音频监听器

src/audio_processing/

基于Sherpa-ONNX的唤醒词检测
支持多唤醒词和拼音匹配
VAD语音活动检测
实时音频流处理
异步事件通知机制

src/views/

PyQt5 GUI界面(设置窗口/激活窗口)
系统托盘和全局快捷键支持
音频设备/摄像头/唤醒词配置界面
异步UI更新和线程安全
基础窗口组件和混入类

src/iot/

Thing基类定义设备抽象
Property/Method异步属性和方法
ThingManager统一设备管理
状态增量更新和并发获取
支持灯光/音量/定时器等设备类型

src/utils/

ConfigManager分层配置管理
点记法访问配置(如AUDIO_DEVICES.input_device_id)
设备指纹生成和激活管理
统一日志系统和资源查找
音量控制和跨平台工具函数

src/core/

OTA在线更新模块
系统初始化器
版本检查和升级管理

技术栈

Python

3.9-3.12

AsyncIO

异步编程框架

PyQt5

GUI框架

qasync

Qt异步集成

Sherpa-ONNX

语音识别引擎

WebRTC AEC

WebRTC音频处理模块

OpusLib

音频编解码

SoXR

高质量重采样

SoundDevice

音频设备管理

WebSockets

实时通信协议

MQTT

IoT消息传输

MCP Protocol

模型上下文协议

Cryptography

加密安全库

Thing抽象

IoT设备抽象

JSON-RPC

远程过程调用

架构特点

单例模式

应用核心采用线程安全的单例模式，保证全局唯一实例和状态一致性

异步架构

全面采用asyncio异步编程，支持高并发处理和实时音频流

资源管理

中央化资源管理器，智能依赖跟踪和优雅清理机制

状态机模式

设备状态管理采用状态机模式，清晰的状态转换和错误恢复

插件化生态

MCP工具和IoT设备采用插件化设计，支持热插拔和动态扩展

跨平台兼容

支持Windows、macOS、Linux多平台，智能特性检测和优雅降级