Py-Xiaozhi Project Architecture
A Python-based Xiaozhi voice assistant client with modular design, supporting multiple communication protocols and device integrations
Core Architecture
核心架构图：展示了 ServiceContainer、EventBus、插件管理器、通信协议层、音频编解码、视图层等模块的关系及数据流向
Module Details
src/bootstrap/
- ServiceContainer 聚合核心服务，统一管理生命周期
- PluginContext/PluginCommands 适配器暴露受控 API
- 按依赖拓扑排序加载 Audio/WakeWord/UI/Shortcuts/MCP 插件
src/core/
- EventBus 实现组件间解耦通信，支持异步事件处理
- StateManager 维护 DeviceState/ListeningMode 状态机
- ProtocolManager 封装协议连接与消息发送
- TaskManager 异步任务生命周期管理
- ResourcePool 统一资源注册与逆序释放
src/plugins/
- PluginManager 拓扑排序依赖，统一 setup/start/stop/shutdown
- AudioPlugin 管理音频编解码与音乐播放控制
- UIPlugin 支持 GUI/CLI 双模式，ShortcutsPlugin 处理快捷键
src/protocols/
- Protocol 抽象定义音频/文本/控制消息接口
- WebSocket/MQTT 双实现，支持实时音频通道
- 广播 AUDIO_CHANNEL_* 事件驱动状态变更
src/audio_codecs/
- AudioCodec 组合设备管理、Opus编解码、重采样模块
- 输入流重采样到 16kHz 单声道 Opus 编码
- 支持热重载音频设备与低延迟播放缓冲
src/audio_processing/
- WakeWordDetector 基于 sherpa-onnx 关键词检测
- 重用 AudioCodec PCM 流，异步队列检测循环
- 检测结果触发 start_listening/abort_speaking
src/mcp/
- McpServer 实现 MCP 规范与 JSON-RPC 2.0
- @mcp_tool 装饰器自动发现并注册工具函数
- 内置工具：音乐/摄像头/截图/应用管理/天气/音量
src/ui/
- PySide6/QML 实现 GUI，CLIViewManager 实现命令行界面
- EventBridge 连接 Python 与 QML 的双向通信
- 系统托盘、情绪表情、设置窗口均由 EventBus 驱动
src/activation/
- ActivationService 处理设备激活与 OTA 信息
- efuse.json 缓存序列号/HMAC 等设备指纹
- 提供激活状态 API 给 UI 显示
src/logging/
- 独立日志子系统，支持分级过滤和格式化
- 自定义 Handler 支持文件轮转和控制台输出
- 日志过滤器按模块/级别精细控制
src/utils/
- ConfigManager 管理配置文件，支持点记法访问和动态更新
- ResourceFinder 解析资源路径，AudioDeviceManager 探测设备
- OpusLoader 跨平台 Opus 库加载，优先内置库
Technology Stack
Python
>= 3.10
AsyncIO
异步编程框架
PySide6
Qt6 GUI框架
QML/QtQuick
声明式UI
qasync
Qt异步集成
uv
包管理器
Sherpa-ONNX
唤醒词检测
OpusLib
音频编解码
SoXR
高质量重采样
SoundDevice
音频设备管理
WebSockets
实时通信协议
MQTT
IoT消息传输
MCP Protocol
模型上下文协议
EventBus
事件驱动架构
Quartz
macOS快捷键
Architecture Features
EventBus 事件驱动
基于发布-订阅模式的事件总线，解耦模块间通信，支持异步事件处理和热重载
异步架构
全面采用 asyncio + qasync 异步编程，支持高并发处理和实时音频流
MVVM 视图层
PySide6 + QML 声明式 UI，Model-View-ViewModel 架构，EventBridge 连接 Python 与 QML
状态机模式
设备状态管理采用状态机模式 (IDLE/LISTENING/SPEAKING)，清晰的状态转换和错误恢复
插件化生态
PluginManager 统一管理插件生命周期，支持 Audio/MCP/UI/Shortcuts/WakeWord 等核心插件
跨平台兼容
支持 Windows/macOS/Linux，快捷键采用 Quartz (macOS) / pynput (其他) 双后端