> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

# 一、结论与范围

小智适合作为桌面智能硬件的**语音与设备工具底座候选**。最有复用价值的是 ESP32 固件的音频状态机、传输协议与 MCP 工具注册，以及第三方服务端的 provider 接口和流式编排。服务端需要安全、数据治理和可复现构建改造后再评估产品接入。仓库当前仍明确要求不要用于生产环境，见 [服务端生产警告](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/README.md#L155-L161)。

它不是新发布的独立桌面整机。固件始于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`](https://github.com/78/xiaozhi-esp32/commit/c435f99a88066029ec2dbd2d758c8cc9d051565b)，提交时间2026-10-25 20:37:57 | [v2.5.2](https://github.com/78/xiaozhi-esp32/releases/tag/v2.5.2)，发布2026-10-11 20:49:36，tag → `49b4380b3faa0ceadd28a3e78aaf0f311c46c57e` |
| `xinnan-tech/xiaozhi-esp32-server`，2025-02-02 14:25:16 | [`a377d89dcd58e6e18417a57e9357c0dd23657746`](https://github.com/xinnan-tech/xiaozhi-esp32-server/commit/a377d89dcd58e6e18417a57e9357c0dd23657746)，提交时间2026-10-26 14:47:47 | [v0.9.8](https://github.com/xinnan-tech/xiaozhi-esp32-server/releases/tag/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`。

# 二、源码链路与实现边界

## （一）固件启动、唤醒、音频与打断

![小智语音底座 源码研究 图示](<../diagrams/%E5%B0%8F%E6%99%BA%E8%AF%AD%E9%9F%B3%E5%BA%95%E5%BA%A7%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6%201.png>)

```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](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/main.cc#L14-L29)、[Application::Initialize](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/application.cc#L66-L180) |
| 状态转换 | `DeviceStateMachine` 显式允许启动、联网、激活、idle、connecting、listening、speaking、升级等转换，非法转换返回 false | 这是具体状态机，不是 README 能力列表。可复用状态与回调，但要为自己的掉线/关机/执行器状态补测试。[IsValidTransition / TransitionTo](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/device_state_machine.cc#L36-L143) |
| 前处理 | AFE 输入格式区分麦克风 `M` 与参考信号 `R`，AEC 初始化取决于 codec 的 `input_reference()`，WakeNet/自定义唤醒模型从资源模型中选择 | 有 AEC 代码不等于所有硬件全双工有效，必须有参考音频链路并校准音量、延迟和麦克风布局。[AfeAudioEngine::Initialize](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/audio/engines/afe_audio_engine.cc#L51-L158) |
| 音频队列 | 采集、输出、Opus 编解码分任务。上行16 kHz、mono、60 ms。编码队列2项，播放队列2项，解码包20项（1.2 s），发送包40项（2.4 s） | 后两项是配置容量，不是测得端到端时延。编码饱和有丢帧计数，适合接入量化监测。[音频链路和队列配置](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/audio/audio_service.h#L30-L81)、[PushTaskToEncodeQueue](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/audio/audio_service.cc#L569-L607) |
| 唤醒 | idle → connecting → 打开音频通道 → listening。失败返回 idle；唤醒音频是否上送由 `CONFIG_SEND_WAKE_WORD_DATA` 控制 | 唤醒可以本地完成，后续对话仍依赖服务器。[HandleWakeWordDetectedEvent / ContinueWakeWordInvoke](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/application.cc#L922-L1017) |
| 打断 | speaking/listening 时的唤醒会发 `abort`，清空待发送音频并切回监听。speaking 非 realtime 模式关闭语音处理，仅保留 AFE 唤醒能力。AEC off 默认 auto，AEC on 默认 realtime | 打断有唤醒词、手动与服务端 VAD 不同路径，不能一概称“全场景自然插话”。实际残留音频和误打断未测。[状态驱动音频开关](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/application.cc#L1032-L1085)、[AbortSpeaking / GetDefaultListeningMode](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/application.cc#L1268-L1282)、[abort / listen 消息](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/protocols/protocol.cc#L66-L99) |

## （二）协议与设备工具

| **模块** | **实现与接口** | **需要保留或改造的边界** |
|---|---|---|
| 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](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/protocols/websocket_protocol.cc#L25-L55)、[OpenAudioChannel](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/protocols/websocket_protocol.cc#L82-L113)、[_route_message / MQTT audio](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/connection.py#L368-L409) |
| 协商 | 服务端 `handleHelloMessage` 将客户端 `audio_params` 回填 welcome，再发送 hello，随后异步初始化 MCP | 默认配置的24 kHz不等于当前固件握手后必然使用24 kHz。本次隔离函数执行已验证16 kHz被回传；未编码/播放音频。[handleHelloMessage](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/handle/helloHandle.py#L42-L67) |
| MQTT + UDP | MQTT 传控制 JSON、UDP 传带16字节头和 AES-CTR 加密的音频，头含长度/时间戳/序号，接收检查短包、长度和旧序号 | Python 服务端的 MQTT 路线需额外网关转接 WebSocket，网关是第三个仓库，未包含在本次两个仓库审查内。AES-CTR 本身不提供消息认证，不能据“加密”推断完整性已保证。[SendAudio](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/protocols/mqtt_protocol.cc#L204-L246)、[UDP OnMessage](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/protocols/mqtt_protocol.cc#L301-L369)、[网关部署边界](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/docs/mqtt-gateway-integration.md#L1-L19) |
| 设备 MCP | `McpServer` 实现 JSON-RPC 2.0、initialize、tools/list、tools/call，协议版本2024-11-05。工具参数按声明校验类型、范围、必填值，再排入 Application 主任务 | 可直接复用工具注册和参数声明模式，不能替代业务授权。`user_only` 在工具列表中过滤，`DoToolCall` 按名称查找全部工具，未见同层用户授权判断。应在受信服务端与设备执行入口添加动作白名单和能力授权。[ParseMessage](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L393-L478)、[GetToolsList](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L527-L558)、[DoToolCall](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L586-L647) |
| 工具示例 | 音量、亮度、主题、拍照等通用工具，reboot、固件升级等列入 user-only。服务端 `DeviceMCPExecutor` 把模型工具参数发送设备，结果回入 LLM | 屏幕/舵机适配可复用该模式，摄像头、重启、升级需要明确用户权限。模型看不见某工具不等于对端无法调用它。[AddCommonTools](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L40-L115)、[AddUserOnlyTools](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L124-L164)、[DeviceMCPExecutor.execute](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/tools/device_mcp/mcp_executor.py#L13-L62) |

## （三）服务端 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](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/utils/modules_initialize.py#L10-L109)、[默认模块](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L232-L245)、[load_config](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config/config_loader.py#L25-L46) |
| VAD | Silero ONNX 在 CPU 本地推理，512 samples 窗口、连接独立状态、双阈值、静默结束判断。默认高0.5/低0.3、静默200 ms；manual 模式直接返回有声 | 200 ms 是配置，不是实测响应时间。嘈杂环境和长停顿应调参。[VADProvider](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/vad/silero.py#L13-L116)、[VAD 默认阈值](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L605-L611) |
| 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](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/asr/fun_local.py#L40-L98)、[receive_audio](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/asr/base.py#L60-L83) |
| LLM | 默认 ChatGLMLLM 经 `openai` provider 请求 `open.bigmodel.cn`。流式 response 与 response_with_functions 返回文本/工具调用，chat 将摘要与对话装配到模型输入，工具递归上限5 | 配置 API key 才能工作，默认不是本地 LLM。Ollama provider 是调用本地 HTTP OpenAI 兼容接口，不在本进程内运行权重。[LLM 默认端点](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L656-L668)、[OpenAI provider](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/llm/openai/openai.py#L27-L127)、[Ollama provider](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/llm/ollama/ollama.py#L10-L49)、[chat](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/connection.py#L1055-L1158) |
| TTS | 默认 EdgeTTS 调 `edge_tts.Communicate.stream()`，TTS 队列经音频发送控制再给设备。GPT-SoVITS 等本地选项也是对另一个服务发 HTTP 请求 | 只部署此 Python 服务不能得到离线 TTS。需要自备服务、模型权重和音色授权。[text_to_speak](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/tts/edge.py#L46-L74)、[GPT-SoVITS 服务地址与参考音色](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/tts/gpt_sovits_v2.py#L10-L18) |
| 服务端打断 | AEC 开启且 VAD 有声时可立即 abort；普通 startToChat 在非 manual 模式也会停止既有播报。abort 设置 client_abort、清队列、发送 tts stop | LLM 循环检查 abort，TTS 发送也检查该标记。但上游云请求是否即时停止计费、播放尾音多长，需服务实测。[handleAudioMessage](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/handle/receiveAudioHandle.py#L17-L36)、[startToChat](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/handle/receiveAudioHandle.py#L93-L117)、[handleAbortMessage](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/handle/abortHandle.py#L9-L20) |
| 默认无跨会话记忆 | nomem 的 save 返回 None、query 返回空字符串；连接仍有 dialogue，会写日志，智控台模式还可上报聊天记录 | “关闭记忆”不等于不保存聊天或不向外发数据。[nomem](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/memory/nomem/nomem.py#L10-L20)、[用户消息 INFO 日志](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/connection.py#L1059-L1066)、[聊天及音频上报](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/handle/reportHandle.py#L24-L50) |
| 本地摘要记忆 | `mem_local_short` 将对话和历史摘要拼接，用 `self.llm.response_no_stream` 总结，按 device_id 保存到 data/.memory.yaml；智控台模式转 Java 总结接口。query 直接返回整份短摘要 | 配置注释“不会上传到外部服务器”不能作为隐私保证，默认专用总结模型仍是 ChatGLMLLM。它不是事件溯源、结构化关系库或可验证长期记忆；未见同一 YAML 的原子更新/跨设备文件锁。[MemoryProvider](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/memory/mem_local_short/mem_local_short.py#L98-L201)、[_initialize_memory](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/connection.py#L959-L998)、[本地记忆配置](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L350-L356) |
| Mem0 | 使用 `MemoryClient(api_key)` 向 mem0 服务 add/search，按 role_id 查询 | 该实现是外部记忆服务路径，不能按库名推成完全本地向量库。[mem0ai MemoryProvider](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/memory/mem0ai/mem0ai.py#L12-L99) |

# 三、认证、存储与生产采用边界

以下属于已读代码及默认配置的风险线索，不是完整安全审计、漏洞复现或公网渗透结论。

| **事实与触发条件** | **对复用的实际影响** | **处理与直接证据** |
|---|---|---|
| 默认监听0.0.0.0，auth.enabled=false。启用 auth 后，allowed_devices 中的 Device-Id 可直接跳过 token | 按示例暴露服务时不能假定每台设备已有可靠身份校验；MAC/Device-Id 是声明的标识 | 隔离实验网络，去除免 token 白名单，为每台设备建立可撤销凭据和 TLS。[默认服务和认证配置](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L9-L36)、[_handle_auth](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/websocket_server.py#L210-L231) |
| 实际 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](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/auth.py#L13-L72) |
| 全模块 compose 含示例数据库密码、Redis无密码、`seccomp:unconfined`、latest 镜像标签 | 默认文件是学习部署配置，不能当已加固的生产清单；MySQL/Redis为容器网络 expose，并非该文件直接发布到宿主公网 | 自建锁 digest 镜像、最小权限、网络隔离、外置秘密与备份。[全模块部署配置](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/docker-compose_all.yml#L6-L92) |
| manager-api 有 Shiro oauth2、server secret 与 anon 路由 | 控制台具备认证结构，但各资源授权仍需逐路由验证。不能因 download 路由 anon 就断言任意下载，它还查 Redis UUID 并使用后删除 | 先复用设备管理数据模型，接入前审资源归属、下载令牌和管理权限。[Shiro 路由](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/manager-api/src/main/java/xiaozhi/modules/security/config/ShiroConfig.java#L61-L108)、[一次性下载 UUID](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/manager-api/src/main/java/xiaozhi/modules/agent/controller/AgentChatHistoryController.java#L102-L126) |
| ASR 文本、LLM 用户输入会进 INFO 日志；智控台模式有文本、音频、工具报告，数据库和 uploadfile volume 持久化 | 删除临时音频或 nomem 无法覆盖日志、数据库、音频报告的保留与删除 | 建立采集同意、脱敏、保留期限、跨设备隔离及删除测试。[ASR 日志与报告](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/asr/base.py#L133-L177)、[report](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/handle/reportHandle.py#L24-L50)、[持久化目录](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/docker-compose_all.yml#L51-L79) |
| 固件 WS v2/v3 接收分支直接按结构和 payload_size 读二进制数据，在该回调中未见与 len 比较的完整帧长检查 | 属于信任边界审查点，异常服务端或畸形帧影响需专门验证，未在硬件复现 | 自建协议采用 v1 先互通，随后在接收边界补长度/上限/版本校验及 fuzz。[二进制接收回调](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/protocols/websocket_protocol.cc#L115-L146) |
| MCP user-only 控制枚举可见性，执行函数仍按名称调用 | 不能把“LLM看不到”当权限；升级和重启有较大设备影响 | 服务端与设备共用白名单，用户动作走明确授权路径，执行器加入本地限位。[工具枚举过滤](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L527-L558)、[执行入口](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/mcp_server.cc#L586-L647) |

# 四、许可与可交付资产

## （一）逐层许可检查

两仓库根 LICENSE 都为 MIT，均要求保留版权和许可声明。该结论只覆盖其授予范围，不把第三方包、权重、音色、品牌和硬件设计一起归为 MIT。下表是已打开正文的重点依赖核查，不是完整 SBOM 或法务批准。

| **层次** | **核查结果与实际边界** | **直接依据** |
|---|---|---|
| 两个主仓库 | MIT，可按条件复制修改和分发，保留声明。服务端含第三方来源文件时仍需保留原头部/NOTICE | [固件 LICENSE](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/LICENSE#L1-L21)、[服务端 LICENSE](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/LICENSE#L1-L20) |
| ESP-IDF | manifest 要求 >=6.0.1，核查 v6.0.1 根许可 Apache-2.0；未展开全部组件许可 | [IDF 要求](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/idf_component.yml#L154-L156)、[ESP-IDF v6.0.1 LICENSE](https://github.com/espressif/esp-idf/blob/v6.0.1/LICENSE) |
| ESP-SR | 固件固定2.4.7。ESPRESSIF MIT 的授权限定 Espressif 产品，不能按普通 MIT 理解为任意芯片可迁移 | [esp-sr 版本](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/idf_component.yml#L40-L45)、[ESP-SR 2.4.7 许可正文](https://components.espressif.com/components/espressif/esp-sr/versions/2.4.7/license) |
| ESP 音频 codec | manifest 为 ~2.5.0。2.5.0 是 Espressif Modified MIT，明确只能与 Espressif 产品结合，禁止为非 Espressif 产品再分发 | [音频 codec 依赖](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/idf_component.yml#L29-L32)、[esp_audio_codec 2.5.0 许可](https://components.espressif.com/components/espressif/esp_audio_codec/versions/2.5.0/license) |
| LVGL | manifest ~9.5.0，v9.5.0 MIT。字体、表情包和其他下载资产仍需各自核查 | [LVGL v9.5.0 LICENSE](https://github.com/lvgl/lvgl/blob/v9.5.0/LICENCE.txt)、[显示与资源依赖](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/idf_component.yml#L73-L84) |
| FunASR代码 | requirements 固定1.4.16，其 v1.4.16 LICENSE 为 MIT | [固定 Python 依赖](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/requirements.txt#L1-L18)、[FunASR v1.4.16 LICENSE](https://github.com/modelscope/FunASR/blob/v1.4.16/LICENSE) |
| SenseVoiceSmall权重 | 默认 model_dir 指向该模型。当前官方模型卡标为 `other`，链接 FunASR 自定义 MODEL_LICENSE v1.1，包括署名、保留模型名及其他条件，不能归为代码 MIT | [默认模型路径](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L358-L365)、[官方模型卡](https://huggingface.co/FunAudioLLM/SenseVoiceSmall/blob/main/README.md)、[模型许可正文](https://github.com/modelscope/FunASR/blob/main/MODEL_LICENSE)。两者滚动访问于2026-10-27，尚未下载并固定实际权重 hash |
| Silero VAD | requirements 固定6.2.3，官方 v6.2.3 LICENSE 为 MIT；当前 provider 实际加载本地 ONNX，须对打包的模型文件补 hash 和来源链 | [Silero VAD v6.2.3 LICENSE](https://github.com/snakers4/silero-vad/blob/v6.2.3/LICENSE)、[实际 ONNX 路径](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/vad/silero.py#L13-L27) |
| edge-tts | requirements 固定7.3.1，该版本主体 LGPLv3，只有 srt_composer.py 为 MIT；包装库许可不授予 Microsoft 音色权重或服务经营权 | [edge-tts 7.3.1 LICENSE](https://github.com/rany2/edge-tts/blob/7.3.1/LICENSE)、[edge-tts 固定版本](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/requirements.txt#L17-L20) |
| 默认音色与可选克隆音色 | 默认 zh-CN-XiaoxiaoNeural 由 Edge 服务生成，仓库没有把音色模型权重授权给集成方。GPT-SoVITS provider 的 ref_audio/ref_text 只是输入接口，没有证明参考说话人授权 | [默认 Edge 音色](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/config.yaml#L770-L776)、[参考音色输入](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/tts/gpt_sovits_v2.py#L10-L18)。商业音色和参考录音权利未确认，不直接打包为自有资产 |
| Opus 与唤醒词 | Opus 官方 COPYING 包含 BSD式版权条款及专利许可入口，固件实际封装依赖还受 ESP codec 条款约束。ESP-SR 当前 README另明确商业使用唤醒词需相应权利 | [Opus COPYING](https://github.com/xiph/opus/blob/main/COPYING)、[ESP-SR 唤醒词说明](https://github.com/espressif/esp-sr/blob/master/README.md)。这两份为访问时滚动版本，未声称与所有传递依赖逐字一致 |

非固定范围依赖、容器镜像、模型下载和 MCU 资源尚未形成可重建物料清单。固件清单存在 `^`、`~`、`*`，服务端存在 `transformers<5`、`powermem>=0.3.1` 等范围。复用前需锁定实际解析版本及制品 hash，而不是只保存两个仓库 commit。见 [固件依赖声明](https://github.com/78/xiaozhi-esp32/blob/c435f99a88066029ec2dbd2d758c8cc9d051565b/main/idf_component.yml#L1-L47)、[服务端依赖声明](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/requirements.txt#L1-L30)。

## （二）资产取舍

| **分类** | **具体资产** | **采用方式与不能遗漏的工作** |
|---|---|---|
| 可直接作为开发起点 | Application 状态机、AudioService 队列、Board/AudioCodec 接口 | 在 Espressif 板卡上保留原有分层，选择一个已支持板型建立基线，再替换硬件适配。直接复用是源码起点，不代表已验证本项目硬件 |
| 可直接作为开发起点 | v1 WebSocket hello/listen/abort/Opus 协议、MCP 参数声明和设备工具注册 | 独立固定协议契约，先接只读状态与受限音量工具。保留错误处理、必填/范围校验和主任务调度 |
| 需要改造 | 服务端 provider 接口、连接编排、流式 TTS 和队列 | 裁剪实际需要的 provider，锁定模型/依赖，增加超时、取消、可观测性及并发负载验证。无需引入所有云厂商适配器 |
| 需要改造 | 记忆、智控台、认证、部署文件 | 记忆改为有来源与删除机制的存储；明确用户/设备隔离；替换示例部署参数，管理台按产品需求决定是否保留 |
| 不直接采用 | 原默认配置作为生产部署、默认角色/音色/唤醒词作为自有商业资产、将小智作为独立桌面整机复制 | 原配置仍含外部服务依赖与未确认内容授权；不包含完整整机交付。只借鉴接口与结构，不将 README 演示等同于交付 |

逐项路径、符号、许可边界与固定证据见 [xiaozhi-assets.json](<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](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/llm/ollama/ollama.py#L10-L49)、[本地TTS适配器](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/a377d89dcd58e6e18417a57e9357c0dd23657746/main/xiaozhi-server/core/providers/tts/gpt_sovits_v2.py#L10-L18) |
| 最小数据保留 | 初期选 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 快照做相同测试，以区分版本变化。

1. **无硬件协议回放**：启动隔离服务，固定 v1、一个provider组合，使用授权录音回放30轮短句与30轮长句，记录有效ASR比例、空结果、首个LLM token、首个TTS包和完整回复时间，报告P50/P95与失败数。重点加入小于1秒短指令，核对ASR门槛影响。
2. **一块硬件闭环**：在固定板卡、麦克风、参考音频和扬声器条件下运行，记录唤醒漏检/误检、上行编码丢帧、播放欠载、堆内存低水位、重连次数。每个AEC模式独立记录，不跨硬件宣称通用效果。
3. **打断与断网**：30次播报中插话和30次唤醒词打断，记录用户声音开始至扬声器停声的P50/P95、旧回复尾音和误打断；关闭网络20次，核对idle恢复、重复工具执行、残留队列和资源回收。
4. **工具与数据边界**：覆盖缺参、错类型、越界值、未知工具、未授权用户、重放请求；观察被拒次数、实际执行次数、MCP错误码。两设备并发修改记忆并模拟进程中断，核对串档、丢失和可恢复性。
5. **离线与保留**：在预装模型后封锁公网，完成同一回放，记录全部DNS/HTTP目的地与失败项；删除一个测试用户数据后核对日志、音频、摘要、数据库和备份残留。只在出站为0并完成核心对话后才称该配置离线。

# 六、证据与未核验范围

正文表格中的永久 GitHub commit 链接是实现证据，许可证表标注版本或滚动访问。正式资产清单维护路径、符号和许可边界。临时目录保留两个固定源码 ZIP、解压源码、GitHub元数据、重点许可原文、局部验证脚本与JSON输出。

已深入阅读启动/音频状态转换、WS/MQTT协议、MCP注册与调用、VAD/ASR/LLM/TTS代表实现、记忆和认证入口，针对性阅读控制台路由及部署配置。未读完所有板型、全部provider、Java业务和前端页面，未运行模型服务、硬件、完整控制台、性能压测或安全审计。没有修改上游源码、公司仓库、发布网站或上传飞书。
