Install
openclaw skills install trtc-ai-customer-serviceTRTC AI Customer Service
Build an AI e-commerce customer service Web app with TRTC ConversationAI — real-time voice/text dual-mode, trilingual (Chinese/English/Cantonese), digital avatar optional. Covers order inquiry, returns, shipping tracking, and promotions. 基于腾讯云 TRTC Conversational AI 快速构建 AI 电商客服 Web 应用 — 实时语音/文字双模、中英粤三语、数字人可选。覆盖订单查询、退换货、物流追踪、商品咨询等场景。
TRTC AI 电商客服 Skill
本 Skill 指导你基于腾讯云 TRTC Conversational AI 能力，快速构建 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 中转
| 平面 | 通道 | 内容 |
|---|---|---|
| 媒体面 | WebRTC 音频流 | 用户麦克风 ↔ TRTC 房间 ↔ AI Bot |
| 控制面 | HTTP /action | 前端 → Flask → TRTC OpenAPI |
| 数据面 | TRTC 自定义消息 | 字幕(10000) / AI 状态(10001) / 文字输入(20000) / 打断(20001) |
后端完全不调用 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 配置 → 根据所选 LLM 服务商填入：
检查点：确认用户看到 ✓ 所有密钥已配置完成！。如果有跳过项，提醒手动编辑 env.yaml。
提示用户：以上为最小必填项，启动成功后还有丰富的可定制选项（角色定制、商城名称、欢迎语、TTS 音色、关键词等），详见 Step 4。
Step 3: 启动验证
启动脚本会自动创建虚拟环境、安装依赖、启动服务。
验证标准（告知用户逐项确认）：
- 终端显示
🚀 启动 TRTC AI 智能客服+ 访问地址（公网服务器会自动检测公网 IP 并启用 HTTPS，显示https://<公网IP>:8080；本地开发则显示http://localhost:8080） - 浏览器打开页面 → 能看到客服头像选择界面
- 选择客服 → 点击"开始对话" → 听到 AI 播报欢迎语
- 说话或打字 → AI 能正常回复
Step 4: 定制化（可选）
启动成功后，主动告知用户以下所有可定制项，引导按需修改：
| 定制项 | 修改位置 | 说明 |
|---|---|---|
| AI 客服角色 | 交互式引导 [4/4]（删除 env.yaml 后重新运行 ./start.sh），或直接编辑 env.yaml → SystemPrompt / SystemPromptYue / SystemPromptEn | 预设品类 + 语气快速定制（见下方枚举表），也可手动编辑三语 SystemPrompt 做精细调整 |
| 商城名称/品牌 | scaffold 的 --name / --name-en 参数 | 一键替换全链路品牌文案（三语 SystemPrompt、欢迎语、告别语、前端 UI） |
| 欢迎语 / 告别语 | env.yaml → WelcomeMessage / FarewellMessage（.zh / .yue / .en） | AI 进房首条播报 / 关键词触发结束时播报 |
| LLM 模型 | env.yaml → LLMConfig.Model / APIUrl / APIKey | LLM 配置指南：国际站 | 中国站 |
| TTS 音色 | config_loader.py → TTS_VOICE_MAP | TTS 音色配置指南：国际站 | 中国站 |
| 商品/订单数据 | static/mock-orders.json，或参考 references/frontend-guide.md 对接真实 API | JSON 格式含三语名称和价格，可替换为真实订单系统 |
| 数字人 | env.yaml → AvatarConfig 三项 | 三项全填启用数字人视频模式，否则纯语音 |
| 部署方式 | 自动检测公网 IP 启用 HTTPS；生产环境用 Gunicorn + Nginx + 正式证书 | WebRTC 要求 HTTPS；生产还需添加 /action 接口鉴权 |
AI 客服角色预设枚举值（start.sh 交互式引导 [4/4]）：
商城品类（影响 AI 的专业知识方向）：
| 选项 | 品类 | AI 擅长方向 |
|---|---|---|
| 1 | 综合电商（默认） | 通用电商场景，不修改 SystemPrompt |
| 2 | 数码产品 | 参数对比、兼容性问题、保修政策、使用教程 |
| 3 | 服装鞋帽 | 尺码推荐、面料材质、搭配建议、洗涤保养、退换尺码 |
| 4 | 食品生鲜 | 保质期、储存方式、配送时效、食材产地、过敏原信息 |
| 5 | 家居百货 | 商品尺寸规格、安装方式、材质说明、配送安装服务 |
客服语气风格（影响 AI 的表达方式）：
| 选项 | 风格 | 效果 |
|---|---|---|
| 1 | 亲切自然（默认） | 像朋友聊天，已内置于默认 SystemPrompt |
| 2 | 专业严谨 | 用词准确规范，适合高端品牌/B2B |
| 3 | 活泼可爱 | 轻松表达方式，适合年轻用户群体 |
选择后自动注入三语 SystemPrompt（中文/粤语/英文同步）。如需更精细定制，直接编辑
env.yaml中的 SystemPrompt 即可。
路径 B：为现有项目集成 TRTC AI 对话
Step 1: 了解现有架构
询问并确认：
- 后端语言和框架（Python/Node/Go/Java？）
- 前端技术栈（React/Vue/原生 JS？已有 TRTC SDK？）
- 集成范围：仅后端 API？还是含前端 UI？
Step 2: 按需读取参考文档并输出代码
根据用户技术栈，读取对应文档并直接输出可集成的代码片段：
| 需求 | 读取文档 | 输出内容 |
|---|---|---|
| 后端 API | references/architecture.md | 用户语言的 5 个 Action 处理器代码（join / Start / Stop / Farewell / Transfer） |
| 配置体系 | references/config-guide.md | 生成 env.yaml 模板 + 配置加载代码 |
| 前端对话 UI | references/frontend-guide.md | TRTC SDK 进房 + 消息监听 + 字幕渲染代码 |
关键：如果用户不是 Python 技术栈，需要将参考文档中的 Python 逻辑翻译为用户的语言（如 Node.js / Go / Java），核心逻辑不变。
Step 3: 验证集成
引导用户完成最小可用流程并逐步确认：
- 后端
/action接口能正常响应（curl -X POST /action -H "Action: join"返回 UserSig） - 前端成功进入 TRTC 房间（控制台无报错）
StartAIConversation调用成功返回 TaskId- 用户说话 → 听到 AI 回复（完整链路跑通）
如果卡在某一步，参照下方 FAQ 表逐条排查。
常见问题排查
当用户遇到问题时，按以下清单排查：
| 现象 | 原因 | 解决方案 |
|---|---|---|
| scaffold.py 报错退出 | Python 版本或参数错误 | 确认 Python 3.8+；检查输出目录路径是否合法 |
start.sh 报 Python 版本不够 | Python < 3.8 | 安装 Python 3.8+ |
| venv 创建失败 | 缺少 python3-venv 包 | Ubuntu/Debian: sudo apt install python3-venv；macOS 自带 |
| 依赖安装失败 | 网络问题 | start.sh 会自动 fallback 官方源；或手动 pip install -r requirements.txt |
env.yaml 解析报错 | YAML 缩进或格式错误 | 用在线 YAML 校验器检查；常见：冒号后缺空格、中文引号 |
| 页面打开空白 | 静态文件缺失 | 确认 static/app.js 和 templates/customer_service.html 存在 |
| 点"开始对话"无反应 | 密钥未填或填错 | 检查 env.yaml 中 SDKAPPID 不为 0、SECRET_ID/KEY 正确 |
| 点"开始对话"提示进房失败 | TRTC 进房参数异常 | 检查 SDKAPPID 是否正确填写；UserSig 是否校验失败（核对 TRTC.SECRET） |
| 说话无任何响应（语音不可用） | 浏览器麦克风权限未授予或设备异常 | 检查浏览器地址栏麦克风权限；测试系统设备：录音机能否录到声音 |
| 仅显示本地字幕，AI 无回应 | LLM 服务异常 | 检查 LLMConfig.APIKey / APIUrl / Model 是否正确；确认 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 访问无声音或麦克风不可用 | WebRTC 安全策略要求 HTTPS | 运行 ./start.sh --https 自动生成自签证书并启用 HTTPS；首次访问浏览器点击"高级→继续前往" |
| 公网 IP 访问页面打不开 | 防火墙未放行端口 | 确认服务器防火墙/安全组已放行 8080 端口（TCP） |
| 端口 8080 被占用 | 其他进程占用 | start.sh 会自动检测并询问是否终止 |
| 浏览器控制台报 CORS 错误 | 前后端不同源 | 确保前端页面由 Flask 提供（同源）；不要用 file:// 打开 HTML |
速查参考
后端 API（POST /action + Action 请求头）
| Action | 职责 |
|---|---|
join | 签发 UserSig（用户/机器人/数字人），下发关键词/告别语/数字人开关 |
StartAIConversation | 组装参数调用 TRTC OpenAPI 启动 AI 对话 |
StopAIConversation | 兜底停止（正常走 FarewellAndStop） |
FarewellAndStop | 推送告别语 + StopAfterPlay 一站式结束 |
TransferAndStop | 推送转接提示语 + StopAfterPlay 一站式结束 |
核心设计模式（详见 references/architecture.md）
| 模式 | 要点 |
|---|---|
| StopAfterPlay 一站式结束 | ControlAIConversation + StopAfterPlay=true，TTS 播完自动停止 |
| 文字输入跳过 ASR | type: 20000 自定义消息直送 LLM |
| 中英文词边界匹配 | 中文用非中文字符边界，英文用 \b |
| 增量/累积自适应字幕 | 自动检测 TRTC 下发模式 |
| 机器人退房 + AI 状态双保险 | REMOTE_USER_LEAVE + state=5 |
| 数字人可选降级 | AvatarConfig 三项齐全启用，否则纯语音 |
技术栈
Python 3.8+ · Flask · tencentcloud-sdk-python · 原生 JS · TRTC Web SDK v5 · YAML（envyaml）
安全
env.yaml含密钥，加入.gitignore，切勿提交- UserSig 服务端签发，密钥不暴露给前端
- 生产环境添加
/action接口鉴权 - 非 localhost 部署必须 HTTPS（WebRTC 安全策略）