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

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/server.py

@@ -0,0 +1,266 @@
+# -*- coding: utf-8 -*-
+"""FastAPI 入口：骨架 REST API + 能力包路由挂载 + 静态 Web Demo 托管。
+
+骨架路由：
+  GET  /api/v1/health          —— 三把钥匙连通性自检
+  POST /api/v1/usersig         —— 给任意 user_id 签发 UserSig（通用工具，供旁听/多身份场景使用）
+  POST /api/v1/agent/start     —— 起一路 Conversational AI 会话（单目标）
+  POST /api/v1/agent/stop      —— 停一路会话
+  POST /api/v1/agent/control   —— 文本注入 / 打断
+  GET  /api/v1/sessions        —— 内存态会话列表（调试用）
+  GET  /                       —— Web Demo 静态页
+
+设计原则：
+  - 骨架只做协议编排，不内置任何行业 prompt / 语言对 / 权限逻辑。
+  - 通过 app.state.conversation_agent 把 Agent 单例暴露给能力包路由（比模块级单例更适合
+    FastAPI 的依赖注入习惯，能力包路由用 `request.app.state.conversation_agent` 取用）。
+  - 能力包路由通过 _capability_loader 动态加载，未安装时静默跳过，不影响骨架启动。
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from dotenv import load_dotenv
+
+_BASE_DIR = Path(__file__).resolve().parent.parent  # capabilities/conversation-core/
+_SRC_DIR = Path(__file__).resolve().parent
+if str(_SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(_SRC_DIR))
+
+load_dotenv(_BASE_DIR / ".env.local")
+load_dotenv(_BASE_DIR / ".env")
+
+from fastapi import APIRouter, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from agent import ConversationAgent
+from credentials import load_from_env
+from health import check_all
+from log_filter import install_redacting_filter
+from trtc_client import AgentLifecycleConfig
+
+logger = logging.getLogger("conversation_core")
+logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO"), format="%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+install_redacting_filter(logging.getLogger())
+
+_credentials = load_from_env()
+_agent: Optional[ConversationAgent] = None
+_init_error: Optional[str] = None
+try:
+    _agent = ConversationAgent(_credentials)
+    logger.info("ConversationAgent initialized")
+except Exception as exc:  # noqa: BLE001
+    _init_error = str(exc)
+    logger.warning("ConversationAgent not initialized: %s", _init_error)
+
+
+# ---------------------------------------------------------------------------
+# Pydantic Models
+# ---------------------------------------------------------------------------
+class UserSigRequest(BaseModel):
+    user_id: str
+
+
+class AgentStartRequest(BaseModel):
+    room_id: str
+    room_id_type: int = 0
+    target_user_id: str
+    agent_user_id: Optional[str] = None
+    instructions: Optional[str] = None
+    greeting: Optional[str] = None
+    language: Optional[str] = "zh"
+    voice_id: Optional[str] = None
+    max_idle_time: Optional[int] = 60
+
+
+class AgentStopRequest(BaseModel):
+    session_id: str
+
+
+class ControlRequest(BaseModel):
+    session_id: str
+    text: str
+    interrupt: bool = True
+
+
+# ---------------------------------------------------------------------------
+# FastAPI App
+# ---------------------------------------------------------------------------
+app = FastAPI(
+    title="conversation-core",
+    version="1.0.0",
+    description="TRTC Conversational AI 通用骨架（拉起单路会话并连通，无行业假设）",
+)
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
+
+# 把 Agent 单例挂到 app.state，供能力包路由通过 request.app.state.conversation_agent 取用
+app.state.conversation_agent = _agent
+app.state.credentials = _credentials
+
+api = APIRouter(prefix="/api/v1")
+
+
+def _to_http_error(exc: Exception) -> HTTPException:
+    if isinstance(exc, ValueError):
+        return HTTPException(status_code=400, detail=str(exc))
+    if isinstance(exc, RuntimeError):
+        return HTTPException(status_code=500, detail=str(exc))
+    return HTTPException(status_code=500, detail=f"internal: {exc}")
+
+
+def require_agent(request: Request) -> ConversationAgent:
+    """能力包路由可直接复用这个依赖函数：request.app.state.conversation_agent。"""
+    agent = getattr(request.app.state, "conversation_agent", None)
+    if agent is None:
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "code": "credentials_missing",
+                "message": _init_error or "credentials not configured",
+                "hint": "在 .env 里配好三把钥匙（TRTC / 腾讯云 / LLM）后重启",
+            },
+        )
+    return agent
+
+
+# ---------------------------------------------------------------------------
+# Health
+# ---------------------------------------------------------------------------
+@api.get("/health")
+def health() -> Dict[str, Any]:
+    cred = load_from_env()
+    tc, trtc, llm = check_all(cred.tencent_cloud, cred.trtc, cred.llm)
+    overall = "ok" if tc.ok and trtc.ok and llm.ok else "partial_failure"
+    return {
+        "status": overall,
+        "checks": {"tencent_cloud": tc.to_dict(), "trtc": trtc.to_dict(), "llm": llm.to_dict()},
+        "configured": cred.fully_configured,
+        "missing": cred.missing(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# UserSig（通用签发，供旁听客户端 / 多身份场景使用）
+# ---------------------------------------------------------------------------
+@api.post("/usersig")
+def issue_usersig(req: UserSigRequest, request: Request) -> Dict[str, Any]:
+    agent = require_agent(request)
+    if not req.user_id or not req.user_id.strip():
+        raise HTTPException(status_code=400, detail="user_id is required")
+    user_id = req.user_id.strip()[:32]
+    sig = agent.issue_user_sig(user_id)
+    return {"sdk_app_id": agent.sdk_app_id, "user_id": user_id, "user_sig": sig}
+
+
+# ---------------------------------------------------------------------------
+# 单路会话生命周期
+# ---------------------------------------------------------------------------
+@api.post("/agent/start")
+def agent_start(req: AgentStartRequest, request: Request) -> Dict[str, Any]:
+    agent = require_agent(request)
+    try:
+        defaults = AgentLifecycleConfig()
+        cfg = AgentLifecycleConfig(
+            instructions=req.instructions or defaults.instructions,
+            greeting=req.greeting or defaults.greeting,
+            language=req.language or "zh",
+            voice_id=req.voice_id or "",
+            max_idle_time=req.max_idle_time or 60,
+        )
+        info = agent.start(
+            room_id=req.room_id,
+            target_user_id=req.target_user_id,
+            config=cfg,
+            room_id_type=req.room_id_type,
+            agent_user_id=req.agent_user_id,
+        )
+        return {
+            "code": 0, "msg": "success",
+            "data": {
+                "session_id": info.session_id, "task_id": info.task_id, "request_id": info.request_id,
+                "agent_user_id": info.agent_user_id, "status": "started",
+            },
+        }
+    except Exception as exc:  # noqa: BLE001
+        raise _to_http_error(exc)
+
+
+@api.post("/agent/stop")
+def agent_stop(req: AgentStopRequest, request: Request) -> Dict[str, Any]:
+    agent = require_agent(request)
+    try:
+        agent.stop(req.session_id)
+        return {"code": 0, "msg": "success", "data": {"session_id": req.session_id, "status": "stopped"}}
+    except Exception as exc:  # noqa: BLE001
+        raise _to_http_error(exc)
+
+
+@api.post("/agent/control")
+def agent_control(req: ControlRequest, request: Request) -> Dict[str, Any]:
+    agent = require_agent(request)
+    try:
+        return {"code": 0, "msg": "success", "data": agent.control(req.session_id, req.text, req.interrupt)}
+    except Exception as exc:  # noqa: BLE001
+        raise _to_http_error(exc)
+
+
+@api.get("/sessions")
+def sessions_list(request: Request) -> Dict[str, Any]:
+    agent = require_agent(request)
+    return {"code": 0, "data": agent.list_sessions()}
+
+
+app.include_router(api)
+
+# ---------------------------------------------------------------------------
+# 能力包路由挂载（可选；动态加载，未安装时静默跳过）
+# ---------------------------------------------------------------------------
+from _capability_loader import try_load_capability as _try_load_capability  # noqa: E402
+
+# [realtime-translation] 挂子路由
+_rt_router_mod = _try_load_capability("realtime-translation", "src/router.py")
+if _rt_router_mod is not None and hasattr(_rt_router_mod, "router"):
+    app.include_router(_rt_router_mod.router, prefix="/api/v1/translation", tags=["realtime-translation"])
+
+# [meeting-ops] 挂子路由
+_mo_router_mod = _try_load_capability("meeting-ops", "src/router.py")
+if _mo_router_mod is not None and hasattr(_mo_router_mod, "router"):
+    app.include_router(_mo_router_mod.router, prefix="/api/v1/meeting", tags=["meeting-ops"])
+
+
+# ---------------------------------------------------------------------------
+# 静态前端：可用 WEB_DEMO_DIR 覆盖（Path A 场景层会把它指向自己的 UI 构建产物）
+# ---------------------------------------------------------------------------
+_DEMO_DIR = Path(os.getenv("WEB_DEMO_DIR", str(_BASE_DIR / "web-demo")))
+if _DEMO_DIR.exists():
+    app.mount("/static", StaticFiles(directory=str(_DEMO_DIR), html=True), name="static")
+
+    @app.get("/")
+    def index() -> FileResponse:
+        return FileResponse(str(_DEMO_DIR / "index.html"))
+
+
+def main() -> None:
+    import uvicorn
+
+    port = int(os.getenv("PORT", "8020"))
+    host = os.getenv("HOST", "0.0.0.0")
+    cert_file = _BASE_DIR.parent.parent / "cert.pem"
+    key_file = _BASE_DIR.parent.parent / "key.pem"
+    if cert_file.exists() and key_file.exists():
+        logger.info("Starting HTTPS server (cert=%s)", cert_file)
+        uvicorn.run(app, host=host, port=port, ssl_certfile=str(cert_file), ssl_keyfile=str(key_file))
+    else:
+        logger.info("Starting HTTP server (no cert.pem/key.pem found)")
+        uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/trtc_client.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""TRTC Conversational AI 控制面客户端（使用 tencentcloud-sdk-python 官方 SDK）。
+
+封装 StartAIConversation / StopAIConversation / ControlAIConversation 三个接口。
+骨架层只做「协议封装 + 密钥签名」，不内置任何 system_prompt / 语言对 / 行业知识——
+这些由上层业务能力包（如 realtime-translation）通过 AgentLifecycleConfig 参数传入。
+
+使用官方 SDK 而非手写 REST，确保请求格式与腾讯云服务端完全兼容
+（手写 REST 在某些参数组合下可能触发 UserSig 校验异常）。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from tencentcloud.common import credential
+from tencentcloud.common.profile.client_profile import ClientProfile
+from tencentcloud.common.profile.http_profile import HttpProfile
+from tencentcloud.trtc.v20190722 import trtc_client, models
+
+from credentials import LlmCredential, TencentCloudCredential, TrtcCredential
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentLifecycleConfig:
+    """单路会话的启动参数（业务无关；具体 system_prompt/语言对由上层能力包填入）。"""
+
+    instructions: str = "You are a helpful voice assistant. Reply briefly."
+    greeting: str = "Hello, how can I help you?"
+    max_idle_time: int = 60
+    welcome_message: str = ""
+    language: str = "zh"           # STT 识别语种
+    voice_id: str = ""             # 空 -> DEFAULT_VOICE_IDS 按 language 选取
+    tts_model: str = "flow_01_turbo"
+    tts_enabled: bool = True       # False 时跳过 TTSConfig（只有字幕，不播报语音）
+    llm_extra: Dict[str, Any] = field(default_factory=dict)   # 额外透传给 LLMConfig 的字段（如 Temperature）
+
+
+# TRTC FlowTTS 内置音色（trtc.io/document/79682）
+DEFAULT_VOICE_IDS = {
+    ("en", "female"): "v-female-p9Xy7Q1L",
+    ("en", "male"): "v-male-A4b9KqP2",
+    ("zh", "female"): "female-kefu-xiaoyue",
+    ("zh", "male"): "male-kefu-xiaoxu",
+}
+
+
+class TrtcConversationClient:
+    """TRTC Conversational AI 控制面的轻量封装（使用官方 SDK）。"""
+
+    def __init__(self, tencent: TencentCloudCredential, trtc: TrtcCredential, llm: LlmCredential) -> None:
+        if not tencent.configured:
+            raise ValueError("tencent cloud credential not configured")
+        if not trtc.configured:
+            raise ValueError("trtc credential not configured")
+        if not llm.configured:
+            raise ValueError("llm credential not configured")
+        self.tencent = tencent
+        self.trtc = trtc
+        self.llm = llm
+        # 用官方 SDK 创建 client（跟原 demo translator_agent.py 完全一致的方式）
+        cred = credential.Credential(tencent.secret_id, tencent.secret_key)
+        http = HttpProfile()
+        http.endpoint = trtc.trtc_endpoint
+        cp = ClientProfile()
+        cp.httpProfile = http
+        self._api = trtc_client.TrtcClient(cred, trtc.trtc_region, cp)
+
+    # ------------------------------------------------------------------
+    # StartAIConversation
+    # ------------------------------------------------------------------
+    def start(
+        self,
+        room_id: str,
+        agent_user_id: str,
+        agent_user_sig: str,
+        target_user_id: str,
+        config: Optional[AgentLifecycleConfig] = None,
+        room_id_type: int = 0,
+    ) -> Dict[str, Any]:
+        cfg = config or AgentLifecycleConfig()
+        voice_id = cfg.voice_id or DEFAULT_VOICE_IDS.get((cfg.language, "female"), DEFAULT_VOICE_IDS[("en", "female")])
+
+        llm_cfg: Dict[str, Any] = {
+            "LLMType": self.llm.llm_type,
+            "Model": self.llm.model,
+            "APIKey": self.llm.api_key,
+            "APIUrl": self.llm.api_url,
+            "Streaming": True,
+            "SystemPrompt": cfg.instructions,
+            "History": 6,
+            "Temperature": 0.2,
+        }
+        llm_cfg.update(cfg.llm_extra or {})
+
+        # AgentConfig 参数对齐原 demo translator_agent.py（已验证跑通的参数组合）
+        agent_cfg = {
+            "UserId": agent_user_id,
+            "UserSig": agent_user_sig,
+            "TargetUserId": target_user_id,
+            "MaxIdleTime": cfg.max_idle_time,
+            "WelcomeMessage": cfg.welcome_message or cfg.greeting,
+            "WelcomeMessagePriority": 1,      # 高优先级，欢迎语不会被打断
+            "TurnDetectionMode": 0,           # 服务端检测一句话说完 -> 自动触发新一轮
+            "InterruptMode": 0,
+            "InterruptSpeechDuration": 500,
+            "SubtitleMode": 0,                # 全量累积字幕
+        }
+        stt_cfg = {"Language": cfg.language}
+        tts_cfg = {
+            "TTSType": "flow",
+            "VoiceId": voice_id,
+            "Model": cfg.tts_model,
+            "Speed": 2.0 if not cfg.tts_enabled else 1.0,
+            "Volume": 0.001 if not cfg.tts_enabled else 1.0,
+        }
+        params = {
+            "SdkAppId": self.trtc.sdk_app_id,
+            "RoomId": str(room_id),
+            "RoomIdType": room_id_type,
+            "AgentConfig": agent_cfg,
+            "STTConfig": stt_cfg,
+            "LLMConfig": json.dumps(llm_cfg, ensure_ascii=False),
+            "TTSConfig": json.dumps(tts_cfg, ensure_ascii=False),
+        }
+
+        logger.info(
+            "StartAIConversation: endpoint=%s region=%s SdkAppId=%s RoomId=%s "
+            "agent=%s target=%s userSig=%s...%s(len=%d) lang=%s voice=%s",
+            self.trtc.trtc_endpoint, self.trtc.trtc_region, self.trtc.sdk_app_id,
+            room_id, agent_user_id, target_user_id,
+            agent_user_sig[:6], agent_user_sig[-4:], len(agent_user_sig),
+            cfg.language, voice_id,
+        )
+
+        req = models.StartAIConversationRequest()
+        req.from_json_string(json.dumps(params, ensure_ascii=False))
+        try:
+            resp = self._api.StartAIConversation(req)
+        except Exception as exc:  # noqa: BLE001
+            err_str = str(exc)
+            if "UserSig" in err_str:
+                raise RuntimeError(
+                    f"TRTC UserSig 校验失败（{err_str}）。"
+                    f"常见原因：TRTC_REGION 与应用所在站点不匹配"
+                    f"（当前 region={self.trtc.region}, endpoint={self.trtc.trtc_endpoint}）。"
+                    f"请检查 .env 中 TRTC_REGION：国际站应用用 intl。"
+                ) from exc
+            raise
+        result = json.loads(resp.to_json_string())
+        return {
+            "task_id": result.get("TaskId"),
+            "request_id": result.get("RequestId"),
+        }
+
+    # ------------------------------------------------------------------
+    # StopAIConversation
+    # ------------------------------------------------------------------
+    def stop(self, task_id: str) -> None:
+        if not task_id:
+            raise ValueError("task_id is required")
+        req = models.StopAIConversationRequest()
+        req.from_json_string(json.dumps({"TaskId": task_id}))
+        try:
+            self._api.StopAIConversation(req)
+        except Exception as exc:  # noqa: BLE001
+            if "TaskNotExist" in str(exc):
+                logger.info("StopAIConversation: task already stopped (%s)", task_id)
+                return
+            raise
+
+    # ------------------------------------------------------------------
+    # ControlAIConversation：文本注入 / 打断
+    # ------------------------------------------------------------------
+    def control(self, task_id: str, command: str, text: Optional[str] = None, interrupt: bool = True) -> Dict[str, Any]:
+        if not task_id or not command:
+            raise ValueError("task_id and command are required")
+        payload: Dict[str, Any] = {"TaskId": task_id, "Command": command}
+        if text is not None:
+            payload["ServerPushText"] = {"Text": text, "Interrupt": interrupt}
+        req = models.ControlAIConversationRequest()
+        req.from_json_string(json.dumps(payload, ensure_ascii=False))
+        resp = self._api.ControlAIConversation(req)
+        return json.loads(resp.to_json_string())

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/usersig.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""TLS-SIG-API-v2 UserSig 签发（纯 Python 实现，无第三方依赖）。
+
+TRTC 进房鉴权：用 SDKAppID + SDKSecretKey 对 UserId 做 HMAC-SHA256 签名，
+再 zlib 压缩 + base64url 编码得到 UserSig。
+
+参考：https://cloud.tencent.com/document/product/647/17275
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import zlib
+
+
+def _base64_encode(data: bytes) -> str:
+    s = base64.b64encode(data).decode("utf-8")
+    return s.replace("+", "*").replace("/", "-").replace("=", "_")
+
+
+def _hmac_sha256(sdk_app_id: int, user_id: str, secret_key: str, current_ts: int, expire: int) -> str:
+    raw_to_sign = (
+        f"TLS.identifier:{user_id}\n"
+        f"TLS.sdkappid:{sdk_app_id}\n"
+        f"TLS.time:{current_ts}\n"
+        f"TLS.expire:{expire}\n"
+    )
+    digest = hmac.new(secret_key.encode("utf-8"), raw_to_sign.encode("utf-8"), hashlib.sha256).digest()
+    return base64.b64encode(digest).decode("utf-8")
+
+
+def gen_user_sig(sdk_app_id: int, sdk_secret_key: str, user_id: str, expire_seconds: int = 86400) -> str:
+    """签发一个 UserSig，供 TRTC Web/Native SDK 进房使用。"""
+    if not sdk_app_id or not sdk_secret_key:
+        raise ValueError("sdk_app_id and sdk_secret_key are required")
+    if not user_id:
+        raise ValueError("user_id is required")
+
+    current_ts = int(time.time())
+    sig = _hmac_sha256(sdk_app_id, user_id, sdk_secret_key, current_ts, expire_seconds)
+    payload = {
+        "TLS.ver": "2.0",
+        "TLS.identifier": str(user_id),
+        "TLS.sdkappid": int(sdk_app_id),
+        "TLS.expire": int(expire_seconds),
+        "TLS.time": int(current_ts),
+        "TLS.sig": sig,
+    }
+    compressed = zlib.compress(json.dumps(payload).encode("utf-8"))
+    return _base64_encode(compressed)

package/skills/trtc-ai-realtime-interpreter/capabilities/meeting-ops/README.md

@@ -0,0 +1,46 @@
+# meeting-ops
+
+多人房间场景的扇出编排能力：给定一组 `targetUserId`，批量起停 [conversation-core](../conversation-core) 会话，并维护房间级状态（当前跑的是什么业务、有哪些 bot 在线）。
+
+## 这个能力包不做什么
+
+**不做权限校验。** `session/start` / `session/stop` 是特权操作（会触发真实的云服务调用，产生费用），但"谁能调用"完全交给集成方自己的业务系统判断——你的会议室/直播间/App 大概率已经有一套用户角色体系了，不需要我们重新发明一套。
+
+集成时请遵循：
+
+```
+[你的前端] -> [你的后端：校验调用者是房主/管理员] -> 通过才转发 -> [meeting-ops /session/start]
+```
+
+Path A 默认场景（`scenarios/meeting-interpreter`）里能看到一个具体实现：用内存字典记录"谁建的房就是谁的房主"，仅供演示参考，**不要直接搬到生产环境**——生产场景请接入你自己系统里真实的房主/管理员判断逻辑。
+
+## 这个能力包做什么
+
+- 按参会人列表批量调用 `conversation-core` 起一路会话（每个人一路，各自独立的 `agent_user_id`）
+- 维护 `room_id -> {capability, params, tasks[]}` 的内存态，供状态查询/幂等重启使用
+- 与具体业务（比如"翻译"）解耦：通过 `capability` 字段 + 动态加载约定接口连接，不直接依赖 `realtime-translation`
+
+## API
+
+| Method | Path | 说明 |
+|---|---|---|
+| POST | `/api/v1/meeting/session/start` | 批量起会话（特权操作） |
+| POST | `/api/v1/meeting/session/stop` | 批量停会话（特权操作） |
+| GET | `/api/v1/meeting/session/state` | 查询房间扇出状态（只读） |
+
+请求示例（起翻译扇出）：
+
+```json
+POST /api/v1/meeting/session/start
+{
+  "room_id": "12345",
+  "room_id_type": 1,
+  "participants": ["user_a", "user_b"],
+  "capability": "realtime-translation",
+  "params": { "mode": "zh-en" }
+}
+```
+
+## 复用到其他场景
+
+只要新业务能力包在 `src/service.py` 里实现 `build_lifecycle_config(params) -> AgentLifecycleConfig`，就可以直接把 `capability` 字段换成新能力包的目录名，无需修改 `meeting-ops` 任何代码。

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

@@ -0,0 +1,63 @@
+# meeting-ops 能力自描述 manifest
+# 类型：业务能力（可选安装）——多人房间的扇出编排，跟"翻译"这个具体业务无关
+
+name: "meeting-ops"
+version: "1.0.0"
+type: "capability"
+description: "按参会人列表批量起停 conversation-core 会话（扇出编排）+ 房间级会话状态存储。不含任何权限/AuthZ 逻辑——调用方必须自行完成权限校验后再转发请求。"
+
+dependencies:
+  - name: "conversation-core"
+    version: ">=1.0.0,<2.0.0"
+
+# ---------------------------------------------------------------------------
+# 与业务能力的连接方式：不直接 import，而是通过 capability 参数 + 动态加载约定接口
+# ---------------------------------------------------------------------------
+integration_contract:
+  description: >
+    session/start 请求体里的 `capability` 字段指定要扇出哪种业务（默认 "realtime-translation"）。
+    本能力包通过 conversation-core 的 _capability_loader 动态加载
+    capabilities/<capability>/src/service.py 里的 build_lifecycle_config(params) 函数，
+    换取 conversation-core 的 AgentLifecycleConfig。因此 meeting-ops 可以脱离"翻译"
+    这个具体业务单独复用——未来任何"按参会人批量起会话"的场景（如会议纪要 bot）
+    只要实现同样的约定接口，就能直接换用本能力包，无需修改 meeting-ops 代码。
+  required_function: "build_lifecycle_config(params: dict) -> AgentLifecycleConfig"
+
+# ---------------------------------------------------------------------------
+# 对外暴露的 API
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: POST
+    path: /api/v1/meeting/session/start
+    description: "按参会人列表批量起会话（特权操作，无内置权限校验，见安全声明）"
+  - method: POST
+    path: /api/v1/meeting/session/stop
+    description: "批量停止该房间当前所有会话（特权操作，无内置权限校验）"
+  - method: GET
+    path: /api/v1/meeting/session/state
+    description: "查询房间当前扇出状态（只读，无需权限）"
+
+# ---------------------------------------------------------------------------
+# 业务契约：无外部业务系统依赖
+# ---------------------------------------------------------------------------
+business_contract:
+  external_apis: []
+
+# ---------------------------------------------------------------------------
+# 安全声明（务必遵守）
+# ---------------------------------------------------------------------------
+security:
+  authz:
+    enforced_by_this_capability: false
+    note: >
+      本能力包的 session/start、session/stop 是特权操作端点，**不做任何调用者身份/权限校验**。
+      集成方必须在自己的后端完成"调用者是否有权触发批量起会话"的校验后，才转发请求到这里。
+      切勿把这些端点直接暴露给未经身份校验的公网客户端。
+  network:
+    enforce_https: true
+
+acceptance:
+  - "meeting-ops 不 import 任何具体业务能力包（如 realtime-translation），只通过 capability 参数 + 动态加载约定接口连接"
+  - "session/start 对已有活跃扇出会先全部停掉再重开（幂等）"
+  - "不做权限校验；README/manifest 明确声明该职责边界，避免误用为'内置安全'"
+  - "单目标场景（不装本能力包）依然可以正常使用 conversation-core + realtime-translation"