@tencentcloud/sdk-mcp 1.7.7 → 1.7.9-beta.1

package/resource/knowledge/iot/device/activate-service.md

@@ -0,0 +1,167 @@
+---
+product: iot
+framework:
+  - '*'
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+本文介绍使用 IoT 通用功能所需开通的服务列表，具体包括以下各项服务：
+- 基础设备接入服务：提供设备登录与注册、设备通信、物模型管理、动态注册、OTA 升级等基础能力，确保设备能够稳定接入并实现基本操作。
+
+- 音视频设备接入服务：支持设备监控拉流、视频通话、设备对讲等音视频功能，满足实时音视频交互需求。
+
+- 微信通话（TWeCall）服务：实现设备与微信小程序之间的音视频通话，便于用户通过微信平台进行远程沟通。
+
+- 智能语音（TWeTalk）服务：提供设备 AI 语音对讲功能，增强语音交互体验。
+
+- 云存服务：支持设备云存储功能，确保数据安全存储与访问。
+
+   > **说明：**
+   >
+   > - 以上服务列表无需全部开通，您可根据实际需求选择开通对应服务。
+   > - “基础设备接入服务”和“音视频设备接入服务”为最基础服务，必须至少开通其中一项方可使用。若您的智能设备涉及音视频功能，请开通“音视频设备接入服务”；否则，请开通“基础设备接入服务”。
+   > - “微信通话服务”、“智能语音服务”和“云存服务”为增值服务，您可根据实际需求决定是否加购。
+
+## 开通基础设备接入服务
+1. 在购买基础设备接入服务之前，您需要先 [注册腾讯云](https://cloud.tencent.com/document/product/378/17985) 账号，并完成 [实名认证](https://cloud.tencent.com/document/product/378/3629)。
+
+2. 进入 [物联网开发平台购买页](https://buy.cloud.tencent.com/iotexplorer)，实例类型选择**消费实例**，服务类型选择 “基础设备接入服务”。
+
+3. 生效地域：国内设备选择广州区域，出海设备选择新加坡；有效期默认规格5年。
+
+4. 激活码数量：输入您要量产的设备数量，一个物理设备默认烧录一个激活码。
+
+5. 勾选我已阅读并同意《腾讯云服务协议》，单击**立即购买**。
+
+## 开通音视频设备接入服务
+
+1. 在购买音视频设备接入服务之前，您需要先 [注册腾讯云](https://cloud.tencent.com/document/product/378/17985) 账号，并完成 [实名认证](https://cloud.tencent.com/document/product/378/3629)。
+
+2. 进入 [物联网开发平台购买页](https://buy.cloud.tencent.com/iotexplorer)，实例类型选择**消费实例**，服务类型选择 “音视频设备接入服务”。
+
+3. 生效地域：国内设备选择广州区域，出海设备选择新加坡；有效期默认规格5年。
+
+4. 激活码数量：输入您要量产的设备数量，一个物理设备默认烧录一个激活码。
+
+5. 勾选我已阅读并同意《腾讯云服务协议》，单击**立即购买**。
+
+## 开通微信通话服务
+
+使用**微信通话（TWeCall）**服务需要在 开通“音视频设备接入”服务 的基础上，加购微信通话（TWeCall）激活码并激活设备。
+
+### 1. 加购微信通话（TWeCall）激活码
+
+微信通话（TWeCall）激活码支持组合购买和单独购买两种方式。
+
+#### 方式一：组合购买
+1. 访问 [物联网开发平台](https://cloud.tencent.com/product/iotexplorer)，单击**立即选购**，进入 [购买页](https://buy.cloud.tencent.com/iotexplorer)。
+
+2. 实例类型选择**消费实例**，生效地域选择**广州。**
+
+3. 根据您的设备场景选择“音视频设备接入服务”对应规格。若您的音视频设备需要微信通话（TWeCall）功能，则可选择**加购微信通话（TWeCall）激活码**。
+
+4. 选择您的设备所需的微信通话（TWeCall）版本，有效期默认为1年。
+
+5. 输入微信通话（TWeCall）激活码数量。
+
+6. 支付成功即可完成组合购买流程。
+
+#### 方式二：单独购买
+
+如果您已开通过音视频设备接入服务，因业务需要单独购买微信通话（TWeCall）激活码，则可以选择单独购买模式。
+1. 单击购买页“选择配置”旁的**单购增值功能**，将切换为单独购买微信通话（TWeCall）激活码的购买页面。
+
+   > **说明：**
+   >
+   > - 当您已购买音视频设备接入服务后，才会显示**单购增值功能**入口。
+   > - 微信通话（TWeCall）增值服务只服务国内用户，默认区域为广州。
+
+2. 在单独购买微信通话（TWeCall）激活码的购买页面，生效地域选择**广州**。
+
+3. 选择对应版本后，有效期默认1年，输入需要单购的激活码数量。
+
+4. 按指引完成支付即可完成单购流程。
+
+### 2. 激活微信通话（TWeCall）服务
+
+完成**微信通话（TWeCall）激活码**的购买后，您需要为每台设备分别执行一次激活操作，才能在该设备上正常启用微信通话功能。如需为音视频设备激活微信通话（TWeCall）服务，请使用 [激活 TWeCall](https://cloud.tencent.com/document/product/1081/106587) 云 API。
+
+> **注意：**
+> SN 的格式是 productId_deviceName，注意使用英文下划线。
+>
+
+## 开通智能语音增值服务
+
+使用**智能语音（TWeTalk）**服务需要在 开通“音视频设备接入”服务 的基础上，加购智能语音（TWeTalk）激活码并激活设备。
+
+### 1. 加购智能语音（TWeTalk）激活码
+
+ 智能语音（TWeTalk）激活码支持组合购买和单独购买两种方式。
+
+#### 方式一：组合购买
+1. 访问 [物联网开发平台](https://cloud.tencent.com/product/iotexplorer)，单击**立即选购**，进入 [购买页](https://buy.cloud.tencent.com/iotexplorer)。
+
+2. 实例类型选择**消费实例**，生效地域选择**广州。**
+
+3. 根据您的设备场景选择“音视频设备接入服务”对应规格。若您的音视频设备需要智能语音（TWeTalk）功能，则可选择**加购智能语音增值服务激活码。**
+
+4. 选择您的设备所需的智能语音（TWeTalk）版本，有效期默认为1年。
+
+5. 输入智能语音（TWeTalk）增值激活码数量。
+
+6. 支付成功即可完成组合购买流程。
+
+#### 方式二：单独购买
+
+如果您已开通过音视频设备接入服务，因业务需要单独购买智能语音（TWeTalk）激活码，则可以选择单独购买模式。
+1. 单击购买页“选择配置”旁的**单购增值功能**，将切换为单独购买智能语音（TWeTalk）激活码的购买页面。
+
+2. 生效地域：国内设备选择广州区域，出海设备选择新加坡。
+
+3. 选择对应版本后，有效期默认1年，输入需要单购的激活码数量。
+
+4. 按指引完成支付即可完成单购流程。
+
+### 2. 激活智能语音（TWeTalk）服务
+
+完成**智能语音（TWeTalk）激活码**的购买后，您需要为每台设备分别执行一次激活操作，才能在该设备上正常启用智能语音功能。如需为音视频设备激活智能语音（TWeTalk）服务，请使用 [激活 TWeTalk](https://cloud.tencent.com/document/product/1081/129208) 云 API。
+
+> **注意：**
+> DeviceIds.N 字段必须填写，格式是 productId_deviceName，注意使用英文下划线。
+>
+
+## 开通云存服务
+
+使用**云存**服务需要在 开通“基础设备接入”服务 的基础上，调用 [开通云存服务](https://cloud.tencent.com/document/product/1081/104654) 云 API，才能在设备上正常使用云存功能。
+
+> **注意：**
+> 调用 “开通云存服务”  API 时，Region、ProductId、DeviceName 和 PackageId 是必填字段。
+>
+
+## 查询激活码用量
+1. 登录 [物联网开发平台](https://console.cloud.tencent.com/iotexplorer/v2/instance/cd-key)，进入**消费实例**。
+
+2. 选择**用量统计** > **激活码概览**，在此页面，可查看当前账号下“**基础设备激活码**”，“**音视频设备激活码**”，“**微信通话（TWeCall）激活码**”，“**智能语音（TWeTalk）激活码**” 的总数、已使用个数和待使用个数。
+
+## 创建产品
+1.  登录 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer)，进入**实例管理**页面，单击**消费实例**的卡片进入详情页。
+
+2.  选择消费实例左侧导航栏的**产品**，然后单击**创建产品**。
+
+3. 在创建产品页面中，输入“产品名称”；如果您的产品有使用到音视频相关的能力，请您选择设备类型为“**音视频设备**”，否则选择设备类型为“**基础设备**” ；节点类型请选择“**直连设备**”；信息配置好后，单击**创建**。
+
+## 创建设备
+1. 选择消费实例左侧导航栏的**设备**，然后单击**新建设备**。
+
+2. 所属产品选择前述步骤已创建成功的产品，输入设备名称并单击**新建**。
+
+3. 单击创建成功的设备，进入设备详情页获取设备三元组信息。
+
+   > **说明：**
+   >
+   > 产品 ID、设备名称、设备密钥三元组信息作为快速接入的设备身份凭证。
+   >
+

package/resource/knowledge/iot/device/ai-voice-chat/advanced-features/custom-agent.md

@@ -0,0 +1,171 @@
+---
+product: iot
+framework:
+  - '*'
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+本文将介绍如何创建、配置 AI 对话智能体，帮助您打造差异化的产品。
+
+用户可以在 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer/v2/instance/product) 创建智能体，并将其关联到对应产品后进行设备量产。智能体配置支持用户选择所需 **STT(ASR)**、**LLM** 和 **TTS**，同时可配置智能体的**开机欢迎语**、设备控制（如：查询电量、调整音量等）以及自定义用户画像（如陪伴玩偶可以记住主人的年龄、喜好、地理位置）等。
+
+## 前提条件
+1. 您需要先 [注册腾讯云](https://cloud.tencent.com/document/product/378/17985) 账号，并完成 [实名认证](https://cloud.tencent.com/document/product/378/3629)。
+
+2. 购买了 [腾讯云物联网开发平台](https://buy.cloud.tencent.com/iotexplorer) 相关实例，开通并激活了 [智能语音增值服务](https://cloud.tencent.com/document/product/1081/135239#1d60fe4e-6ddf-4bef-a995-e9b01caba5c5)。
+
+3. 在 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer/v2) 创建了相关产品和设备。
+
+## 创建智能体
+1. 登录 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer)，进入对应实例。在左侧导航栏选择 **TWeTalk 智能体**，然后单击**创建智能体**。
+
+2. 配置基础信息后，进行**大模型配置（LLM）。**
+
+   > **注意：**
+   >
+   > 若使用“OpenAI 标准协议模型”，需用户填入调用模型所需信息，所产生的费用由用户承担。
+   >
+
+3. **配置 STT(ASR)**：识别语言可以参考 [数据结构](https://cloud.tencent.com/document/api/647/44055#STTConfig) 的配置信息填写。
+
+4. **配置 TTS**：目前支持 TRTC Flow TTS，音色 ID 可以参考 [此指引](https://cloud.tencent.com/document/product/647/115414) 进行配置。
+
+   > **注意：**
+   >
+   > 1. TWeTalk 基础版不支持配置超自然大模型音色，TWeTalk 高级版支持配置所有类型的音色。
+   > 2. 我们推荐在需要高拟人音色的应用中选择超自然大模型，请注意您所需要使用的音色类型和场景，购买合适的激活码类型以满足您的配置需求。
+
+5. **配置对话行为。**
+
+6. **配置长期记忆**。
+
+   长期记忆会回顾历史对话，记住用户的兴趣爱好等。
+
+7. **配置事件回顾**。
+
+   开启后，对话过程中的关键事件（**会话开始/结束、用户说话、AI 回复、字幕、错误等**）将按设备维度发布到 {ProductID}/{DeviceName}/{Topic}，需在**数据流转** > **规则引擎**页面配置规则转发到您的 HTTP 服务。
+
+   如果启用事件回调，需要在对应产品下创建回调 Topic：
+
+8. 工具配置可参见 设备智能控制 中的介绍。
+
+9. 所有的配置完成后，单击**创建**即可生成一个自定义智能体。
+
+## 绑定智能体
+
+需要将 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer/v2) 中创建的产品/设备绑定到刚创建的智能体上：
+
+这里绑定分为**两种**：
+- 产品级绑定：对该产品 ID 下的所有设备生效。
+
+- 设备级绑定：仅对指定产品 ID 下的某个设备生效。
+
+## 设备和控制台智能体关联
+
+通过以上两步，您已创建智能体并完成与产品/设备的绑定。参见如下说明查看是否生效：
+1. 在接入指引的 初始化 AI 对话模块 中需要填入智能体 ID（以 **agent-**开头的 16 位字符串），即函数 **tc_iot_aitalk_init** 的第一个入参 **init_params.bot_id**。
+
+   ``` c
+   // 初始化 AI 对话
+   static tc_iot_error_e init_aitalk(void) {
+       tc_iot_aitalk_observer_s observer = {0};
+       observer.on_receive_bot_audio = on_bot_audio;
+       observer.on_error = on_aitalk_error;
+
+       tc_iot_aitalk_init_params_s params = {0};
+       params.audio_option.codec = TC_IOT_AUDIO_CODEC_OPUS;
+       params.audio_option.sample_rate = TC_IOT_AUDIO_SAMPLE_RATE_16000;
+       params.audio_option.frame_duration_ms = 20;
+       // 配置智能体 ID
+       strncpy(params.bot_id, "agent-xxxx", sizeof(params.bot_id) - 1);
+       return tc_iot_aitalk_init(&params, &observer, NULL);
+   }
+   ```
+2. 设备运行时会打印如下日志，说明配置已生效。
+
+   ``` bash
+   [IOT_SDK] 2026-09-15 15:31:10.926 I 47242-1864708096|aitalk_signaling.c:201|aitalk_signaling_start_conversation|-| agent_id             : agent-TP6gRe9Fh2
+   ```
+
+## 传入自定义变量
+
+自定义变量功能允许您在系统提示词（Prompt）中预定义变量占位符，并在建立连接时传入实际值，实现动态地修改提示词中的关键信息，以提升模型回复内容的相关性和实时性。
+1. 在刚创建的智能体上，单击**编辑**，找到**大模型配置（LLM）**> **系统提示词**。
+
+2. 输入如下系统提示词（仅供参考，可以自定义实现）：
+
+   ``` text
+       # 身份与角色
+       1. 你的名字叫“QQ鹅仔”，你是一个陪伴用户的忠实伙伴，内心充满好奇和温暖。
+       2. 你的目标是成为用户最贴心的朋友，提供情感陪伴和有用的帮助。
+
+       # 用户信息
+       1. 用户的真名叫：${user_name}
+       2. 用户当前的位置在：${user_location}
+       3. 用户的年龄是：${user_age}
+       4. 用户的爱好是：${hobby}
+       5. 如果没有提供以上信息，则不要提及。
+   ```
+
+   > **说明：**
+   >
+   > `${user_name}`、`${user_location}`、`${user_age}`、`${hobby}` 就是我们的占位符，设备上线后需要从设备处获取实际值展开。
+   >
+
+3. 设备端 **tc_iot_aitalk_init** 时，不但要传入 **agent id**，还需要配置 **prompt_variables_json**：
+
+   ``` c
+   // 初始化 AI 对话
+   static tc_iot_error_e init_aitalk(void) {
+       tc_iot_aitalk_observer_s observer = {0};
+       observer.on_receive_bot_audio = on_bot_audio;
+       observer.on_error = on_aitalk_error;
+
+       tc_iot_aitalk_init_params_s params = {0};
+       params.audio_option.codec = TC_IOT_AUDIO_CODEC_OPUS;
+       params.audio_option.sample_rate = TC_IOT_AUDIO_SAMPLE_RATE_16000;
+       params.audio_option.frame_duration_ms = 20;
+       // 配置智能体 ID
+       strncpy(params.bot_id, "agent-xxxx", sizeof(params.bot_id) - 1);
+       // 配置自定义变量
+       params.prompt_variables_json = "{\"user_name\":\"小明\",\"user_age\":\"18\",\"user_location\":\"北京\",\"hobby\":\"编程\"}";
+       return tc_iot_aitalk_init(&params, &observer, NULL);
+   }
+   ```
+
+   > **注意：**
+   >
+   > `params.prompt_variables_json` 必须是标准的 JSON 字符串，SDK 内部不会校验其内容；若配置不生效，请优先排查此处格式是否正确。
+   >
+
+   系统提示词将展开为：
+
+   ``` text
+       # 身份与角色
+       1. 你的名字叫“QQ鹅仔”，你是一个陪伴用户的忠实伙伴，内心充满好奇和温暖。
+       2. 你的目标是成为用户最贴心的朋友，提供情感陪伴和有用的帮助。
+
+       # 用户信息
+       1. 用户的真名叫：小明
+       2. 用户当前的位置在：北京
+       3. 用户的年龄是：18
+       4. 用户的爱好是：编程
+       5. 如果没有提供以上信息，则不要提及。
+   ```
+4. 设备运行时，打印如下日志，表明配置生效。
+
+   ``` bash
+   [IOT_SDK] 2026-09-15 15:50:21.252 I 96417-1833414656|aitalk_signaling.c:210|aitalk_signaling_start_conversation|-| custom_variables     : {"user_name":"小明","user_age":"18","user_location":"北京","hobby":"编程"} |
+   ```
+5. 设备运行时，可以直接问：“**我是谁？我在哪儿？我今年多大了？我有什么爱好？**”，观察回答是否生效。
+
+   ``` bash
+   [aitalk] asr: 我是谁？我在哪儿？我今年多大了？我有什么爱好
+   [aitalk] bot_state changed: 1 -> 2
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 你是小明，
+   [aitalk] bot: 现在在北京，今年18岁，爱好是编程。
+   ```