◉ClassyGitshadowzzh

event_loop_demo.py

event_loop_demo.py
"""
event_loop_demo.py —— 事件驱动 Agent 的端到端演示(单进程、可离线运行)

本章"事件驱动的异步 Agent"一节指出:真正的"主动服务"不仅需要 Agent 能定时
检查世界,更需要世界能主动通知 Agent。本脚本用最小的代码把这一点跑起来——

  1. 注册若干"事件触发器"(trigger source),每个触发器在后台线程里运行,
     在事件真正发生的那一刻把一个结构化 Event 推入统一的事件队列:
       - 一次性定时器 OneShotTimer      —— 对应书中 set_timer 的"一次性定时器"
       - 循环定时器   RecurringTimer     —— 对应书中 set_timer 的"循环定时器"
       - 文件监听     FileWatchTrigger   —— 对应 n8n 等平台的文件变更触发器
  2. 事件循环 EventLoop 从队列里逐个取出事件,唤醒 Agent 处理——这正是
     "Agent 注册、外部触发"的完整闭环:注册时声明关心什么事件,触发时被异步唤醒。

与需要起 HTTP 服务器的 server.py / client.py 不同,本脚本在单个进程里同时扮演
"外部世界"和"Agent",因此适合用来直观演示事件驱动的行为。

离线模式(--mock):不调用大模型,用一个"模拟动作"打印 Agent 被唤醒后的处理
过程,可在没有 API Key 的环境下观察完整的触发→唤醒→处理闭环。
真实模式(默认):接入 EventTriggeredAgent,由大模型真正处理每个事件。

用法示例:
    python event_loop_demo.py --mock                       # 离线演示全部触发器
    python event_loop_demo.py --mock --trigger timer       # 只演示一次性定时器
    python event_loop_demo.py --mock --trigger recurring --interval 3 --duration 12
    python event_loop_demo.py --trigger file --watch-dir ./watched   # 真实 Agent 处理文件事件
"""

import os
import sys
import time
import queue
import logging
import argparse
import threading
from datetime import datetime
from typing import Optional, Callable

from event_types import Event, EventType

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger("event_loop")


# ============================================================================
# 事件触发器(trigger source)
# ============================================================================

class TriggerSource(threading.Thread):
    """事件触发器基类:在后台线程中运行,把事件推入共享的事件队列。

    注册(register)体现在实例化并 start();触发(fire)体现在 run() 中
    满足条件时调用 self.emit(event)。这与书中"注册时由 Agent 主动调用工具、
    触发时由外部事件异步回调"的两个时刻一一对应。
    """

    def __init__(self, name: str, event_queue: "queue.Queue[Event]"):
        super().__init__(name=name, daemon=True)
        self.event_queue = event_queue
        self._stop = threading.Event()

    def emit(self, event: Event):
        """触发:把事件推入事件队列,唤醒事件循环。"""
        logger.info(f"⚡ [{self.name}] 触发事件 -> {event.event_type.value}: {event.content}")
        self.event_queue.put(event)

    def stop(self):
        self._stop.set()


class OneShotTimer(TriggerSource):
    """一次性定时器:延迟 delay 秒后触发一次 timer_trigger 事件。

    对应书中"用户要求给 DMV 打电话,当前是周六,Agent 设置'下周一上午 10:00
    致电 DMV'"这类有明确时间点的任务。
    """

    def __init__(self, event_queue, delay: float, content: str, timer_id: str = "oneshot"):
        super().__init__(name=f"OneShotTimer({timer_id})", event_queue=event_queue)
        self.delay = delay
        self.content = content
        self.timer_id = timer_id

    def run(self):
        logger.info(f"⏱️  [{self.name}] 已注册:{self.delay:.0f} 秒后触发")
        if self._stop.wait(self.delay):
            return
        self.emit(Event(
            event_type=EventType.TIMER_TRIGGER,
            content=self.content,
            metadata={"timer_id": self.timer_id, "kind": "one_shot",
                      "scheduled_delay_seconds": self.delay},
        ))


class RecurringTimer(TriggerSource):
    """循环定时器:每隔 interval 秒触发一次 timer_trigger 事件。

    对应书中"每小时检查一次服务器健康状况""每周五发送进展报告",以及
    OpenClaw Heartbeat 式的定时轮询。
    """

    def __init__(self, event_queue, interval: float, content: str, timer_id: str = "recurring"):
        super().__init__(name=f"RecurringTimer({timer_id})", event_queue=event_queue)
        self.interval = interval
        self.content = content
        self.timer_id = timer_id

    def run(self):
        logger.info(f"🔁 [{self.name}] 已注册:每 {self.interval:.0f} 秒触发一次")
        tick = 0
        while not self._stop.wait(self.interval):
            tick += 1
            self.emit(Event(
                event_type=EventType.TIMER_TRIGGER,
                content=f"{self.content}(第 {tick} 次)",
                metadata={"timer_id": self.timer_id, "kind": "recurring",
                          "interval_seconds": self.interval, "tick": tick},
            ))


class FileWatchTrigger(TriggerSource):
    """文件监听:轮询目录,发现新增或被修改的文件时触发 file_change 事件。

    对应书中"n8n 等工作流平台的触发器生态:Webhook、定时器、邮件、数据库
    变更、文件监听"。这里用轮询实现,不依赖第三方库,便于跨平台离线运行。
    """

    def __init__(self, event_queue, watch_dir: str, poll_interval: float = 1.0):
        super().__init__(name=f"FileWatch({watch_dir})", event_queue=event_queue)
        self.watch_dir = watch_dir
        self.poll_interval = poll_interval
        self._snapshot = {}

    def _scan(self):
        snapshot = {}
        try:
            for entry in os.scandir(self.watch_dir):
                if entry.is_file():
                    snapshot[entry.name] = entry.stat().st_mtime
        except FileNotFoundError:
            pass
        return snapshot

    def run(self):
        os.makedirs(self.watch_dir, exist_ok=True)
        self._snapshot = self._scan()
        logger.info(f"👀 [{self.name}] 已注册:轮询间隔 {self.poll_interval:.0f} 秒"
                    f"(当前已有 {len(self._snapshot)} 个文件)")
        while not self._stop.wait(self.poll_interval):
            current = self._scan()
            for name, mtime in current.items():
                if name not in self._snapshot:
                    change = "created"
                elif mtime != self._snapshot[name]:
                    change = "modified"
                else:
                    continue
                self.emit(Event(
                    event_type=EventType.FILE_CHANGE,
                    content=f"检测到文件{'新增' if change == 'created' else '修改'},请查看其内容并给出简要处理建议。",
                    metadata={"path": os.path.join(self.watch_dir, name), "change": change},
                ))
            self._snapshot = current


# ============================================================================
# 事件循环(event loop)
# ============================================================================

class EventLoop:
    """统一事件队列 + 单线程分发。

    所有触发器把异构事件推入同一个队列;事件循环按到达顺序取出,每个事件
    唤醒一次 Agent 处理。这正是书中"将所有输入统一建模为事件流,通过事件
    循环驱动 Agent 的思考和行动"的最小实现。
    """

    def __init__(self, dispatch: Callable[[Event], None]):
        self.event_queue: "queue.Queue[Event]" = queue.Queue()
        self.dispatch = dispatch
        self.triggers = []
        self.processed = 0

    def add_trigger(self, trigger: TriggerSource):
        self.triggers.append(trigger)

    def run(self, duration: float):
        """启动所有触发器,运行 duration 秒后停止。"""
        deadline = time.monotonic() + duration
        for t in self.triggers:
            t.start()

        logger.info(f"🟢 事件循环启动,将运行 {duration:.0f} 秒,等待事件唤醒 Agent...\n")
        while time.monotonic() < deadline:
            try:
                event = self.event_queue.get(timeout=0.5)
            except queue.Empty:
                continue
            self.processed += 1
            logger.info(f"\n{'='*80}\n📥 事件循环取出第 {self.processed} 个事件"
                        f" -> 唤醒 Agent\n{'='*80}")
            try:
                self.dispatch(event)
            except Exception as e:  # noqa: BLE001 - 演示中不希望单个事件异常终止循环
                logger.error(f"❌ 处理事件时出错: {e}")

        for t in self.triggers:
            t.stop()
        logger.info(f"\n🔴 事件循环结束,共处理 {self.processed} 个事件。")


# ============================================================================
# 分发处理器:模拟动作 or 真实 Agent
# ============================================================================

def make_mock_dispatch() -> Callable[[Event], None]:
    """离线模拟处理器:不调用大模型,打印 Agent 被唤醒后的处理过程。"""

    def dispatch(event: Event):
        logger.info(f"🤖 Agent 被唤醒,收到消息: {event.to_user_message()}")
        # 用一个确定性的"模拟动作"代替大模型 + 工具调用
        if event.event_type == EventType.TIMER_TRIGGER:
            action = "读取定时任务上下文 -> 执行例行检查 -> 汇报结果"
        elif event.event_type == EventType.FILE_CHANGE:
            path = event.metadata.get("path", "")
            preview = ""
            try:
                with open(path, "r", encoding="utf-8", errors="replace") as f:
                    preview = f.read(120).replace("\n", " ")
            except OSError:
                preview = "(无法读取文件内容)"
            action = f"读取文件 {os.path.basename(path)} -> 内容预览: {preview!r} -> 生成处理建议"
        else:
            action = "解析事件 -> 调用相关工具 -> 生成处理结果"
        logger.info(f"🛠️  [模拟动作] {action}")
        logger.info(f"✅ Agent 处理完成: 已响应 {event.event_type.value} 事件")

    return dispatch


def make_agent_dispatch(provider: str, model: Optional[str],
                        max_iterations: int) -> Callable[[Event], None]:
    """真实处理器:接入 EventTriggeredAgent,由大模型处理每个事件。"""
    from agent import EventTriggeredAgent, SystemHintConfig, resolve_provider_and_key

    # 通用兜底:直连 provider 的 key 缺失时,若有 OPENROUTER_API_KEY 则自动改走 openrouter。
    resolved_provider, api_key = resolve_provider_and_key(provider)
    if not api_key:
        print(f"❌ 未检测到 provider '{provider}' 对应的 API Key(也未配置 OPENROUTER_API_KEY 兜底)。")
        print(f"   请先设置环境变量,或改用离线演示:python event_loop_demo.py --mock")
        sys.exit(1)
    if resolved_provider != provider:
        print(f"ℹ️  provider '{provider}' 无可用 Key,已自动改用 OpenRouter 兜底(openrouter)。")
        provider = resolved_provider
        # 保留已是 provider/model 形式的显式模型;否则让 openrouter 用其默认模型。
        model = model if (model and "/" in model) else None

    config = SystemHintConfig(
        enable_timestamps=True,
        enable_tool_counter=True,
        enable_todo_list=True,
        enable_detailed_errors=True,
        enable_system_state=True,
        save_trajectory=True,
        trajectory_file="event_loop_trajectory.json",
        temperature=0.7,
        max_tokens=4096,
        use_mcp_servers=False,  # 本演示仅用内置工具,避免额外的 MCP 依赖
    )
    agent = EventTriggeredAgent(api_key=api_key, provider=provider,
                               model=model, config=config, verbose=True)
    logger.info(f"✅ 真实 Agent 初始化完成(provider={provider}, model={agent.model})")

    def dispatch(event: Event):
        result = agent.handle_event(event, max_iterations=max_iterations)
        logger.info(f"✅ Agent 处理完成: success={result['success']}, "
                    f"iterations={result['iterations']}, "
                    f"tool_calls={len(result['tool_calls'])}")

    return dispatch


# ============================================================================
# CLI
# ============================================================================

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="事件驱动 Agent 端到端演示:注册触发器,由外部事件异步唤醒 Agent。",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""示例:
  python event_loop_demo.py --mock
      离线演示全部触发器(一次性定时器 + 循环定时器 + 文件监听),无需 API Key
  python event_loop_demo.py --mock --trigger timer
      只演示一次性定时器
  python event_loop_demo.py --mock --trigger recurring --interval 3 --duration 12
      每 3 秒触发一次循环定时器,共运行 12 秒
  python event_loop_demo.py --mock --trigger file --watch-dir ./watched
      监听 ./watched 目录,向其中写入文件即可触发事件
  python event_loop_demo.py --trigger timer --provider kimi
      用真实大模型处理一次性定时器事件(需要设置对应的 API Key)
""",
    )
    parser.add_argument(
        "--trigger", choices=["timer", "recurring", "file", "all"], default="all",
        help="要演示的触发器类型:timer=一次性定时器,recurring=循环定时器,"
             "file=文件监听,all=全部(默认:all)",
    )
    parser.add_argument(
        "--mock", action="store_true",
        help="离线模式:不调用大模型,用模拟动作演示触发→唤醒→处理闭环(无需 API Key)",
    )
    parser.add_argument(
        "--duration", type=float, default=12.0,
        help="事件循环总运行时长(秒),到时后停止所有触发器(默认:12)",
    )
    parser.add_argument(
        "--delay", type=float, default=3.0,
        help="一次性定时器的延迟触发时间(秒)(默认:3)",
    )
    parser.add_argument(
        "--interval", type=float, default=4.0,
        help="循环定时器的触发间隔(秒)(默认:4)",
    )
    parser.add_argument(
        "--watch-dir", default="watched_dir",
        help="文件监听触发器监视的目录,不存在会自动创建(默认:watched_dir)",
    )
    parser.add_argument(
        "--provider", default=os.getenv("LLM_PROVIDER", "kimi"),
        choices=["siliconflow", "doubao", "kimi", "moonshot", "openrouter"],
        help="真实模式使用的大模型提供商(默认:环境变量 LLM_PROVIDER 或 kimi)",
    )
    parser.add_argument(
        "--model", default=os.getenv("LLM_MODEL"),
        help="真实模式的模型名覆盖(默认:使用提供商默认模型)",
    )
    parser.add_argument(
        "--max-iterations", type=int, default=10,
        help="真实模式下单个事件的最大工具调用轮数(默认:10)",
    )
    return parser


def main():
    args = build_parser().parse_args()

    print("\n" + "=" * 80)
    print("🚀 事件驱动 Agent 演示(EVENT-DRIVEN AGENT DEMO)")
    print("=" * 80)
    print(f"触发器: {args.trigger} | 模式: {'离线模拟' if args.mock else '真实 Agent'} | "
          f"时长: {args.duration:.0f}s")
    print("=" * 80 + "\n")
    sys.stdout.flush()

    if args.mock:
        dispatch = make_mock_dispatch()
    else:
        dispatch = make_agent_dispatch(args.provider, args.model, args.max_iterations)

    loop = EventLoop(dispatch)

    if args.trigger in ("timer", "all"):
        loop.add_trigger(OneShotTimer(
            loop.event_queue, delay=args.delay, timer_id="daily_backup_check",
            content="一次性定时器到期:请检查每日备份是否已经完成。",
        ))
    if args.trigger in ("recurring", "all"):
        loop.add_trigger(RecurringTimer(
            loop.event_queue, interval=args.interval, timer_id="health_check",
            content="循环定时器到期:请检查服务器健康状况。",
        ))
    if args.trigger in ("file", "all"):
        loop.add_trigger(FileWatchTrigger(loop.event_queue, watch_dir=args.watch_dir))
        print(f"💡 提示:向目录 {args.watch_dir}/ 写入或修改文件即可触发 file_change 事件。")
        print(f"   例如另开一个终端执行:echo hello > {args.watch_dir}/note.txt\n")
    sys.stdout.flush()

    if not loop.triggers:
        print("❌ 没有可运行的触发器。")
        sys.exit(1)

    try:
        loop.run(duration=args.duration)
    except KeyboardInterrupt:
        print("\n⚠️  收到中断信号,正在停止...")
        for t in loop.triggers:
            t.stop()

    print("\n" + "=" * 80)
    print(f"📊 演示结束:共处理 {loop.processed} 个事件。")
    print("=" * 80 + "\n")


if __name__ == "__main__":
    main()