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);