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

package/knowledge-base/slices/conference/web/official-roomkit-api.md

@@ -4,30 +4,44 @@ platform: web
 api_docs:
   - title: 快速接入 Web&H5 (Vue3)
     url: https://cloud.tencent.com/document/product/647/81962
+  - title: 快速接入 Web (React)
+    url: https://cloud.tencent.com/document/product/647/132839
   - title: 界面微调 (Web)
     url: https://cloud.tencent.com/document/product/647/129842
 ---
 
 # 官方 RoomKit 适配层 API — Web 实现
 
-> 本 slice 覆盖 `@tencentcloud/roomkit-web-vue3` 导出的 `conference` 对象的完整 API。
+> 本 slice 覆盖官方 RoomKit Web 包导出的 `conference` 对象 API。
+> Vue3 项目使用 `@tencentcloud/roomkit-web-vue3`，React 项目使用
+> `@tencentcloud/roomkit-web-react`。两者的 `conference` API 调用时序保持一致。
 > 当 `ui_mode = official-roomkit` 时，业务侧通过此对象操作会议，
-> 而不是直接调用 composable（composable 层见 `conference/web/room-lifecycle.md` 等）。
+> 而不是直接调用 no-UI hooks/composables（no-UI 层见 `conference/web/room-lifecycle.md` 等）。
 >
-> 以下签名基于 `@tencentcloud/roomkit-web-vue3@5.9.0` 源码验证。
-> 源码参考：`RoomKit/adapter/conference.ts` + `RoomKit/adapter/type.ts`。
+> Vue3 签名基于 `@tencentcloud/roomkit-web-vue3@5.9.0` 源码验证；React
+> 签名基于官方 React 快速接入文档与同名导出校验。
 
 ## 前置条件
 
-**安装依赖**：
+**安装依赖（按项目框架二选一，不要混装）**：
+
+Vue3：
 ```bash
 npm install @tencentcloud/roomkit-web-vue3@5 tuikit-atomicx-vue3 \
   @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
-**版本要求**：lockfile 中 `@tencentcloud/roomkit-web-vue3` 解析版本必须 `>=5.4.3`。
+React：
+```bash
+npm install @tencentcloud/roomkit-web-react tuikit-atomicx-react \
+  @tencentcloud/uikit-base-component-react @tencentcloud/universal-api
+```
+
+**版本要求**：
+- Vue3：lockfile 中 `@tencentcloud/roomkit-web-vue3` 解析版本必须 `>=5.4.3`。
+- React：使用 `@tencentcloud/roomkit-web-react` 与同版本族的 `tuikit-atomicx-react`。
 
-**导入来源**：
+**导入来源（Vue3）**：
 ```ts
 // 会议组件 + conference API + 事件/枚举
 import {
@@ -43,6 +57,21 @@ import {
 import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3'
 ```
 
+**导入来源（React）**：
+```tsx
+// 会议组件 + conference API + 事件/枚举
+import {
+  ConferenceMainView,
+  conference,
+  RoomEvent,
+  BuiltinWidget,
+  InterceptorAction,
+} from '@tencentcloud/roomkit-web-react'
+
+// UIKitProvider（包裹组件用）
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react'
+```
+
 ## 枚举定义
 
 ```ts
@@ -189,7 +218,7 @@ interface FeatureConfig {
 7. RoomEvent.ROOM_LEAVE / ROOM_DISMISS 回调 → 清理注销函数
 ```
 
-## 完整代码示例
+## 完整代码示例（Vue3）
 
 ```vue
 <template>
@@ -270,14 +299,93 @@ onUnmounted(() => {
 </script>
 ```
 
+## 完整代码示例（React）
+
+```tsx
+import { useEffect } from 'react'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import {
+  ConferenceMainView,
+  conference,
+  RoomEvent,
+  BuiltinWidget,
+} from '@tencentcloud/roomkit-web-react'
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react'
+
+export function MeetingRoom() {
+  const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
+
+  useEffect(() => {
+    const sdkAppId = Number(searchParams.get('sdkAppId'))
+    const userId = searchParams.get('userId') || ''
+    const userSig = searchParams.get('userSig') || ''
+    const roomId = searchParams.get('roomId') || ''
+    const cleanupFns: Array<() => void> = []
+
+    const cleanupRoomListeners = () => {
+      conference.off(RoomEvent.ROOM_LEAVE, handleLeave)
+      conference.off(RoomEvent.ROOM_DISMISS, handleLeave)
+      cleanupFns.forEach((fn) => fn())
+    }
+
+    const handleLeave = () => {
+      cleanupRoomListeners()
+      navigate('/')
+    }
+
+    const start = async () => {
+      if (!sdkAppId || !userId || !userSig || !roomId) {
+        navigate('/')
+        return
+      }
+
+      await conference.login({ sdkAppId, userId, userSig })
+      await conference.setSelfInfo({ userName: userId, avatarUrl: '' })
+
+      conference.setWidgetVisible({
+        [BuiltinWidget.InviteWidget]: false,
+      })
+
+      conference.on(RoomEvent.ROOM_LEAVE, handleLeave)
+      conference.on(RoomEvent.ROOM_DISMISS, handleLeave)
+
+      await conference.createAndJoinRoom({
+        roomId,
+        options: { roomName: `会议-${roomId}` },
+      })
+
+      conference.setFeatureConfig({
+        shareLink: `${window.location.origin}/meeting?roomId=${roomId}`,
+      })
+    }
+
+    start().catch(() => navigate('/'))
+
+    return () => {
+      cleanupRoomListeners()
+    }
+  }, [navigate, searchParams])
+
+  return (
+    <UIKitProvider theme="light" language="zh-CN">
+      <ConferenceMainView />
+    </UIKitProvider>
+  )
+}
+```
+
 ## 代码生成约束
 
 ### MUST
 
 1. **使用 UIKitProvider 包裹会议组件** — `ConferenceMainView` / `ConferenceMainViewH5` 必须放在 `UIKitProvider` 内。
+   - Vue3：`@tencentcloud/uikit-base-component-vue3`
+   - React：`@tencentcloud/uikit-base-component-react`
 2. **界面微调 API 在 login 之后、进房之前注册** — 避免按钮闪烁或拦截器遗漏。
 3. **registerWidget / onWill 返回的注销函数必须收集并在 ROOM_LEAVE + ROOM_DISMISS 时清理** — 防止重复注册。
 4. **shareLink 在进房成功后设置** — 依赖最终确定的 roomId。
+5. **按项目框架选择包名** — React 项目必须使用 `@tencentcloud/roomkit-web-react` / `tuikit-atomicx-react`，Vue3 项目必须使用 `@tencentcloud/roomkit-web-vue3` / `tuikit-atomicx-vue3`。
 
 ### MUST NOT
 
@@ -286,6 +394,7 @@ onUnmounted(() => {
 3. **不要给 joinRoom 传 isOpenCamera / isOpenMicrophone** — 只接受 `roomId`、`roomType`、`password`。
 4. **不要把 shareLink 写成对象** — `setFeatureConfig({ shareLink: '...' })` 是纯字符串。
 5. **不要用 CSS/DOM hack 修改 RoomKit 内部 UI** — 必须用 `setWidgetVisible` / `registerWidget` / `onWill`。
+6. **不要在 React 项目中生成 Vue SFC 或 Vue 包导入**；也不要在 Vue3 项目中生成 React JSX / TSX。
 
 ## 常见错误速查
 
@@ -296,3 +405,5 @@ onUnmounted(() => {
 | `joinRoom({ roomId, isOpenCamera: true })` | `joinRoom({ roomId })` | 无 isOpenCamera 参数 |
 | `setFeatureConfig({ shareLink: { link, title } })` | `setFeatureConfig({ shareLink: 'url' })` | shareLink 是字符串 |
 | `import { UIKitProvider } from '@tencentcloud/roomkit-web-vue3'` | `import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3'` | UIKitProvider 在 peer 包中 |
+| React 项目 `import { ConferenceMainView } from '@tencentcloud/roomkit-web-vue3'` | `import { ConferenceMainView } from '@tencentcloud/roomkit-web-react'` | React 与 Vue3 包名不同 |
+| React 项目 `import { useRoomState } from 'tuikit-atomicx-vue3/room'` | `import { useRoomState } from 'tuikit-atomicx-react/room'` | React no-UI hooks 使用 React 包 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-rtc/trtc-agent-skills",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Installer for the TRTC Agent Skills suite (Chat, Call, RTC Engine, Live, Conference) + knowledge base, with one-command MCP setup for Claude Code / Cursor / CodeBuddy / Codex.",
   "bin": {
     "trtc-agent-skills": "bin/cli.js"

package/skills/trtc/SKILL.md

@@ -2,33 +2,39 @@
 name: trtc
 description: >
   Routes TRTC questions and integration requests to the right skill. Identifies
-  product (Conference, Chat, Call, Live, RTC Engine, Conversational AI), platform,
-  and intent, then dispatches to the appropriate pipeline. Use when the user wants
-  to integrate TRTC, build a video conference, voice room, live stream, 1v1 call,
-  or IM chat app, or asks about SDK usage, error codes, pricing, or API docs —
-  in any phrasing: "接入TRTC", "如何集成", "build a meeting app", "音视频", "直播间",
-  "IM聊天", "错误码", "怎么用TRTC", "video conference", "RTC SDK". 
+  product (Conference, Chat, Call, Live, RTC Engine, Conversational AI, TIMPush),
+  platform, and intent, then dispatches to the appropriate pipeline. Use when the
+  user wants to integrate TRTC, build a video conference, voice room, live stream,
+  1v1 call, or IM chat app, or asks about SDK usage, error codes, pricing, or API
+  docs — in any phrasing: "接入TRTC", "如何集成", "build a meeting app", "音视频",
+  "直播间", "IM聊天", "错误码", "怎么用TRTC", "video conference", "RTC SDK".
   Also triggers for Chat (IM) consult and vue3 headless ui integration.
   Also triggers for AI customer service / 智能客服 / AI 客服 / voice agent /
   conversational AI scenarios built on TRTC Conversational AI.
   Also triggers for AI oral coach / 口语陪练 / 英语口语 / 口语教练 / speaking coach /
   oral practice scenarios built on TRTC Conversational AI.
+  Also triggers for TIMPush / 离线推送 / 帮我集成 timpush / 集成腾讯云 push /
+  接入腾讯云 push / 集成腾讯云离线推送 / 接入腾讯云离线推送 /
+  integrate Tencent Cloud push / Tencent Cloud offline push /
+  registerPush / 800006 / APNs / FCM + TIMPush context — routes to trtc-push.
   Keywords: TRTC, TUIRoom, RoomKit, Conference, Chat, Call, Live, 视频会议, 音视频,
   直播, IM, TUIKit, UIKit, SDK, 集成, 接入, 错误码, REST API, Webhook, UserSig,
   AI客服, 智能客服, 对话式AI, voice agent, 口语陪练, 英语口语, 口语教练, oral coach,
-  speaking coach, IM SDK API, IM 内网代理, 计费/套餐.
-version: 0.1.6
+  speaking coach, IM SDK API, IM 内网代理, 计费/套餐, TIMPush, 离线推送, 腾讯云 push,
+  腾讯云离线推送, Tencent Cloud push, Tencent Cloud offline push, registerPush.
+version: 0.1.8
 ---
 
 # TRTC Integration Assistant
 
 **Language rule**: Always reply in the same language the user writes in. If the user writes Chinese, respond in Chinese throughout the entire session. If the user writes English, respond in English. Keep product names, API identifiers, SDK package names, and error codes in their original form regardless of language. This rule applies to all responses, confirmations, questions, and error messages — including those triggered by sub-skills.
 
-你负责做四件事：
+你负责做五件事：
 1. 读取 session，判断是否要恢复已有 flow。
 2. 检测是否为 AI 客服 / Conversational AI 场景，是则路由到 `trtc-ai-service/SKILL.md`。
 3. 检测是否为 AI 口语陪练 / oral coach 场景，是则路由到 `trtc-ai-oral-coach/SKILL.md`。
-4. 用共享工具识别 product / intent，路由到正确 owner：`trtc-conference/SKILL.md`、`trtc-chat/SKILL.md`、`trtc-chat/docs/SKILL.md` 或 `trtc-docs/SKILL.md`。
+4. 检测是否为 TIMPush / 离线推送场景，是则路由到 `trtc-push/SKILL.md`。
+5. 用共享工具识别 product / intent，路由到正确 owner：`trtc-conference/SKILL.md`、`trtc-chat/SKILL.md`、`trtc-chat/docs/SKILL.md` 或 `trtc-docs/SKILL.md`。
 
 ## Hard Boundary
 
@@ -56,6 +62,7 @@ version: 0.1.6
 **终止契约**：dispatcher 必须在以下任意一条成立时输出最后一条响应并 STOP，不得继续追问或生成内容：
 - 已路由到 `trtc-ai-service/SKILL.md`
 - 已路由到 `trtc-ai-oral-coach/SKILL.md`
+- 已路由到 `trtc-push/SKILL.md`
 - 已路由到 `trtc-conference/SKILL.md`
 - 已路由到 `trtc-chat/SKILL.md`
 - 已路由到 `trtc-chat/docs/SKILL.md`
@@ -170,6 +177,33 @@ python3 "<当前 trtc skill 目录>/tools/reporting.py" prompt --text "<用户
 
 如果同时出现口语陪练触发词与其他产品信号，降回标准路由，询问用户想做哪个。
 
+### Pre-gate: TIMPush fast-path
+
+在进入 Query Classification 之前，再检查是否为 TIMPush / 离线推送场景。
+
+如果用户消息命中以下触发词之一：
+- "帮我集成 TIMPush" / "帮我集成 timpush" / "接入 TIMPush" / "集成 TIMPush"
+- "集成腾讯云 push" / "接入腾讯云 push" / "集成腾讯云 Push" / "接入腾讯云 Push"
+- "集成腾讯云离线推送" / "接入腾讯云离线推送" / "腾讯云离线推送" / "腾讯云 push"
+- "TIMPush 离线推送" / "即时通信推送" / "离线推送接入"
+- "registerPush" / "800006" / "businessID" + 推送语境
+- "TIMPush" / "timpush" / "APNs" / "FCM" 且明确是推送接入或排障
+- "integrate TIMPush" / "TIMPush integration" / "TIMPush offline push" / "setup TIMPush"
+- "integrate Tencent Cloud push" / "setup Tencent Cloud push" / "add Tencent Cloud push"
+- "integrate Tencent Cloud offline push" / "Tencent Cloud offline push" / "Tencent Cloud push integration"
+
+**且** 消息中 **不** 同时出现明确的其他产品主导信号（Conference / Call / Live / 口语陪练 / AI客服）：
+
+→ 命中后，**先执行 prompt 上报再路由**（与 §-1 等价，失败静默跳过）：
+```bash
+python3 "<当前 trtc skill 目录>/tools/reporting.py" prompt --text "<用户原始消息>"
+```
+> **`<当前 trtc skill 目录>` 解析规则**：与上节相同，按 IDE 选择正确路径，不得硬编码。
+
+→ 然后路由到 `../trtc-push/SKILL.md`，按其引导流程执行。**STOP** — 不继续执行后续 §1–§3 步骤。
+
+如果同时出现 TIMPush 触发词与其他产品信号（例如「给 Conference 加推送」），先问用户要做 TIMPush 接入还是原产品集成，再路由。
+
 ### 1. Query classification
 
 运行：
@@ -351,6 +385,7 @@ keyword fallback 也无法匹配时：直接问用户”你在用哪个 TRTC 产
 | domain flow | Conference Web troubleshoot (symptom) | `../trtc-conference/flows/troubleshoot.md` |
 | domain skill | AI customer service / 智能客服 | `../trtc-ai-service/SKILL.md` |
 | domain skill | AI oral coach / 口语陪练 | `../trtc-ai-oral-coach/SKILL.md` |
+| domain skill | TIMPush / 离线推送 | `../trtc-push/SKILL.md` |
 | shared answer layer | factual / docs lookup | `../trtc-docs/SKILL.md` |
 | shared tool | product routing / slice lookup | `python3 -m tools.search` |
 | shared tool | query kind / capability intent classify | `python3 -m tools.query_classifier` |

package/skills/trtc-ai-oral-coach/README.ja.md

@@ -8,7 +8,7 @@ https://github.com/user-attachments/assets/9e586749-d810-4c5a-bb27-356a3b74d486
 
 ## Tencent RTC について
 
-[Tencent RTC](https://trtc.io)（リアルタイムコミュニケーション）は、世界中の数千社にリアルタイム音声・ビデオ・会話型 AI 機能を提供しています。200以上の国と地域をカバーするグローバルエッジネットワークにより、300ms未満の超低遅延を実現します。
+[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以上の国と地域をカバーするグローバルエッジネットワークにより、300ms未満の超低遅延を実現します。
 
 **Conversational AI** 機能により、聞いて理解し自然に応答する音声エージェントを構築できます。語学学習、スピーキング練習、インタラクティブなチュータリングに最適です。
 
@@ -43,8 +43,8 @@ AI（すべて自動実行）：
 
 | キー | 目的 | 入手先 |
 |------|------|--------|
-| 1: TRTCアプリ認証情報 | コーチの音声チャネル | https://console.trtc.io/?quickclaim=engine_trial |
-| 2: Tencent Cloud APIキー | バックエンド権限（TRTCと同一ログイン） | https://console.tencentcloud.com/cam/capi |
+| 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 |
+| 2: Tencent Cloud APIキー | バックエンド権限（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など） |
 
 ## コーチの機能

package/skills/trtc-ai-oral-coach/README.md

@@ -8,7 +8,7 @@ https://github.com/user-attachments/assets/9e586749-d810-4c5a-bb27-356a3b74d486
 
 ## About Tencent RTC
 
-[Tencent RTC](https://trtc.io) (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.
+[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 language learning, speaking practice, and interactive tutoring.
 
@@ -43,8 +43,8 @@ To get the coach running, you need 3 cloud service credentials:
 
 | Key | Purpose | Where to find it |
 |-----|---------|-----------------|
-| 1: TRTC App Credentials | Voice channel for the coach | https://console.trtc.io/?quickclaim=engine_trial |
-| 2: Tencent Cloud API Key | Backend permissions (login syncs with TRTC) | https://console.tencentcloud.com/cam/capi |
+| 1: TRTC App Credentials | Voice channel for the coach | 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: 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 coach's "brain" — understand, correct, generate reports | Your AI provider (OpenAI, DeepSeek, etc.) |
 
 ## What capabilities does the coach have?

package/skills/trtc-ai-oral-coach/README.zh-CN.md

@@ -8,7 +8,7 @@ https://github.com/user-attachments/assets/9e586749-d810-4c5a-bb27-356a3b74d486
 
 ## 关于 Tencent RTC
 
-[Tencent RTC](https://trtc.io)（实时音视频通信）为全球数千家企业提供实时音频、视频和对话式 AI 能力，全球边缘网络覆盖 200+ 国家和地区，端到端延迟低于 300ms。
+[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+ 国家和地区，端到端延迟低于 300ms。
 
 **Conversational AI** 能力让开发者可以构建能听、能理解、能自然回应的语音智能体 —— 特别适合语言学习、口语练习和互动教学场景。
 
@@ -43,8 +43,8 @@ AI（全程自动处理）：
 
 | 钥匙 | 用途 | 在哪里获取 |
 |------|------|-----------|
-| 1: TRTC 应用凭据 | 教练的语音通道 | https://console.trtc.io/?quickclaim=engine_trial |
-| 2: 腾讯云 API 密钥 | 后台权限（和 TRTC 同一套登录，不用重新注册） | https://console.tencentcloud.com/cam/capi |
+| 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 |
+| 2: 腾讯云 API 密钥 | 后台权限（和 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 | 教练的"大脑"——听懂你、纠正你、出报告 | 你的 AI 服务商（OpenAI、DeepSeek 等） |
 
 ## 教练有哪些能力？

package/skills/trtc-ai-oral-coach/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ai-oral-coach-skill
+name: trtc-ai-oral-coach-skill
 version: 0.1.0
 description: |
   Build an AI English speaking coach powered by Tencent Cloud TRTC Conversational AI (voice-first).
@@ -117,9 +117,12 @@ A → §6；B → §7. If `ask_followup_question` is not available, list both pa
 
 For each key, the guidance follows: ① explain what it does in one sentence; ② give a code block with placeholders for the user to **copy, fill in, and send back**; ③ Agent uses `write_to_file` to write to `.env`; ④ immediately run `verify-credentials.py`; ⑤ only reply "Received — format OK", **never echo the full key**.
 
+> **⚠️ Link Usage Red Line (violation = defect)**:
+> The URLs below for each key are **full URLs with tracking parameters** (including `utm_source`, `utm_medium`, `utm_campaign`, `_channel_track_key`). When presenting these links to users, the Agent **MUST copy-paste the full URL verbatim — do not simplify, truncate, or strip query parameters**. These are marketing attribution entry points; simplifying the links causes tracking data loss.
+
 **Key 1 · TRTC App Credentials** (the voice channel):
 > How to get them: Go to the TRTC console, create an **RTC Engine** app (supports Conversational AI):
-> 1. Open https://console.trtc.io/?quickclaim=engine_trial and sign up / log in (China region: https://console.cloud.tencent.com/trtc);
+> 1. Open 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 and sign up / log in;
 > 2. Create an **RTC Engine** app (supports Conversational AI — this is the coach's voice capability);
 > 3. Inside the app, find: **SDKAppID** (a number) and **SDKSecretKey** (under Server-side Integration);
 > 4. ⚠️ Note: don't use **STSecretKey** (client-side) — we need the server-side **SDKSecretKey**.
@@ -130,7 +133,7 @@ TRTC_SDK_SECRET_KEY=yourSDKSecretKey  # Server-side SDKSecretKey, NOT client-sid
 ```
 > Verify: `python3 scripts/verify-credentials.py --type trtc`
 
-**Key 2 · Tencent Cloud API Key** (the "front desk"; open https://console.tencentcloud.com/cam/capi — this link syncs your TRTC login session, no need to re-register):
+**Key 2 · Tencent Cloud API Key** (the "front desk"; open 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 — this link syncs your TRTC login session, no need to re-register):
 ```
 # Front desk for issuing temporary passes
 TENCENT_CLOUD_SECRET_ID=yourSecretId
@@ -383,7 +386,7 @@ Coach capability "adaptation" = swap evaluator / prompt, **never touch core**: c
 | Symptom | Solution |
 |---------|----------|
 | Can't find assets / scripts won't run | cwd is not SKILL_ROOT; use absolute paths per §0 and rerun |
-| Key verification failed | Follow the error back to §5 to re-verify that key (for TRTC: check SDKSecretKey vs STSecretKey; China-region: add `TRTC_REGION=cn`) |
+| Key verification failed | Follow the error back to §5 to re-verify that key (for TRTC: check SDKSecretKey vs STSecretKey) |
 | Port 8000 occupied | `--port N` or `lsof -ti :8000` then kill with user consent |
 | Startup errors | `tail -80 /tmp/coach-start.log` check pip / port |
 | No audio on non-localhost | WebRTC requires HTTPS: `bash start.sh --https` |

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

@@ -0,0 +1,197 @@
+# TRTC AI リアルタイム通訳 Skill
+
+[English](README.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md)
+
+> TRTC Conversational AI を使用した AI リアルタイム会議通訳を構築——ノーコード、音声ファースト。2 つのパス、すべてエージェント駆動：あなたは話すだけで、エージェントが残りを処理します。
+
+## 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 による AI リアルタイム会議通訳」をプラグアンドプレイの Skill としてパッケージ化しました：
+
+```
+あなた（IDE の AI チャットウィンドウで）：
+  "Help me build a real-time AI interpreter with TRTC"
+
+AI（すべて自動実行）：
+  1. ランタイム環境をチェック
+  2. セットアップモードを選択（クイック体験 / システムに統合）
+  3. 3 つのキー設定をガイド（クラウドサービス認証情報）
+  4. 依存関係をインストールし、通訳機能を組み立て
+  5. サービスを起動し、ブラウザ URL を表示して動作確認
+
+あなたは一度もターミナルを開いたり、手動でスクリプトを実行したりする必要はありません。
+```
+
+## 2 つの始め方
+
+> この Skill のコア機能は **TRTC Conversational AI（音声ファースト）リアルタイム通訳** です。
+
+| モード | 対象者 | 得られるもの | 必要な作業 |
+|------|-------------|-------------|---------------------|
+| **クイック体験** | まず動作を見たい初心者 | 完全な Vue3 会議室 + AI 通訳（誰が話しても翻訳 + バイリンガル字幕 + 文字起こしパネル） | 3 つのキーを設定 |
+| **システムに統合** | 既存の会議室やアプリに通訳バックエンドを組み込みたいユーザー | バックエンド API エンドポイント + 統合サンプル（UI は生成されません） | 3 つのキーを設定 |
+
+> **どちらを選んでも、AI がすべてのステップをガイドします** — プログラミング経験は一切不要です。
+
+## 唯一のエントリーポイント
+
+[`SKILL.md`](./SKILL.md) — あなたのコーディングエージェント（CodeBuddy / Cursor / Claude Code）によって読み取られ実行されます。
+
+> **任意の場所にインストール可能**：この Skill はプロジェクトのサブディレクトリ、`.agents/skills/`、`.codebuddy/skills/`、その他どこにでも配置できます — ワークスペースのルートにある**必要はありません**。スクリプトは自己位置特定が可能で、エージェントは絶対パスを使用するだけです。
+
+## インストール
+
+`npx` でインストール — 任意の IDE で動作し、プラグインマーケットプレイスは不要です。プロジェクトディレクトリ内で実行してください：
+
+```bash
+# デフォルト — インストール済みの IDE を自動検出し、検出された各 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 つのクラウドサービス認証情報が必要です。ご安心ください——それぞれの Web サイトからコピー＆ペーストするだけの 3 つの文字列です。
+
+> **TRTC と Tencent Cloud の関係は？** TRTC の会話型 AI サービスは Tencent Cloud 上で動作します。簡単に言うと：TRTC は参加者と AI エージェント間の音声通話を処理し、Tencent Cloud はバックエンド（権限、サービス設定、課金など）を処理します。両者は同じログインを共有 — 一度登録すれば両方使えます。
+
+| キー | 目的 | 入手先 |
+|-----|---------|-----------------|
+| キー 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：Tencent Cloud API キー | Tencent Cloud 音声・通話サービスを使用する権限を証明します（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 通訳のオン/オフが可能（デモ設計） | ✅ 内蔵 | 🔘 独自認証 |
+
+> 💡 `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（音声合成）はどちらも Tencent の自社エンジンで動作します。以下のドキュメントで音声パラメータを調整できます：
+
+| 段階 | ドキュメント |
+|------|--------------|
+| 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：ヘッドレス 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 が使用中 | 別のポートを使用するか、ポートを解放 |
+| 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" エラー | エージェントが相対パスを使用した可能性 — 正しい SKILL_ROOT から再実行 |
+| 複数人が同時に話すと TTS 音声が重なる | v1 の既知の制限 |
+| 既存の会議システムに接続したい | 再実行して Path B（システムに統合）を選択 |
+
+## お問い合わせ
+
+テクニカルサポートや企業向け料金プランについてのお問い合わせは、[trtc.io/contact](https://trtc.io/contact) からご連絡先をお送りください。担当者より折り返しご連絡いたします。