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

package/skills/trtc-ai-realtime-interpreter/capabilities/meeting-ops/src/fanout.py

@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+"""扇出编排器：给定一组 targetUserId，批量起停 conversation-core 会话 + 维护房间级状态。
+
+职责边界（务必保持纯粹）：
+  - 只知道"批量起停会话 + 记住这个房间当前跑的是什么"，不知道"翻译""客服""会议纪要"
+    这些具体业务是什么 —— 具体业务能力包通过 `capability` 参数指定，本模块用
+    conversation-core 的 _capability_loader 动态加载该能力包的 `build_lifecycle_config`
+    约定函数（每个业务能力包都应该在自己的 service.py 里实现这个函数签名，参见
+    realtime-translation/src/service.py 的 build_lifecycle_config）。
+  - **完全不做权限校验**。"谁能调用扇出接口"是集成方自己业务系统的职责——本能力包
+    只是一个特权编排原语，调用方（比如 Path A 场景层的会议室 demo，或 Path B 集成方
+    自己的后端）必须在转发到这里之前，自行完成"调用者是否有权限触发"的校验。
+    参见 manifest.yaml 的安全声明与 README。
+
+状态存储：内存字典，demo/中小规模场景够用；生产场景如需持久化，由集成方自己接管
+（比如换成 Redis），本能力包不内置持久化适配。
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from threading import RLock
+from typing import Any, Dict, List, Optional
+
+_CORE_SRC = Path(__file__).resolve().parents[2] / "conversation-core" / "src"
+if str(_CORE_SRC) not in sys.path:
+    sys.path.insert(0, str(_CORE_SRC))
+
+from agent import ConversationAgent  # noqa: E402
+from _capability_loader import load_capability  # noqa: E402
+
+logger = logging.getLogger(__name__)
+
+
+class FanoutOrchestrator:
+    """房间级扇出编排器（内存态，单进程内单例即可）。"""
+
+    def __init__(self) -> None:
+        self._rooms: Dict[str, Dict[str, Any]] = {}
+        self._lock = RLock()
+
+    # ------------------------------------------------------------------
+    def start(
+        self,
+        agent: ConversationAgent,
+        room_id: str,
+        participants: List[str],
+        capability: str,
+        params: Dict[str, Any],
+        room_id_type: int = 1,
+        agent_user_id_prefix: str = "ai",
+    ) -> Dict[str, Any]:
+        """按参会人列表批量起会话。已有活跃扇出则先全部停掉再重开（幂等重启）。
+
+        capability: 业务能力包目录名（如 "realtime-translation"），必须实现
+                    `src/service.py` 里的 `build_lifecycle_config(params) -> AgentLifecycleConfig`。
+        params:     原样传给该能力包的 build_lifecycle_config，本模块不关心内容。
+        """
+        existing = self._rooms.get(room_id)
+        if existing:
+            self._stop_tasks(agent, existing.get("tasks", []))
+
+        service_mod = load_capability(capability, "src/service.py")
+        if not hasattr(service_mod, "build_lifecycle_config"):
+            raise ValueError(f"capability '{capability}' does not implement build_lifecycle_config(params)")
+
+        tasks: List[Dict[str, str]] = []
+        errors: List[Dict[str, str]] = []
+        for idx, target_user_id in enumerate(participants):
+            # 仅第一路播报欢迎语，避免多路 TTS 欢迎语在同一房间叠放
+            local_params = dict(params)
+            local_params.setdefault("suppress_welcome", idx != 0)
+            cfg = service_mod.build_lifecycle_config(local_params)
+            agent_uid = f"{agent_user_id_prefix}_{target_user_id[:16]}"[:32]
+            try:
+                info = agent.start(
+                    room_id=room_id,
+                    target_user_id=target_user_id,
+                    config=cfg,
+                    room_id_type=room_id_type,
+                    agent_user_id=agent_uid,
+                )
+                tasks.append({
+                    "session_id": info.session_id,
+                    "task_id": info.task_id or "",
+                    "agent_user_id": info.agent_user_id,
+                    "target_user_id": target_user_id,
+                })
+            except Exception as exc:  # noqa: BLE001
+                logger.error("fan-out start failed for target=%s: %s", target_user_id, exc)
+                errors.append({"target_user_id": target_user_id, "error": str(exc)})
+
+        # 全部失败时抛异常，让调用方（scenario backend）返回错误响应给前端
+        if not tasks and errors:
+            error_details = "; ".join(f"{e['target_user_id']}: {e['error']}" for e in errors)
+            raise RuntimeError(f"所有翻译会话启动均失败（{len(errors)}路全败）: {error_details}")
+
+        with self._lock:
+            self._rooms[room_id] = {"capability": capability, "params": params, "tasks": tasks}
+        logger.info("fanout started room=%s capability=%s tasks=%d", room_id, capability, len(tasks))
+        return {
+            "active": True,
+            "capability": capability,
+            "params": params,
+            "bots": [{"agentUserId": t["agent_user_id"], "targetUserId": t["target_user_id"]} for t in tasks],
+        }
+
+    # ------------------------------------------------------------------
+    def stop(self, agent: ConversationAgent, room_id: str) -> int:
+        with self._lock:
+            room = self._rooms.pop(room_id, None)
+        if not room:
+            return 0
+        return self._stop_tasks(agent, room.get("tasks", []))
+
+    def _stop_tasks(self, agent: ConversationAgent, tasks: List[Dict[str, str]]) -> int:
+        stopped = 0
+        for t in tasks:
+            try:
+                agent.stop(t["session_id"])
+                stopped += 1
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("stop session %s failed: %s", t.get("session_id"), exc)
+        return stopped
+
+    # ------------------------------------------------------------------
+    def state(self, room_id: str) -> Dict[str, Any]:
+        with self._lock:
+            room = self._rooms.get(room_id)
+        if not room:
+            return {"active": False, "capability": None, "params": {}, "bots": []}
+        return {
+            "active": True,
+            "capability": room["capability"],
+            "params": room["params"],
+            "bots": [{"agentUserId": t["agent_user_id"], "targetUserId": t["target_user_id"]} for t in room.get("tasks", [])],
+        }
+
+
+# 单进程内共享单例（跟 conversation-core 的 Agent 单例模式一致）
+_orchestrator: Optional[FanoutOrchestrator] = None
+
+
+def get_orchestrator() -> FanoutOrchestrator:
+    global _orchestrator
+    if _orchestrator is None:
+        _orchestrator = FanoutOrchestrator()
+    return _orchestrator

package/skills/trtc-ai-realtime-interpreter/capabilities/meeting-ops/src/router.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""meeting-ops 的 FastAPI 子路由：扇出编排的 HTTP 接口。
+
+挂载于 conversation-core 的 /api/v1/meeting 前缀下（见 conversation-core/src/server.py）。
+
+安全提示（务必阅读 README/manifest 的安全声明）：
+  这些接口是**特权操作端点**，本能力包不做任何调用者身份/权限校验。
+  集成方必须在自己的后端完成"调用者是否有权触发"的校验后，才转发请求到这里
+  （例如：先校验 JWT/Session 里的角色是房主/管理员，再调用 /api/v1/meeting/session/start）。
+  Path A 的会议室 demo 场景里，这层校验由 scenarios/meeting-interpreter 的 demo 专属
+  glue 代码实现（内存字典房主登记），不属于本能力包。
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import BaseModel
+
+_SRC_DIR = Path(__file__).resolve().parent
+if str(_SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(_SRC_DIR))
+
+from fanout import get_orchestrator  # noqa: E402
+
+router = APIRouter()
+
+
+def _require_agent(request: Request):
+    agent = getattr(request.app.state, "conversation_agent", None)
+    if agent is None:
+        raise HTTPException(status_code=503, detail={"code": "credentials_missing", "message": "conversation-core not initialized"})
+    return agent
+
+
+class SessionStartRequest(BaseModel):
+    room_id: str
+    room_id_type: int = 1
+    participants: List[str]
+    capability: str = "realtime-translation"
+    params: Dict[str, Any] = {}
+
+
+class SessionStopRequest(BaseModel):
+    room_id: str
+
+
+@router.post("/session/start")
+def session_start(req: SessionStartRequest, request: Request) -> Dict[str, Any]:
+    agent = _require_agent(request)
+    orchestrator = get_orchestrator()
+    if not req.participants:
+        raise HTTPException(status_code=400, detail="participants must not be empty")
+    try:
+        result = orchestrator.start(
+            agent=agent,
+            room_id=req.room_id,
+            participants=req.participants,
+            capability=req.capability,
+            params=req.params,
+            room_id_type=req.room_id_type,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(exc))
+    return {"code": 0, "msg": "success", "data": result}
+
+
+@router.post("/session/stop")
+def session_stop(req: SessionStopRequest, request: Request) -> Dict[str, Any]:
+    agent = _require_agent(request)
+    orchestrator = get_orchestrator()
+    stopped = orchestrator.stop(agent, req.room_id)
+    return {"code": 0, "msg": "success", "data": {"stopped": stopped}}
+
+
+@router.get("/session/state")
+def session_state(room_id: str = Query(...)) -> Dict[str, Any]:
+    orchestrator = get_orchestrator()
+    return {"code": 0, "data": orchestrator.state(room_id)}

package/skills/trtc-ai-realtime-interpreter/capabilities/realtime-translation/frontend/subtitle-parser.ts

@@ -0,0 +1,145 @@
+/**
+ * 实时翻译字幕/状态自定义消息解析器（框架无关，不依赖任何 UI 库）。
+ *
+ * TRTC Conversational AI 通过 CUSTOM_MESSAGE 广播两类消息：
+ *   - cmd 10000：字幕（可能是某个真人的 ASR 原文，也可能是 AI 的译文/欢迎语）
+ *   - cmd 10001：AI 状态（1=本轮结束 / 2=思考中(翻译中) / 3=正在播报）
+ *
+ * sender 归属判断：消息载荷里的 `data.sender` 是"逻辑发送者"（真人的 userId 或
+ * bot 的 userId），不是 TRTC 传输层的 event.userId（后者在单目标模式下也可能不是
+ * 真正的说话人）。命中 botUserIds 集合 -> 认为是 AI 译文；否则是某个真人的原文。
+ *
+ * 使用方式：
+ *   const parser = createSubtitleParser({
+ *     isBot: (userId) => botUserIds.has(userId),
+ *     resolveSpeakerName: (userId) => participantList.find(...)?.nameCard || userId,
+ *     onBubbleUpdate: (bubble) => { ... },      // 当前气泡（说话人/原文/译文）更新
+ *     onArchive: (item) => { ... },              // 一轮结束，归档一条完整转写记录
+ *     onAgentState: (state) => { ... },           // idle/listen/translate/speak
+ *   })
+ *   silentListener.onCustomMessage((event) => parser.handle(event))
+ */
+
+export type AgentState = 'idle' | 'listen' | 'translate' | 'speak'
+
+export interface TranscriptItem {
+  speaker: string
+  orig: string
+  trans: string
+  time: string
+}
+
+export interface CurrentBubble {
+  speaker: string
+  orig: string
+  trans: string
+}
+
+export interface SubtitleParserOptions {
+  /** 判断某个 userId 是否为 AI bot 身份 */
+  isBot: (userId: string) => boolean
+  /** 把真人 userId 解析成展示名（昵称），找不到则原样返回 userId */
+  resolveSpeakerName: (userId: string) => string
+  /** 计时起点距今的 mm:ss 格式化（调用方可传入自己的计时逻辑），默认从第一次调用起计时 */
+  nowTime?: () => string
+  onBubbleUpdate?: (bubble: CurrentBubble) => void
+  onArchive?: (item: TranscriptItem) => void
+  onAgentState?: (state: AgentState) => void
+}
+
+export interface SubtitleParserHandle {
+  handle: (event: any) => void
+  reset: () => void
+  getTranscript: () => TranscriptItem[]
+  getCurrentBubble: () => CurrentBubble
+}
+
+function defaultNowTime(startRef: { ts: number }) {
+  return () => {
+    if (!startRef.ts) startRef.ts = Date.now()
+    const t = Math.floor((Date.now() - startRef.ts) / 1000)
+    const m = String(Math.floor(t / 60)).padStart(2, '0')
+    const s = String(t % 60).padStart(2, '0')
+    return `${m}:${s}`
+  }
+}
+
+export function createSubtitleParser(opts: SubtitleParserOptions): SubtitleParserHandle {
+  const transcript: TranscriptItem[] = []
+  let curSpeaker = ''
+  let curOrig = ''
+  let curTrans = ''
+  const startRef = { ts: 0 }
+  const nowTime = opts.nowTime || defaultNowTime(startRef)
+
+  function emitBubble() {
+    opts.onBubbleUpdate?.({ speaker: curSpeaker, orig: curOrig, trans: curTrans })
+  }
+
+  function handle(event: any): void {
+    let text: string
+    try {
+      text = new TextDecoder().decode(event.data)
+    } catch {
+      return
+    }
+    let data: any
+    try {
+      data = JSON.parse(text)
+    } catch {
+      return
+    }
+    const sender: string = data.sender || event.userId || ''
+    const payload = data.payload || {}
+
+    if (data.type === 10000) {
+      const raw = (payload.text || '').trim()
+      if (!raw) return
+      if (opts.isBot(sender)) {
+        if (!curSpeaker) curSpeaker = 'AI Interpreter'
+        curTrans = raw
+        emitBubble()
+        opts.onAgentState?.('speak')
+      } else {
+        curSpeaker = opts.resolveSpeakerName(sender)
+        curOrig = raw
+        emitBubble()
+        if (payload.end !== true) opts.onAgentState?.('translate')
+      }
+    } else if (data.type === 10001) {
+      const st = payload.state
+      if (st === 1) {
+        if (curOrig || curTrans) {
+          const item: TranscriptItem = { speaker: curSpeaker || 'AI Interpreter', orig: curOrig, trans: curTrans, time: nowTime() }
+          transcript.push(item)
+          opts.onArchive?.(item)
+        }
+        curSpeaker = ''
+        curOrig = ''
+        curTrans = ''
+        emitBubble()
+        opts.onAgentState?.('listen')
+      } else if (st === 2) {
+        opts.onAgentState?.('translate')
+      } else if (st === 3) {
+        opts.onAgentState?.('speak')
+      }
+    }
+  }
+
+  function reset(): void {
+    transcript.length = 0
+    curSpeaker = ''
+    curOrig = ''
+    curTrans = ''
+    startRef.ts = 0
+    emitBubble()
+  }
+
+  return {
+    handle,
+    reset,
+    getTranscript: () => transcript,
+    getCurrentBubble: () => ({ speaker: curSpeaker, orig: curOrig, trans: curTrans }),
+  }
+}

package/skills/trtc-ai-realtime-interpreter/capabilities/realtime-translation/manifest.yaml

@@ -0,0 +1,68 @@
+# realtime-translation 能力自描述 manifest
+# 类型：业务能力（可选安装）——「翻译」这件事本身，跟会议/客服/直播场景无关
+
+name: "realtime-translation"
+version: "1.0.0"
+type: "capability"
+description: "语言对驱动的实时翻译逻辑：STT 语种/翻译 system_prompt/TTS 音色选型 + 字幕自定义消息解析。单目标场景可独立使用，多目标扇出场景由 meeting-ops 调用本能力的约定接口。"
+
+dependencies:
+  - name: "conversation-core"
+    version: ">=1.0.0,<2.0.0"
+
+# ---------------------------------------------------------------------------
+# 约定接口（供 meeting-ops 等编排能力动态调用，而非直接依赖）
+# ---------------------------------------------------------------------------
+provides:
+  starter_capability:
+    module: "src/service.py"
+    function: "build_lifecycle_config"
+    description: >
+      入参 {mode, suppress_welcome?, max_idle_time?} -> 返回 conversation-core 的
+      AgentLifecycleConfig。任何"批量起会话"的编排能力（如 meeting-ops）都可以通过
+      _capability_loader 动态加载本模块并调用这个函数，而不需要认识"翻译"这个具体业务。
+
+# ---------------------------------------------------------------------------
+# 配置
+# ---------------------------------------------------------------------------
+config:
+  modes:
+    description: "语言对配置（zh-en / zh-yue / en-yue），定义于 src/modes.py"
+    extensible: true
+
+# ---------------------------------------------------------------------------
+# 对外暴露的 API（单目标场景）
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: GET
+    path: /api/v1/translation/modes
+    description: 列出可用语言对
+  - method: POST
+    path: /api/v1/translation/start
+    description: 给单一目标（主播/客服/任意 user）起一路翻译会话
+  - method: POST
+    path: /api/v1/translation/stop
+    description: 停止该翻译会话
+
+# ---------------------------------------------------------------------------
+# 前端资产（框架无关，供 Path A Vue 封装 / Path B 各技术栈适配器复用）
+# ---------------------------------------------------------------------------
+frontend_assets:
+  - path: "frontend/subtitle-parser.ts"
+    description: "解析 cmd 10000 字幕 / cmd 10001 AI 状态自定义消息，按 sender 归属（bot 集合 vs 真人）拼装双语气泡并归档转写记录。框架无关，不依赖任何 UI 库。"
+
+# ---------------------------------------------------------------------------
+# 业务契约：无外部业务系统依赖（纯逻辑 + 复用 conversation-core 的平台级依赖）
+# ---------------------------------------------------------------------------
+business_contract:
+  external_apis: []
+
+security:
+  log_redaction:
+    enabled: true
+    patterns: ["usersig", "api_key"]
+
+acceptance:
+  - "build_lifecycle_config 是稳定的约定接口，meeting-ops 只依赖这个函数签名，不感知 modes.py 内部实现"
+  - "单目标场景可以只装 conversation-core + realtime-translation，不依赖 meeting-ops"
+  - "字幕解析模块不依赖任何前端框架，可被 Vue/React/纯JS 三种 Path A/B 场景复用"

package/skills/trtc-ai-realtime-interpreter/capabilities/realtime-translation/src/modes.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""实时翻译的语言对配置：STT 识别语种 + 翻译 system_prompt + TTS 音色。
+
+这是「翻译」这件事本身的业务知识，跟会议/客服/直播场景无关——单目标场景
+（比如给一个主播/客服配一个翻译）或多目标扇出场景（会议室）都复用同一套配置。
+
+音色全部来自 TRTC 对话式 AI 内置 TTS 音色库（flow_01_turbo，trtc.io/document/79682），
+全程闭环在 TRTC 生态内，不引入外部 TTS 服务。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+_WELCOME_DEFAULT = (
+    "Hello, I'm your AI interpreter. I'll translate everything you say in real-time. "
+    "Please go ahead and speak."
+)
+
+MODE_CONFIG: Dict[str, Dict[str, Any]] = {
+    "zh-en": {
+        "source_label": "Chinese", "target_label": "English",
+        "stt_language": "zh",
+        "tts_voice": "v-female-p9Xy7Q1L",
+        "welcome": _WELCOME_DEFAULT,
+        "system_prompt": (
+            "You are a professional real-time interpreter. "
+            "The user may speak either Mandarin Chinese or English. "
+            "Detect the language of each sentence and translate it into the OTHER language "
+            "(Chinese -> English, English -> Chinese). "
+            "Reply with ONLY the translation — no greetings, no explanations, "
+            "no extra commentary, no quotation marks."
+        ),
+    },
+    "zh-yue": {
+        "source_label": "Chinese", "target_label": "Cantonese",
+        "stt_language": "zh",
+        "tts_voice": "v-female-k3P8sL0Q",
+        "welcome": _WELCOME_DEFAULT,
+        "system_prompt": (
+            "You are a professional real-time interpreter. "
+            "The user may speak either Mandarin Chinese or Cantonese. "
+            "Detect the language of each sentence and translate it into the OTHER language "
+            "(Mandarin -> Cantonese written form, Cantonese -> Mandarin). "
+            "Reply with ONLY the translation — no greetings, no explanations, "
+            "no extra commentary, no quotation marks."
+        ),
+    },
+    "en-yue": {
+        "source_label": "English", "target_label": "Cantonese",
+        "stt_language": "en",
+        "tts_voice": "v-female-k3P8sL0Q",
+        "welcome": _WELCOME_DEFAULT,
+        "system_prompt": (
+            "You are a professional real-time interpreter. "
+            "The user may speak either English or Cantonese. "
+            "Detect the language of each sentence and translate it into the OTHER language "
+            "(English -> Cantonese written form, Cantonese -> English). "
+            "Reply with ONLY the translation — no greetings, no explanations, "
+            "no extra commentary, no quotation marks."
+        ),
+    },
+}
+
+
+def list_modes() -> Dict[str, Dict[str, str]]:
+    return {k: {"source_label": v["source_label"], "target_label": v["target_label"]} for k, v in MODE_CONFIG.items()}
+
+
+def get_mode(mode_id: str) -> Dict[str, Any]:
+    mode = MODE_CONFIG.get(mode_id)
+    if not mode:
+        raise ValueError(f"unknown mode_id: {mode_id!r}, available: {list(MODE_CONFIG.keys())}")
+    return mode

package/skills/trtc-ai-realtime-interpreter/capabilities/realtime-translation/src/router.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""realtime-translation 的 FastAPI 子路由：单目标翻译场景的 HTTP 接口。
+
+挂载于 conversation-core 的 /api/v1/translation 前缀下（见 conversation-core/src/server.py）。
+面向"给一个人配一路翻译"的场景（主播/客服/任意单一目标），不涉及会议扇出——
+多目标扇出场景请用 meeting-ops，它会直接调用 service.py 里的 build_lifecycle_config()
+约定接口，不走这里的 HTTP 层。
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+_SRC_DIR = Path(__file__).resolve().parent
+if str(_SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(_SRC_DIR))
+
+from service import list_modes, start_translation  # noqa: E402
+
+router = APIRouter()
+
+
+def _require_agent(request: Request):
+    agent = getattr(request.app.state, "conversation_agent", None)
+    if agent is None:
+        raise HTTPException(status_code=503, detail={"code": "credentials_missing", "message": "conversation-core not initialized"})
+    return agent
+
+
+class TranslationStartRequest(BaseModel):
+    room_id: str
+    room_id_type: int = 0
+    target_user_id: str
+    mode: str
+    agent_user_id: Optional[str] = None
+
+
+class TranslationStopRequest(BaseModel):
+    session_id: str
+
+
+@router.get("/modes")
+def get_modes() -> Dict[str, Any]:
+    return {"code": 0, "data": list_modes()}
+
+
+@router.post("/start")
+def translation_start(req: TranslationStartRequest, request: Request) -> Dict[str, Any]:
+    agent = _require_agent(request)
+    try:
+        info = start_translation(
+            agent=agent,
+            room_id=req.room_id,
+            target_user_id=req.target_user_id,
+            mode=req.mode,
+            room_id_type=req.room_id_type,
+            agent_user_id=req.agent_user_id,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(exc))
+    return {
+        "code": 0, "msg": "success",
+        "data": {
+            "session_id": info.session_id, "task_id": info.task_id,
+            "agent_user_id": info.agent_user_id, "mode": req.mode, "status": "started",
+        },
+    }
+
+
+@router.post("/stop")
+def translation_stop(req: TranslationStopRequest, request: Request) -> Dict[str, Any]:
+    agent = _require_agent(request)
+    try:
+        agent.stop(req.session_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {"code": 0, "msg": "success", "data": {"session_id": req.session_id, "status": "stopped"}}

package/skills/trtc-ai-realtime-interpreter/capabilities/realtime-translation/src/service.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""实时翻译服务：把「翻译」这件事翻成 conversation-core 认得的启动参数。
+
+对外提供两类接口：
+  1. `build_lifecycle_config(params)` —— **约定接口**，meeting-ops 的扇出编排器会通过
+     _capability_loader 动态加载本模块并调用这个函数，拿到 AgentLifecycleConfig 后自己去调
+     conversation-core 起会话。这样 meeting-ops 完全不需要认识"翻译"这个概念，只认识
+     "给我一个启动配置"这个约定。
+  2. `start_translation(agent, ...)` —— 单目标场景的直接调用封装（配合 router.py 的
+     HTTP 接口），给主播/客服配一个翻译时用，不涉及 meeting-ops。
+
+welcome_message 的多路去重规则由调用方（router 或 meeting-ops）决定，本模块只提供
+"第一路播报欢迎语，其余路静音"的可选参数，不擅自假设场景。
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+_CORE_SRC = Path(__file__).resolve().parents[2] / "conversation-core" / "src"
+if str(_CORE_SRC) not in sys.path:
+    sys.path.insert(0, str(_CORE_SRC))
+
+from agent import ConversationAgent, SessionInfo  # noqa: E402
+from trtc_client import AgentLifecycleConfig  # noqa: E402
+
+from modes import get_mode, list_modes  # noqa: E402
+
+__all__ = ["build_lifecycle_config", "start_translation", "list_modes"]
+
+
+def build_lifecycle_config(params: Dict[str, Any]) -> AgentLifecycleConfig:
+    """约定接口：把 {mode, suppress_welcome?} 换成 AgentLifecycleConfig。
+
+    被 meeting-ops 的扇出编排器动态调用（见 meeting-ops/src/fanout.py 里的
+    `starter_capability` 约定），也被本模块自己的 start_translation() 复用。
+    """
+    mode_id = params.get("mode")
+    if not mode_id:
+        raise ValueError("params.mode is required")
+    mode = get_mode(mode_id)
+    suppress_welcome = bool(params.get("suppress_welcome", False))
+    tts_enabled = bool(params.get("tts_enabled", True))
+    return AgentLifecycleConfig(
+        instructions=mode["system_prompt"],
+        greeting=mode["welcome"],
+        welcome_message="" if suppress_welcome else mode["welcome"],
+        language=mode["stt_language"],
+        voice_id=mode["tts_voice"],
+        max_idle_time=int(params.get("max_idle_time", 60)),
+        tts_enabled=tts_enabled,
+    )
+
+
+def start_translation(
+    agent: ConversationAgent,
+    room_id: str,
+    target_user_id: str,
+    mode: str,
+    room_id_type: int = 0,
+    agent_user_id: Optional[str] = None,
+    suppress_welcome: bool = False,
+) -> SessionInfo:
+    """单目标翻译场景：给一个人（主播/客服/任意 target_user_id）配一路翻译。
+
+    不涉及"参会人列表""房主"等会议概念——这些是 meeting-ops 的职责，本函数
+    只管"起一路翻译会话"这一件事。
+    """
+    cfg = build_lifecycle_config({"mode": mode, "suppress_welcome": suppress_welcome})
+    return agent.start(
+        room_id=room_id,
+        target_user_id=target_user_id,
+        config=cfg,
+        room_id_type=room_id_type,
+        agent_user_id=agent_user_id,
+    )