hermes-workspace Swarm2 Worker 生命周期与上下文压缩（Compaction）实战指南

【免费下载链接】hermes-workspaceNative web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.项目地址https://gitcode.com/gh_mirrors/he/hermes-workspace点击查看免费下载本指南围绕 hermes-workspace 中 Swarm2 多智能体编排系统的 Worker 生命周期管理展开完整解析docs/swarm2-worker-lifecycle-compaction-spec.md规格文档从上下文压力检测、Handoff 契约、状态机判定到自动续约renewal流程。读完本文你将掌握如何通过state.db读取 token 压力、如何请求/解析 durable handoff、如何安全重启 Worker 并注入 resume 提示以及如何借助生命周期 API 与定时巡检脚本实现全自动上下文压缩运维。背景为什么长生命周期 Worker 需要上下文压缩Swarm2 中的 Worker 是持久的 Claude Agent每个 Worker 拥有独立的 profile、session、tmux pane、运行时状态runtime.json和记忆memory。这是正确的架构——Worker 可以跨任务保留技能与经验但代价是长期运行的 Worker 上下文会持续增长一旦逼近模型窗口model window回复质量就会明显退化遗忘早期指令、重复劳动、甚至产生不一致决策。规格文档 docs/swarm2-worker-lifecycle-compaction-spec.md 提出的目标是一个自动生命周期系统让 Worker 具备六种能力在较大的上下文预算下运行run with large context budgets在质量下降前主动打点checkpoint before quality drops写出可持久化的交接文档write durable handoffs干净地重启自己restart/new themselves cleanly从 Handoff 与任务mission状态恢复resume from handoff and mission state始终保持编排者orchestrator知情。这套系统在源码中的落点集中在 src/server/swarm-lifecycle.ts配套 API 在 src/routes/api/swarm-lifecycle.ts下文的每个环节都有对应实现可以对照阅读。上下文策略三层 Token 阈值规格文档为每个 Worker 定义了一套上下文策略context policy包含三个阈值阈值默认值触发行为soft limit软阈值250k tokens进入watch请求尽快输出精简 checkpointhandoff limit交接阈值400k tokens进入handoff_required在做更多工作前必须写入完整 handoffhard limit硬阈值500k tokens进入renew_required停止接收新工作直到续约完成规格明确指出具体数值应按 model/profile 可配置但默认策略必须安全。源码中以SwarmLifecyclePolicy类型与DEFAULT_POLICY常量落实了这一点// src/server/swarm-lifecycle.ts export type SwarmLifecyclePolicy { softTokens: number // 默认 250_000 handoffTokens: number // 默认 400_000 hardTokens: number // 默认 500_000 } const DEFAULT_POLICY: SwarmLifecyclePolicy { softTokens: 250_000, handoffTokens: 400_000, hardTokens: 500_000, }getSwarmLifecycleStatus(workerId, policy DEFAULT_POLICY)的第二个参数允许调用方按 Worker 覆盖策略这正是按模型/profile 可配置的扩展点——Stage 3 的 per-model context policies 会在此基础上演化。生命周期状态机规格文档定义了六种生命周期状态healthy当前 token 低于 soft limit正常运行watch已超过 soft limit继续工作但需要监控上下文增长handoff_required超过 handoff limit要求 Worker 先写 handoff 再继续renew_required超过 hard limit或反复出现 stale/fragmented上下文碎片化状态renewing已请求 handoff正在重启 tmux/sessionblocked续约失败或 handoff 缺失。从源码看当前已实现的是前四个状态SwarmContextState联合类型renewing与blocked属于规格中的后续阶段Stage 2/3。状态判定由classify()完成// src/server/swarm-lifecycle.ts export type SwarmContextState healthy | watch | handoff_required | renew_required function classify(totalTokens: number, policy: SwarmLifecyclePolicy): SwarmContextState { if (totalTokens policy.hardTokens) return renew_required if (totalTokens policy.handoffTokens) return handoff_required if (totalTokens policy.softTokens) return watch return healthy }每个状态还附带机器可读的recommendedActionfunction recommendedAction(state: SwarmContextState): string { switch (state) { case healthy: return Continue normally. case watch: return Monitor context; request concise checkpoint soon. case handoff_required: return Request durable handoff before assigning more work. case renew_required: return Renew worker after handoff; avoid new work until restarted. } }Token 压力检测从 Claudestate.db读取会话计数生命周期系统的第一步是检测上下文压力。规格文档明确要求从 Claude 的state.db会话 token 计数中读取数据。实现上getSwarmLifecycleStatus通过execFileSync(python3, ...)执行一段内联 Python 脚本源码中的PYTHON_STATUS常量以只读模式sqlite3.connect(file:...?modero, uriTrue)打开 profile 下的state.db查询最新一条会话select * from sessions order by started_at desc limit 1从 sessions 表读出input_tokens、output_tokens、cache_read_tokens、cache_write_tokens、reasoning_tokens以及model、title额外对 messages 表执行coalesce(sum(token_count), 0)汇总所有消息 token 数messageTokens作为兜底信号将结果以 JSON 打印供 Node 侧JSON.parse消费。总 token 数采用保守的取最大策略const totalTokens Math.max( inputTokens outputTokens cacheReadTokens cacheWriteTokens reasoningTokens, messageTokens )Profile 目录由 src/server/claude-paths.ts 提供getHermesRoot()优先读取HERMES_HOME/CLAUDE_HOME环境变量默认回落到~/.hermesgetProfilesDir()即hermesRoot/profiles每个 Worker 的 profile 位于profiles/workerId。该路径同时也是state.db所在位置。最终返回的SwarmLifecycleStatus结构体完整覆盖规格中每个 Worker 的上下文状态、当前会话 token 估计等产品需求export type SwarmLifecycleStatus { workerId: string profilePath: string sessionId: string | null model: string | null title: string | null inputTokens: number outputTokens: number cacheReadTokens: number cacheWriteTokens: number reasoningTokens: number messageTokens: number totalTokens: number contextState: SwarmContextState recommendedAction: string policy: SwarmLifecyclePolicy handoffPath: string handoffExists: boolean lastHandoffAt: number | null // 由 handoff 文件的 mtime 推断 }Handoff 契约续约前的交接文档结构化格式规格文档规定续约之前Worker 必须以如下 checkpoint 格式返回或写出 handoffSTATE: HANDOFF FILES_CHANGED: ... COMMANDS_RUN: ... RESULT: current state and what landed BLOCKER: blocker or none NEXT_ACTION: exact next step after renewal这段格式在仓库中并非孤立约定而是被 src/server/swarm-checkpoints.ts 的parseSwarmCheckpoint()作为机器可解析的契约实现。解析器会通过正则^\s*([A-Z_ -]{3,24})\s*:\s*(.*)$逐行匹配六个字段STATE/FILES_CHANGED/COMMANDS_RUN/RESULT/BLOCKER/NEXT_ACTION同时兼容普通文本与Markdown 加粗**STATE:**两种写法解析前先剥掉**缺少任一字段、或STATE不在DONE | BLOCKED | NEEDS_INPUT | HANDOFF | IN_PROGRESS枚举内即判定解析失败返回null每个 state label 会映射到运行时状态与 checkpoint 状态例如HANDOFF → runtimeState: idle, checkpointStatus: handoff。newestCheckpointFromMessages()则从消息流倒序中提取最近一条 assistant 消息里的最新 checkpoint——这正是从 chat 解析 handoff checkpoint续约序列第 3 步的实现基础。持久化路径规格文档给出的 durable handoff 路径是/Users/aurora/.openclaw/workspace/memory/handoffs/swarm/workerId-latest.md并注明latest.md是恢复的唯一来源可选的带时间戳归档版本可以在之后增加。源码中的handoffPath()将其泛化为基于SWARM_MEMORY_ROOT的路径// src/server/swarm-lifecycle.ts function handoffPath(workerId: string): string { return join(SWARM_MEMORY_ROOT, memory, handoffs, swarm, ${workerId}-latest.md) }其中SWARM_MEMORY_ROOT定义于 src/server/swarm-environment.ts默认取~/hermes-workspace即join(homedir(), hermes-workspace)也可通过环境变量HERMES_SWARM_MEMORY_ROOT覆盖——这正是规格中/Users/aurora/.openclaw/...这类机器特定路径在实现中被参数化的方式。同一目录层级下src/server/swarm-memory.ts 的writeSwarmHandoff()提供了双写机制本地写profiles/workerId/memory/handoffs/missionId.md同时镜像到共享根目录的workerId-latest.md与生命周期模块的latest.md约定互补。续约序列Renewal Sequence规格文档定义了八步续约流程从 Claudestate.db会话 token 计数检测上下文压力通过 tmux dispatch 请求 Worker 写 handoff从 chat 解析 handoff checkpoint将 handoff 保存到 durable memory 路径停止 Worker 的 tmux session以相同 profile 和 cwd 启动全新的 Claude session发送包含 handoff 摘要 当前 mission 分配信息的 resume prompt将运行时状态标记为 healthy/executing。源码中这三步被封装为三个导出函数调用链完整可循。requestWorkerHandoff请求交接requestWorkerHandoff(workerId)会构造一个严格的CONTEXT_HANDOFF_REQUIRED提示词通过sendToWorker()投递给 Worker。提示词要求 Worker 同时写两个路径本地副本profiles/workerId/memory/handoffs/latest.md共享 durable 路径SWARM_MEMORY_ROOT/memory/handoffs/swarm/workerId-latest.md。提示词内嵌了完整的 handoff 模板# Handoff — workerId — missionId、Generated、## Current state、## Objective、## Completed、## In progress、## Files touched、## Commands run、## Blockers、## Next exact action、## Resume prompt并要求 Worker 以STATE: HANDOFF的 checkpoint 格式回复。请求的同时会通过appendSwarmMemoryEvent()写入一条handoff-requested类型的事件到 Swarm 记忆含共享/本地 handoff 路径与投递是否成功。sendToWorker()内部实现了跨平台投递src/server/swarm-lifecycle.tsWindows 或无 tmux 环境使用原生child_process.spawn启动的 Worker 进程直接把提示词写入proc.stdinLinux/macOS 且存在 tmux通过tmux load-buffer载入文本、send-keys C-u清行、paste-buffer粘贴、延时 150ms 后send-keys Enter提交目标 session 名为swarm-workerId。renewWorker停止、重启、注入恢复提示renewWorker(workerId)严格执行先有 handoff 才能重启的契约// src/server/swarm-lifecycle.ts export async function renewWorker(workerId: string) { const hp handoffPath(workerId) if (!existsSync(hp)) { return { ok: false, restarted: false, resumeSent: false, error: Handoff missing; request handoff first, handoffPath: hp } } // 1) 停止 Worker 进程原生 kill 或 tmux kill-session // 2) 等待 600ms 让资源释放 // 3) 以相同 profile 启动新会话原生 spawn 或 tmux new-session // 4) 等待 1500ms 等 shell 提示符出现 // 5) 发送 RESUME_AFTER_HANDOFF 提示词 }恢复提示词RESUME_AFTER_HANDOFF明确要求 Worker读取共享 handoff${hp}与本地副本~/.hermes/profiles/workerId/memory/handoffs/、读取runtime.json然后从 Next exact action 继续并在重新落地后回复一份全新的 checkpoint。其中runtime.json的当前 mission/assignment 通过readRuntimeMissionContext()读取字段为currentMissionId/currentAssignmentId对应规格中resume prompt 携带 active mission assignment的要求。成功后同样会写入resume类型的记忆事件。Worker 日志统一追加到profiles/workerId/logs/worker.logappendWorkerLog()包含[dispatch]、[stdout]、[stderr]、[exit]、[error]五类记录方便排查续约过程。生命周期 API状态查询与动作下发规格文档 Stage 1 的首要任务是增加生命周期状态 API源码中的路由为 src/routes/api/swarm-lifecycle.ts/api/swarm-lifecycle需要isAuthenticated认证。GET批量状态查询GET /api/swarm-lifecycle?workerIdswarm13不传workerId时通过listSwarmWorkerIds()src/server/swarm-foundation.ts 中读取profiles目录枚举全部 Worker传入时则需通过 src/server/swarm-roster.ts 的isSwarmWorkerId()校验正则/^(swarm\d|[a-z][a-z0-9]*(?:-[a-z0-9])*)$/i支持swarm13或语义化 profile id返回{ ok, checkedAt, workers: SwarmLifecycleStatus[] }。POST四种动作action行为auto-sweep对全部或指定Worker 执行自动巡检见下文request-handoff触发requestWorkerHandoff(workerId)返回{ ok, workerId, action, handoffPath }renew触发renewWorker(workerId)返回{ ok, restarted, resumeSent, handoffPath }notify-handoff-written调用notifyHandoffWritten(workerId)向 Swarm 记忆写入handoff-written事件Worker 确认已写 handoff 时的回调自动巡检Auto Sweep从手动到自动续约规格文档 Stage 3 的自动续约循环在源码中已有基础实现autoSweepLifecycle(workerIds)对每个 Worker 依据当前状态做决策if (contextState handoff_required) → request-handoff if (contextState renew_required handoffExists) → renew if (contextState renew_required !handoffExists) → request-handoff先补交接再续约 else → none不干预配套的定时入口是脚本 scripts/swarm-lifecycle-sweep.sh向http://localhost:3002/api/swarm-lifecycle发送{action:auto-sweep}并把响应按 JSONL 追加到$HOME/.ocplatform/workspace/memory/swarm/lifecycle-logs/YYYY-MM-DD.jsonl。脚本注释建议通过 cron 或 launchd每约 10 分钟运行一次可用环境变量调整SWARM_BASE_URLhttp://localhost:3002 ./scripts/swarm-lifecycle-sweep.sh SWARM_BASE_URLhttps://swarm.example.com SWARM_LIFECYCLE_LOG_DIR/var/log/swarm ./scripts/swarm-lifecycle-sweep.sh安全规则Safety Rules规格文档列出四条不可妥协的安全红线实现与设计均围绕其展开Worker 正在积极写入actively writing时绝不自动续约除非已达 hard limit——autoSweepLifecycle只在handoff_required/renew_required才动作healthy/watch 一律none续约后不得立即执行破坏性操作除非 mission policy 明确允许——恢复提示词要求 Worker 先重新落地re-ground并回复新 checkpoint而非直接开工重启前 handoff 必须完整——renewWorker以existsSync(hp)硬校验兜底缺失时直接返回Handoff missing; request handoff first绝不盲目重启handoff 解析失败则标记blocked并上报 orchestrator/人工——parseSwarmCheckpoint()对缺字段/非法 STATE 返回null为blocked状态与人工介入保留了明确触发点该状态在规格中定义属后续实现阶段。产品需求Swarm2 UI 需要展示什么规格文档对 Swarm2 界面提出的产品需求包括六项均可由SwarmLifecycleStatus直接支撑每个 Worker 的上下文状态contextState当前会话 token 估算totalTokens及各分项 token 计数生命周期状态lifecycle status最近 handoff 时间lastHandoffAt来自latest.md文件 mtimerenew 按钮对应 POSTrenew动作自动续约状态对应auto-sweep的巡检结果与记忆事件流。规格文档 Stage 2 还规划了runtime.json新增contextTokens、contextState、lastHandoffAt三个字段以及 UI 上的生命周期徽标lifecycle badges——目前runtime.json已承载currentMissionId/currentAssignmentId这些新字段是后续扩展方向。分阶段落地路线与当前实现状态规格文档给出三阶段实施计划结合仓库现状可对照如下Stage 1已基本完成✅ 生命周期状态 APIGET/api/swarm-lifecycle✅ 从state.db读取最新会话 token 计数✅ 返回生命周期状态与 recommended action✅ request-handoff 动作向 tmux 发送严格 handoff 提示词✅ renew 动作当前实现为手动触发未做硬性force门控但以handoff 必须存在作为安全前提✅ 归一化 Swarm wrapper 的 cwdsrc/server/swarm-environment.ts 中SWARM_CANONICAL_REPO与 wrapper 路径规则。Stage 2部分完成✅ 解析 handoff checkpointparseSwarmCheckpoint 将 checkpoint 落盘为 durable handoff 文件writeSwarmHandoff已具备双写能力需与生命周期流程串接runtime.json新增contextTokens/contextState/lastHandoffAt Swarm2 UI 生命周期徽标。Stage 3进行中✅ 自动续约循环基础版autoSweepLifecycle 巡检脚本✅ 携带 mission 状态的 resume promptreadRuntimeMissionContextRESUME_AFTER_HANDOFF 按 model 的上下文策略SwarmLifecyclePolicy已支持注入自定义策略per-model 映射待落地。总体来看本仓库已经把规格文档的核心机制token 压力检测、状态分类、handoff 契约、安全续约、自动巡检以可运行的 TypeScript 服务与 Bash 脚本完整落地后续阶段集中在 UI 呈现、runtime.json字段与 per-model 策略等增强项。若要在自己的部署中启用自动压缩最快路径是确保 Worker profile 与state.db正常 → 手动调用 POST/api/swarm-lifecycle的request-handoff/renew验证单点流程 → 用 cron 注册 scripts/swarm-lifecycle-sweep.sh 每 10 分钟巡检即可获得自动化的上下文生命周期管理。赞分享【免费下载链接】hermes-workspaceNative web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.项目地址https://gitcode.com/gh_mirrors/he/hermes-workspace点击查看免费下载相关推荐ClawX 中 ACP Chat 的 OpenClaw 上下文压缩Compaction生命周期可视化协议、补丁与渲染实现全解析ClawX 中 ACP Chat 的 OpenClaw 上下文压缩Compaction生命周期可视化协议、补丁与渲染实现全解析 导读 本篇文章围绕 Cla人工智能AI 应用桌面应用交互助手Hermes Workspace Swarm2 记忆框架实战指南worker 多任务连续性、事件流与重启恢复Hermes Workspace Swarm2 记忆框架实战指南worker 多任务连续性、事件流与重启恢复 本文围绕 docs/swarm2 memoryContext Compaction上下文压缩面向 LLM Agent 的高效上下文管理实战指南Context Compaction上下文压缩面向 LLM Agent 的高效上下文管理实战指南 导读 在构建 AI Agent 与长会话应用时上下文窗文档教程知识库上一篇如何让GitHub下载速度提升100倍Fast-GitHub插件的终极解决方案下一篇深入解析 Multipass cloud-init-config.isoISO 9660 与 Joliet 扩展的读写与导航原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考