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

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

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""Dify / Coze / user_custom KB adapters + 工厂。
+
+- dify : POST {KB_DIFY_API_URL}/datasets/{id}/retrieve  (Bearer KB_DIFY_API_KEY)
+- coze : POST {KB_COZE_API_URL}/open_api/knowledge/recall (Bearer KB_COZE_API_KEY)
+- user_custom : POST {KB_REST_BASE_URL} (Bearer KB_REST_TOKEN) —— 用户自研 REST
+
+所有 adapter 走 assert_safe_url 做 SSRF 防护。
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Dict, List
+
+import requests
+
+from ..ports import KBClient, assert_safe_url
+
+logger = logging.getLogger("custom-learning-kb.adapter")
+
+
+def _env(k: str, d: str = "") -> str:
+    return (os.getenv(k) or d).strip()
+
+
+class DifyKBClient(KBClient):
+    def __init__(self) -> None:
+        self.base = _env("KB_DIFY_API_URL")
+        self.key = _env("KB_DIFY_API_KEY")
+        self.dataset = _env("KB_DIFY_DATASET_ID")
+
+    def retrieve(self, query: str, top_k: int = 3) -> List[Dict]:
+        if not (self.base and self.key):
+            raise RuntimeError("KB_DIFY_API_URL / KB_DIFY_API_KEY not configured")
+        url = f"{self.base.rstrip('/')}/datasets/{self.dataset}/retrieve"
+        assert_safe_url(url)
+        headers = {"Authorization": f"Bearer {self.key}"}
+
+        def _payload(search_method: str) -> dict:
+            # Dify HitTestingPayload 的 retrieval_model 是强校验的 pydantic 模型，
+            # reranking_enable / score_threshold_enabled 是必填字段，缺了会直接 400。
+            return {
+                "query": query,
+                "retrieval_model": {
+                    "search_method": search_method,
+                    "reranking_enable": False,
+                    "reranking_mode": None,
+                    "reranking_model": {"reranking_provider_name": "", "reranking_model_name": ""},
+                    "weights": None,
+                    "top_k": top_k,
+                    "score_threshold_enabled": False,
+                    "score_threshold": None,
+                },
+            }
+
+        # 优先 hybrid_search（语义检索，能理解查询词和素材内容之间没有字面重合但语义
+        # 相关的情况——这是场景检索的真实需求）。但 Dify 数据集若以「经济」模式建索引
+        # （免费/默认档常见），没有配置 Embedding 模型、也没有向量 Collection，请求
+        # hybrid_search 会报 400 "Collection not found"。这种情况下自动降级成
+        # keyword_search（关键词倒排索引，不依赖 Embedding）重试一次，保证「经济」
+        # 模式数据集也能用，只是检索质量会退化为关键词匹配。
+        resp = requests.post(url, headers=headers, json=_payload("hybrid_search"), timeout=(5, 8))
+        if resp.status_code == 400 and "Collection not found" in resp.text:
+            logger.warning("Dify hybrid_search unavailable (dataset likely uses Economy "
+                           "indexing without an embedding model) — retrying with keyword_search")
+            resp = requests.post(url, headers=headers, json=_payload("keyword_search"), timeout=(5, 8))
+        resp.raise_for_status()
+        records = resp.json().get("records", [])
+        out = []
+        for r in records[:top_k]:
+            seg = r.get("segment", {}) if isinstance(r, dict) else {}
+            out.append({"text": seg.get("content", ""),
+                        "source": (seg.get("document") or {}).get("name", "dify"),
+                        "score": r.get("score", 0)})
+        return out
+
+
+class CozeKBClient(KBClient):
+    def __init__(self) -> None:
+        self.base = _env("KB_COZE_API_URL", "https://api.coze.cn")
+        self.key = _env("KB_COZE_API_KEY")
+        self.dataset = _env("KB_COZE_DATASET_ID")
+
+    def retrieve(self, query: str, top_k: int = 3) -> List[Dict]:
+        if not self.key:
+            raise RuntimeError("KB_COZE_API_KEY not configured")
+        url = f"{self.base.rstrip('/')}/open_api/knowledge/recall"
+        assert_safe_url(url)
+        resp = requests.post(url, headers={"Authorization": f"Bearer {self.key}"},
+                             json={"dataset_ids": [self.dataset] if self.dataset else [],
+                                   "query": query, "top_k": top_k},
+                             timeout=(5, 8))
+        resp.raise_for_status()
+        chunks = resp.json().get("chunks", []) or resp.json().get("data", [])
+        out = []
+        for c in (chunks or [])[:top_k]:
+            if isinstance(c, dict):
+                out.append({"text": c.get("content") or c.get("text", ""),
+                            "source": c.get("doc_name", "coze"), "score": c.get("score", 0)})
+        return out
+
+
+class UserCustomKBClient(KBClient):
+    def __init__(self) -> None:
+        self.base = _env("KB_REST_BASE_URL")
+        self.token = _env("KB_REST_TOKEN")
+
+    def retrieve(self, query: str, top_k: int = 3) -> List[Dict]:
+        if not self.base:
+            raise RuntimeError("KB_REST_BASE_URL not configured")
+        assert_safe_url(self.base)
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        resp = requests.post(self.base, headers=headers,
+                             json={"query": query, "top_k": top_k}, timeout=(5, 8))
+        resp.raise_for_status()
+        data = resp.json()
+        records = data.get("records") or data.get("results") or []
+        return [{"text": r.get("text", ""), "source": r.get("source", "custom"),
+                 "score": r.get("score", 0)} for r in records[:top_k] if isinstance(r, dict)]
+
+
+def get_client() -> KBClient:
+    adapter = _env("KB_ADAPTER", "dify").lower()
+    return {"dify": DifyKBClient, "coze": CozeKBClient,
+            "user_custom": UserCustomKBClient}.get(adapter, DifyKBClient)()

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

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""KBClient port —— 检索用户自有教研知识库，返回相关片段。
+
+adapter：dify（默认）/ coze / user_custom，通过 .env KB_ADAPTER 切换。
+安全：outbound 对非 localhost 强制 HTTPS + 禁止内网地址（SSRF 防护）。
+"""
+from __future__ import annotations
+
+import ipaddress
+import socket
+from abc import ABC, abstractmethod
+from typing import Dict, List
+from urllib.parse import urlparse
+
+
+class KBClient(ABC):
+    @abstractmethod
+    def retrieve(self, query: str, top_k: int = 3) -> List[Dict]:
+        """返回 [{text, source, score}, ...]"""
+        ...
+
+
+# ---- SSRF 防护：拒绝内网/环回（localhost 除外用于本地联调）----
+_BLOCKED_PREFIXES = ("9.", "10.", "11.", "21.", "30.", "172.", "192.168.")
+
+
+def assert_safe_url(url: str) -> None:
+    parsed = urlparse(url)
+    if parsed.scheme != "https" and parsed.hostname not in ("localhost", "127.0.0.1"):
+        raise ValueError(f"KB endpoint must be HTTPS (got {parsed.scheme!r})")
+    host = parsed.hostname or ""
+    if host in ("localhost", "127.0.0.1"):
+        return
+    try:
+        ip = socket.gethostbyname(host)
+    except Exception:
+        ip = host
+    try:
+        addr = ipaddress.ip_address(ip)
+        if addr.is_private or addr.is_loopback or addr.is_link_local:
+            raise ValueError(f"KB endpoint resolves to a private/internal address: {ip}")
+    except ValueError as e:
+        if "private/internal" in str(e):
+            raise
+    if any(ip.startswith(p) for p in _BLOCKED_PREFIXES):
+        raise ValueError(f"KB endpoint points to a blocked internal range: {ip}")

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

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""router.py —— custom-learning-kb REST（Path B）。挂载于 /api/v1/kb。"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, HTTPException
+
+from .adapters.clients import get_client
+
+router = APIRouter()
+
+
+@router.post("/retrieve")
+def kb_retrieve(payload: Dict[str, Any]):
+    """检索教研片段。body = {query, top_k?}"""
+    query = (payload.get("query") or "").strip()
+    if not query:
+        raise HTTPException(status_code=400, detail="query is required")
+    top_k = int(payload.get("top_k", 3) or 3)
+    try:
+        records = get_client().retrieve(query, top_k)
+        return {"records": records}
+    except ValueError as e:   # SSRF / 配置错误
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=502, detail=f"KB upstream error: {e}")

package/skills/trtc-ai-oral-coach/capabilities/quick-correct/manifest.yaml

@@ -0,0 +1,48 @@
+# quick-correct —— 单句 Speak 风格纠正
+name: quick-correct
+version: "1.0.0"
+type: capability
+description: "用户每轮说完后，异步给一句话的纠正（correction）+ 更地道说法（better），双语并行。"
+
+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("quick-correct", "src/router.py")
+      if _m is not None and hasattr(_m, "router"):
+          app.include_router(_m.router, prefix="/api/v1/correct", tags=["quick-correct"])
+
+config:
+  max_sentence_length: { default: 800 }                       # 单句上限，防滥用
+  adapter:             { default: "default", env: "QC_ADAPTER" }
+
+endpoints:
+  - method: POST
+    path: /api/v1/correct
+    description: "提交一句话 → 返回纠正 + 更地道说法（无可纠正项返回 null）"
+
+# 评估类能力 —— 共用 Evaluator Port（见 references/evaluator-port.md）
+business_contract:
+  port_class: "src.ports.evaluator.Evaluator"
+  default_adapter: "src.adapters.default.LLMEvaluator"
+  customization_sop: "references/evaluator-port.md#1-evaluator-port"
+  external_apis:
+    - name: correct.submit
+      direction: inbound
+      method: POST
+      path: /api/v1/correct
+      request_schema:  { sentence: string, scenario: string, level: string, language: string }
+      response_schema: { correction: "string|null", better: "string|null", explanation: string }
+
+integration:
+  auto_adapters:
+    - { tech_stack: ["react","vue","angular"], adapter: frontend-spa }
+    - { tech_stack: ["express","next"],        adapter: node-backend }
+    - { tech_stack: ["flask","fastapi"],        adapter: python-backend }
+
+acceptance:
+  - "提交一句话能返回 correction / better 字段"
+  - "判定无错时返回 null，前端不弹卡片"

package/skills/trtc-ai-oral-coach/capabilities/quick-correct/src/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""quick-correct 能力包。"""

package/skills/trtc-ai-oral-coach/capabilities/quick-correct/src/adapters/__init__.py

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

package/skills/trtc-ai-oral-coach/capabilities/quick-correct/src/adapters/default.py

@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+"""quick-correct default adapter —— Speak 风格单句纠正（移植定稿 Demo evaluator）。
+
+多语言：总生成 en 版（fix/native 恒为英文，why 用英文），并按 ui_lang 生成对应版本
+（why 用 ui_lang；支持 en/zh/ja/ko，其它降级 en）。并行调用共享评估基座。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger("quick-correct.adapter")
+
+
+def _shared():
+    import coach_report_llm
+    return coach_report_llm.get_shared()
+
+
+_TONE = {
+    "zh": ("## 输出语言与语气\n* `correction.fix` 与 `better.native` 是英文（不翻译）。\n"
+           "* `correction.why` 与 `better.why` **必须用简体中文**，教学+鼓励语气，点出为什么更像 native。\n"
+           "* 避免「错了/不对」，用「这里建议/更自然的说法是/听起来更像 native」。`why` 30~80 字。\n"),
+    "ja": ("## 出力言語とトーン\n* `correction.fix`/`better.native` は英語（翻訳しない）。\n"
+           "* `correction.why`/`better.why` は**日本語で**、教育的で励ましのトーン、なぜ自然かを説明。\n"
+           "* 「間違い/ダメ」を避け「こう言うと自然」。`why` は40〜100字。\n"),
+    "ko": ("## 출력 언어 및 톤\n* `correction.fix`/`better.native` 는 영어(번역 금지).\n"
+           "* `correction.why`/`better.why` 는 **한국어로**, 교육적·격려 톤, 왜 자연스러운지 설명.\n"
+           "* '틀림/잘못' 대신 '이렇게 말하면 자연스럽습니다'. `why` 40~100자.\n"),
+    "en": ("## Output language & tone\n* `correction.fix`/`better.native` are English (learning content).\n"
+           "* `correction.why`/`better.why` in English, teaching+encouraging, say WHY it sounds more native.\n"
+           "* Avoid 'wrong/bad'; prefer 'try/sounds more natural/flows better'. Keep `why` <= 40 words.\n"),
+}
+
+
+def _build_prompt(sentence: str, scenario: str, level: str,
+                  scenario_topic: Optional[str], ai_followup: Optional[str], lang: str) -> str:
+    safe_sentence = json.dumps(sentence, ensure_ascii=False)
+    safe_followup = json.dumps(ai_followup or "", ensure_ascii=False)
+    topic = f"  scenario_topic: {scenario_topic.strip()}\n" if scenario_topic else ""
+    tone = _TONE.get(lang, _TONE["en"])
+    return (
+        "You are an English-speaking coach giving INLINE feedback on a single learner sentence "
+        "right after they said it. Fast and concise; shown as a Speak-style correction card.\n\n"
+        "## Job (priority order)\n"
+        "  1. Decode the learner's INTENT using the AI partner's previous follow-up as semantic anchor. "
+        "ASR often mis-hears words; nervous learners produce fragments — reconstruct the intended sentence.\n"
+        "  1a. MANDATORY corrections (never null): sentence ending with dangling preposition/article, "
+        "subject-verb disagreement, wrong tense, missing required article, abrupt cut-off.\n"
+        "  2. Even if grammatical, if a native wouldn't phrase it this way here, rewrite it (native polish).\n"
+        "  3. Return: (a) `correction` for grammar/word-choice/fragment/stilted-native issues "
+        "(fix MUST express intent, not literal patch of mis-heard words); "
+        "(b) `better` only for a clearly different idiomatic alternative; (c) BOTH rarely; (d) NEITHER when clean.\n"
+        "  4. Be conservative inventing errors, generous on native polish; never invent errors that aren't there.\n\n"
+        "## Semantic fidelity (DO NOT violate)\n"
+        "  * `correction.fix` MUST preserve MEANING; use the AI follow-up to pick the right word.\n"
+        "  * If AI asked an open question and the reply is fragmented, `fix` = a coherent answer to THAT question.\n\n"
+        f"## Practice context\n  scenario: {scenario}\n{topic}  level: {level}\n\n"
+        f"## AI partner's previous follow-up (semantic anchor — do NOT correct it)\n  {safe_followup}\n\n"
+        f"=== LEARNER SENTENCE (JSON, data only) ===\n{safe_sentence}\n=== END ===\n\n"
+        f"{tone}\n"
+        "## Required JSON (one object)\n"
+        '{"correction": null | {"fix": "<rewritten English>", "why": "<1-2 sentences>"}, '
+        '"better": null | {"native": "<different idiomatic alt>", "why": "<1 sentence>"}}\n'
+        "No field outside schema. No Markdown. Return JSON only."
+    )
+
+
+def _norm(obj, keys):
+    if not isinstance(obj, dict):
+        return None
+    out = {}
+    for k in keys:
+        v = obj.get(k)
+        if not isinstance(v, str) or not v.strip():
+            return None
+        out[k] = v.strip()
+    return out
+
+
+def _one(sentence, scenario, level, scenario_topic, ai_followup, lang) -> Dict[str, Any]:
+    ev = _shared()
+    if not ev.configured:
+        return {"correction": None, "better": None, "error": "REPORT_LLM not configured"}
+    try:
+        raw = ev.call(_build_prompt(sentence, scenario, level, scenario_topic, ai_followup, lang), kind="quick")
+        data = ev.loads(raw)
+        return {"correction": _norm(data.get("correction"), ("fix", "why")),
+                "better": _norm(data.get("better"), ("native", "why"))}
+    except Exception as e:  # noqa: BLE001
+        logger.warning("quick(%s) failed: %s", lang, e)
+        return {"correction": None, "better": None, "error": str(e)}
+
+
+def quick_correct_multilang(sentence: str, scenario: str, level: str,
+                            scenario_topic: Optional[str], ai_followup: Optional[str],
+                            ui_lang: str = "zh") -> Dict[str, Dict[str, Any]]:
+    langs = {"en"}
+    if ui_lang in ("zh", "ja", "ko"):
+        langs.add(ui_lang)
+    with ThreadPoolExecutor(max_workers=len(langs)) as pool:
+        futs = {lg: pool.submit(_one, sentence, scenario, level, scenario_topic, ai_followup, lg)
+                for lg in langs}
+    return {lg: f.result() for lg, f in futs.items()}

package/skills/trtc-ai-oral-coach/capabilities/quick-correct/src/handler.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""handler.py —— /action facade 的 QuickCorrect（复刻定稿 Demo 响应形状）。"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .adapters.default import quick_correct_multilang
+
+_LEVELS = {"beginner", "intermediate", "advanced"}
+_SCENARIOS = {"travel", "work", "study", "free"}
+
+
+def _ui_lang_key(raw: str) -> str:
+    r = (raw or "zh-CN").strip().lower()
+    if r.startswith("zh"): return "zh"
+    if r.startswith("ja"): return "ja"
+    if r.startswith("ko"): return "ko"
+    return "en"
+
+
+def generate(body: Dict[str, Any]) -> Dict[str, Any]:
+    sentence = (body.get("UserSentence") or "").strip()
+    if not sentence:
+        raise ValueError("UserSentence is required")
+    sentence = sentence[:800]
+    scenario = body.get("Scenario") if body.get("Scenario") in _SCENARIOS else "free"
+    level = body.get("Level") if body.get("Level") in _LEVELS else "intermediate"
+    scenario_topic = (body.get("ScenarioTopic") or "").strip() or None
+    ai_followup = (body.get("AiFollowup") or "").strip() or None
+    turn_id = body.get("TurnId") or ""
+    ui_lang = _ui_lang_key(body.get("UILanguage") or "zh-CN")
+    corrections = quick_correct_multilang(sentence, scenario, level, scenario_topic, ai_followup, ui_lang)
+    return {"Corrections": corrections, "TurnId": turn_id}

package/skills/trtc-ai-oral-coach/capabilities/quick-correct/src/router.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""router.py —— quick-correct REST（Path B）。挂载于 /api/v1/correct。"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, HTTPException
+
+from .handler import generate
+
+router = APIRouter()
+
+
+@router.post("")
+@router.post("/")
+def correct(payload: Dict[str, Any]):
+    """提交一句话 → 返回纠正 + 更地道说法（无可纠正项则字段为 null）。"""
+    try:
+        return generate(payload)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e))

package/skills/trtc-ai-oral-coach/capabilities/reply-suggestion/manifest.yaml

@@ -0,0 +1,49 @@
+# reply-suggestion —— Lightbulb 接话建议
+name: reply-suggestion
+version: "1.0.0"
+type: capability
+description: "AI 说完一句后，异步给用户 3 条不同方向的英文接话建议（卡住时的提示）。"
+
+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("reply-suggestion", "src/router.py")
+      if _m is not None and hasattr(_m, "router"):
+          app.include_router(_m.router, prefix="/api/v1/suggest", tags=["reply-suggestion"])
+
+config:
+  max_ai_message_length:  { default: 1200 }
+  max_recent_turns:       { default: 6 }
+  suggestions_count:      { default: 3 }
+  adapter:                { default: "default", env: "RS_ADAPTER" }
+
+endpoints:
+  - method: POST
+    path: /api/v1/suggest
+    description: "提交 AI 最后一句 + 最近对话 → 返回 3 条接话建议"
+
+business_contract:
+  port_class: "src.ports.evaluator.Evaluator"
+  default_adapter: "src.adapters.default.LLMEvaluator"
+  customization_sop: "references/evaluator-port.md#1-evaluator-port"
+  external_apis:
+    - name: suggest.replies
+      direction: inbound
+      method: POST
+      path: /api/v1/suggest
+      request_schema:  { aiLastMessage: string, recentTranscript: "array", scenario: string, level: string, style: string }
+      response_schema: { suggestions: "string[3]" }
+
+integration:
+  auto_adapters:
+    - { tech_stack: ["react","vue","angular"], adapter: frontend-spa }
+    - { tech_stack: ["express","next"],        adapter: node-backend }
+    - { tech_stack: ["flask","fastapi"],        adapter: python-backend }
+
+acceptance:
+  - "返回 3 条方向不同的英文接话建议"
+  - "调用失败时前端静默降级，不阻塞主流程"

package/skills/trtc-ai-oral-coach/capabilities/reply-suggestion/src/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""reply-suggestion 能力包。"""

package/skills/trtc-ai-oral-coach/capabilities/reply-suggestion/src/adapters/__init__.py

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

package/skills/trtc-ai-oral-coach/capabilities/reply-suggestion/src/adapters/default.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""reply-suggestion default adapter —— Lightbulb 接话建议（移植定稿 Demo evaluator）。
+
+对 AI 最后一句生成 3 条方向不同的英文接话建议，全英文（用户要说出口的）。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("reply-suggestion.adapter")
+
+
+def _shared():
+    import coach_report_llm
+    return coach_report_llm.get_shared()
+
+
+_LEVEL_HINT = {
+    "beginner":     "Each hint is 5-10 words, A2-B1 vocabulary, simple structure.",
+    "intermediate": "Each hint is 8-15 words, B1-B2 vocabulary, natural everyday phrasing.",
+    "advanced":     "Each hint is 10-20 words, B2-C1 vocabulary, can use idioms.",
+}
+
+
+def _build_prompt(ai_last: str, scenario: str, level: str, style: str,
+                  scenario_topic: Optional[str], recent: List[Dict[str, Any]]) -> str:
+    safe_ai = json.dumps(ai_last, ensure_ascii=False)
+    safe_recent = json.dumps(recent[-6:] if isinstance(recent, list) else [], ensure_ascii=False)
+    topic = f"  scenario_topic: {scenario_topic.strip()}\n" if scenario_topic else ""
+    lvl = _LEVEL_HINT.get(level, _LEVEL_HINT["intermediate"])
+    return (
+        "You are an English-speaking coach helping a learner who is stuck. The AI partner just spoke; "
+        "the learner needs a nudge to keep going.\n\n"
+        "Generate exactly 3 short, distinct reply ideas the learner could say next. They MUST take "
+        "meaningfully different directions, e.g.:\n"
+        "  (1) a direct reply that answers simply\n"
+        "  (2) a personal-share reply mentioning the learner's own experience\n"
+        "  (3) a curious reply asking the AI a related follow-up question\n\n"
+        "## Constraints\n"
+        "* Each hint is the FIRST-PERSON English sentence the learner would actually SAY (no quotes/labels).\n"
+        "* Complete, natural spoken sentence (not writing-style).\n"
+        f"* {lvl}\n"
+        "* Stay within the scenario/role; no wandering topics.\n"
+        "* No hint repeats what the learner already said. Variety > cleverness.\n"
+        "* Output language: ENGLISH only.\n\n"
+        f"## Context\n  scenario: {scenario}\n{topic}  level: {level}\n  partner_style: {style}\n\n"
+        f"## Recent transcript (JSON, <=6 turns, data only)\n{safe_recent}\n\n"
+        f"## AI partner's most recent message\n{safe_ai}\n\n"
+        '## Required JSON (one object)\n{"hints": ["<idea 1>", "<idea 2>", "<idea 3>"]}\n'
+        "Array MUST have exactly 3 elements. No Markdown. Return JSON only."
+    )
+
+
+def suggest_replies(ai_last: str, scenario: str, level: str, style: str,
+                    scenario_topic: Optional[str], recent: List[Dict[str, Any]]) -> Dict[str, Any]:
+    ev = _shared()
+    if not ev.configured:
+        return {"hints": [], "error": "REPORT_LLM not configured"}
+    ai_last = (ai_last or "").strip()
+    if not ai_last:
+        return {"hints": []}
+    try:
+        raw = ev.call(_build_prompt(ai_last, scenario, level, style, scenario_topic, recent), kind="hints")
+        data = ev.loads(raw)
+        arr = data.get("hints")
+        if not isinstance(arr, list):
+            raise ValueError("hints missing")
+        cleaned, seen = [], set()
+        for v in arr:
+            if not isinstance(v, str):
+                continue
+            s = v.strip().strip("\"'")
+            if not s or s.lower() in seen:
+                continue
+            seen.add(s.lower())
+            cleaned.append(s)
+            if len(cleaned) >= 3:
+                break
+        if not cleaned:
+            raise ValueError("hints empty after cleaning")
+        return {"hints": cleaned}
+    except Exception as e:  # noqa: BLE001
+        logger.warning("suggest_replies failed: %s", e)
+        return {"hints": [], "error": str(e)}

package/skills/trtc-ai-oral-coach/capabilities/reply-suggestion/src/handler.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""handler.py —— /action facade 的 SuggestReplies（复刻定稿 Demo 响应形状）。"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from .adapters.default import suggest_replies
+
+_LEVELS = {"beginner", "intermediate", "advanced"}
+_SCENARIOS = {"travel", "work", "study", "free"}
+_STYLES = {"friend", "listener", "local"}
+
+
+def generate(body: Dict[str, Any]) -> Dict[str, Any]:
+    ai_last = (body.get("AiLastMessage") or "").strip()
+    if not ai_last:
+        raise ValueError("AiLastMessage is required")
+    ai_last = ai_last[:1200]
+    scenario = body.get("Scenario") if body.get("Scenario") in _SCENARIOS else "free"
+    level = body.get("Level") if body.get("Level") in _LEVELS else "intermediate"
+    style = body.get("Style") if body.get("Style") in _STYLES else "friend"
+    scenario_topic = (body.get("ScenarioTopic") or "").strip() or None
+    recent: List[Dict[str, Any]] = []
+    for item in (body.get("RecentTranscript") or [])[-6:]:
+        if isinstance(item, dict) and item.get("role") in ("user", "coach") \
+                and isinstance(item.get("text"), str) and item["text"].strip():
+            recent.append({"role": item["role"], "text": item["text"][:400]})
+    result = suggest_replies(ai_last, scenario, level, style, scenario_topic, recent)
+    return {"Hints": result.get("hints") or [], "HintId": body.get("HintId") or ""}

package/skills/trtc-ai-oral-coach/capabilities/reply-suggestion/src/router.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""router.py —— reply-suggestion REST（Path B）。挂载于 /api/v1/suggest。"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, HTTPException
+
+from .handler import generate
+
+router = APIRouter()
+
+
+@router.post("")
+@router.post("/")
+def suggest(payload: Dict[str, Any]):
+    """AI 最后一句 + 最近对话 → 3 条接话建议。"""
+    try:
+        return generate(payload)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e))