E001 部署设计

Mac 第一版改 AgentEar，不新起 Pipecat。模型档仍见 建议。AgentEar 的现状见 AgentEar 基线。本文不新增未标注的延迟。

1. 组件

学生在这台 Mac 上说话。AgentEar 已经占着麦克风、识别和 VoxCPM2。agent24d 只在同一台机器上通过 A3 回答。浏览器和 TURN 留到 P2。

flowchart LR
  mic[cpal 麦克风] --> rec[按键录音]
  rec --> asr[SenseVoice 整段转写]
  asr --> route{附着?}
  route -->|否| side[本机 LLM 边车流式]
  route -->|是| a3["_a24/model/complete"]
  side --> sent[按句切开]
  a3 --> sent
  sent --> tts["POST /speak VoxCPM2"]
  tts --> play[本机播放]
  vad[播放时的监听] -->|开口| stop["stop_playback 加 on_barge_in"]
  stop --> play
  stop --> a3

vad 那条今天不存在。按键路径已经会调用 stop 里的两个函数。第一刀是让开口走同一条函数，而不是再写一套播放器。

2. 时序

正常回合，按今天的代码。松键之后才转写。附着时要等整句 model_complete 才开始合成。

sequenceDiagram
  participant U as 用户按键
  participant E as AgentEar
  participant A as agent24d
  participant T as VoxCPM2
  U->>E: 开始录音
  U->>E: 停止
  E->>E: SenseVoice 整段转写
  E->>A: _a24/model/complete
  A-->>E: 整段文本
  E->>T: POST /speak 逐句
  T-->>E: 整段 wav
  E->>U: 播放

要补的打断。播放期间开口，不等下一次按键。

sequenceDiagram
  participant U as 用户开口
  participant E as AgentEar
  participant A as agent24d
  participant T as VoxCPM2
  Note over E,T: Speaking
  U->>E: 监听判定为开口
  E->>E: stop_playback
  E->>E: on_barge_in
  E->>A: $/cancelRequest
  E->>T: 不再发下一句
  E->>U: 开始下一轮录音

$/cancelRequest 今天只在 Conn::call 超时里发送。开口路径要补一次主动发送。本机边车流式已经有 abort 标志，按键会增加 interrupt 计数。语音监听应调用同一套，不要另写取消。

3. 各档要装什么

Mac 各档共用 AgentEar。Windows 和服务器不跑这份二进制，模型服务仍按分析稿的 S2 到 S5，那是以后的移植。

模型文件放在主机的固定目录，文件名带 Hugging Face revision。上课期间不自动下载。更新在维护窗口做，先拉到新目录，校验后再切换软链。

日志记会话 id、轮次 id、VAD、ASR 完成、首个音频块、取消是否赶上播放。默认不落原始学生音频。排错用的环形缓冲在会话结束时删除。指标里不要出现提示词和转写全文，转写进 agent24 的 run 时由 daemon 自己的库保存，并遵守现有保留策略。

4. 教室安全

• 模型地址只允许 loopback 或主机自己的内网网卡。配置里出现公网推理地址就拒绝启动。对应 agent24 的 LocalOnly，不把语音任务路由到远程槽。
• 网关对学生使用单独的教室令牌，不是 daemon 的 host token。令牌只证明「这台浏览器可以说话」，不能读密钥、不能导出记忆。
• 浏览器到网关用校园网 TLS。证书由学校自己签或用内网 CA。
• 扬声器会把回答送回麦克风。Moshi CLI 写明不做回声消除。第一版要求耳机。若必须用扬声器，先加回声消除再打开打断，否则会自己打断自己。
• 不把 MOSS-Live 的公网 API 配进学校主机。

5. 改哪里

不新开 school-voice-gateway。改 AgentEar 自己的源码。agent24 内核先不动。

src/main.rs          按键打断已经在这里。播放时的监听接到同一分支
src/session.rs       Speaking 期间允许进入 Listening
src/talk.rs          开口时置上已有的 abort，停掉下一句合成
src/a3.rs            开口时对当前 model_complete 发 $/cancelRequest
src/host.rs          HostLlm 仍是整句。流式要等 agent24 的推理回调，或闲聊改回本机边车
services/tts/        VoxCPM2 已是默认。第一刀不换模型

Windows 和浏览器若以后要做，再单独开仓库。那时候才用 Pipecat。要对照的上游：

6. 集成草稿

下面是要接到现有函数上的形状，不是新进程。

fn on_voice_open() {
    let stopped = talk::stop_playback();
    host::on_barge_in();
    talk::note_recording_started();
    a3::cancel_inflight_model_complete();
    if stopped {
        log::info!("语音打断，停播并取消本轮推理");
    }
}

cancel_inflight_model_complete 今天没有这个名字。Conn::call 只有超时才写 $/cancelRequest。第一刀可以先只停播放。第二刀再让开口走同一条取消帧，避免整句回答在用户已经开口之后才开始播。

附着时若要首字更快，闲聊不要进 HostLlm::reply。answer_and_speak_streamed 看到 streams() 为 false 会退回整句。本机边车的 streams() 为 true，句子级路径已经能重叠合成。工具回合再 model_complete。

7. 分阶段

人日是判断。旧列是「从零写网关」。新列是「改 AgentEar」。

P3 原生全双工仍另计，规模 L，不替换 AgentEar 的半双工。