TRTC AI 电商客服 Skill

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

触发条件

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

• "AI customer service" "smart customer support" "voice bot" "voice agent" "chat bot"
• "e-commerce support" "online store assistant" "shopping assistant" "after-sales service"
• "build a customer service app" "customer service demo" "support chatbot"
• "real-time voice chat" "voice-to-text conversation" "ASR + LLM + TTS"
• "TRTC conversation" "ConversationAI" "TRTC + AI" "TRTC + LLM"
• "digital human" "virtual agent" "avatar customer service"
• "StartAIConversation" "StopAIConversation" "ControlAIConversation"
• "order inquiry" "returns and exchanges" "shipping tracking" "product consultation"
• "AI 客服" "智能客服" "语音客服" "电商客服" "商城客服" "售后客服"
• "做一个客服系统" "搭建客服" "客服机器人" "数字人客服"
• "订单查询" "退换货" "物流追踪" "商品咨询"

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

架构总览

浏览器 (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 \x3C项目目录> [--name \x3C商城名称>] [--name-en \x3CEnglish name>] [--lang \x3Czh|en|both>]

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

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

Step 2: 配置密钥

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

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

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

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

Step 3: 启动验证

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

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

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

Step 4: 定制（可选）

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

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

Step 1: 了解现有架构

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

Step 2: 按需提供指导

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

Step 3: 验证集成

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

常见问题排查

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

核心设计模式

详见 references/architecture.md

后端 API

统一通过 POST /action + Action 请求头区分：

技术栈

安全注意事项

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