@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

package/skills/trtc-ai-service/README.md

@@ -0,0 +1,195 @@
+# TRTC AI Customer Service Skill
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+> A zero-code AI customer service builder. Just say a sentence in the chat window and the AI will guide you step by step to get your customer service system up and running — no terminal, no scripts, no coding required.
+
+## What is this?
+
+Building an "AI customer service agent with TRTC Conversational AI" packaged into a plug-and-play Skill:
+
+```
+You (in your IDE's AI chat window):
+  "Build me an AI customer service agent with TRTC"
+
+AI (does everything automatically):
+  1. Checks your runtime environment
+  2. Lets you choose a setup mode (Quick Experience / Integrate into My System)
+  3. Guides you through configuring 3 keys (cloud service credentials)
+  4. Installs dependencies and assembles the customer service capabilities
+  5. Starts the service and gives you a browser URL to see it in action
+
+You never open a terminal or run a script manually.
+```
+
+## Two ways to start
+
+> The core capability of this Skill is **TRTC Conversational AI (voice agent)**.
+
+| Mode | Who it's for | What you get | What you need to do |
+|------|-------------|-------------|---------------------|
+| **Quick Experience** | First-timers who want to see what it looks like | A complete voice agent web UI + ticket management dashboard | Configure 3 keys |
+| **Integrate into My System** | Users who already have a website or app and want to embed the AI agent's "brain" | Backend API endpoints + interface specs + sample code (no UI generated) | Configure 3 keys + choose capabilities and interaction modes |
+
+**No matter which one you choose, the AI will walk you through every step** — zero programming experience needed.
+
+## The only entry point
+
+[`SKILL.md`](./SKILL.md) — Read and executed by your Coding Agent (CodeBuddy / Cursor / Claude Code).
+
+> **Install anywhere**: This Skill can live in a project subdirectory, `.agents/skills/`, `.codebuddy/skills/`, or anywhere else —
+> it does **not** need to be at the workspace root. Scripts are self-locating; the Agent just needs to use absolute paths.
+
+### Installation
+
+#### Codex CLI
+
+**User-level** (recommended — available across all projects):
+```bash
+/skills install https://github.com/Burgerham4R/ai-customer-service-skill
+```
+
+**Project-level** (only available in the current project):
+```bash
+# The skill will be installed to ./.codex/skills/ (Cmd+Shift+. to show hidden folders in Finder)
+/skills install --project https://github.com/Burgerham4R/ai-customer-service-skill
+```
+
+#### Claude Code CLI
+
+**User-level** (recommended — available across all projects):
+```bash
+mkdir -p ~/.claude/skills
+git clone https://github.com/Burgerham4R/ai-customer-service-skill.git ~/.claude/skills/ai-customer-service-skill
+```
+
+**Project-level** (only available in the current project):
+```bash
+mkdir -p ./.claude/skills
+git clone https://github.com/Burgerham4R/ai-customer-service-skill.git ./.claude/skills/ai-customer-service-skill
+```
+
+#### Other agents (CodeBuddy / Cursor / etc.)
+
+Clone to any location and point your agent to `SKILL.md`:
+```bash
+git clone https://github.com/Burgerham4R/ai-customer-service-skill.git
+# Then tell your agent:
+# "Load the Skill from /path/to/ai-service-skill/SKILL.md"
+```
+
+> **After installation, restart your CLI session** to ensure the Skill is properly registered and loaded.
+
+### Trigger keywords
+
+- "AI customer service" / "build customer service" / "customer service bot"
+- "TRTC + customer service" / "voice agent + customer service"
+- "Build me an AI customer service agent with TRTC"
+
+## What are the 3 keys?
+
+To get the customer service agent running, you need 3 cloud service credentials. Don't worry — they're just 3 strings you copy-paste from the corresponding websites.
+
+> **Tencent RTC (trtc.io)** is Tencent Cloud's international Real-Time Communication brand. The TRTC Conversational AI service runs on Tencent Cloud infrastructure — your TRTC account and Tencent Cloud account are linked through a unified login system. When you get your API Key, the system will automatically sync your login session.
+
+| Key | Purpose | Where to find it |
+|-----|---------|-----------------|
+| Key 1: TRTC Application Credentials | Lets the agent make calls and do voice chat | https://console.trtc.io/ (register & create a Conversational AI app) |
+| Key 2: Tencent Cloud API Key | Proves you have permission to use Tencent Cloud voice & calling services (login syncs with your TRTC account) | https://console.tencentcloud.com/cam/capi |
+| Key 3: LLM API Key | Lets the agent "think" — understand queries and respond | Your registered AI service website (e.g. OpenAI, DeepSeek, etc.) |
+
+> The AI will tell you exactly how to get each key step by step. Your key info is only used for this configuration session — the system does not log or leak it.
+
+## What capabilities does the agent have?
+
+| Capability | Description | Quick Experience | Integration |
+|------------|-------------|:---:|:---:|
+| Conversation | Voice + text two-way communication | ✅ Auto-assembled | ✅ Default included |
+| Knowledge Base | Upload docs, agent auto-retrieves and answers FAQ | ✅ Simulated demo | 🔘 Optional |
+| Human Handoff | Complex issues auto-escalate to a human agent | ✅ Simulated demo | 🔘 Optional |
+| Tool Calling | Agent can proactively query data from your system | ❌ Not supported | 🔘 Optional |
+| Session Summary | Auto-generates a summary after each conversation | ✅ Simulated demo | 🔘 Optional |
+
+> "Simulated demo" means: the UI and workflow are complete, but uses demo data without connecting to a real business system. For real integration, choose "Integrate into My System".
+
+## Communication modes (optional for integration)
+
+| Mode | Description | Best for |
+|------|-------------|---------|
+| Text-only IM | Agent replies via text chat | Web chat widgets, in-app messaging |
+| Text + TTS | Agent types replies + reads them aloud | Smart speakers, voice assistants |
+| Omni-modal | Text, voice, and video all supported | Advanced customer service scenarios |
+| Voice-only Call | Agent communicates only via phone | Call centers, hotlines |
+
+## Advanced: Customize TRTC Conversational AI
+
+If you want to fine-tune the AI agent's voice behavior or change the underlying models, refer to the official TRTC Conversational AI documentation:
+
+### Adjust voice parameters (speed / pitch / timbre)
+
+Both STT (speech-to-text) and TTS (text-to-speech) are powered by Tencent's in-house engines. You can adjust voice parameters via the following documentation:
+
+| Stage | Documentation |
+|-------|--------------|
+| STT (Speech-to-Text) | [STT configuration parameters](https://trtc.io/document/69592?product=conversationalai) |
+| TTS (Text-to-Speech) | [TTS configuration parameters](https://trtc.io/document/68340?product=conversationalai) |
+
+### Switch STT / LLM / TTS models
+
+To change the underlying STT, LLM, or TTS models, check the model overview for each pipeline stage and follow the integration guide:
+
+| Stage | Documentation |
+|-------|--------------|
+| STT (Speech-to-Text) | [STT Model Overview](https://trtc.io/document/69592?product=conversationalai) |
+| LLM (Language Model) | [LLM Model Overview](https://trtc.io/document/68338?product=conversationalai) |
+| TTS (Text-to-Speech) | [TTS Model Overview](https://trtc.io/document/68340?product=conversationalai) |
+
+### Full documentation
+
+For any other configuration needs, start from the Conversational AI overview and navigate from there:
+
+- [TRTC Conversational AI Overview](https://trtc.io/document/conversational-ai-overview?product=conversationalai)
+
+## Directory structure
+
+```
+ai-service-skill/
+├── SKILL.md                       # ★ The only entry point (triggered by Coding Agent)
+├── start.sh                       # Bootstrap script (auto-install deps + start service)
+│
+├── scripts/                       # AI-invoked tool scripts
+│   ├── verify-credentials.py      # 3-key verification
+│   ├── setup-credentials.py       # Interactive developer setup
+│   ├── add-capability.py          # Capability assembly
+│   ├── contract-adapt.py          # Interface contract adaptation
+│   └── lib/                       # Shared modules
+│
+├── capabilities/
+│   ├── conversation-core/         # Generic Voice Agent skeleton
+│   ├── knowledge-base/            # FAQ knowledge base retrieval
+│   ├── tool-calling/              # Tool calling
+│   ├── human-handoff/             # Human handoff + ticket management
+│   ├── session-summary/           # Session summaries
+│   └── digital-human/             # Digital human (placeholder)
+│
+├── scenarios/
+│   ├── customer-service/          # Path A: Demo UI
+│   └── custom-builder/            # Path B: Capability selection wizard
+│
+├── auto_adapters/                 # Tech stack adapters
+└── tests/                         # Test suite
+```
+
+## FAQ
+
+| Issue | Solution |
+|-------|----------|
+| Key verification failed | Go back to the key configuration step and double-check each key value |
+| Port 3000 is in use | Use a different port (e.g. `--port 8080`) or stop the program occupying the port |
+| Python version too low | Download and install Python 3.9+ from python.org |
+| Browser shows blank page after startup | Hard refresh: `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows) |
+| Want to connect a real business system | Re-run the workflow and choose "Integrate into My System" |
+
+---
+
+> **One last thing**: This Skill is designed so that anyone — even with zero coding experience — can get an AI customer service agent up and running. If you run into any issues along the way, just tell the AI in the chat window and it'll help you resolve them.

package/skills/trtc-ai-service/README.zh-CN.md

@@ -0,0 +1,193 @@
+# TRTC AI 客服 Skill
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+> 零代码 AI 客服搭建器。只需在聊天窗口中说一句话，AI 会一步步引导你完成客服系统的搭建——无需终端、无需脚本、无需编程。
+
+## 这是什么？
+
+将"基于 TRTC Conversational AI 的 AI 客服智能体"打包成一个即插即用的 Skill：
+
+```
+你（在 IDE 的 AI 聊天窗口中说）：
+  "帮我用 TRTC 搭建一个 AI 客服"
+
+AI（自动完成所有操作）：
+  1. 检查你的运行环境
+  2. 让你选择搭建模式（快速体验 / 集成到我的系统）
+  3. 引导你完成 3 个密钥的配置（云服务凭证）
+  4. 安装依赖并组装客服能力
+  5. 启动服务并给你一个浏览器地址，直接查看效果
+
+你完全不需要打开终端或手动执行任何脚本。
+```
+
+## 两种方式开始
+
+> 本 Skill 的核心能力是 **TRTC Conversational AI（语音智能体）**。
+
+| 模式 | 适合谁 | 能得到什么 | 需要做什么 |
+|------|--------|-----------|-----------|
+| **快速体验** | 想先看看效果的新用户 | 一个完整的语音智能体 Web 界面 + 工单管理后台 | 配置 3 个密钥 |
+| **集成到我的系统** | 已有网站或应用、想嵌入 AI 智能体"大脑"的用户 | 后端 API 接口 + 接口规范 + 示例代码（不生成 UI） | 配置 3 个密钥 + 选择能力和交互模式 |
+
+**无论选择哪种方式，AI 都会引导你走完每一步**——零编程经验也没问题。
+
+## 唯一入口
+
+[`SKILL.md`](./SKILL.md) — 由你的编程助手（CodeBuddy / Cursor / Claude Code）读取和执行。
+
+> **任意位置安装**：本 Skill 可以放在项目子目录、`.agents/skills/`、`.codebuddy/skills/` 或任何位置——
+> **不需要**放在工作区根目录。脚本会自动定位自身路径，Agent 只需使用绝对路径。
+
+### 安装方式
+
+#### Codex CLI
+
+**用户级安装**（推荐 — 所有项目均可使用）：
+```bash
+/skills install https://github.com/Burgerham4R/ai-customer-service-skill
+```
+
+**项目级安装**（仅当前项目可用）：
+```bash
+# Skill 将安装到 ./.codex/skills/（访达中按 Cmd+Shift+. 可显示隐藏文件夹）
+/skills install --project https://github.com/Burgerham4R/ai-customer-service-skill
+```
+
+#### Claude Code CLI
+
+**用户级安装**（推荐 — 所有项目均可使用）：
+```bash
+mkdir -p ~/.claude/skills
+git clone https://github.com/Burgerham4R/ai-customer-service-skill.git ~/.claude/skills/ai-customer-service-skill
+```
+
+**项目级安装**（仅当前项目可用）：
+```bash
+mkdir -p ./.claude/skills
+git clone https://github.com/Burgerham4R/ai-customer-service-skill.git ./.claude/skills/ai-customer-service-skill
+```
+
+#### 其他 Agent（CodeBuddy / Cursor 等）
+
+克隆到任意位置，然后让 Agent 加载 `SKILL.md`：
+```bash
+git clone https://github.com/Burgerham4R/ai-customer-service-skill.git
+# 然后对你的 Agent 说：
+# "从 /path/to/ai-service-skill/SKILL.md 加载这个 Skill"
+```
+
+> **安装完成后，请重启 CLI 会话** 以确保 Skill 被正确注册和加载。
+
+- "AI客服" / "搭建客服" / "客服机器人"
+- "TRTC + 客服" / "语音智能体 + 客服"
+- "帮我用 TRTC 搭建一个 AI 客服"
+
+## 3 个密钥是什么？
+
+要让客服智能体跑起来，你需要 3 个云服务凭证。别担心——它们只是从相应网站复制粘贴的 3 个字符串：
+
+> **Tencent RTC (trtc.io)** 是腾讯云旗下的国际实时音视频通信品牌。TRTC Conversational AI 服务基于腾讯云基础设施运行——你的 TRTC 账号和腾讯云账号通过统一登录体系关联。获取 API Key 时，系统会自动同步你的登录状态。
+
+| 密钥 | 用途 | 获取地址 |
+|------|------|---------|
+| 密钥 1：TRTC 应用凭证 | 让智能体能够拨打电话和进行语音聊天 | https://console.trtc.io/（注册并创建 Conversational AI 应用） |
+| 密钥 2：Tencent Cloud API Key | 证明你有权限使用 TRTC 语音和通话服务（登录态与 TRTC 账号自动同步） | https://console.tencentcloud.com/cam/capi |
+| 密钥 3：LLM API Key | 让智能体能够"思考"——理解用户问题并回复 | 你注册的 AI 服务网站（如 OpenAI、DeepSeek 等） |
+
+> AI 会一步步详细告诉你如何获取每个密钥。你的密钥信息仅用于本次配置会话——系统不会记录或泄露。
+
+## 智能体有哪些能力？
+
+| 能力 | 描述 | 快速体验 | 集成模式 |
+|------|------|:---:|:---:|
+| 对话 | 语音 + 文字双向交流 | ✅ 自动组装 | ✅ 默认包含 |
+| 知识库 | 上传文档，智能体自动检索并回答常见问题 | ✅ 模拟演示 | 🔘 可选 |
+| 人工转接 | 复杂问题自动转接至人工客服 | ✅ 模拟演示 | 🔘 可选 |
+| 工具调用 | 智能体可主动查询你的系统中的数据 | ❌ 不支持 | 🔘 可选 |
+| 会话摘要 | 每次对话后自动生成摘要 | ✅ 模拟演示 | 🔘 可选 |
+
+> "模拟演示"指：界面和工作流是完整的，但使用的是演示数据，未接入真实业务系统。如需真实接入，请选择"集成到我的系统"。
+
+## 通信模式（集成模式可选）
+
+| 模式 | 描述 | 适用场景 |
+|------|------|---------|
+| 纯文字即时消息 | 智能体通过文字聊天回复 | 网页聊天插件、应用内消息 |
+| 文字 + TTS | 智能体打字回复 + 语音朗读 | 智能音箱、语音助手 |
+| 全模态 | 文字、语音、视频全部支持 | 高级客服场景 |
+| 纯语音通话 | 智能体仅通过电话沟通 | 呼叫中心、热线 |
+
+## 进阶：自定义 TRTC Conversational AI
+
+如果你想微调 AI 智能体的语音行为或更换底层模型，请参阅 TRTC Conversational AI 官方文档：
+
+### 调整声音参数（语速 / 音调 / 音色）
+
+STT（语音识别）和 TTS（语音合成）均使用腾讯自研引擎。你可以通过以下文档调整声音参数：
+
+| 阶段 | 文档 |
+|------|------|
+| STT（语音识别） | [STT 配置参数](https://trtc.io/document/69592?product=conversationalai) |
+| TTS（语音合成） | [TTS 配置参数](https://trtc.io/document/68340?product=conversationalai) |
+
+### 切换 STT / LLM / TTS 模型
+
+如需更换底层 STT、LLM 或 TTS 模型，请查看各环节的模型总览并按照接入指引操作：
+
+| 阶段 | 文档 |
+|------|------|
+| STT（语音识别） | [STT 模型总览](https://trtc.io/document/69592?product=conversationalai) |
+| LLM（大语言模型） | [LLM 模型总览](https://trtc.io/document/68338?product=conversationalai) |
+| TTS（语音合成） | [TTS 模型总览](https://trtc.io/document/68340?product=conversationalai) |
+
+### 完整文档
+
+如有其他配置需求，请从 Conversational AI 总览页出发寻找相应答案：
+
+- [TRTC Conversational AI 总览](https://trtc.io/document/conversational-ai-overview?product=conversationalai)
+
+## 目录结构
+
+```
+ai-service-skill/
+├── SKILL.md                       # ★ 唯一入口（由编程助手触发）
+├── start.sh                       # 启动脚本（自动安装依赖 + 启动服务）
+│
+├── scripts/                       # AI 调用的工具脚本
+│   ├── verify-credentials.py      # 三密钥验证
+│   ├── setup-credentials.py       # 交互式开发者配置
+│   ├── add-capability.py          # 能力组装
+│   ├── contract-adapt.py          # 接口契约适配
+│   └── lib/                       # 共享模块
+│
+├── capabilities/
+│   ├── conversation-core/         # 通用语音智能体骨架
+│   ├── knowledge-base/            # FAQ 知识库检索
+│   ├── tool-calling/              # 工具调用
+│   ├── human-handoff/             # 人工转接 + 工单管理
+│   ├── session-summary/           # 会话摘要
+│   └── digital-human/             # 数字人（占位）
+│
+├── scenarios/
+│   ├── customer-service/          # 路径 A：演示界面
+│   └── custom-builder/            # 路径 B：能力选择向导
+│
+├── auto_adapters/                 # 技术栈适配器
+└── tests/                         # 测试套件
+```
+
+## 常见问题
+
+| 问题 | 解决方案 |
+|------|---------|
+| 密钥验证失败 | 返回密钥配置步骤，仔细检查每个密钥值 |
+| 端口 3000 被占用 | 使用其他端口（如 `--port 8080`）或停止占用端口的程序 |
+| Python 版本过低 | 从 python.org 下载安装 Python 3.9+ |
+| 启动后浏览器显示空白页 | 强制刷新：`Cmd+Shift+R`（Mac）或 `Ctrl+Shift+R`（Windows） |
+| 想接入真实业务系统 | 重新运行工作流，选择"集成到我的系统" |
+
+---
+
+> **最后再说一句**：本 Skill 的设计目标是让任何人——即使完全不会编程——都能搭起一个 AI 客服智能体。如果在过程中遇到任何问题，直接在聊天窗口中告诉 AI，它会帮你解决。