writer-work-flow/packages/agents/tests/test_generation_specs.py

"""T5.1 worldbuilder + character-gen 契约测试：spec + schema（C6 扩 / ARCH §5.4 §6.5）。

契约测试——构造符合 schema 的 mock 响应，校验字段、tier、读写权限。
worldbuilder：`{entities:[{type,name,rules}]}` 硬规则显式（写手档，reads=projects）。
character-gen：`{cards:[{name,role,traits,backstory,arc,speech_tics,tags,relations}]}`
（写手档，reads=world_entities+characters，writes=characters）。不联网、无 DB。
"""

from __future__ import annotations

import pytest
from pydantic import ValidationError
from ww_agents import (
    AgentSpec,
    CharacterCard,
    CharacterGenResult,
    CharacterRelation,
    WorldEntityCard,
    WorldGenResult,
    character_gen_spec,
    worldbuilder_spec,
)

# ---- WorldGenResult schema（worldbuilder）----


def test_world_gen_parses_mock_response() -> None:
    # Arrange：模拟网关 instructor 校验后的结构化世界观产出（硬规则显式）
    mock = {
        "entities": [
            {
                "type": "力量体系",
                "name": "九转炼气",
                "rules": ["只能逐境突破，不可越级", "突破必有反噬代价"],
            },
            {"type": "地理", "name": "无雨城", "rules": ["终年无雨"]},
        ]
    }

    # Act
    result = WorldGenResult.model_validate(mock)

    # Assert
    assert len(result.entities) == 2
    assert result.entities[0].type == "力量体系"
    assert result.entities[0].name == "九转炼气"
    assert result.entities[0].rules == ["只能逐境突破，不可越级", "突破必有反噬代价"]
    assert result.entities[1].rules == ["终年无雨"]


def test_world_gen_defaults_to_empty_entities() -> None:
    assert WorldGenResult().entities == []


def test_world_entity_rules_default_empty() -> None:
    card = WorldEntityCard.model_validate({"type": "势力", "name": "天剑宗"})
    assert card.rules == []


def test_world_entity_requires_type_and_name() -> None:
    with pytest.raises(ValidationError):
        WorldEntityCard.model_validate({"type": "势力"})


# ---- CharacterGenResult schema（character-gen）----


def test_character_gen_parses_mock_response() -> None:
    mock = {
        "cards": [
            {
                "name": "苏黎",
                "role": "对手",
                "traits": ["表面冷漠", "内心挣扎"],
                "backstory": "出身敌对势力，幼年遭灭门。",
                "arc": "复仇者 → 动摇 → 救赎",
                "speech_tics": ["惯用反问", "句末带『罢了』"],
                "tags": ["亦正亦邪", "宿命纠葛"],
                "relations": [{"name": "主角", "kind": "宿敌", "note": "灭门之仇"}],
            }
        ]
    }

    result = CharacterGenResult.model_validate(mock)

    assert len(result.cards) == 1
    card = result.cards[0]
    assert card.name == "苏黎"
    assert card.role == "对手"
    assert card.traits == ["表面冷漠", "内心挣扎"]
    assert card.speech_tics == ["惯用反问", "句末带『罢了』"]
    assert card.relations[0].name == "主角"
    assert card.relations[0].kind == "宿敌"
    assert card.relations[0].note == "灭门之仇"


def test_character_gen_defaults_to_empty_cards() -> None:
    assert CharacterGenResult().cards == []


def test_character_card_optional_collections_default_empty() -> None:
    card = CharacterCard.model_validate(
        {"name": "甲", "role": "工具人", "backstory": "无名小卒", "arc": "始终如一"}
    )
    assert card.traits == []
    assert card.speech_tics == []
    assert card.tags == []
    assert card.relations == []


def test_character_card_requires_core_fields() -> None:
    # name/role/backstory/arc 为必填
    with pytest.raises(ValidationError):
        CharacterCard.model_validate({"name": "甲", "role": "对手"})


def test_character_relation_note_optional() -> None:
    rel = CharacterRelation.model_validate({"name": "师父", "kind": "师徒"})
    assert rel.note is None


# ---- worldbuilder_spec 声明 ----


def test_worldbuilder_spec_is_writer_tier() -> None:
    # 不变量 #2：世界观创意用写手档，只声明 tier
    assert worldbuilder_spec.tier == "writer"
    assert worldbuilder_spec.name == "worldbuilder"


def test_worldbuilder_spec_reads_projects_writes_world_entities() -> None:
    assert worldbuilder_spec.reads == ("projects",)
    assert worldbuilder_spec.writes == ("world_entities",)


def test_worldbuilder_spec_output_schema() -> None:
    assert worldbuilder_spec.output_schema is WorldGenResult


def test_worldbuilder_spec_prompt_documents_hard_rules() -> None:
    # 硬规则须显式（供 continuity 校验引用）——system_prompt 必须强调
    assert "硬规则" in worldbuilder_spec.system_prompt


# ---- character_gen_spec 声明 ----


def test_character_gen_spec_is_writer_tier() -> None:
    assert character_gen_spec.tier == "writer"
    assert character_gen_spec.name == "character-gen"


def test_character_gen_spec_reads_world_and_characters() -> None:
    # reads=world_entities+characters（约束 + 防雷同对照），writes=characters
    assert character_gen_spec.reads == ("world_entities", "characters")
    assert character_gen_spec.writes == ("characters",)


def test_character_gen_spec_output_schema() -> None:
    assert character_gen_spec.output_schema is CharacterGenResult


def test_character_gen_spec_prompt_documents_anti_duplication() -> None:
    # M5-a 群像防雷同：prompt 必须注入「已生成卡 + 已有角色」差异化要求
    prompt = character_gen_spec.system_prompt
    assert "已有角色" in prompt
    assert "已生成卡" in prompt
    assert "防雷同" in prompt


# ---- 共性：immutable + 是 AgentSpec ----


def test_generation_specs_are_agent_specs() -> None:
    assert isinstance(worldbuilder_spec, AgentSpec)
    assert isinstance(character_gen_spec, AgentSpec)


def test_generation_specs_are_immutable() -> None:
    with pytest.raises(ValidationError):
        worldbuilder_spec.tier = "analyst"
    with pytest.raises(ValidationError):
        character_gen_spec.tier = "analyst"