1. 玩具 FSM 管产品处于什么大状态#

paipop_fsm 管理配网、引擎初始化、聊天和退出等待等产品级状态。本文主线涉及：

1
ENGINE_INIT
2
    ↓ 初始化成功
3
ENGINE_EXIT
4
    ↓ 用户点击并成功提交启动请求
5
ENGINE_CHAT
6
    ↓ 对话真正退出
7
ENGINE_EXIT

ENGINE_EXIT 这个名字容易误导。它不是“初始化失败”，而是引擎已经离开活动聊天、可以等待下一次启动的稳定状态。FSM 的合法转换表明确允许：

1
ENGINE_INIT --ENGINE_INIT_OK--> ENGINE_EXIT
2
ENGINE_EXIT --TOUCH_CLICK/ENGINE_RESTART--> ENGINE_CHAT
3
ENGINE_CHAT --ENGINE_EXIT--> ENGINE_EXIT

源码位置：src/app/paipop_fsm.c:100-140。

2. SDK 阶段管一轮交互进行到哪里#

PaipopSDK 的 Paipop_ChatPhaseCode 描述的是对话内部阶段：

1
typedef enum {
2
    PAIPOP_CHAT_PHASE_STANDBY = 0,
3
    PAIPOP_CHAT_PHASE_STARTING,
4
    PAIPOP_CHAT_PHASE_INPUTING,
5
    PAIPOP_CHAT_PHASE_THINKING,
6
    PAIPOP_CHAT_PHASE_OUTPUTING,
7
    PAIPOP_CHAT_PHASE_INTERRUPTING,
8
    PAIPOP_CHAT_PHASE_EXITING,
9
} Paipop_ChatPhaseCode;

正常连续对话主要经历：

1
STARTING → INPUTING → THINKING → OUTPUTING
2
                ↑                         │
3
                └──── 回答结束，下一轮 ───┘

源码位置：PaipopSDK/paipop_sdk.h:68-83。

所以一次 ENGINE_CHAT 可以包含多次 INPUTING → THINKING → OUTPUTING。前者是产品粗粒度状态，后者是会话细粒度阶段。把两者混成一个枚举，会让 UI、打断和异常退出逻辑互相缠绕。

知识卡：为什么状态名前有 ENGINE_，阶段名前有 CHAT_PHASE_？

这是两个抽象层的提示。ENGINE_CHAT 回答“玩具是否正处于一段活动会话”；CHAT_PHASE_INPUTING 回答“这段会话当前是否正在收取用户输入”。前者由玩具 FSM 持有，后者由 Paipop/LingXin 生命周期回调报告。

1. Paipop_VoiceChatInit() 建立长期能力#

FSM 进入 ENGINE_INIT 时调用 paipop_engine_chat_init()：

1
case PAIPOP_TOY_STATE_ENGINE_INIT:
2
    paipop_eye_closed();
3
    ret = paipop_engine_chat_init();
4
    if (ret >= 0) {
5
        paipop_fsm_transition(PAIPOP_TOY_STATE_ENGINE_EXIT,
6
                              PAIPOP_EVT_ENGINE_INIT_OK);
7
    } else {
8
        paipop_fsm_transition(PAIPOP_TOY_STATE_ENGINE_INIT_FAILED,
9
                              PAIPOP_EVT_ENGINE_INIT_FAIL);
10
    }
11
    break;

paipop_engine_chat_init() 先取得默认参数，再配置：

• 生命周期回调 lifeCycleListener；
• 每轮业务参数准备回调 chatRoundPrepare；
• business/custom JSON 获取函数；
• 欢迎提示音路径；
• WebSocket 心跳间隔 3 秒、超时 10 秒；
• Flash 缓存路径；
• 定时任务能力；
• 云端动作数量和白名单校验器。

最后调用：

1
ret = Paipop_VoiceChatInit(&props);

源码位置：src/app/paipop_fsm.c:1406-1421、src/services/paipop_engine_service.c:500-535。

它通常在联网后初始化一次；如果初始化失败，点击可以触发重新初始化。因此更准确的说法是“正常启动只初始化一次，失败时允许重试”，而不是“整个设备生命周期绝对只能调用一次”。

2. Paipop_StartNewChat() 提交本次会话#

当玩具处于 ENGINE_EXIT 且允许重启时，点击路径进入 paipop_fsm_restart_chat()。它先检查：

• 是否真的存在 restart_after_exit 意图；
• 本地提示音是否仍在播放；
• OTA 是否正在占用系统；
• 本次是新 conversation，还是同一 conversation 的继续轮次。

普通点击最终调用：

1
ret = paipop_engine_start_new_chat(0);

它进一步构造参数并调用：

1
ret = Paipop_StartNewChat(&props);

只有返回值非负，FSM 才把玩具状态从 ENGINE_EXIT 切换到 ENGINE_CHAT。源码位置：src/app/paipop_fsm.c:1285-1375、src/services/paipop_engine_service.c:258-295,538-546。

两者可以用下表记忆：

公开返回码还区分 NOT_READY 和 BUSY。因此 Paipop_StartNewChat() 返回 0 不能被解释为“WebSocket 已连接”或“麦克风已经上传”；真正进入录音阶段必须等待异步 INPUTING。

1. chatMode 决定用户输入怎样结束#

1
PAIPOP_CHAT_MODE_CLOUD_VAD
2
    云端检测用户是否说完，不需要应用主动停止录音
3

4
PAIPOP_CHAT_MODE_MANUAL_STOP
5
    应用必须在松键或超时时调用 Paipop_StopChatRecord()

2. singleRound 决定回答之后做什么#

1
singleRound = true
2
    回答播放完成后退出，不自动开始下一轮录音
3

4
singleRound = false
5
    保持连续对话，回答结束后自动进入下一轮录音

公开契约位置：PaipopSDK/paipop_sdk.h:156-187,203-228。

组合起来看：

当前普通点击属于第一行。Cloud VAD 只说明“本轮怎样判断说完”，连续对话由 singleRound = false 决定。

1. 一帧为什么是 960 字节#

当前录音端口固定要求：

1
#define PAIPOP_VOICE_UPLOAD_SAMPLE_RATE 24000
2
#define PAIPOP_VOICE_UPLOAD_CHANNELS        1
3
#define PAIPOP_VOICE_UPLOAD_FRAME_BYTES   960

若样本为 16 bit，即每个采样点 2 字节，那么 20 ms 数据量为：

1
24000 sample/s × 1 channel × 2 byte/sample × 0.02 s
2
= 960 byte

源码位置：PaipopSDK/port/jl_ac79/src/paipop_audio_recorder.c:8-10，配置位置：include/app_config.h:171-179。

20 ms 是延迟和调用开销之间的折中：帧更小会增加回调、入队和网络发送次数；帧更大则会提高端到端输入延迟。

2. 优先复用统一采集服务，避免重复打开 ADC#

paipop_audio_recorder_open() 先检查玩具层是否提供 paipop_voice_activity_sink_open()。若共享采集服务可用，就校验采样率、声道数和帧长，并把 SDK 的数据回调注册成一个 PCM sink：

1
shared_ret = paipop_voice_activity_sink_open(
2
    recorder_shared_sink_write,
3
    recorder_handler,
4
    recorder_handler->frame_size,
5
    &recorder_handler->shared_sink_generation);

共享服务已经拥有 ADC。若格式不匹配，代码会直接报错，而不是悄悄打开第二个 ADC；注释明确说明这是为了避免 -14 dual-ADC race。

只有共享服务没有链接或不可用时，才回退到：

1
recorder_handler->enc_server =
2
    server_open("audio_server", "enc");

然后以 PCM、mic、指定采样率和帧长发送 AUDIO_ENC_OPEN。源码位置：PaipopSDK/port/jl_ac79/src/paipop_audio_recorder.c:150-194,209-310。

3. PCM 使用回调直达上传链，不走 sys_event#

共享 sink 收到一帧后先检查：

• recorder 仍在运行；
• 当前确实使用共享 sink；
• generation 与注册时一致；
• 回调和数据有效。

然后调用：

1
recorder->data_callback(data,
2
                        len,
3
                        recorder->data_user_data);

源码位置：PaipopSDK/port/jl_ac79/src/paipop_audio_recorder.c:47-69。

PaipopSDK 音频桥把平台回调转换为 LingXinSDK 的输入：

1
static void recorder_data_callback(const void *data,
2
                                   int len,
3
                                   void *user_data)
4
{
5
    (void)user_data;
6
    lingxin_process_record_data((void *)data, len);
7
}

补充源码位置：apps/LINGXIN_JIELI/PAIPOP_JIELI_SDK/src/paipop_audio_port_bridge.c:26-30,58-81。

从 lingxin_process_record_data() 往下进入 LingXinSDK 的录音缓存、WebSocket 和云端协议，属于第三方边界。本文能确认本项目交给第三方引擎的是规定格式的连续 PCM；云端 ASR、模型推理和 TTS 的内部实现不属于本项目源码，也不应在面试中说成自己实现。

1. STARTING：请求正在启动，还不能表示麦克风可用#

STARTING 可能包含旧轮清理、任务建立和网络状态准备。FSM 清理旧播放标志，普通启动时让眼睛保持 IDLE，而不是立即显示麦克风。源码位置：src/app/paipop_fsm.c:1900-1946。

2. INPUTING：录音 sink 已经可以接收 PCM#

这是应用确认输入链准备完成的阶段。FSM 会：

• 取消上一轮退出等待计时器；
• 清理 round_output_seen、playback_active 等旧状态；
• 普通 Cloud VAD 模式启动无输入窗口；
• 将眼睛切换为 LISTENING；
• 打印 pcm input ready 时间点。

源码位置：src/app/paipop_fsm.c:1846-1899。

所以 Paipop_StartNewChat() 返回成功与 INPUTING 到达之间可能有明显延迟。前者是请求被接受，后者才是输入链真正就绪。

3. THINKING：输入结束，云端正在处理#

FSM 清除播放活动标志，眼睛回到 IDLE，并把本地语音活动服务切到思考阶段策略。源码位置：src/app/paipop_fsm.c:1947-1962。

这里的“思考”是产品视角概括，可能包含云端 VAD 收尾、最终 ASR、模型生成和 TTS 准备；当前应用没有能力从一个阶段码精确拆出每项服务器耗时。

4. OUTPUTING：协议已经输出，不等于扬声器已经出声#

收到 OUTPUTING 时，FSM 设置：

1
fsm.round_output_seen = 1;
2
fsm.output_phase_pending = 1;

但只有 fsm.playback_active 已经为 1，眼睛才显示 SPEAKING。否则仍保持 IDLE。源码甚至明确说明：

1
/* OUTPUTING precedes real DAC playback. */

源码位置：src/app/paipop_fsm.c:1972-2002。

这避免了一个常见 UI 错误：云端刚报告输出阶段，设备还在等待 TTS 首包和解码缓冲，屏幕却提前显示正在说话。

知识卡：三个“回答开始”不是同一时刻

AI_TEXT 到达表示已经取得回答文字；OUTPUTING 表示协议进入输出阶段；PLAYBACK_STARTED 表示本地播放器已成功执行解码启动。排查回答延迟时必须分别记录这三个时间点，不能只看一个图标。

回调字符串为什么不能直接保存指针#

公开接口规定 payload 只在本次回调期间有效。直接保存：

1
saved_text = payload;   /* 错误：回调结束后可能悬空 */

如果要交给 UI 任务、写文件或延迟处理，必须在回调内复制内容，再明确由接收者释放。也不应在网络回调里执行阻塞文件 IO，否则可能拖慢 WebSocket 收包和后续音频数据。

1. PaipopSDK 先把第三方接口桥接到平台端口#

PaipopSDK 提供的音频桥把 LingXinSDK 期望的播放接口映射为：

1
module_bufferPlay_audioInit()
2
    → paipop_cloud_audio_play_init()
3

4
module_bufferPlay_data(buf, len)
5
    → paipop_cloud_audio_play_feed(buf, len)
6

7
module_bufferPlay_audioEnd()
8
    → paipop_cloud_audio_play_end()
9

10
module_bufferPlay_terminate()
11
    → paipop_cloud_audio_play_stop()

并通过 module_bufferPlay_formatCheck() 声明当前流格式必须是 MP3。补充源码位置：apps/LINGXIN_JIELI/PAIPOP_JIELI_SDK/src/paipop_audio_port_bridge.c:122-180。

2. init 建立一条新的流代际#

paipop_cloud_audio_play_init() 不会立刻启动解码。它先等待上一条流的硬停止或终态清理完成，然后：

• 保存播放事件回调；
• 生成新的 stream_generation；
• 允许接收 feed；
• 清除 input-ended、首包和暂停状态；
• 通知上层播放器初始化完成。

源码位置：PaipopSDK/port/jl_ac79/src/paipop_cloud_audio_play.c:1112-1190。

generation 用来隔离连续轮次：旧 WebSocket 包、旧解码器结束事件或迟到的 stop 只能影响创建它们的那一代流，不能污染新回答。

3. 首包采用 4 KiB/8 KiB 自适应缓冲#

paipop_cloud_audio_play_feed() 收到的是压缩 MP3 数据，不是解码后的 PCM。第一批数据先累积到 firstData：

1
#define FAST_FIRST_DATA_LEN          (4 * 1024)
2
#define WEAK_LINK_FIRST_DATA_LEN     (8 * 1024)
3
#define WEAK_LINK_FIRST_ACCUMULATE_MS      650
4
#define WEAK_LINK_FEED_GAP_MS              220

健康链路累计 4 KiB 就启动；如果首包累计超过 650 ms，或相邻 feed 间隔超过 220 ms，则认为链路偏弱，改用 8 KiB 缓冲。源码位置：PaipopSDK/port/jl_ac79/src/paipop_cloud_audio_play.c:87-95,900-929,932-1046。

这是首字延迟与稳定性的权衡：

1
缓冲小 → 更早出声，但网络抖动时容易让解码器断粮
2
缓冲大 → 播放更稳，但用户要多等一段时间

当前实现不是永远固定 4 KiB 或 8 KiB，而是根据首批数据节奏选择。

4. 达到阈值后启动 MP3 解码#

audio_buffer_start_generation() 把首批数据写入循环缓冲区，然后调用：

1
audio_init(generation)
2
  → server_open("audio_server", "dec")
3
  → 注册 dec_server_event_handler 到 app_core
4
  → 创建循环缓冲区与信号量
5

6
audio_buffer_data_out(generation)
7
  → AUDIO_DEC_OPEN，dec_type = "mp3"
8
  → 获取数字音量句柄
9
  → AUDIO_DEC_START

解码输出源为 dac。开启播放 AEC 配置时，代码提供原始采样率并要求 48 kHz 输出；否则使用播放器采样率。源码位置：PaipopSDK/port/jl_ac79/src/paipop_cloud_audio_play.c:547-619,638-710,720-850。

后续 MP3 包通过：

1
cbuf_write(&__this->save_cbuf, buf, rlen);

进入循环缓冲区；杰理解码器通过自定义 audio_vfs_fread() 消费。数据暂时不足且流尚未结束时，读端等待；生产者写入新包后唤醒读端。源码位置：PaipopSDK/port/jl_ac79/src/paipop_cloud_audio_play.c:381-421,953-994。

5. PLAYBACK_STARTED 才驱动说话表情#

AUDIO_DEC_START 成功后，适配层设置 playback_started_notified，再调用 cloud_audio_notify_playback_started()。它先同步通知 FSM：

1
fsm.playback_active = 1;
2
fsm.output_phase_pending = 1;
3
fsm.round_output_seen = 1;

随后发布 PAIPOP_EVT_ENGINE_PLAYBACK_STARTED。FSM 只有确认当前仍在 ENGINE_CHAT、没有退出或打断请求时，才把眼睛切换为 SPEAKING。源码位置：PaipopSDK/port/jl_ac79/src/paipop_cloud_audio_play.c:698-710,836-850、src/services/paipop_engine_service.c:626-644、src/app/paipop_fsm.c:391-431,2003-2039。

严格来说，这个事件表示本地播放器成功接受并启动了解码输出链；物理 DAC 的第一颗采样点仍可能受平台内部缓冲影响。但它比云端 OUTPUTING 更接近用户真正听见声音的时刻，因此适合作为产品 UI 的播放开始依据。

6. audioEnd 不等于立刻停止#

paipop_cloud_audio_play_end() 的语义是“云端已经没有更多数据”，不是丢弃缓冲并立刻静音。它标记输入结束、唤醒解码器，让循环缓冲区里的剩余 MP3 继续播放。真正收到 AUDIO_SERVER_EVENT_END 后，适配层才：

• 确认 generation；
• 停止并释放解码器、缓冲区和信号量；
• 通知 playback stopped；
• 回调 PLAY_END 给上层引擎。

源码位置：PaipopSDK/port/jl_ac79/src/paipop_cloud_audio_play.c:270-359,1051-1103,1232-1253。

这与 paipop_cloud_audio_play_stop() 不同：stop 用于中断旧回答，需要主动阻止后续 feed 并尽快拆除播放资源。

1. 控制事件和音频数据使用不同通道#

阶段、退出、点击等低频控制消息走系统事件；PCM 和 MP3 走回调、流接口和缓冲区。这样不会让每 20 ms 一帧的 PCM 挤占 app_core 控制事件队列。

2. FSM mutex 保护复合业务状态#

start_after_init、restart_after_exit、playback_active 等字段会跨系统回调、定时器和播放器通知访问。代码在短临界区内读取或更新，再解锁执行提示音、事件投递和 SDK 调用，避免持锁跨越耗时外部操作。

3. stream generation 隔离旧回答#

播放器的 feed、decoder 和 terminal event 都携带或检查 generation。新一轮开始后，旧轮迟到数据不能再写入新轮循环缓冲区；旧 AUDIO_SERVER_EVENT_END 也不能错误地关闭新解码器。

4. 同步状态更新先于异步 UI 事件#

播放开始时先同步设置 playback_active 和本地语音活动模式，再投递 PLAYBACK_STARTED。这样 AEC/语音活动钩子与 UI 不会看到互相矛盾的阶段。

5. shutdown 先关闭回调入口#

paipop_engine_shutdown() 先把 paipop_engine_callbacks_enabled 清零，再请求退出对话、停止播放器和清理 ID。即使第三方 SDK 之后还有迟到回调，也不会继续向已拆除的玩具服务发布事件。源码位置：src/services/paipop_engine_service.c:647-672。

Q1：为什么点击函数不直接调用 Paipop_StartNewChat()？#

因为点击的语义依赖当前业务状态。事件层只翻译输入，FSM 才能统一处理初始化锁存、失败重试、空闲启动和活动会话切换，防止硬件层和云端生命周期耦合。

Q2：Paipop_StartNewChat() 返回 0，为什么还要等 INPUTING？#

返回 0 只表示异步启动请求被接受。WebSocket、对话任务和录音端口仍可能在准备；INPUTING 才是 SDK 报告输入链已进入采集/上传阶段的生命周期证据。

Q3：Cloud VAD 和连续对话是同一个功能吗？#

不是。chatMode = CLOUD_VAD 决定本轮由云端判断说完；singleRound = false 决定回答后继续下一轮。两者是正交参数。

Q4：为什么 PCM 不走 sys_event？#

24 kHz 单声道 16 bit PCM 每秒约 48 KB，每 20 ms 就有一帧。逐帧包装成系统控制事件会增加复制、排队和调度开销；连续媒体数据更适合回调和专用缓冲区。

Q5：为什么一帧是 960 字节？#

24000 × 1 × 2 × 0.02 = 960。分别对应每秒采样点、声道、每采样点字节数和 20 ms 帧长。

Q6：OUTPUTING 为什么不能直接显示说话图标？#

它只表示协议进入输出阶段。设备可能仍在等待 TTS 首包、累计 4/8 KiB 首播数据或启动 MP3 解码器；播放器成功执行 AUDIO_DEC_START 后的 PLAYBACK_STARTED 才是更可靠的本地依据。

Q7：为什么首播既有 4 KiB 又有 8 KiB？#

4 KiB 降低健康网络下的首字延迟；检测到首包积累过慢或包间隔较大时，8 KiB 给弱网更多抗抖余量。它是在低延迟和不卡顿之间做动态权衡。

Q8：audioEnd 与 stop 有什么区别？#

audioEnd 表示生产者不再发送新 MP3，已有缓冲仍需自然播完；stop 表示主动终止当前回答，要拒绝后续数据并拆除播放链。

Q9：回调中的 ASR/AI 字符串能保存地址以后使用吗？#

不能。公开契约规定 payload 只在本次回调期间有效。跨线程、写文件或延迟显示前必须复制内容，并明确由哪个模块释放。

Q10：这个项目中哪些部分属于第一方工作？#

玩具事件层、业务 FSM、paipop_engine_service、PaipopSDK 封装和杰理音频端口属于 Paipop 第一方实现；LingXinSDK 提供第三方 AI 对话引擎。项目工作的重点是接口抽象、生命周期治理、对话参数管理、音频适配、线程切换和可靠性处理，而不是把第三方云端 ASR/LLM/TTS 说成自己重新实现。