Py-Xiaozhi 项目架构

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

核心架构

核心架构：容器编排 → 插件 / 协议 / 音频 / 界面

模块详情

src/bootstrap/

• ServiceContainer 编排启动与关闭
• 会话、健康检查、插件装配拆分
• 按依赖加载各插件

src/core/

• EventBus 事件通信
• 设备状态机与协议管理
• 任务与资源统一回收

src/plugins/

• 插件生命周期与依赖隔离
• 音频、UI、快捷键、唤醒词、MCP

src/protocols/

• WebSocket / MQTT 双协议
• 实时音频与文本消息

src/audio_codecs/

• Opus 编解码与重采样
• 设备热刷新与热重载

src/audio_processing/

• 离线唤醒词检测
• 复用麦克风 PCM 流

src/mcp/

• 音乐、摄像头、截图、音量等工具
• 容器注入注册；支持外挂插件
• 摄像头支持 USB 与树莓派 CSI

src/ui/

• GUI / CLI / GPIO 统一 ViewPort
• PySide6 + QML 主界面与设置
• 冷启动不抢前台（macOS）

src/activation/

• 设备激活与 OTA
• 独立激活窗口

src/logging/

• 分级日志与文件轮转
• 显式初始化

src/utils/

• 配置管理（按名匹配音频设备）
• 资源路径与跨平台工具

技术栈

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快捷键

架构特点

事件驱动

模块之间用 EventBus 通信，少直接耦合

异步架构

asyncio + qasync，适合实时语音

多界面

GUI / CLI / GPIO 同一套 ViewPort

状态机

待命 / 聆听 / 说话 状态清晰切换

插件化

音频、MCP、UI、快捷键、唤醒词可插拔

跨平台

Windows / macOS / Linux（含树莓派）