TRTC AI 电商客服 Skill

本 Skill 指导你基于腾讯云 TRTC Conversational AI 能力，快速构建 AI 电商客服 Web 应用。

场景预置了订单查询、退换货处理、商品咨询、物流追踪、优惠活动等电商业务模块。

触发条件

当用户表达构建/搭建/集成意图时使用此 Skill：

• "做一个 AI 客服" "搭建电商客服" "帮我做个智能客服系统" "语音客服 demo"
• "build an AI customer service" "e-commerce customer service app"
• "TRTC ConversationAI" "TRTC + AI 客服" "TRTC e-commerce support"
• "StartAIConversation" "StopAIConversation" "ControlAIConversation"（TRTC API 名称）
• "数字人客服" "avatar customer service"
• "实时语音 AI 对话" "ASR + LLM + TTS 客服"

不应触发的场景：

• 用户仅在讨论客服概念，没有构建/开发意图
• 用户询问通用 chat bot 方案，不需要语音能力或电商场景
• 关键词如 "voice bot" "chat bot" 单独出现且无构建上下文

架构总览

浏览器 (TRTC Web SDK v5)
     ↕ 音频 (WebRTC) + 自定义消息 (字幕/状态/文字输入)
TRTC Room
     ↕ 内置 ASR → LLM → TTS → 推回房间
TRTC AI Bot (云端)
     ↕ OpenAPI (TC3-HMAC-SHA256)
Flask 后端 (app.py)  —— 仅 UserSig 签发 + OpenAPI 中转

后端完全不调用 LLM——LLM 由 TRTC 云端 AI Bot 内部调用，后端只负责签发 UserSig 和中转 OpenAPI 请求。

工作流程

根据用户需求选择合适的路径。

路径 A：从零创建新项目（推荐）

Step 1: 生成项目

运行脚手架脚本：

python {baseDir}/scripts/scaffold.py <项目目录> [--name <商城名称>] [--name-en <English name>]

• {baseDir}：本 Skill 所在目录的绝对路径（由 Agent 自动替换为实际路径）
• --name：商城名称（默认"云尚商城"），用于中文/粤语的 SystemPrompt、欢迎语、告别语、前端 UI
• --name-en：英文商城名称（默认自动推导：中文名时为"CloudShop Mall"，英文名时与 --name 相同），用于英文 SystemPrompt、英文欢迎语/告别语
• 默认支持中文/英文/粤语三语，无需手动指定语言
• 脚本自动生成全部文件：后端 + 前端 + 头像 + 鉴权库 + 启动脚本，无需手动复制任何文件

检查点：确认用户看到 ✅ 电商客服项目已生成到: xxx 和完整文件列表，再继续。

Step 2: 配置密钥

引导用户运行启动脚本（根据操作系统自动选择：macOS/Linux 用 ./start.sh，Windows 用 start.bat），首次运行会进入交互式引导：

• [0/4] 选择部署区域（默认 intl 国际站，可选 cn 中国站）— 后续步骤会根据所选区域展示对应的控制台链接
• [1/4] 腾讯云 API 密钥 → 脚本会展示对应区域的 CAM 控制台 链接
• [2/4] TRTC 应用凭据 → 脚本会展示对应区域的 TRTC 控制台 链接
• [3/4] LLM 配置 → 建议优先使用 TokenHub（腾讯云统一 LLM 网关，开箱即用）：
• LLMConfig.LLMType：openai（固定）
• LLMConfig.Model：deepseek-v4-flash（推荐）
• LLMConfig.APIUrl：
• 国际站：https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions
• 中国站：https://tokenhub.tencentmaas.com/v1/chat/completions
• LLMConfig.APIKey：在 TokenHub 控制台获取（国际站 | 中国站）
• 也支持其他兼容 OpenAI 协议的 LLM，参考配置指南：国际站 | 中国站

检查点：确认用户看到 ✓ 所有密钥已配置完成！。如果有跳过项，提醒手动编辑 env.yaml。

> 提示用户：以上为最小必填项，启动成功后还有丰富的可定制选项（角色定制、商城名称、欢迎语、TTS 音色、关键词等），详见 Step 4。

Step 3: 启动验证

启动脚本会自动创建虚拟环境、安装依赖、启动服务。

验证标准（告知用户逐项确认）：

1. 终端显示 🚀 启动 TRTC AI 智能客服 + 访问地址（公网服务器会自动检测公网 IP 并启用 HTTPS，显示 https://<公网IP>:8080；本地开发则显示 http://localhost:8080）
2. 浏览器打开页面 → 能看到客服头像选择界面
3. 选择客服 → 点击"开始对话" → 听到 AI 播报欢迎语
4. 说话或打字 → AI 能正常回复

Step 4: 定制化（可选）

启动成功后，主动告知用户以下所有可定制项，引导按需修改：

AI 客服角色预设枚举值（start.sh 交互式引导 [4/4]）：

商城品类（影响 AI 的专业知识方向）：

客服语气风格（影响 AI 的表达方式）：

> 选择后自动注入三语 SystemPrompt（中文/粤语/英文同步）。如需更精细定制，直接编辑 env.yaml 中的 SystemPrompt 即可。

路径 B：为现有项目集成 TRTC AI 对话

Step 1: 了解现有架构

询问并确认：

• 后端语言和框架（Python/Node/Go/Java？）
• 前端技术栈（React/Vue/原生 JS？已有 TRTC SDK？）
• 集成范围：仅后端 API？还是含前端 UI？

Step 2: 按需读取参考文档并输出代码

根据用户技术栈，读取对应文档并直接输出可集成的代码片段：

关键：如果用户不是 Python 技术栈，需要将参考文档中的 Python 逻辑翻译为用户的语言（如 Node.js / Go / Java），核心逻辑不变。

Step 3: 验证集成

引导用户完成最小可用流程并逐步确认：

1. 后端 /action 接口能正常响应（curl -X POST /action -H "Action: join" 返回 UserSig）
2. 前端成功进入 TRTC 房间（控制台无报错）
3. StartAIConversation 调用成功返回 TaskId
4. 用户说话 → 听到 AI 回复（完整链路跑通）

如果卡在某一步，参照下方 FAQ 表逐条排查。

常见问题排查

当用户遇到问题时，按以下清单排查：

速查参考

后端 API（POST /action + Action 请求头）

核心设计模式（详见 references/architecture.md）

技术栈

Python 3.8+ · Flask · tencentcloud-sdk-python · 原生 JS · TRTC Web SDK v5 · YAML（envyaml）

安全

• env.yaml 含密钥，加入 .gitignore，切勿提交
• UserSig 服务端签发，密钥不暴露给前端
• 生产环境添加 /action 接口鉴权
• 非 localhost 部署必须 HTTPS（WebRTC 安全策略）