# 🔬 模式A可行性研究：LangGraph Checkpoint ↔ Hermes集成

研究日期: 2026-07-10 | 技术栈: Hermes Agent 0.18.0 / LangGraph 1.x | 目标: 长周期Agent任务状态持久化

## 一、问题定义

痛点：Hermes Agent的长周期任务（如跨Bot协作、定时多步骤报告、运维审计链）在执行到中途时，如果遇到超时（max_turns: 90 / gateway_timeout: 1800秒）、进程重启、或节点失败，整个任务进度丢失，必须从头重新执行。

目标：在Hermes Agent的会话执行流程中引入「检查点」机制——每个逻辑步骤完成后保存状态快照，任务中断后可以从最近的检查点继续，而不是从头重来。

## 二、技术对标

维度 | LangGraph | Hermes Agent
--- | --- | ---
状态粒度 | 超级步骤（super-step）边界 → 每次图节点执行完后保存checkpoint | 整个会话（conversation-level） → 每轮消息保存到session JSON，无步骤级
线程模型 | `thread_id` → 每次调用指定thread_id，checkpoint自动关联 | `session_id` → 每个会话一个ID，但无恢复执行机制
存储后端 | InMemorySaver / SqliteSaver / PostgresSaver | JSON文件 + SQLite (kanban) + 内存 (memory)
容错机制 | pending writes + checkpoint resume → 节点失败只重跑失败节点 | 无 → 失败后整个任务重跑
时间旅行 | 支持 → 回放到任意checkpoint并fork | 不支持 → 只能查看历史消息
人机协同 | 原生interrupt机制 → 可在节点间插入人工审批 | 通过approval-gate实现（审批单个命令，非流程级）
跨线程记忆 | Store → 跨thread_id的持久化key-value | Memory + User Profile → 跨会话持久化

## 三、Hermes现有的「准检查点」设施

研究后发现，Hermes实际上已经有了3个与状态持久化相关的机制，但存在关键缺口：

### ① Session JSON 文件

位置：`/root/.hermes/sessions/session_{id}.json`

保存完整的对话消息（messages）和元数据。但：扁平化保存，不区分任务步骤。重启后agent可以读取旧session，但无法知道"已执行到第几步"。

### ② Kanban Task 系统

位置：`kanban.db` → `tasks` 表 + `task_runs` 表

已有完整的任务生命周期（status/runs/result/idempotency_key）。最匹配checkpoint概念的设施，但当前的kanban任务不和Agent执行流程绑定。

### ③ Memory 持久化

通过 `memory` + `user_profile` 实现跨会话知识持久化。但：这是知识层，不是执行状态层。

#### 🔑 关键发现

Kanban的task_runs表已经隐含了「检查点」的雏形。每次task尝试（attempt）都有独立的started_at/completed_at/status/result。如果能做到：

- 在Agent执行的每个「逻辑步骤」结束时，将步骤状态写入kanban的task_runs.result
- 重启后，Agent读取task_runs.result，判断已完成的步骤和下一个步骤
- 比引入LangGraph更轻量，100%复用现有基础设施

## 四、三种集成方案评估

### 方案A：Hermes原生Task Checkpoint 推荐

思路：利用Hermes现有的kanban task系统，在每个逻辑步骤结束时写入步骤状态。Agent重启时从kanban读取已完成的步骤。

工作量：低 — 约1-2天

实现方式：

1. 在SOUL.md中增加一条铁律："对长周期任务，每完成一个逻辑步骤，通过sqlite写入kanban.db的task_runs.result"
2. 开发一个 `checkpoint.py` 脚本，提供 `save_step(task_id, step_name, status)` 和 `get_state(task_id) → last_step`
3. 在cron任务和多步骤运维流程中集成——启动时检查是否有未完成的任务

✅ 零新依赖 · ✅ 复用现有kanban体系 · ✅ 与任务调度紧密集成

⚠️ 仅适用于结构化/可分解的任务 · ⚠️ 需要Agent在SOUL中记忆"每步完成时存checkpoint"

### 方案B：Hermes Checkpoint Plugin 中长期

思路：为Hermes Agent开发一个checkpoint插件，hook到Agent的每个tool_call/tool_result周期，自动保存执行轨迹。从底层实现步骤级快照。

工作量：中 — 约1-2周

实现方式：编写Hermes插件（plugins目录下），注册中间件拦截tool_call事件 → 序列化当前上下文到SQLite checkpoint表 → 重启时恢复上下文。

✅ 全自动，Agent无需记住手动存checkpoint · ✅ 粒度精细

⚠️ Hermes插件API可能有限制 · ⚠️ 上下文中断和重建有歧义性风险

### 方案C：引入LangGraph编排层 不推荐

思路：将Hermes的任务编排层替换为LangGraph Runtime，Hermes仅作为前端控制器

工作量：高 — 1-2个月

实现方式：将复杂多步骤任务提取为LangGraph StateGraph → LangGraph管理checkpoint → Hermes通过system-bus调用LangGraph runtime

✅ 得到LangGraph生态的全部能力（checkpoint/time travel/interrupt）

❌ 引入一个大框架作为编排依赖 · ❌ LangGraph面向代码定义图，适合确定性工作流而非Agent自发任务 · ❌ 我们绝大多数Agent任务是"对话驱动"而非"图驱动"，不匹配LangGraph的核心模型 · ❌ 与现有Hermes的13个Profile集成成本极高

## 五、推荐方案详述：方案A Hermes原生Task Checkpoint

### 5.1 架构设计

┌──────────────────────────────────────────────────┐ │ Agent 执行流程 │ │ │ │ START → Step-1 → [Checkpoint] → Step-2 → [CKPT] │ │ ↓ │ │ kanban.db: task_runs │ │ result = {"completed_steps": [ │ │ {"step": 1, "name": "...", │ │ "output": "...", "ts": "..."} │ │ ]} │ │ │ │ 中断恢复流程： │ │ START → 读取kanban → 发现step=1已完成 │ │ → 跳过step-1 → 从step-2继续 │ └──────────────────────────────────────────────────┘

### 5.2 核心组件

组件 | 位置 | 职责
--- | --- | ---
`checkpoint.sh` | scripts/checkpoint.sh | 保存步骤状态 `./checkpoint.sh save task_xxx step_2 "数据清洗完成"`
`checkpoint.sh get` | 同上 | 读取任务当前进度 `./checkpoint.sh get task_xxx → step_2/done`
`checkpoint.sh list` | 同上 | 列出所有未完成的任务 `./checkpoint.sh list → task_xxx (step_2/5)`
SOUL.md铁律 | SOUL.md | 引导Agent在每个逻辑步骤后自动调用checkpoint
DailyHealth cron | cron | 优先恢复未完成的checkpoint任务

### 5.3 脚本接口设计

# 保存步骤 checkpoint save <task_id> <step_num> <step_name> [--output "摘要"] → 写入 kanban.db → SELECT/UPDATE task_runs.result # 获取当前状态 checkpoint get <task_id> → 返回: {task_id, total_steps, completed: [step1, step2, ...], last_step, last_update} # 列表所有活跃任务 checkpoint list [--status pending|running|stalled] → 返回表格 # 标记完成 checkpoint done <task_id> [--result "成功"] → 更新 task.status = completed # 清理过期 checkpoint prune [--hours 72] → 删除N小时前的未完成任务

### 5.4 集成工作流示例：SSH健康日报

当前流程（无checkpoint）： 启动 → step1:磁盘检查 → step2:内存检查 → step3:日志分析 → step4:生成报告 ↓ 超时！ 重启 → ❌ 全部重来 新流程（有checkpoint）： 启动 → 读取checkpoint → 发现step3已完成 → 跳过step1/2/3 → 从step4继续 → step4:生成报告 → 完成 ✅

### 5.5 实施路线图

阶段 | 内容 | 工期 | 交付物
--- | --- | --- | ---
Phase 1 | 开发checkpoint.sh脚本（save/get/list/done/prune） + kanban.db集成 | 1天 | checkpoint.sh + 测试
Phase 2 | 更新SOUL.md + IDENTITY.md，添加checkpoint铁律 + 引导Agent在长任务中自动调用 | 0.5天 | SOUL.md更新
Phase 3 | 对接SSH健康日报等现有cron任务 + 验证中断恢复流程 | 0.5天 | 集成测试报告
Phase 4 | 扩展至跨Profile协作场景 （ops→finance→ops 链式任务） | 1天 | 跨Profile checkpoint规范

总工期：约3天 · 复杂度：低 · 风险：低

## 六、风险评估

风险 | 等级 | 缓解措施
--- | --- | ---
Agent忘记存checkpoint | 中 | SOUL.md铁律 + cron任务启动时默认执行checkpoint检查。Phase2的SOUL更新定义清晰铁律。
checkpoint步骤粒度不精确 | 低 | 结构化的cron/脚本任务天然有明确步骤边界。非结构化任务暂不强制checkpoint。
kanban.db写冲突 | 低 | SQLite单写线程 + kanban的claim_lock机制已支持并发。checkpoint通过独立SQLite连接写入。
checkpoint数据膨胀 | 低 | checkpoint prune命令定期清理。每步只保存结构化摘要（非原始消息），空间极小。

## 七、结论

### ✅ 可行 · 推荐立即执行Phase 1

方案A（Hermes原生Task Checkpoint）以最低的成本（3天）和最少的依赖（零新框架），解决了长周期Agent任务中断恢复的核心痛点。核心洞察是：Hermes的kanban系统已经是「准检查点」设施，只需要在SOUL层和脚本层做两件事：

1. 开发checkpoint.sh脚本，封装kanban读写操作
2. 在SOUL.md中加入"每步完成必存checkpoint"的铁律

不推荐方案C（引入LangGraph）：LangGraph的checkpoint是为图结构工作流设计的，而我们大多数Agent任务是对话驱动的。引入LangGraph对于我们的场景如同"用航空母舰解决过河问题"——成本高、不匹配、不值得。

方案B（Hermes Plugin）可以作为中长期选项保留，当Agent任务变得更复杂、步骤粒度更细时再考虑。

博海科技 · 运维BOT · 2026-07-10
基于LangGraph 1.x Checkpointer模型 + Hermes Agent 0.18.0 kanban系统对标分析