Hermes Agent Control Room：Claude Code 的自主开发循环引擎

图1：Hermes Agent Control Room 系统架构图，展示了从单 Agent 到团队自动化的演进路径

从一个痛点说起

想象一下这个场景：你正在用 Claude Code 开发一个中型项目，需要连续工作 8 小时。在此期间，你会反复做这些事：写代码 → 运行测试 → 看报错 → 改代码 → 再测试。每一个来回，都需要你盯着屏幕、判断 Claude 的输出、决定下一步。

这种"人在回路"的模式，对于单次任务很高效。但当你需要 Claude Code 长时间自主工作（比如跑一个完整的重构计划，或者连续实现多个功能模块），"人盯着"就成了瓶颈——你不能睡觉，但 Claude Code 跑完一次就停了。

Ralph 解决了这个问题。它是 Claude Code 的自主循环包装器：让 Claude Code 自动循环运行，直到任务完成或触发退出条件。

项目背景

Hermes Agent Control Room（GitHub 858 ⭐）由 CryptoDmitry 开发，是一个控制平面优先的 Agent 管理框架。它的核心理念是：在启动任何 Agent 之前，先建立控制平面（Control Room），用它来文档化、治理和恢复 Agent。

该仓库实际上承载了两个项目：

1. Hermes Agent Control Room 框架本体 — 管理多 Agent 团队的标准模板
2. Ralph for Claude Code（实际核心功能）— Claude Code CLI 的自主循环系统

Ralph 的前身来自 frankbria/ralph-claude-code，CryptoDmitry 将其整合进 Control Room 生态，形成了一个完整的"AI 编程自动化"解决方案。

核心功能解析

自主循环引擎（ralph_loop.sh）

Ralph 的核心是一个 Bash 脚本 ralph_loop.sh（47271 字），它驱动 Claude Code 反复执行，直到满足退出条件。

工作流程：

循环开始
  ↓
执行 Claude Code（带结构化输出：--output-format json）
  ↓
分析响应（response_analyzer.sh）
  ↓
检查退出条件
  ├── 显式 EXIT_SIGNAL + 完成指标 >= 2 → 退出（project_complete）
  ├── 连续 done 信号 >= 2 → 退出（done_signals）
  ├── 仅测试循环 >= 3 → 退出（test_only_loops）
  └── @fix_plan.md 全完成 → 退出（plan_complete）
  ↓
检查熔断器（circuit_breaker.sh）
  ├── 无进展循环 >= 3 → 熔断（HALTED）
  ├── 相同错误 >= 5 → 熔断（HALTED）
  └── 输出下降 > 70% → 熔断（HALTED）
  ↓
速率限制检查（每小时 100 次，可配置）
  ↓
写日志 → 等待 → 下一循环

这个流程的关键创新在于 EXIT_SIGNAL 双条件门控：不仅要求完成指标（completion_indicators >= 2），还要求 Claude 自己在 JSON 输出中明确声明 EXIT_SIGNAL: true。这样避免了 Claude 说"功能A完成了"就退出（因为它可能正在转向测试环节）。

智能响应分析（lib/response_analyzer.sh）

这是代码量最重的库文件，负责从 Claude Code 的 JSON 输出中提取关键信号。

解析的 JSON 结构（Claude CLI 格式）：

{
  "result": "success/error",
  "sessionId": "xxx",
  "metadata": {
    "files_changed": 5,
    "has_errors": false,
    "completion_status": "in_progress",
    "progress_indicators": ["implemented", "tests_added"]
  }
}

两阶段错误检测 是另一个精妙设计：

• 第一阶段：过滤掉 JSON 字段中的"假错误"（如 "is_error": false）
• 第二阶段：在真实日志中查找 Error:、Exception、FATAL 等模式

这样做是因为 Claude Code 的输出中经常出现 "error" 作为配置字段名或自然语言描述，简单的 grep "error" 会产生大量误报。两阶段过滤（先剔除字段名，再匹配真实错误）显著提升了检测准确率。

熔断器模式（lib/circuit_breaker.sh）

基于 Michael Nygard 的《Release It!》设计模式，Ralph 实现了三态熔断器：

状态	含义	触发条件
CLOSED	正常运行	检测到有效进展
HALF_OPEN	监控恢复	熔断后第一次重试
OPEN	熔断停止	无进展/同错误/输出下降

熔断器的核心价值是防止 Token 浪费：如果 Claude Code 在同一个错误上循环 5 次还没有进展，熔断器自动停止，避免消耗更多 API 调用。

会话生命周期管理

Ralph 实现了完整的会话持久化机制（v0.9.7+）：

• 会话ID持久化：.claude_session_id 文件存储当前会话，24小时过期
• 会话历史追踪：.ralph_session_history 记录最近 50 次会话切换
• 自动重置触发点：熔断器断开、手动中断、任务完成
• 会话切换上下文注入：每次循环通过 --append-system-prompt 告诉 Claude Code 当前循环数、剩余任务、熔断器状态

PRD 导入器（ralph_import.sh）

Ralph 不只是执行代码，还支持从文档驱动开发。ralph_import.sh 将 PRD 或规格文档转换为 Ralph 格式，自动生成 PROMPT.md 和 @fix_plan.md（优先级任务列表）。

Agent 控制室模板（templates/）

仓库还包含完整的 Control Room 模板，用于管理多 Agent 团队：

• templates/agent/：Agent 注册模板（inventory.md、runbook.md、backup.md）
• templates/docker/：Docker Compose 编排配置
• templates/task-bus/：Agent 间任务路由模板

技术架构

架构类型：Bash 脚本 + 模块化库系统

主技术栈：Bash（核心脚本语言）、Node.js（测试框架：bats-core、bats-assert、bats-support）、jq（JSON 处理）、tmux（可选监控）

关键设计模式：模块化库分离、熔断器模式、双条件退出门控、会话持久化、两阶段错误检测

测试覆盖：276 个测试，100% 通过率，覆盖 CLI 解析、JSON 解析、会话连续性、退出检测、速率限制、循环执行、边界情况、安装流程、项目设置、PRD 导入。

上手体验

安装极简（5分钟）

git clone https://github.com/CryptoDmitry/hermes-agent-control-room.git
cd hermes-agent-control-room
./install.sh

依赖检查：Node.js/npm、jq、git。Claude Code CLI 在首次运行时自动下载。

使用流程

# 创建新项目
ralph-setup my-project
cd my-project
# 编写 PROMPT.md 和 @fix_plan.md
ralph  # 启动自主循环

# 监控（另一终端）
ralph-monitor

# 状态查看
ralph --status

适用场景

✅ 适合：长时间重构任务、批量功能实现、PRD 驱动的开发、多轮测试-修复循环 ❌ 不适合：需要实时人工判断的创意设计、快速一次性问答、对 API 成本敏感的场景

局限与风险

1. API 成本不可见：每小时 100 次调用的默认设置，如果 Claude Code 进入死循环，损失的是开发者自己的 Token 预算
2. Claude Code 版本依赖：需要 >= 2.0.76，依赖 CLI 的 JSON 输出格式，CLI 升级可能破坏解析逻辑
3. Bash 脚本的维护性：47271 字的单文件循环脚本，代码阅读门槛较高
4. 安全性：set -e 使任何非零退出码都会终止循环，需确保 Claude Code 输出不意外触发错误码

行业意义

Ralph 代表了一种趋势：AI 编程工具从"助手"进化为"执行者"。

过去一年，AI 编程工具（如 Cursor、Copilot）的定位是"人在回路中的建议者"。Ralph 的思路是反过来的：人定义目标，AI 自己跑完。这对于大型重构、批量功能开发、标准化 PRD 实现等场景，价值显著。

Control Room 框架进一步扩展了这个思路：从单个 Agent 的自主循环，到多 Agent 团队的协调治理。这是一个更宏大的愿景——用 AI 工具管理 AI 工具本身。

增长曲线：该仓库 2026-01-16 创建，截至分析时已获得 858 stars、66 forks，说明这个方向确实击中了开发者的痛点。随着 Claude Code CLI 的普及和 Agent 化需求的增长，这类工具的采用率预计会持续上升。