Version: V1.0
Date: 2026-08-30
Purpose: 作为 Xiaozhi AI 硬件端、Server 端、小程序端以及未来开发者开放平台的最高层架构设计与 AI Coding 总体指导文档。
将现有 Xiaozhi AI 从：
AI 对话硬件
逐步升级为：
AI Application Terminal
最终形态类似：
手机
└── 可以安装多个 App
└── 每个 App 包含多个 Task
└── 每个 Task 包含多个 Step
└── Step 调用底层能力
但是 Xiaozhi 与手机的核心区别是：
手机：
用户主动选择 App → 主动操作
Xiaozhi：
家长配置 → 系统调度 → Xiaozhi 主动执行 → 儿童参与
因此 Xiaozhi 最终不是单纯的聊天机器人，而是：
一个可以承载多个 AI App，并根据家长配置主动执行 Task，同时持续记录、评估和分析儿童行为的 AI 终端平台。
最终整个系统由：
Xiaozhi Device
│
│
Xiaozhi Server
│
├── App Platform
├── Task Platform
├── Assessment Platform
├── User Data Platform
├── Developer Platform
├── Subscription Platform
└── Parent Platform
组成。
用户关系：
平台
│
├── App A
│ ├── Task 1
│ ├── Task 2
│ └── Task 3
│
├── App B
│ ├── Task 1
│ └── Task 2
│
└── App C
└── ...
一个孩子可以订阅多个 App。
但是：
同一时间
只能运行一个 App / Task Runtime
因此不要求 Xiaozhi 硬件同时运行多个复杂应用。
整个系统必须坚持以下原则。
App 不应该等同于硬件功能。
例如：
英语学习 App
回忆录 App
益智游戏 App
AI 主持人 App
都是逻辑应用。
系统最终执行的是：
Task
而不是：
Scenario
例如：
英语 App
├── 英语跟读 10 次
├── 单词复习
└── 英语听力
其中：
英语跟读 10 次
就是一个 Task。
本项目中不再把 Scenario 理解为：
业务场景
而定义为：
Device Interaction Mode
即：
Xiaozhi 在执行 Task 时，应该以什么方式与用户交互。
例如：
CHAT
PLAY_AUDIO
REPEAT
FOLLOW_READ
QUESTION_ANSWER
TRANSLATION
CALCULATION
MEMORY
GAME
SILENT
因此：
Task
↓
指定 Interaction Mode
↓
Device Runtime
↓
以对应方式执行
例如：
Task：
听英语复读机 10 遍
interactionMode：
PLAY_AUDIO
steps：
播放 → 等待 → 播放 → 等待 ...
不需要额外建立：
Scenario
↓
Task
这样的业务层级。
统一模型：
App
└── Task
└── Step
└── Action / Skill
例如：
English App
└── English Repeat 10 Times
├── Play Audio
├── Wait
├── Record
├── Evaluate
└── Repeat
Task 负责：
做什么
Step 负责：
具体怎么一步一步做
例如：
Task：
英语跟读
Step 1：
播放标准音频
Step 2：
等待用户说话
Step 3：
录音
Step 4：
ASR
Step 5：
比较
Step 6：
评分
Step 7：
反馈
Step 8：
进入下一句
Step 不直接操作硬件。
Step 调用：
Skill
例如：
play_audio
record_audio
listen
speak
wait
count
asr
evaluate
display
led
button
最终：
Task
↓
Step
↓
Skill
↓
Device Capability
负责：
执行
播放
录音
采集
缓存
通信
基础状态
负责：
调度
Task
App
用户
数据
ASR
AI
评估
分析
长期趋势
未来新增 App：
下载配置
下载资源
而不是：
修改 C++ 固件
重新 OTA
理想情况下：
新增 App
↓
App Manifest
Task Definition
Step Definition
Resource
Assessment Definition
↓
Server
↓
Device Sync
即可运行。
每一个 App 都有：
app.json
定义：
appId
name
version
developerId
description
icon
tasks
resources
permissions
assessment
Task 定义：
taskId
name
description
version
steps
parameters
interactionMode
assessment
resources
例如：
{
"taskId": "english_repeat_10",
"interactionMode": "PLAY_AUDIO",
"parameters": {
"repeatCount": 10
}
}
App 可以携带：
MP3
WAV
图片
JSON
文本
配置
模型参数
这些属于：
Application Resource
而不是固件。
用于：
Device Firmware
例如：
底层驱动
通信协议
音频驱动
系统 Runtime
用于：
App
Task
Config
Resource
Audio
例如：
新增英语 App
只需要：
Sync App
无需 OTA。
16GB SD Card 主要用于：
App Resources
Audio Resources
Cache
Offline Tasks
Pending Upload Audio
Temporary Files
例如：
/sdcard/
apps/
resources/
audio/
cache/
recordings/
pending/
Server 必须建立统一：
Task Runtime
负责：
创建 TaskInstance
启动 Task
推进 Step
等待 Device
处理 Event
判断 Step 完成
进入下一 Step
结束 Task
不要直接修改 Task Definition。
每一次实际执行：
Task
↓
TaskInstance
例如：
Task：
英语跟读 10 次
TaskInstance：
2026-08-30 19:30
保存：
startTime
endTime
status
currentStep
result
家长通过小程序配置：
每天 19:30
英语学习
Server：
Schedule
↓
Scheduler
↓
TaskInstance
↓
Device
因此：
家长配置的是“什么时候做什么 Task”，不是直接控制硬件。
进一步允许：
Plan
例如：
每日学习计划
包含：
19:30 英语跟读
19:45 口算
19:55 记忆游戏
最终：
Plan
↓
Schedule
↓
TaskInstance
Device 只需要理解标准协议：
APP_SYNC
TASK_START
STEP_START
SKILL_EXECUTE
TASK_PAUSE
TASK_RESUME
TASK_STOP
以及向 Server 上报：
TASK_STARTED
STEP_STARTED
STEP_COMPLETED
AUDIO_PLAYED
SPEECH_STARTED
SPEECH_STOPPED
TASK_COMPLETED
Device Runtime 内部增加：
Interaction Runtime
根据：
interactionMode
选择交互方式。
例如：
PLAY_AUDIO
→ Audio Player
FOLLOW_READ
→ Audio Player
→ Recorder
→ VAD
CHAT
→ ASR
→ LLM
→ TTS
TRANSLATION
→ ASR
→ Translation
→ TTS
现有 Xiaozhi 很可能：
Audio
↓
ASR
↓
LLM
↓
TTS
这种架构。
必须升级成：
Task Runtime
↓
Interaction Runtime
↓
┌────────┬────────┬────────┬────────┐
Chat Audio Repeat Game ...
Chat 只是其中一种能力。
Server 保存：
Original Audio
而不是只保存：
ASR Text
结构：
AudioSession
└── AudioSegment
├── Original Audio
├── ASR
├── Voice Feature
└── Assessment
统一 ASR Service：
Audio
↓
ASR
↓
Transcript
保存：
text
confidence
word timing
word confidence
统一提取：
speechDuration
pauseCount
pauseDuration
speechRate
responseLatency
volume
pitch
energy
prosody
不同 Task 使用不同评估策略。
例如：
英语跟读
→ pronunciation
→ fluency
→ accuracy
数字倒背
→ sequenceAccuracy
→ memoryAccuracy
→ responseTime
口算
→ accuracy
→ responseTime
→ difficulty
成语接龙
→ correctness
→ responseTime
→ continuity
所有结果最终统一为：
Metric
例如：
accuracy
response_time
pause_count
speech_rate
pronunciation
fluency
completion
participation
engagement
新 App 可以注册新的 Metric。
Server 建立：
User Baseline
通过：
7 Days
30 Days
90 Days
形成动态基线。
然后比较：
Today
vs
Baseline
系统可以提供：
Emotion Signal
但必须定义为：
基于语音、语言和行为数据的情绪表现信号。
不能直接定义为：
心理疾病诊断
输出：
state
confidence
trend
建立：
Engagement Score
综合：
响应
完成
主动性
持续性
互动
形成：
0 ~ 100
家长最终看到：
今日任务
完成情况
Task Score
能力指标
参与度
趋势
而不是复杂技术指标。
系统持续形成：
User Profile
包括：
Learning
Memory
Speech
Task Performance
Participation
Behavior Trend
Preference
所有 Profile 都应该来自：
Event
↓
Metric
↓
Aggregation
而不是手工维护。
最终开放：
Developer
↓
App
↓
Task
↓
Step
↓
Skill
↓
Assessment
开发者不应该直接修改 Device Firmware。
提供：
App SDK
Task SDK
Assessment SDK
Resource SDK
API
Simulator
开发者可以在 PC 上模拟：
Xiaozhi Device
测试 Task。
最终平台形成：
App Store
用户可以：
浏览 App
查看介绍
试用
订阅
安装
评价
例如：
英语学习
数学训练
记忆训练
成语游戏
AI 主持人
回忆录
故事
订阅关系：
User
↓
Subscription
↓
App
而不是：
User
↓
Firmware
平台负责：
订单
支付
订阅
退款
结算
分成
开发者获得：
Revenue Share
必须建立：
User
Child
Parent
Developer
App
之间的权限体系。
尤其是儿童数据。
开发者：
默认不能读取其他 App 数据
家长：
可以查看孩子数据
平台：
负责权限控制
儿童语音必须重点保护。
建立：
Consent
Encryption
Access Control
Audit Log
Retention Policy
Data Deletion
最终统一成：
App
↓
Task
↓
TaskInstance
↓
StepInstance
↓
Device Event
↓
Audio
↓
ASR
↓
Voice Feature
↓
Assessment
↓
Metric
↓
Aggregation
↓
Profile
↓
Report
这是整个系统最重要的数据链路。
核心状态尽量由 Event 驱动。
例如：
TaskStarted
StepStarted
AudioPlayed
SpeechStarted
SpeechStopped
ASRCompleted
AssessmentCompleted
StepCompleted
TaskCompleted
Event 成为系统的重要事实来源。
实时链路：
Device
↓
Server
↓
Task Runtime
↓
实时反馈
异步链路：
Audio
↓
Queue
↓
ASR
↓
Voice Analysis
↓
Assessment
↓
Aggregation
↓
Report
复杂 AI 分析不能阻塞 Task Runtime。
Device 网络断开时：
Task
↓
Local Cache
↓
执行
↓
Recording
↓
SD Card
↓
网络恢复
↓
Sync
因此：
Server 是中心控制器，但 Device 必须具备一定程度的 Offline Runtime。
所有这些对象必须版本化：
Firmware
App
Task
Step
Assessment
Model
Resource
例如：
App v1.2
Task v3
Assessment v2
Model v5
历史数据必须能够追溯到具体版本。
例如：
Pronunciation Model v1
Score = 82
以后：
Pronunciation Model v2
Score = 87
两个结果都保留。
核心：
User
└── Child
Child
├── Subscription
├── Plan
├── Schedule
└── TaskInstance
App
└── Task
└── TaskStep
TaskInstance
└── TaskStepInstance
├── DeviceEvent
├── AudioSegment
│ ├── ASR
│ └── VoiceFeature
└── Assessment
└── Metric
不要一开始开发完整平台。
首先建立最小闭环：
家长
↓
配置 Task
↓
Server Scheduler
↓
TaskInstance
↓
Xiaozhi
↓
执行
↓
录音
↓
Server
↓
ASR
↓
Assessment
↓
家长查看结果
必须完整跑通。
第一阶段只实现三个 Task：
播放
↓
等待
↓
播放
↓
...
播放标准音频
↓
录音
↓
ASR
↓
准确率
播放问题
↓
等待回答
↓
ASR
↓
答案解析
↓
正确率
增加：
数字倒背
成语接龙
简单记忆游戏
并统一：
Task Engine
Step Engine
Assessment Engine
加入：
Voice Feature
实现：
Pause
Speech Rate
Response Latency
Volume
Pitch
加入：
Baseline
Behavior
Engagement
Participation
实现：
Today
7 Days
30 Days
趋势。
建立：
Emotion Signal
进行实验性分析。
要求：
模型版本化
置信度
趋势
人工验证
不允许直接做医疗诊断。
开放：
App Manifest
Task DSL
Assessment SDK
Developer API
实现第三方 App。
建立：
App Store
Subscription
Payment
Revenue Share
Developer Console
建立：
Parent AI Assistant
家长可以询问：
孩子最近学习怎么样？
哪个 App 最喜欢？
英语最近有没有进步？
最近参与度有没有下降？
过去一个月有什么明显变化？
AI 从：
Metrics
Assessment
Trend
Profile
中生成解释。
AI Coding 不允许一次性重写整个项目。
必须：
Phase 0
代码审计
Phase 1
建立核心 Domain Model
Phase 2
Task Runtime
Phase 3
Device Runtime
Phase 4
App / Resource Sync
Phase 5
Audio / ASR
Phase 6
Assessment
Phase 7
Parent / Schedule
Phase 8
Behavior / Metrics
Phase 9
Developer Platform
Phase 10
Subscription / Marketplace
每个 Phase：
分析
↓
设计
↓
实现
↓
测试
↓
回归
↓
提交
AI 编程 Agent 必须：
优先理解现有代码，再修改代码。
禁止：
没有阅读代码
↓
直接重构
必须：
Repository Audit
↓
Architecture Mapping
↓
Dependency Analysis
↓
Minimal Change
现有 Xiaozhi 的：
Audio
ASR
TTS
LLM
MQTT / WebSocket
Device Communication
能够复用的必须复用。
新架构应该：
包裹现有能力
而不是：
全部推倒重来
旧系统：
Conversation
保留。
增加：
Task Runtime
最终：
Task Runtime
├── Chat Task
├── Repeat Task
├── Follow Read Task
├── Translation Task
└── Game Task
因此：
Chat 最终只是 Task Runtime 的一种 Task，而不是整个系统的核心。
所有 API 必须围绕：
App
Task
TaskInstance
StepInstance
Event
Audio
Assessment
Metric
设计。
避免大量：
/english/xxx
/math/xxx
/game/xxx
这种 App-specific API。
未来开发者应该能够通过：
JSON / YAML / SDK
定义 Task。
例如：
Task
├── parameters
├── steps
│ ├── action
│ ├── condition
│ ├── wait
│ ├── loop
│ └── branch
└── assessment
这样：
新增 Task 尽量不需要修改核心 Runtime。
必须建立稳定的：
Task Runtime API
Skill API
Device API
Assessment API
未来 App 越多：
Runtime 不变
App 增加
Task 增加
这是开放平台成立的关键。
Xiaozhi Platform
│
┌──────────────────┼──────────────────┐
│ │ │
Parent Developer Device
│ │ │
↓ ↓ ↓
Plan App Store Device Runtime
│ │ │
Schedule App Interaction
│ │ │
└──────────────→ Task ←───────────────┘
│
Step
│
Skill
│
Device Capability
│
↓
Audio / Event
│
↓
Server Pipeline
│
┌──────────────────┼─────────────────┐
↓ ↓ ↓
ASR Voice Analysis Assessment
│ │ │
└──────────────────┼─────────────────┘
↓
Metric
↓
Aggregation
↓
User Profile
↓
Parent Report
整个项目最终只需要牢牢抓住以下 8 个核心概念：
App
Task
Step
Skill
Interaction Mode
Event
Assessment
Metric
它们之间：
App
↓
Task
↓
Step
↓
Skill
↓
Device
执行过程中产生：
Event
↓
Audio
↓
Assessment
↓
Metric
因此最终 Xiaozhi 的逻辑不是：
用户
↓
说话
↓
AI 回复
而是：
家长
↓
订阅 App
↓
配置 Plan
↓
配置 Schedule
↓
Server
↓
Task
↓
Xiaozhi
↓
执行 Step
↓
采集 Audio / Event
↓
Server 分析
↓
Assessment
↓
Metric
↓
长期 Profile
↓
家长
第一阶段：
让 Xiaozhi 能执行 Task
第二阶段：
让 Xiaozhi 能记录 Task
第三阶段：
让 Xiaozhi 能评估 Task
第四阶段：
让 Xiaozhi 能理解长期变化
第五阶段：
让任何开发者都能创建 Task / App
第六阶段：
让 App 可以订阅和商业化
最终：
Xiaozhi Device 成为终端，Task Runtime 成为执行引擎，Server 成为 AI 数据与调度中枢，App Store 成为生态入口。
后续将本 Plan 提供给 Cursor / Codex 等 Coding Agent 时，应遵守：
你正在参与的是 Xiaozhi AI 从“AI 对话设备”
向“AI Application Terminal Platform”的架构升级。
不要把 Xiaozhi 设计成只有 Chat 的机器人。
系统必须支持：
App
Task
Step
Skill
Interaction Mode
Task Instance
Event
Audio
ASR
Assessment
Metric
Schedule
User Profile
Task 是系统核心业务执行单位。
Interaction Mode 是设备交互方式，
不是业务层级。
App 是 Task 的业务容器。
Step 是 Task 的执行步骤。
Skill 是底层原子能力。
Device 负责执行和采集。
Server 负责调度、理解、分析、评估和长期数据管理。
新增 App / Task / Audio Resource 尽量通过配置和资源同步实现，
不应该依赖 Firmware OTA。
必须保持旧 Chat 能力继续工作。
所有新架构必须尽可能兼容和复用现有代码。
禁止在未完成代码审计之前大规模重构。
每个 Phase 必须：
1. 分析现有代码
2. 明确修改范围
3. 给出架构方案
4. 实施最小必要修改
5. 编写测试
6. 执行测试
7. 验证旧功能没有回归
8. 输出修改总结
不要一次性实现整个系统。
必须按照 Phase 逐步演进。
优先建立稳定的 Domain Model 和 Runtime Boundary。
未来第三方开发者应该能够在不修改 Xiaozhi 核心 Runtime 的情况下创建新的 App 和 Task。
最终目标是：
“核心 Runtime 稳定，App / Task / Resource / Assessment 可无限扩展。”
以后所有 Coding Plan 都应该从本 Master Plan 派生。
结构：
Master Plan
│
├── Device Plan
│
├── Server Plan
│
├── Mini Program Plan
│
├── Developer Platform Plan
│
├── Assessment Plan
│
└── Marketplace Plan
然后再进一步：
Architecture Plan
↓
Module Plan
↓
Implementation Plan
↓
Coding Task
↓
Code
↓
Test
以后任何一个新需求，都先问：
这是 App？
是 Task？
是 Step？
是 Skill？
是 Interaction Mode？
是 Event？
是 Assessment？
还是 Metric？
如果一个新需求无法归入这些核心抽象：
不要立即写代码。
先重新审视架构。
这套原则将决定 Xiaozhi 最终能不能从一个产品，真正演化成一个开放平台。