Hermes Agent 源码解析

第 12 讲：CLI 交互架构与 Session 持久化——REPL、TUI、SQLite 状态库与跨进程会话管理

基于 Hermes Agent v0.16.0 源码 · 2026-06-25

一、从命令行到智能代理：Hermes 的交互面

前十一讲我们覆盖了 Hermes 从核心架构到 ACP 协议的全链路。这一讲我们深入到 Hermes 的CLI 交互层与Session 持久化系统——这两个模块是所有用户与 Hermes 打交道的"第一公里"。

当你在终端输入 hermes 时，背后发生了什么？Hermes 如何管理数十个活跃会话？Session 数据如何跨进程共享？压缩后的会话如何保持可追溯？这一讲逐一拆解。

二、CLI 启动管线：从 hermes 到 Agent 就绪

Hermes 的 CLI 启动管线是一个精心编排的 12 步流程，每一步都有明确的职责和故障降级策略。

其中最有意思的是Profile 覆盖阶段（main.py:336）。Hermes 在 argparse 解析之前就拦截了 --profile/-p 标志——这是因为大量模块在导入时就缓存了 HERMES_HOME，如果等 argparse 完成才设置环境变量，所有模块级常量都已经指向了错误的路径。

Profile 解析还处理了 mcp add --args 的命令参数透传区域——在 --args 之后的标志属于子命令（如 Docker MCP Toolkit 的 --profile），而非 Hermes 自身的 Profile 选择器。

三、双交互面：CLI REPL 与 TUI 的架构差异

Hermes 提供两种交互界面，用户可通过 --cli、--tui 或 config.yaml 的 display.interface 切换。

TUI 的启动有一个巧妙的鼠标残留抑制机制（main.py:168）。在 Python 导入阶段（约 100-300ms），终端仍处在 cooked + echo 模式，任何鼠标事件产生的字节会被直接回显到 shell 滚动缓冲区，产生 ^[[<…M 这样的乱码。Hermes 在模块顶层就发送了 9 个 ANSI 序列禁用所有鼠标追踪变体，等 Node TUI 真正接管 stdin 后再次调用 resetTerminalModes()。

四、SQLite 状态库：Session 持久化的核心

hermes_state.py 是 Hermes 的"记忆中枢"，实现了基于 SQLite 的 Session 持久化存储。它取代了早期的每会话 JSONL 文件方案，提供了事务安全、全文搜索和跨进程并发访问。

4.1 数据库 Schema 设计

Schema 版本当前为 v16，包含四张核心表：

sessions 表有 30+ 个字段，涵盖了完整的会话生命周期信息：source（cli/telegram/discord 等）、model 配置、token 用量（input/output/cache_read/cache_write/reasoning）、费用估算、工作目录、压缩链关系等。

messages 表的 active 字段是关键设计——压缩后旧会话的消息标记为 active=0，新会话的消息标记为 active=1，实现了"逻辑删除"而非物理删除，保留了完整的审计轨迹。

4.2 WAL 模式与网络文件系统降级

SQLite 默认使用 WAL（Write-Ahead Logging） 模式，允许多个读者并发访问。但 Hermes 实现了一个精妙的降级机制（hermes_state.py:231）：

apply_wal_with_fallback(conn):
    # Step 1: 只读探测 — 不获取锁
    current = conn.execute("PRAGMA journal_mode")
    if current == "wal":
        return "wal"
    
    # Step 2: 尝试设置 WAL
    try:
        conn.execute("PRAGMA journal_mode=WAL")
        return "wal"
    except OperationalError as exc:
        if "locking protocol" in exc:
            # NFS/SMB/FUSE 不支持 WAL
            return "delete"  # 降级为回滚日志模式

这个降级覆盖了 NFS、SMB/CIFS、FUSE 挂载和 WSL1 等场景。警告信息仅每进程每数据库打印一次（_wal_fallback_warned_paths 去重），避免 kanban 操作频繁打开连接时刷屏。

4.3 FTS5 全文搜索

Hermes 使用 SQLite 的 FTS5 虚拟表实现跨会话全文搜索，支持两种分词器：

🔹 unicode61（默认）：适用于拉丁语系，按词边界分词

🔹 trigram：三字节滑动窗口，专为 CJK 子串搜索设计

两张 FTS 表（messages_fts 和 messages_fts_trigram）通过 SQLite 触发器与 messages 表保持同步——INSERT/UPDATE/DELETE 消息时自动更新索引。

当 SQLite 编译未包含 FTS5 扩展时（某些精简版 Python），Hermes 自动降级：消息写入照常工作，全文搜索功能静默禁用，用户收到一次 WARNING。

4.4 Schema 自动修复

当 sqlite_master 出现重复定义（如两个 CREATE VIRTUAL TABLE messages_fts）时，整个数据库无法打开——连 PRAGMA journal_mode 都会失败。Hermes 的自动修复策略（hermes_state.py:410）：

1. 备份原始 DB 文件（含 WAL/SHM 副文件）

2. 策略一：去重 sqlite_master（保留最小 rowid），保留 FTS 索引

3. 策略二：删除所有 FTS 对象 + VACUUM，下次打开时重建

修复尝试每进程每 DB 路径仅一次（_claim_repair_attempt），防止修复循环。

五、并发写入与租约管理

5.1 写入竞争处理

Gateway + CLI + Worktree Agent 多个进程共享同一个 state.db，写入竞争是必然的。Hermes 的解决方案是 应用层重试 + 随机抖动（hermes_state.py:874）：

_execute_write(fn):
    for attempt in range(15):
        with self._lock:
            conn.execute("BEGIN IMMEDIATE")  # 立即获取写锁
            try:
                result = fn(conn)
                conn.commit()
            except:
                conn.rollback()
                raise
        # 每 50 次写入做一次 TRUNCATE checkpoint
        if write_count % 50 == 0:
            conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
        return result
    except OperationalError:
        if "locked" in error or "busy" in error:
            sleep(random.uniform(0.02, 0.15))  # 20-150ms 抖动
            continue

随机抖动打破了"列车效应"——SQLite 内建的回退策略是确定性的，多个竞争者会以相同间隔重试，形成排队。随机抖动让竞争者自然分散。

5.2 跨进程活跃会话租约

active_sessions.py 实现了跨进程的会话槽位管理系统。核心数据结构存储在 ~/.hermes/runtime/active_sessions.json：

+------------------------+
|  active_sessions.json  |
+------------------------+
| entries: [             |
|   {                    |
|     lease_id: uuid,    |  唯一租约标识
|     session_id: str,   |  关联的会话 ID
|     surface: str,      |  "cli" / "telegram" / "discord"
|     pid: int,          |  进程 PID
|     process_start_time: float,  # 防 PID 复用
|     started_at: float, |  租约创建时间
|     updated_at: float  |  最后更新时间
|   }, ...               |
| ]                      |
+------------------------+

租约获取流程（try_acquire_active_session）：

1. 文件锁（fcntl/msvcrt）确保原子读写

2. 读取条目，清理死进程（PID 不存在或创建时间不匹配）

3. 检查是否超过 max_concurrent_sessions 上限

4. 写入新租约，返回 ActiveSessionLease 对象

死进程清理使用了 process_start_time 双重校验——即使 PID 被系统复用，创建时间不匹配也能识别出"假活"进程。

六、Session 生命周期与压缩链

6.1 Session 状态机

每个 Session 经历以下状态转换：

  +----------+
  |  Created |  -- new session row in DB
  +----------+
       |
       v
  +----------+
  |  Active  |  -- messages being written
  +----------+
       |
       +----> End: "completed"    (normal exit)
       +----> End: "error"       (crash/API failure)
       +----> End: "compression"  (context compressed, continues)
       +----> End: "branched"     (forked to new session)
       +----> End: "rewound"      (rewound to checkpoint)

6.2 压缩链与 Session 恢复

当上下文超过窗口限制时，Hermes 触发压缩——旧会话标记 end_reason='compression'，创建新会话并设置 parent_session_id。这形成了一条压缩链。

Session 恢复时（--resume），Hermes 会沿着压缩链向前追踪到最新的活跃端点（get_compression_tip），而不是停在压缩根节点上。这样即使用户记住了旧的 Session ID，也能恢复到最新状态。

子代理委托产生的子会话通过 _delegate_from 标记追踪，父会话删除时级联清理子会话（_delete_delegate_children），但分支会话（_branched_from）和压缩续集会豁免级联删除。

6.3 会话浏览器

hermes sessions browse 命令提供了一个 curses 实现的交互式会话浏览器（main.py:834），支持：

🔹 实时搜索过滤（标题、预览、ID、来源）

🔹 自适应列宽（根据终端宽度动态调整）

🔹 颜色主题（选中行高亮、表头、搜索框）

🔹 无 curses 环境降级（Windows 等显示编号列表）

七、AIAgent 回调系统：交互面的"插线板"

AIAgent.__init__() 接收了 15+ 个回调函数，形成了灵活的交互抽象层：

AIAgent(
    tool_progress_callback=...,   # 工具执行进度
    tool_start_callback=...,      # 工具调用开始
    tool_complete_callback=...,   # 工具调用完成
    thinking_callback=...,        # 思考过程流式输出
    reasoning_callback=...,       # 推理过程输出
    clarify_callback=...,         # 需要用户澄清
    read_terminal_callback=...,   # 终端读取内容
    step_callback=...,            # 每步完成
    stream_delta_callback=...,    # 流式增量
    interim_assistant_callback=..., # 中间助手消息
    tool_gen_callback=...,        # 工具生成
    status_callback=...,          # 状态更新
    notice_callback=...,          # 通知
    notice_clear_callback=...,    # 清除通知
)

CLI REPL 和 TUI 通过注入不同的回调实现，共享同一个 AIAgent 核心。Gateway 平台（Telegram/Discord/Slack）也使用同一套回调接口，实现了"一次实现，多面运行"。

八、会话摘要：纯本地计算的 /recap

session_recap.py 实现了一个纯本地计算的会话摘要功能，灵感来自 Claude Code 的 /recap 命令。关键差异：

🔹 零 LLM 调用：从内存中的对话历史直接计算，不消耗 token

🔹 跨平台一致：CLI 和所有 Gateway 平台使用同一个 build_recap 函数

🔹 工具词汇定制：针对 Hermes 的工具集（terminal、patch、write_file、delegate_task 等）生成有意义的摘要

摘要包含：最近 20 轮对话的统计、工具使用频率 TOP 5、最近修改的文件列表、最后用户请求和助手回复的预览。

九、架构总结

Hermes 的 CLI 交互与 Session 持久化架构体现了几个核心设计原则：

🔹 薄核心，厚边缘：AIAgent 核心不关心交互面，通过回调系统解耦

🔹 SQLite 作为一等公民：WAL 模式 + FTS5 + 自动修复，生产级可靠性

🔹 跨进程安全：文件锁 + 租约 + PID 双重校验，多实例共存

🔹 优雅降级：WAL→DELETE、FTS5→关闭、curses→编号列表，任何环境都能工作

🔹 压缩链可追溯：旧消息标记 inactive 而非删除，审计轨迹完整