@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

package/skills/trtc-ai-service/tests/test_handoff_ports.py

@@ -0,0 +1,195 @@
+"""Phase 3 Stage 6: human-handoff capability ports/adapters unit tests.
+
+Coverage targets:
+- LocalQueueHandoffClient: FIFO queue + auto-connect + cancel / status transitions
+- MockHandoffClient: pre-seeded demo data (_seed three tickets) + list_tickets
+- DefaultRestHandoffClient: base_url security validation (private network denied) + HTTP path calls + passthrough responses
+
+Note: This test file cleans up stale ``src.*`` modules from sys.modules before imports
+to avoid conflicts with the same-named ``src`` package in ``test_kb_ports.py``;
+KB tests likewise self-clean.
+"""
+from __future__ import annotations
+
+import sys
+import time
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+
+# ---------------------------------------------------------------------------
+# Isolated import: clean src.* cache + insert human-handoff's own src parent directory
+# ---------------------------------------------------------------------------
+_ROOT = Path(__file__).resolve().parent.parent
+_HH = _ROOT / "capabilities" / "human-handoff"
+
+for _name in [k for k in list(sys.modules) if k == "src" or k.startswith("src.")]:
+    del sys.modules[_name]
+sys.path[:] = [p for p in sys.path if "/capabilities/" not in p]
+sys.path.insert(0, str(_HH))
+
+# Import directly from core.models module to bypass the circular dependency in src/core/__init__.py
+# (src/core/__init__.py imports service.py, which in turn depends on ports.handoff_client)
+import importlib  # noqa: E402
+
+_models = importlib.import_module("src.core.models")
+TicketStatusEnum = _models.TicketStatusEnum
+
+from src.adapters.local_queue import LocalQueueHandoffClient  # noqa: E402
+from src.adapters.mock import MockHandoffClient  # noqa: E402
+# Pre-import default_rest (HH version) and pin the reference at module scope
+# to avoid ``src`` being replaced by KB namespace when test_kb_ports runs later
+from src.adapters import default_rest as _hh_default_rest  # noqa: E402
+
+DefaultRestHandoffClient = _hh_default_rest.DefaultRestHandoffClient
+
+
+class LocalQueueAdapterTests(unittest.TestCase):
+    """Cover LocalQueueHandoffClient core behaviors."""
+
+    def test_create_then_query_pending(self):
+        c = LocalQueueHandoffClient(
+            capacity=5, agent_pool_size=0, estimated_wait_per_slot=10
+        )
+        t = c.create_ticket(
+            user_id="u1",
+            subject="退款",
+            description="3 天未到账",
+            priority="normal",
+            transcript=["用户：申请退款"],
+        )
+        # agent_pool_size=0 → no auto-connect; enters queue
+        self.assertEqual(t.status, TicketStatusEnum.PENDING.value)
+        self.assertEqual(t.queue_position, 1)
+        self.assertEqual(t.eta_seconds, 10)
+
+        status = c.query_status(t.ticket_id)
+        self.assertIsNotNone(status)
+        self.assertEqual(status.status, TicketStatusEnum.PENDING.value)
+
+    def test_auto_connect_when_agent_available(self):
+        c = LocalQueueHandoffClient(capacity=5, agent_pool_size=1)
+        t = c.create_ticket(user_id="u_auto", subject="物流")
+        self.assertEqual(t.status, TicketStatusEnum.PROCESSING.value)
+        self.assertEqual(t.queue_position, 0)
+        self.assertIsNotNone(t.agent_id)
+
+    def test_cancel_releases_slot(self):
+        c = LocalQueueHandoffClient(capacity=5, agent_pool_size=1)
+        t = c.create_ticket(user_id="u_cancel", subject="发票")
+        canceled = c.cancel_ticket(t.ticket_id, reason="用户主动取消")
+        self.assertIsNotNone(canceled)
+        self.assertEqual(canceled.status, TicketStatusEnum.CANCELED.value)
+        # After cancel, status still queryable (closed ticket), but overall_status.connected = 0
+        status = c.overall_status()
+        self.assertEqual(status.connected, 0)
+
+    def test_capacity_full_yields_timeout(self):
+        c = LocalQueueHandoffClient(capacity=1, agent_pool_size=0)
+        c.create_ticket(user_id="u_fill")
+        t2 = c.create_ticket(user_id="u_overflow")
+        self.assertEqual(t2.status, TicketStatusEnum.TIMEOUT.value)
+        self.assertIsNotNone(t2.closed_at)
+
+    def test_update_status_manual_close(self):
+        c = LocalQueueHandoffClient(capacity=5, agent_pool_size=1)
+        t = c.create_ticket(user_id="u_close")
+        # auto-connected → close
+        closed = c.update_status(t.ticket_id, "closed")
+        self.assertEqual(closed.status, TicketStatusEnum.CLOSED.value)
+        self.assertIsNotNone(closed.closed_at)
+        self.assertEqual(c.overall_status().connected, 0)
+
+    def test_get_or_attach_returns_active_only(self):
+        c = LocalQueueHandoffClient(capacity=5, agent_pool_size=0)
+        t = c.create_ticket(user_id="u_query")
+        same = c.get_or_attach("u_query")
+        self.assertEqual(same.ticket_id, t.ticket_id)
+        # After cancel, get_or_attach should return None (only returns active tickets)
+        c.cancel_ticket(t.ticket_id)
+        self.assertIsNone(c.get_or_attach("u_query"))
+
+
+class MockAdapterTests(unittest.TestCase):
+    """MockHandoffClient demo data should be pre-populated."""
+
+    def test_seed_three_tickets(self):
+        c = MockHandoffClient(seed_demo_data=True, agent_pool_size=2)
+        tickets = c.list_tickets(limit=10)
+        ids = {t.ticket_id for t in tickets}
+        # All three demo tickets present
+        self.assertIn("demo_pending_001", ids)
+        self.assertIn("demo_processing_001", ids)
+        self.assertIn("demo_closed_001", ids)
+        statuses = {t.status for t in tickets}
+        self.assertIn(TicketStatusEnum.PENDING.value, statuses)
+        self.assertIn(TicketStatusEnum.PROCESSING.value, statuses)
+        self.assertIn(TicketStatusEnum.CLOSED.value, statuses)
+
+    def test_seed_can_be_disabled(self):
+        c = MockHandoffClient(seed_demo_data=False, agent_pool_size=2)
+        self.assertEqual(c.list_tickets(), [])
+
+    def test_inherits_create_behavior(self):
+        c = MockHandoffClient(seed_demo_data=False, agent_pool_size=2)
+        t = c.create_ticket(user_id="u_new", subject="测试")
+        # agent_pool_size=2 → immediate connect
+        self.assertEqual(t.status, TicketStatusEnum.PROCESSING.value)
+
+
+class DefaultRestAdapterSecurityTests(unittest.TestCase):
+    """DefaultRestHandoffClient base_url security validation (no actual HTTP calls)."""
+
+    def test_https_public_allowed(self):
+        # No real HTTP: constructing the object is enough to trigger _validate_base_url
+        c = DefaultRestHandoffClient(base_url="https://crm.example.com")
+        # Verify the validated url via _base
+        self.assertTrue(c._base.startswith("https://"))
+
+    def test_localhost_http_allowed(self):
+        c = DefaultRestHandoffClient(base_url="http://localhost:8080")
+        self.assertIn("localhost", c._base)
+
+    def test_private_network_denied(self):
+        for url in (
+            "https://10.1.2.3",
+            "https://192.168.0.1",
+            "https://172.16.0.5",
+            "https://9.0.0.1",
+        ):
+            with self.subTest(url=url):
+                with self.assertRaises(ValueError):
+                    DefaultRestHandoffClient(base_url=url)
+
+    def test_non_https_remote_denied(self):
+        with self.assertRaises(ValueError):
+            DefaultRestHandoffClient(base_url="http://crm.example.com")
+
+    def test_create_ticket_calls_post(self):
+        """Simulate a successful create_ticket via requests, verify key payload fields."""
+        fake_resp = MagicMock()
+        fake_resp.status_code = 200
+        fake_resp.json.return_value = {
+            "ticket_id": "T-9001",
+            "queue_position": 2,
+            "eta_seconds": 60,
+        }
+
+        c = DefaultRestHandoffClient(base_url="https://crm.example.com", token="tok")
+        with patch.object(c._session, "post", return_value=fake_resp) as p:
+            t = c.create_ticket(
+                user_id="u9", subject="退款", description="3 天未到账"
+            )
+        self.assertEqual(t.ticket_id, "T-9001")
+        self.assertEqual(t.queue_position, 2)
+        # Verify call arguments
+        self.assertEqual(p.call_count, 1)
+        _, kwargs = p.call_args
+        self.assertEqual(kwargs["json"]["user_id"], "u9")
+        # Authorization header should carry Bearer
+        self.assertIn("Bearer ", kwargs["headers"]["Authorization"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/trtc-ai-service/tests/test_kb_ports.py

@@ -0,0 +1,195 @@
+"""Phase 3 Stage 6: knowledge-base capability ports/adapters unit tests.
+
+Coverage targets:
+- LocalJsonKbClient: reload / search (TF-IDF) / upsert / delete + stats
+- MockKbClient: 5 pre-seeded demo FAQ entries + keyword search hits
+- DefaultRestKbClient: base_url security validation + search/list_all via HTTP passthrough
+"""
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+
+# ---------------------------------------------------------------------------
+# Isolated import: clean src.* cache (avoid conflict with same-named src in test_handoff_ports)
+# ---------------------------------------------------------------------------
+_ROOT = Path(__file__).resolve().parent.parent
+_KB = _ROOT / "capabilities" / "knowledge-base"
+
+for _name in [k for k in list(sys.modules) if k == "src" or k.startswith("src.")]:
+    del sys.modules[_name]
+sys.path[:] = [p for p in sys.path if "/capabilities/" not in p]
+sys.path.insert(0, str(_KB))
+
+import importlib  # noqa: E402
+
+_models = importlib.import_module("src.core.models")
+FaqEntry = _models.FaqEntry
+
+from src.adapters.local_json import LocalJsonKbClient  # noqa: E402
+from src.adapters.mock import MockKbClient  # noqa: E402
+# 预先导入 default_rest（KB 版本）并固化引用，
+# 避免后续测试运行时 ``src`` 已被替换为 HH 命名空间
+from src.adapters import default_rest as _kb_default_rest  # noqa: E402
+
+DefaultRestKbClient = _kb_default_rest.DefaultRestKbClient
+
+
+class LocalJsonAdapterTests(unittest.TestCase):
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.data_path = Path(self._tmp.name) / "faq.json"
+        self.data_path.write_text(
+            json.dumps(
+                [
+                    {
+                        "id": "kb_refund",
+                        "question": "退款政策是什么？",
+                        "answer": "支持 7 天无理由退款",
+                        "keywords": ["退款", "退货", "refund"],
+                    },
+                    {
+                        "id": "kb_ship",
+                        "question": "物流多久送达？",
+                        "answer": "全国 3-5 天送达",
+                        "keywords": ["物流", "发货"],
+                    },
+                ],
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+        self.client = LocalJsonKbClient(
+            data_file=self.data_path, min_score=0.0, top_k=5
+        )
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_reload_loads_entries(self):
+        self.assertEqual(len(self.client.list_all()), 2)
+        stats = self.client.stats()
+        self.assertEqual(stats.backend, "local_json")
+        self.assertEqual(stats.entry_count, 2)
+        self.assertIsNotNone(stats.loaded_at)
+
+    def test_search_hits_by_keyword(self):
+        hits = self.client.search("退款", top_k=3)
+        self.assertTrue(len(hits) >= 1)
+        self.assertEqual(hits[0].entry.id, "kb_refund")
+        # score should be > 0
+        self.assertGreater(hits[0].score, 0.0)
+
+    def test_search_returns_empty_for_blank_query(self):
+        self.assertEqual(self.client.search(""), [])
+        self.assertEqual(self.client.search("   "), [])
+
+    def test_upsert_persists_to_disk(self):
+        new_entry = FaqEntry(
+            id="kb_invoice",
+            question="如何开发票？",
+            answer="下单时勾选需要发票",
+            keywords=["发票"],
+        )
+        self.client.upsert(new_entry)
+        self.assertEqual(len(self.client.list_all()), 3)
+
+        # 真正落盘了：重读文件
+        on_disk = json.loads(self.data_path.read_text(encoding="utf-8"))
+        ids = {e["id"] for e in on_disk}
+        self.assertIn("kb_invoice", ids)
+
+    def test_upsert_updates_existing(self):
+        updated = FaqEntry(
+            id="kb_refund",
+            question="退款政策（已更新）",
+            answer="支持 14 天无理由退款",
+            keywords=["退款"],
+        )
+        self.client.upsert(updated)
+        items = self.client.list_all()
+        self.assertEqual(len(items), 2)  # 总数不变
+        kept = next(e for e in items if e.id == "kb_refund")
+        self.assertIn("已更新", kept.question)
+
+    def test_delete_removes_entry(self):
+        ok = self.client.delete("kb_ship")
+        self.assertTrue(ok)
+        self.assertEqual(len(self.client.list_all()), 1)
+        # Non-existent id returns False
+        self.assertFalse(self.client.delete("nonexistent"))
+
+
+class MockKbAdapterTests(unittest.TestCase):
+
+    def test_seed_five_demo_entries(self):
+        c = MockKbClient(seed_demo_data=True)
+        items = c.list_all()
+        self.assertGreaterEqual(len(items), 5)
+        ids = {e.id for e in items}
+        for required in ("demo_refund", "demo_logistics", "demo_invoice"):
+            self.assertIn(required, ids)
+
+    def test_search_hits_chinese_keyword(self):
+        c = MockKbClient(seed_demo_data=True)
+        hits = c.search("物流")
+        self.assertTrue(any(h.entry.id == "demo_logistics" for h in hits))
+
+    def test_seed_disable(self):
+        c = MockKbClient(seed_demo_data=False)
+        self.assertEqual(c.list_all(), [])
+
+
+class DefaultRestKbAdapterSecurityTests(unittest.TestCase):
+
+    def test_https_public_allowed(self):
+        c = DefaultRestKbClient(base_url="https://kb.example.com")
+        self.assertTrue(c._base.startswith("https://"))
+
+    def test_localhost_http_allowed(self):
+        c = DefaultRestKbClient(base_url="http://127.0.0.1:9090")
+        self.assertIn("127.0.0.1", c._base)
+
+    def test_private_network_denied(self):
+        for url in ("https://10.1.1.1", "https://192.168.1.5"):
+            with self.subTest(url=url):
+                with self.assertRaises(ValueError):
+                    DefaultRestKbClient(base_url=url)
+
+    def test_search_calls_post(self):
+        fake_resp = MagicMock()
+        fake_resp.status_code = 200
+        fake_resp.json.return_value = {
+            "hits": [
+                {
+                    "entry": {
+                        "id": "1",
+                        "question": "退款？",
+                        "answer": "7 天无理由",
+                        "keywords": ["退款"],
+                    },
+                    "score": 0.85,
+                }
+            ]
+        }
+        c = DefaultRestKbClient(base_url="https://kb.example.com", token="tok")
+        with patch.object(c._session, "post", return_value=fake_resp) as p:
+            hits = c.search("退款", top_k=3)
+
+        self.assertEqual(len(hits), 1)
+        self.assertEqual(hits[0].entry.id, "1")
+        # Request URL path
+        args, kwargs = p.call_args
+        self.assertTrue(args[0].endswith("/faq/search"))
+        self.assertEqual(kwargs["json"]["query"], "退款")
+        self.assertEqual(kwargs["json"]["top_k"], 3)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/trtc-ai-service/tests/test_manifest_resolver.py

@@ -0,0 +1,95 @@
+"""Manifest parsing / topological order / circular dependency / version conflict / unknown injection point tests."""
+import os
+import sys
+import unittest
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_ROOT))
+
+from scripts.lib import manifest_resolver as mr
+
+
+def _mf(name, deps=(), inj=(), ext=(), typ="capability", version="1.0.0"):
+    return mr.Manifest(
+        name=name, version=version, type=typ,
+        dependencies=[mr.DependencySpec(d if isinstance(d, str) else d[0],
+                                        d[1] if isinstance(d, tuple) else "*") for d in deps],
+        injection_points=list(inj),
+        extensions=list(ext),
+    )
+
+
+class ManifestResolverTests(unittest.TestCase):
+
+    def setUp(self):
+        self.skeleton = _mf(
+            "conversation-core", typ="skeleton",
+            inj=[
+                {"id": "agent.before_start", "target": "src/agent.py", "position": "before:start_agent"},
+                {"id": "agent.after_start", "target": "src/agent.py", "position": "after:start_agent"},
+            ],
+        )
+
+    def test_topological_order_with_skeleton_first(self):
+        a = _mf("cap-a", deps=["conversation-core"])
+        b = _mf("cap-b", deps=["conversation-core", "cap-a"])
+        graph = mr.resolve([a, self.skeleton, b])
+        self.assertEqual(graph.skeleton.name, "conversation-core")
+        self.assertEqual(graph.order[0], "conversation-core")
+        # b must come after a
+        self.assertGreater(graph.order.index("cap-b"), graph.order.index("cap-a"))
+
+    def test_circular_dependency_detected(self):
+        a = _mf("cap-a", deps=["cap-b", "conversation-core"])
+        b = _mf("cap-b", deps=["cap-a", "conversation-core"])
+        with self.assertRaises(mr.CircularDependencyError):
+            mr.resolve([self.skeleton, a, b])
+
+    def test_unknown_injection_point_rejected(self):
+        bad = _mf(
+            "cap-x",
+            deps=["conversation-core"],
+            ext=[{"inject_at": "no.such.point"}],
+        )
+        with self.assertRaises(mr.UnknownInjectionPointError):
+            mr.resolve([self.skeleton, bad])
+
+    def test_known_injection_point_accepted(self):
+        ok = _mf(
+            "cap-y",
+            deps=["conversation-core"],
+            ext=[{"inject_at": "agent.before_start"}],
+        )
+        graph = mr.resolve([self.skeleton, ok])
+        self.assertIn("cap-y", graph.order)
+
+    def test_version_conflict_blocked(self):
+        strict = _mf("cap-z", deps=[("conversation-core", ">=2.0.0")])
+        with self.assertRaises(mr.VersionConflictError):
+            mr.resolve([self.skeleton, strict])
+
+    def test_semver_caret_compatibility(self):
+        self.assertTrue(mr.satisfies("1.4.2", "^1.0.0"))
+        self.assertFalse(mr.satisfies("2.0.0", "^1.0.0"))
+        self.assertTrue(mr.satisfies("1.4.0", ">=1.0.0,<2.0.0"))
+
+    def test_skeleton_uniqueness(self):
+        s2 = _mf("another-skeleton", typ="skeleton")
+        with self.assertRaises(mr.ManifestError):
+            mr.resolve([self.skeleton, s2])
+
+    def test_real_project_capabilities_resolve(self):
+        """The 6 capabilities in the real repo should all resolve correctly."""
+        manifests = mr.discover_manifests(_ROOT / "capabilities")
+        self.assertGreaterEqual(len(manifests), 6)
+        graph = mr.resolve(manifests)
+        self.assertEqual(graph.order[0], "conversation-core")
+        for n in ("knowledge-base", "tool-calling", "human-handoff",
+                  "session-summary", "digital-human"):
+            self.assertIn(n, graph.order)
+            self.assertGreater(graph.order.index(n), graph.order.index("conversation-core"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/trtc-ai-service/tests/test_recipe_assembly.py

@@ -0,0 +1,175 @@
+"""Phase 3 Stage 6: scenarios/* recipe static validation + Path B Jinja template rendering tests.
+
+Coverage targets:
+- Path A: scenarios/customer-service/recipe.yaml has valid structure and key fields present
+- Path B: output-templates/recipe.yaml.j2 rendered with 4 typical Q1~Q4 answer sets produces valid YAML with correct field linkage
+- ui_overlay referenced subdirectories widget-floating / admin-board all physically exist
+"""
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+import yaml
+
+_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_ROOT))
+
+_SCEN = _ROOT / "scenarios"
+_RECIPE_A = _SCEN / "customer-service" / "recipe.yaml"
+_TEMPLATE = _SCEN / "custom-builder" / "output-templates" / "recipe.yaml.j2"
+
+
+class CustomerServiceRecipeTests(unittest.TestCase):
+    """Path A default recipe static structure validation."""
+
+    def setUp(self):
+        self.assertTrue(_RECIPE_A.exists(), f"recipe.yaml not found: {_RECIPE_A}")
+        self.recipe = yaml.safe_load(_RECIPE_A.read_text(encoding="utf-8"))
+
+    def test_top_level_kind_and_api_version(self):
+        self.assertEqual(self.recipe.get("kind"), "Recipe")
+        self.assertEqual(self.recipe.get("apiVersion"), "ai-customer-service/v1")
+
+    def test_install_capabilities_contain_kb_and_handoff(self):
+        installs = self.recipe["capabilities"]["install"]
+        names = {c["name"] for c in installs}
+        self.assertIn("knowledge-base", names)
+        self.assertIn("human-handoff", names)
+        # adapter field must be explicitly given (out-of-box experience relies on mock / local_queue)
+        for c in installs:
+            self.assertIn("adapter", c)
+            self.assertIn("env", c)
+
+    def test_excluded_capability_is_digital_human(self):
+        excluded = self.recipe["capabilities"].get("excluded") or []
+        names = {c["name"] for c in excluded}
+        self.assertIn("digital-human", names)
+
+    def test_ui_overlay_layers_reference_real_dirs(self):
+        layers = self.recipe["ui_overlay"]["layers"]
+        ui_root = _SCEN / "customer-service" / "ui"
+        for layer in layers:
+            sub = ui_root / layer["source"]
+            self.assertTrue(sub.is_dir(), f"missing UI overlay source dir: {sub}")
+
+    def test_post_assembly_health_check_url(self):
+        hc = self.recipe["post_assembly"]["health_check"]
+        self.assertEqual(hc["url"], "http://localhost:3000/api/v1/health")
+
+    def test_design_locks_dark_no_emoji(self):
+        d = self.recipe["design"]
+        self.assertEqual(d["theme"], "dark")
+        self.assertFalse(d["emoji_in_ui"])
+
+
+# ---------------------------------------------------------------------------
+# Path B: Jinja2 template rendering (falls back to substring checks if Jinja2 unavailable)
+# ---------------------------------------------------------------------------
+try:
+    import jinja2  # type: ignore
+    _HAS_JINJA = True
+except ImportError:  # pragma: no cover
+    _HAS_JINJA = False
+
+
+class CustomBuilderTemplateStructureTests(unittest.TestCase):
+    """The key Jinja branch literals must exist in the template (does not depend on Jinja2 engine)."""
+
+    def setUp(self):
+        self.assertTrue(_TEMPLATE.exists(), f"template not found: {_TEMPLATE}")
+        self.text = _TEMPLATE.read_text(encoding="utf-8")
+
+    def test_io_modality_branches_present(self):
+        for modality in ("text_only", "text_with_tts", "omni", "voice_only"):
+            self.assertIn(modality, self.text)
+
+    def test_ui_form_branches_present(self):
+        for form in ("floating", "fullscreen", "headless"):
+            self.assertIn(form, self.text)
+
+    def test_capability_branches_present(self):
+        for cap in (
+            "knowledge-base",
+            "human-handoff",
+            "tool-calling",
+            "session-summary",
+        ):
+            self.assertIn(cap, self.text)
+
+    def test_excludes_digital_human(self):
+        self.assertIn("digital-human", self.text)
+        self.assertIn("excluded", self.text)
+
+
+@unittest.skipUnless(_HAS_JINJA, "jinja2 not installed; skip render assertions")
+class CustomBuilderTemplateRenderTests(unittest.TestCase):
+    """Jinja2 渲染后的 YAML 应可被 yaml.safe_load 解析，且关键字段按 Q 答联动。"""
+
+    def _render(self, **ctx) -> str:
+        env = jinja2.Environment(  # type: ignore[name-defined]
+            keep_trailing_newline=True,
+            trim_blocks=False,
+            lstrip_blocks=False,
+        )
+        tpl = env.from_string(_TEMPLATE.read_text(encoding="utf-8"))
+        return tpl.render(**ctx)
+
+    def test_render_text_with_tts_floating_kb_only(self):
+        out = self._render(
+            business_desc="我们是一家咖啡品牌的电商客服",
+            business_name="ACME",
+            io_modality="text_with_tts",
+            ui_form="floating",
+            extra_capabilities=["knowledge-base"],
+        )
+        data = yaml.safe_load(out)
+        self.assertEqual(data["apiVersion"], "ai-customer-service/v1")
+        # Q2 linkage
+        self.assertFalse(data["runtime_modality"]["voice_input"])
+        self.assertTrue(data["runtime_modality"]["voice_output"])
+        # Q3 联动
+        self.assertTrue(data["ui"]["overlay_required"])
+        # human-handoff not selected → admin-board layer not present
+        layer_sources = [l["source"] for l in data["ui"]["ui_overlay"]["layers"]]
+        self.assertIn("widget-floating", layer_sources)
+        self.assertNotIn("admin-board", layer_sources)
+        # Q4: only knowledge-base installed
+        installed_names = {c["name"] for c in data["capabilities"]["install"]}
+        self.assertEqual(installed_names, {"knowledge-base"})
+
+    def test_render_omni_fullscreen_with_handoff(self):
+        out = self._render(
+            business_desc="车企售后客服",
+            business_name="XYZ",
+            io_modality="omni",
+            ui_form="fullscreen",
+            extra_capabilities=["knowledge-base", "human-handoff"],
+        )
+        data = yaml.safe_load(out)
+        self.assertTrue(data["runtime_modality"]["voice_input"])
+        self.assertTrue(data["runtime_modality"]["text_input"])
+        # human-handoff selected → admin-board layer should exist
+        layer_sources = [l["source"] for l in data["ui"]["ui_overlay"]["layers"]]
+        self.assertIn("admin-board", layer_sources)
+        installed_names = {c["name"] for c in data["capabilities"]["install"]}
+        self.assertEqual(installed_names, {"knowledge-base", "human-handoff"})
+
+    def test_render_headless_no_overlay(self):
+        out = self._render(
+            business_desc="纯 API 后端客服",
+            business_name="BackOnly",
+            io_modality="text_only",
+            ui_form="headless",
+            extra_capabilities=[],
+        )
+        data = yaml.safe_load(out)
+        self.assertFalse(data["ui"]["overlay_required"])
+        self.assertIsNone(data["ui"]["ui_overlay"])
+        # User selected no capabilities → install list is empty
+        self.assertEqual(data["capabilities"]["install"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()