一、结论与范围
小智适合作为桌面智能硬件的语音与设备工具底座候选。最有复用价值的是 ESP32 固件的音频状态机、传输协议与 MCP 工具注册,以及第三方服务端的 provider 接口和流式编排。服务端需要安全、数据治理和可复现构建改造后再评估产品接入。仓库当前仍明确要求不要用于生产环境,见 服务端生产警告。
它不是新发布的独立桌面整机。固件始于2024年,服务端始于2025年,两者在2026年10月仍持续维护。与 StackChan 共用小智协议、音频或模型接入时,这部分只计一次基础资产,不能把三个候选当成三套独立语音技术栈。小智专门解决语音链路与设备工具,桌面机构、运动安全、角色设计和整机生产不在这两个仓库的完整交付范围内。
研究访问日期为 2026-10-27(Asia/Shanghai)。首次固定版本的真实时间为 2026-10-26 18:26:56 UTC。采用默认分支 main 当时的精确 commit,保留 GitHub API 元数据和官方 codeload ZIP。最新主线与最新 release 分开记录,未把主线检查称作 release 实测。
| 仓库与创建时间(UTC) | 本次固定主线 | 最近 release 与对应提交 |
|---|---|---|
78/xiaozhi-esp32,2024-08-31 10:08:16 |
c435f99a88066029ec2dbd2d758c8cc9d051565b,提交时间2026-10-25 20:37:57 |
v2.5.2,发布2026-10-11 20:49:36,tag → 49b4380b3faa0ceadd28a3e78aaf0f311c46c57e |
xinnan-tech/xiaozhi-esp32-server,2025-02-02 14:25:16 |
a377d89dcd58e6e18417a57e9357c0dd23657746,提交时间2026-10-26 14:47:47 |
v0.9.8,发布2026-10-23 10:54:47,tag → 8f2dda09cf18f1c1ece0f906eee4cc2fabb7fb58 |
既有广泛调研使用固件 f443114fe7c3fa26b10d3630090119891cd1c4fd 和服务端 9bd668aebc733d77c95d8aa5fb1d25090a772509。本报告以新快照重新读代码,旧版本结论不自动继承。创建与 release 元数据位于临时目录的 firmware-meta.json、server-meta.json、firmware-release.json、server-release.json。
二、源码链路与实现边界
(一)固件启动、唤醒、音频与打断

查看 Mermaid 图源
flowchart LR
A[app_main / NVS] --> B[Application.Initialize / Board]
B --> C[AudioService + AFE 或 Lite engine]
B --> D[网络与 OTA 配置]
D --> E[MQTT 或 WebSocket]
C --> F[唤醒事件 / connecting / listening]
F --> G[16 kHz 单声道 PCM → Opus]
G --> E
E --> H[服务端 VAD → ASR → LLM → TTS]
H --> I[Opus 解码队列 → 播放队列 → 扬声器]
E --> J[MCP JSON-RPC → 主任务执行板级工具]
| 检查点 | 代码实际实现 | 复用边界与直接证据 |
|---|---|---|
| 启动 | app_main 初始化 NVS 后调用 Application::Initialize/Run。Initialize 取得板卡 display/codec、启动 AudioService,注册音频回调和 MCP,再异步启动网络 |
可沿用板级接口和事件驱动框架,换板需适配 codec、GPIO、屏幕和电源。app_main、Application::Initialize |
| 状态转换 | DeviceStateMachine 显式允许启动、联网、激活、idle、connecting、listening、speaking、升级等转换,非法转换返回 false |
这是具体状态机,不是 README 能力列表。可复用状态与回调,但要为自己的掉线/关机/执行器状态补测试。IsValidTransition / TransitionTo |
| 前处理 | AFE 输入格式区分麦克风 M 与参考信号 R,AEC 初始化取决于 codec 的 input_reference(),WakeNet/自定义唤醒模型从资源模型中选择 |
有 AEC 代码不等于所有硬件全双工有效,必须有参考音频链路并校准音量、延迟和麦克风布局。AfeAudioEngine::Initialize |
| 音频队列 | 采集、输出、Opus 编解码分任务。上行16 kHz、mono、60 ms。编码队列2项,播放队列2项,解码包20项(1.2 s),发送包40项(2.4 s) | 后两项是配置容量,不是测得端到端时延。编码饱和有丢帧计数,适合接入量化监测。音频链路和队列配置、PushTaskToEncodeQueue |
| 唤醒 | idle → connecting → 打开音频通道 → listening。失败返回 idle;唤醒音频是否上送由 CONFIG_SEND_WAKE_WORD_DATA 控制 |
唤醒可以本地完成,后续对话仍依赖服务器。HandleWakeWordDetectedEvent / ContinueWakeWordInvoke |
| 打断 | speaking/listening 时的唤醒会发 abort,清空待发送音频并切回监听。speaking 非 realtime 模式关闭语音处理,仅保留 AFE 唤醒能力。AEC off 默认 auto,AEC on 默认 realtime |
打断有唤醒词、手动与服务端 VAD 不同路径,不能一概称“全场景自然插话”。实际残留音频和误打断未测。状态驱动音频开关、AbortSpeaking / GetDefaultListeningMode、abort / listen 消息 |
(二)协议与设备工具
| 模块 | 实现与接口 | 需要保留或改造的边界 |
|---|---|---|
| WebSocket | OTA 配置提供 URL/token/version,header 携带 Authorization、Protocol-Version、Device-Id、Client-Id。hello 宣告 Opus、16 kHz、mono、60 ms 和 MCP。二进制 v1 为裸 Opus,v2/v3 加不同头 | 先选 v1 完成自建服务互通。服务端普通 WS 分支直接把完整二进制交 Opus 解码,没有在该分支处理 v2/v3 头;不能把固件支持3种格式推成该服务端全部兼容。SendAudio、OpenAudioChannel、_route_message / MQTT audio |
| 协商 | 服务端 handleHelloMessage 将客户端 audio_params 回填 welcome,再发送 hello,随后异步初始化 MCP |
默认配置的24 kHz不等于当前固件握手后必然使用24 kHz。本次隔离函数执行已验证16 kHz被回传;未编码/播放音频。handleHelloMessage |
| MQTT + UDP | MQTT 传控制 JSON、UDP 传带16字节头和 AES-CTR 加密的音频,头含长度/时间戳/序号,接收检查短包、长度和旧序号 | Python 服务端的 MQTT 路线需额外网关转接 WebSocket,网关是第三个仓库,未包含在本次两个仓库审查内。AES-CTR 本身不提供消息认证,不能据“加密”推断完整性已保证。SendAudio、UDP OnMessage、网关部署边界 |
| 设备 MCP | McpServer 实现 JSON-RPC 2.0、initialize、tools/list、tools/call,协议版本2024-11-05。工具参数按声明校验类型、范围、必填值,再排入 Application 主任务 |
可直接复用工具注册和参数声明模式,不能替代业务授权。user_only 在工具列表中过滤,DoToolCall 按名称查找全部工具,未见同层用户授权判断。应在受信服务端与设备执行入口添加动作白名单和能力授权。ParseMessage、GetToolsList、DoToolCall |
| 工具示例 | 音量、亮度、主题、拍照等通用工具,reboot、固件升级等列入 user-only。服务端 DeviceMCPExecutor 把模型工具参数发送设备,结果回入 LLM |
屏幕/舵机适配可复用该模式,摄像头、重启、升级需要明确用户权限。模型看不见某工具不等于对端无法调用它。AddCommonTools、AddUserOnlyTools、DeviceMCPExecutor.execute |
(三)服务端 ASR、LLM、TTS 与记忆
| 环节 | 当前默认/源码路径 | 本地与外部服务边界 |
|---|---|---|
| Provider 选择 | initialize_modules 按 selected_module 的名称、type 创建 VAD/ASR/LLM/TTS/Memory/Intent。默认 SileroVAD + FunASR + ChatGLMLLM + EdgeTTS + nomem |
替换 provider 是明确扩展点。接入智控台后配置从 manager-api 拉取,不能只改本地 config.yaml 就声称完成替换。initialize_modules、默认模块、load_config |
| VAD | Silero ONNX 在 CPU 本地推理,512 samples 窗口、连接独立状态、双阈值、静默结束判断。默认高0.5/低0.3、静默200 ms;manual 模式直接返回有声 | 200 ms 是配置,不是实测响应时间。嘈杂环境和长停顿应调参。VADProvider、VAD 默认阈值 |
| ASR | fun_local.ASRProvider 用 AutoModel 加载 models/SenseVoiceSmall,speech_to_text 调 model.generate。非流式基类在 VAD stop 后识别,要求累计 PCM 字节数大于 1920*15 |
属于句段触发,不是逐字实时 ASR。16 kHz/16-bit 下该门槛约0.9 s累计音频,短指令要专项测。默认模型文件不由两个主仓库 MIT 自动授权。AutoModel / speech_to_text、receive_audio |
| LLM | 默认 ChatGLMLLM 经 openai provider 请求 open.bigmodel.cn。流式 response 与 response_with_functions 返回文本/工具调用,chat 将摘要与对话装配到模型输入,工具递归上限5 |
配置 API key 才能工作,默认不是本地 LLM。Ollama provider 是调用本地 HTTP OpenAI 兼容接口,不在本进程内运行权重。LLM 默认端点、OpenAI provider、Ollama provider、chat |
| TTS | 默认 EdgeTTS 调 edge_tts.Communicate.stream(),TTS 队列经音频发送控制再给设备。GPT-SoVITS 等本地选项也是对另一个服务发 HTTP 请求 |
只部署此 Python 服务不能得到离线 TTS。需要自备服务、模型权重和音色授权。text_to_speak、GPT-SoVITS 服务地址与参考音色 |
| 服务端打断 | AEC 开启且 VAD 有声时可立即 abort;普通 startToChat 在非 manual 模式也会停止既有播报。abort 设置 client_abort、清队列、发送 tts stop | LLM 循环检查 abort,TTS 发送也检查该标记。但上游云请求是否即时停止计费、播放尾音多长,需服务实测。handleAudioMessage、startToChat、handleAbortMessage |
| 默认无跨会话记忆 | nomem 的 save 返回 None、query 返回空字符串;连接仍有 dialogue,会写日志,智控台模式还可上报聊天记录 | “关闭记忆”不等于不保存聊天或不向外发数据。nomem、用户消息 INFO 日志、聊天及音频上报 |
| 本地摘要记忆 | mem_local_short 将对话和历史摘要拼接,用 self.llm.response_no_stream 总结,按 device_id 保存到 data/.memory.yaml;智控台模式转 Java 总结接口。query 直接返回整份短摘要 |
配置注释“不会上传到外部服务器”不能作为隐私保证,默认专用总结模型仍是 ChatGLMLLM。它不是事件溯源、结构化关系库或可验证长期记忆;未见同一 YAML 的原子更新/跨设备文件锁。MemoryProvider、_initialize_memory、本地记忆配置 |
| Mem0 | 使用 MemoryClient(api_key) 向 mem0 服务 add/search,按 role_id 查询 |
该实现是外部记忆服务路径,不能按库名推成完全本地向量库。mem0ai MemoryProvider |
三、认证、存储与生产采用边界
以下属于已读代码及默认配置的风险线索,不是完整安全审计、漏洞复现或公网渗透结论。
| 事实与触发条件 | 对复用的实际影响 | 处理与直接证据 |
|---|---|---|
| 默认监听0.0.0.0,auth.enabled=false。启用 auth 后,allowed_devices 中的 Device-Id 可直接跳过 token | 按示例暴露服务时不能假定每台设备已有可靠身份校验;MAC/Device-Id 是声明的标识 | 隔离实验网络,去除免 token 白名单,为每台设备建立可撤销凭据和 TLS。默认服务和认证配置、_handle_auth |
实际 WS 认证使用 core/auth.py::AuthManager 的 HMAC-SHA256,绑定 client_id/device_id/时间戳,并用 constant-time digest compare |
可以复用协议逻辑;另一个 core/utils/auth.py::AuthToken 的 JWT/AES 类不是此 WS 入口实际使用的类,不能混写 |
本次执行7项正反例及期限边界。部署仍需密钥生成、轮换、OTA签发和撤销策略。AuthManager |
全模块 compose 含示例数据库密码、Redis无密码、seccomp:unconfined、latest 镜像标签 |
默认文件是学习部署配置,不能当已加固的生产清单;MySQL/Redis为容器网络 expose,并非该文件直接发布到宿主公网 | 自建锁 digest 镜像、最小权限、网络隔离、外置秘密与备份。全模块部署配置 |
| manager-api 有 Shiro oauth2、server secret 与 anon 路由 | 控制台具备认证结构,但各资源授权仍需逐路由验证。不能因 download 路由 anon 就断言任意下载,它还查 Redis UUID 并使用后删除 | 先复用设备管理数据模型,接入前审资源归属、下载令牌和管理权限。Shiro 路由、一次性下载 UUID |
| ASR 文本、LLM 用户输入会进 INFO 日志;智控台模式有文本、音频、工具报告,数据库和 uploadfile volume 持久化 | 删除临时音频或 nomem 无法覆盖日志、数据库、音频报告的保留与删除 | 建立采集同意、脱敏、保留期限、跨设备隔离及删除测试。ASR 日志与报告、report、持久化目录 |
| 固件 WS v2/v3 接收分支直接按结构和 payload_size 读二进制数据,在该回调中未见与 len 比较的完整帧长检查 | 属于信任边界审查点,异常服务端或畸形帧影响需专门验证,未在硬件复现 | 自建协议采用 v1 先互通,随后在接收边界补长度/上限/版本校验及 fuzz。二进制接收回调 |
| MCP user-only 控制枚举可见性,执行函数仍按名称调用 | 不能把“LLM看不到”当权限;升级和重启有较大设备影响 | 服务端与设备共用白名单,用户动作走明确授权路径,执行器加入本地限位。工具枚举过滤、执行入口 |
四、许可与可交付资产
(一)逐层许可检查
两仓库根 LICENSE 都为 MIT,均要求保留版权和许可声明。该结论只覆盖其授予范围,不把第三方包、权重、音色、品牌和硬件设计一起归为 MIT。下表是已打开正文的重点依赖核查,不是完整 SBOM 或法务批准。
| 层次 | 核查结果与实际边界 | 直接依据 |
|---|---|---|
| 两个主仓库 | MIT,可按条件复制修改和分发,保留声明。服务端含第三方来源文件时仍需保留原头部/NOTICE | 固件 LICENSE、服务端 LICENSE |
| ESP-IDF | manifest 要求 >=6.0.1,核查 v6.0.1 根许可 Apache-2.0;未展开全部组件许可 | IDF 要求、ESP-IDF v6.0.1 LICENSE |
| ESP-SR | 固件固定2.4.7。ESPRESSIF MIT 的授权限定 Espressif 产品,不能按普通 MIT 理解为任意芯片可迁移 | esp-sr 版本、ESP-SR 2.4.7 许可正文 |
| ESP 音频 codec | manifest 为 ~2.5.0。2.5.0 是 Espressif Modified MIT,明确只能与 Espressif 产品结合,禁止为非 Espressif 产品再分发 | 音频 codec 依赖、esp_audio_codec 2.5.0 许可 |
| LVGL | manifest ~9.5.0,v9.5.0 MIT。字体、表情包和其他下载资产仍需各自核查 | LVGL v9.5.0 LICENSE、显示与资源依赖 |
| FunASR代码 | requirements 固定1.4.16,其 v1.4.16 LICENSE 为 MIT | 固定 Python 依赖、FunASR v1.4.16 LICENSE |
| SenseVoiceSmall权重 | 默认 model_dir 指向该模型。当前官方模型卡标为 other,链接 FunASR 自定义 MODEL_LICENSE v1.1,包括署名、保留模型名及其他条件,不能归为代码 MIT |
默认模型路径、官方模型卡、模型许可正文。两者滚动访问于2026-10-27,尚未下载并固定实际权重 hash |
| Silero VAD | requirements 固定6.2.3,官方 v6.2.3 LICENSE 为 MIT;当前 provider 实际加载本地 ONNX,须对打包的模型文件补 hash 和来源链 | Silero VAD v6.2.3 LICENSE、实际 ONNX 路径 |
| edge-tts | requirements 固定7.3.1,该版本主体 LGPLv3,只有 srt_composer.py 为 MIT;包装库许可不授予 Microsoft 音色权重或服务经营权 | edge-tts 7.3.1 LICENSE、edge-tts 固定版本 |
| 默认音色与可选克隆音色 | 默认 zh-CN-XiaoxiaoNeural 由 Edge 服务生成,仓库没有把音色模型权重授权给集成方。GPT-SoVITS provider 的 ref_audio/ref_text 只是输入接口,没有证明参考说话人授权 | 默认 Edge 音色、参考音色输入。商业音色和参考录音权利未确认,不直接打包为自有资产 |
| Opus 与唤醒词 | Opus 官方 COPYING 包含 BSD式版权条款及专利许可入口,固件实际封装依赖还受 ESP codec 条款约束。ESP-SR 当前 README另明确商业使用唤醒词需相应权利 | Opus COPYING、ESP-SR 唤醒词说明。这两份为访问时滚动版本,未声称与所有传递依赖逐字一致 |
非固定范围依赖、容器镜像、模型下载和 MCU 资源尚未形成可重建物料清单。固件清单存在 ^、~、*,服务端存在 transformers<5、powermem>=0.3.1 等范围。复用前需锁定实际解析版本及制品 hash,而不是只保存两个仓库 commit。见 固件依赖声明、服务端依赖声明。
(二)资产取舍
| 分类 | 具体资产 | 采用方式与不能遗漏的工作 |
|---|---|---|
| 可直接作为开发起点 | Application 状态机、AudioService 队列、Board/AudioCodec 接口 | 在 Espressif 板卡上保留原有分层,选择一个已支持板型建立基线,再替换硬件适配。直接复用是源码起点,不代表已验证本项目硬件 |
| 可直接作为开发起点 | v1 WebSocket hello/listen/abort/Opus 协议、MCP 参数声明和设备工具注册 | 独立固定协议契约,先接只读状态与受限音量工具。保留错误处理、必填/范围校验和主任务调度 |
| 需要改造 | 服务端 provider 接口、连接编排、流式 TTS 和队列 | 裁剪实际需要的 provider,锁定模型/依赖,增加超时、取消、可观测性及并发负载验证。无需引入所有云厂商适配器 |
| 需要改造 | 记忆、智控台、认证、部署文件 | 记忆改为有来源与删除机制的存储;明确用户/设备隔离;替换示例部署参数,管理台按产品需求决定是否保留 |
| 不直接采用 | 原默认配置作为生产部署、默认角色/音色/唤醒词作为自有商业资产、将小智作为独立桌面整机复制 | 原配置仍含外部服务依赖与未确认内容授权;不包含完整整机交付。只借鉴接口与结构,不将 README 演示等同于交付 |
逐项路径、符号、许可边界与固定证据见 xiaozhi-assets.json。
五、替换路径与最小复用验证
(一)保持接口的替换方案
| 目标 | 最小替换 | 必须同时验证 |
|---|---|---|
| 自建语音服务 | 保留固件 v1 WebSocket,服务端只启用一种 ASR、一种 LLM、一种 TTS | hello 音频参数、Opus帧时长、listen/abort/tts顺序、断线回 idle 和重连 |
| 局域网离线试验 | 保留本地 Silero/FunASR,LLM改 Ollama 或本地 OpenAI兼容端点,TTS改已有本地 HTTP provider;关闭外网天气/搜索等工具 | 模型制品提前准备并锁hash,主LLM及记忆LLM都指向本地,停掉公网网络验证实际出站请求为0。已有接口见 Ollama、本地TTS适配器 |
| 最小数据保留 | 初期选 nomem,关闭不必要上报,日志脱敏并设置保留周期 | 确认日志、上传目录、MySQL、备份四条路径,不只检查 memory 文件 |
| 桌面动作工具 | 复用 MCP 参数声明,增加一个有限幅度/有限速度的动作工具 | 设备本地限位与紧急停止不依赖 LLM;未授权工具0次执行,错误参数0次驱动硬件 |
离线方案是后续验证建议。未安装 Ollama、ASR/TTS服务、依赖或模型,不作“已离线跑通”结论。
(二)本次完成的局部验证
实际执行时间 2026-10-26 18:31:05 UTC,Windows 11,既有 Python 3.13.9。未安装依赖。上游服务推荐 Python 3.10,因此该结果只证明被测纯标准库模块在当前解释器下行为,不证明整服务兼容 Python 3.13。
| 验证 | 方法与结果 | 不能证明的内容 |
|---|---|---|
| AuthManager | 直接 import 下载的 core/auth.py,以固定时间测试正确身份、错误client、错误device、篡改签名、畸形token、期限恰好边界与边界后,7项通过 |
未测 OTA签发、管理台认证、TLS、吊销或攻击者能力 |
| hello协商与顺序 | 从原始 helloHandle.py AST 提取未修改函数,替换 transport/MCP/logger协作者执行,确认客户端音频参数原样回传、hello先于MCP初始化、AEC标志生效,3项通过 |
不是完整 WebSocket 集成测试,也未测试不同采样率音频质量 |
| 固件契约 | 静态 assert 上行Opus/16k/mono、60ms帧、显式队列容量,3项通过 | 未编译 C++、未验证编解码正确性或硬件实时行为 |
共 13项通过,是局部函数执行与静态契约核验,不是语法检查冒称端到端。脚本、输出及被测文件 SHA-256保存在 研究底稿(未随网页发布) 与 verification-results.json。
(三)下一轮最小实测与量化观察项
下列样本量是建议验证方案,不是已取得性能数据。先用最新 release 建稳定基线,再对本报告 main 快照做相同测试,以区分版本变化。
- 无硬件协议回放:启动隔离服务,固定 v1、一个provider组合,使用授权录音回放30轮短句与30轮长句,记录有效ASR比例、空结果、首个LLM token、首个TTS包和完整回复时间,报告P50/P95与失败数。重点加入小于1秒短指令,核对ASR门槛影响。
- 一块硬件闭环:在固定板卡、麦克风、参考音频和扬声器条件下运行,记录唤醒漏检/误检、上行编码丢帧、播放欠载、堆内存低水位、重连次数。每个AEC模式独立记录,不跨硬件宣称通用效果。
- 打断与断网:30次播报中插话和30次唤醒词打断,记录用户声音开始至扬声器停声的P50/P95、旧回复尾音和误打断;关闭网络20次,核对idle恢复、重复工具执行、残留队列和资源回收。
- 工具与数据边界:覆盖缺参、错类型、越界值、未知工具、未授权用户、重放请求;观察被拒次数、实际执行次数、MCP错误码。两设备并发修改记忆并模拟进程中断,核对串档、丢失和可恢复性。
- 离线与保留:在预装模型后封锁公网,完成同一回放,记录全部DNS/HTTP目的地与失败项;删除一个测试用户数据后核对日志、音频、摘要、数据库和备份残留。只在出站为0并完成核心对话后才称该配置离线。
六、证据与未核验范围
正文表格中的永久 GitHub commit 链接是实现证据,许可证表标注版本或滚动访问。正式资产清单维护路径、符号和许可边界。临时目录保留两个固定源码 ZIP、解压源码、GitHub元数据、重点许可原文、局部验证脚本与JSON输出。
已深入阅读启动/音频状态转换、WS/MQTT协议、MCP注册与调用、VAD/ASR/LLM/TTS代表实现、记忆和认证入口,针对性阅读控制台路由及部署配置。未读完所有板型、全部provider、Java业务和前端页面,未运行模型服务、硬件、完整控制台、性能压测或安全审计。没有修改上游源码、公司仓库、发布网站或上传飞书。