mcp-probe-kit 1.10.1 → 1.13.0

package/build/tools/start_ralph.js

@@ -0,0 +1,779 @@
+import { parseArgs, getString, getNumber } from "../utils/parseArgs.js";
+// 默认值（保守安全）
+const DEFAULTS = {
+    mode: "safe",
+    completion_promise: "tests passing + requirements met",
+    test_command: "npm test",
+    cli_command: "claude-code",
+    max_iterations: 8,
+    max_minutes: 25,
+    confirm_every: 1,
+    confirm_timeout: 20,
+    max_same_output: 2,
+    max_diff_lines: 300,
+    cooldown_seconds: 8,
+};
+/**
+ * 生成 PROMPT.md 模板
+ */
+function generatePromptTemplate(goal, completionPromise, testCommand) {
+    return `# Ralph Wiggum Loop - Development Prompt
+
+## 🎯 Goal
+
+${goal}
+
+## ✅ Completion Promise
+
+**Exit Condition**: ${completionPromise}
+
+You MUST satisfy BOTH conditions to exit:
+1. \`COMPLETION_PROMISE_MET: true\`
+2. \`EXIT_SIGNAL: true\`
+
+
+## 📋 Iteration Rules
+
+### 1. Small Steps
+- Make ONE focused change per iteration
+- Avoid large refactors in a single iteration
+- Keep changes under ${DEFAULTS.max_diff_lines} lines when possible
+
+### 2. Test First
+- **CRITICAL**: First iteration MUST identify the correct test command for this project
+- Check for: package.json scripts, pytest, cargo test, go test, mvn test, etc.
+- Update this PROMPT.md with the correct command
+- Run tests EVERY iteration: \`${testCommand}\`
+- Do NOT proceed if tests fail (unless fixing test failures is the goal)
+
+### 3. Update Progress
+- Update \`@fix_plan.md\` after each iteration
+  - Mark completed tasks with ✅
+  - Add new discovered tasks
+  - Adjust priorities
+- Update \`PROGRESS.md\` with:
+  - What was done
+  - Test results
+  - Next step
+  - Current status
+
+### 4. State Block (REQUIRED)
+At the end of EVERY response, output:
+
+\`\`\`
+COMPLETION_PROMISE_MET: [true|false]
+EXIT_SIGNAL: [true|false]
+SUMMARY: [one-line summary of this iteration]
+NEXT_STEP: [what to do next, or "EXIT" if done]
+\`\`\`
+
+**Exit Logic**:
+- Set \`COMPLETION_PROMISE_MET: true\` only when completion promise is satisfied
+- Set \`EXIT_SIGNAL: true\` only when you're confident to exit
+- Loop continues if EITHER is false
+
+### 5. Safety Checks
+- If stuck or repeating same action → set \`EXIT_SIGNAL: true\` and ask for help
+- If single change exceeds ${DEFAULTS.max_diff_lines} lines → stop and break into smaller tasks
+- If tests keep failing after 3 attempts → stop and ask for help
+
+---
+
+## 📂 Files
+
+- \`@fix_plan.md\`: Task breakdown and priorities
+- \`PROGRESS.md\`: Iteration log
+- \`STOP\`: Create this file to emergency stop
+
+---
+
+*Generated by MCP Probe Kit - start_ralph*
+`;
+}
+/**
+ * 生成 @fix_plan.md 模板
+ */
+function generateFixPlanTemplate(goal) {
+    return `# Task Plan: ${goal}
+
+## 🎯 Goal
+${goal}
+
+## 📋 Tasks
+
+### ✅ Completed
+- [ ] Identify correct test command
+- [ ] Verify project structure
+
+### 🚧 In Progress
+- [ ] [Task will be added by agent]
+
+### 📝 Todo
+- [ ] [Tasks will be added by agent]
+
+### 🔍 Discovered Issues
+- [Issues will be added during iterations]
+
+---
+
+**Instructions for Agent**:
+1. First iteration: identify test command and update PROMPT.md
+2. Break down goal into small, testable tasks
+3. Mark tasks as completed with ✅
+4. Add new tasks as discovered
+5. Keep this file updated every iteration
+`;
+}
+/**
+ * 生成 PROGRESS.md 模板
+ */
+function generateProgressTemplate() {
+    return `# Ralph Loop Progress Log
+
+## Iteration Summary
+
+| Iter | Time | Changed Lines | Tests | Status | Summary |
+|------|------|---------------|-------|--------|---------|
+| 0    | -    | -             | -     | START  | Loop initialized |
+
+---
+
+## Detailed Log
+
+### Iteration 0 - Initialization
+- **Time**: [timestamp]
+- **Action**: Loop started
+- **Next**: Identify test command and begin first task
+
+---
+
+**Instructions for Agent**:
+- Add entry for each iteration
+- Include: iteration number, timestamp, what was done, test results, next step
+- Keep summary table updated
+`;
+}
+/**
+ * 生成安全模式脚本 (Bash)
+ */
+function generateSafeScript(params) {
+    return `#!/bin/bash
+# Ralph Loop - Safe Mode
+# Generated by MCP Probe Kit
+
+set -euo pipefail
+
+# ============================================
+# SAFETY PARAMETERS (Override with env vars)
+# ============================================
+MAX_ITERS=\${MAX_ITERS:-${params.max_iterations}}
+MAX_MINUTES=\${MAX_MINUTES:-${params.max_minutes}}
+CONFIRM_EVERY=\${CONFIRM_EVERY:-${params.confirm_every}}
+CONFIRM_TIMEOUT=\${CONFIRM_TIMEOUT:-${params.confirm_timeout}}
+MAX_SAME_OUTPUT=\${MAX_SAME_OUTPUT:-${params.max_same_output}}
+MAX_DIFF_LINES=\${MAX_DIFF_LINES:-${params.max_diff_lines}}
+COOLDOWN_SECONDS=\${COOLDOWN_SECONDS:-${params.cooldown_seconds}}
+REQUIRE_TTY=\${REQUIRE_TTY:-1}
+CLI_COMMAND=\${CLI_COMMAND:-${params.cli_command}}
+
+# ============================================
+# SAFETY CHECKS
+# ============================================
+if [ "$REQUIRE_TTY" = "1" ] && [ ! -t 0 ]; then
+  echo "❌ ERROR: Not running in interactive terminal (TTY required for safety)"
+  echo "   To override: REQUIRE_TTY=0 $0"
+  exit 1
+fi
+
+if [ ! -f "PROMPT.md" ]; then
+  echo "❌ ERROR: PROMPT.md not found. Run from .ralph/ directory"
+  exit 1
+fi
+
+# ============================================
+# STARTUP WARNING
+# ============================================
+echo "🚀 Ralph Loop - Safe Mode"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "⚠️  Safety Limits:"
+echo "   • Max iterations: $MAX_ITERS"
+echo "   • Max time: $MAX_MINUTES minutes"
+echo "   • Confirm every: $CONFIRM_EVERY iteration(s)"
+echo "   • Confirm timeout: $CONFIRM_TIMEOUT seconds"
+echo "   • Max same output: $MAX_SAME_OUTPUT times"
+echo "   • Max diff lines: $MAX_DIFF_LINES lines"
+echo ""
+echo "💡 Emergency stop: touch STOP"
+echo "💡 Pause: Ctrl+C"
+echo ""
+echo "Press Ctrl+C to cancel, or wait 5s to start..."
+sleep 5
+
+
+# ============================================
+# INITIALIZATION
+# ============================================
+ITER=0
+START_TIME=$(date +%s)
+LAST_OUTPUT_HASH=""
+SAME_OUTPUT_COUNT=0
+LOG_FILE="ralph.log"
+
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [INFO] Loop started" >> "$LOG_FILE"
+
+# ============================================
+# MAIN LOOP
+# ============================================
+while [ $ITER -lt $MAX_ITERS ]; do
+  ITER=$((ITER + 1))
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $ITER / $MAX_ITERS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  
+  # Check: STOP file
+  if [ -f "STOP" ]; then
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SAFE] STOP file detected" >> "$LOG_FILE"
+    echo "🛑 STOP file detected. Emergency exit."
+    exit 0
+  fi
+  
+  # Check: Max time
+  CURRENT_TIME=$(date +%s)
+  ELAPSED_MINUTES=$(( (CURRENT_TIME - START_TIME) / 60 ))
+  if [ $ELAPSED_MINUTES -ge $MAX_MINUTES ]; then
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SAFE] Max time reached: $ELAPSED_MINUTES min" >> "$LOG_FILE"
+    echo "⏰ Max time ($MAX_MINUTES min) reached. Stopping."
+    exit 0
+  fi
+  
+  # Check: Confirmation required
+  if [ $((ITER % CONFIRM_EVERY)) -eq 0 ]; then
+    echo ""
+    echo "⏸️  Confirmation required (timeout: \${CONFIRM_TIMEOUT}s)"
+    echo -n "   Continue? [y/N]: "
+    
+    if read -t $CONFIRM_TIMEOUT -r REPLY; then
+      if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SAFE] User declined to continue" >> "$LOG_FILE"
+        echo "🛑 User stopped the loop."
+        exit 0
+      fi
+    else
+      echo ""
+      echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SAFE] Confirmation timeout" >> "$LOG_FILE"
+      echo "⏰ Confirmation timeout. Stopping for safety."
+      exit 0
+    fi
+  fi
+  
+  # Execute Claude Code
+  echo "🤖 Running: $CLI_COMMAND @PROMPT.md"
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] [INFO] Iteration $ITER started" >> "$LOG_FILE"
+  
+  OUTPUT_FILE="last_output_$ITER.txt"
+  if $CLI_COMMAND @PROMPT.md > "$OUTPUT_FILE" 2>&1; then
+    cat "$OUTPUT_FILE"
+  else
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] CLI command failed" >> "$LOG_FILE"
+    echo "❌ CLI command failed. Check $OUTPUT_FILE"
+    exit 1
+  fi
+  
+  # Check: Output repetition
+  CURRENT_HASH=$(md5sum "$OUTPUT_FILE" 2>/dev/null | cut -d' ' -f1 || echo "")
+  if [ "$CURRENT_HASH" = "$LAST_OUTPUT_HASH" ]; then
+    SAME_OUTPUT_COUNT=$((SAME_OUTPUT_COUNT + 1))
+    if [ $SAME_OUTPUT_COUNT -ge $MAX_SAME_OUTPUT ]; then
+      echo "[$(date '+%Y-%m-%d %H:%M:%S')] [WARN] Output repeated $SAME_OUTPUT_COUNT times" >> "$LOG_FILE"
+      echo "⚠️  Output repeated $SAME_OUTPUT_COUNT times. Likely stuck. Stopping."
+      exit 0
+    fi
+  else
+    SAME_OUTPUT_COUNT=0
+  fi
+  LAST_OUTPUT_HASH="$CURRENT_HASH"
+  
+  # Check: Git diff size (if in git repo)
+  if git rev-parse --git-dir > /dev/null 2>&1; then
+    CHANGED_LINES=$(git diff --stat | tail -1 | grep -oE '[0-9]+ insertion|[0-9]+ deletion' | grep -oE '[0-9]+' | awk '{s+=$1} END {print s}' || echo "0")
+    if [ "$CHANGED_LINES" -gt "$MAX_DIFF_LINES" ]; then
+      echo "[$(date '+%Y-%m-%d %H:%M:%S')] [WARN] Changed lines ($CHANGED_LINES) exceeds limit ($MAX_DIFF_LINES)" >> "$LOG_FILE"
+      echo "⚠️  Changed $CHANGED_LINES lines (limit: $MAX_DIFF_LINES). Please review manually."
+      echo "   Run: git diff --stat"
+      exit 0
+    fi
+  fi
+  
+  # Check: Exit signals in output
+  if grep -q "COMPLETION_PROMISE_MET: true" "$OUTPUT_FILE" && grep -q "EXIT_SIGNAL: true" "$OUTPUT_FILE"; then
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [INFO] Both exit conditions met" >> "$LOG_FILE"
+    echo "✅ Completion promise met and exit signal received. Success!"
+    exit 0
+  fi
+  
+  # Cooldown
+  echo "😴 Cooldown: \${COOLDOWN_SECONDS}s..."
+  sleep $COOLDOWN_SECONDS
+done
+
+# Max iterations reached
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SAFE] Max iterations reached" >> "$LOG_FILE"
+echo "⏰ Max iterations ($MAX_ITERS) reached. Stopping."
+exit 0
+`;
+}
+/**
+ * 生成普通模式脚本 (Bash)
+ */
+function generateNormalScript(params) {
+    return `#!/bin/bash
+# Ralph Loop - Normal Mode (Use with caution!)
+# Generated by MCP Probe Kit
+
+set -euo pipefail
+
+# ============================================
+# PARAMETERS
+# ============================================
+MAX_ITERS=\${MAX_ITERS:-${params.max_iterations}}
+CLI_COMMAND=\${CLI_COMMAND:-${params.cli_command}}
+
+echo "🚀 Ralph Loop - Normal Mode"
+echo "⚠️  WARNING: No confirmation required. Use Ctrl+C to stop."
+echo "   Max iterations: $MAX_ITERS"
+echo ""
+sleep 3
+
+ITER=0
+LOG_FILE="ralph.log"
+
+while [ $ITER -lt $MAX_ITERS ]; do
+  ITER=$((ITER + 1))
+  echo "🔄 Iteration $ITER / $MAX_ITERS"
+  
+  if [ -f "STOP" ]; then
+    echo "🛑 STOP file detected."
+    exit 0
+  fi
+  
+  OUTPUT_FILE="last_output_$ITER.txt"
+  $CLI_COMMAND @PROMPT.md | tee "$OUTPUT_FILE"
+  
+  if grep -q "COMPLETION_PROMISE_MET: true" "$OUTPUT_FILE" && grep -q "EXIT_SIGNAL: true" "$OUTPUT_FILE"; then
+    echo "✅ Success!"
+    exit 0
+  fi
+  
+  sleep 5
+done
+
+echo "⏰ Max iterations reached."
+exit 0
+`;
+}
+/**
+ * 生成 Windows 安全模式脚本 (PowerShell)
+ */
+function generateSafeScriptWindows(params) {
+    return `# Ralph Loop - Safe Mode (Windows)
+# Generated by MCP Probe Kit
+
+$ErrorActionPreference = "Stop"
+
+# ============================================
+# SAFETY PARAMETERS
+# ============================================
+$MAX_ITERS = if ($env:MAX_ITERS) { [int]$env:MAX_ITERS } else { ${params.max_iterations} }
+$MAX_MINUTES = if ($env:MAX_MINUTES) { [int]$env:MAX_MINUTES } else { ${params.max_minutes} }
+$CONFIRM_EVERY = if ($env:CONFIRM_EVERY) { [int]$env:CONFIRM_EVERY } else { ${params.confirm_every} }
+$CONFIRM_TIMEOUT = if ($env:CONFIRM_TIMEOUT) { [int]$env:CONFIRM_TIMEOUT } else { ${params.confirm_timeout} }
+$MAX_SAME_OUTPUT = if ($env:MAX_SAME_OUTPUT) { [int]$env:MAX_SAME_OUTPUT } else { ${params.max_same_output} }
+$MAX_DIFF_LINES = if ($env:MAX_DIFF_LINES) { [int]$env:MAX_DIFF_LINES } else { ${params.max_diff_lines} }
+$COOLDOWN_SECONDS = if ($env:COOLDOWN_SECONDS) { [int]$env:COOLDOWN_SECONDS } else { ${params.cooldown_seconds} }
+$CLI_COMMAND = if ($env:CLI_COMMAND) { $env:CLI_COMMAND } else { "${params.cli_command}" }
+
+if (-not (Test-Path "PROMPT.md")) {
+    Write-Host "❌ ERROR: PROMPT.md not found" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "🚀 Ralph Loop - Safe Mode" -ForegroundColor Cyan
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+Write-Host "⚠️  Safety Limits:"
+Write-Host "   • Max iterations: $MAX_ITERS"
+Write-Host "   • Max time: $MAX_MINUTES minutes"
+Write-Host "   • Confirm every: $CONFIRM_EVERY iteration(s)"
+Write-Host ""
+Write-Host "💡 Emergency stop: New-Item -ItemType File -Name STOP"
+Write-Host ""
+Write-Host "Press Ctrl+C to cancel, or wait 5s to start..."
+Start-Sleep -Seconds 5
+
+$ITER = 0
+$START_TIME = Get-Date
+$LAST_OUTPUT_HASH = ""
+$SAME_OUTPUT_COUNT = 0
+$LOG_FILE = "ralph.log"
+
+Add-Content -Path $LOG_FILE -Value "[$((Get-Date).ToString('yyyy-MM-dd HH:mm:ss'))] [INFO] Loop started"
+
+while ($ITER -lt $MAX_ITERS) {
+    $ITER++
+    Write-Host ""
+    Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    Write-Host "🔄 Iteration $ITER / $MAX_ITERS" -ForegroundColor Yellow
+    Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    
+    if (Test-Path "STOP") {
+        Add-Content -Path $LOG_FILE -Value "[$((Get-Date).ToString('yyyy-MM-dd HH:mm:ss'))] [SAFE] STOP file detected"
+        Write-Host "🛑 STOP file detected. Emergency exit." -ForegroundColor Red
+        exit 0
+    }
+    
+    $ELAPSED_MINUTES = ((Get-Date) - $START_TIME).TotalMinutes
+    if ($ELAPSED_MINUTES -ge $MAX_MINUTES) {
+        Add-Content -Path $LOG_FILE -Value "[$((Get-Date).ToString('yyyy-MM-dd HH:mm:ss'))] [SAFE] Max time reached"
+        Write-Host "⏰ Max time reached. Stopping." -ForegroundColor Yellow
+        exit 0
+    }
+    
+    if ($ITER % $CONFIRM_EVERY -eq 0) {
+        Write-Host ""
+        Write-Host "⏸️  Confirmation required" -ForegroundColor Yellow
+        $response = Read-Host "   Continue? [y/N]"
+        if ($response -notmatch '^[Yy]$') {
+            Add-Content -Path $LOG_FILE -Value "[$((Get-Date).ToString('yyyy-MM-dd HH:mm:ss'))] [SAFE] User declined"
+            Write-Host "🛑 User stopped the loop." -ForegroundColor Red
+            exit 0
+        }
+    }
+    
+    Write-Host "🤖 Running: $CLI_COMMAND @PROMPT.md"
+    $OUTPUT_FILE = "last_output_$ITER.txt"
+    & $CLI_COMMAND "@PROMPT.md" | Tee-Object -FilePath $OUTPUT_FILE
+    
+    $CURRENT_HASH = (Get-FileHash -Path $OUTPUT_FILE -Algorithm MD5).Hash
+    if ($CURRENT_HASH -eq $LAST_OUTPUT_HASH) {
+        $SAME_OUTPUT_COUNT++
+        if ($SAME_OUTPUT_COUNT -ge $MAX_SAME_OUTPUT) {
+            Write-Host "⚠️  Output repeated. Likely stuck. Stopping." -ForegroundColor Yellow
+            exit 0
+        }
+    } else {
+        $SAME_OUTPUT_COUNT = 0
+    }
+    $LAST_OUTPUT_HASH = $CURRENT_HASH
+    
+    $content = Get-Content $OUTPUT_FILE -Raw
+    if ($content -match "COMPLETION_PROMISE_MET: true" -and $content -match "EXIT_SIGNAL: true") {
+        Write-Host "✅ Success!" -ForegroundColor Green
+        exit 0
+    }
+    
+    Write-Host "😴 Cooldown: \${COOLDOWN_SECONDS}s..."
+    Start-Sleep -Seconds $COOLDOWN_SECONDS
+}
+
+Write-Host "⏰ Max iterations reached." -ForegroundColor Yellow
+exit 0
+`;
+}
+/**
+ * 生成执行指南
+ */
+function generateGuide(params, isWindows) {
+    const scriptName = isWindows ? "ralph_loop_safe.ps1" : "ralph_loop_safe.sh";
+    const scriptCmd = isWindows ? `powershell -ExecutionPolicy Bypass -File ${scriptName}` : `./${scriptName}`;
+    const chmodCmd = isWindows ? "" : `chmod +x ${scriptName}\n`;
+    return `# 🚀 Ralph Loop Setup Complete!
+
+## 📂 Generated Files
+
+\`.ralph/\` directory structure:
+- \`PROMPT.md\` - Loop prompt with goal and rules
+- \`@fix_plan.md\` - Task breakdown (updated by agent)
+- \`PROGRESS.md\` - Iteration log (updated by agent)
+- \`${scriptName}\` - Safe mode script (default)
+- \`ralph_loop.sh\` - Normal mode script (optional, use with caution)
+
+---
+
+## 🎯 Goal
+
+${params.goal}
+
+**Completion Promise**: ${params.completion_promise}
+
+---
+
+## 🛡️ Safety Configuration (Mode: ${params.mode})
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| Max Iterations | ${params.max_iterations} | Hard limit on loop count |
+| Max Minutes | ${params.max_minutes} | Hard limit on runtime |
+| Confirm Every | ${params.confirm_every} | Require confirmation every N iterations |
+| Confirm Timeout | ${params.confirm_timeout}s | Auto-stop if no response |
+| Max Same Output | ${params.max_same_output} | Stop if output repeats N times |
+| Max Diff Lines | ${params.max_diff_lines} | Stop if changes exceed N lines |
+| Cooldown | ${params.cooldown_seconds}s | Pause between iterations |
+
+---
+
+## 🚀 How to Start
+
+### 1. Create .ralph directory
+\`\`\`bash
+mkdir -p .ralph
+cd .ralph
+\`\`\`
+
+### 2. Copy files
+Copy the generated content below into respective files:
+- \`PROMPT.md\`
+- \`@fix_plan.md\`
+- \`PROGRESS.md\`
+- \`${scriptName}\`
+
+### 3. Make script executable${isWindows ? "" : " (Linux/Mac)"}
+\`\`\`bash
+${chmodCmd}\`\`\`
+
+### 4. Run the loop
+\`\`\`bash
+${scriptCmd}
+\`\`\`
+
+---
+
+## 🛑 How to Stop
+
+### Emergency Stop
+\`\`\`bash
+touch .ralph/STOP
+\`\`\`
+The loop will exit immediately on next check.
+
+### Manual Stop
+Press \`Ctrl+C\` in the terminal.
+
+### Timeout Stop
+Don't respond to confirmation prompt (waits ${params.confirm_timeout}s then stops).
+
+---
+
+## ⚙️ How to Adjust Parameters
+
+Override via environment variables:
+
+\`\`\`bash
+# Example: Increase max iterations to 15
+${isWindows ? "$env:MAX_ITERS=15" : "MAX_ITERS=15"} ${scriptCmd}
+
+# Example: Disable confirmation (not recommended!)
+${isWindows ? "$env:CONFIRM_EVERY=999" : "CONFIRM_EVERY=999"} ${scriptCmd}
+
+# Example: Use different CLI command
+${isWindows ? "$env:CLI_COMMAND='claude'" : "CLI_COMMAND='claude'"} ${scriptCmd}
+\`\`\`
+
+Available overrides:
+- \`MAX_ITERS\`
+- \`MAX_MINUTES\`
+- \`CONFIRM_EVERY\`
+- \`CONFIRM_TIMEOUT\`
+- \`MAX_SAME_OUTPUT\`
+- \`MAX_DIFF_LINES\`
+- \`COOLDOWN_SECONDS\`
+- \`CLI_COMMAND\`
+
+---
+
+## 📊 How to Monitor
+
+### View logs
+\`\`\`bash
+tail -f .ralph/ralph.log
+\`\`\`
+
+### Check progress
+\`\`\`bash
+cat .ralph/PROGRESS.md
+\`\`\`
+
+### Check tasks
+\`\`\`bash
+cat .ralph/@fix_plan.md
+\`\`\`
+
+### View last output
+\`\`\`bash
+cat .ralph/last_output_*.txt
+\`\`\`
+
+---
+
+## 💡 Tips
+
+1. **First iteration is critical**: The agent will identify the correct test command for your project
+2. **Watch for repetition**: If output repeats ${params.max_same_output} times, loop auto-stops
+3. **Review large changes**: If changes exceed ${params.max_diff_lines} lines, loop stops for manual review
+4. **Use git**: Loop works best in git repos (tracks changes, can auto-backup)
+5. **Start small**: Default limits are conservative - adjust after successful runs
+
+---
+
+## ⚠️ Warnings
+
+- **Cost**: Each iteration calls the LLM API. Monitor usage!
+- **Normal mode**: Use only when you're confident. No confirmations = potential runaway.
+- **Test command**: Wrong test command = wasted iterations. Verify in first run.
+- **Background execution**: Not recommended. Always run in foreground with TTY.
+
+---
+
+## 🔗 Integration with Other Tools
+
+### Recommended workflow:
+
+1. **Generate context** (optional but recommended):
+   \`\`\`bash
+   ${params.cli_command} "使用 init_project_context 生成项目文档"
+   \`\`\`
+
+2. **Generate feature spec** (if building new feature):
+   \`\`\`bash
+   ${params.cli_command} "使用 start_feature 生成功能规格，goal='${params.goal}'"
+   \`\`\`
+
+3. **Start Ralph Loop**:
+   \`\`\`bash
+   cd .ralph
+   ${scriptCmd}
+   \`\`\`
+
+---
+
+*Generated by MCP Probe Kit - start_ralph v1.0*
+`;
+}
+/**
+ * start_ralph 主函数
+ */
+export async function startRalph(args) {
+    try {
+        const parsedArgs = parseArgs(args, {
+            defaultValues: DEFAULTS,
+            primaryField: "goal",
+            fieldAliases: {
+                goal: ["目标", "任务", "task"],
+                mode: ["模式"],
+                completion_promise: ["完成条件", "退出条件"],
+                test_command: ["测试命令"],
+                cli_command: ["命令", "cli"],
+                max_iterations: ["最大迭代", "max_iters"],
+                max_minutes: ["最大时间", "max_time"],
+                confirm_every: ["确认频率"],
+                confirm_timeout: ["确认超时"],
+                max_same_output: ["最大重复"],
+                max_diff_lines: ["最大变更行数"],
+                cooldown_seconds: ["冷却时间"],
+            },
+        });
+        const goal = getString(parsedArgs.goal) || "Complete the development task";
+        const mode = getString(parsedArgs.mode) || DEFAULTS.mode;
+        const completionPromise = getString(parsedArgs.completion_promise) || DEFAULTS.completion_promise;
+        const testCommand = getString(parsedArgs.test_command) || DEFAULTS.test_command;
+        const cliCommand = getString(parsedArgs.cli_command) || DEFAULTS.cli_command;
+        const params = {
+            goal,
+            mode,
+            completion_promise: completionPromise,
+            test_command: testCommand,
+            cli_command: cliCommand,
+            max_iterations: getNumber(parsedArgs.max_iterations) ?? DEFAULTS.max_iterations,
+            max_minutes: getNumber(parsedArgs.max_minutes) ?? DEFAULTS.max_minutes,
+            confirm_every: getNumber(parsedArgs.confirm_every) ?? DEFAULTS.confirm_every,
+            confirm_timeout: getNumber(parsedArgs.confirm_timeout) ?? DEFAULTS.confirm_timeout,
+            max_same_output: getNumber(parsedArgs.max_same_output) ?? DEFAULTS.max_same_output,
+            max_diff_lines: getNumber(parsedArgs.max_diff_lines) ?? DEFAULTS.max_diff_lines,
+            cooldown_seconds: getNumber(parsedArgs.cooldown_seconds) ?? DEFAULTS.cooldown_seconds,
+        };
+        // 检测操作系统
+        const isWindows = process.platform === "win32";
+        // 生成所有文件内容
+        const promptMd = generatePromptTemplate(params.goal, params.completion_promise, params.test_command);
+        const fixPlanMd = generateFixPlanTemplate(params.goal);
+        const progressMd = generateProgressTemplate();
+        const safeScript = isWindows
+            ? generateSafeScriptWindows(params)
+            : generateSafeScript(params);
+        const normalScript = generateNormalScript(params);
+        const guide = generateGuide(params, isWindows);
+        // 组装输出
+        const scriptExt = isWindows ? "ps1" : "sh";
+        const output = `${guide}
+
+---
+
+## 📄 File Contents
+
+### 1. PROMPT.md
+\`\`\`markdown
+${promptMd}
+\`\`\`
+
+---
+
+### 2. @fix_plan.md
+\`\`\`markdown
+${fixPlanMd}
+\`\`\`
+
+---
+
+### 3. PROGRESS.md
+\`\`\`markdown
+${progressMd}
+\`\`\`
+
+---
+
+### 4. ralph_loop_safe.${scriptExt} (Safe Mode - Recommended)
+\`\`\`${isWindows ? 'powershell' : 'bash'}
+${safeScript}
+\`\`\`
+
+---
+
+### 5. ralph_loop.sh (Normal Mode - Use with Caution)
+\`\`\`bash
+${normalScript}
+\`\`\`
+
+---
+
+## ✅ Next Steps
+
+1. Create \`.ralph/\` directory
+2. Copy each file content above into respective files
+3. Make scripts executable (if on Linux/Mac)
+4. Review PROMPT.md and adjust if needed
+5. Run \`ralph_loop_safe.${scriptExt}\`
+6. Monitor progress and logs
+
+**Happy coding! 🚀**
+`;
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `❌ start_ralph 执行失败: ${errorMsg}` }],
+            isError: true,
+        };
+    }
+}