名称： ralph-loop
描述： 为 Ralph Wiggum/AI 代理循环（Codex、Claude Code、OpenCode、Goose）生成可直接复制粘贴的 bash 脚本。当用户要求“Ralph 循环”、“Ralph Wiggum 循环”或通过 PROMPT.md + AGENTS.md、SPECS 和 IMPLEMENTATION_PLAN.md 来规划/构建代码的 AI 循环时使用，包括 PLANNING 与 BUILDING 模式、背压机制、沙箱化以及完成条件。

Ralph 循环

概述

生成一个可立即运行的 bash 脚本，用于循环执行 AI 编码 CLI。遵循 Ralph 工作手册流程：

1) 定义需求 → JTBD → 关注主题 → specs/*.md
2) PLANNING 循环 → 创建/更新 IMPLEMENTATION_PLAN.md（不进行实现）
3) BUILDING 循环 → 实现任务、运行测试（背压）、更新计划、提交

循环通过每次迭代加载 PROMPT.md + AGENTS.md 以及磁盘上的计划/规格文件来保持上下文。

工作流程

1) 收集输入（缺失则询问）

• 目标 / JTBD（需要达成的结果）
• CLI 工具 (codex, claude-code, opencode, goose, 其他)
• 模式: PLANNING, BUILDING, 或 BOTH
• 完成条件
• 承诺短语（用于检测的字符串），或
• 每次迭代运行的测试/命令，或
• 计划标记（例如，IMPLEMENTATION_PLAN.md 中的一行 STATUS: COMPLETE）
• 最大迭代次数
• 沙箱选择 (none | docker | 其他) + 安全策略
• 背压命令（测试/代码检查/构建）以嵌入到 AGENTS.md 中
• 自动批准标志（需明确询问）
• Codex: --full-auto
• Claude Code: --dangerously-skip-permissions

2) 阶段 1 — 需求 → 规格文件

如果用户需要“完整 Ralph 流程”（或需求不明确），请在循环开始前执行此步骤：
- 将 JTBD 分解为关注主题（1 个主题 = 1 个规格文件）。
- 为每个主题起草 specs/<topic>.md。
- 使用子代理加载 URL 或现有文档到上下文中，以提高规格文件质量。
- 保持规格文件简短且可测试。

3) 阶段 2/3 — PROMPT.md + AGENTS.md

• 每次迭代加载的上下文: PROMPT.md + AGENTS.md。
• AGENTS.md 应包含：
• 项目测试命令（背压）
• 构建/运行指令
• 任何操作经验总结
• PROMPT.md 应引用：
• specs/*.md
• IMPLEMENTATION_PLAN.md
• 任何相关的项目文件/目录

4) 两种提示模板（PLANNING 与 BUILDING）

创建两个提示，并根据模式切换 PROMPT.md。

PLANNING 提示（不进行实现）：

你正在为以下目标运行 Ralph PLANNING 循环：<JTBD/GOAL>。

请阅读 specs/* 和当前代码库。进行差距分析并仅更新 IMPLEMENTATION_PLAN.md。
规则：
- 请勿进行实现。
- 请勿提交。
- 对任务进行优先级排序，并保持计划简洁。
- 如果需求不明确，请将澄清问题写入计划中。

完成条件：
如果计划已完成，请添加一行：STATUS: COMPLETE

BUILDING 提示：

你正在为以下目标运行 Ralph BUILDING 循环：<JTBD/GOAL>。

上下文：
- specs/*
- IMPLEMENTATION_PLAN.md
- AGENTS.md（测试/背压）

任务：
1) 从 IMPLEMENTATION_PLAN.md 中选取最重要的任务。
2) 调查相关代码（不要假设缺失部分）。
3) 实现。
4) 运行 AGENTS.md 中的背压命令。
5) 更新 IMPLEMENTATION_PLAN.md（标记为完成并添加备注）。
6) 如果学到了新的操作细节，请更新 AGENTS.md。
7) 使用清晰的消息进行提交。

完成条件：
如果所有任务都已完成，请添加一行：STATUS: COMPLETE

5) 构建每次迭代的命令

• Codex: codex exec <FLAGS> "$(cat PROMPT.md)"
• 需要 git 仓库。
• Claude Code: claude <FLAGS> "$(cat PROMPT.md)"
• OpenCode: opencode run "$(cat PROMPT.md)"
• Goose: goose run "$(cat PROMPT.md)"（询问是否需要 Goose 配方）

如果 CLI 工具未知，请询问每次迭代要运行的确切命令。

6) 输出可复制粘贴的脚本

提供一个最小化循环或一个带最大迭代次数和停止条件的受控循环。

最小化循环（Geoff 风格）：

while :; do cat PROMPT.md | claude ; done

受控循环（推荐）：

#!/usr/bin/env bash
set -euo pipefail

PROMISE='...'
MAX_ITERS=...
CLI_FLAGS="..."  # 可选
PLAN_SENTINEL='STATUS: COMPLETE'
TEST_CMD='...'   # 可选

if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "❌ 请在 git 仓库内运行此脚本。"
  exit 1
fi

touch PROMPT.md AGENTS.md IMPLEMENTATION_PLAN.md
LOG_FILE=".ralph/ralph.log"
mkdir -p .ralph

CLI_CMD="..." # 例如 "codex exec" 或 "claude"

for i in $(seq 1 "$MAX_ITERS"); do
  echo -e "\n=== Ralph 迭代 $i/$MAX_ITERS ===" | tee -a "$LOG_FILE"

  $CLI_CMD $CLI_FLAGS "$(cat PROMPT.md)" | tee -a "$LOG_FILE"

  if [[ -n "${TEST_CMD}" ]]; then
    echo "运行测试: $TEST_CMD" | tee -a "$LOG_FILE"
    bash -lc "$TEST_CMD" | tee -a "$LOG_FILE"
  fi

  if grep -Fq "$PROMISE" "$LOG_FILE" || grep -Fq "$PLAN_SENTINEL" IMPLEMENTATION_PLAN.md; then
    echo "✅ 检测到完成条件。停止循环。" | tee -a "$LOG_FILE"
    exit 0
  fi

done

echo "❌ 达到最大迭代次数但未完成。" | tee -a "$LOG_FILE"
exit 1

安全/沙箱指南（必须提及）

• 使用 --dangerously-skip-permissions 或 --full-auto 运行意味着信任 + 风险。
• 建议使用沙箱（docker/e2b/fly），配置最小权限和受限网络。
• 应急措施：Ctrl+C 停止；git reset --hard 回滚。

防护措施

• 如果需求不明确，坚持在 BUILDING 前先制定规格文件。
• 如果计划看起来过时/错误，重新生成它（PLANNING 循环）。
• 如果背压命令缺失，请询问用户并将其添加到 AGENTS.md。