拉尔夫循环

概述

此技能引导OpenClaw 智能体使用exec和process工具来执行拉尔夫循环工作流。该智能体遵循拉尔夫操作手册流程来编排 AI 编程智能体会话：

1. 定义需求→ JTBD → 重点主题 →specs/*.md
2. 规划循环→ 创建/更新IMPLEMENTATION_PLAN.md（不实施）
3. 构建循环→ 实施任务、运行测试（反压）、更新计划、提交

该循环通过PROMPT.md+AGENTS.md（每次迭代加载）以及磁盘上的计划/规范来持久化上下文。

本技能工作原理

本技能为OpenClaw智能体生成指令，使其能够使用exec与process工具来执行Ralph循环。

• 智能体调用exec工具并执行编码智能体命令
• 使用pty: true为交互式命令行界面提供TTY支持
• 使用background: true以实现监控能力
• 使用process工具来监控进度并检测完成状态

重要提示：用户不直接运行这些脚本——OpenClaw智能体通过其工具能力来执行它们。

TTY要求

某些编码智能体需要一个真实的终端（TTY）才能正常工作，否则它们会挂起：

交互式CLI（需要TTY）：

• OpenCode、Codex、Claude Code、Pi、Goose

非交互式CLI（基于文件）：

• aider、自定义脚本

解决方案：对交互式CLI使用exec + 进程模式，对基于文件的工具使用简单循环。

智能体工具使用模式

交互式CLI（推荐模式）

对于OpenCode、Codex、Claude Code、Pi和Goose - 这些需要TTY支持：

当我（智能体）收到Ralph Loop请求时，我将：

1. 使用exec工具启动编码智能体：

   exec tool with parameters:
   - command: "opencode run --model <MODEL> \"$(cat PROMPT.md)\""
   - workdir: <project_path>
   - background: true
   - pty: true
   - yieldMs: 60000
   - timeout: 3600
   

2. 从exec工具响应中捕获会话ID

3. 使用process工具进行监控：

   process tool with:
   - action: "poll"
   - sessionId: <captured_session_id>
   
   process tool with:
   - action: "log"
   - sessionId: <captured_session_id>
   - offset: -30  (for recent output)
   

4. 检查完成情况通过阅读IMPLEMENTATION_PLAN.md以获取哨兵文本

5. 清理必要时终止进程：

   process tool with:
   - action: "kill"
   - sessionId: <session_id>
   

优势：支持TTY、实时日志、超时处理、并行会话、工作目录隔离

代理工作流程

1) 收集输入

必需项：

• 目标 / 待完成的工作
• CLI (opencode、codex、claude、goose、pi等)
• 模式 (规划中,构建，或两者)
• 最大迭代次数（默认：PLANNING=5, BUILDING=10）

可选：

• 完成标记（默认：STATUS: COMPLETE在IMPLEMENTATION_PLAN.md文件中）
• 工作目录（默认：$PWD）
• 每次迭代超时时间（默认：3600秒）
• 沙盒选择
• 自动批准标志（--full-auto、--yolo、--dangerously-skip-permissions）

自动检测:

• 如果CLI处于交互式列表状态 → 使用带有 pty: true 的 exec 工具
• 从CLI需求中提取模型标志

2) 需求 → 规格 (可选)

如果需求不明确:

• 将JTBD分解为焦点主题
• 起草specs/<主题>.md为每个主题
• 保持规格简短且可测试

3) PROMPT.md + AGENTS.md

PROMPT.md引用:

• specs/*.md
• IMPLEMENTATION_PLAN.md
• 相关项目文件

AGENTS.md包含:

• 测试命令 (背压)
• 构建/运行说明
• 操作经验总结

4) 提示模板

规划提示(无实现):

You are running a Ralph PLANNING loop for this goal: <goal>.

Read specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.

Rules:
- Do not implement
- Do not commit
- Create a prioritized task list
- Write down questions if unclear

Completion:
When plan is ready, add: STATUS: PLANNING_COMPLETE

构建 提示词：

You are running a Ralph BUILDING loop for this goal: <goal>.

Context: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md

Tasks:
1) Pick the most important task
2) Investigate code
3) Implement
4) Run backpressure commands from AGENTS.md
5) Update IMPLEMENTATION_PLAN.md
6) Update AGENTS.md with learnings
7) Commit with clear message

Completion:
When all done, add: STATUS: COMPLETE

5) CLI 命令参考

代理使用以下模式构建命令字符串：

常用标志：

• Codex：--full-auto、--yolo、--model <model>
• Claude:--dangerously-skip-permissions

详细的代理工具使用示例

示例1：OpenCode Ralph循环

代理执行此序列：

Step 1: Launch OpenCode with exec tool
{
  command: "opencode run --model github-copilot/claude-opus-4.5 \"$(cat PROMPT.md)\"",
  workdir: "/path/to/project",
  background: true,
  pty: true,
  timeout: 3600,
  yieldMs: 60000
}

Step 2: Capture session ID from response
sessionId: "abc123"

Step 3: Monitor with process tool every 10-30 seconds
{
  action: "poll",
  sessionId: "abc123"
}

Step 4: Check recent logs
{
  action: "log",
  sessionId: "abc123",
  offset: -30
}

Step 5: Read IMPLEMENTATION_PLAN.md to check for completion
- Look for: "STATUS: COMPLETE" or "STATUS: PLANNING_COMPLETE"

Step 6: If complete or timeout, cleanup
{
  action: "kill",
  sessionId: "abc123"
}

示例2：Codex全自动模式

代理工具调用：

exec tool:
{
  command: "codex exec --full-auto --model anthropic/claude-opus-4 \"$(cat PROMPT.md)\"",
  workdir: "/path/to/project",
  background: true,
  pty: true,
  timeout: 3600
}

# Then monitor with process tool as above

完成检测

使用灵活的正则表达式匹配变体：

grep -Eq "STATUS:?\s*(PLANNING_)?COMPLETE" IMPLEMENTATION_PLAN.md

匹配项：

• 状态：完成
• 状态：完成
• 状态：规划完成
• ## 状态：规划完成

安全与防护措施

自动批准标志（危险！）

• Codex：--full-auto（沙盒环境，自动批准）或--yolo（无沙盒！）
• Claude：--危险地跳过权限检查
• 建议：使用沙箱（docker/e2b/fly）和受限凭据

应急出口

• 停止：Ctrl+C
• 终止会话：使用动作“kill”的处理工具
• 回滚：git reset --hard HEAD~N

最佳实践

1. 从小处着手：先进行1-2次迭代测试
2. 工作目录隔离：防止读取无关文件
3. 设置超时：默认1小时可能不适用于所有任务
4. 主动监控：检查日志，不要过早终止
5. 需求优先：在构建前明确规范
6. 早期反压：从一开始就添加测试

故障排除

许可证

MIT

致谢

此项技能基于以下人员的工作构建：

• @jordyvandomselaar- 原始的 Ralph Loop 概念和工作流设计
• @steipete- 编码代理模式及支持 pty 的 exec/process 工具使用

主要改进：采用OpenClaw的exec工具并启用pty: true参数，为交互式命令行界面提供TTY支持，从而解决了简单后台bash执行方式导致的程序挂起问题。