{"id":50552281,"url":"https://github.com/nancheung/open-xiaozhi-client","last_synced_at":"2026-06-04T04:31:35.904Z","repository":{"id":359430015,"uuid":"1245973436","full_name":"nancheung/open-xiaozhi-client","owner":"nancheung","description":"小智的客户端全协议实现。🎙️ 面向 小智生态 的开源客户端全协议实现。 让你可以更快地 学习协议、联调服务端、排查问题、体验小智能力。","archived":false,"fork":false,"pushed_at":"2026-05-31T08:40:53.000Z","size":1584,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T10:07:18.024Z","etag":null,"topics":["esp32","xiaozhi","xiaozhi-ai","xiaozhi-bot","xiaozhi-esp32","xiaozhi-server"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/open-xiaozhi-client-webui","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nancheung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T18:42:05.000Z","updated_at":"2026-05-31T08:39:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nancheung/open-xiaozhi-client","commit_stats":null,"previous_names":["nancheung/open-xiaozhi-client"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nancheung/open-xiaozhi-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nancheung%2Fopen-xiaozhi-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nancheung%2Fopen-xiaozhi-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nancheung%2Fopen-xiaozhi-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nancheung%2Fopen-xiaozhi-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nancheung","download_url":"https://codeload.github.com/nancheung/open-xiaozhi-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nancheung%2Fopen-xiaozhi-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33890052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","xiaozhi","xiaozhi-ai","xiaozhi-bot","xiaozhi-esp32","xiaozhi-server"],"created_at":"2026-06-04T04:31:35.110Z","updated_at":"2026-06-04T04:31:35.895Z","avatar_url":"https://github.com/nancheung.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Open Xiaozhi Client\n\n![WebUI](https://img.shields.io/badge/WebUI-Available-22c55e?style=flat-square)\n![Xiaozhi](https://img.shields.io/badge/Xiaozhi-Ecosystem-2563eb?style=flat-square)\n![Client](https://img.shields.io/badge/Client-Full%20Protocol%20Implementation-7c3aed?style=flat-square)\n![npm](https://img.shields.io/npm/v/open-xiaozhi-client-webui?style=flat-square\u0026color=cb3837)\n![License](https://img.shields.io/badge/License-AGPL--3.0-orange?style=flat-square)\n\n![Open Xiaozhi Client WebUI 亮色-双栏](https://raw.githubusercontent.com/nancheung/open-xiaozhi-client/main/docs/images/open-xiaozhi-client-webui-placeholder-1.png)\n\n\u003e 🎙️ 面向 **小智生态** 的开源客户端全协议实现。  \n\u003e 让你可以更快地 **学习协议、联调服务端、排查问题、体验小智能力**。\n\n**Open Xiaozhi Client** 是一个基于小智生态的开源客户端项目，目标是提供一个真正可用、可观察、可调试的客户端实现入口。当前已经提供 **WebUI 调试端**，后续会继续扩展到更多平台和终端形态。\n\n它既适合开发者作为 **小智服务端调试工具** 使用，也适合普通用户快速上手体验小智的交互链路。\n\n```bash\nnpm install -g open-xiaozhi-client-webui\nopen-xiaozhi-client-webui\n```\n\n\u003e ⚡ 1分钟跑起来！执行后自动启动本地服务并打开浏览器，默认访问 `http://127.0.0.1:14100`，按 `Ctrl+C` 退出。\n\n## ✨ 为什么值得关注\n\n- ⚡ **1 分钟跑起来**：安装依赖、启动 WebUI、连接服务端，快速进入调试状态\n- 📐 **全协议实现定位**：围绕小智客户端侧能力建设，方便理解消息流和交互链路\n- 🔍 **兼顾调试与体验**：既能看协议细节，也能直接体验 WebUI 交互\n- 🔗 **适配小智生态**：支持官方小智，也支持开源服务端\n- 🔮 **面向未来多端**：当前是 WebUI，未来会继续支持更多客户端形态\n\n## 🚀 当前已经可以做什么\n\n当前版本重点提供一个面向学习、联调、排障的 **WebUI 小智客户端**。\n\n| 能力 | 说明 |\n| --- | --- |\n| 🖥️ 响应式 WebUI 客户端 | 宽屏双栏布局（对话历史 + 指令中心）/ 窄屏单栏布局，面板宽度可拖拽调整 |\n| 📡 连接状态查看 | 查看 OTA 获取、连接中、握手中、就绪、播放中等状态变化 |\n| 🎤 三种监听模式 | 对讲机（手动）/ 智能助理（VAD 自动）/ 通话（全双工实时），可随时切换 |\n| 🔊 音频可视化 | 录音音量条 + 播放波形动画，实时反映收发音频状态 |\n| 📋 协议日志面板 | 实时观察 WebSocket 文本帧、二进制帧、系统日志 |\n| 📨 自定义消息发送 | 手动发送 JSON 消息，便于模拟与调试协议行为 |\n| 🎛️ 设备控制面板 | 调整音量、屏幕亮度、明暗主题，查看收到的 IoT 命令，设置持久化 |\n| 🌐 HTTP 面板 | 在连接态下发送服务端管理指令（更新配置、重启等） |\n| ⚙️ 设置面板 | 调整 Hello 参数、音频参数、心跳、日志数量等配置，持久化保存 |\n| 🤖 MCP 协议支持 | 客户端作为 MCP Server 响应服务端工具调用（音量、亮度、主题、重启等） |\n| 📸 摄像头 / 视觉能力 | 支持 `self.camera.take_photo`：调用浏览器摄像头拍照，通过服务端下发的视觉端点分析图像并回传结果 |\n| 🔐 设备激活流程 | 对齐 xiaozhi-esp32 OTA 激活协议，自动轮询 `/activate` 完成设备注册 |\n\n## 👥 适合谁\n\n- 📖 想学习 **小智协议 / xiaozhi protocol** 的开发者\n- 🔧 想联调 **官方小智** 或 **开源服务端** 的开发者\n- 🐛 想快速定位连接、握手、消息收发问题的服务端开发者\n- 🏗️ 想基于小智生态继续扩展桌面端、移动端或其他客户端的贡献者\n- 🌟 想先体验小智交互流程的普通用户\n\n## 🔍 为什么这个项目对服务端调试有价值\n\n很多小智相关项目在服务端开发阶段，最难的不是功能本身，而是：\n\n- 👀 不容易看清楚客户端到底发了什么\n- 🔄 不容易复现某个握手或协议问题\n- ✅ 不容易快速验证 IoT、HTTP、音频、消息链路是否正常\n\n这个项目的价值就在于提供一个 **可视化、可操作、可观察** 的客户端调试入口：  \n你可以一边连接服务端，一边查看协议日志，一边手动发送消息或修改配置，从而更高效地定位问题。\n\n## 🌐 支持的小智生态项目\n\n### 官方小智\n\n- GitHub: https://github.com/78/xiaozhi-esp32\n\n### 开源服务端\n\n- GitHub: https://github.com/xinnan-tech/xiaozhi-esp32-server\n\n\u003e 本项目聚焦 **客户端侧实现、协议学习与服务端调试体验**，不替代服务端项目本身。\n\n## ⚡ 快速开始\n\n```bash\nnpm install -g open-xiaozhi-client-webui\nopen-xiaozhi-client-webui\n```\n\n命令执行后会自动启动本地服务并打开浏览器，默认访问地址为 `http://127.0.0.1:14100`。若端口被占用会自动顺延。按 `Ctrl+C` 退出。\n\n进入页面后，你可以：\n\n1. 在顶部填写服务地址，默认可按小智服务端 OTA 地址格式接入\n2. 点击连接，观察连接状态与握手流程\n3. 在协议日志中查看消息收发\n4. 在设备控制 / HTTP / 设置面板中继续联调和排障\n\n### 源码开发模式\n\n\u003e 适合在本地修改代码、参与开发的贡献者。\n\n**环境要求**：Node.js 18+、npm 9+\n\n```bash\nnpm install\nnpm run dev\n```\n\n启动后默认访问：`http://localhost:5173`\n\n## 🏗️ 构建\n\n```bash\nnpm run build\n```\n\n## 📁 项目结构\n\n```text\nsrc/\n  🧩 components/   WebUI 组件与调试面板\n  ⚙️ features/     连接、协议、音频、IoT、MCP、设备、摄像头等业务状态\n  🪝 hooks/        音频与连接相关 Hook\n  🗄️ store/        全局状态管理（Zustand slice 模式）\n  📡 ws/           WebSocket 管理与协议收发\n```\n\n## 🎯 这个项目的定位\n\n这不是一个单纯的演示页面，也不只是一个简单的调试脚本。\n\n它更适合作为：\n\n- 📌 **小智客户端实现参考**\n- 🔧 **小智服务端联调工具**\n- 📚 **小智协议学习入口**\n- 🏗️ **未来多端客户端的基础工程**\n\n## 🗺️ 路线图\n\n- [x] ~~WebUI 调试端~~ ✅\n- [x] ~~面向协议学习与服务端调试的基础交互能力~~ ✅\n- [x] ~~响应式双栏布局 + 三种监听模式~~ ✅\n- [x] ~~MCP 协议支持 + 设备控制面板~~ ✅\n- [x] ~~摄像头 / 视觉能力（`self.camera.take_photo`）~~ ✅\n- [x] ~~设备激活流程（OTA 激活协议对齐）~~ ✅\n- [ ] 📱 更多客户端形态支持\n- [ ] 🖥️ 更完整的多端体验\n- [ ] 🔄 持续完善小智生态下的客户端能力\n\n## 🤝 贡献与关注\n\n如果你也在关注 **小智客户端、xiaozhi WebUI、服务端联调、协议实现**，欢迎：\n\n- ⭐ Star 这个项目\n- 🐛 提交 Issue 反馈问题或需求\n- 🔀 提交 PR 一起完善客户端能力\n- 🌍 参与多端扩展与生态适配\n\n---\n\n\u003e 💡 如果你希望有一个 **更容易上手、又足够专业的小智客户端调试入口**，这个项目正是为此而生。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnancheung%2Fopen-xiaozhi-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnancheung%2Fopen-xiaozhi-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnancheung%2Fopen-xiaozhi-client/lists"}