2737 Event Schema E25a35ef

Agent 事件系统 (Event System) - v2

本文档旨在说明 infiAgent 项目中经过规范化重构后的事件驱动架构，为二次开发和系统集成提供指导。

1. 设计哲学

为了将核心的Agent业务逻辑与外部的展示、日志、监控等功能解耦，我们引入了一套事件系统。其核心思想遵循观察者模式：

• 事件生产者 (Producer)：AgentExecutor 在其执行的关键节点，只负责生产并“分发”携带结构化数据的事件，它不关心事件如何被消费。
• 事件消费者 (Consumer/Handler)：可以有多个事件处理器，它们“订阅”事件流。每个处理器根据自己的职责，对感兴趣的事件进行处理。例如，ConsoleLogHandler 负责将事件格式化后打印到控制台，而 JsonlStreamHandler 则负责将事件序列化为JSONL格式，供外部工具使用。

这种设计使得添加新的输出渠道（如HTTP SSE、WebSocket、文件日志等）变得非常简单，只需实现一个新的事件处理器并注册即可，无需修改AgentExecutor的任何代码。

2. 事件命名与划分规范

为了保证事件的清晰性和可扩展性，我们遵循以下规范：

A. 事件命名 (event_type)

所有事件的 event_type 字符串都遵循 phase.domain.action 的三段式命名格式：

• phase: 描述事件发生在Agent生命周期的哪个主要阶段。
  • prepare: 任务执行前（循环开始前）的准备阶段。
  • run: Agent的核心执行循环阶段。
  • agent: 贯穿整个生命周期的Agent自身事件。
  • system: 非业务逻辑的系统级事件，如CLI打印或严重错误。
• domain: 事件所属的业务领域。
  • model: 模型选择。
  • history: 对话历史加载。
  • llm: 大语言模型交互。
  • tool: 工具执行。
  • thinking: Agent的自我反思/规划。
• action: 具体的动作。
  • start, end, fail, select, load 等。

示例: prepare.model.select 表示在“准备阶段”，关于“模型领域”的“选择”事件。

B. 事件类别

我们将事件明确划分为两大类：

• 核心生命周期事件: 代表关键状态转变，携带结构化数据，是程序化消费的主要对象。
• 系统/展示事件: 主要用于CLI展示或表示非业务逻辑的系统状态（如错误），通常不被外部业务系统消费。

3. 当前事件清单

所有事件均定义在 core/events.py 中。

核心生命周期事件

系统与展示事件

4. 如何拓展新事件

在为系统添加新功能时，请遵循以下准则来决定是否以及如何添加新事件：

步骤1: 判断事件类型

首先问自己：“这个新事件所代表的信息，除了给CLI用户看之外，是否有可能被其他系统（如Web UI、监控、测试）以编程方式利用？”

• 如果答案是“是”:

  • 这应该是一个核心生命周期事件。
  • 在 core/events.py 中，创建一个新的 dataclass 继承自 AgentEvent。
  • 遵循 phase.domain.action 的规范为 event_type 命名。
  • 为它定义清晰、结构化的字段。
  • 示例: 假设我们要引入一个“上下文压缩”的详细事件，供UI展示压缩细节。可以创建一个 ContextCompressionEvent，event_type 为 run.context.compress，并包含 original_tokens, compressed_tokens, summary 等字段。

• 如果答案是“否”:

  • 这应该是一个CLI展示事件。
  • 不要创建新的事件类！ 直接在需要打印信息的地方，分发一个 CliDisplayEvent 即可。
  • 示例: 如果想在开始压缩前打印一条消息，只需在 _compress_action_history_if_needed 方法中调用:

    self.event_emitter.dispatch(
        CliDisplayEvent(message="正在准备压缩历史记录...")
    )
    

步骤2: 更新事件处理器

• 如果添加了新的核心生命周期事件:

  • 必须 更新 ConsoleLogHandler (core/event_handlers.py)，添加一个对应的 _print_... 方法来在CLI中友好地展示它（方法名将 . 替换为 _）。
  • 必须 考虑是否需要更新 JsonlStreamHandler。根据新的实现，JsonlStreamHandler会自动序列化所有非系统事件，因此通常无需修改，除非需要特殊处理。

• 如果只是分发了新的CliDisplayEvent:

  • 无需任何操作。现有的 ConsoleLogHandler 会自动处理它，而 JsonlStreamHandler 会自动忽略它。这就是该设计的优势所在。

遵循以上准则，可以确保我们的事件系统在不断迭代的过程中，始终保持清晰、解耦和易于维护。