docs: 补充核心分层中文注释

components/platform/internal/multimodal/audio_pipeline.h

@@ -10,7 +10,9 @@
 extern "C" {
 #endif
 
+/* 上行回调接收已经编码的 Opus 包；返回错误会被采集任务记录并按策略处理。 */
 typedef esp_err_t (*multimodal_audio_uplink_cb_t)(const uint8_t *data, size_t len, void *ctx);
+/* PCM 观察者运行在采集任务上下文，必须有界且不可阻塞。 */
 typedef void (*multimodal_audio_pcm_observer_t)(const int16_t *pcm,
                                                size_t samples,
                                                uint32_t sample_rate_hz,
@@ -23,6 +25,7 @@ typedef enum {
     MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_STALLED,
 } multimodal_audio_downstream_playback_event_type_t;
 
+/* generation 将开始、完成、停止或卡顿事件绑定到唯一一次下行响应。 */
 typedef struct {
     multimodal_audio_downstream_playback_event_type_t type;
     uint32_t playback_generation;
@@ -35,6 +38,7 @@ typedef void (*multimodal_audio_downstream_playback_callback_t)(
 esp_err_t multimodal_audio_init(void);
 void multimodal_audio_deinit(void);
 
+/* 上行和下行工作任务共享 codec/I2S 资源，但生命周期和停止请求彼此独立。 */
 esp_err_t multimodal_audio_start_uplink(multimodal_audio_uplink_cb_t cb, void *cb_ctx);
 esp_err_t multimodal_audio_stop_uplink(int timeout_ms);
 bool multimodal_audio_is_uplink_running(void);
@@ -48,6 +52,7 @@ esp_err_t multimodal_audio_unregister_pcm_observer(
         void *observer_ctx,
         int timeout_ms);
 
+/* 下行响应先 begin 建代、持续送入 Opus 包，最后 finish 标记服务端数据结束。 */
 esp_err_t multimodal_audio_handle_downstream_opus(const uint8_t *data, size_t len);
 esp_err_t multimodal_audio_begin_downstream_response(uint32_t *out_playback_generation);
 esp_err_t multimodal_audio_finish_downstream_response(void);

components/platform/internal/multimodal/transport_ws.h

@@ -9,6 +9,7 @@
 extern "C" {
 #endif
 
+/* 仅描述 WebSocket 传输事件，不携带 domain 层的业务会话语义。 */
 typedef enum {
     MULTIMODAL_WS_EVENT_CONNECTED = 0,
     MULTIMODAL_WS_EVENT_DISCONNECTED,
@@ -17,6 +18,7 @@ typedef enum {
     MULTIMODAL_WS_EVENT_BINARY_MESSAGE,
 } multimodal_ws_event_type_t;
 
+/* data 指针只在事件回调期间有效，需要异步处理时必须复制。 */
 typedef struct {
     multimodal_ws_event_type_t type;
     const uint8_t *data;
@@ -26,6 +28,7 @@ typedef struct {
 typedef void (*multimodal_ws_event_callback_t)(const multimodal_ws_event_t *event,
                                                void *user_data);
 
+/* start 复制鉴权信息和回调；stop 负责回收 client、队列及全部工作任务。 */
 esp_err_t multimodal_ws_start(const char *bearer_token,
                               const char *workspace_id,
                               multimodal_ws_event_callback_t cb,
@@ -33,6 +36,7 @@ esp_err_t multimodal_ws_start(const char *bearer_token,
 esp_err_t multimodal_ws_stop(int timeout_ms);
 bool multimodal_ws_is_connected(void);
 
+/* 普通文本允许内部重试；realtime 接口使用更短锁等待和发送超时以保护实时性。 */
 esp_err_t multimodal_ws_send_text(const char *label, const char *text);
 esp_err_t multimodal_ws_send_text_realtime(const char *label, const char *text);
 esp_err_t multimodal_ws_send_binary_realtime(const uint8_t *data, size_t len);