Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

53.9 KB
Raw Blame
"""
Tests for TemplateManager
"""

import shutil
import tempfile
from pathlib import Path

import pytest
import yaml

from src.xagent.templates.manager import TemplateManager


@pytest.fixture
def temp_templates_dir():
    """创建临时 templates 目录"""
    temp_dir = tempfile.mkdtemp()
    templates_dir = Path(temp_dir)

    # 创建有效的模板文件
    template1 = templates_dir / "customer_support.yaml"
    template1.write_text(
        """
id: customer_support
name: Customer Support Agent
category: Support
tags:
  - support
  - customer
descriptions:
  en: Professional customer support assistant
  zh: 专业的客服助手
author: Xagent
version: "1.0"

agent_config:
  instructions: |
    You are a customer support assistant.
  skills:
    - product_knowledge
  tool_categories:
    - web_search
"""
    )

    template2 = templates_dir / "sales_assistant.yaml"
    template2.write_text(
        """
id: sales_assistant
name: Sales Assistant
category: Sales
tags:
  - sales
  - marketing
descriptions:
  en: Professional sales assistant
  zh: 专业的销售助手
author: Xagent
version: "1.0"

agent_config:
  instructions: |
    You are a sales assistant.
  skills:
    - sales_techniques
  tool_categories:
    - file_operations
"""
    )

    # 创建无效的模板文件(缺少必需字段)
    invalid_template = templates_dir / "invalid.yaml"
    invalid_template.write_text(
        """
name: Invalid Template
descriptions:
  en: This template is missing required fields
"""
    )

    # 创建非 YAML 文件(应被忽略)
    (templates_dir / "readme.txt").write_text("This is a readme file")

    yield templates_dir

    # 清理
    shutil.rmtree(temp_dir)


class TestTemplateManager:
    """测试 TemplateManager"""

    @pytest.mark.asyncio
    async def test_initialize_and_list_templates(self, temp_templates_dir):
        """测试初始化和列出模板"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        templates = await manager.list_templates()

        assert len(templates) == 2
        template_ids = [t["id"] for t in templates]
        assert "customer_support" in template_ids
        assert "sales_assistant" in template_ids

    @pytest.mark.asyncio
    async def test_get_template(self, temp_templates_dir):
        """测试获取单个模板"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("customer_support")

        assert template is not None
        assert template["id"] == "customer_support"
        assert template["name"] == "Customer Support Agent"
        assert template["category"] == "Support"
        assert (
            template["descriptions"]["en"] == "Professional customer support assistant"
        )
        assert template["descriptions"]["zh"] == "专业的客服助手"
        assert template["author"] == "Xagent"
        assert template["version"] == "1.0"
        assert "support" in template["tags"]
        assert "customer" in template["tags"]

    @pytest.mark.asyncio
    async def test_get_template_with_agent_config(self, temp_templates_dir):
        """测试获取模板的 agent_config"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("customer_support")

        assert "agent_config" in template
        assert "instructions" in template["agent_config"]
        assert (
            "customer support assistant"
            in template["agent_config"]["instructions"].lower()
        )
        assert template["agent_config"]["skills"] == ["product_knowledge"]
        assert template["agent_config"]["tool_categories"] == ["web_search"]

    @pytest.mark.asyncio
    async def test_get_nonexistent_template(self, temp_templates_dir):
        """测试获取不存在的模板"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("nonexistent")

        assert template is None

    @pytest.mark.asyncio
    async def test_reload_templates(self, temp_templates_dir):
        """测试重新加载模板"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        # 初始加载
        templates = await manager.list_templates()
        assert len(templates) == 2

        # 添加新模板
        new_template = temp_templates_dir / "data_analyst.yaml"
        new_template.write_text(
            """
id: data_analyst
name: Data Analyst
category: Data & Dev
tags:
  - data
descriptions:
  en: Data analysis expert
  zh: 数据分析专家
author: Xagent
version: "1.0"

agent_config:
  instructions: |
    You are a data analyst.
  skills: []
  tool_categories: []
"""
        )

        # 重新加载
        await manager.reload()
        templates = await manager.list_templates()

        assert len(templates) == 3
        template_ids = [t["id"] for t in templates]
        assert "data_analyst" in template_ids

    @pytest.mark.asyncio
    async def test_ensure_initialized(self, temp_templates_dir):
        """测试懒加载初始化"""
        manager = TemplateManager(templates_root=temp_templates_dir)

        # 未初始化时,has_templates 应该返回 False
        assert not manager.has_templates()

        # 调用 ensure_initialized
        await manager.ensure_initialized()

        # 初始化后,has_templates 应该返回 True
        assert manager.has_templates()

    @pytest.mark.asyncio
    async def test_parse_yaml_with_defaults(self, temp_templates_dir):
        """测试 YAML 解析时的默认值设置"""
        # 创建缺少可选字段的模板
        minimal_template = temp_templates_dir / "minimal.yaml"
        minimal_template.write_text(
            """
id: minimal_template
name: Minimal Template
category: Other
descriptions:
  en: A minimal template
  zh: 最小模板
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("minimal_template")

        assert template is not None
        # tags/features are per-locale dicts (like descriptions/sample_prompts),
        # so their "not authored" default is {} - get_localized_value resolves
        # that to [] per-locale at the API layer (see test_template_data_structure).
        assert template["tags"] == {}
        assert template["features"] == {}
        assert template["author"] == "Xagent"
        assert template["version"] == "1.0"
        assert template["featured"] is False
        assert template["sample_prompts"] == {}
        assert template["agent_config"]["instructions"] == ""
        assert template["agent_config"]["skills"] == []
        assert template["agent_config"]["tool_categories"] == []

    @pytest.mark.asyncio
    async def test_get_template_with_sample_prompts(self, temp_templates_dir):
        """测试模板的 sample_prompts 能正确加载并保留本地化结构"""
        template_with_prompts = temp_templates_dir / "with_prompts.yaml"
        template_with_prompts.write_text(
            """
id: with_prompts
name: Template With Prompts
category: Support
descriptions:
  en: A template with sample prompts
  zh: 一个带有示例提示词的模板
sample_prompts:
  en:
  - title: Do the thing
    prompt: 'Do the thing: paste input.'
    highlights:
    - paste input
  - title: Do another thing
    prompt: Do another thing entirely.
    highlights: []
  zh:
  - title: 做这件事
    prompt: 做这件事:粘贴输入。
    highlights:
    - 粘贴输入
  - title: 做另一件事
    prompt: 做另一件完全不同的事。
    highlights: []
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("with_prompts")

        assert template is not None
        assert len(template["sample_prompts"]["en"]) == 2
        assert template["sample_prompts"]["en"][0]["title"] == "Do the thing"
        assert template["sample_prompts"]["en"][0]["highlights"] == ["paste input"]
        assert template["sample_prompts"]["zh"][0]["title"] == "做这件事"

    @pytest.mark.asyncio
    async def test_malformed_sample_prompts_entry_is_skipped_not_fatal(
        self, temp_templates_dir
    ):
        """一个模板的 sample_prompts 条目缺少必需字段时,该模板应被跳过而不是让
        整个模板目录加载失败(避免单个作者错误导致 GET /api/templates/ 500)。"""
        bad_template = temp_templates_dir / "bad_prompts.yaml"
        bad_template.write_text(
            """
id: bad_prompts
name: Bad Prompts Template
category: Support
descriptions:
  en: A template with a malformed sample prompt
  zh: 一个带有格式错误提示词的模板
sample_prompts:
  en:
  - title: Missing the prompt field
    highlights: []
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("bad_prompts")
        assert template is None

        templates = await manager.list_templates()
        template_ids = [t["id"] for t in templates]
        assert "bad_prompts" not in template_ids
        # The other, valid templates in the fixture directory still load.
        assert "customer_support" in template_ids
        assert "sales_assistant" in template_ids

    @pytest.mark.asyncio
    async def test_flat_list_sample_prompts_is_rejected(self, temp_templates_dir):
        """sample_prompts 必须按语言分组({"en": [...]}),写成扁平列表会静默
        跳过本地化解析,因此在解析阶段就应当拒绝该写法。"""
        bad_template = temp_templates_dir / "flat_prompts.yaml"
        bad_template.write_text(
            """
id: flat_prompts
name: Flat Prompts Template
category: Support
descriptions:
  en: A template with a flat-list sample_prompts shape
  zh: 一个 sample_prompts 为扁平列表的模板
sample_prompts:
- title: Not locale-keyed
  prompt: This should have been nested under 'en'.
  highlights: []
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("flat_prompts")
        assert template is None

    @pytest.mark.asyncio
    async def test_get_template_with_persona(self, temp_templates_dir):
        """persona 应正确加载并保留本地化结构,供 marketplace 卡片使用。"""
        template_with_persona = temp_templates_dir / "with_persona.yaml"
        template_with_persona.write_text(
            """
id: with_persona
name: Social Media Content Manager
category: Marketing
descriptions:
  en: A template with a persona
  zh: 一个带有 persona 的模板
persona:
  name: Maya
  role:
    en: Social Media Content Manager
    zh: 社媒内容经理
  avatar: /marketplace/avatars/maya.png
  intro:
    en: "Hi — I'm Maya, your Social Media Content Manager."
    zh: 你好,我是 Maya,你的社媒内容经理。
  kickoff_questions:
    en:
    - Which platforms are in scope?
    - Do you have brand guidelines?
    zh:
    - 涉及哪些平台?
    - 有品牌规范吗?
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("with_persona")

        assert template is not None
        persona = template["persona"]
        assert persona["name"] == "Maya"
        assert persona["role"]["en"] == "Social Media Content Manager"
        assert persona["role"]["zh"] == "社媒内容经理"
        assert persona["avatar"] == "/marketplace/avatars/maya.png"
        assert len(persona["kickoff_questions"]["en"]) == 2

    @pytest.mark.asyncio
    async def test_persona_defaults_to_none_when_absent(self, temp_templates_dir):
        """没有 persona 字段的模板(如 workforce 类型)应保持 persona=None,
        而不是要求每个模板都作者一份 marketplace 卡片内容。"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("customer_support")

        assert template is not None
        assert template["persona"] is None

    @pytest.mark.asyncio
    async def test_persona_role_missing_en_falls_back_to_template_name_end_to_end(
        self, temp_templates_dir
    ):
        """A persona.role authored with no 'en' key loads successfully - the
        full YAML pipeline backfills persona.role.en from the template's
        own top-level `name` (see the unit-level assertion in
        TestValidatePersona for the exact mechanics)."""
        template_file = temp_templates_dir / "no_en_persona_role.yaml"
        template_file.write_text(
            """
id: no_en_persona_role
name: No En Persona Role Template
category: Support
descriptions:
  en: A template with a persona.role missing 'en'
  zh: 一个 persona.role 缺少 'en' 的模板
persona:
  name: Nia
  role:
    zh: 某个角色
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("no_en_persona_role")
        assert template is not None
        assert template["persona"]["role"]["en"] == "No En Persona Role Template"
        assert template["persona"]["role"]["zh"] == "某个角色"

    @pytest.mark.asyncio
    async def test_persona_intro_and_kickoff_without_en_key_still_optional(
        self, temp_templates_dir
    ):
        """persona.intro / persona.kickoff_questions themselves stay
        optional - omitting them entirely (not just their 'en' key) must
        not fail load. Unlike persona.role (backfilled from the template's
        `name` - see the test above), intro/kickoff have no fallback
        content, so an empty dict is the honest result of "not authored"."""
        template_file = temp_templates_dir / "persona_no_intro.yaml"
        template_file.write_text(
            """
id: persona_no_intro
name: Persona No Intro Template
category: Support
descriptions:
  en: A template whose persona has no intro or kickoff_questions at all
persona:
  name: Nia
  role:
    en: Some Role
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("persona_no_intro")
        assert template is not None
        assert template["persona"]["intro"] == {}
        assert template["persona"]["kickoff_questions"] == {}

    @pytest.mark.asyncio
    async def test_invalid_persona_skips_only_that_template(self, temp_templates_dir):
        """The end-to-end half of what TestValidatePersona covers at the
        unit level: a persona that fails validation must make the loader
        skip that one template (like any other parse failure), not crash
        the whole directory load or slip through unvalidated."""
        bad_template = temp_templates_dir / "flat_persona_role.yaml"
        bad_template.write_text(
            """
id: flat_persona_role
name: Flat Persona Role Template
category: Support
descriptions:
  en: A template with a flat persona.role
persona:
  name: Nia
  role: Some Role
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        assert await manager.get_template("flat_persona_role") is None
        # The sibling fixture templates in temp_templates_dir still load.
        assert await manager.list_templates()

    @pytest.mark.asyncio
    async def test_non_string_template_name_skips_the_template(
        self, temp_templates_dir
    ):
        """A non-string top-level `name` (e.g. YAML parsing `name: 2026` as
        an int) must fail at load time. Before this check, it was only
        tested for *presence*, so it flowed into the persona.role.en
        backfill and blew up as a pydantic ValidationError - a 500 on the
        whole list endpoint - the first time a response was built from it
        (PR #1498 round-2 review, M2)."""
        template_file = temp_templates_dir / "int_name.yaml"
        template_file.write_text(
            """
id: int_name
name: 2026
category: Support
descriptions:
  en: A template whose name YAML-parses as an int
persona:
  name: Nia
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        assert await manager.get_template("int_name") is None

    @pytest.mark.asyncio
    async def test_template_name_is_stripped_before_the_role_en_backfill(
        self, temp_templates_dir
    ):
        """The top-level `name` is stripped at load time, so the
        persona.role.en backfilled from it never carries surrounding
        whitespace that an authored (always-stripped) role.zh would not."""
        template_file = temp_templates_dir / "padded_name.yaml"
        template_file.write_text(
            """
id: padded_name
name: "  Padded Name Template  "
category: Support
descriptions:
  en: A template whose name has surrounding whitespace
persona:
  name: Nia
"""
        )

        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        template = await manager.get_template("padded_name")
        assert template is not None
        assert template["name"] == "Padded Name Template"
        assert template["persona"]["role"]["en"] == "Padded Name Template"

    @pytest.mark.asyncio
    async def test_workforce_template_with_a_persona_is_rejected(self, tmp_path):
        """persona is an agent-template concept - a workforce card renders
        from workforce_config instead (see _validate_persona's docstring).
        A workforce template authoring one anyway must fail to load rather
        than have the persona validated, backfilled, and served in silent
        contradiction of that contract (PR #1498 round-2 review, N3)."""
        (tmp_path / "persona_workforce.yaml").write_text(
            """
id: persona_workforce
name: Persona Workforce
category: Marketing
type: workforce
descriptions:
  en: A workforce template that wrongly authors a persona.
persona:
  name: Nia
workforce_config:
  manager:
    name: Growth Manager
    instructions: Orchestrate.
  agents:
  - template_id: ga-analyzer
    name: GA Analyzer
    assignment_instructions: Measure performance.
"""
        )
        manager = TemplateManager(templates_root=tmp_path)
        await manager.initialize()

        assert await manager.get_template("persona_workforce") is None

    @pytest.mark.asyncio
    async def test_skip_invalid_templates(self, temp_templates_dir):
        """测试跳过无效的模板文件"""
        manager = TemplateManager(templates_root=temp_templates_dir)
        await manager.initialize()

        # invalid.yaml 缺少必需字段,应该被跳过
        # readme.txt 不是 YAML 文件,应该被忽略
        templates = await manager.list_templates()

        assert len(templates) == 2
        template_ids = [t["id"] for t in templates]
        assert "invalid" not in template_ids

    @pytest.mark.asyncio
    async def test_empty_templates_directory(self, tmp_path):
        """测试空的模板目录"""
        manager = TemplateManager(templates_root=tmp_path)
        await manager.initialize()

        templates = await manager.list_templates()

        assert len(templates) == 0
        assert not manager.has_templates()

    def test_builtin_templates_that_use_web_search_select_web_tools_category(self):
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        markers = (
            "web_search",
            "zhipu_web_search",
            "exa_web_search",
            "tavily_web_search",
            "web research",
            "web search",
        )
        offenders: list[str] = []

        for template_file in built_in_dir.glob("*.yaml"):
            data = yaml.safe_load(template_file.read_text(encoding="utf-8")) or {}
            agent_config = data.get("agent_config") or {}
            instructions = str(agent_config.get("instructions") or "").lower()
            tool_categories = agent_config.get("tool_categories") or []
            if any(marker in instructions for marker in markers):
                if "web_tools" not in tool_categories:
                    offenders.append(template_file.name)

        assert not offenders

    def test_builtin_templates_directory_loads_every_file_without_silent_skips(self):
        """TemplateManager.reload() silently skips a file that fails to parse or is
        missing a required field (see manager.py's except/continue in reload()). Assert
        every real built_in/*.yaml is actually indexed, so a broken new template fails
        this test instead of just vanishing from the UI at runtime."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        yaml_files = list(built_in_dir.glob("*.yaml"))
        assert yaml_files, "expected at least one built-in template file"

        manager = TemplateManager(templates_root=built_in_dir)
        ids = {manager._parse_yaml_file(f)["id"] for f in yaml_files}

        assert len(ids) == len(yaml_files)
        for expected_id in (
            "sales-meeting-agent",
            "marketing-google-analytics-analyzer",
            "marketing-google-ads-recommendation",
            "operations-devops-ai-agent",
        ):
            assert expected_id in ids

    def test_builtin_agent_templates_all_have_a_persona(self):
        """Every 'agent'-type built-in template must carry a marketplace
        persona - a newly added agent template with no persona would
        otherwise silently ship a nameless, avatar-less marketplace card
        with no test catching the gap. The single 'workforce'-type
        template is deliberately excluded (its card renders from
        workforce_config instead - see TemplateManager._enrich_template)."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        manager = TemplateManager(templates_root=built_in_dir)
        offenders = [
            template_file.name
            for template_file in built_in_dir.glob("*.yaml")
            if (data := manager._parse_yaml_file(template_file)).get("type", "agent")
            == "agent"
            and data.get("persona") is None
        ]

        assert not offenders

    def test_builtin_persona_avatars_resolve_to_committed_files(self):
        """persona.avatar is an app-relative path resolved against the
        Next.js frontend's own static assets (frontend/public/...), a
        distinct convention from Agent.logo_url's /uploads/agent_logos
        path or connections[].logo's external hotlinks (PR #1498 review,
        M2/M3) - nothing ties it to a real committed file, so a future
        rename or a typo'd path would ship a 404 image with no test
        failure. Mirrors the existing connections/MCP-app invariant test
        below for the same class of drift."""
        repo_root = Path(__file__).resolve().parents[2]
        built_in_dir = repo_root / "src/xagent/templates/built_in"
        frontend_public_dir = repo_root / "frontend/public"
        manager = TemplateManager(templates_root=built_in_dir)

        offenders: list[str] = []
        for template_file in built_in_dir.glob("*.yaml"):
            persona = manager._parse_yaml_file(template_file).get("persona")
            if not persona or not persona.get("avatar"):
                continue
            avatar_path = persona["avatar"]
            if not avatar_path.startswith("/"):
                offenders.append(
                    f"{template_file.name}: not app-relative: {avatar_path}"
                )
                continue
            if not (frontend_public_dir / avatar_path.lstrip("/")).is_file():
                offenders.append(f"{template_file.name}: missing file: {avatar_path}")

        assert not offenders

    def test_builtin_persona_names_and_avatars_are_unique(self):
        """Two templates sharing a persona name or avatar would make two
        distinct marketplace cards look like the same AI teammate."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        manager = TemplateManager(templates_root=built_in_dir)

        names: list[str] = []
        avatars: list[str] = []
        for template_file in built_in_dir.glob("*.yaml"):
            persona = manager._parse_yaml_file(template_file).get("persona")
            if not persona:
                continue
            names.append(persona["name"])
            if persona.get("avatar"):
                avatars.append(persona["avatar"])

        assert len(names) == len(set(names)), f"duplicate persona names: {names}"
        assert len(avatars) == len(set(avatars)), (
            f"duplicate persona avatars: {avatars}"
        )

    def test_builtin_personas_author_role_en_explicitly(self):
        """Built-in personas must author role.en as a real job title
        instead of leaning on the fallback-to-`name` backfill: the
        template display name is a product name, and several leak badly
        as persona copy ("Google Ads Recommendation", "Email Agent
        (Sales)") - PR #1498 round-3 review. The fallback stays for
        external/user-authored templates; this pins the content bar for
        shipped ones. Reads the raw YAML because the parsed dict has the
        backfill already applied and can't tell the two apart."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        offenders = []
        for template_file in built_in_dir.glob("*.yaml"):
            raw = yaml.safe_load(template_file.read_text())
            persona = raw.get("persona")
            if not persona:
                continue
            role = persona.get("role") or {}
            if not role.get("en"):
                offenders.append(template_file.name)

        assert not offenders, f"personas relying on the role.en fallback: {offenders}"

    def test_builtin_template_connections_resolve_to_a_registered_mcp_app(self):
        """A connections[].name that the build wizard can't resolve to a registered
        built-in MCP app (src/xagent/web/builtin_mcp_registry.py) makes its Configure
        step un-completable (see PR #1023 review). Mirror the frontend's lenient
        name/app_id matching (lowercase + trim, plus a hyphen-for-space variant) so
        this doesn't false-flag entries the wizard would actually resolve."""
        from src.xagent.web.builtin_mcp_registry import get_builtin_public_mcp_app_rows

        def lookup_keys(*values):
            keys = set()
            for value in values:
                normalized = str(value or "").strip().lower()
                if not normalized:
                    continue
                keys.add(normalized)
                keys.add(normalized.replace(" ", "-"))
            return keys

        registered_keys = set()
        for row in get_builtin_public_mcp_app_rows():
            registered_keys |= lookup_keys(row.get("name"), row.get("app_id"))

        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        offenders: list[str] = []

        for template_file in built_in_dir.glob("*.yaml"):
            data = yaml.safe_load(template_file.read_text(encoding="utf-8")) or {}
            for conn in data.get("connections") or []:
                name = conn.get("name") if isinstance(conn, dict) else conn
                if name and not (lookup_keys(name) & registered_keys):
                    offenders.append(f"{template_file.name}: {name}")

        assert not offenders

    def test_builtin_workforce_connections_are_union_of_sub_template_connections(self):
        """A `type: workforce` template's `connections:` is hand-maintained
        display-only data (see the comment above `connections:` in
        marketing-growth-marketing-workforce.yaml) - nothing in
        `TemplateManager` derives or validates it against the sub-templates
        it actually references. That invariant has drifted and been
        hand-fixed at least twice already (PR #1127 re-review, F7; and
        again when the Google Analytics connector was added to
        marketing-google-analytics-analyzer). Assert it generically for
        every built-in workforce template so this class of drift is caught
        automatically instead of relying on a reviewer to notice."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )

        def connection_names(data):
            return {
                conn.get("name") if isinstance(conn, dict) else conn
                for conn in data.get("connections") or []
            }

        templates_by_id = {}
        for template_file in built_in_dir.glob("*.yaml"):
            data = yaml.safe_load(template_file.read_text(encoding="utf-8")) or {}
            template_id = data.get("id")
            if template_id:
                templates_by_id[template_id] = data

        offenders: list[str] = []
        for template_id, data in templates_by_id.items():
            if data.get("type") != "workforce":
                continue

            workforce_config = data.get("workforce_config") or {}
            sub_template_ids = [
                agent.get("template_id")
                for agent in workforce_config.get("agents") or []
            ]
            expected = set()
            for sub_template_id in sub_template_ids:
                sub_template = templates_by_id.get(sub_template_id)
                if sub_template is not None:
                    expected |= connection_names(sub_template)

            actual = connection_names(data)
            if actual != expected:
                offenders.append(
                    f"{template_id}: connections {sorted(actual)} != union of "
                    f"sub-template connections {sorted(expected)}"
                )

        assert not offenders, "\n".join(offenders)

    @pytest.mark.asyncio
    async def test_builtin_ga_analyzer_preconfigures_google_analytics_connector(self):
        """The GA Analyzer template must ship with the Google Analytics
        connector preconfigured: declared under `connections:` (so the card
        advertises it and the build wizard preconnects it) and merged into
        the enriched agent_config.tool_categories as an `mcp:` entry (so an
        agent created from the template actually gets the connector). Its
        instructions promise a live GA4 pull - without the connector that
        promise is dead on arrival."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        manager = TemplateManager(templates_root=built_in_dir)
        template = await manager.get_template("marketing-google-analytics-analyzer")

        assert template is not None
        connection_names = [
            conn.get("name")
            for conn in template["connections"]
            if isinstance(conn, dict)
        ]
        assert "Google Analytics" in connection_names
        assert "mcp:Google Analytics" in template["agent_config"]["tool_categories"]

    def test_builtin_sample_prompt_highlights_are_literal_substrings(self):
        """Every highlight must be a literal substring of its own prompt, in
        both locales - otherwise the frontend's highlight matching
        (replaceFirstOccurrence) silently underlines nothing, or the wrong
        word if an earlier literal duplicate shadows the intended placeholder
        (this caught a real bug: see marketing-content-agent and
        marketing-seo-brief-writer's original prompt wording)."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        offenders: list[str] = []

        for template_file in sorted(built_in_dir.glob("*.yaml")):
            data = yaml.safe_load(template_file.read_text(encoding="utf-8")) or {}
            sample_prompts = data.get("sample_prompts") or {}
            if not isinstance(sample_prompts, dict):
                offenders.append(
                    f"{template_file.name}: sample_prompts is not a per-locale dict"
                )
                continue

            for locale, prompts in sample_prompts.items():
                for entry in prompts or []:
                    prompt_text = entry.get("prompt") or ""
                    for highlight in entry.get("highlights") or []:
                        if highlight not in prompt_text:
                            offenders.append(
                                f"{template_file.name} [{locale}]: highlight "
                                f"{highlight!r} not found in prompt {prompt_text!r}"
                            )

        assert not offenders, "\n".join(offenders)

    @pytest.mark.asyncio
    async def test_nonexistent_templates_directory(self, tmp_path):
        """测试不存在的模板目录"""
        nonexistent_dir = tmp_path / "nonexistent"
        manager = TemplateManager(templates_root=nonexistent_dir)

        # 应该不抛出异常,只是记录警告
        await manager.initialize()

        templates = await manager.list_templates()

        assert len(templates) == 0

    # ----- workforce_config validation (PR #1127 review: zero coverage) -----

    @staticmethod
    def _valid_workforce_config():
        return {
            "manager": {
                "name": "Growth Manager",
                "instructions": "Orchestrate.",
                "execution_mode": "think",
                "tool_categories": ["basic"],
                "skills": [],
            },
            "agents": [
                {
                    "template_id": "ga-analyzer",
                    "name": "GA Analyzer",
                    "assignment_instructions": "Measure performance.",
                },
                {
                    "template_id": "ads-recommendation",
                    "name": "Ads Recommendation",
                    "assignment_instructions": "Recommend spend changes.",
                },
            ],
        }

    def test_valid_workforce_config_does_not_raise(self, tmp_path):
        manager = TemplateManager(templates_root=tmp_path)
        manager._validate_workforce_config(self._valid_workforce_config())

    @pytest.mark.parametrize(
        "mutate,match",
        [
            (lambda c: "not a dict", "must be a mapping"),
            (lambda c: {**c, "manager": None}, "manager.*must be a mapping"),
            (
                lambda c: {**c, "manager": {"name": "M", "instructions": "  "}},
                "manager.instructions",
            ),
            (lambda c: {**c, "manager": {"instructions": "Go"}}, "manager.name"),
            # Strict isinstance(str) - str(...) coercion used to let YAML
            # lists/ints through load-time validation, only to surface as
            # garbage prompts/ids (or an AttributeError -> 500 for the
            # normalize_text'd optional fields) at instantiation time
            # (PR #1127 re-review, m1).
            (
                lambda c: {
                    **c,
                    "manager": {**c["manager"], "instructions": ["not", "a", "str"]},
                },
                "manager.instructions",
            ),
            (
                lambda c: {**c, "manager": {**c["manager"], "description": 123}},
                "manager.description",
            ),
            (
                lambda c: {**c, "agents": [{**c["agents"][0], "template_id": 42}]},
                r"agents\[0\]\.template_id",
            ),
            (
                lambda c: {**c, "agents": [{**c["agents"][0], "alias": ["GA"]}]},
                r"agents\[0\]\.alias",
            ),
            (lambda c: {**c, "agents": None}, "agents.*non-empty list"),
            (lambda c: {**c, "agents": []}, "agents.*non-empty list"),
            (lambda c: {**c, "agents": ["not a dict"]}, r"agents\[0\].*mapping"),
            (
                lambda c: {**c, "agents": [{**c["agents"][0], "template_id": ""}]},
                r"agents\[0\]\.template_id",
            ),
            (
                lambda c: {**c, "agents": [{**c["agents"][0], "name": ""}]},
                r"agents\[0\]\.name",
            ),
            (
                lambda c: {
                    **c,
                    "agents": [{**c["agents"][0], "assignment_instructions": ""}],
                },
                r"agents\[0\]\.assignment_instructions",
            ),
            (
                lambda c: {
                    **c,
                    "agents": [
                        c["agents"][0],
                        {
                            **c["agents"][1],
                            "template_id": c["agents"][0]["template_id"],
                        },
                    ],
                },
                "duplicate template_id",
            ),
            (
                lambda c: {
                    **c,
                    "manager": {**c["manager"], "execution_mode": "sonic"},
                },
                "manager.execution_mode",
            ),
            (
                lambda c: {
                    **c,
                    "manager": {**c["manager"], "tool_categories": "basic"},
                },
                "manager.tool_categories",
            ),
            (
                lambda c: {**c, "manager": {**c["manager"], "skills": [123]}},
                "manager.skills",
            ),
        ],
    )
    def test_invalid_workforce_config_raises(self, tmp_path, mutate, match):
        manager = TemplateManager(templates_root=tmp_path)
        config = mutate(self._valid_workforce_config())
        with pytest.raises(ValueError, match=match):
            manager._validate_workforce_config(config)

    def test_workforce_config_strings_are_normalized_in_place(self, tmp_path):
        """Validation strips string fields in place. A template_id with
        surrounding whitespace used to be stripped for the duplicate check
        but looked up RAW at instantiation time, guaranteeing a
        "references an unknown template" 400 the moment anyone used the
        template (PR #1127 re-review, m1)."""
        manager = TemplateManager(templates_root=tmp_path)
        config = self._valid_workforce_config()
        config["agents"][0]["template_id"] = "  ga-analyzer  "
        config["manager"]["name"] = " Growth Manager "

        manager._validate_workforce_config(config)

        assert config["agents"][0]["template_id"] == "ga-analyzer"
        assert config["manager"]["name"] == "Growth Manager"

    @pytest.mark.asyncio
    async def test_workforce_type_template_requires_workforce_config(self, tmp_path):
        """A `type: workforce` template with no workforce_config at all must
        fail to load (not silently become a broken, config-less template)."""
        (tmp_path / "broken_workforce.yaml").write_text(
            """
id: broken_workforce
name: Broken Workforce
category: Marketing
type: workforce
descriptions:
  en: Missing workforce_config entirely.
"""
        )
        manager = TemplateManager(templates_root=tmp_path)
        await manager.initialize()

        assert await manager.get_template("broken_workforce") is None

    @pytest.mark.asyncio
    async def test_agent_type_template_never_sees_workforce_validation(self, tmp_path):
        """type defaults to 'agent' and must not trip workforce_config
        validation just because a template happens to omit it (the common
        case for every pre-existing template)."""
        (tmp_path / "plain_agent.yaml").write_text(
            """
id: plain_agent
name: Plain Agent
category: General
descriptions:
  en: A normal single-agent template.
agent_config:
  instructions: You help with things.
"""
        )
        manager = TemplateManager(templates_root=tmp_path)
        await manager.initialize()

        template = await manager.get_template("plain_agent")
        assert template is not None
        assert template["type"] == "agent"
        assert template["workforce_config"] is None
        assert template["agent_config"]["instructions"]

    # ----- _warn_on_dangling_workforce_references -----

    @pytest.mark.asyncio
    async def test_dangling_workforce_reference_warns_but_still_loads(
        self, tmp_path, caplog
    ):
        (tmp_path / "wf.yaml").write_text(
            """
id: wf
name: WF
category: Marketing
type: workforce
descriptions:
  en: A workforce with a typo'd worker reference.
workforce_config:
  manager:
    name: Manager
    instructions: Orchestrate.
  agents:
  - template_id: does-not-exist
    name: Ghost Worker
    assignment_instructions: Do the thing.
"""
        )
        manager = TemplateManager(templates_root=tmp_path)
        with caplog.at_level("WARNING"):
            await manager.initialize()

        assert await manager.get_template("wf") is not None
        assert any(
            "does-not-exist" in record.message and record.levelname == "WARNING"
            for record in caplog.records
        )

    @pytest.mark.asyncio
    async def test_workforce_referencing_another_workforce_warns(
        self, tmp_path, caplog
    ):
        """agents[].template_id must resolve to an 'agent'-type template - a
        workforce referencing another workforce as a worker would crash at
        instantiation time (that template's agent_config is null), so this
        must be flagged at load time too, not just guarded at the point of
        use."""
        (tmp_path / "inner.yaml").write_text(
            """
id: inner
name: Inner
category: Marketing
type: workforce
descriptions:
  en: Another workforce, wrongly used as a worker below.
workforce_config:
  manager:
    name: Inner Manager
    instructions: Orchestrate.
  agents:
  - template_id: leaf
    name: Leaf
    assignment_instructions: Do the thing.
"""
        )
        (tmp_path / "leaf.yaml").write_text(
            """
id: leaf
name: Leaf
category: Marketing
descriptions:
  en: A normal single-agent template.
agent_config:
  instructions: You help with things.
"""
        )
        (tmp_path / "outer.yaml").write_text(
            """
id: outer
name: Outer
category: Marketing
type: workforce
descriptions:
  en: References 'inner' (a workforce) as if it were a single agent.
workforce_config:
  manager:
    name: Outer Manager
    instructions: Orchestrate.
  agents:
  - template_id: inner
    name: Nested Workforce
    assignment_instructions: Do the thing.
"""
        )
        manager = TemplateManager(templates_root=tmp_path)
        with caplog.at_level("WARNING"):
            await manager.initialize()

        assert any(
            "outer" in record.message
            and "inner" in record.message
            and "not 'agent'" in record.message
            for record in caplog.records
        )

    @pytest.mark.asyncio
    async def test_builtin_workforce_template_references_resolve(self):
        """The real shipped YAML never loaded in any test before this - a
        typo'd `workforce_config.agents[].template_id` on the built-in
        Growth Marketing Workforce template would not have failed CI. Load
        the actual built_in/ directory and assert every workforce
        template's references resolve to a loaded 'agent'-type template."""
        built_in_dir = (
            Path(__file__).resolve().parents[2] / "src/xagent/templates/built_in"
        )
        manager = TemplateManager(templates_root=built_in_dir)
        await manager.initialize()
        templates = {t["id"]: t for t in await manager.list_templates()}

        workforce_templates = [
            t for t in templates.values() if t["type"] == "workforce"
        ]
        assert workforce_templates, "expected at least one built-in workforce template"

        offenders: list[str] = []
        for template in workforce_templates:
            workforce_config = template.get("workforce_config") or {}
            for agent in workforce_config.get("agents") or []:
                referenced_id = agent.get("template_id")
                referenced = templates.get(referenced_id)
                if referenced is None:
                    offenders.append(
                        f"{template['id']} -> unknown template_id {referenced_id!r}"
                    )
                elif referenced.get("type", "agent") != "agent":
                    offenders.append(
                        f"{template['id']} -> {referenced_id!r} has type="
                        f"{referenced.get('type')!r}, not 'agent'"
                    )

        assert not offenders, "\n".join(offenders)


class TestValidatePersona:
    """Unit tests calling TemplateManager._validate_persona directly - the
    same stronger pattern TestTemplateManager.test_invalid_workforce_config_raises
    already uses for _validate_workforce_config, so each rejection asserts
    the actual error message (not just "the template failed to load",
    which passes for any unrelated parse failure too)."""

    @pytest.fixture
    def manager(self, tmp_path):
        return TemplateManager(templates_root=tmp_path)

    def test_none_is_a_no_op(self, manager):
        """persona is optional; None must not raise."""
        manager._validate_persona(None)

    def test_not_a_mapping_is_rejected(self, manager):
        for bad_value in ("a string", ["a", "list"], 42):
            with pytest.raises(ValueError, match="persona.*must be a mapping"):
                manager._validate_persona(bad_value)

    def test_unknown_key_is_rejected(self, manager):
        """A typo'd or misspelled key (`avator`, `kickoff_question` singular)
        must fail loudly rather than silently parsing as an absent field -
        the whole point of `persona` being a real, validated schema."""
        persona = {"name": "Nia", "avator": "/marketplace/avatars/nia.png"}
        with pytest.raises(ValueError, match=r"unknown key\(s\).*avator"):
            manager._validate_persona(persona)

    def test_missing_name_is_rejected(self, manager):
        with pytest.raises(ValueError, match="persona.name"):
            manager._validate_persona({"role": {"en": "Some Role"}})

    def test_name_whitespace_is_stripped_in_place(self, manager):
        persona = {"name": "  Nia  "}
        manager._validate_persona(persona)
        assert persona["name"] == "Nia"

    def test_role_flat_string_is_rejected(self, manager):
        """persona.role must be locale-keyed ({"en": ...}); a flat string
        would silently bypass localization if it were allowed through."""
        with pytest.raises(ValueError, match="persona.role"):
            manager._validate_persona({"name": "Nia", "role": "Some Role"})

    def test_role_empty_locale_value_is_rejected(self, manager):
        with pytest.raises(ValueError, match="persona.role.en"):
            manager._validate_persona({"name": "Nia", "role": {"en": "   "}})

    def test_role_explicit_null_is_treated_as_absent(self, manager):
        """`role:` (YAML null) means "not provided", same as omitting the
        key - it must not reach the isinstance(role, dict) check as None."""
        persona = {"name": "Nia", "role": None}
        manager._validate_persona(persona)
        assert persona["role"] == {}

    def test_role_falsy_junk_is_still_rejected(self, manager):
        """Only None gets the treated-as-absent leniency: falsy junk like
        `role: ""` or `role: []` is a type error, not "not provided" - an
        `or {}` null-check would silently swallow these."""
        for junk in ("", []):
            with pytest.raises(ValueError, match="persona.role"):
                manager._validate_persona({"name": "Nia", "role": junk})

    def test_role_values_are_stripped_in_place(self, manager):
        persona = {"name": "Nia", "role": {"en": "  Some Role  "}}
        manager._validate_persona(persona)
        assert persona["role"]["en"] == "Some Role"

    def test_avatar_defaults_to_none_when_omitted(self, manager):
        persona = {"name": "Nia"}
        manager._validate_persona(persona)
        assert persona["avatar"] is None

    def test_avatar_wrong_type_is_rejected(self, manager):
        with pytest.raises(ValueError, match="persona.avatar"):
            manager._validate_persona({"name": "Nia", "avatar": 42})

    def test_avatar_empty_string_is_rejected(self, manager):
        with pytest.raises(ValueError, match="persona.avatar"):
            manager._validate_persona({"name": "Nia", "avatar": "   "})

    def test_avatar_is_stripped_in_place(self, manager):
        persona = {"name": "Nia", "avatar": "  /marketplace/avatars/nia.png  "}
        manager._validate_persona(persona)
        assert persona["avatar"] == "/marketplace/avatars/nia.png"

    def test_avatar_external_url_is_rejected(self, manager):
        """persona.avatar's contract is an app-relative path served from
        the frontend's own static assets - an external hotlink could rot,
        leak requests to a third party, and bypasses the committed-file
        invariant test (PR #1498 round-3 review)."""
        persona = {"name": "Nia", "avatar": "https://example.com/nia.png"}
        with pytest.raises(ValueError, match="persona.avatar.*app-relative"):
            manager._validate_persona(persona)

    def test_intro_flat_string_is_rejected(self, manager):
        with pytest.raises(ValueError, match="persona.intro"):
            manager._validate_persona({"name": "Nia", "intro": "Hi there"})

    def test_intro_explicit_null_is_treated_as_absent(self, manager):
        """Same null-vs-absent hazard as persona.role above, for the field
        the PR review specifically flagged (m2): `intro:` (YAML null) used
        to reach the isinstance check as None and raise the wrong message
        ("must be a dict... not a flat string") instead of being treated
        as simply not authored."""
        persona = {"name": "Nia", "intro": None}
        manager._validate_persona(persona)
        assert persona["intro"] == {}

    def test_intro_missing_en_is_rejected(self, manager):
        """persona.intro, once authored at all, must include 'en' -
        get_localized_value's fallback-to-'en' would otherwise resolve to
        "" for an English requester, silently seeding a blank opening
        message instead of failing loudly here at load time."""
        persona = {"name": "Nia", "intro": {"zh": "你好,我是 Nia。"}}
        with pytest.raises(ValueError, match="persona.intro.*'en'"):
            manager._validate_persona(persona)

    def test_intro_empty_locale_value_is_rejected(self, manager):
        with pytest.raises(ValueError, match="persona.intro.en"):
            manager._validate_persona({"name": "Nia", "intro": {"en": "  "}})

    def test_intro_values_are_stripped_in_place(self, manager):
        persona = {"name": "Nia", "intro": {"en": "  Hi there  "}}
        manager._validate_persona(persona)
        assert persona["intro"]["en"] == "Hi there"

    def test_kickoff_questions_flat_list_is_rejected(self, manager):
        """The likeliest real authoring mistake: writing kickoff_questions
        as a plain list instead of locale-keyed, the same class of bug
        `test_flat_list_sample_prompts_is_rejected` guards against for
        sample_prompts."""
        persona = {
            "name": "Nia",
            "kickoff_questions": ["What platforms are in scope?"],
        }
        with pytest.raises(ValueError, match="persona.kickoff_questions"):
            manager._validate_persona(persona)

    def test_kickoff_questions_explicit_null_is_treated_as_absent(self, manager):
        persona = {"name": "Nia", "kickoff_questions": None}
        manager._validate_persona(persona)
        assert persona["kickoff_questions"] == {}

    def test_kickoff_questions_empty_flat_list_is_still_rejected(self, manager):
        """An empty flat list is the same shape mistake as a populated one
        (test_kickoff_questions_flat_list_is_rejected) - being falsy must
        not earn it the None-only treated-as-absent leniency."""
        with pytest.raises(ValueError, match="persona.kickoff_questions"):
            manager._validate_persona({"name": "Nia", "kickoff_questions": []})

    def test_kickoff_questions_missing_en_is_rejected(self, manager):
        persona = {
            "name": "Nia",
            "kickoff_questions": {"zh": ["第一个问题?"]},
        }
        with pytest.raises(ValueError, match="persona.kickoff_questions.*'en'"):
            manager._validate_persona(persona)

    def test_kickoff_questions_empty_item_is_rejected(self, manager):
        persona = {"name": "Nia", "kickoff_questions": {"en": ["  "]}}
        with pytest.raises(ValueError, match="persona.kickoff_questions.en"):
            manager._validate_persona(persona)

    def test_kickoff_questions_non_string_item_is_rejected(self, manager):
        persona = {"name": "Nia", "kickoff_questions": {"en": [42]}}
        with pytest.raises(ValueError, match="persona.kickoff_questions.en"):
            manager._validate_persona(persona)

    def test_kickoff_questions_items_are_stripped_in_place(self, manager):
        persona = {
            "name": "Nia",
            "kickoff_questions": {"en": ["  What platforms?  "]},
        }
        manager._validate_persona(persona)
        assert persona["kickoff_questions"]["en"] == ["What platforms?"]

    def test_kickoff_questions_empty_locale_list_is_rejected(self, manager):
        """An authored `kickoff_questions.<locale>: []` used to pass
        vacuously (all() over an empty sequence is True) - the same blank
        content the require_en check exists to prevent. "No questions" is
        expressed by omitting the locale or the field entirely (PR #1498
        round-3 review)."""
        persona = {"name": "Nia", "kickoff_questions": {"en": []}}
        with pytest.raises(ValueError, match="persona.kickoff_questions.en"):
            manager._validate_persona(persona)

    def test_non_string_locale_key_is_rejected(self, manager):
        """YAML happily parses `true:` or `2026:` as non-string mapping
        keys; get_localized_value would never match them, so they are
        dead content that must fail loudly instead (PR #1498 round-3
        review)."""
        persona = {"name": "Nia", "role": {True: "Some Role"}}
        with pytest.raises(ValueError, match="locale keys must be non-empty"):
            manager._validate_persona(persona)