[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-huangjunsen0406--py-xiaozhi":3,"tool-huangjunsen0406--py-xiaozhi":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",150037,2,"2026-04-10T23:33:47",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":76,"owner_website":79,"owner_url":80,"languages":81,"stars":116,"forks":117,"last_commit_at":118,"license":119,"difficulty_score":32,"env_os":120,"env_gpu":121,"env_ram":122,"env_deps":123,"category_tags":132,"github_topics":135,"view_count":10,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":142,"updated_at":143,"faqs":144,"releases":174},2318,"huangjunsen0406\u002Fpy-xiaozhi","py-xiaozhi","A Python-based Xiaozhi AI for users who want the full Xiaozhi experience without owning specialized hardware.","py-xiaozhi 是一款基于 Python 开发的开源语音助手客户端，让用户无需购买专用硬件，即可在电脑或服务器上完整体验“小智”AI 的语音交互能力。它源自嵌入式项目 xiaozhi-esp32，成功将原本依赖特定芯片的功能移植到通用操作系统上，解决了普通用户和开发者因缺乏硬件而无法低成本试用或二次开发 AI 语音助手的痛点。\n\n这款工具非常适合希望探索 AI 语音技术的开发者、研究人员，以及想要个性化定制智能助手的极客用户。它不仅支持自然的语音对话、多模态图像识别和智能唤醒，还构建了丰富的 MCP 工具生态，涵盖日程管理、音乐播放、12306 查询甚至传统命理分析等实用功能。此外，py-xiaozhi 具备强大的 IoT 设备集成能力和高级音频处理技术（如回声消除、实时重采样），并提供了基于 PyQt5 的图形界面与命令行双模式，兼容 Windows、macOS 和 Linux 系统。其模块化架构与异步设计也为二次开发提供了极大便利，是入门 AI 语音应用开发的理想选择。","\u003Cp align=\"center\" class=\"trendshift\">\n  \u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F14130\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_readme_0dcd13139b79.png\" alt=\"Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Freleases\u002Flatest\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fhuangjunsen0406\u002Fpy-xiaozhi?style=flat-square&logo=github&color=blue\" alt=\"Release\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg?style=flat-square\" alt=\"License: MIT\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fstargazers\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fhuangjunsen0406\u002Fpy-xiaozhi?style=flat-square&logo=github\" alt=\"Stars\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Freleases\u002Flatest\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Ftotal?style=flat-square&logo=github&color=52c41a1&maxAge=86400\" alt=\"Download\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgitee.com\u002Fhuang-jun-sen\u002Fpy-xiaozhi\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitee-FF5722?style=flat-square&logo=gitee\" alt=\"Gitee\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002Fguide\u002F00_%E6%96%87%E6%A1%A3%E7%9B%AE%E5%BD%95.html\">\n    \u003Cimg alt=\"使用文档\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F使用文档-点击查看-blue?labelColor=2d2d2d\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n简体中文 | [English](README.en.md)\n\n## 项目简介\n\npy-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。\n本仓库是基于[xiaozhi-esp32](https:\u002F\u002Fgithub.com\u002F78\u002Fxiaozhi-esp32)移植\n\n## 演示\n\n- [Bilibili 演示视频](https:\u002F\u002Fwww.bilibili.com\u002Fvideo\u002FBV1HmPjeSED2\u002F#reply255921347937)\n\n![Image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_readme_d8afd1a53a13.png)\n\n## 功能特点\n\n### 🎯 核心AI功能\n\n- **AI语音交互**：支持语音输入与识别，实现智能人机交互，提供自然流畅的对话体验\n- **视觉多模态**：支持图像识别和处理，提供多模态交互能力，理解图像内容\n- **智能唤醒**：支持多种唤醒词激活交互，免去手动操作的烦恼（可配置开启）\n- **自动对话模式**：实现连续对话体验，提升用户交互流畅度\n\n### 🔧 MCP工具生态系统\n\n- **系统控制工具**：系统状态监控、应用程序管理、音量控制、设备管理等\n- **日程管理工具**：全功能日程管理，支持创建、查询、更新、删除事件，智能分类和提醒\n- **定时任务工具**：倒计时器功能，支持延时执行MCP工具，多任务并行管理\n- **音乐播放工具**：在线音乐搜索播放，支持播放控制、歌词显示、本地缓存管理\n- **12306查询工具**：12306铁路票务查询，支持车票查询、中转查询、列车路线查询\n- **搜索工具**：网络搜索和网页内容获取，支持必应搜索和智能内容解析\n- **菜谱工具**：丰富菜谱库，支持菜谱搜索、分类查询、智能推荐\n- **地图工具**：高德地图服务，支持地理编码、路径规划、周边搜索、天气查询\n- **八字命理工具**：传统八字命理分析，支持八字计算、婚姻分析、黄历查询\n- **摄像头工具**：图像捕获和AI分析，支持拍照识别和智能问答\n\n### 🏠 IoT设备集成\n\n- **设备管理架构**：基于Thing模式的统一设备管理，支持属性和方法的异步调用\n- **智能家居控制**：支持灯光、音量、温度传感器等设备控制\n- **状态同步机制**：实时状态监控，支持增量更新和并发状态获取\n- **可扩展设计**：模块化设备驱动，易于添加新设备类型\n\n### 🎵 高级音频处理\n\n- **多级音频处理**：支持Opus编解码、实时重采样\n- **语音活动检测**：VAD检测器实现智能打断，支持语音活动实时监控\n- **唤醒词检测**：基于Sherpa-ONNX的离线语音识别，支持多唤醒词和拼音匹配\n- **音频流管理**：独立输入输出流，支持流重建和错误恢复\n- **音频回声消除**：集成WebRTC音频处理模块，提供高质量的回声消除功能\n- **系统音频录制**：支持系统音频录制，实现音频环回处理\n\n### 🖥️ 用户界面\n\n- **图形化界面**：基于PyQt5的现代GUI，支持小智表情与文本显示，增强视觉体验\n- **命令行模式**：支持CLI运行，适用于嵌入式设备或无GUI环境\n- **系统托盘**：后台运行支持，集成系统托盘功能\n- **全局快捷键**：支持全局快捷键操作，提升使用便捷性\n- **设置界面**：完整的设置管理界面，支持配置自定义\n\n### 🔒 安全与稳定\n\n- **加密音频传输**：支持WSS协议，保障音频数据的安全性，防止信息泄露\n- **设备激活系统**：支持v1\u002Fv2双协议激活，自动处理验证码和设备指纹\n- **错误恢复**：完整的错误处理和恢复机制，支持断线重连\n\n### 🌐 跨平台支持\n\n- **系统兼容**：兼容Windows 10+、macOS 10.15+和Linux系统\n- **协议支持**：支持WebSocket和MQTT双协议通信\n- **多环境部署**：支持GUI和CLI双模式，适应不同部署环境\n- **平台优化**：针对不同平台的音频和系统控制优化\n\n### 🔧 开发友好\n\n- **模块化架构**：清晰的代码结构和职责分离，便于二次开发\n- **异步优先**：基于asyncio的事件驱动架构，高性能并发处理\n- **配置管理**：分层配置系统，支持点记法访问和动态更新\n- **日志系统**：完整的日志记录和调试支持\n- **API文档**：详细的代码文档和使用指南\n\n## 系统要求\n\n### 基础要求\n\n- **Python版本**：3.9 - 3.12\n- **操作系统**：Windows 10+、macOS 10.15+、Linux\n- **音频设备**：麦克风和扬声器设备\n- **网络连接**：稳定的互联网连接（用于AI服务和在线功能）\n\n### 推荐配置\n\n- **内存**：至少4GB RAM（推荐8GB+）\n- **处理器**：支持AVX指令集的现代CPU\n- **存储**：至少2GB可用磁盘空间（用于模型文件和缓存）\n- **音频**：支持16kHz采样率的音频设备\n\n### 可选功能要求\n\n- **语音唤醒**：需要下载Sherpa-ONNX语音识别模型\n- **摄像头功能**：需要摄像头设备和OpenCV支持\n\n## 请先看这里\n\n- 仔细阅读 [项目文档](https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002F) 启动教程和文件说明都在里面了\n- main是最新代码，每次更新都需要手动重新安装一次pip依赖防止我新增依赖后你们本地没有\n\n[从零开始使用小智客户端（视频教程）](https:\u002F\u002Fwww.bilibili.com\u002Fvideo\u002FBV1dWQhYEEmq\u002F?vd_source=2065ec11f7577e7107a55bbdc3d12fce)\n\n## 技术架构\n\n### 核心架构设计\n\n- **事件驱动架构**: 基于asyncio的异步事件循环，支持高并发处理\n- **分层设计**: 清晰的应用层、协议层、设备层、UI层分离\n- **单例模式**: 核心组件采用单例模式，确保资源统一管理\n- **插件化**: MCP工具系统和IoT设备支持插件化扩展\n\n### 关键技术组件\n\n- **音频处理**: Opus编解码、WebRTC回声消除、实时重采样、系统音频录制\n- **语音识别**: Sherpa-ONNX离线模型、语音活动检测、唤醒词识别\n- **协议通信**: WebSocket\u002FMQTT双协议支持、加密传输、自动重连\n- **配置系统**: 分层配置、点记法访问、动态更新、JSON\u002FYAML支持\n\n### 性能优化\n\n- **异步优先**: 全系统异步架构，避免阻塞操作\n- **内存管理**: 智能缓存、垃圾回收\n- **音频优化**: 5ms低延迟处理、队列管理、流式传输\n- **并发控制**: 任务池管理、信号量控制、线程安全\n\n### 安全机制\n\n- **加密通信**: WSS\u002FTLS加密、证书验证\n- **设备认证**: 双协议激活、设备指纹识别\n- **权限控制**: 工具权限管理、API访问控制\n- **错误隔离**: 异常隔离、故障恢复、优雅降级\n\n## 开发指南\n\n### 项目结构\n\n```\npy-xiaozhi\u002F\n├── main.py                     # 应用程序主入口（CLI参数处理）\n├── src\u002F\n│   ├── application.py          # 应用程序核心逻辑\n│   ├── audio_codecs\u002F           # 音频编解码器\n│   │   ├── aec_processor.py    # 音频回声消除处理器\n│   │   ├── audio_codec.py      # 音频编解码基础类\n│   │   └── system_audio_recorder.py  # 系统音频录制器\n│   ├── audio_processing\u002F       # 音频处理模块\n│   │   ├── vad_detector.py     # 语音活动检测\n│   │   └── wake_word_detect.py # 唤醒词检测\n│   ├── core\u002F                   # 核心组件\n│   │   ├── ota.py             # 在线更新模块\n│   │   └── system_initializer.py # 系统初始化器\n│   ├── display\u002F                # 显示界面抽象层\n│   ├── iot\u002F                    # IoT设备管理\n│   │   ├── thing.py           # 设备基类\n│   │   ├── thing_manager.py   # 设备管理器\n│   │   └── things\u002F            # 具体设备实现\n│   ├── mcp\u002F                    # MCP工具系统\n│   │   ├── mcp_server.py      # MCP服务器\n│   │   └── tools\u002F             # 各种工具模块\n│   ├── protocols\u002F              # 通信协议\n│   ├── utils\u002F                  # 工具函数\n│   └── views\u002F                  # UI视图组件\n├── libs\u002F                       # 第三方原生库\n│   ├── libopus\u002F               # Opus音频编解码库\n│   ├── webrtc_apm\u002F            # WebRTC音频处理模块\n│   └── SystemAudioRecorder\u002F   # 系统音频录制工具\n├── config\u002F                     # 配置文件目录\n├── models\u002F                     # 语音模型文件\n├── assets\u002F                     # 静态资源文件\n├── scripts\u002F                    # 辅助脚本\n├── requirements.txt            # Python依赖包列表\n└── build.json                  # 构建配置文件\n```\n\n### 开发环境设置\n\n```bash\n# 克隆项目\ngit clone https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi.git\ncd py-xiaozhi\n\n# 安装依赖\npip install -r requirements.txt\n\n# 代码格式化\n.\u002Fformat_code.sh\n\n# 运行程序 - GUI模式（默认）\npython main.py\n\n# 运行程序 - CLI模式\npython main.py --mode cli\n\n# 指定通信协议\npython main.py --protocol websocket  # WebSocket（默认）\npython main.py --protocol mqtt       # MQTT协议\n```\n\n### 核心开发模式\n\n- **异步优先**: 使用`async\u002Fawait`语法，避免阻塞操作\n- **错误处理**: 完整的异常处理和日志记录\n- **配置管理**: 使用`ConfigManager`统一配置访问\n- **测试驱动**: 编写单元测试，确保代码质量\n\n### 扩展开发\n\n- **添加MCP工具**: 在`src\u002Fmcp\u002Ftools\u002F`目录创建新工具模块\n- **添加IoT设备**: 继承`Thing`基类实现新设备\n- **添加协议**: 实现`Protocol`抽象基类\n- **添加界面**: 扩展`BaseDisplay`实现新的UI组件\n\n### 状态流转图\n\n```\n                        +----------------+\n                        |                |\n                        v                |\n+------+  唤醒词\u002F按钮  +------------+   |   +------------+\n| IDLE | -----------> | CONNECTING | --+-> | LISTENING  |\n+------+              +------------+       +------------+\n   ^                                            |\n   |                                            | 语音识别完成\n   |          +------------+                    v\n   +--------- |  SPEAKING  | \u003C-----------------+\n     完成播放 +------------+\n```\n\n## 贡献指南\n\n欢迎提交问题报告和代码贡献。请确保遵循以下规范：\n\n1. 代码风格符合PEP8规范\n2. 提交的PR包含适当的测试\n3. 更新相关文档\n\n## 社区与支持\n\n### 感谢以下开源人员\n>\n> 排名不分前后\n\n[Xiaoxia](https:\u002F\u002Fgithub.com\u002F78)\n[zhh827](https:\u002F\u002Fgithub.com\u002Fzhh827)\n[四博智联-李洪刚](https:\u002F\u002Fgithub.com\u002FSmartArduino)\n[HonestQiao](https:\u002F\u002Fgithub.com\u002FHonestQiao)\n[vonweller](https:\u002F\u002Fgithub.com\u002Fvonweller)\n[孙卫公](https:\u002F\u002Fspace.bilibili.com\u002F416954647)\n[isamu2025](https:\u002F\u002Fgithub.com\u002Fisamu2025)\n[Rain120](https:\u002F\u002Fgithub.com\u002FRain120)\n[kejily](https:\u002F\u002Fgithub.com\u002Fkejily)\n[电波bilibili君](https:\u002F\u002Fspace.bilibili.com\u002F119751)\n[赛搏智能](https:\u002F\u002Fshop115087494.m.taobao.com\u002F?refer=https%3A%2F%2Fm.tb.cn%2F&ut_sk=1.WMelxbgDQWkDAJ1Rq9Pn7DCD_21380790_1757337352472.Copy.shop&suid=0E25E948-651D-46E0-8E89-5C8CB03B4F56&shop_navi=shopindex&sourceType=shop&shareUniqueId=33038752403&un=d22c5ceda82844ab8bd7bab98ffeb263&share_crt_v=1&un_site=0&spm=a2159r.13376460.0.0&sp_tk=dkRKUjRKUWo2ZHY%3D&bc_fl_src=share-1041250486811064-2-1&cpp=1&shareurl=true&short_name=h.SaBKVHytsCKIPNS&bxsign=scdGtSe264e_qkFQBh0rXCkF-Mrb_s6t35EnpVBBU5dsrd-J24c-_rn_PhJiXRk0hg2hjGoAm0L7j2UQg27OIH_6gZkbhKDyLziD2cy4pDf8sC3KmqrF55TXP3USZaPTw_-&app=weixin)\n\n### 赞助支持\n\n\u003Cdiv align=\"center\">\n  \u003Ch3>感谢所有赞助者的支持 ❤️\u003C\u002Fh3>\n  \u003Cp>无论是接口资源、设备兼容测试还是资金支持，每一份帮助都让项目更加完善\u003C\u002Fp>\n  \n  \u003Ca href=\"https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002Fsponsors\u002F\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F查看-赞助者名单-brightgreen?style=for-the-badge&logo=github\" alt=\"赞助者名单\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002Fsponsors\u002F\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F成为-项目赞助者-orange?style=for-the-badge&logo=heart\" alt=\"成为赞助者\">\n  \u003C\u002Fa>\n\u003C\u002Fdiv>\n\n## 项目统计\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_readme_8035e9df79bd.png)](https:\u002F\u002Fwww.star-history.com\u002F#huangjunsen0406\u002Fpy-xiaozhi&Date)\n\n## 许可证\n\n[MIT License](LICENSE)\n","\u003Cp align=\"center\" class=\"trendshift\">\n  \u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F14130\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_readme_0dcd13139b79.png\" alt=\"Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Freleases\u002Flatest\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fhuangjunsen0406\u002Fpy-xiaozhi?style=flat-square&logo=github&color=blue\" alt=\"Release\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg?style=flat-square\" alt=\"License: MIT\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fstargazers\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fhuangjunsen0406\u002Fpy-xiaozhi?style=flat-square&logo=github\" alt=\"Stars\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Freleases\u002Flatest\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Ftotal?style=flat-square&logo=github&color=52c41a1&maxAge=86400\" alt=\"Download\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgitee.com\u002Fhuang-jun-sen\u002Fpy-xiaozhi\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitee-FF5722?style=flat-square&logo=gitee\" alt=\"Gitee\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002Fguide\u002F00_%E6%96%87%E6%A1%A3%E7%9B%AE%E5%BD%95.html\">\n    \u003Cimg alt=\"使用文档\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F使用文档-点击查看-blue?labelColor=2d2d2d\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n简体中文 | [English](README.en.md)\n\n## 项目简介\n\npy-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。\n本仓库是基于[xiaozhi-esp32](https:\u002F\u002Fgithub.com\u002F78\u002Fxiaozhi-esp32)移植\n\n## 演示\n\n- [Bilibili 演示视频](https:\u002F\u002Fwww.bilibili.com\u002Fvideo\u002FBV1HmPjeSED2\u002F#reply255921347937)\n\n![Image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_readme_d8afd1a53a13.png)\n\n## 功能特点\n\n### 🎯 核心AI功能\n\n- **AI语音交互**：支持语音输入与识别，实现智能人机交互，提供自然流畅的对话体验\n- **视觉多模态**：支持图像识别和处理，提供多模态交互能力，理解图像内容\n- **智能唤醒**：支持多种唤醒词激活交互，免去手动操作的烦恼（可配置开启）\n- **自动对话模式**：实现连续对话体验，提升用户交互流畅度\n\n### 🔧 MCP工具生态系统\n\n- **系统控制工具**：系统状态监控、应用程序管理、音量控制、设备管理等\n- **日程管理工具**：全功能日程管理，支持创建、查询、更新、删除事件，智能分类和提醒\n- **定时任务工具**：倒计时器功能，支持延时执行MCP工具，多任务并行管理\n- **音乐播放工具**：在线音乐搜索播放，支持播放控制、歌词显示、本地缓存管理\n- **12306查询工具**：12306铁路票务查询，支持车票查询、中转查询、列车路线查询\n- **搜索工具**：网络搜索和网页内容获取，支持必应搜索和智能内容解析\n- **菜谱工具**：丰富菜谱库，支持菜谱搜索、分类查询、智能推荐\n- **地图工具**：高德地图服务，支持地理编码、路径规划、周边搜索、天气查询\n- **八字命理工具**：传统八字命理分析，支持八字计算、婚姻分析、黄历查询\n- **摄像头工具**：图像捕获和AI分析，支持拍照识别和智能问答\n\n### 🏠 IoT设备集成\n\n- **设备管理架构**：基于Thing模式的统一设备管理，支持属性和方法的异步调用\n- **智能家居控制**：支持灯光、音量、温度传感器等设备控制\n- **状态同步机制**：实时状态监控，支持增量更新和并发状态获取\n- **可扩展设计**：模块化设备驱动，易于添加新设备类型\n\n### 🎵 高级音频处理\n\n- **多级音频处理**：支持Opus编解码、实时重采样\n- **语音活动检测**：VAD检测器实现智能打断，支持语音活动实时监控\n- **唤醒词检测**：基于Sherpa-ONNX的离线语音识别，支持多唤醒词和拼音匹配\n- **音频流管理**：独立输入输出流，支持流重建和错误恢复\n- **音频回声消除**：集成WebRTC音频处理模块，提供高质量的回声消除功能\n- **系统音频录制**：支持系统音频录制，实现音频环回处理\n\n### 🖥️ 用户界面\n\n- **图形化界面**：基于PyQt5的现代GUI，支持小智表情与文本显示，增强视觉体验\n- **命令行模式**：支持CLI运行，适用于嵌入式设备或无GUI环境\n- **系统托盘**：后台运行支持，集成系统托盘功能\n- **全局快捷键**：支持全局快捷键操作，提升使用便捷性\n- **设置界面**：完整的设置管理界面，支持配置自定义\n\n### 🔒 安全与稳定\n\n- **加密音频传输**：支持WSS协议，保障音频数据的安全性，防止信息泄露\n- **设备激活系统**：支持v1\u002Fv2双协议激活，自动处理验证码和设备指纹\n- **错误恢复**：完整的错误处理和恢复机制，支持断线重连\n\n### 🌐 跨平台支持\n\n- **系统兼容**：兼容Windows 10+、macOS 10.15+和Linux系统\n- **协议支持**：支持WebSocket和MQTT双协议通信\n- **多环境部署**：支持GUI和CLI双模式，适应不同部署环境\n- **平台优化**：针对不同平台的音频和系统控制优化\n\n### 🔧 开发友好\n\n- **模块化架构**：清晰的代码结构和职责分离，便于二次开发\n- **异步优先**：基于asyncio的事件驱动架构，高性能并发处理\n- **配置管理**：分层配置系统，支持点记法访问和动态更新\n- **日志系统**：完整的日志记录和调试支持\n- **API文档**：详细的代码文档和使用指南\n\n## 系统要求\n\n### 基础要求\n\n- **Python版本**：3.9 - 3.12\n- **操作系统**：Windows 10+、macOS 10.15+、Linux\n- **音频设备**：麦克风和扬声器设备\n- **网络连接**：稳定的互联网连接（用于AI服务和在线功能）\n\n### 推荐配置\n\n- **内存**：至少4GB RAM（推荐8GB+）\n- **处理器**：支持AVX指令集的现代CPU\n- **存储**：至少2GB可用磁盘空间（用于模型文件和缓存）\n- **音频**：支持16kHz采样率的音频设备\n\n### 可选功能要求\n\n- **语音唤醒**：需要下载Sherpa-ONNX语音识别模型\n- **摄像头功能**：需要摄像头设备和OpenCV支持\n\n## 请先看这里\n\n- 仔细阅读 [项目文档](https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002F) 启动教程和文件说明都在里面了\n- main是最新代码，每次更新都需要手动重新安装一次pip依赖防止我新增依赖后你们本地没有\n\n[从零开始使用小智客户端（视频教程）](https:\u002F\u002Fwww.bilibili.com\u002Fvideo\u002FBV1dWQhYEEmq\u002F?vd_source=2065ec11f7577e7107a55bbdc3d12fce)\n\n## 技术架构\n\n### 核心架构设计\n\n- **事件驱动架构**: 基于asyncio的异步事件循环，支持高并发处理\n- **分层设计**: 清晰的应用层、协议层、设备层、UI层分离\n- **单例模式**: 核心组件采用单例模式，确保资源统一管理\n- **插件化**: MCP工具系统和IoT设备支持插件化扩展\n\n### 关键技术组件\n\n- **音频处理**: Opus编解码、WebRTC回声消除、实时重采样、系统音频录制\n- **语音识别**: Sherpa-ONNX离线模型、语音活动检测、唤醒词识别\n- **协议通信**: WebSocket\u002FMQTT双协议支持、加密传输、自动重连\n- **配置系统**: 分层配置、点记法访问、动态更新、JSON\u002FYAML支持\n\n### 性能优化\n\n- **异步优先**: 全系统异步架构，避免阻塞操作\n- **内存管理**: 智能缓存、垃圾回收\n- **音频优化**: 5ms低延迟处理、队列管理、流式传输\n- **并发控制**: 任务池管理、信号量控制、线程安全\n\n### 安全机制\n\n- **加密通信**: WSS\u002FTLS加密、证书验证\n- **设备认证**: 双协议激活、设备指纹识别\n- **权限控制**: 工具权限管理、API访问控制\n- **错误隔离**: 异常隔离、故障恢复、优雅降级\n\n## 开发指南\n\n### 项目结构\n\n```\npy-xiaozhi\u002F\n├── main.py                     # 应用程序主入口（CLI参数处理）\n├── src\u002F\n│   ├── application.py          # 应用程序核心逻辑\n│   ├── audio_codecs\u002F           # 音频编解码器\n│   │   ├── aec_processor.py    # 音频回声消除处理器\n│   │   ├── audio_codec.py      # 音频编解码基础类\n│   │   └ой system_audio_recorder.py  # 系统音频录制器\n│   ├── audio_processing\u002F       # 音频处理模块\n│   │   ├── vad_detector.py     # 语音活动检测\n│   │   └ой wake_word_detect.py # 唤醒词检测\n│   ├── core\u002F                   # 核心组件\n│   │   ├── ota.py             # 在线更新模块\n│   │   └ой system_initializer.py # 系统初始化器\n│   ├── display\u002F                # 显示界面抽象层\n│   ├── iot\u002F                    # IoT设备管理\n│   │   ├── thing.py           # 设备基类\n│   │   ├── thing_manager.py   # 设备管理器\n│   │   └ой things\u002F            # 具体设备实现\n│   ├── mcp\u002F                    # MCP工具系统\n│   │   ├── mcp_server.py      # MCP服务器\n│   │   └ой tools\u002F             # 各种工具模块\n│   ├── protocols\u002F              # 通信协议\n│   ├── utils\u002F                  # 工具函数\n│   └oy views\u002F                  # UI视图组件\n├── libs\u002F                       # 第三方原生库\n│   ├── libopus\u002F               # Opus音频编解码库\n│   ├── webrtc_apm\u002F            # WebRTC音频处理模块\n│   └ой SystemAudioRecorder\u002F   # 系统音频录制工具\n├── config\u002F                     # 配置文件目录\n├── models\u002F                     # 语音模型文件\n├── assets\u002F                     # 静态资源文件\n├── scripts\u002F                    # 辅助脚本\n├── requirements.txt            # Python依赖包列表\n└oy build.json                  # 构建配置文件\n```\n\n### 开发环境设置\n\n```bash\n# 克隆项目\ngit clone https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi.git\ncd py-xiaozhi\n\n# 安装依赖\npip install -r requirements.txt\n\n# 代码格式化\n.\u002Fformat_code.sh\n\n# 运行程序 - GUI模式（默认）\npython main.py\n\n# 运行程序 - CLI模式\npython main.py --mode cli\n\n# 指定通信协议\npython main.py --protocol websocket  # WebSocket（默认）\npython main.py --protocol mqtt       # MQTT协议\n```\n\n### 核心开发模式\n\n- **异步优先**: 使用`async\u002Fawait`语法，避免阻塞操作\n- **错误处理**: 完整的异常处理和日志记录\n- **配置管理**: 使用`ConfigManager`统一配置访问\n- **测试驱动**: 编写单元测试，确保代码质量\n\n### 扩展开发\n\n- **添加MCP工具**: 在`src\u002Fmcp\u002Ftools\u002F`目录创建新工具模块\n- **添加IoT设备**: 继承`Thing`基类实现新设备\n- **添加协议**: 实现`Protocol`抽象基类\n- **添加界面**: 扩展`BaseDisplay`实现新的UI组件\n\n### 状态流转图\n\n```\n                        +----------------+\n                        |                |\n                        v                |\n+------+  唤醒词\u002F按钮  +------------+   |   +------------+\n| IDLE | -----------> | CONNECTING | --+-> | LISTENING  |\n+------+              +------------+       +------------+\n   ^                                            |\n   |                                            | 语音识别完成\n   |          +------------+                    v\n   +--------- |  SPEAKING  | \u003C-----------------+\n     完成播放 +------------+\n```\n\n## 贡献指南\n\n欢迎提交问题报告和代码贡献。请确保遵循以下规范：\n\n1. 代码风格符合PEP8规范\n2. 提交的PR包含适当的测试\n3. 更新相关文档\n\n## 社区与支持\n\n### 感谢以下开源人员\n>\n> 排名不分前后\n\n[Xiaoxia](https:\u002F\u002Fgithub.com\u002F78)\n[zhh827](https:\u002F\u002Fgithub.com\u002Fzhh827)\n[四博智联-李洪刚](https:\u002F\u002Fgithub.com\u002FSmartArduino)\n[HonestQiao](https:\u002F\u002Fgithub.com\u002FHonestQiao)\n[vonweller](https:\u002F\u002Fgithub.com\u002Fvonweller)\n[孙卫公](https:\u002F\u002Fspace.bilibili.com\u002F416954647)\n[isamu2025](https:\u002F\u002Fgithub.com\u002Fisamu2025)\n[Rain120](https:\u002F\u002Fgithub.com\u002FRain120)\n[kejily](https:\u002F\u002Fgithub.com\u002Fkejily)\n[电波bilibili君](https:\u002F\u002Fspace.bilibili.com\u002F119751)\n[赛搏智能](https:\u002F\u002Fshop115087494.m.taobao.com\u002F?refer=https%3A%2F%2Fm.tb.cn%2F&ut_sk=1.WMelxbgDQWkDAJ1Rq9Pn7DCD_21380790_1757337352472.Copy.shop&suid=0E25E948-651D-46E0-8E89-5C8CB03B4F56&shop_navi=shopindex&sourceType=shop&shareUniqueId=33038752403&un=d22c5ceda82844ab8bd7bab98ffeb263&share_crt_v=1&un_site=0&spm=a2159r.13376460.0.0&sp_tk=dkRKUjRKUWo2ZHY%3D&bc_fl_src=share-1041250486811064-2-1&cpp=1&shareurl=true&short_name=h.SaBKVHytsCKIPNS&bxsign=scdGtSe264e_qkFQBh0rXCkF-Mrb_s6t35EnpVBBU5dsrd-J24c-_rn_PhJiXRk0hg2hjGoAm0L7j2UQg27OIH_6gZkbhKDyLziD2cy4pDf8sC3KmqrF55TXP3USZaPTw_-&app=weixin)\n\n### 赞助支持\n\n\u003Cdiv align=\"center\">\n  \u003Ch3>感谢所有赞助者的支持 ❤️\u003C\u002Fh3>\n  \u003Cp>无论是接口资源、设备兼容测试还是资金支持，每一份帮助都让项目更加完善\u003C\u002Fp>\n  \n  \u003Ca href=\"https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002Fsponsors\u002F\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F查看-赞助者名单-brightgreen?style=for-the-badge&logo=github\" alt=\"赞助者名单\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002Fsponsors\u002F\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F成为-项目赞助者-orange?style=for-the-badge&logo=heart\" alt=\"成为赞助者\">\n  \u003C\u002Fa>\n\u003C\u002Fdiv>\n\n## 项目统计\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_readme_8035e9df79bd.png)](https:\u002F\u002Fwww.star-history.com\u002F#huangjunsen0406\u002Fpy-xiaozhi&Date)\n\n## 许可证\n\n[MIT License](LICENSE)","# py-xiaozhi 快速上手指南\n\npy-xiaozhi 是一个基于 Python 实现的小智语音客户端，旨在让开发者在无硬件条件下体验 AI 语音交互、多模态视觉及智能家居控制功能。本项目移植自 [xiaozhi-esp32](https:\u002F\u002Fgithub.com\u002F78\u002Fxiaozhi-esp32)。\n\n## 1. 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n### 系统要求\n- **操作系统**：Windows 10+、macOS 10.15+ 或 Linux\n- **Python 版本**：3.9 - 3.12\n- **硬件配置**：\n  - 内存：至少 4GB RAM（推荐 8GB+）\n  - 存储：至少 2GB 可用空间（用于模型和缓存）\n  - 音频：具备麦克风和扬声器设备\n  - 网络：稳定的互联网连接\n\n### 前置依赖\n- **音频驱动**：确保系统音频输入输出正常。\n- **可选组件**：\n  - 若需使用**语音唤醒**功能，需下载 Sherpa-ONNX 模型（首次运行会自动提示或下载）。\n  - 若需使用**摄像头**功能，需安装摄像头并支持 OpenCV。\n\n> **提示**：国内用户如遇网络问题，可考虑配置 pip 国内镜像源加速依赖安装。\n\n## 2. 安装步骤\n\n### 克隆项目\n使用 git 克隆代码仓库：\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi.git\ncd py-xiaozhi\n```\n> **国内加速**：也可通过 Gitee 镜像克隆：\n> ```bash\n> git clone https:\u002F\u002Fgitee.com\u002Fhuang-jun-sen\u002Fpy-xiaozhi.git\n> cd py-xiaozhi\n> ```\n\n### 安装依赖\n安装项目所需的 Python 库：\n```bash\npip install -r requirements.txt\n```\n> **建议**：每次拉取最新代码后，建议重新执行此命令以确保新增依赖已安装。\n\n### 获取模型（可选）\n首次运行时，若未检测到语音唤醒模型，程序通常会引导下载。如需手动准备，请参考项目文档中的模型存放路径（通常在 `models\u002F` 目录）。\n\n## 3. 基本使用\n\n安装完成后，您可以通过以下命令启动小智客户端。\n\n### 启动图形界面模式（默认）\n适用于桌面环境，提供完整的可视化交互界面：\n```bash\npython main.py\n```\n\n### 启动命令行模式\n适用于无图形界面环境或嵌入式调试：\n```bash\npython main.py --mode cli\n```\n\n### 指定通信协议\n默认使用 WebSocket，也可切换为 MQTT 协议：\n```bash\n# 使用 WebSocket (默认)\npython main.py --protocol websocket\n\n# 使用 MQTT\npython main.py --protocol mqtt\n```\n\n### 基础操作流程\n1. **启动程序**：运行上述命令打开界面。\n2. **激活交互**：\n   - **语音唤醒**：说出配置的唤醒词（需提前开启该功能）。\n   - **手动触发**：点击界面上的按钮或使用全局快捷键。\n3. **对话体验**：对着麦克风说话，系统将进行语音识别、AI 处理并语音回复。\n4. **功能扩展**：尝试使用内置的 MCP 工具（如查询天气、播放音乐、控制智能家居等）。\n\n---\n*更多详细配置、API 开发指南及故障排查，请参阅 [官方项目文档](https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002F)。*","独立开发者阿明正在家中调试一套基于 ESP32 的智能家居原型，他急需验证语音交互逻辑，但手边没有专用的“小智”硬件开发板。\n\n### 没有 py-xiaozhi 时\n- **硬件依赖受限**：必须等待专用开发板快递送达或进行复杂的电路焊接，无法立即开始软件逻辑调试。\n- **多模态测试困难**：想要测试“拍照识别冰箱食材”功能时，缺乏便捷的摄像头接入方案，只能编写大量模拟代码桩。\n- **交互体验割裂**：只能通过命令行查看枯燥的日志输出来判断语音识别结果，无法直观感受对话流畅度和打断机制。\n- **生态集成繁琐**：想测试查询天气或控制灯光等 MCP 工具链，需要单独搭建后端服务并手动模拟 API 调用，耗时耗力。\n\n### 使用 py-xiaozhi 后\n- **零硬件启动**：直接在笔记本电脑上运行 Python 脚本，利用现有麦克风和扬声器即刻获得完整的小智语音体验，秒级进入开发状态。\n- **原生多模态支持**：调用笔记本摄像头即可实时演示图像识别与问答，无需额外配置即可验证视觉交互逻辑。\n- **可视化调试反馈**：通过内置的 PyQt5 图形界面，实时观察小智的表情变化、语音波形及对话文本，直观优化唤醒词灵敏度与打断效果。\n- **工具链即插即用**：内置的日程管理、12306 查询及智能家居控制工具可直接配置测试，快速验证业务场景下的指令执行准确性。\n\npy-xiaozhi 让开发者摆脱了专用硬件的束缚，将原本需要数天的环境搭建与联调工作压缩至分钟级，极大降低了 AI 语音应用的试错成本。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuangjunsen0406_py-xiaozhi_d8afd1a5.png","huangjunsen0406","Junsen Huang","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fhuangjunsen0406_a76a77a1.jpg","Frontend Developer | Full-stack Enthusiast\r\nExperienced in Vue.js, Java, and Node.js. Currently working as a frontend developer but proficient in both frontend ",null,"Guangzhou, China","951434130@qq.com","https:\u002F\u002FJunsen.online","https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406",[82,86,90,94,98,101,105,108,112],{"name":83,"color":84,"percentage":85},"Python","#3572A5",93.2,{"name":87,"color":88,"percentage":89},"Vue","#41b883",2.8,{"name":91,"color":92,"percentage":93},"QML","#44a51c",2.5,{"name":95,"color":96,"percentage":97},"TypeScript","#3178c6",0.5,{"name":99,"color":100,"percentage":97},"CSS","#663399",{"name":102,"color":103,"percentage":104},"JavaScript","#f1e05a",0.2,{"name":106,"color":107,"percentage":104},"Shell","#89e051",{"name":109,"color":110,"percentage":111},"Batchfile","#C1F12E",0.1,{"name":113,"color":114,"percentage":115},"SCSS","#c6538c",0,3258,677,"2026-04-03T08:14:34","MIT","Windows, macOS, Linux","未说明","最低 4GB，推荐 8GB+",{"notes":124,"python":125,"dependencies":126},"需要麦克风和扬声器设备；支持 16kHz 采样率的音频设备；语音唤醒功能需下载 Sherpa-ONNX 模型；摄像头功能需额外设备及 OpenCV 支持；至少需要 2GB 可用磁盘空间用于模型和缓存；每次更新代码后建议重新安装 pip 依赖。","3.9 - 3.12",[127,128,129,130,131],"PyQt5","Sherpa-ONNX","Opus","WebRTC","asyncio",[35,133,13,134],"音频","其他",[136,137,138,139,140,141],"esp32","esp32-s3","xiaozhi-esp32","mcp","mcp-server","python","2026-03-27T02:49:30.150509","2026-04-11T16:57:40.085205",[145,150,155,160,165,170],{"id":146,"question_zh":147,"answer_zh":148,"source_url":149},10625,"如何配置 py-xiaozhi 使用自己搭建的 xiaozhi-esp32-server？","只要固件是基于 https:\u002F\u002Fgithub.com\u002F78\u002Fxiaozhi-esp32 项目的，就可以正常使用。你可以直接修改配置文件中的 websocket_url 地址指向你自己的服务器。如果是内网环境，重启后通常会自动下发配置；如果是外网或特殊网络环境（如 IPv6），可能需要手动硬编码配置地址，而不依赖 OTA 自动下发。","https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fissues\u002F154",{"id":151,"question_zh":152,"answer_zh":153,"source_url":154},10626,"在 Linux（如树莓派、Orange Pi）上运行程序时音频播放断断续续或无声音怎么办？","1. 请确保获取了最新的 main 代码，维护者已在多个设备上测试修复了该问题。\n2. 建议在树莓派等 ARM 设备上不要直接使用 pip 安装 PyQt5，因为编译问题较多。推荐使用 conda 环境安装预编译好的 PyQt5，命令参考：使用 conda 安装可以避免编译错误且速度更快。\n3. 检查 ALSA 配置，确保使用了正确的默认设备（default），如果日志出现大量 'underrun occurred'，通常是因为音频缓冲区设置不当或 CPU 性能不足，更新代码后通常可解决。","https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fissues\u002F89",{"id":156,"question_zh":157,"answer_zh":158,"source_url":159},10627,"在树莓派上运行时遇到 'ModuleNotFoundError: No module named PyQt5' 错误如何解决？","即使系统中显示已安装 PyQt5，仍可能因架构或版本不匹配报错。建议：\n1. 树莓派 3B 及更低版本可能因性能或架构限制不支持该项目，建议使用树莓派 4B 及以上版本。\n2. 强烈建议使用 conda 环境来管理依赖，通过 conda 安装预编译的 PyQt5 包，避免源码编译导致的兼容性问题。","https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fissues\u002F205",{"id":161,"question_zh":162,"answer_zh":163,"source_url":164},10628,"在 Ubuntu 20.04 等旧版系统上运行报错 'version GLIBC_2.38 not found' 怎么办？","该错误是因为项目依赖的 libwebrtc_apm.so 库需要较新版本的 GLIBC（2.38+），而 Ubuntu 20.04 自带的版本过低。\n解决方案：\n1. 推荐升级到 Ubuntu 24.04 或使用 Docker 运行（维护者验证过 Docker 方案有效）。\n2. 或者切换到 'bugfix\u002Fwebrtc_apm' 分支，该分支实现了动态引入 APM 模块，可能在旧系统上兼容更好，但仍建议升级系统以获得最佳稳定性。","https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fissues\u002F204",{"id":166,"question_zh":167,"answer_zh":168,"source_url":169},10629,"如何修改 Config 配置中的 websocket_url 以连接自建服务器？","虽然官方方案是通过 OTA 自动下发配置，但你也可以直接手动修改：\n1. 在配置文件中找到 websocket_url 字段，直接写入你自建服务器的地址（例如内网 IP 192.168.x.x）。\n2. 如果是在外网使用 IPv6 等复杂网络，建议同时手动配置相关行，不要完全依赖 OTA。\n3. 修改后重启程序即可生效。维护者表示可以直接“写死”地址，在线文档中也有相关操作说明。","https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fissues\u002F201",{"id":171,"question_zh":172,"answer_zh":173,"source_url":159},10630,"树莓派部署小智 AI 时，对于硬件版本有什么要求？","根据社区反馈和维护者回复，树莓派 3B 及以下版本由于性能限制，不适合部署该项目，容易出现音频断断续续或模块加载失败的问题。建议最低使用树莓派 4B 进行部署，以获得稳定的运行体验。",[175,180,185,190,195,200,205,210,215,220,225],{"id":176,"version":177,"summary_zh":178,"released_at":179},71195,"v1.1.8","# What's Changed\r\n\r\n* fix(audio): 修复加入aec后开源服务端播放异常 (#200) @huangjunsen0406\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fcompare\u002Fv1.1.7...v1.1.8\r\n## Documentation\r\n\r\n- [在线文档](https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002F)","2025-08-19T17:02:16",{"id":181,"version":182,"summary_zh":183,"released_at":184},71196,"v1.1.7","# What's Changed\r\n\r\n* 为 opus_loader 增加类型声明，提高可维护性；创建 windows 端适用的 format_code (#199) @Yang-ZhiHang\r\n* 优化mqtt连接方式，根据端口来区分tls (#189) @hackers365\r\n* add mcp support (#163) @Hasen-dc\r\n* 修复HA导入时候的报错 (#157) @520xcy\r\n* 修复通过ssh连接环境CLI方式启动失败问题 (#134) @gaochuang\r\n* 新增人脸识别功能 (#119) @gdmec07150717\r\n* 一键添加HA设备，自动注册设备 (#114) @Y-ASLant\r\n* Linux下一段时间后 按键无法唤醒问题 (#111) @Y-ASLant\r\n* fix.资源路径问题 (#108) @Y-ASLant\r\n* GIF切换增加淡出淡入效果 (#98) @Y-ASLant\r\n* GUI更新 (#97) @Y-ASLant\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fhuangjunsen0406\u002Fpy-xiaozhi\u002Fcompare\u002Fv1.1.6...v1.1.7\r\n\r\n## 新特性\r\n* 增加了不同平台的声学回声消除（AEC）方案。\r\n* 支持自定义图片格式切换，支持PNG、GIF等格式。\r\n* 新增了MCP 支持。\r\n* 将Vosk替换为Sherap-ONNX，提升了性能。\r\n* 新增快捷键自定义\r\n\r\n## Documentation\r\n\r\n- [在线文档](https:\u002F\u002Fhuangjunsen0406.github.io\u002Fpy-xiaozhi\u002F)","2025-08-19T06:56:10",{"id":186,"version":187,"summary_zh":188,"released_at":189},71197,"v1.1.6","# 版本 1.1.6\r\n\r\n### 文档相关\r\n- **修复** 在线文档打包失败问题，确保文档生成过程顺利进行。 (`fix(docs): 修复在线文档打包失败`)\r\n- **新增** 系统架构和相关生态的介绍，进一步完善文档内容。 (`feat(docs): 新增系统架构、相关生态`)\r\n- **修复** 赞助名单显示异常，确保显示正确无误。 (`docs: 修复赞助名单显示异常`)\r\n- **更新** 相关文档到文档网站，保持文档内容的最新性。 (`docs: 更新相关文档到文档网站`)\r\n\r\n### 性能优化\r\n- **提高** 温湿度传感器的播报概率，提升设备响应速度和准确度。 (`perf: 提高温湿度传感器播报概率`)\r\n- **优化** 音频相关功能，新增 IoT 执行完毕后主动播报内容，改善用户体验。 (`perf: 优化音频相关、新增iot执行完毕后主动播报内容`)\r\n\r\n### 功能改进\r\n- **新增** 温湿度数据的主动更新和自动语音播报功能。 (`feat(temperature): 新增温湿度主动更新数据自动语音播报`)\r\n- **新增** TTS 说话检测，当 TTS 说话或点击打断按钮时暂停播放，恢复播放时再继续。 (`feat(music_player): 新增tts说话检测`)\r\n- **优化** 音频播放器，支持暂停、播放、调整进度的功能，改善用户控制体验。 (`feat(music_player): 使用pygame重构原有ffmpeg实现的播放`)\r\n\r\n### 修复和改进\r\n- **修复** IoT 增量更新异常问题，增强设备的稳定性。 (`fix(iot): 修复iot增量更新异常问题`)\r\n- **修复** IoT 生成 JSON 错误的问题，确保数据格式正确。 (`fix: 修复iot生成json错误问题`)\r\n- **修复** 合并冲突，保持代码的一致性和完整性。 (`fix: 修复合并冲突`)\r\n- **修复** PyQt5 界面中出现的 bug，提升界面的稳定性。 (`fix(pyqt): 新增ota地址修改`)\r\n\r\n### 构建与配置\r\n- **优化** 打包配置，提升构建过程的稳定性。 (`build: 优化打包配置`)\r\n- **更新** 依赖文件，确保环境配置的准确性和兼容性。 (`update: 更新依赖文件`)","2025-04-20T13:49:52",{"id":191,"version":192,"summary_zh":193,"released_at":194},71198,"v1.1.5","# 版本 1.1.5\r\n\r\n## 系统兼容性\r\n\r\n- 修复IoT状态JSON解析错误，解决设备状态更新时的类型转换问题\r\n- 修复网络错误处理回调参数不匹配问题，提高连接稳定性\r\n- 优化服务器消息处理逻辑，增强错误恢复能力\r\n- 优化音乐触发优先使用联网音乐\r\n- 新增PipeWire support\r\n- 修复重置音频输出设备选择错误\r\n\r\n## 文档改进\r\n\r\n- 拆分使用教程，将原使用教程移动至docs\u002Fold_docs\u002F，优化文档结构\r\n- 新增赞助者名单，感谢社区贡献\r\n\r\n## 技术优化\r\n\r\n- 统一使用全局logger，提升日志系统一致性\r\n- 修复IoT模块参数缺失问题\r\n- 代码结构优化，提高系统稳定性\r\n","2025-04-14T10:58:45",{"id":196,"version":197,"summary_zh":198,"released_at":199},71199,"v1.1.4","# 版本 1.1.4\r\n此版本主要修复了音频流线程重复创建问题\r\n\r\n## 系统兼容性\r\n- 此版本主要修复了音频流线程重复创建问题\r\n","2025-03-23T14:44:04",{"id":201,"version":202,"summary_zh":203,"released_at":204},71200,"v1.1.3","# 版本 1.1.3\r\n此版本主要修复了打包后mac地址异常问题、点击打断无法暂停在线音乐播放\r\n\r\n## 主要变更\r\n- 打包脚本全面升级，使用pathlib统一处理路径，提升各平台兼容性\r\n- 修复打包后无法生成新的MAC地址的问题\r\n- 修复点击打断无法暂停在线音乐播放\r\n\r\n## 系统兼容性\r\n- 增强对Windows\u002FmacOS\u002FLinux多平台的支持\r\n- 改进打包后的路径处理逻辑\r\n\r\n## 路径处理优化\r\n- 使用pathlib替代os.path，实现更统一的跨平台路径处理\r\n- 优化模型加载路径计算逻辑，解决唤醒词模型路径识别问题\r\n- 改进配置文件和资源文件路径处理\r\n\r\n## 唤醒词功能\r\n- 修复打包后唤醒词模型加载问题\r\n","2025-03-21T08:17:00",{"id":206,"version":207,"summary_zh":208,"released_at":209},71201,"v1.1.2","# 版本 1.1.2\r\n\r\n此版本主要修复了音频处理和在线音源集成相关的问题。\r\n\r\n## 主要变更\r\n\r\n- 重构 MusicPlayer 以支持在线音源播放\r\n- 修复部分平台上音频丢失的问题\r\n- 解决录音资源争夺问题，实现共用录音流\r\n- 改进摄像头模块，确保每次启动都重新从配置中读取参数\r\n- 修复唤醒词打包后无法加载\r\n\r\n## 音频改进\r\n\r\n- 解决了播放中途音频丢失的问题\r\n- 优化音频解码队列管理\r\n- 改进了TTS和音乐播放之间的切换逻辑\r\n\r\n## IOT设备优化\r\n\r\n- 增强音乐播放器组件，支持更稳定的在线歌曲播放\r\n- 优化摄像头设备初始化流程\r\n- 改进各IOT设备的错误处理机制","2025-03-18T18:21:00",{"id":211,"version":212,"summary_zh":213,"released_at":214},71202,"v1.1.1","项目优化\r\n\r\n修复：修复keyboard在macos下导致程序异常问题\r\n","2025-03-17T17:23:57",{"id":216,"version":217,"summary_zh":218,"released_at":219},71203,"v1.1.0","# 版本 1.1.0\r\n\r\n## 主要更新\r\n- 新增 IoT 视觉识别能力，支持摄像头控制和画面识别\r\n- 优化在线音乐播放器，改进与 TTS 的交互\r\n- 去除 VAD 检测打断功能，提高系统稳定性\r\n- 修复音乐播放时切换聆听状态的问题\r\n\r\n## 详细变更\r\n\r\n### 新功能\r\n- **IoT 视觉识别**：\r\n  - 添加摄像头控制功能，支持打开\u002F关闭摄像头\r\n  - 新增画面识别能力，可以识别摄像头捕获的图像内容\r\n  - 优化摄像头与 VL 推理 URL 配置设置\r\n  - 使用方法：只需说\"打开摄像头\"、\"关闭摄像头\"、\"识别画面\"即可\r\n\r\n- **在线音乐播放**：\r\n  - 优化音乐播放器与 TTS 的交互逻辑\r\n  - 改进播放状态管理，确保音乐播放不会被应用程序状态变化中断\r\n  - 修复音乐播放完成后进度更新不完整的问题\r\n\r\n### 改进\r\n- 去除了 VAD 检测打断功能，现在只支持通过唤醒词打断，提高系统稳定性\r\n- 改进了 TTS 播放状态管理，确保 is_tts_playing 状态正确更新\r\n- 更新了项目文档和 issues 模板\r\n- 优化了依赖项配置\r\n\r\n## 升级说明\r\n如果从 v1.0.1 升级到 v1.1.0，只需要拉取 main 分支代码即可。\r\n\r\n## 使用说明\r\n- **视觉识别**：说\"打开摄像头\"、\"关闭摄像头\"、\"识别画面\"\r\n- **音乐播放**：说\"播放音乐 [歌曲名]\"、\"暂停音乐\"\r\n\r\n## 已知问题\r\n无","2025-03-17T14:59:17",{"id":221,"version":222,"summary_zh":223,"released_at":224},71204,"v1.0.1","项目优化\r\n\r\n- 修复：修复mac和linux的运行异常（原先使用pycaw来处理音频音量大小） \r\n- 新增：wss协议\r\n- 重构：按照虾哥1.1.2固件移植\r\n\r\n安装\u002F升级方式\r\n1. 下载最新的源码或二进制包并解压。\r\n2. 按照文档进行配置。\r\n3. 启动程序并确认正常运行。\r\n\r\n注意事项\r\n- 如果从 v1.0.0 升级到 v1.0.1，只需要拉取main分支代码即可，如果旧版在V1分支，请勿合并，main分支破坏性更新。\r\n","2025-03-01T16:49:20",{"id":226,"version":227,"summary_zh":228,"released_at":229},71205,"v1.0.0","## 项目优化\r\n- 优化了 goodbye 后无法重连问题\r\n- 新增 GUI 页面，无需在控制台一直按空格\r\n- 拆分代码，封装为类，各司其职","2025-02-16T14:16:49"]