Function lesson_1_interface

tutorials/18_design_patterns_for_agents.py:37–172

对应源码: conversation.rs:34-36 → trait ApiClient { fn stream(...) } conversation.rs:38-39 → trait ToolExecutor { fn execute(...) } permissions.rs:39-41 → trait PermissionPrompter { fn decide(...) } 这三个 trait (Rust 的叫法) 就是 Python 的 ABC (Abstract Base Class)。 它们定义了 "你必

()

# ============================================================

def lesson_1_interface():
    """
    对应源码:
      conversation.rs:34-36  → trait ApiClient { fn stream(...) }
      conversation.rs:38-39  → trait ToolExecutor { fn execute(...) }
      permissions.rs:39-41   → trait PermissionPrompter { fn decide(...) }

    这三个 trait (Rust 的叫法) 就是 Python 的 ABC (Abstract Base Class)。
    它们定义了 "你必须实现这些方法", 但不关心你怎么实现。

    为什么? 因为 ConversationRuntime 不应该知道:
    - API 调用是走 HTTP 还是假数据 (测试时)
    - 工具是执行 Bash 还是读文件
    - 权限提示是 CLI 弹窗还是 IDE 对话框

    日常类比: USB 接口
    ─────────────
    USB 口不管你插的是鼠标、键盘还是 U盘——只要你有 USB 插头就行。
    "USB 接口" = trait/ABC, "鼠标" = 一个具体实现。
    """
    print("=" * 60)
    print("第一课: 接口 (ABC) — 签合同, 不管你怎么干活")
    print("=" * 60)

    # ---- 步骤 1: 定义接口 (对应 Rust 的 trait) ----

    # 对应 conversation.rs:34-36
    # pub trait ApiClient {
    #     fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError>;
    # }
    class ApiClient(ABC):
        """API 客户端接口: 你必须能发送请求并返回事件流"""
        @abstractmethod
        def stream(self, messages: list[dict]) -> list[dict]:
            """发送消息, 返回 assistant 事件列表"""
            ...

    # 对应 conversation.rs:38-39
    # pub trait ToolExecutor {
    #     fn execute(&mut self, tool_name: &str, input: &str) -> Result<String, ToolError>;
    # }
    class ToolExecutor(ABC):
        """工具执行器接口: 你必须能按名字执行工具"""
        @abstractmethod
        def execute(self, tool_name: str, tool_input: str) -> str:
            ...

    # 对应 permissions.rs:39-41
    # pub trait PermissionPrompter {
    #     fn decide(&mut self, request: &PermissionRequest) -> PermissionPromptDecision;
    # }
    class PermissionPrompter(ABC):
        """权限提示器接口: 你必须能做出允许/拒绝决定"""
        @abstractmethod
        def decide(self, tool_name: str, tool_input: str) -> bool:
            ...

    # ---- 步骤 2: 多种实现 ----