技术架构对比

1. Ralph Loop 核心技术机制

1.1 Stop Hook 拦截循环

设计原理：将传统的”单次执行”模式转变为”持续迭代”模式。

工作流程：

sequenceDiagram
    participant U as 用户
    participant R as Ralph 控制器
    participant C as CLI 工具
    participant A as AI 模型
    participant H as Stop Hook
    
    U->>R: 启动任务
    R->>C: 构建命令
    C->>A: 发送提示词
    A->>A: 执行任务
    A->>C: 尝试退出
    C->>H: 触发 Stop Hook
    H->>H: 评估完成条件
    
    alt 条件满足
        H->>C: exit 0
        C->>R: 正常退出
        R->>U: 任务完成
    else 条件不满足
        H->>C: exit 2
        C->>R: 阻止退出
        R->>C: 重新注入提示词
        C->>A: 继续执行
    end

退出码语义：

• exit 0：允许正常退出
• exit 2：阻止退出，触发下一轮循环
• exit 1：错误退出，需要人工干预

Stop Hook 实现示例：

#!/bin/bash
# hooks/stop-hook.sh

OUTPUT_FILE="$1"
MIN_COMPLETION_INDICATORS=2

# 检查输出文件
if [ ! -f "$OUTPUT_FILE" ]; then
    exit 0
fi

# 提取完成指示器
OUTPUT_CONTENT=$(cat "$OUTPUT_FILE")
COMPLETION_INDICATORS=$(echo "$OUTPUT_CONTENT" | \
    grep -oEi "complete|done|finished|ready|implemented" | wc -l)

# 检查 EXIT_SIGNAL
EXIT_SIGNAL="false"
if echo "$OUTPUT_CONTENT" | grep -qE '"EXIT_SIGNAL":\s*true'; then
    EXIT_SIGNAL="true"
fi

# 检查显式完成标记
if echo "$OUTPUT_CONTENT" | grep -q "<<COMPLETED>>"; then
    exit 0
fi

# 双重条件判断
if [ "$COMPLETION_INDICATORS" -ge "$MIN_COMPLETION_INDICATORS" ] && \
   [ "$EXIT_SIGNAL" = "true" ]; then
    exit 0  # 允许退出
else
    exit 2  # 阻止退出
fi

1.2 双重退出检测机制

问题背景：单一条件可能导致误判。

双重条件架构：

条件 1：启发式完成指示器

• “完成”关键词：complete, done, finished, ready, implemented
• 阶段转换信号：moving to next, now working on
• 测试通过反馈：all tests passing, no errors

条件 2：显式退出信号

RALPH_STATUS:
{
  "progress": 80,
  "current_task": "完成结论章节",
  "EXIT_SIGNAL": false,
  "notes": "还需完成最后两个章节"
}

1.3 断路器保护机制

Circuit Breaker 模式：检测和防止停滞或无限循环。

多层错误检测：

断路器状态机：

stateDiagram-v2
    [*] --> Closed: 初始化
    Closed --> Open: 3次无进展 或 5次相同错误
    Open --> HalfOpen: 手动重置
    HalfOpen --> Closed: 1次成功循环
    HalfOpen --> Open: 1次失败循环

1.4 会话连续性管理

Session Continuity：通过 --continue 标志保持跨循环的上下文连续性。

实现机制：

1. Session ID 持久化：存储在 .ralph_session 文件
2. 跨循环上下文传递：使用 CLI 工具的 --continue 标志
3. 会话过期控制：默认 24 小时后自动重置

会话自动重置触发条件：

1.5 速率限制与配额管理

默认配置：100 API 调用/小时

实现机制：

# 调用计数器
API_CALLS=$(cat .api_calls 2>/dev/null || echo 0)
((API_CALLS++))
echo $API_CALLS > .api_calls

# 倒计时器
HOURLY_LIMIT_RESET=$(cat .hour_limit_reset)
CURRENT_TIME=$(date +%s)
WAIT_SECONDS=$((HOURLY_LIMIT_RESET - CURRENT_TIME))

2. 四大平台能力对比

2.1 平台架构概览

flowchart TB
    subgraph "Claude Code"
        CC1[Stop Hook<br/>✓ Native] --> CC2[Session Mgmt<br/>✓ Full]
        CC2 --> CC3[JSON Output<br/>✓ Yes]
        CC3 --> CC4[Plugin System<br/>✓ Complete]
    end
    
    subgraph "OpenCode"
        OC1[Stop Hook<br/>⚠️ Unknown] --> OC2[Session Mgmt<br/>⚠️ Partial]
        OC2 --> OC3[JSON Output<br/>⚠️ Unknown]
        OC3 --> OC4[Plugin System<br/>✓ Good]
    end
    
    subgraph "CodeBuddy"
        CB1[Stop Hook<br/>✗ No] --> CB2[Session Mgmt<br/>✓ Limited]
        CB2 --> CB3[JSON Output<br/>⚠️ Limited]
        CB3 --> CB4[IDE Integration<br/>✓ Deep]
    end
    
    subgraph "pi-agent"
        PA1[Stop Hook<br/>❓ Unknown] --> PA2[Session Mgmt<br/>❓ Unknown]
        PA2 --> PA3[JSON Output<br/>❓ Unknown]
        PA3 --> PA4[Resource Usage<br/>✓ Low]
    end

2.2 详细能力矩阵

2.3 平台特定分析

Claude Code

Stop Hook 实现：

# Claude Code 原生支持 hooks 目录
~/.claude-code/hooks/
├── stop-hook.sh
├── pre-command.sh
└── post-command.sh

适用场景评估：

• ✅ 已有成熟 Ralph Loop 实现
• ✅ 企业级稳定性
• ⚠️ 闭源产品，定制能力受限

OpenCode

Stop Hook 调研：

可能的实现方式：

• Skills 层拦截：在 skill 中实现退出检测
• Commands 层拦截：通过配置 onExit

验证方案：

mkdir -p hooks
echo -e '#!/bin/bash\necho "HOOK_TEST" >> /tmp/test.log\nexit 2' > hooks/stop-hook.sh
chmod +x hooks/stop-hook.sh
opencode -p "测试任务"
grep "HOOK_TEST" /tmp/test.log && echo "支持" || echo "不支持"

CodeBuddy

架构限制：

• IDE 插件模式，无”会话退出”概念
• 生命周期与 IDE 窗口绑定

适配策略：

• 使用外部循环方案 B
• 利用 CodeBuddy API 进行程序化调用

pi-agent

待调研问题：

1. 是否支持命令行调用？
2. 是否有扩展机制？
3. 会话如何管理？

3. Stop Hook 机制在各平台的支持情况

3.1 Stop Hook 技术原理

实现方式对比：

3.2 各平台支持详情

Claude Code：原生支持

export CLAUDE_CODE_HOOKS_DIR="./hooks"
# 退出前调用 $CLAUDE_CODE_HOOKS_DIR/stop-hook.sh $OUTPUT_FILE

OpenCode：待验证

建议进行黑盒测试验证。

CodeBuddy：不支持

原因：IDE 插件模式，不存在”会话退出”概念。

pi-agent：待调研

需要确认 CLI 接口和扩展机制。

4. 会话管理与状态持久化差异分析

4.1 会话管理对比

4.2 统一状态管理方案

由于各平台会话管理机制不同，建议采用统一的自定义状态管理方案。

统一状态文件结构（.current_status.json）：

{
  "version": "1.0.0",
  "session": {
    "id": "session_1710928200_a3f9",
    "created_at": "2026-03-20T10:30:00Z",
    "platform": "opencode",
    "model": "glm-4-flash"
  },
  "task": {
    "name": "研究报告生成",
    "progress": 65,
    "status": "in_progress"
  },
  "state": {
    "current_task": "撰写技术架构章节",
    "completed_tasks": ["研究背景", "文献综述"],
    "pending_tasks": ["技术架构", "案例分析", "结论"]
  },
  "metrics": {
    "loop_count": 12,
    "api_calls": 24,
    "last_update": "2026-03-20T11:45:00Z"
  },
  "safety": {
    "circuit_breaker_state": "closed",
    "no_progress_count": 0
  }
}

4.3 跨平台状态恢复流程

sequenceDiagram
    participant U as 用户
    participant S as 状态管理器
    participant P as 平台 CLI
    participant A as AI 模型
    
    U->>S: 启动任务
    S->>S: 检查 .current_status.json
    
    alt 状态文件存在
        S->>S: 读取上次状态
        S->>U: 显示恢复信息
        S->>S: 构建上下文提示词
    else 状态文件不存在
        S->>S: 初始化新状态
    end
    
    S->>P: 调用 CLI（带上下文）
    P->>A: 发送增强提示词
    A->>A: 理解上下文并继续
    A->>P: 返回输出
    P->>S: 传递输出
    
    S->>S: 解析输出并更新状态
    S->>S: 保存到 .current_status.json

5. 总结

通过对比分析，我们可以得出以下结论：

1. Claude Code 是唯一原生完整支持 Ralph Loop 所有机制的平台

2. OpenCode 具有良好潜力，但 Stop Hook 支持需要验证

3. CodeBuddy 不支持 Stop Hook，但可通过外部循环实现类似效果

4. pi-agent 信息不足，需要进一步调研

5. 统一状态管理 是跨平台适配的关键