chore: migrate project into clean repository

LIVEKIT_CALL_LINK.md

@@ -0,0 +1,710 @@
+# LiveKit 通话链路说明
+
+本文档记录 `arcs_mini` 硬件端新增的通话链路：设备通过语音意图触发呼叫，连接 Node LiveKit 桥接服务，完成设备与设备、设备与 App/Web 之间的实时语音通话。
+
+## 背景
+
+原有主链路主要负责唤醒、语音对话、MCP 工具调用、TTS 播放等能力。新增通话能力后，硬件端多了一条独立的通话链路：
+
+1. 设备联网后主动连接 LiveKit Node 桥接服务的 WebSocket。
+2. 用户通过主链路语音对话说“给某人/某设备打电话”。
+3. 主链路意图识别命中通话工具，调用硬件端 MCP 工具 `ls.built_in.call_device`。
+4. MCP 工具把目标设备号 `toId` 交给硬件端 LiveKit 桥接模块。
+5. 桥接模块通过 WebSocket 给 Node 发送 `device_call`。
+6. Node 创建 invite、加入 LiveKit 房间，并把双方音频转成硬件可消费的 PCM 帧。
+7. 硬件端收下行 PCM 播放，同时采集本机麦克风 PCM 上行给 Node。
+
+这条链路和主对话链路是并行关系：主对话链路负责“识别用户想打电话”和“调用工具”，通话链路负责“真正建立通话和传输音频”。
+
+## 核心链路
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Device as 硬件端 arcs_mini
+    participant MainCloud as 主链路云服务
+    participant MCP as MCP 工具 call_device
+    participant Bridge as 硬件 LiveKit Bridge
+    participant Node as Node LiveKit 桥接服务
+    participant Peer as 被叫端/对端
+
+    Device->>Node: WiFi IP ready 后连接 /ws/device?deviceId=<did>
+    User->>Device: 单击唤醒后说“给小红打电话”
+    Device->>MainCloud: 主链路语音对话/意图识别
+    MainCloud->>Device: MCP tool call: ls.built_in.call_device(toId)
+    Device->>MCP: 执行 MCP 工具
+    MCP->>Bridge: voice_livekit_bridge_request_call(toId)
+    Bridge->>Node: {"type":"device_call","toId":"..."}
+    Node->>Peer: incoming_call / invite
+    Peer->>Node: accept
+    Node->>Device: {"type":"call_start","sampleRate":16000,"channels":1}
+    Node-->>Device: 二进制 PCM 下行帧
+    Device-->>Node: 二进制 PCM 上行帧
+    Device->>Node: 来电中三击 {"type":"device_reject","inviteId":"..."}
+    Device->>Node: {"type":"device_hangup"} 或收到 call_end
+```
+
+## 新增/修改代码清单
+
+### 1. LiveKit WebSocket 与音频桥接
+
+文件：`src/category/comm/msgs/voice_livekit_poll_msg.c`
+
+这是硬件端通话链路的核心文件，职责包括：
+
+- 设备联网后连接 Node 桥接服务。
+- 维护通话状态机。
+- 处理 Node 下发的 JSON 控制消息。
+- 处理 Node 下发的二进制 PCM 音频帧。
+- 从本机麦克风采集 PCM，上行发送给 Node。
+- 处理来电响铃、双击接听、三击拒接、双击挂断。
+- 通话结束后恢复唤醒和主云链路。
+
+当前关键配置在文件顶部：
+
+```c
+#define LK_BRIDGE_WS_SCHEME    "ws"
+#define LK_BRIDGE_WS_HOST      "39.108.110.91"
+#define LK_BRIDGE_WS_PORT      "3000"
+#define LK_BRIDGE_WS_PATH_PREFIX "/ws/device?deviceId="
+#define LK_BRIDGE_FALLBACK_DEVICE_ID "B"
+#define LK_BRIDGE_DEFAULT_CALL_TARGET "f17c0a1a322ed2ad"
+```
+
+这些配置决定硬件端连接哪个 Node LiveKit 桥接服务。当前仍是编译期宏，部署到线上时需要改成目标服务器地址，或后续再改造成配置文件/云端下发。
+
+#### 通话状态机
+
+```c
+typedef enum {
+    LK_CALL_IDLE = 0,
+    LK_CALL_RINGING,
+    LK_CALL_PREPARING,
+    LK_CALL_ACTIVE,
+} lk_call_state_e;
+```
+
+含义：
+
+- `LK_CALL_IDLE`：空闲状态，可以发起呼叫或接收来电。
+- `LK_CALL_RINGING`：收到来电，设备播放提示音并显示表情，等待双击接听。
+- `LK_CALL_PREPARING`：预留状态，用于播放器准备阶段。
+- `LK_CALL_ACTIVE`：通话中，正在收发 PCM 音频。
+
+#### WebSocket 连接
+
+初始化入口：
+
+```c
+SYS_INIT(voice_livekit_poll_evt_init, SYS_INIT_LEVEL_PRE_APPLICATION, 50);
+```
+
+模块初始化时订阅：
+
+```c
+voice_msg_sub(VOICE_MSG_WIFI_IP_GOT, bridge_wifi_ip_got, NULL);
+voice_msg_sub(VOICE_MSG_BUTTON_CHANGE, bridge_button_event, NULL);
+```
+
+当 WiFi 获取 IP 后，创建 `lk.bridge` 线程，线程会循环连接 Node：
+
+```c
+bridge_connect();
+```
+
+WebSocket 路径由设备 ID 拼出：
+
+```c
+/ws/device?deviceId=<device_did>
+```
+
+设备 ID 优先来自：
+
+```c
+get_app_datas()->did
+```
+
+如果设备 ID 为空，则使用 `LK_BRIDGE_FALLBACK_DEVICE_ID`。
+
+#### JSON 控制消息
+
+`handle_text_frame()` 负责处理 Node 发来的文本 JSON。
+
+目前支持的消息：
+
+- `hello`：连接确认。
+- `play_url`：调试用，播放 URL。
+- `stop`：停止播放。
+- `incoming_call`：来电通知，进入响铃状态。
+- `call_start`：通话开始，初始化音频播放和录音。
+- `call_end`：通话结束，停止音频链路。
+- `device_call_ack`：发起呼叫确认。
+- `device_accept_ack`：接听确认。
+- `device_reject_ack`：拒接确认。
+- `device_hangup_ack`：挂断确认。
+
+发给 Node 的消息：
+
+```json
+{"type":"device_call","toId":"目标设备号"}
+{"type":"device_accept","inviteId":"来电 inviteId"}
+{"type":"device_reject","inviteId":"来电 inviteId"}
+{"type":"device_hangup"}
+```
+
+#### 二进制音频协议
+
+二进制帧格式：
+
+```c
+#define LK_BRIDGE_MAGIC        0xA5
+#define LK_BRIDGE_VERSION      0x01
+#define LK_BRIDGE_HEADER_SIZE  20
+#define LK_BRIDGE_SAMPLE_RATE  16000
+#define LK_BRIDGE_CHANNELS     1
+#define LK_BRIDGE_BITS         16
+```
+
+每个音频包：
+
+- 前 20 字节：自定义 header。
+- 后面 payload：PCM16 little-endian。
+- 下行方向：Node -> 硬件，`flags = 0x00`。
+- 上行方向：硬件 -> Node，`flags = 0x01`。
+
+header 结构：
+
+```c
+typedef struct {
+    uint8_t  magic;
+    uint8_t  version;
+    uint8_t  flags;
+    uint8_t  channels;
+    uint32_t sample_rate;
+    uint32_t samples_per_channel;
+    uint32_t seq;
+    uint32_t timestamp;
+} lk_bridge_header_t;
+```
+
+#### 下行播放
+
+Node 下发的 PCM 二进制帧进入：
+
+```c
+handle_binary_frame()
+```
+
+处理流程：
+
+1. 校验 magic/version/sampleRate/channels。
+2. 确认当前处于 `LK_CALL_ACTIVE`。
+3. 把 PCM payload 放入 `g_pcm_queue`。
+4. `lk.audio.writer` 线程从队列取帧。
+5. 调用 `lisa_audio_play_write()` 写入音频设备。
+
+为降低断续感，播放端做了预填充：
+
+```c
+#define LK_BRIDGE_AUDIO_START_PREFILL 4
+```
+
+队列满时丢弃最旧帧，优先保持实时性，避免旧音频追播。
+
+#### 上行录音
+
+通话开始时，`start_stream_playback()` 会配置 `audio0`：
+
+```c
+lisa_audio_record_config()
+lisa_audio_register_callback()
+lisa_audio_record_start()
+```
+
+录音回调：
+
+```c
+livekit_audio_record_cb()
+```
+
+处理流程：
+
+1. 音频设备回调 PCM。
+2. `uplink_accumulate_pcm()` 聚合为 640 字节一帧。
+3. 放入 `g_uplink_queue`。
+4. `lk.audio.uplink` 线程组装 20 字节 header。
+5. 调用 `lisa_ws_send_binary()` 发给 Node。
+
+当前上行帧大小：
+
+```c
+#define LK_BRIDGE_UPLINK_FRAME_BYTES 640
+```
+
+对应 16kHz/16bit/mono 下约 20ms 音频。
+
+#### 音频参数
+
+当前通话链路使用：
+
+```c
+#define LK_BRIDGE_RECORD_ANALOG_GAIN 20
+#define LK_BRIDGE_RECORD_DIGITAL_GAIN 0
+#define LK_BRIDGE_PLAY_DIGITAL_GAIN (-18)
+```
+
+含义：
+
+- `RECORD_ANALOG_GAIN`：设备麦克风采集增益。
+- `RECORD_DIGITAL_GAIN`：设备麦克风数字增益。
+- `PLAY_DIGITAL_GAIN`：设备播放通话音频的数字增益。
+
+之前调试噪音时，主要就是围绕这几个参数和 Node 端音频增益做过调整。当前版本里，硬件端播放数字增益为 `-18`，上行录音模拟增益为 `20`。
+
+#### 来电响铃与表情
+
+收到 `incoming_call` 后进入 `LK_CALL_RINGING`：
+
+```c
+bridge_start_ringing()
+```
+
+行为：
+
+- 保存 `inviteId` 和 `fromId`。
+- 显示表情：
+
+```c
+#define LK_BRIDGE_RING_EMOJI "wait"
+```
+
+- 循环播放本地提示音：
+
+```c
+player_mgr_play(LOCAL, app_tone_get_url(TONE_ID_94), 0);
+```
+
+- 每 2500ms 重复一次：
+
+```c
+#define LK_BRIDGE_RING_REPEAT_MS 2500
+```
+
+通话接通或结束后显示：
+
+```c
+#define LK_BRIDGE_IDLE_EMOJI "neutral"
+```
+
+#### 按键交互
+
+在 `bridge_button_event()` 中处理 button 0 的双击和三击：
+
+```c
+if (evt->action == VOICE_MSG_BUTTON_ACTION_DOUBLE_CLICK) {
+    if (g_call_state == LK_CALL_RINGING) {
+        bridge_request_accept();
+    } else if (g_call_state == LK_CALL_IDLE) {
+        // 当前不再用双击主动发起呼叫
+    } else {
+        bridge_request_hangup();
+    }
+} else if (evt->action == VOICE_MSG_BUTTON_ACTION_TRIPLE_CLICK) {
+    if (g_call_state == LK_CALL_RINGING) {
+        bridge_request_reject();
+    }
+}
+```
+
+当前设计：
+
+- 来电中：双击接听。
+- 来电中：三击拒接。
+- 通话中：双击挂断。
+- 空闲中：双击不主动发起呼叫，发起呼叫改由语音意图/MCP 工具触发。
+- 空闲中：三击不再打开二维码/信息页，避免和来电拒接冲突。
+
+### 2. MCP 通话工具
+
+文件：`apps/arcs-mini/mcp-tools/mcp_tool_call_device.c`
+
+这个文件新增 MCP 工具：
+
+```c
+MCP_TOOL_DEFINE(ls.built_in.call_device, call_device_list, call_device_call);
+```
+
+工具名：
+
+```text
+ls.built_in.call_device
+```
+
+入参：
+
+```json
+{
+  "toId": "目标设备号"
+}
+```
+
+执行逻辑：
+
+```c
+voice_livekit_bridge_request_call(to_id);
+```
+
+也就是说，主链路意图识别到“打电话”后，只要返回 MCP tool call，硬件端就会通过该工具把目标设备号交给 LiveKit 桥接模块。
+
+返回结果：
+
+```json
+{
+  "content": "呼叫已发起",
+  "ret": 0
+}
+```
+
+如果失败则返回：
+
+```json
+{
+  "content": "呼叫发起失败",
+  "ret": -1
+}
+```
+
+### 3. MCP 工具注册
+
+文件：`apps/arcs-mini/mcp-tools/CMakeLists.txt`
+
+新增编译文件：
+
+```cmake
+mcp_tool_call_device.c
+```
+
+这一步确保 `ls.built_in.call_device` 会进入固件，主链路才能调用到该工具。
+
+### 4. LiveKit 事件模块注册
+
+文件：`src/category/comm/msgs/CMakeLists.txt`
+
+新增编译文件：
+
+```cmake
+voice_livekit_poll_msg.c
+```
+
+这一步确保 LiveKit WebSocket/音频桥接模块会进入固件，并通过 `SYS_INIT` 自动初始化。
+
+### 5. 主按键逻辑调整
+
+文件：`apps/arcs-mini/main.c`
+
+主按键处理里，双击逻辑被调整为保留给 LiveKit 通话，不再触发原先可能冲突的行为：
+
+```c
+case VOICE_MSG_BUTTON_ACTION_DOUBLE_CLICK:
+{
+    LISA_LOGI(TAG, "power button double click, reserved for livekit call");
+    break;
+}
+```
+
+实际通话状态下的双击接听/挂断由 `voice_livekit_poll_msg.c` 中订阅的 `bridge_button_event()` 处理。
+
+三击逻辑也被调整为保留给 LiveKit 来电拒接，主按键处理不再打开信息/二维码页：
+
+```c
+case VOICE_MSG_BUTTON_ACTION_TRIPLE_CLICK:
+{
+    LISA_LOGI(TAG, "power button triple click, reserved for livekit reject");
+    break;
+}
+```
+
+这样做的目的：
+
+- 避免双击同时触发拍照识图、唤醒或其他主链路行为。
+- 避免来电中三击拒接后又打开二维码/信息页。
+- 让通话状态机拥有双击接听、三击拒接、双击挂断的优先处理权。
+
+## 发起呼叫流程
+
+### 语音发起
+
+1. 用户单击设备按钮唤醒。
+2. 用户说“给小红打电话”。
+3. 主链路云服务识别为通话意图。
+4. 主链路根据联系人/设备映射得到目标 `toId`。
+5. 主链路返回 MCP 调用：
+
+```json
+{
+  "name": "ls.built_in.call_device",
+  "arguments": {
+    "toId": "目标设备号"
+  }
+}
+```
+
+6. 硬件端执行 `mcp_tool_call_device.c`。
+7. 调用 `voice_livekit_bridge_request_call(toId)`。
+8. 硬件端通过 WebSocket 发：
+
+```json
+{"type":"device_call","toId":"目标设备号"}
+```
+
+9. Node 创建 invite，通知被叫端。
+
+### 代码入口
+
+```text
+apps/arcs-mini/mcp-tools/mcp_tool_call_device.c
+  -> voice_livekit_bridge_request_call(toId)
+src/category/comm/msgs/voice_livekit_poll_msg.c
+  -> lisa_ws_send_text({"type":"device_call","toId":"..."})
+```
+
+## 接听流程
+
+1. Node 给硬件端发送：
+
+```json
+{
+  "type": "incoming_call",
+  "inviteId": "...",
+  "fromId": "..."
+}
+```
+
+2. 硬件端进入 `LK_CALL_RINGING`。
+3. 设备循环播放提示音并显示 `wait` 表情。
+4. 用户双击按钮。
+5. 硬件端发送：
+
+```json
+{"type":"device_accept","inviteId":"..."}
+```
+
+6. Node 完成接听，双方加入 LiveKit 房间。
+7. Node 下发：
+
+```json
+{"type":"call_start","sampleRate":16000,"channels":1}
+```
+
+8. 硬件端启动录音和播放，进入 `LK_CALL_ACTIVE`。
+
+## 拒接流程
+
+来电中三击按钮：
+
+```json
+{"type":"device_reject","inviteId":"..."}
+```
+
+Node 收到后：
+
+1. 校验 invite 仍为 `pending`。
+2. 将 invite 状态更新为 `rejected`。
+3. 回包给设备：
+
+```json
+{"type":"device_reject_ack","inviteId":"...","status":"rejected"}
+```
+
+4. 通知主叫端 `call_end`，reason 为 `rejected`。
+
+硬件端发送拒接后会立即：
+
+- 停止本地来电提示音。
+- 清空当前 pending invite。
+- 状态回到 `LK_CALL_IDLE`。
+- 显示空闲表情。
+
+## 挂断流程
+
+### 设备主动挂断
+
+通话中双击按钮：
+
+```json
+{"type":"device_hangup"}
+```
+
+Node 结束 invite，并通知双方 `call_end`。
+
+### 对端挂断
+
+Node 下发：
+
+```json
+{"type":"call_end","reason":"..."}
+```
+
+硬件端执行：
+
+```c
+stop_stream_playback();
+```
+
+然后：
+
+- 停止播放。
+- 停止录音。
+- 清空上下行队列。
+- 关闭 PA。
+- 恢复唤醒。
+- 请求主云链路重连。
+
+对应代码：
+
+```c
+app_wakeup_start();
+voice_cloud_reconnect_async();
+```
+
+## 与 Node LiveKit 桥接服务的协议约定
+
+硬件端连接：
+
+```text
+ws://<LK_BRIDGE_WS_HOST>:<LK_BRIDGE_WS_PORT>/ws/device?deviceId=<deviceId>
+```
+
+文本消息使用 JSON。
+
+音频消息使用二进制帧：
+
+```text
+20 字节 header + PCM16 LE payload
+```
+
+当前固定音频格式：
+
+```text
+sampleRate: 16000
+channels: 1
+bits: 16
+frame: 20ms 左右
+```
+
+如果 Node 下发音频格式不一致，硬件端会丢帧并打印 `format mismatch`。
+
+## 与主链路的关系
+
+这次硬件端新增的是“工具执行能力”和“实时通话音频能力”，而不是在硬件端自己做联系人识别。
+
+联系人识别/目标设备号选择由主链路完成：
+
+- App/后台维护联系人别名与设备号映射。
+- 主链路意图识别根据用户语音得到目标 `toId`。
+- 硬件端只接受 `toId` 并发起呼叫。
+
+所以硬件端不关心“小红”“爸爸”“卧室设备”这些自然语言名称，它只关心最终的设备标识。
+
+## 调试日志关键字
+
+设备端常用日志关键字：
+
+```text
+voice.app.lkbridge
+bridge ws connect
+bridge ws: connected
+incoming call ringing
+device call requested
+device accept requested
+device reject requested
+device_reject_ack
+device hangup requested
+call_start
+first pcm queued
+writer stats
+first uplink pcm sent
+uplink stats
+direct audio playback stopped
+```
+
+Node 端常用日志关键字：
+
+```text
+[bridge.ws] device=<id> connected
+[bridge.call] device invite created
+[bridge] incoming_call
+[bridge.ws] device=<id> text: { type: 'device_reject', ... }
+[bridge.call] invite=<id> ... pending->rejected by=<deviceId>
+[call.accept]
+[bridge] joined room
+[bridge.uplink] audio stats
+[bridge.ws] audio stats
+```
+
+## 当前限制与后续优化点
+
+### 1. Node 地址仍是硬编码
+
+当前硬件端地址在 `voice_livekit_poll_msg.c` 顶部宏里：
+
+```c
+#define LK_BRIDGE_WS_HOST "39.108.110.91"
+#define LK_BRIDGE_WS_PORT "3000"
+```
+
+后续如果要更适合测试/生产切换，可以改为：
+
+- 配置文件读取。
+- BLE/云端配置下发。
+- 编译参数注入。
+
+### 2. 默认目标仍有兜底值
+
+```c
+#define LK_BRIDGE_DEFAULT_CALL_TARGET "f17c0a1a322ed2ad"
+```
+
+正常语音发起通话时，目标应该由 MCP 入参 `toId` 提供；默认目标只是防御性兜底。
+
+### 3. 来电拒接已接入，但拒接入口固定为三击
+
+当前来电中支持：
+
+- 双击接听。
+- 三击拒接。
+- 对端取消或超时后 Node 下发结束。
+
+为避免来电拒接后继续打开二维码页，主按键里的三击打开信息/二维码页逻辑已经移除。后续如果还需要二维码入口，建议放到设置菜单、五击/六击/七击组合，或由语音/页面触发，而不要复用三击。
+
+### 4. 音频参数仍需要按设备环境微调
+
+当前播放/录音参数已经经过一轮调试，但不同硬件、外壳、麦克风距离、扬声器音量下仍可能需要调整：
+
+```c
+LK_BRIDGE_RECORD_ANALOG_GAIN
+LK_BRIDGE_RECORD_DIGITAL_GAIN
+LK_BRIDGE_PLAY_DIGITAL_GAIN
+LK_BRIDGE_AUDIO_BUFFER_COUNT
+LK_BRIDGE_AUDIO_BUFFER_SAMPLES
+LK_BRIDGE_AUDIO_START_PREFILL
+```
+
+### 5. 与主链路音频资源互斥
+
+通话开始时会停止唤醒/录音/播放相关共享音频路径：
+
+```c
+app_wakeup_stop();
+lisa_audio_record_stop();
+lisa_audio_play_stop();
+```
+
+通话结束后再恢复：
+
+```c
+app_wakeup_start();
+voice_cloud_reconnect_async();
+```
+
+这是为了避免主链路 ASR/TTS 和通话链路同时占用 `audio0` 导致噪声、卡顿或录音失败。