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

package/skills/trtc-ai-realtime-interpreter/auto_adapters/integration_templates/generic-rest-api.md

@@ -0,0 +1,85 @@
+# 通用 REST API 集成指南（L3 兜底：识别不出技术栈时的手动接入方式）
+
+无论你的项目是什么技术栈，都可以直接调用 `conversation-core`（骨架必装）暴露的 REST API。是否再装 `realtime-translation` / `meeting-ops`，取决于你是「单目标」还是「多目标扇出」场景（见下方两条路径）。
+
+## 0. 启动骨架
+
+```bash
+cd capabilities/conversation-core
+cp .env.example .env   # 填好三把钥匙
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python -m src.server   # 默认 0.0.0.0:8020
+```
+
+## 1. 骨架通用接口
+
+| Method | Path | 说明 |
+|---|---|---|
+| GET | `/api/v1/health` | 三把钥匙实时自检 |
+| POST | `/api/v1/usersig` | 给任意 user_id 签发 UserSig（供旁听客户端等场景使用） |
+| POST | `/api/v1/agent/start` | 起一路会话（单目标，room_id 由你给定） |
+| POST | `/api/v1/agent/stop` | 停一路会话 |
+| POST | `/api/v1/agent/control` | 文本注入 / 打断 |
+
+## 2. 场景 A：单目标翻译（给一个人配一路 AI 翻译）
+
+装 `realtime-translation` 后新增：
+
+| Method | Path | 说明 |
+|---|---|---|
+| GET | `/api/v1/translation/modes` | 列出可用语言对（zh-en / zh-yue / en-yue） |
+| POST | `/api/v1/translation/start` | 给单一目标起一路翻译会话 |
+| POST | `/api/v1/translation/stop` | 停止 |
+
+```bash
+curl -X POST https://localhost:8020/api/v1/translation/start \
+  -H "Content-Type: application/json" \
+  -d '{
+    "room_id": "你的房间号",
+    "room_id_type": 0,
+    "target_user_id": "要被翻译的那个人的 userId",
+    "mode": "zh-en"
+  }'
+```
+
+返回 `session_id`，之后用它调用 `/api/v1/translation/stop` 结束。
+
+## 3. 场景 B：多目标扇出（多人房间，谁说话都翻译）
+
+装 `meeting-ops`（依赖 `realtime-translation`）后新增：
+
+| Method | Path | 说明 |
+|---|---|---|
+| POST | `/api/v1/meeting/session/start` | 按参会人列表批量起翻译会话（特权操作） |
+| POST | `/api/v1/meeting/session/stop` | 批量停止 |
+| GET | `/api/v1/meeting/session/state` | 查询房间当前扇出状态（只读） |
+
+```bash
+curl -X POST https://localhost:8020/api/v1/meeting/session/start \
+  -H "Content-Type: application/json" \
+  -d '{
+    "room_id": "你的房间号",
+    "room_id_type": 1,
+    "participants": ["user_a", "user_b"],
+    "capability": "realtime-translation",
+    "params": { "mode": "zh-en" }
+  }'
+```
+
+**⚠️ 安全要求（务必阅读）**：`meeting-ops` 的这两个端点是特权操作（会产生真实云服务调用费用），本能力包**不做任何调用者权限校验**。你必须在自己的后端加一层校验（比如"调用者是不是这个房间的管理员"），校验通过才转发到这里，绝不能让未经身份校验的客户端直接打到这些端点。详见 `room-owner-authz-note.md`。
+
+## 4. 前端：如何收到 AI 的字幕/状态
+
+如果你已有的会议/直播 SDK 没有把底层 TRTC engine 暴露出来供你监听自定义消息，参考 `../frontend_assets` 里的两个框架无关片段：
+
+- `silent-listener.ts`：独立起一个静默旁听 TRTC 客户端，只收自定义消息不推流
+- `subtitle-parser.ts`：解析 cmd 10000/10001，产出双语气泡 + 转写记录
+
+拷进你的项目后按你的技术栈（Vue/React/纯 JS）简单包一层调用即可，两个文件都不依赖任何 UI 框架。
+
+## 5. 安全合规
+
+- **HTTPS**：生产环境务必启用（TRTC Web SDK 采集麦克风也要求安全上下文）
+- **SecretKey 不下发到客户端**：骨架只把 `user_sig`（带 TTL）发给客户端，绝不暴露 `SDKSecretKey`
+- **日志脱敏**：骨架内置 `RedactingFilter`；反向代理层也应避免记录 Authorization 头

package/skills/trtc-ai-realtime-interpreter/auto_adapters/integration_templates/room-owner-authz-note.md

@@ -0,0 +1,53 @@
+# 权限校验说明：meeting-ops 为什么不内置房主/管理员判断
+
+## 结论
+
+`meeting-ops` 的 `/api/v1/meeting/session/start` 和 `/session/stop` 是特权操作端点（会触发真实的云服务调用，产生费用），但**本能力包完全不做任何调用者身份/权限校验**。
+
+## 为什么这么设计
+
+这不是接入 TRTC 能力本身的必要条件，是我们刻意做的边界收窄：
+
+1. **你的系统大概率已经有权限体系了**。如果你在接入一个已有的会议室/直播间/App，你自己的后端应该已经知道"当前请求是谁发的、他是不是管理员"。让 `meeting-ops` 再实现一套自己的权限判断，反而会跟你已有的权限体系打架，或者变成"两套互不认识的权限系统"。
+
+2. **权限规则因业务而异**。有的产品是"仅主持人可操作"，有的是"任何管理员都可以"，有的甚至是"付费用户才能开"——这些规则属于具体业务，不该固化进一个可复用能力包里。
+
+## 你应该怎么做
+
+在你自己的后端加一层转发前置校验：
+
+```
+[你的前端] --请求--> [你的后端]
+                        │
+                        ├─ 校验调用者身份 + 权限（用你已有的鉴权体系）
+                        │
+                        ├─ 通过 --转发--> [meeting-ops /api/v1/meeting/session/start]
+                        │
+                        └─ 不通过 --> 直接拒绝，不转发
+```
+
+伪代码示例（Node/Express 风格，其他语言逻辑相同）：
+
+```js
+app.post('/my-api/ai-translate/start', requireAuth, async (req, res) => {
+  const room = await myRoomService.getRoom(req.body.roomId)
+  if (room.ownerId !== req.user.id) {
+    return res.status(403).json({ error: 'only room owner can start AI translation' })
+  }
+  const resp = await fetch('https://localhost:8020/api/v1/meeting/session/start', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      room_id: room.id,
+      participants: room.participantUserIds,
+      capability: 'realtime-translation',
+      params: { mode: req.body.mode },
+    }),
+  })
+  res.json(await resp.json())
+})
+```
+
+## 参考实现（仅供理解思路，不要直接照搬到生产）
+
+`scenarios/meeting-interpreter/backend/app/server.py` 里有一个**演示用**的房主校验实现（内存字典记录"建房人=房主"），那是我们自己的会议室 demo 的产品规则，仅用来说明"这一层校验该长什么样子"。生产环境请换成你自己系统里真实的权限判断逻辑，而不是照搬这个内存字典。

package/skills/trtc-ai-realtime-interpreter/auto_adapters/manifest.yaml

@@ -0,0 +1,49 @@
+# auto_adapters 索引 manifest（Path B：无 UI，直接接入已有系统）
+#
+# 与 Path A 的关系：Path A（scenarios/meeting-interpreter）交付的是一整套可运行的
+# Vue3 会议室 demo；Path B 不生成任何 UI，只交付「API 契约 + 按目标模式挑选的
+# 集成示例代码」，供集成方把能力接进自己已有的会议室/直播间/App。
+
+version: "1.0.0"
+description: "无 UI 集成资产：REST API 契约 + 前端片段（静默旁听+字幕解析）+ 后端反代示例"
+
+# ---------------------------------------------------------------------------
+# 目标模式（Path B 引导时二选一，决定装哪些能力包）
+# ---------------------------------------------------------------------------
+target_modes:
+  - id: single_target
+    label: "单目标：给一个人（主播/客服/任意角色）配一路实时翻译"
+    capabilities: ["conversation-core", "realtime-translation"]
+    api_prefix: "/api/v1/translation"
+    guide: "integration_templates/single-target-integration.md"
+
+  - id: multi_target_fanout
+    label: "多目标：多人房间场景，谁说话都要翻译（会议/多人直播间）"
+    capabilities: ["conversation-core", "realtime-translation", "meeting-ops"]
+    api_prefix: "/api/v1/meeting"
+    guide: "integration_templates/multi-target-fanout-integration.md"
+    note: "meeting-ops 不做权限校验，务必在你自己的后端先校验调用者权限再转发，见 room-owner-authz-note.md"
+
+# ---------------------------------------------------------------------------
+# 前端资产（框架无关，按需拷贝进集成方项目）
+# ---------------------------------------------------------------------------
+frontend_assets:
+  - source: "../capabilities/conversation-core/frontend/silent-listener.ts"
+    description: "静默旁听 TRTC 客户端封装（进房收自定义消息，不推流/不播音频）"
+  - source: "../capabilities/realtime-translation/frontend/subtitle-parser.ts"
+    description: "字幕/AI状态自定义消息解析（cmd 10000/10001），产出双语气泡+转写记录"
+
+# ---------------------------------------------------------------------------
+# 后端反代模板（按检测到的技术栈渲染，转发到 conversation-core 的 REST API）
+# ---------------------------------------------------------------------------
+adapters:
+  - name: "python-backend"
+    path: "python"
+    tech_stack: ["flask", "fastapi", "django"]
+    description: "Python 后端反代示例：转发到 conversation-core / meeting-ops 的 REST API，并在转发前插入权限校验钩子"
+
+# ---------------------------------------------------------------------------
+# 三级降级兜底
+# ---------------------------------------------------------------------------
+fallback_templates:
+  manual_rest_api: "integration_templates/generic-rest-api.md"

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

@@ -0,0 +1,11 @@
+# python 反代适配器
+
+`fastapi_reverse_proxy.py.tpl` —— 转发到骨架服务 `/api/v1/meeting/*` 的示例路由，转发前带一个必须实现的权限校验占位函数 `require_room_owner`。
+
+拷贝后：
+1. 去掉 `.tpl` 后缀
+2. 替换 `${SKELETON_BASE_URL}` 和 `${ROUTE_PREFIX}`
+3. 实现 `require_room_owner`，接入你自己系统的权限判断（见 `../integration_templates/room-owner-authz-note.md`）
+4. 挂到你的 FastAPI app：`app.include_router(router)`
+
+如果你是单目标场景（不需要 meeting-ops），把转发目标换成 `/api/v1/translation/start` / `/stop` 即可，不需要权限校验占位（该端点不是特权操作，但仍建议做基础鉴权）。

package/skills/trtc-ai-realtime-interpreter/auto_adapters/python/fastapi_reverse_proxy.py.tpl

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""FastAPI 反代示例：把已有系统的请求转发到 trtc-ai-realtime-interpreter 骨架服务。
+
+用法：把本文件拷进你的 FastAPI 项目（去掉 .tpl 后缀），修改 SKELETON_BASE_URL，
+把 `include_router(router)` 挂到你的 app 上。
+
+关键点：转发前先做权限校验（见 require_room_owner 的占位实现），再转发到骨架。
+骨架服务本身跑在 ${SKELETON_BASE_URL}（默认 https://localhost:8020）。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+SKELETON_BASE_URL = "${SKELETON_BASE_URL}"  # 例如 https://localhost:8020
+
+router = APIRouter(prefix="${ROUTE_PREFIX}", tags=["ai-realtime-interpreter"])
+
+
+# ---------------------------------------------------------------------------
+# TODO：替换为你自己系统里真实的权限校验（见 room-owner-authz-note.md）
+# ---------------------------------------------------------------------------
+async def require_room_owner(room_id: str, caller_user_id: str) -> None:
+    """占位实现：请替换成你系统里"调用者是不是这个房间的管理员/主持人"的真实判断。"""
+    # 示例：
+    # room = await my_room_service.get_room(room_id)
+    # if room.owner_id != caller_user_id:
+    #     raise HTTPException(status_code=403, detail="only room owner can operate")
+    raise NotImplementedError("请实现 require_room_owner：接入你自己系统的权限判断")
+
+
+class FanoutStartRequest(BaseModel):
+    room_id: str
+    room_id_type: int = 1
+    caller_user_id: str            # 你自己系统里发起这次操作的用户
+    participants: List[str]
+    mode: str = "zh-en"
+
+
+@router.post("/session/start")
+async def session_start(req: FanoutStartRequest) -> Dict[str, Any]:
+    await require_room_owner(req.room_id, req.caller_user_id)
+    async with httpx.AsyncClient(verify=False, timeout=10.0) as client:
+        resp = await client.post(
+            f"{SKELETON_BASE_URL}/api/v1/meeting/session/start",
+            json={
+                "room_id": req.room_id,
+                "room_id_type": req.room_id_type,
+                "participants": req.participants,
+                "capability": "realtime-translation",
+                "params": {"mode": req.mode},
+            },
+        )
+    if resp.status_code != 200:
+        raise HTTPException(status_code=resp.status_code, detail=resp.text)
+    return resp.json()
+
+
+class FanoutStopRequest(BaseModel):
+    room_id: str
+    caller_user_id: str
+
+
+@router.post("/session/stop")
+async def session_stop(req: FanoutStopRequest) -> Dict[str, Any]:
+    await require_room_owner(req.room_id, req.caller_user_id)
+    async with httpx.AsyncClient(verify=False, timeout=10.0) as client:
+        resp = await client.post(f"{SKELETON_BASE_URL}/api/v1/meeting/session/stop", json={"room_id": req.room_id})
+    if resp.status_code != 200:
+        raise HTTPException(status_code=resp.status_code, detail=resp.text)
+    return resp.json()
+
+
+@router.get("/session/state")
+async def session_state(room_id: str) -> Dict[str, Any]:
+    # 只读查询，无需权限校验
+    async with httpx.AsyncClient(verify=False, timeout=10.0) as client:
+        resp = await client.get(f"{SKELETON_BASE_URL}/api/v1/meeting/session/state", params={"room_id": room_id})
+    if resp.status_code != 200:
+        raise HTTPException(status_code=resp.status_code, detail=resp.text)
+    return resp.json()

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/.env.example

@@ -0,0 +1,17 @@
+# 钥匙 1 · 腾讯云 API 密钥（console.tencentcloud.com/cam/capi）
+TENCENT_CLOUD_SECRET_ID=
+TENCENT_CLOUD_SECRET_KEY=
+TENCENT_CLOUD_REGION=ap-guangzhou
+
+# 钥匙 2 · TRTC 应用凭证
+# intl = 国际站 console.trtc.io (ap-singapore)
+TRTC_REGION=intl
+TRTC_SDK_APP_ID=
+TRTC_SDK_SECRET_KEY=
+
+# 钥匙 3 · LLM 密钥（OpenAI 兼容协议）
+LLM_API_KEY=
+LLM_API_URL=https://api.openai.com/v1/chat/completions
+LLM_MODEL=gpt-4o-mini
+
+PORT=8020

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/frontend/silent-listener.ts

@@ -0,0 +1,91 @@
+/**
+ * 通用「静默旁听」TRTC Web 客户端封装（conversation-core 的前端配套工具）。
+ *
+ * 用途：不依赖上层是否把 TRTC 引擎暴露给业务方（比如接入了 Atomicx/RoomKit 这类
+ * 无 UI 会议 SDK 时，业务层通常拿不到底层 engine 实例去监听 CUSTOM_MESSAGE），
+ * 而是另起一个独立身份，静默进同一个 SdkAppId+RoomId，不推流、不订阅音视频，
+ * 只挂 CUSTOM_MESSAGE 监听 —— 零风险、不依赖任何会议 SDK 内部实现。
+ *
+ * 这是「怎么收到 AI 通道消息」的通用机制，跟「收到消息后怎么解析 payload」是两件事：
+ * 后者（比如翻译字幕解析）由具体业务能力包（realtime-translation）实现，通过
+ * onCustomMessage 回调接上去，不需要重新造进房/退房这一层轮子。
+ *
+ * 使用方需要自行 `npm install trtc-sdk-v5`（依赖由业务项目安装，本文件不打包依赖）。
+ */
+
+export interface SilentListenerConfig {
+  sdkAppId: number
+  roomId: string
+  userId: string
+  userSig: string
+  /** TRTC Web SDK 静态资源路径，默认官方 CDN */
+  assetsPath?: string
+}
+
+export interface SilentListenerHandle {
+  enter: () => Promise<void>
+  exit: () => Promise<void>
+  onCustomMessage: (cb: (event: any) => void) => void
+  onError: (cb: (err: any) => void) => void
+}
+
+/**
+ * 创建一个静默旁听客户端。调用 enter() 后即进房收自定义消息，不会有任何本地
+ * 采集/推流/播放行为；调用 exit() 退房并销毁底层实例。
+ *
+ * @param TRTC 由调用方传入 `trtc-sdk-v5` 的默认导出（避免本文件强制依赖该包）
+ */
+export function createSilentListener(TRTC: any, cfg: SilentListenerConfig): SilentListenerHandle {
+  let client: any = null
+  let customMessageCb: ((event: any) => void) | null = null
+  let errorCb: ((err: any) => void) | null = null
+
+  async function enter(): Promise<void> {
+    if (client) return
+    client = TRTC.create({
+      assetsPath: cfg.assetsPath || 'https://web.sdk.qcloud.com/trtc/webrtc/v5/assets/',
+    })
+    client.on(TRTC.EVENT.CUSTOM_MESSAGE, (event: any) => {
+      customMessageCb?.(event)
+    })
+    client.on(TRTC.EVENT.ERROR, (err: any) => {
+      errorCb?.(err)
+    })
+    await client.enterRoom({
+      strRoomId: cfg.roomId,
+      scene: 'rtc',
+      sdkAppId: cfg.sdkAppId,
+      userId: cfg.userId,
+      userSig: cfg.userSig,
+      // 旁听客户端不播音频：避免跟业务方自己的会议/直播客户端重复播放 AI 的 TTS
+      autoReceiveAudio: false,
+    })
+    // 静默旁听：不调用 startLocalAudio / startLocalVideo
+  }
+
+  async function exit(): Promise<void> {
+    if (!client) return
+    try {
+      await client.exitRoom()
+    } catch {
+      /* ignore */
+    }
+    try {
+      client.destroy()
+    } catch {
+      /* ignore */
+    }
+    client = null
+  }
+
+  return {
+    enter,
+    exit,
+    onCustomMessage: (cb) => {
+      customMessageCb = cb
+    },
+    onError: (cb) => {
+      errorCb = cb
+    },
+  }
+}

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

@@ -0,0 +1,110 @@
+# conversation-core 能力自描述 manifest
+# 类型：骨架（必装；不含任何行业/场景业务逻辑）
+
+name: "conversation-core"
+version: "1.0.0"
+type: "skeleton"
+description: "通用语音 Agent 骨架：三把钥匙管理、UserSig 签发、单路 Conversational AI 起停/控制，无业务逻辑"
+
+dependencies: []   # 骨架层无依赖
+
+# ---------------------------------------------------------------------------
+# 配置接口
+# ---------------------------------------------------------------------------
+config:
+  credentials:
+    - key: "TENCENT_CLOUD_SECRET_ID"
+      required: true
+      description: "腾讯云 API SecretId（钥匙 1）"
+    - key: "TENCENT_CLOUD_SECRET_KEY"
+      required: true
+      description: "腾讯云 API SecretKey（钥匙 1）"
+    - key: "TENCENT_CLOUD_REGION"
+      required: false
+      default: "ap-guangzhou"
+    - key: "TRTC_SDK_APP_ID"
+      required: true
+      description: "TRTC 应用 SDKAppID（钥匙 2）"
+    - key: "TRTC_SDK_SECRET_KEY"
+      required: true
+      description: "TRTC 应用 SDKSecretKey（钥匙 2）"
+    - key: "TRTC_REGION"
+      required: false
+      default: "intl"
+      description: "intl=国际站"
+    - key: "LLM_API_KEY"
+      required: true
+      description: "外部 LLM 访问密钥（钥匙 3）"
+    - key: "LLM_API_URL"
+      required: false
+      default: "https://api.openai.com/v1/chat/completions"
+    - key: "LLM_MODEL"
+      required: false
+      default: "gpt-4o-mini"
+
+# ---------------------------------------------------------------------------
+# 对外暴露的 API
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: GET
+    path: /api/v1/health
+    description: 三把钥匙实时连通性自检
+  - method: POST
+    path: /api/v1/usersig
+    description: 给任意 user_id 签发 UserSig（供旁听客户端等通用场景使用）
+  - method: POST
+    path: /api/v1/agent/start
+    description: 起一路 Conversational AI 会话（单目标，room_id 由调用方给定）
+  - method: POST
+    path: /api/v1/agent/stop
+    description: 停一路会话
+  - method: POST
+    path: /api/v1/agent/control
+    description: 文本注入 / 打断
+  - method: GET
+    path: /api/v1/sessions
+    description: 内存态会话列表（调试用）
+
+# ---------------------------------------------------------------------------
+# 业务契约：骨架只对接腾讯云 TRTC 控制面 + LLM，均为平台级依赖，不提供 contract-adapt
+# ---------------------------------------------------------------------------
+business_contract:
+  external_apis:
+    - name: llm.chat_completions
+      direction: outbound
+      method: POST
+      path: /v1/chat/completions
+      description: "调用外部 LLM 做文本生成（OpenAI Chat Completions 兼容协议）"
+      auth:
+        type: bearer
+        location: header
+        name: Authorization
+      timeout_ms: 30000
+    - name: trtc.start_ai_conversation
+      direction: outbound
+      method: POST
+      path: "tencentcloudapi.com/?Action=StartAIConversation"
+      description: "腾讯云 TRTC 控制面：启动 AI 会话（平台级协议，不可适配）"
+      timeout_ms: 10000
+
+# ---------------------------------------------------------------------------
+# 安全声明
+# ---------------------------------------------------------------------------
+security:
+  log_redaction:
+    enabled: true
+    patterns: ["secret_id", "secret_key", "api_key", "usersig", "authorization"]
+  credential_storage:
+    source: "env-only"
+    env_file_permission: "0600"
+  network:
+    enforce_https: true
+
+# ---------------------------------------------------------------------------
+# 验收标准
+# ---------------------------------------------------------------------------
+acceptance:
+  - "三把钥匙实时自检，全部通过后 /api/v1/health 返回 status=ok"
+  - "start/stop 不含任何行业 prompt / 语言对，纯协议编排"
+  - "同一 room_id 可被多次调用 start（供 meeting-ops 扇出场景），互不冲突"
+  - "日志脱敏生效，.env 权限 600，无明文密钥落盘/落日志"

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.110
+uvicorn[standard]>=0.29
+python-dotenv>=1.0
+requests>=2.31
+tencentcloud-sdk-python>=3.0.1000

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

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+"""兄弟能力包（capabilities/*）的动态加载器（与 cwd / 目录名无关）。
+
+能力目录用连字符命名（realtime-translation / meeting-ops），Python import 语法不认连字符；
+且各能力包内部模块用「平铺 import」（不用包内相对导入），因此加载前需要把目标能力包的
+src 目录临时加进 sys.path，再普通 import。
+
+用法：
+    from _capability_loader import try_load_capability
+    mod = try_load_capability("meeting-ops", "src/router.py")
+    if mod is not None:
+        app.include_router(mod.router, prefix="/api/v1/meeting")
+"""
+from __future__ import annotations
+
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# 本文件位于 <skill_root>/capabilities/conversation-core/src/_capability_loader.py
+# parents[0]=src parents[1]=conversation-core parents[2]=capabilities parents[3]=skill_root
+_HERE = Path(__file__).resolve()
+_SKILL_ROOT = _HERE.parents[3]
+_CAPABILITIES_ROOT = _SKILL_ROOT / "capabilities"
+
+_module_cache: dict[str, ModuleType] = {}
+
+
+def skill_root() -> Path:
+    return _SKILL_ROOT
+
+
+def capabilities_root() -> Path:
+    return _CAPABILITIES_ROOT
+
+
+def load_capability(cap_name: str, module_rel: str) -> ModuleType:
+    """加载 capabilities/<cap_name>/<module_rel> 并返回模块对象。
+
+    会把该能力包的 src 目录加入 sys.path（一次性、幂等），使其内部的平铺 import 生效。
+    """
+    cache_key = f"{cap_name}::{module_rel}"
+    cached = _module_cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    cap_dir = _CAPABILITIES_ROOT / cap_name
+    file_path = cap_dir / module_rel
+    if not file_path.is_file():
+        raise ModuleNotFoundError(f"capability '{cap_name}' module '{module_rel}' not found at {file_path}")
+
+    src_dir = str(file_path.parent)
+    if src_dir not in sys.path:
+        sys.path.insert(0, src_dir)
+
+    mod_name = f"_capabilities_{cap_name.replace('-', '_')}_{file_path.stem}"
+    cached_mod = sys.modules.get(mod_name)
+    if cached_mod is not None:
+        _module_cache[cache_key] = cached_mod
+        return cached_mod
+
+    spec = importlib.util.spec_from_file_location(mod_name, file_path)
+    if spec is None or spec.loader is None:
+        raise ModuleNotFoundError(f"failed to build spec for '{cap_name}'/'{module_rel}'")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[mod_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        sys.modules.pop(mod_name, None)
+        raise
+
+    _module_cache[cache_key] = module
+    logger.debug("capability loaded: %s -> %s", mod_name, file_path)
+    return module
+
+
+def try_load_capability(cap_name: str, module_rel: str) -> Optional[ModuleType]:
+    """同 load_capability，但失败时返回 None（用于「可选安装」场景，静默降级）。"""
+    try:
+        return load_capability(cap_name, module_rel)
+    except Exception as exc:  # noqa: BLE001
+        logger.info("capability '%s' module '%s' not loaded (skipped): %s", cap_name, module_rel, exc)
+        return None