🤖 Ralph Loop for Gemini CLI: 自動化遞迴思考模組

這是一份給 Gemini CLI (Preview) 使用者的擴充指南。 "Ralph Loop" 是一個靈感來自 Anthropic Claude Code 的概念，旨在讓 AI 在 CLI 環境中具備「自我循環」、「自我檢查」直到達成目標的能力，而非僅僅回應一次對話。

本指南將教你如何在你的 Gemini CLI 環境中安裝並啟用這個功能。

📋 前置需求與安裝 (Essential Setup)

要使用 Ralph Loop 與 Agent Skills，請務必按照以下步驟操作：

安裝 Gemini CLI Preview: 前往 Gemini CLI Preview Changelogs 下載並安裝最新版本。
開啟預覽功能 (Preview Features):
- 啟動（或重啟）Gemini CLI。
- 輸入 /settings 進入設定介面。
- 找到 Preview Features (e.g., models) 並將其設定為 True。
- 重啟 Gemini CLI。
啟用 Agent Skills:
- 再次進入 /settings。
- 找到 Agent Skills 並設定為 True。
- 再次重啟 Gemini CLI。
驗證: 在終端機輸入 /skills，如果您能看到 Skills 列表，代表環境已準備就緒！
- 詳細 Skills 說明請參閱官方文件。

🚀 快速安裝 Ralph Loop 指令

在終端機執行以下指令，自動建立 .gemini 資料夾結構並配置檔案：

# 1. 建立目錄結構
mkdir -p .gemini/commands .gemini/scripts

# 2. 建立指令設定檔 (ralph-loop.toml)
cat <<EOF > .gemini/commands/ralph-loop.toml
description = "Start an autonomous iterative loop (Ralph Wiggum mode)"
prompt = """
!{bash .gemini/scripts/ralph_manager.sh start {{args}}}

System: The Ralph Loop has been initialized with the parameters shown above.
If the initialization was successful (see "🚀 Ralph Loop initialized"), please:
1. Acknowledge the mode (Autonomous Iteration).
2. Confirm the "Promise" (exit condition) and "Max Iterations".
3. IMMEDIATELY start executing the user's Task/Prompt.

IMPORTANT: Do not stop until you output the Promise string or run out of iterations.
"""
EOF

# 3. 建立取消指令 (cancel-ralph.toml)
cat <<EOF > .gemini/commands/cancel-ralph.toml
description = "Stop the current active Ralph loop"
prompt = """
!{bash .gemini/scripts/ralph_manager.sh cancel}

System: The user has requested to cancel the autonomous loop.
Please confirm to the user that the loop state has been cleared (based on the output above).
"""
EOF

# 4. 建立管理器腳本 (ralph_manager.sh)
cat <<'EOF' > .gemini/scripts/ralph_manager.sh
#!/bin/bash
STATE_FILE=".gemini/ralph-loop.local.md"
if [ "$1" == "cancel" ]; then
    [ -f "$STATE_FILE" ] && rm "$STATE_FILE" && echo "🛑 Ralph Loop has been cancelled." || echo "ℹ️ No active Ralph Loop found."
    exit 0
fi
if [ "$1" == "start" ]; then
    shift
    PROMISE="<promise>"; MAX=5; PROMPT=""
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --promise|-p) PROMISE="$2"; shift; shift ;;
            --max|-m) MAX="$2"; shift; shift ;;
            *) PROMPT="$PROMPT $1"; shift ;;
        esac
    done
    PROMPT=$(echo "$PROMPT" | sed 's/^ *//')
    [ -z "$PROMPT" ] && echo "⚠️ Error: No prompt provided." && exit 1
    echo -e "# Ralph Loop State\nPrompt: $PROMPT\nPromise: $PROMISE\nMaxIterations: $MAX\nCurrentIteration: 0\nStartedAt: $(date)" > "$STATE_FILE"
    echo -e "🚀 Ralph Loop initialized.\n📝 Task: $PROMPT\n🎯 Goal: Output '$PROMISE' to finish.\n🔄 Max Iterations: $MAX"
    exit 0
fi
EOF

chmod +x .gemini/scripts/ralph_manager.sh

🎮 如何使用

安裝後，您可以使用以下 Slash Commands：

1. 啟動循環 (`/ralph-loop`)

/ralph-loop 幫我開發一個具備測試案例的 API 模組，持續修正直到所有測試通過，最後輸出 <promise>

AI 會進入「自主迭代」模式，它會自動呼叫工具、檢查錯誤並自我修正，直到達成目標。

2. 取消循環 (`/cancel-ralph`)

如果發現 AI 陷入死迴圈或想提早終止，輸入 /cancel-ralph 即可清除狀態。

🛠️ 原理說明 (Deep Dive)

指令觸發: 當您輸入 /ralph-loop 時，Gemini CLI 會執行 ralph-loop.toml。
狀態鎖定: 透過 !{bash ...} 語法調用 ralph_manager.sh，在 .gemini/ralph-loop.local.md 建立一個狀態檔案。
模式切換: Prompt 會將 AI 切換至「自主迭代模式」，並明確告知其結束條件（Promise 字串）。
Context 保持: Gemini CLI 會偵測到鎖定檔案的存在，並配合內建的 Hook 機制（或系統提示的強引導），讓 AI 持續在對話中呼叫工具直到輸出承諾的高價值結果。

⚠️ 注意事項

Generated by Gemini CLI Agent

Keyboard shortcuts

Jason's Notes