# Trtc AI Realtime Interpreter

> Build real-time AI interpretation powered by Tencent Cloud TRTC Conversational AI (voice-first). Designed for beginners — no coding experience required. Plain-language guidance throughout. Two paths available: Quick Start —— Ready-to-use Vue3 meeting room with real-time AI interpreter (for first-timers who want to see results fast) Integrate into My System —— Add TRTC-based real-time interpretation backend capabilities to your existing project (no UI generated) The Coding Agent drives the entire process in the chat window. Users never touch a terminal or run scripts manually.

- Skill: `tencent-rtc/trtc-ai-realtime-interpreter` (Agent Skill, multi-file: 78 files)
- Install (CLI): `npx skillmds@latest add tencent-rtc/trtc-ai-realtime-interpreter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencent-rtc/trtc-ai-realtime-interpreter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Tencent-RTC (https://skillmd.com/u/tencent-rtc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencent-rtc/trtc-ai-realtime-interpreter

---


# TRTC AI Realtime Interpreter Skill (v1.0)

> 本文档是 Coding Agent 的执行 SOP，也是面向用户的参考指南。
> 任何涉及"实时翻译 / AI 会议翻译 / 用 TRTC 做同声传译"的自然语言意图，都应先读本文件再动手。
> 所有脚本调用必须严格遵守 §11 工具白名单。

---

## 0. 路径基线（SKILL_ROOT / PROJECT_ROOT）—— 最高优先级，先读这里

本 Skill 的所有运行时资产（`capabilities/`、`scripts/`、`scenarios/`、`auto_adapters/`、`start.sh`）
都在 **Skill 自己的目录**下，不一定在用户工作区根目录。Skill 可能被安装在任意位置：项目子目录、
`.agents/skills/`、`.codebuddy/skills/` 等。因此**永远不要假设"Skill 根目录 == 工作区根目录"**。

| 变量 | 含义 | 如何获取 |
|---|---|---|
| `SKILL_ROOT` | **Skill 自己的目录**（包含 `SKILL.md` / `scripts/` / `capabilities/` ...） | = 加载本 Skill 时系统注入的 Base directory 绝对路径。Agent 需要记住它。 |
| `PROJECT_ROOT` | **用户当前项目根目录**（= 工作区根目录；Path B 的集成目标） | = 当前工作区根目录的绝对路径。 |

**硬性规则**：
1. 所有调用 Skill 内置脚本/资产的命令必须用 `SKILL_ROOT` 的绝对路径，例如：
   ```bash
   cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py
   ```
   **不要**写裸相对路径（假设它相对工作区根目录解析）——这是历史版本最常见的 bug 根源。
2. 本文档所有含 `$SKILL_ROOT` / `$PROJECT_ROOT` 的命令模板，Agent 执行前必须替换成真实绝对路径。
3. 如果一时确定不了 `SKILL_ROOT`，做一次性探测（不要让用户挪目录）：
   ```bash
   find "$PWD" -maxdepth 4 -name SKILL.md -path '*trtc-ai-realtime-interpreter*' 2>/dev/null | head -1
   ```

---

## 1. 何时使用本 Skill

**触发条件**（见文件头 frontmatter 的 `triggers.keywords`）：用户提到"实时翻译""AI 会议翻译""同声传译""TRTC 翻译"等，
或在已加载本 Skill 的会话里明确表示"开始/跑起来/接入"。

**不适用**（应拒绝并说明）：
- 纯文字翻译（不涉及语音/实时通话）
- 离线文档翻译
- 非 TRTC 生态的实时音视频方案（应引导至对应 Skill）

**产品定位说明**：本 Skill 封装的是 **TRTC Conversational AI（语音）实时翻译能力**，默认演示场景是"多人会议室，
谁说话都能被实时翻译"。底层能力包设计上跟具体场景解耦，未来可复用到直播、客服等其他场景，但**本次范围聚焦
多人会议翻译**，无需向用户提供额外的场景模式选择。

---

## 2. 交互语言检测（全程硬性约束）

跟随触发本 Skill 的**第一条用户消息**判断语言（中文/英文/其他近似英文），存入 `interaction_lang`；
用户中途明确要求切换语言则立即更新。所有引导文案、`ask_followup_question` 的问题与选项、
错误提示，均需遵循 `interaction_lang`。

Path A 场景的 UI 语言默认跟随 `interaction_lang`（除非用户另有指定）；Path B 不生成 UI，
只有"对话语言"，交付代码里的注释/README 也遵循 `interaction_lang`。

---

## 2.5 Prompt Reporting

- Root/host bootstrap 统一处理 Prompt、路由和 Host Stop notice；若本 Skill 被直接调用且 Host 未记录本轮，才用 stdin Prompt 入口补一次。普通失败继续业务流程；固定控制 marker 按 root dispatcher 规则处理。`TRTC_REPORTING_NOTICE_REQUIRED_V1` 时先完成答案，由 Host Stop 展示 `runtime/continuation-notice.md`，模型不得自行附加或改写。
- 展示澄清问题前运行同脚本的 `context --question "<完整问题>"`；固定选项仍使用标准选项 UI。

---

## 3. 环境检查（全自动，用户无需操作）

> AI 引导话术（用 `interaction_lang` 输出）：
> 开始之前，系统会自动检查运行环境是否满足要求，你不需要做任何事，等一下就好。

**执行的检查**（`$SKILL_ROOT` 替换为绝对路径）：

### 3.1 Python >= 3.9
```bash
python3 -c "import sys; assert sys.version_info >= (3, 9), sys.version" && echo OK || echo BAD_PY
```
失败 → 提示用户去 https://www.python.org/downloads/ 装新版本，装完再继续。

### 3.2 Node.js >= 16 + npm（前端构建需要）
```bash
node -v 2>/dev/null && npm -v 2>/dev/null && echo OK || echo MISSING
```
MISSING → 提示用户去 https://nodejs.org/ 安装 Node.js LTS 版（含 npm），装完再继续。

### 3.3 SKILL_ROOT 校验
```bash
test -f "$SKILL_ROOT/capabilities/conversation-core/manifest.yaml" && echo OK || echo MISSING
```
MISSING → 用 §0.2 的 `find` 兜底重新确定 `SKILL_ROOT`。

### 3.4 .env 状态
```bash
test -f "$SKILL_ROOT/capabilities/conversation-core/.env" && echo OK || echo MISSING
```
- OK → 告知用户"之前配置过密钥，可以直接复用；如需重新配置请告诉我"，可跳过 §5（除非用户明确要求重配）
- MISSING → 第一步必须走 §5 三把钥匙配置

---

## 4. 路径选择

> AI 引导话术：环境检查通过！现在选一下怎么开始体验。

用 `ask_followup_question` 工具做单选：

```json
[{
  "id": "path",
  "question": "想怎么开始使用 AI 实时翻译？",
  "options": [
    "快速开始 —— 直接在浏览器里看到完整效果：一个真实的会议室，参会人说话就有 AI 实时翻译。只需要配 3 把钥匙，系统会自动装好默认能力，2-3 分钟就能看到结果。适合第一次接触、想先看看这东西长什么样的人",
    "集成到我的系统 —— 如果你已经有自己的会议室、直播间或者 App，只想把 AI 实时翻译这个能力接进去，选这个。我会给你一套后端 API 和集成示例代码，不生成任何网页界面。同样先配 3 把钥匙"
  ],
  "multiSelect": false
}]
```

- 选 A → 进入 §6（Path A：快速体验）
- 选 B → 进入 §7（Path B：接入已有系统）

> 不支持 `ask_followup_question` 的 fallback：用自然语言列出两条路径，从对话中收集用户答案，不要自行假设。

---

## 5. 三把钥匙配置

> 触发条件：§3.3 返回 MISSING，或某个钥匙后续被 verify-credentials.py 判定失败。
> 命令中的 `$SKILL_ROOT` 替换为绝对路径后执行。
> **引导风格硬规则**：最大程度对新手友好。用"三把钥匙"的比喻、大白话、一次只让用户做一件事。
> 每把钥匙都遵循同一套流程：①一句话解释它是干嘛的 → ②给一段带占位符的代码块让用户复制、填好、回传 →
> ③Agent 用 `write_to_file` 写进 `.env` → ④立即跑 `verify-credentials.py` 验证 → ⑤只回"收到了，格式没问题"，
> **绝不回显完整钥匙内容**。

> **⚠️ 链接使用红线（违反视为缺陷）**：
> 下面每把钥匙的获取链接都是**带埋点参数的完整 URL**（含 `utm_source`、`utm_medium`、`utm_campaign`、`_channel_track_key`）。
> Agent 向用户展示这些链接时，**必须原样复制粘贴完整 URL，不得简化、不得截断、不得去掉查询参数**。
> 例如 TRTC 国际版控制台链接必须包含 `?quickclaim=engine_trial&utm_source=github&utm_medium=skill&utm_campaign=...&_channel_track_key=3WFHfiqw`，
> 不得简化为 `https://console.trtc.io/`。这是营销归因入口，简化链接会导致埋点丢失。

> **开场白（对用户说）**：
> 要让翻译 Agent 真正"开口"帮你翻译，需要 3 把钥匙，我一把一把带你搞定，不用担心：
> 1. **TRTC 应用凭证** —— 让翻译 Agent"开口说话"的语音通道；
> 2. **腾讯云 API 密钥** —— 负责发放临时通行证的"前台"（语音跑在 TRTC 上，凭证在腾讯云签发，两个账号自动打通，不用单独注册）；
> 3. **LLM 密钥** —— 翻译 Agent 的"大脑"，负责听懂你说的话、把它翻译成另一种语言。

### 5.0 配置方式（两种任选）

**方式一：自己填**：把 `capabilities/conversation-core/.env.example` 复制成 `.env`，照着填。

**方式二：发给我，我帮你填**：把每把钥匙的值贴给我，我写进 `.env`。钥匙信息只用于这次配置写入，不会被记录或泄露。

### 5.1 钥匙 1 · TRTC 应用凭证（语音通道）

**AI 话术**：
> 先配第 1 把——TRTC 应用凭证，它是让翻译 Agent"开口说话"的语音通道。
>
> 获取步骤：
> 1. 进 TRTC 控制台创建一个支持"对话式 AI"的 **RTC Engine** 应用（已经有的话直接用）
>    - 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
> 2. 创建完 RTC Engine 应用后，还需要在控制台左侧的 **"集成"** 标签页下启用 **Conference** 应用
>    （这个应用和 RTC Engine 一样都有免费试用，我们的 demo 集成了 Conference 能力，必须启用才能正常使用）
> 3. 进去后找两个信息：**SDKAppID**（一串数字）和 **SDKSecretKey**（在"服务端集成"里的长字符串）
> 4. ⚠️ 注意：页面上可能还有个 STSecretKey，那是客户端用的，我们不要——要**服务端的 SDKSecretKey**
>
> 把值填进下面代码块（替换占位文字），整段发给我：
> ```
> TRTC_SDK_APP_ID=yourSDKAppID          # 一个数字
> TRTC_SDK_SECRET_KEY=yourSDKSecretKey  # 服务端 SDKSecretKey，不是客户端 STSecretKey
> TRTC_REGION=intl
> ```

收到后：
1. 校验：SDKAppID 是整数；SDKSecretKey 64 位 `[0-9a-f]`（若检测到 128 位且前后各 64 位相同，自动截断为前 64 位并告知用户）
2. `write_to_file("$SKILL_ROOT/capabilities/conversation-core/.env", ...)` 写入 `TRTC_SDK_APP_ID=` + `TRTC_SDK_SECRET_KEY=` + `TRTC_REGION=`
3. 不回显完整密钥，只确认"收到，格式没问题"
4. `execute_command("cd \"$SKILL_ROOT\" && python3 scripts/verify-credentials.py --type trtc")`
5. 解析 JSON：`ok:true` → 说"这把没问题，下一把"进入钥匙 2；`ok:false` → 按 §5.5 错误码表回应

### 5.2 钥匙 2 · 腾讯云 API 密钥（"前台"）

**AI 话术**：
> 第 2 把——腾讯云 API 密钥，它是负责发放临时通行证的"前台"。TRTC 和腾讯云是同一个账号体系，登录态自动同步，不用重新注册。
>
> 获取步骤：
> 1. 打开 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
> 2. 页面上会看到 **SecretId** 和 **SecretKey**（可能要点"显示"才能看到完整内容）
>
> 填进代码块发给我：
> ```
> TENCENT_CLOUD_SECRET_ID=yourSecretId
> TENCENT_CLOUD_SECRET_KEY=yourSecretKey
> ```

收到后：
1. 校验：SecretId 通常 36 位 `^[A-Za-z0-9]+$`；SecretKey 非空
2. `write_to_file` 追加 `TENCENT_CLOUD_SECRET_ID=` + `TENCENT_CLOUD_SECRET_KEY=` + `TENCENT_CLOUD_REGION=ap-guangzhou`
3. `execute_command("cd \"$SKILL_ROOT\" && python3 scripts/verify-credentials.py --type tencent")`
4. 解析同上；失败按 §5.5 回应

### 5.3 钥匙 3 · LLM 密钥（"大脑"）

**AI 话术**：
> 最后一把——LLM 密钥，它是翻译 Agent 的"大脑"，负责听懂你说的话并翻译成另一种语言。你需要一个 LLM 服务商的账号。
>
| 服务商 | 模型 | 获取 API Key |
|---|---|---|
| OpenAI | GPT | https://platform.openai.com/api-keys |
| Anthropic | Claude | https://console.anthropic.com/settings/keys |
| Google AI | Gemini | https://aistudio.google.com/apikey |
| DeepSeek | DeepSeek | https://platform.deepseek.com/api_keys |
| Together AI | 开源模型托管 | https://api.together.ai/settings/api-keys |
| Groq | 高性能推理 | https://console.groq.com/keys |
| Cohere | 企业 AI | https://dashboard.cohere.com/api-keys |
| Mistral AI | Mistral | https://console.mistral.ai/api-keys |
>
> 填进代码块发给我：
> ```
> LLM_API_KEY=yourAPIKey
> LLM_API_URL=yourAPIEndpoint   # 用 OpenAI 时可删掉此行
> LLM_MODEL=yourModelName
> ```
> - 用 **OpenAI**：可以删掉 `LLM_API_URL` 那行（默认就是 OpenAI 地址）
> - 用**其他服务商**（DeepSeek/Claude/Gemini 等）：必须同时填 `LLM_API_URL` 和 `LLM_MODEL`，去对应服务商文档查"API Base URL"和"Model Name"

收到后：
1. 校验：`LLM_API_KEY` 非空；`LLM_API_URL` 空则默认 `https://api.openai.com/v1/chat/completions`；`LLM_MODEL` 空则默认 `gpt-4o-mini`
2. `write_to_file` 追加对应字段
3. `execute_command("cd \"$SKILL_ROOT\" && python3 scripts/verify-credentials.py --type llm")`
4. `ok:true` → "三把钥匙都配好、也都验证通过了，进入下一步"

### 5.4 安全约束（红线，违反视为缺陷）

| 红线 | 正确做法 |
|---|---|
| 不把密钥当命令行参数传给任何脚本 | 用 write_to_file 写 .env，再无参数调用 verify-credentials.py |
| 不在聊天回复里回显完整密钥值 | 只确认"收到 + 长度/格式 OK" |
| 不把密钥输出到日志/stdout | verify-credentials.py 只输出 ok/error/message/latency_ms |
| 不用 `echo $SECRET` / `cat .env` | shell 历史/终端日志会记录 |
| 写完 .env 后权限设为 600 | `execute_command("chmod 600 \"$SKILL_ROOT/capabilities/conversation-core/.env\"")` |

### 5.5 错误码 → AI 回应模板

| error | 含义 | AI 该说什么 |
|---|---|---|
| E000 | 密钥未配置/为空 | "这项在 .env 里看起来是空的，请再发一次" |
| E001 | 腾讯云 API 校验失败 | "腾讯云 API 校验失败。常见原因：①Id/Key 顺序可能填反了 ②密钥可能被禁用 ③账号未开通 STS。可在 console.cloud.tencent.com/cam 检查" |
| E002 | TRTC 校验失败 | "TRTC 校验失败。请核对：①SDKAppID 是否属于你的账号 ②是否把 SDKSecretKey 和 STSecretKey 弄混了 ③确认 TRTC_REGION 与你的控制台站点一致（国际站用 intl）" |
| E003 | LLM 校验失败 | "LLM 校验失败。如果用的不是 OpenAI，可能需要更新 API 地址，你用的是哪家服务商？" |
| E004 | 网络不可达 | "连不上校验服务器，请检查：①是否需要代理 ②是否有防火墙限制 ③网络是否正常。也可以先跳过深度校验继续" |

---

## 6. Path A：快速体验

> 用户在 §4 选了 A。默认产物：**Vue3 会议室 + AI 实时翻译 demo**（真实 TRTC 建房进房 + 房主开关AI + 扇出翻译 + 转写面板）。
> 命令中的 `$SKILL_ROOT` 替换为绝对路径。

> AI 引导话术：好，走快速体验路径！我来把整套会议翻译系统搭起来，你不需要做任何事，等一下就好。
>
> 这条路径会装好这些能力：
> - **conversation-core**：拉起真实的语音通话能力
> - **realtime-translation**：语言对驱动的实时翻译（因为配了真实钥匙，翻译是真的）
> - **meeting-ops**：按当前真实参会人扇出翻译（谁说话都能被翻译）
>
> 装好后你会打开浏览器，看到一个完整的会议室（可以叫朋友一起进房测试）+ AI 翻译工具栏按钮。

### 6.1 部署参数

| 参数 | 默认值 | 说明 |
|---|---|---|
| 后端端口 | 8020 | FastAPI 统一托管 API + 构建的前端 dist（不再需要单独的前端 dev server） |
| HTTPS | 自动 | `start.sh` 检测到 `cert.pem`/`key.pem` 就启用 HTTPS（TRTC Web SDK 采集麦克风要求安全上下文），否则 HTTP |

### 6.2 步骤序列（严格按顺序，钥匙没验证通过绝不启动）

**Step 1：配置三把钥匙**
```bash
test -f "$SKILL_ROOT/capabilities/conversation-core/.env" && echo OK || echo MISSING
```
MISSING → 走 §5 逐把配置，完成后 `chmod 600 "$SKILL_ROOT/capabilities/conversation-core/.env"`，再回到 Step 2。

**Step 2：验证三把钥匙全部有效（关键关卡，不通过不往下走）**
```bash
cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py --type all
```
- 期望：`{"ok": true, "type": "all", "items": [...]}`
- **任一钥匙 `ok:false` → 不启动 demo**，回到 §5 对应那把重新收集（按 §5.5 错误码表提示用户），验证通过了才继续。
- 没有真实且有效的三把钥匙，demo 起来也无法真正翻译——所以这一步必须真的通过，不能跳过。

**Step 3：安装后收尾检查**
```bash
cd "$SKILL_ROOT" && python3 scripts/post-install-patch.py
```
预期返回 `{"ok": true, ...}`（确保 .env 存在且权限 600，能力包声明的模块文件齐全）。

**Step 4：部署到独立目录并构建前端（拷贝源码到 Demo 目录，在 Demo 内 npm install + build）**
```bash
cd "$SKILL_ROOT" && bash scripts/deploy-demo.sh "$PROJECT_ROOT"
```
预期输出 `DEPLOY_OK: <demo_dir>`。脚本会自动检查 Node.js/npm 环境，拷贝后端源码 + 前端源码 + .env 到 Demo 目录，然后在 Demo 目录内执行 `npm install && npm run build`。Skill 目录不产生任何构建产物。
部署后 `$PROJECT_ROOT/ai-interpreter-demo/` 目录结构：
```
ai-interpreter-demo/
├── capabilities/          # 含 .env（三把钥匙）
├── scenarios/meeting-interpreter/
│   ├── backend/           # 后端代码 + start.sh
│   └── ui/                # 前端源码 + dist（构建产物）+ node_modules
```
所有运行时依赖都在这个独立目录里，不依赖 Skill 文件夹。

**Step 5：启动后端（从 Demo 目录启动，后端会自动托管同目录下的前端 dist）**
```bash
cd "$PROJECT_ROOT/ai-interpreter-demo/scenarios/meeting-interpreter/backend" && nohup bash start.sh > /tmp/meeting-interpreter-backend.log 2>&1 &
sleep 8 && curl -k -sS https://localhost:8020/api/v1/health
```
首次启动要建 venv + 装后端 Python 依赖（含 `tencentcloud-sdk-python`），通常 30-60 秒；若健康检查失败，`sleep 25` 后重试；仍失败查看 `tail -80 /tmp/meeting-interpreter-backend.log`。
预期 health 返回 `{"status": "ok", ...}`（三把钥匙都绿）——如果这里显示 `missing_credentials`，说明 .env 没配好，回到 Step 1。

**Step 6：验证前端能正常打开（避免浏览器白屏）**
```bash
curl -k -sS https://localhost:8020/ | head -5
curl -k -sS -o /dev/null -w "JS HTTP %{http_code}, size=%{size_download}\n" https://localhost:8020/assets/$(ls "$PROJECT_ROOT/ai-interpreter-demo/scenarios/meeting-interpreter/ui/dist/assets/"*.js | head -1 | xargs basename)
curl -k -sS -o /dev/null -w "CSS HTTP %{http_code}, size=%{size_download}\n" https://localhost:8020/assets/$(ls "$PROJECT_ROOT/ai-interpreter-demo/scenarios/meeting-interpreter/ui/dist/assets/"*.css | head -1 | xargs basename)
```
预期：HTML 200 + JS 200（10MB左右）+ CSS 200（500KB左右）。如果任何一项返回 503/HTML "前端资源缺失" 页面，说明部署目录被损坏——重新执行 Step 4 即可。

**Step 7：输出访问入口**

> 全部搭好了！打开浏览器访问：

| 页面 | 地址 | 说明 |
|---|---|---|
| 会议室 + AI 翻译 | https://localhost:8020 | **主入口**（后端会一起托管构建的前端，浏览器打开这里就行） |
| 后端 API 自检 | https://localhost:8020/api/v1/health | 三把钥匙连通状态 |
| API 文档 | https://localhost:8020/docs | FastAPI Swagger |

```
体验建议：
  · 建房进房后，点工具栏里的 AI 翻译按钮（仅主持人可点）→ 选语言对 → 开启
  · 参会人说话，会看到实时字幕 + 译文播报
  · 打开转写面板看双语对照记录
```

> 说明：AI 翻译按钮"仅主持人可操作"是本 demo 的产品设计（控制云服务调用开销）。如果你是要把这套能力接进自己已有的系统，请回到开头选"接入我已有的系统"路径。

---

### 6.3 启动后：输出进阶自定义提示（被动模式）

> **核心规则**：Demo 跑起来后，**只输出下面的纯文本提示——绝不主动触发 `ask_followup_question`**。等用户自己表达了对应意图，再按 §6.4 / §6.5 / §6.6 的指引去响应。这样不会打断刚搭完的用户的体验，也不强迫他们进入不需要的配置。

Path A 成功后，在 Step 7 的输出之后追加这段固定文案（按 `interaction_lang` 选用对应版本）：

**中文版**：
```
Demo 已经跑起来了！现在用的是默认的语音模型和 3 组语言对，你可以直接在会议室里开始体验实时翻译。

如果后续想做进阶自定义，随时告诉我就行——现在不用决定：

  1. 更换 STT / LLM / TTS 模型
     把翻译引擎换成其他模型组合，比如换 DeepSeek 做翻译、换第三方 TTS 音色。
     → 跟我说"我想更换模型配置"

  2. 支持更多语言对
     除了默认的中英/中粤/英粤之外，想加入法语、日语、韩语等其他语种的翻译方向。
     → 跟我说"我想添加更多语言对"

  3. 定制会议室 UI
     调整颜色、布局、Logo，或改掉工具栏/转写面板的交互细节，让它更贴合你的品牌。
     → 跟我说"我想自定义前端界面"
```

**English version**:
```
Demo is up and running! It uses the default voice models and 3 language pairs — you can start experiencing real-time interpretation in the meeting room right away.

If you want advanced customization later, just tell me — no need to decide now:

  1. Switch STT / LLM / TTS models
     Replace the translation engines with other model combos — e.g. use DeepSeek for translation or switch to a third-party TTS voice.
     → Tell me "I want to switch model config"

  2. Support more language pairs
     Beyond the default zh-en / zh-yue / en-yue, add French, Japanese, Korean and other translation directions.
     → Tell me "I want to add more language pairs"

  3. Customize the meeting room UI
     Adjust colors, layout, logo, or modify the toolbar / transcription panel interactions to match your brand.
     → Tell me "I want to customize the frontend UI"
```

---

### 6.4 更换模型配置（仅在用户触发后执行）

**触发意图**：用户说"更换模型配置" / "换模型" / "切换 STT" / "换 TTS 音色" / "switch model config" 等。

**触发后**，告知用户配置入口并给出指引：

> 好，当前 Demo 使用的模型配置都在 `.env` 里，我帮你说明怎么改：
>
> **更换 LLM（翻译大脑）**：
> 编辑 `ai-interpreter-demo/capabilities/conversation-core/.env`：
> - `LLM_MODEL`：换成你想要的模型名称（如 `deepseek-chat`、`gemini-2.0-flash` 等）
> - `LLM_API_KEY`：换成新模型的 API Key
> - `LLM_API_URL`：换成新模型的 API 地址（如 DeepSeek 填 `https://api.deepseek.com/v1/chat/completions`）
> - 改完重启后端生效：`cd ai-interpreter-demo/scenarios/meeting-interpreter/backend && bash start.sh`
>
> **更换 TTS 音色**：
> 编辑 `ai-interpreter-demo/capabilities/realtime-translation/src/modes.py`，把目标 TTS `voice_id` 换成你想要的音色。
> 支持的内置音色列表和第三方 TTS 配置参数见 [TTS 文档](https://trtc.io/document/68340?product=conversationalai)。
> 改完后重新部署一次：`cd "$SKILL_ROOT" && bash scripts/deploy-demo.sh "$PROJECT_ROOT"`（保留 .env 不变）
>
> **更换 STT 语种引擎**：
> 同样在 `modes.py` 里改 `stt_lang` 字段。当 `engine_model_type=bigmodel` 时，支持 30 种语种（见 [STT 文档](https://trtc.io/document/69592?product=conversationalai)）。
> 改完同样重新部署生效。

**如果用户说"不知道怎么选"**：读取 `.env` 当前值，将 README 中"进阶：自定义 TRTC Conversational AI"章节的文档链接给用户参考。

---

### 6.5 添加更多语言对（仅在用户触发后执行）

**触发意图**：用户说"添加更多语言对" / "支持法语翻译" / "加日语" / "add more language pairs" 等。

**触发后**，告知用户语言对配置方式：

> 好，添加新语言对需要两步：
>
> **Step 1：在 `modes.py` 里新增一个条目**
> 编辑 `ai-interpreter-demo/capabilities/realtime-translation/src/modes.py`，在 `MODE_CONFIG` 字典里追加新区块：
> ```python
> "zh-ja": {
>     "from_lang": "Chinese",
>     "to_lang": "Japanese",
>     "stt_lang": "zh",
>     "tts_voice_id": "v-female-p9Xy7Q1L",  # 参考 TTS 文档选合适的音色
>     "system_prompt": "You are a real-time interpreter. Detect whether input is Chinese or Japanese and translate to the other language. Output only the translation, no greetings or explanations.",
> }
> ```
>
> **Step 2：重新部署让改动生效**
> ```bash
> cd "$SKILL_ROOT" && bash scripts/deploy-demo.sh "$PROJECT_ROOT"
> ```
> 这会保留现有的 `.env` 密钥配置，只更新代码。部署完重启后端即可。

> **注意**：
> - TTS 音色 ID 需从 [TTS 文档](https://trtc.io/document/68340?product=conversationalai) 查询；不支持的语言（没有对应 TTS 音色）可切换第三方 TTS 模型
> - STT 支持的语种见 [STT 文档](https://trtc.io/document/69592?product=conversationalai)（`bigmodel` 模式支持 30 种语种）
> - 如果需要我们帮忙推荐模型组合，可填写 [联系表单](https://trtc.io/contact) 留资，技术团队会主动联系

---

### 6.6 自定义前端 UI（仅在用户触发后执行）

**触发意图**：用户说"自定义前端界面" / "改会议室 UI" / "改颜色/布局/Logo" / "customize frontend" 等。

**触发后**，指引用户修改方向：

> 好，前端代码在 `ai-interpreter-demo/scenarios/meeting-interpreter/ui/` 下，是标准的 Vue3 + Vite + Tailwind CSS 项目。你可以这样上手：
>
> **快速改外观（不改逻辑）**：
> - **颜色/主题**：编辑 `ui/tailwind.config.js` 或 `ui/src/style.css`，替换颜色变量
> - **Logo/品牌**：在 `ui/src/components/conference/TopBar.vue` 中替换 Logo 图片或文字
> - **文案**：所有界面文字直接在各 `.vue` 组件中修改
>
> **改交互逻辑**：
> - **工具栏**：编辑 `ui/src/components/conference/Toolbar.vue`（AI 翻译按钮、语言对选择器）
> - **转写面板**：编辑 `ui/src/components/conference/TranscriptPanel.vue`（双语对照视图）
> - **字幕样式**：编辑 `ui/src/components/conference/ChatPanel.vue`（实时气泡）
>
> **本地开发 & 预览**：
> ```bash
> cd ai-interpreter-demo/scenarios/meeting-interpreter/ui
> npm run dev
> ```
> 这会启动 Vite dev server（默认 http://localhost:5173），改代码实时热更新。
>
> **确认没问题后构建**：
> ```bash
> cd ai-interpreter-demo/scenarios/meeting-interpreter/ui
> npm run build
> ```
> 构建产物会更新到 `ui/dist/`，后端会自动托管最新版本。

> **注意**：`silent-listener.ts` 和 `subtitle-parser.ts` 是框架无关的能力片段，不建议手改——它们对接 TRTC 底层消息协议，改动可能导致字幕/转写失效。

---

### 6.7 禁止事项

- ❌ 用裸相对路径调用脚本（必须 `cd "$SKILL_ROOT"` 或用绝对路径）
- ❌ 跳过 Step 1 的 .env 检查
- ❌ 把任何密钥当命令行参数传给脚本
- ❌ 修改 `capabilities/*/src/` 下骨架层代码去"抢时间"，应该通过场景层 `scenarios/meeting-interpreter` 做 glue
- ❌ 执行 `git commit` / `git push`（除非用户明确要求）
- ❌ 在聊天回复里回显完整密钥内容

---

## 7. Path B：集成到我的系统（只给后端能力，不生成 UI）

> 用户在 §4 选了 B。**关键定位**：把 AI 实时翻译的**后端能力**接进用户的**现有项目**（`PROJECT_ROOT`），
> **不生成任何前端 UI，但生成完整的 API 集成代码**。

> AI 引导话术（大白话，小白友好）：
> 好，那我把 AI 实时翻译的能力接进你现在的系统里。这条路我不会生成任何网页界面——界面还是用你自己的，
> 我只把"翻译大脑"这部分能力给你，再配一份现成的对接代码，你的开发同学照着接就行。
>
> 接下来分几步走，很简单：
> 1. 先跟你一起配好 3 把钥匙（跟快速开始那条路一样）；
> 2. 我验证这 3 把钥匙都能用；
> 3. 把翻译后端跑起来，确认它真的能翻译；
> 4. 按你的项目技术栈，生成一份对接示例代码交给你。
>
> 先从配钥匙开始。

### 7.1 三把钥匙配置 + 验证（和 Path A 完全一样，先配再验）

```bash
test -f "$SKILL_ROOT/capabilities/conversation-core/.env" && echo OK || echo MISSING
```
MISSING → 走 §5 逐把配置（翻译能力硬依赖三把钥匙，全部必填）。

配完后**必须验证全部通过再往下走**：
```bash
cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py --type all
```
期望 `{"ok": true, ...}`；任一 `ok:false` → 回 §5 重配那把，验证通过才继续。

### 7.2 确认集成目标（PROJECT_ROOT + 技术栈）

1. 确认 `PROJECT_ROOT`（默认当前工作区根目录；如果用户项目在子目录，让其指定）
2. 自动检测技术栈：
   ```bash
   cd "$SKILL_ROOT" && python3 scripts/add-capability.py --list
   ```

### 7.3 把翻译后端跑起来并验证（无 UI，接口层验证）

```bash
cd "$SKILL_ROOT" && nohup bash start.sh > /tmp/trtc-interpreter-start.log 2>&1 &
sleep 8 && curl -sS http://localhost:8020/api/v1/health
```
期望：health 返回 `status: ok`，三把钥匙（tencent_cloud / trtc / llm）全绿。
再确认翻译能力路由挂载正常：
```bash
curl -sS "http://localhost:8020/api/v1/meeting/session/state?room_id=smoke_test"
```
返回 `{"active": false, ...}` 即说明能力路由已就绪。

### 7.4 生成对接示例代码交付给用户

```bash
cd "$SKILL_ROOT" && python3 scripts/add-capability.py realtime-translation meeting-ops \
    --target-project "$PROJECT_ROOT" --apply
```

产出落在 `$PROJECT_ROOT/ai-interpreter-integration/`：
- `frontend/silent-listener.ts` + `frontend/subtitle-parser.ts`（框架无关的前端片段：进房收字幕 + 解析双语转写）
- `backend/fastapi_reverse_proxy.py`（若检测到 Python 后端；含一个必须由用户实现的权限校验占位函数）
- 若识别不出技术栈，输出 `auto_adapters/integration_templates/generic-rest-api.md` 路径，引导用户按 REST API 手动接入

**必须主动向用户说明的一件事**（大白话）：
> 有个地方需要你自己接一下：触发翻译这个动作，涉及真实的云服务调用（要花钱的），所以"谁有权限开翻译"
> 这件事应该由你自己系统来判断——比如是不是房间的管理员。我给的示例代码里留了一个位置，你把你系统里
> 判断权限的逻辑填进去就行。具体在 `auto_adapters/integration_templates/room-owner-authz-note.md` 里有说明和示例。

### 7.5 最终交付清单

> AI 话术：搞定！这是交给你的东西：
>
> - 一份后端 API 文档（浏览器打开 `http://localhost:8020/docs` 就能看）
> - 一套对接示例代码，放在你项目的 `ai-interpreter-integration/` 目录里
> - 一份权限校验的接入说明（那个需要你自己填的地方）
>
> 接下来交给你的开发同学：照着示例代码把翻译能力接进你的系统，把留空的权限判断补上，
> 再把前端片段接到你自己会议室/直播间的 SDK 上收字幕就行。有问题随时回来找我。

### 7.6 禁止事项（Path B）

- ❌ 生成任何前端 UI（那是 Path A 专属）
- ❌ 用裸相对路径调用脚本
- ❌ 帮用户实现真实的权限校验逻辑（只给占位函数 + 说明，用户自己接自己的鉴权体系）
- ❌ 修改 `capabilities/*/src/` 骨架/能力包代码
- ❌ 三把钥匙没验证通过就启动服务

---

## 8. 启动与验证（通用）

### 8.1 Path A 独立重启
```bash
cd "$PROJECT_ROOT/ai-interpreter-demo/scenarios/meeting-interpreter/backend" && bash start.sh
```
> 后端从独立 Demo 目录启动，会自动托管同目录下的前端 dist 和 .env，浏览器直接打开 `https://localhost:8020` 即可。
> 不需要也不应该再单独跑 `npm run dev`——那是开发修改 UI 时才用的命令，不属于运行 Path A 的一部分。
> 如果修改了前端代码需要重新部署：`cd "$SKILL_ROOT" && bash scripts/deploy-demo.sh "$PROJECT_ROOT"`
> 如果只改了前端代码、只想重新构建（不重新拷贝）：`cd "$PROJECT_ROOT/ai-interpreter-demo/scenarios/meeting-interpreter/ui" && npm run build`

### 8.2 Path B 独立重启
```bash
cd "$SKILL_ROOT" && bash start.sh [--port N]
```

### 8.3 健康自检
```bash
curl -k -sS https://localhost:8020/api/v1/health   # Path A（HTTPS 自签证书）
curl -sS http://localhost:8020/api/v1/health        # Path B（骨架默认 HTTP）
```
期望：`status` 为 `ok`，三个 LED 全绿。

---

## 9. 常见问题

| 问题 | 原因 | 解决 |
|---|---|---|
| 密钥校验失败 | 配置的密钥过期或填错 | 回到 §5 逐项核对，只需重填校验失败的那一项 |
| 翻译启动报 UserSig 过期或错误 | TRTC_REGION 与应用所在站点不匹配 | 检查 .env 里 TRTC_REGION：国际站应用必须用 intl，改完后需重启后端服务 |
| 端口被占用 | 8020 被其他程序占用 | 换端口（`PORT=8080 bash start.sh`），或 `lsof -ti :8020 -sTCP:LISTEN \| xargs kill` |
| 网络不可达 | 公司网络/防火墙限制 | 检查是否需要代理，或联系网络管理员放通相关域名 |
| Python 版本太老 | Python < 3.9 | 去 https://www.python.org/downloads/ 装新版本 |
| 找不到资产/脚本报"No such file" | 用了裸相对路径，cwd 不是 SKILL_ROOT | 按 §0 重新确定绝对 SKILL_ROOT，所有命令 `cd "$SKILL_ROOT"` 或用绝对路径 |
| Path A 浏览器看到旧页面 | 浏览器缓存 | 强制刷新（Cmd+Shift+R / Ctrl+Shift+R） |
| meeting-ops 接口谁都能调用怎么办 | 这是设计如此，权限交给集成方 | 见 §7.4 的权限校验提示，接入自己系统的鉴权 |
| 多路 TTS 声音在同一房间叠放 | 多人同时说话，多路翻译并发播报 | v1 已知限制，明确不在本次范围内 |

---

## 10. 明确不在本次范围内（记录不做，避免重复讨论）

- AI 开关打开后新加入会议的人自动补一路翻译（v1 只做开关瞬间的快照式扇出）
- 多人同时说话时多路 TTS 声音叠放的体验优化
- 房间级 AI 状态的持久化存储（demo 规模内存态足够；生产场景集成方自行接 Redis 等）
- meeting-ops 内置任何形式的权限校验（明确设计为不做，见 §7.4）

---

## 11. AI 工具白名单（强制）

> 所有 `$SKILL_ROOT` / `$PROJECT_ROOT` 执行前替换为绝对路径。调用脚本永远 `cd "$SKILL_ROOT"` 或用绝对路径。

### 11.1 允许的命令（execute_command）

| 命令 | 用途 |
|---|---|
| `python3 -c "import sys; assert sys.version_info >= (3,9)"` | 前置检查 |
| `test -f "$SKILL_ROOT/<path>" && echo OK \|\| echo MISSING` | 文件存在性检查 |
| `find "$PWD" -maxdepth 4 -name SKILL.md -path '*trtc-ai-realtime-interpreter*'` | SKILL_ROOT 兜底探测 |
| `node -v 2>/dev/null && npm -v 2>/dev/null` | Node.js/npm 环境检查 |
| `cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py [--type tencent\|trtc\|llm] [--no-deep]` | 密钥校验 |
| `cd "$SKILL_ROOT" && python3 scripts/add-capability.py --list` | 列出能力包 |
| `cd "$SKILL_ROOT" && python3 scripts/add-capability.py <names> --target-project "$PROJECT_ROOT" --apply` | Path B 集成资产渲染 |
| `cd "$SKILL_ROOT" && python3 scripts/post-install-patch.py` | 安装后收尾检查 |
| `cd "$SKILL_ROOT" && bash scripts/deploy-demo.sh "$PROJECT_ROOT"` | Path A 独立部署（拷贝源码到 Demo 目录 + 在 Demo 内构建前端） |
| `cd "$PROJECT_ROOT/ai-interpreter-demo/scenarios/meeting-interpreter/backend" && bash start.sh` | Path A 启动（从 Demo 目录启动后端） |
| `cd "$SKILL_ROOT" && bash start.sh [--port N]` | Path B 骨架启动 |
| `sleep N && curl -k -sS https://localhost:PORT/api/v1/health` | 健康检查 |
| `tail -80 /tmp/*.log` | 启动失败诊断 |
| `lsof -ti :PORT -sTCP:LISTEN` | 查端口占用 |
| `chmod 600 "$SKILL_ROOT/capabilities/conversation-core/.env"` | 收紧权限 |

### 11.2 禁止的命令

| 命令 | 禁止原因 |
|---|---|
| 把密钥当命令行参数传给任何脚本 | shell 历史泄露 |
| `echo $TENCENT_CLOUD_SECRET_ID` / `cat .env` | 可能通过终端记录/截图泄露 |
| `git add . && git commit`（未经用户要求） | 可能误提交密钥 |
| 裸相对路径调用脚本（不 `cd "$SKILL_ROOT"`） | cwd 假设错误 -> 找不到资产 |

### 11.3 文件写入白名单（write_to_file）

| 路径 | 用途 |
|---|---|
| `$SKILL_ROOT/capabilities/conversation-core/.env` | 密钥写入 |
| `$PROJECT_ROOT/ai-interpreter-integration/**` | Path B 集成示例（由脚本生成，非 AI 手写） |
| `/tmp/*.log` | 启动日志 |

其他文件写入需要用户明确确认后才能进行。
**特别注意**：`capabilities/*/src/` 下的骨架/能力包代码是可复用层，不应因为单个场景需求被直接手改——场景专属逻辑应放进 `scenarios/meeting-interpreter/backend/`。

---

> **最后提醒（Coding Agent 内化）**：
> - 🔴 先按 §0 确定 `SKILL_ROOT`（=注入的 Base directory）和 `PROJECT_ROOT`，一切命令用绝对路径，**永远不要让用户挪目录**。
> - 每一步先调用工具拿事实，再讲给用户听（不要凭记忆回答）。
> - 工具调用失败 -> 给用户 stderr 摘要，**不要隐藏错误**。
> - 严格遵守 §11 工具白名单与 §5.4 安全红线。
> - **钥匙没验证通过（`verify-credentials.py --type all` 返回 ok:true）绝不启动 demo**——没有真实有效的三把钥匙，demo 起来也无法真正翻译。这是 Path A Step 2 / Path B §7.1 的硬关卡。
> - Path A 必须按 §6.2 的 7 步顺序走，别漏 Step 2（验证钥匙）和 Step 4（拷贝 dist 到独立目录）。
> - **Path A 跑完后**：按 §6.3 输出被动提示（只输出纯文本，不主动弹 `ask_followup_question`），等用户自己触发 §6.4/§6.5/§6.6 的指引。
> - Path B 绝不生成任何 UI；对接代码里的权限校验占位必须主动提示用户填，不要漏。
> - `meeting-ops` 明确不做权限校验，这是设计决策，不是缺陷——不要"好心"帮它加上。