# lm-livekit-helper

`lm-livekit-helper` 是 Combrabo Voice 的 LiveKit 媒体 worker。它从 `lmrobot-app` 接收每次通话的 `CV_*` 运行参数，加入 LiveKit 房间，发布 bot 音轨，播放主动问候音频，并在 S7 阶段承接用户语音 turn 的媒体输入输出。

它不是业务服务，不承担鉴权、数据库、订单、ASR/LLM/TTS 权威、消息落库或 diagnostics 聚合。业务权威仍在 `lmrobot-app`。

## 当前职责

1. 读取 `lmrobot-app` 注入的 `CV_*` 环境变量；
2. 使用 bot token 连接 LiveKit room；
3. 发布 bot 本地音轨；
4. 播放 WAV / MP3 主动问候音频；
5. 在 smoke 模式下通过 LiveKit reliable Data Message 下发 `device_output`；
6. S7 阶段通过 Java runtime turn bridge 复用后端 ASR / TextChat / TTS / Message 能力。

## 本机构建

```bash
cargo build --release
```

helper 目录内带 `.cargo/config.toml`，本机构建建议通过本仓库根目录执行，确保使用同一套 registry / retry 配置。

## 本机运行

推荐通过包装脚本启动：

```bash
./run-local.sh
```

如果本地还没有 release 二进制，脚本会先执行构建。macOS 默认优先使用 Docker 模式，避免 host 侧 WebRTC native 依赖链路反复阻塞。

可预先准备运行模式：

```bash
./run-local.sh --prepare
./run-local.sh --prepare --rebuild
```

## 本机固定问候音频

helper 支持 WAV / MP3 音频自动识别。主动问候 `prepare` 生成的 MP3 可以直接进入 helper；本地 smoke 仍可使用 WAV fixture 作为固定兜底样本。

在 macOS local 环境，可先生成一份本机固定问候 WAV fixture：

```bash
./generate-local-fixture.sh
```

默认输出：

```text
.local/greeting-local.wav
```

## lmrobot-app 接线示例

```bash
export COMBRABO_VOICE_RUNTIME_WORKDIR=/opt/lmrobot/lm-livekit-helper
export COMBRABO_VOICE_RUNTIME_LAUNCH_COMMAND=/opt/lmrobot/lm-livekit-helper/run-local.sh
export COMBRABO_VOICE_RUNTIME_HELPER_MODE=docker
export COMBRABO_VOICE_RUNTIME_HELPER_IMAGE=registry.example.com/lm-livekit-helper:git-sha
export COMBRABO_VOICE_RUNTIME_FALLBACK_GREETING_AUDIO_PATH=/opt/lmrobot/lm-livekit-helper/.local/greeting-local.wav
```

`CV_LIVEKIT_URL`、`CV_LIVEKIT_ROOM_ID`、`CV_LIVEKIT_BOT_TOKEN`、`CV_LIVEKIT_BOT_PARTICIPANT_IDENTITY` 等连接材料由 `lmrobot-app` 在每次 `calls/start` 时生成并注入，不写入仓库。

## LiveKit Data 设备输出 smoke

需要验证 NativeSDK 是否能收到设备输出 Data Message 时，在启动 `lmrobot-app` 前打开：

```bash
export CV_DEVICE_OUTPUT_SMOKE_ENABLED=true
```

helper 会在 bot 进房并发布音轨后，向 `CV_LIVEKIT_USER_PARTICIPANT_IDENTITY` 指向的 SDK client 发送 reliable Data Message：

- `topic`: `device_output`
- `type`: `device_output`
- `schemaVersion`: `1.0`
- `commandCode`: 例如 `vibration.start`
- `params`: 设备参数

如需指定接收方，可使用英文逗号分隔：

```bash
export CV_DEVICE_OUTPUT_DESTINATION_IDENTITIES=client-identity-a,client-identity-b
```

如果没有指定接收方且没有 `CV_LIVEKIT_USER_PARTICIPANT_IDENTITY`，helper 会广播到 room。设备控制建议继续使用 reliable/ordered Data Message；ACK / 执行结果首版建议走 HTTP，便于落库、重试和排查。

## 文档

- [Runtime Contract](docs/runtime-contract.md)
- [Jenkins Build And Deploy Runbook](docs/jenkins-build-deploy.md)

## 安全要求

仓库内只允许提交 `.env.example` 这类脱敏样例。禁止提交真实 LiveKit token、API key、secret、roomId、participantIdentity、用户语音内容、ASR 文本、LLM 回复全文或完整 prompt。