docs: correct inaccuracies across guides, references, and tutorials

docs-site/docs/faq.md

@@ -89,9 +89,8 @@ UDP实现版本有非常好的弱网性能支持, 即使在网络条件很差的
 - 重新调用 `iot_client_get_session_token()` 获取新 token，然后创建新 session
 
 **RTC TCP Client：**
-- 使用长连接 + Ping/Pong 保活，不依赖 session_token
+- 连接建立时需要 `agent_token`（通过 `iot_client_get_session_token()` 获取），但建立后使用长连接 + Ping/Pong 保活，无需定期刷新 token
 - 如果连接断开（`on_disconnect` 回调），由持有 `tai_ctx_t` 的线程重新调用 `tai_connect()` 即可
-- 连接刷新由协议内部自动处理（`CONNECTION_REFRESH_REQ/RESP`）
 
 :::caution 不要在回调里重连
 所有回调都运行在后台工作线程上。**绝对不要**在回调（包括 `on_disconnect`）内部调用 `tai_connect()` / `tai_disconnect()` / `tai_ctx_deinit()`——这些函数会 join 工作线程，导致自死锁（self-deadlock）。

docs-site/docs/guides/dp-persistence.md

@@ -43,7 +43,7 @@ if (iot_dp_dump_json(client, &json) == OPRT_OK && json) {
 }
 ```
 
-`iot_dp_dump_json` 与 `iot_dp_restore_json` 产出 / 消费同一种 `{"dps":{...}}` 格式,可无损往返。
+`iot_dp_dump_json` 与 `iot_dp_restore_json` 产出 / 消费同一种 `{"dps":{...}}` 格式,可往返恢复。**注意:`iot_dp_dump_json` 的快照不含 RAW 类型 DP**(见 `iot_dp.h` 中 RAW omission 说明),因此 dump→restore 周期会丢失运行中的 RAW 值;如需保留 RAW,请通过保存回调(回调快照同样不含 RAW,需应用自行另行保存)或避免依赖其往返。
 
 ## 保存回调在嵌入式上的注意事项
 
@@ -95,5 +95,5 @@ iot_client_t *client = iot_client_init(&cfg);
 
 应用周期调用 `iot_dp_schema_check_update()` 轮询最新 schema。若有更新,SDK 会**保留仍存在的 DP 的当前值、给新增 DP 填默认值**,然后触发 `iot_schema_update_callback_t`。在该回调里:
 
-1. 把新的 `schema_id` / `schema` 覆盖持久化;
+1. 把新的 `schema` 覆盖持久化(`schema_id` 不变,无需重写);
 2. 建议随后调一次 `iot_dp_report_all()` 做一次全量同步。

docs-site/docs/guides/ota-upgrade.md

@@ -65,7 +65,7 @@ typedef struct {
 typedef enum {
     OTA_STATUS_IDLE        = 0,  // 空闲
     OTA_STATUS_UPGRADING   = 1,  // 升级中（下载/烧写前）
-    OTA_STATUS_UPGRAD_FINI = 2,  // 升级成功（通常重启后回报）
+    OTA_STATUS_UPGRAD_FINI = 2,  // 升级成功（重启前回报）
     OTA_STATUS_UPGRD_EXEC  = 3,  // 升级失败
     OTA_STATUS_UPGRD_ABORT = 4,  // 升级中止
 } iot_ota_status_t;
@@ -109,6 +109,7 @@ CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL=y
 #include "iot_client.h"
 #include "iot_ota.h"
 #include "esp_app_desc.h"
+#include "esp_crt_bundle.h"
 
 const esp_app_desc_t *desc = esp_app_get_description();
 
@@ -122,7 +123,13 @@ iot_client_config_t iot_cfg = {
     .mqtt_auto_connect = false,
     /* 应用固件版本：init 时自动上报，供云端 OTA 比较（NULL 用 SDK 默认） */
     .sw_ver     = desc->version,
+    /* 公共 CA 证书包：ATOP HTTPS（版本上报/升级查询/状态回报）需要 */
+    .cert_bundle_attach = (tls_cert_bundle_attach_fn)esp_crt_bundle_attach,
 };
+
+/* iot_init(pal) 必须在 iot_client_init 前调用，否则 iot_client_init 返回 NULL */
+iot_init(tai_pal_freertos());
+
 iot_client_t *iot = iot_client_init(&iot_cfg);
 
 /* 查询升级（云端与 init 时上报的 sw_ver 比较，无需再传版本号） */

docs-site/docs/guides/porting-to-new-platform.md

@@ -146,7 +146,7 @@ CONFIG_FREERTOS_HZ=1000
 
 ## 通用注意事项
 
-- PAL `thread_create` 需要设置足够的栈大小；`pal_freertos.c` 默认使用 `PAL_FR_TASK_STACK_WORDS`（约 6KB，可按平台内存情况调小或调大）
+- PAL `thread_create` 需要设置足够的栈大小；`pal_freertos.c` 默认使用 `PAL_FR_TASK_STACK_WORDS`（6144 words，32 位平台上约 24KB，可按平台内存情况调小或调大）
 - SDK 内部通过 mbedTLS 处理 TLS，需要正确的系统时间用于证书验证；若未提供 CA 证书，TLS 连接可能退化为不校验证书的模式
 - `tcp_recv` 应支持阻塞/超时语义（后台线程会循环调用）
 - `tcp_poll` 用于检查套接字的可读/可写状态，需正确实现 events 位掩码

docs-site/docs/guides/vad-and-interrupt.md

@@ -41,19 +41,22 @@ void on_event(tai_ctx_t *ctx, const tai_event_msg_t *msg, void *ud)
 
 ### 启用/配置云端 VAD
 
-通过 `session_attrs_json` 传入自定义会话属性 JSON。当前 SDK 只负责原样透传该字符串，具体字段含义和支持情况以平台侧配置为准：
+通过 `event_user_data_json` 传入 `chatAttributes`，该字符串会随每个 EventStart 包发送给云端。SDK 默认已启用云端 VAD（留空时使用内置默认值），如需自定义可覆盖：
 
 ```c
 tai_config_t cfg = {
     // ...
-    .session_attrs_json = "{\"vad_enable\":true,\"vad_silence_ms\":800}",
+    .event_user_data_json =
+        "{\"sys.workflow\":\"asr-llm-tts\","
+        "\"asr.enableVad\":true,"
+        "\"processing.interrupt\":true}",
 };
 ```
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `vad_enable` | bool | 是否启用云端 VAD |
-| `vad_silence_ms` | int | 静默判定时长（毫秒），默认约 800ms |
+| `asr.enableVad` | bool | 是否启用云端 VAD（默认 true） |
+| `processing.interrupt` | bool | 是否启用打断处理（默认 true） |
 
 ### 设备端 VAD 是否需要？
 

docs-site/docs/reference/iot-client.md

@@ -235,7 +235,7 @@ int iot_client_process(iot_client_t *client, uint32_t timeout_ms);
 - `client` — IoT 客户端实例
 - `timeout_ms` — 处理超时时间（毫秒）
 
-**返回值：** `OPRT_OK` 成功。
+**返回值：** `OPRT_OK` 成功；`client` 为 NULL 时返回 `OPRT_INVALID_PARAMETER`；无 MQTT 连接时返回 `OPRT_UNINITIALIZED`。
 
 ---
 
@@ -252,7 +252,7 @@ int iot_client_publish(iot_client_t *client, const uint8_t *data, size_t data_le
 - `data` — 明文数据（内部自动加密）
 - `data_len` — 数据长度
 
-**返回值：** `OPRT_OK` 成功。
+**返回值：** `OPRT_OK` 成功；`client` 为 NULL 或 `data` 为 NULL / `data_len` 为 0 时返回 `OPRT_INVALID_PARAMETER`；无 MQTT 连接时返回 `OPRT_UNINITIALIZED`；加密缓冲区分配失败返回 `OPRT_MALLOC_FAILED`；加密或发布失败返回 `OPRT_COMMUNICATION_ERROR`。
 
 ---
 

docs-site/docs/tutorials/openapi-activate.md

@@ -124,7 +124,7 @@ python3 ./build/tuya_openapi.py pairing-token --uid "ay..." --paring-type BLE \
 
 ## 注意事项
 
-- 配网 Token 有有效期（通常 100 秒），需在有效期内完成设备激活。
+- 配网 Token 有有效期，需在有效期内完成设备激活；可用 `tuya_openapi.py pairing-result --poll` 轮询确认结果（`--timeout` 默认 100 秒）。
 - `tuya_openapi.py` 使用 Python 标准库实现，无需安装额外依赖。
 - 实际产品中，OpenAPI 调用应在厂商自己的后台服务中完成，**不应将 Access
   Secret 暴露在客户端或设备端**。

docs-site/docs/tutorials/pair-by-ble.md

@@ -129,7 +129,7 @@ int tuya_ble_nimble_stop(void);
 
 停止 BLE 广播和服务，释放 NimBLE 资源。
 
-**返回值：** `0` 成功，非零表示错误。
+**返回值：** 当前实现始终返回 `0`（内部 `nimble_port_stop()` 的结果被忽略，不返回错误码）。
 
 ### `tuya_ble_wifi_creds_t`