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

package/skills/trtc-ai-oral-coach/capabilities/conversation-core/src/core/report_llm.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""共享评估基座（F1）—— 4 个评估能力（scenario-roleplay / quick-correct /
+reply-suggestion / ability-report）复用的 LLM 客户端。
+
+设计要点（沿用定稿 Demo coach_evaluator 的成熟策略）：
+  - OpenAI 兼容 /chat/completions，response_format=json_object 强约束
+  - 不同任务用不同 temperature / timeout（见 KIND_PROFILES）
+  - 防 Prompt Injection：调用方拼 prompt 时用 json.dumps() 序列化用户内容
+  - core 对**实时对话零 LLM**（那是 TRTC 云端）；本模块仅是给能力用的共享 utility
+
+用法（能力侧 default adapter）：
+    from ..._shared import get_evaluator          # 见各能力的加载封装
+    ev = get_evaluator()
+    raw = ev.call(prompt, kind="quick")           # 返回 LLM 文本（JSON 串）
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Dict, Tuple
+
+import requests
+
+logger = logging.getLogger("report_llm")
+
+# kind → (temperature 调整策略, read_timeout 上限, system_msg)
+_CONNECT_TIMEOUT = 10.0
+KIND_PROFILES = {
+    "report":  ("base",  None, "You are a strict JSON-only English conversation coach producing learning reports."),
+    "quick":   ("low",   15.0, "You are a strict JSON-only English-conversation coach producing Speak-style inline corrections."),
+    "hints":   ("high",  15.0, "You are a strict JSON-only English-conversation coach producing short natural reply suggestions."),
+    "scene":   ("higher",12.0, "You are a strict JSON-only assistant generating short vivid English-practice scene snippets."),
+    "opening": ("mid",   12.0, "You are a strict JSON-only assistant writing one in-character English opening line."),
+    # KB 场景素材批量提炼：要忠实原素材，创造力要求不高，timeout 稍长（一次处理多条）
+    "kb_scene": ("low",  20.0, "You are a strict JSON-only assistant extracting structured English-practice "
+                                "scene setups from a customer's own knowledge-base snippets."),
+}
+
+
+class ReportLLM:
+    """共享 LLM 客户端。由 core 依据 .env REPORT_LLM_* 实例化后交给各能力。"""
+
+    def __init__(self, api_key: str, api_url: str, model: str,
+                 temperature: float = 0.2, timeout: float = 120.0) -> None:
+        self.api_key = (api_key or "").strip()
+        self.api_url = (api_url or "https://api.openai.com/v1/chat/completions").strip()
+        self.model = (model or "gpt-4o-mini").strip()
+        self.temperature = float(temperature)
+        self.timeout = float(timeout)
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.api_key)
+
+    def _temp_for(self, strategy: str) -> float:
+        t = self.temperature
+        return {
+            "low":    min(0.2, t),
+            "base":   t,
+            "mid":    max(0.5, min(0.8, t + 0.3)),
+            "high":   max(0.5, min(0.8, t + 0.4)),
+            "higher": max(0.6, min(0.9, t + 0.5)),
+        }.get(strategy, t)
+
+    def call(self, prompt: str, kind: str = "report") -> str:
+        """调用 LLM，返回 message.content（应为 JSON 串）。失败抛异常，由能力侧兜底。"""
+        if not self.configured:
+            raise RuntimeError("REPORT_LLM api_key is not configured")
+        strategy, read_timeout, system_msg = KIND_PROFILES.get(kind, KIND_PROFILES["report"])
+        timeout: Tuple[float, float] = (
+            _CONNECT_TIMEOUT,
+            min(read_timeout, self.timeout) if read_timeout else self.timeout,
+        )
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system_msg},
+                {"role": "user",   "content": prompt},
+            ],
+            "temperature":     self._temp_for(strategy),
+            "response_format": {"type": "json_object"},
+        }
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type":  "application/json",
+        }
+        resp = requests.post(self.api_url, headers=headers, json=payload, timeout=timeout)
+        resp.raise_for_status()
+        data = resp.json()
+        try:
+            return data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as e:
+            raise ValueError(f"unexpected LLM response shape: {e}; body={data}")
+
+    @staticmethod
+    def loads(raw: str) -> Dict:
+        """JSON 解析辅助（能力侧统一用）。"""
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            raise ValueError("top-level is not an object")
+        return data
+
+
+# ---- 单例：core 在 server 启动时用 .env 配置初始化后，能力通过 get_shared() 取用 ----
+_shared: ReportLLM | None = None
+
+
+def init_shared(api_key: str, api_url: str, model: str,
+                temperature: float = 0.2, timeout: float = 120.0) -> ReportLLM:
+    global _shared
+    _shared = ReportLLM(api_key, api_url, model, temperature, timeout)
+    return _shared
+
+
+def get_shared() -> ReportLLM:
+    """能力侧调用；若 core 尚未初始化则返回一个未配置实例（configured=False，能力自动降级）。"""
+    global _shared
+    if _shared is None:
+        _shared = ReportLLM("", "", "gpt-4o-mini")
+    return _shared
+
+
+# ---------------------------------------------------------------------------
+# 全局模块别名：让通过 _capability_loader 加载的各能力可直接 `import coach_report_llm`
+# 取到 server.py 初始化后的**同一**单例（避免跨包 dual-import 导致的配置丢失）。
+# ---------------------------------------------------------------------------
+import sys as _sys
+_sys.modules.setdefault("coach_report_llm", _sys.modules[__name__])
+

package/skills/trtc-ai-oral-coach/capabilities/conversation-core/src/health.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""健康自检：三 LED（tencent_cloud / trtc / llm）。供前端顶栏状态灯 + Path B e2e 用。
+
+轻量策略：不做深度联网探测（避免慢/误报），只校验凭据是否齐全 + 格式合理。
+需要深度校验时走 scripts/verify-credentials.py（对齐客服）。
+"""
+from __future__ import annotations
+
+import re
+from typing import Dict
+
+from .config import CoreConfig
+
+
+def _led(ok: bool, msg: str) -> Dict[str, object]:
+    return {"ok": ok, "message": msg}
+
+
+def check_all(cfg: CoreConfig) -> Dict[str, Dict[str, object]]:
+    # TRTC
+    if not cfg.trtc.configured:
+        trtc = _led(False, "TRTC 应用凭据未配置")
+    elif not re.fullmatch(r"[0-9a-fA-F]{64}", cfg.trtc.sdk_secret_key or ""):
+        trtc = _led(False, "SDKSecretKey 格式异常（应为 64 位十六进制）")
+    else:
+        trtc = _led(True, "TRTC 凭据就绪")
+
+    # Tencent Cloud
+    tc = _led(cfg.tencent.configured,
+              "腾讯云 API 凭据就绪" if cfg.tencent.configured else "腾讯云 API 凭据未配置")
+
+    # LLM
+    llm = _led(cfg.llm.configured,
+               "LLM 密钥就绪" if cfg.llm.configured else "LLM 密钥未配置")
+
+    return {"tencent_cloud": tc, "trtc": trtc, "llm": llm}

package/skills/trtc-ai-oral-coach/capabilities/conversation-core/src/server.py

@@ -0,0 +1,205 @@
+# -*- coding: utf-8 -*-
+"""FastAPI 入口：REST 路由（Path B）+ /action 兼容 facade（Path A 定稿 UI）+ 能力子路由挂载。
+
+双轨（F2）：
+  - REST：/api/v1/config|agent/start|stop|farewell|invoke|health（给 Path B 集成者）
+  - facade：POST /action + Action 头（定稿 Demo 的 app.js 原样调用，零改动）
+两者都走同一套 Agent 方法。
+
+能力路由：用 try_load_capability 预接线（未安装的能力优雅跳过）。
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from fastapi import FastAPI, Request, APIRouter, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from .config import load_config
+from .health import check_all
+from .agent import Agent
+from .core.report_llm import init_shared
+from ._capability_loader import try_load_capability
+
+logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO"),
+                    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+logger = logging.getLogger("server")
+
+_cfg = load_config()
+# 初始化共享评估基座（F1）—— 供 4 个评估能力复用
+init_shared(_cfg.report_llm.api_key, _cfg.report_llm.api_url, _cfg.report_llm.model,
+            _cfg.report_llm_temperature, _cfg.report_llm_timeout)
+
+_agent: Optional[Agent] = None
+_init_error: Optional[str] = None
+try:
+    if _cfg.trtc.configured and _cfg.tencent.configured:
+        _agent = Agent(_cfg)
+        logger.info("Agent initialized")
+    else:
+        _init_error = f"credentials missing: {_cfg.missing()}"
+        logger.warning(_init_error)
+except Exception as exc:  # noqa: BLE001
+    _init_error = str(exc)
+    logger.warning("Agent not initialized: %s", _init_error)
+
+
+app = FastAPI(title="ai-oral-coach / conversation-core", version="1.0.0")
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_credentials=True,
+                   allow_methods=["*"], allow_headers=["*"])
+
+api = APIRouter(prefix="/api/v1")
+
+
+def _require_agent() -> Agent:
+    if _agent is None:
+        raise HTTPException(status_code=503, detail={
+            "code": "credentials_missing",
+            "message": _init_error or "credentials not configured",
+            "hint": "配置三把钥匙后重启（见 SKILL.md §5）",
+        })
+    return _agent
+
+
+# ---------------------------------------------------------------------------
+# REST（Path B）
+# ---------------------------------------------------------------------------
+@api.get("/health")
+def health() -> Dict[str, Any]:
+    checks = check_all(_cfg)
+    overall = "ok" if all(c["ok"] for c in checks.values()) else "partial_failure"
+    return {"status": overall, "checks": checks,
+            "configured": _cfg.fully_configured, "missing": _cfg.missing()}
+
+
+@api.post("/config")
+def rest_config(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return _require_agent().issue_config(payload.get("userid") or payload.get("user_id"))
+
+
+@api.post("/agent/start")
+def rest_start(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return _require_agent().start(payload)
+
+
+@api.post("/agent/stop")
+def rest_stop(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return _require_agent().stop(payload)
+
+
+@api.post("/agent/farewell")
+def rest_farewell(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return _require_agent().farewell(payload)
+
+
+@api.post("/agent/invoke")
+def rest_invoke(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return _require_agent().invoke(payload)
+
+
+app.include_router(api)
+
+
+# ---------------------------------------------------------------------------
+# 能力子路由挂载（预接线；未安装能力 try_load 返回 None 自动跳过）
+# ---------------------------------------------------------------------------
+_CAP_ROUTES = [
+    ("scenario-roleplay",  "/api/v1/scene"),
+    ("quick-correct",      "/api/v1/correct"),
+    ("reply-suggestion",   "/api/v1/suggest"),
+    ("ability-report",     "/api/v1/report"),
+    ("custom-learning-kb", "/api/v1/kb"),
+]
+for _cap, _prefix in _CAP_ROUTES:
+    _mod = try_load_capability(_cap, "src/router.py")
+    if _mod is not None and hasattr(_mod, "router"):
+        app.include_router(_mod.router, prefix=_prefix, tags=[_cap])
+        logger.info("mounted capability router: %s -> %s", _cap, _prefix)
+
+
+# ---------------------------------------------------------------------------
+# /action 兼容 facade（Path A 定稿 UI）—— Action 头 → Agent 方法 / 能力
+# 复刻定稿 Demo 的 POST /action 契约，让 app.js 零改动即可跑。
+# ---------------------------------------------------------------------------
+_FACADE_ACTIONS = {
+    "join", "StartAIConversation", "StopAIConversation", "FarewellAndStop",
+    "InvokeLLM", "GenerateReport", "QuickCorrect", "SuggestReplies", "GetSceneCandidates",
+}
+
+
+def _err(msg: str) -> JSONResponse:
+    return JSONResponse({"Response": {"Error": {"Code": "InvalidParameter", "Message": msg}}})
+
+
+@app.post("/action")
+async def action(request: Request):
+    act = request.headers.get("Action", "")
+    if act not in _FACADE_ACTIONS:
+        return _err(f"action {act!r} invalid")
+    body = await request.json() if request.headers.get("content-type", "").startswith("application/json") else {}
+    body = body or {}
+    try:
+        # 核心 action 需要 Agent（依赖 TRTC/腾讯云）；评估类只需 LLM，不经 Agent。
+        if act == "join":
+            return _require_agent().issue_config(body.get("userid"))
+        if act == "StartAIConversation":
+            return _require_agent().start(body)
+        if act == "StopAIConversation":
+            return _require_agent().stop(body)
+        if act == "FarewellAndStop":
+            return _require_agent().farewell(body)
+        if act == "InvokeLLM":
+            return _require_agent().invoke(body)
+        # 评估类 → 转发到对应能力的 handler（不依赖 Agent/TRTC）
+        if act == "GenerateReport":
+            return _dispatch_capability("ability-report", "generate", body)
+        if act == "QuickCorrect":
+            return _dispatch_capability("quick-correct", "generate", body)
+        if act == "SuggestReplies":
+            return _dispatch_capability("reply-suggestion", "generate", body)
+        if act == "GetSceneCandidates":
+            return _dispatch_capability("scenario-roleplay", "get_scene_candidates", body)
+    except HTTPException:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        logger.error("action %s failed: %s", act, exc)
+        return _err(str(exc))
+
+
+def _dispatch_capability(cap: str, func: str, body: Dict[str, Any]):
+    """调用能力 src/handler.py 里的 facade 函数（复刻 Demo 的响应形状）。"""
+    mod = try_load_capability(cap, "src/handler.py")
+    if mod is None or not hasattr(mod, func):
+        return _err(f"capability {cap!r} not installed")
+    return getattr(mod, func)(body)
+
+
+# ---------------------------------------------------------------------------
+# 静态 Web Demo（Path A）—— 由 WEB_DEMO_DIR 指向三屏 SPA
+# ---------------------------------------------------------------------------
+_DEMO_DIR = Path(os.getenv("WEB_DEMO_DIR", "")) if os.getenv("WEB_DEMO_DIR") else None
+if _DEMO_DIR and _DEMO_DIR.exists():
+    app.mount("/static", StaticFiles(directory=str(_DEMO_DIR), html=True), name="static")
+
+    @app.get("/")
+    def index() -> FileResponse:
+        # 优先 coach.html（定稿 Demo 入口），否则 index.html
+        for name in ("coach.html", "index.html"):
+            p = _DEMO_DIR / name
+            if p.exists():
+                return FileResponse(str(p))
+        raise HTTPException(status_code=404, detail="demo index not found")
+
+
+def main() -> None:
+    import uvicorn
+    uvicorn.run(app, host=os.getenv("HOST", "0.0.0.0"), port=int(os.getenv("PORT", "8000")))
+
+
+if __name__ == "__main__":
+    main()

package/skills/trtc-ai-oral-coach/capabilities/conversation-core/src/trtc_client.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""TRTC OpenAPI 客户端封装：Start / Stop / Control AI Conversation。
+
+只做协议编排，不含任何业务 prompt（业务在 scenario-roleplay 能力里组装好后传入）。
+"""
+from __future__ import annotations
+
+import json
+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 .config import CoreConfig
+
+
+class TRTCClient:
+    def __init__(self, cfg: CoreConfig) -> None:
+        self._cfg = cfg
+        cred = credential.Credential(cfg.tencent.secret_id, cfg.tencent.secret_key)
+        http = HttpProfile()
+        http.endpoint = cfg.trtc.endpoint
+        cp = ClientProfile()
+        cp.httpProfile = http
+        self._api = trtc_client.TrtcClient(cred, cfg.trtc.api_region, cp)
+
+    def start(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        req = models.StartAIConversationRequest()
+        req.from_json_string(json.dumps(params, ensure_ascii=False))
+        resp = self._api.StartAIConversation(req)
+        return json.loads(resp.to_json_string())
+
+    def stop(self, task_id: str) -> Dict[str, Any]:
+        req = models.StopAIConversationRequest()
+        req.from_json_string(json.dumps({"TaskId": task_id}))
+        try:
+            resp = self._api.StopAIConversation(req)
+            return json.loads(resp.to_json_string())
+        except Exception as e:  # noqa: BLE001
+            if "TaskNotExist" in str(e):
+                return {"RequestId": "N/A", "message": "Task already stopped"}
+            raise
+
+    def control(self, task_id: str, command: str, text: str,
+                interrupt: bool = True, stop_after_play: bool = False,
+                add_history: bool = True, priority: int = 0) -> Dict[str, Any]:
+        """
+        !!! 关键修复 !!!
+        ControlAIConversation 的 Command 与子对象是按 Command 值互斥的：
+          Command="ServerPushText" → 必须配 "ServerPushText": {Text, Interrupt, AddHistory, Priority, StopAfterPlay}
+          Command="InvokeLLM"      → 必须配 "InvokeLLM":      {Content, Interrupt, ExperimentalParams}
+        之前这里不管 command 是什么，payload 永远塞进 "ServerPushText"（且用 "Text" 而不是
+        "Content"）——Command=InvokeLLM 时 TRTC 服务端根本不会去读 ServerPushText 这个键，
+        等于 push-to-talk 场景下用户的原话从来没有真正传给大模型，AI 只能在没拿到这轮新发
+        言的情况下瞎凑一句延续对话（"答非所问/编造内容"的根本原因）。
+        """
+        if command == "InvokeLLM":
+            params = {
+                "TaskId":  task_id,
+                "Command": "InvokeLLM",
+                "InvokeLLM": {
+                    "Content":   text,
+                    "Interrupt": interrupt,
+                },
+            }
+        else:
+            push = {
+                "Text":        text,
+                "Interrupt":   interrupt,
+                "AddHistory":  add_history,
+                "Priority":    priority,
+            }
+            if stop_after_play:
+                push["StopAfterPlay"] = True
+            params = {"TaskId": task_id, "Command": command, "ServerPushText": push}
+        req = models.ControlAIConversationRequest()
+        req.from_json_string(json.dumps(params, ensure_ascii=False))
+        try:
+            resp = self._api.ControlAIConversation(req)
+            return json.loads(resp.to_json_string())
+        except Exception as e:  # noqa: BLE001
+            if "TaskNotExist" in str(e):
+                return {"RequestId": "N/A", "message": "Task already ended"}
+            raise

package/skills/trtc-ai-oral-coach/capabilities/conversation-core/src/usersig.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""UserSig 三套签发（用户 / 机器人 / 数字人）—— 复用腾讯云官方 TLSSigAPIv2。"""
+from __future__ import annotations
+
+from . import TLSSigAPIv2  # noqa: F401  —— 同目录官方库
+
+
+def _api(sdk_app_id: int, secret: str):
+    return TLSSigAPIv2.TLSSigAPIv2(sdk_app_id, secret)
+
+
+def gen_user_sig(sdk_app_id: int, sdk_secret_key: str, user_id: str,
+                 expire_seconds: int = 86400) -> str:
+    if not user_id or len(user_id) > 32:
+        raise ValueError(f"invalid userId: {user_id!r}")
+    return _api(sdk_app_id, sdk_secret_key).genUserSig(user_id, expire_seconds)
+
+
+def sign_trio(sdk_app_id: int, sdk_secret_key: str, user_id: str,
+              expire_seconds: int = 86400) -> dict:
+    """一次签三套：真人用户 / AI 机器人 / 数字人。"""
+    robot_id  = f"{user_id}_robot"
+    avatar_id = f"{user_id}_avatar"
+    api = _api(sdk_app_id, sdk_secret_key)
+    return {
+        "sdkappid":        sdk_app_id,
+        "user_id":         user_id,
+        "user_sig":        api.genUserSig(user_id, expire_seconds),
+        "robot_user_id":   robot_id,
+        "robot_user_sig":  api.genUserSig(robot_id, expire_seconds),
+        "avatar_user_id":  avatar_id,
+        "avatar_user_sig": api.genUserSig(avatar_id, expire_seconds),
+    }

package/skills/trtc-ai-oral-coach/capabilities/custom-learning-kb/manifest.yaml

@@ -0,0 +1,65 @@
+# custom-learning-kb —— 接入自有教研知识库（Path A / Path B 均可选装）
+name: custom-learning-kb
+version: "1.0.0"
+type: capability
+description: "把用户自有教研库（默认 Dify/Coze）接进来，驱动 Setup 屏的场景候选（由 scenario-roleplay 消费），也为报告的 betterExpressions 提供素材。唯一走『连外部系统』的能力。"
+
+path_a: true                   # Path A / Path B 均可选装；不配置任何 KB_* 时行为等同不装（用内置题库）
+
+dependencies:
+  - { name: conversation-core, version: ">=1.0.0,<2.0.0" }
+
+extensions:
+  - inject_at: server.router_extension
+    inline_code: |
+      from ._capability_loader import try_load_capability as _try
+      _m = _try("custom-learning-kb", "src/router.py")
+      if _m is not None and hasattr(_m, "router"):
+          app.include_router(_m.router, prefix="/api/v1/kb", tags=["custom-learning-kb"])
+
+config:
+  adapter: { default: "dify", env: "KB_ADAPTER" }     # dify | coze | user_custom
+  top_k:   { default: 3, env: "KB_TOP_K" }
+
+endpoints:
+  - { method: POST, path: /api/v1/kb/retrieve, description: "检索教研片段（供内部能力调用，也可前端直调）" }
+
+# 经典「连外部系统」契约 —— 用 KBClient Port（见 references/evaluator-port.md#2）
+business_contract:
+  port_class: "src.ports.kb_client.KBClient"
+  default_adapter: "src.adapters.dify.DifyKBClient"
+  customization_sop: "references/evaluator-port.md#2-kbclient-port"
+  external_apis:
+    - name: kb.retrieve
+      direction: outbound        # ← 关键：去拉用户的 KB（非 inbound）
+      method: POST
+      path: "{KB_DIFY_API_URL}/datasets/retrieve  |  Coze /open_api/knowledge/recall"
+      description: "检索用户知识库，返回相关教研片段"
+      request_schema:  { query: string, top_k: int }
+      response_schema: { records: "[{text, source, score}]" }
+      auth: { type: bearer, location: header, name: Authorization }
+      timeout_ms: 8000
+
+integration:
+  auto_adapters:
+    - { tech_stack: ["dify"], adapter: dify }
+    - { tech_stack: ["coze"], adapter: coze }
+  fallback:
+    manual_api: { rest_endpoint: "/api/v1/kb" }
+  # scenario-roleplay 是当前唯一的内部消费者：装了本能力后，Setup 屏场景候选会自动
+  # 从内置题库切到本能力检索到的内容（契约格式快解析 / 自由文本 LLM 提炼），检索/
+  # 提炼失败静默降级回内置题库，不需要额外接线。
+  consumers:
+    - { capability: scenario-roleplay, via: "src/scenario_source.py::get_kb_candidates" }
+
+security:
+  network:
+    enforce_https: true          # 非 localhost 强制 HTTPS
+    deny_private_network: true   # 禁止访问内网地址（SSRF 防护）
+
+acceptance:
+  - "配置 Dify/Coze key 后 /api/v1/kb/retrieve 能返回片段"
+  - "切换 KB_ADAPTER (dify|coze|user_custom) 无需改业务代码"
+  - "outbound 拒绝内网地址（localhost 除外）"
+  - "装了本能力后，GetSceneCandidates 自动改用 KB 内容；不装或检索失败静默降级回内置题库"
+

package/skills/trtc-ai-oral-coach/capabilities/custom-learning-kb/src/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""custom-learning-kb 能力包（Path B 专属，唯一走 outbound 连外部系统）。"""

package/skills/trtc-ai-oral-coach/capabilities/custom-learning-kb/src/adapters/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""adapters 子包。"""