@tencent-rtc/trtc-agent-skills 0.1.7 → 0.1.8

package/skills/trtc-ai-realtime-interpreter/README.md

@@ -0,0 +1,197 @@
+# TRTC AI Realtime Interpreter Skill
+
+[English](README.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md)
+
+> Build an AI real-time meeting interpreter powered by TRTC Conversational AI — zero code, voice-first. Two paths, both agent-driven: you just talk, the agent does the rest.
+
+## About Tencent RTC
+
+[Tencent RTC](https://trtc.io/?utm_source=github&utm_medium=skill&utm_campaign=Twitter%20AI%20%E4%B8%93%E9%A1%B9%20-%20AI%20Oral%20Coach&_channel_track_key=HIzH2eVJ) (Real-Time Communication) powers real-time audio, video, and conversational AI experiences for thousands of businesses worldwide. With a global edge network spanning 200+ countries and regions, TRTC delivers sub-300ms ultra-low latency at scale.
+
+The **Conversational AI** capability enables developers to build voice agents that can listen, understand, and respond naturally — perfect for real-time interpretation, multilingual meetings, and cross-language communication scenarios.
+
+## What is this?
+
+A plug-and-play Skill that builds an AI real-time meeting interpreter — packaged into a single agent-driven workflow:
+
+```
+You (in your IDE's AI chat window):
+  "Help me build a real-time AI interpreter with TRTC"
+
+AI (does everything automatically):
+  1. Checks your runtime environment
+  2. Lets you choose Quick Experience or Integrate into My System
+  3. Guides you through 3 keys setup (cloud service credentials)
+  4. Installs dependencies and assembles interpreter capabilities
+  5. Starts the service and gives you a browser URL
+
+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-first) real-time interpretation**.
+
+| Mode | Who it's for | What you get | What you need |
+|------|-------------|-------------|---------------|
+| **Quick Experience** | First-timers who want to see it in action | A complete Vue3 meeting room + AI interpreter (anyone speaks → translated + bilingual subtitles + transcription panel) | 3 keys |
+| **Integrate into My System** | Users who already have a meeting room, live room, or app and want backend interpretation | Backend API endpoints + integration samples (no UI generated) | 3 keys |
+
+> **No matter which path you choose, the AI walks you through every step** — zero coding 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 any location — it does **not** need to be at the workspace root. Scripts self-locate and the agent only needs absolute paths.
+
+## Installation
+
+Install via `npx` — works with any IDE, no plugin marketplace required. Run inside your project directory:
+
+```bash
+# Default — auto-detect installed IDEs and install for each one found
+npx -y @tencent-rtc/trtc-agent-skills@latest add
+
+# Force install for every supported IDE
+npx -y @tencent-rtc/trtc-agent-skills@latest add --ide all
+
+# Install only for one specific IDE
+npx -y @tencent-rtc/trtc-agent-skills@latest add --ide cursor
+
+# Wipe a previous install before re-installing
+npx -y @tencent-rtc/trtc-agent-skills@latest add --clean
+```
+
+## Trigger keywords
+
+- "实时翻译" / "AI 翻译" / "同声传译" / "会议翻译" / "TRTC 翻译"
+- "real-time interpreter" / "real-time translation" / "AI interpreter"
+- "TRTC Conversational AI" / "会议实时翻译" / "跨语言会议"
+- "帮我用 TRTC 做一个 AI 实时会议翻译"
+- "Help me build a real-time AI interpreter with TRTC"
+- "把 AI 实时翻译能力接入我现有的直播间"
+
+## What are the 3 keys?
+
+To get the interpreter running, you need 3 cloud service credentials. Don't worry — they're just 3 strings you copy and paste from the respective websites:
+
+> **How are TRTC and Tencent Cloud related?** TRTC's Conversational AI service runs on Tencent Cloud. Simply put: TRTC handles the voice calls between participants and the AI agent, while Tencent Cloud handles the backend (permissions, service activation, billing, etc.). Both share the same login — register once and use both.
+
+| Key | Purpose | Where to find it |
+|-----|---------|-----------------|
+| 1: TRTC App Credentials | Voice channel for the interpreter | https://console.trtc.io/?quickclaim=engine_trial&utm_source=github&utm_medium=skill&utm_campaign=Twitter%20AI%20%E4%B8%93%E9%A1%B9%20-%20AI%20Oral%20Coach&_channel_track_key=3WFHfiqw (Sign up and create an **RTC Engine** app — supports Conversational AI) |
+| 2: Tencent Cloud API Key | Backend permissions (login syncs with TRTC) | https://console.tencentcloud.com/cam/capi?utm_source=github&utm_medium=skill&utm_campaign=Twitter%20AI%20%E4%B8%93%E9%A1%B9%20-%20AI%20Oral%20Coach&_channel_track_key=v0K1Q0DSE |
+| 3: LLM API Key | The interpreter's "brain" — understand and translate speech in real time | Your AI provider (OpenAI, DeepSeek, etc.) |
+
+> The AI will guide you step-by-step on how to obtain each key. Your key information is only used during this setup session — the system does not record or leak it.
+
+## What capabilities does the interpreter have?
+
+| Capability | Description | Quick Experience | Integration |
+|------------|-------------|:---:|:---:|
+| Conversation Core | Voice pipeline + UserSig signer + credential management (skeleton, required) | ✅ Auto-assembled | ✅ Default included |
+| Realtime Translation | Language-pair-driven real-time translation (STT → LLM translate → TTS + subtitle) | ✅ Default | 🔘 Optional |
+| Meeting Ops | Multi-participant fanout orchestration (translate for everyone in the room) | ✅ Default | 🔘 Optional |
+| Bilingual Subtitles | Real-time bilingual subtitle display (original + translation side by side) | ✅ Built-in | ✅ Built-in |
+| Transcription Panel | Session transcription history with bilingual view | ✅ Built-in | ✅ Built-in |
+| Host-only Control | Only the room host can toggle AI interpretation (demo design) | ✅ Built-in | 🔘 Your own auth |
+
+> 💡 `realtime-translation` and `meeting-ops` capabilities share the same `conversation-core` skeleton — swap the language pair configuration to support different translation directions.
+
+## Supported language pairs
+
+| Mode ID | Source Language | Target Language | STT Language | TTS Voice | Direction |
+|---------|----------------|-----------------|--------------|-----------|-----------|
+| `zh-en` | Chinese | English | `zh` | `v-female-p9Xy7Q1L` | Bidirectional (zh ↔ en) |
+| `zh-yue` | Chinese | Cantonese | `zh` | `v-female-k3P8sL0Q` | Bidirectional (Mandarin ↔ Cantonese) |
+| `en-yue` | English | Cantonese | `en` | `v-female-k3P8sL0Q` | Bidirectional (en ↔ Cantonese) |
+
+> Language pairs are extensible — add more entries in `modes.py` to support additional translation directions. All TTS voices are built-in TRTC Conversational AI voices (`flow_01_turbo`), fully contained within the TRTC ecosystem.
+>
+> **Need more languages?** TRTC Conversational AI supports a wide range of STT languages and TTS voices beyond the defaults above. You can:
+> - Check the [STT supported languages](https://trtc.io/document/69592?product=conversationalai) and [TTS voice list](https://trtc.io/document/68340?product=conversationalai) to switch to built-in models that cover your target languages
+> - Switch to third-party STT/TTS models within the TRTC ecosystem via the configuration docs
+> - [Contact our technical team](https://trtc.io/contact) for custom language pair requirements — we'll help you find the right model combination
+
+## Advanced: Customize TRTC Conversational AI
+
+If you want to fine-tune the AI interpreter'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) |
+
+### STT supported languages
+
+When `engine_model_type` is set to `bigmodel`, you can specify the audio language for STT. Supported languages include: `zh` (Chinese), `en` (English), `yue` (Cantonese), `ar` (Arabic), `de` (German), `fr` (French), `es` (Spanish), `pt` (Portuguese), `id` (Indonesian), `it` (Italian), `ko` (Korean), `ru` (Russian), `th` (Thai), `vi` (Vietnamese), `ja` (Japanese), `tr` (Turkish), `hi` (Hindi), `ms` (Malay), `nl` (Dutch), `sv` (Swedish), `da` (Danish), `fi` (Finnish), `pl` (Polish), `cs` (Czech), `fil` (Filipino), `fa` (Persian), `el` (Greek), `ro` (Romanian), `hu` (Hungarian), `mk` (Macedonian).
+
+### Complete documentation
+
+For other configuration needs, start from the [Conversational AI Overview](https://trtc.io/document/71130?product=conversationalai) page.
+
+## Directory structure
+
+```
+trtc-ai-realtime-interpreter/
+├── SKILL.md                    # Agent execution SOP (the only entry point)
+├── README.md                   # English (main)
+├── README.zh-CN.md             # Chinese
+├── README.ja.md                # Japanese
+├── start.sh                    # Bootstrap (venv + deps + FastAPI:8020)
+├── capabilities/               # Atomic capabilities (shipped with repo, auto-mounted)
+│   ├── conversation-core/      # Skeleton: FastAPI + voice pipeline + credential signer
+│   ├── realtime-translation/   # Language-pair translation logic (STT/LLM/TTS)
+│   └── meeting-ops/            # Multi-target fanout orchestration (no auth built-in)
+├── scenarios/
+│   └── meeting-interpreter/    # Path A default: Vue3 meeting room + AI interpreter overlay
+│       ├── recipe.yaml         # Assembly recipe
+│       ├── backend/            # Scenario-specific backend (host auth, HTTP serve)
+│       └── ui/                 # Vue3 frontend (conference room, toolbar, transcript)
+├── auto_adapters/              # Path B: headless API integration templates
+│   ├── manifest.yaml
+│   ├── python/
+│   │   └── fastapi_reverse_proxy.py.tpl
+│   └── integration_templates/
+│       ├── generic-rest-api.md
+│       └── room-owner-authz-note.md
+└── scripts/                    # Verify credentials / add capability / post-install patch / deploy
+    ├── verify-credentials.py
+    ├── add-capability.py
+    ├── post-install-patch.py
+    ├── deploy-demo.sh
+    └── lib/
+```
+
+## FAQ
+
+| Issue | Solution |
+|-------|----------|
+| Key verification failed | Go back and double-check each key value — make sure you're using the server-side SDKSecretKey (not STSecretKey) |
+| TRTC_REGION mismatch | Check your TRTC app region: international site apps must use `intl` |
+| Port 8020 is in use | Use a different port or free port 8020: `lsof -ti :8020 -sTCP:LISTEN \| xargs kill` |
+| Python version too low | Install Python 3.9+ from [python.org](https://www.python.org/downloads/) |
+| Node.js / npm missing | Install Node.js LTS from [nodejs.org](https://nodejs.org/) |
+| Browser shows blank page | Hard refresh: `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows) |
+| "No such file" errors | The agent may have used a relative path — re-run from the correct SKILL_ROOT |
+| Multiple TTS voices overlapping | Known v1 limitation when multiple participants speak simultaneously |
+| Want to connect your own meeting system | Re-run and choose Path B (Integrate into My System) |
+
+## Contact Us
+
+Need technical support or enterprise pricing? Submit your contact information at [trtc.io/contact](https://trtc.io/contact) and our team will get back to you shortly.

package/skills/trtc-ai-realtime-interpreter/README.zh-CN.md

@@ -0,0 +1,197 @@
+# TRTC AI 实时翻译 Skill
+
+[English](README.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md)
+
+> 基于 TRTC Conversational AI 构建的 AI 实时会议翻译——零代码、语音优先。两条路径，全程由 AI 引导：你只需开口说话，AI 帮你搞定一切。
+
+## 关于 Tencent RTC
+
+[Tencent RTC](https://trtc.io/?utm_source=github&utm_medium=skill&utm_campaign=Twitter%20AI%20%E4%B8%93%E9%A1%B9%20-%20AI%20Oral%20Coach&_channel_track_key=HIzH2eVJ)（实时音视频）为全球数千家企业提供实时音频、视频和对话式 AI 体验。依托覆盖 200+ 国家和地区的全球边缘网络，TRTC 提供低于 300ms 的超低延迟大规模实时通信能力。
+
+**Conversational AI** 能力让开发者可以构建能够聆听、理解并自然回应的语音智能体——非常适合实时翻译、多语言会议和跨语言沟通场景。
+
+## 这是什么？
+
+将"基于 TRTC Conversational AI 的实时会议翻译"打包成一个即插即用的 Skill：
+
+```
+你（在 IDE 的 AI 聊天窗口中说）：
+  "帮我用 TRTC 做一个 AI 实时会议翻译"
+
+AI（自动完成所有操作）：
+  1. 检查你的运行环境
+  2. 让你选择搭建模式（快速体验 / 集成到我的系统）
+  3. 引导你完成 3 个密钥的配置（云服务凭证）
+  4. 安装依赖并组装翻译能力
+  5. 启动服务并给你一个浏览器地址，直接查看效果
+
+你完全不需要打开终端或手动执行任何脚本。
+```
+
+## 两种方式开始
+
+> 本 Skill 的核心能力是 **TRTC Conversational AI（语音优先）实时翻译**。
+
+| 模式 | 适合谁 | 能得到什么 | 需要做什么 |
+|------|--------|-----------|-----------|
+| **快速体验** | 想先看看效果的新用户 | 一个完整的 Vue3 会议室 + AI 实时翻译（谁说话都有翻译 + 双语字幕 + 转写面板） | 配置 3 个密钥 |
+| **集成到我的系统** | 已有会议室、直播间或应用、只想接入翻译能力的用户 | 后端 API 接口 + 集成示例代码（不生成 UI） | 配置 3 个密钥 |
+
+> **无论选择哪种方式，AI 都会引导你走完每一步**——零编程经验也没问题。
+
+## 唯一入口
+
+[`SKILL.md`](./SKILL.md) — 由你的编程助手（CodeBuddy / Cursor / Claude Code）读取和执行。
+
+> **任意位置安装**：本 Skill 可以放在项目子目录、`.agents/skills/`、`.codebuddy/skills/` 或任何位置——**不需要**放在工作区根目录。脚本会自动定位自身路径，Agent 只需使用绝对路径。
+
+## 安装方式
+
+通过 `npx` 安装 — 支持任意 IDE，无需插件市场。在项目根目录执行：
+
+```bash
+# 默认 — 自动检测已安装的 IDE 并安装
+npx -y @tencent-rtc/trtc-agent-skills@latest add
+
+# 强制为所有支持的 IDE 都安装
+npx -y @tencent-rtc/trtc-agent-skills@latest add --ide all
+
+# 只为某个指定的 IDE 安装
+npx -y @tencent-rtc/trtc-agent-skills@latest add --ide cursor
+
+# 重装前先清理旧的安装
+npx -y @tencent-rtc/trtc-agent-skills@latest add --clean
+```
+
+## 触发关键词
+
+- "实时翻译" / "AI 翻译" / "同声传译" / "会议翻译" / "TRTC 翻译"
+- "real-time interpreter" / "real-time translation" / "AI interpreter"
+- "TRTC Conversational AI" / "会议实时翻译" / "跨语言会议"
+- "帮我用 TRTC 做一个 AI 实时会议翻译"
+- "Help me build a real-time AI interpreter with TRTC"
+- "把 AI 实时翻译能力接入我现有的直播间"
+
+## 3 个密钥是什么？
+
+要让翻译智能体跑起来，你需要 3 个云服务凭证。别担心——它们只是从相应网站复制粘贴的 3 个字符串：
+
+> **TRTC 和腾讯云是什么关系？** TRTC 的对话式 AI 服务运行在腾讯云上。简单理解：TRTC 负责参会者与 AI 智能体之间的语音通话，腾讯云负责后台（权限校验、服务开通、计费等）。两者使用同一套登录体系，注册一次就能两边通用。
+
+| 密钥 | 用途 | 获取地址 |
+|------|------|---------|
+| 密钥 1：TRTC 应用凭证 | 让翻译智能体能够进行语音通话 | https://console.trtc.io/?quickclaim=engine_trial&utm_source=github&utm_medium=skill&utm_campaign=Twitter%20AI%20%E4%B8%93%E9%A1%B9%20-%20AI%20Oral%20Coach&_channel_track_key=3WFHfiqw（注册并创建 **RTC Engine** 应用，支持 Conversational AI） |
+| 密钥 2：腾讯云 API 密钥 | 证明你有权限使用 TRTC 语音和通话服务（登录态与 TRTC 账号自动同步） | https://console.tencentcloud.com/cam/capi?utm_source=github&utm_medium=skill&utm_campaign=Twitter%20AI%20%E4%B8%93%E9%A1%B9%20-%20AI%20Oral%20Coach&_channel_track_key=v0K1Q0DSE |
+| 密钥 3：LLM API 密钥 | 翻译智能体的"大脑"——实时听懂并翻译语音 | 你注册的 AI 服务网站（如 OpenAI、DeepSeek 等） |
+
+> AI 会一步步详细告诉你如何获取每个密钥。你的密钥信息仅用于本次配置会话——系统不会记录或泄露。
+
+## 翻译能力有哪些？
+
+| 能力 | 描述 | 快速体验 | 集成模式 |
+|------|------|:---:|:---:|
+| 对话骨架 | 语音通道 + UserSig 签发 + 凭证管理（骨架，必装） | ✅ 自动组装 | ✅ 默认包含 |
+| 实时翻译 | 语言对驱动的实时翻译（STT → LLM 翻译 → TTS 播报 + 字幕） | ✅ 默认 | 🔘 可选 |
+| 会议扇出 | 按参会人批量扇出翻译（房间内谁说话都有翻译） | ✅ 默认 | 🔘 可选 |
+| 双语字幕 | 实时双语字幕显示（原文 + 译文并列显示） | ✅ 内置 | ✅ 内置 |
+| 转写面板 | 整场会议的双语转写记录 | ✅ 内置 | ✅ 内置 |
+| 房主控制 | 仅会议室主持人可以开关 AI 翻译（Demo 设计） | ✅ 内置 | 🔘 自定义鉴权 |
+
+> 💡 `realtime-translation` 和 `meeting-ops` 能力共用同一套 `conversation-core` 骨架——替换语言对配置即可支持不同翻译方向。
+
+## 支持的语言对
+
+| 模式 ID | 源语言 | 目标语言 | STT 识别语种 | TTS 音色 | 翻译方向 |
+|---------|--------|----------|-------------|----------|---------|
+| `zh-en` | 中文 | 英语 | `zh` | `v-female-p9Xy7Q1L` | 中英双向（中文 ↔ 英文） |
+| `zh-yue` | 中文 | 粤语 | `zh` | `v-female-k3P8sL0Q` | 普通话 ↔ 粤语双向 |
+| `en-yue` | 英语 | 粤语 | `en` | `v-female-k3P8sL0Q` | 英文 ↔ 粤语双向 |
+
+> 语言对可扩展——在 `modes.py` 中新增条目即可支持更多翻译方向。所有 TTS 音色均为 TRTC 对话式 AI 内置音色（`flow_01_turbo`），全程闭环在 TRTC 生态内。
+>
+> **需要更多语言？** TRTC Conversational AI 支持远超上述默认配置的 STT 语种和 TTS 音色。你可以：
+> - 查看 [STT 支持语种](https://trtc.io/document/69592?product=conversationalai) 和 [TTS 音色列表](https://trtc.io/document/68340?product=conversationalai)，切换到覆盖目标语言的内置模型
+> - 通过配置文档在 TRTC 生态内切换到第三方 STT/TTS 模型
+> - [联系我们的技术团队](https://trtc.io/contact) 获取定制语言对方案——我们会帮你找到最合适的模型组合
+
+## 进阶：自定义 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) |
+
+### STT 支持语种
+
+当 `engine_model_type` 指定为 `bigmodel` 时，可指定音频语种。支持语种包括：`zh`（中文）、`en`（英语）、`yue`（粤语）、`ar`（阿拉伯语）、`de`（德语）、`fr`（法语）、`es`（西班牙语）、`pt`（葡萄牙语）、`id`（印尼语）、`it`（意大利语）、`ko`（韩语）、`ru`（俄语）、`th`（泰语）、`vi`（越南语）、`ja`（日语）、`tr`（土耳其语）、`hi`（印地语）、`ms`（马来语）、`nl`（荷兰语）、`sv`（瑞典语）、`da`（丹麦语）、`fi`（芬兰语）、`pl`（波兰语）、`cs`（捷克语）、`fil`（菲律宾语）、`fa`（波斯语）、`el`（希腊语）、`ro`（罗马尼亚语）、`hu`（匈牙利语）、`mk`（马其顿语）。
+
+### 完整文档
+
+如有其他配置需求，请从 [Conversational AI 总览](https://trtc.io/document/71130?product=conversationalai) 页面出发寻找相关文档。
+
+## 目录结构
+
+```
+trtc-ai-realtime-interpreter/
+├── SKILL.md                    # Agent 执行 SOP（唯一入口）
+├── README.md                   # English（主文档）
+├── README.zh-CN.md             # Chinese
+├── README.ja.md                # Japanese
+├── start.sh                    # 骨架启动脚本（venv + deps + FastAPI:8020）
+├── capabilities/               # 原子能力包（随仓库发布，自动挂载）
+│   ├── conversation-core/      # 骨架：FastAPI + 语音通道 + 凭证签发
+│   ├── realtime-translation/   # 语言对翻译逻辑（STT/LLM/TTS）
+│   └── meeting-ops/            # 多目标扇出编排（无内置权限）
+├── scenarios/
+│   └── meeting-interpreter/    # Path A 默认场景：Vue3 会议室 + AI 翻译叠加层
+│       ├── recipe.yaml         # 组装配方
+│       ├── backend/            # 场景专属后端（房主鉴权、HTTP 托管）
+│       └── ui/                 # Vue3 前端（会议室、工具栏、转写面板）
+├── auto_adapters/              # Path B：无 UI API 集成模板
+│   ├── manifest.yaml
+│   ├── python/
+│   │   └── fastapi_reverse_proxy.py.tpl
+│   └── integration_templates/
+│       ├── generic-rest-api.md
+│       └── room-owner-authz-note.md
+└── scripts/                    # 凭证校验 / 能力安装 / 安装后检查 / 部署
+    ├── verify-credentials.py
+    ├── add-capability.py
+    ├── post-install-patch.py
+    ├── deploy-demo.sh
+    └── lib/
+```
+
+## 常见问题
+
+| 问题 | 解决方法 |
+|------|---------|
+| 密钥校验失败 | 回到配置步骤逐项核对——注意要用服务端的 SDKSecretKey（不是客户端的 STSecretKey） |
+| TRTC_REGION 不匹配 | 检查 TRTC 应用所在站点：国际站应用必须用 `intl` |
+| 8020 端口被占用 | 换端口或释放端口：`lsof -ti :8020 -sTCP:LISTEN \| xargs kill` |
+| Python 版本太旧 | 去 [python.org](https://www.python.org/downloads/) 安装 Python 3.9+ |
+| 缺少 Node.js / npm | 去 [nodejs.org](https://nodejs.org/) 安装 Node.js LTS 版本 |
+| 浏览器打开是空白页 | 强制刷新：Mac `Cmd+Shift+R` / Windows `Ctrl+Shift+R` |
+| 报"No such file"错误 | Agent 可能用了相对路径——从正确的 SKILL_ROOT 重新执行 |
+| 多人同时说话，TTS 声音叠放 | v1 已知限制，多人同时说话时多路翻译的 TTS 播报会叠加 |
+| 想接入自己已有的会议室系统 | 重新运行并选择 Path B（集成到我的系统） |
+
+## 联系我们
+
+需要技术支持或企业定价方案？请通过 [trtc.io/contact](https://trtc.io/contact) 提交你的联系方式，我们的团队会尽快回复。