# ❌ 胖接口：一个接口承担了太多职责
class UniversalAIClient:
    def chat(self, prompt: str) -> str: ...
    def code_review(self, diff: str) -> list: ...
    def generate_image(self, desc: str) -> bytes: ...
    def analyze_sentiment(self, text: str) -> float: ...
    def summarize_document(self, doc: str) -> str: ...
    def translate(self, text: str, target_lang: str) -> str: ...
    
# 问题：如果你只需要聊天功能，却不得不了解所有方法

# ✅ 瘦接口：每个接口只做一件事
class ChatInterface:
    def chat(self, messages: list[Message]) -> Response: ...

class CodeReviewInterface:
    def review(self, diff: str, context: ReviewContext) -> ReviewResult: ...

class ImageGenerationInterface:
    def generate(self, prompt: str, options: ImageOptions) -> ImageResult: ...

# ✅ 清晰的 Intent 接口调用
review_intent = CodeReviewIntent(
    type="code_review",
    scope="function",
    focus_areas=["logic", "security"],
    constraints=Constraints(
        max_suggestions=5,
        severity_threshold="warning"
    ),
    output_format="inline_comments"
)

result = ai.execute(review_intent, context={"code": user_code})

# ❌ 边界模糊的契约
class VagueContract:
    """帮我处理数据"""
    pass  # 什么数据？怎么处理？处理到什么程度？

# ✅ 边界清晰的契约  
class ClearContract:
    """
    契约：CSV 数据清洗
    
    输入边界：
    - 格式：UTF-8 编码的 CSV 文件
    - 大小：最大 10MB
    - 列数：1-50 列
    - 行数：1-100,000 行
    
    处理边界：
    - 去除空行和完全重复的行
    - 标准化日期格式为 ISO 8601
    - 修复常见编码错误（如智能引号）
    - 不修改数据语义（不做聚合、不删除列）
    
    输出边界：
    - 格式：清洗后的 CSV
    - 编码：UTF-8
    - 包含：原始数据 + 清洗报告
    """

# ❌ 粒度太粗：一个接口做太多事
class OmnipotentAI:
    def do_something(self, description: str) -> Any:
        """
        根据描述做各种事情：
        - 可以写代码
        - 可以分析数据
        - 可以生成文档
        - 可以 debug
        """
        pass

# ❌ 粒度太细：过度碎片化
class OverlyGranularAI:
    def write_function_signature(self, name: str, params: list) -> str: ...
    def write_function_docstring(self, description: str) -> str: ...
    def write_function_body_line(self, line_number: int) -> str: ...
    def add_import_statement(self, module: str) -> str: ...

# ✅ 基于任务的粒度
class CodeGenerationInterface:
    def generate_function(self, spec: FunctionSpec) -> GeneratedFunction: ...
    def generate_class(self, spec: ClassSpec) -> GeneratedClass: ...
    def generate_module(self, spec: ModuleSpec) -> GeneratedModule: ...

class CodeModificationInterface:
    def refactor_function(self, func: Function, changes: RefactorPlan) -> Function: ...
    def add_error_handling(self, func: Function, error_types: list[Type]) -> Function: ...
    def optimize_performance(self, func: Function, target: OptimizationTarget) -> Function: ...

# ✅ 一致的动词前缀
interface.generate_function()      # 生成新内容
interface.refactor_function()      # 重构已有内容
interface.analyze_function()       # 分析内容
interface.validate_function()      # 验证内容

# ✅ 一致的参数顺序
interface.do_action(target, options, context)
# 而不是
interface.do_action(options, target, context)  # ❌ 不一致

# 基础积木
@dataclass
class Intent:
    """所有 Intent 的基类"""
    id: str
    timestamp: datetime
    
@dataclass  
class CodeIntent(Intent):
    """代码相关 Intent 的基类"""
    language: str
    code_context: CodeContext

# 组合成复杂 Intent
@dataclass
class GenerateAndReviewIntent(Intent):
    """组合：生成代码并评审"""
    generation: GenerateCodeIntent      # 基础积木 1
    review: CodeReviewIntent            # 基础积木 2
    execution_order: Literal["sequential", "parallel"]
    
    # 组合逻辑
    def execute(self, ai: AI) -> CombinedResult:
        if self.execution_order == "sequential":
            generated = ai.execute(self.generation)
            review_input = {**self.review, "code": generated}
            return ai.execute(review_input)
        else:
            # 并行执行
            ...

# 一个完整的代码审查工作流
workflow = Workflow([
    # Step 1: 理解代码
    UnderstandCodeIntent(files=changed_files),
    
    # Step 2: 分析影响
    AnalyzeImpactIntent(scope="module", dependencies=get_deps()),
    
    # Step 3: 检查安全
    SecurityReviewIntent(level="comprehensive"),
    
    # Step 4: 风格检查  
    StyleReviewIntent(standard="team_guidelines"),
    
    # Step 5: 综合生成报告
    GenerateReportIntent(
        sections=["summary", "issues", "suggestions", "action_items"],
        audience="developer"
    )
])

result = ai.execute_workflow(workflow)

# ✅ 向后兼容：添加新字段
class CodeReviewInput_v1:
    code: str
    
class CodeReviewInput_v2:
    code: str
    language: str           # 新增：可选，有默认值
    review_focus: list      # 新增：可选，有默认值

# 处理逻辑
if input.version == "v1":
    # 使用默认值填充新字段
    input.language = detect_language(input.code)
    input.review_focus = ["logic", "style"]

class AIContract:
    SUPPORTED_VERSIONS = ["1.0", "1.1", "2.0"]
    
    def execute(self, intent: Intent) -> Result:
        # 协商使用哪个版本
        requested_version = intent.version or "1.0"
        
        if requested_version not in self.SUPPORTED_VERSIONS:
            # 找到最接近的兼容版本
            compatible_version = self._find_compatible_version(requested_version)
            return VersionNegotiationResponse(
                requested=requested_version,
                actual=compatible_version,
                breaking_changes=self._get_breaking_changes(requested_version)
            )
        
        return self._execute_with_version(intent, requested_version)

class IntentMigration:
    """Intent 版本迁移工具"""
    
    MIGRATIONS = {
        ("1.0", "2.0"): migrate_v1_to_v2,
        ("2.0", "2.1"): migrate_v2_to_v2_1,
    }
    
    @staticmethod
    def migrate(intent: Intent, target_version: str) -> Intent:
        current = intent.version
        
        while current != target_version:
            next_version = find_next_version(current, target_version)
            migrator = MIGRATIONS.get((current, next_version))
            
            if not migrator:
                raise MigrationError(f"无法从 {current} 迁移到 {next_version}")
            
            intent = migrator(intent)
            current = next_version
        
        return intent

# 迁移函数示例
def migrate_v1_to_v2(intent: Intent) -> Intent:
    """v1 到 v2 的迁移"""
    if "review_type" in intent.payload:
        # 旧字段映射到新字段
        intent.payload["review_focus"] = [intent.payload.pop("review_type")]
    
    intent.version = "2.0"
    return intent

# ❌ 信息过载
context = {
    "entire_codebase": 1000000,  # 100万行代码
    "git_history": "全部提交历史",
    "team_docs": "所有设计文档",
    "similar_issues": "过去5年的所有bug"
}

# ✅ 精心筛选的上下文
context = {
    "relevant_files": ["src/auth/login.py", "tests/test_login.py"],
    "recent_changes": "最近3次相关提交",
    "error_message": "具体的错误堆栈",
    "expected_behavior": "一句话描述期望行为"
}

# ❌ 隐式假设
prompt = "优化这个函数"
# AI 可能：缩短代码？提高性能？增加可读性？

# ✅ 显式约束
intent = OptimizeIntent(
    target="performance",
    constraints={
        "time_complexity": "保持 O(n)",
        "space_complexity": "不增加额外空间",
        "maintainability": "不降低可读性",
        "test_coverage": "不改变测试行为"
    },
    success_criteria="benchmark 提升至少 20%"
)

# ❌ 宽容的契约（导致意外行为）
class LenientContract:
    def review_code(self, code: str = None, file_path: str = None):
        if code is None and file_path:
            code = read_file(file_path)  # 隐式读取
        elif code is None:
            code = "整个项目代码"  # 危险！
        # ...

# ✅ 严格的契约
class StrictContract:
    def review_code(self, input: CodeReviewInput):
        if not input.code and not input.file_path:
            raise ValidationError("必须提供 code 或 file_path")
        
        if input.file_path and not input.code:
            raise ValidationError(
                "Contract 不负责文件读取，" +
                "请使用 FileContext 提供文件内容"
            )

from jsonschema import validate, ValidationError

class IntentValidator:
    def __init__(self):
        self.schemas = load_schemas()
    
    def validate(self, intent: dict) -> ValidationResult:
        intent_type = intent.get("intent")
        schema = self.schemas.get(intent_type)
        
        if not schema:
            return ValidationResult(
                valid=False,
                errors=[f"未知的 intent 类型: {intent_type}"]
            )
        
        try:
            validate(instance=intent, schema=schema)
            return ValidationResult(valid=True)
        except ValidationError as e:
            return ValidationResult(
                valid=False,
                errors=[self._format_error(e)]
            )