Hermes CI FixandHermes AI
e1a9b25afa
- nginx 安全加固 (CSP, HSTS, 缓存策略) - 共享 style.css - 138个页面全部接入 Co-authored-by: Hermes AI <agent@hermes>
309 lines
16 KiB
HTML
309 lines
16 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>模式A可行性研究 · LangGraph Checkpoint ↔ Hermes集成方案</title>
|
||
<style>
|
||
:root {
|
||
--bg: #0f172a; --card: #1e293b; --border: #334155;
|
||
--text: #e2e8f0; --muted: #94a3b8; --accent: #38bdf8;
|
||
--green: #22c55e; --yellow: #eab308; --red: #ef4444;
|
||
--gold: #f59e0b; --purple: #a78bfa;
|
||
}
|
||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||
body { font-family: -apple-system, 'Segoe UI', 'Noto Sans SC', sans-serif; background: var(--bg); color: var(--text); line-height: 1.7; padding: 2rem 1rem; }
|
||
.container { max-width: 960px; margin: 0 auto; }
|
||
|
||
h1 { font-size: 1.6rem; border-bottom: 2px solid var(--accent); padding-bottom: .5rem; margin-bottom: .5rem; }
|
||
.meta { color: var(--muted); font-size: .85rem; margin-bottom: 1.5rem; }
|
||
h2 { font-size: 1.2rem; color: var(--accent); margin: 2rem 0 .6rem; }
|
||
h3 { font-size: 1.05rem; color: var(--gold); margin: 1.2rem 0 .4rem; }
|
||
h4 { color: var(--purple); margin: 1rem 0 .3rem; }
|
||
|
||
p, li { color: var(--text); margin-bottom: .4rem; }
|
||
ul, ol { padding-left: 1.5rem; margin: .4rem 0 .8rem; }
|
||
|
||
table { width: 100%; border-collapse: collapse; margin: .8rem 0; font-size: .9rem; }
|
||
th, td { border: 1px solid var(--border); padding: .5rem .6rem; text-align: left; }
|
||
th { background: var(--card); color: var(--accent); font-weight: 600; }
|
||
|
||
.card { background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 1rem; margin: .8rem 0; }
|
||
|
||
.verdict-box { background: linear-gradient(135deg, #1e3a5f, #1e293b); border: 2px solid var(--accent); border-radius: 10px; padding: 1.2rem; margin: 1.5rem 0; }
|
||
.verdict-box h3 { margin-top: 0; color: var(--accent); }
|
||
|
||
.arch { background: var(--card); border: 1px solid var(--gold); border-radius: 8px; padding: 1rem; margin: .8rem 0; font-family: 'Courier New', monospace; font-size: .85rem; line-height: 1.5; white-space: pre; overflow-x: auto; }
|
||
|
||
.badge { display: inline-block; padding: .15rem .5rem; border-radius: 4px; font-size: .75rem; font-weight: 600; }
|
||
.bg-green { background: #14532d; color: var(--green); }
|
||
.bg-yellow { background: #422006; color: var(--yellow); }
|
||
.bg-red { background: #450a0a; color: var(--red); }
|
||
.bg-blue { background: #0c4a6e; color: var(--accent); }
|
||
.bg-purple { background: #3b0764; color: var(--purple); }
|
||
|
||
.pros { color: var(--green); }
|
||
.cons { color: var(--red); }
|
||
|
||
hr { border: none; border-top: 1px solid var(--border); margin: 1.5rem 0; }
|
||
</style>
|
||
<link rel="stylesheet" href="/style.css">
|
||
</head>
|
||
<body>
|
||
<div class="container">
|
||
|
||
<h1>🔬 模式A可行性研究：LangGraph Checkpoint ↔ Hermes集成</h1>
|
||
<div class="meta">
|
||
研究日期: 2026-07-10 | 技术栈: Hermes Agent 0.18.0 / LangGraph 1.x | 目标: 长周期Agent任务状态持久化
|
||
</div>
|
||
|
||
<h2>一、问题定义</h2>
|
||
<p><strong>痛点</strong>：Hermes Agent的长周期任务（如跨Bot协作、定时多步骤报告、运维审计链）在执行到中途时，如果遇到超时（max_turns: 90 / gateway_timeout: 1800秒）、进程重启、或节点失败，<span class="bg-red badge">整个任务进度丢失</span>，必须从头重新执行。</p>
|
||
<p><strong>目标</strong>：在Hermes Agent的会话执行流程中引入「检查点」机制——每个逻辑步骤完成后保存状态快照，任务中断后可以从最近的检查点继续，而不是从头重来。</p>
|
||
|
||
<h2>二、技术对标</h2>
|
||
|
||
<table>
|
||
<tr><th width="25%">维度</th><th width="37%">LangGraph</th><th width="38%">Hermes Agent</th></tr>
|
||
<tr>
|
||
<td><strong>状态粒度</strong></td>
|
||
<td>超级步骤（super-step）边界 → 每次图节点执行完后保存checkpoint</td>
|
||
<td>整个会话（conversation-level） → 每轮消息保存到session JSON，无步骤级</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>线程模型</strong></td>
|
||
<td><code>thread_id</code> → 每次调用指定thread_id，checkpoint自动关联</td>
|
||
<td><code>session_id</code> → 每个会话一个ID，但无恢复执行机制</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>存储后端</strong></td>
|
||
<td>InMemorySaver / SqliteSaver / PostgresSaver</td>
|
||
<td>JSON文件 + SQLite (kanban) + 内存 (memory)</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>容错机制</strong></td>
|
||
<td>pending writes + checkpoint resume → 节点失败只重跑失败节点</td>
|
||
<td>无 → 失败后整个任务重跑</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>时间旅行</strong></td>
|
||
<td>支持 → 回放到任意checkpoint并fork</td>
|
||
<td>不支持 → 只能查看历史消息</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>人机协同</strong></td>
|
||
<td>原生interrupt机制 → 可在节点间插入人工审批</td>
|
||
<td>通过approval-gate实现（审批单个命令，非流程级）</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>跨线程记忆</strong></td>
|
||
<td>Store → 跨thread_id的持久化key-value</td>
|
||
<td>Memory + User Profile → 跨会话持久化</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h2>三、Hermes现有的「准检查点」设施</h2>
|
||
|
||
<p>研究后发现，Hermes实际上已经有了3个与状态持久化相关的机制，但存在关键缺口：</p>
|
||
|
||
<h3>① Session JSON 文件</h3>
|
||
<p>位置：<code>/root/.hermes/sessions/session_{id}.json</code></p>
|
||
<p>保存完整的对话消息（messages）和元数据。但：<span class="bg-red badge">扁平化保存，不区分任务步骤</span>。重启后agent可以读取旧session，但无法知道"已执行到第几步"。</p>
|
||
|
||
<h3>② Kanban Task 系统</h3>
|
||
<p>位置：<code>kanban.db</code> → <code>tasks</code> 表 + <code>task_runs</code> 表</p>
|
||
<p>已有完整的任务生命周期（status/runs/result/idempotency_key）。<span class="bg-green badge">最匹配checkpoint概念</span>的设施，但当前的kanban任务不和Agent执行流程绑定。</p>
|
||
|
||
<h3>③ Memory 持久化</h3>
|
||
<p>通过 <code>memory</code> + <code>user_profile</code> 实现跨会话知识持久化。但：这是知识层，不是执行状态层。</p>
|
||
|
||
<div class="card">
|
||
<h4>🔑 关键发现</h4>
|
||
<p><strong>Kanban的task_runs表已经隐含了「检查点」的雏形</strong>。每次task尝试（attempt）都有独立的started_at/completed_at/status/result。如果能做到：</p>
|
||
<ul>
|
||
<li>在Agent执行的每个「逻辑步骤」结束时，将步骤状态写入kanban的task_runs.result</li>
|
||
<li>重启后，Agent读取task_runs.result，判断已完成的步骤和下一个步骤</li>
|
||
<li>比引入LangGraph更轻量，100%复用现有基础设施</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h2>四、三种集成方案评估</h2>
|
||
|
||
<h3>方案A：Hermes原生Task Checkpoint <span class="bg-green badge">推荐</span></h3>
|
||
<div class="card">
|
||
<p><strong>思路</strong>：利用Hermes现有的kanban task系统，在每个逻辑步骤结束时写入步骤状态。Agent重启时从kanban读取已完成的步骤。</p>
|
||
<p><strong>工作量</strong>：<span class="bg-yellow badge">低</span> — 约1-2天</p>
|
||
<p><strong>实现方式</strong>：</p>
|
||
<ol>
|
||
<li>在SOUL.md中增加一条铁律：<strong>"对长周期任务，每完成一个逻辑步骤，通过sqlite写入kanban.db的task_runs.result"</strong></li>
|
||
<li>开发一个 <code>checkpoint.py</code> 脚本，提供 <code>save_step(task_id, step_name, status)</code> 和 <code>get_state(task_id) → last_step</code></li>
|
||
<li>在cron任务和多步骤运维流程中集成——启动时检查是否有未完成的任务</li>
|
||
</ol>
|
||
<p><span class="pros">✅ 零新依赖</span> · <span class="pros">✅ 复用现有kanban体系</span> · <span class="pros">✅ 与任务调度紧密集成</span></p>
|
||
<p><span class="cons">⚠️ 仅适用于结构化/可分解的任务</span> · <span class="cons">⚠️ 需要Agent在SOUL中记忆"每步完成时存checkpoint"</span></p>
|
||
</div>
|
||
|
||
<h3>方案B：Hermes Checkpoint Plugin <span class="bg-blue badge">中长期</span></h3>
|
||
<div class="card">
|
||
<p><strong>思路</strong>：为Hermes Agent开发一个checkpoint插件，hook到Agent的每个tool_call/tool_result周期，自动保存执行轨迹。从底层实现步骤级快照。</p>
|
||
<p><strong>工作量</strong>：<span class="bg-yellow badge">中</span> — 约1-2周</p>
|
||
<p><strong>实现方式</strong>：编写Hermes插件（plugins目录下），注册中间件拦截tool_call事件 → 序列化当前上下文到SQLite checkpoint表 → 重启时恢复上下文。</p>
|
||
<p><span class="pros">✅ 全自动，Agent无需记住手动存checkpoint</span> · <span class="pros">✅ 粒度精细</span></p>
|
||
<p><span class="cons">⚠️ Hermes插件API可能有限制</span> · <span class="cons">⚠️ 上下文中断和重建有歧义性风险</span></p>
|
||
</div>
|
||
|
||
<h3>方案C：引入LangGraph编排层 <span class="bg-red badge">不推荐</span></h3>
|
||
<div class="card">
|
||
<p><strong>思路</strong>：将Hermes的任务编排层替换为LangGraph Runtime，Hermes仅作为前端控制器</p>
|
||
<p><strong>工作量</strong>：<span class="bg-red badge">高</span> — 1-2个月</p>
|
||
<p><strong>实现方式</strong>：将复杂多步骤任务提取为LangGraph StateGraph → LangGraph管理checkpoint → Hermes通过system-bus调用LangGraph runtime</p>
|
||
<p><span class="pros">✅ 得到LangGraph生态的全部能力（checkpoint/time travel/interrupt）</span></p>
|
||
<p><span class="cons">❌ 引入一个大框架作为编排依赖</span> · <span class="cons">❌ LangGraph面向代码定义图，适合确定性工作流而非Agent自发任务</span> · <span class="cons">❌ 我们绝大多数Agent任务是"对话驱动"而非"图驱动"，不匹配LangGraph的核心模型</span> · <span class="cons">❌ 与现有Hermes的13个Profile集成成本极高</span></p>
|
||
</div>
|
||
|
||
<h2>五、推荐方案详述：方案A Hermes原生Task Checkpoint</h2>
|
||
|
||
<h3>5.1 架构设计</h3>
|
||
|
||
<div class="arch">┌──────────────────────────────────────────────────┐
|
||
│ 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继续 │
|
||
└──────────────────────────────────────────────────┘</div>
|
||
|
||
<h3>5.2 核心组件</h3>
|
||
|
||
<table>
|
||
<tr><th>组件</th><th>位置</th><th>职责</th></tr>
|
||
<tr><td><code>checkpoint.sh</code></td><td>scripts/checkpoint.sh</td><td>保存步骤状态<br><code>./checkpoint.sh save task_xxx step_2 "数据清洗完成"</code></td></tr>
|
||
<tr><td><code>checkpoint.sh get</code></td><td>同上</td><td>读取任务当前进度<br><code>./checkpoint.sh get task_xxx → step_2/done</code></td></tr>
|
||
<tr><td><code>checkpoint.sh list</code></td><td>同上</td><td>列出所有未完成的任务<br><code>./checkpoint.sh list → task_xxx (step_2/5)</code></td></tr>
|
||
<tr><td>SOUL.md铁律</td><td>SOUL.md</td><td>引导Agent在每个逻辑步骤后自动调用checkpoint</td></tr>
|
||
<tr><td>DailyHealth cron</td><td>cron</td><td>优先恢复未完成的checkpoint任务</td></tr>
|
||
</table>
|
||
|
||
<h3>5.3 脚本接口设计</h3>
|
||
|
||
<div class="arch"># 保存步骤
|
||
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小时前的未完成任务</div>
|
||
|
||
<h3>5.4 集成工作流示例：SSH健康日报</h3>
|
||
|
||
<div class="arch">当前流程（无checkpoint）：
|
||
启动 → step1:磁盘检查 → step2:内存检查 → step3:日志分析 → step4:生成报告
|
||
↓ 超时！
|
||
重启 → ❌ 全部重来
|
||
|
||
新流程（有checkpoint）：
|
||
启动 → 读取checkpoint → 发现step3已完成
|
||
→ 跳过step1/2/3 → 从step4继续 → step4:生成报告 → 完成 ✅</div>
|
||
|
||
<h3>5.5 实施路线图</h3>
|
||
|
||
<table>
|
||
<tr><th>阶段</th><th>内容</th><th>工期</th><th>交付物</th></tr>
|
||
<tr>
|
||
<td><strong>Phase 1</strong></td>
|
||
<td>开发checkpoint.sh脚本（save/get/list/done/prune）<br>+ kanban.db集成</td>
|
||
<td><span class="bg-yellow badge">1天</span></td>
|
||
<td>checkpoint.sh + 测试</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Phase 2</strong></td>
|
||
<td>更新SOUL.md + IDENTITY.md，添加checkpoint铁律<br>+ 引导Agent在长任务中自动调用</td>
|
||
<td><span class="bg-green badge">0.5天</span></td>
|
||
<td>SOUL.md更新</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Phase 3</strong></td>
|
||
<td>对接SSH健康日报等现有cron任务<br>+ 验证中断恢复流程</td>
|
||
<td><span class="bg-green badge">0.5天</span></td>
|
||
<td>集成测试报告</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Phase 4</strong></td>
|
||
<td>扩展至跨Profile协作场景<br>（ops→finance→ops 链式任务）</td>
|
||
<td><span class="bg-yellow badge">1天</span></td>
|
||
<td>跨Profile checkpoint规范</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p><strong>总工期：约3天</strong> · 复杂度：低 · 风险：低</p>
|
||
|
||
<h2>六、风险评估</h2>
|
||
|
||
<table>
|
||
<tr><th>风险</th><th>等级</th><th>缓解措施</th></tr>
|
||
<tr>
|
||
<td>Agent忘记存checkpoint</td>
|
||
<td><span class="bg-yellow badge">中</span></td>
|
||
<td>SOUL.md铁律 + cron任务启动时默认执行checkpoint检查。Phase2的SOUL更新定义清晰铁律。</td>
|
||
</tr>
|
||
<tr>
|
||
<td>checkpoint步骤粒度不精确</td>
|
||
<td><span class="bg-green badge">低</span></td>
|
||
<td>结构化的cron/脚本任务天然有明确步骤边界。非结构化任务暂不强制checkpoint。</td>
|
||
</tr>
|
||
<tr>
|
||
<td>kanban.db写冲突</td>
|
||
<td><span class="bg-green badge">低</span></td>
|
||
<td>SQLite单写线程 + kanban的claim_lock机制已支持并发。checkpoint通过独立SQLite连接写入。</td>
|
||
</tr>
|
||
<tr>
|
||
<td>checkpoint数据膨胀</td>
|
||
<td><span class="bg-green badge">低</span></td>
|
||
<td>checkpoint prune命令定期清理。每步只保存结构化摘要（非原始消息），空间极小。</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h2>七、结论</h2>
|
||
|
||
<div class="verdict-box">
|
||
<h3>✅ 可行 · 推荐立即执行Phase 1</h3>
|
||
<p><strong>方案A（Hermes原生Task Checkpoint）</strong>以最低的成本（3天）和最少的依赖（零新框架），解决了长周期Agent任务中断恢复的核心痛点。核心洞察是：<strong>Hermes的kanban系统已经是「准检查点」设施</strong>，只需要在SOUL层和脚本层做两件事：</p>
|
||
<ol>
|
||
<li>开发checkpoint.sh脚本，封装kanban读写操作</li>
|
||
<li>在SOUL.md中加入"每步完成必存checkpoint"的铁律</li>
|
||
</ol>
|
||
<p><strong>不推荐方案C（引入LangGraph）</strong>：LangGraph的checkpoint是为图结构工作流设计的，而我们大多数Agent任务是对话驱动的。引入LangGraph对于我们的场景如同"用航空母舰解决过河问题"——成本高、不匹配、不值得。</p>
|
||
<p><strong>方案B（Hermes Plugin）</strong>可以作为中长期选项保留，当Agent任务变得更复杂、步骤粒度更细时再考虑。</p>
|
||
</div>
|
||
|
||
<hr>
|
||
|
||
<p style="text-align:center; color:var(--muted); font-size:.85rem;">
|
||
博海科技 · 运维BOT · 2026-07-10<br>
|
||
基于LangGraph 1.x Checkpointer模型 + Hermes Agent 0.18.0 kanban系统对标分析
|
||
</p>
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|