Xiaozhi AI Architecture Audit

你现在负责对 Xiaozhi AI 项目进行一次 Architecture Audit。

本次任务是：

只分析，不修改代码。

项目包含两个 Repository：

1. Xiaozhi Client —— 硬件端 / Device Runtime
2. Xiaozhi Server —— Server / AI / Backend

同时提供了一份《Xiaozhi AI 开放应用平台 Master Plan》。

Master Plan 是未来目标架构，但当前代码很可能与目标架构存在较大差异。

你的任务不是立即实现 Master Plan，而是：

找出当前系统是什么、已经具备什么、缺少什么，以及应该以什么最小代价逐步演进到目标架构。

---

一、禁止事项

本阶段禁止：

• 修改代码
• 删除代码
• 重构代码
• 创建新的业务模块
• 修改数据库
• 修改 API
• 修改协议
• 修改配置
• 修改硬件端逻辑

只允许：

• 阅读代码
• 分析代码
• 建立架构认知
• 输出分析报告
• 提出建议

---

二、Audit 范围

必须同时分析 Client 和 Server。

不要只看目录结构。

需要追踪真实代码调用链。

---

三、Client Audit

重点分析：

1. 当前 Runtime

回答：

• Client 当前启动流程是什么？
• 主循环在哪里？
• 当前 Conversation / Chat Runtime 在哪里？
• 用户说话 → ASR → LLM → TTS → 播放的完整调用链是什么？
• Audio Input / Output 如何实现？
• 是否已经存在 Event / Message / Command 机制？
• Server 与 Client 使用什么通信协议？

---

2. 硬件能力

整理当前已经存在的：

• 麦克风
• 扬声器
• 音频播放
• 音频录音
• VAD
• 按键
• LED
• 屏幕（如果有）
• SD Card
• 网络
• MQTT / WebSocket / HTTP 等通信能力

并指出哪些能力已经可以直接作为未来 Skill。

---

3. 找出当前可以抽象成 Skill 的能力

例如：

play_audio
record_audio
listen
speak
wait
display
led
button

但不要强行创造不存在的能力。

必须基于真实代码分析。

---

4. 当前 Chat Architecture

重点回答：

Audio Input
    ↓
VAD
    ↓
ASR
    ↓
Conversation
    ↓
LLM
    ↓
TTS
    ↓
Audio Output

实际代码中分别对应什么模块、类、函数和文件？

---

5. Task Runtime 插入点

重点分析：

未来增加：

Task
 ↓
Step
 ↓
Skill

应该插入现有 Client 的什么位置？

重点回答：

如何做到“不破坏现有 Chat 功能”的情况下增加 Task Runtime。

---

四、Server Audit

重点分析：

1. Server 当前架构

分析：

• Server 启动入口
• API
• WebSocket
• MQTT
• Session
• User
• Device
• Conversation
• Audio
• ASR
• LLM
• TTS

之间的关系。

---

2. 当前对话链路

完整追踪：

Device
 ↓
Server
 ↓
ASR
 ↓
Conversation
 ↓
LLM
 ↓
TTS
 ↓
Device

指出真实代码实现位置。

---

3. 数据库

列出当前与以下对象相关的数据表：

User
Device
Conversation
Message
Audio
Session

以及其他与未来 Task 系统可能相关的表。

说明：

• 表结构
• 主键
• 外键
• 关系
• 当前数据生命周期

---

五、重点寻找未来 Domain Model 的落点

对以下概念逐一分析：

App
Task
Step
Skill
InteractionMode
TaskInstance
StepInstance
Event
Audio
Assessment
Metric
Schedule
Plan
Subscription

对于每一个概念回答：

1. 当前代码中是否已经存在类似概念？
2. 如果存在，在哪里？
3. 是否可以复用？
4. 是否需要扩展？
5. 是否需要新建？
6. 最适合放在哪个 Repository / Module？

---

六、重点分析 InteractionMode

Master Plan 中：

InteractionMode 不是业务场景，而是 Xiaozhi 的硬件交互方式。

重点确认当前代码是否存在类似：

Chat
Audio Playback
Recording
Listening
Translation
Game

或者其他模式。

分析：

InteractionMode 最适合放在 Client、Server，还是两边都有？

并给出推荐。

---

七、重点分析 Task Runtime

这是本次 Audit 最重要的部分。

回答：

当前系统应该如何从：

Conversation Runtime

逐步演进为：

Device Runtime
    ├── Chat Runtime
    └── Task Runtime
          ├── Step
          └── Skill

不要直接设计新代码。

先分析：

当前代码在哪里最适合插入这个 Runtime。

---

八、重点分析 Audio / Recording

未来 Server 需要保存儿童 Task 执行过程中的语音。

因此分析：

• 当前录音在哪里产生？
• 音频是否已经上传 Server？
• 音频格式是什么？
• 是否可以保存原始音频？
• 当前音频生命周期是什么？
• 是否存在 Audio ID？
• 是否存在 Session ID？
• 是否可以关联到 TaskInstance / StepInstance？

指出未来最小改造方案。

---

九、重点分析 Event

检查当前是否已经存在：

Event
Message
Command
State
Callback

等机制。

如果存在：

判断能否演进成统一 Event Architecture。

如果不存在：

指出最合适的插入位置。

---

十、最终输出 Audit Report

最终不要只输出总结。

必须输出以下内容：

1. Current Architecture

分别画出：

Client Architecture
Server Architecture

最好使用 Mermaid。

---

2. Current Runtime Call Graph

画出：

用户说话
 ↓
...

对应真实代码模块。

---

3. Existing Capability Map

整理：

Capability
Current Implementation
Repository
Module
Reusable?
Required Change

---

4. Domain Mapping

建立：

Master Plan Domain
        ↓
Current Code
        ↓
Gap
        ↓
Recommended Location

---

5. Architecture Gap

明确列出：

P0 必须解决
P1 后续解决
P2 未来平台化解决

---

6. Recommended Evolution Architecture

不是要求立即实现。

而是说明：

Current
   ↓
Phase 1
   ↓
Phase 2
   ↓
Phase 3
   ↓
Target Architecture

---

7. 最关键的修改点

最终明确列出：

Client

需要改哪些模块。

Server

需要改哪些模块。

Database

需要新增/修改哪些实体。

Protocol

需要增加哪些消息。

API

需要增加哪些接口。

但此阶段只提出，不实现。

---

十一、最终必须回答的核心问题

请特别回答以下问题：

Q1

当前 Chat Runtime 能否直接作为未来 Task Runtime 的一个子 Runtime？

---

Q2

Task Runtime 最适合放在 Client 还是 Server？

请结合当前代码分析，而不是只根据理论回答。

---

Q3

Step 状态应该由 Client 保存、Server 保存，还是两边都有？

---

Q4

Task 执行过程中 Server 与 Client 的状态同步机制应该如何设计？

---

Q5

App / Task / Resource 是否可以完全通过 JSON + Audio Resource 下发，而不需要 OTA？

如果不能，请指出哪些能力必须固化到 Firmware。

---

Q6

当前代码距离：

App
 ↓
Task
 ↓
Step
 ↓
Skill
 ↓
Device Capability

最大的架构障碍是什么？

---

Q7

如何以最小修改实现第一个：

英语复读 Task

而不破坏现有 Chat？

---

Q8

如何以最小修改实现：

英语跟读
 ↓
录音
 ↓
上传
 ↓
ASR
 ↓
Assessment

---

十二、最终结论

最后给出：

Architecture Audit Conclusion

并明确：

1. 当前架构可以保留什么
2. 当前架构必须改什么
3. 第一阶段应该改什么
4. 哪些事情现在绝对不要做
5. 下一阶段应该如何生成 Phase 1 Coding Plan

再次强调：

本次任务的目标不是写代码，而是建立对当前系统的完整架构认知，并找到从 Current Architecture 到 Master Plan 的最小演进路径。

完成 Audit 后停止。

等待下一步指令。