RTC TCP Client SDK 参考文档

1. 概述​

RTC TCP Client（API 前缀 tai_*）是 tRTC(tuya自研RTC协议) 的 TCP 实现。以源码形式提供，通过 PAL（Platform Abstraction Layer）实现跨平台移植，适用于 POSIX、FreeRTOS（ESP-IDF）等环境。

头文件：tuya_ai.h（单一 include）

特点​

• 简洁 API：类型化发送函数（tai_send_text、tai_send_audio_*、tai_send_image），无需手动组装数据结构体
• 后台接收线程：tai_connect 后自动启动后台线程处理接收和 keepalive
• 回调驱动：通过 on_audio、on_text、on_image、on_event、on_disconnect 接收数据
• 无外部依赖：用户 PAL 只需提供原始 TCP 和平台原语；TLS 和加密由 SDK 内部通过 bundled mbedTLS 处理

2. 常量定义​

2.1 数据包类型​

2.2 流标志（Stream Flags）​

2.3 事件类型​

2.4 客户端类型​

2.5 音频编码​

2.6 图像格式​

2.7 图像负载类型​

2.8 签名级别​

2.9 数据 ID​

2.10 返回码​

3. 配置（tai_config_t）​

调用 tai_ctx_init 前填充此结构体。所有指针字段在 context 生命周期内必须保持有效。

3.1 服务器配置​

3.2 身份配置​

3.3 会话选项​

3.4 业务标识​

3.5 安全配置​

3.6 保活配置​

3.7 测试配置​

3.8 平台适配​

3.9 回调函数​

所有回调均在后台接收线程中调用。

回调签名：

每个回调接收单个 const 消息结构体指针 + user_data（不再是旧的多参数形式）。

void (*on_audio)     (tai_ctx_t *ctx, const tai_audio_msg_t      *msg, void *user_data);
void (*on_text)      (tai_ctx_t *ctx, const tai_text_msg_t       *msg, void *user_data);
void (*on_image)     (tai_ctx_t *ctx, const tai_image_msg_t      *msg, void *user_data);
void (*on_event)     (tai_ctx_t *ctx, const tai_event_msg_t      *msg, void *user_data);
void (*on_disconnect)(tai_ctx_t *ctx, const tai_disconnect_msg_t *msg, void *user_data);
int  (*on_flow_control)(tai_ctx_t *ctx, void *user_data);

接收背压（on_flow_control）​

• worker 在每次读取前及完整 Frame 之间调用钩子。符合规范的服务端不会在握手阶段触发它（应答先于媒体下发）；仅当服务端把媒体排在应答之前才可能在握手期被调用。钩子必须非阻塞；应用负责同步共享的队列状态。
• 返回 0 会暂停读取和解析，所有入站流量都会停滞，包括 ChatBreak、ASR 文本、Pong 和 EOF 检测。恢复后先处理已缓冲的完整 Frame，再读取；不完整输入回到有上限的阻塞接收。
• 主动暂停挂起接收存活超时；恢复时获得新的完整 ping_timeout_ms 预算。Ping 和停止请求仍执行，Ping 发送失败仍断连。
• 背压也在 Audio Packet 内的每个编解码帧回调前检查。中途暂停会以零拷贝方式保留该 Packet 的剩余字节，恢复时先交付剩余帧、再处理后续 Packet。应用应在 on_audio 中按服务端时间（msg->timestamp_ms）丢弃过期音频，而不是改写 SDK 接收状态。

默认每 AGENTIC_KIT_TAI_FLOW_CONTROL_POLL_MS（50 ms）重查背压，并以 AGENTIC_KIT_TAI_WORKER_YIELD_MS（10 ms）在持续流量下让出 CPU。

pal_t 新增必填的 sleep_ms 回调。它必须非忙等地休眠至少请求的毫秒数，0 为 no-op，且不能依赖 socket 可读性。所有自定义 PAL 和使用方必须用新头文件重新编译。

接收消息结构体​

tai_audio_msg_t（音频回调）：

tai_text_msg_t（文本回调）：

tai_image_msg_t（图像回调）：

tai_event_msg_t（事件回调）：

tai_disconnect_msg_t（断连回调）：

断连原因（reason）​

detail（当 reason==TRANSPORT）​

detail（当 reason==PROTOCOL）​

4. 生命周期 API​

tai_ctx_size​

size_t tai_ctx_size(void);

返回 context 所需的内存大小。调用方需分配至少此大小的内存，传给 tai_ctx_init。

tai_ctx_init​

tai_ctx_t *tai_ctx_init(void *mem, const tai_config_t *cfg);

初始化 context。mem 必须至少为 tai_ctx_size() 字节，且在 context 生命周期内保持有效。

参数：

• mem — 预分配的内存块
• cfg — 配置结构体

返回值： 成功返回 tai_ctx_t*（即 mem 强转），失败返回 NULL。

tai_ctx_deinit​

void tai_ctx_deinit(tai_ctx_t *ctx);

反初始化 context，释放内部资源。调用后 mem 可以 free。必须在 tai_disconnect 之后调用。

tai_connect​

int tai_connect(tai_ctx_t *ctx);

执行 TLS 握手、发送 ClientHello、建立会话、启动后台接收线程。

返回值： TAI_OK 成功，TAI_ERR_* 失败。

行为：

• 阻塞直到连接建立或失败
• 成功后，后台线程开始处理 Ping/Pong 和接收数据
• 连接成功后即可调用 tai_send_* 系列函数

tai_disconnect​

void tai_disconnect(tai_ctx_t *ctx);

先停止并 join 后台接收线程，再发送一个 best-effort 的 SessionClose，最后关闭传输（TLS / TCP）。

行为：

• 阻塞直到后台线程退出（join）
• 调用后不可再发送数据
• 之后应调用 tai_ctx_deinit
• 不可在回调中调用（会 join 自身所在的 worker 线程，导致自死锁）；如需从回调中触发断连，请用 tai_request_disconnect

tai_request_disconnect​

void tai_request_disconnect(tai_ctx_t *ctx);

请求后台 worker 停止，但不 join、不拆除连接。可从任意线程调用，包括从接收回调内部调用（与 tai_disconnect 不同）。worker 会在下一轮循环退出。

用途： 在回调中安全地触发断连。调用后，拥有 context 的线程仍需调用 tai_disconnect() 来 join worker、发送 SessionClose 并释放资源。

5. 发送 API​

tai_send_text​

int tai_send_text(tai_ctx_t *ctx, const char *text, size_t len);

发送文本消息。一次调用内部依次发出 4 个应用包：EventStart → 文本（ONE_SHOT 标志）→ EventPayloadsEnd → EventEnd，调用方无需再手动收尾。

参数：

• text — UTF-8 文本
• len — 文本字节数

返回值： TAI_OK 或 TAI_ERR_*。

tai_send_audio_start​

int tai_send_audio_start(tai_ctx_t *ctx,
                         uint8_t codec, uint8_t channels,
                         uint8_t bit_depth, uint32_t sample_rate);

开始一段音频流。必须在 tai_send_audio_chunk 之前调用。

参数：

• codec — 编码格式：TAI_AUDIO_PCM（101）或 TAI_AUDIO_OPUS（111）
• channels — 声道数（通常为 1）
• bit_depth — 位深（通常为 16）
• sample_rate — 采样率（通常为 16000）

tai_send_audio_chunk​

int tai_send_audio_chunk(tai_ctx_t *ctx, const uint8_t *pcm, size_t len);

发送一帧音频数据。可多次调用（流中间包）。

参数：

• pcm — 音频数据（PCM 或 Opus 帧，取决于 audio_start 时的 codec）
• len — 数据字节数

tai_send_audio_end​

int tai_send_audio_end(tai_ctx_t *ctx);

结束音频流。通知服务端本次音频输入完毕，开始处理。

tai_send_image​

int tai_send_image(tai_ctx_t *ctx,
                   const uint8_t *data, size_t len,
                   uint8_t format, uint16_t width, uint16_t height);

发送单张图片。

参数：

• data — 图片二进制数据
• len — 数据长度
• format — 图片格式：TAI_IMG_JPEG（1）或 TAI_IMG_PNG（2）
• width / height — 图片尺寸

tai_send_image_with_text​

int tai_send_image_with_text(tai_ctx_t *ctx,
                             const char *text, size_t text_len,
                             const uint8_t *img_data, size_t img_len,
                             uint8_t format,
                             uint16_t width, uint16_t height);

同时发送文本和图片（如图片理解场景）。内部会先发文本包再发图片包，组成一次完整请求。

tai_chat_break​

int tai_chat_break(tai_ctx_t *ctx);

发送聊天打断事件。用于用户主动打断 AI 回复（如按键中断）。服务端收到后会停止当前响应生成。

tai_send_mcp_response​

int tai_send_mcp_response(tai_ctx_t *ctx, const char *json_rpc_response);

发送 MCP 命令的响应。当 on_event 收到 TAI_EVT_MCP_CMD 时，设备执行完命令后通过此函数返回结果。

参数：

• json_rpc_response — JSON-RPC 格式的响应字符串

6. 日志​

SDK 日志的全局开关是编译期的 AGENTIC_KIT_LOG_LEVEL（在 common/log.h 统一设限，作用于整个 SDK，不限于本模块）；本模块可再用 AGENTIC_KIT_TAI_LOG_LEVEL 单独压低（原 TAI_LOG_LEVEL 的改名，只降不升，默认等于全局值）。有效值：

高于上限的日志在编译期消除；上限以下无条件输出——没有运行时级别（tai_set_log_level() 已随运行时层一起移除）。量产用 -DAGENTIC_KIT_LOG_LEVEL=2 压到 error + warn，或用 -DAGENTIC_KIT_TAI_LOG_LEVEL=N 只压本模块（低于 3 时 tai_log_packet 的 JSON 格式化器连同调用一并消失）；改变日志去向（或按级别丢弃）同样是构建决策：定义 AGENTIC_KIT_LOG 把分发接管进你自己的宏。

媒体中间帧默认按 1/N 采样打 INFO（AGENTIC_KIT_TAI_LOG_MEDIA_SAMPLE_N，默认 50；设 0 = 关采样进 flood 模式）。flood 模式下中间帧改打 DEBUG，仅当有效上限为 4 时才输出——上限为 3 时把采样设为 0，中间帧会完全没有日志（比默认采样更少，别误判成丢包）。

7. 典型使用流程​

#include "tuya_ai.h"

// 1. 分配内存
void *mem = malloc(tai_ctx_size());

// 2. 配置
tai_config_t cfg = {
    .host             = "ai-gw.example.com",
    .port             = 8883,
    .device_id        = devid,
    .local_key        = local_key,
    .client_type      = TAI_CLIENT_DEVICE,
    .protocol_version = TAI_VER_21,
    .sign_level       = TAI_SIGN_HMAC_SHA256,
    .pal              = &my_pal,
    .on_audio         = my_on_audio,
    .on_text          = my_on_text,
    .on_image         = my_on_image,
    .on_event         = my_on_event,
    .on_disconnect    = my_on_disconnect,
};

// 3. 初始化 + 连接
tai_ctx_t *ctx = tai_ctx_init(mem, &cfg);
if (tai_connect(ctx) != TAI_OK) { /* handle error */ }

// 4. 发送文本
tai_send_text(ctx, "hello", 5);

// 5. 或发送音频流
tai_send_audio_start(ctx, TAI_AUDIO_PCM, 1, 16, 16000);
while (has_audio) {
    tai_send_audio_chunk(ctx, pcm_frame, frame_len);
}
tai_send_audio_end(ctx);   // 手动模式收尾；云端 VAD 模式下不要调用 audio_end

// 6. 响应通过回调异步接收...

// 7. 清理
tai_disconnect(ctx);
tai_ctx_deinit(ctx);
free(mem);

音频流的调用模式取决于 VAD 模式（云端 VAD 连续对话 vs 设备端 VAD/手动按键），详见 VAD 与打断 中的对比表。

8. 线程安全​

• tai_send_* 函数是线程安全的，可以从任意线程调用
• 所有回调在同一个后台接收线程中按序调用
• 回调中可以调用 tai_send_*()（不持有锁）
• 回调中不可调用 tai_connect、tai_disconnect 或 tai_ctx_deinit（它们会 join worker 线程，导致自死锁）
• 如需在回调中触发断连，应调用 tai_request_disconnect()，再由拥有 context 的线程调用 tai_disconnect()