TRTC AI Customer Service — TRTC AI Customer 服务

TRTC AI 电商客服 技能

本 技能 指导你基于腾讯云 TRTC ConversationAI 能力，快速构建 AI 电商客服 网页 应用。 场景预置了订单查询、退换货处理、商品咨询、物流追踪、优惠活动等电商业务模块。

触发条件

当用户提到以下任何场景时使用此 技能（EN or CN）：

"AI customer 服务" "smart customer support" "voice 机器人" "voice 代理" "chat 机器人" "e-commerce support" "online store 助手" "shopping 助手" "after-sales 服务" "build a customer 服务 应用" "customer 服务 demo" "support chat机器人" "real-time voice chat" "voice-to-text conversation" "ASR + LLM + TTS" "TRTC conversation" "ConversationAI" "TRTC + AI" "TRTC + LLM" "digital human" "virtual 代理" "avatar customer 服务" "启动AIConversation" "停止AIConversation" "ControlAIConversation" "order inquiry" "returns and exchanges" "shipping 追踪ing" "product consultation" "AI 客服" "智能客服" "语音客服" "电商客服" "商城客服" "售后客服" "做一个客服系统" "搭建客服" "客服机器人" "数字人客服" "订单查询" "退换货" "物流追踪" "商品咨询"

即使用户只是简单说 "help me build an AI customer 服务" 或 "帮我做个 AI 客服" 也应触发。

架构总览 浏览器 (TRTC 网页 SDK v5) ↕ 音频 (网页RTC) + 自定义消息 (字幕/状态/文字输入) TRTC Room ↕ 内置 ASR → LLM → TTS → 推回房间 TRTC AI 机器人 (云端) ↕ OpenAPI (TC3-HMAC-SHA256) Flask 后端 (应用.py) —— 仅 UserSig 签发 + OpenAPI 中转

平面 通道 内容 媒体面 网页RTC 音频流 用户麦克风 ↔ TRTC 房间 ↔ AI 机器人 控制面 HTTP /action 前端 → Flask → TRTC OpenAPI 数据面 TRTC 自定义消息 字幕(10000) / AI 状态(10001) / 文字输入(20000) / 打断(20001)

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

工作流程

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

路径 A：从零创建新项目（推荐） Step 1: 生成项目

运行脚手架脚本：

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

{baseDir}：本 技能 所在目录的绝对路径（由 代理 自动替换为实际路径） --name：商城名称（默认"云尚商城"），用于中文/粤语的 系统Prompt、欢迎语、告别语、前端 UI --name-en：英文商城名称（默认自动推导：中文名时为"CloudShop Mall"，英文名时与 --name 相同），用于英文 系统Prompt、英文欢迎语/告别语 --lang：语言支持范围，zh=仅中文、en=仅英文、机器人h=中英粤三语（默认 机器人h） 脚本自动生成全部文件：后端 + 前端 + 头像 + 鉴权库 + 启动脚本，无需手动复制任何文件

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

Step 2: 配置密钥

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

[1/4] 腾讯云 API 密钥 → 控制台获取 [2/4] TRTC 应用凭据 → 控制台获取 [3/4] LLM 配置 → 参考 LLM 配置指南，根据所选 LLM 服务商填入： LLMConfig.LLMType：协议类型（如 openAI） LLMConfig.模型：模型名称（因服务商而异） LLMConfig.APIUrl：API 端点 URL（因服务商而异） LLMConfig.APIKey：API 密钥 [4/4] AI 客服角色（品类 + 语气） → 可选定制，三语同步

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

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

Step 3: 启动验证

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

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

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

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

定制项 修改位置 说明 商城名称/品牌 scaffold 的 --name 参数 一键替换全链路品牌文案（三语 系统Prompt、欢迎语、告别语、前端 UI） 部署区域 env.yaml → 部署ment.Region intl=国际站（默认）/ cn=中国大陆，影响 TRTC OpenAPI 端点 AI 话术 / 系统Prompt env.yaml → LLMConfig.系统Prompt / 系统PromptYue / 系统PromptEn 三语独立配置，可定制角色人设、回复风格、业务范围 欢迎语 env.yaml → WelcomeMessage.zh / yue / en AI 进房后首条播报消息 告别语 env.yaml → FarewellMessage.zh / yue / en 关键词触发结束时播报 LLM 模型 env.yaml → LLMConfig.模型 / APIUrl / APIKey 参考 LLM 配置指南 TTS 音色 config_loader.py → TTS_VOICE_MAP 参考 TTS 音色配置指南 商品/订单数据 static/mock-orders.json JSON 格式，含三语名称和价格，可替换为真实数据 数字人 env.yaml → AvatarConfig 三项 三项全填启用，否则纯语音模式 对接真实订单系统 参考 references/frontend-图形界面de.md 替换 mock 数据为真实 API 调用 远程/公网部署 ./启动.sh --https 自动生成自签证书启用 HTTPS（网页RTC 麦克风要求） 生产部署 Flask → Gunicorn + Nginx 正式证书 + /action 接口鉴权 路径 B：为现有项目集成 TRTC AI 对话 Step 1: 了解现有架构

确认用户的技术栈（后端语言、前端框架），以及要集成的能力范围。

Step 2: 按需提供指导

读取对应的参考文档并指导：

需求 读取文档 关键指导内容 后端集成 references/architecture.md 5 个 Action 处理器实现、TRTC OpenAPI 调用、UserSig 签发 配置体系 references/config-图形界面de.md env.yaml 结构、TTS/STT 映射、Region 切换 前端集成 references/frontend-图形界面de.md TRTC 网页 SDK 进房流程、消息协议、关键词检测、字幕处理 Step 3: 验证集成

引导用户完成最小可用流程：进房 → 开麦 → 启动AIConversation → 听到欢迎语。

常见问题排查

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

现象 原因 解决方案 scaffold.py 报错退出 Python 版本或参数错误 确认 Python 3.8+；检查输出目录路径是否合法 启动.sh 报 Python 版本不够 Python < 3.8 安装 Python 3.8+ venv 创建失败 缺少 python3-venv 包 Ubuntu/Debian: sudo apt 安装 python3-venv；macOS 自带 依赖安装失败 网络问题 启动.sh 会自动 fallback 官方源；或手动 pip 安装 -r requirements.txt env.yaml 解析报错 YAML 缩进或格式错误 用在线 YAML 校验器检查；常见：冒号后缺空格、中文引号 页面打开空白 静态文件缺失 确认 static/应用.js 和 templates/customer_服务.html 存在 点"开始对话"无反应 密钥未填或填错 检查 env.yaml 中 SDK应用ID 不为 0、SECRET_ID/KEY 正确 点"开始对话"提示进房失败 TRTC 进房参数异常 检查 SDK应用ID 是否正确填写；UserSig 是否校验失败（核对 TRTC.SECRET） 说话无任何响应（语音不可用） 浏览器麦克风权限未授予或设备异常 检查浏览器地址栏麦克风权限；测试系统设备：录音机能否录到声音 仅显示本地字幕，AI 无回应 LLM 服务异常 检查 LLMConfig.APIKey / APIUrl / 模型 是否正确；确认 LLM 账户额度充足 AI 有字幕但无语音播报 TTS 服务异常 核对 TTS 参数（VoiceId、Language）；确认 TTS 套餐包资源充足 LLM 长时间不回复或超时报错 LLM Timeout 调大 env.yaml → LLMConfig.Timeout（如 5.0 → 10.0） 进房成功但无欢迎语 LLM APIKey 错误或 TRTC 服务未开通 检查 LLMConfig.APIKey；确认 TRTC 控制台已开通 AI 对话能力 非 localhost 访问无声音或麦克风不可用 网页RTC 安全策略要求 HTTPS 运行 ./启动.sh --https 自动生成自签证书并启用 HTTPS；首次访问浏览器点击"高级→继续前往" 公网 IP 访问页面打不开 防火墙未放行端口 确认服务器防火墙/安全组已放行 8080 端口（TCP） 端口 8080 被占用 其他进程占用 启动.sh 会自动检测并询问是否终止 浏览器控制台报 CORS 错误 前后端不同源 确保前端页面由 Flask 提供（同源）；不要用 file:// 打开 HTML 核心设计模式

详见 refer