OpenHands 源码解析 · 第 5 讲
OpenHands 源码解析系列 第 5 讲：事件溯源系统 (Event Log + 3 Backends) 基于 OpenHands 源码 · 2026-08-01 一、事件溯源：OpenHands 的数据基石 在 OpenHands V1 架构中， 事件（Event） 是会话中所有交互的唯一真相来源。用户的每一条消息、Agent 的每一次工具调用、沙箱的每一个输出片段——全部被序列化为 JSON 事件，持久化到不同的存储后端。 这种 事件溯源（Event Sourcing） 模式意味着： 🔹 会话状态不是直接存储的，而是由事件序列回放重建 🔹 每个事件是不可变的 JSON 文档，存储在独立文件中 🔹 三种存储后端（文件系统 / AWS S3 / Google Cloud Storage）通过同一抽象接口切换 🔹 事件回调系统（Event Callback）在事件产生时触发下游处理 📦 源码位置 openhands/app_server/event/ — 事件存储服务 openhands/app_server/event_callback/ — 事件回调系统 openhands/app_server/conversation_paths.py — 路径构造工具 openhands/app_server/utils/environment.py — 存储提供商检测 二、事件存储架构总览 事件溯源系统架构 +----------------------------------------------------------+ | EventService (ABC) | | 抽象接口: get / search / count / save / batch_get | +---------------------------+------------------------------+ | +---------------+----------------+ | | | +-----------v----------+ +---v----------+ +--v-------------+ | EventServiceBase | | (future: | | (future: | | (带路径逻辑的基类) | | RedisEvent | | PostgresEvent | +-----------+----------+ +-------------+ +---------------+ | +-------+--------+ | | | +v1 | v2 | v3 | | | | +---v----+ +v-------v+ +v------------v+ |Filesys | | AWS | | Google Cloud| |Event | | S3 | | Storage | |Service | | Service | | Service | +--------+ +---------+ +--------------+ | | | +-------+--------+ | {prefix}/{user_id}/v1_conversations/ {conversation_id_hex}/{event_id_hex}.json 三、EventService 抽象接口 所有事件存储后端的共同契约，定义了事件操作的完整 API： 📄 event_service.py (第 18-71 行) class EventService(ABC): """Event Service for getting events.""" @abstractmethod async def get_event(self, conversation_id: UUID, event_id: UUID) -> Event | None: """Given an id, retrieve an event.""" @abstractmethod async def search_events( self, conversation_id: UUID, kind__eq: EventKind | None = None, # 按事件类型过滤 times…
阅读全文：OpenHands 源码解析 第 5 讲