OpenHands 源码解析 · 第 4 讲
OpenHands 源码解析系列 第 4 讲：会话管理核心 (AppConversationService) 基于 OpenHands 源码 · 2026-07-31 一、会话管理的核心地位 在 OpenHands 的 V1 架构中， 会话（Conversation） 是用户与 AI Agent 交互的核心载体。每一个会话从创建到销毁，贯穿了沙箱启动、仓库克隆、Skill 加载、Agent 初始化、事件回调等完整生命周期。 会话管理模块位于 openhands/app_server/app_conversation/ ，包含 14 个核心文件，由三个抽象服务接口 + 对应的 SQL 实现组成： 📄 目录结构概览 app_conversation/ ├── app_conversation_service.py # 抽象服务接口 ├── app_conversation_service_base.py # Git 功能基类 ├── app_conversation_info_service.py # 会话信息抽象接口 ├── app_conversation_start_task_service.py # 启动任务抽象接口 ├── live_status_app_conversation_service.py # 核心实现 (3115 行!) ├── sql_app_conversation_info_service.py # SQL 信息存储 ├── sql_app_conversation_start_task_service.py ├── app_conversation_models.py # 数据模型 ├── app_conversation_router.py # FastAPI 路由 ├── skill_loader.py # Skill 加载 ├── hook_loader.py # Hook 加载 ├── conversation_secret_enricher.py # 密钥注入 └── git/ # Git hooks 脚本 二、三层抽象架构 OpenHands 的会话管理采用了经典的 接口-基类-实现 三层架构，职责清晰分离： 2.1 AppConversationService — 顶层抽象 定义了会话 CRUD 的完整契约，包含搜索、计数、创建、更新、删除和导出等核心操作： 📄 app_conversation_service.py (第 33-175 行) class AppConversationService(ABC): """Service for managing conversations running in sandboxes.""" @abstractmethod async def search_app_conversations(...) -> AppConversationPage: """Search for sandboxed conversations.""" @abstractmethod async def start_app_conversation( self, request: AppConversationStartRequest ) -> AsyncGenerator[AppConversationStartTask, None]: """Start a conversation, optionally specifying a sandbox. Status progression: WORKING → WAITING_FOR_SANDBOX → PREPARING_REPOSITORY → RUNNING_SETUP_SCRIPT → SETTING_UP_GIT_HOOKS → SETTING_UP_SKILLS → STARTING_CONVERSATION → READY (or ERROR at any point).""" @abstractmethod async def delete_app_conversation( self, conversation_id: UUID, skip_agent_server_delete: bool = Fal…
阅读全文：OpenHands 源码解析 第 4 讲